discussion framework migration
This commit is contained in:
parent
a27ad45f91
commit
21030f5c08
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
2
.gitignore
vendored
2
.gitignore
vendored
@ -59,3 +59,5 @@ temp/**
|
|||||||
|
|
||||||
**/build/**
|
**/build/**
|
||||||
**/node_modules/**
|
**/node_modules/**
|
||||||
|
|
||||||
|
AGENTS.md
|
||||||
274
AGENTS.md
274
AGENTS.md
@ -1,274 +0,0 @@
|
|||||||
# AGENTS
|
|
||||||
|
|
||||||
## Missao
|
|
||||||
|
|
||||||
Este repositorio deve operar com um pipeline rigido de conhecimento e execucao:
|
|
||||||
|
|
||||||
`agenda -> decision -> PR/plan -> spec ou codigo -> learn`
|
|
||||||
|
|
||||||
Regra central:
|
|
||||||
|
|
||||||
- nao pular etapas;
|
|
||||||
- nao resolver ambiguidade estrutural no meio da implementacao;
|
|
||||||
- nao transformar `learn` em deposito cru de historico;
|
|
||||||
- nao escrever spec ou codigo sem base em `decision` e `PR/plan` quando houver impacto arquitetural.
|
|
||||||
|
|
||||||
## Mapa Canonico
|
|
||||||
|
|
||||||
- `docs/runtime/agendas/`: discussao, enquadramento do problema, pontos mais importantes, sugestoes e recomendacao.
|
|
||||||
- `docs/runtime/decisions/`: registro normativo do que foi decidido. Deve estar pronto para propagar em spec ou implementacao.
|
|
||||||
- `docs/runtime/pull-requests/`: plano executavel de entrega para spec e/ou codigo.
|
|
||||||
- `docs/runtime/specs/`: contrato tecnico normativo consolidado.
|
|
||||||
- `docs/runtime/learn/`: consolidacao didatica do que ja foi fechado e executado.
|
|
||||||
- `crates/`: implementacao em codigo.
|
|
||||||
|
|
||||||
## Fluxo Obrigatorio
|
|
||||||
|
|
||||||
### 1. Agenda
|
|
||||||
|
|
||||||
Use `agenda` quando ainda existe ambiguidade, disputa de abordagem, risco arquitetural, escopo mal fechado ou falta de recomendacao.
|
|
||||||
|
|
||||||
Toda agenda deve:
|
|
||||||
|
|
||||||
- apresentar o problema real;
|
|
||||||
- listar os pontos mais importantes da discussao;
|
|
||||||
- separar fato, risco, tradeoff e hipotese;
|
|
||||||
- trazer sugestoes objetivas, nao so perguntas soltas;
|
|
||||||
- terminar com uma recomendacao clara, mesmo que condicional;
|
|
||||||
- explicitar o que ainda impede a decisao.
|
|
||||||
|
|
||||||
Template minimo:
|
|
||||||
|
|
||||||
- `Contexto`
|
|
||||||
- `Problema`
|
|
||||||
- `Pontos Criticos`
|
|
||||||
- `Opcoes`
|
|
||||||
- `Sugestao / Recomendacao`
|
|
||||||
- `Perguntas em Aberto`
|
|
||||||
- `Criterio para Encerrar`
|
|
||||||
|
|
||||||
Regra de saida:
|
|
||||||
|
|
||||||
- agenda concluida deve virar `decision`;
|
|
||||||
- agenda que ainda nao fecha contrato nao pode virar PR de implementacao.
|
|
||||||
|
|
||||||
### 2. Decision
|
|
||||||
|
|
||||||
Toda agenda concluida deve se tornar uma `decision`.
|
|
||||||
|
|
||||||
Uma `decision` deve conter tudo que a equipe precisa para propagar a decisao em spec ou implementacao, inclusive referencias para specs ja consolidadas quando existirem.
|
|
||||||
|
|
||||||
Toda decision deve:
|
|
||||||
|
|
||||||
- declarar a decisao tomada sem ambiguidade;
|
|
||||||
- registrar contexto e drivers;
|
|
||||||
- listar alternativas descartadas e por que foram descartadas;
|
|
||||||
- definir invariantes e contrato operacional;
|
|
||||||
- delimitar impacto em specs, runtime, host, firmware e tooling quando aplicavel;
|
|
||||||
- apontar referencias normativas existentes;
|
|
||||||
- deixar claro o que ainda precisa ser implementado ou publicado.
|
|
||||||
|
|
||||||
Template minimo:
|
|
||||||
|
|
||||||
- `Status`
|
|
||||||
- `Contexto`
|
|
||||||
- `Decisao`
|
|
||||||
- `Rationale`
|
|
||||||
- `Invariantes / Contrato`
|
|
||||||
- `Impactos`
|
|
||||||
- `Referencias`
|
|
||||||
- `Propagacao Necessaria`
|
|
||||||
|
|
||||||
Regra de saida:
|
|
||||||
|
|
||||||
- decision fechada deve evoluir para `PR/plan`;
|
|
||||||
- se a decision nao estiver pronta para orientar execucao, ela ainda nao esta fechada.
|
|
||||||
|
|
||||||
### 3. PR / Plan
|
|
||||||
|
|
||||||
`PR` e o artefato de planejamento de execucao. Ele nasce de uma ou mais `decisions`.
|
|
||||||
|
|
||||||
Toda PR deve:
|
|
||||||
|
|
||||||
- citar explicitamente as decisions de origem;
|
|
||||||
- separar implementacao de spec e implementacao de codigo quando o escopo pedir;
|
|
||||||
- definir alvo, fora de escopo, riscos e ordem de execucao;
|
|
||||||
- trazer criterios de aceite verificaveis;
|
|
||||||
- definir estrategia de testes e evidencias esperadas;
|
|
||||||
- bloquear reabertura de debate arquitetural dentro da fase de execucao.
|
|
||||||
|
|
||||||
Template minimo:
|
|
||||||
|
|
||||||
- `Briefing`
|
|
||||||
- `Decisions de Origem`
|
|
||||||
- `Alvo`
|
|
||||||
- `Escopo`
|
|
||||||
- `Fora de Escopo`
|
|
||||||
- `Plano de Execucao`
|
|
||||||
- `Criterios de Aceite`
|
|
||||||
- `Tests / Validacao`
|
|
||||||
- `Riscos`
|
|
||||||
|
|
||||||
Regra de saida:
|
|
||||||
|
|
||||||
- PR de spec alimenta `docs/runtime/specs/`;
|
|
||||||
- PR de codigo alimenta `crates/`;
|
|
||||||
- PR concluida deve deixar rastro para consolidacao em `learn`.
|
|
||||||
|
|
||||||
### 4. Learn
|
|
||||||
|
|
||||||
`learn` recebe conhecimento consolidado de decisions que ja viraram PR e tiveram resultado publicado em spec, codigo ou ambos.
|
|
||||||
|
|
||||||
`learn` nao e fonte normativa. `learn` explica, organiza, ensina e melhora a transmissao do modelo mental.
|
|
||||||
|
|
||||||
Toda consolidacao em `learn` deve:
|
|
||||||
|
|
||||||
- partir de decisions ja fechadas;
|
|
||||||
- refletir o estado publicado em specs e/ou codigo;
|
|
||||||
- explicar o "como pensar" e nao so o "o que aconteceu";
|
|
||||||
- linkar para specs e decisions correspondentes;
|
|
||||||
- remover redundancia historica quando houver material sobreposto.
|
|
||||||
|
|
||||||
Regra de manutencao:
|
|
||||||
|
|
||||||
- de tempos em tempos, refatorar `learn` por tema, modelo mental e progressao didatica;
|
|
||||||
- preferir guias tematicos a acumulo cronologico de decisions aposentadas;
|
|
||||||
- preservar backlinks para decisions/specs originais.
|
|
||||||
|
|
||||||
## Workers Obrigatorios
|
|
||||||
|
|
||||||
### Agenda Worker
|
|
||||||
|
|
||||||
Use para abrir ou conduzir discussoes.
|
|
||||||
|
|
||||||
Responsabilidades:
|
|
||||||
|
|
||||||
- sintetizar pontos mais importantes;
|
|
||||||
- propor sugestoes concretas;
|
|
||||||
- separar sinal de ruido;
|
|
||||||
- empurrar para uma recomendacao.
|
|
||||||
|
|
||||||
Nao faz:
|
|
||||||
|
|
||||||
- fechar contrato normativo cedo demais;
|
|
||||||
- planejar implementacao detalhada.
|
|
||||||
|
|
||||||
### Decision Worker
|
|
||||||
|
|
||||||
Use para transformar agenda concluida em decisao clara.
|
|
||||||
|
|
||||||
Responsabilidades:
|
|
||||||
|
|
||||||
- cristalizar a decisao;
|
|
||||||
- registrar invariantes;
|
|
||||||
- preparar a propagacao para spec e implementacao;
|
|
||||||
- referenciar material normativo ja existente.
|
|
||||||
|
|
||||||
Nao faz:
|
|
||||||
|
|
||||||
- escrever plano de execucao detalhado;
|
|
||||||
- deixar ambiguidades estruturais escondidas.
|
|
||||||
|
|
||||||
### PR Worker
|
|
||||||
|
|
||||||
Use para transformar decisions em execucao.
|
|
||||||
|
|
||||||
Responsabilidades:
|
|
||||||
|
|
||||||
- decompor o trabalho;
|
|
||||||
- separar fases editorial e de codigo;
|
|
||||||
- definir aceite, testes, riscos e sequenciamento.
|
|
||||||
|
|
||||||
Nao faz:
|
|
||||||
|
|
||||||
- rediscutir arquitetura base;
|
|
||||||
- improvisar contrato no meio do plano.
|
|
||||||
|
|
||||||
### Learn Worker
|
|
||||||
|
|
||||||
Use para consolidar conhecimento e refatorar `docs/runtime/learn/`.
|
|
||||||
|
|
||||||
Perfil esperado:
|
|
||||||
|
|
||||||
- didatico;
|
|
||||||
- editorial;
|
|
||||||
- orientado a modelo mental, exemplos e progressao pedagogica.
|
|
||||||
|
|
||||||
Responsabilidades:
|
|
||||||
|
|
||||||
- consolidar varias decisions em artefatos mais ensinaveis;
|
|
||||||
- reorganizar material por tema;
|
|
||||||
- reduzir repeticao e melhorar navegacao.
|
|
||||||
|
|
||||||
Nao faz:
|
|
||||||
|
|
||||||
- redefinir contrato tecnico;
|
|
||||||
- competir com specs.
|
|
||||||
|
|
||||||
### Spec Worker
|
|
||||||
|
|
||||||
Use para implementar specs a partir de decisions e PRs.
|
|
||||||
|
|
||||||
Perfil esperado:
|
|
||||||
|
|
||||||
- editorial;
|
|
||||||
- normativo;
|
|
||||||
- preciso em contrato, escopo e linguagem.
|
|
||||||
|
|
||||||
Responsabilidades:
|
|
||||||
|
|
||||||
- atualizar ou criar specs coerentes com a decision;
|
|
||||||
- manter contrato tecnico consistente;
|
|
||||||
- citar referencias normativas corretas.
|
|
||||||
|
|
||||||
Nao faz:
|
|
||||||
|
|
||||||
- inventar decisao nova durante edicao;
|
|
||||||
- introduzir framing pedagogico de `learn` dentro do texto normativo.
|
|
||||||
|
|
||||||
### Code Worker
|
|
||||||
|
|
||||||
Use para implementar codigo a partir de decisions, specs e PRs.
|
|
||||||
|
|
||||||
Perfil esperado:
|
|
||||||
|
|
||||||
- executor;
|
|
||||||
- rigoroso;
|
|
||||||
- focado em comportamento, testes e aderencia ao contrato.
|
|
||||||
|
|
||||||
Responsabilidades:
|
|
||||||
|
|
||||||
- implementar o que a spec/decision manda;
|
|
||||||
- validar impacto e cobertura;
|
|
||||||
- apontar qualquer conflito entre codigo e contrato.
|
|
||||||
|
|
||||||
Nao faz:
|
|
||||||
|
|
||||||
- compensar ambiguidade arquitetural com heuristica local;
|
|
||||||
- esconder mudanca de contrato dentro de refactor.
|
|
||||||
|
|
||||||
## Regras de Transicao
|
|
||||||
|
|
||||||
- nunca criar PR de implementacao se o assunto ainda e uma agenda em aberto;
|
|
||||||
- toda agenda encerrada deve resultar em `decision` ou ser explicitamente descartada;
|
|
||||||
- toda decision relevante deve gerar `PR/plan` antes de alterar spec ou codigo;
|
|
||||||
- toda decision executada deve deixar consolidacao em `learn`, direta ou agrupada;
|
|
||||||
- quando `learn` acumular historico demais, ativar o `Learn Worker` para refatoracao didatica.
|
|
||||||
|
|
||||||
## Regra Editorial
|
|
||||||
|
|
||||||
- `agenda` discute;
|
|
||||||
- `decision` decide;
|
|
||||||
- `PR` planeja;
|
|
||||||
- `spec` normatiza;
|
|
||||||
- `codigo` implementa;
|
|
||||||
- `learn` ensina.
|
|
||||||
|
|
||||||
Se um artefato comecar a fazer o trabalho do outro, ele esta errado.
|
|
||||||
|
|
||||||
## Regra de Idioma
|
|
||||||
|
|
||||||
- todo conteudo publicado em `docs/runtime/specs/` deve ser escrito em ingles;
|
|
||||||
- todo conteudo publicado em `docs/runtime/learn/` deve ser escrito em ingles;
|
|
||||||
- essa regra vale mesmo quando a discussao, agenda, decision, PR ou conversa com o usuario acontecer em portugues;
|
|
||||||
- ao editar artefatos existentes em `specs` ou `learn`, corrigir para ingles qualquer trecho residual em outro idioma.
|
|
||||||
@ -1,47 +0,0 @@
|
|||||||
# Runtime Decisions
|
|
||||||
|
|
||||||
Este diretório reúne decision records do runtime.
|
|
||||||
|
|
||||||
Objetivo:
|
|
||||||
|
|
||||||
- registrar decisoes arquiteturais ja tomadas;
|
|
||||||
- servir como referencia normativa para agendas derivadas;
|
|
||||||
- evitar reabrir discussoes que ja foram fechadas.
|
|
||||||
|
|
||||||
Regra de uso:
|
|
||||||
|
|
||||||
- agendas existem para discutir e fechar ambiguidade;
|
|
||||||
- decision records existem para registrar o que foi decidido;
|
|
||||||
- quando uma agenda for resolvida, ela deve sair de `agendas/` e virar decision record aqui.
|
|
||||||
|
|
||||||
Decisoes ativas:
|
|
||||||
|
|
||||||
Nenhuma no momento.
|
|
||||||
|
|
||||||
Decisoes implementadas e aposentadas (migradas para `learn/`):
|
|
||||||
|
|
||||||
- `historical-vm-core-and-assets.md`
|
|
||||||
- decisions: `003`, `006`, `007`, `011`, `012`
|
|
||||||
- rationales: VM-owned stateful core, byte transfer protocol, FS fault policy, assets.pa contract and ID-based preload.
|
|
||||||
- `historical-gfx-status-first-fault-and-return-contract.md`
|
|
||||||
- spec: `../specs/04-gfx-peripheral.md`
|
|
||||||
- impl: `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/gfx.rs`
|
|
||||||
- `historical-audio-status-first-fault-and-return-contract.md`
|
|
||||||
- spec: `../specs/05-audio-peripheral.md`
|
|
||||||
- impl: `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/audio.rs`, `crates/console/prometeu-hal/src/audio_bridge.rs`, `crates/console/prometeu-drivers/src/audio.rs`
|
|
||||||
- `historical-asset-status-first-fault-and-return-contract.md`
|
|
||||||
- spec: `../specs/15-asset-management.md`
|
|
||||||
- impl: `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/asset.rs`, `crates/console/prometeu-hal/src/asset_bridge.rs`, `crates/console/prometeu-drivers/src/asset.rs`
|
|
||||||
- `historical-game-memcard-slots-surface-and-semantics.md`
|
|
||||||
- spec: `../specs/08-save-memory-and-memcard.md`, `../specs/16-host-abi-and-syscalls.md`, `../specs/16a-syscall-policies.md`
|
|
||||||
- impl: `crates/console/prometeu-system/src/services/memcard.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/fs.rs`
|
|
||||||
|
|
||||||
Decisoes aposentadas que ja viraram spec:
|
|
||||||
|
|
||||||
- `004-host-fault-taxonomy.md` -> `../specs/16a-syscall-policies.md`
|
|
||||||
- `005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md` -> `../specs/06-input-peripheral.md`, `../specs/16-host-abi-and-syscalls.md`, `../specs/16a-syscall-policies.md`
|
|
||||||
- `013-asset-codec-none-vs-raw.md` -> `../specs/15-asset-management.md`, `../learn/mental-model-asset-management.md`, `crates/console/prometeu-drivers/src/asset.rs`, `crates/console/prometeu-hal/src/asset.rs`
|
|
||||||
|
|
||||||
Racional historico (nao normativo):
|
|
||||||
|
|
||||||
- `../learn/historical-retired-fault-and-input-decisions.md`
|
|
||||||
@ -1,47 +0,0 @@
|
|||||||
# Pull Requests
|
|
||||||
|
|
||||||
Este diretório armazena propostas de PRs arquiteturais e de implementação para o runtime.
|
|
||||||
|
|
||||||
## Padrão
|
|
||||||
|
|
||||||
Toda PR neste diretório deve ser autocontida.
|
|
||||||
|
|
||||||
Cada documento deve incluir, no mínimo:
|
|
||||||
|
|
||||||
- `Briefing`
|
|
||||||
- `Alvo`
|
|
||||||
- `Critérios de Aceite`
|
|
||||||
- `Tests`, quando necessário
|
|
||||||
|
|
||||||
## Barra de Qualidade
|
|
||||||
|
|
||||||
O padrão esperado é JVM-grade.
|
|
||||||
|
|
||||||
Isso implica:
|
|
||||||
|
|
||||||
- arquitetura vem antes de implementação;
|
|
||||||
- decisões arquiteturais não devem ser tomadas durante a fase de implementação;
|
|
||||||
- quando a implementação encontrar dúvida arquitetural, a PR deve voltar para discussão de arquitetura;
|
|
||||||
- diante de ambiguidade estrutural, é preferível interromper a execução da PR e levantar um questionamento severo do que cristalizar uma decisão errada no código.
|
|
||||||
|
|
||||||
## Condução
|
|
||||||
|
|
||||||
Uma PR deste diretório deve:
|
|
||||||
|
|
||||||
- definir claramente o problema;
|
|
||||||
- delimitar o alvo da mudança;
|
|
||||||
- explicitar o que está fora de escopo quando houver risco de expansão;
|
|
||||||
- estabelecer critérios objetivos de aceite;
|
|
||||||
- definir a estratégia de teste proporcional ao risco da mudança.
|
|
||||||
|
|
||||||
## Roadmap Atual
|
|
||||||
|
|
||||||
Nenhuma PR em aberto no momento.
|
|
||||||
|
|
||||||
## PRs Finalizadas
|
|
||||||
|
|
||||||
- `012-assets-preload-asset-id-propagation.md`: concluída. Propagação de ID-based preload concluída em specs e prometeu-hal.
|
|
||||||
- `013-tile-bank-runtime-contract-alignment.md`: concluída. Contrato normativo de `tile bank` v1 alinhado entre `specs/04` e `specs/15`.
|
|
||||||
- `014-tile-bank-loader-packed-nibbles-and-palette-boundary.md`: concluída. Loader/runtime atualizado para consumir payload serializado `4bpp` packed com `64` paletas por bank.
|
|
||||||
- `015-asset-codec-none-canonicalization-in-specs.md`: concluída. `NONE` publicado como valor canonico de ausencia de codec adicional nas specs.
|
|
||||||
- `016-asset-codec-none-runtime-and-tests.md`: concluída. Runtime e fixtures migrados para `NONE`, preservando `RAW` apenas como alias legado temporário.
|
|
||||||
Loading…
x
Reference in New Issue
Block a user