adjustments on docs

This commit is contained in:
2026-03-24 13:40:47 +00:00
parent f6751a03a4
commit a6ad14fcb2
33 changed files with 831 additions and 1330 deletions
@@ -1,81 +0,0 @@
# Agenda - Single Canonical Architecture
## Problema
Hoje a arquitetura do runtime está fragmentada em documentos com níveis diferentes de autoridade.
Na prática existem pelo menos dois problemas:
- mais de um documento tenta falar pela arquitetura;
- um deles ainda se apresenta como `stub`, enquanto outro se declara baseline canônico.
## Dor
- Contribuidores perdem tempo tentando descobrir qual documento manda.
- PR arquitetural pode ser validada por um texto e contrariar outro.
- A documentação deixa de servir como guardrail e passa a gerar ambiguidade.
- O projeto perde disciplina exatamente na camada que deveria fixar invariantes.
## Alvo da Discussao
Definir um único documento canônico de arquitetura do runtime, com papel explícito para cada outro documento remanescente.
O alvo é matar a ambiguidade, não só mover arquivos.
Ao final da discussão deve ficar claro:
- qual documento é canônico;
- quais docs são derivativos, históricos ou de apoio;
- o que deve ser removido, fundido ou rebaixado de autoridade.
## O Que Precisa Ser Definido
1. Documento canônico.
Onde vive a arquitetura mandatória do runtime.
2. Escopo do documento.
Quais invariantes ele deve cobrir:
- execution model
- memory model
- safepoints
- scheduler
- verifier
- syscall ABI
- firmware/runtime boundary
3. Papel dos demais docs.
O que é:
- arquitetura normativa
- roadmap
- histórico
- specification detalhada
- material pedagógico
4. Política de atualização.
Mudança arquitetural deve exigir atualização do doc canônico no mesmo PR?
5. Estratégia de remoção do `stub`.
Se será apagado, redirecionado ou transformado em índice.
## O Que Necessita Para Resolver
- inventário dos docs que hoje competem por autoridade;
- decisão de taxonomia documental;
- definição do local canônico;
- plano de migração de conteúdo sem perder contexto útil;
- regra de governança para futuras PRs arquiteturais.
## Fora de Escopo
- reorganização completa de todo o diretório `docs/`;
- rewrite estilístico de todo material pedagógico;
- padronização editorial fina além do necessário para eliminar ambiguidade.
## Critério de Saida Desta Agenda
Pode virar PR quando houver:
- definição do documento canônico;
- lista do que será removido, fundido ou rebaixado;
- regra explícita de atualização futura;
- plano curto de migração sem deixar lacuna documental.
@@ -1,77 +0,0 @@
# 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.