Fonte: SDRs/sdr-0022-repositorio-convencoes-e-construcao.md
SDR-0022 — Repositório: convenções de construção e rótulos dos contratos (C1-GOV / C2-OPR / C3-SEC)
Nomenclatura: arquivo físico
sdr-0022-repositorio-convencoes-e-construcao.md. SSoT no âmbito “como organizamos o repositório, onde colocar artefatos e como nomear os três contratos em material novo”. Não substitui a arquitetura dos papéis (dono: sdr-0001) nem a fonte única entre SDRs (procedimento: REGRAS-AGENTE-E-PROMPTS.md).
1. Metadados
| Campo | Valor |
|---|---|
| ID | sdr-0022-repositorio-convencoes-e-construcao |
| Título | Repositório: convenções de construção e rótulos dos contratos (C1-GOV / C2-OPR / C3-SEC) |
| Versão | v0.2 |
| Data | 2026-05-03 |
| Autor | Equipe do repositório |
| Revisores | (pendente) |
| Status | Em validação |
| Substitui | — |
| Substituído por | — |
| Classificação | Interno |
| Eixo | Ambos |
| Domínio | Organização do repositório; convenções transversas; nomenclatura dos itens contratuais C1/C2/C3 em documentos novos |
| Stakeholders | Quem edita SDRs, site, processo de contratação e scripts; revisores de PR; operadores de agentes (Cursor) |
| SDRs relacionados | sdr-0001, sdr-0003, sdr-0017, sdr-0021 |
| SSoT (âmbito deste SDR) | Sim — dono de mapa raiz de pastas, política de rótulos estendidos dos três contratos em material novo e encaminhamento para rastreabilidade código ↔ SDR (detalhe operacional nos artefatos citados na §8 e §17.2). |
2. Controle de Revisão
| Versão | Data | Autor | Mudanças |
|---|---|---|---|
| v0.1 | 2026-05-03 | Equipe do repositório | Criação: convenções de repositório; C1-GOV, C2-OPR, C3-SEC; remissões |
| v0.2 | 2026-05-04 | Equipe do repositório | Mapa: docs/architecture/adrs/ (ADRs); visão §8.1 |
3. Objetivo
Normatizar como o projeto é construído e mantido no Git: papel das pastas raiz, vínculo entre implementação (scripts, JS do site, etc.) e SDRs, e rótulos C1-GOV, C2-OPR e C3-SEC para material novo, sem obrigar refatoração em massa do legado C1 / C2 / C3.
4. Escopo e Abstração
4.1 Dentro do escopo
- Mapa de pastas na raiz do repositório e uso esperado de cada uma.
- Política de primeira menção e consistência de C1-GOV, C2-OPR, C3-SEC em TR, ANS, minutas, secções novas de HTML e tabelas novas.
- Onde registrar vínculo implementação ↔ norma (comentário
SDR:, traceability.md, seção 17.2 do SDR dono) — critério de escolha, sem duplicar o sdr-0017. - Mutação por agente de IA: ordem planejar → mutar — dono do texto: sdr-0021; este SDR apenas contextualiza o repositório.
4.2 Fora do escopo
- Regras de fonte única entre arquivos
sdr-*.md(dono: REGRAS-AGENTE-E-PROMPTS.md + sdr-0003). - Conteúdo de negócio de C1, C2 ou C3 (IMR, N1–N3, SOC, PPSI, etc.) — SDRs temáticos.
- Convenção de nome de arquivo
sdr-<NNNN><letra>-*.md(sub-SDR) — descrita no índice sdr-0003; aqui só se remete. - Detalhe de busca estática, siglas.js ou ver-md — dono: sdr-0017.
4.3 Nível de abstração
Política de engenharia de repositório e de redação para novos artefatos; não substitui cláusulas de edital.
4.4 Implementação de software
Alterações em código cobertos pelos detectores exigem vínculo conforme traceability.md e regras em .cursor/rules/implementation-without-sdr-detector.mdc. O detalhe por tipo de arquivo (ex.: gerar_site_search_index.py) permanece no SDR dono do domínio (ex.: 0017).
5. Contexto e Síntese Executiva
5.1 Problema
Regras “de projeto” (pastas, nomes dos contratos em documentos novos, onde apontar SDR:) estavam implícitas ou espalhadas entre README, AGENTS.md e metadocumentos, dificultando onboarding e revisão.
5.2 Solução proposta (resumo)
Este SDR concentra convenções gerais de construção e a política C1-GOV / C2-OPR / C3-SEC, com links aos donos já existentes.
5.3 Benefícios esperados
Menos ambiguidade em PRs, alinhamento entre site, SDRs/ e processo-contratacao/, e rótulos contratuais legíveis em material novo.
5.4 Riscos se não implementado
Inconsistência de pastas, duplicação de norma entre SDRs (mitigada pelo remetimento explícito à REGRAS) e TRs que misturam vocabulários sem âncora.
6. Slides Executivos
- Um mapa de pastas — cada coisa no seu lugar.
- C1-GOV / C2-OPR / C3-SEC — forma preferida em material novo; C1/C2/C3 permanecem válidos (legado).
- Vínculo código ↔ SDR —
SDR:,traceability.mdou §17.2; detalhe no SDR de domínio.
7. Restrições Globais, Não-Funcionais e Critérios de Sucesso
7.1 Restrições técnicas
- Não versionar segredos (ex.:
access-tokens.jsondo gate — ver .gitignore). - Preferir links relativos entre
sdr-*na pastaSDRs/.
7.2 Restrições de negócio / compliance
- Texto voltado ao órgão em pt-BR; termos técnicos de indústria em inglês quando for padrão — ver .cursor/rules/portugues-brasil-respostas.mdc (sem duplicar a tabela inteira neste SDR).
7.3 Critérios de sucesso mensuráveis
- Novos TR/ANS/secções HTML seguem a política de §10.1 (primeira menção + consistência).
- PRs de código nos globs cobertos trazem vínculo rastreável conforme §17.2.
8. Design / Arquitetura
8.1 Visão geral
O repositório CentralDeServicos separa especificação normativa (SDRs/), arquitetura contratual e site (arquitetura-contratual/), decisões de arquitetura (docs/architecture/adrs/), processo IN94 e seleção (processo-contratacao/), dados e geradores (Dados-ibama/, scripts/, arquitetura-contratual/scripts/) e automação do editor (.cursor/). O mapa detalhado está na §10.1 (tabela).
8.2 Componentes
| Componente | Função |
|---|---|
| AGENTS.md | Mapa de instruções para agentes (Cursor); remete a SDRs e regras |
| REGRAS-AGENTE-E-PROMPTS.md | Fonte única entre SDRs; nome sdr-NNNN |
| sdr-0003 | Índice de donos e sub-SDRs |
| sdr-0021 | Planejamento antes de mutação por agente |
| traceability.md | Tabela código ↔ SDR (onde aplicável) |
8.3 Fluxos
- Novo requisito normativo → localizar ou criar dono em sdr-0003; seguir REGRAS-AGENTE-E-PROMPTS.md §4.
- Nova implementação → SDR
Aprovadoou exceção documentada; vínculo emtraceability.mdouSDR:conforme governança. - Edição por agente → sdr-0021 antes de mutar.
9. Processos e Integrações
9.1 Processos afetados
Elaboração de TR, ANS, DFD/ETP, páginas do site e commits em main / PR no Bitbucket.
9.2 Integrações
- Cursor: regras em
.cursor/rules/; comandos em.cursor/commands/. - Conformidade SDR:
python scripts/check_sdr_conformity.pyna raiz.
9.3 SLAs / tempos
Não aplicável neste SDR.
10. Dados, Modelos e Classificações
10.1 Entidades / glossário
Mapa raiz (referência)
| Pasta / arquivo na raiz | Uso esperado |
|---|---|
SDRs/ |
Especificações sdr-*.md, índice, REGRAS, governança, templates |
docs/architecture/adrs/ |
ADRs — premissas de arquitetura (ex.: IC servidor versus cliente); ver README.md |
arquitetura-contratual/ |
Proposta, ANS modelo, site estático (site/), análises PPSI |
processo-contratacao/ |
DFD, ETP, documentos IN94, seleção |
scripts/ |
Scripts transversais ao repo (ex.: conformidade SDR) |
arquitetura-contratual/scripts/ |
Geração de artefatos do site (ex.: índice de busca) |
Dados-ibama/ |
Dados e geradores de mapa/KML (ver sdr-0020) |
Informacoes-gerais/ |
Referências curadas transversais (ex.: CMDB em três arquivos; ver sdr-0024) |
.cursor/ |
Regras, skills e comandos do Cursor |
AGENTS.md |
Ponto de entrada para agentes |
Rótulos estendidos dos três contratos (material novo)
| Rótulo | Significado | Equivalente legado | Papel (resumo) |
|---|---|---|---|
| C1-GOV | Contrato de governança e medição | C1 | Mede, fiscaliza, IMR/ANS — ver sdr-0011 |
| C2-OPR | Contrato de opreração | C2 | Executa, sustenta, mudança operacional — ver sdr-0006 |
| C3-SEC | Contrato de securança da informação e continuidade cibernética | C3 | Postura, detecção, resposta, continuidade no escopo C3 — ver sdr-0016 |
Política de redação
- Em material novo (trechos novos de TR, ANS, minutas, secções novas de HTML, tabelas criadas após a adoção deste SDR): na primeira menção do contrato na secção ou no documento, usar C1-GOV (C1) ou C1-GOV — uma forma, de modo consistente no mesmo documento (não alternar GOV e “Governança” como siglas diferentes para o mesmo item sem necessidade).
- Material legado (
sdr-*existentes, Proposta longa, páginas já publicadas): não exige alteração em massa; evoluções pontuais podem adotar a forma estendida quando tocadas por outro motivo. - SEC refere-se ao contrato C3 do modelo (segurança da informação e continuidade no escopo acordado), alinhado a sdr-0001 e sdr-0016; não implica por si só certificação ou produto comercial “SEC”.
10.2 Modelos de dados
Não aplicável.
10.3 Classificações (LGPD, criticidade, etc.)
Remeter a SDRs de domínio (ex.: sdr-0014).
11. Controles de Exclusividade e Risco
11.1 Exclusividade / fonte única
Este SDR é dono só do que está em §3–§10.1 (mapa raiz + política C1-GOV/C2-OPR/C3-SEC). Demais normas: remeter aos donos listados no sdr-0003.
11.2 Riscos e mitigação
| Risco | Mitigação |
|---|---|
| Inflar este SDR com regras de negócio | Manter tabelas curtas; link ao SDR temático |
| Conflito com “C3” vs “SEC” | Tabela §10.1 + remissão ao 0001 / 0016 |
12. Segurança, LGPD e Auditoria
12.1 Controles de segurança
Não expor credenciais no Git; seguir .gitignore e sdr-0017 para gate de acesso ao site.
12.2 LGPD / privacidade
Dados pessoais em documentos: seguir SDRs de PPSI/LGPD e processo do órgão.
12.3 Auditoria / evidências
Histórico Git e PRs; plano de agente quando aplicável (sdr-0021).
13. Rastreabilidade e Validação
13.1 Critérios de aceite globais
- Índice sdr-0003 lista este SDR como dono do tópico “repositório / convenções / rótulos”.
- Novos artefatos seguem §10.1 quando forem “material novo”.
13.2 Validações automáticas (quando existem)
python scripts/check_sdr_conformity.py — estrutura e metadados deste arquivo.
13.3 Validações manuais
Revisor confere se alteração de código tem vínculo e se TR novo usa rótulos conforme política.
14. Matriz de Implementações Dependentes e Riscos
| Implementação | Depende de | Risco se atrasar |
|---|---|---|
| PRs alinhados ao mapa de pastas | Equipe ler §10.1 | Arquivos fora do lugar esperado |
| TR com C1-GOV / C2-OPR / C3-SEC | Política §10.1 | Vocabulário inconsistente |
15. Histórico de Mudanças Governadas
| Data | Mudança | SDR / proposta |
|---|---|---|
| 2026-05-03 | Criação do SDR-0022 | v0.1 |
| 2026-05-04 | v0.2 — pasta docs/architecture/adrs/ no mapa raiz |
sdr-0022 |
16. Propostas Governadas (alternativas)
- Substituir totalmente C1/C2/C3 por GOV/OPR/SEC em todo o repositório: rejeitado neste ciclo — custo alto; política atual é convivência legado + forma estendida em material novo.
17. Requisitos
17.1 Requisitos funcionais
| ID | Requisito | Prioridade | Aceite quando |
|---|---|---|---|
| RF-001 | Material novo que identifique o contrato deve seguir a política de §10.1 | Alta | Primeira menção e consistência verificáveis |
| RF-002 | Novos artefatos de código nos globs governados devem manter vínculo SDR conforme traceability.md ou comentário SDR: |
Alta | PR sem alerta do detector configurado |
| RF-003 | Mutação por agente deve obedecer sdr-0021 | Alta | Fluxo documentado na conversa ou modo Plan |
17.2 Rastreabilidade implementação ↔ requisito
| Requisito | Arquivo / componente | Observação |
|---|---|---|
| RF-002 | traceability.md | Tabela por item implementado |
| RF-002 | .cursor/rules/implementation-without-sdr-detector.mdc |
Globs de código |
| RF-003 | .cursor/rules/inicio-sessao-agente.mdc, sdr-0021 |
Dono da política de plano: 0021 |
| RF-001 | sdr-0001, glossario-eixos.md | Arquitetura e vocabulário; 0022 dono da política de rótulo novo |
17.3 Requisitos não-funcionais
| ID | Requisito | Métrica |
|---|---|---|
| RNF-001 | Clareza do mapa de pastas | Onboarding sem perguntas repetidas sobre “onde colocar” |
18. Checklist de Governança
- [x] Metadados completos (seção 1)
- [x] Status coerente com o ciclo de vida (
Em validação) - [x] Sem duplicar norma já dona em outro
sdr-*.md(fonte única entre SDRs: REGRAS-AGENTE-E-PROMPTS.md; planejamento: sdr-0021) - [x]
traceability.mde/ou comentáriosSDR:quando houver implementação (política remetida na §17.2) - [ ] Revisores e data de aprovação quando Status: Aprovado
18.1 Agentes de conformidade (Cursor)
| Agente | Regra Cursor | Norma em SDRs/governance/rules/ |
|---|---|---|
| Verificador de conformidade SDR | sdr-conformity-checker.mdc |
sdr-conformity-checker.md |
| Detector de implementação sem vínculo SDR | implementation-without-sdr-detector.mdc |
implementation-without-sdr-detector.md |
| Anti-vibecoding sem SDR | no-vibecoding-without-sdr.mdc |
no-vibecoding-without-sdr.md |
Processo: governance/README.md · Rastreabilidade código: traceability.md · Checagem: python scripts/check_sdr_conformity.py (na raiz do repositório).