# Plano 02 — Governança IA-First e Especificação Viva

> **Milestone:** M0 · **Depende de:** 01 · **Habilita:** 03–15
> **Objetivo:** fazer do "caminho correto" o caminho de menor resistência — para
> humanos e agentes de IA — antes de existir código de negócio.

---

## 1. Contexto e referências

O `cms/` provou que specs + stubs + protocolo de sessão reduzem alucinação e
retrabalho; o `sucesu-cms` provou que `MODULE.md` e convenções grep-friendly
economizam contexto; o `prefeituras_v5` mostrou o custo de não tê-los. Aqui,
governança é o **primeiro** artefato, não o último.

---

## 2. Entregáveis

1. **Constituição do repositório**
   - `AGENTS.md` (global): segurança, não-regressão, tarefas granulares, staging de
     contexto, regras de fronteira, convenções de resposta.
   - `CONTRIBUTING.md`: fluxo de branch/MR, DoD, revisão.
2. **Specs vivas** em `wiki/specs/` (numeradas), cada uma com dono e status:
   - `00-visao.md`, `01-arquitetura.md`, `02-dominio-prefeituras.md`,
   - `03-layout-e-slots.md`, `04-acessibilidade-ux.md`, `05-seguranca-lgpd.md`,
   - `06-observabilidade.md`, `07-migracao-legado.md`, `08-ia-e-qualidade.md`,
   - `09-grep-friendly.md` (token canônico + tabela por artefato do ADR-004).
   - `10-migracoes-e-dados.md` (template + checklist do ADR-017).
   - `11-frontend-moderno.md` (semântica, mínimo JS, CSS moderno, PWA — ADR-010).
   - `12-postgres-18.md` (tipos, migrações seguras e tuning do PG 18 — ADR-007/017).
   - `13-i18n.md` (locales, JSONB por locale, middleware, hreflang — ADR-012).
   - `14-dados-abertos.md` (catálogo, DCAT/INDA, export, licença — ADR-018).
   - `15-lgpd-privacidade.md` (classificação, DSAR, retenção, incidentes — ADR-019).
   - `16-edge-apache-whm.md` (proxy burro do WHM, isolamento do cPanel, storage fora da cota — ADR-005/006).
   - `17-up-prod.md` (contrato do `scripts/update_prod.sh`: subir/atualizar produção com rollback e otimizações — ADR-005/008).
   - `16-rate-limiting.md` (camadas borda/app/form, Valkey, `429` — ADR-021).
   - `17-cache-resposta-etag.md` (`Cache-Control`, ETag/304, CSRF fora do HTML — ADR-022).
   - `18-media-gallery.md` (ingestão única, AVIF/WebP, `<picture>`, catálogo — ADR-026).
   - `19-seo.md` (service, `@graph`, arquivos de raiz, redirects, analytics — ADR-027).
3. **`wiki/DESIGN.md`** (fonte única visual): tokens, tipografia (default de conteúdo
   **Atkinson Hyperlegible Next** — ADR-011), espaçamento, regras de cor (oklch + fallback hex),
   z-index permitidos, estados de foco.
4. **Protocolo de sessão/IA**: template de log de sessão, `.STAGING.md`, regra
   "ler a spec antes de editar", tags `@intent`/`@see`/`@debt`.
5. **Convenção grep-friendly** (`wiki/specs/09-grep-friendly.md` + ADR-004): cada
   feature tem um **token canônico** e todos os artefatos derivam dele em todas as
   camadas/estilos — classes (`DiarioOficialController`), funções
   (`fn diarioOficialClean()`), views (`diario-oficial-edit.blade.php`), rotas
   (`diario-oficial.index`), migrations/tabelas (`diario_oficial_*`), testes, slots e
   logs. Vale para `modules`, `services`, `layout` e os componentes do `core`; o lado
   público usa o sufixo `Portal`.
6. **Guia de estilo funcional** (`wiki/specs/08-ia-e-qualidade.md`): nativo primeiro,
   funções puras/focadas, injeção de dependência, logs estruturados obrigatórios e
   padronização de lint/fmt (Pint + Prettier/ESLint). **Sem limite de linhas** — o
   critério é funcionalidade e efetividade.
7. **Skills/subagentes** (se o harness suportar): `module-creator`, `a11y-audit`,
   `e2e-scenario`, `migration-reviewer`.
8. **Determinismo e padronização** (ADR-001, fundamento): regras **determinísticas** —
   clock/aleatoriedade **injetados**, ordem **explícita**, dados **idempotentes**; nada de
   `now()`/`rand()` soltos; testes **sem flaky**. Padrão único em todo artefato (token canônico,
   blueprint/stubs, `make`).

> Toda documentação vive em `/wiki`. A raiz do repositório é Laravel típico; `/src`
> contém só `core`, `services`, `layout`, `modules` e `tests-e2e`.

## 3. Atividades

- [x] Criar `/AGENTS.md` com a seção de segurança (`NUNCA rm -rf`, git read-only,
      `.pi/trash/`, executar no container, não em `vendor/`).
- [x] Adotar **tasks granulares** (uma por fase, fechada ao fim da fase).
- [x] Definir nomenclatura grep-friendly: token canônico por módulo e a tabela de
      derivação por artefato (ADR-004); renomeações do Blueprint como exemplo.
- [ ] Criar o gate `tools/name-check` (todo arquivo em `src/modules/{Modulo}` carrega o token).
- [x] Definir o template de **Action** (uma ação por arquivo, focada e testável,
      `declare(strict_types=1)`, dependências injetadas, `@intent`).
- [x] Definir o workflow **Contract-First**: `Action` concreta (função/classe) → `Teste`;
      interfaces só onde há porta/DI real.
- [x] Padronizar lint/fmt: **Pint** (PHP), **Prettier + ESLint** (JS/TS); `make check`
      e `make check` obrigatórios; hook de pré-commit opcional.
- [ ] Publicar os checklists de acessibilidade (base: guidelines eMAG do
      `prefeituras_v5/.agents/guidelines/accessibility`) e UX (foco, teclado, alvos ≥44px).
- [x] Criar o log de sessão template e a regra de dívida técnica (`// @debt [ID]`).
- [x] Documentar as regras de **determinismo** (clock/IdGen injetados, ordenação explícita,
      idempotência de migrations/seeds) em `wiki/specs/08-ia-e-qualidade.md` (ADR-001).

## 4. Testes e evidências

- [ ] `make check term=Noticia` retorna arquivos em Model/Action/Test (prova de localidade léxica).
- [x] Script `bash tools/docs-check.sh` valida que toda spec tem status e link no índice.
- [ ] Um agente novo consegue criar um módulo seguindo só `AGENTS.md` + spec.

## 5. Definition of Done

- [ ] `AGENTS.md`, `CONTRIBUTING.md`, `wiki/DESIGN.md` e 20 specs em `wiki/specs/` commitados.
- [x] Checklist de acessibilidade/UX linkado no `wiki/DESIGN.md`.
- [x] Guia funcional (nativo primeiro + DI + logs) e spec grep-friendly publicados.
- [x] Protocolo de sessão e dívida técnica documentados.
- [ ] Nenhum item do plano depende de conhecimento tácito não escrito.

## 6. Riscos

| Risco | Mitigação |
|---|---|
| Documentação virar cemitério | `docs-check` no CI + dono por spec + revisão trimestral |
| Excesso de regras engessar | Regra mínima; exceções via ADR |