# 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](./sdr-0001-arquitetura-tres-contratos.md)) nem a **fonte única entre SDRs** (procedimento: [REGRAS-AGENTE-E-PROMPTS.md](./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-0001-arquitetura-tres-contratos.md), [sdr-0003](./sdr-0003-indice-fonte-unica.md), [sdr-0017](./sdr-0017-site-html-rastreabilidade.md), [sdr-0021](./sdr-0021-planejamento-pre-alteracao-agente.md) | | **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](./traceability.md), seção 17.2 do SDR dono) — critério de escolha, sem duplicar o [sdr-0017](./sdr-0017-site-html-rastreabilidade.md). - **Mutação por agente de IA:** ordem **planejar → mutar** — dono do texto: [sdr-0021](./sdr-0021-planejamento-pre-alteracao-agente.md); 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](./REGRAS-AGENTE-E-PROMPTS.md) + [sdr-0003](./sdr-0003-indice-fonte-unica.md)). - 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--*.md` (sub-SDR) — descrita no índice [sdr-0003](./sdr-0003-indice-fonte-unica.md); aqui só se **remete**. - Detalhe de **busca estática**, **siglas.js** ou **ver-md** — dono: [sdr-0017](./sdr-0017-site-html-rastreabilidade.md). ### 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](./traceability.md) e regras em [`.cursor/rules/implementation-without-sdr-detector.mdc`](../.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.md` ou §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.json` do gate — ver [.gitignore](../.gitignore)). - Preferir **links relativos** entre `sdr-*` na pasta `SDRs/`. ### 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](../.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](../AGENTS.md) | Mapa de instruções para agentes (Cursor); remete a SDRs e regras | | [REGRAS-AGENTE-E-PROMPTS.md](./REGRAS-AGENTE-E-PROMPTS.md) | Fonte única *entre* SDRs; nome `sdr-NNNN` | | [sdr-0003](./sdr-0003-indice-fonte-unica.md) | Índice de donos e sub-SDRs | | [sdr-0021](./sdr-0021-planejamento-pre-alteracao-agente.md) | Planejamento antes de mutação por agente | | [traceability.md](./traceability.md) | Tabela código ↔ SDR (onde aplicável) | ### 8.3 Fluxos 1. **Novo requisito normativo** → localizar ou criar dono em [sdr-0003](./sdr-0003-indice-fonte-unica.md); seguir [REGRAS-AGENTE-E-PROMPTS.md](./REGRAS-AGENTE-E-PROMPTS.md) §4. 2. **Nova implementação** → SDR `Aprovado` ou exceção documentada; vínculo em `traceability.md` ou `SDR:` conforme governança. 3. **Edição por agente** → [sdr-0021](./sdr-0021-planejamento-pre-alteracao-agente.md) 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.py` na 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`](../docs/architecture/adrs/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](./sdr-0020-dados-ibama-mapa-ativos-cmdb-kml.md)) | | `Informacoes-gerais/` | Referências curadas transversais (ex.: CMDB em três arquivos; ver [sdr-0024](./sdr-0024-cmdb-taxonomia-referencia-projeto.md)) | | `.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 **gov**ernança e medição | **C1** | Mede, fiscaliza, IMR/ANS — ver [sdr-0011](./sdr-0011-governanca-c1-medicao.md) | | **C2-OPR** | Contrato de **opr**eração | **C2** | Executa, sustenta, mudança operacional — ver [sdr-0006](./sdr-0006-operacao-c2-niveis-capacidade.md) | | **C3-SEC** | Contrato de **sec**urança da informação e continuidade cibernética | **C3** | Postura, detecção, resposta, continuidade no escopo C3 — ver [sdr-0016](./sdr-0016-seguranca-c3-continuidades.md) | **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](./sdr-0001-arquitetura-tres-contratos.md) e [sdr-0016](./sdr-0016-seguranca-c3-continuidades.md); **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](./sdr-0014-ppsi-lgpd-conformidade.md)). --- ## 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](./sdr-0003-indice-fonte-unica.md). ### 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](./sdr-0017-site-html-rastreabilidade.md) 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](./sdr-0021-planejamento-pre-alteracao-agente.md)). --- ## 13. Rastreabilidade e Validação ### 13.1 Critérios de aceite globais - Índice [sdr-0003](./sdr-0003-indice-fonte-unica.md) 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](./traceability.md) ou comentário `SDR:` | Alta | PR sem alerta do detector configurado | | RF-003 | Mutação por agente deve obedecer [sdr-0021](./sdr-0021-planejamento-pre-alteracao-agente.md) | Alta | Fluxo documentado na conversa ou modo Plan | ### 17.2 Rastreabilidade implementação ↔ requisito | Requisito | Arquivo / componente | Observação | |-----------|----------------------|------------| | RF-002 | [traceability.md](./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`](../.cursor/rules/inicio-sessao-agente.mdc), [sdr-0021](./sdr-0021-planejamento-pre-alteracao-agente.md) | Dono da política de plano: **0021** | | RF-001 | [sdr-0001](./sdr-0001-arquitetura-tres-contratos.md), [glossario-eixos.md](./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](./REGRAS-AGENTE-E-PROMPTS.md); planejamento: [sdr-0021](./sdr-0021-planejamento-pre-alteracao-agente.md)) - [x] `traceability.md` e/ou comentários `SDR:` 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`](../.cursor/rules/sdr-conformity-checker.mdc) | [`sdr-conformity-checker.md`](./governance/rules/sdr-conformity-checker.md) | | Detector de implementação sem vínculo SDR | [`implementation-without-sdr-detector.mdc`](../.cursor/rules/implementation-without-sdr-detector.mdc) | [`implementation-without-sdr-detector.md`](./governance/rules/implementation-without-sdr-detector.md) | | Anti-vibecoding sem SDR | [`no-vibecoding-without-sdr.mdc`](../.cursor/rules/no-vibecoding-without-sdr.mdc) | [`no-vibecoding-without-sdr.md`](./governance/rules/no-vibecoding-without-sdr.md) | **Processo:** [`governance/README.md`](./governance/README.md) · **Rastreabilidade código:** [`traceability.md`](./traceability.md) · **Checagem:** `python scripts/check_sdr_conformity.py` (na raiz do repositório).