# 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.