docs: add Prometeu Engineering README
This commit is contained in:
@@ -1,3 +1,3 @@
|
||||
---
|
||||
schemaVersion: 2
|
||||
lastWork: "0001"
|
||||
lastWork: "0002"
|
||||
|
||||
+12
@@ -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"
|
||||
+37
@@ -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."
|
||||
}
|
||||
+12
@@ -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"
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0002",
|
||||
"inputHash" : "a51290e3dff5fb7c0a7d0ff332c35a98d9291d393a3dc7cc3b45c4183318e5c0",
|
||||
"plans" : [ {
|
||||
"id" : "PLN-0001",
|
||||
"revision" : 5,
|
||||
"sha256" : "507e309bdba50d03a4656516b6ce5ee54f71de57e88dba2db0e2daf96a17a87d"
|
||||
} ]
|
||||
}
|
||||
+13
@@ -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.
|
||||
+18
@@ -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
|
||||
---
|
||||
|
||||
+29
@@ -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
|
||||
---
|
||||
|
||||
+31
@@ -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
|
||||
---
|
||||
|
||||
+34
@@ -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
|
||||
---
|
||||
|
||||
+32
@@ -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
|
||||
---
|
||||
|
||||
+66
@@ -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
|
||||
---
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user