prometeu-runtime/docs/runtime/pull-requests/PR-018-[SPECS]-reorganize-hardware-specification-surface.md

PR-018 [SPECS]: Reorganize Hardware Specification Surface

Briefing

As specs de hardware e sistema acumuladas no repositorio contem material valioso, mas a organizacao atual esta irregular. Hoje convivem no mesmo pacote temas de perifericos, VM, firmware, cartridge, assets e host ABI, com pesos muito diferentes entre si e sem uma separacao suficientemente clara entre conteudo normativo e conteudo pedagogico.

Esta PR nao pretende reescrever toda a especificacao. Ela existe para organizar a superficie documental, definir taxonomia e preparar o terreno para futuras PRs de conteudo sem perpetuar a colcha de retalhos atual.

Problema

• o pacote de specs atual mistura dominios heterogeneos sob a mesma superficie de "hardware";
• ha capitulos extensos e narrativos convivendo com material que deveria ser normativo;
• ownership documental por area nao esta claro;
• a navegacao esta fraca para quem precisa alterar apenas um dominio tecnico;
• o risco de contradicao entre spec, arquitetura e implementacao cresce a cada novo remendo.

Alvo

• docs/specs/hardware/ e sua organizacao atual;
• relacao entre specs de hardware, arquitetura de runtime, firmware, cartridge, assets e host ABI;
• indice e taxonomia documental das specs tecnicas.

Escopo

• Definir uma taxonomia clara para as specs tecnicas do projeto, por exemplo:
  • machine/runtime;
  • hardware/peripherals;
  • firmware/system;
  • cartridge/package;
  • host ABI;
  • assets/tooling.
• Decidir o que realmente pertence ao pacote de "hardware" e o que deve migrar para outra categoria.
• Propor uma nova arvore de organizacao e navegacao para as specs.
• Mapear os capitulos atuais para seus destinos futuros.
• Explicitar o que e:
  • normativo;
  • explicativo;
  • historico;
  • pedagogico.

Fora de Escopo

• Reescrever tecnicamente todos os capitulos.
• Atualizar o conteudo detalhado de cada spec nesta mesma PR.
• Alterar a arquitetura do runtime por meio de reorganizacao documental.
• Normalizar todo estilo editorial do repositorio.

Abordagem

1. Inventariar a estrutura atual das specs e classificar cada documento por dominio e funcao.
2. Definir uma taxonomia pequena, defensavel e duravel para as specs do projeto.
3. Desenhar a arvore alvo de diretorios e indices.
4. Mapear capitulo atual -> destino futuro, explicitando:
   • permanece;
   • move;
   • divide;
   • funde;
   • vira historico.
5. Ajustar a navegacao minima para que a reorganizacao nao deixe o leitor sem trilha.

Criterios de Aceite

• Existe uma taxonomia aprovada para as specs tecnicas.
• A organizacao alvo de diretorios e indices esta definida.
• Cada capitulo atual relevante tem destino planejado.
• A separacao entre conteudo normativo e pedagogico fica explicita.
• O pacote de "hardware" deixa de ser deposito generico de temas nao relacionados.

Tests

• Revisao manual da navegacao entre indice principal, README das specs e topicos afetados.
• Confirmacao de que a nova organizacao nao cria links quebrados nos pontos principais do repositorio.
• Validacao de que a taxonomia proposta e coerente com o documento canonico de arquitetura.

Risco

Medio. O risco principal e trocar a desordem atual por uma reorganizacao cosmetica sem criterio de autoridade nem ownership. A PR deve sair com taxonomia clara e mapa de migracao; sem isso, sera apenas renomeacao de pastas.