Policy — Content location: single source por categoria

*rincípio* cada categoria de conteúdo tem um path canônico único no monorepo. Sem duplicação, sem symlink, sem cópia. Quem precisa citar referencia pelo path completo. Quem precisa editar edita no path canônico.

Escopo

Esta policy define *nde cada tipo de conteúdo de leitura humana vive* Aplicase a docs, specs, RFCs, READMEs, runbooks, ADRs, post mortems, catalog entries — qualquer arquivo cujo consumidor primário é um leitor humano (não um runtime).

*ÃO está no escopo desta policy*(essas regras vivem em outros documentos):

Esta policy assume que os módulos já estão colocados corretamente pela L1/L2 taxonomy (não corrige isso) e foca em *entro de cada módulo / da árvore meta* qual conteúdo vai onde.

Tabela canônica

Specs normativas

*egra dura* spec normativa nunca vive dentro do módulo da engine ou do produto que a implementa. O módulo referencia por path completo no README ou em comentários — sem cópia, sem symlink.

RFCs (Request for Comments — propostas arquiteturais)

Numeração: incremental por escopo. RFC001 crossstack é diferente de RFC-001 do koder_kit. Cada escopo tem seu contador.

Documentação de módulo

Architecture decision records (ADRs)

ADR é diferente de RFC: ADR registra decisão *á tomada* RFC propõe discussão antes de decidir.

Runbooks operacionais

Post-mortems

Naming: data ISO no início ordena cronologicamente.

Memórias de sessão Claude/agentes

Aqui .md é mantido como exceção da policies/document-format.kmd porque consumidores externos (agente Claude Code) leem extensão literal.

Reminders e listas pessoais

Documentação interna do tooling

Convenção de nomes de arquivo

Dentro do path canônico, o nome do arquivo segue:

• *pec de formato* format.kmd (sempre, quando o slug do path identifica a spec).
• *pec por tópico* nome descritivo do tópico (packaging.kmd, wake-word.kmd).
• *FC/ADR* RFC-NNN-<slug>.kmd ou ADR-NNN-<slug>.kmd com NNN = número de 3 dígitos (RFC-001, ADR-042).
• *atalog entry* <slug>.kmd (ou .md por compat histórica nos casos

  já legados em meta/docs/stack/modules/).

Migração de conteúdo no lugar errado

Quando uma sessão encontra conteúdo no path errado:

1. Identifica a categoria (consulta a tabela acima).
2. Verifica se há *ma cópia*ou *uas cópias divergentes*
3. *ingle copy no path errado* git mv para o path canônico,

   atualiza refs com sed, commit em PR único.

4. *uas cópias* identifica qual é a mais recente, aplica como

   conteúdo final no path canônico, deleta a outra. Anota o histórico no commit message.

5. Adiciona frontmatter mínimo (name/type/summary/triggers/references)

   se o path canônico for em meta/docs/stack/specs/ ou meta/docs/stack/policies/ — esses paths exigem frontmatter por policies/document-format.kmd.

Casos resolvidos sob esta policy (registros históricos):

• 20260430: KMD spec migrada de engines/lang/kmd/SPEC.kmd →

  meta/docs/stack/specs/kmd/format.kmd (commit 7d7d185ff).

• 20260430: KVG spec criada já no path canônico (meta/docs/stack/specs/kvg/format.kmd).

Por que esta policy existe

Antes desta policy, a Stack tinha inconsistência:

• KMD spec inline em engines/lang/kmd/SPEC.kmd.
• KVG spec em meta/docs/stack/specs/kvg/format.kmd.
• RFCs espalhados entre meta/docs/stack/rfcs/, engines/sdk/koder_kit/docs/rfcs/, services/ai/kortex/docs/rfcs/, sem critério explícito de quando vai onde.

Sessões de IA e novos engenheiros tomavam decisões casoacaso, gerando drift. Esta policy é o ponto de citação canônico — quando houver dúvida sobre onde colocar algo, consultar esta tabela.

Roadmap

• v0.1 (esta policy) — codifica regra. Sweep manual em PRs cuidando

  de violações.

• v0.2 — koder-test-gate checa criação de arquivos novos contra a

  tabela e falha CI se path errado.

• v0.3 — /k-housekeep audita conteúdo existente, propõe migrações

  pra paths canônicos quando achar violações em sweep periódica.