From 21030f5c0895d009dde6286f2d809b6a44174cef Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 27 Mar 2026 04:42:38 +0000 Subject: [PATCH] discussion framework migration --- .gitignore | 4 +- AGENTS.md | 274 --------------------------- docs/runtime/decisions/README.md | 47 ----- docs/runtime/pull-requests/README.md | 47 ----- 4 files changed, 3 insertions(+), 369 deletions(-) delete mode 100644 AGENTS.md delete mode 100644 docs/runtime/decisions/README.md delete mode 100644 docs/runtime/pull-requests/README.md diff --git a/.gitignore b/.gitignore index dd4f167f..d6ff6eed 100644 --- a/.gitignore +++ b/.gitignore @@ -58,4 +58,6 @@ temp temp/** **/build/** -**/node_modules/** \ No newline at end of file +**/node_modules/** + +AGENTS.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index a781f661..00000000 --- a/AGENTS.md +++ /dev/null @@ -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. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md deleted file mode 100644 index e3f3c992..00000000 --- a/docs/runtime/decisions/README.md +++ /dev/null @@ -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` diff --git a/docs/runtime/pull-requests/README.md b/docs/runtime/pull-requests/README.md deleted file mode 100644 index f5aab88c..00000000 --- a/docs/runtime/pull-requests/README.md +++ /dev/null @@ -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.