docs(reorg): requirements/ + backlog/ + specs/ — SDD canon aplicado ao Interpop

[GabeMarques-Intetsu]

Resumo

Reorganização incremental e não-destrutiva da pasta docs/. 3 entregas em um único PR:

1. ✅ docs/requirements/ — RF/RNF + personas (engenharia-de-requisitos canon)
2. ✅ docs/backlog/ — Epics/Features/Sprints/done com rastreabilidade bidirecional
3. ✅ docs/specs/ — Spec-Driven Development (TLC canon) com brownfield + project + template + 6 retroativos

Total: 60 arquivos novos · ~7.500 LOC de documentação + 1 ADR de produto (Supabase deferred).

O que vem em cada pasta

docs/requirements/ (12 arquivos)

• README.md + personas-e-cenarios.md
• RF/ — 7 arquivos (6 stubs + RF-007 busca completo com cross-refs)
• RNF/ — 5 arquivos completos (perf, security, a11y, lgpd, availability)

docs/backlog/ (16 arquivos)

• README.md + glossario.md
• epics/ — 7 arquivos (6 stubs + EP-10 completo)
• features/ — 3 arquivos (F-30 done com Gherkin pt-BR + 36 Tasks com commits; F-31/F-32 Sprint 5)
• sprints/ — 3 arquivos (sprint-4 done, sprint-5 plan, sprint-6 Supabase spike)
• done/ vazio

docs/specs/ (29 arquivos NOVOS — busca-editorial já existia)

• README.md (método SDD + mapeamento com eng-de-requisitos)
• codebase/ — 7 docs brownfield produzidos por fan-out de specialists:
  • STACK.md — versões reais dos lockfiles (SendGrid declarado mas Gmail SMTP por default!)
  • ARCHITECTURE.md — topologia + 7 mermaid + 3 fluxos cross-layer
  • STRUCTURE.md — onde vive o quê (526 LOC merge backend+frontend)
  • CONVENTIONS.md — convenções Python+TS+React+Django + anti-patterns banidos
  • INTEGRATIONS.md — 12 integrações com status real (vs aspiracional)
  • TESTING.md — números reais (352 backend, 118 frontend) + matriz consultiva
  • CONCERNS.md — 11 riscos segurança + 10 débitos + gotchas (anti-sycophancy)
• project/ — visão + estado:
  • PROJECT.md — KPIs alvo + bases que NÃO escolhemos
  • ROADMAP.md — Sprint 5/6/7/8/9 + marcos macro + backlog longo
  • STATE.md — memória viva: decisões, blockers, lessons, deferred
• _template/ — esqueleto canônico para nova Feature Large/Complex
• 6 specs retroativos — articles, comments, moderation, newsletter, users-auth, audit

docs/planning/adrs/

• ADR-015 — Supabase evaluation deferred (force-added; primeira ADR tracked em planning/)

Achados críticos descobertos (anti-sycophancy honrada)

Durante o fan-out de 13 agentes, descobertas que merecem atenção:

1. SendGrid (ADR-004) NÃO instalado — base.py:226 usa Gmail SMTP por default; cliente SendGrid não existe em pyproject.toml
2. 4 de 5 scripts em scripts/ são stubs com exit 1 — toda a operação de produção descrita em 1262 LOC de HOSTING-DEPLOY-PLAN aguarda implementação
3. TS 6.0.3 (pre-release amplo) em CI gate — ESLint 10, Vite 8, Vitest 4 — toda cadeia frontend em majors recentes
4. articles → newsletter import EAGER (articles/admin.py:3) — única dependência cross-app não-lazy; quebra padrão do resto
5. audit/views.py:27-30 puxa modelos de 5 apps em AdminMetricsView — Ce mais alto do projeto, virou BFF de admin escondido
6. main.tsx:7-10 deriva QueryClient defaults de pages/Buscar/searchService.ts — feature lazy virou owner de política transversal
7. view_count bucket vaza entre workers gunicorn (LocMemCache per-process) — 3 workers infla métrica 3×
8. AuditLog sem TTL nem anonimização de IP — LGPD Art. 16 blocker pré-go-live
9. IsNotBanned em DEFAULT_PERMISSION_CLASSES vaza por omissão — DRF substitui, não merge
10. JWT_SIGNING_KEY fallback para SECRET_KEY sem hard-fail — réplica do mesmo problema que F2-B-03 corrigiu para HMAC cursor
11. Sem 2FA para staff — dev é imune a ban; takeover total se conta comprometida
12. signals.py NÃO existe em apps.newsletter — foi deletado; signal canônico vive em apps.articles.signals.py:42-64 (cross-app reverso para evitar bug histórico C2)
13. Ban.user é OneToOneField — re-banir perde histórico do banned_by + reason originais
14. 2 bugs críticos invisíveis no test suite de newsletter: cover URL relativa quebra imagens; except Exception em send_welcome mata autoretry_for
15. published_at carimbado no view, não no model — publicar via Django admin deixa published_at=NULL (viola invariante)

Decisão arquitetural registrada

Supabase NÃO entra agora (ADR-015). Avaliação Sprint 6+ limitada ao Cenário A (Storage para capas) com gatilhos explícitos.

Rastreabilidade demonstrada

362 cross-refs internos validados (script Python). Cada Feature cita Epic pai + Requisitos atendidos + Sprint(s) + Specs técnicas. Cada Requisito lista Epics que o realizam (bidirecional).

26 "broken" reportados pelo validator são falso-positivos — citações arquivo:linha dentro de markdown links que pathlib trata mal; GitHub renderiza corretamente.

O que NÃO vem nesta PR (decisões conscientes)

1. Não migro Improvement-system.md (1755 LOC) — continua gitignored como backlog mestre histórico; migração para nova estrutura é progressiva por Sprint
2. Não preencho RF-001..RF-006 nem EP-01..EP-06 completamente — stubs com cross-refs corretas + TODO; preenchimento quando módulo for tocado em Sprint dedicado
3. Não unignoro docs/planning/ — só ADR-015 com -f explícito (decisão pública). ADRs 001-014 permanecem locais; decisão futura
4. Não toco docs/specs/busca-editorial/BACKLOG.md — fica intacto como spec técnica; EP-10/F-30 na nova estrutura referenciam

Heads-up

• Cross-refs para ADRs 001-014 em docs/planning/adrs/ aparecem como 404 no GitHub web (gitignored). Não é bug do meu trabalho; é convenção atual do repo
• Bug fixes descobertos (BUG-1/2 do newsletter, OPS-1 do articles published_at) merecem hotfix em PRs separados — NÃO entram neste PR de docs

Test plan

• Ler docs/specs/README.md — método SDD claro?
• Ler docs/specs/codebase/CONCERNS.md — débitos honestos?
• Ler docs/specs/project/PROJECT.md — visão concorda?
• Ler docs/specs/articles/DESIGN.md ou docs/specs/audit/DESIGN.md — spec retroativo é útil?
• Ler docs/specs/_template/DESIGN.md — template reusável?
• CI passa (só docs, sem efeito em testes/build)

🤖 Generated with Claude Code