# Spec 08 — IA e qualidade: guia funcional, determinismo e dívida

> **Dono:** Core/Qualidade · **Status:** Proposta · **Plano:** 02, 05
> **Relaciona:** ADR-001, ADR-002, ADR-008, ADR-023, ADR-024
> **Objetivo:** fixar o **guia funcional** de código (nativo primeiro, DI, sem abstrações
> especulativas) e as **regras de determinismo** que tornam o projeto previsível, testável e
> seguro para agentes de IA e humanos.

---

## 1. Princípios de código (ADR-001)

1. **Nativo primeiro** — esgote Laravel/PHP antes de qualquer pacote ou abstração própria.
2. **Funcional e concreto** — funções pequenas e focadas; classes concretas.
   **Proibido:** `trait`, `abstract`, generics, `Result<T>`, *magic methods* desnecessários.
3. **Duplicação é aceitável** quando elimina acoplamento ou indireção — não crie a "abstração
   certa" para dois casos.
4. **Injeção de dependência** — dependências entram pelo construtor/assinatura; **nada** de
   `new`/`resolve()`/`app()` escondidos no corpo. Use as portas do `core` onde há DI real.
5. **Sem limite de linhas** — o critério é funcionalidade e efetividade, não tamanho.
6. **`declare(strict_types=1)`** em todo arquivo PHP.
7. **Logs estruturados obrigatórios** (ADR-024): JSON com `module`, `action`, `id`, `user`,
   `ts`, `duration_ms` — nunca `error_log`/`var_dump`.

## 2. Action — template canônico

Uma **Action por arquivo**, focada, testável e nomeada pelo token canônico (spec 09).

```php
<?php
declare(strict_types=1);

namespace Modules\Noticias\Logic\Actions;

// @intent: publicar uma notícia e agendar indexação
// @see: wiki/specs/09-grep-friendly.md
final class PublicarNoticia
{
    public function __construct(
        private readonly Relogio $relogio,        // clock injetado (determinismo)
        private readonly NotificacaoService $notificacao,
    ) {}

    public function execute(Noticia $noticia, string $autorId): Noticia
    {
        // ... foco único; sem `new`, sem `resolve()`
    }
}
```

Regras: dependências **injetadas**; sem estado mutável global; efeitos colaterais explícitos;
retorno concreto (nunca `Result<T>`); erros via exceção de domínio (`ProblemDetailsException`).

## 3. Contract-First

- Escreva a **Action concreta** → escreva o **teste** → só então integre.
- **Interfaces apenas onde há porta/DI real** (ex.: contrato do `core` para um service);
  não crie interface "para poder mockar".
- Feature nova: testes **estruturais** durante o build. Bug: **teste vermelho → correção →
  verde** (nunca corrija sem teste que reproduza).

### 3.1 Blueprint e stubs (vermelho→verde)

- O **Blueprint** é o módulo-exemplo canônico; os **stubs** em `src/core/Stub/` são a fonte do
  scaffolding e evoluem **junto** com o Blueprint. Guia: `src/core/Stub/README.md`.
- `make:module <Modulo>` cria a estrutura **e os testes**; a estrutura-alvo é
  `src/modules/{Grupo}/{Modulo}/` (ADR-014) — grupo e `ModuleProvider` são concluídos no **F2**.
- Política: o artefato nasce de um teste que **falha** (vermelho), implementa-se até ficar
  **verde** e o teste **nunca** é removido.

## 4. Lint e formatação

| Linguagem | Ferramenta | Comando |
|---|---|---|
| PHP | **Pint** (`preset laravel` + `declare_strict_types`) | `make check` (corrige e valida) |
| JS/TS/CSS | **Prettier + ESLint** (`stylelint` quando aplicável) | `make check` (corrige e valida) |

- `make check` é o único caminho: corrige o estilo e valida (falha = não passa).
- Config única na raiz (`pint.json`, `.prettierrc`, `eslint.config.*`); sem regras locais.

## 5. Determinismo (ADR-001) — regras invioláveis

1. **Clock injetado** — proibido `now()`/`date()`/`time()` soltos em domínio.
   Interface de relógio no `core` (padrão determinístico nos testes).
2. **Aleatoriedade injetada** — IDs/valores aleatórios vêm de geradores injetáveis
   (ex.: `IdGenerator`, `Uuidv7`); o teste fixa a semente.
3. **Ordem explícita** — toda listagem/iteração com ordenação determinística declarada
   (nunca depender da ordem do banco/SO).
4. **Idempotência** — migrations e seeds podem rodar 2× sem efeito colateral; operações de
   bootstrap são idempotentes.
5. **Sem flaky tests** — `make check` precisa passar **2× seguidas**; qualquer teste que
   dependa de tempo/rede/aleatoriedade é corrigido na raiz.
6. **Builds reprodutíveis** — versões pinadas (Composer/npm; imagens por digest);
   nada de `latest`.
7. **Tempo nas respostas** — ETag/304 derivam de corpo determinístico (ADR-022).

## 6. Dívida técnica

- Marker obrigatório: `// @debt [ID] <descrição>` (o `ID` referencia a nota do knudge).
- Toda dívida entra no `kd write` com `--anchor` no arquivo; a task só fecha com a dívida
  registrada ou quitada.
- Dívida nunca esconde bug de segurança/a11y/dados — esses bloqueiam.

## 7. Qualidade estática

- **PHPStan/Larastan `level: max`** + baseline em **ratchet** (só encolhe; ADR-023).
- `make check` = Pint `--test` + PHPStan + PHPUnit estrito + cobertura.
- `tools/arch-check` (fronteiras), `tools/name-check` (token), `tools/migration-check`,
  `tools/vendor-check` — ver F1.I4.
- `composer audit` / `npm audit` no CI.

## 8. Protocolo de IA (agentes e humanos)

1. `kd prime` → `kd ask` (procure antes de criar) → leia **ADR + spec + plano** relevantes.
2. Trabalhe **dentro do container**; nunca `rm -rf`; git read-only sem pedido explícito.
3. Decisão relevante → **ADR**; aprendizado/erro/risco → nota (`kd write`, uma asserção).
4. Log de sessão conforme `wiki/SESSION_LOG.md`; `.STAGING.md` antes de compactar contexto.
5. Resposta concisa, com caminhos e evidência; sem conhecimento tácito não escrito.

## 9. Definition of Done (por contribuição)

- [ ] `make check` verde **2× seguidas**.
- [ ] `make exec cmd='bash tools/docs-check.sh'` verde quando houver spec/documentação tocada.
- [ ] Fronteiras, token, migrations e vendor-check verdes.
- [ ] `declare(strict_types=1)`, DI, logs estruturados, testes (vermelho→verde para bug).
- [ ] Dívida registrada (`@debt`) e documento/ADR coerente.

## 10. Referências

- ADR-001 · ADR-002 · ADR-008 · ADR-023 · ADR-024
- `wiki/plan/02-governanca-ia-first.md` · `wiki/plan/05-qualidade-phpstan-max.md`
- `CONTRIBUTING.md` · `AGENTS.md` · `wiki/specs/09-grep-friendly.md`