{
  "id": "convencoes-da-documentacao",
  "title": "Convenções da documentação",
  "description": "Regras para manter fontes de verdade, estados, links internos e referências de código consistentes.",
  "type": "documentation-standard",
  "status": "maintained",
  "visibility": "public",
  "tags": [
    "sge/documentacao",
    "sge/desenvolvimento",
    "sge/qualidade"
  ],
  "related": [
    "dominio-e-modelo-de-dados",
    "fluxos-principais",
    "glossario",
    "ciclos-de-status",
    "backlog-e-decisoes"
  ],
  "sourceRefs": [],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Fonte de verdade por assunto\n\n| Assunto | Fonte principal | Material complementar |\n| --- | --- | --- |\n| Regras funcionais de domínio | [Domínio e modelo de dados](doc:dominio-e-modelo-de-dados) | [Fluxos principais](doc:fluxos-principais), [Glossário](doc:glossario) |\n| Estados e transições | [Ciclos de status](doc:ciclos-de-status) | enum e fluxo correspondentes |\n| Esquema, índices e FKs | notas de migration | diagramas conceituais |\n| Decisão aprovada | [Backlog e decisões](doc:backlog-e-decisoes) | notas de implementação relacionadas |\n| Estado do código existente | nota técnica com `source_refs` | código e testes apontados pela mesma lista |\n\nUma nota derivada deve linkar para a fonte principal em vez de repetir o contrato inteiro.\n\n## Estados das notas\n\n| Status | Uso |\n| --- | --- |\n| `planned` | Contrato ou trabalho ainda não iniciado. |\n| `defined` | Regra aprovada, mas ainda não implementada. |\n| `in-progress` | Conteúdo, implementação ou validação em curso. |\n| `implemented` | Artefato de código existe; os checklists devem indicar integrações ou testes restantes. |\n| `maintained` | Nota operacional ou histórica que continua válida e recebe revisões. |\n| `observed` | Fotografia do estado atual, sem prometer comportamento futuro. |\n| `completed` | Marco concluído e sem trabalho pendente próprio. |\n| `archived` | Material preservado apenas para consulta histórica. |\n\nNão marque uma fase como `completed` se seu checklist ainda tiver itens pendentes. Para uma nota de código, `implemented` pode coexistir com pendências de integração e testes, desde que o texto deixe isso explícito.\n\n## Frontmatter e referências de código\n\nToda nota Markdown deve possuir `id`, `title`, `description`, `type`, `status` e `visibility`.\n\nO repositório Laravel fica em um repositório público separado. Para manter as referências portáveis e verificáveis em qualquer checkout, use URLs estáveis do código:\n\n```yaml\nsource_refs: https://github.com/sge-suite/sge/blob/master/app/Enums/InternshipStatus.php, https://github.com/sge-suite/sge/blob/master/tests/Unit/Enums/InternshipStatusTest.php\n```\n\nNunca grave um caminho absoluto de máquina em `source_refs`. O comando `npm run check` valida a estrutura, os links e as referências disponíveis.\n\n## Fronteira de publicação no Aurelius\n\nO Aurelius publica as notas em `content/` e os diagramas em `diagrams/`, gerando páginas HTML, Markdown e uma API para consulta por agentes. Portanto:\n\n- notas publicadas não devem linkar ou incorporar materiais excluídos da publicação;\n- `visibility` registra a intenção de exposição da nota;\n- `description` é exibida pelo Aurelius e deve explicar a nota sem depender de contexto interno;\n- o título já é renderizado pela página, então as páginas públicas não devem repetir o H1 do frontmatter no corpo.\n\n## Checklist de alteração\n\n1. Atualize a fonte principal e as notas derivadas afetadas.\n2. Verifique links e frontmatter com `npm run check`.\n3. Execute `npm run build` quando a alteração afetar conteúdo publicado.\n4. Atualize o checklist da fase e a matriz de testes quando houver código novo.",
  "sections": [
    {
      "id": "fonte-de-verdade-por-assunto",
      "level": 2,
      "title": "Fonte de verdade por assunto",
      "text": "| Assunto | Fonte principal | Material complementar | | --- | --- | --- | | Regras funcionais de domínio | [Domínio e modelo de dados](doc:dominio-e-modelo-de-dados) | [Fluxos principais](doc:fluxos-principais), [Glossário](doc:glossario) | | Estados e transições | [Ciclos de status](doc:ciclos-de-status) | enum e fluxo correspondentes | | Esquema, índices e FKs | notas de migration | diagramas conceituais | | Decisão aprovada | [Backlog e decisões](doc:backlog-e-decisoes) | notas de implementação relacionadas | | Estado do código existente | nota técnica com `source_refs` | código e testes apontados pela mesma lista |  Uma nota derivada deve linkar para a fonte principal em vez de repetir o contrato inteiro.",
      "line": 1
    },
    {
      "id": "estados-das-notas",
      "level": 2,
      "title": "Estados das notas",
      "text": "| Status | Uso | | --- | --- | | `planned` | Contrato ou trabalho ainda não iniciado. | | `defined` | Regra aprovada, mas ainda não implementada. | | `in-progress` | Conteúdo, implementação ou validação em curso. | | `implemented` | Artefato de código existe; os checklists devem indicar integrações ou testes restantes. | | `maintained` | Nota operacional ou histórica que continua válida e recebe revisões. | | `observed` | Fotografia do estado atual, sem prometer comportamento futuro. | | `completed` | Marco concluído e sem trabalho pendente próprio. | | `archived` | Material preservado apenas para consulta histórica. |  Não marque uma fase como `completed` se seu checklist ainda tiver itens pendentes. Para uma nota de código, `implemented` pode coexistir com pendências de integração e testes, desde que o texto deixe isso explícito.",
      "line": 13
    },
    {
      "id": "frontmatter-e-referencias-de-codigo",
      "level": 2,
      "title": "Frontmatter e referências de código",
      "text": "Toda nota Markdown deve possuir `id`, `title`, `description`, `type`, `status` e `visibility`.  O repositório Laravel fica em um repositório público separado. Para manter as referências portáveis e verificáveis em qualquer checkout, use URLs estáveis do código:   Nunca grave um caminho absoluto de máquina em `source_refs`. O comando `npm run check` valida a estrutura, os links e as referências disponíveis.",
      "line": 28
    },
    {
      "id": "fronteira-de-publicacao-no-aurelius",
      "level": 2,
      "title": "Fronteira de publicação no Aurelius",
      "text": "O Aurelius publica as notas em `content/` e os diagramas em `diagrams/`, gerando páginas HTML, Markdown e uma API para consulta por agentes. Portanto:  - notas publicadas não devem linkar ou incorporar materiais excluídos da publicação; - `visibility` registra a intenção de exposição da nota; - `description` é exibida pelo Aurelius e deve explicar a nota sem depender de contexto interno; - o título já é renderizado pela página, então as páginas públicas não devem repetir o H1 do frontmatter no corpo.",
      "line": 40
    },
    {
      "id": "checklist-de-alteracao",
      "level": 2,
      "title": "Checklist de alteração",
      "text": "1. Atualize a fonte principal e as notas derivadas afetadas. 2. Verifique links e frontmatter com `npm run check`. 3. Execute `npm run build` quando a alteração afetar conteúdo publicado. 4. Atualize o checklist da fase e a matriz de testes quando houver código novo.",
      "line": 49
    }
  ],
  "sourcePath": "content/convencoes-da-documentacao.md",
  "visuals": [],
  "apiVersion": 1
}