refactor(skills): cut the workflows to ~100 lines and scale phases by tier
Each workflow was ~300 lines of grep-count "VERIFICAR" steps and ran every phase for every request. Phases now state their minimum tier, checks are the quality gate plus real tools, detail moved to references/, and machine-specific paths and non-public skills are gone. Security references move to OWASP Top 10:2025, ASVS 5.0 and the OWASP LLM Top 10. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
EvandroandClaude Opus 5.5 committed
1 parent
c18d3356ae
commit
f2db2d69da
20 files changed
+823
-1176
No files matched your search
@@ -0,0 +1,31 @@
|
||||
# Modelo de ADR
|
||||
|
||||
Arquivo: `docs/architecture/adr/NNNN-titulo-curto.md` (S-ADR de segurança em `docs/security/adr/`).
|
||||
Numeração sequencial. ADR aceito não é reescrito: uma decisão nova cria outro ADR com `Substitui:`.
|
||||
|
||||
```markdown
|
||||
# ADR-0003: PostgreSQL como banco de pedidos
|
||||
|
||||
- Status: proposto | aceito | substituído por ADR-NNNN
|
||||
- Data: 2026-09-24
|
||||
- Requisitos: REQ-002, REQ-010
|
||||
- Substitui: (se houver)
|
||||
|
||||
## Contexto
|
||||
O que força a decisão agora. Restrições reais (volume, equipe, custo, prazo), com números.
|
||||
|
||||
## Opções
|
||||
1. PostgreSQL gerenciado: prós, contras.
|
||||
2. MongoDB: prós, contras.
|
||||
3. Manter o SQLite atual: prós, contras.
|
||||
|
||||
## Decisão
|
||||
A opção escolhida e o motivo principal, em duas ou três frases.
|
||||
|
||||
## Consequências
|
||||
- Boas: o que fica mais fácil.
|
||||
- Ruins: o que fica mais difícil ou caro, e o que foi aceito conscientemente.
|
||||
- Como desfazer, se precisar, e quanto custa.
|
||||
```
|
||||
|
||||
Um ADR por decisão. Se duas decisões dependem uma da outra, dois ADRs que se referenciam.
|
||||
@@ -0,0 +1,45 @@
|
||||
# C4 em Mermaid
|
||||
|
||||
Regras: até 20 elementos por view, toda seta com rótulo (o que trafega e por qual protocolo),
|
||||
IDs estáveis reaproveitados em ADRs e no threat model, declaração na ordem de leitura
|
||||
(de quem usa para o que é usado).
|
||||
|
||||
## Context
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
title Contexto: Sistema de Pedidos
|
||||
Person(cliente, "Cliente", "Compra pelo site")
|
||||
System(pedidos, "Sistema de Pedidos", "Cria e acompanha pedidos")
|
||||
System_Ext(pagamento, "Gateway de pagamento", "Cobra o cartão")
|
||||
Rel(cliente, pedidos, "Cria pedido", "HTTPS")
|
||||
Rel(pedidos, pagamento, "Autoriza cobrança", "HTTPS/REST")
|
||||
```
|
||||
|
||||
## Container
|
||||
|
||||
```mermaid
|
||||
C4Container
|
||||
title Containers: Sistema de Pedidos
|
||||
Person(cliente, "Cliente")
|
||||
System_Boundary(sp, "Sistema de Pedidos") {
|
||||
Container(web, "Web", "Next.js", "Interface")
|
||||
Container(api, "API", "FastAPI", "Regras de pedido")
|
||||
ContainerDb(db, "Banco", "PostgreSQL", "Pedidos e itens")
|
||||
Container(worker, "Worker", "Celery", "Cobrança assíncrona")
|
||||
}
|
||||
System_Ext(pagamento, "Gateway de pagamento")
|
||||
Rel(cliente, web, "Usa", "HTTPS")
|
||||
Rel(web, api, "Chama", "HTTPS/JSON")
|
||||
Rel(api, db, "Lê e grava", "SQL/TLS")
|
||||
Rel(api, worker, "Enfileira cobrança", "Redis")
|
||||
Rel(worker, pagamento, "Autoriza", "HTTPS")
|
||||
```
|
||||
|
||||
## Render
|
||||
|
||||
```bash
|
||||
npx -y @mermaid-js/mermaid-cli -i docs/architecture/c4.mmd -o /tmp/c4.svg
|
||||
```
|
||||
|
||||
Se o comando falhar, o diagrama tem erro de sintaxe e não está pronto.
|
||||
@@ -0,0 +1,35 @@
|
||||
# EARS: requisitos com ID
|
||||
|
||||
EARS (Easy Approach to Requirements Syntax) força cada requisito a ter gatilho e resposta
|
||||
verificáveis. Um requisito por linha, ID estável `REQ-NNN`, nunca reaproveitado.
|
||||
|
||||
| Padrão | Forma | Exemplo |
|
||||
|---|---|---|
|
||||
| Ubíquo | THE SYSTEM SHALL <resposta> | `REQ-001: THE SYSTEM SHALL registrar toda alteração de preço com autor e data.` |
|
||||
| Evento | WHEN <evento> THE SYSTEM SHALL <resposta> | `REQ-002: WHEN o usuário envia o formulário de cadastro THE SYSTEM SHALL responder 201 com o ID criado.` |
|
||||
| Indesejado | IF <condição> THEN THE SYSTEM SHALL <resposta> | `REQ-003: IF o token expirou THEN THE SYSTEM SHALL responder 401 sem revelar se a conta existe.` |
|
||||
| Estado | WHILE <estado> THE SYSTEM SHALL <resposta> | `REQ-004: WHILE a fila tiver mais de 1000 itens THE SYSTEM SHALL recusar novos jobs com 429.` |
|
||||
| Opcional | WHERE <recurso> THE SYSTEM SHALL <resposta> | `REQ-005: WHERE o SSO estiver habilitado THE SYSTEM SHALL ocultar o login por senha.` |
|
||||
|
||||
## Não funcionais
|
||||
|
||||
Mesmo formato de ID, sempre com número e forma de medir:
|
||||
|
||||
```
|
||||
REQ-010: THE SYSTEM SHALL responder GET /orders em p95 < 250 ms com 200 req/s (medido com k6).
|
||||
REQ-011: THE SYSTEM SHALL manter 99,9% de disponibilidade mensal (SLO no monitoramento).
|
||||
REQ-012: THE SYSTEM SHALL atender ASVS 5.0 nível L2 nos capítulos de autenticação e sessão.
|
||||
REQ-013: THE SYSTEM SHALL carregar a página inicial com LCP <= 2,5 s e INP <= 200 ms (Lighthouse CI).
|
||||
```
|
||||
|
||||
## Rastreabilidade
|
||||
|
||||
Cada teste cita o ID que prova, no nome ou num comentário:
|
||||
|
||||
```python
|
||||
def test_req_003_token_expirado_retorna_401():
|
||||
...
|
||||
```
|
||||
|
||||
Com `[spec]` no `.dev-workflows.toml`, o gate nível 3 falha se algum `REQ-` da spec não aparecer
|
||||
em nenhum arquivo de teste.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Threat model STRIDE com ASVS 5.0
|
||||
|
||||
Arquivo: `docs/security/threat-model.md`. Uma tabela por fronteira de confiança.
|
||||
|
||||
## Categorias e onde procurar o controle no ASVS 5.0
|
||||
|
||||
| STRIDE | Ameaça típica | Capítulos ASVS 5.0 para o controle |
|
||||
|---|---|---|
|
||||
| Spoofing (identidade falsa) | login forjado, token roubado, serviço se passando por outro | Autenticação, Gerenciamento de sessão, Tokens autocontidos |
|
||||
| Tampering (adulteração) | parâmetro alterado, mensagem na fila modificada, upload malicioso | Validação e lógica de negócio, Manipulação de arquivos, Comunicação segura |
|
||||
| Repudiation (negação) | ação sensível sem rastro | Log e tratamento de erro |
|
||||
| Information disclosure (vazamento) | IDOR, stack trace na resposta, segredo em log | Autorização, Proteção de dados, Log e tratamento de erro |
|
||||
| Denial of service | endpoint sem limite, query sem paginação, arquivo gigante | Validação e lógica de negócio (limites), Manipulação de arquivos |
|
||||
| Elevation of privilege | usuário comum chega em rota de admin, injeção de comando | Autorização, Codificação e sanitização |
|
||||
|
||||
Os nomes dos capítulos seguem o ASVS 5.0 (maio de 2025). Cite o requisito exato (`V<cap>.<seção>.<item>`)
|
||||
consultando https://github.com/OWASP/ASVS, não pela memória.
|
||||
|
||||
## Modelo por fronteira
|
||||
|
||||
```markdown
|
||||
## Fronteira: Internet -> API
|
||||
|
||||
| # | STRIDE | Ameaça concreta | Controle | ASVS | Status |
|
||||
|---|---|---|---|---|---|
|
||||
| T1 | S | Token JWT aceito com alg none | Validar alg fixo e assinatura | Tokens autocontidos | ok |
|
||||
| T2 | I | GET /orders/{id} devolve pedido de outro cliente | Query escopada ao usuário autenticado | Autorização | pendente |
|
||||
| T3 | D | POST /orders sem limite de taxa | Rate limit por usuário e IP | Validação e lógica de negócio | pendente |
|
||||
```
|
||||
|
||||
Fronteiras que costumam faltar: serviço interno sem autenticação ("está na rede privada"),
|
||||
worker que confia em qualquer mensagem da fila, integração com LLM (prompt injection, ferramenta
|
||||
com permissão demais: OWASP LLM01 e LLM06).
|
||||
|
||||
Status `pendente` em ameaça alta bloqueia a aprovação da Fase 5.
|
||||
Reference in new issue
Block a user