Metadata-Version: 2.5
Name: sdd-kit-ai
Version: 0.15.0
Summary: SDD agnóstico: especificações como contrato, verificação fora do LLM.
Author: Luciano Oliveira Nunes
License: MIT
License-File: LICENSE
Keywords: ai-agents,evals,llm,mutation-testing,sdd,spec-driven-development
Requires-Python: >=3.10
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml<7,>=6
Requires-Dist: typer<1,>=0.16
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.25; extra == 'dev'
Requires-Dist: pip>=23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# sdd-kit

Português · [English](README.en.md)

[![ci](https://github.com/lucianoon/sdd-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/lucianoon/sdd-kit/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/sdd-kit-ai.svg)](https://pypi.org/project/sdd-kit-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Specification-Driven Development para desenvolvimento assistido por IA, com verificação
por ferramentas independentes.**

O agente (Claude Code, Codex, Cursor, Copilot...) escolhe **como** implementar. A spec
define **o que** é correto. O `sdd` decide se está **pronto**, rodando fora do LLM, na sua
máquina e no CI.

> LLMs propõem e implementam. Especificações definem os contratos.
> Ferramentas independentes verificam. Humanos governam as decisões de maior risco.

O sdd-kit combina orientação ao agente com verificação executável: cada critério precisa
de um teste identificado passando,
código não muda sem a spec mudar junto, testes fracos são expostos por mutação, e
comportamento de LLM é medido com critério estatístico. Checks de código usam ferramentas
externas ao agente. Evals com juiz LLM exigem política explícita e são identificadas como
evidência probabilística.

## Instalação

O comando é `sdd`. O nome do pacote no `pyproject.toml` é `sdd-kit-ai`.

```bash
pipx install git+https://github.com/lucianoon/sdd-kit    # da fonte, sempre atualizado
uv tool install git+https://github.com/lucianoon/sdd-kit # equivalente com uv
# pipx install sdd-kit-ai                                # do PyPI, quando publicado
```

Python 3.10+. Funciona com qualquer linguagem cujo runner de testes gere JUnit XML
(pytest, jest, vitest, Go, JUnit...); veja [`examples/`](examples/).

## Começo em 5 minutos

```bash
sdd init                                   # 4 arquivos: config, spec de exemplo, AGENTS.md, CI
sdd specify criar-pedido --acs 2           # esqueleto da spec com IDs livres
# preencha os campos marcados com PREENCHER:, escreva os testes com o ID no nome
sdd validate && sdd check                  # pronto = verde
```

```
$ sdd specify criar-pedido --acs 2
criado   specs/features/FEATURE-002/spec.yaml
IDs      REQ: REQ-002  AC: AC-002, AC-003
```

```python
def test_ac_002_pedido_persistido(): ...   # o ID do critério no nome liga teste e spec
```

```
$ sdd check
OK         AC-002   criar-pedido: pedido é persistido
SEM_TESTE  AC-003   criar-pedido: pedido é rejeitado
ERRO  AC-003 (criar-pedido): SEM_TESTE

REPROVADO — relatório em .sdd/report.md
```

## Fluxo guiado para o agente

Depois de criar a spec, prepare o contexto da feature para o agente de sua escolha:

```bash
sdd guide criar-pedido --stage clarify     # perguntas abertas e critérios a esclarecer
sdd guide criar-pedido --stage plan        # design e tarefas rastreáveis
sdd analyze                               # diagnósticos e matriz critério → tarefas
sdd guide criar-pedido --stage implement   # contexto e dependências declaradas das tarefas
sdd check
sdd guide criar-pedido --stage converge    # instruções para revisar lacunas após implementar
```

O `guide` imprime instruções e contexto; o agente trabalha sobre eles. Não chama LLM,
não altera arquivos nem executa testes. `analyze` preserva as fontes e grava relatórios
estáticos em `.sdd/analyze.json` e `.md`, inclusive quando há erros. Ambos aceitam `--json`.
Implementação e convergência ficam bloqueadas por erros estáticos; clarificação e plano
continuam disponíveis para corrigir a spec. Veja [fluxo guiado](docs/fluxo-guiado.md).

## Adote aos poucos

Comece no mínimo e ligue camadas quando fizerem sentido:

```bash
sdd init --preset minimo      # spec, check e diff (padrão)
sdd init --preset padrao      # + design, tarefas, constituição, arquitetura, decisões
sdd init --preset completo    # + evals, mutação, critério estrito

sdd enable design tasks       # liga camadas num projeto existente
sdd enable agentes            # perfil de agentes de IA (61 requisitos, incluindo LGPD)
```

## Aplicações de agentes de IA

`sdd enable agentes` (ou `sdd init --profile agentes`) traz um catálogo de requisitos de
referência para agentes, derivado da *SPEC-BASE v0.1*: 12 módulos (núcleo, ferramentas e
efeitos, recuperação, memória, humano no laço, delegação, produção, LGPD/PL 2338...),
61 requisitos. Cada requisito ativo é cobrado por evidência — um AC ou NFR com teste
passando, uma regra ARCH executável ou um EVAL com critério estatístico — ou justificado
com `not_applicable` + motivo; "acho que cobre" não satisfaz. O `sdd profile` mostra a
matriz com o estado real de cada evidência. Detalhes e tabela completa em
[`docs/agentes.md`](docs/agentes.md).

## Complementos para o fluxo

```bash
sdd integrate all                          # entradas locais para Codex, Claude Code e Cursor
sdd adequacy template criar-pedido         # revisão separada da adequação dos testes
sdd lesson list                            # lições propostas e aceitas
sdd change propose ajustar-pedido --feature criar-pedido --reason 'Nova regra'
sdd import-spec referencias/spec.md --format speckit --feature pagamentos
```

Revisões usam referências com hashes; lições aceitas atuais entram no `guide`.
Propostas preservam baseline e histórico; arquivar exige `check` novo. Importações de
Spec Kit/OpenSpec são rascunhos com fonte preservada e revisão obrigatória.
Veja [complementos e limites](docs/complementos.md) e a
[demonstração executável de falha e correção](docs/demonstracao.md).

## Revisão escalonada por risco

```bash
sdd risk --base origin/main --author "$AUTOR"   # tier da mudança e aprovações humanas exigidas
sdd findings                                    # achados de um revisor LLM externo
sdd fixes --base v0.15.0                        # correções SDD-Fix como casos de avaliação
```

O piso vem de regras declaradas: globs por tier, `specs/` e a severidade dos riscos das
specs donas. Um classificador ou revisor LLM externo pode **elevar** o tier por arquivo,
nunca reduzi-lo. Achados de LLM exigem política explícita, são evidência probabilística e
não contam como aprovação humana. Veja [revisão escalonada](docs/revisao.md).

## Comandos

| Comando | O que faz |
|---|---|
| `sdd init` | preserva arquivos iniciais existentes e aplica as camadas do preset escolhido |
| `sdd enable <camada>` | liga design, tasks, constitution, arch, decisions, evals, mutate, strict, agentes |
| `sdd specify <nome>` | esqueleto de spec com IDs livres e as seções que o `--size` exige |
| `sdd validate` | analisa specs, tarefas, constituição, perfil: órfãos, ciclos, referências, critério vago |
| `sdd analyze` | consolida erros, avisos, cenários repetidos e matriz de rastreabilidade declarada |
| `sdd guide <feature> --stage <etapa>` | prepara contexto para clarify, plan, implement ou converge |
| `sdd check` | roda testes, gates e regras de arquitetura; reprova critério sem teste passando |
| `sdd diff` | reprova código alterado sem a spec mudar junto (com exceções auditáveis) |
| `sdd mutate` | injeta falhas no código e reprova se os testes não as detectam |
| `sdd eval` | aplica critérios estatísticos a comportamento de LLM |
| `sdd arch` | verifica as regras de dependência entre camadas |
| `sdd profile` | mostra a matriz do perfil de agentes |
| `sdd risk` | calcula o piso de risco da mudança e as aprovações humanas exigidas |
| `sdd findings` | valida achados de revisor LLM externo como evidência probabilística |
| `sdd fixes` | exporta commits `SDD-Fix` como casos para avaliar revisores |

## O ciclo

| Etapa | Artefato | Verificado por |
|---|---|---|
| 0 Constituição | `constitution.yaml` | `validate`, `check` |
| 1 Especificação | `spec.yaml` | `specify`, `validate` |
| 2 Clarificação | `open_questions`, `assumptions` | pergunta aberta bloqueia o `validate` |
| 3 Plano | `design` | `validate` |
| 4 Tarefas | `tasks` | `validate`, `check` |
| 5 Análise | — | `validate` |
| 6 Implementação | código e testes | `check`, `diff`, `mutate`, `eval`, `arch` |

`guide --stage converge` orienta uma revisão do agente após implementar, com lacunas
rastreáveis e tarefas adicionais. Essa revisão não substitui os comandos de verificação.

O `AGENTS.md` gerado ensina esse ciclo ao agente, com o que fazer e o que não fazer.

| Mudança | No commit |
|---|---|
| Comportamento mudou | spec alterada junto com o código |
| Bug (código descumpre spec correta) | `SDD-Fix: AC-012` + teste de regressão que cite o ID |
| Só a solução técnica mudou | `SDD-No-Spec-Change(nome-da-feature): <motivo>` |

## Exemplos de IA sem ampliar o núcleo

[`examples/rag`](examples/rag/) demonstra recuperação autorizada, revogação de cache,
fallback, orçamentos, traces, manifesto reproduzível e comparação de avaliações usando
`check`, `eval` e gates existentes. É offline: não mede qualidade ou latência de um LLM.
Veja também a [avaliação de complexidade e regra de simplicidade](docs/simplicidade.md).

## Documentação

- [Changelog](CHANGELOG.md): o que mudou em cada versão
- [Especificação](docs/especificacao.md): specs, rastreio, convenções por stack, size, premissas, tarefas
- [Verificação contínua](docs/verificacao.md): `diff`, `SDD-Fix`, `mutate`
- [Fluxo guiado](docs/fluxo-guiado.md): `analyze`, contexto por etapa e limites da convergência
- [Desenho arquitetural](docs/design.md): números, alternativas, riscos, modos de falha
- [Arquitetura e constituição](docs/arquitetura.md): `arch`, princípios executáveis
- [Arquitetura interna](docs/arquitetura-interna.md): módulos, proteção de IO e testes da distribuição
- [Auditoria de outubro de 2026](docs/auditoria-2026-10.md): achado corrigido, alcance, validação e limites
- [Comportamento de LLM](docs/evals.md): `eval`, intervalo de confiança, juiz LLM
- [Perfil de agentes](docs/agentes.md): matriz de módulos, requisitos críticos, LGPD
- [Revisão escalonada](docs/revisao.md): piso de risco, achados de LLM, correções como eval
- [Configuração](docs/configuracao.md): todas as chaves e camadas
- [Limites, origem e créditos](docs/limites-e-creditos.md)

Este repositório verifica a si mesmo com onze specs: verificação, diff, mutação, evals,
arquitetura, governança, adoção, perfil de agentes, fluxo guiado, artefatos e complementos. `sdd validate` mostra a contagem
atual de critérios; `sdd check` roda os testes, a constituição e as regras de arquitetura.

Os relatórios JSON e Markdown identificam a versão do kit, o formato e o comando.
Princípios dependentes de comandos separados ficam `PENDENTE` no check; uma regra
declarada não comprova execução. Veja [estados de evidência](docs/arquitetura.md).

## Licença

MIT. O perfil de agentes deriva da *SPEC-BASE v0.1* e o ciclo de sete etapas do *Guia SDD
para Agentes de IA*, ambos de Luciano Oliveira Nunes; detalhes em
[créditos](docs/limites-e-creditos.md#créditos).
