Implantação MVP

2026-10-03 00:36:29 -03:00
commit aa1d925642
@@ -0,0 +1,185 @@
+# P00 — Discovery técnico e auditoria do módulo existente
+
+Data: 2026-10-02  
+Escopo auditado: `c:\Users\Usuário\Documents\crm` (package `crm-2.0`, Next.js 16.0.10).  
+Workspace desta sessão: `gerador-contratos` (repositório Gitea vazio, sem código de produto).  
+Cópia irmã `Documents\CRM-2.0` existe e contém o mesmo módulo antigo de contratos, sem as migrations mais novas da calculadora. A fonte usada aqui é `crm`.
+
+Nenhum código de produto, banco ou UI foi alterado.
+
+## Achado de localização
+
+O Gerador de Contratos não pode nascer neste repositório. `gerador-contratos` só tem git e remote `https://gitea.fatorxtech.com/cferraz/gerador-contratos.git`. Auth, RLS, feature flag, AppShell, Sentry, Redis e Design System estão em `crm`.
+
+A spec e a regra do módulo proíbem arquitetura paralela. **DT-CTR-007 foi aprovado:** implementar dentro de `crm`, preservando `/dashboard/contracts`.
+
+## Arquitetura atual
+
+```
+Sidebar (lib/nav.ts, flag contracts)
+        |
+        v
+app/dashboard/contracts/layout.tsx
+  requireFeature('contracts')  --> fail-closed, redirect /dashboard
+        |
+        +-- page.tsx            lista
+        +-- new/page.tsx        ContractWizard (passos fixos)
+        +-- [id]/page.tsx       ContractEditor
+        +-- actions.ts          Server Actions (CRUD, PDF, deal)
+        |
+        v
+Supabase Auth/SSR + getCurrentWorkspaceId()
+  cookie active_workspace_id validado por membership
+        |
+        v
+Postgres
+  contracts + contract_commercial + contract_sla_items
+  + contract_modules + contract_clauses
+  + contract_sla_defaults + contract_clause_defaults
+  RLS: is_workspace_member (qualquer papel)
+        |
+        v
+PDF @react-pdf/renderer (utils/contractPdf.tsx)
+  persistido no bucket privado Storage `contracts`
+  caminho {workspace_id}/{contract_id}.pdf
+  pdf_url gravado na linha
+
+API externa paralela (Bearer API key, service role):
+  POST/GET /api/v1/contracts
+  /api/v1/contracts/defaults
+  /api/v1/contracts/:id
+  POST /api/v1/contracts/:id/generate-pdf
+```
+
+Fora deste fluxo, e **não é o gerador**:
+
+- `calculator_contracts` (migration 156) confirma uma versão imutável de proposta da calculadora. Dono, time e hash. Não usar essas tabelas para templates.
+
+## Inventário
+
+| Caminho | Papel | Classe |
+|---|---|---|
+| `lib/nav.ts` | Item Contratos, flag `contracts` | REUTILIZAR |
+| `utils/featureFlags.ts` | `isFeatureEnabled` / `requireFeature`, sem linha = desligado | REUTILIZAR |
+| `app/dashboard/contracts/layout.tsx` | Guard da flag | REUTILIZAR |
+| `utils/supabase/server.ts`, `utils/supabase/user.ts` | Auth SSR | REUTILIZAR |
+| `utils/workspace.ts` | `getCurrentWorkspaceId`, `isWorkspaceAdmin`, `isWorkspaceManager`, `getManagedTeamIds` | REUTILIZAR |
+| `utils/workspaceAdmin.ts` | Decisões puras de papel | REUTILIZAR |
+| `migrations/038_contracts.sql` | Schema do contrato comercial Fly Apex | MANTER como legado; não é o gerador |
+| `app/dashboard/contracts/actions.ts` | CRUD do contrato fixo | ADAPTAR só depois do DT-CTR-007; hoje qualquer membro edita |
+| `components/Contracts/ContractWizard.tsx` | Wizard de campos fixos + hex antigo | ADAPTAR ou conviver; não é wizard de template |
+| `components/Contracts/ContractEditor.tsx` | Editor de cláusulas/SLA/módulos | idem |
+| `components/Contracts/DealContractsTab.tsx` | Contratos no card do deal | REUTILIZAR o gancho de deal; domínio novo é outro |
+| `components/Contracts/ContractStatusBadge.tsx` | Badge de status comercial | REUTILIZAR se o status legado permanecer |
+| `utils/contractPdf.tsx` | PDF do schema fixo + persistência | ADAPTAR o renderer; o modelo de documento é CRIAR |
+| `app/api/v1/contracts/**` | API externa do schema antigo | MANTER para o legado; API nova só se DT-CTR-006 exigir |
+| `utils/sanitize.ts` | `stripHtml` / `sanitizeText` (remove tags) | ADAPTAR; não é sanitizador HTML com allowlist |
+| `utils/auditLog.ts` | Auditoria de plataforma (workspace/user/org) | ADAPTAR o padrão; eventos de contrato são CRIAR |
+| `utils/rateLimit.ts`, `utils/cache.ts` | Redis/ioredis, rate limit fail-open | REUTILIZAR |
+| `sentry.*.config.ts`, `instrumentation-client.ts` | Sentry, `sendDefaultPii: false`, replay em erro | ADAPTAR (falta scrub de conteúdo contratual) |
+| `app/globals.css` tokens `--bc-*` | Traxion DS implementado no app | REUTILIZAR; ver conflito visual abaixo |
+| `scripts/db/migrate.ts` + `migrations/*.sql` | Migrations numeradas, `npm run migrate` | REUTILIZAR |
+| `.github/workflows/ci.yml` | npm ci, Node 20, tsc, build | REUTILIZAR |
+| Famílias/versões de template, placeholders, drafts 24 h, Contract Document Model | inexistentes | CRIAR |
+
+Não há parser DOCX, upload de `.docx`/`.txt` de modelo, autosave de rascunho de formulário, nem cota de 10 modelos.
+
+## Schema encontrado
+
+Migration `038_contracts.sql`:
+
+- `contracts`: workspace, deal opcional, título, cliente, status `rascunho|enviado|assinado|ativo|expirado|cancelado`, `pdf_url`.
+- `contract_commercial`: limites, setup, mensalidade, vencimento, pagamento.
+- `contract_sla_items`, `contract_modules`, `contract_clauses`.
+- `contract_sla_defaults` e `contract_clause_defaults`: seed global (`workspace_id` nulo) ou por workspace. Escrita de global exige `is_superadmin()`.
+- Flag `contracts` inserida com `enabled_globally = false`.
+- RLS de membro em todas as tabelas de contrato. Sem divisão owner/admin vs gestor/agent.
+- Nenhuma migration posterior altera `public.contracts`.
+
+`calculator_contracts` é outro bounded context (proposta da calculadora).
+
+## Feature flag e guards
+
+- Flag `contracts`, default global desligado. Override por workspace vence o global (`utils/featureFlags.ts`).
+- Ausência da linha retorna `false` (fail-closed).
+- Layout chama `requireFeature('contracts')` e redireciona para `/dashboard`.
+- Server Actions repetem `guardFeature()`.
+- API v1 repete a checagem e devolve 403.
+- Sidebar só mostra o item com a flag ligada.
+- **Não há guard de papel** nas actions de contrato. `isWorkspaceAdmin()` não é usado em `app/dashboard/contracts`.
+
+Tenant: `getCurrentWorkspaceId()` lê o cookie `active_workspace_id` e confirma membership. As queries filtram `workspace_id` no servidor. A API v1 usa o workspace da API key, não um id solto do body.
+
+## Gaps contra o Gerador de Contratos
+
+| Requisito | Estado |
+|---|---|
+| Famílias e versões; mesmo nome cria versão; sem overwrite | Inexistente. Defaults globais são seed fixo. |
+| Upload `.docx`/`.txt`, 5 MB, 50 `{{chave}}` | Inexistente. |
+| Tipos `data_*` date, `valor_*`/`preco_*` number, resto text | Inexistente. Campos comerciais são colunas fixas. |
+| Todos os campos obrigatórios | Wizard só exige título. |
+| Máx. 10 modelos-base ativos; versões não contam | Inexistente. |
+| Draft autosave ~15 s, TTL 24 h | Inexistente. Status `rascunho` é o contrato persistido. |
+| Draft ativo bloqueia exclusão da versão | Delete bloqueia só status `assinado` e `ativo`. |
+| Preview e PDF no mesmo Contract Document Model | PDF lê o schema relacional direto. Não há preview compartilhado. |
+| PDF não é repositório permanente no MVP | O fluxo atual grava o PDF no Storage e `pdf_url`. |
+| owner/admin gerenciam templates; gestor/agent operam | Qualquer membro do workspace faz CRUD. |
+| Superadmin não edita documento privado no fluxo comum | Superadmin entra em `isWorkspaceAdmin` (plataforma). Defaults globais usam `is_superadmin()`. Não misturar com o fluxo operacional novo. |
+| Sentry sem conteúdo contratual | `sendDefaultPii: false`. Sem `beforeSend` que raspe corpo de contrato, formulário, token ou cookie. Replay de erro está ligado no client (`replaysOnErrorSampleRate: 1`). |
+| UI no Design System, sem tokens do protocolo antigo | Wizard/editor usam hex `#001A3B`, `#00478F`, `#00AEEF`. O app vivo usa `--bc-*` (Traxion). |
+
+Conflitos que não devem ser resolvidos em silêncio:
+
+1. O módulo em produção é um contrato comercial de plataforma (SLA, módulos, cláusulas markdown), ligado a deal e funil (`proposal_created` / `proposal_sent`). O gerador novo é template com placeholders. Substituir o schema atual quebra deal, API v1 e PDF armazenado.
+2. A spec chama o visual de EloPro Design System V2.1. No `crm` o handoff implementado é Traxion DS, tokens `--bc-*` em `app/globals.css` e `docs/design/redesign-traxion-ds1.md`. Não há artefato nomeado V2.1 neste repo. Os hex do wizard são o visual antigo e não devem ser copiados.
+3. `audit_log` da plataforma não tem ações de contrato e o `target_type` não inclui contrato. A calculadora tem `calculator_audit_log` próprio. O gerador precisa de trilha nova, no mesmo estilo, sem enfiar conteúdo do documento no `meta`.
+
+## Estratégia recomendada
+
+Não apagar o módulo atual nesta fase.
+
+1. Implementar o gerador **dentro de `crm`**, na flag `contracts` já existente.
+2. Conviver com o contrato comercial legado até uma decisão de produto (aba, rota irmã ou substituição). Não reutilizar `contracts` / `contract_clauses` como tabela de template.
+3. Criar tabelas novas de família, versão, campo, draft e auditoria do gerador, com RLS por `workspace_id` e checagem de papel no servidor (`isWorkspaceAdmin` para gestão).
+4. Reusar Auth SSR, `getCurrentWorkspaceId`, feature flag, nav, Redis, `@react-pdf/renderer`, runner de migration e CI.
+5. PDF novo: gerar sob demanda com o Contract Document Model e não gravar como acervo. O bucket `contracts` continua válido para o PDF legado.
+6. UI nova com tokens `--bc-*` já presentes, até alguém apontar o arquivo V2.1 se ele for diferente do Traxion.
+
+## Decisões aprovadas em 2026-10-02 (encerram o P00)
+
+1. Implementar dentro de `Documents\crm`, ao lado do módulo antigo. Não substituir, migrar nem alterar o contrato comercial ligado ao deal.
+2. Parser DOCX: Mammoth. Sanitização HTML: `sanitize-html` no servidor, obrigatória antes de persistir ou renderizar, preservando `{{chave}}`. Sem troca de biblioteca; Mammoth fica no Node (não no client e não no Edge). Cabeçalho, rodapé e caixa de texto seguem fora até a matriz DT-CTR-003.
+3. Sem endpoint público `/api/v1` para o gerador. A API antiga permanece só no domínio legado.
+
+Os dez achados deste relatório continuam vinculantes. `workspace_id` não vem do browser. Tabela do módulo antigo não é reaproveitada por semelhança de nome.
+
+## Decision gates
+
+| Gate | Status | Evidência |
+|---|---|---|
+| DT-CTR-001 parser DOCX | RESOLVIDO | Mammoth 1.13 no `crm`. Conversão do upload fica no P03. Roda só no Node. |
+| DT-CTR-002 sanitização HTML | RESOLVIDO | `sanitize-html` no servidor (`lib/gerador-contratos/sanitize.ts`), antes de persistir ou renderizar. `{{chave}}` é preservado fora de tag removida. |
+| DT-CTR-003 matriz DOCX | PENDENTE | Cabeçalho, rodapé, caixa de texto e estilo não estão prometidos. |
+| DT-CTR-004 Storage | RESOLVIDO POR EVIDÊNCIA | Supabase Storage. Bucket privado `contracts`, service role, URL assinada. Templates devem usar esse mecanismo; o path/bucket exato do arquivo-fonte fica para a implementação, sem trocar de produto. |
+| DT-CTR-005 deploy/CI/package | RESOLVIDO POR EVIDÊNCIA | npm (`package-lock.json`), Node 20, `npm run migrate` via `postgres`+`tsx`, CI em `.github/workflows/ci.yml` (tsc + build; lint não bloqueia). |
+| DT-CTR-006 API `/api/v1` | RESOLVIDO | Sem API pública nova no gerador. `/api/v1/contracts` permanece só no legado. |
+| DT-CTR-007 migração de `/dashboard/contracts` | RESOLVIDO | Convive. Gerador em `/dashboard/gerador-contratos`. Contrato comercial do deal intocado. |
+
+## Plano P01–P12 (só depois do DT-CTR-007)
+
+Trabalho no repo `crm`, branch dedicada. Este repo `gerador-contratos` não recebe o app.
+
+1. **P01** Fundação: tipos de domínio, guards de flag e de admin, esqueleto de telas (lista, novo, modelos admin, histórico) sem parser nem PDF novo.
+2. **P02** Migrations novas (próximo número após a última em `crm/migrations`), RLS por workspace e papel, índices. Não alterar o significado das tabelas da 038.
+3. **P03** Upload e parser com Mammoth e `sanitizeContractHtml`. Validação 5 MB, 50 chaves, tipos por prefixo, cota de 10 bases, versão por nome. A matriz DT-CTR-003 continua em aberto.
+4. **P04** Wizard operacional: escolha, revisão, formulário dinâmico, tudo obrigatório.
+5. **P05** Draft autosave ~15 s, TTL 24 h. Redis só como apoio; Postgres é a fonte se o draft precisar sobreviver. Bloqueio de exclusão com draft ativo.
+6. **P06** Contract Document Model único para preview e PDF. `@react-pdf/renderer`. Sem persistir o PDF novo.
+7. **P07** Admin de templates, versões, exclusão protegida, auditoria sem conteúdo sensível no log.
+8. **P08** Trocar hex do fluxo novo pelos tokens `--bc-*`. Não criar design system.
+9. **P09** Hardening: papel no servidor, scrub Sentry (corpo, formulário, token, cookie, replay), upload, XSS, rate limit reusando `utils/rateLimit.ts`.
+10. **P10** Vitest + critérios de aceite. E2E no Playwright já existente se o fluxo estiver estável.
+11. **P11** Performance, WCAG AA, responsivo.
+12. **P12** Rollout pela flag `contracts` (continua fail-closed, default desligada).
+
+P13 e P14 ficam para revisão e correção, fora deste plano de construção.
@@ -0,0 +1,53 @@
+# Contexto mestre para Cursor — EloPro Gerador de Contratos
+
+Use este texto no início de uma sessão longa do Cursor Agent, ou converta-o em regra local do projeto se a equipe desejar.
+
+Você está implementando o **Gerador de Contratos** dentro do EloPro/CRO. Não é um produto isolado.
+
+## Prioridade das fontes
+
+1. Stack e decisões explícitas do projeto.
+2. Documentação oficial EloPro/CRO do repositório.
+3. EloPro Design System V2.1/handoff.
+4. Especificação final `EloPro_Gerador_de_Contratos_Escopo_e_Especificacao_v1.0`.
+5. Protocolo V3 como origem das regras de negócio já consolidadas.
+6. Gerador de Propostas como referência de composição, nunca como fonte para copiar regra de negócio.
+
+Em conflito de arquitetura, prevalece EloPro. Em conflito visual, Design System. Em regra de negócio, prevalece a especificação final consolidada.
+
+## Não negociáveis
+
+- `workspace_id` é o tenant técnico.
+- Supabase Auth/SSR; sem login próprio.
+- feature flag `contracts`, fail-closed.
+- RLS em Postgres + autorização server-side.
+- owner/admin gerenciam templates; gestor/agent não.
+- superadmin não é atalho para editar documento privado do cliente em fluxo operacional comum.
+- Next.js 16 App Router, React 19, TS5, Tailwind v4.
+- DS EloPro e Lucide; não inventar tokens/components globais.
+- TanStack Query somente quando necessário.
+- Redis é efêmero/cache/locks/rate limit, não banco primário.
+- PDF via `@react-pdf/renderer`.
+- preview e PDF do mesmo Contract Document Model.
+- `.docx` e `.txt`, 5 MB, 50 campos únicos.
+- placeholders `{{chave}}`.
+- todos os campos obrigatórios no MVP.
+- autosave ~15 s; draft 24 h.
+- no máximo 10 modelos-base ativos por workspace.
+- mesmo nome => nova versão; sem overwrite.
+- template com draft ativo => delete bloqueado.
+- PDF não persistido como repositório no MVP.
+- Sentry sem conteúdo contratual sensível.
+- IA/Claude não é requisito do MVP.
+
+## Modo de trabalho
+
+Antes de editar:
+1. Leia arquivos reais relacionados.
+2. Reuse padrões existentes.
+3. Mostre plano curto.
+4. Faça mudanças pequenas e coesas.
+5. Rode testes/lint/typecheck relevantes.
+6. Reporte o que mudou e o que ficou pendente.
+
+Nunca resolva silenciosamente um decision gate sem evidência no repo ou aprovação explícita.
@@ -0,0 +1,32 @@
+---
+description: Regras obrigatórias do módulo EloPro Gerador de Contratos
+globs:
+  - "app/**/contracts/**"
+  - "components/**/contracts/**"
+  - "lib/**/contracts/**"
+  - "utils/**/contracts/**"
+  - "**/*contract*"
+alwaysApply: false
+---
+
+# EloPro Gerador de Contratos
+
+- Reuse arquitetura e helpers existentes do EloPro; não crie auth, RBAC, feature flag ou design system paralelos.
+- Tenant técnico = `workspace_id`; nunca confie em workspace_id arbitrário do client.
+- Feature flag = `contracts`, fail-closed.
+- Auth = Supabase Auth/SSR.
+- Gestão de templates = owner/admin somente.
+- Gestor/agent = fluxo operacional.
+- Use RLS + autorização server-side.
+- Templates: .docx/.txt, até 5 MB, até 50 chaves únicas {{chave}}.
+- data_* => date; valor_*/preco_* => number; demais => text.
+- Todos os campos obrigatórios no MVP.
+- Autosave ~15 s; draft TTL 24 h.
+- 10 modelos-base ativos/workspace; versões não contam como novos modelos.
+- Mesmo nome nunca sobrescreve; cria nova versão.
+- Draft ativo bloqueia exclusão da versão.
+- Preview e PDF devem usar o mesmo Contract Document Model.
+- PDF via @react-pdf/renderer e não é repositório permanente no MVP.
+- Design System EloPro V2.1 obrigatório; não usar os tokens antigos do protocolo.
+- Sentry deve scrubbar conteúdo do contrato, formulário, tokens e cookies.
+- Não adicionar dependências para parser/sanitização/storage sem resolver DT-CTR-001…004.
@@ -0,0 +1,71 @@
+# P00 — Discovery técnico e auditoria do módulo existente
+
+Você está trabalhando no repositório do **EloPro/CRO**. Antes de escrever qualquer código do Gerador de Contratos, faça uma auditoria completa do que já existe.
+
+## Contexto obrigatório
+
+A documentação oficial registra:
+- rota existente `/dashboard/contracts`;
+- feature flag `contracts`;
+- arquitetura Next.js App Router + Supabase/Postgres;
+- tenant por `workspace_id`;
+- papéis reais em `workspace_members.role` (`owner`, `admin`, `gestor`, `agent`) e `profiles.is_superadmin`;
+- helpers de permissão já existentes, como `isWorkspaceAdmin()`, `isWorkspaceManager()`, `getManagedTeamIds()` e equivalentes;
+- superadmin usa arquitetura própria e não deve ser confundido com operações normais do workspace.
+
+## Objetivo
+
+Descobrir o estado real do módulo de contratos, impedir duplicação de arquitetura e produzir um plano de migração/reuso antes da implementação.
+
+## Tarefas
+
+1. Localize todas as ocorrências de:
+   - `contracts`
+   - `/dashboard/contracts`
+   - feature flag `contracts`
+   - tabelas/migrations relacionadas a contratos/templates/drafts
+   - APIs, Server Actions, componentes e hooks relacionados.
+2. Mapeie:
+   - rotas e layouts;
+   - componentes server/client;
+   - schema atual;
+   - RLS/policies;
+   - helpers de autorização;
+   - feature flags e AppShell/sidebar;
+   - padrões de auditoria;
+   - padrões de Sentry;
+   - padrões de upload/Storage existentes;
+   - padrões de Server Actions vs Route Handlers;
+   - package manager, scripts, CI e convenções de migrations.
+3. Compare o estado atual com estes requisitos do novo módulo:
+   - famílias e versões de templates;
+   - placeholders dinâmicos;
+   - drafts temporários;
+   - preview + PDF;
+   - auditoria;
+   - RBAC;
+   - isolamento por `workspace_id`.
+4. NÃO implemente nada nesta fase.
+5. Classifique cada parte encontrada como:
+   - REUTILIZAR
+   - ADAPTAR
+   - MIGRAR
+   - REMOVER/DEPRECAR
+   - CRIAR
+6. Identifique conflitos com a especificação. Não escolha arbitrariamente. Registre-os como decisões necessárias.
+
+## Saída esperada
+
+Crie `docs/contracts/P00-discovery-audit.md` contendo:
+- inventário de arquivos;
+- diagrama textual da arquitetura atual;
+- schema/migrations encontradas;
+- feature flag e guards;
+- gaps contra RF/RN/CA do Gerador de Contratos;
+- estratégia recomendada de migração/reuso;
+- lista dos decision gates DT-CTR-001…007 com status `RESOLVIDO POR EVIDÊNCIA`, `PENDENTE` ou `NÃO APLICÁVEL`;
+- plano de execução para P01–P12.
+
+## Critério de conclusão
+
+Pare ao final da auditoria. Não altere produto, banco ou UI. Mostre um resumo com os 10 achados mais importantes e os bloqueios que precisam de decisão humana.
@@ -0,0 +1,57 @@
+# P01 — Fundação e arquitetura do módulo
+
+Implemente somente a fundação do Gerador de Contratos com base no resultado aprovado do P00.
+
+## Regras
+
+- Next.js 16 App Router + React 19 + TypeScript 5.
+- Não criar app separado; integrar ao AppShell EloPro.
+- Rota principal deve seguir o padrão real do repo e preservar `/dashboard/contracts` quando aplicável.
+- Feature flag `contracts` é obrigatória e fail-closed.
+- Sessão vem de Supabase Auth/SSR; sem login próprio.
+- Tenant vem do contexto autenticado/membership. Nunca confie em `workspace_id` arbitrário vindo do browser.
+- Papéis: Superadmin / owner/admin / gestor / agent, reutilizando helpers existentes.
+- Somente owner/admin gerenciam templates.
+- Gestor e agent executam o fluxo operacional.
+- Não criar novas libs ou abstrações globais sem necessidade comprovada.
+
+## Implementar
+
+1. Estrutura de pastas do módulo, separando apresentação, domínio e acesso a dados conforme padrões do repo.
+2. Guard de feature flag e membership.
+3. Guard server-side para gestão administrativa.
+4. Navegação/entrada do módulo no AppShell conforme padrão existente.
+5. Esqueleto das telas:
+   - Contratos
+   - Novo contrato
+   - Modelos de contrato (admin)
+   - Histórico (admin)
+6. Tipos de domínio centrais:
+   - TemplateFamily
+   - ContractTemplate
+   - TemplateField
+   - ContractDraft
+   - ContractAuditEvent
+   - ContractDocumentModel
+7. Catálogo de erros do módulo com códigos estáveis:
+   `TEMPLATE_INVALID_FORMAT`, `TEMPLATE_TOO_LARGE`, `TEMPLATE_NO_PLACEHOLDERS`, `TEMPLATE_TOO_MANY_FIELDS`, `TEMPLATE_LIMIT_REACHED`, `TEMPLATE_IN_USE`, `DRAFT_EXPIRED`, `DRAFT_SAVE_FAILED`, `PDF_GENERATION_FAILED`, `FEATURE_DISABLED`, `FORBIDDEN`, `RESOURCE_NOT_FOUND`.
+
+## Não fazer ainda
+
+- migrations definitivas;
+- parser DOCX;
+- PDF;
+- autosave;
+- telas finais;
+- API pública v1.
+
+## Qualidade
+
+- TypeScript strict conforme repo.
+- Reusar helpers do EloPro.
+- Sem duplicação de auth/permissions/feature flags.
+- Rodar lint/typecheck/testes mínimos disponíveis.
+
+## Entrega
+
+Ao final, relate arquivos criados/alterados, decisões herdadas do P00, riscos e o que ficou preparado para P02.
@@ -0,0 +1,76 @@
+# P02 — Banco, migrations, índices e RLS
+
+Implemente a persistência do Gerador de Contratos usando os padrões reais de migration do EloPro.
+
+## Modelo alvo
+
+Crie/adapte estas entidades sem duplicar estruturas equivalentes já existentes:
+
+1. `contract_template_families`
+   - `id`
+   - `workspace_id`
+   - `name`
+   - `slug`
+   - `is_active`
+   - `created_by`
+   - `created_at`
+
+2. `contract_templates`
+   - `id`
+   - `workspace_id`
+   - `family_id`
+   - `version`
+   - `original_filename`
+   - `storage_path` ou referência equivalente aprovada no P00
+   - `mime_type`
+   - `size_bytes`
+   - `checksum`
+   - `is_active`
+   - `created_by`
+   - `created_at`
+
+3. `contract_template_fields`
+   - `id`, `workspace_id`, `template_id`, `key`, `label`, `field_type`, `position`, `required`, `metadata`
+
+4. `contract_drafts`
+   - `id`, `workspace_id`, `user_id`, `template_id`, `values_json`, `status`, `last_saved_at`, `expires_at`, `created_at`
+
+5. `contract_audit_events`
+   - `id`, `workspace_id`, `actor_id`, `action`, `entity_type`, `entity_id`, `metadata`, `created_at`
+
+6. `app_connections`
+   - só criar se não existir estrutura equivalente no repo; caso exista, adaptar/reusar.
+
+## Regras obrigatórias
+
+- `workspace_id` em todas as entidades tenant-scoped.
+- Máximo de 10 modelos-base ativos por workspace; versões da mesma família não contam como novos modelos-base.
+- Versão de template é imutável após ativação, exceto estado permitido explicitamente.
+- Unicidade coerente para `family_id + version`.
+- Índices para listagem por workspace, família/versão, drafts por usuário/template e expiração.
+- Draft expira 24 h após último save elegível.
+- RLS deve ser a barreira principal, não apenas filtros da aplicação.
+
+## RLS mínima
+
+- SELECT templates: membro do workspace; fluxo operacional vê somente versões permitidas/ativas.
+- INSERT/gestão templates: owner/admin.
+- SELECT/UPSERT draft: próprio usuário no mesmo workspace.
+- SELECT audit: owner/admin no próprio workspace; superadmin apenas via mecanismos globais já existentes.
+- INSERT audit: somente caminho server/controlado; cliente não pode forjar actor/workspace.
+- Nunca usar service role no fluxo normal do módulo.
+
+## Testes adversariais obrigatórios
+
+Inclua testes/SQL checks cobrindo:
+- Tenant A não lê/escreve Tenant B.
+- agent/gestor não cria ou exclui template.
+- usuário não altera draft de outro usuário.
+- actor/workspace do audit não pode ser falsificado pelo browser.
+
+## Entrega
+
+- migrations idempotentes no padrão do repo;
+- documentação curta em `docs/contracts/P02-database-rls.md`;
+- output dos testes de RLS;
+- nenhuma API/UI além do mínimo necessário para compilar.
@@ -0,0 +1,58 @@
+# P03 — Upload, validação, parsing e versionamento técnico de templates
+
+Implemente o pipeline de templates do MVP.
+
+## Regras de produto
+
+- Formatos MVP: `.docx` e `.txt`.
+- Tamanho máximo: 5 MB.
+- Placeholder: `{{chave}}`.
+- Máximo: 50 chaves únicas.
+- Tipos:
+  - prefixo `data_` => `date`
+  - prefixo `valor_` ou `preco_` => `number`
+  - demais => `text`
+- Label: transformar underscore em espaço e humanizar.
+- Mesma chave repetida no documento representa um único campo lógico e deve receber o mesmo valor em todas as ocorrências.
+- Template sem placeholder válido deve ser rejeitado.
+- Mesmo nome base não sobrescreve: deve entrar no fluxo de nova versão.
+- Não editar in-place versão histórica.
+
+## Decision gates
+
+Antes de adicionar dependência:
+1. Verifique P00 para DT-CTR-001 (parser DOCX) e DT-CTR-002 (sanitização).
+2. Se o repo já tiver solução aprovada, reutilize.
+3. Se continuarem pendentes, NÃO invente silenciosamente. Implemente a interface/adapter e registre o bloqueio exato para aprovação humana.
+4. Respeite DT-CTR-003: não prometa fidelidade a recursos DOCX que a matriz aprovada não suporte.
+5. Respeite DT-CTR-004 para Storage.
+
+## Pipeline
+
+Upload → validar extensão/MIME/tamanho → armazenar/ler de forma segura → extrair conteúdo → sanitizar → detectar placeholders → deduplicar chaves → preservar ordem da primeira ocorrência → inferir tipos/labels → validar limites → calcular checksum → resolver família/nova versão → persistir template + fields → auditar.
+
+## Segurança
+
+- Não confiar só na extensão.
+- Não executar macros/scripts.
+- Sanitizar HTML/markup antes de qualquer preview.
+- Storage privado/URLs temporárias se esse for o padrão aprovado.
+- Nomes de arquivo normalizados.
+- Erros claros sem revelar stack trace.
+
+## Testes Vitest
+
+Cubra:
+- regex/placeholders;
+- chaves repetidas;
+- tipos inferidos;
+- label humanizado;
+- 0, 1, 50 e 51 campos;
+- 5 MB e acima;
+- MIME/extensão inconsistente;
+- mesmo nome => versão seguinte;
+- checksum e não sobrescrita.
+
+## Entrega
+
+Implemente serviços puros de parsing/normalização com boa testabilidade. Não construa ainda o wizard operacional completo.
@@ -0,0 +1,54 @@
+# P04 — Fluxo operacional: seleção, review e formulário dinâmico
+
+Construa o fluxo principal do usuário usando o EloPro Design System e padrões reais do Gerador de Propostas.
+
+## Telas
+
+- CTR-UI-01 Contratos
+- CTR-UI-02 Novo contrato — Selecionar modelo
+- CTR-UI-03 Novo contrato — Revisar modelo
+- CTR-UI-04 Novo contrato — Preencher informações
+
+## Fluxo
+
+Contratos → Novo contrato → listar templates ativos do workspace → selecionar um → carregar conteúdo e metadados → review read-only + campos detectados → “Preencher informações” → formulário dinâmico.
+
+## Regras
+
+- Um template por draft.
+- Ordenação por nome/versão conforme especificação.
+- Empty state: “Nenhum modelo disponível. Solicite ao administrador.” ou microcopy equivalente no padrão EloPro.
+- Formulário respeita ordem da primeira ocorrência.
+- Todos os campos obrigatórios.
+- number: positivo, até 2 decimais, contexto BRL quando aplicável.
+- date: controle de data acessível.
+- voltar para seleção com dados preenchidos exige Dialog de confirmação quando houver risco real de perda.
+- gestor/usuário não veem controles administrativos.
+- feature flag e auth sempre revalidados no servidor para mutações.
+
+## Arquitetura frontend
+
+- Server Components por padrão para carga inicial quando apropriado.
+- Client Components apenas para interação necessária.
+- TanStack Query v5 somente onde cache/fetch client-side trouxer benefício real; não duplicar Server Components sem motivo.
+- Evitar estado global novo sem necessidade.
+- Lucide React para ícones.
+- `@dnd-kit` NÃO é necessário neste fluxo; não use sem necessidade funcional.
+
+## UX
+
+Use componentes existentes do EloPro: Button, Card/OpenFramePanel, Input, Select, DateField, Badge/SemanticMarker, Dialog, Toast/Tooltip quando apropriado.
+
+Implemente estados loading, empty, error, disabled e blocked. Mensagens devem explicar o que ocorreu e qual o próximo passo.
+
+## Testes
+
+- somente templates do workspace;
+- seleção única;
+- review read-only;
+- campos obrigatórios;
+- tipos corretos;
+- voltar com/sem dados;
+- papéis sem acesso admin.
+
+Pare antes de implementar preview/PDF; isso vem em P06.
@@ -0,0 +1,48 @@
+# P05 — Drafts, autosave e restauração
+
+Implemente a preservação de progresso do formulário.
+
+## Regras
+
+- Autosave aproximadamente a cada 15 segundos após alterações, com debounce adequado para evitar request por tecla.
+- Draft identificado por `workspace_id + user_id + template_id` ou pela estratégia aprovada no P02.
+- Cada draft fixa uma versão exata de template.
+- TTL: 24 h desde o último save elegível.
+- Ao retornar dentro do TTL: oferecer “Encontramos um progresso não salvo. Deseja restaurar?” com data/hora quando disponível.
+- SIM: restaurar valores.
+- NÃO: abandonar/excluir draft e iniciar limpo.
+- Voltar do preview nunca apaga os valores.
+- Logout/limpeza deve impedir exposição de dados via cache/histórico do app.
+
+## Redis
+
+Use Redis/ioredis apenas conforme arquitetura aprovada no P00:
+- cache/coordenação/locks/TTL efêmero se necessário;
+- não transforme Redis em banco primário do domínio;
+- persistência mínima confiável continua em Postgres quando necessária para restauração do produto.
+
+## Concorrência
+
+- Não há edição colaborativa.
+- Drafts são isolados por usuário.
+- Se houver múltiplas abas, evite sobrescrita silenciosa quando possível; use `updated_at`/versionamento otimista se o padrão do repo permitir.
+- Draft ativo deve bloquear exclusão da versão de template correspondente.
+
+## UI
+
+Exibir status discreto e acessível:
+- Salvando…
+- Salvo
+- Não foi possível salvar. Seus dados continuam nesta tela. Tentar novamente / nova tentativa automática conforme padrão do repo.
+
+Não bloquear digitação por falha temporária de autosave.
+
+## Testes
+
+- autosave não dispara por tecla;
+- salva após janela esperada;
+- restaura dentro de 24 h;
+- expira após TTL;
+- recusa restauração remove/abandona;
+- draft de outro usuário/workspace não é acessível;
+- template com draft ativo fica protegido.
@@ -0,0 +1,48 @@
+# P06 — Contract Document Model, preview, PDF e download
+
+Implemente o núcleo de renderização garantindo consistência entre tela e PDF.
+
+## Princípio obrigatório
+
+Não mantenha duas fontes de verdade. Crie/use um `ContractDocumentModel` intermediário derivado de:
+
+Template + campos detectados + valores normalizados → ContractDocumentModel → Web Preview Renderer + @react-pdf/renderer.
+
+## Regras
+
+- Nenhum `{{placeholder}}` pode permanecer no preview aprovado ou no PDF.
+- Mesma chave repetida usa o mesmo valor em todas as ocorrências.
+- Cláusulas fixas devem permanecer semanticamente inalteradas.
+- Voltar do preview mantém 100% dos valores.
+- Durante geração: botão desabilitado e feedback “Gerando seu contrato…” no tom EloPro.
+- Sucesso: habilitar download.
+- Meta de performance: PDF em até 5 s no cenário de referência.
+- MVP não cria repositório permanente de PDFs.
+
+## Nome do arquivo
+
+`[NomeDoTemplate]_[NomeDoCliente].pdf`
+
+- Preferir valor de `razao_social` ou equivalente mapeado.
+- Fallback: `[NomeDoTemplate]_contrato.pdf`.
+- Normalizar caracteres inseguros e evitar path traversal.
+
+## Fidelidade
+
+A especificação exige equivalência de conteúdo/estrutura, não pixel-perfect entre DOM e React PDF. Documente diferenças inevitáveis de paginação/fontes dentro da matriz DOCX aprovada.
+
+## Segurança/privacidade
+
+- PDF deve ser gerado server-side ou no local apropriado do padrão do repo sem expor segredos.
+- Não enviar conteúdo contratual integral ao Sentry.
+- Não persistir o PDF após o ciclo necessário para download, salvo mecanismo temporário já aprovado.
+
+## Testes
+
+- placeholder residual = falha;
+- cláusula fixa alterada = falha;
+- valores repetidos consistentes;
+- nome do arquivo normalizado;
+- geração duplicada por double click impedida;
+- falha de PDF retorna erro acionável e preserva dados;
+- benchmark do cenário de referência.
@@ -0,0 +1,54 @@
+# P07 — Administração de modelos, versões, exclusão protegida e histórico
+
+Implemente o fluxo administrativo, somente para owner/admin do workspace.
+
+## Telas
+
+- CTR-UI-07 Modelos de contrato
+- CTR-UI-08 Subir modelo
+- CTR-UI-09 Revisar campos identificados
+- CTR-UI-10 Revisar e ativar modelo
+- CTR-UI-11 Nova versão
+- CTR-UI-12 Histórico
+
+## Regras
+
+- Máximo de 10 modelos-base ativos por workspace.
+- Versões da mesma família não consomem nova cota.
+- Mesmo nome base => modal confirmando nova versão; nunca sobrescrever.
+- Versão nova recebe vN+1.
+- Versão histórica permanece imutável.
+- Versão com draft ativo não pode ser excluída.
+- Exclusão é destrutiva: Dialog obrigatório com confirmação clara.
+- Gestor/Usuário não podem acessar nem chamar mutações administrativas, mesmo por URL direta.
+- Superadmin não deve modificar templates privados como rotina operacional; seguir mecanismos de plataforma para suporte.
+
+## Auditoria
+
+Registrar no mínimo:
+- `contract.template_uploaded`
+- `contract.template_version_created`
+- `contract.template_delete_blocked`
+- `contract.template_deleted`
+- `contract.template_selected`
+- `contract.draft_restored`
+- `contract.previewed`
+- `contract.pdf_generated`
+- `contract.pdf_downloaded`
+- `contract.integration_toggled`
+
+Cada evento deve incluir actor, workspace, timestamp, entidade e metadados mínimos. Não guardar conteúdo contratual completo no audit log.
+
+## Histórico
+
+Admin vê somente seu workspace. Use paginação/filtros conforme padrão existente. Se filtros avançados estiverem fora do MVP, implemente somente o necessário para leitura útil sem expandir escopo.
+
+## Testes
+
+- quota de 10 famílias;
+- versão não aumenta quota;
+- nova versão preserva anterior;
+- draft ativo bloqueia delete;
+- admin only;
+- audit actor/workspace não falsificável;
+- eventos mínimos emitidos.
@@ -0,0 +1,57 @@
+# P08 — Conformidade UX/UI com EloPro Design System
+
+Faça uma revisão e implementação visual do módulo inteiro sem inventar um design system paralelo.
+
+## Fonte de verdade
+
+Use os componentes/tokens existentes do EloPro e a composição do Gerador de Propostas como referência de aplicação prática. Não copie telas cegamente; preserve a semântica específica de contratos.
+
+## Tokens essenciais
+
+- Midnight Ink `#071B45`
+- Cloud White `#FBFBFE`
+- Primary Blue `#1F6FFF`
+- Blue 600 `#225EDB`
+- Bright Blue `#2F8FFF`
+- Soft Blue `#DCEBFF`
+- Aqua Signal `#00C2A8`
+- Warning `#F39A2D`
+- Insight `#7C8CFF`
+- Error `#E63946`
+- Text Secondary `#69758A`
+- Border `#D1D8E3`
+- Fonte principal: Manrope
+
+Não recrie tokens antigos do protocolo (Montserrat/dark #323232/verde #004E32/lime #CCFF00).
+
+## Componentes preferenciais
+
+Button, IconButton, Card, OpenFramePanel, Input, Select, Checkbox, Radio, Switch, DateField, DateRangeField, Badge, SemanticMarker, Tag, Tabs, CapsuleTabs, ContextGroup, SectionPill, Toast, Tooltip, Dialog, JourneyTrail/ContextLayers somente quando a semântica justificar.
+
+## Revisar todas as telas CTR-UI-01…12
+
+Para cada tela, validar:
+- hierarquia visual;
+- estados loading/empty/error/success/disabled/autosave/blocked;
+- microcopy clara;
+- foco visível;
+- teclado;
+- labels;
+- contraste;
+- responsividade;
+- ações destrutivas com confirmação;
+- consistência com AppShell.
+
+## Regras de UX
+
+- self-service;
+- progressive disclosure;
+- defaults seguros;
+- feedback claro;
+- preservação de progresso;
+- baixo esforço cognitivo;
+- nenhuma interação dependente só de cor.
+
+## Entrega
+
+Corrija divergências encontradas, sem alterar regras de negócio. Gere `docs/contracts/P08-ui-conformance.md` com checklist por tela e componentes reutilizados.
@@ -0,0 +1,55 @@
+# P09 — Segurança, privacidade, observabilidade e hardening
+
+Faça hardening do módulo sem expandir escopo funcional.
+
+## Segurança obrigatória
+
+- RLS por `workspace_id`.
+- Autorização server-side em toda mutação.
+- Feature flag fail-closed.
+- Proteção contra IDOR.
+- Upload: tamanho/MIME/extensão, sanitização, nomes seguros.
+- Preview sem XSS.
+- Storage privado/URL temporária se aplicável.
+- Sem service role no fluxo normal.
+- Rate limit para upload/geração PDF se padrão/necessidade justificar; Redis é permitido.
+- Após logout, voltar no browser não deve revelar dados anteriores.
+- Sem secrets/tokens/cookies em logs.
+
+## Sentry
+
+Configurar/validar client/server/edge conforme padrão EloPro.
+
+Eventos técnicos relevantes:
+- `template.upload.failed`
+- `template.parse.failed`
+- `pdf.generation.failed`
+- `pdf.generation.timeout`
+- `draft.save.failed`
+- `tenant.access.denied`
+
+Aplicar scrubbing para remover:
+- valores de formulário;
+- conteúdo do template/contrato;
+- PDF;
+- tokens/cookies;
+- credenciais;
+- URLs assinadas sensíveis.
+
+Adicionar correlation/request id se o repo tiver padrão.
+
+## Testes adversariais
+
+- workspace A tenta IDs do B;
+- agent chama mutação admin;
+- MIME forjado;
+- HTML/script malicioso;
+- nome de arquivo com traversal;
+- payload excessivo;
+- Sentry não recebe PII/conteúdo contratual;
+- feature flag desligada;
+- logout + browser back.
+
+## Entrega
+
+Gere relatório `docs/contracts/P09-security-review.md` com achados, correções e riscos residuais.
@@ -0,0 +1,56 @@
+# P10 — Testes e critérios de aceite
+
+Construa a suíte de testes do módulo alinhada à especificação.
+
+## Unitários — Vitest
+
+Cobrir regras puras:
+- placeholders;
+- deduplicação;
+- labels;
+- inferência de tipos;
+- validação de campos;
+- quota de famílias;
+- versionamento;
+- nome de PDF;
+- expiração de draft;
+- Contract Document Model;
+- normalização/sanitização onde testável.
+
+## Integração
+
+Cobrir:
+- upload → parse → persistência;
+- template → fields;
+- draft → save/restore;
+- preview → PDF;
+- RBAC;
+- RLS;
+- audit events;
+- feature flag.
+
+## Critérios CA-CTR obrigatórios
+
+- CA-CTR-001: Tenant A não acessa template/draft/audit do Tenant B.
+- CA-CTR-002: PDF ≤ 5 s no cenário de referência.
+- CA-CTR-003: interrupção + retorno dentro de 24 h oferece restauração.
+- CA-CTR-004: upload sem tags é bloqueado.
+- CA-CTR-005: logout + voltar não revela contrato anterior.
+- CA-CTR-006: mesma chave repetida usa valor consistente.
+- CA-CTR-007: nome existente oferece v2 e mantém v1.
+- CA-CTR-008: template com draft ativo não exclui.
+- CA-CTR-009: voltar do preview mantém 100% dos valores.
+- CA-CTR-010: PDF sem placeholder residual e cláusulas fixas preservadas.
+- CA-CTR-011: Gestor/Usuário não acessam gestão de templates.
+- CA-CTR-012: feature `contracts` desligada impede acesso.
+
+## E2E
+
+Use o framework E2E já existente no repo. Se não houver, não adicione uma nova stack silenciosamente: registre a lacuna e implemente o máximo possível com o padrão aprovado.
+
+Fluxo mínimo E2E:
+login → contracts → novo → selecionar template → review → preencher → autosave → preview → editar → gerar → baixar.
+
+## Saída
+
+Crie uma matriz `docs/contracts/P10-test-matrix.md` ligando teste → RF/RN/CA. Nenhum critério crítico pode ficar sem cobertura ou justificativa explícita.
@@ -0,0 +1,41 @@
+# P11 — Performance, acessibilidade e responsividade
+
+Otimize e valide o módulo sem alterar regras de negócio.
+
+## Metas
+
+- acesso ao módulo ≤ 3 s em condições de referência;
+- PDF ≤ 5 s;
+- autosave sem degradação de digitação;
+- loading sem layout shift desnecessário.
+
+## Performance
+
+- revisar boundaries Server/Client Components;
+- eliminar fetch duplicado;
+- usar TanStack Query somente onde necessário;
+- revisar payloads de template/preview;
+- lazy load quando apropriado;
+- evitar re-render excessivo do formulário dinâmico;
+- medir geração de PDF;
+- checar índices das queries críticas.
+
+## Acessibilidade — referência WCAG AA
+
+- foco visível;
+- navegação por teclado;
+- labels e descrições;
+- erro associado ao campo;
+- Dialog com focus trap/retorno de foco conforme componente DS;
+- status de autosave com `aria-live` quando apropriado;
+- loading acessível;
+- nenhuma informação depende apenas de cor;
+- contraste conforme DS.
+
+## Responsividade
+
+Desktop é principal, mas a UI web deve responder a larguras menores sem quebrar tarefas essenciais. Não criar app mobile nativo.
+
+## Entrega
+
+Crie `docs/contracts/P11-performance-a11y.md` com medições, gargalos, correções e pendências.
@@ -0,0 +1,45 @@
+# P12 — Homologação, rollout e release por feature flag
+
+Prepare o Gerador de Contratos para release controlado.
+
+## Antes do rollout
+
+1. Rodar lint, typecheck, unitários, integração e E2E existentes.
+2. Validar migrations em ambiente seguro.
+3. Validar RLS com usuários/tenants distintos.
+4. Testar templates reais representativos da matriz DOCX aprovada.
+5. Confirmar Sentry sem vazamento de conteúdo.
+6. Confirmar feature flag `contracts` fail-closed.
+7. Confirmar papéis:
+   - owner/admin: gestão + operação;
+   - gestor/agent: operação, sem gestão;
+   - superadmin: mecanismos de plataforma, sem edição operacional rotineira de documentos privados.
+8. Confirmar que PDFs não estão sendo armazenados permanentemente no MVP.
+9. Confirmar backup/restauração 24 h.
+10. Medir metas de 3 s / 5 s no cenário acordado.
+
+## Rollout
+
+Use o mecanismo real de feature flags do EloPro. Não crie flag paralela.
+
+Sugestão de ordem, se compatível com a plataforma:
+- workspace interno/teste;
+- workspace piloto;
+- pequena coorte;
+- expansão gradual.
+
+Não habilite globalmente se CA críticos falharem.
+
+## Definition of Done
+
+Marcar cada item da seção 24 da especificação como `PASS`, `FAIL` ou `WAIVED COM JUSTIFICATIVA`.
+
+## Entrega
+
+Crie:
+- `docs/contracts/P12-release-checklist.md`
+- notas de rollback;
+- lista de migrations;
+- lista de variáveis/configurações necessárias;
+- riscos residuais;
+- recomendação objetiva de `READY` ou `NOT READY` baseada somente nos critérios técnicos, sem mascarar falhas.
@@ -0,0 +1,44 @@
+# P13 — Auditoria final de código independente
+
+Faça uma revisão crítica do Gerador de Contratos como se você NÃO tivesse escrito a implementação.
+
+## Não altere código no primeiro passe
+
+Primeiro produza achados classificados por severidade:
+- P0 crítico
+- P1 alto
+- P2 médio
+- P3 baixo
+
+## Revisar
+
+1. Tenant/RLS/IDOR.
+2. RBAC real vs UI.
+3. Feature flag fail-closed.
+4. Imutabilidade/versionamento de templates.
+5. Quota de 10 famílias.
+6. Draft TTL 24 h e proteção de exclusão.
+7. Consistência Contract Document Model → preview/PDF.
+8. Conteúdo fixo e placeholders residuais.
+9. Upload e XSS.
+10. Sentry/privacidade.
+11. App Router/Server Components/Actions conforme padrões do repo.
+12. Uso indevido de client components/TanStack Query.
+13. Design System EloPro; componentes ou tokens paralelos.
+14. Acessibilidade.
+15. Performance.
+16. Cobertura de CA-CTR-001…012.
+17. Débitos/pendências DT-CTR-001…007.
+18. Duplicação com módulo `/dashboard/contracts` legado.
+
+## Depois da auditoria
+
+Apresente:
+- tabela de achados com arquivo/linha quando possível;
+- impacto;
+- evidência;
+- correção recomendada;
+- risco de regressão;
+- itens sem evidência suficiente.
+
+Somente após aprovação do relatório, aplique correções P0/P1 em uma segunda etapa.
@@ -0,0 +1,29 @@
+# P14 — Prompt reutilizável para bugfix sem regressão
+
+Corrija o bug descrito abaixo no módulo Gerador de Contratos sem alterar comportamentos não relacionados.
+
+## Bug
+
+[COLE AQUI O BUG, PASSOS PARA REPRODUZIR, RESULTADO ATUAL E RESULTADO ESPERADO]
+
+## Processo obrigatório
+
+1. Reproduza/identifique a causa raiz antes de alterar código.
+2. Localize RF/RN/CA afetados.
+3. Verifique se o problema envolve tenant, RLS, RBAC, feature flag, versionamento, draft, preview/PDF ou Design System.
+4. Escreva teste de regressão que falha antes da correção, quando tecnicamente viável.
+5. Faça a menor correção segura.
+6. Execute testes relacionados + lint/typecheck.
+7. Não adicione dependências sem necessidade e aprovação.
+8. Não relaxe segurança/RLS para “fazer funcionar”.
+9. Não use service role para contornar policy no fluxo normal.
+10. Não envie conteúdo contratual ao Sentry.
+
+## Saída
+
+Informe:
+- causa raiz;
+- arquivos alterados;
+- teste de regressão;
+- comportamento após correção;
+- riscos/efeitos colaterais verificados.
@@ -0,0 +1,67 @@
+# Cursor Prompt Pack — EloPro Gerador de Contratos
+
+Versão: 1.0  
+Base: `EloPro_Gerador_de_Contratos_Escopo_e_Especificacao_v1.0`  
+Objetivo: construir o módulo **Gerador de Contratos** dentro do ecossistema EloPro/CRO sem criar arquitetura, padrões visuais ou mecanismos paralelos aos já existentes.
+
+## Como usar
+
+1. Execute os prompts **na ordem** abaixo em uma branch dedicada.
+2. Cole cada prompt no Cursor Agent/Composer com acesso ao repositório completo.
+3. Não pule o **P00 — Discovery/Auditoria**. A documentação oficial já registra um módulo `/dashboard/contracts` protegido por feature flag `contracts`; o primeiro trabalho é descobrir o que existe e reaproveitar/migrar corretamente.
+4. Em cada fase, exija que o Cursor:
+   - leia os arquivos reais antes de alterar código;
+   - apresente um plano curto;
+   - implemente apenas o escopo da fase;
+   - execute lint/testes aplicáveis;
+   - entregue um relatório final com arquivos alterados, decisões, pendências e riscos.
+5. Não aprove automaticamente novas dependências não previstas. Para parser DOCX, sanitização, Storage, deploy/API externa e migração do módulo existente, siga os **decision gates** da especificação.
+
+## Ordem de execução
+
+- `P00_DISCOVERY_AUDIT.md` — auditoria obrigatória do módulo existente
+- `P01_FOUNDATION_ARCHITECTURE.md` — fundação, feature flag, guards, estrutura de domínio
+- `P02_DATABASE_RLS.md` — schema, migrations, índices e RLS
+- `P03_TEMPLATES_UPLOAD_PARSER.md` — upload, validação, parsing, placeholders, famílias/versões
+- `P04_USER_FLOW_WIZARD.md` — seleção, review, formulário dinâmico, validação
+- `P05_DRAFTS_AUTOSAVE_RESTORE.md` — autosave 15 s, TTL 24 h, Redis/Postgres
+- `P06_PREVIEW_AND_PDF.md` — Contract Document Model, preview, React PDF e download
+- `P07_ADMIN_TEMPLATES_AUDIT.md` — gestão admin, versionamento, exclusão protegida, auditoria
+- `P08_UX_DESIGN_SYSTEM.md` — conformidade com EloPro Design System e Gerador de Propostas
+- `P09_SECURITY_OBSERVABILITY.md` — hardening, Sentry, upload seguro, XSS, rate limit
+- `P10_TESTS_ACCEPTANCE.md` — Vitest + integração/E2E + critérios CA-CTR
+- `P11_PERFORMANCE_ACCESSIBILITY.md` — performance, WCAG AA e responsividade
+- `P12_RELEASE_FEATURE_FLAG.md` — homologação, rollout e Definition of Done
+- `P13_CODE_REVIEW_AUDIT.md` — revisão final independente
+- `P14_BUGFIX_REGRESSION.md` — prompt reutilizável para correções sem regressão
+
+## Regras imutáveis do produto
+
+- Tenant técnico: `workspace_id`.
+- Auth: Supabase Auth/SSR; sem login próprio do módulo.
+- Feature flag: `contracts`, comportamento fail-closed.
+- Papéis EloPro: Superadmin, Administrador (`owner/admin`), Gestor (`gestor`), Usuário (`agent`).
+- Apenas Administrador gerencia templates.
+- UI deve reutilizar o **EloPro Design System V2.1**; não criar um design system paralelo.
+- Stack oficial: Next.js 16 App Router, React 19, Tailwind CSS v4, Lucide React, TanStack Query v5, @react-pdf/renderer, Supabase, Redis/ioredis, Sentry, TypeScript 5, Vitest, ESLint 9, postgres+tsx. `@dnd-kit` está disponível, mas só deve ser usado quando houver necessidade funcional real.
+- IA via Anthropic/Claude não é dependência do MVP.
+- Templates MVP: `.docx` e `.txt`, até 5 MB, até 50 chaves únicas `{{chave}}`.
+- Tipos: `data_` => date; `valor_`/`preco_` => number; demais => text.
+- Todos os campos são obrigatórios no MVP.
+- Draft: autosave aproximadamente a cada 15 s; TTL de 24 h após o último save elegível.
+- Preview e PDF devem derivar do mesmo Contract Document Model.
+- PDF final não deve persistir como repositório permanente no MVP.
+- Mesmo nome de template nunca sobrescreve: cria fluxo de nova versão.
+- Versão com draft ativo não pode ser excluída.
+- Máximo de 10 **modelos-base ativos** por workspace; versões não consomem cota extra.
+- Conteúdo contratual não deve vazar para Sentry/telemetria.
+
+## Decision gates que não podem ser inventados silenciosamente
+
+- DT-CTR-001 — parser DOCX (Mammoth.js ou equivalente JS): verificar dependências/padrão real do repo; se inexistente, registrar necessidade antes de adicionar.
+- DT-CTR-002 — sanitização HTML: verificar solução existente; se inexistente, registrar decisão.
+- DT-CTR-003 — matriz de recursos DOCX suportados: tabelas, imagens, headers/footers, listas, estilos etc.
+- DT-CTR-004 — Storage de templates: confirmar Supabase Storage ou mecanismo existente.
+- DT-CTR-005 — deploy/CI/package manager: seguir o repositório.
+- DT-CTR-006 — API externa `/api/v1`: só expor se o padrão real do EloPro exigir.
+- DT-CTR-007 — migração do módulo `/dashboard/contracts` existente: resolver após P00.