diff --git a/.ai-engineering/works/.sequence.yaml b/.ai-engineering/works/.sequence.yaml index 9a9d561..4ebeb6e 100644 --- a/.ai-engineering/works/.sequence.yaml +++ b/.ai-engineering/works/.sequence.yaml @@ -1,3 +1,3 @@ --- schemaVersion: 2 -lastWork: "0001" +lastWork: "0002" diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0001/artifact.yaml b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0001/artifact.yaml new file mode 100644 index 0000000..1ea9e62 --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0001/artifact.yaml @@ -0,0 +1,12 @@ +--- +schemaVersion: 1 +id: "ART-0001" +workId: "WRK-0002" +origin: "Revisão local da documentação nesta sessão" +purpose: "Conferência dos links, comandos de referência, cadastro dos submódulos e\ + \ integridade AIE." +path: "artifacts/evidence/ART-0001/payload" +sha256: "5a5ac6d3c67fa6154469fe6f1dc29f0bee5d0d088e9218e701d821f48c5d2985" +size: 1049 +author: "codex" +createdAt: "2026-11-16T15:21:17.596766Z" diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0001/payload b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0001/payload new file mode 100644 index 0000000..bc9486b --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0001/payload @@ -0,0 +1,37 @@ +{ + "file": "README.md", + "language": "pt-BR", + "verifiedLocalLinks": [ + ".ai-engineering/README.md", + ".ai-engineering/ai-engineering.yaml", + ".ai-engineering/protocol.json", + ".gitignore", + ".gitmodules", + "AGENTS.md", + "runtime/README.md", + "runtime/docs/specs/runtime/README.md", + "runtime/docs/vm-arch/ARCHITECTURE.md", + "runtime/rust-toolchain.toml", + "studio/README.md", + "studio/docs/specs/README.md", + "studio/docs/specs/compiler-languages/pbs/README.md", + "studio/docs/specs/compiler/README.md", + "studio/docs/specs/packer/README.md" + ], + "commandsCheckedAgainst": [ + "runtime/README.md", + "studio/README.md", + ".ai-engineering/README.md" + ], + "aieRepositories": [ + "runtime", + "studio" + ], + "aieValidation": { + "valid": true, + "issues": [] + }, + "formatChecks": "Links existentes, blocos de código fechados e nenhuma linha com whitespace final.", + "buildsAndTestsExecuted": false, + "scope": "Documentação da raiz; nenhum arquivo dos submódulos alterado." +} diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0002/artifact.yaml b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0002/artifact.yaml new file mode 100644 index 0000000..b360e71 --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0002/artifact.yaml @@ -0,0 +1,12 @@ +--- +schemaVersion: 1 +id: "ART-0002" +workId: "WRK-0002" +origin: "ai-engineering:plans:2803d39a98459502e73c955be703622a8cc47dd69c7a569f4c43ee7ed6e073d7" +purpose: "Deterministic aggregation of completed Plans and reviewed cancellations;\ + \ not semantic verification of prose criteria" +path: "artifacts/evidence/ART-0002/payload" +sha256: "2803d39a98459502e73c955be703622a8cc47dd69c7a569f4c43ee7ed6e073d7" +size: 283 +author: "system:plans" +createdAt: "2026-11-16T15:21:18.142480Z" diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0002/payload b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0002/payload new file mode 100644 index 0000000..2a44955 --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/artifacts/evidence/ART-0002/payload @@ -0,0 +1,10 @@ +{ + "schemaVersion" : 1, + "workId" : "WRK-0002", + "inputHash" : "a51290e3dff5fb7c0a7d0ff332c35a98d9291d393a3dc7cc3b45c4183318e5c0", + "plans" : [ { + "id" : "PLN-0001", + "revision" : 5, + "sha256" : "507e309bdba50d03a4656516b6ce5ee54f71de57e88dba2db0e2daf96a17a87d" + } ] +} diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/discussions/DSC-0001.md b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/discussions/DSC-0001.md new file mode 100644 index 0000000..b0dd938 --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/discussions/DSC-0001.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0001" +workId: "WRK-0002" +discussionId: "main" +kind: "NOTE" +author: "user" +createdAt: "2026-11-16T15:20:07.403258Z" +respondsTo: null +documentVersion: 2 +--- + +Solicitação explícita nesta sessão: "escreva um README para o prometeu engineering." Escopo: documentação na raiz do workspace, mantendo somente runtime e studio como projetos versionados. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0001.md b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0001.md new file mode 100644 index 0000000..51b828e --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0001.md @@ -0,0 +1,18 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-0002" +title: "Escrever e revisar o README do workspace" +decisions: [] +steps: [] +status: "OPEN" +author: "codex" +createdAt: "2026-11-16T15:20:07.665626Z" +revision: 1 +previousHash: null +updatedAt: "2026-11-16T15:20:07.665626Z" +updatedBy: "codex" +changeReason: "Plan created" +documentVersion: 2 +--- + diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0002.md b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0002.md new file mode 100644 index 0000000..de9c83c --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0002.md @@ -0,0 +1,29 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-0002" +title: "Escrever e revisar o README do workspace" +decisions: [] +steps: +- id: "TSK-0001" + title: "Escrever README em português e conferir referências e comandos locais" + description: "" + acceptanceCriteria: + - "Propósito, submódulos, ignore, início do trabalho com AIE e referências locais\ + \ documentados; links e integridade AIE verificados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-16T15:20:08.090183Z" +status: "OPEN" +author: "codex" +createdAt: "2026-11-16T15:20:07.665626Z" +revision: 2 +previousHash: "16f89cd1148f3383a1e267c63bc9b3e7618c263f883efc2bd944ab19ac5bfef9" +updatedAt: "2026-11-16T15:20:08.090212Z" +updatedBy: "codex" +changeReason: "Step added" +documentVersion: 2 +--- + diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0003.md b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0003.md new file mode 100644 index 0000000..974f34a --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0003.md @@ -0,0 +1,31 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-0002" +title: "Escrever e revisar o README do workspace" +decisions: [] +steps: +- id: "TSK-0001" + title: "Escrever README em português e conferir referências e comandos locais" + description: "" + acceptanceCriteria: + - "Propósito, submódulos, ignore, início do trabalho com AIE e referências locais\ + \ documentados; links e integridade AIE verificados." + dependsOn: [] + status: "ACTIVE" + result: "README escrito; conferindo links, exemplos e correspondência com a configuraç\ + ão local." + evidence: [] + updatedAt: "2026-11-16T15:21:08.185034Z" +status: "ACTIVE" +author: "codex" +createdAt: "2026-11-16T15:20:07.665626Z" +revision: 3 +previousHash: "8bdd1fd4ecbfbb87e46bef9d9b004fd2c34b5361cebf0f08fcc3e966414d13dd" +updatedAt: "2026-11-16T15:21:08.185074Z" +updatedBy: "codex" +changeReason: "README escrito; conferindo links, exemplos e correspondência com a\ + \ configuração local." +documentVersion: 2 +--- + diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0004.md b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0004.md new file mode 100644 index 0000000..75ac0fd --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/.history/PLN-0001/r0004.md @@ -0,0 +1,34 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-0002" +title: "Escrever e revisar o README do workspace" +decisions: [] +steps: +- id: "TSK-0001" + title: "Escrever README em português e conferir referências e comandos locais" + description: "" + acceptanceCriteria: + - "Propósito, submódulos, ignore, início do trabalho com AIE e referências locais\ + \ documentados; links e integridade AIE verificados." + dependsOn: [] + status: "COMPLETED" + result: "README em português criado com visão do workspace, submódulos, política\ + \ de ignore, preparação, fluxo AIE, desenvolvimento e referências; links e comandos\ + \ conferidos e validação AIE sem erros." + evidence: + - "ART-0001" + updatedAt: "2026-11-16T15:21:17.892124Z" +status: "ACTIVE" +author: "codex" +createdAt: "2026-11-16T15:20:07.665626Z" +revision: 4 +previousHash: "15f998f0780319273c8b2772289fbf16b22c1b74795e81e3ae1141278fc901a4" +updatedAt: "2026-11-16T15:21:17.892152Z" +updatedBy: "codex" +changeReason: "README em português criado com visão do workspace, submódulos, polí\ + tica de ignore, preparação, fluxo AIE, desenvolvimento e referências; links e comandos\ + \ conferidos e validação AIE sem erros." +documentVersion: 2 +--- + diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/PLN-0001.md b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/PLN-0001.md new file mode 100644 index 0000000..76dbad6 --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/plans/PLN-0001.md @@ -0,0 +1,32 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-0002" +title: "Escrever e revisar o README do workspace" +decisions: [] +steps: +- id: "TSK-0001" + title: "Escrever README em português e conferir referências e comandos locais" + description: "" + acceptanceCriteria: + - "Propósito, submódulos, ignore, início do trabalho com AIE e referências locais\ + \ documentados; links e integridade AIE verificados." + dependsOn: [] + status: "COMPLETED" + result: "README em português criado com visão do workspace, submódulos, política\ + \ de ignore, preparação, fluxo AIE, desenvolvimento e referências; links e comandos\ + \ conferidos e validação AIE sem erros." + evidence: + - "ART-0001" + updatedAt: "2026-11-16T15:21:17.892124Z" +status: "COMPLETED" +author: "codex" +createdAt: "2026-11-16T15:20:07.665626Z" +revision: 5 +previousHash: "dc6be7ae04a25403541f097f49a4346829698b59c4652e760b7de7705111ae0e" +updatedAt: "2026-11-16T15:21:18.008863Z" +updatedBy: "system:plans" +changeReason: "All required steps completed; reviewed cancellations retained" +documentVersion: 2 +--- + diff --git a/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/work.md b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/work.md new file mode 100644 index 0000000..cb09ff9 --- /dev/null +++ b/.ai-engineering/works/WRK-0002-documentar-o-prometeu-engineering-no-readme-da-raiz/work.md @@ -0,0 +1,66 @@ +--- +schemaVersion: 1 +id: "WRK-0002" +title: "Documentar o Prometeu Engineering no README da raiz" +description: "" +goal: "Apresentar o workspace, seus dois submódulos e o fluxo de engenharia com AIE\ + \ em um README em português." +motivation: "" +constraints: [] +acceptanceCriteria: +- "README.md explica propósito, runtime, studio, inicialização dos submódulos e polí\ + tica de ignore." +- "README.md orienta o fluxo AIE e referencia documentação e comandos verificados\ + \ nos arquivos locais." +status: "COMPLETED" +createdAt: "2026-11-16T15:19:58.000374Z" +updatedAt: "2026-11-16T15:21:18.154806Z" +author: "codex" +repositories: [] +discussions: +- "DSC-0001" +decisions: [] +artifacts: +- "ART-0001" +- "ART-0002" +plans: +- "PLN-0001" +completions: +- at: "2026-11-16T15:21:18.154806Z" + by: "system:plans" + summary: "All required Plans completed; requester=codex" + humanApproved: false + scopeHash: "e6d2bb5571a56ed8dbe62ee7b42da149cc11f146eaa642db7ad68f4f74fefbcd" + criteria: + - criterion: 1 + text: "README.md explica propósito, runtime, studio, inicialização dos submódulos\ + \ e política de ignore." + evidence: + - "ART-0002" + - criterion: 2 + text: "README.md orienta o fluxo AIE e referencia documentação e comandos verificados\ + \ nos arquivos locais." + evidence: + - "ART-0002" + integrations: [] + noIntegrationReason: "Canonical changes and execution results are recorded in the\ + \ Plan step evidence" + origin: "SYSTEM_PLANS" + delegation: null + aggregation: + receipt: "ART-0002" + inputHash: "a51290e3dff5fb7c0a7d0ff332c35a98d9291d393a3dc7cc3b45c4183318e5c0" + requester: "codex" + requestId: "0835f52b-b814-465d-9fa2-e5e6851f00e9" +events: +- action: "COMPLETE" + by: "system:plans" + reason: "All required Plans completed; requester=codex" + at: "2026-11-16T15:21:18.154806Z" +archived: false +topics: [] +surveys: [] +dispositions: [] +agentRuns: [] +epic: false +--- diff --git a/README.md b/README.md new file mode 100644 index 0000000..459e4e7 --- /dev/null +++ b/README.md @@ -0,0 +1,147 @@ +# Prometeu Engineering + +Workspace de engenharia do **Prometeu**, um console virtual educacional e +experimental. Reúne os repositórios da plataforma e o contexto de trabalho em +[AI Engineering (AIE)](.ai-engineering/README.md): discussões, decisões, planos e +evidências de execução. + +## Projetos + +Os únicos projetos integrados a este workspace são os submódulos Git abaixo, +também cadastrados no AIE: + +| Projeto | Responsabilidade | Tecnologia | +| --- | --- | --- | +| [runtime](runtime/README.md) | Execução da máquina: VM, periféricos, firmware, integração com o host e CLI. | Rust | +| [studio](studio/README.md) | Ambiente de desenvolvimento: interface desktop, compilador, empacotamento de assets e integração com execução e depuração. | Java, JavaFX e Gradle | + +Cada submódulo mantém seu próprio histórico, especificações e comandos de +validação. Este repositório registra as revisões usadas em conjunto e organiza o +trabalho de engenharia do workspace. + +## Estrutura + +```text +. +├── .ai-engineering/ # Configuração, protocolo e Works do AIE +├── .gitignore # Política de arquivos e diretórios locais +├── .gitmodules # Origens dos dois submódulos +├── AGENTS.md # Instruções de engenharia para agentes +├── README.md +├── runtime/ # Submódulo da máquina e runtime +└── studio/ # Submódulo do ambiente de desenvolvimento +``` + +O [`.gitignore`](.gitignore) ignora os demais diretórios na raiz, inclusive novos +projetos locais. As exceções são `runtime/`, `studio/` e `.ai-engineering/`. +Os arquivos locais e temporários do AIE têm regras próprias de exclusão. + +## Preparar o workspace + +É necessário ter Git e acesso SSH aos repositórios definidos em +[`.gitmodules`](.gitmodules). Após clonar este repositório, execute na raiz: + +```bash +git submodule update --init runtime studio +git submodule status +``` + +Esse comando carrega as revisões registradas pelo workspace. Após atualizar o +repositório principal, execute novamente `git submodule update --init runtime studio` +para alinhar os submódulos às revisões recebidas. + +Para desenvolver, consulte os requisitos específicos de cada projeto: + +- **Runtime:** Rust via `rustup`, com a versão definida em + [`rust-toolchain.toml`](runtime/rust-toolchain.toml). Veja os requisitos completos + no [README do runtime](runtime/README.md). +- **Studio:** JDK e ambiente desktop para JavaFX; o Gradle Wrapper está incluído. + Veja os requisitos e opções de instalação no [README do Studio](studio/README.md). +- **Engenharia:** CLI `aie` ou `ai-engineering` disponível no ambiente. + +## Trabalhar com AIE + +Antes de iniciar trabalho de engenharia, leia o [AGENTS.md](AGENTS.md), o +[guia do protocolo](.ai-engineering/README.md) e o +[manifesto](.ai-engineering/protocol.json). Consulte também as instruções locais +do projeto que será alterado. + +Na raiz do workspace, consulte o estado e as próximas ações: + +```bash +aie status --format json +aie next-actions --format json +aie repo list --format json +``` + +Selecione um Work existente que corresponda à tarefa. Se não houver, crie um +com objetivo e critérios de aceitação; associe apenas os repositórios envolvidos. +Por exemplo, para uma alteração de integração: + +```bash +aie work create "Descrever a alteração de integração" --repo runtime --repo studio +``` + +Carregue o contexto usando o identificador retornado, substituindo `WRK-XXXX`: + +```bash +aie work context WRK-XXXX --format markdown +``` + +Registre discussões, decisões, planos e evidências no Work correspondente. +Aprovações humanas devem ser explícitas, conforme o protocolo. A configuração +atual cadastra os dois repositórios com acesso de leitura no AIE; esse cadastro +não concede autorização de edição. + +Para conferir a integridade dos registros: + +```bash +aie project validate --format json +``` + +Se o alias `aie` não estiver disponível, use `ai-engineering` com os mesmos +argumentos. Sem a CLI, consulte os arquivos portáveis em `.ai-engineering/`. + +## Desenvolvimento e validação + +Execute os comandos no diretório do respectivo submódulo. + +**Runtime:** + +```bash +cd runtime +cargo build +make test +``` + +O gate de CI do runtime é `make ci-domains`; seus requisitos adicionais estão +documentados no [README do runtime](runtime/README.md). + +**Studio**, a partir da raiz do workspace: + +```bash +cd studio +./gradlew :prometeu-app:run +./gradlew test +``` + +As instruções de distribuição, cobertura e testes de integração estão no +[README do Studio](studio/README.md). + +As alterações de código são commitadas no submódulo correspondente. Depois, +registre neste repositório a atualização do ponteiro de `runtime` ou `studio`, +junto aos registros de engenharia relacionados. O commit da raiz referencia um +commit do submódulo; os arquivos de código pertencem ao histórico desse projeto. + +## Referências + +- [Especificações da máquina](runtime/docs/specs/runtime/README.md) +- [Arquitetura da VM e runtime](runtime/docs/vm-arch/ARCHITECTURE.md) +- [Guia de especificações do Studio](studio/docs/specs/README.md) +- [Compilador](studio/docs/specs/compiler/README.md) +- [Linguagem PBS e SDK](studio/docs/specs/compiler-languages/pbs/README.md) +- [Empacotamento de assets](studio/docs/specs/packer/README.md) +- [Configuração do AIE](.ai-engineering/ai-engineering.yaml) + +As especificações de cada projeto são a referência para seus contratos e +comportamentos. O README da raiz orienta a navegação e o trabalho conjunto.