chore(repo): organização estratégica — fundação para agentes + taxonomia src/

[1marcelserrano]

Resumo

Auditoria estrutural + organização profissional do repositório, executada em fases com aprovação humana. O repo já era saudável (passou por governance audit em 2026-04-22); o ganho aqui foi fechar o drift de versão docs↔código e adicionar a camada de contexto para agentes, além da reestruturação de taxonomia para src/.

Tensão central diagnosticada: a camada de código já estava na v3.0 "Era Midnight", mas a documentação ainda descrevia a v2.2 "Âmbar Elétrico" — o repo falava duas versões ao mesmo tempo.

Fase 0 — Fundação (commit 6e13866, não-destrutivo)

• CLAUDE.md + AGENTS.md — contexto operacional para agentes (propósito, como rodar, convenções, tabus/legado, o que não commitar).
• .gitattributes — normalização EOL (LF) + hints de linguist.
• SETUP_STRATEGY.md — diagnóstico da auditoria + roadmap das fases.
• README + CHANGELOG alinhados à v3.0 Midnight (badge, descrição, rodapé; entrada [3.0.0 Midnight] reconstruída a partir dos commits DEC-001→018).
• CI validate.yml — html-check ampliado (removido -maxdepth 2) para cobrir os HTMLs de studies/ que antes escapavam.

Fase 1 — Taxonomia (commit 09c97d2)

• Código servido movido para src/ (5 superfícies HTML + css/ + js/ + templates/ + studies/) via git mv — histórico preservado (git log --follow atravessa o rename; 26 renames detectados pelo git).
• vercel.json adicionado: rewrites mapeiam a raiz pública do deploy → src/, mantendo o deploy transparente.
• kebab-case em studies/: editorial_typography/ → editorial-typography/ e os 9 editorial_study_*.html → editorial-study-*.html; 8 links internos atualizados.
• Referências reescritas: README, CONTRIBUTING, CLAUDE.md, CODEOWNERS, CI css-validate, .gitattributes, docs/CANONICAL_REFERENCE.md, SECURITY.md, texto em src/formats.html.

Estrutura final: raiz = fundação/governança + docs/ + .github/ + vercel.json; src/ = todo o código servido.

Fase 2 — Convenções

Sem ação destrutiva: Conventional Commits + branch naming já documentados; kebab-case aplicado nos novos (studies) na Fase 1. Sem mass-rename de legado — âncoras como #chumbo-quente permanecem grandfatheradas, conforme regra do repo.

Fase 3 — Higiene de Git

Nada a fazer: sem mídia pesada, sem artefatos efêmeros rastreados (.git ~452K). LFS desnecessário; sem reescrita de histórico.

✅ Verificação local (espelho do validate.yml)

• html-check (16 HTMLs) ✅ · css-validate (src/css) ✅ · markdown-check (obrigatórios na raiz) ✅ · secret-scan ✅
• Todos os links internos de editorial-typography/index.html resolvem ✅
• Todos os assets referenciados pelas superfícies existem em src/ ✅

⚠️ Ação manual sua (não verificável no sandbox)

1. Validar o deploy Vercel após o merge — o vercel.json faz rewrite de / → /src/index.html e /(.*) → /src/$1. Conferir que https://design-system-beta.vercel.app/ e as páginas (/products.html, etc.) carregam e que css//js/ resolvem. Não consegui testar Vercel daqui.
   • Alternativa: definir Root Directory = src no painel Vercel e remover o vercel.json (ambos resolvem; o vercel.json mantém a config versionada).
2. Submódulos downstream que referenciam css/… por caminho fixo precisam passar a apontar para src/css/….

https://claude.ai/code/session_016txcnkz6wG7iHyHMRCVgMX

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
design-system	Ready	Preview, Comment	May 30, 2026 8:21am