prometeu-runtime/docs/runtime/agendas/008-hardware-specs-reorganization.md

Agenda - Hardware Specs Reorganization

Problema

As specs de hardware hoje estão com cara de colcha de retalhos.

Há material útil, mas a organização mistura:

• capítulos extensos e narrativos;
• conteúdo normativo e conteúdo pedagógico;
• temas de VM, firmware, cartridge, assets e ABI no mesmo bloco de "hardware";
• granularidade desigual entre capítulos.

Dor

• Fica difícil saber o que é norma e o que é explicação.
• A navegação está ruim para quem precisa alterar um domínio específico.
• Ownership documental por área não está claro.
• Revisões futuras tendem a acrescentar mais remendos em vez de consolidar o modelo.
• O risco de contradição entre spec, arquitetura e implementação cresce.

Alvo da Discussao

Definir uma organização coerente para as specs do sistema, com separação clara entre:

• spec normativa;
• material conceitual/pedagógico;
• arquitetura de runtime;
• domínios de hardware/periféricos;
• firmware, cartridge e tooling-related specs.

O Que Precisa Ser Definido

1. Taxonomia das specs. Quais grandes categorias devem existir:

   • machine/runtime
   • hardware/peripherals
   • firmware/system
   • cartridge/package
   • host ABI
   • assets/tooling

2. Critério de corte. O que pertence a "hardware" de fato e o que deve sair desse pacote.

3. Estrutura de navegação. Como organizar índice, capítulos, subpastas e documentos canônicos por domínio.

4. Nível de autoridade. Quais documentos são normativos e quais são apenas explicativos.

5. Estratégia de migração. Como reorganizar sem quebrar referências, sem perder contexto e sem reescrever tudo de uma vez.

O Que Necessita Para Resolver

• inventário da estrutura atual;
• proposta de taxonomia e árvore de diretórios;
• mapeamento capítulo atual -> destino futuro;
• política para docs históricos ou híbridos;
• critério mínimo de consistência editorial para novos documentos.

Fora de Escopo

• reescrever toda a spec de hardware imediatamente;
• normalizar cada frase ou estilo de escrita;
• atualizar todo conteúdo técnico de cada capítulo nesta mesma discussão.

Critério de Saida Desta Agenda

Pode virar PR quando houver:

• taxonomia alvo aprovada;
• nova árvore de organização definida;
• mapa de migração dos capítulos atuais;
• decisão sobre normativo vs pedagógico;
• plano incremental de execução.