diff --git a/.ai-engineering/works/.sequence.yaml b/.ai-engineering/works/.sequence.yaml index 9bab387..6078e59 100644 --- a/.ai-engineering/works/.sequence.yaml +++ b/.ai-engineering/works/.sequence.yaml @@ -1,3 +1,3 @@ --- schemaVersion: 2 -lastWork: "000B" +lastWork: "000D" diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0001.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0001.md new file mode 100644 index 0000000..db516e2 --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0001.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0001" +workId: "WRK-000C" +discussionId: "main" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T10:06:12.127522Z" +respondsTo: null +documentVersion: 2 +--- + +Ticket solicitado explicitamente por Nilton em 2026-11-22 durante a discussão do WRK-001D do Prometeu. Ambiente: macOS, CLI instalada /Users/niltonconstantino/.local/bin/aie; aie --version retornou ai-engineering 0.1.0. Consumidor: /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/project. Comandos aie status --format json e aie next-actions --format json foram iniciados em paralelo pelo agente e permaneceram sem saída em várias consultas durante minutos. Na inspeção final, ps mostrou PID 66921, estado Rs, elapsed 08:43, comando aie status --format json ainda ativo, sem saída na sessão correspondente. next-actions acabou retornando; sua saída refletia guidance UNSPECIFIED do WRK-001D apesar de a escolha EXPLORATORY já ter sido gravada durante a espera, compatível com leitura anterior à mutação, sem confirmar mecanismo de cache. Mutações pontuais terminaram: criação do WRK-001D levou cerca de 0,55 s; discussion add teve exemplos de 0,29 s a 0,69 s; nesta abertura de ticket, work create no projeto AIE levou cerca de 0,15 s. São durações retornadas pelo executor para aquelas chamadas, não benchmark controlado. work context e work validate do Work novo também chegaram a concluir; não há evidência de bloqueio universal das gravações. No projeto AIE, status e next-actions concluíram entre consultas, com estado LEGACY_COMPATIBLE, readable=true, migrationRequired=false. Hipóteses ainda não comprovadas: varredura/validação de histórico e artefatos, operações de filesystem, custo dependente do volume, concorrência ou restrições de ambiente. Próxima investigação proposta: reproduzir com timeout e timestamps, medir primeira saída e conclusão, comparar chamadas sequenciais/concorrentes, e perfilar o processo demorado sem alterar dados canônicos. Esperado: comandos rotineiros interativos com duração mensurada e feedback útil, preservando integridade. Escopo atual é abertura do ticket, não execução de correção. Modo DIRECT/EXPLORATORY não informado para este Work; não foi herdado do Prometeu. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0002.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0002.md new file mode 100644 index 0000000..5bda6db --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0002.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0002" +workId: "WRK-000C" +discussionId: "main" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T10:12:39.669653Z" +respondsTo: null +documentVersion: 2 +--- + +Enquadramento inicial em modo EXPLORATORY, escolhido explicitamente por Nilton nesta conversa. Dor proposta: o custo e a ausência de feedback das consultas obrigatórias interrompem a conversa e tornam um registro simples imprevisível; melhorar apenas a mensagem de espera pode ser insuficiente. Evidência histórica: DSC-0001 relata espera de minutos no Prometeu, sem causa confirmada. Observação desta sessão, sem benchmark controlado: work context concluiu em aproximadamente 0,98 s; work guidance em aproximadamente 1,72 s; status e next-actions iniciados em paralelo ultrapassaram a janela inicial de 10 s sem saída; next-actions depois concluiu; ps observou status com elapsed de 31 s e CPU acumulada de 21,12 s. Esses dados não provam deadlock, efeito de concorrência ou causa raiz. Perguntas de produto para discutir: (1) qual limite de tempo total e de primeira resposta torna consultas e registros aceitáveis? (2) o fluxo de uma alteração pontual precisa sempre de visão global ou pode obter contexto suficiente do Work com garantias explícitas? (3) qual volume real de Works, revisões e evidências deve permanecer responsivo? Perguntas técnicas a investigar: (4) qual fase concentra tempo e CPU: inicialização, descoberta/leitura, interpretação, compatibilidade, integridade ou montagem da saída? (5) como o custo varia com o volume, CLI instalada versus local, ambiente e execução sequencial versus concorrente? (6) consultas e mutações têm gargalos distintos, e qual consistência é esperada se o Work mudar durante uma consulta? (7) qual correção mínima cumpre os limites acordados sem enfraquecer integridade, validação ou autoridade humana? Próximo passo proposto: acordar orçamento de latência e cenário representativo, depois medir com limite de duração e localizar o custo. Nenhuma solução, meta numérica, DEC ou implementação aprovada. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0003.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0003.md new file mode 100644 index 0000000..3915c06 --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0003.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0003" +workId: "WRK-000C" +discussionId: "main" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T10:22:00.400005Z" +respondsTo: null +documentVersion: 2 +--- + +Resposta explícita sobre responsividade nesta conversa: o mínimo possível. O sistema não pode ficar flutuando sem retorno dessa maneira, principalmente para leitura. Solicita sugestões para as perguntas do enquadramento com base na inspeção do código existente. Não define um limite numérico nem aprova solução ou implementação. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0004.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0004.md new file mode 100644 index 0000000..1480955 --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0004.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0004" +workId: "WRK-000C" +discussionId: "main" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T10:23:19.859847Z" +respondsTo: null +documentVersion: 2 +--- + +Inspeção estática do código em 2026-11-22, sem alteração de implementação ou benchmark nesta etapa. Achados verificáveis: WorkService.load (linha 27) chama list e desserializa todos os work.md; folder (linha 32) chama load novamente. EpicService.definitions (linha 33) lista todos os Works e chama folder para cada um, inclusive Works sem EPIC; VerificationService.work (linha 48) repete definitions em cada validação. Há portanto amplificação de leituras globais, com termo cúbico no número de Works no caminho de validação global derivado desses laços, sem que isso determine sozinho o tempo observado. VerificationService.status (linha 299) chama work e actions; actions (linha 310) chama work outra vez. status JSON valida cada Work ao menos duas vezes e depois executa CompatibilityService.inspect, que percorre registros e revisões e em geral lê cada registro para metadata e novamente para desserialização. PlanService.list e DecisionService.list verificam cadeias de revisões; ArtifactService.validate relê payloads para SHA-256 e resolve a pasta do Work por artefato. context valida work e PlanCoordinator.inspect valida novamente. A CLI monta o objeto completo antes de emitir JSON; não há progresso nem prazo próprio desses comandos. Filespace.locked utiliza espera bloqueante de lock nas mutações; o caminho normal dessas consultas não adquire esse lock, logo não há base para atribuir a demora de leitura a ele. Contagem local nesta inspeção: 12 Works, 530 arquivos sob works excluindo runs e .local, 206 arquivos de histórico, aproximadamente 1,75 MB; contagem não caracteriza o consumidor Prometeu nem exclui custo de parsing. Propostas para discussão: primeiro eliminar leituras/validações repetidas sem mudar as garantias; criar contexto de leitura por invocação com mapa de IDs/pastas, documentos e avaliações reutilizados entre serviços; verificar alterações concorrentes com mecanismo explícito, pois memória por comando não é snapshot atômico. Investigar acesso ao Work selecionado sem desserializar demais Works, preservando detecção de IDs duplicados e validando dependências relevantes. Só depois avaliar consultas operacionais leves separadas de auditoria completa, com validação não realizada declarada e sem apresentar validade não aferida. A distinção é mudança contratual a discutir, não autorização para retirar validação atual. Aproveitar next-actions WRK já existente e considerar reduzir a redundância do bootstrap em futura revisão do protocolo. Proposta inicial de metas a validar, não promessa: no cenário local representativo, p95 menor ou igual a 1 s para leitura de Work e menor ou igual a 2 s para visão global; se ultrapassar 300-500 ms, progresso verdadeiro em stderr sem contaminar stdout JSON, com prazo/cancelamento e diagnóstico de fase e volume. Medir início frio/quente, tempo total e primeira saída útil, contagens de leituras/parse/hash, volumes de 10/100/1000 Works com histórias curtas/longas e evidências, CLI instalada/local e execução sequencial/concorrente. Não começar por cache persistente ou paralelização; primeiro remover a amplificação e medir. Mutações devem conservar lock, publicação atômica e integridade, com espera limitada e feedback explícito. Próxima investigação proposta: confirmar correspondência do binário instalado com o fonte e perfilar uma reprodução com duração limitada para atribuir custos, comparando os resultados e o comportamento de detecção de corrupção. Todas as metas e soluções são recomendações; exploração permanece aberta. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0005.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0005.md new file mode 100644 index 0000000..30463e9 --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0005.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0005" +workId: "WRK-000C" +discussionId: "main" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T10:37:39.149693Z" +respondsTo: null +documentVersion: 2 +--- + +Nova alternativa trazida por Nilton nesta conversa, antes de perseguir as otimizações: avaliar uma base de dados real local distribuída junto com o AIE. Pergunta exploratória, sem aprovação de adoção ou migração. Avaliação: SQLite embarcado é candidato forte para o estado operacional local, pois não exige processo servidor e oferece índices, transações e leitura consistente. Referências oficiais consultadas: https://sqlite.org/serverless.html ; https://sqlite.org/whentouse.html ; https://sqlite.org/isolation.html ; https://sqlite.org/atomiccommit.html . Proposta para discussão: comparar arquivos otimizados, SQLite como índice reconstruível e SQLite como fonte canônica; não manter arquivos e banco como autoridades independentes. Se acesso e edição direta dos arquivos sem CLI for requisito essencial, índice preserva esse contrato, mas precisa detectar alterações externas e invalidar estado sem repetir uma auditoria global em cada consulta. Se a CLI puder ser a interface normal, SQLite canônico com Markdown/JSON exportados tende a simplificar consultas e consistência entre registros; exportações seriam derivadas, e importação seria explícita. Transações cobrem dados no banco; evidências mantidas em arquivos exigem protocolo próprio para publicação e recuperação. SQLite em WAL admite leitura concorrente à escrita, mantendo um escritor por vez; não substitui regras de aprovação ou integridade de evidências. A arquitetura e README atuais tratam arquivos legíveis como persistência canônica e execução sem banco; portanto a troca modifica contrato e exige decisão própria quando o humano encerrar a exploração. Banco por si só não elimina chamadas redundantes nem verificação integral de históricos/payloads em cada leitura; é preciso ajustar os caminhos de acesso. Antes de escolher biblioteca ou migrar, comparar protótipos descartáveis com dados representativos e verificar integração/distribuição JVM e GraalVM Native Image, backup, exportação, histórico e recuperação. Recomendação preliminar: avaliar SQLite embarcado como alternativa arquitetural antes de investir em otimização extensa do armazenamento atual; preferência por fonte canônica se a leitura/edição direta dos arquivos puder deixar de ser o caminho operacional. Nenhuma mudança de implementação executada. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0006.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0006.md new file mode 100644 index 0000000..a9913e2 --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0006.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0006" +workId: "WRK-000C" +discussionId: "main" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T10:42:15.904220Z" +respondsTo: null +documentVersion: 2 +--- + +Direção expressa nesta conversa: pergunta se migrar para banco local resolveria os atrasos e afirma que, se sim, considera esse o caminho a seguir. Esclarece que não tem intenção de alterar os arquivos manualmente. Isso remove a edição manual de arquivos como necessidade pessoal declarada e favorece avaliar banco como fonte principal. A preferência pelo caminho foi condicionada à solução dos atrasos; não constitui aprovação de uma DEC concreta, autorização de migração ou pedido explícito para encerrar a exploração. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0007.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0007.md new file mode 100644 index 0000000..1d69128 --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0007.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0007" +workId: "WRK-000C" +discussionId: "main" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T10:42:16.345039Z" +respondsTo: null +documentVersion: 2 +--- + +Síntese após a preferência de Nilton: recomendar SQLite embarcado por projeto como candidato a fonte canônica, com acesso normal pela CLI e exportação Markdown/JSON. A inspeção do fonte sustenta que acesso indexado e reutilização de dados podem remover varreduras e desserializações globais repetidas; transações também podem reduzir a complexidade de consistência entre registros armazenados no banco. Não é possível garantir eliminação da latência sem medir o caminho real: substituir armazenamento preservando chamadas redundantes, auditoria integral por consulta, hashes de payloads e montagem completa antes da saída ainda pode produzir demora. A proposta precisa combinar banco, consultas com escopo adequado, reuso por invocação e feedback/prazo explícitos. Critério para confirmar a direção: protótipo descartável com volume e histórico representativos, comparado à CLI atual, medindo tempo total, primeira saída útil, consultas, início frio e chamadas concorrentes; verificar recuperação e preservação das regras de autoridade. As metas anteriores de 1 s por Work e 2 s global continuam propostas, não SLA aceito nem promessa. Histórico, aprovações e hashes existentes devem ser preservados numa eventual migração explícita, com preview, backup, verificação e recuperação; não alterar Works concluídos para acomodar o novo modelo. Ainda não há DEC, Plan ou migração autorizada. Exploração continua aberta; a preferência registrada pode orientar a próxima investigação. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0008.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0008.md new file mode 100644 index 0000000..a3c2194 --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0008.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0008" +workId: "WRK-000C" +discussionId: "main" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T10:45:08.490904Z" +respondsTo: null +documentVersion: 2 +--- + +Reorientação explicitamente solicitada por Nilton nesta conversa: manter este ticket de latência e abrir outro para a mudança de persistência para uma base consolidada como SQLite; retornar ao problema da demora depois, sob a ótica da nova base. Criado WRK-000D — Adotar SQLite como persistência local do AIE, em modo EXPLORATORY escolhido explicitamente para aquele Work. Sequência acordada: priorizar a discussão e futura entrega da persistência no WRK-000D; retomar a investigação e correção da latência no WRK-000C após a mudança, medindo os comandos na arquitetura então entregue. WRK-000C permanece OPEN, preservando relatos, achados estáticos e critérios; não foi concluído nem arquivado. A adoção de banco não será tomada como evidência de solução da demora. O baseline histórico permanece disponível para a futura comparação. A reorientação não aprova DEC nem autoriza implementação ou migração imediata. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0009.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0009.md new file mode 100644 index 0000000..cb5c2ee --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/discussions/DSC-0009.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0009" +workId: "WRK-000C" +discussionId: "main" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T14:05:45.720030Z" +respondsTo: null +documentVersion: 2 +--- + +Handoff do WRK-000D para responsividade: implementação SQLite/local concluída por etapas; validação integrada ainda em execução nesta sessão. O WRK-000C permanece OPEN e não há alegação de correção da latência. Cenário reproduzível em docs/latency-scenario.md e gerador scripts/latency-fixture.py: comparar o mesmo pacote nativo nos backends sqlite/legacy com 1/10/100 Works e 10 notas por Work; medir work show/context selecionado, next-actions selecionado, list e status em processos novos. Registrar versão + SHA do binário, revisão/build, protocolo/schema, volume, OS/CPU e acesso Git. Ambiente físico desta prova: macOS arm64, GraalVM CE 25.5.5.0+3, JDBC 3.54.1.0/sqlite3 3.54.1. Scripts não fazem instalação, migração real ou benchmark automaticamente. Retomar critérios de espera/feedback e medir separadamente startup, leitura e acesso Git. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/work.md b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/work.md new file mode 100644 index 0000000..a304855 --- /dev/null +++ b/.ai-engineering/works/WRK-000C-investigar-latencia-excessiva-nos-comandos-de-consulta-e-reg/work.md @@ -0,0 +1,71 @@ +--- +schemaVersion: 1 +id: "WRK-000C" +title: "Investigar latência excessiva nos comandos de consulta e registro do AIE" +description: "Ticket solicitado por Nilton durante a discussão do WRK-001D no projeto\ + \ Prometeu: consultas obrigatórias do AIE ficam vários minutos sem saída, tornando\ + \ demorado um registro simples. Investigar e distinguir custo da CLI, tamanho do\ + \ projeto, IO, ambiente e efeito de chamadas concorrentes; causa ainda não confirmada.\ + \ Reorientação solicitada em 2026-11-22: manter este ticket aberto e priorizar a\ + \ mudança de persistência no WRK-000D; após essa entrega, retomar a avaliação e\ + \ o tratamento da latência sob a arquitetura de banco de dados, preservando o baseline\ + \ histórico e sem presumir que SQLite resolve o atraso." +goal: "Identificar e documentar a causa da latência percebida e propor correção verificá\ + vel para manter consultas e registros interativos responsivos." +motivation: "Um simples registro de preferência de janela foi acompanhado de espera\ + \ de minutos em status e next-actions, prejudicando a conversa e a confiança no\ + \ fluxo." +constraints: +- "Este ticket registra uma investigação; não autoriza implementação, migração, commits\ + \ ou alteração dos projetos consumidores." +- "Preservar Works, histórico, aprovações, evidências e alterações preexistentes.\ + \ Não herdar modo de discussão nem aprovações do WRK-001D do Prometeu." +- "Não afirmar deadlock ou causa raiz sem evidência; comparar execução sequencial\ + \ e concorrente, CLI instalada e execução local, e ambiente restrito versus normal\ + \ quando aplicável." +acceptanceCriteria: +- "Reprodução com comandos, versão, ambiente, volume de dados, tempos totais e tempo\ + \ até a primeira saída, usando limites de duração definidos." +- "Causa ou gargalos localizados com evidência, diferenciando consultas status/next-actions/context\ + \ de mutações como discussion add e work guidance." +- "Proposta de correção e critérios mensuráveis de responsividade registrados, sem\ + \ enfraquecer validação, integridade ou autoridade humana." +status: "OPEN" +createdAt: "2026-11-22T10:05:02.624219Z" +updatedAt: "2026-11-22T14:05:45.746386Z" +author: "Codex" +repositories: [] +discussions: +- "DSC-0001" +- "DSC-0002" +- "DSC-0003" +- "DSC-0004" +- "DSC-0005" +- "DSC-0006" +- "DSC-0007" +- "DSC-0008" +- "DSC-0009" +decisions: [] +artifacts: [] +plans: [] +completions: [] +events: [] +archived: false +topics: [] +surveys: [] +dispositions: [] +agentRuns: [] +epic: false +guidance: + mode: "EXPLORATORY" + approvalPolicy: "REQUIRED" + history: + - mode: "EXPLORATORY" + approvalPolicy: "REQUIRED" + by: "Nilton" + reason: "Escolha explícita nesta conversa: investigar a dor e comparar hipóteses\ + \ antes de decidir." + at: "2026-11-22T10:12:24.202784Z" + humanApproved: true + decisionRequests: [] +--- diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0001/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0001/artifact.yaml new file mode 100644 index 0000000..22f83de --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0001/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0001" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0001" +purpose: "Resultado mínimo do mapeamento e dos 45 testes de baseline do TSK-0001" +path: "artifacts/evidence/ART-0001/payload" +sha256: "ca7863dd1128ef219d653c1c988e5632b4e012ebfde76c63704c21e92fe9f9e6" +size: 2502 +author: "Codex" +createdAt: "2026-11-22T12:00:15.272156Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0001/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0001/payload new file mode 100644 index 0000000..2bcbc8c --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0001/payload @@ -0,0 +1,25 @@ +# WRK-000D / PLN-0001 / TSK-0001 — resultado + +Source revision: f5d5db73c22055988d53cd125d9246f51575410b +Deliverable: docs/sqlite-migration-design.md +Deliverable SHA-256: f492cfa78fdb9132afafb7e58b3de05843062bea971635bf04909d7e259c2cca + +Inspeção dos modelos/serviços e formatos atuais concluída. O documento mapeia identidades, relações, defaults históricos, aprovações, recibos e cinco classes de hashes para grupos lógicos SQLite; identifica os limites transacionais e o ciclo futuro de anexos temporários. Corpus de compatibilidade, workflows e importação definido antes da conversão; casos futuros de falha, retry e limpeza são identificados como ainda não implementados. + +Validação executada nesta sessão: +`./gradlew test --tests net.intrepid.aiengineering.CompatibilityTest --tests net.intrepid.aiengineering.WorkGuidanceTest --tests net.intrepid.aiengineering.PlanConsolidationSafetyTest --tests net.intrepid.aiengineering.EpicSafetyTest --tests net.intrepid.aiengineering.RefinementSafetyTest --tests net.intrepid.aiengineering.legacyimport.DiscussionImportRecoveryTest --console=plain` + +Resultado observado: BUILD SUCCESSFUL em 1m40s; 45 testes, zero falhas/erros/skips em seis classes. Resultados individuais: +- net.intrepid.aiengineering.CompatibilityTest: 9 testes, 0 falhas, 0 erros, 0 skips. +- net.intrepid.aiengineering.EpicSafetyTest: 9 testes, 0 falhas, 0 erros, 0 skips. +- net.intrepid.aiengineering.PlanConsolidationSafetyTest: 9 testes, 0 falhas, 0 erros, 0 skips. +- net.intrepid.aiengineering.RefinementSafetyTest: 9 testes, 0 falhas, 0 erros, 0 skips. +- net.intrepid.aiengineering.WorkGuidanceTest: 8 testes, 0 falhas, 0 erros, 0 skips. +- net.intrepid.aiengineering.legacyimport.DiscussionImportRecoveryTest: 1 testes, 0 falhas, 0 erros, 0 skips. + +Âncoras congeladas conferidas: 9 arquivos; scopeHash 72d5803add0b8714d7dc4bf7e63ad55cc3259df910aa8b03790657eac4c2bd02; draftHash 545dc8e36da222fdeaf9458f77880bf2d1842738b82bac5296cddf62452a7e01; payloadHash 98545564d0747210b91b933bf8554c4b7e36ba878e6662cb48156b08ff74e1ee. +git diff --check concluiu com sucesso. + +Limites preservados: nenhuma instalação, substituição de binário/biblioteca/atalho, migração do workspace canônico ou de consumidores, descarte de evidências legadas ou alteração dos recursos congelados. Esta etapa caracteriza o backend atual; não comprova implementação SQLite nem solução da latência. + +Próximo step: TSK-0002 — prova JVM e Native Image em dados descartáveis. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0002/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0002/artifact.yaml new file mode 100644 index 0000000..272df32 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0002/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0002" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0002" +purpose: "Resultado mínimo da prova SQLite JVM/Native Image TSK-0002 e EXP-0001" +path: "artifacts/evidence/ART-0002/payload" +sha256: "6eda6a977ee223e375e98e2d91922a63928ed69e3122c2dc43d4d6995ba998fc" +size: 1961 +author: "Codex" +createdAt: "2026-11-22T12:16:29.197218Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0002/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0002/payload new file mode 100644 index 0000000..585f839 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0002/payload @@ -0,0 +1,20 @@ +# TSK-0002 / EXP-0001 — resultado observado + +Driver selecionado: org.xerial:sqlite-jdbc:3.54.1.0, motor SQLite 3.54.1. +Plataforma verificada: macOS arm64; GraalVM Community 25.0.5.0.3+1 (25.5.5.0+3-graalce). + +Mudanças: dependência fixada; source set src/sqliteProbe separado do CLI; tarefas sqliteProbe/nativeSqliteProbeCompile; biblioteca JNI exportada ao lado do executável; scripts/sqlite-probe.sh usa exclusivamente diretório descartável. + +Observações desta sessão: +- ./gradlew sqliteProbeClasses: BUILD SUCCESSFUL. +- ./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/wrk000d/proof.db: criou a base e verificou UTF-8 e rollback. +- Nova invocação JVM: reabriu a mesma base, com UTF-8 e rollback preservados. +- Primeira tentativa nativa selecionou o JDK comum pelo ambiente; corrigido javaLauncher explícito GraalVM Java 25 antes da repetição. Falha de setup, sem refutar a hipótese de persistência. +- nativeSqliteProbeCompile com o GraalVM existente: BUILD SUCCESSFUL, build de imagem em 46,7 s; executável e libsqlitejdbc.dylib produzidos em build/native/nativeSqliteProbeCompile. +- bash scripts/sqlite-probe.sh : passou create/reopen em processos nativos independentes, UTF-8 e rollback com diretório de extração sem escrita. Cópia isolada do executável sem biblioteca falhou conforme esperado. +- Há avisos de depreciação/native-access do toolchain/driver; não impediram o resultado. A prova confirma macOS arm64, sem afirmar validação de outras plataformas. +- git diff --check passou. + +Interpretação: hipótese confirmada na plataforma alvo; integração JVM/Native Image e distribuição conjunta da biblioteca são viáveis. Próxima ação: infraestrutura transacional SQLite do TSK-0003. + +Nenhuma instalação, substituição de binários/bibliotecas/atalhos ou migração de projetos reais foi feita. A prova não implementa persistência do domínio nem comprova latência fim a fim. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0003/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0003/artifact.yaml new file mode 100644 index 0000000..512d110 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0003/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0003" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0003" +purpose: "Resultado mínimo da infraestrutura SQLite, 13 testes e prova nativa do TSK-0003" +path: "artifacts/evidence/ART-0003/payload" +sha256: "bbdc1fa4341e4fe1015c6e10ad33f19eabd1ea5aaef1a7853e8de33bc8ca92de" +size: 2100 +author: "Codex" +createdAt: "2026-11-22T12:25:56.560824Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0003/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0003/payload new file mode 100644 index 0000000..dc6f726 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0003/payload @@ -0,0 +1,14 @@ +# TSK-0003 — infraestrutura transacional SQLite + +Implementado SqliteDatabase e sqlite/schema-v1.sql: inicialização explícita, marca de aplicação/schema, chaves de identidade/propriedade/revisão/referência e contador local; foreign keys por conexão, WAL/FULL, BEGIN IMMEDIATE para escrita, leitura readonly e consistente, busy timeout limitado. Transações aninhadas compartilham conexão e falha interna impede commit parcial mesmo quando capturada. Abertura não cria base ausente; versões futuras, symlinks e sidecars indevidos são recusados. Campos/tabelas específicos do domínio serão integrados nas TSKs seguintes; CLI ainda não usa SQLite para Works. + +Validação executada nesta sessão: +- ./gradlew test --tests net.intrepid.aiengineering.SqliteDatabaseTest --tests net.intrepid.aiengineering.ArchitectureTest --console=plain: BUILD SUCCESSFUL; 12 testes SQLite e 1 teste de arquitetura, zero falhas/erros/skips. +- Casos observados: rollback em falha de FK; publicação conjunta com referências diferidas; falha aninhada capturada não comita; leitura readonly; snapshot estável enquanto outro escritor comita; lock com espera limitada a 75 ms e diagnóstico; schema futuro; nomes de diretório com espaço/?/#/UTF-8; recusa de symlinks e sidecar órfão. +- Prova Native Image recompilada com infraestrutura e recurso de schema: BUILD SUCCESSFUL. scripts/sqlite-probe.sh passou criação e reabertura do schema em processos separados, além de UTF-8, rollback e biblioteca externa, com extração desabilitada. Ausência da biblioteca falha conforme esperado. +- Uma ambiguidade de inferência de tipos no código do teste foi corrigida antes da execução bem-sucedida. +- git diff --check passou. + +Arquivos principais: SqliteDatabase.java, sqlite/schema-v1.sql, SqliteDatabaseTest.java, NativeHints.java, build.gradle.kts, src/sqliteProbe e docs/sqlite-migration-design.md. + +Nenhuma instalação, ativação de backend no workspace real, migração de consumidores ou descarte de evidências legadas foi feito. Próxima ação: TSK-0004, persistir Works e investigação. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0004/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0004/artifact.yaml new file mode 100644 index 0000000..a778efc --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0004/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0004" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0004" +purpose: "Resultado mínimo dos testes e prova nativa de Works/investigação SQLite" +path: "artifacts/evidence/ART-0004/payload" +sha256: "3816032ba0550cd18c16d9a05aeecd6f834d4847c91e1af79a60476af96ed024" +size: 2108 +author: "Codex" +createdAt: "2026-11-22T12:43:35.892224Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0004/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0004/payload new file mode 100644 index 0000000..40f5ec3 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0004/payload @@ -0,0 +1,11 @@ +# TSK-0004 — Works e investigação em SQLite + +Implementados: configuração explícita storage=sqlite em ProjectConfig e initializeSqlite para projetos descartáveis; WorkService com busca direta, alocação transacional e localização estável; SqliteRecords com colunas escalares tipadas, listas em linhas ordenadas e estruturas operacionais por item, sem arquivo/Work inteiro serializado; RecordStorage preserva codecs e cadeias de revisão. Discussões, tópicos, surveys/respostas e disposições usam a mesma transação das referências do Work. Backend legado preservado; init público ainda não mudou. + +Validação desta sessão: +- ./gradlew test --tests net.intrepid.aiengineering.SqliteInvestigationTest --tests net.intrepid.aiengineering.SqliteDatabaseTest --tests net.intrepid.aiengineering.WorkGuidanceTest --tests net.intrepid.aiengineering.RefinementSafetyTest --tests net.intrepid.aiengineering.CompatibilityTest --tests net.intrepid.aiengineering.ArchitectureTest --console=plain: BUILD SUCCESSFUL; 45 testes, zero falhas/erros/skips, incluindo 6 novos cenários de investigação SQLite. +- Outro processo JVM reconstituiu contexto com discussão UTF-8 e survey pendente. Testados rollback conjunto de filho e referência, encadeamento de revisões de tópico/survey, respostas supersedidas, escolha/pedido de DEC explícitos, duas criações locais concorrentes, renomeação sem mudar localização e leitura selecionada sem desserializar Work alheio inválido. +- nativeSqliteProbeCompile com GraalVM 25: BUILD SUCCESSFUL após incluir metadados AOT com dependência Gradle explícita. scripts/sqlite-probe.sh passou create/reopen de Work e discussão tipados em processos nativos separados, além da infraestrutura e biblioteca externa já verificadas. +- A execução nativa usa apenas diretórios descartáveis; nenhum instalador foi executado. + +Próxima etapa: TSK-0005, decisões/planos/experimentos. A instalação ativa, o backend do workspace canônico e os consumidores permanecem intactos. Persistência de domínio completo e migração ainda não são declaradas prontas. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0005/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0005/artifact.yaml new file mode 100644 index 0000000..2adb789 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0005/artifact.yaml @@ -0,0 +1,12 @@ +--- +schemaVersion: 1 +id: "ART-0005" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0005" +purpose: "Resultado mínimo da persistência e checks de decisões/planos/experimentos\ + \ SQLite" +path: "artifacts/evidence/ART-0005/payload" +sha256: "c339f321e05e9225e03895e515a925967dad9637ffb8754af4c4c4440c3b039f" +size: 1614 +author: "Codex" +createdAt: "2026-11-22T12:54:08.349836Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0005/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0005/payload new file mode 100644 index 0000000..7eff82e --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0005/payload @@ -0,0 +1,10 @@ +# TSK-0005 — decisões, planos e experimentos SQLite + +DecisionService e PlanService usam RecordStorage para registros/revisões. Aprovação/supersessão e promoção permitida na criação do Plan compartilham transação com o Plan e referências. Backend SQL não usa compensações por gravação de Markdown; backend legado preserva o fluxo existente. Metadados de ART foram integrados como suporte aos checks; bytes continuam externos e a limpeza será implementada no TSK-0008. + +Verificação executada: +- Rodada selecionada de SqliteImplementationTest, SqliteInvestigationTest, PlanExperimentsTest, PlanDecisionPromotionTest, OperationalSafetyTest e ArchitectureTest: 34 testes, um teste novo falhou apenas na expectativa textual (buscava experiment, mas o check existente informa EXP-0001). +- Expectativa corrigida para identificar o EXP bloqueante. ./gradlew test --tests net.intrepid.aiengineering.SqliteImplementationTest --console=plain: BUILD SUCCESSFUL; os 5 testes passaram, zero falhas/erros/skips. Os demais testes da rodada ampla já haviam passado; 34 cenários distintos cobertos ao final. +- Exercitados: exigência de aprovação humana; conteúdo aceito imutável; revisões/UTF-8; dependências; experimentos abertos e retry com reconsideração; evidência real; supersessão que bloqueia execução até reconsiderar o Plan; rollback de promoção+Plan+referência e retry sem duplicar ou fabricar aprovação. + +Sem instalação, ativação de novo backend no workspace real, migração de consumidores ou descarte do legado. Próximo: TSK-0006 — RUNs e coordenação de EPICs/Plans. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0006/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0006/artifact.yaml new file mode 100644 index 0000000..f6b10cf --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0006/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0006" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0006" +purpose: "Resultados focados de RUNs, EPICs e coordenação em SQLite" +path: "artifacts/evidence/ART-0006/payload" +sha256: "0a76ae66f292c31a1e96381d23e052b112f4342bb2d411b18bca40684c151339" +size: 520 +author: "Codex" +createdAt: "2026-11-22T13:02:06.489484Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0006/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0006/payload new file mode 100644 index 0000000..4d3665d --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0006/payload @@ -0,0 +1,3 @@ +TSK-0006: RUNs e EPICs em SQLite + +30 cenários distintos passaram em duas rodadas focadas: SqliteCoordinationTest (5), EpicWorkflowTest (6), EpicSafetyTest (9), RefinementSafetyTest (9), ArchitectureTest (1). Comandos: ./gradlew test --tests ... --console=plain. RUNs idempotentes; trigger SQL confirma rollback integral com diagnóstico posterior. EPIC RESULTS/DECOMPOSITION, autoridade, histórico, propagação/reabertura e consolidação por Plans preservados. Sem instalação nativa ou migração deste workspace. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0007/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0007/artifact.yaml new file mode 100644 index 0000000..656498b --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0007/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0007" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0007" +purpose: "Resultados de gates cumulativos e vinculados ao estado" +path: "artifacts/evidence/ART-0007/payload" +sha256: "2e024d13c3cf349df3ef3e6fd335eb79d1e1da94ae21671cfee632b0f6f950c2" +size: 563 +author: "Codex" +createdAt: "2026-11-22T13:08:06.641638Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0007/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0007/payload new file mode 100644 index 0000000..30f7612 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0007/payload @@ -0,0 +1,3 @@ +TSK-0007: gates do projeto + Work + +./gradlew test --tests *SqliteQualityGatesTest --tests *SqliteCoordinationTest --tests *SqliteDatabaseTest --tests *ArchitectureTest --console=plain: BUILD SUCCESSFUL, 23 cenários. Verificados gates cumulativos, bloqueio por pendência/falha, fingerprint de fontes/escopo/DEC, recusa de resultado obsoleto, evidência obrigatória íntegra, observação explícita, conclusão automática condicionada e snapshot histórico com detecção de alteração. Nenhum executor de repositório, instalação ativa ou migração real. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0008/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0008/artifact.yaml new file mode 100644 index 0000000..35af186 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0008/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0008" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0008" +purpose: "Prova do ciclo recuperável dos anexos temporários" +path: "artifacts/evidence/ART-0008/payload" +sha256: "9bad92fc4bc4804167f2637699cd3dee1c33f62fec6f0a91707aff962b41f143" +size: 618 +author: "Codex" +createdAt: "2026-11-22T13:16:11.708988Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0008/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0008/payload new file mode 100644 index 0000000..ae2b185 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0008/payload @@ -0,0 +1,3 @@ +TSK-0008 / EXP-0002: ciclo de anexos temporários + +32 cenários distintos passaram nas rodadas focadas: SqliteArtifactLifecycleTest (9), SqliteQualityGatesTest (5), SqliteCoordinationTest (5), SqliteDatabaseTest (12), ArchitectureTest (1). BUILD SUCCESSFUL. Retenção durante checks, descarte somente após commit, rollback sem apagar entradas, recuperação após commit/unlink e publicação órfã, retry sem duplicação, recusa de reuso de evidência aposentada, outputs externos intactos e originais legados preservados. Recibos internos tipados, sem payload JSON. Instalação e workspace reais não migrados. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0009/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0009/artifact.yaml new file mode 100644 index 0000000..faa5aa1 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0009/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0009" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0009" +purpose: "Resultados de consultas, snapshots e diagnóstico SQLite" +path: "artifacts/evidence/ART-0009/payload" +sha256: "5e76bdbb24b819727c7aa55710ad133db3aef54abee03e23963142cc9621d938" +size: 531 +author: "Codex" +createdAt: "2026-11-22T13:23:21.359613Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0009/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0009/payload new file mode 100644 index 0000000..18d5850 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0009/payload @@ -0,0 +1,3 @@ +TSK-0009: consultas SQLite + +./gradlew test --tests *SqliteQueriesTest --tests *SqliteInvestigationTest --tests *SqliteQualityGatesTest --tests *ArchitectureTest --console=plain: 15 testes passaram. Contexto em outro JVM, snapshot com escrita concorrente, contexto selecionado apesar de outro Work inválido, leitura de histórico e recusa de schema não suportado, integridade global e leitura sem descarte. Rodada anterior de CompatibilityTest/coordenação/anexos/arquitetura também passou. Sem migração ou instalação real. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0010/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0010/artifact.yaml new file mode 100644 index 0000000..891acd7 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0010/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0010" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0010" +purpose: "Prova de migração e recuperação em fixtures" +path: "artifacts/evidence/ART-0010/payload" +sha256: "c962195302f83a24932413c4e4991284c29a29d6b374268f15ed95e96bf0673d" +size: 749 +author: "Codex" +createdAt: "2026-11-22T13:38:16.617539Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0010/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0010/payload new file mode 100644 index 0000000..66a6e1b --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0010/payload @@ -0,0 +1,3 @@ +TSK-0010 / EXP-0003: migração explícita e recuperável + +Rodada final: ./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest --tests *SqliteImplementationTest --tests *SqliteInvestigationTest --tests *ArchitectureTest --console=plain: 34 testes passaram (13 de migração). Cinco fronteiras interrompidas retomaram; corpus congelado manteve hash 72d5803add0b8714d7dc4bf7e63ad55cc3259df910aa8b03790657eac4c2bd02, aprovações e bytes. Plans, surveys, EPICs, RUNs e IDs reservados preservados. Correção derivada da prova: preservar lista nula versus vazia. Staging limpo ao concluir, originais mantidos, mudanças legadas exigem nova prévia, rollback após nova escrita SQLite recusado. Nenhuma instalação ou migração real. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0011/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0011/artifact.yaml new file mode 100644 index 0000000..870e07b --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0011/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0011" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0011" +purpose: "Resultados de init local e compatibilidade" +path: "artifacts/evidence/ART-0011/payload" +sha256: "f2bd87e9d928ce49f8bcaa3fd5ae55e49c6f8781c61d76890ac30b169be53244" +size: 627 +author: "Codex" +createdAt: "2026-11-22T13:45:50.903749Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0011/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0011/payload new file mode 100644 index 0000000..31557dd --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0011/payload @@ -0,0 +1,3 @@ +TSK-0011: init local e compatibilidade + +Rodada consolidada SqliteInitTest, StorageMigrationTest, CompatibilityTest, ProtocolIntegrationTest e ArchitectureTest passou. Rodada separada de SqliteInitTest + ProcessContinuityTest + ArchitectureTest também passou (12 cenários, seis em processos JVM independentes, sem Git no PATH). Init prepara SQLite antes da publicação, preserva regras e ignora estado por padrão; --version-state mantém política própria. Legacy explícito, onboard não converte, contrato incompatível recusa escrita. Fixtures antigas agora declaram storage legacy. Sem instalação ou migração real. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0012/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0012/artifact.yaml new file mode 100644 index 0000000..a5cf009 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0012/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0012" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0012" +purpose: "Resultados do pacote preparado e instalador simulado" +path: "artifacts/evidence/ART-0012/payload" +sha256: "906a3047bb0430f307ada5420c02b6c3698a790587886c9f3d47365adfabca3c" +size: 693 +author: "Codex" +createdAt: "2026-11-22T13:51:38.945560Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0012/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0012/payload new file mode 100644 index 0000000..4a0b1ba --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0012/payload @@ -0,0 +1,3 @@ +TSK-0012: pacote nativo preparado sem instalação + +./gradlew [GraalVM 25 fixado] nativePackage: BUILD SUCCESSFUL; AIE nativo e bibliotecas + sqlite3 3.54.1 compilado de fonte oficial com SHA3 fixado. python3 scripts/verify-native-package.py build/native/package passou: hashes/versões, init descartável pelo AIE nativo e leitura da base com sqlite3 do pacote. python3 scripts/test-install-native.py: 17 testes passaram com ferramentas simuladas; diretórios/atalhos, biblioteca ausente/corrompida, atualização e falha parcial restauram instalação simulada. Plataforma física macOS arm64; Linux somente fixtures. Nenhum instalador real executado, nenhuma ativação ou migração real. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0013/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0013/artifact.yaml new file mode 100644 index 0000000..70803e7 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0013/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0013" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0013" +purpose: "Verificação da documentação e recursos distribuídos" +path: "artifacts/evidence/ART-0013/payload" +sha256: "ff34868d7634deaf60467b56ac1ee73d7bafc70a7a3a9203e4fe5a72a182107c" +size: 554 +author: "Codex" +createdAt: "2026-11-22T13:58:03.406806Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0013/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0013/payload new file mode 100644 index 0000000..d74d53c --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0013/payload @@ -0,0 +1,3 @@ +TSK-0013: documentação do framework local + +README, arquitetura, protocolo/compatibilidade, recursos distribuídos e guias de domínio atualizados. Procedimento público docs/storage-migration.md cobre prévia, aplicação, recuperação e rollback. Referência de arquivos mantida como legado explícito. Links locais: OK. ./gradlew test --tests *SqliteInitTest --tests *CompatibilityTest --tests *WorkGuidanceTest --console=plain: BUILD SUCCESSFUL. Dois ciclos/OODA/autoridade preservados, retenção mínima e fronteiras de instalação explícitas. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0014/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0014/artifact.yaml new file mode 100644 index 0000000..a729704 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0014/artifact.yaml @@ -0,0 +1,11 @@ +--- +schemaVersion: 1 +id: "ART-0014" +workId: "WRK-000D" +origin: "PLN-0001/TSK-0014" +purpose: "Resultados finais dos gates, pacote e smoke nativo" +path: "artifacts/evidence/ART-0014/payload" +sha256: "808f3fac540afa13534fb625b77b92b076f68aad4e622f030221baaa9cd8236f" +size: 1127 +author: "Codex" +createdAt: "2026-11-22T14:23:07.098606Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0014/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0014/payload new file mode 100644 index 0000000..5fb3b9a --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0014/payload @@ -0,0 +1,7 @@ +TSK-0014: regressão integrada e entrega + +./gradlew check: 230 testes JVM, zero falhas/erros/skips; fixture Jenkins com 11 cenários passou. Ajuste final do importador: 17 testes focados de importação/recuperação/arquitetura passaram. Instalador: 17 fixtures finais passaram com ferramentas simuladas, incluindo recuperação de ativação parcial. + +GraalVM gerou pacote e ZIP/TAR; componentes, hashes, versões e permissão executável verificados. Native smoke completo passou em macOS arm64, incluindo backend legado, guidance/OODA, SQLite/gates, descarte e migração histórica; diagnóstico de processos exigiu repetição autorizada fora do sandbox. Pacote isolado abriu SQLite sem extração temporária; ausência da biblioteca JDBC recusada. Linux/Windows físicos não executados nesta máquina. + +Gerador de latência verificado com 1 Work/1 nota, sem benchmark; cenário em docs/latency-scenario.md encaminhado ao WRK-000C, que permanece aberto. Nenhuma instalação nativa real ou migração de workspace/consumidores. Workspace canônico segue contrato 3 sem aie.db. DEC respeitada, EXP-0001/2/3 confirmados. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0015/artifact.yaml b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0015/artifact.yaml new file mode 100644 index 0000000..6f33e97 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0015/artifact.yaml @@ -0,0 +1,12 @@ +--- +schemaVersion: 1 +id: "ART-0015" +workId: "WRK-000D" +origin: "ai-engineering:plans:d26d0825f0d98177995dcde3abadae702077096385b6692472e7f3d34ef4c17a" +purpose: "Deterministic aggregation of completed Plans and reviewed cancellations;\ + \ not semantic verification of prose criteria" +path: "artifacts/evidence/ART-0015/payload" +sha256: "d26d0825f0d98177995dcde3abadae702077096385b6692472e7f3d34ef4c17a" +size: 284 +author: "system:plans" +createdAt: "2026-11-22T14:23:22.737899Z" diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0015/payload b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0015/payload new file mode 100644 index 0000000..9e0474f --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/artifacts/evidence/ART-0015/payload @@ -0,0 +1,10 @@ +{ + "schemaVersion" : 1, + "workId" : "WRK-000D", + "inputHash" : "ca97695e9cd8cd557b48e25b8cbedb372ae7ef892fa164e59042c60892c25152", + "plans" : [ { + "id" : "PLN-0001", + "revision" : 51, + "sha256" : "35c51ecbaff2dc840635c4417a436323759783bf74ecbf552a0831cb09bdd222" + } ] +} diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/decisions/.history/DEC-0001/r0001.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/decisions/.history/DEC-0001/r0001.md new file mode 100644 index 0000000..ea68002 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/decisions/.history/DEC-0001/r0001.md @@ -0,0 +1,238 @@ +--- +schemaVersion: 1 +id: "DEC-0001" +workId: "WRK-000D" +title: "Adotar memória de engenharia local em SQLite com gates preservados e retenç\ + ão mínima" +context: "O humano definiu AIE como memória local de engenharia por Work, com investigaç\ + ão, implementação, OODA e entrega por gates de qualidade. Arquivos atuais geram\ + \ acessos repetidos e retenção excessiva. Compartilhamento distribuído e integraç\ + ão Git foram retirados deste recorte. Projetos em andamento impedem instalar ou\ + \ substituir agora a distribuição nativa em uso." +approach: "Adotar SQLite por projeto como fonte principal; preservar os dois ciclos,\ + \ autoridade e checks existentes, com anexos temporários e resultados mínimos persistidos.\ + \ Migrar explicitamente com verificação e recuperação. Preparar pacote e script\ + \ com AIE nativo e SQLite juntos, validar com fixtures e artefatos descartáveis\ + \ e adiar instalação real até instrução humana específica. Manter .ai-engineering\ + \ fora de Git por padrão e deixar importação/exportação e sincronização para etapa\ + \ posterior." +alternatives: [] +rationale: "A decisão concentra o AIE em continuidade e qualidade do trabalho, simplifica\ + \ persistência e retenção e trata consistência entre registros com transações. Preserva\ + \ histórico e regras humanas, limita mudanças nos consumidores e separa a adoçã\ + o do armazenamento da futura comprovação de responsividade no WRK-000C." +risks: [] +acceptanceCriteria: [] +approvalStatus: "DRAFT" +author: "Codex" +createdAt: "2026-11-22T11:44:02.759315Z" +evidence: [] +revision: 1 +previousHash: null +updatedAt: "2026-11-22T11:44:02.759315Z" +updatedBy: "Codex" +changeReason: "Draft created" +approvals: [] +revises: null +supersededBy: null +documentVersion: 2 +--- + +# Memória de engenharia local com SQLite + +## Contexto e objetivo + +O AIE deve preservar conhecimento de engenharia por Work: contexto, discussão, +refinamento, decisões e suas justificativas, planos e resultados. A entrega depende +dos gates de qualidade estipulados. Auditoria e retenção de arquivos devem servir +a esse funcionamento com o mínimo necessário. + +O armazenamento atual combina documentos e referências em arquivos, validações +repetidas e publicação atômica por arquivo. O WRK-000C registra latência percebida +em consultas e registros. Este Work trata a mudança de persistência; a avaliação +da latência será retomada separadamente após a entrega. + +O uso desta versão é local. A discussão de colaboração demonstrou que contador +local e snapshot binário não resolvem criação independente e reconciliação entre +máquinas. Por escolha humana, sincronização e compartilhamento foram retirados +deste recorte, em favor de um framework local fora de Git por padrão. + +## Decisão proposta + +### 1. Fonte principal e acesso + +- Manter uma base SQLite por projeto em `.ai-engineering/aie.db`. +- Persistir registros tipados, textos úteis e relações: Works, discussões, tópicos, + surveys e respostas, DECs e aprovações, Plans e passos, experimentos, coordenação + de EPICs, registros operacionais de execução e resultados dos gates. +- Usar tabelas, índices e restrições para as consultas e relações necessárias. + Consultar um Work não deve carregar todos os Works por conveniência de acesso. +- Textos e estruturas operacionais podem ser armazenados como dados de domínio; + conteúdo de arquivos não será convertido em BLOB, base64 ou TEXT equivalente. +- A CLI é a interface normal de leitura e alteração. Preservar comandos e formatos + públicos quando compatíveis; mudanças necessárias terão documentação explícita. +- Manter a descoberta do projeto, configuração e instruções de entrada em arquivos + pequenos quando necessários ao bootstrap. Eles não constituem uma segunda cópia + autoritativa da memória dos Works. + +### 2. Ciclos, qualidade e autoridade + +Preservar os dois ciclos existentes: investigação/discussão e implementação, +conectados por DEC e Plan. OODA continua adaptativo: observar resultados, orientar +a investigação, decidir e agir; reconsiderar hipóteses e replanejar quando houver +novas observações. Não criar quatro etapas burocráticas por ação. + +Gates obrigatórios vêm do projeto e podem ser complementados por Work. Preservar +os checks existentes e os anexos exigidos durante a avaliação. Gate obrigatório +pendente, falho ou não executado impede a entrega. Registrar o resultado realmente +observado e o estado avaliado; alterações relevantes exigem reavaliar os gates +afetados. Aprovação humana continua distinta de sucesso técnico. + +O registro mínimo de um gate identifica a verificação, a execução ou avaliação, +o estado/revisão relevante, o momento e o resultado com resumo curto. O registro +de execução de agente mantém o necessário para continuidade, idempotência e +diagnóstico. Não há obrigação de guardar transporte bruto ou logs completos. + +Esta mudança não introduz um executor autônomo de comandos do repositório. A +execução externa e as responsabilidades de agentes/humanos seguem o contrato +aplicável; a persistência registra resultados e aplica os checks determinísticos. + +### 3. Anexos, temporários e entregas + +- Anexos de comprovação ficam no filesystem e podem continuar obrigatórios. +- Antes de descartar um anexo, concluir todos os checks que dele dependem e + persistir o resultado mínimo correspondente no banco. +- Ao terminar uma execução, limpar os temporários elegíveis automaticamente. + Arquivos ainda necessários a checks pendentes permanecem até esse uso terminar. +- Distinguir anexo temporário validado e legitimamente descartado de arquivo + perdido antes da avaliação. A consulta histórica usa o resultado persistido; + avaliações atuais continuam exigindo suas entradas. +- Em interrupções, não marcar checks como concluídos. A recuperação identifica + resíduos e respeita referências de operações ainda pendentes. +- Código alterado permanece no repositório. Documentos, imagens e outros outputs + solicitados são entregues no destino apropriado e preservados como entregas. + O AIE não exige uma cópia permanente adicional apenas por auditoria. +- Recibos internos necessários ao protocolo podem ter representação estruturada + no banco, preservando a proveniência histórica na migração. + +### 4. Transações e concorrência local + +Uma operação coerente de alteração usa transação SQLite, inclusive a atualização +de registros e referências relacionados. Habilitar integridade referencial em +cada conexão e tratar concorrência entre processos do mesmo projeto. + +Manter transações curtas e espera de escrita limitada, com diagnóstico útil em +caso de contenção. Montar leituras relacionadas em uma visão consistente. +Escolher o modo de journal e os parâmetros de durabilidade com verificação na +plataforma alvo. Arquivos externos não integram a transação SQLite: sua publicação, +referência e remoção precisam de recuperação explícita quando houver interrupção. + +### 5. Migração e compatibilidade + +A migração do legado é uma operação pública explícita, com prévia, cópia de +segurança própria da migração e recuperação. Não converter projetos consumidores +automaticamente ao instalar, atualizar ou fazer uma consulta. + +Preparar uma base separada, importar os registros tipados em transação e comparar +IDs, conteúdo, relações, aprovações, revisões e proveniência com o legado. Preservar +os hashes históricos e suas representações de origem quando necessários à leitura +e verificação de entregas antigas, sem fabricar novas aprovações ou despejar os +arquivos inteiros no banco. Trocar a fonte principal somente após validação. + +Repetir uma tentativa não deve duplicar registros. Interrupções e falhas deixam a +fonte anterior recuperável; o comando informa o estado e a próxima ação. Registros +legados e originais de segurança não serão apagados retroativamente nesta mudança +sem disposição explícita. + +Versionar o esquema da base e declarar o novo armazenamento no contrato público. +Formatos suportados, diagnóstico de compatibilidade e recusa de combinações +incompatíveis precisam ser explícitos. O bootstrap deve impedir que uma base nova +seja confundida com um projeto vazio ou alterada por uma CLI incompatível. + +### 6. Instalação conjunta preparada, ativação adiada + +Evoluir `scripts/install-native.sh` e seu empacotamento para distribuir o AIE +nativo, a biblioteca SQLite do driver e o executável `sqlite3` juntos em um +diretório configurável do usuário, com atalhos em `~/.local/bin`. Bancos de projeto +permanecem em `.ai-engineering/`, separados dos binários. + +Usar a biblioteca/driver no processo AIE. O `sqlite3` do pacote serve à inspeção +e ao diagnóstico. Avaliar Xerial SQLite JDBC em prova JVM e Native Image; +fixar versão e plataforma compatíveis antes de consolidar a dependência. + +Uma disposição recomendada para o pacote é `~/.local/lib/ai-engineering/`, com +atalhos `aie` e `ai-engineering` em `~/.local/bin`. O instalador deve verificar o +pacote completo antes de ativar uma atualização e preservar a instalação anterior +em falhas. + +**Restrição humana vigente:** não executar instalação nativa, substituir atalhos, +binários ou bibliotecas da instalação em uso, nem migrar projetos consumidores. +Há projetos em andamento. Este Work pode preparar o script e o pacote e verificar +seu comportamento com fixtures e artefatos de build descartáveis após aprovação; +a instalação real e a ativação exigem uma instrução humana posterior específica. + +### 7. Git e recortes futuros + +O `init` deixa `.ai-engineering/` fora de Git por padrão e o framework funciona +sem Git. Preservar regras existentes e tornar explícito o tratamento de projetos +já versionados; não remover arquivos rastreados nem reescrever histórico Git +automaticamente. Versionar o estado fica a critério do desenvolvedor. + +Ficam fora deste recorte: integração Git LFS, sincronização entre máquinas ou +branches, reconciliação distribuída, importação/exportação de Works ou DECs e +backup como funcionalidade. A cópia de segurança da migração é uma medida local +da conversão. O compartilhamento futuro de DECs tem interesse de produto, sem +reintroduzir colaboração distribuída nesta entrega. + +## Condições de sucesso + +1. Criar e retomar um Work em processos distintos usando SQLite local preserva + contexto, estado e autoridade nos dois ciclos e em suas transições. +2. Gates do projeto e adicionais do Work bloqueiam a entrega quando necessário; + anexos continuam disponíveis durante os checks e seu descarte legítimo não + invalida resultados históricos nem encobre falta de entrada antes da avaliação. +3. Migração em fixtures representativas preserva conteúdo, IDs, relações, + aprovações e proveniência; falhas, rollback e repetição não perdem nem duplicam + a memória de engenharia. +4. Rollback e concorrência local não publicam alterações relacionadas parcialmente + nem produzem espera ilimitada sem diagnóstico. +5. O projeto funciona sem Git; novas inicializações adotam estado local ignorado. +6. A prova JVM/nativa abre, grava, lê e reabre a base. O pacote contém os componentes + SQLite necessários e seu instalador é validado com fixtures, sem tocar a + instalação ativa ou projetos consumidores. +7. Testes de domínio, integração, compatibilidade, migração e smoke apropriados + verificam a mudança. Não guardar arquivos adicionais apenas para provar que + esses testes existiram. +8. Entregar um cenário reproduzível para retomar a avaliação de responsividade no + WRK-000C; adoção de SQLite não encerra automaticamente o ticket da demora. + +## Riscos e adaptação permitida + +A integração do driver com Native Image, a preservação das representações +históricas e a distinção entre descarte legítimo e perda de anexos são incertezas +técnicas. Devem ser investigadas com dados descartáveis e critérios prévios. + +A implementação pode ajustar esquema, índices, transações e detalhes de build +dentro desses limites. Evidência que questione uma escolha significativa exige +reconsideração e revisão da DEC conforme a autoridade do Work. Preservar OODA e +a restrição de instalação durante essa adaptação. + +## Fundamentação + +- WRK-000D, DSC-0001 a DSC-0016 e respostas de SVY-0001/SVY-0002: escolhas humanas, + evolução de escopo, retenção mínima, uso local e restrição de instalação. +- WRK-000C, DSC-0004: inspeção estática dos acessos repetidos; não é benchmark nem + comprovação da causa integral da latência. +- Código atual: `WorkService`, `ArtifactService`, `VerificationService`, + `PlanCoordinator`, `EpicCoordinator`, `scripts/install-native.sh` e + `scripts/test-install-native.py`. +- [SQLite JDBC e Native Image](https://github.com/xerial/sqlite-jdbc#graalvm-native-image-support). +- [Transações SQLite](https://sqlite.org/lang_transaction.html) e + [integridade referencial](https://sqlite.org/foreignkeys.html). + +## Estado de aprovação + +DEC emitida em rascunho a pedido explícito de Nilton. Esse pedido autoriza a +emissão, não aprova antecipadamente seu conteúdo. Aprovação da DEC precede o Plan +e a implementação. A instalação real permanece adiada mesmo após eventual +aprovação desta decisão. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/decisions/DEC-0001.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/decisions/DEC-0001.md new file mode 100644 index 0000000..12edcad --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/decisions/DEC-0001.md @@ -0,0 +1,247 @@ +--- +schemaVersion: 1 +id: "DEC-0001" +workId: "WRK-000D" +title: "Adotar memória de engenharia local em SQLite com gates preservados e retenç\ + ão mínima" +context: "O humano definiu AIE como memória local de engenharia por Work, com investigaç\ + ão, implementação, OODA e entrega por gates de qualidade. Arquivos atuais geram\ + \ acessos repetidos e retenção excessiva. Compartilhamento distribuído e integraç\ + ão Git foram retirados deste recorte. Projetos em andamento impedem instalar ou\ + \ substituir agora a distribuição nativa em uso." +approach: "Adotar SQLite por projeto como fonte principal; preservar os dois ciclos,\ + \ autoridade e checks existentes, com anexos temporários e resultados mínimos persistidos.\ + \ Migrar explicitamente com verificação e recuperação. Preparar pacote e script\ + \ com AIE nativo e SQLite juntos, validar com fixtures e artefatos descartáveis\ + \ e adiar instalação real até instrução humana específica. Manter .ai-engineering\ + \ fora de Git por padrão e deixar importação/exportação e sincronização para etapa\ + \ posterior." +alternatives: [] +rationale: "A decisão concentra o AIE em continuidade e qualidade do trabalho, simplifica\ + \ persistência e retenção e trata consistência entre registros com transações. Preserva\ + \ histórico e regras humanas, limita mudanças nos consumidores e separa a adoçã\ + o do armazenamento da futura comprovação de responsividade no WRK-000C." +risks: [] +acceptanceCriteria: [] +approvalStatus: "ACCEPTED" +author: "Codex" +createdAt: "2026-11-22T11:44:02.759315Z" +evidence: [] +revision: 2 +previousHash: "b0ac158915839dd73162f32c3f1ad1a8f39c2f5468a39a4e81e480b9333acabc" +updatedAt: "2026-11-22T11:49:21.244680Z" +updatedBy: "Nilton" +changeReason: "Aprovação explícita nesta conversa: aceitar a DEC e gerar um Plan dividido\ + \ em vários steps. A instalação nativa e a migração de projetos consumidores permanecem\ + \ adiadas conforme a DEC." +approvals: +- status: "ACCEPTED" + by: "Nilton" + reason: "Aprovação explícita nesta conversa: aceitar a DEC e gerar um Plan dividido\ + \ em vários steps. A instalação nativa e a migração de projetos consumidores permanecem\ + \ adiadas conforme a DEC." + at: "2026-11-22T11:49:21.244639Z" + humanApproved: true +revises: null +supersededBy: null +documentVersion: 2 +--- + +# Memória de engenharia local com SQLite + +## Contexto e objetivo + +O AIE deve preservar conhecimento de engenharia por Work: contexto, discussão, +refinamento, decisões e suas justificativas, planos e resultados. A entrega depende +dos gates de qualidade estipulados. Auditoria e retenção de arquivos devem servir +a esse funcionamento com o mínimo necessário. + +O armazenamento atual combina documentos e referências em arquivos, validações +repetidas e publicação atômica por arquivo. O WRK-000C registra latência percebida +em consultas e registros. Este Work trata a mudança de persistência; a avaliação +da latência será retomada separadamente após a entrega. + +O uso desta versão é local. A discussão de colaboração demonstrou que contador +local e snapshot binário não resolvem criação independente e reconciliação entre +máquinas. Por escolha humana, sincronização e compartilhamento foram retirados +deste recorte, em favor de um framework local fora de Git por padrão. + +## Decisão proposta + +### 1. Fonte principal e acesso + +- Manter uma base SQLite por projeto em `.ai-engineering/aie.db`. +- Persistir registros tipados, textos úteis e relações: Works, discussões, tópicos, + surveys e respostas, DECs e aprovações, Plans e passos, experimentos, coordenação + de EPICs, registros operacionais de execução e resultados dos gates. +- Usar tabelas, índices e restrições para as consultas e relações necessárias. + Consultar um Work não deve carregar todos os Works por conveniência de acesso. +- Textos e estruturas operacionais podem ser armazenados como dados de domínio; + conteúdo de arquivos não será convertido em BLOB, base64 ou TEXT equivalente. +- A CLI é a interface normal de leitura e alteração. Preservar comandos e formatos + públicos quando compatíveis; mudanças necessárias terão documentação explícita. +- Manter a descoberta do projeto, configuração e instruções de entrada em arquivos + pequenos quando necessários ao bootstrap. Eles não constituem uma segunda cópia + autoritativa da memória dos Works. + +### 2. Ciclos, qualidade e autoridade + +Preservar os dois ciclos existentes: investigação/discussão e implementação, +conectados por DEC e Plan. OODA continua adaptativo: observar resultados, orientar +a investigação, decidir e agir; reconsiderar hipóteses e replanejar quando houver +novas observações. Não criar quatro etapas burocráticas por ação. + +Gates obrigatórios vêm do projeto e podem ser complementados por Work. Preservar +os checks existentes e os anexos exigidos durante a avaliação. Gate obrigatório +pendente, falho ou não executado impede a entrega. Registrar o resultado realmente +observado e o estado avaliado; alterações relevantes exigem reavaliar os gates +afetados. Aprovação humana continua distinta de sucesso técnico. + +O registro mínimo de um gate identifica a verificação, a execução ou avaliação, +o estado/revisão relevante, o momento e o resultado com resumo curto. O registro +de execução de agente mantém o necessário para continuidade, idempotência e +diagnóstico. Não há obrigação de guardar transporte bruto ou logs completos. + +Esta mudança não introduz um executor autônomo de comandos do repositório. A +execução externa e as responsabilidades de agentes/humanos seguem o contrato +aplicável; a persistência registra resultados e aplica os checks determinísticos. + +### 3. Anexos, temporários e entregas + +- Anexos de comprovação ficam no filesystem e podem continuar obrigatórios. +- Antes de descartar um anexo, concluir todos os checks que dele dependem e + persistir o resultado mínimo correspondente no banco. +- Ao terminar uma execução, limpar os temporários elegíveis automaticamente. + Arquivos ainda necessários a checks pendentes permanecem até esse uso terminar. +- Distinguir anexo temporário validado e legitimamente descartado de arquivo + perdido antes da avaliação. A consulta histórica usa o resultado persistido; + avaliações atuais continuam exigindo suas entradas. +- Em interrupções, não marcar checks como concluídos. A recuperação identifica + resíduos e respeita referências de operações ainda pendentes. +- Código alterado permanece no repositório. Documentos, imagens e outros outputs + solicitados são entregues no destino apropriado e preservados como entregas. + O AIE não exige uma cópia permanente adicional apenas por auditoria. +- Recibos internos necessários ao protocolo podem ter representação estruturada + no banco, preservando a proveniência histórica na migração. + +### 4. Transações e concorrência local + +Uma operação coerente de alteração usa transação SQLite, inclusive a atualização +de registros e referências relacionados. Habilitar integridade referencial em +cada conexão e tratar concorrência entre processos do mesmo projeto. + +Manter transações curtas e espera de escrita limitada, com diagnóstico útil em +caso de contenção. Montar leituras relacionadas em uma visão consistente. +Escolher o modo de journal e os parâmetros de durabilidade com verificação na +plataforma alvo. Arquivos externos não integram a transação SQLite: sua publicação, +referência e remoção precisam de recuperação explícita quando houver interrupção. + +### 5. Migração e compatibilidade + +A migração do legado é uma operação pública explícita, com prévia, cópia de +segurança própria da migração e recuperação. Não converter projetos consumidores +automaticamente ao instalar, atualizar ou fazer uma consulta. + +Preparar uma base separada, importar os registros tipados em transação e comparar +IDs, conteúdo, relações, aprovações, revisões e proveniência com o legado. Preservar +os hashes históricos e suas representações de origem quando necessários à leitura +e verificação de entregas antigas, sem fabricar novas aprovações ou despejar os +arquivos inteiros no banco. Trocar a fonte principal somente após validação. + +Repetir uma tentativa não deve duplicar registros. Interrupções e falhas deixam a +fonte anterior recuperável; o comando informa o estado e a próxima ação. Registros +legados e originais de segurança não serão apagados retroativamente nesta mudança +sem disposição explícita. + +Versionar o esquema da base e declarar o novo armazenamento no contrato público. +Formatos suportados, diagnóstico de compatibilidade e recusa de combinações +incompatíveis precisam ser explícitos. O bootstrap deve impedir que uma base nova +seja confundida com um projeto vazio ou alterada por uma CLI incompatível. + +### 6. Instalação conjunta preparada, ativação adiada + +Evoluir `scripts/install-native.sh` e seu empacotamento para distribuir o AIE +nativo, a biblioteca SQLite do driver e o executável `sqlite3` juntos em um +diretório configurável do usuário, com atalhos em `~/.local/bin`. Bancos de projeto +permanecem em `.ai-engineering/`, separados dos binários. + +Usar a biblioteca/driver no processo AIE. O `sqlite3` do pacote serve à inspeção +e ao diagnóstico. Avaliar Xerial SQLite JDBC em prova JVM e Native Image; +fixar versão e plataforma compatíveis antes de consolidar a dependência. + +Uma disposição recomendada para o pacote é `~/.local/lib/ai-engineering/`, com +atalhos `aie` e `ai-engineering` em `~/.local/bin`. O instalador deve verificar o +pacote completo antes de ativar uma atualização e preservar a instalação anterior +em falhas. + +**Restrição humana vigente:** não executar instalação nativa, substituir atalhos, +binários ou bibliotecas da instalação em uso, nem migrar projetos consumidores. +Há projetos em andamento. Este Work pode preparar o script e o pacote e verificar +seu comportamento com fixtures e artefatos de build descartáveis após aprovação; +a instalação real e a ativação exigem uma instrução humana posterior específica. + +### 7. Git e recortes futuros + +O `init` deixa `.ai-engineering/` fora de Git por padrão e o framework funciona +sem Git. Preservar regras existentes e tornar explícito o tratamento de projetos +já versionados; não remover arquivos rastreados nem reescrever histórico Git +automaticamente. Versionar o estado fica a critério do desenvolvedor. + +Ficam fora deste recorte: integração Git LFS, sincronização entre máquinas ou +branches, reconciliação distribuída, importação/exportação de Works ou DECs e +backup como funcionalidade. A cópia de segurança da migração é uma medida local +da conversão. O compartilhamento futuro de DECs tem interesse de produto, sem +reintroduzir colaboração distribuída nesta entrega. + +## Condições de sucesso + +1. Criar e retomar um Work em processos distintos usando SQLite local preserva + contexto, estado e autoridade nos dois ciclos e em suas transições. +2. Gates do projeto e adicionais do Work bloqueiam a entrega quando necessário; + anexos continuam disponíveis durante os checks e seu descarte legítimo não + invalida resultados históricos nem encobre falta de entrada antes da avaliação. +3. Migração em fixtures representativas preserva conteúdo, IDs, relações, + aprovações e proveniência; falhas, rollback e repetição não perdem nem duplicam + a memória de engenharia. +4. Rollback e concorrência local não publicam alterações relacionadas parcialmente + nem produzem espera ilimitada sem diagnóstico. +5. O projeto funciona sem Git; novas inicializações adotam estado local ignorado. +6. A prova JVM/nativa abre, grava, lê e reabre a base. O pacote contém os componentes + SQLite necessários e seu instalador é validado com fixtures, sem tocar a + instalação ativa ou projetos consumidores. +7. Testes de domínio, integração, compatibilidade, migração e smoke apropriados + verificam a mudança. Não guardar arquivos adicionais apenas para provar que + esses testes existiram. +8. Entregar um cenário reproduzível para retomar a avaliação de responsividade no + WRK-000C; adoção de SQLite não encerra automaticamente o ticket da demora. + +## Riscos e adaptação permitida + +A integração do driver com Native Image, a preservação das representações +históricas e a distinção entre descarte legítimo e perda de anexos são incertezas +técnicas. Devem ser investigadas com dados descartáveis e critérios prévios. + +A implementação pode ajustar esquema, índices, transações e detalhes de build +dentro desses limites. Evidência que questione uma escolha significativa exige +reconsideração e revisão da DEC conforme a autoridade do Work. Preservar OODA e +a restrição de instalação durante essa adaptação. + +## Fundamentação + +- WRK-000D, DSC-0001 a DSC-0016 e respostas de SVY-0001/SVY-0002: escolhas humanas, + evolução de escopo, retenção mínima, uso local e restrição de instalação. +- WRK-000C, DSC-0004: inspeção estática dos acessos repetidos; não é benchmark nem + comprovação da causa integral da latência. +- Código atual: `WorkService`, `ArtifactService`, `VerificationService`, + `PlanCoordinator`, `EpicCoordinator`, `scripts/install-native.sh` e + `scripts/test-install-native.py`. +- [SQLite JDBC e Native Image](https://github.com/xerial/sqlite-jdbc#graalvm-native-image-support). +- [Transações SQLite](https://sqlite.org/lang_transaction.html) e + [integridade referencial](https://sqlite.org/foreignkeys.html). + +## Estado de aprovação + +DEC emitida em rascunho a pedido explícito de Nilton. Esse pedido autoriza a +emissão, não aprova antecipadamente seu conteúdo. Aprovação da DEC precede o Plan +e a implementação. A instalação real permanece adiada mesmo após eventual +aprovação desta decisão. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0001.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0001.md new file mode 100644 index 0000000..67fbf1a --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0001.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0001" +workId: "WRK-000D" +discussionId: "main" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T10:45:08.099964Z" +respondsTo: null +documentVersion: 2 +--- + +Origem: Nilton propôs explicitamente nesta conversa manter o ticket da demora WRK-000C, abrir um Work separado para a mudança para uma base consolidada como SQLite e retornar à latência depois, sob a ótica da nova base. Escolheu EXPLORATORY especificamente para este novo Work. O escopo deste ticket é a mudança de persistência, incluindo futura implementação e migração após decisão aprovada; os critérios iniciais são proposta a refinar durante a exploração. Contexto de origem no WRK-000C: DSC-0004 contém a inspeção estática dos acessos repetidos; DSC-0005 compara arquivos, índice reconstruível e SQLite canônico; DSC-0006 e DSC-0007 registram que Nilton não pretende editar os arquivos manualmente e favorece a direção de banco principal. A fonte de verdade atual continua sendo os arquivos; nenhuma migração foi executada. Primeiras questões: modelo e limites das transações; formato de histórico e preservação de hashes; evidências internas ou externas; migração e recuperação; exportação e backup; compatibilidade/distribuição JVM e Native Image. A latência permanece no WRK-000C e será reavaliada após a entrega desta mudança; não presumir solução apenas pela adoção de SQLite. A relação entre Works é registrada na discussão, sem inventar dependência formal ou transformar um deles em EPIC. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0002.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0002.md new file mode 100644 index 0000000..7ddec43 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0002.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0002" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T10:48:14.674435Z" +respondsTo: null +documentVersion: 2 +--- + +Preferência explícita nesta conversa: não gostaria de gravar os artefatos produzidos (run, output e outros) como blobs. Propõe que SQLite grave somente os textos pertinentes ao funcionamento do AIE e pergunta se essa fronteira faz sentido. A instrução orienta o escopo de persistência; não solicita encerrar a exploração nem aprova uma DEC concreta. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0003.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0003.md new file mode 100644 index 0000000..de0d9fc --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0003.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0003" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T10:48:15.103274Z" +respondsTo: null +documentVersion: 2 +--- + +Proposta baseada na inspeção do código atual: SQLite guarda estado estruturado, textos operacionais, relações, revisões, aprovações e metadados; filesystem guarda conteúdo de anexos, outputs, relatórios, logs e demais arquivos produzidos, inclusive os de formato textual. A fronteira é a função do conteúdo, não sua extensão: uma conclusão de experimento entra no banco; o log completo que a sustenta permanece em arquivo. Não serializar arquivos em BLOB, base64 ou grandes campos TEXT para contornar a restrição. Registros operacionais incluem números, timestamps e flags, não apenas colunas TEXT. Há duas coisas distintas chamadas run no desenho atual: agent-runs/RUN contém tarefa, executor/modelo, estado, sourceHash, proposta validada, referências aplicadas e proveniência necessárias ao funcionamento e replay idempotente (AgentRun.java e AgentService.java); runs/ contém resultados temporários ignorados (docs/protocol.md). A proposta é manter a parte operacional do RUN no banco e arquivos brutos fora dele. Conteúdo estruturado de proposta necessário a auditoria/replay deve ser preservado com esquema e limites explícitos, sem copiar todo transporte bruto. Hoje adapters descartam workspace temporário e não persistem stderr bruto; não introduzir retenção indiscriminada na migração. Artifact.java já separa metadados de bytes: ID local ao Work, workId, origem, finalidade, caminho, SHA-256, tamanho, autor e data; ArtifactService mantém payload no filesystem. Essa separação pode ser mantida, com metadados no banco e caminho relativo ao projeto, propriedade/identidade verificadas e bytes preservados. Outputs temporários não são evidência durável: promover explicitamente a artefato retido quando forem usados para comprovação, sem limpeza automática de evidências ou histórico. Recibos internos de conclusão/importação são registros do protocolo e podem ter representação estruturada no banco; originais históricos que participam de hashes permanecem preservados em arquivos, sem recalcular silenciosamente cadeias ou aprovações. Banco e arquivos externos não compartilham transação SQLite: para anexar, preparar e publicar arquivo completo e imutável antes de confirmar o registro no banco; falha intermediária pode deixar arquivo órfão diagnosticável, sem removê-lo automaticamente. Falta/alteração de arquivo referenciado deve gerar diagnóstico de integridade. Backup/restauração precisam cobrir uma visão consistente do banco e os arquivos por ela referenciados; copiar somente a base não é backup completo do projeto. Leituras rotineiras consultam metadados e conteúdo operacional necessários; validação integral de payloads tem escopo explícito, preservando os checks exigidos nas operações que dependem da evidência. Permanecem em exploração: layout e propriedade dos arquivos, promoção e retenção de outputs, compatibilidade dos hashes/recibos, transações de publicação e recuperação e política de backup. Nenhuma implementação ou migração realizada. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0004.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0004.md new file mode 100644 index 0000000..bbd9175 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0004.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0004" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T11:03:13.616058Z" +respondsTo: null +documentVersion: 2 +--- + +Reorientação explícita nesta conversa: não vê sentido em reter o conjunto de artefatos para auditoria. Considera suficiente atender aos gates de qualidade; para esta versão propõe reduzir drasticamente os artefatos armazenados pelo AIE e manter somente o output solicitado quando a entrega não for alteração de código. Observa que os artefatos se tornam obsoletos conforme novos Works são feitos. Considera útil preservar o trabalho no banco para consulta e possíveis lessons futuras. Sugere tornar configurável no init a política de Git: banco como binário referenciado por ponteiro ou diretório .ai-engineering completamente ignorado. Nenhuma das duas políticas foi escolhida como padrão. A mensagem revê as premissas das perguntas de retenção anteriores; não solicita apagar artefatos existentes nem encerrar exploração. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0005.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0005.md new file mode 100644 index 0000000..c006781 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0005.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0005" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T11:03:14.037888Z" +respondsTo: null +documentVersion: 2 +--- + +Síntese e proposta revista: a retenção de evidências em arquivos não deve ser requisito obrigatório de novos Works apenas para auditoria. Para alterações em código, a entrega permanece no repositório; para entregas não relacionadas a código, manter somente os outputs solicitados no destino apropriado, sem cópia adicional obrigatória no AIE. Banco mantém conhecimento útil e estado operacional: escopo, discussão, decisões e justificativas, planos/resultados, aprovações e registro enxuto de gates observados. Proposta de registro de gate: identificação, invocação ou procedimento, revisão/estado do código avaliado quando aplicável, data, resultado e resumo curto; comandos realmente executados ou avaliações realmente feitas devem ser distinguíveis de intenção, sem persistir logs completos ou inventar sucesso. A aprovação humana continua separada do resultado do gate. Logs, payloads de transporte, relatórios intermediários e cópias de builds não são retidos por padrão; temporários de execuções ativas e falhas ainda precisam de ciclo de vida definido. Outputs solicitados não precisam ficar dentro de .ai-engineering; basta referência útil, sem comprometer conhecimento histórico caso um output seja posteriormente movido. Sem BLOB/base64 ou arquivos serializados em TEXT. Mudança exige revisão do contrato, não somente backend: Plan.Step atualmente exige evidence não vazio para COMPLETED; Work.CriterionResult e VerificationService.complete exigem ART por critério; PlanCoordinator e EpicCoordinator geram recibos externos. Propor substituir a obrigação de ART para novos registros por resultados estruturados e critérios/gates satisfeitos; preservar a leitura/proveniência do legado, sem excluir arquivos atuais ou alterar retroativamente entregas. Quanto a Git, propor config explícita no init: LOCAL com .ai-engineering ignorado, ou snapshot consistente versionado opcionalmente via Git LFS; default LOCAL ainda é recomendação. Git LFS armazena ponteiros no Git e conteúdo fora dele (https://git-lfs.com/); não mescla semanticamente duas bases SQLite. Recomenda-se versionar snapshot produzido por API de backup SQLite, em vez de tomar o arquivo de banco em uso como cópia completa: em WAL há arquivos auxiliares relevantes. Referências https://sqlite.org/backup.html e https://sqlite.org/wal.html . São alternativas configuráveis, sem executar Git, mudar ignore ou instalar LFS nesta discussão. Menor retenção é requisito funcional do WRK-000D, separado da futura medição de latência no WRK-000C. Possíveis lessons são uso futuro do conhecimento existente; não introduzir entidade ou fluxo obrigatório de lessons nesta versão. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0006.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0006.md new file mode 100644 index 0000000..98d9706 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0006.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0006" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T11:08:23.031938Z" +respondsTo: null +documentVersion: 2 +--- + +Princípio de produto explicitamente afirmado nesta conversa: precisamos garantir os gates de qualidade estipulados, porém não precisamos de tanta auditoria e retenção de arquivos. AI-Engineering deve ser muito mais próximo de uma memória de engenharia, com discussão e afinamento por trabalho, que entrega por gates de qualidade. O foco não é auditoria; manter somente o mínimo. Esta orientação reforça a simplificação de retenção sem dispensar, enfraquecer ou considerar atendidos os gates por mera ausência de arquivos. Não solicita encerrar exploração nem aprova uma DEC concreta. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0007.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0007.md new file mode 100644 index 0000000..7554082 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0007.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0007" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T11:08:23.444959Z" +respondsTo: null +documentVersion: 2 +--- + +Síntese orientadora: AIE é memória de engenharia por Work, com discussão/refinamento e entrega condicionada aos gates estipulados; auditoria é mínima e subordinada a essa finalidade. Proposta de funcionamento: definir os gates aplicáveis e sua condição de sucesso antes da avaliação; registrar o resultado efetivamente observado com identificação do gate, referência à versão/estado avaliado quando pertinente e resumo suficiente para continuidade; impedir entrega enquanto gate obrigatório estiver pendente ou falhar. Gates não executados não contam como atendidos. Mudanças relevantes após avaliação exigem reavaliar os gates afetados. Aprovação humana e resultado técnico permanecem conceitos distintos, respeitando a autoridade registrada no Work. Nenhum gate deve exigir retenção de log, anexo ART, recibo externo ou cópia de build apenas por auditoria; persistir no banco somente estado, relações, textos de engenharia e resultados operacionais necessários. Outputs solicitados são entregas; temporários e resíduos de execução não se tornam acervo permanente. Revisões e histórico do legado permanecem preservados durante esta exploração; não executar descarte retroativo. O nível mínimo de histórico futuro deve servir a retomada, justificativas e consulta, evitando um novo sistema de auditoria extensivo. Sem introduzir mecanismo de execução autônoma ou novos gates neste registro: integração, execução e avaliação dos gates serão detalhadas na discussão e na DEC quando solicitada pelo humano. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0008.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0008.md new file mode 100644 index 0000000..dc8e356 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0008.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0008" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T11:09:54.902840Z" +respondsTo: null +documentVersion: 2 +--- + +Esclarecimento explícito nesta conversa: os dois ciclos existentes, investigação e implementação, com uso de OODA, serão mantidos. A simplificação de auditoria, retenção de arquivos e adoção de SQLite não deve remover esses ciclos nem o caráter adaptativo do processo. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0009.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0009.md new file mode 100644 index 0000000..5a22daa --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0009.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0009" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T11:11:08.043729Z" +respondsTo: null +documentVersion: 2 +--- + +Escolha explícita de versionamento nesta conversa: Git LFS primeiro; exportação para backup será considerada depois, se necessário. Esta escolha substitui a recomendação anterior de LOCAL como padrão e retira exportação/backup como funcionalidade obrigatória desta versão. Não constitui aprovação de DEC concreta nem pedido para encerrar a exploração. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0010.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0010.md new file mode 100644 index 0000000..7b9dd04 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0010.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0010" +workId: "WRK-000D" +discussionId: "TOP-0002" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T11:21:47.081629Z" +respondsTo: null +documentVersion: 2 +--- + +Respostas explícitas nesta conversa: (1) gates por projeto mais gates individuais por Work quando necessários; (4) sim ao descarte automático de temporários ao fim da execução. Os itens (2) momento de captura para LFS e (3) colaboração precisam de discussão adicional antes de prosseguir. Hoje o uso do AIE é individual, mas Nilton quer considerar compartilhamento com outras pessoas no mesmo projeto e relata que já há problemas no desenho atual: duas pessoas criando um Work em máquinas diferentes podem colidir. Não escolher um fluxo exclusivo de um escritor nem adiar essa questão sem discutir. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0011.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0011.md new file mode 100644 index 0000000..e723a08 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0011.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0011" +workId: "WRK-000D" +discussionId: "TOP-0002" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T11:21:47.512328Z" +respondsTo: null +documentVersion: 2 +--- + +Inspeção estática confirma origem da colisão de identidade: WorkService.createPrepared lê .sequence.yaml e o maior ID local, soma 1 e gera WRK-%04X sob Filespace.locked. O lock só coordena processos com a mesma área local; clones separados reservam o mesmo próximo ID sem se conhecer. WorkService.list rejeita IDs duplicados, mas não reconcilia Works diferentes com o mesmo ID. SQLite com contador local manteria esse problema. Além disso, UUIDs resolveriam geração independente de identidade com probabilidade desprezível de colisão, mas não a combinação de duas bases que divergiram. Recomenda-se discutir identidade completa distribuída (UUID de projeto e entidades) com referências humanas curtas como aliases desambiguáveis, preservando IDs/identidade histórica na migração. UUIDv4/v7 são candidatos, sem escolha final (RFC 9562: https://www.rfc-editor.org/rfc/rfc9562.html). A escolha Git LFS continua registrada para versionamento, porém não resolve sincronização semântica dos registros. Git oferece merge de binários como conflito ou driver próprio (https://git-scm.com/docs/gitattributes); lock LFS é lock de caminho no servidor, não reconciliação de alterações offline (https://raw.githubusercontent.com/git-lfs/git-lfs/main/docs/man/git-lfs-lock.adoc). Snapshot consistente resolve captura local, não combinação de conhecimento produzido separadamente. Alternativas a comparar: (A) SQLite local por participante com sincronização lógica dos registros pelo AIE e transporte via Git; exige representação de intercâmbio/driver de merge e regras de conflito, mesmo sem exportação de backup; (B) serviço compartilhado como autoridade com SQLite local opcional, trazendo infraestrutura e política online/offline, sujeito a revisão explícita da restrição atual sem servidor; (C) atualização serializada de um snapshot único sob lock, opção simples que restringe colaboração e não atende trabalho independente offline. Primeira hipótese recomendada para avaliar, se offline e ausência de servidor forem prioridades: SQLite local, IDs distribuídos, união idempotente de Works independentes e detecção de conflitos nos mesmos registros, sem last-write-wins para decisões, aprovações, critérios e gates. Entradas de discussão independentes podem ser combinadas por identidade; alterações concorrentes do mesmo escopo exigem resolução explícita e reavaliação das aprovações/gates afetados. Identificar um gate como passado em outra versão não satisfaz automaticamente o gate do código após merge. Precisamos esclarecer necessidade de trabalho offline e edição simultânea do mesmo Work para dimensionar colaboração antes de escolher captura/sync. A exigência de sincronização é de funcionamento e memória, não acervo de auditoria; não introduzir logs completos ou trilha infinita de eventos como solução automática. Nenhuma estratégia aprovada, código alterado, DEC ou migração executada. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0012.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0012.md new file mode 100644 index 0000000..43e35f1 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0012.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0012" +workId: "WRK-000D" +discussionId: "TOP-0002" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T11:29:41.062263Z" +respondsTo: null +documentVersion: 2 +--- + +Pivô explícito de produto nesta conversa: desenvolver o AI-Engineering como framework de trabalho local, com .ai-engineering fora de Git por padrão. Versionar o estado fica a critério do desenvolvedor. Importação e exportação de Works para compartilhar registros podem ser planejadas posteriormente, se necessário. DEC é o conteúdo mais interessante para compartilhar, pois orienta o trabalho, mas esse compartilhamento também fica para etapa posterior. A escolha substitui Git LFS como primeira estratégia obrigatória e retira sincronização entre máquinas e colaboração compartilhada do escopo desta versão. Preservar os dois ciclos, OODA, gates e memória de engenharia já definidos. Não há pedido explícito de encerramento da exploração nem aprovação de DEC concreta. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0013.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0013.md new file mode 100644 index 0000000..0494794 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0013.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0013" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T11:37:40.902619Z" +respondsTo: null +documentVersion: 2 +--- + +Esclarecimentos explícitos nesta conversa: (1) exigência de anexos pode continuar; devem ser tratados como temporários, e os checks podem permanecer como hoje. (2) o desenho da migração é delegado ao agente para investigação e proposta. (3) instalar executável nativo e SQLite juntos num mesmo diretório por script, semelhante ao instalador existente do AIE em ~/.local/bin. A escolha não pede uma instalação imediata nem encerra a exploração. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0014.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0014.md new file mode 100644 index 0000000..8b48cdc --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0014.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0014" +workId: "WRK-000D" +discussionId: "TOP-0001" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T11:37:41.342432Z" +respondsTo: null +documentVersion: 2 +--- + +Proposta ajustada: preservar a exigência de anexos e as condições dos checks durante a avaliação; anexos de comprovação são temporários e só podem ser descartados depois de todos os checks que deles dependem. Descarte ao fim da execução não pode remover arquivo que ainda é necessário a um gate pendente. Persistir no banco o resultado mínimo e referências/metadados necessários à memória; outputs solicitados continuam entregas. Hoje VerificationService.work revalida payloads e recibos inclusive em Works concluídos, portanto expurgo legítimo precisa ter tratamento de ciclo de vida para que consultas históricas distingam anexo temporário já validado de arquivo perdido antes da validação, sem dispensar checks ativos nem inventar sucesso. Ajuste funcional necessário é a temporalidade/retenção, não afrouxar qualidade. Recibos internos necessários ao funcionamento podem virar registros estruturados no banco. Migração proposta sob responsabilidade técnica do agente: usar cópia descartável do legado, importação transacional dos registros tipados, preservação de identidade, aprovações, relações e proveniência, comparação do contexto e do estado antes/depois e troca da fonte principal somente após validação; cópia de segurança de migração é separada de funcionalidade de exportação/backup. Não despejar arquivos inteiros em TEXT nem remover os originais durante exploração. Instalador existente confirmado: scripts/install-native.sh compila nativeCompile, instala ai-engineering em ~/.local/bin e cria aie como link; scripts/test-install-native.py cobre instalação em ambientes descartáveis. Proposta é evoluir esse script para instalar pacote nativo e dependências SQLite juntos em um diretório privado do usuário, mantendo atalhos em ~/.local/bin e bancos separados em .ai-engineering de cada projeto. SQLite possui motor/biblioteca e CLI sqlite3 distintos (https://sqlite.org/cli.html). Recomenda-se acesso por driver/biblioteca dentro do processo AIE; incluir sqlite3 junto ao pacote para inspeção e diagnóstico, sem usar um subprocesso para cada consulta. Driver Xerial declara suporte GraalVM Native Image e exportação da biblioteca no build para instalação ao lado do executável, evitando extração em cada execução (https://github.com/xerial/sqlite-jdbc#graalvm-native-image-support). Validar versão/plataforma e atualização conjunta do pacote; seleção final da dependência, layout e prova nativa permanecem investigação técnica. Não executar instalação, migração ou mudança de código nesta etapa. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0015.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0015.md new file mode 100644 index 0000000..21f8842 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0015.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0015" +workId: "WRK-000D" +discussionId: "main" +kind: "NOTE" +author: "Codex" +createdAt: "2026-11-22T11:40:07.438598Z" +respondsTo: null +documentVersion: 2 +--- + +Síntese técnica proposta após as respostas de Nilton: não há novas perguntas essenciais de produto identificadas. Discussão pode ser considerada madura para futura DEC, cujo pedido de criação e encerramento da exploração permanecem com o humano. Proposta concreta: (1) uma base .ai-engineering/aie.db por projeto, fora do Git por padrão, armazenando registros tipados, textos úteis e relações; tabelas e índices por identidade/Work/estado/referências, sem arquivos em BLOB/base64/TEXT e sem substituir toda a estrutura por um único documento serializado. Preservar interfaces públicas e regras de domínio tanto quanto possível, alterando a infraestrutura de persistência. (2) Avaliar Xerial SQLite JDBC como driver, começando por uma prova descartável JVM/Native Image que faça create/read/write/reopen e instale biblioteca ao lado do nativo; incluir CLI sqlite3 no pacote para diagnóstico. Fixar versão suportada e verificar plataforma; não prometer compatibilidade apenas pela documentação. (3) Usar transações curtas por operação coerente, integridade referencial explicitamente habilitada por conexão e espera de lock limitada com mensagem útil. Uma leitura de contexto utiliza uma transação coerente e consulta somente os dados necessários; definição de journal/configuração será validada em prova, sem supor ganho de desempenho automaticamente. (4) Gates atuais, inclusive anexos quando exigidos, permanecem durante avaliação; persistir resultado mínimo antes do descarte de anexos temporários, condicionado à inexistência de checks pendentes que os usem. Caso uma execução seja interrompida, não marcar gate como concluído e recuperar temporários remanescentes no ciclo de vida definido. Outputs solicitados permanecem entregas. (5) Migração explícita e repetível: prévia sem escrita, cópia de segurança de migração, importação transacional numa base de preparo, comparação de IDs/relações/conteúdo/aprovações/contexto com o legado e ativação apenas após verificação. Retentar não duplica registros; falha deixa a fonte anterior utilizável. Preservar hashes e proveniência históricos sem inventar nova aprovação nem manter cópias integrais de arquivos em TEXT. (6) Evoluir scripts/install-native.sh para diretório de instalação configurável com nativo, biblioteca SQLite e sqlite3 juntos, atalhos aie/ai-engineering em ~/.local/bin, instalação verificada antes de troca e bancos de projeto separados dos binários. (7) Validar principalmente continuidade entre processos, transações/rollback, preservação do legado, checks/gates e descarte legítimo, funcionamento sem Git, instalação/atualização e smoke nativo. WRK-000C recebe depois o cenário e as medições para tratar responsividade; esta entrega não comprova automaticamente a solução da latência. Fora deste recorte: Git LFS, sincronização distribuída, importação/exportação de Works/DECs e backup como funcionalidade. Fontes oficiais verificadas: https://github.com/xerial/sqlite-jdbc#graalvm-native-image-support ; https://sqlite.org/lang_transaction.html ; https://sqlite.org/foreignkeys.html ; https://sqlite.org/pragma.html#pragma_busy_timeout . Nenhuma DEC, Plan, instalação ou migração foi executada. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0016.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0016.md new file mode 100644 index 0000000..70283f5 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/discussions/DSC-0016.md @@ -0,0 +1,13 @@ +--- +schemaVersion: 1 +id: "DSC-0016" +workId: "WRK-000D" +discussionId: "main" +kind: "NOTE" +author: "Nilton" +createdAt: "2026-11-22T11:42:06.434625Z" +respondsTo: null +documentVersion: 2 +--- + +Instrução explícita nesta conversa: não fazer a instalação nativa ainda, pois existem projetos em andamento usando o AIE instalado. Quanto ao restante da proposta, solicita emitir a DEC. Esta instrução autoriza preparar a decisão concreta; não é aprovação antecipada de seu conteúdo nem autorização para substituir o executável, bibliotecas ou instalação em uso. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0001.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0001.md new file mode 100644 index 0000000..923f3fe --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0001.md @@ -0,0 +1,103 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: [] +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 1 +previousHash: null +updatedAt: "2026-11-22T11:52:06.993736Z" +updatedBy: "Codex" +changeReason: "Plan created" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0002.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0002.md new file mode 100644 index 0000000..8d9c758 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0002.md @@ -0,0 +1,124 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 2 +previousHash: "96fcb80d5c6936cf092e438986bfb435dd545f06cd6114d96f325eaf07d20087" +updatedAt: "2026-11-22T11:52:14.922357Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0003.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0003.md new file mode 100644 index 0000000..da3068a --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0003.md @@ -0,0 +1,145 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 3 +previousHash: "5e98ef835eec106eb218719eadbcd0ef99ea983815b9c7aa518ae770751f8610" +updatedAt: "2026-11-22T11:52:22.768476Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0004.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0004.md new file mode 100644 index 0000000..0c7fd03 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0004.md @@ -0,0 +1,167 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 4 +previousHash: "5a8fe04ac73648bc424f6df5fa1b6667463193979deaf0e57c8ec677ea1ad30e" +updatedAt: "2026-11-22T11:52:29.986274Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0005.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0005.md new file mode 100644 index 0000000..1f339d6 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0005.md @@ -0,0 +1,187 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 5 +previousHash: "5a41820703048e87fa2cab136c911a2460845b62cf85be0cb9bbc99a2a28f6e9" +updatedAt: "2026-11-22T11:52:37.091242Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0006.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0006.md new file mode 100644 index 0000000..6163c9e --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0006.md @@ -0,0 +1,207 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 6 +previousHash: "28a7c87dce0f2e58035fc3f00d77a311c371b1b660b8403a7859e8954a3e7e52" +updatedAt: "2026-11-22T11:52:43.954322Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0007.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0007.md new file mode 100644 index 0000000..8aa87bf --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0007.md @@ -0,0 +1,228 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 7 +previousHash: "2432f0ab223e793f269fac5db5e34a5d8072cd07d68bdd1a52204497bb37d8d2" +updatedAt: "2026-11-22T11:52:50.899331Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0008.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0008.md new file mode 100644 index 0000000..7d179ab --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0008.md @@ -0,0 +1,250 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 8 +previousHash: "58c2cfdd0506391bf10caa81aa7651deb5586e5683ef4a5ec2fb46158b8f139a" +updatedAt: "2026-11-22T11:52:58.285688Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0009.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0009.md new file mode 100644 index 0000000..b9b896a --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0009.md @@ -0,0 +1,271 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 9 +previousHash: "91de294440e7e2179a9c771514361e26abef103d361dabf8b494108b7d8c4987" +updatedAt: "2026-11-22T11:53:05.801077Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0010.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0010.md new file mode 100644 index 0000000..a9a5a9a --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0010.md @@ -0,0 +1,295 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 10 +previousHash: "a096e72fa947ed7509a4f51a54b72b3f0661931fcd74bc5f41af2b856f56218f" +updatedAt: "2026-11-22T11:53:13.390203Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0011.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0011.md new file mode 100644 index 0000000..2029ca8 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0011.md @@ -0,0 +1,317 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 11 +previousHash: "c59eed84ea2f9a1eef5e67f8e3f6354e1ae87fb271a4f94ed10f4b5f68a2dc30" +updatedAt: "2026-11-22T11:53:21.075089Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0012.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0012.md new file mode 100644 index 0000000..fb6a759 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0012.md @@ -0,0 +1,339 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 12 +previousHash: "970111b8d97ee7737298e1c24fde59e418edfbefe93f8442b5c79f4eb2492cb8" +updatedAt: "2026-11-22T11:53:28.842081Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0013.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0013.md new file mode 100644 index 0000000..887c0e6 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0013.md @@ -0,0 +1,362 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 13 +previousHash: "f7315978de2bb516a99c90e4799b2ba448cdd913ca068735bd74b2b86b0f60d7" +updatedAt: "2026-11-22T11:53:37.290468Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0014.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0014.md new file mode 100644 index 0000000..137395e --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0014.md @@ -0,0 +1,385 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 14 +previousHash: "70649e46d952cff45e9333b6f15489309c1285266b46ece7727a03c2fca57920" +updatedAt: "2026-11-22T11:53:45.332155Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0015.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0015.md new file mode 100644 index 0000000..b74c67c --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0015.md @@ -0,0 +1,406 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "OPEN" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 15 +previousHash: "a5a5c39864250c49d70cfdd5dccbdf15f4f5b71d7d1c8ec650106b2a97730962" +updatedAt: "2026-11-22T11:53:53.421222Z" +updatedBy: "Codex" +changeReason: "Decomposição solicitada por Nilton; DEC-0001 aceita, com instalaçã\ + o real adiada." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0016.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0016.md new file mode 100644 index 0000000..f95b3c1 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0016.md @@ -0,0 +1,406 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:14.922292Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 16 +previousHash: "736533eb9739961d687b9b6c4e5ee2fe60178bb6356c650dae79cec2e8ed6d03" +updatedAt: "2026-11-22T11:56:30.194272Z" +updatedBy: "Codex" +changeReason: "Execução sequencial solicitada por Nilton; iniciar pelo mapeamento,\ + \ sem instalação ativa ou migração real." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0017.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0017.md new file mode 100644 index 0000000..0eb8560 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0017.md @@ -0,0 +1,407 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "ACTIVE" + result: "Iniciar inventário do contrato, relações e corpus de compatibilidade; executar\ + \ somente inspeções e testes em dados descartáveis." + evidence: [] + updatedAt: "2026-11-22T11:57:06.380554Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 17 +previousHash: "2eb7f7137f0686ea862b03d2c7c88592b22ce415e3fd021fd4ed800c5db04447" +updatedAt: "2026-11-22T11:57:06.380736Z" +updatedBy: "Codex" +changeReason: "Iniciar inventário do contrato, relações e corpus de compatibilidade;\ + \ executar somente inspeções e testes em dados descartáveis." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0018.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0018.md new file mode 100644 index 0000000..a1288e1 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0018.md @@ -0,0 +1,412 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:22.768410Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 18 +previousHash: "dfb8546ea0ce546e036d526c18e04e34394e02d0ca11de4114b7cb20917d4a61" +updatedAt: "2026-11-22T12:00:26.700211Z" +updatedBy: "Codex" +changeReason: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus\ + \ e casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas. Sem\ + \ instalação ou migração real." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0019.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0019.md new file mode 100644 index 0000000..a958bc2 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0019.md @@ -0,0 +1,411 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "ACTIVE" + result: "Prosseguir autonomamente conforme instrução de Nilton; provar driver em\ + \ JVM e Native Image, somente em bases descartáveis e sem instalação." + evidence: [] + updatedAt: "2026-11-22T12:09:51.453556Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 19 +previousHash: "024176b8c1377147b8bb96529bbafb271ad5a0a7d232fcd4ce390ee759c390fb" +updatedAt: "2026-11-22T12:09:51.453985Z" +updatedBy: "Codex" +changeReason: "Prosseguir autonomamente conforme instrução de Nilton; provar driver\ + \ em JVM e Native Image, somente em bases descartáveis e sem instalação." +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0020.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0020.md new file mode 100644 index 0000000..ac7f9f7 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0020.md @@ -0,0 +1,434 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "ACTIVE" + result: "Prosseguir autonomamente conforme instrução de Nilton; provar driver em\ + \ JVM e Native Image, somente em bases descartáveis e sem instalação." + evidence: [] + updatedAt: "2026-11-22T12:09:51.453556Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 20 +previousHash: "1e1d15717b43c85aa2c5f59026ad61674da13352f168154acab557ab9a9dc45a" +updatedAt: "2026-11-22T12:10:00.110882Z" +updatedBy: "Codex" +changeReason: "Prova da dependência e empacotamento nativo antes de implementar a\ + \ persistência do domínio." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "OPEN" + observation: null + interpretation: null + nextAction: null + evidence: [] + questionsDecision: null + finishedAt: null + finishedBy: null +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0021.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0021.md new file mode 100644 index 0000000..ac56905 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0021.md @@ -0,0 +1,438 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "ACTIVE" + result: "Prosseguir autonomamente conforme instrução de Nilton; provar driver em\ + \ JVM e Native Image, somente em bases descartáveis e sem instalação." + evidence: [] + updatedAt: "2026-11-22T12:09:51.453556Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 21 +previousHash: "cdfd73b6ed22c8ced85592a9168e02bfb70eb948e6dd1b90b473ee43bc58fb12" +updatedAt: "2026-11-22T12:16:43.109433Z" +updatedBy: "Codex" +changeReason: "Critérios da prova atendidos em dados descartáveis." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0022.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0022.md new file mode 100644 index 0000000..260e193 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0022.md @@ -0,0 +1,440 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:29.986202Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 22 +previousHash: "d52d9fb2f4d314c9b18ddf1a419177dd13773296d68664556a12e6a016f48ce6" +updatedAt: "2026-11-22T12:16:52.149228Z" +updatedBy: "Codex" +changeReason: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0023.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0023.md new file mode 100644 index 0000000..b4b85cb --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0023.md @@ -0,0 +1,441 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "ACTIVE" + result: "Prosseguir autonomamente para esquema, conexões, transações e concorrê\ + ncia local após prova do driver." + evidence: [] + updatedAt: "2026-11-22T12:17:01.556543Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 23 +previousHash: "7216bae64f3ae85841087a46e8e067ffe00ae38e016e0917135c87f806e6cfee" +updatedAt: "2026-11-22T12:17:01.556708Z" +updatedBy: "Codex" +changeReason: "Prosseguir autonomamente para esquema, conexões, transações e concorrê\ + ncia local após prova do driver." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0024.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0024.md new file mode 100644 index 0000000..f5d63af --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0024.md @@ -0,0 +1,444 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:37.091047Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 24 +previousHash: "78d801b18317e63d5f244299d6cbd35f979058af6284a4df6dc0f626beb03b46" +updatedAt: "2026-11-22T12:26:10.846699Z" +updatedBy: "Codex" +changeReason: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0025.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0025.md new file mode 100644 index 0000000..3afdaff --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0025.md @@ -0,0 +1,444 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "ACTIVE" + result: "Integrar Works, guidance e investigação ao backend transacional, preservando\ + \ leitura do legado e autoridade humana." + evidence: [] + updatedAt: "2026-11-22T12:26:20.696235Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 25 +previousHash: "49d5bca8fc12419c5822883338ab55e6cba35d0d8f22ef2ffea5f0761ce6832a" +updatedAt: "2026-11-22T12:26:20.696401Z" +updatedBy: "Codex" +changeReason: "Integrar Works, guidance e investigação ao backend transacional, preservando\ + \ leitura do legado e autoridade humana." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0026.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0026.md new file mode 100644 index 0000000..79caca5 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0026.md @@ -0,0 +1,445 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:43.954237Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 26 +previousHash: "ce6cc97b923d3b36f8b01b9980f75bb4a55b75cbbe97afa8d3b280a2d6670d8d" +updatedAt: "2026-11-22T12:43:38.166330Z" +updatedBy: "Codex" +changeReason: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM\ + \ e nativo; referências transacionais, histórico e autoridade preservados." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0027.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0027.md new file mode 100644 index 0000000..b7ca967 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0027.md @@ -0,0 +1,446 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "ACTIVE" + result: "Prosseguir para persistência de decisões, planos e experimentos, preservando\ + \ aprovação, revisão e rollback." + evidence: [] + updatedAt: "2026-11-22T12:43:49.770509Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 27 +previousHash: "8bcede277e67c22d1880a8dd13b45cdf533f19bc198624dddbc59587a252f726" +updatedAt: "2026-11-22T12:43:49.770679Z" +updatedBy: "Codex" +changeReason: "Prosseguir para persistência de decisões, planos e experimentos, preservando\ + \ aprovação, revisão e rollback." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0028.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0028.md new file mode 100644 index 0000000..efdb5f4 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0028.md @@ -0,0 +1,449 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:50.899228Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 28 +previousHash: "c95e42363b9a422460f20bbfb49f606a433f0ef06230d96f9f4a116ffb819949" +updatedAt: "2026-11-22T12:54:10.341713Z" +updatedBy: "Codex" +changeReason: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0029.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0029.md new file mode 100644 index 0000000..32ddcdf --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0029.md @@ -0,0 +1,448 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "ACTIVE" + result: "Integrar RUNs, idempotência e coordenação EPIC/Plans na persistência local." + evidence: [] + updatedAt: "2026-11-22T12:54:20.537359Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 29 +previousHash: "44f025ca24fd0dbeed6a56368b6845fd5003b96a0aeb8711fe898df66b7ee206" +updatedAt: "2026-11-22T12:54:20.537526Z" +updatedBy: "Codex" +changeReason: "Integrar RUNs, idempotência e coordenação EPIC/Plans na persistência\ + \ local." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0030.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0030.md new file mode 100644 index 0000000..04d29de --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0030.md @@ -0,0 +1,450 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:52:58.285586Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 30 +previousHash: "7b2ebdc1b387d96c1c5096ecd1945951149fb3112b3f6f2972cbaa3cd2218acc" +updatedAt: "2026-11-22T13:02:08.858381Z" +updatedBy: "Codex" +changeReason: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0031.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0031.md new file mode 100644 index 0000000..84df125 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0031.md @@ -0,0 +1,451 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "ACTIVE" + result: "Integrar gates do projeto e complementos por Work com resultados vinculados\ + \ ao estado avaliado." + evidence: [] + updatedAt: "2026-11-22T13:02:21.247070Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 31 +previousHash: "5791d8f5f1fb3ef63a6490ae901fdb91cbb232cad3d64a430069e0f3252a8bc9" +updatedAt: "2026-11-22T13:02:21.247243Z" +updatedBy: "Codex" +changeReason: "Integrar gates do projeto e complementos por Work com resultados vinculados\ + \ ao estado avaliado." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0032.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0032.md new file mode 100644 index 0000000..8b2021b --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0032.md @@ -0,0 +1,452 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:05.800970Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 32 +previousHash: "597f19b6e0d50560cc7b2d47df01bd3bf141998edc85b594f02cced2f8164dd8" +updatedAt: "2026-11-22T13:08:08.952425Z" +updatedBy: "Codex" +changeReason: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots histó\ + ricos preservados. 23 cenários focados passaram." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0033.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0033.md new file mode 100644 index 0000000..bbce857 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0033.md @@ -0,0 +1,453 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "ACTIVE" + result: "Integrar anexos temporários, resultados mínimos e recuperação de descarte\ + \ após os checks dependentes." + evidence: [] + updatedAt: "2026-11-22T13:08:20.915778Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 33 +previousHash: "6ee53b10324a77c886e77ff889d54f35e6b573a229c3827836c7b92c8ff759c9" +updatedAt: "2026-11-22T13:08:20.915953Z" +updatedBy: "Codex" +changeReason: "Integrar anexos temporários, resultados mínimos e recuperação de descarte\ + \ após os checks dependentes." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0034.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0034.md new file mode 100644 index 0000000..b2e9a0b --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0034.md @@ -0,0 +1,474 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "ACTIVE" + result: "Integrar anexos temporários, resultados mínimos e recuperação de descarte\ + \ após os checks dependentes." + evidence: [] + updatedAt: "2026-11-22T13:08:20.915778Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 34 +previousHash: "527e8276dd84f7b24c72b909831977a045ca5f8f8cc710733a39c4406662e6df" +updatedAt: "2026-11-22T13:12:55.720974Z" +updatedBy: "Codex" +changeReason: "Provar a fronteira entre resultado persistido e arquivo temporario\ + \ antes da limpeza automatica." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "OPEN" + observation: null + interpretation: null + nextAction: null + evidence: [] + questionsDecision: null + finishedAt: null + finishedBy: null +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0035.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0035.md new file mode 100644 index 0000000..0e1960f --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0035.md @@ -0,0 +1,478 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "ACTIVE" + result: "Integrar anexos temporários, resultados mínimos e recuperação de descarte\ + \ após os checks dependentes." + evidence: [] + updatedAt: "2026-11-22T13:08:20.915778Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 35 +previousHash: "9ab0a0a63415c87df7fb8b7fae4fa1141190fe125e322d423e4f8e4b0c2b02f6" +updatedAt: "2026-11-22T13:16:14.087901Z" +updatedBy: "Codex" +changeReason: "32 cenários distintos focados passaram em duas rodadas." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0036.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0036.md new file mode 100644 index 0000000..a3659c6 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0036.md @@ -0,0 +1,480 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:13.390096Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 36 +previousHash: "b5b137e36f548e3e2b3e79c51f317f8b6d34a86637de3c9fb459d9589ecaddac" +updatedAt: "2026-11-22T13:16:27.036779Z" +updatedBy: "Codex" +changeReason: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado\ + \ e 32 cenários distintos passaram." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0037.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0037.md new file mode 100644 index 0000000..d40233d --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0037.md @@ -0,0 +1,481 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "ACTIVE" + result: "Adaptar consultas, contexto, status e diagnóstico de integridade ao SQLite\ + \ sem varredura global para ler um Work." + evidence: [] + updatedAt: "2026-11-22T13:16:40.765836Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 37 +previousHash: "80e71191e1c96555d747935774d05dbef8cdf58e405bb20281d8d2145e2546b4" +updatedAt: "2026-11-22T13:16:40.766019Z" +updatedBy: "Codex" +changeReason: "Adaptar consultas, contexto, status e diagnóstico de integridade ao\ + \ SQLite sem varredura global para ler um Work." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0038.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0038.md new file mode 100644 index 0000000..4f6e714 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0038.md @@ -0,0 +1,482 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:21.074969Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 38 +previousHash: "21edbd058479e7846f79a7244342c0813c38ce52129ffb34174e0e828cdd6eac" +updatedAt: "2026-11-22T13:23:23.963086Z" +updatedBy: "Codex" +changeReason: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0039.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0039.md new file mode 100644 index 0000000..5831cab --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0039.md @@ -0,0 +1,483 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "ACTIVE" + result: "Implementar prévia, migração explícita, comparação e recuperação somente\ + \ em fixtures descartáveis." + evidence: [] + updatedAt: "2026-11-22T13:23:38.291996Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 39 +previousHash: "c72704d869495ed44491a9992cf7ee1bba00c4225ed4456bbfd3de1f187b43ec" +updatedAt: "2026-11-22T13:23:38.292184Z" +updatedBy: "Codex" +changeReason: "Implementar prévia, migração explícita, comparação e recuperação somente\ + \ em fixtures descartáveis." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0040.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0040.md new file mode 100644 index 0000000..2ae0bcc --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0040.md @@ -0,0 +1,504 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "ACTIVE" + result: "Implementar prévia, migração explícita, comparação e recuperação somente\ + \ em fixtures descartáveis." + evidence: [] + updatedAt: "2026-11-22T13:23:38.291996Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 40 +previousHash: "17e0bf43f565c0c1b6c512729b0609f1d76991f486d5e7acde4011a7675054f2" +updatedAt: "2026-11-22T13:28:47.295686Z" +updatedBy: "Codex" +changeReason: "Verificar importacao tipada, guarda de compatibilidade e fronteiras\ + \ de recuperacao antes de disponibilizar conversao." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "OPEN" + observation: null + interpretation: null + nextAction: null + evidence: [] + questionsDecision: null + finishedAt: null + finishedBy: null +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0041.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0041.md new file mode 100644 index 0000000..2ca4263 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0041.md @@ -0,0 +1,507 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "ACTIVE" + result: "Implementar prévia, migração explícita, comparação e recuperação somente\ + \ em fixtures descartáveis." + evidence: [] + updatedAt: "2026-11-22T13:23:38.291996Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 41 +previousHash: "6d5f8ba4831db9324b1c4e6ff4f6bf283dca6ef081bd981814c1a21b1e311878" +updatedAt: "2026-11-22T13:38:19.181502Z" +updatedBy: "Codex" +changeReason: "Prova concluída somente com fixtures temporárias." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0042.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0042.md new file mode 100644 index 0000000..3e9b92b --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0042.md @@ -0,0 +1,509 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:28.841960Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 42 +previousHash: "274b0bb5aa666e95af61dd1a7052fa2c51fc915781a57e0ecaf4a9b45054c792" +updatedAt: "2026-11-22T13:38:32.272646Z" +updatedBy: "Codex" +changeReason: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34\ + \ testes finais passaram e originais preservados." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0043.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0043.md new file mode 100644 index 0000000..3f84da7 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0043.md @@ -0,0 +1,510 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "ACTIVE" + result: "Consolidar init SQLite, descoberta e estado ignorado por Git por padrã\ + o, sem converter projetos existentes." + evidence: [] + updatedAt: "2026-11-22T13:38:44.981612Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 43 +previousHash: "1e0da8a4c0a32c9d133491a34cdeb32e2a4b051339bb98a7ebe2c97ba13782d6" +updatedAt: "2026-11-22T13:38:44.981815Z" +updatedBy: "Codex" +changeReason: "Consolidar init SQLite, descoberta e estado ignorado por Git por padrã\ + o, sem converter projetos existentes." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0044.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0044.md new file mode 100644 index 0000000..f203c0d --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0044.md @@ -0,0 +1,511 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "COMPLETED" + result: "Init SQLite com estado ignorado por padrão, bootstrap preparado e compatibilidade\ + \ protegida; testes de init e continuidade entre processos passaram." + evidence: + - "ART-0011" + updatedAt: "2026-11-22T13:45:53.651201Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:37.290314Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 44 +previousHash: "151907451670bbfc311669ceb6a0a79b4682939a12a864dec04b8e94e16e171d" +updatedAt: "2026-11-22T13:45:53.651392Z" +updatedBy: "Codex" +changeReason: "Init SQLite com estado ignorado por padrão, bootstrap preparado e compatibilidade\ + \ protegida; testes de init e continuidade entre processos passaram." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0045.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0045.md new file mode 100644 index 0000000..6966571 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0045.md @@ -0,0 +1,512 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "COMPLETED" + result: "Init SQLite com estado ignorado por padrão, bootstrap preparado e compatibilidade\ + \ protegida; testes de init e continuidade entre processos passaram." + evidence: + - "ART-0011" + updatedAt: "2026-11-22T13:45:53.651201Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "ACTIVE" + result: "Preparar pacote conjunto e testar instalador somente em fixtures; não executar\ + \ instalação real." + evidence: [] + updatedAt: "2026-11-22T13:46:10.209963Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 45 +previousHash: "0dcd4f68fe3ac6518bd27ba33166be75f5c73ed08ee3f14192f17bdfcb49db85" +updatedAt: "2026-11-22T13:46:10.210164Z" +updatedBy: "Codex" +changeReason: "Preparar pacote conjunto e testar instalador somente em fixtures; nã\ + o executar instalação real." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0046.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0046.md new file mode 100644 index 0000000..b807112 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0046.md @@ -0,0 +1,513 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "COMPLETED" + result: "Init SQLite com estado ignorado por padrão, bootstrap preparado e compatibilidade\ + \ protegida; testes de init e continuidade entre processos passaram." + evidence: + - "ART-0011" + updatedAt: "2026-11-22T13:45:53.651201Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "COMPLETED" + result: "Pacote AIE+SQLite preparado e verificado em build; 17 fixtures do instalador\ + \ passaram, sem executar instalação real." + evidence: + - "ART-0012" + updatedAt: "2026-11-22T13:51:41.443318Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:45.331995Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 46 +previousHash: "229c64b34a967eaeebfd73a2f70272edacb103d523af6c11424101e79c0858ce" +updatedAt: "2026-11-22T13:51:41.443536Z" +updatedBy: "Codex" +changeReason: "Pacote AIE+SQLite preparado e verificado em build; 17 fixtures do instalador\ + \ passaram, sem executar instalação real." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0047.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0047.md new file mode 100644 index 0000000..5991fba --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0047.md @@ -0,0 +1,514 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "COMPLETED" + result: "Init SQLite com estado ignorado por padrão, bootstrap preparado e compatibilidade\ + \ protegida; testes de init e continuidade entre processos passaram." + evidence: + - "ART-0011" + updatedAt: "2026-11-22T13:45:53.651201Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "COMPLETED" + result: "Pacote AIE+SQLite preparado e verificado em build; 17 fixtures do instalador\ + \ passaram, sem executar instalação real." + evidence: + - "ART-0012" + updatedAt: "2026-11-22T13:51:41.443318Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "ACTIVE" + result: "Consolidar documentação do framework local, gates, retenção e migração\ + \ pública." + evidence: [] + updatedAt: "2026-11-22T13:51:54.874434Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 47 +previousHash: "239335c7fa0efbd3c3a695854ff1d80be394076c540e028bc09eb0169a13d9a8" +updatedAt: "2026-11-22T13:51:54.874627Z" +updatedBy: "Codex" +changeReason: "Consolidar documentação do framework local, gates, retenção e migraç\ + ão pública." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0048.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0048.md new file mode 100644 index 0000000..0564d31 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0048.md @@ -0,0 +1,515 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "COMPLETED" + result: "Init SQLite com estado ignorado por padrão, bootstrap preparado e compatibilidade\ + \ protegida; testes de init e continuidade entre processos passaram." + evidence: + - "ART-0011" + updatedAt: "2026-11-22T13:45:53.651201Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "COMPLETED" + result: "Pacote AIE+SQLite preparado e verificado em build; 17 fixtures do instalador\ + \ passaram, sem executar instalação real." + evidence: + - "ART-0012" + updatedAt: "2026-11-22T13:51:41.443318Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "COMPLETED" + result: "Documentação e bootstrap alinhados ao framework local; links e testes de\ + \ init/compatibilidade/guidance passaram." + evidence: + - "ART-0013" + updatedAt: "2026-11-22T13:58:06.665430Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "OPEN" + result: "" + evidence: [] + updatedAt: "2026-11-22T11:53:53.421052Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 48 +previousHash: "59e71bdc2e0b20d9c4b521f16fbfd606dae15be94bc413fa385232aad095c80e" +updatedAt: "2026-11-22T13:58:06.665628Z" +updatedBy: "Codex" +changeReason: "Documentação e bootstrap alinhados ao framework local; links e testes\ + \ de init/compatibilidade/guidance passaram." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0049.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0049.md new file mode 100644 index 0000000..1f5604f --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0049.md @@ -0,0 +1,516 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "COMPLETED" + result: "Init SQLite com estado ignorado por padrão, bootstrap preparado e compatibilidade\ + \ protegida; testes de init e continuidade entre processos passaram." + evidence: + - "ART-0011" + updatedAt: "2026-11-22T13:45:53.651201Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "COMPLETED" + result: "Pacote AIE+SQLite preparado e verificado em build; 17 fixtures do instalador\ + \ passaram, sem executar instalação real." + evidence: + - "ART-0012" + updatedAt: "2026-11-22T13:51:41.443318Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "COMPLETED" + result: "Documentação e bootstrap alinhados ao framework local; links e testes de\ + \ init/compatibilidade/guidance passaram." + evidence: + - "ART-0013" + updatedAt: "2026-11-22T13:58:06.665430Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "ACTIVE" + result: "Executar regressão integrada, smoke nativo e handoff de responsividade\ + \ ao WRK-000C sem instalar ou migrar projetos reais." + evidence: [] + updatedAt: "2026-11-22T13:58:22.322521Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 49 +previousHash: "9a9e1860f5f73b097bca590a2e6022e0107bc7d41a681e5b1ea35a3c31fdd0e6" +updatedAt: "2026-11-22T13:58:22.322716Z" +updatedBy: "Codex" +changeReason: "Executar regressão integrada, smoke nativo e handoff de responsividade\ + \ ao WRK-000C sem instalar ou migrar projetos reais." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0050.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0050.md new file mode 100644 index 0000000..4bad270 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/.history/PLN-0001/r0050.md @@ -0,0 +1,519 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "COMPLETED" + result: "Init SQLite com estado ignorado por padrão, bootstrap preparado e compatibilidade\ + \ protegida; testes de init e continuidade entre processos passaram." + evidence: + - "ART-0011" + updatedAt: "2026-11-22T13:45:53.651201Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "COMPLETED" + result: "Pacote AIE+SQLite preparado e verificado em build; 17 fixtures do instalador\ + \ passaram, sem executar instalação real." + evidence: + - "ART-0012" + updatedAt: "2026-11-22T13:51:41.443318Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "COMPLETED" + result: "Documentação e bootstrap alinhados ao framework local; links e testes de\ + \ init/compatibilidade/guidance passaram." + evidence: + - "ART-0013" + updatedAt: "2026-11-22T13:58:06.665430Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "COMPLETED" + result: "Regressão integrada passou: 230 testes no check, 17 focados finais, 17\ + \ fixtures do instalador e smoke nativo completo; pacote verificado e WRK-000C\ + \ encaminhado. Sem instalação ou migração real." + evidence: + - "ART-0014" + updatedAt: "2026-11-22T14:23:10.284465Z" +status: "ACTIVE" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 50 +previousHash: "0fc20d8c12d3dabc6e0fa2f67bee2d1524b623d0eada712f53e9f54d847fd346" +updatedAt: "2026-11-22T14:23:10.284654Z" +updatedBy: "Codex" +changeReason: "Regressão integrada passou: 230 testes no check, 17 focados finais,\ + \ 17 fixtures do instalador e smoke nativo completo; pacote verificado e WRK-000C\ + \ encaminhado. Sem instalação ou migração real." +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/PLN-0001.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/PLN-0001.md new file mode 100644 index 0000000..4a2a4a0 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/plans/PLN-0001.md @@ -0,0 +1,517 @@ +--- +schemaVersion: 1 +id: "PLN-0001" +workId: "WRK-000D" +title: "Implementar memória de engenharia local em SQLite sem instalação ativa" +decisions: +- "DEC-0001" +steps: +- id: "TSK-0001" + title: "Mapear contrato, dados legados e cenários de migração" + description: "Inspecionar WorkService, serviços de Discussion/Decision/Plan/Agent,\ + \ coordenadores e VerificationService. Mapear registros, referências, revisões,\ + \ hashes, recibos e bootstrap para tabelas e regras do backend SQLite, preservando\ + \ conteúdo e autoridade. Selecionar fixtures existentes de compatibilidade, workflows\ + \ e importação como corpus; usar apenas cópias descartáveis. Identificar checks\ + \ e pontos de retenção sem realizar benchmark conclusivo do WRK-000C." + acceptanceCriteria: + - "Mapeamento cobre entidades persistidas, IDs locais ao Work, referências, revisõ\ + es, aprovações e casos de conclusão legada com hashes/recibos." + - "Corpus representativo e resultados esperados de continuidade/migração estão definidos\ + \ antes da conversão, incluindo dados inválidos e estados interrompidos." + - "Limites de instalação, migração de consumidores e preservação do workspace atual\ + \ estão explícitos e respeitados." + dependsOn: [] + status: "COMPLETED" + result: "Contrato e legado mapeados em docs/sqlite-migration-design.md; corpus e\ + \ casos de falha/retry definidos antes da migração. Baseline: 45 testes em seis\ + \ classes passaram, hashes congelados conferidos e fontes históricas intactas.\ + \ Sem instalação ou migração real." + evidence: + - "ART-0001" + updatedAt: "2026-11-22T12:00:26.700050Z" +- id: "TSK-0002" + title: "Provar driver SQLite em JVM e Native Image" + description: "Avaliar Xerial SQLite JDBC e fixar versão compatível com Java, Gradle\ + \ e GraalVM do projeto. Registrar hipótese, critério e invocação antes da prova.\ + \ Criar, gravar, ler e reabrir uma base descartável em processos JVM e nativos.\ + \ Verificar carregamento da biblioteca distribuída ao lado do nativo; sqlite3\ + \ será ferramenta de diagnóstico do pacote. Construir e executar somente artefatos\ + \ descartáveis, sem instalação real." + acceptanceCriteria: + - "Driver e versão selecionados demonstram persistência e reabertura em JVM e Native\ + \ Image na plataforma alvo." + - "Biblioteca do pacote é encontrada por caminho controlado e não depende acidentalmente\ + \ do SQLite global ou de extração repetida não planejada." + - "Hipótese, resultado e limitações da prova estão registrados; instalação ativa\ + \ e projetos consumidores não foram alterados." + dependsOn: + - "TSK-0001" + status: "COMPLETED" + result: "Prova JVM e Native Image passou create/read/write/reopen, UTF-8, rollback\ + \ e dependência da biblioteca do pacote; sem instalação ativa." + evidence: + - "ART-0002" + updatedAt: "2026-11-22T12:16:52.149066Z" +- id: "TSK-0003" + title: "Implementar esquema, conexões e transações SQLite" + description: "Criar infraestrutura de persistência local em .ai-engineering/aie.db\ + \ com esquema versionado, tabelas tipadas, índices e relações. Habilitar integridade\ + \ referencial em cada conexão, delimitar unidade transacional por operação coerente\ + \ e usar leitura consistente. Definir journal/durabilidade e espera limitada de\ + \ escrita com diagnóstico. Preservar limites de módulos; serviços aninhados devem\ + \ compartilhar a transação aplicável." + acceptanceCriteria: + - "Esquema e índices atendem ao mapeamento sem BLOB/base64 ou arquivos completos\ + \ serializados em TEXT." + - "Falha em operação relacionada causa rollback; referências inválidas são recusadas\ + \ e gravações concorrentes têm contenção limitada e diagnóstico útil." + - "Abertura de esquema incompatível é diagnosticada sem alterar dados; teste de\ + \ leitura consistente cobre mudanças concorrentes locais." + dependsOn: + - "TSK-0001" + - "TSK-0002" + status: "COMPLETED" + result: "Infraestrutura SQLite validada: 12 testes de transação/integridade/concorrê\ + ncia e arquitetura passaram; schema também criado e reaberto pelo Native Image.\ + \ CLI de domínio e instalação ativa continuam intactos." + evidence: + - "ART-0003" + updatedAt: "2026-11-22T12:26:10.846492Z" +- id: "TSK-0004" + title: "Persistir Works e investigação no novo backend" + description: "Integrar Work, guidance e histórico de escolhas, discussões, tópicos,\ + \ surveys, respostas e disposições à unidade de persistência. Preservar IDs existentes,\ + \ semântica dos IDs locais, referências e histórico útil. Consultas selecionadas\ + \ devem buscar o Work diretamente. Manter leitura legada delimitada para compatibilidade\ + \ e migração; não manter duas fontes autoritativas para a mesma memória." + acceptanceCriteria: + - "Criar e retomar Work/discussão/survey em outro processo preserva conteúdo, histó\ + rico de respostas e pendências." + - "Escolhas DIRECT/EXPLORATORY e autoridade humana mantêm as regras existentes,\ + \ inclusive ausência de escolha e pedido específico de DEC." + - "Busca por Work e suas referências usa consultas com escopo adequado; alteraçõ\ + es e referências relacionadas são transacionais." + dependsOn: + - "TSK-0003" + status: "COMPLETED" + result: "Works/investigação SQLite passaram 45 testes e retomada em outro JVM e\ + \ nativo; referências transacionais, histórico e autoridade preservados." + evidence: + - "ART-0004" + updatedAt: "2026-11-22T12:43:38.166159Z" +- id: "TSK-0005" + title: "Persistir decisões, planos e experimentos" + description: "Integrar DecisionService e PlanService com revisões, aceitação, supersessã\ + o, passos, dependências e experimentos. Preservar os dois ciclos e OODA, a autoridade\ + \ de DEC/Plan e a distinção entre aprovação humana e promoção permitida por polí\ + tica. Tratar operações que alteram registros relacionados em uma transação, sem\ + \ reduzir os checks de domínio." + acceptanceCriteria: + - "Aprovação, revisão e supersessão preservam autoria e referências, sem fabricaç\ + ão de aprovação ou edição silenciosa de decisão aceita." + - "Dependências e estados de passos, critérios de experimentos, preocupações com\ + \ DEC e replanejamento conservam os bloqueios existentes." + - "Interrupção simulada não publica meia supersessão ou promoção parcial; retomada\ + \ em outro processo preserva o contexto." + dependsOn: + - "TSK-0004" + status: "COMPLETED" + result: "Decisões/Plans/experimentos SQLite preservam autoridade, revisão, dependê\ + ncias e rollback conjunto; 34 cenários distintos selecionados passaram ao final\ + \ após ajuste textual de um teste." + evidence: + - "ART-0005" + updatedAt: "2026-11-22T12:54:10.341537Z" +- id: "TSK-0006" + title: "Integrar execuções de agentes e coordenação de EPICs" + description: "Persistir RUNs e seus dados operacionais mínimos, idempotência de\ + \ requestId, referências aplicadas e diagnóstico. Integrar PlanCoordinator/EpicCoordinator,\ + \ políticas e proveniência de conclusão, representando recibos internos como dados\ + \ estruturados quando aplicável. Preservar a fronteira do adaptador: propostas\ + \ não aprovam DEC, não respondem pelo humano nem executam comandos de repositó\ + rio." + acceptanceCriteria: + - "Repetição idempotente de uma solicitação concluída não duplica registros; solicitaç\ + ões divergentes e estados interrompidos são diagnosticados." + - "Políticas RESULTS/DECOMPOSITION, delegação, reabertura, propagação e conclusã\ + o por Plans preservam autoridade e proveniência." + - "Resultados estruturados necessários permanecem; transporte bruto, ambiente e\ + \ logs completos não viram acervo permanente no banco." + dependsOn: + - "TSK-0005" + status: "COMPLETED" + result: "RUNs/EPICs persistidos e coordenação preservada; 30 cenários distintos\ + \ passaram, incluindo rollback integral e idempotência." + evidence: + - "ART-0006" + updatedAt: "2026-11-22T13:02:08.858215Z" +- id: "TSK-0007" + title: "Integrar gates do projeto e adicionais por Work" + description: "Representar gates obrigatórios do projeto e complementos do Work e\ + \ conectar seus resultados aos checks e à entrega. Preservar avaliação externa\ + \ e condições de qualidade, inclusive anexos exigidos. Registrar identificaçã\ + o, procedimento/execução, estado avaliado, momento e resultado mínimo. Alteraç\ + ões pertinentes invalidam a aplicação do resultado aos gates afetados; aprovaç\ + ão humana não equivale a sucesso técnico." + acceptanceCriteria: + - "Gate obrigatório pendente, falho ou não executado bloqueia a entrega; gates adicionais\ + \ do Work são considerados sem dispensar obrigatórios do projeto." + - "Resultados correspondem ao estado realmente avaliado e não satisfazem silenciosamente\ + \ um gate após mudança relevante." + - "Checks existentes e anexos necessários continuam exigidos durante avaliação,\ + \ sem introduzir executor autônomo ou retenção bruta obrigatória." + dependsOn: + - "TSK-0005" + - "TSK-0006" + status: "COMPLETED" + result: "Gates cumulativos bloqueiam entrega sem PASS atual; snapshots históricos\ + \ preservados. 23 cenários focados passaram." + evidence: + - "ART-0007" + updatedAt: "2026-11-22T13:08:08.952170Z" +- id: "TSK-0008" + title: "Implementar anexos temporários e descarte após checks" + description: "Definir ciclo de vida de anexos e arquivos de execução no filesystem.\ + \ Publicar arquivos completos, validar e registrar resultados mínimos antes do\ + \ descarte; limpar elegíveis ao fim da execução. Proteger anexos ainda usados\ + \ por checks pendentes e outputs solicitados. Recuperar falhas entre publicaçã\ + o de arquivo, transação no banco e limpeza, distinguindo descarte legítimo de\ + \ perda prematura. Não descartar artefatos legados deste workspace." + acceptanceCriteria: + - "Arquivos exigidos permanecem acessíveis até todos os checks dependentes terminarem,\ + \ com resultado persistido antes da remoção." + - "Descarte automático preserva outputs solicitados e memória histórica; arquivo\ + \ perdido antes da avaliação continua causando falha." + - "Interrupções nos pontos de publicação, registro e limpeza não fabricam sucesso\ + \ e permitem recuperação sem remoção de entradas ainda necessárias." + dependsOn: + - "TSK-0007" + status: "COMPLETED" + result: "Anexos temporários e recibos tipados integrados; EXP-0002 confirmado e\ + \ 32 cenários distintos passaram." + evidence: + - "ART-0008" + updatedAt: "2026-11-22T13:16:27.036583Z" +- id: "TSK-0009" + title: "Adaptar verificação, status e contexto ao SQLite" + description: "Integrar VerificationService, CompatibilityService e projeções da\ + \ CLI ao backend. Montar status, next-actions, context e readiness com consultas\ + \ necessárias e resultados reutilizados na invocação; preservar contrato público\ + \ quando compatível e informar mudanças. Separar resultado histórico com anexo\ + \ descartado legitimamente de validação ativa. Manter diagnóstico de reparo e\ + \ ausência de transições de estado em consultas." + acceptanceCriteria: + - "Consultas e contexto em processos novos preservam informações e autoridade e\ + \ não promovem, migram ou concluem registros por leitura." + - "Anexos descartados legitimamente não invalidam histórico; corrupção e referê\ + ncias ausentes não são tratadas como gates satisfeitos." + - "Caminhos selecionados não repetem varreduras/validações globais sem necessidade;\ + \ saída e códigos de erro compatíveis são verificados." + dependsOn: + - "TSK-0004" + - "TSK-0005" + - "TSK-0006" + - "TSK-0008" + status: "COMPLETED" + result: "Consultas e verificação usam SQLite e snapshots consistentes; 15 testes\ + \ focados passaram e compatibilidade legada preservada." + evidence: + - "ART-0009" + updatedAt: "2026-11-22T13:23:23.962895Z" +- id: "TSK-0010" + title: "Implementar migração explícita e recuperável do legado" + description: "Criar comando público de prévia e aplicação da migração, sem conversã\ + o em leituras ou atualização do instalador. Usar base de preparo e cópia de seguranç\ + a da conversão, importação tipada transacional e verificação contra o corpus.\ + \ Preservar IDs, conteúdo, aprovações, hashes, revisões e proveniência histórica\ + \ sem despejar arquivos no banco. Ativar somente após sucesso; repetir ou recuperar\ + \ interrupção sem duplicar. Executar apenas em fixtures/cópias descartáveis." + acceptanceCriteria: + - "Prévia não modifica o projeto; aplicação compara registros/contexto e ativa a\ + \ base somente após validação completa." + - "Fixtures históricas, recibos, aprovações e referências preservam identidade/proveniê\ + ncia; execução repetida não duplica conteúdo." + - "Falhas e interrupções deixam a fonte anterior recuperável e informam próxima\ + \ ação; nenhum projeto real ou workspace canônico foi migrado." + dependsOn: + - "TSK-0001" + - "TSK-0009" + status: "COMPLETED" + result: "Migração explícita e recuperável validada; EXP-0003 confirmado, 34 testes\ + \ finais passaram e originais preservados." + evidence: + - "ART-0010" + updatedAt: "2026-11-22T13:38:32.272456Z" +- id: "TSK-0011" + title: "Atualizar init, descoberta e contrato de compatibilidade" + description: "Inicializar projetos locais em SQLite e deixar .ai-engineering ignorado\ + \ pelo Git por padrão sem exigir Git. Preservar regras preexistentes e instruç\ + ões fora do bloco gerido. Declarar backend e versões no contrato público, atualizar\ + \ diagnóstico/onboard e evitar que base SQLite seja interpretada como workspace\ + \ vazio por combinação incompatível. Manter tratamento explícito de projetos legados\ + \ e previamente rastreados." + acceptanceCriteria: + - "Init cria projeto funcional sem Git, com estado local ignorado por padrão e bootstrap\ + \ suficiente para humanos e agentes." + - "Reexecução preserva conteúdo/regras; não remove arquivos já rastreados nem converte\ + \ legado automaticamente." + - "Versões e backend incompatíveis são recusados com diagnóstico acionável antes\ + \ de escrita; documentação/entrypoints não induzem uso de CLI incompatível." + dependsOn: + - "TSK-0009" + - "TSK-0010" + status: "COMPLETED" + result: "Init SQLite com estado ignorado por padrão, bootstrap preparado e compatibilidade\ + \ protegida; testes de init e continuidade entre processos passaram." + evidence: + - "ART-0011" + updatedAt: "2026-11-22T13:45:53.651201Z" +- id: "TSK-0012" + title: "Preparar pacote nativo e instalador conjunto sem ativação" + description: "Evoluir build/distribuição e scripts/install-native.sh para empacotar\ + \ AIE nativo, biblioteca SQLite do driver e CLI sqlite3 num diretório configurá\ + vel, com atalhos aie/ai-engineering e dados de projeto separados. Fixar componentes/plataformas\ + \ e verificar pacote antes de ativação, preservando versão anterior em falhas.\ + \ Testar instalador com ferramentas simuladas e destinos descartáveis; smoke usa\ + \ build local. Não executar instalação real nem tocar ~/.local/bin ou dependê\ + ncias ativas." + acceptanceCriteria: + - "Pacote contém componentes corretos e o build nativo acessa uma base descartá\ + vel sem depender da instalação global." + - "Fixtures verificam diretórios configuráveis, atalhos, atualização conjunta e\ + \ falha sem danificar instalação anterior simulada." + - "Nenhum binário, biblioteca ou atalho ativo é substituído e o instalador real\ + \ não é executado; a ativação posterior continua dependente de instrução humana." + dependsOn: + - "TSK-0002" + - "TSK-0011" + status: "COMPLETED" + result: "Pacote AIE+SQLite preparado e verificado em build; 17 fixtures do instalador\ + \ passaram, sem executar instalação real." + evidence: + - "ART-0012" + updatedAt: "2026-11-22T13:51:41.443318Z" +- id: "TSK-0013" + title: "Consolidar documentação e instruções do framework local" + description: "Atualizar README, docs de arquitetura/protocolo/compatibilidade/migraç\ + ão e recursos de entrada para memória local, SQLite, gates e retenção mínima.\ + \ Explicar anexos temporários, outputs entregues, migração explícita e recuperaç\ + ão, pacote preparado e instalação adiada. Remover instruções que apresentem arquivos\ + \ de Works como fonte principal nova ou Git como exigência. Preservar orientaç\ + ões dos dois ciclos, OODA, DEC/Plan e aprovações." + acceptanceCriteria: + - "Documentação e recursos distribuídos descrevem o mesmo contrato e permitem inicializar/retomar\ + \ um projeto sem Git." + - "Procedimento público de migração explica prévia, efeitos e recuperação sem depender\ + \ de inspeção do código interno." + - "Limites de retenção e instalação, papel dos gates e recortes futuros estão claros;\ + \ fontes e exemplos não alegam testes ou migrações reais não executados." + dependsOn: + - "TSK-0010" + - "TSK-0011" + - "TSK-0012" + status: "COMPLETED" + result: "Documentação e bootstrap alinhados ao framework local; links e testes de\ + \ init/compatibilidade/guidance passaram." + evidence: + - "ART-0013" + updatedAt: "2026-11-22T13:58:06.665430Z" +- id: "TSK-0014" + title: "Executar regressão integrada e encaminhar responsividade ao WRK-000C" + description: "Integrar as verificações das etapas e executar gates apropriados de\ + \ testes/arquitetura, migração, concorrência e smoke JVM/nativo em ambientes descartá\ + veis. Revisar continuidade e autoridade nos dois ciclos, anexos temporários, recuperaç\ + ão e funcionamento sem Git. Consolidar resultados mínimos, resolver experimentos/preocupaç\ + ões e entregar cenário reproduzível ao WRK-000C com comandos, versão, dados e\ + \ ambiente. Não instalar o pacote nem declarar resolvido o atraso." + acceptanceCriteria: + - "Suíte relevante de domínio/integração/compatibilidade, fixtures do instalador\ + \ e smoke nativo passam ou impedimentos são tratados antes da conclusão." + - "Falhas, rollback, concorrência, legado, gates e descarte legítimo foram verificados\ + \ com resultados reais e sem alteração da instalação ativa ou consumidores." + - "Todos os steps e critérios da DEC estão satisfeitos, sem experimentos/preocupaç\ + ões pendentes; WRK-000C recebe cenário para medição futura e permanece aberto." + dependsOn: + - "TSK-0013" + status: "COMPLETED" + result: "Regressão integrada passou: 230 testes no check, 17 focados finais, 17\ + \ fixtures do instalador e smoke nativo completo; pacote verificado e WRK-000C\ + \ encaminhado. Sem instalação ou migração real." + evidence: + - "ART-0014" + updatedAt: "2026-11-22T14:23:10.284465Z" +status: "COMPLETED" +author: "Codex" +createdAt: "2026-11-22T11:52:06.993736Z" +revision: 51 +previousHash: "0cebb53e05375ec0a5c052c04834ea5ae8ddca2bdb808eb093704474fe1ced86" +updatedAt: "2026-11-22T14:23:16.315099Z" +updatedBy: "system:plans" +changeReason: "All required steps completed; reviewed cancellations retained" +experiments: +- id: "EXP-0001" + stepId: "TSK-0002" + hypothesis: "SQLite JDBC pode criar, persistir e reabrir uma base em processos JVM\ + \ e Native Image com biblioteca distribuída ao lado do executável." + successCriterion: "As duas formas executam create/read/write/reopen e rollback em\ + \ diretório descartável; o nativo usa a biblioteca do pacote com extração temporá\ + ria indisponível; nenhum binário ativo ou consumidor é alterado." + invocation: "./gradlew sqliteProbeClasses nativeSqliteProbeCompile; scripts/sqlite-probe.sh\ + \ ; execução da classe de prova JVM e do binário de build em processos\ + \ distintos" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T12:10:00.110720Z" + outcome: "CONFIRMED" + observation: "JVM criou e reabriu a base com UTF-8 e rollback. Native Image GraalVM\ + \ 25 criou e reabriu em processos independentes com biblioteca externa e extraç\ + ão sem escrita; a cópia isolada sem biblioteca falhou." + interpretation: "Driver SQLite JDBC 3.54.1.0 e biblioteca distribuída ao lado do\ + \ nativo funcionam na plataforma macOS arm64. Seleção inicial de JDK foi corrigida\ + \ explicitamente; sem instalação real." + nextAction: "Implementar infraestrutura transacional e esquema local no TSK-0003." + evidence: + - "ART-0002" + questionsDecision: null + finishedAt: "2026-11-22T12:16:43.109268Z" + finishedBy: "Codex" +- id: "EXP-0002" + stepId: "TSK-0008" + hypothesis: "Anexos temporarios podem ser descartados apos a conclusao sem perder\ + \ resultados historicos ou aceitar entradas ausentes em novos checks." + successCriterion: "Fixtures confirmam retencao durante checks, limpeza apos commit,\ + \ rollback sem apagar entradas, recuperacao de descarte interrompido e recusa\ + \ de evidencia perdida ou aposentada em avaliacao atual." + invocation: "./gradlew test --tests *SqliteArtifactLifecycleTest --tests *SqliteCoordinationTest\ + \ --tests *SqliteQualityGatesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:12:55.720771Z" + outcome: "CONFIRMED" + observation: "Fixtures passaram retenção durante checks, descarte após commit, rollback\ + \ e recuperação de interrupções; entrada perdida ou aposentada não satisfaz avaliaç\ + ão atual." + interpretation: "Resultado estruturado e estado de descarte permitem retenção mí\ + nima sem enfraquecer entradas obrigatórias. Originais legados preservados." + nextAction: "Integrar consultas, verificação e compatibilidade ao backend SQLite\ + \ no TSK-0009." + evidence: + - "ART-0008" + questionsDecision: null + finishedAt: "2026-11-22T13:16:14.087721Z" + finishedBy: "Codex" +- id: "EXP-0003" + stepId: "TSK-0010" + hypothesis: "Migracao explicita com base preparada e originais preservados conserva\ + \ hashes e autoridade, e recupera falhas sem duplicar dados." + successCriterion: "Corpus legado e Works ativos preservam DTOs, hashes, aprovacoes\ + \ e historicos; fixtures interrompidas retomam ou revertem com seguranca; escrita\ + \ nova impede rollback destrutivo." + invocation: "./gradlew test --tests *StorageMigrationTest --tests *CompatibilityTest\ + \ --tests *SqliteQueriesTest" + retryOf: null + reconsideration: null + by: "Codex" + createdAt: "2026-11-22T13:28:47.295494Z" + outcome: "CONFIRMED" + observation: "Após corrigir presença de listas nulas e limpeza de staging, 34 testes\ + \ finais passaram; cinco fronteiras recuperadas e hashes históricos preservados." + interpretation: "Importação tipada com fontes externas e ativação protegida conserva\ + \ autoridade e permite recuperação sem duplicação; novas gravações impedem rollback\ + \ com perda." + nextAction: "Consolidar init SQLite e contrato de armazenamento local no TSK-0011." + evidence: + - "ART-0010" + questionsDecision: null + finishedAt: "2026-11-22T13:38:19.181293Z" + finishedBy: "Codex" +documentVersion: 2 +--- + +# Implementar memória de engenharia local em SQLite + +## Autoridade e objetivo + +Executar a DEC-0001 do WRK-000D, aceita explicitamente por Nilton nesta conversa. +O resultado é um framework local de memória de engenharia por Work, com SQLite +por projeto, investigação e implementação orientadas por OODA, gates preservados, +anexos temporários e retenção mínima. A aprovação desta DEC mantém a instalação +real adiada. + +Este Plan foi solicitado com decomposição em vários steps. Todos os steps começam +OPEN; a criação do Plan não constitui execução ou comprovação de resultado. + +## Limites obrigatórios + +- Não instalar nem substituir o AIE, SQLite, bibliotecas ou atalhos em uso. +- Não executar o instalador real contra HOME, ~/.local/bin ou outro destino ativo. + Sua validação usa fixtures com ferramentas simuladas e destinos descartáveis. +- Não migrar este workspace canônico ou projetos consumidores. Exercitar o novo + backend e a migração em fixtures e cópias descartáveis; ativação real depende de + instrução humana posterior específica. +- Preservar alterações preexistentes, IDs, conteúdo e proveniência legada, + aprovações, evidências históricas e instruções do projeto fora do bloco gerido. +- Não introduzir arquivos em BLOB/base64 ou TEXT equivalente, retenção extensa, + executor autônomo de repositório, colaboração distribuída ou integração Git LFS. +- Importação/exportação de Works/DECs e backup como funcionalidade ficam fora. + A cópia de segurança da migração é parte da recuperação da conversão. +- Código e outputs solicitados permanecem nos destinos de entrega apropriados. +- O WRK-000C permanece aberto para avaliar e tratar latência após esta mudança. + +## Execução e dependências + +Os 14 steps possuem dependências explícitas e critérios próprios. Mapear primeiro +o contrato e o legado; provar a integração SQLite/JVM/Native Image; depois construir +as transações e migrar os fluxos de domínio. Integrar gates e ciclo dos anexos antes +de consolidar as consultas, a migração pública e o bootstrap. Preparar distribuição +e documentação e concluir com regressão integrada e encaminhamento ao WRK-000C. + +Não iniciar um step com dependências pendentes. Verificações focadas fazem parte +de cada mudança; a última etapa integra os cenários e não substitui essas verificações. +Steps independentes podem ser executados em ordem compatível, sem presumir +autorização de delegação ou de instalação real. + +## OODA e incertezas + +Nas provas relevantes, principalmente driver/nativo, migração e descarte de anexos, +registrar hipótese, critério de sucesso e invocação antes de executar. Registrar +observação, interpretação e próxima ação após o resultado; reconsiderar antes de +repetir uma hipótese falha. Usar os registros de experimentos do Plan quando úteis, +sem impor um ritual de quatro fases a toda alteração. + +Ajustar esquema, índices, transações e build dentro da DEC. Se um resultado +questionar a decisão, registrar a preocupação, continuar investigações autorizadas +e rever a DEC com aprovação aplicável antes da execução afetada. + +## Verificação e registro mínimo + +Durante a execução deste Work, respeitar o protocolo que está em uso. Registrar +resultados reais e evidência mínima necessária para completar os steps; não usar +a futura política de limpeza para apagar evidências legadas ou simular gates. + +Verificar continuidade entre processos, integridade referencial, rollback, +concorrência local com espera limitada, autoridade humana, gates e anexos +temporários, migração repetível e operação sem Git. Provas nativas usam somente +artefatos de build e projetos descartáveis. + +Comandos candidatos à validação, ajustados ao resultado e ao código final: + +- `./gradlew test` e `./gradlew check` para a suíte e arquitetura do projeto. +- `python3 scripts/test-install-native.py` para fixtures do instalador. +- `./gradlew nativeCompile` e tarefas de distribuição para construir o pacote. +- `bash scripts/native-smoke.sh ` em projetos descartáveis. + +Esses comandos são planejados, não executados na criação do Plan. Preservar os +gates específicos do projeto e adicionais do Work definidos na execução. Logs de +trabalho podem ser temporários; guardar na memória somente o necessário ao contrato. + +## Conclusão + +Todos os steps obrigatórios devem satisfazer seus critérios, com a DEC aceita e +sem experimentos ou preocupações pendentes. A entrega é código, documentação, +pacote preparado e resultados de verificação. Não depende de instalar a nova +versão no ambiente em uso. Encaminhar ao WRK-000C um cenário reproduzível com +comandos, versão, volume e ambiente, sem declarar resolvido o problema de atraso. diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0001.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0001.md new file mode 100644 index 0000000..e5a36e8 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0001.md @@ -0,0 +1,18 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: [] +answers: [] +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 1 +previousHash: null +updatedAt: "2026-11-22T10:55:44.572670Z" +updatedBy: "Codex" +changeReason: "Survey created" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0002.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0002.md new file mode 100644 index 0000000..86ad774 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0002.md @@ -0,0 +1,33 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +answers: [] +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 2 +previousHash: "297495eaab6cc6b03aadc0b9fa0a393202ef7257e0dd798e01ef1340112beec7" +updatedAt: "2026-11-22T10:55:45.429247Z" +updatedBy: "Codex" +changeReason: "Question added" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0003.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0003.md new file mode 100644 index 0000000..e4628c3 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0003.md @@ -0,0 +1,47 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quais outputs de uma execução devem ser preservados como artefatos duráveis,\ + \ além das evidências já utilizadas por decisões e entregas?" + options: + - id: "1" + text: "Reter explicitamente os outputs úteis e as evidências utilizadas; os demais\ + \ outputs continuam temporários." + - id: "2" + text: "Reter automaticamente os outputs finais declarados por cada execução; manter\ + \ logs intermediários temporários." + multiple: false + recommendedOption: "1" + sources: [] +answers: [] +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 3 +previousHash: "c0298111c82da3c10c12b71b01ae1462c07bf0a7d3b2c4c08ca1e32d034007f6" +updatedAt: "2026-11-22T10:55:46.297660Z" +updatedBy: "Codex" +changeReason: "Question added" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0004.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0004.md new file mode 100644 index 0000000..5238099 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0004.md @@ -0,0 +1,61 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quais outputs de uma execução devem ser preservados como artefatos duráveis,\ + \ além das evidências já utilizadas por decisões e entregas?" + options: + - id: "1" + text: "Reter explicitamente os outputs úteis e as evidências utilizadas; os demais\ + \ outputs continuam temporários." + - id: "2" + text: "Reter automaticamente os outputs finais declarados por cada execução; manter\ + \ logs intermediários temporários." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Como tratar a limpeza dos arquivos temporários de execução, sem afetar artefatos\ + \ duráveis, evidências ou histórico?" + options: + - id: "1" + text: "Limpeza explícita por comando, com prévia do que será removido e proteç\ + ão das referências duráveis." + - id: "2" + text: "Limpeza automática com prazo configurável, aplicada exclusivamente a temporá\ + rios sem referências duráveis e fora de execuções ativas." + multiple: false + recommendedOption: "1" + sources: [] +answers: [] +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 4 +previousHash: "91ef14ee4c7884ff099d721bc497f5ce11285f108806e9540beccf5d96406cd1" +updatedAt: "2026-11-22T10:55:47.129770Z" +updatedBy: "Codex" +changeReason: "Question added" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0005.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0005.md new file mode 100644 index 0000000..0f55fb1 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0005.md @@ -0,0 +1,75 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quais outputs de uma execução devem ser preservados como artefatos duráveis,\ + \ além das evidências já utilizadas por decisões e entregas?" + options: + - id: "1" + text: "Reter explicitamente os outputs úteis e as evidências utilizadas; os demais\ + \ outputs continuam temporários." + - id: "2" + text: "Reter automaticamente os outputs finais declarados por cada execução; manter\ + \ logs intermediários temporários." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Como tratar a limpeza dos arquivos temporários de execução, sem afetar artefatos\ + \ duráveis, evidências ou histórico?" + options: + - id: "1" + text: "Limpeza explícita por comando, com prévia do que será removido e proteç\ + ão das referências duráveis." + - id: "2" + text: "Limpeza automática com prazo configurável, aplicada exclusivamente a temporá\ + rios sem referências duráveis e fora de execuções ativas." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0004" + topicId: "TOP-0001" + text: "Qual deve ser a forma padrão de transportar e versionar os artefatos durá\ + veis junto com o estado do AIE?" + options: + - id: "1" + text: "Backup/exportação completa e consistente do banco e arquivos referenciados,\ + \ com inclusão em Git opcional e explícita." + - id: "2" + text: "Além do backup completo, versionar por padrão no Git os artefatos durá\ + veis e uma exportação textual do estado; definir limites para arquivos grandes." + multiple: false + recommendedOption: "1" + sources: [] +answers: [] +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 5 +previousHash: "ee0a6c734d7c490a8bc0306d8dfcb74dd21e26b8340ace1e72947e2d6ba25767" +updatedAt: "2026-11-22T10:55:48.033952Z" +updatedBy: "Codex" +changeReason: "Question added" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0006.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0006.md new file mode 100644 index 0000000..ce092c5 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0006.md @@ -0,0 +1,86 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quais outputs de uma execução devem ser preservados como artefatos duráveis,\ + \ além das evidências já utilizadas por decisões e entregas?" + options: + - id: "1" + text: "Reter explicitamente os outputs úteis e as evidências utilizadas; os demais\ + \ outputs continuam temporários." + - id: "2" + text: "Reter automaticamente os outputs finais declarados por cada execução; manter\ + \ logs intermediários temporários." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Como tratar a limpeza dos arquivos temporários de execução, sem afetar artefatos\ + \ duráveis, evidências ou histórico?" + options: + - id: "1" + text: "Limpeza explícita por comando, com prévia do que será removido e proteç\ + ão das referências duráveis." + - id: "2" + text: "Limpeza automática com prazo configurável, aplicada exclusivamente a temporá\ + rios sem referências duráveis e fora de execuções ativas." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0004" + topicId: "TOP-0001" + text: "Qual deve ser a forma padrão de transportar e versionar os artefatos durá\ + veis junto com o estado do AIE?" + options: + - id: "1" + text: "Backup/exportação completa e consistente do banco e arquivos referenciados,\ + \ com inclusão em Git opcional e explícita." + - id: "2" + text: "Além do backup completo, versionar por padrão no Git os artefatos durá\ + veis e uma exportação textual do estado; definir limites para arquivos grandes." + multiple: false + recommendedOption: "1" + sources: [] +answers: +- id: "ANS-0001" + questionId: "QST-0001" + choices: [] + text: "Revejo a premissa de reter esses artefatos: reduzir drasticamente o armazenamento\ + \ pelo AIE. Para esta versão, manter somente o output solicitado quando a entrega\ + \ não for alteração de código. A escolha anterior entre copiar todo artefato ou\ + \ referenciar o original deixa de orientar o modelo padrão; o destino dos outputs\ + \ solicitados ainda será detalhado." + author: "Nilton" + at: "2026-11-22T11:03:15.185973Z" + supersedes: null +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 6 +previousHash: "92faa3a6535f5a34080924fe0e530380a1d06b109bbd5d793afc6605f838fada" +updatedAt: "2026-11-22T11:03:15.194303Z" +updatedBy: "Nilton" +changeReason: "Answer recorded" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0007.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0007.md new file mode 100644 index 0000000..761731b --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0007.md @@ -0,0 +1,96 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quais outputs de uma execução devem ser preservados como artefatos duráveis,\ + \ além das evidências já utilizadas por decisões e entregas?" + options: + - id: "1" + text: "Reter explicitamente os outputs úteis e as evidências utilizadas; os demais\ + \ outputs continuam temporários." + - id: "2" + text: "Reter automaticamente os outputs finais declarados por cada execução; manter\ + \ logs intermediários temporários." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Como tratar a limpeza dos arquivos temporários de execução, sem afetar artefatos\ + \ duráveis, evidências ou histórico?" + options: + - id: "1" + text: "Limpeza explícita por comando, com prévia do que será removido e proteç\ + ão das referências duráveis." + - id: "2" + text: "Limpeza automática com prazo configurável, aplicada exclusivamente a temporá\ + rios sem referências duráveis e fora de execuções ativas." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0004" + topicId: "TOP-0001" + text: "Qual deve ser a forma padrão de transportar e versionar os artefatos durá\ + veis junto com o estado do AIE?" + options: + - id: "1" + text: "Backup/exportação completa e consistente do banco e arquivos referenciados,\ + \ com inclusão em Git opcional e explícita." + - id: "2" + text: "Além do backup completo, versionar por padrão no Git os artefatos durá\ + veis e uma exportação textual do estado; definir limites para arquivos grandes." + multiple: false + recommendedOption: "1" + sources: [] +answers: +- id: "ANS-0001" + questionId: "QST-0001" + choices: [] + text: "Revejo a premissa de reter esses artefatos: reduzir drasticamente o armazenamento\ + \ pelo AIE. Para esta versão, manter somente o output solicitado quando a entrega\ + \ não for alteração de código. A escolha anterior entre copiar todo artefato ou\ + \ referenciar o original deixa de orientar o modelo padrão; o destino dos outputs\ + \ solicitados ainda será detalhado." + author: "Nilton" + at: "2026-11-22T11:03:15.185973Z" + supersedes: null +- id: "ANS-0002" + questionId: "QST-0002" + choices: [] + text: "Para esta versão, manter somente o output solicitado quando não se tratar\ + \ de uma alteração de código. Gates de qualidade atendidos são suficientes; nã\ + o precisamos reter artefatos para toda essa auditoria. O conhecimento do Work\ + \ no banco pode ser útil para consulta e lessons futuras." + author: "Nilton" + at: "2026-11-22T11:03:18.878811Z" + supersedes: null +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 7 +previousHash: "129546ba68111666b145bdd763b3be215cbf64a14eac6e0017d4e9734b2e6018" +updatedAt: "2026-11-22T11:03:18.887210Z" +updatedBy: "Nilton" +changeReason: "Answer recorded" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0008.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0008.md new file mode 100644 index 0000000..4c692c5 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0008.md @@ -0,0 +1,105 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quais outputs de uma execução devem ser preservados como artefatos duráveis,\ + \ além das evidências já utilizadas por decisões e entregas?" + options: + - id: "1" + text: "Reter explicitamente os outputs úteis e as evidências utilizadas; os demais\ + \ outputs continuam temporários." + - id: "2" + text: "Reter automaticamente os outputs finais declarados por cada execução; manter\ + \ logs intermediários temporários." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Como tratar a limpeza dos arquivos temporários de execução, sem afetar artefatos\ + \ duráveis, evidências ou histórico?" + options: + - id: "1" + text: "Limpeza explícita por comando, com prévia do que será removido e proteç\ + ão das referências duráveis." + - id: "2" + text: "Limpeza automática com prazo configurável, aplicada exclusivamente a temporá\ + rios sem referências duráveis e fora de execuções ativas." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0004" + topicId: "TOP-0001" + text: "Qual deve ser a forma padrão de transportar e versionar os artefatos durá\ + veis junto com o estado do AIE?" + options: + - id: "1" + text: "Backup/exportação completa e consistente do banco e arquivos referenciados,\ + \ com inclusão em Git opcional e explícita." + - id: "2" + text: "Além do backup completo, versionar por padrão no Git os artefatos durá\ + veis e uma exportação textual do estado; definir limites para arquivos grandes." + multiple: false + recommendedOption: "1" + sources: [] +answers: +- id: "ANS-0001" + questionId: "QST-0001" + choices: [] + text: "Revejo a premissa de reter esses artefatos: reduzir drasticamente o armazenamento\ + \ pelo AIE. Para esta versão, manter somente o output solicitado quando a entrega\ + \ não for alteração de código. A escolha anterior entre copiar todo artefato ou\ + \ referenciar o original deixa de orientar o modelo padrão; o destino dos outputs\ + \ solicitados ainda será detalhado." + author: "Nilton" + at: "2026-11-22T11:03:15.185973Z" + supersedes: null +- id: "ANS-0002" + questionId: "QST-0002" + choices: [] + text: "Para esta versão, manter somente o output solicitado quando não se tratar\ + \ de uma alteração de código. Gates de qualidade atendidos são suficientes; nã\ + o precisamos reter artefatos para toda essa auditoria. O conhecimento do Work\ + \ no banco pode ser útil para consulta e lessons futuras." + author: "Nilton" + at: "2026-11-22T11:03:18.878811Z" + supersedes: null +- id: "ANS-0003" + questionId: "QST-0004" + choices: [] + text: "A política deve ser uma configuração do init: a base pode ser versionada\ + \ como binário por ponteiro, ou .ai-engineering pode ser completamente ignorado.\ + \ Não escolhi nesta conversa uma dessas alternativas como padrão." + author: "Nilton" + at: "2026-11-22T11:03:22.814831Z" + supersedes: null +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 8 +previousHash: "11cdfc238b66c6d5126ea546e9d9417fd9d0486cec6806d2b445bec5838901f6" +updatedAt: "2026-11-22T11:03:22.823113Z" +updatedBy: "Nilton" +changeReason: "Answer recorded" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0009.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0009.md new file mode 100644 index 0000000..f749884 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0009.md @@ -0,0 +1,114 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quais outputs de uma execução devem ser preservados como artefatos duráveis,\ + \ além das evidências já utilizadas por decisões e entregas?" + options: + - id: "1" + text: "Reter explicitamente os outputs úteis e as evidências utilizadas; os demais\ + \ outputs continuam temporários." + - id: "2" + text: "Reter automaticamente os outputs finais declarados por cada execução; manter\ + \ logs intermediários temporários." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Como tratar a limpeza dos arquivos temporários de execução, sem afetar artefatos\ + \ duráveis, evidências ou histórico?" + options: + - id: "1" + text: "Limpeza explícita por comando, com prévia do que será removido e proteç\ + ão das referências duráveis." + - id: "2" + text: "Limpeza automática com prazo configurável, aplicada exclusivamente a temporá\ + rios sem referências duráveis e fora de execuções ativas." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0004" + topicId: "TOP-0001" + text: "Qual deve ser a forma padrão de transportar e versionar os artefatos durá\ + veis junto com o estado do AIE?" + options: + - id: "1" + text: "Backup/exportação completa e consistente do banco e arquivos referenciados,\ + \ com inclusão em Git opcional e explícita." + - id: "2" + text: "Além do backup completo, versionar por padrão no Git os artefatos durá\ + veis e uma exportação textual do estado; definir limites para arquivos grandes." + multiple: false + recommendedOption: "1" + sources: [] +answers: +- id: "ANS-0001" + questionId: "QST-0001" + choices: [] + text: "Revejo a premissa de reter esses artefatos: reduzir drasticamente o armazenamento\ + \ pelo AIE. Para esta versão, manter somente o output solicitado quando a entrega\ + \ não for alteração de código. A escolha anterior entre copiar todo artefato ou\ + \ referenciar o original deixa de orientar o modelo padrão; o destino dos outputs\ + \ solicitados ainda será detalhado." + author: "Nilton" + at: "2026-11-22T11:03:15.185973Z" + supersedes: null +- id: "ANS-0002" + questionId: "QST-0002" + choices: [] + text: "Para esta versão, manter somente o output solicitado quando não se tratar\ + \ de uma alteração de código. Gates de qualidade atendidos são suficientes; nã\ + o precisamos reter artefatos para toda essa auditoria. O conhecimento do Work\ + \ no banco pode ser útil para consulta e lessons futuras." + author: "Nilton" + at: "2026-11-22T11:03:18.878811Z" + supersedes: null +- id: "ANS-0003" + questionId: "QST-0004" + choices: [] + text: "A política deve ser uma configuração do init: a base pode ser versionada\ + \ como binário por ponteiro, ou .ai-engineering pode ser completamente ignorado.\ + \ Não escolhi nesta conversa uma dessas alternativas como padrão." + author: "Nilton" + at: "2026-11-22T11:03:22.814831Z" + supersedes: null +- id: "ANS-0004" + questionId: "QST-0004" + choices: [] + text: "Versionamento: Git LFS primeiro. Depois, se necessário, pensamos em exportaç\ + ão para backup. Esta escolha substitui a indefinição anterior entre manter somente\ + \ local ou versionar por ponteiro." + author: "Nilton" + at: "2026-11-22T11:11:09.285263Z" + supersedes: "ANS-0003" +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 9 +previousHash: "fcd54fa585345a46d195cf1788833e115fb51b8ec92c7bddb62665b03f6a1d4a" +updatedAt: "2026-11-22T11:11:09.294087Z" +updatedBy: "Nilton" +changeReason: "Answer revised; related conclusions may need review" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0010.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0010.md new file mode 100644 index 0000000..be5f99e --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0001/r0010.md @@ -0,0 +1,123 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quais outputs de uma execução devem ser preservados como artefatos duráveis,\ + \ além das evidências já utilizadas por decisões e entregas?" + options: + - id: "1" + text: "Reter explicitamente os outputs úteis e as evidências utilizadas; os demais\ + \ outputs continuam temporários." + - id: "2" + text: "Reter automaticamente os outputs finais declarados por cada execução; manter\ + \ logs intermediários temporários." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Como tratar a limpeza dos arquivos temporários de execução, sem afetar artefatos\ + \ duráveis, evidências ou histórico?" + options: + - id: "1" + text: "Limpeza explícita por comando, com prévia do que será removido e proteç\ + ão das referências duráveis." + - id: "2" + text: "Limpeza automática com prazo configurável, aplicada exclusivamente a temporá\ + rios sem referências duráveis e fora de execuções ativas." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0004" + topicId: "TOP-0001" + text: "Qual deve ser a forma padrão de transportar e versionar os artefatos durá\ + veis junto com o estado do AIE?" + options: + - id: "1" + text: "Backup/exportação completa e consistente do banco e arquivos referenciados,\ + \ com inclusão em Git opcional e explícita." + - id: "2" + text: "Além do backup completo, versionar por padrão no Git os artefatos durá\ + veis e uma exportação textual do estado; definir limites para arquivos grandes." + multiple: false + recommendedOption: "1" + sources: [] +answers: +- id: "ANS-0001" + questionId: "QST-0001" + choices: [] + text: "Revejo a premissa de reter esses artefatos: reduzir drasticamente o armazenamento\ + \ pelo AIE. Para esta versão, manter somente o output solicitado quando a entrega\ + \ não for alteração de código. A escolha anterior entre copiar todo artefato ou\ + \ referenciar o original deixa de orientar o modelo padrão; o destino dos outputs\ + \ solicitados ainda será detalhado." + author: "Nilton" + at: "2026-11-22T11:03:15.185973Z" + supersedes: null +- id: "ANS-0002" + questionId: "QST-0002" + choices: [] + text: "Para esta versão, manter somente o output solicitado quando não se tratar\ + \ de uma alteração de código. Gates de qualidade atendidos são suficientes; nã\ + o precisamos reter artefatos para toda essa auditoria. O conhecimento do Work\ + \ no banco pode ser útil para consulta e lessons futuras." + author: "Nilton" + at: "2026-11-22T11:03:18.878811Z" + supersedes: null +- id: "ANS-0003" + questionId: "QST-0004" + choices: [] + text: "A política deve ser uma configuração do init: a base pode ser versionada\ + \ como binário por ponteiro, ou .ai-engineering pode ser completamente ignorado.\ + \ Não escolhi nesta conversa uma dessas alternativas como padrão." + author: "Nilton" + at: "2026-11-22T11:03:22.814831Z" + supersedes: null +- id: "ANS-0004" + questionId: "QST-0004" + choices: [] + text: "Versionamento: Git LFS primeiro. Depois, se necessário, pensamos em exportaç\ + ão para backup. Esta escolha substitui a indefinição anterior entre manter somente\ + \ local ou versionar por ponteiro." + author: "Nilton" + at: "2026-11-22T11:11:09.285263Z" + supersedes: "ANS-0003" +- id: "ANS-0005" + questionId: "QST-0003" + choices: [] + text: "Sim à pergunta desta conversa: descartar temporários automaticamente ao terminar\ + \ uma execução, mantendo no banco o resultado e um diagnóstico curto em caso de\ + \ falha. Outputs solicitados permanecem preservados." + author: "Nilton" + at: "2026-11-22T11:20:56.934809Z" + supersedes: null +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 10 +previousHash: "92ad94f6d0af07e7627a565af289114512c493df55d2b757855c21662e13aa70" +updatedAt: "2026-11-22T11:20:56.942731Z" +updatedBy: "Nilton" +changeReason: "Answer recorded" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0001.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0001.md new file mode 100644 index 0000000..fad4841 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0001.md @@ -0,0 +1,18 @@ +--- +schemaVersion: 1 +id: "SVY-0002" +workId: "WRK-000D" +title: "Gates e uso da base versionada nesta versão" +questions: [] +answers: [] +author: "Codex" +createdAt: "2026-11-22T11:12:51.375415Z" +revision: 1 +previousHash: null +updatedAt: "2026-11-22T11:12:51.375415Z" +updatedBy: "Codex" +changeReason: "Survey created" +documentVersion: 2 +--- + +Perguntas sobre a origem dos gates, momento de captura da base para Git LFS e necessidade de conciliar bases divergentes. A pergunta sobre descarte de temporários permanece em SVY-0001/QST-0003. Propostas ainda não escolhidas pelo humano. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0002.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0002.md new file mode 100644 index 0000000..8cc7c50 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0002.md @@ -0,0 +1,32 @@ +--- +schemaVersion: 1 +id: "SVY-0002" +workId: "WRK-000D" +title: "Gates e uso da base versionada nesta versão" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "De onde vêm os gates obrigatórios aplicáveis a cada Work?" + options: + - id: "1" + text: "Gates padrão definidos no projeto, refinados por tipo e escopo do Work;\ + \ gates adicionais são definidos antes da avaliação. Não criar bypass silencioso\ + \ dos obrigatórios." + - id: "2" + text: "Definir o conjunto de gates individualmente em cada Work, sem catálogo\ + \ padrão do projeto." + multiple: false + recommendedOption: "1" + sources: [] +answers: [] +author: "Codex" +createdAt: "2026-11-22T11:12:51.375415Z" +revision: 2 +previousHash: "22c9040e843779f46ed66eb3b71704df17035e57974b493b80eb0fa9727e292c" +updatedAt: "2026-11-22T11:12:52.072941Z" +updatedBy: "Codex" +changeReason: "Question added" +documentVersion: 2 +--- + +Perguntas sobre a origem dos gates, momento de captura da base para Git LFS e necessidade de conciliar bases divergentes. A pergunta sobre descarte de temporários permanece em SVY-0001/QST-0003. Propostas ainda não escolhidas pelo humano. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0003.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0003.md new file mode 100644 index 0000000..2f53ef5 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0003.md @@ -0,0 +1,45 @@ +--- +schemaVersion: 1 +id: "SVY-0002" +workId: "WRK-000D" +title: "Gates e uso da base versionada nesta versão" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "De onde vêm os gates obrigatórios aplicáveis a cada Work?" + options: + - id: "1" + text: "Gates padrão definidos no projeto, refinados por tipo e escopo do Work;\ + \ gates adicionais são definidos antes da avaliação. Não criar bypass silencioso\ + \ dos obrigatórios." + - id: "2" + text: "Definir o conjunto de gates individualmente em cada Work, sem catálogo\ + \ padrão do projeto." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quando atualizar a cópia consistente da base que será versionada com Git\ + \ LFS, sem criar commits ou pushes automaticamente?" + options: + - id: "1" + text: "Ao concluir um Work e também por comando explícito quando for preciso preservar\ + \ uma discussão ainda aberta." + - id: "2" + text: "Somente por comando explícito ao preparar um commit do projeto." + multiple: false + recommendedOption: "1" + sources: [] +answers: [] +author: "Codex" +createdAt: "2026-11-22T11:12:51.375415Z" +revision: 3 +previousHash: "0562ffb7c7186d0570312759e59f19ff38125a1c69a7250d5cc966a2ef74d58c" +updatedAt: "2026-11-22T11:12:52.810152Z" +updatedBy: "Codex" +changeReason: "Question added" +documentVersion: 2 +--- + +Perguntas sobre a origem dos gates, momento de captura da base para Git LFS e necessidade de conciliar bases divergentes. A pergunta sobre descarte de temporários permanece em SVY-0001/QST-0003. Propostas ainda não escolhidas pelo humano. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0004.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0004.md new file mode 100644 index 0000000..c98067a --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0004.md @@ -0,0 +1,59 @@ +--- +schemaVersion: 1 +id: "SVY-0002" +workId: "WRK-000D" +title: "Gates e uso da base versionada nesta versão" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "De onde vêm os gates obrigatórios aplicáveis a cada Work?" + options: + - id: "1" + text: "Gates padrão definidos no projeto, refinados por tipo e escopo do Work;\ + \ gates adicionais são definidos antes da avaliação. Não criar bypass silencioso\ + \ dos obrigatórios." + - id: "2" + text: "Definir o conjunto de gates individualmente em cada Work, sem catálogo\ + \ padrão do projeto." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quando atualizar a cópia consistente da base que será versionada com Git\ + \ LFS, sem criar commits ou pushes automaticamente?" + options: + - id: "1" + text: "Ao concluir um Work e também por comando explícito quando for preciso preservar\ + \ uma discussão ainda aberta." + - id: "2" + text: "Somente por comando explícito ao preparar um commit do projeto." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Precisamos conciliar automaticamente memórias SQLite que evoluíram separadamente\ + \ em branches ou máquinas distintas já nesta versão?" + options: + - id: "1" + text: "Não nesta versão: manter evolução coordenada da base; divergências exigem\ + \ escolha explícita de uma versão completa, sem tentar mesclar automaticamente." + - id: "2" + text: "Sim: projetar identificação e reconciliação dos registros de bases divergentes\ + \ nesta versão, preservando conhecimento e decisões de ambos os lados." + multiple: false + recommendedOption: "1" + sources: [] +answers: [] +author: "Codex" +createdAt: "2026-11-22T11:12:51.375415Z" +revision: 4 +previousHash: "130c9b8f87e6aecfd7f48e0fb4def6b4cbe94e698b5d5d6c102115c37c90bcb9" +updatedAt: "2026-11-22T11:12:53.575537Z" +updatedBy: "Codex" +changeReason: "Question added" +documentVersion: 2 +--- + +Perguntas sobre a origem dos gates, momento de captura da base para Git LFS e necessidade de conciliar bases divergentes. A pergunta sobre descarte de temporários permanece em SVY-0001/QST-0003. Propostas ainda não escolhidas pelo humano. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0005.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0005.md new file mode 100644 index 0000000..f2856cf --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0005.md @@ -0,0 +1,67 @@ +--- +schemaVersion: 1 +id: "SVY-0002" +workId: "WRK-000D" +title: "Gates e uso da base versionada nesta versão" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "De onde vêm os gates obrigatórios aplicáveis a cada Work?" + options: + - id: "1" + text: "Gates padrão definidos no projeto, refinados por tipo e escopo do Work;\ + \ gates adicionais são definidos antes da avaliação. Não criar bypass silencioso\ + \ dos obrigatórios." + - id: "2" + text: "Definir o conjunto de gates individualmente em cada Work, sem catálogo\ + \ padrão do projeto." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quando atualizar a cópia consistente da base que será versionada com Git\ + \ LFS, sem criar commits ou pushes automaticamente?" + options: + - id: "1" + text: "Ao concluir um Work e também por comando explícito quando for preciso preservar\ + \ uma discussão ainda aberta." + - id: "2" + text: "Somente por comando explícito ao preparar um commit do projeto." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Precisamos conciliar automaticamente memórias SQLite que evoluíram separadamente\ + \ em branches ou máquinas distintas já nesta versão?" + options: + - id: "1" + text: "Não nesta versão: manter evolução coordenada da base; divergências exigem\ + \ escolha explícita de uma versão completa, sem tentar mesclar automaticamente." + - id: "2" + text: "Sim: projetar identificação e reconciliação dos registros de bases divergentes\ + \ nesta versão, preservando conhecimento e decisões de ambos os lados." + multiple: false + recommendedOption: "1" + sources: [] +answers: +- id: "ANS-0001" + questionId: "QST-0001" + choices: + - "1" + text: "Gates por projeto mais gates individuais por Work, caso sejam necessários." + author: "Nilton" + at: "2026-11-22T11:20:51.658806Z" + supersedes: null +author: "Codex" +createdAt: "2026-11-22T11:12:51.375415Z" +revision: 5 +previousHash: "446c9eb0bce1cb3ccb18a0dbb6107fed43c0bd649f90de921b8deec3be68d4c2" +updatedAt: "2026-11-22T11:20:51.666112Z" +updatedBy: "Nilton" +changeReason: "Answer recorded" +documentVersion: 2 +--- + +Perguntas sobre a origem dos gates, momento de captura da base para Git LFS e necessidade de conciliar bases divergentes. A pergunta sobre descarte de temporários permanece em SVY-0001/QST-0003. Propostas ainda não escolhidas pelo humano. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0006.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0006.md new file mode 100644 index 0000000..f077206 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/.history/SVY-0002/r0006.md @@ -0,0 +1,77 @@ +--- +schemaVersion: 1 +id: "SVY-0002" +workId: "WRK-000D" +title: "Gates e uso da base versionada nesta versão" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "De onde vêm os gates obrigatórios aplicáveis a cada Work?" + options: + - id: "1" + text: "Gates padrão definidos no projeto, refinados por tipo e escopo do Work;\ + \ gates adicionais são definidos antes da avaliação. Não criar bypass silencioso\ + \ dos obrigatórios." + - id: "2" + text: "Definir o conjunto de gates individualmente em cada Work, sem catálogo\ + \ padrão do projeto." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quando atualizar a cópia consistente da base que será versionada com Git\ + \ LFS, sem criar commits ou pushes automaticamente?" + options: + - id: "1" + text: "Ao concluir um Work e também por comando explícito quando for preciso preservar\ + \ uma discussão ainda aberta." + - id: "2" + text: "Somente por comando explícito ao preparar um commit do projeto." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Precisamos conciliar automaticamente memórias SQLite que evoluíram separadamente\ + \ em branches ou máquinas distintas já nesta versão?" + options: + - id: "1" + text: "Não nesta versão: manter evolução coordenada da base; divergências exigem\ + \ escolha explícita de uma versão completa, sem tentar mesclar automaticamente." + - id: "2" + text: "Sim: projetar identificação e reconciliação dos registros de bases divergentes\ + \ nesta versão, preservando conhecimento e decisões de ambos os lados." + multiple: false + recommendedOption: "1" + sources: [] +answers: +- id: "ANS-0001" + questionId: "QST-0001" + choices: + - "1" + text: "Gates por projeto mais gates individuais por Work, caso sejam necessários." + author: "Nilton" + at: "2026-11-22T11:20:51.658806Z" + supersedes: null +- id: "ANS-0002" + questionId: "QST-0002" + choices: [] + text: "A questão de quando capturar a base para Git LFS deixa de se aplicar ao escopo\ + \ atual: framework local, fora de Git por padrão, com versionamento a critério\ + \ do desenvolvedor. Não desenvolver integração obrigatória de captura/versionamento\ + \ Git nesta versão." + author: "Nilton" + at: "2026-11-22T11:29:53.002489Z" + supersedes: null +author: "Codex" +createdAt: "2026-11-22T11:12:51.375415Z" +revision: 6 +previousHash: "b9755c4d29b6549ef942e4d813a4cbd7b5fe33e3917032411ca35900950e64cd" +updatedAt: "2026-11-22T11:29:53.011417Z" +updatedBy: "Nilton" +changeReason: "Answer recorded" +documentVersion: 2 +--- + +Perguntas sobre a origem dos gates, momento de captura da base para Git LFS e necessidade de conciliar bases divergentes. A pergunta sobre descarte de temporários permanece em SVY-0001/QST-0003. Propostas ainda não escolhidas pelo humano. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/SVY-0001.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/SVY-0001.md new file mode 100644 index 0000000..35596a2 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/SVY-0001.md @@ -0,0 +1,133 @@ +--- +schemaVersion: 1 +id: "SVY-0001" +workId: "WRK-000D" +title: "Política de arquivos e artefatos externos ao SQLite" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "Ao reter um arquivo como artefato durável, o AIE deve manter uma cópia pró\ + pria dentro do projeto ou depender do arquivo na localização original?" + options: + - id: "1" + text: "Copiar para uma área gerida pelo AIE dentro do projeto, usando caminho\ + \ relativo e verificando hash; recursos externos muito grandes podem continuar\ + \ como referências explícitas." + - id: "2" + text: "Guardar apenas a referência à localização original; disponibilidade e transporte\ + \ ficam sob responsabilidade de quem mantém esse arquivo." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quais outputs de uma execução devem ser preservados como artefatos duráveis,\ + \ além das evidências já utilizadas por decisões e entregas?" + options: + - id: "1" + text: "Reter explicitamente os outputs úteis e as evidências utilizadas; os demais\ + \ outputs continuam temporários." + - id: "2" + text: "Reter automaticamente os outputs finais declarados por cada execução; manter\ + \ logs intermediários temporários." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Como tratar a limpeza dos arquivos temporários de execução, sem afetar artefatos\ + \ duráveis, evidências ou histórico?" + options: + - id: "1" + text: "Limpeza explícita por comando, com prévia do que será removido e proteç\ + ão das referências duráveis." + - id: "2" + text: "Limpeza automática com prazo configurável, aplicada exclusivamente a temporá\ + rios sem referências duráveis e fora de execuções ativas." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0004" + topicId: "TOP-0001" + text: "Qual deve ser a forma padrão de transportar e versionar os artefatos durá\ + veis junto com o estado do AIE?" + options: + - id: "1" + text: "Backup/exportação completa e consistente do banco e arquivos referenciados,\ + \ com inclusão em Git opcional e explícita." + - id: "2" + text: "Além do backup completo, versionar por padrão no Git os artefatos durá\ + veis e uma exportação textual do estado; definir limites para arquivos grandes." + multiple: false + recommendedOption: "1" + sources: [] +answers: +- id: "ANS-0001" + questionId: "QST-0001" + choices: [] + text: "Revejo a premissa de reter esses artefatos: reduzir drasticamente o armazenamento\ + \ pelo AIE. Para esta versão, manter somente o output solicitado quando a entrega\ + \ não for alteração de código. A escolha anterior entre copiar todo artefato ou\ + \ referenciar o original deixa de orientar o modelo padrão; o destino dos outputs\ + \ solicitados ainda será detalhado." + author: "Nilton" + at: "2026-11-22T11:03:15.185973Z" + supersedes: null +- id: "ANS-0002" + questionId: "QST-0002" + choices: [] + text: "Para esta versão, manter somente o output solicitado quando não se tratar\ + \ de uma alteração de código. Gates de qualidade atendidos são suficientes; nã\ + o precisamos reter artefatos para toda essa auditoria. O conhecimento do Work\ + \ no banco pode ser útil para consulta e lessons futuras." + author: "Nilton" + at: "2026-11-22T11:03:18.878811Z" + supersedes: null +- id: "ANS-0003" + questionId: "QST-0004" + choices: [] + text: "A política deve ser uma configuração do init: a base pode ser versionada\ + \ como binário por ponteiro, ou .ai-engineering pode ser completamente ignorado.\ + \ Não escolhi nesta conversa uma dessas alternativas como padrão." + author: "Nilton" + at: "2026-11-22T11:03:22.814831Z" + supersedes: null +- id: "ANS-0004" + questionId: "QST-0004" + choices: [] + text: "Versionamento: Git LFS primeiro. Depois, se necessário, pensamos em exportaç\ + ão para backup. Esta escolha substitui a indefinição anterior entre manter somente\ + \ local ou versionar por ponteiro." + author: "Nilton" + at: "2026-11-22T11:11:09.285263Z" + supersedes: "ANS-0003" +- id: "ANS-0005" + questionId: "QST-0003" + choices: [] + text: "Sim à pergunta desta conversa: descartar temporários automaticamente ao terminar\ + \ uma execução, mantendo no banco o resultado e um diagnóstico curto em caso de\ + \ falha. Outputs solicitados permanecem preservados." + author: "Nilton" + at: "2026-11-22T11:20:56.934809Z" + supersedes: null +- id: "ANS-0006" + questionId: "QST-0004" + choices: [] + text: "Pivô: AIE local e .ai-engineering fora de Git por padrão. Versionar fica\ + \ a critério do desenvolvedor. Git LFS deixa de ser estratégia obrigatória desta\ + \ versão. Importação e exportação de Works e compartilhamento de DECs ficam para\ + \ etapa posterior, se necessário." + author: "Nilton" + at: "2026-11-22T11:29:42.842844Z" + supersedes: "ANS-0004" +author: "Codex" +createdAt: "2026-11-22T10:55:44.572670Z" +revision: 11 +previousHash: "7ce6f71d9e7249c77913e18012c7be92c58bce2f99f44a19e33b1564314b6cf6" +updatedAt: "2026-11-22T11:29:42.855436Z" +updatedBy: "Nilton" +changeReason: "Answer revised; related conclusions may need review" +documentVersion: 2 +--- + +Perguntas iniciais sobre posse dos arquivos, retenção de outputs, limpeza de temporários e transporte/versionamento. SQLite sem blobs já é restrição; evidências e histórico permanecem preservados. Sugestões não são respostas nem aprovações. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/SVY-0002.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/SVY-0002.md new file mode 100644 index 0000000..9ce40e4 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/surveys/SVY-0002.md @@ -0,0 +1,87 @@ +--- +schemaVersion: 1 +id: "SVY-0002" +workId: "WRK-000D" +title: "Gates e uso da base versionada nesta versão" +questions: +- id: "QST-0001" + topicId: "TOP-0001" + text: "De onde vêm os gates obrigatórios aplicáveis a cada Work?" + options: + - id: "1" + text: "Gates padrão definidos no projeto, refinados por tipo e escopo do Work;\ + \ gates adicionais são definidos antes da avaliação. Não criar bypass silencioso\ + \ dos obrigatórios." + - id: "2" + text: "Definir o conjunto de gates individualmente em cada Work, sem catálogo\ + \ padrão do projeto." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0002" + topicId: "TOP-0001" + text: "Quando atualizar a cópia consistente da base que será versionada com Git\ + \ LFS, sem criar commits ou pushes automaticamente?" + options: + - id: "1" + text: "Ao concluir um Work e também por comando explícito quando for preciso preservar\ + \ uma discussão ainda aberta." + - id: "2" + text: "Somente por comando explícito ao preparar um commit do projeto." + multiple: false + recommendedOption: "1" + sources: [] +- id: "QST-0003" + topicId: "TOP-0001" + text: "Precisamos conciliar automaticamente memórias SQLite que evoluíram separadamente\ + \ em branches ou máquinas distintas já nesta versão?" + options: + - id: "1" + text: "Não nesta versão: manter evolução coordenada da base; divergências exigem\ + \ escolha explícita de uma versão completa, sem tentar mesclar automaticamente." + - id: "2" + text: "Sim: projetar identificação e reconciliação dos registros de bases divergentes\ + \ nesta versão, preservando conhecimento e decisões de ambos os lados." + multiple: false + recommendedOption: "1" + sources: [] +answers: +- id: "ANS-0001" + questionId: "QST-0001" + choices: + - "1" + text: "Gates por projeto mais gates individuais por Work, caso sejam necessários." + author: "Nilton" + at: "2026-11-22T11:20:51.658806Z" + supersedes: null +- id: "ANS-0002" + questionId: "QST-0002" + choices: [] + text: "A questão de quando capturar a base para Git LFS deixa de se aplicar ao escopo\ + \ atual: framework local, fora de Git por padrão, com versionamento a critério\ + \ do desenvolvedor. Não desenvolver integração obrigatória de captura/versionamento\ + \ Git nesta versão." + author: "Nilton" + at: "2026-11-22T11:29:53.002489Z" + supersedes: null +- id: "ANS-0003" + questionId: "QST-0003" + choices: [] + text: "Não desenvolver sincronização ou conciliação de memórias entre máquinas/branches\ + \ nesta versão. Pivotar para framework de trabalho local. Importação/exportaçã\ + o de Works e compartilhamento de DECs poderão ser tratados em etapa posterior;\ + \ DEC é o principal conteúdo de interesse para compartilhar." + author: "Nilton" + at: "2026-11-22T11:30:00.692369Z" + supersedes: null +author: "Codex" +createdAt: "2026-11-22T11:12:51.375415Z" +revision: 7 +previousHash: "a6e9ab2d5d36abc68b20d0762035560612350c915722f0782db9a84f709db332" +updatedAt: "2026-11-22T11:30:00.703105Z" +updatedBy: "Nilton" +changeReason: "Answer recorded" +documentVersion: 2 +--- + +Perguntas sobre a origem dos gates, momento de captura da base para Git LFS e necessidade de conciliar bases divergentes. A pergunta sobre descarte de temporários permanece em SVY-0001/QST-0003. Propostas ainda não escolhidas pelo humano. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/topics/TOP-0001.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/topics/TOP-0001.md new file mode 100644 index 0000000..494455c --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/topics/TOP-0001.md @@ -0,0 +1,17 @@ +--- +schemaVersion: 1 +id: "TOP-0001" +workId: "WRK-000D" +title: "Fronteira entre estado no SQLite e artefatos no filesystem" +sources: [] +author: "Codex" +createdAt: "2026-11-22T10:48:14.261976Z" +revision: 1 +previousHash: null +updatedAt: "2026-11-22T10:48:14.261976Z" +updatedBy: "Codex" +changeReason: "Topic created" +documentVersion: 2 +--- + +Definir quais textos e registros operacionais pertencem ao banco, quais conteúdos permanecem em arquivos e como tratar identidade, proveniência, integridade, publicação, backup e recuperação sem armazenar blobs. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/topics/TOP-0002.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/topics/TOP-0002.md new file mode 100644 index 0000000..fc6b7be --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/topics/TOP-0002.md @@ -0,0 +1,17 @@ +--- +schemaVersion: 1 +id: "TOP-0002" +workId: "WRK-000D" +title: "Identidade e colaboração entre máquinas e branches" +sources: [] +author: "Codex" +createdAt: "2026-11-22T11:21:01.143784Z" +revision: 1 +previousHash: null +updatedAt: "2026-11-22T11:21:01.143784Z" +updatedBy: "Codex" +changeReason: "Topic created" +documentVersion: 2 +--- + +Resolver criação concorrente de Works, identidade estável, compartilhamento da memória e alterações concorrentes antes de definir captura e sincronização do SQLite por Git LFS. O uso atual é individual, mas o desenho precisa considerar compartilhamento futuro no mesmo projeto. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/work.md b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/work.md new file mode 100644 index 0000000..eac1e18 --- /dev/null +++ b/.ai-engineering/works/WRK-000D-adotar-sqlite-como-persistencia-local-do-aie/work.md @@ -0,0 +1,240 @@ +--- +schemaVersion: 1 +id: "WRK-000D" +title: "Adotar SQLite e memória de engenharia local no AIE" +description: "Pivô solicitado por Nilton: AIE como framework de trabalho local, com\ + \ .ai-engineering fora de Git por padrão e versionamento a critério do desenvolvedor.\ + \ Adotar SQLite para estado e conhecimento útil, preservar os dois ciclos e OODA,\ + \ entregar por gates do projeto e adicionais do Work e reter apenas o mínimo e outputs\ + \ solicitados. Git LFS e sincronização deixam o escopo obrigatório; importação/exportaç\ + ão de Works e compartilhamento de DECs poderão ser tratados depois. A investigaç\ + ão de latência continua separada no WRK-000C." +goal: "Adotar SQLite como persistência de um framework local de memória de engenharia\ + \ por Work, fora de Git por padrão, com investigação, implementação, OODA, gates\ + \ de qualidade e retenção mínima." +motivation: "O armazenamento atual repete varreduras, parsing e validações globais\ + \ e publica alterações relacionadas por arquivo. O humano propôs tratar a mudanç\ + a de persistência em Work próprio e depois retornar à responsividade." +constraints: +- "Abertura e exploração não autorizam implementação, migração de dados reais, commits\ + \ ou alteração de projetos consumidores; compromissos concretos dependem de DEC\ + \ e aprovação aplicável." +- "Preservar IDs, conteúdo e proveniência histórica, aprovações, revisões, hashes\ + \ e evidências legadas existentes na migração; não reescrever Works concluídos nem\ + \ executar descarte retroativo durante a exploração." +- "Framework de trabalho local por projeto, operado pela CLI e com SQLite embarcado.\ + \ Sem serviço de banco separado ou dependência de Git para funcionar; avaliar distribuiç\ + ão JVM e GraalVM Native Image." +- "SQLite é a fonte principal única do estado e dos textos operacionais. Não armazenar\ + \ arquivos produzidos como BLOB, base64 ou equivalente em TEXT; outputs solicitados\ + \ permanecem no filesystem no destino adequado." +- "Reter permanentemente somente conhecimento útil, registros operacionais enxutos\ + \ e outputs solicitados. Anexos podem continuar exigidos pelos checks existentes,\ + \ mas são temporários: descartá-los após todos os checks dependentes, sem cópias\ + \ permanentes apenas para auditoria; preservar entregas solicitadas." +- "Fora de Git por padrão: inicialização configura .ai-engineering como estado local\ + \ ignorado. Versionamento fica a critério do desenvolvedor; Git LFS, captura de\ + \ snapshots para Git e sincronização entre branches ou máquinas deixam de ser funcionalidades\ + \ obrigatórias desta versão." +- "Importação/exportação de Works, exportação para backup e compartilhamento de DECs\ + \ ficam para etapa posterior, se necessário. DEC é o principal conteúdo de interesse\ + \ para futuro compartilhamento. Cópia de segurança interna da migração não constitui\ + \ funcionalidade de exportação." +- "AIE é memória de engenharia por Work, com discussão e refinamento e entrega condicionada\ + \ aos gates estipulados. Auditoria e retenção são mínimas; simplificá-las não dispensa\ + \ gates nem autoriza registrar sucesso sem avaliação real." +- "Preservar os dois ciclos de investigação/discussão e implementação, conectados\ + \ por DEC e Plan e pela autoridade humana aplicável. Manter OODA adaptativo, com\ + \ observação, reconsideração e replanejamento quando necessário, sem impor quatro\ + \ etapas burocráticas a cada ação." +- "Gates obrigatórios são definidos por projeto e podem ser complementados por Work.\ + \ Preservar condições dos checks e exigências de anexos durante a avaliação. Descartar\ + \ temporários ao terminar a execução apenas quando não restarem checks dependentes;\ + \ distinguir descarte legítimo de perda prematura, mantendo resultado mínimo no\ + \ banco." +- "O WRK-000C permanece aberto e separado; retomar a avaliação de latência após a\ + \ mudança de persistência, sem pressupor que SQLite a elimina." +- "Distribuir AIE nativo e SQLite juntos em um diretório de instalação do usuário,\ + \ por evolução do script existente, com atalhos em ~/.local/bin; bancos de projeto\ + \ permanecem em .ai-engineering. Validar biblioteca/driver SQLite e CLI sqlite3\ + \ do pacote na plataforma alvo, sem servidor de banco separado." +- "Não executar instalação nativa nem substituir binários, bibliotecas ou atalhos\ + \ da instalação em uso, pois existem projetos em andamento. Preparar script/pacote\ + \ e validar com fixtures e artefatos de build descartáveis é permitido após aprovaç\ + ão aplicável; instalação real e migração de projetos consumidores exigem instruç\ + ão humana posterior específica." +acceptanceCriteria: +- "Arquitetura e escopo aprovados definem SQLite local como fonte principal, entidades,\ + \ índices, transações, concorrência entre processos locais e versionamento do esquema,\ + \ preservando os dois ciclos, OODA e autoridade humana." +- "Após aprovação da DEC, SQLite sustenta leitura, registro, discussão/refinamento,\ + \ decisão, planejamento, verificação e coordenação local, com histórico e contexto\ + \ úteis para retomada." +- "Gates por projeto e adicionais por Work preservam checks e anexos exigidos durante\ + \ a avaliação; pendência ou falha impede entrega. Resultados reais e mínimos persistem\ + \ no banco, e descarte legítimo posterior de anexos temporários não invalida a memó\ + ria histórica nem oculta arquivo perdido antes da checagem." +- "A política de retenção preserva outputs solicitados e resultados enxutos no banco;\ + \ anexos, logs e relatórios usados pelos checks são temporários e só são descartados\ + \ após todos os checks dependentes, sem criar retenção permanente de auditoria." +- "Inicialização deixa .ai-engineering fora de Git por padrão e o framework funciona\ + \ sem Git; o comportamento para projetos existentes é explícito e preserva conteú\ + do e regras preexistentes conforme o escopo aprovado. Versionamento opcional pelo\ + \ desenvolvedor não exige integração Git LFS nesta versão." +- "Migração explícita oferece preview e cópia de segurança e verifica preservação\ + \ de IDs, conteúdo e proveniência legados; falhas, recuperação e reversão são exercitadas\ + \ com dados descartáveis, sem impor auditoria extensa a novos registros." +- "Script e pacote são preparados para instalar e atualizar AIE nativo e SQLite juntos\ + \ num diretório do usuário, com atalhos em ~/.local/bin, e validados por fixtures\ + \ e smoke de build na plataforma alvo. Não executar instalação real nem substituir\ + \ a distribuição ativa; bancos de projeto permanecem separados dos binários. Compatibilidade\ + \ JVM/Native Image e protocolo/CLI é documentada." +- "Entrega registra resultados de verificação e cenário reproduzível para retomar\ + \ responsividade no WRK-000C, sem encerrá-lo automaticamente." +status: "COMPLETED" +createdAt: "2026-11-22T10:44:39.939391Z" +updatedAt: "2026-11-22T14:23:22.777113Z" +author: "Nilton" +repositories: [] +discussions: +- "DSC-0001" +- "DSC-0002" +- "DSC-0003" +- "DSC-0004" +- "DSC-0005" +- "DSC-0006" +- "DSC-0007" +- "DSC-0008" +- "DSC-0009" +- "DSC-0010" +- "DSC-0011" +- "DSC-0012" +- "DSC-0013" +- "DSC-0014" +- "DSC-0015" +- "DSC-0016" +decisions: +- "DEC-0001" +artifacts: +- "ART-0001" +- "ART-0002" +- "ART-0003" +- "ART-0004" +- "ART-0005" +- "ART-0006" +- "ART-0007" +- "ART-0008" +- "ART-0009" +- "ART-0010" +- "ART-0011" +- "ART-0012" +- "ART-0013" +- "ART-0014" +- "ART-0015" +plans: +- "PLN-0001" +completions: +- at: "2026-11-22T14:23:22.777113Z" + by: "system:plans" + summary: "All required Plans completed; requester=Codex" + humanApproved: false + scopeHash: "7fd5cc06408c8d2a9f0f5fbb6b09af6f047184caaec2849510c51ee583489041" + criteria: + - criterion: 1 + text: "Arquitetura e escopo aprovados definem SQLite local como fonte principal,\ + \ entidades, índices, transações, concorrência entre processos locais e versionamento\ + \ do esquema, preservando os dois ciclos, OODA e autoridade humana." + evidence: + - "ART-0015" + - criterion: 2 + text: "Após aprovação da DEC, SQLite sustenta leitura, registro, discussão/refinamento,\ + \ decisão, planejamento, verificação e coordenação local, com histórico e contexto\ + \ úteis para retomada." + evidence: + - "ART-0015" + - criterion: 3 + text: "Gates por projeto e adicionais por Work preservam checks e anexos exigidos\ + \ durante a avaliação; pendência ou falha impede entrega. Resultados reais e\ + \ mínimos persistem no banco, e descarte legítimo posterior de anexos temporá\ + rios não invalida a memória histórica nem oculta arquivo perdido antes da checagem." + evidence: + - "ART-0015" + - criterion: 4 + text: "A política de retenção preserva outputs solicitados e resultados enxutos\ + \ no banco; anexos, logs e relatórios usados pelos checks são temporários e\ + \ só são descartados após todos os checks dependentes, sem criar retenção permanente\ + \ de auditoria." + evidence: + - "ART-0015" + - criterion: 5 + text: "Inicialização deixa .ai-engineering fora de Git por padrão e o framework\ + \ funciona sem Git; o comportamento para projetos existentes é explícito e preserva\ + \ conteúdo e regras preexistentes conforme o escopo aprovado. Versionamento\ + \ opcional pelo desenvolvedor não exige integração Git LFS nesta versão." + evidence: + - "ART-0015" + - criterion: 6 + text: "Migração explícita oferece preview e cópia de segurança e verifica preservaç\ + ão de IDs, conteúdo e proveniência legados; falhas, recuperação e reversão sã\ + o exercitadas com dados descartáveis, sem impor auditoria extensa a novos registros." + evidence: + - "ART-0015" + - criterion: 7 + text: "Script e pacote são preparados para instalar e atualizar AIE nativo e SQLite\ + \ juntos num diretório do usuário, com atalhos em ~/.local/bin, e validados\ + \ por fixtures e smoke de build na plataforma alvo. Não executar instalação\ + \ real nem substituir a distribuição ativa; bancos de projeto permanecem separados\ + \ dos binários. Compatibilidade JVM/Native Image e protocolo/CLI é documentada." + evidence: + - "ART-0015" + - criterion: 8 + text: "Entrega registra resultados de verificação e cenário reproduzível para\ + \ retomar responsividade no WRK-000C, sem encerrá-lo automaticamente." + evidence: + - "ART-0015" + integrations: [] + noIntegrationReason: "Canonical changes and execution results are recorded in the\ + \ Plan step evidence" + origin: "SYSTEM_PLANS" + delegation: null + aggregation: + receipt: "ART-0015" + inputHash: "ca97695e9cd8cd557b48e25b8cbedb372ae7ef892fa164e59042c60892c25152" + requester: "Codex" + requestId: "ad8644c1-8c18-4c00-ba7e-8b4720dba3c8" +events: +- action: "COMPLETE" + by: "system:plans" + reason: "All required Plans completed; requester=Codex" + at: "2026-11-22T14:23:22.777113Z" +archived: false +topics: +- "TOP-0001" +- "TOP-0002" +surveys: +- "SVY-0001" +- "SVY-0002" +dispositions: [] +agentRuns: [] +epic: false +guidance: + mode: "EXPLORATORY" + approvalPolicy: "REQUIRED" + history: + - mode: "EXPLORATORY" + approvalPolicy: "REQUIRED" + by: "Nilton" + reason: "Nilton escolheu explicitamente EXPLORATORY para este novo Work nesta\ + \ conversa, para detalhar arquitetura, migração e recuperação antes da decisã\ + o." + at: "2026-11-22T10:44:39.918751Z" + humanApproved: true + decisionRequests: + - decisionId: "DEC-0001" + by: "Nilton" + reason: "Pedido explícito nesta conversa para emitir a DEC da proposta consolidada,\ + \ com restrição de não realizar instalação nativa enquanto projetos em andamento\ + \ usam a instalação atual." + at: "2026-11-22T11:42:07.724623Z" + humanApproved: true +--- diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c1a5398..2d84b20 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -17,7 +17,7 @@ jobs: distribution: temurin java-version: '25' - uses: gradle/actions/setup-gradle@v4 - - run: ./gradlew clean test bootJar --console=plain + - run: ./gradlew clean check bootJar --console=plain - uses: actions/upload-artifact@v4 if: always() with: @@ -38,6 +38,9 @@ jobs: runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' - uses: graalvm/setup-graalvm@v1 with: version: '25.5' @@ -56,8 +59,9 @@ jobs: - name: Native continuity smoke shell: bash run: | - native_binary="$PWD/build/native/nativeCompile/ai-engineering" + native_binary="$PWD/build/native/package/ai-engineering" if [[ "$RUNNER_OS" == Windows ]]; then native_binary="${native_binary}.exe"; fi + python3 scripts/verify-native-package.py "$PWD/build/native/package" bash scripts/native-smoke.sh "$native_binary" - uses: actions/upload-artifact@v4 with: diff --git a/README.md b/README.md index 099a94e..fe13c22 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,11 @@ AI Engineering (AIE) is a local CLI for keeping engineering work understandable across people, AI agents, and sessions. It stores goals, discussions, decisions, -plans, and verification evidence as readable files alongside your project. +plans, and quality results in a local SQLite database for each project. Use it in a single folder or across several source repositories. Git is optional. -The core workflow runs without a model API, database, or background service. +SQLite runs inside AIE; no database server, model API or background service is required. +State stays outside Git by default. Versioning it is the developer's choice. ## What you can do @@ -53,71 +54,46 @@ ai-engineering() { java -jar "$AIE_JAR" "$@"; } The JAR requires Java 25 at runtime. On Windows, use `gradlew.bat` in place of `./gradlew`; you can invoke the JAR directly with `java -jar` and its full path. -### Build a native executable +### Prepare a native package -On Linux (x64/ARM64) and macOS (Apple Silicon), build and install for your user: - -```sh -./scripts/install-native.sh -``` - -The script uses a compatible `GRAALVM_HOME` or `JAVA_HOME`, otherwise installs the -GraalVM version pinned in `.sdkmanrc` through [SDKMAN](https://sdkman.io/install/), -installing SDKMAN too when needed. It builds with the Gradle Wrapper, checks the -executable, copies it to `~/.local/bin/ai-engineering`, and creates the `aie` -shortcut. Run the same command again to update. The installed copy works independently -of this checkout. A failed build or executable check leaves the previous installation -in place. Downloads require internet access. - -If `~/.local/bin` is not in your `PATH`, add this to your shell profile and current -session (the script prints the appropriate command for your destination): - -```sh -export PATH="$HOME/.local/bin:$PATH" -aie --help -``` - -Use `./scripts/install-native.sh --bin-dir /path/to/bin` to select another destination. -The script can be invoked from any directory and does not modify shell profiles or -install system packages. It requires `curl`, `zip`, and `unzip` when installing GraalVM -through SDKMAN. Install [native build prerequisites](https://www.graalvm.org/jdk25/reference-manual/native-image/) -before running it: - -- macOS: `xcode-select --install` (Apple Command Line Tools). -- Debian/Ubuntu: `sudo apt-get install build-essential zlib1g-dev`. -- Fedora/RHEL: `sudo dnf install gcc gcc-c++ glibc-devel zlib-devel libstdc++-static`. - -The pinned GraalVM does not support macOS Intel; use the JVM instructions above. - -For a manual native build: - -The native executable runs without a JVM. Building it requires **GraalVM for -JDK 25**, Native Image, and a C/C++ toolchain for the target platform. Set both -`JAVA_HOME` and `GRAALVM_HOME` to your GraalVM installation. - -If you use SDKMAN, the repository pins a compatible toolchain in [.sdkmanrc](.sdkmanrc): +On Linux (x64/ARM64) and macOS (Apple Silicon), use the GraalVM JDK 25 pinned in +[.sdkmanrc](.sdkmanrc), Native Image, a C/C++ toolchain and Python 3: ```sh sdk env install sdk env export GRAALVM_HOME="$JAVA_HOME" -./gradlew nativeCompile -./build/native/nativeCompile/ai-engineering --help -``` - -Add the executable's directory to `PATH` to use `ai-engineering` from other folders. -On Windows the executable is named `ai-engineering.exe`. The shorter `aie` command -can be provided as a local alias or symlink. - -To create distribution archives: - -```sh +./gradlew nativePackage +python3 scripts/verify-native-package.py build/native/package ./gradlew nativeDistZip nativeDistTar ``` -Archives are written to `build/distributions/` and include the README, documentation, -and MIT license. Build on the intended OS and architecture; the native CI matrix -is defined in [.github/workflows/build.yml](.github/workflows/build.yml). +These commands prepare build outputs. The complete package contains AIE, the +companion JDBC/native libraries and a pinned `sqlite3` diagnostic executable. +Keep those components together; copying the AIE executable alone is insufficient. +SQLite source is checksum-pinned in [sqlite-version.json](scripts/sqlite-version.json). +Distributions are written to `build/distributions/` with docs and licenses. +Build on the intended OS/architecture. macOS Intel uses the JVM distribution. + +### Install when ready + +Installation is a separate action. From a checkout: + +```sh +./scripts/install-native.sh +``` + +The script prepares and verifies the complete package before activation. It uses a +compatible `GRAALVM_HOME`/`JAVA_HOME`, or obtains the pinned GraalVM through SDKMAN. +Defaults are `~/.local/lib/ai-engineering` for releases and `~/.local/bin` for +`ai-engineering`, `aie` and `aie-sqlite3` shortcuts. Project databases stay in their +projects. Failed checks preserve the prior installation; activation failures restore +the prior release/shortcuts. No project is migrated by installation. + +Use `--lib-dir DIR --bin-dir DIR` for custom destinations. The script does not edit +shell profiles or install system packages. Add your bin directory to PATH yourself. +Native builds require platform C/C++ and zlib development tools; SDKMAN bootstrap +also needs curl, zip and unzip. Installer verification uses Python 3. ## Quick start @@ -144,8 +120,9 @@ ai-engineering project validate `init` creates `.ai-engineering/` and installs portable instructions for agents, including a managed block in the project's `AGENTS.md`. Existing project rules -outside that block are preserved. Keep the canonical engineering files under -version control when you use Git; `.ai-engineering/.local/` contains local state. +outside that block are preserved. New state is SQLite and `/.ai-engineering/` is +added to .gitignore, even without Git installed. `init --version-state` leaves ignore +policy to you. Existing tracked files are never untracked automatically. The exported context brings together the Work's scope, discussion, decisions, plans, evidence references, and pending questions. `next-actions` suggests what to @@ -226,7 +203,8 @@ model call. Direct human approval remains available through `decision accept`. | Survey | Questions with suggested choices, free text, and answer history | | Decision | A reviewed choice with explicit approval and revision history | | Plan | Steps, dependencies, observed results, and evidence references | -| Artifact | Retained evidence with integrity metadata | +| Artifact | Temporary check input with integrity and retirement state | +| Quality gate | Required project/Work check and state-bound observed result | Completed required plans can consolidate a Work automatically. The framework checks recorded state and evidence integrity; it does not prove that arbitrary @@ -236,6 +214,20 @@ and system completion retains its own provenance. See the [protocol reference](docs/protocol.md) for commands, formats, lifecycle rules, and recovery behavior. +## Quality and retention + +Investigation/discussion and implementation remain connected through DEC and Plan. +OODA guides experiments and reconsideration. Required gates come from the project, +with additional gates per Work; pending, failed or stale checks block delivery. +Checks run externally. AIE records the actual observation against an evaluated +state and keeps a short result; human approval is separate. + +Evidence attachments stay available while checks need them. After Work completion, +new temporary copies retire automatically; missing input before a check is an error. +Outputs requested by the user belong at their delivery destination outside AIE state. +Internal receipts are structured database facts. Legacy originals and migration safety +copies remain preserved. See [gates and retention](docs/protocol.md#quality-gates). + ## AI agent integration Agents can discover the protocol through `AGENTS.md` and `.ai-engineering/`. @@ -266,9 +258,9 @@ ai-engineering project validate --format json `CURRENT` and `LEGACY_COMPATIBLE` both indicate readable formats. Supported older records remain readable without automatic normalization or reopening completed -Works. `onboard` refreshes entry instructions with backups while preserving Work -files. The [compatibility guide](docs/compatibility.md) explains contract versions, -storage formats, diagnostics, and future explicit migrations. +Works. `onboard` refreshes entry instructions without converting storage. To move a +legacy project to SQLite, review `aie storage migrate --format json`, then apply +with its fingerprint. See [migration and recovery](docs/storage-migration.md). ## Development and verification @@ -294,6 +286,7 @@ Tests generate JUnit results and JaCoCo coverage. Open |---|---| | [Protocol reference](docs/protocol.md) | Commands, records, approval, persistence, and recovery | | [Compatibility](docs/compatibility.md) | Supported formats and update procedures | +| [Storage migration](docs/storage-migration.md) | Preview, apply, recover and rollback | | [Work conduct and OODA](docs/work-guidance.md) | Human discussion choices, DEC authority and optional Plan experiments | | [Discussion and refinement](docs/discussion-slice.md) | Topics, surveys, and proposal handling | | [Plan consolidation](docs/plan-consolidation.md) | Steps, results, and automatic completion | diff --git a/build.gradle.kts b/build.gradle.kts index da8f3a0..a7de470 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -24,6 +24,7 @@ dependencies { implementation("info.picocli:picocli:4.7.7") annotationProcessor("info.picocli:picocli-codegen:4.7.7") implementation("tools.jackson.dataformat:jackson-dataformat-yaml") + implementation("org.xerial:sqlite-jdbc:3.54.1.0") testImplementation("org.springframework.modulith:spring-modulith-starter-test") { exclude(group = "org.junit.jupiter") exclude(group = "org.junit.platform") @@ -39,6 +40,7 @@ tasks.withType().configureEach { } tasks.test { useJUnitPlatform() + jvmArgs("--enable-native-access=ALL-UNNAMED") dependsOn(tasks.bootJar) systemProperty("cli.jar", tasks.bootJar.get().archiveFile.get().asFile.absolutePath) finalizedBy(tasks.jacocoTestReport) @@ -65,34 +67,88 @@ val jenkinsPipelineTest = tasks.register("jenkinsPipelineTest") { } tasks.check { dependsOn(jenkinsPipelineTest) } springBoot { mainClass = "net.intrepid.aiengineering.AiEngineeringApplication" } +val sqliteProbe = sourceSets.create("sqliteProbe") +sqliteProbe.compileClasspath += sourceSets.main.get().output +sqliteProbe.runtimeClasspath += sourceSets.main.get().output +configurations[sqliteProbe.implementationConfigurationName].extendsFrom(configurations.implementation.get()) +configurations[sqliteProbe.runtimeOnlyConfigurationName].extendsFrom(configurations.runtimeOnly.get()) +tasks.register("sqliteProbe") { + group = "verification" + description = "Exercise SQLite in a separate JVM against an explicitly supplied disposable database." + classpath = sqliteProbe.runtimeClasspath + mainClass.set("net.intrepid.aiengineering.probe.SqliteProbe") + jvmArgs("--enable-native-access=ALL-UNNAMED") + if (providers.gradleProperty("probeDatabase").isPresent) { + args(providers.gradleProperty("probeDatabase").get()) + } +} graalvmNative { binaries.named("main") { imageName = "ai-engineering" - buildArgs.addAll("--no-fallback", "-O1") + javaLauncher.set(javaToolchains.launcherFor { + languageVersion.set(JavaLanguageVersion.of(25)) + vendor.set(JvmVendorSpec.matching("GraalVM")) + }) + buildArgs.addAll("--no-fallback", "-O1", "--enable-native-access=ALL-UNNAMED", + "-Dorg.sqlite.lib.exportPath=${layout.buildDirectory.dir("native/nativeCompile").get().asFile}") + } + binaries.create("sqliteProbe") { + imageName.set("aie-sqlite-probe") + mainClass.set("net.intrepid.aiengineering.probe.SqliteProbe") + javaLauncher.set(javaToolchains.launcherFor { + languageVersion.set(JavaLanguageVersion.of(25)) + vendor.set(JvmVendorSpec.matching("GraalVM")) + }) + classpath.from(sqliteProbe.runtimeClasspath) + classpath.from(files(layout.buildDirectory.dir("generated/aotResources")).builtBy(tasks.named("processAot"))) + buildArgs.addAll("--no-fallback", "-O1", + "--enable-native-access=ALL-UNNAMED", + "-Dorg.sqlite.lib.exportPath=${layout.buildDirectory.dir("native/nativeSqliteProbeCompile").get().asFile}") } } +tasks.named("nativeSqliteProbeCompile") { dependsOn(tasks.named("processAot")) } val platformName = providers.gradleProperty("targetPlatform").orElse( "${System.getProperty("os.name").lowercase().replace(" ", "-")}-${System.getProperty("os.arch")}") +val sqliteCliName = if (System.getProperty("os.name").startsWith("Windows")) "sqlite3.exe" else "sqlite3" +val sqliteCli = tasks.register("sqliteCli") { + group = "build" + description = "Build the pinned SQLite diagnostic CLI into build/ without installing it." + inputs.files("scripts/build-sqlite-cli.py", "scripts/sqlite-version.json") + outputs.file(layout.buildDirectory.file("sqlite-cli/$sqliteCliName")) + commandLine("python3", "scripts/build-sqlite-cli.py", layout.buildDirectory.dir("sqlite-cli").get().asFile.absolutePath) +} +val nativePackage = tasks.register("nativePackage") { + group = "distribution" + description = "Prepare native AIE, companion libraries and sqlite3 together; no installation." + dependsOn("nativeCompile", sqliteCli) + inputs.file("scripts/native-package-manifest.py") + into(layout.buildDirectory.dir("native/package")) + from(layout.buildDirectory.dir("native/nativeCompile")) { include("ai-engineering", "ai-engineering.exe", "*.dylib", "*.so", "*.dll") } + from(layout.buildDirectory.file("sqlite-cli/$sqliteCliName")) + from("README.md", "LICENSE") + from("docs") { into("docs") } + filePermissions { unix("rwxr-xr-x") } + doLast { + providers.exec { + commandLine("python3", "scripts/native-package-manifest.py", layout.buildDirectory.dir("native/package").get().asFile.absolutePath) + }.result.get().assertNormalExitValue() + } +} tasks.register("nativeDistZip") { - dependsOn("nativeCompile") + dependsOn(nativePackage) archiveBaseName = "ai-engineering" archiveClassifier = platformName destinationDirectory = layout.buildDirectory.dir("distributions") - from(layout.buildDirectory.dir("native/nativeCompile")) { - include("ai-engineering", "ai-engineering.exe") - filePermissions { unix("rwxr-xr-x") } - } - from("README.md", "LICENSE") - from("docs") { into("docs") } + from(layout.buildDirectory.dir("native/package")) + filePermissions { unix("rwxr-xr-x") } } tasks.register("nativeDistTar") { - dependsOn("nativeCompile") + dependsOn(nativePackage) archiveBaseName = "ai-engineering" archiveClassifier = platformName archiveExtension = "tar.gz" compression = Compression.GZIP destinationDirectory = layout.buildDirectory.dir("distributions") - from(layout.buildDirectory.dir("native/nativeCompile")) { include("ai-engineering"); filePermissions { unix("rwxr-xr-x") } } - from("README.md", "LICENSE") - from("docs") { into("docs") } + from(layout.buildDirectory.dir("native/package")) + filePermissions { unix("rwxr-xr-x") } } diff --git a/docs/architecture.md b/docs/architecture.md index 2299e0e..2245014 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,287 +1,114 @@ # Architecture -## Technology selection +AIE is a local engineering memory with two cycles: investigation/refinement and +implementation, connected by DEC and Plan. OODA is adaptive; gates constrain delivery. +The CLI records external observations and applies deterministic checks. It does not +execute repository commands, operate a server or provide distributed collaboration. -The project deliberately stays on a compatible maintenance pair: **Spring Boot -4.0.9 and Spring Modulith 2.0.9**. The published Modulith 2.0.9 POM declares -Boot autoconfigure 4.0.9. Java compilation and bytecode target are both **25**, -without preview features. Gradle **9.3.1** supports running on Java 25; its Wrapper -distribution is pinned with SHA-256 verification. +## Runtime and modules -The local development JDK is pinned through `.sdkmanrc` to SDKMAN candidate -`25.5.5.0+3-graalce` (GraalVM CE 25.5.5.0.3, OpenJDK 25.0.5.0.3). This -[GraalVM innovation release](https://www.graalvm.org/release-notes/25.5/) still uses -Java 25. It provides both JVM and Native Image tooling without changing compilation -target or application dependencies. Use `sdk env` for project-scoped activation; -the Gradle Wrapper remains responsible for the Gradle version. - -Primary compatibility references checked during implementation: - -- [Spring Boot 4.0 requirements](https://docs.spring.io/spring-boot/4.0/system-requirements.html): Java 25, Gradle 9 and GraalVM 25 are supported; Native Build Tools 0.11.5 is the documented version. -- [Published Modulith 2.0.9 dependencies](https://repo.maven.apache.org/maven2/org/springframework/modulith/spring-modulith-core/2.0.9/spring-modulith-core-2.0.9.pom): Boot 4.0.9 dependency. -- [Gradle Java compatibility](https://docs.gradle.org/9.3.1/userguide/compatibility.html): Java 25 support starts at Gradle 9.1. -- [Spring AOT Gradle integration](https://docs.spring.io/spring-boot/4.0/gradle-plugin/aot.html). -- [Picocli native configuration](https://picocli.info/#_graalvm_native_images): annotation-processor-generated reflection metadata. -- [GraalVM 25 release notes](https://www.graalvm.org/release-notes/JDK_25/): macOS x86_64 support was removed. - -Picocli **4.7.7** handles argument validation, help and dispatch. Jackson 3 YAML/JSON -comes from Boot's BOM. JUnit is explicitly pinned to **5.13.4** because the requested -test baseline is JUnit 5; the Boot BOM otherwise selects a newer major generation. -AssertJ and Modulith/ArchUnit verify behavior and dependencies. There is no Spring AI, -Embabel, web starter, persistence server or workflow framework. - -## Module boundaries - -All packages below are under `net.intrepid.aiengineering`. A module's base package is -its explicit public API; implementation-only Git adapters live in `project.internal`. -`package-info.java` declares allowed dependencies. `ArchitectureTest` calls -`ApplicationModules.verify()` to enforce cycles, visibility and dependency rules. +Java 25, Gradle 9.3.1, Spring Boot 4.0.9, Modulith 2.0.9, Picocli 4.7.7 and Jackson 3 +remain pinned by the build. JUnit 5.13.4, AssertJ and Modulith/ArchUnit verify behavior. +GraalVM CE 25.5.5.0+3 is pinned in .sdkmanrc. Spring supplies process lifecycle and AOT; +services are ordinary Java classes with explicit project paths and no retained Work +cache. Infrastructure stays outside immutable domain records. | Module | Owns | May depend on | |---|---|---| -| filesystem | Protocol codecs, safe paths, atomic file writes, locks, errors | none | -| project | Configuration, discovery, repository policy, read-only Git adapter | filesystem | -| work | Work identity/lifecycle, human guidance/history, repository snapshots, references and EPIC policy/graph | project, filesystem | -| discussion | Entries, topics, surveys, answer history and proposal dispositions | work, project, artifact, filesystem | -| decision | Draft, approval, revision and supersession records | work, filesystem | -| planning | Plans, dependencies, step results, experiments and revision history | work, decision, discussion, artifact, filesystem | -| legacyimport | DF preview, original agenda evidence, provenance and prepared Work publication | filesystem, project, work, discussion, artifact | -| artifact | Small evidence payloads and integrity metadata | work, filesystem | -| agent | Adapter contract, deterministic fixtures, routing and proposal application | project, work, discussion, decision, planning, artifact, filesystem | -| verification | Structural conformance, context, reviewed closure and deterministic EPIC coordination | all protocol modules | -| cli | Picocli commands, formats, exit codes | all APIs above | +| filesystem | Codecs, paths, SQLite sessions/typed storage, atomic external files and locks | none | +| project | Bootstrap, discovery, native/entry contracts and repository policy | filesystem | +| work | Work identity/guidance/lifecycle, source snapshots and EPIC graph/policy | project, filesystem | +| discussion | Entries, topics, surveys, answer history and dispositions | work, project, artifact, filesystem | +| decision | Drafts, approvals, revision and supersession | work, filesystem | +| planning | Plans, dependencies, results, experiments and scope exclusions | work, decision, discussion, artifact, filesystem | +| artifact | Temporary payloads, lifecycle, publication recovery and typed receipts | work, filesystem | +| agent | Proposal adapters, bounded local transport, validation and application | project, work, discussion, decision, planning, artifact, filesystem | +| legacyimport | Explicit DF preview/import, preserved originals and provenance | filesystem, project, work, discussion, artifact | +| verification | Integrity/readiness, gates, snapshots, coordination, migration and context | protocol modules | +| cli | Picocli commands and presentation | public module APIs | -Spring owns the process lifecycle and CLI bean, and supplies AOT processing. Protocol -services are ordinary Java classes with explicit path arguments and no retained Work -cache. This keeps direct tests and fresh instances simple. Infrastructure dependencies -remain inside services, outside immutable domain records. The small `GitAdapter` port -is internal to Project and can be replaced without changing Work contracts. +ArchitectureTest enforces these boundaries. Work does not import Decision, Artifact +or Verification. Verification coordinates across independently owned domains. -Context assembly, readiness and evidence-mapped closure belong to Verification because they combine independently persisted -modules and refuse to export structurally inconsistent state. Work does not depend -on Discussion, Decision or Artifact, avoiding cycles. It owns stable references only. +## Storage boundary -The engineering project is independent of repository count: a plain folder can use -the protocol with no Git dependency, a single Git repository can register the root -using `.`, and a larger workspace can register several child repositories. The same -configuration schema and services support each case; no separate project mode or -additional repository type is needed. +New projects use `.ai-engineering/aie.db`, selected explicitly in the bootstrap. +Small configuration and entry files remain outside the database. File existence alone +never selects SQLite. Contract 4 and the database application/schema versions are +validated before use. Legacy decoding remains explicit and never converts on read. -Work refinement uses an immutable update value that distinguishes omitted fields from -explicitly emptied lists. The domain preserves identity, lifecycle and references; -the filesystem service locks the project and replaces front matter while retaining -trailing notes. Discussion file input belongs to the CLI adapter: Picocli enforces -exclusive text sources and a bounded strict UTF-8 read supplies the existing domain -entry. Neither feature changes canonical record schemas or introduces new modules. +SQLite JDBC 3.54.1.0 provides the embedded engine. SqliteDatabase owns connection +lifecycle, foreign keys, WAL/FULL durability, IMMEDIATE writes, snapshot reads and +bounded busy waits. Nested services share a transaction; failed nested mutations +cannot be accidentally committed after an exception is caught. File-publication +callbacks run after commit or rollback, after the connection closes. -## Persistence and native execution +SqliteRecords maps trusted record components to typed scalar columns and ordered +child rows. Composite operational values have a domain codec, not serialized file +content. List presence preserves null versus empty, necessary for historical hashes. +Identity/current-revision/format/reference tables retain ownership and revisions; +EPIC links have a unique child-parent index and foreign keys. Selected Work reads +use direct keys. Global integrity checks still inspect the whole project. -Writers take an OS file lock per project. Nested service calls on the same thread reuse -the outer lock; other threads/processes cannot interleave the proposal application. -Complete UTF-8 files are written to a sibling -temporary file, forced to disk and published atomically. New files use a hard link -to avoid overwriting an existing destination. Existing files use atomic replacement; -unsupported filesystems fail instead of quietly falling back to partial writes. -New Works, projects and artifact payload bundles are staged before directory rename. -See the protocol document for crash limits and recovery. +A project publication lock fences storage migration/rollback from writers. SQLite +commands wait a bounded interval and reject a backend transition observed while +waiting. Ordinary related reads need no file lock and use one database snapshot. -Jackson parses explicit records, rejects unknown fields, duplicate YAML keys and -unsupported schema versions. Native hints register those records; Picocli's annotation -processor provides command reflection metadata. The Spring AOT tasks are wired by the -native build plugin. No application arguments are passed through Spring's property -parser. The entry point explicitly chooses non-web mode and closes its context. +## Quality and temporary files -Discussion document version 2 separates typed YAML metadata from an opaque Markdown -body. The filesystem codec maps that body to the domain record's existing `text` -field; it does not infer structure from prose headings. The reader accepts legacy -YAML-only text as well. Explicit discussion migration backs up originals, preserves -semantic state and skips converted files. New decision narrative (`text`) and plan -description use the same Markdown-body codec; legacy draft DECs remain readable. -Work front matter remains canonical, with additive operational fields. Markdown -context renders discussion/decision prose without YAML escaping. +QualityGates stores required project definitions and cumulative Work additions. +Observed results bind procedures, actual invocation, inputs, Work scope/guidance, +DEC revisions, outcome and a short summary. Missing, failed or stale gates block +manual, Plan and EPIC delivery. Delivery snapshots bind the exact passed results. +Human approval remains a different record and responsibility. -## Operational replacement baseline +Artifact bytes remain outside SQLite. Inputs stay available while the Work needs +checks. Completion atomically records validated retirement intent; after commit, +eligible payloads are unlinked and acknowledged. Pending retirement is repeatable +when deletion or acknowledgement was interrupted. New checks refuse retired inputs. +Structured Plan/EPIC receipts need no payload file. Legacy originals are preserved. +Requested outputs stay in their delivery destinations, outside the cleanup scope. -The user expanded the original bootstrap scope to replace the existing discussion -workflow before introducing intelligent adapters or a legacy importer. Planning is -a concrete ninth module, not a custom workflow engine. A plan records editable scope, -dependencies and externally executed results. Starting/completing steps checks their -dependencies and accepted decisions. No repository command is executed by Planning. +ArtifactPublication journals only owned publication intent. Rollback/recovery removes +its own orphan payload, never an unrelated file. Unknown residue is reported for +inspection. Local provider workspaces are bounded temporary directories; raw transport, +credentials, environment and complete logs do not become engineering memory. -Work owns optional human guidance and its choice/request history. New contract-3 -Works begin without an inferred discussion mode and require human DEC approval. -Decision and Planning enforce that authority; explicit Work-wide waiver retains -system promotion provenance. Planning owns optional experiments inside its existing -revision chain and depends on Discussion to check unresolved planning commitments. -Verification and local CLI adapters expose the applicable conduct and OODA guidance. -Legacy absent fields are omitted to preserve historical digests. +## Authority, coordination and migration -Plan creation prepares eligible deterministic draft-decision promotions through Decision, -validates every reference before publication and records SYSTEM_PLAN provenance -with the causal Plan ID and no fabricated human attestation. Existing accepted -decisions are unchanged. Decision exposes prepared promotion/recovery operations; -Planning coordinates them under the existing project lock. Ordinary failures roll -back the attempted writes; crash interruption remains subject to per-file atomicity -and structural validation. Verification checks promotion links against Plan history. -No adapter is invoked, and the Decision module has no dependency on Planning. -Plans/steps can be reopened and revised when observations change. +Guidance preserves explicit human choices, DEC requests and approval policy. +Decision/Plan revisions enforce accepted authority, dependency completion, experiment +reconsideration and unresolved concerns. SQL promotion/supersession and related +references commit together. RUN failure rolls back its proposal and separately +records a short diagnostic without references to reverted records. Request replay +remains idempotent. No adapter can approve a DEC or answer on behalf of a human. -DEC approval is an explicit human-attestation command, with actor, reason and time. -Accepted records are immutable through the CLI; revision creates a new linked draft. -Acceptance supersedes the prior accepted DEC. Decision and plan changes preserve -the previous complete file under `.history`, linked by SHA-256. Hashes detect broken -chains; they are not signatures or protection against someone rewriting every file. -Cross-record supersession uses per-file atomic publication; validation diagnoses -incomplete links. There is no distributed transaction or automatic history repair. +PlanCoordinator and EpicCoordinator retain SYSTEM_PLANS/SYSTEM_EPIC provenance, +RESULTS/DECOMPOSITION policy and explicit scope-bound delegation. Related SQL +mutations/propagation are transactional. Historical legacy semantics and hashes +remain readable; only the legacy backend retains per-file recovery boundaries. -Verification separates structural validity, mechanical readiness and human judgment. -PlanCoordinator consolidates valid Plan results without invoking an adapter, records -SYSTEM_PLANS receipts and invokes existing EPIC propagation. Planning owns content-bound -scope reviews of cancellations; Verification coordinates public mutations/reconciliation -without a reverse dependency. Reads expose the same pending reasons without writes. -Explicit reopening leaves time to change Plans. Legacy optional fields are omitted -to preserve historical digests. See [the contract](plan-consolidation.md). +StorageMigration previews canonical hashes, retains safety originals, imports typed +records in a separate database, compares content/authority/history and validates +before activation. Exact legacy bytes stay external for revision-chain verification; +readers also compare them with typed rows. Contract 4 and a visible legacy-reader +marker prevent incompatible writers. Recovery is repeatable; rollback refuses to +lose engineering memory written after activation. Existing tracked originals are +not removed. Details: [migration](storage-migration.md). -For inspection-only Works without Plans, manual -readiness requires explicit criteria, resolved questions, reviewed DECs and terminal -plans. Completion records criterion-to-artifact mappings, a stable scope digest, -human approval, and canonical integration file digests or a reason no update is -needed. Canonical-file hashes are historical snapshots; later source evolution does -not invalidate an old delivery. Current completed Work records must still match -their frozen scope. Archive retains every file. Reopening preserves completion and -lifecycle history and permits new discussion/evidence. +## Native package -Project owns provider-neutral entry resources copied into `.ai-engineering` by -`init`/`onboard`, including a machine-readable manifest. A managed root `AGENTS.md` -block points to those resources while preserving surrounding rules. Changed -instructions are backed up; repeated onboarding is idempotent. Context includes the -guide. This supports agents that inspect the project; it cannot force discovery by -an arbitrary agent. `status` and `next-actions` derive diagnostics from persisted -state without executing work or inventing human approval. +`nativePackage` builds AIE and the pinned SQLite diagnostic CLI with companion native +libraries and a checksum manifest. Native hints cover operational records/resources. +The candidate verifier creates a disposable database with native AIE and reads it +with packaged sqlite3. Install preparation is distinct from activation: versioned +releases, a current symlink and shortcuts are switched only after verification. +Installer tests use fake tools and disposable destinations. This Work did not run +an actual installer or modify the active distribution or consumer projects. -## Discussion refinement and adapter boundary - -Discussion still owns refinement; DEC and Plan remain its downstream commitments. -Topics and surveys are functional records in Discussion. Legacy threads are derived -as implicit topics; reads never migrate files. Answers append explicit supersession -links. Archive/restore dispositions retain proposals and require policy/evidence. -There is no separate Idea entity. See [record contracts](discussion-slice.md). - -Agent is the tenth module. `AgentAdapter` accepts immutable context/task/executor -values and returns a typed `AgentProposal`; it receives no filesystem Path, persistence -service or execution tools. Only two deterministic adapters are registered. General -selects an activity when omitted and provides fallback for unspecialized activities; -an explicit activity selects its configured executor. Classification in fixtures uses -task markers, not natural-language model interpretation. - -AgentService validates the entire proposal before applying it through domain APIs. -It rechecks the source fingerprint under the project lock to reject concurrent stale -application. A RUN preserves source digest, selected executor, requester, task, -proposal, applied references and terminal/error state. Completed request IDs provide -idempotent replay of identical input. An interrupted APPLYING run blocks new runs -pending inspection. Publication is atomic per file, not a rollback transaction; -FAILED records and validation expose partial application for deliberate repair. - -Verification reads run provenance and computes staleness from canonical semantic -sources, excluding run bookkeeping. State checks never invoke an adapter. A summary -is a recorded result; fresh context does not implicitly rerun it. Adapter output -cannot provide human survey answers, approve DECs, complete Works or execute commands. -Typed records and nested proposal values have Native Image reflection hints. -The initial slice did not add provider integration; the local CLI slice below extends it. - -## Local provider CLI transport - -PLN-0003 implements the human-selected Codex/Claude CLI transport for Discussion and -synthesis. The agent module retains the same public adapter boundary. Its internal -LocalProcess uses fixed ProcessBuilder vectors, bounded streams, virtual threads, -timeout/descendant termination and private temporary workspaces. It receives no -engineering root. Provider tool/configuration controls constrain proposals, while -OS/provider policy remains separate. The full contract and verified CLI references -are in [cli-adapters.md](cli-adapters.md). - -Versioned wire schemas normalize provider output into existing AgentProposal values; -the framework assigns identity and performs ownership/policy preflight. Classification -can request clarify surveys. An explicit activity skips that provider call. Immutable -previous RUNs travel in context, but derived run bookkeeping stays out of semantic -source fingerprints. Only validated results publish canonical RUNs. Earlier transport -failures return safe diagnostics without mutating Work state or storing raw stderr. - -Optional invocation provenance captures observed version, configured role/model, -duration and output digest. Absent optional fields are omitted to preserve older -fingerprints/digests. Setup collects/validates all answers before initialization and -does not invoke providers. No Node SDK, HTTP client framework or external service is -required by tests. Deterministic JDK subprocess fixtures use the production transport. - -## EPIC coordination - -PLN-0002 implements DEC-0003 within the existing modules. Work owns the EPIC marker, -definition, forest topology, revision history and explicit policy authorization. -Verification coordinates lifecycle writes and checks affected ancestors, using -Artifact for owned aggregate receipts. No extra module, broker, workflow engine or -agent invocation is needed. Low-level storage callers must reconcile explicitly; -public CLI/Verification lifecycle entry points propagate within the project lock. - -Policy authority binds parent/important-child scopes and links, excluding execution -status. Important child completions and local readiness control RESULTS completion; -DECOMPOSITION remains a reviewed human delivery. System completions record their -origin, policy delegation and receipt, with humanApproved=false. Historical direct -human completions keep their existing digest/approval semantics. - -Frozen EPIC scope digests include current important delivery records; optional -execution can continue independently. Deterministic serialization uses ordered maps -and canonical records across JVM/native processes. Automatic receipts exclude prior -receipts from their input key, allowing reuse after interrupted publication. -Reconciliation derives state from files; no mutable in-memory index is authoritative. -Details and explicit reopening/reauthorization rules are in [epics.md](epics.md). - -## Compatibility inspection - -The project module owns the protocol contract revision independently of the CLI -release and manifest schema. Filesystem owns the supported storage-format catalog; -existing typed readers continue interpreting older representations in memory. -Verification's compatibility service inspects actual metadata and typed content, -including record revisions and system completion receipts. The CLI exposes a full -read-only report through `project compatibility` and a summary in `status`. - -This adds no automatic conversion or blanket normalization. Onboarding refreshes -entry instructions with backups and refuses to overwrite an unsupported contract. -Frozen prior-release fixtures protect historical approvals, completion provenance, -scope hashes and bytes. See [compatibility](compatibility.md) for the public contract -and requirements before a future incompatible writer or migration is introduced. - -## Earlier framework review and migration - -Both implementations were inspected read-only: - -- The user-identified Python repository at - `/Users/niltonconstantino/personal/workspace.personal/intrepid/discussion-framework`: - README, model/locking/index persistence and structural validation. -- The sibling Java `discussion-framework`: `DiscussionOrchestrator`, - `WorkflowValidator`, `WorkPacket`, `ArtifactDocumentParser` and - `FilesystemDiscussionRepository` concepts and implementations. - -Reused concepts: deterministic context as the handoff surface, stable IDs, explicit -references, file locks, atomic replacement, duplicate/reference checks and separating -content from mechanical CLI state management. No Python code or dependency was copied. -The old generic Markdown inference was replaced by typed, versioned front matter; -semantic sections are explicit and cannot silently disappear from context parsing. - -No legacy HTTP adapter, NDJSON global index, accepted-agenda gate, automatic housekeeping -deletion or Lesson model was retained. Work is the project-scoped aggregate; Discussion -is refinement within a Work. Source repositories were not changed. - -The deterministic DF importer reads each independent source's NDJSON index and open -AGDs. It creates one Work per source+DSC, retaining agenda Markdown as refinement -NOTEs and original bytes as evidence. A versioned owned receipt links source IDs, -DSCs, AGDs, target descriptions and generated AIE references; existing Work schemas -and historical data remain unchanged. Receipt validation is available without the -source directory and compatibility inspection recognizes the receipt format. - -Work, Discussion and Artifact expose prepared publication helpers using their normal -formats. The importer seeds a complete hidden Work folder before the normal atomic -directory publication and monotonic ID reservation. Revalidation under the destination -lock binds application to the preview fingerprint; immutable receipts make retry -recognize already published Works. A multi-Work batch is deliberately not a global -transaction. No legacy decision/Plan/Lesson is imported, source files are untouched -and no agent adapter is involved. See [the import contract](discussion-import.md). -Legacy Lessons remain candidates for manual integration into canonical docs. +Primary references: [SQLite JDBC native support](https://github.com/xerial/sqlite-jdbc#graalvm-native-image-support), +[SQLite transactions](https://sqlite.org/lang_transaction.html), +[foreign keys](https://sqlite.org/foreignkeys.html), +[official source releases/checksums](https://sqlite.org/download.html), +[Boot requirements](https://docs.spring.io/spring-boot/4.0/system-requirements.html), +[Gradle Java compatibility](https://docs.gradle.org/9.3.1/userguide/compatibility.html). diff --git a/docs/compatibility.md b/docs/compatibility.md index e2ff67c..11de4c6 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -1,7 +1,7 @@ # Compatibility and protocol evolution A project's historical records do not have to be rewritten whenever AIE evolves. -Completed Works retain their original files, approvals, evidence and completion +Completed Works retain useful memory, approvals, validated evidence results and completion provenance. Continued readability is a reader responsibility, not a reason to reopen delivered work or to add current refinement content to old Works. @@ -32,13 +32,24 @@ No repository commands, adapters, locks or writes occur during compatibility rea | `UNSUPPORTED` | A declared version has no supported reader | 4 | | `INVALID` | Malformed metadata, unknown fields, missing records or invalid typed content | 4 | -The report is an inspection, not a conversion plan. No required migrations are -registered, so `migrationRequired` is false, including for unsupported versions: +The report is an inspection, not a conversion plan. Legacy reading does not require conversion, so `migrationRequired` is false, including for unsupported versions: an unknown version is not evidence that an older CLI can convert it. Unsupported records require a CLI with the appropriate reader; invalid data needs deliberate repair. Basic command/path errors retain the usual exit codes. -## Three independent version dimensions +Contract 4 adds `sqlite-storage`, `local-memory`, `quality-gates`, +`temporary-artifacts` and the explicit storage migration route. New projects select +SQLite and ignore state by default. Legacy projects can remain readable on their +original backend. SQLite requires contract 4; a database without the matching +bootstrap is refused rather than treated as empty memory. + +The SQLite report inspects typed records/revisions in the database. Bootstrap, +database schema and original legacy document versions remain separate dimensions. +Project validation checks foreign keys, revision chains and evidence/retirement facts. +A retired attachment is valid historical evidence only with its persisted validation; +new checks still require available inputs. + +## Independent version dimensions `protocol.json.schemaVersion` describes the manifest's structure. Its new optional `protocolVersion` identifies the engineering contract. The initial explicit contract @@ -49,7 +60,7 @@ operations and onboarding from overwriting a newer contract. Compatibility inspe remains available to explain the mismatch. Contract 2 advertises deterministic DF open-agenda import. The CLI reads contracts -1, 2 and 3, and existing contract-1 projects remain legacy compatible without any +1, 2, 3 and 4, and existing contract-1 projects remain legacy compatible without any Work migration. An import-enabled manifest requires contract 2 and the `discussion-import` capability. This makes old contract-1 CLIs refuse the new manifest before onboarding could overwrite its feature declaration. `onboard` @@ -70,7 +81,8 @@ The format catalog is deliberately small: | Canonical record schema (including configuration and Work) | 1 | 1 | | Narrative document | 2 | 1, 2 | | Metadata-only document (Work) | 1 | 1 | -| Work sequence | 2 | 1, 2 | +| Work sequence (legacy files) | 2 | 1, 2 | +| SQLite schema/application | 1 / AIE1 | 1 / AIE1 | `schemaVersion` and `documentVersion` describe different layers of one file. A discussion may have record schema 1 in document version 2. An omitted document @@ -84,7 +96,7 @@ record has been converted. The scanner reads actual versions in current records history; mixed supported versions are normal. Capabilities are discovery labels, not independent migration versions or evidence that a feature has been configured. -## Updating instructions and future migrations +## Updating instructions and storage `aie onboard` is idempotent and backs up changed entry files. It refreshes the README, agent instructions and manifest, preserving project rules outside the managed block. @@ -99,12 +111,12 @@ reader/adaptation path and retained fixtures. Unknown schemas and fields must no be silently ignored to simulate compatibility. Increasing a writer version must not remove an existing reader or alter the meaning of historical approval/provenance. -A future required conversion must declare its source and target versions and expose -a public command that previews exact scope before applying changes, backs up original -bytes, resumes safely and is idempotent. The report may only claim a required migration -when a known route actually exists. Completed historical Works must retain a read path; -they must not be selected for blanket normalization. There is no placeholder migration -command and no automatic project-wide rewrite in this release. +The public SQLite route is `storage migrate` (read-only preview), then +`--apply --expect HASH`. `--recover` and `--rollback` require the operation's same +fingerprint. It is optional for supported legacy reading and never runs implicitly. +Read [the migration procedure](storage-migration.md) before conversion. Unknown +schemas still need an appropriate reader; this route converts supported legacy +records, not arbitrary unsupported versions. ## Historical regression fixture diff --git a/docs/discussion-import.md b/docs/discussion-import.md index 9534649..300ba9f 100644 --- a/docs/discussion-import.md +++ b/docs/discussion-import.md @@ -92,3 +92,8 @@ Exit codes follow AIE: 0 for a valid preview/application, 2 for invalid command arguments, 3 for a missing project/root, 4 for invalid/stale/review-required data, and 1 for unexpected I/O failures. Diagnostics after partial publication retain the normal failure code and identify the Work IDs already published. + +SQLite application commits the batch and its references together. Failure rolls back +all Works in that transaction and recovers owned temporary payloads. The explicit +legacy backend keeps its per-Work publication/resume boundary. Imported originals +and import provenance remain preserved by the current retention policy. diff --git a/docs/discussion-slice.md b/docs/discussion-slice.md index 5d5db9e..d4353de 100644 --- a/docs/discussion-slice.md +++ b/docs/discussion-slice.md @@ -12,11 +12,12 @@ Existing free-form discussionId threads remain valid and appear as implicit topi an empty Work presents implicit topic `main`. Formal topics can reference original discussion entries without rewriting those entries. -Records reside in Work-local `topics/`, `surveys/`, `dispositions/` and `agent-runs/`. -Prose uses Markdown bodies with documentVersion 2 and schemaVersion 1 metadata. -Topic and survey revisions preserve complete prior files with SHA-256 links under -their `.history/` directories, following decision/plan conventions. New files are -published before Work references; interrupted cross-file writes are diagnosed. +SQLite stores these records and their revisions as typed data. Related publication +and Work references commit together. Legacy directories/Markdown and `.history` +remain supported on the explicit file backend; migration preserves original bytes. +SQLite RUN application rolls back the full proposal on failure, then records a short +failure diagnostic without reverted references. Legacy failed publication can retain +partial applied references for deliberate repair. A survey owns immutable question definitions and append-only answers. QST and ANS IDs are survey-local. Each question identifies a topic and nonempty options numbered diff --git a/docs/epics.md b/docs/epics.md index 74db855..ea76f47 100644 --- a/docs/epics.md +++ b/docs/epics.md @@ -1,7 +1,7 @@ # EPIC contract -An EPIC is a Work with `epic: true` and a versioned definition under -`epic/.md`. Ordinary schema-1 Works default to `epic: false`; reads never +An EPIC is a Work with `epic: true` and a versioned typed SQLite policy. +The legacy file backend uses `epic/.md`. Ordinary schema-1 Works default to `epic: false`; reads never rewrite them. Definition revisions retain SHA-256-linked snapshots under `epic/.history//`. Links point to project-scoped Work IDs, not source repos. @@ -50,9 +50,11 @@ editing links/scopes and reviewing authorization again. `epic check` is read-only. `epic reconcile` deterministically repairs missed propagation from canonical child state, including after interruption between child and parent writes. Repeated notifications do not duplicate completion or receipts. -No server, message broker, database or agent invocation is used. Invalid histories, +SQLite is embedded; no server, message broker or agent invocation is used. Invalid histories, missing links and unsafe paths are diagnosed; arbitrary corrupted files still need -deliberate repair. Publication remains atomic per file, not a global transaction. +deliberate repair. SQLite commits related propagation transactionally; only legacy +files retain per-file publication. Required gates also constrain parent delivery. +New aggregate receipts are structured database facts; old receipt files stay readable. ## CLI diff --git a/docs/latency-scenario.md b/docs/latency-scenario.md new file mode 100644 index 0000000..866d54f --- /dev/null +++ b/docs/latency-scenario.md @@ -0,0 +1,35 @@ +# WRK-000C measurement handoff + +SQLite adoption does not close the latency ticket. This scenario prepares comparable +local datasets; it makes no performance claim and was not run as a benchmark in +WRK-000D. Use the same final executable/package, machine and source revision for +both backends. Keep companion libraries beside the executable. + +```sh +python3 scripts/latency-fixture.py --binary "$PWD/build/native/package/ai-engineering" \ + --directory /tmp/aie-latency-sqlite --works 100 --entries 10 --storage sqlite +python3 scripts/latency-fixture.py --binary "$PWD/build/native/package/ai-engineering" \ + --directory /tmp/aie-latency-legacy --works 100 --entries 10 --storage legacy +``` + +Directories must be new. The script creates only synthetic Works/notes, with no +approval, installation or migration. `latency-fixture.json` records version, binary +SHA-256, backend, environment, volume and selected Work. Creation time is distinct +from query latency. Record the source revision/build identifier as well; the release +label alone is insufficient to distinguish this checkout from older 0.1.0 builds. + +Measure fresh processes separately from repeated queries. In each dataset, repeat +`work show WRK-0064 --format json`, `work context WRK-0064 --format json`, +`next-actions WRK-0064 --format json`, `work list --open --format table` and +`status --format json`. Capture wall time, exit status and whether the command gives +feedback while waiting; avoid including terminal rendering time accidentally. +Record each sample, then compare median and tail latency. Vary volume afterward +(1/10/100 Works), using identical note counts and commands across both backends. + +Record OS/CPU, package/JVM mode, protocol/database schema and source access settings. +Use no registered Git repositories first, then measure their contribution separately. +Do not mix migration, integrity repair, network/provider calls or fixture generation +into query timing. The current physical native verification used macOS arm64 and +GraalVM CE 25.5.5.0+3 with SQLite JDBC 3.54.1.0 / sqlite3 3.54.1; other machines need +their own recorded environment. WRK-000C remains OPEN until actual measurements and +responsiveness criteria justify its decision and implementation. diff --git a/docs/legacy-file-storage.md b/docs/legacy-file-storage.md new file mode 100644 index 0000000..bbc2569 --- /dev/null +++ b/docs/legacy-file-storage.md @@ -0,0 +1,609 @@ +# Legacy file backend reference + +This reference applies to the explicit legacy backend. New projects use SQLite. +For current persistence, gates and retention, read [the protocol](protocol.md). +When recreating legacy examples, add `--storage legacy` to init. +Legacy source documents retained by migration are not a second writable authority. + +# Portable engineering protocol — schema 1 + +## Project root and configuration + +The engineering root is the parent of `.ai-engineering`. Repository paths resolve +against that root, independently of the CLI's current directory. Discovery searches +upward or accepts an explicit `--project` root (or `.ai-engineering` directory). + +An engineering project may be a simple source folder without Git, one Git repository, +or a workspace containing several repositories. All three use the same Work protocol. +Initialize directly in the folder that represents the desired project scope. An empty +`repositories: []` is valid; Works need no repository references to persist discussions, +decisions, artifacts and context. Git is invoked only when inspecting registered +repositories. Without repository references, a Work has no Git revision snapshots. + +For a single Git repository at the engineering root, register it with `path: "."` +and `type: linked-git`. Registration remains explicit; initialization does not create +or register a Git repository. For multiple repositories, register their relative +subdirectory paths as in the example below. + +```yaml +schemaVersion: 1 +project: + id: prometeu + name: Prometeu +repositories: + - id: runtime + path: runtime + type: linked-git + language: rust + access: + read: true + edit: false + validationCommands: [] +``` + +IDs use lowercase ASCII letters, digits and hyphens, beginning with a letter. +Repository types are `linked-git` and `git-submodule`. Omitted `access` defaults to +`read: true, edit: false`. If `access` is supplied its booleans are explicit; edit +requires read. Language is optional. `validationCommands` is optional metadata, +never executable through this release. Unknown fields and schema versions fail validation. + +Absolute repository paths, `..` components, backslashes and symlinks beneath the root +are rejected, including links that point inside the root. This stricter initial rule +avoids ambiguous link policies. A linked Git repository may be the engineering root; +repositories cannot live inside `.ai-engineering`. Git inspection verifies the registered +path is a repository top-level; +submodule registration additionally verifies its superproject. Paths must exist. +No submodules are automatically created, moved or updated. + +Policy controls protocol intent, not OS security. Concurrent malicious filesystem +replacement is outside this CLI's sandbox guarantee; use OS isolation for untrusted +processes. The adapter clears inherited `GIT_*` variables and disables optional Git locks. + +## Work and files + +```text +.ai-engineering/ + ai-engineering.yaml + README.md # portable agent entry point + AGENTS.md # provider-neutral instructions + protocol.json # discovery manifest and capabilities + .gitignore + .local/write.lock # ignored, no semantic state + contracts/ # reserved for project contracts + works/ + .sequence.yaml # canonical high-water mark; commit this + WRK-0001-improve-scene-editor/ + work.md + epic/WRK-0001.md # present when epic: true + epic/.history/WRK-0001/r0001.md + discussions/DSC-0001.md + topics/TOP-0001.md + topics/.history/TOP-0001/r0001.md + surveys/SVY-0001.md + surveys/.history/SVY-0001/r0001.md + dispositions/DSP-0001.md + agent-runs/RUN-0001.md # canonical provenance; version this + decisions/DEC-0001.md + decisions/.history/DEC-0001/r0001.md + plans/PLN-0001.md + plans/.history/PLN-0001/r0001.md + artifacts/ + references/ + experiments/ + evidence/ART-0001/ + artifact.yaml + payload + outputs/ + runs/ # ignored temporary execution outputs +``` + +`work.md`, discussion and decision files contain YAML front matter, delimited by +`---`. Work fields remain in front matter; trailing Work notes are noncanonical. +New discussion/decision narrative and plan descriptions use version 2 Markdown +bodies, with typed metadata in front matter. Legacy YAML-only discussions and draft +DECs remain readable without rewriting. There is no Java object serialization and no +dependency on conversation state. + +Work fields: `schemaVersion`, `id`, `title`, `description`, `goal`, `motivation`, +`constraints[]`, `acceptanceCriteria[]`, `status`, `createdAt`, `updatedAt`, `author`, +`repositories[]`, `discussions[]`, `decisions[]`, `artifacts[]`, `plans[]`, +`completions[]`, `events[]`, `archived`, `topics[]`, `surveys[]`, `dispositions[]`, +`agentRuns[]`, `epic`. Operational, refinement and EPIC fields default to empty/false +when absent in older schema 1 Works. Updated CLI versions write them explicitly; +older CLI binaries that reject unknown fields cannot read these extended records. +Each repository snapshot +records `repositoryId`, relative `path`, exact `head` commit and `dirty`. An empty +repository records `UNBORN`, not an invented commit. Snapshots are taken at Work +creation and remain stable; they are not claims about later experiments. + +Work IDs are project-wide, monotonic `WRK-` identifiers with an uppercase hexadecimal +suffix of four to nine digits: `WRK-0001` through `WRK-FFFFFFFFF`. The sequence passes +from `WRK-0009` to `WRK-000A`, then `WRK-000F` to `WRK-0010`. Zero is not a Work ID; +lowercase, `0x` prefixes and non-hexadecimal characters are rejected. Listing uses +numeric hexadecimal order, including when the width grows beyond four digits. + +A persisted sequence reserves identity before publishing a Work; crashes may leave +gaps. New `.sequence.yaml` files use their own schema version 2: + +```yaml +schemaVersion: 2 +lastWork: "000A" +``` + +`lastWork` is the highest reserved hexadecimal suffix, written as a quoted uppercase +string. `"0000"` represents no reservation. Work records and project configuration +continue to use protocol schema version 1; the sequence file has an independent format. + +Legacy schema version 1 counters with a decimal numeric `lastWork` remain readable. +Existing Work IDs, directory names and references are not renamed. Their suffixes +are interpreted as hexadecimal from this version onward. To protect prior reservations, +the legacy high-water mark is converted by identifier spelling: decimal counter 16 +reserved `WRK-0016`, so it becomes hexadecimal `"0016"` (0x16), even if that Work was +removed. The next identifier is `WRK-0017`. This deliberately leaves any gaps below +that reservation unused. Read/validation commands do not rewrite legacy counters; +the next creation atomically writes version 2 under the project lock. Use the updated +CLI for hexadecimal IDs and version 2 sequence files. + +Do not remove or rewind the sequence. Discussion/decision/artifact/plan IDs remain decimal and are **Work-local**; +their full identity is `(project, Work ID, child ID)`. Work reference arrays determine +history order. Directory names are a convenience; ID stability does not depend on title. +Duplicate Work IDs and directory/record mismatches fail validation. + +Statuses: OPEN, ACTIVE, BLOCKED, COMPLETED, CANCELLED. `work status` changes an open +Work's state but cannot set COMPLETED. `work complete` records the evidence mapping +and explicit approval described below. Terminal or archived Works reject mutation +until `work reopen --by NAME --reason TEXT` returns them to ACTIVE. Reopening preserves +all prior completion records and lifecycle events. Nothing is irreversibly closed. +Legacy COMPLETED Works without completion evidence remain readable, but validation +diagnoses the missing record; reopen and record reviewed evidence before archiving. + +`work update ` explicitly refines `title`, `description`, `goal`, `motivation`, +`constraints[]` and `acceptanceCriteria[]`. Omitted fields retain their current values. +Repeated `--constraint` and `--acceptance` values replace the entire respective list; +`--clear-constraints` and `--clear-acceptance` explicitly empty them. Supplying values +and the corresponding clear option is invalid. A command with no fields is invalid. +Title, goal and individual list entries must be nonblank; description and motivation +can be cleared with an empty string. + +Updates hold the project lock and atomically replace only Work metadata. ID, folder, +status, creator, creation time, repository revision snapshots and all child references +are preserved. `updatedAt` changes only when field values actually change; repeated +identical updates retain the original bytes and timestamp. Trailing noncanonical Work +notes are retained during metadata, status and child-reference updates. Updating a +Work neither approves a DEC nor changes its lifecycle status. Existing discussion and +decision records remain the history of how the scope was refined. + +## Discovery and agent entry + +The directory `.ai-engineering` identifies the protocol workspace. `init` installs +its README, instructions and `protocol.json`. The manifest declares schema, relative +entrypoint/configuration/Works paths, executable, startup commands, capabilities and +explicit human-attestation semantics. `onboard` installs or refreshes those files in +existing projects, without rewriting Work data. It also maintains a root `AGENTS.md` +block between `` and ``. +Rules outside that block remain byte-identical; replaced files have `.local` backups. +Ambiguous, duplicated or unclosed markers cause refusal. Repeated onboarding is a no-op. +Legacy projects with none of the three entry files remain valid. Partial installation, +malformed/duplicate JSON fields, unknown manifest versions and unsupported paths are +validation failures. `onboard` refreshes the contract while backing up changed files. + +`work list`, `status`, and `next-actions` support `--format table|csv|markdown|json`. +Their default Markdown output is a table; `table` aligns columns for terminals, +and CSV provides UTF-8 comma-separated records with stable headers and RFC 4180 +quoting/CRLF record endings. CSV emits no project preamble and keeps original +multiline field values. Empty results still have headers. JSON retains its full +existing records (`Work[]`, `ProjectStatus`, and `Action[]`, respectively). + +Work table/CSV/Markdown columns are `id`, `title`, `status`, `archived`, `steps`, +`pending_actions`, `validation`, and `next_action` (human formats use display +labels). Progress counts COMPLETED steps over all registered steps across Plans, +including cancelled steps in the denominator. No steps means `0/0`; unreadable +Plan data means `unavailable`, with invalid validation and a repair suggestion. +Pending actions count deterministic suggestions, including execution and +maintenance; they are not solely blockers or semantic progress. The next command +is the first existing suggestion, without a new prioritization algorithm. +Action columns are `work_id`, `code`, `message`, and `command`. A project-level +action has an empty `work_id`. Markdown escapes cell text; terminal tables flatten +line breaks/control characters without truncating field values. + +`work list --open` filters every format to nonterminal, unarchived Works: OPEN, +ACTIVE, and BLOCKED. Unfiltered Work lists continue to include archived Works. +Tabular formats apply to these three read commands only; other commands retain +their existing format choices. No storage or protocol revision is required. + +An agent begins with the guide, status, next-actions and selected Work context. These +are portable instructions, not an LLM plugin or enforcement mechanism. Without the +CLI, an agent can inspect the files directly. Agents must still inspect the entry +files and respect project/user rules. Quoted protocol data and evidence do not gain +instruction authority. `guide` also works outside a project. `status` hides archived +Works by default (`--all` includes them); `next-actions [WRK]` returns deterministic +suggestions and never executes a repository action. + +## Discussion and decisions + +Each discussion entry has `schemaVersion`, `id`, `workId`, `discussionId` (thread name), +`kind`, `author`, `createdAt`, optional `respondsTo`, and `text`. Multiple threads can +coexist. Kinds: NOTE, QUESTION, RESPONSE, SUGGESTION, ASSUMPTION, HYPOTHESIS, +INVESTIGATION, ALTERNATIVE, ISSUE, CONCLUSION. Entries are appended, not rewritten. +Text is supplied by a human, external agent or explicitly labeled fixture adapter. + +`discussion add` requires exactly one text source: `--text` for an inline string or +`--text-file` for a regular UTF-8 file up to 1 MiB. A file path resolves relative to +the caller's working directory, independently of `--project`. The entire file is +read as prose, without trimming, newline normalization or front-matter interpretation. +Nonblank content is required. Missing files produce exit 3; nonregular, malformed UTF-8, +blank or oversized input produces exit 2, with no appended discussion. The source is +not changed or retained as an external dependency: later edits/removal cannot alter +the persisted entry. File input does not implicitly register an evidence artifact. + +New discussion files have `documentVersion: 2` in front matter and omit the `text` +field there. The complete Markdown body supplies `text`, including its original +headings, lists, tables, code blocks and whitespace: + +```markdown +--- +schemaVersion: 1 +id: DSC-0002 +workId: WRK-0001 +discussionId: main +kind: SUGGESTION +author: agent +createdAt: '2026-11-11T16:47:32Z' +respondsTo: DSC-0001 +documentVersion: 2 +--- + +## Proposed approach + +Use the next small, testable slice. + +- State the limits. +- Identify supporting evidence. +``` + +One blank line separates the closing delimiter from the body; that formatting line +is excluded from `text`. All subsequent whitespace belongs to the prose. LF and CRLF +front matter are accepted; the reader does not normalize the body's line endings. +`schemaVersion: 1` still describes the protocol record. `documentVersion: 2` describes +this file representation, not a change to JSON context fields. Unknown document +versions and simultaneous YAML `text` plus a version 2 body fail validation. + +Legacy discussions omit `documentVersion` (or declare 1) and keep canonical `text` +in YAML; their trailing body remains noncanonical notes. The new reader accepts both +representations without automatic writes. The old CLI cannot read document version 2. + +`discussion migrate ` explicitly converts legacy entries. Every discussion is +preflighted before any file is replaced. Nonblank legacy trailing notes cause refusal; +incorporate those notes into canonical text first. Original UTF-8 files are backed up +under `.local/backups/discussions///` before atomic replacement. +Migration preserves all semantic fields, Work timestamps and context JSON/Markdown, +and skips already converted entries. It changes formatting, not discussion history. +Interrupted migrations can be resumed; completed files are skipped and existing backups +are retained. This is per-file publication, not an all-or-nothing multi-file transaction. + +A response must refer to an earlier entry in the same Work. Outstanding questions +include QUESTION and ISSUE entries without an explicit RESPONSE or CONCLUSION pointing +to them. This mechanical definition does not infer agreement or approval from prose. + +DEC fields: `schemaVersion`, `id`, `workId`, `title`, `context`, `approach`, +`alternatives[]`, `rationale`, `risks[]`, `acceptanceCriteria[]`, `approvalStatus`, +`author`, `createdAt`, `evidence[]`, narrative `text`, `revision`, `previousHash`, +`updatedAt`, `updatedBy`, `changeReason`, `approvals[]`, optional `revises` and +`supersededBy`. Legacy draft fields default to revision 1, no approvals/links and +empty narrative. Narrative uses document version 2; the JSON `text` field remains explicit. + +Statuses: DRAFT, ACCEPTED, REJECTED, SUPERSEDED. `decision update` changes only drafts, +recording actor/reason and a snapshot. Lists replace entire lists; explicit `--clear-*` +options clear them. `--text`/`--text-file` supplies narrative. Direct acceptance requires +nonblank context/approach/rationale, actor/reason and `--human-approved`. This flag is +an attestation that approval occurred, not authenticated identity or OS permission. +An agent cannot infer approval from a proposal or a prior status. Rejection retains +the proposal. `decision revise` creates a new draft linked to an accepted/rejected +DEC. Accepting that draft supersedes the prior accepted DEC, preserving both records. +Operational choices during execution remain distinct from these formal commitments. + +Creating a Plan from a draft DEC is a separate deterministic acceptance route. +The framework records `origin: SYSTEM_PLAN`, the causal `planId`, actor +`system:planning` and `humanApproved: false`; it does not invent a direct human +attestation. Context, approach and rationale must still be nonblank. Referenced +drafts are promoted and their accepted predecessors are superseded with the same +Plan provenance. Already accepted DECs stay byte-identical; rejected/superseded +DECs and conflicting replacements cannot be used to create the Plan. Optional +approval `origin`/`planId` fields are absent on historical direct approvals, whose +meaning and serialization remain unchanged. Readers predating this capability +cannot read new system-promotion records; use the updated CLI, without rewriting +historical approvals. + +## Topics, surveys and adapter runs + +[Discussion refinement contracts](discussion-slice.md) specify TOP/SVY/DSP/RUN records, +questions, answers, sources and commands. These IDs are decimal and Work-local; +QST/ANS IDs are survey-local. Topic and survey revisions use the same SHA-256 history +convention as decisions/plans. Existing discussionId threads are implicit topic views, +including `main` for an empty Work, without canonical file changes. + +Questions have a topic, suggestions, optional recommendation, single/multiple selection +and discussion sources. Free-text answers are always available. A revised answer +supersedes the prior one without deletion; only the latest determines pending status. +Revision signals a review and does not change accepted decisions/plans. Guided console +answering and noninteractive commands use the same persisted contract. + +Project configuration can optionally include: + +```yaml +agents: + general: + adapter: fixture-general + profile: fixture + model: deterministic + activities: + analyze: + adapter: fixture-reviewer + profile: fixture + model: deterministic + archivePolicy: review-only +``` + +Without agents configuration ordinary commands still work. Agent execution requires +an explicitly configured general. Unknown activities fall back to general; configured +specializations win. Fixture adapters and local codex-cli/claude-cli are available. An explicit +`reversible` policy permits archive with owned ART evidence and a reason; restore +preserves the source and disposition history. Questions/responses cannot be hidden +through proposal archive. Policies are metadata, not OS enforcement. + +RUN records preserve request ID, raw task, requested/chosen activity, requester, +executor, sourceHash, fixture proposal bundle, applied references, status, error and +timestamps. Proposals have typed source links; `@request` in a proposal resolves to a +persisted raw Discussion NOTE. Framework checks validate output before application. +Adapters cannot generate survey answers or human approvals. Fixture analyses are +synthetic observations, never claims about a real experiment or investigation. + +Source fingerprints include semantic project/Work/discussion/survey/evidence/decision/ +plan state, excluding run bookkeeping and Work modification time. Context derives +staleness without invoking an adapter. A proposal-changing run can already be stale +against its own resulting state; sourceHash identifies the input it actually saw. +Identical completed request IDs replay the recorded result even if context later +changes; use a new ID for a new computation. Changed request input with the same ID +is invalid. Interrupted APPLYING records block further runs pending inspection; +FAILED records retain applied references. This is diagnostic publication, not rollback. + +## Local provider executors + +Executor adds optional timeoutSeconds, bounded 1–600; omission means 120 seconds. +Old records remain readable without writing. Null timeout/provenance fields are +omitted from serialized values so legacy fixture digests remain stable. Local CLI +profile/model names are constrained tokens, not arbitrary flags; default model omits +the provider flag. Profile is an AIE role instruction. Provider configuration profiles, +private session state and credentials do not become portable AIE configuration. + +The [CLI adapter contract](cli-adapters.md) defines bounded process invocation, +required controls, versioned schemas, failure semantics and setup. Wire output cannot +set adapter/fixture identity or human authority. The normal complete proposal bundle +must validate before publication. RUN adds optional provenance with classification +and/or proposal invocation: transport, observed CLI version, configured role/model, +durationMillis, timeoutSeconds, outputSha256 and outputBytes. No raw environment or +stderr is canonical. A pre-publication transport failure leaves the Work unchanged. + +General can classify a request into configured/common activities. Explicit activity +skips classification. Clarify requires a survey with suggestions and leaves human +answers pending. Prior RUN outputs are supplied as derived interpretations; source +fingerprints still follow canonical semantic sources. State/conformance/EPIC checks +never invoke a provider. Setup/doctor similarly never sends a model request. + +## Plans and execution records + +Plans are optional, proportional Work-local records (`PLN-0001`). A plan contains +title, Markdown description, referenced decisions, steps, lifecycle status, creator, +timestamps and revision metadata. Each step (`TSK-0001`, decimal and plan-local) +records title/description, acceptance criteria, dependencies, status, result, evidence +and modification time. Statuses match Work's five values but describe external work. + +`plan create --decision DEC` promotes eligible DRAFT decisions without an adapter +or LLM. Guided Works require an explicit Work-wide human waiver; otherwise the DEC +needs human approval before Plan creation. Legacy Works retain prior promotion +semantics until explicit guidance adoption. Input, decision and revision-history validation runs +before promotion, under the project lock. Ordinary publication failures roll back +the attempted Plan and promotions. Publication is atomic per file, not a crash-proof +multi-file transaction: interrupted writes or failed recovery remain inspectable +with `work validate`. Validation checks the causal Plan's first revision, so later +Plan reference edits retain the original promotion provenance and cannot invent it. +Creating another Plan from an already accepted DEC does not add an approval. +`plan update` does not promote drafts; review its references before changing them. + +Step dependencies must exist in that plan and be acyclic. Starting or completing a +step requires completed dependencies and accepted referenced decisions. Completion +requires result text (`--reason`) and owned evidence. `plan status COMPLETED` requires +at least one completed step and all required steps completed; cancelled steps need +explicit scope review with `plan exclude --step`. Exclusions retain the cancelled +record and bind its content hash, actor and reason. Legacy Plans remain readable +without rewriting. Reopen a terminal plan with +`plan status ACTIVE` before editing; reopen terminal steps before changing scope. +Reopening a prerequisite first requires reopening/cancelling its dependent steps. +If a DEC is superseded, reconsider the plan and update its references before execution. + +Plan/step changes retain previous plan snapshots. `decision history` and `plan history` +walk `.history//rNNNN.md`; `previousHash` links each revision to the complete prior +UTF-8 file. Validation checks identity, numbering and hashes. Hashes are integrity +links, not signatures: manual rewriting of an entire chain is not prevented. New +records start at revision 1. A snapshot published before an interrupted current-file +replacement can be reused only when identical; conflicting history is never overwritten. + +The CLI does not execute steps, tests or validation-command metadata. Humans/agents +run real commands externally and record observations, commands, source revisions and +results in evidence. Plans support explicit adaptation; no autonomous OODA engine or +fixed four-phase pipeline is implemented. + +## Completion, integration and archive + +Works with executable Plans derive completion from those Plans. Mutation commands +and `work reconcile WRK` consolidate the last completed step into its Plan and +recheck all associated Plans. Completed required Plans and no pending questions, +surveys, draft DECs or explicit blocking states produce SYSTEM_PLANS completion, +without a model call, repeated human delivery approval or manual Work-level criterion +mapping. Empty sets never auto-complete; reviewed cancellations retain history. +New Plans after delivery require reopening. Unchanged old Plans do not immediately +close an explicitly reopened Work/Plan. See [Plan consolidation](plan-consolidation.md) +for records, provenance and recovery. `work check` reports consolidation pending +reasons; status/context/next-actions remain read-only. Existing EPIC authority and +policy continue to govern EPIC completion. + +For inspection-only Works without Plans, `work check` checks mechanical readiness: explicit acceptance criteria, +no unresolved questions/issues or draft DECs, and terminal plans. Noncancelled plans +must reference currently accepted decisions. Small Works can close without a DEC/plan. +The check cannot determine whether arbitrary prose/evidence proves the desired outcome. + +`work complete` requires human attestation, actor, summary and one unique +`--criterion N=ART-0001[,ART-0002]` mapping per criterion (1-based). Artifacts must +belong to the Work and pass integrity checks. Completion captures criterion text, +evidence IDs, approval metadata and a deterministic SHA-256 digest of scope, source +snapshots, discussion, decisions, plans and artifact metadata. Current COMPLETED Work +data must still match that digest. Reopened Works retain earlier snapshots as history. + +Supply updated canonical project files via `--integration PATH` or explicitly state +`--no-integration-needed REASON`. Integration paths are safe project-relative regular +files outside `.ai-engineering`; their hashes identify contents at closure. Those +files can evolve later without invalidating a historical completion. The CLI records +the attestation/snapshot; it does not prove that the file changed or infer its meaning. +Canonical code/spec/test/docs hold integrated knowledge; no Lesson entity is required. + +`work archive --by NAME --reason TEXT` marks a verified completed or cancelled Work +archived. It retains all files and prior approvals/results. `work reopen` clears +archive, returns to ACTIVE and appends a reasoned event. There is no automatic deletion. +`import discussion` imports DF DSCs with open AGDs using a read-only preview and +an explicit `--apply --expect` fingerprint. Independent `--source ID=PATH` origins +share one AIE destination; targets are described in their Works. Only open agendas +are imported as complete refinement notes and original evidence. Owned versioned +receipts preserve source+DSC identity, source hashes and references without changing +the Work schema. Identical reimports are no-ops; changes are reported for review. +Work publication is atomic per prepared directory, while a batch may be resumed +after partial publication. Closed agendas, DECs, Plans and Lessons are not imported. +See [the import contract](discussion-import.md) for limits, diagnostics and recovery. + +## EPIC policy and system completion + +[The EPIC contract](epics.md) defines topology, authority and recovery. An EPIC remains +a project Work, marked `epic: true`, with one versioned definition in its `epic/` +directory. Links use Work IDs, with important=true by default. Definitions preserve +mode, links, explicit authorization, editor/reason, revision and previousHash. +History follows the DEC/Plan snapshot convention. Initial topology is a forest. + +RESULTS tracks verified important deliveries; optional children are reported without +blocking. Important CANCELLED remains pending. DECOMPOSITION uses ordinary reviewed +closure for the parent's own output and does not wait for execution. Empty important +sets never auto-close. Policy edits require an open parent and invalidate automatic +authority; `epic authorize --human-approved` binds the parent/important-child scopes +and current policy. Authorization is delegation for the structured aggregate condition, +not an inferred human approval of a future delivery. + +Completion records add optional `origin` and `delegation`. Old records default to +HUMAN with no delegation and retain their digest semantics. HUMAN requires direct +humanApproved=true. SYSTEM_EPIC requires humanApproved=false, actor system:epic, +an actual policy authorization/history hash and request correlation. Its criteria map +to a framework-owned aggregate ART receipt containing policy/input and important-child +completion digests. The human's policy delegation attests that this condition suffices +for the parent criteria; the framework performs no semantic inference about prose. + +Frozen RESULTS scope includes important completion records; optional execution can +continue independently. Important reopening reopens ancestors and clears their archive, +retaining prior completions. Explicit reopening of an EPIC suspends its authority for +replanning. Child-caused reopening preserves unchanged-scope authority. BLOCKED and +CANCELLED parents require explicit resumption. Nested propagation runs from descendants +to ancestors under the project lock, without calling any AgentAdapter. + +Public CLI/Verification lifecycle APIs return the changed Work plus affected EPIC +reports when linked; plain Work output remains compatible. `--requester` and +`--request-id` correlate results. IDs correlate notifications rather than acting as a +global transaction log. `epic reconcile [WRK]` derives missed updates from canonical +files and does not duplicate a satisfied completion. A matching published receipt is +reused after interrupted completion. Invalid histories, missing children and orphan +publication are diagnosed; arbitrary corruption still needs deliberate repair. +Low-level storage callers must explicitly reconcile after lifecycle writes. + +## Evidence and integrity + +`artifact add` copies one regular file up to 1 MiB. Its manifest records schema, ID, +Work ID, origin, purpose, Work-relative payload path, SHA-256, byte size, author and UTC +creation time. The origin defaults to the source basename; use `--origin` for a useful +portable provenance reference. Payload bytes are exact. The fixed `payload` filename +avoids filename ambiguity; origin preserves the supplied source identity. + +Validation checks required directories, IDs, schemas, repository references, child +ownership, missing records, orphan records and payload integrity. Evidence paths stay +inside the Work. Large resources should remain in their canonical location and be +described in discussion/reference files, rather than copied into this workspace. +`artifacts/outputs` is versionable for deliberately retained outputs; use ignored `runs/` +for large temporary results. No command creates large output files by default. + +## Compatibility and evolution + +`project compatibility` inspects actual stored formats and revisions without writes. +`protocol.json.schemaVersion` versions the manifest, while optional `protocolVersion` +versions the engineering contract (absent means the supported legacy baseline 1). +The diagnostic exposes the supported read/write format catalog separately from the +executable release. Old compatible records remain valid and readable without +normalization, including COMPLETED Works. `onboard` updates only entry instructions +and the manifest; a newer unsupported contract is never silently overwritten. +See [compatibility and evolution](compatibility.md) for public states, update guidance +and requirements for future explicit conversions. No required migration exists today. + +## Context and continuity + +`work context --format markdown|json` loads only canonical project/Work files. It +includes all Work fields (metadata separately in Markdown), stored source revisions, +ordered discussion history/conclusions, explicit decisions and approvals, plans/results, unresolved questions +and complete artifact references with integrity metadata. JSON has top-level +`schemaVersion`, `work`, `discussionHistory`, `decisions`, `outstandingQuestions`, +`artifacts`, `plans`, `protocolGuide`, `topics`, `surveys`, `dispositions`, `agentRuns`, +`agents`, `epic`, `parentEpic`. Completion and lifecycle history are included +in `work`. It does not embed arbitrary evidence payloads or all revision snapshots; +use history commands when prior versions are relevant. + +No export timestamp, current absolute path or live Git state is injected. Unchanged +files yield byte-identical output across new instances and processes. Export rejects +broken references or integrity failures. It requires neither a model nor live Git +inspection; `project validate` separately verifies live repositories. + +Markdown context renders discussion and decision prose directly, with IDs, authors, +timestamps and reply/approval metadata. Empty sections use `None recorded.`. JSON +keeps the complete typed records, including discussion `text`, regardless of their +on-disk document version. Evidence remains referenced rather than embedded. + +## Write guarantees and recovery + +Protocol mutations hold `.local/write.lock`, an OS lock released automatically at +process exit. Individual files publish atomically; create operations reject overwrites. +New project/Work/artifact directories are staged and renamed. Work sequence reservation +precedes directory publication to avoid identity reuse after interruption. + +A child file/bundle is published before its reference is atomically added to `work.md`. +The filesystem is not a multi-file transactional database: interruption in that window +can leave an orphan, which validation reports. Inspect its metadata and either add its +ID to the Work reference array or remove it after review. Hidden `.tmp` directories are +incomplete staging outputs, ignored by readers; inspect and clean them manually after +an interrupted write. Concurrent manual editors do not honor the CLI lock. Directory +entry durability under sudden power loss depends on the host filesystem. + +## Work guidance and OODA + +Contract 3 adds optional typed Work guidance and Plan experiments. New Works ask +for human discussion mode and require human DEC approval by default; explicit +Work-wide waivers and requests retain human provenance. Guided operations enforce +the selected authority. See [Work conduct and adaptive implementation](work-guidance.md) +for commands, experiment criteria/results, affected execution and legacy behavior. +This preserves the existing loops and does not add a repository executor. + +## Future contracts (design only) + +- Additional AgentAdapter transports and execution permissions: local proposal-only + Codex/Claude CLIs are implemented; direct provider APIs, repository execution and + vendor-native configuration profiles need separate contracts and authorization. +- OODA iteration: identify Work and prior observations, orientation, operational + choices and attempts. Phases can repeat or be skipped; no four-stage workflow gate. +- Attempt: stable identity, hypothesis, input references, exact repository revisions, + granted permissions, invocation/environment, observations, outputs, result and + evidence references. Evidence and interpretation remain distinguishable. +- Coordinated execution: independent per-repository worktrees and commit records, + integrated validation, explicit authority for destructive actions, pushes and merges. + No claim of atomic commits across repositories. +- Conformance: evaluate explicit criteria against evidence and canonical code/spec/test + updates. No required Lesson artifact. Later schema changes require explicit migration. diff --git a/docs/plan-consolidation.md b/docs/plan-consolidation.md index b44c19f..456d8f1 100644 --- a/docs/plan-consolidation.md +++ b/docs/plan-consolidation.md @@ -34,8 +34,11 @@ Receipts use origin `ai-engineering:plans:`. Their input hash om framework receipts so a published receipt can be reused after interruption. Final completion freezes the full scope including the receipt. Recovery validates integrity/history, consolidates Plans, publishes/reuses a receipt, records completion -and invokes existing EPIC reconciliation. Publication is atomic per file; malformed -or orphan records require explicit repair rather than silent deletion. +and invokes existing EPIC reconciliation. SQLite commits these related changes +together; legacy publication remains per-file. New receipts are structured facts in +SQLite. Required project/Work gates must pass for the current evaluated state; +temporary step inputs retire only after all Work checks and completion commit. +Malformed or orphan records require explicit repair. Existing completed Works and legacy serialized hashes remain unchanged. New optional fields are omitted when absent. Manual completion remains available for diff --git a/docs/protocol.md b/docs/protocol.md index f048fd7..071ae2c 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -1,602 +1,148 @@ -# Portable engineering protocol — schema 1 +# Local engineering memory protocol -## Project root and configuration +AIE is a local framework per project. `.ai-engineering/aie.db` owns operational +memory: Works, investigation, decisions, Plans, execution facts and gate results. +Small YAML/JSON and README/AGENTS files bootstrap discovery and configuration. +There is no database server or background process. Git and source repositories are +optional; synchronization, distributed IDs, Git LFS and Work/DEC export are outside +this version. -The engineering root is the parent of `.ai-engineering`. Repository paths resolve -against that root, independently of the CLI's current directory. Discovery searches -upward or accepts an explicit `--project` root (or `.ai-engineering` directory). +## Starting and continuing -An engineering project may be a simple source folder without Git, one Git repository, -or a workspace containing several repositories. All three use the same Work protocol. -Initialize directly in the folder that represents the desired project scope. An empty -`repositories: []` is valid; Works need no repository references to persist discussions, -decisions, artifacts and context. Git is invoked only when inspecting registered -repositories. Without repository references, a Work has no Git revision snapshots. +Run `aie status`, `aie next-actions`, then `aie work context WRK-0001`. +The closest enclosing `.ai-engineering` owns the project. `--project PATH` selects +one explicitly. A SQLite workspace requires a compatible CLI; unavailable or +unreadable memory must be reported, never treated as an empty project. -For a single Git repository at the engineering root, register it with `path: "."` -and `type: linked-git`. Registration remains explicit; initialization does not create -or register a Git repository. For multiple repositories, register their relative -subdirectory paths as in the example below. +`init --name TEXT` defaults to SQLite and adds `/.ai-engineering/` to .gitignore. +`--version-state` leaves ignore policy to the developer without removing existing +rules. Existing tracked files are not untracked. `--storage legacy` is an explicit +compatibility option. Neither reads, `onboard`, nor installation migrate storage. -```yaml -schemaVersion: 1 -project: - id: prometeu - name: Prometeu -repositories: - - id: runtime - path: runtime - type: linked-git - language: rust - access: - read: true - edit: false - validationCommands: [] +Work IDs are uppercase hexadecimal (`WRK-000A`); child IDs are decimal and local to +their Work (`DEC-0001`, `PLN-0001`, `TSK-0001`). The database transaction reserves +new identities and owned references together. Migration preserves reserved gaps. + +## Investigation and implementation + +Discussion/investigation and implementation remain separate cycles connected by +DEC and Plan. Work stores scope, criteria and useful refinement; topics, surveys, +answer supersession and explicit conclusions preserve continuity. OODA is adaptive: +observe results, reconsider assumptions, decide and act. It is not a four-step +ritual imposed on every edit. + +Ask for DIRECT or EXPLORATORY when unspecified. Only the human chooses/changes the +mode or ends exploration. Record choices with `work guidance --human-approved`; +exploratory DEC emission needs `work request-decision`. Human DEC approval is the +default. Direct mode does not waive it. An explicit Work-wide waiver is recorded +separately. Never infer approval from an adapter proposal or status label. + +Accepted DECs are immutable; revisions/supersession retain their authority and +history. Plans require applicable accepted decisions and resolved discussion. +Steps have dependencies, criteria and results. Relevant experiments record their +hypothesis/criterion before execution and observations/interpretation afterward. +Failed hypotheses require reconsideration before retry; DEC concerns block affected +execution until the accepted replacement is referenced. + +See [Work guidance/OODA](work-guidance.md), [refinement](discussion-slice.md) and +[Plan consolidation](plan-consolidation.md) for command details. + +## Quality gates + +Required project gates and additional Work gates are cumulative. A Work cannot +replace a project gate by reusing its local name. Define the procedure and relevant +input files/directories before evaluating it: + +```sh +aie gate configure tests --title "Project tests" --procedure "./gradlew check" \ + --input src --input build.gradle.kts --require-evidence --by owner +aie gate configure review --work WRK-0001 --title "Work review" \ + --procedure "Review the DEC criteria" --input src --by owner +aie gate status WRK-0001 --format json ``` -IDs use lowercase ASCII letters, digits and hyphens, beginning with a letter. -Repository types are `linked-git` and `git-submodule`. Omitted `access` defaults to -`read: true, edit: false`. If `access` is supplied its booleans are explicit; edit -requires read. Language is optional. `validationCommands` is optional metadata, -never executable through this release. Unknown fields and schema versions fail validation. +Obtain `evaluatedHash` before running the procedure externally. Attach required +small evidence with `artifact add`. Then record the actual result: -Absolute repository paths, `..` components, backslashes and symlinks beneath the root -are rejected, including links that point inside the root. This stricter initial rule -avoids ambiguous link policies. A linked Git repository may be the engineering root; -repositories cannot live inside `.ai-engineering`. Git inspection verifies the registered -path is a repository top-level; -submodule registration additionally verifies its superproject. Paths must exist. -No submodules are automatically created, moved or updated. - -Policy controls protocol intent, not OS security. Concurrent malicious filesystem -replacement is outside this CLI's sandbox guarantee; use OS isolation for untrusted -processes. The adapter clears inherited `GIT_*` variables and disables optional Git locks. - -## Work and files - -```text -.ai-engineering/ - ai-engineering.yaml - README.md # portable agent entry point - AGENTS.md # provider-neutral instructions - protocol.json # discovery manifest and capabilities - .gitignore - .local/write.lock # ignored, no semantic state - contracts/ # reserved for project contracts - works/ - .sequence.yaml # canonical high-water mark; commit this - WRK-0001-improve-scene-editor/ - work.md - epic/WRK-0001.md # present when epic: true - epic/.history/WRK-0001/r0001.md - discussions/DSC-0001.md - topics/TOP-0001.md - topics/.history/TOP-0001/r0001.md - surveys/SVY-0001.md - surveys/.history/SVY-0001/r0001.md - dispositions/DSP-0001.md - agent-runs/RUN-0001.md # canonical provenance; version this - decisions/DEC-0001.md - decisions/.history/DEC-0001/r0001.md - plans/PLN-0001.md - plans/.history/PLN-0001/r0001.md - artifacts/ - references/ - experiments/ - evidence/ART-0001/ - artifact.yaml - payload - outputs/ - runs/ # ignored temporary execution outputs +```sh +aie gate record WRK-0001 project/tests --expect \ + --invocation "./gradlew check" --outcome PASS --summary "Observed checks passed" \ + --evidence ART-0001 --by observer --observed ``` -`work.md`, discussion and decision files contain YAML front matter, delimited by -`---`. Work fields remain in front matter; trailing Work notes are noncanonical. -New discussion/decision narrative and plan descriptions use version 2 Markdown -bodies, with typed metadata in front matter. Legacy YAML-only discussions and draft -DECs remain readable without rewriting. There is no Java object serialization and no -dependency on conversation state. - -Work fields: `schemaVersion`, `id`, `title`, `description`, `goal`, `motivation`, -`constraints[]`, `acceptanceCriteria[]`, `status`, `createdAt`, `updatedAt`, `author`, -`repositories[]`, `discussions[]`, `decisions[]`, `artifacts[]`, `plans[]`, -`completions[]`, `events[]`, `archived`, `topics[]`, `surveys[]`, `dispositions[]`, -`agentRuns[]`, `epic`. Operational, refinement and EPIC fields default to empty/false -when absent in older schema 1 Works. Updated CLI versions write them explicitly; -older CLI binaries that reject unknown fields cannot read these extended records. -Each repository snapshot -records `repositoryId`, relative `path`, exact `head` commit and `dirty`. An empty -repository records `UNBORN`, not an invented commit. Snapshots are taken at Work -creation and remain stable; they are not claims about later experiments. - -Work IDs are project-wide, monotonic `WRK-` identifiers with an uppercase hexadecimal -suffix of four to nine digits: `WRK-0001` through `WRK-FFFFFFFFF`. The sequence passes -from `WRK-0009` to `WRK-000A`, then `WRK-000F` to `WRK-0010`. Zero is not a Work ID; -lowercase, `0x` prefixes and non-hexadecimal characters are rejected. Listing uses -numeric hexadecimal order, including when the width grows beyond four digits. - -A persisted sequence reserves identity before publishing a Work; crashes may leave -gaps. New `.sequence.yaml` files use their own schema version 2: - -```yaml -schemaVersion: 2 -lastWork: "000A" -``` - -`lastWork` is the highest reserved hexadecimal suffix, written as a quoted uppercase -string. `"0000"` represents no reservation. Work records and project configuration -continue to use protocol schema version 1; the sequence file has an independent format. - -Legacy schema version 1 counters with a decimal numeric `lastWork` remain readable. -Existing Work IDs, directory names and references are not renamed. Their suffixes -are interpreted as hexadecimal from this version onward. To protect prior reservations, -the legacy high-water mark is converted by identifier spelling: decimal counter 16 -reserved `WRK-0016`, so it becomes hexadecimal `"0016"` (0x16), even if that Work was -removed. The next identifier is `WRK-0017`. This deliberately leaves any gaps below -that reservation unused. Read/validation commands do not rewrite legacy counters; -the next creation atomically writes version 2 under the project lock. Use the updated -CLI for hexadecimal IDs and version 2 sequence files. - -Do not remove or rewind the sequence. Discussion/decision/artifact/plan IDs remain decimal and are **Work-local**; -their full identity is `(project, Work ID, child ID)`. Work reference arrays determine -history order. Directory names are a convenience; ID stability does not depend on title. -Duplicate Work IDs and directory/record mismatches fail validation. - -Statuses: OPEN, ACTIVE, BLOCKED, COMPLETED, CANCELLED. `work status` changes an open -Work's state but cannot set COMPLETED. `work complete` records the evidence mapping -and explicit approval described below. Terminal or archived Works reject mutation -until `work reopen --by NAME --reason TEXT` returns them to ACTIVE. Reopening preserves -all prior completion records and lifecycle events. Nothing is irreversibly closed. -Legacy COMPLETED Works without completion evidence remain readable, but validation -diagnoses the missing record; reopen and record reviewed evidence before archiving. - -`work update ` explicitly refines `title`, `description`, `goal`, `motivation`, -`constraints[]` and `acceptanceCriteria[]`. Omitted fields retain their current values. -Repeated `--constraint` and `--acceptance` values replace the entire respective list; -`--clear-constraints` and `--clear-acceptance` explicitly empty them. Supplying values -and the corresponding clear option is invalid. A command with no fields is invalid. -Title, goal and individual list entries must be nonblank; description and motivation -can be cleared with an empty string. - -Updates hold the project lock and atomically replace only Work metadata. ID, folder, -status, creator, creation time, repository revision snapshots and all child references -are preserved. `updatedAt` changes only when field values actually change; repeated -identical updates retain the original bytes and timestamp. Trailing noncanonical Work -notes are retained during metadata, status and child-reference updates. Updating a -Work neither approves a DEC nor changes its lifecycle status. Existing discussion and -decision records remain the history of how the scope was refined. - -## Discovery and agent entry - -The directory `.ai-engineering` identifies the protocol workspace. `init` installs -its README, instructions and `protocol.json`. The manifest declares schema, relative -entrypoint/configuration/Works paths, executable, startup commands, capabilities and -explicit human-attestation semantics. `onboard` installs or refreshes those files in -existing projects, without rewriting Work data. It also maintains a root `AGENTS.md` -block between `` and ``. -Rules outside that block remain byte-identical; replaced files have `.local` backups. -Ambiguous, duplicated or unclosed markers cause refusal. Repeated onboarding is a no-op. -Legacy projects with none of the three entry files remain valid. Partial installation, -malformed/duplicate JSON fields, unknown manifest versions and unsupported paths are -validation failures. `onboard` refreshes the contract while backing up changed files. - -`work list`, `status`, and `next-actions` support `--format table|csv|markdown|json`. -Their default Markdown output is a table; `table` aligns columns for terminals, -and CSV provides UTF-8 comma-separated records with stable headers and RFC 4180 -quoting/CRLF record endings. CSV emits no project preamble and keeps original -multiline field values. Empty results still have headers. JSON retains its full -existing records (`Work[]`, `ProjectStatus`, and `Action[]`, respectively). - -Work table/CSV/Markdown columns are `id`, `title`, `status`, `archived`, `steps`, -`pending_actions`, `validation`, and `next_action` (human formats use display -labels). Progress counts COMPLETED steps over all registered steps across Plans, -including cancelled steps in the denominator. No steps means `0/0`; unreadable -Plan data means `unavailable`, with invalid validation and a repair suggestion. -Pending actions count deterministic suggestions, including execution and -maintenance; they are not solely blockers or semantic progress. The next command -is the first existing suggestion, without a new prioritization algorithm. -Action columns are `work_id`, `code`, `message`, and `command`. A project-level -action has an empty `work_id`. Markdown escapes cell text; terminal tables flatten -line breaks/control characters without truncating field values. - -`work list --open` filters every format to nonterminal, unarchived Works: OPEN, -ACTIVE, and BLOCKED. Unfiltered Work lists continue to include archived Works. -Tabular formats apply to these three read commands only; other commands retain -their existing format choices. No storage or protocol revision is required. - -An agent begins with the guide, status, next-actions and selected Work context. These -are portable instructions, not an LLM plugin or enforcement mechanism. Without the -CLI, an agent can inspect the files directly. Agents must still inspect the entry -files and respect project/user rules. Quoted protocol data and evidence do not gain -instruction authority. `guide` also works outside a project. `status` hides archived -Works by default (`--all` includes them); `next-actions [WRK]` returns deterministic -suggestions and never executes a repository action. - -## Discussion and decisions - -Each discussion entry has `schemaVersion`, `id`, `workId`, `discussionId` (thread name), -`kind`, `author`, `createdAt`, optional `respondsTo`, and `text`. Multiple threads can -coexist. Kinds: NOTE, QUESTION, RESPONSE, SUGGESTION, ASSUMPTION, HYPOTHESIS, -INVESTIGATION, ALTERNATIVE, ISSUE, CONCLUSION. Entries are appended, not rewritten. -Text is supplied by a human, external agent or explicitly labeled fixture adapter. - -`discussion add` requires exactly one text source: `--text` for an inline string or -`--text-file` for a regular UTF-8 file up to 1 MiB. A file path resolves relative to -the caller's working directory, independently of `--project`. The entire file is -read as prose, without trimming, newline normalization or front-matter interpretation. -Nonblank content is required. Missing files produce exit 3; nonregular, malformed UTF-8, -blank or oversized input produces exit 2, with no appended discussion. The source is -not changed or retained as an external dependency: later edits/removal cannot alter -the persisted entry. File input does not implicitly register an evidence artifact. - -New discussion files have `documentVersion: 2` in front matter and omit the `text` -field there. The complete Markdown body supplies `text`, including its original -headings, lists, tables, code blocks and whitespace: - -```markdown ---- -schemaVersion: 1 -id: DSC-0002 -workId: WRK-0001 -discussionId: main -kind: SUGGESTION -author: agent -createdAt: '2026-11-11T16:47:32Z' -respondsTo: DSC-0001 -documentVersion: 2 ---- - -## Proposed approach - -Use the next small, testable slice. - -- State the limits. -- Identify supporting evidence. -``` - -One blank line separates the closing delimiter from the body; that formatting line -is excluded from `text`. All subsequent whitespace belongs to the prose. LF and CRLF -front matter are accepted; the reader does not normalize the body's line endings. -`schemaVersion: 1` still describes the protocol record. `documentVersion: 2` describes -this file representation, not a change to JSON context fields. Unknown document -versions and simultaneous YAML `text` plus a version 2 body fail validation. - -Legacy discussions omit `documentVersion` (or declare 1) and keep canonical `text` -in YAML; their trailing body remains noncanonical notes. The new reader accepts both -representations without automatic writes. The old CLI cannot read document version 2. - -`discussion migrate ` explicitly converts legacy entries. Every discussion is -preflighted before any file is replaced. Nonblank legacy trailing notes cause refusal; -incorporate those notes into canonical text first. Original UTF-8 files are backed up -under `.local/backups/discussions///` before atomic replacement. -Migration preserves all semantic fields, Work timestamps and context JSON/Markdown, -and skips already converted entries. It changes formatting, not discussion history. -Interrupted migrations can be resumed; completed files are skipped and existing backups -are retained. This is per-file publication, not an all-or-nothing multi-file transaction. - -A response must refer to an earlier entry in the same Work. Outstanding questions -include QUESTION and ISSUE entries without an explicit RESPONSE or CONCLUSION pointing -to them. This mechanical definition does not infer agreement or approval from prose. - -DEC fields: `schemaVersion`, `id`, `workId`, `title`, `context`, `approach`, -`alternatives[]`, `rationale`, `risks[]`, `acceptanceCriteria[]`, `approvalStatus`, -`author`, `createdAt`, `evidence[]`, narrative `text`, `revision`, `previousHash`, -`updatedAt`, `updatedBy`, `changeReason`, `approvals[]`, optional `revises` and -`supersededBy`. Legacy draft fields default to revision 1, no approvals/links and -empty narrative. Narrative uses document version 2; the JSON `text` field remains explicit. - -Statuses: DRAFT, ACCEPTED, REJECTED, SUPERSEDED. `decision update` changes only drafts, -recording actor/reason and a snapshot. Lists replace entire lists; explicit `--clear-*` -options clear them. `--text`/`--text-file` supplies narrative. Direct acceptance requires -nonblank context/approach/rationale, actor/reason and `--human-approved`. This flag is -an attestation that approval occurred, not authenticated identity or OS permission. -An agent cannot infer approval from a proposal or a prior status. Rejection retains -the proposal. `decision revise` creates a new draft linked to an accepted/rejected -DEC. Accepting that draft supersedes the prior accepted DEC, preserving both records. -Operational choices during execution remain distinct from these formal commitments. - -Creating a Plan from a draft DEC is a separate deterministic acceptance route. -The framework records `origin: SYSTEM_PLAN`, the causal `planId`, actor -`system:planning` and `humanApproved: false`; it does not invent a direct human -attestation. Context, approach and rationale must still be nonblank. Referenced -drafts are promoted and their accepted predecessors are superseded with the same -Plan provenance. Already accepted DECs stay byte-identical; rejected/superseded -DECs and conflicting replacements cannot be used to create the Plan. Optional -approval `origin`/`planId` fields are absent on historical direct approvals, whose -meaning and serialization remain unchanged. Readers predating this capability -cannot read new system-promotion records; use the updated CLI, without rewriting -historical approvals. - -## Topics, surveys and adapter runs - -[Discussion refinement contracts](discussion-slice.md) specify TOP/SVY/DSP/RUN records, -questions, answers, sources and commands. These IDs are decimal and Work-local; -QST/ANS IDs are survey-local. Topic and survey revisions use the same SHA-256 history -convention as decisions/plans. Existing discussionId threads are implicit topic views, -including `main` for an empty Work, without canonical file changes. - -Questions have a topic, suggestions, optional recommendation, single/multiple selection -and discussion sources. Free-text answers are always available. A revised answer -supersedes the prior one without deletion; only the latest determines pending status. -Revision signals a review and does not change accepted decisions/plans. Guided console -answering and noninteractive commands use the same persisted contract. - -Project configuration can optionally include: - -```yaml -agents: - general: - adapter: fixture-general - profile: fixture - model: deterministic - activities: - analyze: - adapter: fixture-reviewer - profile: fixture - model: deterministic - archivePolicy: review-only -``` - -Without agents configuration ordinary commands still work. Agent execution requires -an explicitly configured general. Unknown activities fall back to general; configured -specializations win. Fixture adapters and local codex-cli/claude-cli are available. An explicit -`reversible` policy permits archive with owned ART evidence and a reason; restore -preserves the source and disposition history. Questions/responses cannot be hidden -through proposal archive. Policies are metadata, not OS enforcement. - -RUN records preserve request ID, raw task, requested/chosen activity, requester, -executor, sourceHash, fixture proposal bundle, applied references, status, error and -timestamps. Proposals have typed source links; `@request` in a proposal resolves to a -persisted raw Discussion NOTE. Framework checks validate output before application. -Adapters cannot generate survey answers or human approvals. Fixture analyses are -synthetic observations, never claims about a real experiment or investigation. - -Source fingerprints include semantic project/Work/discussion/survey/evidence/decision/ -plan state, excluding run bookkeeping and Work modification time. Context derives -staleness without invoking an adapter. A proposal-changing run can already be stale -against its own resulting state; sourceHash identifies the input it actually saw. -Identical completed request IDs replay the recorded result even if context later -changes; use a new ID for a new computation. Changed request input with the same ID -is invalid. Interrupted APPLYING records block further runs pending inspection; -FAILED records retain applied references. This is diagnostic publication, not rollback. - -## Local provider executors - -Executor adds optional timeoutSeconds, bounded 1–600; omission means 120 seconds. -Old records remain readable without writing. Null timeout/provenance fields are -omitted from serialized values so legacy fixture digests remain stable. Local CLI -profile/model names are constrained tokens, not arbitrary flags; default model omits -the provider flag. Profile is an AIE role instruction. Provider configuration profiles, -private session state and credentials do not become portable AIE configuration. - -The [CLI adapter contract](cli-adapters.md) defines bounded process invocation, -required controls, versioned schemas, failure semantics and setup. Wire output cannot -set adapter/fixture identity or human authority. The normal complete proposal bundle -must validate before publication. RUN adds optional provenance with classification -and/or proposal invocation: transport, observed CLI version, configured role/model, -durationMillis, timeoutSeconds, outputSha256 and outputBytes. No raw environment or -stderr is canonical. A pre-publication transport failure leaves the Work unchanged. - -General can classify a request into configured/common activities. Explicit activity -skips classification. Clarify requires a survey with suggestions and leaves human -answers pending. Prior RUN outputs are supplied as derived interpretations; source -fingerprints still follow canonical semantic sources. State/conformance/EPIC checks -never invoke a provider. Setup/doctor similarly never sends a model request. - -## Plans and execution records - -Plans are optional, proportional Work-local records (`PLN-0001`). A plan contains -title, Markdown description, referenced decisions, steps, lifecycle status, creator, -timestamps and revision metadata. Each step (`TSK-0001`, decimal and plan-local) -records title/description, acceptance criteria, dependencies, status, result, evidence -and modification time. Statuses match Work's five values but describe external work. - -`plan create --decision DEC` promotes eligible DRAFT decisions without an adapter -or LLM. Guided Works require an explicit Work-wide human waiver; otherwise the DEC -needs human approval before Plan creation. Legacy Works retain prior promotion -semantics until explicit guidance adoption. Input, decision and revision-history validation runs -before promotion, under the project lock. Ordinary publication failures roll back -the attempted Plan and promotions. Publication is atomic per file, not a crash-proof -multi-file transaction: interrupted writes or failed recovery remain inspectable -with `work validate`. Validation checks the causal Plan's first revision, so later -Plan reference edits retain the original promotion provenance and cannot invent it. -Creating another Plan from an already accepted DEC does not add an approval. -`plan update` does not promote drafts; review its references before changing them. - -Step dependencies must exist in that plan and be acyclic. Starting or completing a -step requires completed dependencies and accepted referenced decisions. Completion -requires result text (`--reason`) and owned evidence. `plan status COMPLETED` requires -at least one completed step and all required steps completed; cancelled steps need -explicit scope review with `plan exclude --step`. Exclusions retain the cancelled -record and bind its content hash, actor and reason. Legacy Plans remain readable -without rewriting. Reopen a terminal plan with -`plan status ACTIVE` before editing; reopen terminal steps before changing scope. -Reopening a prerequisite first requires reopening/cancelling its dependent steps. -If a DEC is superseded, reconsider the plan and update its references before execution. - -Plan/step changes retain previous plan snapshots. `decision history` and `plan history` -walk `.history//rNNNN.md`; `previousHash` links each revision to the complete prior -UTF-8 file. Validation checks identity, numbering and hashes. Hashes are integrity -links, not signatures: manual rewriting of an entire chain is not prevented. New -records start at revision 1. A snapshot published before an interrupted current-file -replacement can be reused only when identical; conflicting history is never overwritten. - -The CLI does not execute steps, tests or validation-command metadata. Humans/agents -run real commands externally and record observations, commands, source revisions and -results in evidence. Plans support explicit adaptation; no autonomous OODA engine or -fixed four-phase pipeline is implemented. - -## Completion, integration and archive - -Works with executable Plans derive completion from those Plans. Mutation commands -and `work reconcile WRK` consolidate the last completed step into its Plan and -recheck all associated Plans. Completed required Plans and no pending questions, -surveys, draft DECs or explicit blocking states produce SYSTEM_PLANS completion, -without a model call, repeated human delivery approval or manual Work-level criterion -mapping. Empty sets never auto-complete; reviewed cancellations retain history. -New Plans after delivery require reopening. Unchanged old Plans do not immediately -close an explicitly reopened Work/Plan. See [Plan consolidation](plan-consolidation.md) -for records, provenance and recovery. `work check` reports consolidation pending -reasons; status/context/next-actions remain read-only. Existing EPIC authority and -policy continue to govern EPIC completion. - -For inspection-only Works without Plans, `work check` checks mechanical readiness: explicit acceptance criteria, -no unresolved questions/issues or draft DECs, and terminal plans. Noncancelled plans -must reference currently accepted decisions. Small Works can close without a DEC/plan. -The check cannot determine whether arbitrary prose/evidence proves the desired outcome. - -`work complete` requires human attestation, actor, summary and one unique -`--criterion N=ART-0001[,ART-0002]` mapping per criterion (1-based). Artifacts must -belong to the Work and pass integrity checks. Completion captures criterion text, -evidence IDs, approval metadata and a deterministic SHA-256 digest of scope, source -snapshots, discussion, decisions, plans and artifact metadata. Current COMPLETED Work -data must still match that digest. Reopened Works retain earlier snapshots as history. - -Supply updated canonical project files via `--integration PATH` or explicitly state -`--no-integration-needed REASON`. Integration paths are safe project-relative regular -files outside `.ai-engineering`; their hashes identify contents at closure. Those -files can evolve later without invalidating a historical completion. The CLI records -the attestation/snapshot; it does not prove that the file changed or infer its meaning. -Canonical code/spec/test/docs hold integrated knowledge; no Lesson entity is required. - -`work archive --by NAME --reason TEXT` marks a verified completed or cancelled Work -archived. It retains all files and prior approvals/results. `work reopen` clears -archive, returns to ACTIVE and appends a reasoned event. There is no automatic deletion. -`import discussion` imports DF DSCs with open AGDs using a read-only preview and -an explicit `--apply --expect` fingerprint. Independent `--source ID=PATH` origins -share one AIE destination; targets are described in their Works. Only open agendas -are imported as complete refinement notes and original evidence. Owned versioned -receipts preserve source+DSC identity, source hashes and references without changing -the Work schema. Identical reimports are no-ops; changes are reported for review. -Work publication is atomic per prepared directory, while a batch may be resumed -after partial publication. Closed agendas, DECs, Plans and Lessons are not imported. -See [the import contract](discussion-import.md) for limits, diagnostics and recovery. - -## EPIC policy and system completion - -[The EPIC contract](epics.md) defines topology, authority and recovery. An EPIC remains -a project Work, marked `epic: true`, with one versioned definition in its `epic/` -directory. Links use Work IDs, with important=true by default. Definitions preserve -mode, links, explicit authorization, editor/reason, revision and previousHash. -History follows the DEC/Plan snapshot convention. Initial topology is a forest. - -RESULTS tracks verified important deliveries; optional children are reported without -blocking. Important CANCELLED remains pending. DECOMPOSITION uses ordinary reviewed -closure for the parent's own output and does not wait for execution. Empty important -sets never auto-close. Policy edits require an open parent and invalidate automatic -authority; `epic authorize --human-approved` binds the parent/important-child scopes -and current policy. Authorization is delegation for the structured aggregate condition, -not an inferred human approval of a future delivery. - -Completion records add optional `origin` and `delegation`. Old records default to -HUMAN with no delegation and retain their digest semantics. HUMAN requires direct -humanApproved=true. SYSTEM_EPIC requires humanApproved=false, actor system:epic, -an actual policy authorization/history hash and request correlation. Its criteria map -to a framework-owned aggregate ART receipt containing policy/input and important-child -completion digests. The human's policy delegation attests that this condition suffices -for the parent criteria; the framework performs no semantic inference about prose. - -Frozen RESULTS scope includes important completion records; optional execution can -continue independently. Important reopening reopens ancestors and clears their archive, -retaining prior completions. Explicit reopening of an EPIC suspends its authority for -replanning. Child-caused reopening preserves unchanged-scope authority. BLOCKED and -CANCELLED parents require explicit resumption. Nested propagation runs from descendants -to ancestors under the project lock, without calling any AgentAdapter. - -Public CLI/Verification lifecycle APIs return the changed Work plus affected EPIC -reports when linked; plain Work output remains compatible. `--requester` and -`--request-id` correlate results. IDs correlate notifications rather than acting as a -global transaction log. `epic reconcile [WRK]` derives missed updates from canonical -files and does not duplicate a satisfied completion. A matching published receipt is -reused after interrupted completion. Invalid histories, missing children and orphan -publication are diagnosed; arbitrary corruption still needs deliberate repair. -Low-level storage callers must explicitly reconcile after lifecycle writes. - -## Evidence and integrity - -`artifact add` copies one regular file up to 1 MiB. Its manifest records schema, ID, -Work ID, origin, purpose, Work-relative payload path, SHA-256, byte size, author and UTC -creation time. The origin defaults to the source basename; use `--origin` for a useful -portable provenance reference. Payload bytes are exact. The fixed `payload` filename -avoids filename ambiguity; origin preserves the supplied source identity. - -Validation checks required directories, IDs, schemas, repository references, child -ownership, missing records, orphan records and payload integrity. Evidence paths stay -inside the Work. Large resources should remain in their canonical location and be -described in discussion/reference files, rather than copied into this workspace. -`artifacts/outputs` is versionable for deliberately retained outputs; use ignored `runs/` -for large temporary results. No command creates large output files by default. - -## Compatibility and evolution - -`project compatibility` inspects actual stored formats and revisions without writes. -`protocol.json.schemaVersion` versions the manifest, while optional `protocolVersion` -versions the engineering contract (absent means the supported legacy baseline 1). -The diagnostic exposes the supported read/write format catalog separately from the -executable release. Old compatible records remain valid and readable without -normalization, including COMPLETED Works. `onboard` updates only entry instructions -and the manifest; a newer unsupported contract is never silently overwritten. -See [compatibility and evolution](compatibility.md) for public states, update guidance -and requirements for future explicit conversions. No required migration exists today. - -## Context and continuity - -`work context --format markdown|json` loads only canonical project/Work files. It -includes all Work fields (metadata separately in Markdown), stored source revisions, -ordered discussion history/conclusions, explicit decisions and approvals, plans/results, unresolved questions -and complete artifact references with integrity metadata. JSON has top-level -`schemaVersion`, `work`, `discussionHistory`, `decisions`, `outstandingQuestions`, -`artifacts`, `plans`, `protocolGuide`, `topics`, `surveys`, `dispositions`, `agentRuns`, -`agents`, `epic`, `parentEpic`. Completion and lifecycle history are included -in `work`. It does not embed arbitrary evidence payloads or all revision snapshots; -use history commands when prior versions are relevant. - -No export timestamp, current absolute path or live Git state is injected. Unchanged -files yield byte-identical output across new instances and processes. Export rejects -broken references or integrity failures. It requires neither a model nor live Git -inspection; `project validate` separately verifies live repositories. - -Markdown context renders discussion and decision prose directly, with IDs, authors, -timestamps and reply/approval metadata. Empty sections use `None recorded.`. JSON -keeps the complete typed records, including discussion `text`, regardless of their -on-disk document version. Evidence remains referenced rather than embedded. - -## Write guarantees and recovery - -Protocol mutations hold `.local/write.lock`, an OS lock released automatically at -process exit. Individual files publish atomically; create operations reject overwrites. -New project/Work/artifact directories are staged and renamed. Work sequence reservation -precedes directory publication to avoid identity reuse after interruption. - -A child file/bundle is published before its reference is atomically added to `work.md`. -The filesystem is not a multi-file transactional database: interruption in that window -can leave an orphan, which validation reports. Inspect its metadata and either add its -ID to the Work reference array or remove it after review. Hidden `.tmp` directories are -incomplete staging outputs, ignored by readers; inspect and clean them manually after -an interrupted write. Concurrent manual editors do not honor the CLI lock. Directory -entry durability under sudden power loss depends on the host filesystem. - -## Work guidance and OODA - -Contract 3 adds optional typed Work guidance and Plan experiments. New Works ask -for human discussion mode and require human DEC approval by default; explicit -Work-wide waivers and requests retain human provenance. Guided operations enforce -the selected authority. See [Work conduct and adaptive implementation](work-guidance.md) -for commands, experiment criteria/results, affected execution and legacy behavior. -This preserves the existing loops and does not add a repository executor. - -## Future contracts (design only) - -- Additional AgentAdapter transports and execution permissions: local proposal-only - Codex/Claude CLIs are implemented; direct provider APIs, repository execution and - vendor-native configuration profiles need separate contracts and authorization. -- OODA iteration: identify Work and prior observations, orientation, operational - choices and attempts. Phases can repeat or be skipped; no four-stage workflow gate. -- Attempt: stable identity, hypothesis, input references, exact repository revisions, - granted permissions, invocation/environment, observations, outputs, result and - evidence references. Evidence and interpretation remain distinguishable. -- Coordinated execution: independent per-repository worktrees and commit records, - integrated validation, explicit authority for destructive actions, pushes and merges. - No claim of atomic commits across repositories. -- Conformance: evaluate explicit criteria against evidence and canonical code/spec/test - updates. No required Lesson artifact. Later schema changes require explicit migration. +`--observed` attests an actual external check; it is not human DEC approval. +AIE does not execute the procedure or establish the semantic truth of a claim. +Results retain definition, invocation, scope/input fingerprint, moment, observer, +outcome and short summary. `gate history` exposes prior observations. Changed +inputs, Work scope/guidance, DEC revisions or gate definitions require evaluation +again. Plan/status bookkeeping does not invalidate the check. + +Pending, failed or stale gates prevent manual, Plan and EPIC delivery. Completion +freezes references/hashes of the actual gate results in the same transaction. +Later source/policy changes do not invent checks on old deliveries; reopened work +requires applicable current results. Imported deliveries keep their historical +contract, without fabricated retroactive gates. + +## Temporary inputs and outputs + +`artifact add WRK --file PATH --purpose TEXT` copies a small input to the filesystem +with owned integrity metadata; bytes never become BLOB, base64 or file-shaped TEXT +in SQLite. Inputs remain available during dependent checks. Finishing a partial +step or gate alone does not mean all future Work checks have consumed an input. + +At Work completion, integrity and completion facts commit before eligible payloads +are removed. AVAILABLE, DISCARD_PENDING and DISCARDED distinguish usable input, +interrupted cleanup and legitimate retirement. Current evaluations require available +inputs; a retired artifact cannot be reused after reopening. Historical queries +use the validated result, and missing input before evaluation remains an error. + +`artifact recover WRK` finishes interrupted publication/retirement. Reads only expose +recovery actions. Publication journals identify owned residue; unknown files require +inspection. Adapter process workspaces are temporary and cleaned at execution end. +New Plan/EPIC receipts are structured facts, without an extra JSON file. Imported +originals and migration safety copies remain preserved until explicit disposition. + +Requested documents/images/other deliverables belong at their output destination, +outside `.ai-engineering`; code stays in the source repository. AIE does not require +a permanent duplicate solely for auditing. Cleanup targets owned temporary copies, +never the source/deliverable. + +## Persistence, consistency and recovery + +SQLite uses foreign keys, WAL, FULL durability, IMMEDIATE writes and bounded writer +waits. Nested domain mutations share the transaction; related reads use a snapshot. +An OS publication lock coordinates writers with storage activation/rollback, with +bounded waits for SQLite commands. Backend changes during a wait require a retry. + +Typed columns and ordered child rows retain domain data. Nullable historical lists +remain distinct from empty lists. Revision hashes reconstruct the relevant typed +representation or verify retained original bytes. Migration also compares original +representations to typed records, detecting changed historical rows. + +RUN application is transactional on SQLite. Failure rolls back the whole proposal; +a separate failure record has a short diagnostic and no rolled-back applied refs. +Request IDs retain idempotence. Adapters cannot answer for humans, approve DECs, +complete Works or execute repository commands through this framework. + +Legacy storage retains its per-file publication/recovery behavior. Supported legacy +records remain readable; [the legacy reference](legacy-file-storage.md) documents +those file formats. [Storage migration](storage-migration.md) is explicit, staged, +verified and recoverable. No consumer or installed executable is automatically +converted by a new build. + +## Verification and closure + +`project validate` checks the project, identities, graph, references, history and +integrity. `work validate` scopes checks to selected memory and its dependencies. +`work check` reports mechanical readiness, not semantic proof of prose criteria. +`status`, `next-actions` and context are read-only projections. + +Required completed Plans consolidate through SYSTEM_PLANS receipts; RESULTS EPICs +still need explicit current authorization, and DECOMPOSITION remains reviewed. +Empty sets, open questions/experiments, unresolved DEC concerns and unfinished scope +remain pending. Cancelled content needs explicit scope review. Reopening preserves +history and does not immediately reconclude unchanged old Plans. Archive preserves +memory, not an obligation to retain every temporary file. + +Exit codes: 0 success, 1 I/O/runtime, 2 invalid input, 3 missing resource, 4 validation +or readiness failure. Use command `--help` for exact options. diff --git a/docs/roadmap.md b/docs/roadmap.md index 86b4ebf..5a2eb73 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -28,7 +28,7 @@ and long proposals can be authored as ordinary Markdown files before persistence Acceptance demonstration: initialize a project with two independent Git repositories, create a Work referencing both, append discussion, persist a draft decision and evidence, export context, then reconstruct the same context in independent processes -using only files. No framework state or model history may be required. +using persisted local memory and a compatible CLI. No process-local model history may be required. Platform release targets: Linux x86_64, macOS ARM64, macOS x86_64 and Windows x86_64. The workflow builds the three available GraalVM 25 platforms. **macOS x86_64 is blocked @@ -89,7 +89,7 @@ completion requires explicit policy delegation, local readiness and valid import deliveries; receipts distinguish system results from human delivery approvals. Lifecycle commands propagate outcomes/reopenings and return a deterministic report. -Reconciliation recovers missed propagation from files without an LLM. Acceptance +Reconciliation recovers missed propagation from persisted state without an LLM. Acceptance covers independent processes, repeated notification, policy/scope changes, history, important/optional/cancelled children and native standalone execution. Actual observed results are recorded in [experiments](experiments.md). @@ -150,3 +150,13 @@ checks against evidence; identify impacted canonical specs, tests, code and documentation; expose conformance checks to agents and CI. Acceptance: a Work can demonstrate its outcome and preserve actionable knowledge without a mandatory Lesson model or redundant documentation trail. + +## Local SQLite memory + +Implemented in WRK-000D: typed per-project SQLite memory, transactional domain +mutations, cumulative project/Work gates, temporary attachments and structured +receipts, snapshot reads, explicit recoverable legacy migration and default Git +ignore policy. Native AIE/JDBC/sqlite3 packaging is prepared and verified; actual +installation and consumer migration remain deferred. The latency ticket WRK-000C +remains open for separate measurement. Work/DEC sharing, distributed sync, +Git LFS and backup/export are future discussions. diff --git a/docs/sqlite-migration-design.md b/docs/sqlite-migration-design.md new file mode 100644 index 0000000..242d845 --- /dev/null +++ b/docs/sqlite-migration-design.md @@ -0,0 +1,421 @@ +# SQLite persistence: legacy mapping and migration cases + +This is the implementation map for WRK-000D / DEC-0001 / PLN-0001, starting with +TSK-0001. It describes the inspected file backend and the invariants the SQLite +implementation must preserve. The implementation sections below record the completed SQLite integration; the +source inventory also documents the supported legacy backend. + +The active CLI and this repository's canonical `.ai-engineering` remain on the file +backend. Native installation, replacement of active binaries/libraries/shortcuts, +and migration of consumer projects are deferred by explicit human instruction. +Implementation and verification use fixtures, disposable copies and build outputs. + +## Persistence boundary + +One SQLite database, `.ai-engineering/aie.db`, will own a local project's Work +memory. Keep discovery/configuration/agent entry files small and explicit where +bootstrap needs them. A file named `aie.db` alone does not establish that migration +completed or that the installed CLI can read its schema. + +Store domain fields and relationships, not files encoded as BLOB, base64 or a large +TEXT document. Ordered child data belongs to typed dependent rows; constrained +operational structures may use an explicit codec when they are not independently +queried. Do not put every aggregate into a serialized `work.md` column. + +Generated contexts, readiness/evaluation reports, suggested actions and freshness +flags are projections, not additional authorities. Rebuild them from the applicable +records in a consistent read transaction. File payloads remain outside SQLite. + +## Source-to-target inventory + +Table names below identify logical groups for the schema step, not a final SQL +migration. Preserve ordered lists and nullable/omitted historical values where they +affect interpretation or digests. Do not change externally visible identities. + +| Source and owner | Domain data to preserve | Target groups and invariants | +|---|---|---| +| `ai-engineering.yaml`; `ProjectService`, `ProjectConfig` | Project identity/name; repositories, paths/type/language/access/validation commands; general/activity adapters, profile/model/timeout and archive policy | Bootstrap configuration and typed configuration records; one authority per field. Empty repositories are valid. Repository access defaults to read-only. A source repository is optional. | +| `protocol.json`, entry README/AGENTS; `ProtocolGuide`, `ProtocolContract` | Contract/schema versions, capabilities, startup and managed instruction boundaries | Explicit storage/schema discovery and compatibility. Preserve external project rules. Unsupported contracts fail before writes. `onboard` is not data migration. | +| `works/.sequence.yaml`; `WorkService.Sequence` | Highest reserved Work number, including gaps | Transactional project-local allocation. Preserve legacy high-water interpretation; never recompute solely from surviving Works or rename decimal-looking historical IDs. | +| `work.md`; `Work` | ID, title, description, goal, motivation, ordered constraints/acceptance criteria, status, timestamps, author, repository revisions and all child references | `works`, ordered scope/revision rows and owned references. A Work ID is project-wide; `(work_id, child_id)` identifies a Work-local child. Preserve terminal/editability/archive/reopen semantics. | +| Work guidance; `WorkGuidance` | Mode, approval policy, explicit choice history and decision requests, with actor/reason/time/human attestation | Guidance/choice/request rows. Absence in a historical Work differs from newly UNSPECIFIED guidance. Only recorded human instructions change authority. | +| Work completion/events; `Work.Completion` | Criterion texts and evidence references; scope hash, integrations, summary, origin, delegation/aggregation, actor/time and lifecycle events | Completion/criterion/integration/event rows. Preserve HUMAN, SYSTEM_EPIC and SYSTEM_PLANS provenance, not just COMPLETED status. Do not invent approval during migration. | +| `discussions/DSC-*.md`; `DiscussionEntry` | Work/thread/topic, kind, author/time, exact narrative, optional earlier response target | Discussion entries and response edges in source order. QUESTION/ISSUE remains pending until an explicit linked RESPONSE/CONCLUSION. Preserve UTF-8, Markdown and whitespace. | +| `topics/TOP-*.md`, `.history`; `TopicService` | Title/description, ordered source discussion IDs, revision/hash/editor/reason/time | Topic/current revision/source rows. Legacy threads remain implicit topic views, without fabricated formal topic history. | +| `surveys/SVY-*.md`, `.history`; `SurveyService` | Questions/options/recommendation/multiple flag/topic/sources; every answer, selected choices, author/time and supersedes link | Survey/question/option/answer/choice rows and revision provenance. Recommendations are not answers. Superseded answers remain available; latest answer determines pending state. | +| `dispositions/DSP-*.md`; `DispositionService` | Target entry, ARCHIVE/RESTORE, reason/evidence, author/time | Owned disposition/evidence references. Archive remains subject to the configured policy; restore does not delete the original proposal. | +| `decisions/DEC-*.md`, `.history`; `DecisionService` | Narrative/context/approach/rationale, alternatives/risks/criteria/evidence, approval status/history, revisions and revises/supersededBy | Decision/revision/approval/list/reference rows. DIRECT and SYSTEM_PLAN approval provenance stay distinct; preserve causal Plan IDs and no-human-attestation semantics of permitted system promotion. | +| `plans/PLN-*.md`, `.history`; `PlanService` | Narrative, decisions, steps and ordered criteria/dependencies/results/evidence; status/revisions; scope exclusions; experiments | Plan/revision/step/dependency/exclusion/experiment rows. Excluding cancelled scope does not satisfy a dependency; completed steps still require results and applicable checks. | +| Plan experiments; `Experiment` | Hypothesis, criterion, invocation, step, author/time; observed outcome, interpretation/next action/evidence, retry/reconsideration, questioned DEC | Experiment/result/reference rows. Criteria precede results; failed retries require reconsideration. Open experiments and unresolved DEC concerns continue to block affected execution. | +| `epic/WRK-*.md`, `.history`; `EpicService` | RESULTS/DECOMPOSITION, ordered children/importance, revision/hash, explicit scope-bound authorization | EPIC policy/revision/link/authorization rows. Enforce existing forest topology, one parent, no cycles and no authorization inferred from status. | +| `agent-runs/RUN-*.md`; `AgentService`, `AgentRun` | Request identity/task/activity/requester/executor/source hash; APPLYING/COMPLETED/FAILED, typed proposal, applied references, diagnostic and invocation provenance | Run/proposal/applied-reference/invocation rows. Preserve idempotency and interrupted publication diagnostics; do not retain raw transport, environment or credentials. | +| `artifacts/evidence/ART-*/artifact.yaml`; `ArtifactService` | Work-local identity, origin/purpose/path, SHA-256, size, author/time | Artifact metadata and references. New temporary evidence needs explicit lifecycle state. Payload bytes are external; their absence is not success unless legitimate post-check disposal is recorded. | +| Plan/EPIC completion and DF-import receipt payloads | Typed receipt identity, inputs, referenced source revisions/hashes and producer provenance | Typed internal receipt/source rows. These are protocol state; parse only recognized owned receipts, not arbitrary user payloads. Preserve legacy payload/representation provenance when required. | +| `runs/`, `artifacts/outputs`, references and experiment files | Temporary execution files, requested deliverables and external references | Filesystem lifecycle/paths only when needed. A RUN record differs from the ignored `runs/` folder. Do not promote every generated file into permanent evidence. | + +### Current gate boundary + +`ProjectConfig.Repository.validationCommands` describes repository validation +commands. The legacy baseline did not expose a complete project-level and +per-Work gate-result catalog; QualityGates now supplies that contract in SQLite. Completion enforces mechanical protocol checks, +recorded results and owned evidence; it does not itself execute those commands. + +TSK-0007 adds the project gate baseline and Work additions while preserving this +execution boundary. A historical COMPLETED label or an ART reference is not proof +that a newly introduced gate was executed. Imported approvals retain their original +meaning; new gate results must record actual observations of the applicable state. + +## Hashes and historical representations + +There are several distinct digests, with different source material: + +1. **Revision chain:** `Revisions.chain` hashes the preceding file's exact UTF-8 + content. Parsing and reserializing YAML can change bytes without changing the + domain object. Keep the original source representation/provenance available + for legacy chain checks; never replace a historical hash with a new one merely + to make import pass. Retained migration originals stay outside database TEXT. +2. **Work completion scope:** `VerificationService.scopeHash` hashes deterministic + JSON of selected domain fields and ordered child records. Optional legacy + fields are conditionally omitted. Do not normalize missing guidance to a new + choice, add optional empty collections to old digest inputs, or reorder lists. +3. **Plan/EPIC receipt sources:** source Plan revisions and child completions bind + to their semantic digests and producer/authority metadata. Importing a receipt + does not authorize re-completion, reevaluation or a new human approval. +4. **Artifact integrity:** SHA-256 is over exact payload bytes; retain size/path + ownership checks and the distinction between a user file and a protocol receipt. +5. **Adapter and import fingerprints:** preserve source fingerprints, request IDs + and import source identities. An identical retry is not a new Work or RUN; + changed input with the same identity requires existing rejection/review rules. + +Storage schema, manifest schema, protocol contract and Markdown document versions +are separate. Existing record schema is 1, Work sequence reads versions 1/2, +narrative Markdown reads document versions 1/2 and protocol contracts read 1/2/3. +A new SQLite schema does not mean historical documents were rewritten. + +## Unit-of-work and file lifecycle map + +| Operation | Records that must publish coherently | External boundary | +|---|---|---| +| Create Work | Reserved high-water and initial identity/guidance | Bootstrap and legacy source discovery; no ID reuse on retry | +| Add discussion/answer | Entry or revised survey, source links and Work references/timestamp | No implicit evidence attachment or human answer | +| Accept/revise/supersede DEC | Approval and revision, replacement links and affected references | Preserve immutable accepted content and causal authority | +| Create/update Plan or finish step | Eligible decision promotion, Plan revision, step/result/evidence references | Evidence must be available and valid during dependent checks | +| Apply agent proposal | RUN state, typed proposals/applied references and resulting records | Provider call stays outside a write lock; recheck source state before application; preserve idempotent retry | +| Complete Plan/Work or coordinate EPIC | Source revisions, internal receipt, completion and applicable propagation | No automatic completion from an empty set; retain reopen/authorization rules | +| Retire temporary evidence | Completed dependent checks, minimal result and legitimate disposal state | File deletion follows committed result/disposal intent; interruption is recoverable; requested outputs are protected | +| Migrate file backend | Imported rows, mapping/provenance and activation state | Stable source snapshot, migration safety copy and staged database; never switch before verification | + +Keep local write transactions short; provider calls and external quality commands +must not hold the database write lock. A read of related context uses one coherent +view. Waits have a duration limit and an actionable diagnostic. + +File publication and removal are not SQLite transactions. Define interruption +cases explicitly: unreferenced staged file; committed reference with missing input; +committed checked result pending cleanup; process interrupted before completion. +Only the third case is eligible for post-check disposal. Removing one evidence +file must consider every dependent check, including other Plans or Work completion. + +## Representative corpus and expected outcomes + +Use the existing resource bytes and workflow builders. All mutations below are +against temporary copies/projects. Do not regenerate frozen resources with the new +writer to obtain expected values. + +| Corpus/case | Existing source | Required result of future migration/SQLite checks | +|---|---|---| +| Frozen pre-contract delivered Work | `src/test/resources/compatibility/baseline-v1/.ai-engineering`; `CompatibilityTest` | Keep 9 original files unchanged, implicit contract 1 and sequence schema 1 readable, accepted DEC plus draft history, legacy defaults and exact frozen scope hash. SQLite import yields equivalent meaning without rewriting or reopening the source. | +| Missing optional refinement/guidance | `CompatibilityTest`, `RefinementSafetyTest`, `WorkGuidanceTest` | Interpret defaults in memory; no invented mode, waiver, answer or approval. New guided Works still require human choices. | +| Current refinement/history | `DiscussionRefinementTest`, `RefinementSafetyTest`, `DiscussionMarkdownTest` | Preserve UTF-8/body text, response links, implicit/formal topics, all survey answers and latest-answer semantics, reversible dispositions. | +| DEC and Plan authority | `WorkGuidanceTest`, `PlanDecisionPromotionTest`, `OperationalSafetyTest` | Preserve direct versus system approvals, exact causal links, accepted-content immutability, revised decision blocking and Plan authority. | +| Plan consolidation/recovery | `PlanConsolidationTest`, `PlanConsolidationSafetyTest` | Preserve actual completed Plan sources, exclusions, incomplete scopes, existing receipt reuse, reopen semantics and pending questions. Tampered evidence fails before the step write. | +| EPIC delegation/history | `EpicWorkflowTest`, `EpicSafetyTest` | Keep important/optional children, authorization invalidation, nested forest and historical hashes; reproduce recovery without duplicating completions. | +| Import receipts and colliding source-local IDs | `src/test/resources/discussion-import/alpha`, `beta`; `DiscussionImportTest`, `legacyimport/DiscussionImportRecoveryTest` | Preserve stable source identity and original evidence; distinguish sources that reused DSC IDs; identical reimport/recovery does not duplicate Works or overwrite changed inputs. | +| Fresh processes without Git | `ProcessContinuityTest`, `scripts/native-smoke.sh` | Reconstruct the same memory in a new process without Git installed; preserve source files and avoid a server dependency. | +| Evidence missing/tampered before check | `IntegrityTest`, `PlanConsolidationSafetyTest` | Reject size/hash/path/ownership failures and do not publish successful checks. | +| Explicitly retired temporary evidence | New scenario in TSK-0008/0009 | Check while present, persist minimal result, retire only after all consumers finish; historical queries remain valid; pending consumers prevent deletion. This behavior is not implemented in the current backend. | +| Unsupported versions/unknown fields | `CompatibilityTest`, `OperationalSafetyTest` | Reject malformed, future or inconsistent records before activation; a current manifest cannot hide unsupported history; preview does not modify source. | +| Traversal, symlink, foreign ownership | `IntegrityTest`, `RefinementSafetyTest`, `EpicSafetyTest` | Refuse unsafe paths/identities without reading a symlink target, leaking its contents or publishing partial records. Apply the same boundary to database and sidecar paths. | +| Interrupted conversion/retry | New scenario in TSK-0010; existing import recovery pattern | Fail before activation, retain usable legacy state, expose recovery state and retry without duplicate IDs/approvals/completions. Two usable writers must not become independent authorities. | +| Local concurrent writers/rollback | New scenario in TSK-0003 | Enforce ownership/foreign keys and whole-operation rollback; no duplicate allocated identity; bounded lock contention. Multi-machine reconciliation is out of scope. | + +### Frozen anchors + +The frozen baseline's expected completed Work scope hash is +`72d5803add0b8714d7dc4bf7e63ad55cc3259df910aa8b03790657eac4c2bd02`. +Its accepted DEC is revision 2; `previousHash` and the original draft's byte digest +are `545dc8e36da222fdeaf9458f77880bf2d1842738b82bac5296cddf62452a7e01`. +The ART-0001 payload digest is +`98545564d0747210b91b933bf8554c4b7e36ba878e6662cb48156b08ff74e1ee`. +These anchors were inspected from existing resources, not generated by SQLite. + +## Mapping to implementation steps + +- TSK-0002/0003 establish the driver, native loading, schema and unit of work. +- TSK-0004/0005 map investigation and implementation records while retaining authority. +- TSK-0006 maps RUNs, source fingerprints and deterministic coordination/receipts. +- TSK-0007/0008 add gate records and temporary evidence lifecycle. +- TSK-0009 builds projections without repeated unrelated reads. +- TSK-0010 exercises the corpus before any activation and implements public migration. +- TSK-0011 declares storage compatibility and initializes local ignored state. +- TSK-0012 prepares the distribution with disposable installer fixtures only. +- TSK-0013 updates public operational documentation once the commands exist. +- TSK-0014 verifies the integrated result and hands a reproducible workload to WRK-000C. + +This mapping does not change DEC authority, weaken a gate or authorize installation. +Successful legacy tests characterize the source backend; they do not yet prove +equivalence of a SQLite importer. Future steps must exercise these same expectations +through the implemented database path. + +## Driver and Native Image proof (TSK-0002) + +The selected candidate is `org.xerial:sqlite-jdbc:3.54.1.0` (SQLite 3.54.1). +`src/sqliteProbe` is a build-only entry point, separate from the installed CLI and +project discovery. `sqliteProbe` exercises create/read/write/rollback/reopen in a +JVM; `nativeSqliteProbeCompile` builds the same entry point with its JNI library +exported beside the executable. The native binary explicitly selects a GraalVM +Java 25 toolchain; selecting the Gradle JVM alone did not select the correct +Native Image launcher in the first local build attempt. + +Example disposable verification, using the repository's pinned GraalVM: + +```sh +mkdir -p build/sqlite-probe/disposable +./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db +./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db +./gradlew nativeSqliteProbeCompile +bash scripts/sqlite-probe.sh /absolute/path/to/build/native/nativeSqliteProbeCompile/aie-sqlite-probe +``` + +The shell proof creates its own temporary database and starts separate native +processes, checks a UTF-8 value and rollback, disables temporary-library extraction +and verifies that an isolated executable fails when its companion library is absent. +These are build/driver checks; they do not install the native application, activate +the database backend or establish the end-to-end latency of the AIE CLI. + +## Transaction foundation (TSK-0003) + +`SqliteDatabase` now provides explicit initialization and command-scoped read/write +transactions. Opening a missing database does not create files. Its application ID, +`user_version` and schema metadata must agree before domain operations proceed. +Initialization uses WAL with FULL synchronization; connection foreign keys are +enabled explicitly, and writer transactions begin IMMEDIATE with a bounded busy +timeout (2 seconds by default). + +Nested operations share their connection. A nested failure makes the enclosing +write rollback-only even if its caller catches the exception. Read transactions +use a read-only SQLite connection and cannot be upgraded implicitly to writes. +Related reads retain a stable snapshot while another local writer commits. + +`sqlite/schema-v1.sql` establishes the ownership/revision/reference keys and local +identity high-water marks. Domain field tables will be integrated in TSK-0004 +through TSK-0007; the foundation does not yet route the CLI's Works to SQLite. +References are deferred until commit so related revisions can publish together. +Missing target ownership aborts the transaction. Database and sidecar symlinks, +nonregular paths and orphan sidecars during initialization require inspection. + +`SqliteDatabaseTest` covers initialization, path encoding, rollback, foreign keys, +nested failures, read-only access, snapshot consistency, writer contention, +unsupported schemas and filesystem boundaries. The build-only native probe also +creates and reopens the foundation schema, verifying its resource loading and +transaction entry points in Native Image without installing the application. + +## Investigation record integration (TSK-0004) + +`ProjectService.initializeSqlite` is the explicit backend entry point used by +disposable integration projects. The public `init` default is still the legacy +backend until the storage-contract/initialization step. Existing projects are not +converted by the presence of an arbitrary database file: the bootstrap configuration +must explicitly select SQLite. + +`SqliteRecords` maps record scalar fields to typed columns in domain-specific +tables. Ordered fields use dependent tables and ordinals; structured operational +items (such as an answer or completion) have an explicit JSON representation per +item, not a serialized source document or entire Work. Work-owned references also +bind to the shared revision identity keys. Tables/columns come from trusted domain +record definitions, while identities and values use bound SQL parameters. + +`RecordStorage` adapts the existing record codec and revision operations without +placing canonical Markdown files in SQLite projects. New revision hashes bind to +deterministic materializations of the typed record; migration can retain original +source paths/digests for legacy representations. `WorkService` loads a selected +Work by identity, allocates IDs transactionally and preserves its folder location +when the title changes. Discussions, topic revisions, survey/answer history and +dispositions use the same transaction as their Work references. + +Integration checks cover rejected publication rollback, missing owned references, +concurrent local allocation, selecting one Work without parsing an unrelated broken +record, UTF-8 and explicit guidance/decision requests. A fresh JVM reconstructs +discussion/survey context, and the native probe creates and reopens a Work and its +discussion in separate processes using the application's AOT metadata. These checks +do not yet migrate DECs, Plans or the active workspace to the new backend. + +## Decision and Plan integration (TSK-0005) + +Decisions, approvals, supersession and Plan/experiment revisions now use the typed +record adapter. SQLite Plan creation publishes permitted draft promotions, the +Plan and its Work reference in one transaction. The legacy backend retains its +file-publication recovery path; SQL publication does not compensate by writing +Markdown files. A requested rollback of a prepared SQL promotion marks the whole +unit of work rollback-only. + +The existing domain checks still enforce pending discussion, approval policy, +accepted decision references, step dependencies, experiment outcomes and required +owned evidence. Artifact metadata is mapped into SQLite as foundational support +for these checks; payloads remain files and are still retained at this step. The +temporary-artifact lifecycle and disposal policy belong to TSK-0008. + +`SqliteImplementationTest` covers human acceptance and immutability, atomic system +promotion rollback/retry under an explicit fixture waiver, supersession and Plan +reconsideration, dependencies, owned evidence and the OODA experiment/retry loop. +Existing file-backend authority, promotion and experiment tests remain applicable. +### TSK-0006 — RUNs e coordenação + +RUNs e políticas de EPIC usam registros tipados no SQLite. Idempotência e +fingerprints continuam derivados do contexto; a aplicação de propostas é uma +transação. Uma falha reverte todo o bundle e publica, em transação posterior, +somente o RUN falho com diagnóstico e referências aplicadas vazias. Não há +transporte bruto ou logs no banco. A coordenação conserva os recibos existentes +até a integração de seu ciclo de vida no TSK-0008. + +Verificação: 30 cenários distintos de SqliteCoordinationTest, EpicWorkflowTest, +EpicSafetyTest, RefinementSafetyTest e ArchitectureTest passaram, incluindo +idempotência, falha intermediária via trigger SQL, RESULTS/DECOMPOSITION, +aprovação explícita, revisão de política, propagação e reabertura. + +### TSK-0007 — gates obrigatórios + +Definições de gates do projeto e adicionais por Work são cumulativas. Cada gate +declara procedimento e caminhos avaliados; não executa comandos. O registro exige +atestado de observação, fingerprint prévio, resultado, invocação e resumo curto. +Arquivos, escopo/guidance do Work e revisões das DECs compõem o fingerprint; +mudanças relevantes ou na definição exigem nova avaliação. Bookkeeping do Plan +não invalida um resultado. Anexos obrigatórios passam pela integridade existente. + +Conclusões humanas, por Plans e por EPICs verificam os gates e congelam referências +e hashes dos resultados entregues na mesma transação. A consulta histórica não +reaplica regras configuradas depois da entrega. Testes focados de gates, +coordenação, infraestrutura e arquitetura: 23 cenários passaram. Instalação e +workspace canônico permanecem no formato legado. + +### TSK-0008 — anexos temporários e recuperação + +O Work aberto conserva seus anexos porque outros checks ainda podem precisar +deles. A conclusão valida os anexos e registra DISCARD_PENDING na transação; +somente após commit remove os payloads e reconhece DISCARDED. Interrupções entre +essas fases são repetíveis por `artifact recover WRK`. Ausência sem validação +prévia continua inválida. Novas avaliações exigem entradas disponíveis, inclusive +após reabrir um Work; o histórico usa o resultado mínimo persistido. + +Recibos de Plans/EPICs novos são fatos tipados, sem arquivos JSON. As origens +legadas de importação permanecem preservadas, assim como futuras cópias de +migração. Publicações temporárias usam um pequeno journal operacional, removido +após commit/rollback; recuperação distingue órfão próprio de payload já publicado. +Rollback de preparação remove diretórios vazios próprios e preserva resíduos +desconhecidos. Outputs solicitados fora do estado AIE não são alvos da limpeza. + +EXP-0002: 32 cenários distintos focados passaram em duas rodadas. Cobertura inclui +arquivo perdido antes de check, recusa de reuso após descarte, rollback da +conclusão, interrupção após commit e após unlink, publicação interrompida, +repetição, preservação de output e originais legados, recibos e coordenação. + +### TSK-0009 — consultas e diagnóstico + +Contexto, status, next-actions e validação usam snapshots SQLite para leituras +relacionadas. Parent/links de EPIC têm índice relacional com unicidade de pai e +FKs. Consultar um Work selecionado não carrega outros Works por conveniência: +um registro alheio inválido não bloqueia seu contexto. Validação global continua +inspecionando o projeto, contador, grafo, FK e integridade SQLite. + +Compatibilidade inspeciona registros tipados e revisões no banco, sem procurar +Markdown inexistente nem converter arquivos. Contexto expõe gates e disponibilidade +dos anexos. Next-actions sinaliza descarte interrompido sem fazê-lo durante leitura. +15 testes focados passaram, incluindo contexto em JVM separado, snapshot com outro +escritor, isolamento de Work inválido, histórico com formato não suportado e leitura +sem limpeza. A regressão legada de compatibilidade também passou na rodada anterior. + +### TSK-0010 — migração explícita + +`storage migrate` apresenta prévia sem escrita; `--apply --expect HASH` prepara +uma base separada, importa registros tipados e compara DTOs, revisões, autoridade +e integridade antes de selecionar SQLite. `--recover` e `--rollback` usam o +fingerprint da operação. A cópia de segurança conserva originais e fontes exatas +dos hashes; o staging é removido após êxito. Os arquivos legados existentes +permanecem em seus destinos, sem alteração ou remoção de arquivos rastreados. + +Contrato 4 e um marcador visível em `works/` impedem escrita por CLI antiga, +inclusive comandos que já aguardavam o lock. Escritores modernos compartilham +uma fronteira de publicação com espera limitada e recusam mudança de backend +durante a espera. Leituras não precisam desse lock. A recuperação recusa ativação +se o legado mudou; rollback preserva essas alterações e exige nova prévia. Depois +de novas gravações SQLite, rollback é recusado para não perder memória. + +A prova encontrou e corrigiu a distinção entre lista nula e vazia (especialmente +exclusions de Plan). Essa presença é tipada no esquema e os hashes originais +continuam ancorados em bytes externos, com comparação contra o registro tipado. +EXP-0003: 34 testes na rodada final passaram, incluindo cinco pontos de falha, +corpus congelado, Plan/survey ativo, EPIC/RUN, IDs reservados e compatibilidade. +Nenhum consumidor nem este workspace foi migrado. + +### TSK-0011 — inicialização local + +`init` prepara SQLite e bootstrap antes de publicar o workspace. Acrescenta +`/.ai-engineering/` ao .gitignore sem exigir Git, preservando instruções externas +e regras anteriores. `--version-state` deixa essa política ao desenvolvedor; +`--storage legacy` é explícito para compatibilidade. Nenhum comando remove arquivos +rastreados ou converte projetos existentes durante onboard/leitura. + +Bootstrap SQLite exige contrato 4 antes de acessar a base; esquemas/contratos +incompatíveis são diagnosticados. As instruções distribuídas exigem CLI compatível +para ler SQLite e proíbem interpretar memória ilegível como projeto vazio. Testes +de continuidade passaram em seis cenários JVM separados, inclusive sem Git no PATH. +A rodada consolidada de init, migração, compatibilidade, protocolo e arquitetura +também passou após explicitar o backend das fixtures legadas. + +### TSK-0012 — pacote preparado, instalação adiada + +`nativePackage` reúne AIE nativo, bibliotecas companheiras e CLI sqlite3 em +`build/native/package`; distribuições usam esse diretório completo. SQLite 3.54.1 +é compilado de fonte oficial com SHA3-256 fixado em scripts/sqlite-version.json. +O verificador confere componentes/hashes/versões, inicializa um projeto descartável +com AIE nativo e lê sua base com o sqlite3 do pacote. + +O instalador preparado aceita bin-dir/lib-dir, verifica uma release completa antes +de alternar current e publicar atalhos aie/ai-engineering/aie-sqlite3. Uma falha na +troca dos atalhos restaura a release e os atalhos anteriores. 17 testes com +ferramentas simuladas passaram, inclusive falha parcial de ativação. O pacote real +de build foi verificado em macOS arm64; Linux está coberto pelas fixtures de +instalação, sem prova nativa física nesta máquina. + +Nenhuma instalação real foi executada: binários/bibliotecas/atalhos ativos e +projetos consumidores permanecem intactos. + +### TSK-0013 — contrato documentado + +README, arquitetura, protocolo, compatibilidade e recursos de entrada agora +descrevem memória local SQLite, gates e anexos temporários. O procedimento público +está em docs/storage-migration.md. A referência detalhada do backend de arquivos +foi mantida separadamente como legado explícito. Os dois ciclos, OODA e autoridade +humana permanecem; instalação/migração reais continuam adiadas. Links locais foram +verificados e os testes de init, compatibilidade e Work guidance passaram. + +### TSK-0014 — regressão integrada e handoff + +`./gradlew check` passou com 230 testes JVM, zero falhas/erros/skips, além dos 11 +cenários do fixture Jenkins. O ajuste final do importador SQLite passou em rodada +focada de 17 testes (importação/recuperação e arquitetura). As 17 fixtures finais do +instalador passaram com ferramentas simuladas; nenhuma instalação real ocorreu. + +O pacote final e arquivos ZIP/TAR foram gerados com GraalVM e tiveram componentes, +hashes, versões e permissões verificados. O smoke nativo completo passou, incluindo +legado, continuidade, guidance/OODA e os novos cenários SQLite de gate pendente, +conclusão, descarte, recusa de reuso e migração do corpus congelado. O diagnóstico de +processos do macOS exigiu execução fora do sandbox; a repetição autorizada passou. +Uma cópia isolada do pacote abriu SQLite com extração temporária sem escrita; uma +cópia sem a biblioteca JDBC foi corretamente recusada. + +O gerador de latência foi verificado com um Work/uma nota sintéticos, sem medição. +docs/latency-scenario.md e scripts/latency-fixture.py foram encaminhados por Discussion +ao WRK-000C, que permanece OPEN. Adoção do banco não foi declarada prova de melhora. +A verificação física foi macOS arm64; Linux/Windows permanecem dependentes da matriz +CI para confirmação nativa. Instalação ativa, workspace canônico e consumidores +continuam no estado anterior, sem migração real. diff --git a/docs/storage-migration.md b/docs/storage-migration.md new file mode 100644 index 0000000..1252044 --- /dev/null +++ b/docs/storage-migration.md @@ -0,0 +1,72 @@ +# SQLite migration and recovery + +Installation and migration are separate operations. Building/installing a CLI does +not convert a project. Keep the installed version used by ongoing projects until +choosing to activate a compatible release. This implementation was tested on +fixtures only; its canonical workspace and consumers were not migrated. + +## Preview and apply + +Use a CLI that advertises protocol contract 4. In the chosen legacy project: + +```sh +aie project compatibility --format json +aie project validate --format json +aie storage migrate --format json +``` + +Preview reads supported canonical records, histories, evidence and bootstrap. It +returns validity, Work count and a fingerprint. It writes no lock, backup or database. +Repair invalid input first. Preserve original scope/authority; do not reopen completed +Works to normalize them. This route does not accept unknown future schemas. + +After reviewing the preview: + +```sh +aie storage migrate --apply --expect --format json +``` + +Application takes the publication lock, verifies the current fingerprint, makes a +safety copy under `.ai-engineering/.local/sqlite-migration//original`, +and imports into a separate staging database. It compares typed values/revisions, +references, approvals, reserved IDs, hashes and completion provenance. Original +file bytes remain external for historical chain verification; they are not BLOBs +or file-shaped TEXT in SQLite. + +Only after validation does activation publish the protected contract, database and +storage selection. A visible `works/SQLITE-STORAGE` marker also stops legacy readers +that had already passed an old contract check. Existing Work documents stay +byte-identical as retained non-authoritative originals; future writes use SQLite. +No tracked file is automatically untracked or removed, and existing Git ignore policy +is preserved. New projects use `init` with state ignored by default. + +Success reports APPLIED and the safety-copy path. Staging is removed. Repeating the +same application is idempotent. Keep the safety originals: historical revision hashes +may depend on them. They are not a general backup/export feature. + +## Interrupted operation + +Ordinary CLI access reports the pending migration rather than reading mixed storage. +Inspect its public preview/report, then choose: + +```sh +aie storage migrate --recover --expect +# Or explicitly return to the recoverable legacy source: +aie storage migrate --rollback --expect +``` + +Recovery verifies source/safety/prepared data and resumes without duplicate records. +If a legacy writer changed input before activation, recovery refuses stale data; +rollback preserves those legacy edits, then a new preview captures them. + +Rollback restores only bootstrap files changed by this operation and removes its +unchanged published database/guard. It retains the safety copy. Unrelated bootstrap +edits require deliberate review. Once SQLite has received new engineering writes, +rollback refuses to discard that memory; keep SQLite and inspect the diagnostic. +Never delete the database or journal to force a fresh-looking project. + +A migration does not retroactively discard legacy evidence, add approvals or claim +new quality gates passed. New temporary inputs and gate results follow the current +[retention contract](protocol.md#temporary-inputs-and-outputs). Work/DEC sharing, +import/export, distributed reconciliation and backup as a product feature remain +outside this version. diff --git a/scripts/activate-native-package.py b/scripts/activate-native-package.py new file mode 100644 index 0000000..fc71519 --- /dev/null +++ b/scripts/activate-native-package.py @@ -0,0 +1,72 @@ +#!/usr/bin/env python3 +"""Installer activation helper. Tests run a copied helper with fake tools and destinations.""" +import argparse +import os +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import uuid + +parser = argparse.ArgumentParser() +parser.add_argument("package", type=Path) +parser.add_argument("--bin-dir", type=Path, required=True) +parser.add_argument("--lib-dir", type=Path, required=True) +args = parser.parse_args() +bin_dir = args.bin_dir.absolute() +lib_dir = args.lib_dir.absolute() +bin_dir.mkdir(parents=True, exist_ok=True) +lib_dir.mkdir(parents=True, exist_ok=True) +current = lib_dir / "current" +if current.exists() and not current.is_symlink(): + raise SystemExit("Package current target must be a symlink") +names = {"ai-engineering": str(current / "ai-engineering"), "aie": "ai-engineering", + "aie-sqlite3": str(current / "sqlite3")} +for name in names: + if (bin_dir / name).is_dir(): + raise SystemExit("Installation target is a directory: " + str(bin_dir / name)) +release = lib_dir / "releases" / str(uuid.uuid4()) +release.parent.mkdir(parents=True, exist_ok=True) +shutil.copytree(args.package, release) +try: + subprocess.run([sys.executable, str(Path(__file__).with_name("verify-native-package.py")), str(release)], check=True) +except BaseException: + shutil.rmtree(release) + raise +backup = Path(tempfile.mkdtemp(prefix=".aie-install.", dir=bin_dir)) +previous_current = os.readlink(current) if current.is_symlink() else None +changed = [] +safe_to_cleanup = False +try: + for name, target in names.items(): + path = bin_dir / name + if path.is_symlink() or path.exists(): + shutil.copy2(path, backup / name, follow_symlinks=False) + (backup / (name + ".new")).symlink_to(target) + switch = lib_dir / (".current-" + str(uuid.uuid4())) + switch.symlink_to(str(release.relative_to(lib_dir))) + os.replace(switch, current) + for name in names: + os.replace(backup / (name + ".new"), bin_dir / name) + changed.append(name) + safe_to_cleanup = True +except BaseException: + for name in reversed(changed): + saved = backup / name + if saved.is_symlink() or saved.exists(): + os.replace(saved, bin_dir / name) + else: + (bin_dir / name).unlink() + if previous_current is None: + current.unlink(missing_ok=True) + else: + restored = lib_dir / (".restore-" + str(uuid.uuid4())); restored.symlink_to(previous_current) + os.replace(restored, current) + shutil.rmtree(release) + safe_to_cleanup = True + raise +finally: + if safe_to_cleanup: + shutil.rmtree(backup) +print("Activated native package:", current) diff --git a/scripts/build-sqlite-cli.py b/scripts/build-sqlite-cli.py new file mode 100644 index 0000000..507e8ad --- /dev/null +++ b/scripts/build-sqlite-cli.py @@ -0,0 +1,57 @@ +#!/usr/bin/env python3 +"""Build the pinned diagnostic CLI in build/, never install it.""" +import hashlib +import json +import os +import platform +from pathlib import Path +import subprocess +import sys +import urllib.request +import zipfile + +destination = Path(sys.argv[1]).resolve() +destination.mkdir(parents=True, exist_ok=True) +pin = json.loads(Path(__file__).with_name("sqlite-version.json").read_text()) +if sys.platform == "win32": + if platform.machine().lower() not in ("amd64", "x86_64"): + raise SystemExit("The native Windows package currently requires x64") + archive = destination / "sqlite-tools-win-x64.zip" + if not archive.exists(): + urllib.request.urlretrieve(pin["windows_url"], archive) + if hashlib.sha3_256(archive.read_bytes()).hexdigest() != pin["windows_sha3_256"]: + raise SystemExit("SQLite Windows package checksum differs from the official pin") + with zipfile.ZipFile(archive) as bundle: + names = [name for name in bundle.namelist() if name.rsplit("/", 1)[-1] == "sqlite3.exe"] + if len(names) != 1: + raise SystemExit("SQLite package lacks an unambiguous sqlite3.exe") + (destination / "sqlite3.exe").write_bytes(bundle.read(names[0])) + version = subprocess.check_output([str(destination / "sqlite3.exe"), "--version"], text=True).split()[0] + if version != pin["version"]: + raise SystemExit("SQLite Windows package version differs from the pin") + sys.exit(0) +archive = destination / pin["archive"] +if not archive.exists(): + temporary = archive.with_suffix(".download") + urllib.request.urlretrieve(pin["url"], temporary) + temporary.replace(archive) +if hashlib.sha3_256(archive.read_bytes()).hexdigest() != pin["sha3_256"]: + raise SystemExit("SQLite source checksum differs from the pinned official release") +source = destination / "source" +source.mkdir(exist_ok=True) +with zipfile.ZipFile(archive) as bundle: + prefix = pin["archive"].removesuffix(".zip") + "/" + for name in ("sqlite3.c", "sqlite3.h", "sqlite3ext.h", "shell.c"): + (source / name).write_bytes(bundle.read(prefix + name)) +binary = destination / "sqlite3" +temporary = destination / "sqlite3.new" +command = [os.environ.get("CC", "cc"), "-O2", "-DSQLITE_THREADSAFE=1", "-DSQLITE_DQS=0", + str(source / "shell.c"), str(source / "sqlite3.c"), "-o", str(temporary), "-lm", "-lpthread"] +if sys.platform.startswith("linux"): + command.append("-ldl") +subprocess.run(command, check=True) +version = subprocess.check_output([str(temporary), "--version"], text=True).split()[0] +if version != pin["version"]: + raise SystemExit("Compiled SQLite version differs from the pin") +temporary.replace(binary) +print("Built SQLite", version, "in", destination) diff --git a/scripts/install-native.sh b/scripts/install-native.sh index 771b617..8a23370 100755 --- a/scripts/install-native.sh +++ b/scripts/install-native.sh @@ -4,10 +4,11 @@ set -euo pipefail usage() { cat <<'EOF' -Usage: scripts/install-native.sh [--bin-dir DIR] +Usage: scripts/install-native.sh [--bin-dir DIR] [--lib-dir DIR] -Build and install ai-engineering and the aie shortcut (Linux/macOS). -Default destination: $HOME/.local/bin. Run again to update. +Build and install a complete AIE + SQLite package (Linux/macOS). +Default package: $HOME/.local/lib/ai-engineering; shortcuts: $HOME/.local/bin. +Creates ai-engineering, aie and aie-sqlite3 shortcuts. Run again to update. Uses GRAALVM_HOME, a compatible JAVA_HOME, or installs the GraalVM pinned in .sdkmanrc through SDKMAN (bootstrapped when absent). Requires JDK 25 with @@ -16,6 +17,7 @@ Does not install system packages or edit shell profiles. Options: --bin-dir DIR Installation directory (no sudo needed for the default). + --lib-dir DIR Package/releases directory; data stays in each project. -h, --help Show this help. EOF } @@ -24,6 +26,7 @@ die() { printf 'Error: %s\n' "$*" >&2; exit 1; } log() { printf '\n==> %s\n' "$*"; } bin_dir="${HOME:?HOME must be set}/.local/bin" +lib_dir="$HOME/.local/lib/ai-engineering" while [[ $# -gt 0 ]]; do case "$1" in --bin-dir) @@ -31,6 +34,11 @@ while [[ $# -gt 0 ]]; do bin_dir=$2 shift 2 ;; + --lib-dir) + [[ $# -ge 2 && -n "$2" && "$2" != --* ]] || die '--lib-dir requires a directory.' + lib_dir=$2 + shift 2 + ;; -h|--help) usage; exit 0 ;; *) usage >&2; die "Unknown argument: $1" ;; esac @@ -48,7 +56,7 @@ case "$platform/$architecture" in esac case "$bin_dir" in /*) ;; *) bin_dir="$PWD/$bin_dir" ;; esac -for name in ai-engineering aie; do +for name in ai-engineering aie aie-sqlite3; do [[ ! -d "$bin_dir/$name" ]] || die "Installation target is a directory: $bin_dir/$name" done @@ -154,22 +162,14 @@ log "Building with $JAVA_HOME" "-Dorg.gradle.java.home=$JAVA_HOME" \ "-Porg.gradle.java.installations.paths=$JAVA_HOME" \ -Porg.gradle.java.installations.auto-detect=false \ - -Porg.gradle.java.installations.auto-download=false nativeCompile + -Porg.gradle.java.installations.auto-download=false nativePackage ) -native_binary="$project_dir/build/native/nativeCompile/ai-engineering" -[[ -x "$native_binary" ]] || die "Build did not produce an executable: $native_binary" -log "Installing in $bin_dir" -mkdir -p -- "$bin_dir" -bin_dir=$(cd -- "$bin_dir" && pwd -P) -# Stage on the destination filesystem. Rename replaces old binaries/symlinks -# without following a previous symlink back into this checkout. -stage_dir=$(mktemp -d "$bin_dir/.aie-install.XXXXXXXX") -install -m 755 "$native_binary" "$stage_dir/ai-engineering" -"$stage_dir/ai-engineering" --help >/dev/null -ln -s ai-engineering "$stage_dir/aie" -mv -f -- "$stage_dir/ai-engineering" "$bin_dir/ai-engineering" -mv -f -- "$stage_dir/aie" "$bin_dir/aie" +native_package="$project_dir/build/native/package" +[[ -x "$native_package/ai-engineering" ]] || die "Build did not produce a complete package: $native_package" +command -v python3 >/dev/null 2>&1 || die 'Python 3 is required to verify and activate the package.' +log "Verifying package before activation in $lib_dir" +python3 "$project_dir/scripts/activate-native-package.py" "$native_package" --bin-dir "$bin_dir" --lib-dir "$lib_dir" log "Installed: $bin_dir/ai-engineering (shortcut: $bin_dir/aie)" case ":$PATH:" in *":$bin_dir:"*) ;; diff --git a/scripts/latency-fixture.py b/scripts/latency-fixture.py new file mode 100644 index 0000000..c804280 --- /dev/null +++ b/scripts/latency-fixture.py @@ -0,0 +1,41 @@ +#!/usr/bin/env python3 +"""Generate a disposable WRK-000C dataset; does not benchmark, install or migrate anything.""" +import argparse +import hashlib +import json +from pathlib import Path +import platform +import re +import subprocess + +parser = argparse.ArgumentParser() +parser.add_argument("--binary", type=Path, required=True) +parser.add_argument("--directory", type=Path, required=True) +parser.add_argument("--works", type=int, default=100) +parser.add_argument("--entries", type=int, default=10) +parser.add_argument("--storage", choices=("sqlite", "legacy"), default="sqlite") +args = parser.parse_args() +if args.works < 1 or args.entries < 0: + parser.error("Use positive Works and nonnegative entries") +binary = args.binary.resolve(strict=True) +root = args.directory.absolute() +root.mkdir(parents=True, exist_ok=False) +def run(*command): + return subprocess.check_output([str(binary), *command], cwd=root, text=True, stderr=subprocess.STDOUT, timeout=60) +version = run("--version").strip() +run("init", "--name", "Disposable latency dataset", "--storage", args.storage) +last = None +for index in range(args.works): + output = run("work", "create", "Synthetic work " + str(index + 1), "--goal", "Resume local engineering memory") + match = re.search(r'^id: "(WRK-[0-9A-F]+)"', output, re.MULTILINE) + if not match: + raise SystemExit("Cannot identify generated Work") + last = match.group(1) + for entry in range(args.entries): + run("discussion", "add", last, "--text", "Synthetic observation " + str(entry + 1) + " — UTF-8", "--author", "fixture") +metadata = {"version": version, "binary": str(binary), "binarySha256": hashlib.sha256(binary.read_bytes()).hexdigest(), + "platform": platform.platform(), "machine": platform.machine(), "storage": args.storage, + "works": args.works, "entriesPerWork": args.entries, "selectedWork": last, + "measurementPerformed": False} +(root / "latency-fixture.json").write_text(json.dumps(metadata, indent=2) + "\n") +print(json.dumps(metadata, indent=2)) diff --git a/scripts/native-package-manifest.py b/scripts/native-package-manifest.py new file mode 100644 index 0000000..b44d48d --- /dev/null +++ b/scripts/native-package-manifest.py @@ -0,0 +1,12 @@ +#!/usr/bin/env python3 +import hashlib +import json +from pathlib import Path +import sys + +package = Path(sys.argv[1]).resolve() +files = {str(path.relative_to(package)): hashlib.sha256(path.read_bytes()).hexdigest() + for path in sorted(package.rglob("*")) if path.is_file() and path.name != "aie-package.json"} +manifest = {"schemaVersion": 1, "aieVersion": "0.1.0", "protocolVersion": 4, + "sqliteVersion": "3.54.1", "files": files} +(package / "aie-package.json").write_text(json.dumps(manifest, indent=2) + "\n") diff --git a/scripts/native-smoke.sh b/scripts/native-smoke.sh index 7c7ede2..a95a458 100755 --- a/scripts/native-smoke.sh +++ b/scripts/native-smoke.sh @@ -26,7 +26,7 @@ aie_without_git() { mkdir plain cd plain printf 'Existing source\n' > main.txt -aie_without_git init --name 'Simple Project' > init.yaml +aie_without_git init --storage legacy --name 'Simple Project' > init.yaml aie_without_git work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" 'Continue application' --goal 'Preserve local context' > work.yaml aie_without_git work list --open --format table > works-table.txt grep -q 'WRK-0001' works-table.txt @@ -48,9 +48,9 @@ grep -q '^WRK-0001,CREATE_PLAN,' actions.csv aie_without_git project compatibility --format json > compatibility.json grep -q '"state" : "CURRENT"' compatibility.json grep -q '"migrationRequired" : false' compatibility.json -grep -q '"protocolVersion": 3' .ai-engineering/protocol.json +grep -q '"protocolVersion": 4' .ai-engineering/protocol.json cp .ai-engineering/protocol.json baseline-protocol.json -sed 's/"protocolVersion": 3/"protocolVersion": 99/' baseline-protocol.json > .ai-engineering/protocol.json +sed 's/"protocolVersion": 4/"protocolVersion": 99/' baseline-protocol.json > .ai-engineering/protocol.json cp .ai-engineering/protocol.json future-protocol.json if aie_without_git project compatibility --format json > future-compatibility.json; then echo 'Unsupported contract unexpectedly succeeded' >&2 @@ -113,7 +113,7 @@ cd "$aie_fixture" # Creating a Plan promotes a draft without a model or direct human attestation. mkdir plan-promotion cd plan-promotion -aie_without_git init --name 'Plan Promotion' > init.yaml +aie_without_git init --storage legacy --name 'Plan Promotion' > init.yaml aie_without_git work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" 'Promote decision' > work.yaml aie_without_git decision draft WRK-0001 --title 'Chosen approach' --context 'Problem' \ --approach 'Small implementation' --rationale 'Bounded scope' > draft.yaml @@ -143,7 +143,7 @@ cp -R "$aie_fixture/df-alpha" "$aie_fixture/df-alpha-before" cp -R "$aie_fixture/df-beta" "$aie_fixture/df-beta-before" mkdir "$aie_fixture/df-import" cd "$aie_fixture/df-import" -aie_without_git init --name 'DF import destination' > init.yaml +aie_without_git init --storage legacy --name 'DF import destination' > init.yaml aie_df_args=(--source "alpha=$aie_fixture/df-alpha" --source "beta=$aie_fixture/df-beta" --target alpha=runtime --target alpha=docs --target beta=studio --format json) aie_without_git import discussion "${aie_df_args[@]}" > preview.json @@ -175,7 +175,7 @@ cd "$aie_fixture" # A single Git repository can contain both the source and protocol workspace. git init -q single cd single -"$aie_binary" init --name 'Single Repository' > init.yaml +"$aie_binary" init --storage legacy --name 'Single Repository' > init.yaml "$aie_binary" repo add app --path . > repo.yaml "$aie_binary" work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" 'Inspect application' --repo app > work.yaml "$aie_binary" work context WRK-0001 --format json > before.json @@ -193,7 +193,7 @@ echo 'Native simple-project continuity smoke passed (without Git and with one ro # Work numbers are hexadecimal; child counters still use decimal. mkdir hexadecimal cd hexadecimal -aie_without_git init --name 'Hexadecimal Works' > init.yaml +aie_without_git init --storage legacy --name 'Hexadecimal Works' > init.yaml for aie_number in {1..16}; do aie_without_git work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" "Work $aie_number" > "work-$aie_number.yaml" done @@ -218,7 +218,7 @@ cd "$aie_fixture" # Reserve all old decimal spellings, including removed Works, when upgrading counters. mkdir legacy-counter cd legacy-counter -aie_without_git init --name 'Legacy reservations' > init.yaml +aie_without_git init --storage legacy --name 'Legacy reservations' > init.yaml printf 'schemaVersion: 1\nlastWork: 16\n' > .ai-engineering/works/.sequence.yaml aie_without_git work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" 'After legacy reservation' > work.yaml grep -q 'id: "WRK-0017"' work.yaml @@ -231,7 +231,7 @@ echo 'Native hexadecimal Work identifiers and legacy reservations smoke passed.' # Exercise the refinement contract with two fixture adapters and fresh processes. mkdir refinement cd refinement -aie_without_git init --name 'Refinement fixture' --general-adapter fixture-general \ +aie_without_git init --storage legacy --name 'Refinement fixture' --general-adapter fixture-general \ --archive-policy reversible > init.yaml aie_without_git work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" 'Compare ideas' > work.yaml printf 'Rendering: measure layers\nInput: compare controls\n' > ideas.md @@ -326,7 +326,7 @@ export AIE_CODEX_EXECUTABLE="$aie_fixture/providers/codex" export AIE_CLAUDE_EXECUTABLE="$aie_fixture/providers/claude" cd local-cli printf '1\ngeneral\ndefault\n5\n1\n3\nreviewer\ndefault\n5\n1\n' > setup.txt -aie_without_git init . --name 'Native CLI fixture' --interactive --input-file setup.txt > setup.yaml +aie_without_git init --storage legacy . --name 'Native CLI fixture' --interactive --input-file setup.txt > setup.yaml aie_without_git agent doctor --format json > doctor.json grep -q '"compatible" : true' doctor.json aie_without_git work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" 'Provider protocol' > work.yaml @@ -354,7 +354,7 @@ echo 'Native local-CLI transport smoke passed (controlled subprocess fixtures, g # EPIC state control is entirely deterministic and does not need configured agents. mkdir epic-coordination cd epic-coordination -aie_without_git init --name 'EPIC coordination fixture' > init.yaml +aie_without_git init --storage legacy --name 'EPIC coordination fixture' > init.yaml for aie_title in Parent Required Cancelled Optional; do aie_without_git work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" "$aie_title" --acceptance 'Reviewed fixture result' > "$aie_title.yaml" done @@ -427,7 +427,7 @@ for aie_repo in runtime studio; do git -C "$aie_repo" -c user.name=Fixture -c user.email=fixture@example.invalid \ commit -q --allow-empty -m fixture done -"$aie_binary" init --name 'Continuity Experiment' > init.yaml +"$aie_binary" init --storage legacy --name 'Continuity Experiment' > init.yaml "$aie_binary" repo add runtime --path runtime --language rust > runtime.yaml "$aie_binary" repo add studio --path studio --language java > studio.yaml "$aie_binary" work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" 'Improve scene editor' --repo runtime --repo studio \ @@ -521,7 +521,7 @@ echo 'Native operational-cycle smoke passed (discovery, approval, plan, evidence # Automatic consolidation across independent native processes without Git/JVM/models. mkdir "$aie_fixture/plan-consolidation" cd "$aie_fixture/plan-consolidation" -aie_without_git init --name 'Plan consolidation' > init.yaml +aie_without_git init --storage legacy --name 'Plan consolidation' > init.yaml aie_without_git work create --mode DIRECT --approval WAIVED --human-approved --choice-reason "Explicit synthetic fixture policy" 'Delivery' > work.yaml printf 'Synthetic executed result\n' > result.txt aie_without_git artifact add WRK-0001 --file result.txt --purpose 'Fixture execution' > evidence.yaml @@ -559,7 +559,7 @@ echo 'Native Plan consolidation smoke passed (multiple Plans, reviewed cancellat # Human conduct and optional OODA across fresh native processes without Git/JVM/model. mkdir "$aie_fixture/work-guidance" cd "$aie_fixture/work-guidance" -aie_without_git init --name 'Human conduct and experiments' > init.yaml +aie_without_git init --storage legacy --name 'Human conduct and experiments' > init.yaml aie_without_git work create 'Explicit human control' > unspecified.yaml aie_without_git next-actions WRK-0001 --format json > unspecified-actions.json grep -q ASK_DISCUSSION_MODE unspecified-actions.json @@ -624,3 +624,6 @@ aie_without_git project validate --format json > validation.json grep -q '"valid" : true' validation.json echo 'Native Work guidance/OODA smoke passed (human mode/request/approval, explicit waiver, criteria, evidence, independent execution and approved DEC revision).' if [[ "${AIE_KEEP_FIXTURE:-0}" == 1 ]]; then echo "Fixture retained: $aie_fixture"; fi + +# Exercise the default SQLite backend, gates and migration separately from legacy fixtures. +bash "$aie_source_root/scripts/native-sqlite-smoke.sh" "$aie_binary" diff --git a/scripts/native-sqlite-smoke.sh b/scripts/native-sqlite-smoke.sh new file mode 100644 index 0000000..6dc7f8e --- /dev/null +++ b/scripts/native-sqlite-smoke.sh @@ -0,0 +1,57 @@ +#!/usr/bin/env bash +set -euo pipefail +binary=${1:?Usage: native-sqlite-smoke.sh /absolute/package/ai-engineering} +source_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P) +fixture=$(mktemp -d "${TMPDIR:-/tmp}/aie-sqlite-smoke.XXXXXXXX") +trap 'rm -rf "$fixture"' EXIT +mkdir "$fixture/local" +cd "$fixture/local" +run() { PATH="$fixture/no-tools" "$binary" "$@"; } +run init --name 'Local memory' > init.yaml +test -f .ai-engineering/aie.db +grep -q '/.ai-engineering/' .gitignore +printf 'Source evaluated by the fixture\n' > source.txt +run work create 'Deliver' --goal 'Preserve quality' --acceptance 'Observed check' \ + --mode EXPLORATORY --human-approved --choice-reason 'Explicit synthetic human choice' --author fixture-owner > work.yaml +run discussion add WRK-0001 --text 'Investigação — preservar contexto' --author fixture-owner > note.yaml +run work request-decision WRK-0001 --by fixture-owner --reason 'Exploration ended in this fixture' --human-approved > request.yaml +run decision draft WRK-0001 --title 'Approach' --context 'Observed facts' --approach 'Small change' --rationale 'Bounded' > decision.yaml +run decision accept WRK-0001 DEC-0001 --by fixture-owner --reason 'Reviewed fixture DEC' --human-approved > accepted.yaml +run plan create WRK-0001 --title 'Deliver' --decision DEC-0001 > plan.yaml +run plan step add WRK-0001 PLN-0001 --title 'Check result' > step.yaml +run gate configure quality --title 'Project quality' --procedure 'Review source.txt' --input source.txt --require-evidence --by fixture-owner > gate.yaml +run artifact add WRK-0001 --file source.txt --purpose 'Temporary evaluated input' > evidence.yaml +run plan step status WRK-0001 PLN-0001 TSK-0001 COMPLETED --by fixture --reason 'Observed synthetic result' --evidence ART-0001 > finished-step.yaml +run work show WRK-0001 --format json > pending.json +if grep -q '"status" : "COMPLETED"' pending.json; then echo 'Pending gate did not block delivery' >&2; exit 1; fi +test -f .ai-engineering/works/WRK-0001-deliver/artifacts/evidence/ART-0001/payload +run gate status WRK-0001 --format json > gate-status.json +fingerprint=$(python3 -c 'import json; print(json.load(open("gate-status.json"))[0]["evaluatedHash"])') +run gate record WRK-0001 project/quality --expect "$fingerprint" --invocation 'Review source.txt' \ + --outcome PASS --summary 'Synthetic observed evaluation' --evidence ART-0001 --by fixture --observed > result.yaml +run work context WRK-0001 --format json > context.json +grep -q '"status" : "COMPLETED"' context.json +grep -q 'DISCARDED' context.json +test ! -f .ai-engineering/works/WRK-0001-deliver/work.md +test ! -f .ai-engineering/works/WRK-0001-deliver/artifacts/evidence/ART-0001/payload +test -f source.txt +run project validate > validation.yaml +run work reopen WRK-0001 --by fixture-owner --reason 'New observation' > reopened.yaml +if run gate record WRK-0001 project/quality --expect "$fingerprint" --invocation 'Review source.txt' \ + --outcome PASS --summary 'Invalid retired reuse' --evidence ART-0001 --by fixture --observed > retired-error.txt 2>&1; then + echo 'Retired input unexpectedly accepted' >&2; exit 1 +fi +mkdir "$fixture/legacy" +cd "$fixture/legacy" +run init --storage legacy --name 'Migration fixture' > init.yaml +run work create 'Delivered baseline' > work.yaml +cp -R "$source_root/src/test/resources/compatibility/baseline-v1/.ai-engineering/." .ai-engineering/ +run storage migrate --format json > preview.json +fingerprint=$(python3 -c 'import json; print(json.load(open("preview.json"))["fingerprint"])') +run storage migrate --apply --expect "$fingerprint" --format json > migrated.json +run project validate > validation.yaml +run work context WRK-0001 --format json > context.json +grep -q '72d5803add0b8714d7dc4bf7e63ad55cc3259df910aa8b03790657eac4c2bd02' context.json +run storage migrate --apply --expect "$fingerprint" --format json > repeated.json +grep -q 'APPLIED' repeated.json +echo 'Native SQLite lifecycle, gates and legacy migration smoke passed.' diff --git a/scripts/sqlite-probe.sh b/scripts/sqlite-probe.sh new file mode 100644 index 0000000..106e568 --- /dev/null +++ b/scripts/sqlite-probe.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# Smoke the build-only native probe. Never installs binaries or opens project data. +set -euo pipefail +probe=${1:?Usage: sqlite-probe.sh /absolute/path/to/aie-sqlite-probe} +case "$probe" in /*) ;; *) echo 'Supply an absolute build path.' >&2; exit 2 ;; esac +[[ -x "$probe" ]] || { echo 'Native probe is missing.' >&2; exit 2; } +probe_dir=$(cd -- "$(dirname -- "$probe")" && pwd -P) +fixture=$(mktemp -d "${TMPDIR:-/tmp}/aie-sqlite-proof.XXXXXXXX") +trap 'rm -rf -- "$fixture"' EXIT +# Extraction must not be needed: the temporary directory is readable but not writable. +mkdir "$fixture/no-extraction" +chmod 500 "$fixture/no-extraction" +"$probe" "-Dorg.sqlite.lib.path=$probe_dir" "-Dorg.sqlite.tmpdir=$fixture/no-extraction" "$fixture/proof.db" +"$probe" "-Dorg.sqlite.lib.path=$probe_dir" "-Dorg.sqlite.tmpdir=$fixture/no-extraction" "$fixture/proof.db" +# Exported JNI support must really come from the distribution. The isolated copy +# has neither a sibling library nor an embedded resource from which to extract it. +mkdir "$fixture/isolated" +cp "$probe" "$fixture/isolated/aie-sqlite-probe" +if "$fixture/isolated/aie-sqlite-probe" "-Dorg.sqlite.lib.path=$fixture/isolated" \ + "-Dorg.sqlite.tmpdir=$fixture/no-extraction" "$fixture/missing-library.db" \ + > "$fixture/missing-library.log" 2>&1; then + echo 'Isolated executable unexpectedly worked without its SQLite library.' >&2 + exit 1 +fi +echo 'Native SQLite proof passed: separate processes, UTF-8, rollback and external library.' diff --git a/scripts/sqlite-version.json b/scripts/sqlite-version.json new file mode 100644 index 0000000..f250bd4 --- /dev/null +++ b/scripts/sqlite-version.json @@ -0,0 +1,9 @@ +{ + "version": "3.54.1", + "archive": "sqlite-amalgamation-3540100.zip", + "url": "https://sqlite.org/2026/sqlite-amalgamation-3540100.zip", + "sha3_256": "92281c86e2957f9b9305890f9ac04204caa7b677cc868dc326d942689df28e30", + "source": "https://sqlite.org/download.html", + "windows_url": "https://sqlite.org/2026/sqlite-tools-win-x64-3540100.zip", + "windows_sha3_256": "e171f3993a992edf076746926dd52b5e2ebfabaee38818e74987e1d8112ab987" +} diff --git a/scripts/test-install-native.py b/scripts/test-install-native.py index ba1a7a6..d4b6496 100644 --- a/scripts/test-install-native.py +++ b/scripts/test-install-native.py @@ -7,9 +7,12 @@ These test installation behavior, not native compilation itself. import os from pathlib import Path import shutil +import runpy import subprocess +import sys import tempfile import unittest +from unittest import mock INSTALLER = Path(__file__).resolve().with_name("install-native.sh") @@ -28,6 +31,8 @@ class NativeInstallerTest(unittest.TestCase): self.tools.mkdir() (self.repo / "scripts").mkdir(parents=True) shutil.copy2(INSTALLER, self.repo / "scripts/install-native.sh") + for name in ("activate-native-package.py", "verify-native-package.py", "native-package-manifest.py"): + shutil.copy2(INSTALLER.with_name(name), self.repo / "scripts" / name) (self.repo / ".sdkmanrc").write_text("java=25-test-graalce\n") self.env = {key: value for key, value in os.environ.items() if not key.startswith(("JAVA", "GRAAL", "SDKMAN", "BASH_ENV"))} @@ -46,13 +51,25 @@ printf '%s\n' "$PWD" "$JAVA_HOME" "$GRAALVM_HOME" "$@" >> "$FIXTURE_LOG" [[ "$JAVA_HOME" == "$GRAALVM_HOME" ]] || exit 91 [[ "${FIXTURE_BUILD_EXIT:-0}" == 0 ]] || exit "$FIXTURE_BUILD_EXIT" [[ "${FIXTURE_MISSING_BINARY:-0}" == 0 ]] || exit 0 -mkdir -p build/native/nativeCompile -cat > build/native/nativeCompile/ai-engineering <<'EOF' +mkdir -p build/native/package +cat > build/native/package/ai-engineering <<'EOF' #!/bin/bash -echo "fixture CLI" +case "${1:-}" in + --version) echo "ai-engineering 0.1.0" ;; + init) mkdir -p .ai-engineering; touch .ai-engineering/aie.db ;; + *) echo "fixture CLI" ;; +esac exit "${FIXTURE_BINARY_EXIT:-0}" EOF -chmod +x build/native/nativeCompile/ai-engineering +chmod +x build/native/package/ai-engineering +cat > build/native/package/sqlite3 <<'EOF' +#!/bin/bash +[[ "${1:-}" == --version ]] && echo "3.54.1 fixture" || echo "ok" +EOF +chmod +x build/native/package/sqlite3 +if [[ "${FIXTURE_MISSING_LIBRARY:-0}" == 0 ]]; then echo "fixture library" > build/native/package/libsqlitejdbc.so; fi +python3 scripts/native-package-manifest.py build/native/package +if [[ "${FIXTURE_CORRUPT_PACKAGE:-0}" == 1 ]]; then echo "changed" >> build/native/package/libsqlitejdbc.so; fi ''') def executable(self, path, body): @@ -84,7 +101,7 @@ chmod +x build/native/nativeCompile/ai-engineering def test_default_install_is_independent_and_can_be_updated(self): output = self.run_installer() dest = self.home / ".local/bin" - self.assertFalse((dest / "ai-engineering").is_symlink()) + self.assertTrue((dest / "ai-engineering").is_symlink()) self.assertEqual(os.readlink(dest / "aie"), "ai-engineering") self.assertEqual((dest / "ai-engineering").stat().st_mode & 0o777, 0o755) self.assertIn('export PATH=', output) @@ -106,6 +123,49 @@ chmod +x build/native/nativeCompile/ai-engineering self.env["FIXTURE_ARCH"] = "aarch64" self.run_installer() + def test_complete_package_uses_custom_library_directory(self): + library = self.root / "custom library" + self.run_installer("--lib-dir", str(library)) + current = library / "current" + self.assertTrue(current.is_symlink()) + self.assertTrue((current / "libsqlitejdbc.so").is_file()) + self.assertTrue((current / "sqlite3").is_file()) + shortcut = self.home / ".local/bin/aie-sqlite3" + self.assertEqual(subprocess.check_output([str(shortcut), "--version"], text=True).split()[0], "3.54.1") + previous = os.readlink(current) + self.run_installer("--lib-dir", str(library)) + self.assertNotEqual(os.readlink(current), previous) + self.assertTrue((library / previous).is_dir()) + + def test_missing_or_corrupt_library_preserves_previous_installation(self): + dest = self.old_installation() + for key in ("FIXTURE_MISSING_LIBRARY", "FIXTURE_CORRUPT_PACKAGE"): + with self.subTest(key=key): + self.env[key] = "1" + self.run_installer(success=False) + self.assert_old_installation(dest) + del self.env[key] + + def test_activation_failure_restores_current_release_and_all_shortcuts(self): + self.run_installer() + library = self.home / ".local/lib/ai-engineering" + dest = self.home / ".local/bin" + previous = os.readlink(library / "current") + links = {name: os.readlink(dest / name) for name in ("ai-engineering", "aie", "aie-sqlite3")} + replace = os.replace + def fail_second_shortcut(source, target): + if Path(source).name == "aie.new": + raise OSError("Synthetic activation failure") + return replace(source, target) + arguments = [str(self.repo / "scripts/activate-native-package.py"), str(self.repo / "build/native/package"), + "--bin-dir", str(dest), "--lib-dir", str(library)] + with mock.patch.dict(os.environ, self.env, clear=True), mock.patch.object(sys, "argv", arguments), mock.patch("os.replace", side_effect=fail_second_shortcut): + with self.assertRaisesRegex(OSError, "Synthetic activation failure"): + runpy.run_path(arguments[0], run_name="__main__") + self.assertEqual(os.readlink(library / "current"), previous) + self.assertEqual({name: os.readlink(dest / name) for name in links}, links) + self.assertEqual(list(dest.glob(".aie-install.*")), []) + def test_replaces_previous_symlinks_without_following_them(self): dest = self.home / ".local/bin" dest.mkdir(parents=True) @@ -115,7 +175,7 @@ chmod +x build/native/nativeCompile/ai-engineering (dest / "aie").symlink_to(old) self.run_installer() self.assertEqual(old.read_text(), "keep this target") - self.assertFalse((dest / "ai-engineering").is_symlink()) + self.assertTrue((dest / "ai-engineering").is_symlink()) self.assertEqual(os.readlink(dest / "aie"), "ai-engineering") def test_build_failure_preserves_installation(self): diff --git a/scripts/verify-native-package.py b/scripts/verify-native-package.py new file mode 100644 index 0000000..615afe1 --- /dev/null +++ b/scripts/verify-native-package.py @@ -0,0 +1,44 @@ +#!/usr/bin/env python3 +"""Validate a complete candidate before activation, using only disposable project data.""" +import hashlib +import json +from pathlib import Path +import subprocess +import sys +import tempfile + +package = Path(sys.argv[1]).resolve() +manifest = json.loads((package / "aie-package.json").read_text()) +if manifest.get("schemaVersion") != 1 or manifest.get("protocolVersion") != 4: + raise SystemExit("Unsupported native package manifest") +expected = manifest["files"] +actual = set() +for path in package.rglob("*"): + if path.is_symlink(): + raise SystemExit("Package components must be regular files, not symlinks") + if path.is_file() and path.name != "aie-package.json": + relative = str(path.relative_to(package)); actual.add(relative) + if hashlib.sha256(path.read_bytes()).hexdigest() != expected.get(relative): + raise SystemExit("Package integrity mismatch: " + relative) +aie_name = "ai-engineering.exe" if "ai-engineering.exe" in actual else "ai-engineering" +sqlite_name = "sqlite3.exe" if "sqlite3.exe" in actual else "sqlite3" +if actual != set(expected) or not {aie_name, sqlite_name}.issubset(actual): + raise SystemExit("Incomplete package components") +if not any(name.startswith("libsqlitejdbc.") or name == "sqlitejdbc.dll" for name in actual): + raise SystemExit("Missing companion SQLite JDBC library") +aie, sqlite = package / aie_name, package / sqlite_name +if subprocess.check_output([str(aie), "--version"], text=True).strip() != "ai-engineering " + manifest["aieVersion"]: + raise SystemExit("AIE package version mismatch") +if subprocess.check_output([str(sqlite), "--version"], text=True).split()[0] != manifest["sqliteVersion"]: + raise SystemExit("SQLite package version mismatch") +with tempfile.TemporaryDirectory(prefix="aie-package-check-") as temporary: + root = Path(temporary) + subprocess.run([str(aie), "init", "--name", "Disposable package verification"], cwd=root, + check=True, stdout=subprocess.DEVNULL) + database = root / ".ai-engineering/aie.db" + if not database.is_file(): + raise SystemExit("Native AIE did not create its disposable database") + result = subprocess.check_output([str(sqlite), "-readonly", str(database), "PRAGMA quick_check;"], text=True).strip() + if result != "ok": + raise SystemExit("Packaged SQLite cannot read the native AIE database") +print("Native package verified:", package) diff --git a/src/main/java/net/intrepid/aiengineering/NativeHints.java b/src/main/java/net/intrepid/aiengineering/NativeHints.java index 8cfbbaa..3d373b8 100644 --- a/src/main/java/net/intrepid/aiengineering/NativeHints.java +++ b/src/main/java/net/intrepid/aiengineering/NativeHints.java @@ -23,6 +23,8 @@ public final class NativeHints implements RuntimeHintsRegistrar { net.intrepid.aiengineering.planning.Experiment.Outcome.class, PlanCoordinator.PlanSource.class, PlanCoordinator.Receipt.class, PlanCoordinator.Evaluation.class, PlanCoordinator.Result.class, PlanCoordinator.Mutation.class, Work.Aggregation.class, + QualityGates.Definition.class, QualityGates.Result.class, QualityGates.View.class, QualityGates.Outcome.class, + StorageMigration.State.class, StorageMigration.Report.class, Work.Event.class, Work.Completion.class, Work.CriterionResult.class, Work.Integration.class, Work.Delegation.class, Epic.class, Epic.Link.class, Epic.Authorization.class, EpicCoordinator.Child.class, EpicCoordinator.Evaluation.class, EpicCoordinator.ChildReceipt.class, EpicCoordinator.Receipt.class, @@ -40,9 +42,11 @@ public final class NativeHints implements RuntimeHintsRegistrar { DiscussionImport.Source.class, DiscussionImport.SourceView.class, DiscussionImport.AgendaView.class, DiscussionImport.Entry.class, DiscussionImport.Report.class, DiscussionImport.ImportedAgenda.class, DiscussionImport.Receipt.class, DiscussionImport.Action.class, - Artifact.class, ValidationReport.class, VerificationService.Context.class, DiscussionService.MigrationReport.class}) { + Artifact.class, ProtocolReceipt.class, ProtocolReceipt.Source.class, ArtifactPublication.Intent.class, + ValidationReport.class, VerificationService.Context.class, DiscussionService.MigrationReport.class}) { hints.reflection().registerType(type, MemberCategory.INVOKE_DECLARED_CONSTRUCTORS, MemberCategory.INVOKE_PUBLIC_METHODS); } hints.resources().registerPattern("protocol/*"); + hints.resources().registerPattern("sqlite/*"); } } diff --git a/src/main/java/net/intrepid/aiengineering/agent/AgentService.java b/src/main/java/net/intrepid/aiengineering/agent/AgentService.java index 42bd80a..393f641 100644 --- a/src/main/java/net/intrepid/aiengineering/agent/AgentService.java +++ b/src/main/java/net/intrepid/aiengineering/agent/AgentService.java @@ -62,7 +62,8 @@ public final class AgentService { /** Source fingerprint excludes run bookkeeping and Work modification time. */ public String fingerprint(AgentContext context) { var w=context.work(); var data=new LinkedHashMap(); - data.put("project",context.project()); data.put("workId",w.id()); data.put("title",w.title()); data.put("description",w.description()); + var project = Documents.jsonTree(context.project()); project.remove("storage"); + data.put("project",project); data.put("workId",w.id()); data.put("title",w.title()); data.put("description",w.description()); if (w.guidance() != null) data.put("guidance", w.guidance()); data.put("goal",w.goal()); data.put("motivation",w.motivation()); data.put("constraints",w.constraints()); data.put("criteria",w.acceptanceCriteria()); data.put("status",w.status()); data.put("archived",w.archived()); data.put("repositories",w.repositories()); @@ -76,7 +77,7 @@ public final class AgentService { public List history(Path root,String work) { var w=works.load(root,work); var all=new ArrayList(); var requests=new HashSet(); for(String id:w.agentRuns()) { - var run=Documents.readMarkdownDocument(path(root,work,id),AgentRun.class,"task"); + var run=RecordStorage.read(path(root,work,id),AgentRun.class,"task"); if(!run.id().equals(id)||!run.workId().equals(work)||!requests.add(run.requestId())) throw ProtocolException.validation("Invalid run identity/request: "+id); for(var reference:run.applied()) { var ids=switch(reference.kind()) {case "topics"->w.topics(); case "surveys"->w.surveys(); case "dispositions"->w.dispositions(); case "decisions"->w.decisions(); default->w.discussions();}; @@ -148,7 +149,7 @@ public final class AgentService { ||output.surveys().stream().flatMap(s->s.questions().stream()).anyMatch(q->q.sources().contains("@request")); } private void write(Path root,AgentRun run,boolean replace) { - var p=path(root,run.workId(),run.id()); Filespace.directory(p.getParent()); Documents.writeMarkdownDocument(p,run,"task",replace); + var p=path(root,run.workId(),run.id()); Filespace.directory(p.getParent()); RecordStorage.write(p,run,AgentRun.class,"task",replace); } public AgentRun run(Path root,String work,String task,String activity,String requester,String requestId) { text(task,"task"); text(requester,"requester"); if(activity!=null) ProjectConfig.identifier(activity); @@ -173,7 +174,8 @@ public final class AgentService { var output=response.proposal(); validate(root,context,output,selected); var provenance=selection.invocation()==null&&response.invocation()==null?null:new AgentRun.Provenance(selection.invocation(),response.invocation()); - return Filespace.locked(root,()->{ + var attempted = new AgentRun[1]; + try { return Filespace.locked(root,()->{ works.editable(root,work); // Another process may have applied the same no-op/summary request without changing semantic sources. for(var old:history(root,work)) if(old.requestId().equals(key)) { @@ -184,6 +186,7 @@ public final class AgentService { new ArtifactService().validate(root,work); validate(root,context,output,selected); String id=works.nextReference(works.load(root,work).agentRuns(),"RUN"), now=Instant.now().toString(); var run=new AgentRun(1,id,work,key,task,activity,selectedActivity,requester,executor,hash,AgentRun.Status.APPLYING,output,List.of(),"",now,now,provenance); + attempted[0] = run; write(root,run,false); works.addReference(root,work,"agentRuns",id); var applied=new ArrayList(); try { String requestSource=null; @@ -215,10 +218,32 @@ public final class AgentService { } var completed=run.finish(AgentRun.Status.COMPLETED,applied,""); write(root,completed,true); works.touched(root,work,completed.updatedAt()); return completed; } catch(RuntimeException failure) { + if (SqliteDatabase.active(root)) throw failure; try { write(root,run.finish(AgentRun.Status.FAILED,applied,failure.getMessage()==null?failure.getClass().getSimpleName():failure.getMessage()),true); } catch(RuntimeException secondary) { failure.addSuppressed(secondary); } throw new ProtocolException(failure instanceof ProtocolException p?p.exitCode():1,"Run "+id+" failed; inspect agent show: "+failure.getMessage()); } - }); + }); } catch (RuntimeException failure) { + if (!SqliteDatabase.active(root) || attempted[0] == null) throw failure; + // The proposal transaction has rolled back. Publish only its diagnostic in a fresh transaction. + AgentRun failed; + try { + failed = Filespace.locked(root, () -> { + works.editable(root, work); + if (history(root, work).stream().anyMatch(old -> old.requestId().equals(key))) + throw ProtocolException.validation("Request already recorded during failure recovery: " + key); + var original = attempted[0]; + String id = works.nextReference(works.load(root, work).agentRuns(), "RUN"); + String diagnostic = failure.getMessage() == null ? failure.getClass().getSimpleName() : failure.getMessage(); + var record = new AgentRun(1, id, work, key, task, activity, selectedActivity, requester, executor, hash, + AgentRun.Status.FAILED, output, List.of(), diagnostic, original.createdAt(), Instant.now().toString(), provenance); + write(root, record, false); works.addReference(root, work, "agentRuns", id); return record; + }); + } catch (RuntimeException diagnosticFailure) { + failure.addSuppressed(diagnosticFailure); throw failure; + } + throw new ProtocolException(failure instanceof ProtocolException p ? p.exitCode() : 1, + "Run " + failed.id() + " rolled back; inspect agent show: " + failure.getMessage()); + } } } diff --git a/src/main/java/net/intrepid/aiengineering/artifact/ArtifactLifecycle.java b/src/main/java/net/intrepid/aiengineering/artifact/ArtifactLifecycle.java new file mode 100644 index 0000000..c76701a --- /dev/null +++ b/src/main/java/net/intrepid/aiengineering/artifact/ArtifactLifecycle.java @@ -0,0 +1,88 @@ +package net.intrepid.aiengineering.artifact; + +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.work.*; +import java.nio.file.*; +import java.time.Instant; + +/** Two-phase retirement: checked facts commit before any external payload is removed. */ +public final class ArtifactLifecycle { + private ArtifactLifecycle() {} + public static String state(Path root, String work, String artifact) { + if (!SqliteDatabase.active(root)) return "RETAINED_LEGACY"; + return SqliteDatabase.read(root, connection -> { + try (var statement = connection.prepareStatement("SELECT state FROM artifact_lifecycle WHERE work_id=? AND artifact_id=?")) { + statement.setString(1, work); statement.setString(2, artifact); + try (var row = statement.executeQuery()) { return row.next() ? row.getString(1) : "RETAINED_LEGACY"; } + } + }); + } + public static int pending(Path root, String work) { + if (!SqliteDatabase.active(root)) return 0; + return SqliteDatabase.read(root, connection -> { + try (var statement = connection.prepareStatement("SELECT count(*) FROM artifact_lifecycle WHERE work_id=? AND state='DISCARD_PENDING'")) { + statement.setString(1, work); + try (var row = statement.executeQuery()) { return row.next() ? row.getInt(1) : 0; } + } + }); + } + static void register(Path root, Artifact artifact, String state) { + SqliteDatabase.write(root, connection -> { + try (var statement = connection.prepareStatement("INSERT INTO artifact_lifecycle(work_id,artifact_id,state,checked_sha256,checked_at) VALUES (?,?,?,?,?)")) { + statement.setString(1, artifact.workId()); statement.setString(2, artifact.id()); statement.setString(3, state); + statement.setString(4, state.equals("STRUCTURED") ? artifact.sha256() : null); + statement.setString(5, state.equals("STRUCTURED") ? Instant.now().toString() : null); statement.executeUpdate(); + } + return null; + }); + } + static void checked(Path root, Artifact artifact) { + SqliteDatabase.read(root, connection -> { + try (var statement = connection.prepareStatement("SELECT checked_sha256,checked_at FROM artifact_lifecycle WHERE work_id=? AND artifact_id=?")) { + statement.setString(1, artifact.workId()); statement.setString(2, artifact.id()); + try (var row = statement.executeQuery()) { + if (!row.next() || !artifact.sha256().equals(row.getString(1)) || row.getString(2) == null) + throw ProtocolException.validation("Missing validated artifact retirement: " + artifact.id()); + Instant.parse(row.getString(2)); + } + } + return null; + }); + } + public static void prepareCompleted(Path root, String work) { + if (!SqliteDatabase.active(root)) return; + if (new WorkService().load(root, work).status() != Work.Status.COMPLETED) throw ProtocolException.validation("Pending Work still needs its evidence"); + var artifacts = new ArtifactService(); artifacts.validate(root, work); + SqliteDatabase.write(root, connection -> { + for (var artifact : artifacts.list(root, work)) if (state(root, work, artifact.id()).equals("AVAILABLE")) { + try (var statement = connection.prepareStatement("UPDATE artifact_lifecycle SET state='DISCARD_PENDING',checked_sha256=?,checked_at=? WHERE work_id=? AND artifact_id=? AND state='AVAILABLE'")) { + statement.setString(1, artifact.sha256()); statement.setString(2, Instant.now().toString()); + statement.setString(3, work); statement.setString(4, artifact.id()); statement.executeUpdate(); + } + } + SqliteDatabase.afterCommit(root, () -> recover(root, work)); return null; + }); + } + public static int recover(Path root, String work) { + if (!SqliteDatabase.active(root)) return 0; + return Filespace.locked(root, () -> { + var artifacts = new ArtifactService(); int count = 0; + for (var artifact : artifacts.list(root, work)) if (state(root, work, artifact.id()).equals("DISCARD_PENDING")) { + checked(root, artifact); + Path path = Filespace.resolve(new WorkService().folder(root, work), artifact.path()); + if (Files.exists(path, LinkOption.NOFOLLOW_LINKS)) { + artifacts.validatePayload(path, artifact); + Filespace.io(() -> { Files.delete(path); return null; }); + } + SqliteDatabase.write(root, connection -> { + try (var statement = connection.prepareStatement("UPDATE artifact_lifecycle SET state='DISCARDED' WHERE work_id=? AND artifact_id=? AND state='DISCARD_PENDING'")) { + statement.setString(1, work); statement.setString(2, artifact.id()); statement.executeUpdate(); + } + return null; + }); + count++; + } + return count; + }); + } +} diff --git a/src/main/java/net/intrepid/aiengineering/artifact/ArtifactPublication.java b/src/main/java/net/intrepid/aiengineering/artifact/ArtifactPublication.java new file mode 100644 index 0000000..0e34130 --- /dev/null +++ b/src/main/java/net/intrepid/aiengineering/artifact/ArtifactPublication.java @@ -0,0 +1,59 @@ +package net.intrepid.aiengineering.artifact; + +import net.intrepid.aiengineering.filesystem.*; +import java.nio.file.*; +import java.util.*; + +/** A tiny temporary intent identifies files owned by an interrupted publication. */ +public final class ArtifactPublication { + private ArtifactPublication() {} + public record Intent(Artifact artifact, String target, String staging) {} + static Path begin(Path root, Artifact artifact, Path target, Path staging) { + if (Files.exists(target, LinkOption.NOFOLLOW_LINKS)) throw ProtocolException.validation("Existing artifact publication requires recovery before retry: " + target); + Path directory = Filespace.resolve(root, ".ai-engineering/.local/artifact-publications"); Filespace.directory(directory); + Path journal = directory.resolve(UUID.randomUUID() + ".json"); + Filespace.write(journal, Documents.json(new Intent(artifact, root.relativize(target).toString(), root.relativize(staging).toString())), false); + SqliteDatabase.afterRollback(root, () -> recoverOne(root, journal)); + SqliteDatabase.afterCommit(root, () -> recoverOne(root, journal)); + return journal; + } + private static void removeOwned(Path directory, Artifact artifact) { + if (!Files.exists(directory, LinkOption.NOFOLLOW_LINKS)) return; + Path payload = Filespace.resolve(directory, "payload"); + try (var files = Filespace.io(() -> Files.list(directory))) { + if (files.anyMatch(file -> !file.getFileName().toString().equals("payload"))) + throw ProtocolException.validation("Unexpected publication residue; inspect " + directory); + } + if (Files.exists(payload, LinkOption.NOFOLLOW_LINKS)) new ArtifactService().validatePayload(payload, artifact); + Filespace.io(() -> { Files.deleteIfExists(payload); Files.delete(directory); return null; }); + } + private static void recoverOne(Path root, Path journal) { + var intent = Documents.readJson(journal, Intent.class); var artifact = intent.artifact(); + Path target = Filespace.resolve(root, intent.target()), staging = Filespace.resolve(root, intent.staging()); + Path parent = target.getParent(); + if (!target.getFileName().toString().equals(artifact.id()) || !parent.endsWith("artifacts/evidence") + || !target.startsWith(root.resolve(".ai-engineering/works")) + || !staging.getParent().equals(parent) || !staging.getFileName().toString().startsWith("." + artifact.id() + "-")) + throw ProtocolException.validation("Invalid artifact publication intent: " + journal); + int current = SqliteRecords.current(root, artifact.workId(), "artifact", artifact.id()); + if (current == 0) removeOwned(target, artifact); + else if (!SqliteRecords.get(root, artifact.workId(), "artifact", artifact.id(), 0, Artifact.class).equals(artifact)) + throw ProtocolException.validation("Publication identity changed; inspect " + journal); + removeOwned(staging, artifact); + Filespace.io(() -> { Files.delete(journal); return null; }); + } + public static int recover(Path root) { + if (!SqliteDatabase.active(root)) return 0; + return Filespace.locked(root, () -> { + Path directory = Filespace.resolve(root, ".ai-engineering/.local/artifact-publications"); + if (!Files.exists(directory)) return 0; + var journals = Filespace.children(directory); + for (Path journal : journals) { + Path safe = Filespace.resolve(directory, journal.getFileName().toString()); + if (!safe.getFileName().toString().matches("[0-9a-f-]{36}\\.json")) throw ProtocolException.validation("Unexpected publication journal: " + journal); + recoverOne(root, safe); + } + return journals.size(); + }); + } +} diff --git a/src/main/java/net/intrepid/aiengineering/artifact/ArtifactService.java b/src/main/java/net/intrepid/aiengineering/artifact/ArtifactService.java index fad120f..c45c11c 100644 --- a/src/main/java/net/intrepid/aiengineering/artifact/ArtifactService.java +++ b/src/main/java/net/intrepid/aiengineering/artifact/ArtifactService.java @@ -12,7 +12,8 @@ public final class ArtifactService { public List list(Path root, String id) { var work = works.load(root, id); Path folder = works.folder(root, id); return work.artifacts().stream().map(ref -> { - var artifact = Documents.read(Filespace.resolve(folder, "artifacts/evidence/" + ref + "/artifact.yaml"), Artifact.class); + var artifact = SqliteDatabase.active(root) ? SqliteRecords.get(root, id, "artifact", ref, 0, Artifact.class) + : Documents.read(Filespace.resolve(folder, "artifacts/evidence/" + ref + "/artifact.yaml"), Artifact.class); if (!artifact.id().equals(ref) || !artifact.workId().equals(id)) throw ProtocolException.validation("Artifact identity mismatch: " + ref); String expected = "artifacts/evidence/" + ref + "/payload"; if (!artifact.path().equals(expected)) throw ProtocolException.validation("Invalid artifact payload reference: " + artifact.path()); @@ -39,26 +40,80 @@ public final class ArtifactService { works.addReference(root, workId, "artifacts", id); return artifact; }); } + /** Internal aggregation facts live in typed columns/rows, with legacy files readable unchanged. */ + public Artifact attachReceipt(Path root, String work, Object receipt, String purpose, String origin, String author) { + if (!SqliteDatabase.active(root)) return attachBytes(root, work, Documents.json(receipt).getBytes(java.nio.charset.StandardCharsets.UTF_8), purpose, origin, author); + return Filespace.locked(root, () -> { + var w = works.editable(root, work); String id = works.nextReference(w.artifacts(), "ART"); + var data = ProtocolReceipt.from(id, work, receipt); + String json = Documents.json(receipt); + if (!Documents.json(data.content()).equals(json)) throw ProtocolException.validation("Unsupported protocol receipt fields"); + byte[] bytes = json.getBytes(java.nio.charset.StandardCharsets.UTF_8); + var artifact = new Artifact(1, id, work, origin, purpose, "artifacts/evidence/" + id + "/payload", hash(bytes), bytes.length, author, Instant.now().toString()); + SqliteRecords.put(root, work, "receipt", id, data, ProtocolReceipt.class, false, 1); + SqliteRecords.put(root, work, "artifact", id, artifact, Artifact.class, false, 1); + ArtifactLifecycle.register(root, artifact, "STRUCTURED"); + works.addReference(root, work, "artifacts", id); return artifact; + }); + } + public T readReceipt(Path root, String work, Artifact artifact, Class type) { + if (!ArtifactLifecycle.state(root, work, artifact.id()).equals("STRUCTURED")) + return Documents.readJson(Filespace.resolve(works.folder(root, work), artifact.path()), type); + String json = receiptJson(root, artifact); + return Documents.parseJson(json, type); + } + private String receiptJson(Path root, Artifact artifact) { + var receipt = SqliteRecords.get(root, artifact.workId(), "receipt", artifact.id(), 0, ProtocolReceipt.class); + String json = Documents.json(receipt.content()); byte[] bytes = json.getBytes(java.nio.charset.StandardCharsets.UTF_8); + if (!hash(bytes).equals(artifact.sha256()) || bytes.length != artifact.size()) throw ProtocolException.validation("Structured receipt integrity mismatch: " + artifact.id()); + ArtifactLifecycle.checked(root, artifact); return json; + } /** Normal evidence format in an unpublished Work folder; caller publishes its Work references. */ public Artifact writePrepared(Path folder, String workId, String id, byte[] content, String purpose, String origin, String author) { Work.identifier(workId, "WRK"); Work.identifier(id, "ART"); byte[] bytes = content.clone(); if (bytes.length > MAX_BYTES) throw ProtocolException.invalid("Evidence exceeds 1 MiB"); Path parent = Filespace.resolve(folder, "artifacts/evidence"); - Path stage = Filespace.resolve(parent, "." + id + "-" + UUID.randomUUID() + ".tmp"); Filespace.directory(stage); + Path stage = Filespace.resolve(parent, "." + id + "-" + UUID.randomUUID() + ".tmp"); var artifact = new Artifact(1, id, workId, origin, purpose, "artifacts/evidence/" + id + "/payload", hash(bytes), bytes.length, author, Instant.now().toString()); + Path sqliteRoot = RecordStorage.sqliteRoot(folder); + if (sqliteRoot != null) ArtifactPublication.begin(sqliteRoot, artifact, Filespace.resolve(parent, id), stage); + Filespace.directory(stage); Filespace.writeBytes(stage.resolve("payload"), bytes, false); - Filespace.write(stage.resolve("artifact.yaml"), Documents.yaml(artifact), false); - Filespace.moveDirectory(stage, Filespace.resolve(parent, id)); return artifact; + if (sqliteRoot == null) Filespace.write(stage.resolve("artifact.yaml"), Documents.yaml(artifact), false); + Filespace.moveDirectory(stage, Filespace.resolve(parent, id)); + if (sqliteRoot != null) { + SqliteRecords.put(sqliteRoot, workId, "artifact", id, artifact, Artifact.class, false, 1); + ArtifactLifecycle.register(sqliteRoot, artifact, origin.startsWith("discussion-framework:") || origin.startsWith("ai-engineering:discussion-import:") ? "RETAINED_LEGACY" : "AVAILABLE"); + } + return artifact; } public void validate(Path root, String id) { for (var artifact : list(root, id)) { Path path = Filespace.resolve(works.folder(root, id), artifact.path()); - if (!Files.isRegularFile(path)) throw ProtocolException.validation("Missing artifact payload: " + artifact.path()); - if (Filespace.io(() -> Files.size(path)) != artifact.size() || artifact.size() > MAX_BYTES) - throw ProtocolException.validation("Artifact size mismatch: " + artifact.id()); - if (!hash(Filespace.io(() -> Files.readAllBytes(path))).equals(artifact.sha256())) - throw ProtocolException.validation("Artifact SHA-256 mismatch: " + artifact.id()); + String state = ArtifactLifecycle.state(root, id, artifact.id()); + if (state.equals("STRUCTURED")) { receiptJson(root, artifact); continue; } + if (state.equals("DISCARDED") || state.equals("DISCARD_PENDING")) { + ArtifactLifecycle.checked(root, artifact); + if (!Files.exists(path, LinkOption.NOFOLLOW_LINKS)) continue; + } + validatePayload(path, artifact); + } + } + void validatePayload(Path path, Artifact artifact) { + if (!Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)) throw ProtocolException.validation("Missing artifact payload: " + artifact.path()); + if (Filespace.io(() -> Files.size(path)) != artifact.size() || artifact.size() > MAX_BYTES) + throw ProtocolException.validation("Artifact size mismatch: " + artifact.id()); + if (!hash(Filespace.io(() -> Files.readAllBytes(path))).equals(artifact.sha256())) + throw ProtocolException.validation("Artifact SHA-256 mismatch: " + artifact.id()); + } + public void requireAvailable(Path root, String work, List evidence) { + var all = list(root, work); + for (String id : evidence) { + var artifact = all.stream().filter(a -> a.id().equals(id)).findFirst().orElseThrow(() -> ProtocolException.invalid("Unknown evidence: " + id)); + if (!List.of("AVAILABLE", "RETAINED_LEGACY").contains(ArtifactLifecycle.state(root, work, id))) + throw ProtocolException.validation("Evidence already retired; attach current inputs for a new evaluation: " + id); + validatePayload(Filespace.resolve(works.folder(root, work), artifact.path()), artifact); } } private static String hash(byte[] bytes) { diff --git a/src/main/java/net/intrepid/aiengineering/artifact/ProtocolReceipt.java b/src/main/java/net/intrepid/aiengineering/artifact/ProtocolReceipt.java new file mode 100644 index 0000000..d4a3c14 --- /dev/null +++ b/src/main/java/net/intrepid/aiengineering/artifact/ProtocolReceipt.java @@ -0,0 +1,52 @@ +package net.intrepid.aiengineering.artifact; + +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.work.Work; +import java.util.*; +import tools.jackson.databind.node.ObjectNode; + +/** Only protocol aggregation facts; never arbitrary JSON/file content. */ +public record ProtocolReceipt(int schemaVersion, String id, String workId, String type, String inputHash, + String policyHash, List sources) { + public record Source(String id, Integer revision, String sha256) { + public Source { + if (revision == null) Work.identifier(id, "WRK"); + else { Work.identifier(id, "PLN"); if (revision < 1) throw ProtocolException.validation("Invalid receipt source revision"); } + digest(sha256); + } + } + private static void digest(String value) { + if (value == null || !value.matches("[a-f0-9]{64}")) throw ProtocolException.validation("Invalid receipt digest"); + } + public ProtocolReceipt { + ProtocolException.schema(schemaVersion); Work.identifier(id, "ART"); Work.identifier(workId, "WRK"); digest(inputHash); + if (!List.of("plans", "epic").contains(type)) throw ProtocolException.validation("Unknown structured receipt type"); + if (type.equals("epic")) digest(policyHash); + else if (policyHash != null) throw ProtocolException.validation("Plan receipt has no EPIC policy"); + sources = List.copyOf(sources); + if (sources.isEmpty() || sources.stream().map(Source::id).distinct().count() != sources.size()) throw ProtocolException.validation("Invalid receipt sources"); + for (var source : sources) if (type.equals("plans") != (source.revision() != null)) throw ProtocolException.validation("Receipt source type mismatch"); + } + public static ProtocolReceipt from(String id, String work, Object value) { + var data = Documents.jsonTree(value); String type = data.has("policyHash") ? "epic" : "plans"; + var sources = new ArrayList(); var array = data.get(type.equals("epic") ? "children" : "plans"); + if (array == null || !array.isArray() || !data.get("workId").stringValue().equals(work)) throw ProtocolException.validation("Invalid structured receipt"); + for (var source : array) sources.add(type.equals("epic") + ? new Source(source.get("workId").stringValue(), null, source.get("completionHash").stringValue()) + : new Source(source.get("id").stringValue(), source.get("revision").intValue(), source.get("sha256").stringValue())); + return new ProtocolReceipt(1, id, work, type, data.get("inputHash").stringValue(), + type.equals("epic") ? data.get("policyHash").stringValue() : null, sources); + } + public ObjectNode content() { + var data = Documents.jsonTree(Map.of()); data.put("schemaVersion", schemaVersion); data.put("workId", workId); + if (type.equals("epic")) data.put("policyHash", policyHash); + data.put("inputHash", inputHash); + var array = data.putArray(type.equals("epic") ? "children" : "plans"); + for (var source : sources) { + var item = array.addObject(); + if (type.equals("epic")) { item.put("workId", source.id()); item.put("completionHash", source.sha256()); } + else { item.put("id", source.id()); item.put("revision", source.revision()); item.put("sha256", source.sha256()); } + } + return data; + } +} diff --git a/src/main/java/net/intrepid/aiengineering/cli/EngineeringCli.java b/src/main/java/net/intrepid/aiengineering/cli/EngineeringCli.java index 2a2ef91..5143bb7 100644 --- a/src/main/java/net/intrepid/aiengineering/cli/EngineeringCli.java +++ b/src/main/java/net/intrepid/aiengineering/cli/EngineeringCli.java @@ -41,7 +41,7 @@ public final class EngineeringCli implements Runnable { .addSubcommand("decision", new DecisionCommands()).addSubcommand("artifact", new ArtifactCommands()) .addSubcommand("plan", new CommandLine(new PlanCommands()).addSubcommand("step", new StepCommands()).addSubcommand("experiment", new ExperimentCommands())) .addSubcommand("topic", new TopicCommands()).addSubcommand("survey", new SurveyCommands()).addSubcommand("agent", new AgentCommands()) - .addSubcommand("epic", new EpicCommands()); + .addSubcommand("epic", new EpicCommands()).addSubcommand("gate", new GateCommands()).addSubcommand("storage", new StorageCommands()); commandLine.addSubcommand("import", new CommandLine(new ImportCommands()).addSubcommand("discussion", new DiscussionImportCommand())); configure(commandLine, out, err); commandLine.setExecutionExceptionHandler((exception, command, parse) -> { @@ -58,10 +58,59 @@ public final class EngineeringCli implements Runnable { @Override public void run() { commandLine.usage(output); } private Path discoveredRoot() { return projects.discover(cwd, project == null ? null : resolve(project)); } private Path root() { - Path root = discoveredRoot(); ProtocolGuide.requireSupportedVersion(root); return root; + Path root = discoveredRoot(); StorageMigration.requireStable(root); ProtocolGuide.requireSupportedVersion(root); return root; } private Path resolve(Path path) { return path.isAbsolute() ? path : cwd.resolve(path); } enum Format { markdown, json } + @Command(name = "storage", mixinStandardHelpOptions = true, description = "Explicit local storage migration and recovery; never installs native tools.") + public class StorageCommands { + @Command(name = "migrate", mixinStandardHelpOptions = true, description = "Preview by default. Apply, recover or roll back using the reviewed fingerprint.") + int migrate(@Option(names = "--apply") boolean apply, @Option(names = "--recover") boolean recover, + @Option(names = "--rollback") boolean rollback, @Option(names = "--expect") String expected, + @Option(names = "--format", defaultValue = "markdown") Format format) { + int actions = (apply ? 1 : 0) + (recover ? 1 : 0) + (rollback ? 1 : 0); + if (actions > 1 || (actions == 0 && expected != null) || (actions == 1 && expected == null)) + throw ProtocolException.invalid("Use preview without flags, or one of --apply/--recover/--rollback with --expect"); + Path root = discoveredRoot(); var migration = new StorageMigration(); + var result = apply ? migration.apply(root, expected) : recover || rollback ? migration.recover(root, expected, rollback) : migration.preview(root); + emit(result, format); return result.valid() ? 0 : 4; + } + } + @Command(name = "gate", mixinStandardHelpOptions = true, description = "Configure required quality checks and record actual external evaluations.") + public class GateCommands { + @Command(name = "configure", mixinStandardHelpOptions = true) + int configureGate(@Parameters(index = "0") String id, + @Option(names = "--work", description = "Additional Work gate; omitted means a required project gate.") String work, + @Option(names = "--title", required = true) String title, + @Option(names = "--procedure", required = true) String procedure, + @Option(names = "--input", required = true, description = "Project-relative file/directory evaluated; repeat for multiple inputs.") List inputs, + @Option(names = "--require-evidence") boolean evidence, + @Option(names = "--by", required = true) String by, + @Option(names = "--format", defaultValue = "markdown") Format format) { + return emit(new QualityGates().configure(root(), work == null ? "project" : work, id, title, procedure, inputs, evidence, by), format); + } + @Command(name = "status", mixinStandardHelpOptions = true) + int gates(@Parameters(index = "0") String work, @Option(names = "--format", defaultValue = "markdown") Format format) { + return emit(new QualityGates().inspect(root(), work), format); + } + @Command(name = "history", mixinStandardHelpOptions = true) + int gateHistory(@Parameters(index = "0") String work, @Option(names = "--format", defaultValue = "markdown") Format format) { + return emit(new QualityGates().history(root(), work), format); + } + @Command(name = "record", mixinStandardHelpOptions = true, description = "Record observed evaluation against the fingerprint obtained before running the check.") + int recordGate(@Parameters(index = "0") String work, @Parameters(index = "1", description = "project/ID or WRK-ID/ID.") String key, + @Option(names = "--expect", required = true) String expected, + @Option(names = "--invocation", required = true) String invocation, + @Option(names = "--outcome", required = true) QualityGates.Outcome outcome, + @Option(names = "--summary", required = true) String summary, + @Option(names = "--evidence") List evidence, + @Option(names = "--by", required = true) String by, + @Option(names = "--observed", description = "Attest this check actually ran; separate from human decision approval.") boolean observed, + @Option(names = "--format", defaultValue = "markdown") Format format) { + var result = new QualityGates().record(root(), work, key, expected, invocation, outcome, summary, safe(evidence), by, observed); + afterChange(work, by); return emit(result, format); + } + } @Command(name = "import", mixinStandardHelpOptions = true, description = "Import supported legacy context with explicit preview and application.") public class ImportCommands implements Runnable { @Override public void run() { commandLine.getSubcommands().get("import").usage(output); } @@ -129,10 +178,13 @@ public final class EngineeringCli implements Runnable { @Option(names = "--name") String name, @Option(names = "--general-adapter", description = "Configure an available adapter without calling it.") String generalAdapter, @Option(names = "--archive-policy", description = "review-only or reversible; requires an executor.") String archivePolicy, + @Option(names = "--storage", defaultValue = "sqlite", description = "sqlite (default), or legacy for compatibility fixtures.") String storage, + @Option(names = "--version-state", description = "Leave Git ignore policy to the developer; does not untrack or change existing rules.") boolean versionState, @Option(names = "--interactive", description = "Guide project and executor setup before writing files.") boolean interactive, @Option(names = "--input-file", description = "Explicit UTF-8 answers for guided setup.") Path inputFile) { if (project != null && directory != null) throw ProtocolException.invalid("Use a project directory or --project, not both"); Path target = project != null ? resolve(project) : directory != null ? resolve(directory) : cwd; + if (!List.of("sqlite", "legacy").contains(storage)) throw ProtocolException.invalid("Storage must be sqlite or legacy"); boolean guided = interactive || inputFile != null || (name == null && (injectedInput || System.console() != null)); if (guided) { if (generalAdapter != null) throw ProtocolException.invalid("Use guided setup or --general-adapter, not both"); @@ -140,7 +192,7 @@ public final class EngineeringCli implements Runnable { var reader = inputFile == null ? input : new java.io.StringReader(readDiscussionText(resolve(inputFile))); Path filename = target.toAbsolutePath().normalize().getFileName(); var setup = new ProjectSetup(reader, output).collect(name, filename == null ? "Engineering Project" : filename.toString(), archivePolicy); - var initialized = projects.initialize(target, setup.name()); + var initialized = storage.equals("legacy") ? projects.initializeLegacy(target, setup.name()) : projects.initializeSqlite(target, setup.name(), !versionState); if (setup.agents() == null) return emit(initialized, Format.markdown); return emit(projects.configureAgents(projects.discover(target, null), setup.agents()), Format.markdown); } @@ -150,7 +202,7 @@ public final class EngineeringCli implements Runnable { if (new AgentService().available().stream().noneMatch(a -> a.id().equals(generalAdapter))) throw ProtocolException.invalid("Unknown adapter: " + generalAdapter); new ProjectConfig.Agents(new ProjectConfig.Executor(generalAdapter,"general","default"), java.util.Map.of(), archivePolicy == null ? "review-only" : archivePolicy); } - var initialized = projects.initialize(target, name); + var initialized = storage.equals("legacy") ? projects.initializeLegacy(target, name) : projects.initializeSqlite(target, name, !versionState); if (generalAdapter != null) return emit(new AgentService().configure(projects.discover(target, null), "general", generalAdapter, null, null, archivePolicy), Format.markdown); return emit(initialized, Format.markdown); } @@ -687,6 +739,12 @@ public final class EngineeringCli implements Runnable { } @Command(name = "artifact", mixinStandardHelpOptions = true, description = "Attach small evidence files with integrity metadata.") public class ArtifactCommands { + @Command(name = "recover", mixinStandardHelpOptions = true, description = "Recover interrupted temporary publications and retirements; never remove requested outputs.") + int recoverArtifacts(@Parameters(index = "0") String work, @Option(names = "--format", defaultValue = "markdown") Format format) { + Path root = root(); works.load(root, work); + int publications = ArtifactPublication.recover(root), retired = ArtifactLifecycle.recover(root, work); + return emit(java.util.Map.of("publicationsRecovered", publications, "temporaryPayloadsRetired", retired), format); + } @Command(name = "add", mixinStandardHelpOptions = true) int add(@Parameters(index = "0") String id, @Option(names = "--file", required = true) Path file, @Option(names = "--purpose", required = true) String purpose, @Option(names = "--origin") String origin, diff --git a/src/main/java/net/intrepid/aiengineering/decision/DecisionService.java b/src/main/java/net/intrepid/aiengineering/decision/DecisionService.java index 08d8075..167f0d4 100644 --- a/src/main/java/net/intrepid/aiengineering/decision/DecisionService.java +++ b/src/main/java/net/intrepid/aiengineering/decision/DecisionService.java @@ -9,7 +9,7 @@ import java.util.*; public final class DecisionService { private final WorkService works = new WorkService(); private Path path(Path root, String workId, String id) { Work.identifier(id, "DEC"); return Filespace.resolve(works.folder(root, workId), "decisions/" + id + ".md"); } - private Decision read(Path path) { return Documents.readMarkdownDocument(path, Decision.class, "text"); } + private Decision read(Path path) { return RecordStorage.read(path, Decision.class, "text"); } public List list(Path root, String workId) { var work = works.load(root, workId); return work.decisions().stream().map(id -> { @@ -23,7 +23,7 @@ public final class DecisionService { private List chain(Path root, Decision current) { var history = new ArrayList(); history.add(current); var next = current; Path folder = works.folder(root, current.workId()); for (int revision = current.revision() - 1; revision >= 1; revision--) { - Path path = Revisions.history(folder, "decisions", current.id(), revision); String original = Filespace.read(path); + Path path = Revisions.history(folder, "decisions", current.id(), revision); String original = RecordStorage.raw(path, Decision.class, "text"); Revisions.chain(next.revision(), next.previousHash(), revision + 1, original); var prior = read(path); identity(prior, current.workId(), current.id()); if (prior.revision() != revision) throw ProtocolException.validation("Invalid decision history revision: " + path); @@ -45,7 +45,7 @@ public final class DecisionService { if (work.guidance() != null) work.guidance().requireDecisionRequest(id); var decision = new Decision(1, id, workId, title, context, approach, List.of(), rationale, List.of(), List.of(), Decision.Status.DRAFT, author, now, evidence, text, 1, null, now, author, "Draft created", List.of(), null, null); - Documents.writeMarkdownDocument(path(root, workId, id), decision, "text", false); works.addReference(root, workId, "decisions", id); return decision; + RecordStorage.write(path(root, workId, id), decision, Decision.class, "text", false); works.addReference(root, workId, "decisions", id); return decision; }); } private void evidence(Work work, List references) { @@ -53,24 +53,24 @@ public final class DecisionService { } private Decision publish(Path root, Decision old, Decision changed, String original) { if (changed.equals(old)) return old; - Revisions.replace(works.folder(root, old.workId()), "decisions", old.id(), old.revision(), original, Documents.markdownDocument(changed, "text")); + RecordStorage.replaceRevision(works.folder(root, old.workId()), "decisions", old.id(), old.revision(), original, Documents.markdownDocument(changed, "text"), Decision.class, "text"); works.touched(root, old.workId(), changed.updatedAt()); return changed; } public Decision update(Path root, String workId, String id, Decision.Update value, String by, String reason) { return Filespace.locked(root, () -> { - var work = works.editable(root, workId); var old = get(root, workId, id); String original = Filespace.read(path(root, workId, id)); + var work = works.editable(root, workId); var old = get(root, workId, id); String original = RecordStorage.raw(path(root, workId, id), Decision.class, "text"); var changed = old.update(value, by, reason, Revisions.hash(original)); evidence(work, changed.evidence()); return publish(root, old, changed, original); }); } public Decision accept(Path root, String workId, String id, String by, String reason, boolean humanApproved) { return Filespace.locked(root, () -> { - works.editable(root, workId); var old = get(root, workId, id); String original = Filespace.read(path(root, workId, id)); + works.editable(root, workId); var old = get(root, workId, id); String original = RecordStorage.raw(path(root, workId, id), Decision.class, "text"); var accepted = old.accept(by, reason, humanApproved, Revisions.hash(original)); Decision parent = null; String parentOriginal = null; if (old.revises() != null) { parent = get(root, workId, old.revises()); if (parent.approvalStatus() != Decision.Status.ACCEPTED && parent.approvalStatus() != Decision.Status.REJECTED) throw ProtocolException.invalid("The revised decision has already been superseded"); - parentOriginal = Filespace.read(path(root, workId, parent.id())); + parentOriginal = RecordStorage.raw(path(root, workId, parent.id()), Decision.class, "text"); } publish(root, old, accepted, original); if (parent != null && parent.approvalStatus() == Decision.Status.ACCEPTED) @@ -87,10 +87,14 @@ public final class DecisionService { public void publish(Path folder) { for (var change : changes) { attempted.add(change); - Revisions.replace(folder, "decisions", change.old().id(), change.old().revision(), change.original(), change.replacement()); + RecordStorage.replaceRevision(folder, "decisions", change.old().id(), change.old().revision(), change.original(), change.replacement(), Decision.class, "text"); } } public void rollback() { + if (!changes.isEmpty()) { + Path root = RecordStorage.sqliteRoot(changes.getFirst().current()); + if (root != null) { SqliteDatabase.rollbackOnly(root); return; } + } for (var change : attempted.reversed()) { String current = Filespace.read(change.current()); if (!current.equals(change.original()) && !current.equals(change.replacement())) @@ -119,7 +123,7 @@ public final class DecisionService { if (!work.guidance().waived()) throw ProtocolException.invalid("Human approval is required for " + old.id() + "; creating a Plan cannot bypass it"); } evidence(work, old.evidence()); - String original = Filespace.read(path(root, workId, old.id())); originals.put(old.id(), original); + String original = RecordStorage.raw(path(root, workId, old.id()), Decision.class, "text"); originals.put(old.id(), original); proposed.put(old.id(), old.acceptForPlan(plan, requester, Revisions.hash(original))); if (old.revises() != null) { var parent = get(root, workId, old.revises()); @@ -127,7 +131,7 @@ public final class DecisionService { throw ProtocolException.invalid("The revised decision has already been superseded"); if (parent.approvalStatus() == Decision.Status.ACCEPTED) { if (proposed.containsKey(parent.id())) throw ProtocolException.invalid("Conflicting decision replacements in Plan: " + parent.id()); - String parentOriginal = Filespace.read(path(root, workId, parent.id())); originals.put(parent.id(), parentOriginal); + String parentOriginal = RecordStorage.raw(path(root, workId, parent.id()), Decision.class, "text"); originals.put(parent.id(), parentOriginal); proposed.put(parent.id(), parent.supersedeForPlan(old.id(), plan, requester, Revisions.hash(parentOriginal))); } } @@ -140,14 +144,14 @@ public final class DecisionService { var old = get(root, workId, next.id()); String original = originals.get(next.id()); Path current = path(root, workId, old.id()), history = Revisions.history(folder, "decisions", old.id(), old.revision()); boolean exists = Files.exists(history); - if (exists && !Filespace.read(history).equals(original)) throw ProtocolException.validation("Conflicting revision history: " + history); + if (exists && !RecordStorage.raw(history, Decision.class, "text").equals(original)) throw ProtocolException.validation("Conflicting revision history: " + history); changes.add(new PlanChange(old, next, original, Documents.markdownDocument(next, "text"), current, history, exists)); } return new PlanAcceptance(changes); } public Decision reject(Path root, String workId, String id, String by, String reason) { return Filespace.locked(root, () -> { - works.editable(root, workId); var old = get(root, workId, id); String original = Filespace.read(path(root, workId, id)); + works.editable(root, workId); var old = get(root, workId, id); String original = RecordStorage.raw(path(root, workId, id), Decision.class, "text"); return publish(root, old, old.reject(by, reason, Revisions.hash(original)), original); }); } @@ -161,7 +165,7 @@ public final class DecisionService { if (work.guidance() != null) work.guidance().requireDecisionRequest(next); var draft = new Decision(1, next, workId, old.title(), old.context(), old.approach(), old.alternatives(), old.rationale(), old.risks(), old.acceptanceCriteria(), Decision.Status.DRAFT, by, now, old.evidence(), old.text(), 1, null, now, by, reason, List.of(), id, null); - Documents.writeMarkdownDocument(path(root, workId, next), draft, "text", false); works.addReference(root, workId, "decisions", next); return draft; + RecordStorage.write(path(root, workId, next), draft, Decision.class, "text", false); works.addReference(root, workId, "decisions", next); return draft; }); } } diff --git a/src/main/java/net/intrepid/aiengineering/discussion/DiscussionService.java b/src/main/java/net/intrepid/aiengineering/discussion/DiscussionService.java index 3b867c4..5c1f2c8 100644 --- a/src/main/java/net/intrepid/aiengineering/discussion/DiscussionService.java +++ b/src/main/java/net/intrepid/aiengineering/discussion/DiscussionService.java @@ -18,7 +18,7 @@ public final class DiscussionService { public List list(Path root, String id) { Work work = works.load(root, id); Path folder = works.folder(root, id); return work.discussions().stream().map(ref -> { - var entry = Documents.readMarkdownDocument(Filespace.resolve(folder, "discussions/" + ref + ".md"), DiscussionEntry.class, "text"); + var entry = RecordStorage.read(Filespace.resolve(folder, "discussions/" + ref + ".md"), DiscussionEntry.class, "text"); if (!entry.id().equals(ref) || !entry.workId().equals(id)) throw ProtocolException.validation("Discussion identity mismatch: " + ref); return entry; }).toList(); @@ -38,7 +38,7 @@ public final class DiscussionService { public DiscussionEntry writePrepared(Path folder, String workId, String id, String text, DiscussionEntry.Kind kind, String author, String discussionId, String respondsTo) { var entry = new DiscussionEntry(1, id, workId, discussionId, kind, author, Instant.now().toString(), respondsTo, text); - Documents.writeMarkdownDocument(Filespace.resolve(folder, "discussions/" + id + ".md"), entry, "text", false); return entry; + RecordStorage.write(Filespace.resolve(folder, "discussions/" + id + ".md"), entry, DiscussionEntry.class, "text", false); return entry; } public record MigrationReport(int schemaVersion, int converted, int unchanged, List backups) { public MigrationReport { backups = List.copyOf(backups); } @@ -46,6 +46,7 @@ public final class DiscussionService { private record Conversion(Path path, String original, String converted) {} /** Explicit formatting migration, preserving semantic history and Work modification timestamps. */ public MigrationReport migrate(Path root, String workId) { + if (SqliteDatabase.active(root)) return new MigrationReport(1, 0, list(root, workId).size(), List.of()); return Filespace.locked(root, () -> { var entries = list(root, workId); var conversions = new java.util.ArrayList(); Path folder = works.folder(root, workId); diff --git a/src/main/java/net/intrepid/aiengineering/discussion/DispositionService.java b/src/main/java/net/intrepid/aiengineering/discussion/DispositionService.java index d0ee30e..64289ff 100644 --- a/src/main/java/net/intrepid/aiengineering/discussion/DispositionService.java +++ b/src/main/java/net/intrepid/aiengineering/discussion/DispositionService.java @@ -17,7 +17,7 @@ public final class DispositionService { var w=works.load(root,work); var result=new ArrayList(); var archived=new HashSet(); var entries=new DiscussionService().list(root,work); for(String id:w.dispositions()) { - var d=Documents.readMarkdownDocument(Filespace.resolve(works.folder(root,work),"dispositions/"+id+".md"),Disposition.class,"reason"); + var d=RecordStorage.read(Filespace.resolve(works.folder(root,work),"dispositions/"+id+".md"),Disposition.class,"reason"); if(!id.equals(d.id())||!work.equals(d.workId())||!w.discussions().contains(d.entryId())||!w.artifacts().containsAll(d.evidence())) throw ProtocolException.validation("Invalid disposition references: "+id); if(entries.stream().noneMatch(e->e.id().equals(d.entryId())&&eligible(e))) throw ProtocolException.validation("Invalid disposition target: "+id); boolean changed=d.action()==Disposition.Action.ARCHIVE?archived.add(d.entryId()):archived.remove(d.entryId()); @@ -38,6 +38,7 @@ public final class DispositionService { if(config==null||!config.archivePolicy().equals("reversible")) throw ProtocolException.invalid("Archive policy is review-only; configure reversible explicitly"); if(evidence.isEmpty()) throw ProtocolException.invalid("Archive requires evidence"); new ArtifactService().validate(root,work); + new ArtifactService().requireAvailable(root,work,evidence); } if(archived(root,work,entry)==(action==Disposition.Action.ARCHIVE)) throw ProtocolException.invalid("Proposal is already in the requested state"); } @@ -46,7 +47,7 @@ public final class DispositionService { var w=works.editable(root,work); check(root,work,entry,action,evidence); var d=new Disposition(1,works.nextReference(w.dispositions(),"DSP"),work,entry,action,reason,evidence,by,Instant.now().toString()); var p=Filespace.resolve(works.folder(root,work),"dispositions/"+d.id()+".md"); Filespace.directory(p.getParent()); - Documents.writeMarkdownDocument(p,d,"reason",false); works.addReference(root,work,"dispositions",d.id()); return d; + RecordStorage.write(p,d,Disposition.class,"reason",false); works.addReference(root,work,"dispositions",d.id()); return d; }); } } diff --git a/src/main/java/net/intrepid/aiengineering/discussion/SurveyService.java b/src/main/java/net/intrepid/aiengineering/discussion/SurveyService.java index 79e72f5..4668451 100644 --- a/src/main/java/net/intrepid/aiengineering/discussion/SurveyService.java +++ b/src/main/java/net/intrepid/aiengineering/discussion/SurveyService.java @@ -9,7 +9,7 @@ import java.util.*; public final class SurveyService { private final WorkService works = new WorkService(); private Path path(Path root, String work, String id) { Work.identifier(id, "SVY"); return Filespace.resolve(works.folder(root, work), "surveys/" + id + ".md"); } - private Survey read(Path path) { return Documents.readMarkdownDocument(path, Survey.class, "description"); } + private Survey read(Path path) { return RecordStorage.read(path, Survey.class, "description"); } private void identity(Survey value, String work, String id) { if (!value.id().equals(id) || !value.workId().equals(work)) throw ProtocolException.validation("Survey identity mismatch: " + id); } @@ -30,7 +30,7 @@ public final class SurveyService { private List chain(Path root, Survey current) { var all = new ArrayList(); all.add(current); var next = current; for (int revision = current.revision() - 1; revision >= 1; revision--) { - Path p = Revisions.history(works.folder(root, current.workId()), "surveys", current.id(), revision); String raw = Filespace.read(p); + Path p = Revisions.history(works.folder(root, current.workId()), "surveys", current.id(), revision); String raw = RecordStorage.raw(p, Survey.class, "description"); Revisions.chain(next.revision(), next.previousHash(), revision + 1, raw); var previous = read(p); identity(previous, current.workId(), current.id()); if (previous.revision() != revision) throw ProtocolException.validation("Invalid survey history revision"); @@ -43,12 +43,12 @@ public final class SurveyService { return Filespace.locked(root, () -> { var w = works.editable(root, work); String id = works.nextReference(w.surveys(), "SVY"), now = Instant.now().toString(); var survey = new Survey(1, id, work, title, description, List.of(), List.of(), author, now, 1, null, now, author, "Survey created"); - var p = path(root, work, id); Filespace.directory(p.getParent()); Documents.writeMarkdownDocument(p, survey, "description", false); + var p = path(root, work, id); Filespace.directory(p.getParent()); RecordStorage.write(p, survey, Survey.class, "description", false); works.addReference(root, work, "surveys", id); return survey; }); } private Survey publish(Path root, Survey old, Survey changed, String raw) { - Revisions.replace(works.folder(root, old.workId()), "surveys", old.id(), old.revision(), raw, Documents.markdownDocument(changed, "description")); + RecordStorage.replaceRevision(works.folder(root, old.workId()), "surveys", old.id(), old.revision(), raw, Documents.markdownDocument(changed, "description"), Survey.class, "description"); works.touched(root, old.workId(), changed.updatedAt()); return changed; } public Survey question(Path root, String work, String id, String topic, String text, List options, @@ -58,7 +58,7 @@ public final class SurveyService { if (!w.discussions().containsAll(sources)) throw ProtocolException.invalid("Unknown question source"); var choices = new ArrayList(); for (int i=0;i(old.questions()); questions.add(question); String raw = Filespace.read(path(root, work, id)); + var questions = new ArrayList<>(old.questions()); questions.add(question); String raw = RecordStorage.raw(path(root, work, id), Survey.class, "description"); return publish(root, old, old.changed(questions, old.answers(), by, "Question added", Revisions.hash(raw)), raw); }); } @@ -69,7 +69,7 @@ public final class SurveyService { var latest = old.latest(questionId); var answer = new Survey.Answer(works.nextReference(old.answers().stream().map(Survey.Answer::id).toList(), "ANS"), questionId, choices, text == null ? "" : text, author, Instant.now().toString(), latest == null ? null : latest.id()); - var answers = new ArrayList<>(old.answers()); answers.add(answer); String raw = Filespace.read(path(root, work, id)); + var answers = new ArrayList<>(old.answers()); answers.add(answer); String raw = RecordStorage.raw(path(root, work, id), Survey.class, "description"); return publish(root, old, old.changed(old.questions(), answers, author, latest == null ? "Answer recorded" : "Answer revised; related conclusions may need review", Revisions.hash(raw)), raw); }); } diff --git a/src/main/java/net/intrepid/aiengineering/discussion/TopicService.java b/src/main/java/net/intrepid/aiengineering/discussion/TopicService.java index 0f7a74b..217372b 100644 --- a/src/main/java/net/intrepid/aiengineering/discussion/TopicService.java +++ b/src/main/java/net/intrepid/aiengineering/discussion/TopicService.java @@ -12,7 +12,7 @@ public final class TopicService { public View { sources = List.copyOf(sources); } } private Path path(Path root, String work, String id) { Work.identifier(id, "TOP"); return Filespace.resolve(works.folder(root, work), "topics/" + id + ".md"); } - private Topic read(Path path) { return Documents.readMarkdownDocument(path, Topic.class, "description"); } + private Topic read(Path path) { return RecordStorage.read(path, Topic.class, "description"); } private void identity(Topic t, String work, String id) { if (!t.workId().equals(work) || !t.id().equals(id)) throw ProtocolException.validation("Topic identity mismatch: " + id); } @@ -45,7 +45,7 @@ public final class TopicService { private List chain(Path root, Topic current) { var all = new ArrayList(); all.add(current); var next = current; for (int revision = current.revision() - 1; revision >= 1; revision--) { - var p = Revisions.history(works.folder(root, current.workId()), "topics", current.id(), revision); String raw = Filespace.read(p); + var p = Revisions.history(works.folder(root, current.workId()), "topics", current.id(), revision); String raw = RecordStorage.raw(p, Topic.class, "description"); Revisions.chain(next.revision(), next.previousHash(), revision + 1, raw); var previous = read(p); identity(previous, current.workId(), current.id()); if (previous.revision() != revision) throw ProtocolException.validation("Invalid topic history revision"); @@ -59,19 +59,19 @@ public final class TopicService { if (!w.discussions().containsAll(sources)) throw ProtocolException.invalid("Unknown topic source"); String id = works.nextReference(w.topics(), "TOP"), now = Instant.now().toString(); var topic = new Topic(1, id, work, title, description, sources, author, now, 1, null, now, author, "Topic created"); - var p = path(root, work, id); Filespace.directory(p.getParent()); Documents.writeMarkdownDocument(p, topic, "description", false); + var p = path(root, work, id); Filespace.directory(p.getParent()); RecordStorage.write(p, topic, Topic.class, "description", false); works.addReference(root, work, "topics", id); return topic; }); } public Topic update(Path root, String work, String id, String title, String description, String by, String reason) { if (title == null && description == null) throw ProtocolException.invalid("Specify a topic field to update"); return Filespace.locked(root, () -> { - works.editable(root, work); var old = get(root, work, id); String raw = Filespace.read(path(root, work, id)); + works.editable(root, work); var old = get(root, work, id); String raw = RecordStorage.raw(path(root, work, id), Topic.class, "description"); String nextTitle = title == null ? old.title() : title, nextDescription = description == null ? old.description() : description; if (nextTitle.equals(old.title()) && nextDescription.equals(old.description())) return old; var changed = new Topic(1, id, work, nextTitle, nextDescription, old.sources(), old.author(), old.createdAt(), old.revision() + 1, Revisions.hash(raw), Instant.now().toString(), by, reason); - Revisions.replace(works.folder(root, work), "topics", id, old.revision(), raw, Documents.markdownDocument(changed, "description")); + RecordStorage.replaceRevision(works.folder(root, work), "topics", id, old.revision(), raw, Documents.markdownDocument(changed, "description"), Topic.class, "description"); works.touched(root, work, changed.updatedAt()); return changed; }); } diff --git a/src/main/java/net/intrepid/aiengineering/filesystem/Documents.java b/src/main/java/net/intrepid/aiengineering/filesystem/Documents.java index 0e702f8..76abc7e 100644 --- a/src/main/java/net/intrepid/aiengineering/filesystem/Documents.java +++ b/src/main/java/net/intrepid/aiengineering/filesystem/Documents.java @@ -21,6 +21,11 @@ public final class Documents { private Documents() {} public static String yaml(Object value) { return YAML.writeValueAsString(value); } public static String json(Object value) { return JSON.writerWithDefaultPrettyPrinter().writeValueAsString(value) + "\n"; } + public static ObjectNode jsonTree(Object value) { return JSON.valueToTree(value); } + public static T jsonValue(ObjectNode value, Class type) { + try { return JSON.treeToValue(value, type); } + catch (RuntimeException e) { throw ProtocolException.validation("Invalid " + type.getSimpleName() + ": " + e.getMessage()); } + } public static T parse(String yaml, Class type) { try { return YAML.readValue(yaml, type); } catch (RuntimeException e) { throw ProtocolException.validation("Invalid " + type.getSimpleName() + ": " + e.getMessage()); } @@ -39,7 +44,13 @@ public final class Documents { } /** Version 1 keeps prose in YAML; version 2 maps the Markdown body to one explicit text field. */ public static T readMarkdownDocument(Path path, Class type, String bodyField) { - var parts = parts(path); + return parseMarkdownDocument(Filespace.read(path), type, bodyField, path); + } + public static T parseMarkdownDocument(String content, Class type, String bodyField) { + return parseMarkdownDocument(content, type, bodyField, Path.of("captured-record.md")); + } + private static T parseMarkdownDocument(String content, Class type, String bodyField, Path path) { + var parts = parts(content, path.toString()); int version = version(parts.metadata(), path); parts.metadata().remove("documentVersion"); if (version == 2) { diff --git a/src/main/java/net/intrepid/aiengineering/filesystem/Filespace.java b/src/main/java/net/intrepid/aiengineering/filesystem/Filespace.java index 4acaaa6..d671164 100644 --- a/src/main/java/net/intrepid/aiengineering/filesystem/Filespace.java +++ b/src/main/java/net/intrepid/aiengineering/filesystem/Filespace.java @@ -66,11 +66,28 @@ public final class Filespace { }); } public static T locked(Path projectRoot, Supplier operation) { + boolean sqlite = SqliteDatabase.active(projectRoot); + String transition = transition(projectRoot); + return lockedFile(projectRoot, () -> { + if (sqlite != SqliteDatabase.active(projectRoot) || !transition.equals(transition(projectRoot))) + throw ProtocolException.validation("Project storage changed while waiting; inspect migration and retry the command"); + return sqlite ? SqliteDatabase.write(projectRoot, connection -> operation.get()) : operation.get(); + }, sqlite); + } + private static String transition(Path root) { + Path journal = resolve(root, ".ai-engineering/.local/sqlite-migration/state.json"); + return Files.exists(journal) ? read(journal) : ""; + } + /** Explicit bootstrap/migration lock, also usable before a database becomes authoritative. */ + public static T lockedLegacy(Path projectRoot, Supplier operation) { + return lockedFile(projectRoot, operation, false); + } + private static T lockedFile(Path projectRoot, Supplier operation, boolean bounded) { Path lock = resolve(projectRoot, ".ai-engineering/.local/write.lock"); if (HELD.get().contains(lock)) return operation.get(); directory(lock.getParent()); return io(() -> { - try (var channel = FileChannel.open(lock, CREATE, WRITE, NOFOLLOW_LINKS); var ignored = channel.lock()) { + try (var channel = FileChannel.open(lock, CREATE, WRITE, NOFOLLOW_LINKS); var ignored = acquire(channel, bounded)) { HELD.get().add(lock); try { return operation.get(); } finally { HELD.get().remove(lock); if (HELD.get().isEmpty()) HELD.remove(); } @@ -79,6 +96,17 @@ public final class Filespace { } }); } + private static java.nio.channels.FileLock acquire(FileChannel channel, boolean bounded) throws IOException { + if (!bounded) return channel.lock(); + long deadline = System.nanoTime() + SqliteDatabase.DEFAULT_BUSY_MILLIS * 1_000_000L; + do { + try { var lock = channel.tryLock(); if (lock != null) return lock; } + catch (java.nio.channels.OverlappingFileLockException busy) { /* Another local command is publishing. */ } + try { Thread.sleep(10); } + catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); throw ProtocolException.validation("Interrupted while waiting for the storage publication lock"); } + } while (System.nanoTime() < deadline); + throw ProtocolException.validation("Project storage publication is busy after a wait limited to " + SqliteDatabase.DEFAULT_BUSY_MILLIS + " ms; retry after migration or the other command finishes"); + } public static void moveDirectory(Path from, Path to) { io(() -> { if (Files.exists(to, NOFOLLOW_LINKS)) throw ProtocolException.invalid("Already exists: " + to); diff --git a/src/main/java/net/intrepid/aiengineering/filesystem/RecordStorage.java b/src/main/java/net/intrepid/aiengineering/filesystem/RecordStorage.java new file mode 100644 index 0000000..e97f797 --- /dev/null +++ b/src/main/java/net/intrepid/aiengineering/filesystem/RecordStorage.java @@ -0,0 +1,92 @@ +package net.intrepid.aiengineering.filesystem; + +import java.nio.file.Path; +import java.util.*; +import java.util.regex.Pattern; + +/** Explicit domain record adapter. File serialization remains the legacy/bootstrap codec. */ +public final class RecordStorage { + private RecordStorage() {} + private record Key(Path root, String work, String kind, String id, int revision) {} + private static final Pattern WORK_FOLDER = Pattern.compile("(WRK-[0-9A-F]{4,9})-.+"); + private static final Map AREAS = Map.of("discussions", "discussion", "topics", "topic", + "surveys", "survey", "dispositions", "disposition", "decisions", "decision", "plans", "plan", + "epic", "epic", "agent-runs", "run"); + public static Path sqliteRoot(Path inside) { + for (Path current = inside.toAbsolutePath().normalize(); current != null; current = current.getParent()) + if (current.getFileName() != null && current.getFileName().toString().equals(".ai-engineering")) + return SqliteDatabase.active(current.getParent()) ? current.getParent() : null; + return null; + } + + private static Key key(Path path) { + Path absolute = path.toAbsolutePath().normalize(); + Path workspace = absolute.getParent(); + while (workspace != null && (workspace.getFileName() == null || !workspace.getFileName().toString().equals(".ai-engineering"))) workspace = workspace.getParent(); + if (workspace == null) return null; + Path root = workspace.getParent(); + Path relative = workspace.relativize(absolute); + if (relative.getNameCount() < 3 || !relative.getName(0).toString().equals("works") || !SqliteDatabase.active(root)) return null; + var match = WORK_FOLDER.matcher(relative.getName(1).toString()); + if (!match.matches()) return null; + String work = match.group(1), kind, id; int revision = 0; + if (relative.getNameCount() == 3 && relative.getName(2).toString().equals("work.md")) { kind = "work"; id = work; } + else if (relative.getNameCount() == 4 && AREAS.containsKey(relative.getName(2).toString())) { + kind = AREAS.get(relative.getName(2).toString()); id = relative.getFileName().toString().replaceFirst("\\.md$", ""); + } else if (relative.getNameCount() == 6 && AREAS.containsKey(relative.getName(2).toString()) + && relative.getName(3).toString().equals(".history") && relative.getFileName().toString().matches("r[0-9]{4,9}\\.md")) { + kind = AREAS.get(relative.getName(2).toString()); id = relative.getName(4).toString(); + revision = Integer.parseInt(relative.getFileName().toString().substring(1).replace(".md", "")); + } else return null; + String folder = SqliteDatabase.read(root, connection -> { + try (var statement = connection.prepareStatement("SELECT folder FROM work_location WHERE work_id=?")) { + statement.setString(1, work); + try (var rows = statement.executeQuery()) { + if (!rows.next()) throw ProtocolException.missing("Work location not found: " + work); + return rows.getString(1); + } + } + }); + if (!folder.equals(relative.getName(1).toString())) throw ProtocolException.validation("Work directory/identity mismatch: " + path); + return new Key(root, work, kind, id, revision); + } + + public static T read(Path path, Class type, String bodyField) { + var key = key(path); + return key == null ? Documents.readMarkdownDocument(path, type, bodyField) + : SqliteRecords.get(key.root(), key.work(), key.kind(), key.id(), key.revision(), type); + } + public static void write(Path path, T value, Class type, String bodyField, boolean replace) { + var key = key(path); + if (key == null) { + if (bodyField == null) Documents.writeDocument(path, value, replace); + else Documents.writeMarkdownDocument(path, value, bodyField, replace); + } else SqliteRecords.put(key.root(), key.work(), key.kind(), key.id(), value, type, replace, bodyField == null ? 1 : 2); + } + public static String raw(Path path, Class type, String bodyField) { + var key = key(path); + return key == null ? Filespace.read(path) + : SqliteRecords.raw(key.root(), key.work(), key.kind(), key.id(), key.revision(), type, bodyField); + } + public static void frontMatter(Path path, T value, Class type) { + if (key(path) == null) Documents.replaceFrontMatter(path, value); + else write(path, value, type, null, true); + } + public static void replaceRevision(Path folder, String area, String id, int revision, + String original, String replacement, Class type, String bodyField) { + Path current = Filespace.resolve(folder, area + "/" + id + ".md"); + var key = key(current); + if (key == null) { Revisions.replace(folder, area, id, revision, original, replacement); return; } + SqliteDatabase.write(key.root(), connection -> { + if (SqliteRecords.current(key.root(), key.work(), key.kind(), id) != revision + || !raw(current, type, bodyField).equals(original)) throw ProtocolException.validation("Concurrent record edit: " + id); + T changed = Documents.parseMarkdownDocument(replacement, type, bodyField); + var tree = Documents.jsonTree(changed); + if (tree.get("revision").intValue() != revision + 1) throw ProtocolException.validation("Invalid replacement revision: " + id); + var metadata = Documents.metadataText(replacement); + int version = metadata.has("documentVersion") ? metadata.get("documentVersion").intValue() : 1; + SqliteRecords.put(key.root(), key.work(), key.kind(), id, changed, type, true, version); + return null; + }); + } +} diff --git a/src/main/java/net/intrepid/aiengineering/filesystem/SqliteDatabase.java b/src/main/java/net/intrepid/aiengineering/filesystem/SqliteDatabase.java new file mode 100644 index 0000000..fe36ccb --- /dev/null +++ b/src/main/java/net/intrepid/aiengineering/filesystem/SqliteDatabase.java @@ -0,0 +1,220 @@ +package net.intrepid.aiengineering.filesystem; + +import java.nio.charset.StandardCharsets; +import java.nio.file.*; +import java.sql.*; +import java.util.*; +import org.sqlite.JDBC; + +/** Explicit local database lifecycle and command-scoped transactions; no project discovery or migration. */ +public final class SqliteDatabase { + public static final int SCHEMA_VERSION = 1; + public static final int APPLICATION_ID = 0x41494531; + public static final int DEFAULT_BUSY_MILLIS = 2000; + private static final ThreadLocal> SESSIONS = ThreadLocal.withInitial(HashMap::new); + private SqliteDatabase() {} + + @FunctionalInterface public interface Operation { T run(Connection connection) throws SQLException; } + private static final class Session { + final Connection connection; + final boolean write; + boolean rollbackOnly; + final List committed = new ArrayList<>(); + final List rolledBack = new ArrayList<>(); + Session(Connection connection, boolean write) { this.connection = connection; this.write = write; } + } + + public static Path path(Path root) { return Filespace.resolve(root, ".ai-engineering/aie.db"); } + + public static boolean active(Path root) { + Path config = Filespace.resolve(root, ".ai-engineering/ai-engineering.yaml"); + if (!Files.isRegularFile(config, LinkOption.NOFOLLOW_LINKS)) return false; + var node = Documents.read(config, tools.jackson.databind.node.ObjectNode.class).get("storage"); + if (node == null || node.isNull()) return false; + if (!node.isString() || !node.stringValue().equals("sqlite")) throw ProtocolException.validation("Unsupported project storage"); + Path manifest = Filespace.resolve(root, ".ai-engineering/protocol.json"); + if (!Files.isRegularFile(manifest, LinkOption.NOFOLLOW_LINKS)) throw ProtocolException.validation("SQLite storage requires protocol contract 4; inspect compatibility with a compatible CLI"); + var version = Documents.readJson(manifest, tools.jackson.databind.node.ObjectNode.class).get("protocolVersion"); + if (version == null || !version.isIntegralNumber() || version.intValue() != 4) + throw ProtocolException.validation("SQLite storage requires supported protocol contract 4; inspect compatibility before writing"); + return true; + } + + private static Path checked(Path root) { + Path path = path(root); + for (String suffix : List.of("-wal", "-shm", "-journal")) { + Path sidecar = Filespace.resolve(root, ".ai-engineering/aie.db" + suffix); + if (Files.exists(sidecar, LinkOption.NOFOLLOW_LINKS) && !Files.isRegularFile(sidecar, LinkOption.NOFOLLOW_LINKS)) + throw ProtocolException.validation("SQLite sidecar must be a regular file: " + sidecar); + } + if (Files.exists(path, LinkOption.NOFOLLOW_LINKS) && !Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)) + throw ProtocolException.validation("AIE database must be a regular file: " + path); + return path; + } + + /** A separate, explicit operation. Opening a missing database never creates one. */ + public static void initialize(Path root) { + Path path = checked(root); + if (Files.exists(path, LinkOption.NOFOLLOW_LINKS)) + throw ProtocolException.invalid("Database already exists; initialization cannot replace it: " + path); + for (String suffix : List.of("-wal", "-shm", "-journal")) + if (Files.exists(path.resolveSibling("aie.db" + suffix), LinkOption.NOFOLLOW_LINKS)) + throw ProtocolException.validation("Existing SQLite sidecar requires inspection before initialization"); + Filespace.directory(path.getParent()); + Filespace.io(() -> { Files.createFile(path); return null; }); + boolean complete = false; + try (var connection = connect(path, true, DEFAULT_BUSY_MILLIS)) { + try (var statement = connection.createStatement()) { + statement.execute("PRAGMA journal_mode=WAL"); + statement.execute("PRAGMA synchronous=FULL"); + } + connection.setAutoCommit(false); + try (var statement = connection.createStatement()) { + String schema = Filespace.io(() -> { + try (var input = SqliteDatabase.class.getResourceAsStream("/sqlite/schema-v1.sql")) { + if (input == null) throw ProtocolException.validation("Missing SQLite schema resource"); + return new String(input.readAllBytes(), StandardCharsets.UTF_8); + } + }); + for (String sql : schema.split(";")) if (!sql.isBlank()) statement.execute(sql); + statement.execute("PRAGMA application_id=" + APPLICATION_ID); + statement.execute("PRAGMA user_version=" + SCHEMA_VERSION); + connection.commit(); + complete = true; + } catch (SQLException | RuntimeException failure) { + rollback(connection, failure); throw failure; + } + } catch (SQLException failure) { throw problem(failure, DEFAULT_BUSY_MILLIS); } + finally { + if (!complete) Filespace.io(() -> { + for (String suffix : List.of("", "-wal", "-shm", "-journal")) + Files.deleteIfExists(Filespace.resolve(root, ".ai-engineering/aie.db" + suffix)); + return null; + }); + } + } + + public static T read(Path root, Operation operation) { + return transaction(root, false, DEFAULT_BUSY_MILLIS, operation); + } + public static void checkpoint(Path root) { + Path path = checked(root); + if (!Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)) throw ProtocolException.missing("Missing AIE database: " + path); + if (SESSIONS.get().containsKey(path)) throw ProtocolException.invalid("Checkpoint requires closed command transactions"); + try (var connection = connect(path, true, DEFAULT_BUSY_MILLIS)) { + validate(connection); + try (var statement = connection.createStatement(); var row = statement.executeQuery("PRAGMA wal_checkpoint(TRUNCATE)")) { + if (!row.next() || row.getInt(1) != 0) throw ProtocolException.validation("Database checkpoint is busy; retry migration after other commands finish"); + } + } catch (SQLException failure) { throw problem(failure, DEFAULT_BUSY_MILLIS); } + } + public static void rollbackOnly(Path root) { + var session = SESSIONS.get().get(path(root)); + if (session == null || !session.write) throw ProtocolException.invalid("No active SQLite write transaction to roll back"); + session.rollbackOnly = true; + } + public static void afterCommit(Path root, Runnable operation) { callbacks(root).committed.add(operation); } + public static void afterRollback(Path root, Runnable operation) { callbacks(root).rolledBack.add(operation); } + private static Session callbacks(Path root) { + var session = SESSIONS.get().get(path(root)); + if (session == null || !session.write) throw ProtocolException.invalid("File publication requires an active SQLite write transaction"); + return session; + } + public static T write(Path root, Operation operation) { + return transaction(root, true, DEFAULT_BUSY_MILLIS, operation); + } + public static T write(Path root, int busyMillis, Operation operation) { + return transaction(root, true, busyMillis, operation); + } + + private static T transaction(Path root, boolean write, int busyMillis, Operation operation) { + Objects.requireNonNull(operation); + if (busyMillis < 0 || busyMillis > 30000) throw ProtocolException.invalid("SQLite busy timeout must be 0–30000 ms"); + Path path = checked(root); + if (!Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)) throw ProtocolException.missing("Missing AIE database: " + path); + var active = SESSIONS.get(); + var nested = active.get(path); + if (nested != null) { + if (write && !nested.write) { + nested.rollbackOnly = true; + throw ProtocolException.invalid("Cannot start a write inside a read transaction"); + } + try { return operation.run(nested.connection); } + catch (SQLException failure) { nested.rollbackOnly = true; throw problem(failure, busyMillis); } + catch (RuntimeException | Error failure) { nested.rollbackOnly = true; throw failure; } + } + var committed = new ArrayList(); + var rolledBack = new ArrayList(); + T result; + try (var connection = connect(path, write, busyMillis)) { + validate(connection); + connection.setAutoCommit(false); + var session = new Session(connection, write); + active.put(path, session); + try { + result = operation.run(connection); + if (session.rollbackOnly) { + connection.rollback(); + if (write) throw ProtocolException.validation("SQLite transaction rolled back after a nested operation failed"); + } else { connection.commit(); committed.addAll(session.committed); } + } catch (SQLException | RuntimeException | Error failure) { + rollback(connection, failure); + rolledBack.addAll(session.rolledBack.reversed()); + throw failure; + } finally { active.remove(path); } + } catch (SQLException failure) { + var translated = problem(failure, busyMillis); recover(rolledBack, translated); throw translated; + } catch (RuntimeException | Error failure) { recover(rolledBack, failure); throw failure; } + finally { if (active.isEmpty()) SESSIONS.remove(); } + for (var operationAfterCommit : committed) { + try { operationAfterCommit.run(); } + catch (RuntimeException failure) { throw new ProtocolException(1, "SQLite change committed; file cleanup needs recovery: " + failure.getMessage()); } + } + return result; + } + private static void recover(List operations, Throwable failure) { + for (var operation : operations) { + try { operation.run(); } catch (RuntimeException secondary) { failure.addSuppressed(secondary); } + } + } + + private static Connection connect(Path path, boolean write, int busyMillis) throws SQLException { + var properties = new Properties(); + // READONLY / READWRITE, plus SQLITE_OPEN_URI. CREATE is deliberately absent. + properties.setProperty("open_mode", Integer.toString((write ? 2 : 1) | 64)); + properties.setProperty("foreign_keys", "true"); + properties.setProperty("busy_timeout", Integer.toString(busyMillis)); + properties.setProperty("transaction_mode", write ? "IMMEDIATE" : "DEFERRED"); + return new JDBC().connect("jdbc:sqlite:" + path.toUri().toASCIIString(), properties); + } + + private static void validate(Connection connection) throws SQLException { + try (var statement = connection.createStatement()) { + try (var row = statement.executeQuery("PRAGMA application_id")) { + if (!row.next() || row.getInt(1) != APPLICATION_ID) + throw ProtocolException.validation("Not a recognized AIE SQLite database; use explicit initialization or migration"); + } + try (var row = statement.executeQuery("PRAGMA user_version")) { + if (!row.next() || row.getInt(1) != SCHEMA_VERSION) + throw ProtocolException.validation("Unsupported AIE SQLite schema; use a compatible CLI and inspect compatibility"); + } + try (var row = statement.executeQuery("SELECT schema_version FROM aie_schema WHERE singleton=1")) { + if (!row.next() || row.getInt(1) != SCHEMA_VERSION) + throw ProtocolException.validation("Inconsistent AIE SQLite schema metadata"); + } + } + } + + private static void rollback(Connection connection, Throwable failure) { + try { if (!connection.getAutoCommit()) connection.rollback(); } + catch (SQLException rollbackFailure) { failure.addSuppressed(rollbackFailure); } + } + + private static ProtocolException problem(SQLException failure, int busyMillis) { + int code = failure.getErrorCode() & 0xff; + if (code == 5 || code == 6) + return ProtocolException.validation("AIE database is busy after a wait limited to " + busyMillis + " ms; retry after the other operation finishes"); + if (code == 19) return ProtocolException.validation("SQLite integrity constraint rejected the operation: " + failure.getMessage()); + return new ProtocolException(1, "SQLite operation failed: " + failure.getMessage()); + } +} diff --git a/src/main/java/net/intrepid/aiengineering/filesystem/SqliteRecords.java b/src/main/java/net/intrepid/aiengineering/filesystem/SqliteRecords.java new file mode 100644 index 0000000..ce61d7a --- /dev/null +++ b/src/main/java/net/intrepid/aiengineering/filesystem/SqliteRecords.java @@ -0,0 +1,246 @@ +package net.intrepid.aiengineering.filesystem; + +import java.lang.reflect.RecordComponent; +import java.nio.file.Path; +import java.sql.*; +import java.util.*; +import tools.jackson.databind.JsonNode; +import tools.jackson.databind.node.ObjectNode; + +/** Typed record columns and ordered child rows. Never stores a serialized file or whole aggregate. */ +public final class SqliteRecords { + private SqliteRecords() {} + private static final Set KINDS = Set.of("work", "discussion", "topic", "survey", "disposition", "decision", "plan", "epic", "run", "artifact", "gate", "receipt"); + private static String table(String kind) { + if (!KINDS.contains(kind)) throw ProtocolException.invalid("Unknown record kind: " + kind); + return "data_" + kind; + } + private static String field(RecordComponent component) { + String name = component.getName(); + if (!name.matches("[a-zA-Z][a-zA-Z0-9]*")) throw ProtocolException.validation("Unsupported record field"); + return "f_" + name; + } + private static boolean list(RecordComponent component) { return component.getType() == List.class; } + private static boolean number(RecordComponent component) { + return Set.of(int.class, long.class, Integer.class, Long.class, boolean.class, Boolean.class).contains(component.getType()); + } + private static boolean bool(RecordComponent component) { return component.getType() == boolean.class || component.getType() == Boolean.class; } + private static boolean text(RecordComponent component) { return component.getType() == String.class || component.getType().isEnum(); } + private static void key(PreparedStatement statement, String work, String id, int revision) throws SQLException { + statement.setString(1, work); statement.setString(2, id); statement.setInt(3, revision); + } + private static void identity(PreparedStatement statement, String work, String kind, String id, int revision) throws SQLException { + statement.setString(1, work); statement.setString(2, kind); statement.setString(3, id); statement.setInt(4, revision); + } + + private static void schema(Connection connection, String kind, Class type) throws SQLException { + if (!type.isRecord()) throw ProtocolException.invalid("Storage requires a domain record"); + String name = table(kind); + var columns = new ArrayList(); + for (var component : type.getRecordComponents()) { + if (list(component)) columns.add(field(component) + "__present INTEGER NOT NULL DEFAULT 1 CHECK(" + field(component) + "__present IN (0,1))"); + else columns.add(field(component) + " " + (number(component) ? "INTEGER" : "TEXT") + + (!text(component) && !number(component) ? " CHECK(" + field(component) + " IS NULL OR json_valid(" + field(component) + "))" : "")); + } + try (var statement = connection.createStatement()) { + statement.execute("CREATE TABLE IF NOT EXISTS " + name + " (work_id TEXT NOT NULL, local_id TEXT NOT NULL, storage_revision INTEGER NOT NULL, kind TEXT NOT NULL DEFAULT '" + kind + + "' CHECK(kind='" + kind + "')," + String.join(",", columns) + + ", PRIMARY KEY(work_id,local_id,storage_revision), FOREIGN KEY(work_id,kind,local_id,storage_revision) REFERENCES record_identity(work_id,kind,local_id,revision) DEFERRABLE INITIALLY DEFERRED)"); + for (var component : type.getRecordComponents()) if (list(component)) + statement.execute("CREATE TABLE IF NOT EXISTS " + name + "_" + field(component) + + " (work_id TEXT NOT NULL,local_id TEXT NOT NULL,storage_revision INTEGER NOT NULL,ordinal INTEGER NOT NULL CHECK(ordinal>=0),value_kind TEXT NOT NULL CHECK(value_kind IN ('string','record')),value TEXT NOT NULL," + + "CHECK(value_kind='string' OR json_valid(value)),PRIMARY KEY(work_id,local_id,storage_revision,ordinal)," + + "FOREIGN KEY(work_id,local_id,storage_revision) REFERENCES " + name + "(work_id,local_id,storage_revision) DEFERRABLE INITIALLY DEFERRED)"); + for (String property : List.of("title", "status")) if (Arrays.stream(type.getRecordComponents()).anyMatch(c -> c.getName().equals(property))) + statement.execute("CREATE INDEX IF NOT EXISTS " + name + "_by_" + property + " ON " + name + "(f_" + property + ",work_id,local_id)"); + } + } + + public static int current(Path root, String work, String kind, String id) { + table(kind); + return SqliteDatabase.read(root, connection -> current(connection, work, kind, id)); + } + private static int current(Connection connection, String work, String kind, String id) throws SQLException { + try (var statement = connection.prepareStatement("SELECT revision FROM current_record WHERE work_id=? AND kind=? AND local_id=?")) { + statement.setString(1, work); statement.setString(2, kind); statement.setString(3, id); + try (var rows = statement.executeQuery()) { return rows.next() ? rows.getInt(1) : 0; } + } + } + + public static List ids(Path root, String kind, String work) { + table(kind); + return SqliteDatabase.read(root, connection -> { + var ids = new ArrayList(); + try (var statement = connection.prepareStatement("SELECT local_id FROM current_record WHERE kind=?" + (work == null ? "" : " AND work_id=?") + " ORDER BY local_id")) { + statement.setString(1, kind); if (work != null) statement.setString(2, work); + try (var rows = statement.executeQuery()) { while (rows.next()) ids.add(rows.getString(1)); } + } + return List.copyOf(ids); + }); + } + + public static T get(Path root, String work, String kind, String id, int requestedRevision, Class type) { + String name = table(kind); + return SqliteDatabase.read(root, connection -> { + int revision = requestedRevision == 0 ? current(connection, work, kind, id) : requestedRevision; + if (revision == 0) throw ProtocolException.missing("Record not found: " + kind + "/" + id); + ObjectNode data = Documents.jsonTree(Map.of()); + try (var statement = connection.prepareStatement("SELECT * FROM " + name + " WHERE work_id=? AND local_id=? AND storage_revision=?")) { + key(statement, work, id, revision); + try (var rows = statement.executeQuery()) { + if (!rows.next()) throw ProtocolException.missing("Record revision not found: " + kind + "/" + id + "/" + revision); + for (var component : type.getRecordComponents()) { + String column = field(component), property = component.getName(); + if (list(component)) { + if (rows.getInt(column + "__present") == 0) data.putNull(property); + else data.putArray(property); + continue; + } + Object value = rows.getObject(column); + if (value == null) { data.putNull(property); continue; } + if (bool(component)) data.put(property, rows.getInt(column) != 0); + else if (number(component)) data.put(property, rows.getLong(column)); + else if (text(component)) data.put(property, rows.getString(column)); + else data.set(property, Documents.parseJson(rows.getString(column), JsonNode.class)); + } + } + } + for (var component : type.getRecordComponents()) if (list(component)) { + if (data.get(component.getName()).isNull()) continue; + var array = data.putArray(component.getName()); + try (var statement = connection.prepareStatement("SELECT value_kind,value FROM " + name + "_" + field(component) + " WHERE work_id=? AND local_id=? AND storage_revision=? ORDER BY ordinal")) { + key(statement, work, id, revision); + try (var rows = statement.executeQuery()) { + while (rows.next()) { + if (rows.getString(1).equals("string")) array.add(rows.getString(2)); + else array.add(Documents.parseJson(rows.getString(2), JsonNode.class)); + } + } + } + } + return Documents.jsonValue(data, type); + }); + } + + public static void put(Path root, String work, String kind, String id, T value, Class type, boolean replace, int documentVersion) { + String name = table(kind); + var data = Documents.jsonTree(value); + String objectId = data.has("id") ? data.get("id").stringValue() : data.get("workId").stringValue(); + String owner = kind.equals("work") ? objectId : data.get("workId").stringValue(); + if (!id.equals(objectId) || !work.equals(owner)) throw ProtocolException.validation("Stored record identity/ownership mismatch: " + id); + int revision = data.hasNonNull("revision") ? data.get("revision").intValue() : 1; + SqliteDatabase.write(root, connection -> { + int old = current(connection, work, kind, id); + if (!replace && old != 0) throw ProtocolException.invalid("Record already exists: " + id); + if (replace && old == 0) throw ProtocolException.missing("Record not found: " + id); + schema(connection, kind, type); + try (var statement = connection.prepareStatement("INSERT INTO record_identity VALUES (?,?,?,?) ON CONFLICT DO NOTHING")) { + identity(statement, work, kind, id, revision); statement.executeUpdate(); + } + var components = Arrays.stream(type.getRecordComponents()).filter(c -> !list(c)).toList(); + String fields = String.join(",", components.stream().map(SqliteRecords::field).toList()); + String placeholders = String.join(",", Collections.nCopies(3 + components.size(), "?")); + String updates = String.join(",", components.stream().map(c -> field(c) + "=excluded." + field(c)).toList()); + try (var statement = connection.prepareStatement("INSERT INTO " + name + "(work_id,local_id,storage_revision," + fields + ") VALUES (" + placeholders + ") ON CONFLICT(work_id,local_id,storage_revision) DO UPDATE SET " + updates)) { + key(statement, work, id, revision); int position = 4; + for (var component : components) { + var node = data.get(component.getName()); + if (node == null || node.isNull()) statement.setNull(position, number(component) ? Types.INTEGER : Types.VARCHAR); + else if (bool(component)) statement.setInt(position, node.booleanValue() ? 1 : 0); + else if (number(component)) statement.setLong(position, node.longValue()); + else if (text(component)) statement.setString(position, node.stringValue()); + else statement.setString(position, Documents.json(node)); + position++; + } + statement.executeUpdate(); + } + for (var component : type.getRecordComponents()) if (list(component)) { + String child = name + "_" + field(component); + boolean present; + try { present = component.getAccessor().invoke(value) != null; } + catch (ReflectiveOperationException failure) { throw ProtocolException.validation("Cannot inspect typed list presence: " + component.getName()); } + try (var statement = connection.prepareStatement("UPDATE " + name + " SET " + field(component) + "__present=? WHERE work_id=? AND local_id=? AND storage_revision=?")) { + statement.setInt(1, present ? 1 : 0); statement.setString(2, work); statement.setString(3, id); statement.setInt(4, revision); statement.executeUpdate(); + } + try (var statement = connection.prepareStatement("DELETE FROM " + child + " WHERE work_id=? AND local_id=? AND storage_revision=?")) { + key(statement, work, id, revision); statement.executeUpdate(); + } + var array = data.get(component.getName()); + if (array != null && !array.isNull()) try (var statement = connection.prepareStatement("INSERT INTO " + child + " VALUES (?,?,?,?,?,?)")) { + int ordinal = 0; + for (var node : array) { + key(statement, work, id, revision); statement.setInt(4, ordinal++); + statement.setString(5, node.isString() ? "string" : "record"); + statement.setString(6, node.isString() ? node.stringValue() : Documents.json(node)); statement.addBatch(); + } + statement.executeBatch(); + } + } + try (var statement = connection.prepareStatement("INSERT INTO current_record VALUES (?,?,?,?) ON CONFLICT(work_id,kind,local_id) DO UPDATE SET revision=excluded.revision")) { + identity(statement, work, kind, id, revision); statement.executeUpdate(); + } + try (var statement = connection.prepareStatement("INSERT INTO record_format(work_id,kind,local_id,revision,document_version) VALUES (?,?,?,?,?) ON CONFLICT(work_id,kind,local_id,revision) DO UPDATE SET document_version=excluded.document_version,original_path=NULL,original_sha256=NULL")) { + identity(statement, work, kind, id, revision); statement.setInt(5, documentVersion); statement.executeUpdate(); + } + if (kind.equals("work")) { + try (var statement = connection.prepareStatement("DELETE FROM record_reference WHERE work_id=? AND kind='work' AND local_id=? AND revision=?")) { + key(statement, work, id, revision); statement.executeUpdate(); + } + var owned = Map.of("discussions", "discussion", "topics", "topic", "surveys", "survey", + "dispositions", "disposition", "decisions", "decision", "plans", "plan", "agentRuns", "run", "artifacts", "artifact"); + for (var entry : owned.entrySet()) { + var references = data.get(entry.getKey()); + if (references == null || references.isNull()) continue; + int ordinal = 0; + for (var reference : references) { + String target = reference.stringValue(); int targetRevision = current(connection, work, entry.getValue(), target); + if (targetRevision == 0) throw ProtocolException.validation("Missing owned record: " + target); + try (var statement = connection.prepareStatement("INSERT INTO record_reference VALUES (?,?,?,?,?,?,?,?,?,?)")) { + identity(statement, work, kind, id, revision); statement.setString(5, entry.getKey()); statement.setInt(6, ordinal++); + statement.setString(7, work); statement.setString(8, entry.getValue()); statement.setString(9, target); statement.setInt(10, targetRevision); + statement.executeUpdate(); + } + } + } + } + if (kind.equals("epic")) { + try (var statement = connection.prepareStatement("DELETE FROM epic_link WHERE parent_work_id=?")) { + statement.setString(1, work); statement.executeUpdate(); + } + try (var statement = connection.prepareStatement("INSERT INTO epic_link VALUES (?,?,?)")) { + for (var child : data.get("children")) { + statement.setString(1, work); statement.setString(2, child.get("workId").stringValue()); + statement.setInt(3, child.get("important").booleanValue() ? 1 : 0); statement.addBatch(); + } + statement.executeBatch(); + } + } + return null; + }); + } + + public static String raw(Path root, String work, String kind, String id, int revision, Class type, String bodyField) { + return SqliteDatabase.read(root, connection -> { + int selected = revision == 0 ? current(connection, work, kind, id) : revision; + int version; + try (var statement = connection.prepareStatement("SELECT document_version,original_path,original_sha256 FROM record_format WHERE work_id=? AND kind=? AND local_id=? AND revision=?")) { + identity(statement, work, kind, id, selected); + try (var row = statement.executeQuery()) { + if (!row.next()) throw ProtocolException.missing("Record format not found: " + id); + version = row.getInt(1); + if (row.getString(2) != null) { + String original = Filespace.read(Filespace.resolve(root, row.getString(2))); + if (!Revisions.hash(original).equals(row.getString(3))) throw ProtocolException.validation("Historical source representation changed: " + id); + var represented = Documents.parseMarkdownDocument(original, type, bodyField); + if (!Objects.equals(represented, get(root, work, kind, id, selected, type))) + throw ProtocolException.validation("Typed historical record differs from its source representation: " + id); + return original; + } + } + } + T value = get(root, work, kind, id, selected, type); + if (version == 2) return Documents.markdownDocument(value, bodyField); + return "---\n" + Documents.yaml(value).replaceFirst("^---\\n", "") + "---\n"; + }); + } +} diff --git a/src/main/java/net/intrepid/aiengineering/legacyimport/DiscussionImportService.java b/src/main/java/net/intrepid/aiengineering/legacyimport/DiscussionImportService.java index bc4ab00..689abc1 100644 --- a/src/main/java/net/intrepid/aiengineering/legacyimport/DiscussionImportService.java +++ b/src/main/java/net/intrepid/aiengineering/legacyimport/DiscussionImportService.java @@ -59,6 +59,8 @@ public final class DiscussionImportService { } } catch (RuntimeException failure) { int code = failure instanceof ProtocolException p ? p.exitCode() : 1; + if (SqliteDatabase.active(root)) throw new ProtocolException(code, "DF import rolled back: " + failure.getMessage() + + ". No Works from this transaction committed; run preview again to resume."); throw new ProtocolException(code, "DF import failed: " + failure.getMessage() + "; published Works: " + published + ". Run preview again to resume; unpublished staging may remain for inspection."); } diff --git a/src/main/java/net/intrepid/aiengineering/planning/PlanService.java b/src/main/java/net/intrepid/aiengineering/planning/PlanService.java index 1101fdf..4d24e17 100644 --- a/src/main/java/net/intrepid/aiengineering/planning/PlanService.java +++ b/src/main/java/net/intrepid/aiengineering/planning/PlanService.java @@ -13,7 +13,7 @@ public final class PlanService { private final WorkService works = new WorkService(); private final DecisionService decisions = new DecisionService(); private Path path(Path root, String work, String id) { Work.identifier(id, "PLN"); return Filespace.resolve(works.folder(root, work), "plans/" + id + ".md"); } - private Plan read(Path path) { return Documents.readMarkdownDocument(path, Plan.class, "description"); } + private Plan read(Path path) { return RecordStorage.read(path, Plan.class, "description"); } public List list(Path root, String work) { return works.load(root, work).plans().stream().map(id -> { var plan = read(path(root, work, id)); identity(plan, work, id); chain(root, plan); return plan; @@ -29,7 +29,7 @@ public final class PlanService { private List chain(Path root, Plan current) { var history = new ArrayList(); history.add(current); var next = current; for (int revision = current.revision() - 1; revision >= 1; revision--) { - Path path = Revisions.history(works.folder(root, current.workId()), "plans", current.id(), revision); String original = Filespace.read(path); + Path path = Revisions.history(works.folder(root, current.workId()), "plans", current.id(), revision); String original = RecordStorage.raw(path, Plan.class, "description"); Revisions.chain(next.revision(), next.previousHash(), revision + 1, original); var prior = read(path); identity(prior, current.workId(), current.id()); if (prior.revision() != revision) throw ProtocolException.validation("Invalid plan history revision: " + path); @@ -68,6 +68,13 @@ public final class PlanService { throw ProtocolException.invalid("Resolve pending discussion questions and surveys before creating a Plan"); var plan = new Plan(1, id, workId, title, description, refs, List.of(), Plan.Status.OPEN, author, now, 1, null, now, author, "Plan created"); Path path = path(root, workId, id), folder = works.folder(root, workId), workPath = Filespace.resolve(folder, "work.md"); + if (SqliteDatabase.active(root)) { + var promotions = decisions.preparePlanAcceptance(root, workId, refs, id, author); + promotions.publish(folder); + RecordStorage.write(path, plan, Plan.class, "description", false); + works.addReference(root, workId, "plans", id); + return plan; + } if (Files.exists(path)) throw ProtocolException.invalid("Already exists: " + path); String originalWork = Filespace.read(workPath), document = Documents.markdownDocument(plan, "description"); var promotions = decisions.preparePlanAcceptance(root, workId, refs, id, author); @@ -95,10 +102,10 @@ public final class PlanService { private Plan mutate(Path root, String work, String id, String by, String reason, Function mutation) { return Filespace.locked(root, () -> { works.editable(root, work); ProtocolException.text(by, "plan actor"); ProtocolException.text(reason, "plan change reason"); - var old = get(root, work, id); String original = Filespace.read(path(root, work, id)); var candidate = mutation.apply(old); + var old = get(root, work, id); String original = RecordStorage.raw(path(root, work, id), Plan.class, "description"); var candidate = mutation.apply(old); if (candidate.equals(old)) return old; var changed = candidate.snapshot(by, reason, Revisions.hash(original)); - Revisions.replace(works.folder(root, work), "plans", id, old.revision(), original, Documents.markdownDocument(changed, "description")); + RecordStorage.replaceRevision(works.folder(root, work), "plans", id, old.revision(), original, Documents.markdownDocument(changed, "description"), Plan.class, "description"); works.touched(root, work, changed.updatedAt()); return changed; }); } @@ -185,7 +192,10 @@ public final class PlanService { accepted(root, work, old.decisions()); old.requireExperimentReady(stepId); } if (!works.load(root, work).artifacts().containsAll(evidence)) throw ProtocolException.invalid("Unknown step evidence"); - if (target == Plan.Status.COMPLETED) new ArtifactService().validate(root, work); + if (target == Plan.Status.COMPLETED) { + new ArtifactService().validate(root, work); + new ArtifactService().requireAvailable(root, work, evidence); + } var changed = new Plan.Step(stepId, previous.title(), previous.description(), previous.acceptanceCriteria(), previous.dependsOn(), target, reason, evidence, Instant.now().toString()); var steps = old.steps().stream().map(step -> step.id().equals(stepId) ? changed : step).toList(); var status = old.status() == Plan.Status.OPEN && (target == Plan.Status.ACTIVE || target == Plan.Status.COMPLETED) ? Plan.Status.ACTIVE : old.status(); @@ -216,6 +226,7 @@ public final class PlanService { .orElseThrow(() -> ProtocolException.missing("Experiment not found: " + experimentId)); if (!works.load(root, work).artifacts().containsAll(evidence)) throw ProtocolException.invalid("Unknown experiment evidence"); new ArtifactService().validate(root, work); + new ArtifactService().requireAvailable(root, work, evidence); if (concern != null && !old.decisions().contains(concern)) throw ProtocolException.invalid("Questioned DEC must belong to the Plan"); var result = experiment.finish(outcome, observation, interpretation, nextAction, evidence, concern, by); return old.withExperiments(old.experiments().stream().map(e -> e.id().equals(experimentId) ? result : e).toList()); diff --git a/src/main/java/net/intrepid/aiengineering/project/ProjectConfig.java b/src/main/java/net/intrepid/aiengineering/project/ProjectConfig.java index 82820b0..3881d54 100644 --- a/src/main/java/net/intrepid/aiengineering/project/ProjectConfig.java +++ b/src/main/java/net/intrepid/aiengineering/project/ProjectConfig.java @@ -3,7 +3,9 @@ package net.intrepid.aiengineering.project; import net.intrepid.aiengineering.filesystem.ProtocolException; import java.util.*; -public record ProjectConfig(int schemaVersion, Identity project, List repositories, Agents agents) { +public record ProjectConfig(int schemaVersion, Identity project, List repositories, Agents agents, + @com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL) String storage) { + public ProjectConfig(int schemaVersion, Identity project, List repositories, Agents agents) { this(schemaVersion, project, repositories, agents, null); } public ProjectConfig(int schemaVersion, Identity project, List repositories) { this(schemaVersion, project, repositories, null); } public record Executor(String adapter, String profile, String model, @com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL) Integer timeoutSeconds) { @@ -25,6 +27,7 @@ public record ProjectConfig(int schemaVersion, Identity project, List line.equals("/.ai-engineering/"))) + nextIgnore += (nextIgnore.isEmpty() || nextIgnore.endsWith("\n") ? "" : "\n") + "/.ai-engineering/\n"; + Path staging = Filespace.resolve(root, ".aie-bootstrap-" + UUID.randomUUID()); Filespace.directory(staging); + boolean published = false; + try { + var initial = initializeLegacy(staging, name); + SqliteDatabase.initialize(staging); + var config = new ProjectConfig(initial.schemaVersion(), initial.project(), initial.repositories(), initial.agents(), "sqlite"); + Filespace.write(staging.resolve(".ai-engineering/ai-engineering.yaml"), Documents.yaml(config), true); + SqliteDatabase.checkpoint(staging); + Filespace.write(instructions, nextInstructions, originalInstructions != null); + if (ignoreState && !Objects.equals(nextIgnore, originalIgnore)) Filespace.write(ignore, nextIgnore, originalIgnore != null); + Filespace.moveDirectory(staging.resolve(".ai-engineering"), target); published = true; + return config; + } catch (RuntimeException failure) { + if (!published) { + try { + restoreBootstrap(instructions, originalInstructions, nextInstructions); + if (ignoreState) restoreBootstrap(ignore, originalIgnore, nextIgnore); + } catch (RuntimeException recovery) { failure.addSuppressed(recovery); } + } + throw failure; + } finally { + try (var paths = Filespace.io(() -> Files.walk(staging))) { + for (Path path : paths.sorted(Comparator.reverseOrder()).toList()) { + if (!path.equals(staging)) Filespace.resolve(projectRoot, projectRoot.relativize(path).toString()); + Filespace.io(() -> { Files.delete(path); return null; }); + } + } + } + } + private void restoreBootstrap(Path path, String original, String intended) { + if (!Files.exists(path) || !Filespace.read(path).equals(intended)) return; + if (original == null) Filespace.io(() -> { Files.delete(path); return null; }); + else Filespace.write(path, original, true); + } public static String slug(String text) { ProtocolException.text(text, "name"); String result = java.text.Normalizer.normalize(text, java.text.Normalizer.Form.NFD) @@ -58,7 +113,7 @@ public final class ProjectService { if (config.repositories().stream().anyMatch(r -> repositoryPath(root, r).equals(path))) throw ProtocolException.invalid("Repository path already registered: " + path); git.inspect(root, path, repository.type()); var repositories = new ArrayList<>(config.repositories()); repositories.add(repository); - var updated = new ProjectConfig(1, config.project(), repositories, config.agents()); + var updated = new ProjectConfig(1, config.project(), repositories, config.agents(), config.storage()); Filespace.write(Filespace.resolve(root, ".ai-engineering/ai-engineering.yaml"), Documents.yaml(updated), true); return updated; }); @@ -70,7 +125,7 @@ public final class ProjectService { } public ProjectConfig configureAgents(Path root, ProjectConfig.Agents agents) { return Filespace.locked(root, () -> { - var original = load(root); var changed = new ProjectConfig(1, original.project(), original.repositories(), agents); + var original = load(root); var changed = new ProjectConfig(1, original.project(), original.repositories(), agents, original.storage()); if (!changed.equals(original)) Filespace.write(Filespace.resolve(root, ".ai-engineering/ai-engineering.yaml"), Documents.yaml(changed), true); return changed; }); diff --git a/src/main/java/net/intrepid/aiengineering/project/ProtocolContract.java b/src/main/java/net/intrepid/aiengineering/project/ProtocolContract.java index a60abe2..3fc06ef 100644 --- a/src/main/java/net/intrepid/aiengineering/project/ProtocolContract.java +++ b/src/main/java/net/intrepid/aiengineering/project/ProtocolContract.java @@ -7,8 +7,8 @@ import java.util.List; public final class ProtocolContract { private ProtocolContract() {} public static final String CLI_VERSION = "0.1.0"; - public static final int CURRENT = 3; - public static final List READABLE = List.of(1, 2, 3); + public static final int CURRENT = 4; + public static final List READABLE = List.of(1, 2, 3, 4); /** Pre-versioned manifests describe the supported baseline contract, without rewriting them. */ public static int effective(Integer declared) { return declared == null ? 1 : declared; } public static void require(Integer declared) { diff --git a/src/main/java/net/intrepid/aiengineering/project/ProtocolGuide.java b/src/main/java/net/intrepid/aiengineering/project/ProtocolGuide.java index 82b04f8..80aef2d 100644 --- a/src/main/java/net/intrepid/aiengineering/project/ProtocolGuide.java +++ b/src/main/java/net/intrepid/aiengineering/project/ProtocolGuide.java @@ -13,8 +13,9 @@ public final class ProtocolGuide { + "This project uses AI Engineering. Read `.ai-engineering/README.md` and\n" + "`.ai-engineering/protocol.json` before engineering work. Run `aie status` and\n" + "`aie next-actions`, then load the selected Work with `aie work context `.\n" - + "Use `ai-engineering` if the `aie` alias is unavailable; without a CLI, read the\n" - + "portable files directly. Preserve the project rules outside this block.\n" + + "Use `ai-engineering` if the `aie` alias is unavailable. SQLite memory requires\n" + + "a compatible CLI; without one, read bootstrap guidance and report the tool gap.\n" + + "Never treat unreadable memory as an empty project. Preserve rules outside this block.\n" + "Ask for missing Work discussion mode; only the human changes it or ends exploration.\n" + "Never infer human approval; record it explicitly before significant commitments.\n" + END; private ProtocolGuide() {} @@ -52,6 +53,8 @@ public final class ProtocolGuide { throw ProtocolException.validation("Unsupported protocol discovery manifest"); if (ProtocolContract.effective(protocolVersion) >= 3 && !capabilities.containsAll(List.of("work-guidance", "human-decision-request", "plan-experiments"))) throw ProtocolException.validation("Contract 3 requires Work guidance, human decision requests and Plan experiments"); + if (ProtocolContract.effective(protocolVersion) >= 4 && !capabilities.containsAll(List.of("sqlite-storage", "local-memory", "quality-gates", "temporary-artifacts"))) + throw ProtocolException.validation("Contract 4 requires SQLite storage, local memory, quality gates and temporary artifacts"); for (String value : List.of(entrypoint, instructions, configuration, works)) ProtocolException.text(value, "manifest path"); aliases = List.copyOf(aliases); startup = List.copyOf(startup); capabilities = List.copyOf(capabilities); if (startup.isEmpty() || capabilities.isEmpty()) throw ProtocolException.validation("Incomplete protocol discovery manifest"); @@ -101,13 +104,17 @@ public final class ProtocolGuide { if (start >= 0) return original.substring(0, start) + POINTER + original.substring(end + END.length()); return original + (original.isEmpty() ? "" : original.endsWith("\n") ? "\n" : "\n\n") + POINTER + "\n"; } + public static Map entries(Path root) { + var content = new LinkedHashMap(); + for (String name : List.of("README.md", "AGENTS.md", "protocol.json")) content.put(".ai-engineering/" + name, bundled(name)); + content.put("AGENTS.md", rootInstructions(root)); + return Collections.unmodifiableMap(content); + } public static Report install(Path root) { requireSupportedVersion(root); return Filespace.locked(root, () -> { requireSupportedVersion(root); - var content = new LinkedHashMap(); - for (String name : List.of("README.md", "AGENTS.md", "protocol.json")) content.put(".ai-engineering/" + name, bundled(name)); - content.put("AGENTS.md", rootInstructions(root)); + var content = entries(root); var originals = new LinkedHashMap(); for (var item : content.entrySet()) { Path path = Filespace.resolve(root, item.getKey()); diff --git a/src/main/java/net/intrepid/aiengineering/verification/CompatibilityService.java b/src/main/java/net/intrepid/aiengineering/verification/CompatibilityService.java index 6d059dd..d12c2e1 100644 --- a/src/main/java/net/intrepid/aiengineering/verification/CompatibilityService.java +++ b/src/main/java/net/intrepid/aiengineering/verification/CompatibilityService.java @@ -49,6 +49,12 @@ public final class CompatibilityService { try { ProtocolGuide.validate(root); } catch (RuntimeException e) { invalid(findings, ".ai-engineering/protocol.json", "entry-contract", e.getMessage()); } } + try { if (SqliteDatabase.active(root)) return inspectSqlite(root, findings); } + catch (RuntimeException failure) { + findings.add(new Finding(".ai-engineering/aie.db", "sqlite", failure.getMessage() != null && failure.getMessage().contains("Unsupported") ? State.UNSUPPORTED : State.INVALID, + Map.of(), List.of(), failure.getMessage() == null ? "Invalid SQLite storage" : failure.getMessage())); + return report(findings, true); + } Path workspace = Filespace.resolve(root, ".ai-engineering/works"); Path sequence = Filespace.resolve(root, ".ai-engineering/works/.sequence.yaml"); if (Files.exists(sequence)) inspect(root, root.relativize(sequence).toString(), "sequence", WorkService.Sequence.class, null, false, findings); @@ -95,11 +101,44 @@ public final class CompatibilityService { } } catch (RuntimeException ignored) { /* The Work's parse diagnostic was already recorded above. */ } }); - // Presence/version inspection is independent from structural/evidence validation. + return report(findings, false); + } + private Report inspectSqlite(Path root, List findings) { + SqliteDatabase.read(root, connection -> { + findings.add(new Finding(".ai-engineering/aie.db", "sqlite", State.CURRENT, + Map.of("schemaVersion", Integer.toString(SqliteDatabase.SCHEMA_VERSION)), List.of(), "Explicit SQLite backend; no file conversion on read.")); + try (var statement = connection.createStatement(); var rows = statement.executeQuery("SELECT work_id,kind,local_id,revision FROM record_identity ORDER BY work_id,kind,local_id,revision")) { + while (rows.next()) { + String work = rows.getString(1), kind = rows.getString(2), id = rows.getString(3); int revision = rows.getInt(4); + String path = ".ai-engineering/aie.db#" + work + "/" + kind + "/" + id + "/r" + revision; + try { + Class type = switch (kind) { + case "work" -> Work.class; case "discussion" -> DiscussionEntry.class; case "decision" -> Decision.class; + case "plan" -> Plan.class; case "topic" -> Topic.class; case "survey" -> Survey.class; case "disposition" -> Disposition.class; + case "epic" -> Epic.class; case "run" -> AgentRun.class; case "artifact" -> Artifact.class; + case "gate" -> QualityGates.Result.class; case "receipt" -> net.intrepid.aiengineering.artifact.ProtocolReceipt.class; + default -> throw ProtocolException.validation("Unknown SQLite record kind: " + kind); + }; + SqliteRecords.get(root, work, kind, id, revision, type); + if (SqliteRecords.current(root, work, kind, id) == 0) throw ProtocolException.validation("Missing current record pointer"); + findings.add(new Finding(path, kind, State.CURRENT, Map.of("schemaVersion", "1"), List.of(), "Readable typed SQLite record.")); + } catch (RuntimeException failure) { + findings.add(new Finding(path, kind, failure.getMessage() != null && failure.getMessage().contains("Unsupported") ? State.UNSUPPORTED : State.INVALID, + Map.of(), List.of(), failure.getMessage() == null ? "Invalid SQLite record" : failure.getMessage())); + } + } + } + return null; + }); + return report(findings, true); + } + private Report report(List findings, boolean sqlite) { + // Presence/version inspection is independent from completion readiness. State state = findings.stream().map(Finding::state).max(Comparator.naturalOrder()).orElse(State.CURRENT); boolean readable = state == State.CURRENT || state == State.LEGACY_COMPATIBLE; var guidance = new ArrayList(); - if (readable) guidance.add("No migration is required. Keep readable historical and COMPLETED Works in their existing formats."); + if (readable) guidance.add(sqlite ? "SQLite is selected explicitly. Use the CLI for engineering memory; reads do not migrate data." + : "No migration is required for legacy reading. Keep readable historical and COMPLETED Works in their existing formats."); else guidance.add("Unsupported versions require a compatible CLI; invalid files require deliberate repair. No migration route is inferred."); guidance.add("onboard refreshes entry instructions only, with backups; it does not convert Works or their history."); guidance.add("Compatibility describes storage readability, not completion readiness or evidence integrity. Run aie project validate separately."); diff --git a/src/main/java/net/intrepid/aiengineering/verification/EpicCoordinator.java b/src/main/java/net/intrepid/aiengineering/verification/EpicCoordinator.java index 8139c8e..5969520 100644 --- a/src/main/java/net/intrepid/aiengineering/verification/EpicCoordinator.java +++ b/src/main/java/net/intrepid/aiengineering/verification/EpicCoordinator.java @@ -96,7 +96,7 @@ public final class EpicCoordinator { if (ids.size() != 1) throw ProtocolException.validation("System EPIC completion requires one owned aggregate receipt"); var artifact = artifacts.list(root, work.id()).stream().filter(a -> a.id().equals(ids.getFirst())).findFirst() .orElseThrow(() -> ProtocolException.validation("Missing EPIC receipt artifact")); - var receipt = Documents.readJson(Filespace.resolve(works.folder(root, work.id()), artifact.path()), Receipt.class); + var receipt = artifacts.readReceipt(root, work.id(), artifact, Receipt.class); if (!receipt.workId().equals(work.id()) || !receipt.policyHash().equals(delegation.policyHash()) || !artifact.author().equals("system:epic") || !artifact.origin().equals(RECEIPT_ORIGIN + Revisions.hash(Documents.json(receipt)))) throw ProtocolException.validation("Invalid EPIC receipt provenance"); @@ -123,18 +123,18 @@ public final class EpicCoordinator { var existing = artifacts.list(root, definition.workId()).stream().filter(a -> a.origin().equals(origin)).toList(); if (existing.size() > 1) throw ProtocolException.validation("Duplicate EPIC receipts for the same inputs"); Artifact evidence; - if (existing.isEmpty()) evidence = artifacts.attachBytes(root, definition.workId(), json.getBytes(java.nio.charset.StandardCharsets.UTF_8), + if (existing.isEmpty()) evidence = artifacts.attachReceipt(root, definition.workId(), receipt, "Deterministic EPIC aggregate receipt under explicitly authorized policy", origin, "system:epic"); else { evidence = existing.getFirst(); artifacts.validate(root, definition.workId()); - if (!Filespace.read(Filespace.resolve(works.folder(root, definition.workId()), evidence.path())).equals(json)) throw ProtocolException.validation("Conflicting EPIC receipt content"); + if (!Documents.json(artifacts.readReceipt(root, definition.workId(), evidence, Receipt.class)).equals(json)) throw ProtocolException.validation("Conflicting EPIC receipt content"); } var current = works.load(root, definition.workId()); var criteria = new ArrayList(); for (int i = 0; i < current.acceptanceCriteria().size(); i++) criteria.add(new Work.CriterionResult(i + 1, current.acceptanceCriteria().get(i), List.of(evidence.id()))); var completion = new Work.Completion(Instant.now().toString(), "system:epic", "Authorized aggregate condition satisfied; requester=" + requester, false, verification.scopeHash(root, current), criteria, List.of(), "Coordination-only delivery; canonical integration is evidenced by the child completions", Work.CompletionOrigin.SYSTEM_EPIC, new Work.Delegation(receipt.policyHash(), definition.authorization(), trigger, requester, requestId)); - return works.recordCompletion(root, current.id(), completion); + return verification.recordCompletion(root, current.id(), completion); } private Set selected(Map definitions, String target) { if (target == null) return new HashSet<>(definitions.keySet()); diff --git a/src/main/java/net/intrepid/aiengineering/verification/PlanCoordinator.java b/src/main/java/net/intrepid/aiengineering/verification/PlanCoordinator.java index 08313c0..f7e976b 100644 --- a/src/main/java/net/intrepid/aiengineering/verification/PlanCoordinator.java +++ b/src/main/java/net/intrepid/aiengineering/verification/PlanCoordinator.java @@ -69,7 +69,7 @@ public final class PlanCoordinator { var aggregation = completion.aggregation(); var artifact = artifacts.list(root, work.id()).stream().filter(a -> a.id().equals(aggregation.receipt())).findFirst() .orElseThrow(() -> ProtocolException.validation("Missing Plan aggregate receipt")); - var receipt = Documents.readJson(Filespace.resolve(works.folder(root, work.id()), artifact.path()), Receipt.class); + var receipt = artifacts.readReceipt(root, work.id(), artifact, Receipt.class); if (!receipt.workId().equals(work.id()) || !receipt.inputHash().equals(aggregation.inputHash()) || !artifact.author().equals("system:plans") || !artifact.origin().equals(RECEIPT_ORIGIN + Revisions.hash(Documents.json(receipt)))) throw ProtocolException.validation("Invalid Plan receipt provenance"); @@ -108,15 +108,15 @@ public final class PlanCoordinator { var existing = artifacts.list(root, id).stream().filter(a -> a.origin().equals(origin)).toList(); if (existing.size() > 1) throw ProtocolException.validation("Duplicate Plan receipts for the same inputs"); Artifact artifact; - if (existing.isEmpty()) artifact = artifacts.attachBytes(root, id, json.getBytes(java.nio.charset.StandardCharsets.UTF_8), + if (existing.isEmpty()) artifact = artifacts.attachReceipt(root, id, receipt, "Deterministic aggregation of completed Plans and reviewed cancellations; not semantic verification of prose criteria", origin, "system:plans"); else { artifact = existing.getFirst(); artifacts.validate(root, id); - if (!Filespace.read(Filespace.resolve(works.folder(root, id), artifact.path())).equals(json)) throw ProtocolException.validation("Conflicting Plan receipt content"); + if (!Documents.json(artifacts.readReceipt(root, id, artifact, Receipt.class)).equals(json)) throw ProtocolException.validation("Conflicting Plan receipt content"); } work = works.load(root, id); var criteria = new ArrayList(); for (int i = 0; i < work.acceptanceCriteria().size(); i++) criteria.add(new Work.CriterionResult(i + 1, work.acceptanceCriteria().get(i), List.of(artifact.id()))); - works.recordCompletion(root, id, new Work.Completion(Instant.now().toString(), "system:plans", "All required Plans completed; requester=" + requester, + verification.recordCompletion(root, id, new Work.Completion(Instant.now().toString(), "system:plans", "All required Plans completed; requester=" + requester, false, verification.scopeHash(root, work), criteria, List.of(), "Canonical changes and execution results are recorded in the Plan step evidence", Work.CompletionOrigin.SYSTEM_PLANS, null, new Work.Aggregation(artifact.id(), receipt.inputHash(), requester, requestId))); } @@ -126,7 +126,11 @@ public final class PlanCoordinator { requireValid(root, id); new EpicService().definitions(root); T result = operation.get(); try { return new Mutation<>(result, reconcile(root, id, requester, key)); } - catch (RuntimeException failure) { throw persisted(id, failure); } + catch (RuntimeException failure) { + if (SqliteDatabase.active(root)) throw new ProtocolException(failure instanceof ProtocolException p ? p.exitCode() : 1, + "Change rolled back for " + id + "; inspect coordination: " + failure.getMessage()); + throw persisted(id, failure); + } }); } public static ProtocolException persisted(String id, RuntimeException failure) { diff --git a/src/main/java/net/intrepid/aiengineering/verification/QualityGates.java b/src/main/java/net/intrepid/aiengineering/verification/QualityGates.java new file mode 100644 index 0000000..80690e1 --- /dev/null +++ b/src/main/java/net/intrepid/aiengineering/verification/QualityGates.java @@ -0,0 +1,232 @@ +package net.intrepid.aiengineering.verification; + +import net.intrepid.aiengineering.artifact.ArtifactService; +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.project.ProjectConfig; +import net.intrepid.aiengineering.work.*; +import java.nio.file.*; +import java.time.Instant; +import java.util.*; + +/** Records externally observed checks. Never executes a repository command or infers human approval. */ +public final class QualityGates { + public record Definition(String scope, String id, String title, String procedure, List inputs, + boolean evidenceRequired, int revision, String updatedBy) { + public Definition { + if (!"project".equals(scope)) Work.identifier(scope, "WRK"); + ProjectConfig.identifier(id); ProtocolException.text(title, "gate title"); + ProtocolException.text(procedure, "gate procedure"); ProtocolException.text(updatedBy, "gate actor"); + inputs = List.copyOf(inputs); + if (inputs.isEmpty() || new HashSet<>(inputs).size() != inputs.size() || revision < 1) + throw ProtocolException.invalid("Gate requires unique input paths and a positive revision"); + inputs.forEach(path -> ProtocolException.text(path, "gate input")); + } + public String key() { return scope + "/" + id; } + } + public enum Outcome { PASS, FAIL } + public record Result(int schemaVersion, String id, String workId, Definition definition, String evaluatedHash, + String invocation, Outcome outcome, String summary, List evidence, String by, String observedAt) { + public Result { + ProtocolException.schema(schemaVersion); Work.identifier(id, "GAT"); Work.identifier(workId, "WRK"); + Objects.requireNonNull(definition); Objects.requireNonNull(outcome); + if (evaluatedHash == null || !evaluatedHash.matches("[a-f0-9]{64}")) throw ProtocolException.validation("Invalid evaluated gate hash"); + ProtocolException.text(invocation, "observed invocation"); ProtocolException.text(summary, "gate summary"); + if (summary.length() > 2000) throw ProtocolException.invalid("Gate summary exceeds 2000 characters; attach temporary detail instead"); + ProtocolException.text(by, "gate observer"); Instant.parse(observedAt); evidence = List.copyOf(evidence); + } + } + public record View(Definition definition, String evaluatedHash, Result latest, boolean satisfied, String pending) {} + private final WorkService works = new WorkService(); + private void sqlite(Path root) { + if (!SqliteDatabase.active(root)) throw ProtocolException.validation("Quality gates require SQLite; use the explicit storage migration first"); + } + public Definition configure(Path root, String scope, String id, String title, String procedure, + List inputs, boolean evidenceRequired, String by) { + sqlite(root); + var candidate = new Definition(scope, id, title, procedure, inputs, evidenceRequired, 1, by); + for (String input : candidate.inputs()) input(root, input); + return Filespace.locked(root, () -> { + if (!scope.equals("project")) works.editable(root, scope); + int revision = definitions(root, scope).stream().filter(d -> d.id().equals(id)).mapToInt(Definition::revision).max().orElse(0) + 1; + var definition = new Definition(scope, id, title, procedure, inputs, evidenceRequired, revision, by); + return SqliteDatabase.write(root, connection -> { + try (var statement = connection.prepareStatement("INSERT INTO quality_gate VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(scope,gate_id) DO UPDATE SET title=excluded.title,procedure=excluded.procedure,evidence_required=excluded.evidence_required,revision=excluded.revision,updated_by=excluded.updated_by")) { + statement.setString(1, scope); statement.setString(2, id); statement.setString(3, scope.equals("project") ? null : scope); + statement.setString(4, title); statement.setString(5, procedure); statement.setInt(6, evidenceRequired ? 1 : 0); + statement.setInt(7, revision); statement.setString(8, by); statement.executeUpdate(); + } + try (var statement = connection.prepareStatement("DELETE FROM quality_gate_input WHERE scope=? AND gate_id=?")) { + statement.setString(1, scope); statement.setString(2, id); statement.executeUpdate(); + } + try (var statement = connection.prepareStatement("INSERT INTO quality_gate_input VALUES (?,?,?,?)")) { + int ordinal = 0; + for (String input : inputs) { + statement.setString(1, scope); statement.setString(2, id); statement.setInt(3, ordinal++); statement.setString(4, input); statement.addBatch(); + } + statement.executeBatch(); + } + return definition; + }); + }); + } + private List definitions(Path root, String scope) { + return SqliteDatabase.read(root, connection -> { + var result = new ArrayList(); + try (var statement = connection.prepareStatement("SELECT gate_id,title,procedure,evidence_required,revision,updated_by FROM quality_gate WHERE scope=? ORDER BY gate_id")) { + statement.setString(1, scope); + try (var rows = statement.executeQuery()) { + while (rows.next()) { + var inputs = new ArrayList(); + try (var child = connection.prepareStatement("SELECT path FROM quality_gate_input WHERE scope=? AND gate_id=? ORDER BY ordinal")) { + child.setString(1, scope); child.setString(2, rows.getString(1)); + try (var values = child.executeQuery()) { while (values.next()) inputs.add(values.getString(1)); } + } + result.add(new Definition(scope, rows.getString(1), rows.getString(2), rows.getString(3), inputs, rows.getBoolean(4), rows.getInt(5), rows.getString(6))); + } + } + } + return List.copyOf(result); + }); + } + public List definitions(Path root, String work, boolean includeProject) { + if (!SqliteDatabase.active(root)) return List.of(); + works.load(root, work); + var all = new ArrayList(); + if (includeProject) all.addAll(definitions(root, "project")); + all.addAll(definitions(root, work)); return List.copyOf(all); + } + private Path input(Path root, String relative) { + Path path = Filespace.resolve(root, relative); + if (path.startsWith(root.resolve(".ai-engineering")) || path.startsWith(root.resolve(".git"))) + throw ProtocolException.invalid("Gate inputs must be outside AIE state and Git internals: " + relative); + if (!Files.exists(path, LinkOption.NOFOLLOW_LINKS)) throw ProtocolException.validation("Missing gate input: " + relative); + return path; + } + private boolean excluded(Path root, Path path) { + Path relative = root.relativize(path); + return relative.getNameCount() > 0 && Set.of(".ai-engineering", ".git").contains(relative.getName(0).toString()); + } + public String fingerprint(Path root, String work, Definition definition) { + var hashes = new TreeMap(); + for (String relative : definition.inputs()) { + Path selected = input(root, relative); + try (var paths = Filespace.io(() -> Files.walk(selected))) { + for (Path path : paths.filter(path -> !excluded(root, path)).sorted().toList()) { + Filespace.resolve(root, root.relativize(path).toString()); + if (Files.isDirectory(path, LinkOption.NOFOLLOW_LINKS)) { + hashes.put(root.relativize(path).toString(), "directory"); continue; + } + if (!Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)) throw ProtocolException.validation("Unsupported gate input: " + path); + hashes.put(root.relativize(path).toString(), Revisions.hash(Filespace.io(() -> Files.readAllBytes(path)))); + } + } catch (java.io.UncheckedIOException failure) { throw new ProtocolException(1, "Cannot read gate inputs: " + failure.getMessage()); } + } + return SqliteDatabase.read(root, connection -> { + var w = works.load(root, work); var data = new LinkedHashMap(); + data.put("definition", definition); data.put("files", hashes); + data.put("scope", List.of(w.id(), w.title(), w.description(), w.goal(), w.motivation(), w.constraints(), w.acceptanceCriteria(), w.repositories())); + data.put("guidance", w.guidance()); + var decisions = new ArrayList(); + try (var statement = connection.prepareStatement("SELECT local_id,revision FROM current_record WHERE work_id=? AND kind='decision' ORDER BY local_id")) { + statement.setString(1, work); + try (var rows = statement.executeQuery()) { while (rows.next()) decisions.add(rows.getString(1) + ":" + rows.getInt(2)); } + } + data.put("decisions", decisions); return Revisions.hash(Documents.json(data)); + }); + } + public List history(Path root, String work) { + if (!SqliteDatabase.active(root)) return List.of(); + works.load(root, work); + return SqliteDatabase.read(root, connection -> SqliteRecords.ids(root, "gate", work).stream() + .map(id -> SqliteRecords.get(root, work, "gate", id, 0, Result.class)) + .sorted(Comparator.comparingLong(result -> Long.parseLong(result.id().substring(4)))).toList()); + } + public List inspect(Path root, String work) { + if (!SqliteDatabase.active(root)) return List.of(); + return SqliteDatabase.read(root, connection -> { + var history = history(root, work); var views = new ArrayList(); + for (var definition : definitions(root, work, true)) { + var latest = history.stream().filter(r -> r.definition().key().equals(definition.key())).reduce((a, b) -> b).orElse(null); + String hash; + try { hash = fingerprint(root, work, definition); } + catch (ProtocolException problem) { views.add(new View(definition, null, latest, false, problem.getMessage())); continue; } + boolean current = latest != null && latest.definition().equals(definition) && latest.evaluatedHash().equals(hash); + boolean satisfied = current && latest.outcome() == Outcome.PASS; + views.add(new View(definition, hash, latest, satisfied, satisfied ? "" : !current ? "Not evaluated for the current state" : "Latest evaluation failed")); + } + return List.copyOf(views); + }); + } + public List pending(Path root, String work) { + return inspect(root, work).stream().filter(view -> !view.satisfied()).map(view -> "Gate " + view.definition().key() + ": " + view.pending()).toList(); + } + public Result record(Path root, String work, String gateKey, String expected, String invocation, + Outcome outcome, String summary, List evidence, String by, boolean observed) { + sqlite(root); + if (!observed) throw ProtocolException.invalid("--observed is required to attest an actual external evaluation"); + return Filespace.locked(root, () -> { + var w = works.editable(root, work); + var definition = definitions(root, work, true).stream().filter(d -> d.key().equals(gateKey)).findFirst() + .orElseThrow(() -> ProtocolException.missing("Gate not configured: " + gateKey)); + String hash = fingerprint(root, work, definition); + if (!hash.equals(expected)) throw ProtocolException.validation("Gate state changed or --expect differs; evaluate the current fingerprint"); + if (definition.evidenceRequired() && evidence.isEmpty()) throw ProtocolException.validation("Gate requires temporary evidence"); + if (!w.artifacts().containsAll(evidence)) throw ProtocolException.invalid("Unknown gate evidence"); + new ArtifactService().validate(root, work); + new ArtifactService().requireAvailable(root, work, evidence); + String id = works.nextReference(SqliteRecords.ids(root, "gate", work), "GAT"); + var result = new Result(1, id, work, definition, hash, invocation, outcome, summary, evidence, by, Instant.now().toString()); + if (!hash.equals(fingerprint(root, work, definition))) throw ProtocolException.validation("Gate inputs changed while recording the evaluation"); + SqliteRecords.put(root, work, "gate", id, result, Result.class, false, 1); return result; + }); + } + public void freeze(Path root, Work work, String completedAt) { + if (!SqliteDatabase.active(root)) return; + var views = inspect(root, work.id()); + var pending = views.stream().filter(v -> !v.satisfied()).map(v -> v.definition().key()).toList(); + if (!pending.isEmpty()) throw ProtocolException.validation("Required gates pending: " + pending); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.prepareStatement("INSERT INTO quality_delivery VALUES (?,?,?)")) { + statement.setString(1, work.id()); statement.setString(2, completedAt); statement.setInt(3, views.size()); statement.executeUpdate(); + } + try (var statement = connection.prepareStatement("INSERT INTO quality_delivery_gate(work_id,completed_at,gate_key,result_id,result_sha256) VALUES (?,?,?,?,?)")) { + for (var view : views) { + statement.setString(1, work.id()); statement.setString(2, completedAt); statement.setString(3, view.definition().key()); + statement.setString(4, view.latest().id()); statement.setString(5, Revisions.hash(Documents.json(view.latest()))); statement.addBatch(); + } + statement.executeBatch(); + } + return null; + }); + } + public void validateHistory(Path root, Work work) { + if (!SqliteDatabase.active(root)) return; + SqliteDatabase.read(root, connection -> { + for (var completion : work.completions()) { + int count; + try (var statement = connection.prepareStatement("SELECT gate_count FROM quality_delivery WHERE work_id=? AND completed_at=?")) { + statement.setString(1, work.id()); statement.setString(2, completion.at()); + try (var row = statement.executeQuery()) { + if (!row.next()) throw ProtocolException.validation("Missing delivered gate snapshot: " + work.id()); + count = row.getInt(1); + } + } + int found = 0; + try (var statement = connection.prepareStatement("SELECT gate_key,result_id,result_sha256 FROM quality_delivery_gate WHERE work_id=? AND completed_at=?")) { + statement.setString(1, work.id()); statement.setString(2, completion.at()); + try (var rows = statement.executeQuery()) { + while (rows.next()) { + var result = SqliteRecords.get(root, work.id(), "gate", rows.getString(2), 1, Result.class); + if (result.outcome() != Outcome.PASS || !result.definition().key().equals(rows.getString(1)) + || !Revisions.hash(Documents.json(result)).equals(rows.getString(3))) + throw ProtocolException.validation("Invalid delivered gate result"); + found++; + } + } + } + if (count != found) throw ProtocolException.validation("Incomplete delivered gate snapshot"); + } + return null; + }); + } +} diff --git a/src/main/java/net/intrepid/aiengineering/verification/StorageMigration.java b/src/main/java/net/intrepid/aiengineering/verification/StorageMigration.java new file mode 100644 index 0000000..faf4842 --- /dev/null +++ b/src/main/java/net/intrepid/aiengineering/verification/StorageMigration.java @@ -0,0 +1,328 @@ +package net.intrepid.aiengineering.verification; + +import net.intrepid.aiengineering.agent.AgentRun; +import net.intrepid.aiengineering.artifact.Artifact; +import net.intrepid.aiengineering.decision.Decision; +import net.intrepid.aiengineering.discussion.*; +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.planning.Plan; +import net.intrepid.aiengineering.project.*; +import net.intrepid.aiengineering.work.*; +import java.nio.file.*; +import java.nio.file.attribute.BasicFileAttributes; +import java.util.*; +import java.util.function.Consumer; + +/** Explicit one-project conversion. Originals and the active native installation are never edited. */ +public final class StorageMigration { + private static final String JOURNAL = ".ai-engineering/.local/sqlite-migration/state.json"; + private static final String GUARD = ".ai-engineering/works/SQLITE-STORAGE"; + private static final String GUARD_TEXT = "SQLite is authoritative. Use a CLI supporting protocol contract 4. Legacy Work documents are retained originals, not writable state.\n"; + public record State(String operation, String phase, String fingerprint, Map sourceHashes, + Map publishedHashes, String databaseHash) { + public State { + if (!operation.matches("[0-9a-f-]{36}")) throw ProtocolException.validation("Invalid migration operation"); + sourceHashes = Collections.unmodifiableMap(new TreeMap<>(sourceHashes)); + publishedHashes = Collections.unmodifiableMap(new TreeMap<>(publishedHashes)); + } + State phase(String next) { return new State(operation, next, fingerprint, sourceHashes, publishedHashes, databaseHash); } + } + public record Report(int schemaVersion, boolean valid, String phase, String fingerprint, int works, + String backup, List issues, String nextAction) { + public Report { issues = List.copyOf(issues); } + } + private final Consumer boundary; + public StorageMigration() { this(phase -> {}); } + /** Package-local fault injection for disposable recovery fixtures. */ + StorageMigration(Consumer boundary) { this.boundary = boundary; } + private static String relative(Path root, Path path) { return root.relativize(path).toString().replace('\\', '/'); } + private static String hash(Path path) { return Revisions.hash(Filespace.io(() -> Files.readAllBytes(path))); } + private static Path operation(Path root, State state) { return Filespace.resolve(root, ".ai-engineering/.local/sqlite-migration/" + state.operation()); } + private static Path original(Path root, State state) { return operation(root, state).resolve("original"); } + private static Path stage(Path root, State state) { return operation(root, state).resolve("stage"); } + private State state(Path root) { + Path path = Filespace.resolve(root, JOURNAL); + return Files.exists(path) ? Documents.readJson(path, State.class) : null; + } + private void save(Path root, State state) { + Path path = Filespace.resolve(root, JOURNAL); Filespace.directory(path.getParent()); + Filespace.write(path, Documents.json(state), Files.exists(path)); + } + public static void requireStable(Path root) { + var state = new StorageMigration().state(root); + if (state != null && !List.of("APPLIED", "ROLLED_BACK").contains(state.phase())) + throw ProtocolException.validation("SQLite migration is " + state.phase() + "; use aie storage migrate --recover or --rollback --expect " + state.fingerprint()); + } + private TreeMap capture(Path root) { + var hashes = new TreeMap(); + Filespace.io(() -> { + Files.walkFileTree(Filespace.resolve(root, ".ai-engineering"), new SimpleFileVisitor<>() { + @Override public FileVisitResult preVisitDirectory(Path path, BasicFileAttributes attributes) { + Filespace.resolve(root, relative(root, path)); + return path.equals(root.resolve(".ai-engineering/.local")) ? FileVisitResult.SKIP_SUBTREE : FileVisitResult.CONTINUE; + } + @Override public FileVisitResult visitFile(Path path, BasicFileAttributes attributes) { + Path safe = Filespace.resolve(root, relative(root, path)); + if (!attributes.isRegularFile()) throw ProtocolException.validation("Unsupported migration source: " + path); + hashes.put(relative(root, path), hash(safe)); return FileVisitResult.CONTINUE; + } + }); + return null; + }); + for (String name : List.of("AGENTS.md", ".gitignore")) { + Path path = Filespace.resolve(root, name); + if (Files.exists(path)) { + if (!Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)) throw ProtocolException.validation("Invalid bootstrap source: " + name); + hashes.put(name, hash(path)); + } + } + return hashes; + } + public Report preview(Path root) { + State state = state(root); + if (state != null && !state.phase().equals("ROLLED_BACK")) return report(root, state, List.of()); + var issues = new ArrayList(); var hashes = new TreeMap(); int count = 0; + try { + if (SqliteDatabase.active(root)) return new Report(1, true, "ALREADY_SQLITE", null, new WorkService().list(root).size(), null, List.of(), "No conversion required."); + if (Files.exists(SqliteDatabase.path(root))) throw ProtocolException.validation("Unselected database already exists; inspect it before migration"); + ProtocolGuide.requireSupportedVersion(root); + var validation = new VerificationService().project(root); issues.addAll(validation.issues()); + count = new WorkService().list(root).size(); hashes = capture(root); + } catch (RuntimeException failure) { issues.add(failure.getMessage()); } + return new Report(1, issues.isEmpty(), "LEGACY", Revisions.hash(Documents.json(hashes)), count, null, issues, + "Review this preview; apply with storage migrate --apply --expect . No consumer is migrated automatically."); + } + private Report report(Path root, State state, List issues) { + int count = (int) state.sourceHashes().keySet().stream().filter(path -> path.matches("\\.ai-engineering/works/WRK-[^/]+/work\\.md")).count(); + return new Report(1, issues.isEmpty(), state.phase(), state.fingerprint(), count, relative(root, original(root, state)), issues, + state.phase().equals("APPLIED") ? "SQLite active; originals retained. Native installation is unchanged." + : "Use storage migrate --recover or --rollback --expect " + state.fingerprint()); + } + public Report apply(Path root, String expected) { + return Filespace.lockedLegacy(root, () -> { + State previous = state(root); + if (previous != null && !previous.phase().equals("ROLLED_BACK")) { + expect(previous, expected); + if (previous.phase().equals("APPLIED")) { removeStage(stage(root, previous)); return report(root, previous, List.of()); } + throw ProtocolException.validation("Interrupted migration; use --recover or --rollback with its fingerprint"); + } + var preview = preview(root); + if (!preview.valid() || !preview.phase().equals("LEGACY")) throw ProtocolException.validation("Migration preview is not applicable: " + preview.issues()); + if (!Objects.equals(preview.fingerprint(), expected)) throw ProtocolException.validation("Migration preview changed; preview again"); + State current = new State(UUID.randomUUID().toString(), "PREPARING", expected, capture(root), Map.of(), null); + save(root, current); + try { return prepareAndActivate(root, current); } + catch (RuntimeException failure) { throw interrupted(current, failure); } + }); + } + private ProtocolException interrupted(State state, RuntimeException failure) { + return new ProtocolException(failure instanceof ProtocolException p ? p.exitCode() : 1, + "Migration interrupted; originals retained. Use storage migrate --recover or --rollback --expect " + state.fingerprint() + ": " + failure.getMessage()); + } + private void expect(State state, String expected) { + if (!Objects.equals(expected, state.fingerprint())) throw ProtocolException.validation("Expected fingerprint differs from the migration journal"); + } + public Report recover(Path root, String expected, boolean rollback) { + return Filespace.lockedLegacy(root, () -> { + State current = state(root); + if (current == null) throw ProtocolException.missing("No SQLite migration journal; run preview first"); + expect(current, expected); + if (rollback) return rollback(root, current); + if (current.phase().equals("APPLIED")) { removeStage(stage(root, current)); return report(root, current, List.of()); } + if (current.phase().equals("ROLLED_BACK")) throw ProtocolException.validation("Migration rolled back; preview before a new application"); + try { return current.databaseHash() == null ? prepareAndActivate(root, current) : activate(root, current); } + catch (RuntimeException failure) { throw interrupted(current, failure); } + }); + } + private void copyChecked(Path fromRoot, Path toRoot, Map hashes) { + for (var entry : hashes.entrySet()) { + Path source = Filespace.resolve(fromRoot, entry.getKey()), target = Filespace.resolve(toRoot, entry.getKey()); + if (!hash(source).equals(entry.getValue())) throw ProtocolException.validation("Migration source changed: " + entry.getKey()); + Filespace.directory(target.getParent()); + if (Files.exists(target)) { + if (!hash(target).equals(entry.getValue())) throw ProtocolException.validation("Migration safety copy differs: " + target); + } else Filespace.writeBytes(target, Filespace.io(() -> Files.readAllBytes(source)), false); + } + } + private void removeStage(Path directory) { + if (!Files.exists(directory)) return; + try (var paths = Filespace.io(() -> Files.walk(directory))) { + for (Path path : paths.sorted(Comparator.reverseOrder()).toList()) { + if (!path.equals(directory)) Filespace.resolve(directory, relative(directory, path)); + Filespace.io(() -> { Files.delete(path); return null; }); + } + } + } + private Report prepareAndActivate(Path root, State state) { + if (!capture(root).equals(state.sourceHashes())) throw ProtocolException.validation("Legacy source changed since preview; rollback and preview again"); + Path originals = original(root, state); Filespace.directory(originals); + copyChecked(root, originals, state.sourceHashes()); + Filespace.directory(originals.resolve(".ai-engineering/works")); + boundary.accept("BACKUP_READY"); + Path staging = stage(root, state); removeStage(staging); Filespace.directory(staging); + var config = new ProjectService().load(originals); + new ProjectService().initializeSqlite(staging, config.project().name(), false); + Filespace.write(staging.resolve(".ai-engineering/ai-engineering.yaml"), Documents.yaml( + new ProjectConfig(1, config.project(), config.repositories(), config.agents(), "sqlite")), true); + // Provenance paths have the same project-relative spelling before and after activation. + Path stageOriginals = Filespace.resolve(staging, relative(root, originals)); Filespace.directory(stageOriginals); + copyChecked(originals, stageOriginals, state.sourceHashes()); + var legacyWorks = new WorkService().list(originals); + var payloads = new TreeMap(); + state.sourceHashes().forEach((path, digest) -> { if (path.startsWith(".ai-engineering/works/")) payloads.put(path, digest); }); + copyChecked(originals, staging, payloads); + for (var work : legacyWorks) { + Path folder = staging.resolve(".ai-engineering/works/" + new WorkService().folder(originals, work.id()).getFileName()); + for (String directory : List.of("discussions", "decisions", "plans", "artifacts/references", "artifacts/experiments", "artifacts/evidence", "artifacts/outputs", "runs")) + Filespace.directory(Filespace.resolve(folder, directory)); + } + importRecords(root, staging, originals, state, legacyWorks); + for (var work : legacyWorks) { + var validation = new VerificationService().work(staging, work.id()); + if (!validation.valid()) throw ProtocolException.validation("Staged " + work.id() + ": " + validation.issues()); + } + new EpicService().definitions(staging); + SqliteDatabase.checkpoint(staging); + state = new State(state.operation(), "STAGED", state.fingerprint(), state.sourceHashes(), Map.of(), hash(SqliteDatabase.path(staging))); + save(root, state); boundary.accept("STAGE_VALIDATED"); + return activate(root, state); + } + private void record(Path destination, Path originals, State state, String work, String kind, String id, + Path source, Class type, String body) { + T latest = Documents.readMarkdownDocument(source, type, body); + var tree = Documents.jsonTree(latest); int last = tree.hasNonNull("revision") ? tree.get("revision").intValue() : 1; + for (int revision = 1; revision <= last; revision++) { + Path file = revision == last ? source : source.getParent().resolve(".history/" + id + "/r%04d.md".formatted(revision)); + T value = Documents.readMarkdownDocument(file, type, body); + int version = Documents.metadata(file).has("documentVersion") ? Documents.metadata(file).get("documentVersion").intValue() : 1; + SqliteRecords.put(destination, work, kind, id, value, type, revision != 1, version); + if (!Objects.equals(value, SqliteRecords.get(destination, work, kind, id, revision, type))) + throw ProtocolException.validation("Typed migration comparison failed: " + id); + provenance(destination, work, kind, id, revision, ".ai-engineering/.local/sqlite-migration/" + state.operation() + "/original/" + relative(originals, file), hash(file)); + } + } + private void provenance(Path root, String work, String kind, String id, int revision, String source, String digest) { + SqliteDatabase.write(root, connection -> { + try (var statement = connection.prepareStatement("UPDATE record_format SET original_path=?,original_sha256=? WHERE work_id=? AND kind=? AND local_id=? AND revision=?")) { + statement.setString(1, source); statement.setString(2, digest); statement.setString(3, work); statement.setString(4, kind); statement.setString(5, id); statement.setInt(6, revision); + if (statement.executeUpdate() != 1) throw ProtocolException.validation("Missing migration provenance target"); + } + return null; + }); + } + private void importRecords(Path root, Path staging, Path originals, State state, List all) { + var works = new WorkService(); + SqliteDatabase.write(staging, connection -> { + for (var work : all) { + try (var identity = connection.prepareStatement("INSERT INTO work_identity VALUES (?)"); var location = connection.prepareStatement("INSERT INTO work_location VALUES (?,?)")) { + identity.setString(1, work.id()); identity.executeUpdate(); location.setString(1, work.id()); + location.setString(2, works.folder(originals, work.id()).getFileName().toString()); location.executeUpdate(); + } + } + for (var work : all) { + Path folder = works.folder(originals, work.id()); + for (String id : work.discussions()) record(staging, originals, state, work.id(), "discussion", id, folder.resolve("discussions/" + id + ".md"), DiscussionEntry.class, "text"); + for (String id : work.topics()) record(staging, originals, state, work.id(), "topic", id, folder.resolve("topics/" + id + ".md"), Topic.class, "description"); + for (String id : work.surveys()) record(staging, originals, state, work.id(), "survey", id, folder.resolve("surveys/" + id + ".md"), Survey.class, "description"); + for (String id : work.dispositions()) record(staging, originals, state, work.id(), "disposition", id, folder.resolve("dispositions/" + id + ".md"), Disposition.class, "reason"); + for (String id : work.decisions()) record(staging, originals, state, work.id(), "decision", id, folder.resolve("decisions/" + id + ".md"), Decision.class, "text"); + for (String id : work.plans()) record(staging, originals, state, work.id(), "plan", id, folder.resolve("plans/" + id + ".md"), Plan.class, "description"); + for (String id : work.agentRuns()) record(staging, originals, state, work.id(), "run", id, folder.resolve("agent-runs/" + id + ".md"), AgentRun.class, "task"); + if (work.epic()) record(staging, originals, state, work.id(), "epic", work.id(), folder.resolve("epic/" + work.id() + ".md"), Epic.class, "reason"); + for (String id : work.artifacts()) { + var artifact = Documents.read(folder.resolve("artifacts/evidence/" + id + "/artifact.yaml"), Artifact.class); + SqliteRecords.put(staging, work.id(), "artifact", id, artifact, Artifact.class, false, 1); + try (var statement = connection.prepareStatement("INSERT INTO artifact_lifecycle(work_id,artifact_id,state) VALUES (?,?,'RETAINED_LEGACY')")) { + statement.setString(1, work.id()); statement.setString(2, id); statement.executeUpdate(); + } + } + } + for (var work : all) { + record(staging, originals, state, work.id(), "work", work.id(), works.folder(originals, work.id()).resolve("work.md"), Work.class, null); + for (var completion : work.completions()) try (var statement = connection.prepareStatement("INSERT INTO quality_delivery VALUES (?,?,0)")) { + statement.setString(1, work.id()); statement.setString(2, completion.at()); statement.executeUpdate(); + } + } + Path counter = originals.resolve(".ai-engineering/works/.sequence.yaml"); + long highWater = Files.exists(counter) ? Documents.read(counter, WorkService.Sequence.class).number() : 0; + highWater = Math.max(highWater, all.stream().mapToLong(work -> Work.number(work.id())).max().orElse(0)); + try (var statement = connection.prepareStatement("UPDATE identity_sequence SET high_water=? WHERE scope='project' AND kind='work'")) { + statement.setLong(1, highWater); statement.executeUpdate(); + } + return null; + }); + } + private Report activate(Path root, State state) { + var observed = capture(root); + observed.keySet().removeIf(path -> path.matches("\\.ai-engineering/aie\\.db(?:-wal|-shm|-journal)?")); + for (var entry : observed.entrySet()) { + if (!entry.getValue().equals(state.sourceHashes().get(entry.getKey())) && !entry.getValue().equals(state.publishedHashes().get(entry.getKey()))) + throw ProtocolException.validation("Source changed before activation: " + entry.getKey() + "; rollback and preview again"); + } + for (String path : state.sourceHashes().keySet()) if (!observed.containsKey(path)) throw ProtocolException.validation("Source disappeared before activation: " + path); + Path originals = original(root, state), staging = stage(root, state); + var published = new TreeMap(); ProtocolGuide.entries(root).forEach((path, text) -> published.put(path, Revisions.hash(text))); + var config = new ProjectService().load(originals); + var sqlite = new ProjectConfig(1, config.project(), config.repositories(), config.agents(), "sqlite"); + published.put(".ai-engineering/ai-engineering.yaml", Revisions.hash(Documents.yaml(sqlite))); + published.put(GUARD, Revisions.hash(GUARD_TEXT)); + state = new State(state.operation(), "ACTIVATING", state.fingerprint(), state.sourceHashes(), published, state.databaseHash()); save(root, state); + ProtocolGuide.install(root); + Path guard = Filespace.resolve(root, GUARD); + if (Files.exists(guard)) { if (!Filespace.read(guard).equals(GUARD_TEXT)) throw ProtocolException.validation("Storage guard differs; inspect migration"); } + else Filespace.write(guard, GUARD_TEXT, false); + boundary.accept("ENTRY_GUARDED"); + Path database = SqliteDatabase.path(root); + if (Files.exists(database)) { + if (!hash(database).equals(state.databaseHash())) throw ProtocolException.validation("Published database differs; inspect before recovery"); + } else { + Path prepared = SqliteDatabase.path(staging); + if (!hash(prepared).equals(state.databaseHash())) throw ProtocolException.validation("Prepared database changed"); + Filespace.writeBytes(database, Filespace.io(() -> Files.readAllBytes(prepared)), false); + } + boundary.accept("DATABASE_PUBLISHED"); + Filespace.write(Filespace.resolve(root, ".ai-engineering/ai-engineering.yaml"), Documents.yaml(sqlite), true); + boundary.accept("ACTIVATED"); + var validation = new VerificationService().project(root); + if (!validation.valid()) throw ProtocolException.validation("Activated database needs inspection: " + validation.issues()); + save(root, state.phase("APPLIED")); removeStage(staging); return report(root, state.phase("APPLIED"), List.of()); + } + private Report rollback(Path root, State state) { + if (state.phase().equals("ROLLED_BACK")) return report(root, state, List.of()); + Path database = SqliteDatabase.path(root); + if (state.publishedHashes().isEmpty() && !Files.exists(database)) { + // No active file was changed: keep any subsequent legacy edits and abandon only our staging. + save(root, state.phase("ROLLED_BACK")); removeStage(stage(root, state)); return report(root, state.phase("ROLLED_BACK"), List.of()); + } + if (Files.exists(database)) { + SqliteDatabase.checkpoint(root); + if (state.databaseHash() == null || !hash(database).equals(state.databaseHash())) + throw ProtocolException.validation("Database changed since activation; rollback would lose engineering memory. Keep SQLite and inspect deliberately"); + } + // Refuse to overwrite unrelated post-migration edits, including human bootstrap changes. + for (var entry : state.publishedHashes().entrySet()) { + Path path = Filespace.resolve(root, entry.getKey()); + if (Files.exists(path) && !hash(path).equals(entry.getValue()) && !hash(path).equals(state.sourceHashes().get(entry.getKey()))) + throw ProtocolException.validation("Bootstrap changed since migration: " + entry.getKey()); + } + Path originals = original(root, state); + for (String path : state.sourceHashes().keySet()) { + Path source = Filespace.resolve(originals, path), target = Filespace.resolve(root, path); + if (!Files.exists(source)) { + if (!Files.exists(target) || !hash(target).equals(state.sourceHashes().get(path))) throw ProtocolException.validation("Incomplete safety copy: " + path); + continue; + } + if (!hash(source).equals(state.sourceHashes().get(path))) throw ProtocolException.validation("Safety copy changed: " + path); + } + for (String path : state.publishedHashes().keySet()) { + Path target = Filespace.resolve(root, path); + if (state.sourceHashes().containsKey(path)) Filespace.writeBytes(target, Filespace.io(() -> Files.readAllBytes(Filespace.resolve(originals, path))), true); + else Filespace.io(() -> { Files.deleteIfExists(target); return null; }); + } + for (String suffix : List.of("", "-wal", "-shm", "-journal")) { + Path path = Filespace.resolve(root, ".ai-engineering/aie.db" + suffix); + Filespace.io(() -> { Files.deleteIfExists(path); return null; }); + } + save(root, state.phase("ROLLED_BACK")); removeStage(stage(root, state)); return report(root, state.phase("ROLLED_BACK"), List.of()); + } +} diff --git a/src/main/java/net/intrepid/aiengineering/verification/VerificationService.java b/src/main/java/net/intrepid/aiengineering/verification/VerificationService.java index af2c0d0..7aa8dab 100644 --- a/src/main/java/net/intrepid/aiengineering/verification/VerificationService.java +++ b/src/main/java/net/intrepid/aiengineering/verification/VerificationService.java @@ -23,6 +23,9 @@ public final class VerificationService { try { operation.run(); } catch (RuntimeException e) { issues.add(e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage()); } } public ValidationReport project(Path root) { + return SqliteDatabase.active(root) ? SqliteDatabase.read(root, connection -> projectSnapshot(root)) : projectSnapshot(root); + } + private ValidationReport projectSnapshot(Path root) { var issues = new ArrayList(); check(issues, () -> projects.validate(root)); check(issues, () -> ProtocolGuide.validate(root)); @@ -30,10 +33,24 @@ public final class VerificationService { var all = works.list(root); Path counter = Filespace.resolve(works.workspace(root), ".sequence.yaml"); if (!all.isEmpty()) { - var sequence = Documents.read(counter, WorkService.Sequence.class); + long number = SqliteDatabase.active(root) ? SqliteDatabase.read(root, connection -> { + try (var statement = connection.createStatement(); var row = statement.executeQuery("SELECT high_water FROM identity_sequence WHERE scope='project' AND kind='work'")) { + if (!row.next()) throw ProtocolException.validation("Missing Work sequence"); return row.getLong(1); + } + }) : Documents.read(counter, WorkService.Sequence.class).number(); long max = all.stream().mapToLong(w -> Work.number(w.id())).max().orElse(0); - if (sequence.number() < max) issues.add("Work sequence is below the highest reserved ID"); + if (number < max) issues.add("Work sequence is below the highest reserved ID"); } + new EpicService().definitions(root); + if (SqliteDatabase.active(root)) SqliteDatabase.read(root, connection -> { + try (var statement = connection.createStatement(); var rows = statement.executeQuery("PRAGMA foreign_key_check")) { + if (rows.next()) issues.add("SQLite foreign key violation: " + rows.getString(1)); + } + try (var statement = connection.createStatement(); var rows = statement.executeQuery("PRAGMA quick_check")) { + while (rows.next()) if (!"ok".equals(rows.getString(1))) issues.add("SQLite integrity: " + rows.getString(1)); + } + return null; + }); all.forEach(w -> issues.addAll(work(root, w.id()).issues())); }); for (String directory : List.of("works", "contracts", ".local")) @@ -41,11 +58,14 @@ public final class VerificationService { return new ValidationReport(issues.isEmpty(), issues); } public ValidationReport work(Path root, String id) { + return SqliteDatabase.active(root) ? SqliteDatabase.read(root, connection -> workSnapshot(root, id)) : workSnapshot(root, id); + } + private ValidationReport workSnapshot(Path root, String id) { var issues = new ArrayList(); check(issues, () -> ProtocolGuide.validate(root)); check(issues, () -> { Work work = works.load(root, id); Path folder = works.folder(root, id); - check(issues, () -> new EpicService().definitions(root)); + check(issues, () -> new EpicService().validateSelected(root, id)); var registered = projects.load(root).repositories().stream().map(ProjectConfig.Repository::id).toList(); for (var revision : work.repositories()) { if (!registered.contains(revision.repositoryId())) issues.add("Unknown Work repository: " + revision.repositoryId()); @@ -95,6 +115,12 @@ public final class VerificationService { } })); check(issues, () -> artifacts.validate(root, id)); + if (SqliteDatabase.active(root)) check(issues, () -> { + var owned = Map.of("discussion", work.discussions(), "decision", work.decisions(), "plan", work.plans(), + "topic", work.topics(), "survey", work.surveys(), "disposition", work.dispositions(), "run", work.agentRuns(), "artifact", work.artifacts()); + for (var entry : owned.entrySet()) if (!new HashSet<>(SqliteRecords.ids(root, entry.getKey(), id)).equals(new HashSet<>(entry.getValue()))) + issues.add("Unreferenced or missing SQLite records: " + entry.getKey()); + }); check(issues, () -> new net.intrepid.aiengineering.legacyimport.DiscussionImportService().receipts(root, id)); check(issues, () -> new TopicService().views(root, id)); check(issues, () -> new SurveyService().list(root, id)); @@ -120,6 +146,7 @@ public final class VerificationService { if (!work.artifacts().containsAll(criterion.evidence())) issues.add("Missing completion evidence for criterion " + criterion.criterion()); check(issues, () -> new EpicCoordinator().validateHistory(root, work)); check(issues, () -> new PlanCoordinator().validateHistory(root, work)); + check(issues, () -> new QualityGates().validateHistory(root, work)); if (work.status() == Work.Status.COMPLETED) check(issues, () -> { if (work.completions().isEmpty()) { issues.add("Completed Work has no verified completion record; reopen it to record evidence"); return; } var completion = work.completions().getLast(); @@ -155,6 +182,7 @@ public final class VerificationService { } ValidationReport localReadiness(Path root, String id) { var issues = new ArrayList<>(work(root, id).issues()); + check(issues, () -> issues.addAll(new QualityGates().pending(root, id))); check(issues, () -> { Work work = works.load(root, id); if (work.guidance() != null) check(issues, () -> work.guidance().requireMode()); @@ -173,6 +201,7 @@ public final class VerificationService { /** Pending protocol commitments; neither invokes models nor interprets prose. */ List executionPending(Path root, String id) { var issues = new ArrayList(); + check(issues, () -> issues.addAll(new QualityGates().pending(root, id))); var guided = works.load(root, id).guidance(); if (guided != null) check(issues, guided::requireMode); if (!outstanding(root, id).isEmpty()) issues.add("Resolve outstanding questions and issues explicitly"); @@ -229,6 +258,7 @@ public final class VerificationService { if (index > work.acceptanceCriteria().size() || results.containsKey(index)) throw ProtocolException.validation("Unknown or duplicate criterion: " + index); var evidence = List.of(mapping.substring(mapping.indexOf('=') + 1).split(",")); if (!work.artifacts().containsAll(evidence)) throw ProtocolException.validation("Unknown criterion evidence: " + mapping); + artifacts.requireAvailable(root, id, evidence); results.put(index, new Work.CriterionResult(index, work.acceptanceCriteria().get(index - 1), evidence)); } if (results.size() != work.acceptanceCriteria().size()) throw ProtocolException.validation("Every acceptance criterion needs an evidence mapping (--criterion N=ART-0001)"); @@ -240,11 +270,17 @@ public final class VerificationService { if (!seen.add(path)) throw ProtocolException.invalid("Duplicate canonical integration: " + relative); integrations.add(new Work.Integration(root.relativize(path).toString().replace('\\', '/'), Revisions.hash(Filespace.io(() -> Files.readAllBytes(path))))); } - works.recordCompletion(root, id, new Work.Completion(Instant.now().toString(), by, summary, true, scopeHash(root, work), + recordCompletion(root, id, new Work.Completion(Instant.now().toString(), by, summary, true, scopeHash(root, work), List.copyOf(results.values()), integrations, noIntegrationReason)); return notifyChange(root, id, requester, key); }); } + Work recordCompletion(Path root, String id, Work.Completion completion) { + new QualityGates().freeze(root, works.load(root, id), completion.at()); + var completed = works.recordCompletion(root, id, completion); + ArtifactLifecycle.prepareCompleted(root, id); + return completed; + } private EpicCoordinator.LifecycleResult notifyChange(Path root, String id, String requester, String requestId) { try { var propagation = new PlanCoordinator().reconcile(root, id, requester, requestId).propagation(); @@ -252,7 +288,8 @@ public final class VerificationService { } catch (RuntimeException failure) { throw new ProtocolException(failure instanceof ProtocolException p ? p.exitCode() : 1, - "Work change persisted for " + id + "; propagation needs inspection/retry with epic reconcile " + id + ": " + failure.getMessage()); + (SqliteDatabase.active(root) ? "Work transaction rolled back for " + id + "; inspect propagation: " + : "Work change persisted for " + id + "; propagation needs inspection/retry with epic reconcile " + id + ": ") + failure.getMessage()); } } public EpicCoordinator.LifecycleResult status(Path root, String id, Work.Status status, String by, String reason, String requester, String requestId) { @@ -283,6 +320,9 @@ public final class VerificationService { /** Read-only projection for human listings; the full JSON contracts remain unchanged. */ public record Overview(Work work, String steps, ValidationReport validation, List nextActions) {} public List overview(Path root, List selected) { + return SqliteDatabase.active(root) ? SqliteDatabase.read(root, connection -> overviewSnapshot(root, selected)) : overviewSnapshot(root, selected); + } + private List overviewSnapshot(Path root, List selected) { return selected.stream().map(w -> { var validation = work(root, w.id()); String progress = "unavailable"; @@ -297,11 +337,17 @@ public final class VerificationService { }).toList(); } public ProjectStatus status(Path root, boolean all) { + return SqliteDatabase.active(root) ? SqliteDatabase.read(root, connection -> statusSnapshot(root, all)) : statusSnapshot(root, all); + } + private ProjectStatus statusSnapshot(Path root, boolean all) { return new ProjectStatus(1, projects.load(root).project(), ProtocolGuide.installed(root), works.list(root).stream() .filter(w -> all || !w.archived()).map(w -> new WorkSummary(w.id(), w.title(), w.status(), w.archived(), work(root, w.id()), actions(root, w))).toList(), new CompatibilityService().inspect(root).summary()); } public List nextActions(Path root, String id) { + return SqliteDatabase.active(root) ? SqliteDatabase.read(root, connection -> nextActionsSnapshot(root, id)) : nextActionsSnapshot(root, id); + } + private List nextActionsSnapshot(Path root, String id) { var result = new ArrayList(); if (!ProtocolGuide.installed(root)) result.add(new Action("ONBOARD", null, "Install the portable protocol entry instructions", "aie onboard")); var selected = id == null ? works.list(root).stream().filter(w -> !w.archived()).toList() : List.of(works.load(root, id)); @@ -314,8 +360,15 @@ public final class VerificationService { String id = work.id(); var actions = new ArrayList(); if (!validation.valid()) return List.of(new Action(work.epic() ? "RECONCILE_EPIC" : "REPAIR_PROTOCOL", id, String.join("; ", validation.issues()), work.epic() ? "aie epic reconcile " + id : "aie work validate " + id)); + if (ArtifactLifecycle.pending(root, id) > 0) actions.add(new Action("RECOVER_ARTIFACTS", id, + "Finish interrupted retirement of validated temporary attachments", "aie artifact recover " + id)); if (work.archived()) return List.of(new Action("REOPEN", id, "Reopen only when new work is needed", "aie work reopen " + id + " --help")); - if (work.terminal()) return List.of(new Action("ARCHIVE", id, "Retain the completed or cancelled record", "aie work archive " + id + " --help")); + if (work.terminal()) { + actions.add(new Action("ARCHIVE", id, "Retain the completed or cancelled record", "aie work archive " + id + " --help")); + return List.copyOf(actions); + } + for (var gate : new QualityGates().inspect(root, id)) if (!gate.satisfied()) + actions.add(new Action("EVALUATE_GATE", id, gate.definition().key() + ": " + gate.pending(), "aie gate status " + id)); if (work.epic()) { var evaluation = new EpicCoordinator().inspect(root, id); if (evaluation.canAutoComplete()) actions.add(new Action("RECONCILE_EPIC", id, "Apply the authorized aggregate condition", "aie epic reconcile " + id)); @@ -391,8 +444,12 @@ public final class VerificationService { public record Context(int schemaVersion, Work work, List discussionHistory, List decisions, List outstandingQuestions, List artifacts, List plans, String protocolGuide, List topics, List surveys, List dispositions, List agentRuns, - ProjectConfig.Agents agents, EpicCoordinator.Evaluation epic, String parentEpic, PlanCoordinator.Evaluation consolidation, String guidanceInstructions) {} + ProjectConfig.Agents agents, EpicCoordinator.Evaluation epic, String parentEpic, PlanCoordinator.Evaluation consolidation, String guidanceInstructions, + List gates, java.util.Map artifactStates) {} public Context context(Path root, String id) { + return SqliteDatabase.active(root) ? SqliteDatabase.read(root, connection -> contextSnapshot(root, id)) : contextSnapshot(root, id); + } + private Context contextSnapshot(Path root, String id) { var report = work(root, id); if (!report.valid()) throw ProtocolException.validation(String.join("; ", report.issues())); var history = discussions.list(root, id); @@ -400,7 +457,12 @@ public final class VerificationService { new TopicService().views(root, id), new SurveyService().list(root, id), new DispositionService().list(root, id), new AgentService().views(root, id), projects.load(root).agents(), works.load(root, id).epic() ? new EpicCoordinator().inspect(root, id) : null, new EpicService().parent(root, id), new PlanCoordinator().inspect(root, id), works.load(root, id).guidance() == null ? "Historical Work without guidance: preserve recorded authority; adopt explicitly with work guidance before applying the new contract." - : works.load(root, id).guidance().instructions()); + : works.load(root, id).guidance().instructions(), new QualityGates().inspect(root, id), artifactStates(root, id)); + } + private java.util.Map artifactStates(Path root, String id) { + var states = new LinkedHashMap(); + for (var artifact : artifacts.list(root, id)) states.put(artifact.id(), ArtifactLifecycle.state(root, id, artifact.id())); + return Collections.unmodifiableMap(states); } private List outstanding(Path root, String id) { var all = new ArrayList<>(outstanding(discussions.list(root, id))); @@ -431,6 +493,8 @@ public final class VerificationService { section(result, "Plans and execution steps", yaml(context.plans())); section(result, "Outstanding questions", items(context.outstandingQuestions())); section(result, "Artifact references (paths relative to Work)", yaml(context.artifacts())); + section(result, "Artifact availability", yaml(context.artifactStates())); + section(result, "Quality gates", yaml(context.gates())); section(result, "Completion records", yaml(w.completions())); section(result, "Plan consolidation", yaml(context.consolidation())); section(result, "Lifecycle history", yaml(w.events())); diff --git a/src/main/java/net/intrepid/aiengineering/work/EpicService.java b/src/main/java/net/intrepid/aiengineering/work/EpicService.java index b9c555b..95a3cbd 100644 --- a/src/main/java/net/intrepid/aiengineering/work/EpicService.java +++ b/src/main/java/net/intrepid/aiengineering/work/EpicService.java @@ -11,7 +11,7 @@ public final class EpicService { private final WorkService works = new WorkService(); public Path path(Path root, String id) { Work.identifier(id, "WRK"); return Filespace.resolve(works.folder(root, id), "epic/" + id + ".md"); } private Epic read(Path path, String id) { - var value = Documents.readMarkdownDocument(path, Epic.class, "reason"); + var value = RecordStorage.read(path, Epic.class, "reason"); if (!value.workId().equals(id)) throw ProtocolException.validation("EPIC identity mismatch: " + id); return value; } @@ -20,7 +20,7 @@ public final class EpicService { var next = current; for (int revision = current.revision() - 1; revision >= 1; revision--) { Path previousPath = Revisions.history(works.folder(root, id), "epic", id, revision); - String raw = Filespace.read(previousPath); Revisions.chain(next.revision(), next.previousHash(), revision + 1, raw); + String raw = RecordStorage.raw(previousPath, Epic.class, "reason"); Revisions.chain(next.revision(), next.previousHash(), revision + 1, raw); var previous = read(previousPath, id); if (previous.revision() != revision) throw ProtocolException.validation("Invalid EPIC history revision"); result.add(previous); next = previous; @@ -58,21 +58,48 @@ public final class EpicService { } } public Epic get(Path root, String id) { - Work.identifier(id, "WRK"); works.load(root, id); + Work.identifier(id, "WRK"); var work = works.load(root, id); + if (SqliteDatabase.active(root)) { + if (!work.epic()) throw ProtocolException.missing("Work is not an EPIC: " + id); + var value = history(root, id).getLast(); + var links = SqliteDatabase.read(root, connection -> { + var result = new TreeMap(); + try (var statement = connection.prepareStatement("SELECT child_work_id,important FROM epic_link WHERE parent_work_id=?")) { + statement.setString(1, id); + try (var rows = statement.executeQuery()) { while (rows.next()) result.put(rows.getString(1), rows.getBoolean(2)); } + } + return result; + }); + var expected = new TreeMap(); value.children().forEach(link -> expected.put(link.workId(), link.important())); + if (!links.equals(expected)) throw ProtocolException.validation("EPIC indexed links differ from policy: " + id); + return value; + } var result = definitions(root).get(id); if (result == null) throw ProtocolException.missing("Work is not an EPIC: " + id); return result; } public String parent(Path root, String child) { works.load(root, child); + if (SqliteDatabase.active(root)) return SqliteDatabase.read(root, connection -> { + try (var statement = connection.prepareStatement("SELECT parent_work_id FROM epic_link WHERE child_work_id=?")) { + statement.setString(1, child); + try (var row = statement.executeQuery()) { return row.next() ? row.getString(1) : null; } + } + }); return definitions(root).values().stream().filter(e -> e.children().stream().anyMatch(c -> c.workId().equals(child))) .map(Epic::workId).findFirst().orElse(null); } + public void validateSelected(Path root, String id) { + if (!SqliteDatabase.active(root)) { definitions(root); return; } + var work = works.load(root, id); + if (work.epic()) get(root, id); + else if (SqliteRecords.current(root, id, "epic", id) != 0) throw ProtocolException.validation("Unreferenced EPIC definition: " + id); + } private Epic publish(Path root, Epic old, Epic next) { if (old.equals(next)) return old; var proposed = new LinkedHashMap<>(definitions(root)); proposed.put(next.workId(), next); validateGraph(works.list(root), proposed); - String raw = Filespace.read(path(root, old.workId())); - Revisions.replace(works.folder(root, old.workId()), "epic", old.workId(), old.revision(), raw, Documents.markdownDocument(next, "reason")); + String raw = RecordStorage.raw(path(root, old.workId()), Epic.class, "reason"); + RecordStorage.replaceRevision(works.folder(root, old.workId()), "epic", old.workId(), old.revision(), raw, Documents.markdownDocument(next, "reason"), Epic.class, "reason"); works.touched(root, old.workId(), next.updatedAt()); return next; } public Epic configure(Path root, String id, Epic.Mode mode, String by, String reason) { @@ -83,7 +110,7 @@ public final class EpicService { return old.mode() == mode ? old : publish(root, old, old.changed(mode, old.children(), null, policyHash(root, id), by, reason)); } var value = new Epic(1, id, mode, List.of(), null, 1, null, Instant.now().toString(), by, reason); - Path target = path(root, id); Filespace.directory(target.getParent()); Documents.writeMarkdownDocument(target, value, "reason", false); + Path target = path(root, id); Filespace.directory(target.getParent()); RecordStorage.write(target, value, Epic.class, "reason", false); works.markEpic(root, id); return value; }); } @@ -127,12 +154,12 @@ public final class EpicService { return Revisions.hash(Documents.json(data)); } public boolean authorized(Path root, Epic epic) { return epic.authorization() != null && epic.authorization().scopeHash().equals(authorityScope(root, epic)); } - public String policyHash(Path root, String id) { return Revisions.hash(Filespace.read(path(root, id))); } + public String policyHash(Path root, String id) { return Revisions.hash(RecordStorage.raw(path(root, id), Epic.class, "reason")); } public Epic byHash(Path root, String id, String hash) { var revisions = history(root, id); for (var value : revisions) { Path candidate = value.revision() == revisions.getLast().revision() ? path(root, id) : Revisions.history(works.folder(root, id), "epic", id, value.revision()); - if (Revisions.hash(Filespace.read(candidate)).equals(hash)) return value; + if (Revisions.hash(RecordStorage.raw(candidate, Epic.class, "reason")).equals(hash)) return value; } throw ProtocolException.validation("Missing authorized EPIC policy history: " + id); } diff --git a/src/main/java/net/intrepid/aiengineering/work/SqliteWorkStore.java b/src/main/java/net/intrepid/aiengineering/work/SqliteWorkStore.java new file mode 100644 index 0000000..10480f5 --- /dev/null +++ b/src/main/java/net/intrepid/aiengineering/work/SqliteWorkStore.java @@ -0,0 +1,49 @@ +package net.intrepid.aiengineering.work; + +import net.intrepid.aiengineering.filesystem.*; +import java.nio.file.Path; +import java.util.*; + +/** Work-specific ownership/allocation; field persistence uses typed columns and ordered rows. */ +final class SqliteWorkStore { + private SqliteWorkStore() {} + static Work load(Path root, String id) { return SqliteRecords.get(root, id, "work", id, 0, Work.class); } + static List list(Path root) { + return SqliteDatabase.read(root, connection -> SqliteRecords.ids(root, "work", null).stream() + .map(id -> load(root, id)).sorted(Comparator.comparingLong(w -> Work.number(w.id()))).toList()); + } + static String folder(Path root, String id) { + return SqliteDatabase.read(root, connection -> { + try (var statement = connection.prepareStatement("SELECT folder FROM work_location WHERE work_id=?")) { + statement.setString(1, id); + try (var rows = statement.executeQuery()) { + if (!rows.next()) throw ProtocolException.missing("Work not found: " + id); + return rows.getString(1); + } + } + }); + } + static String allocate(Path root) { + return SqliteDatabase.write(root, connection -> { + try (var statement = connection.prepareStatement("UPDATE identity_sequence SET high_water=high_water+1 WHERE scope='project' AND kind='work' AND high_water { + try (var statement = connection.prepareStatement("INSERT INTO work_identity VALUES (?)")) { + statement.setString(1, work.id()); statement.executeUpdate(); + } + try (var statement = connection.prepareStatement("INSERT INTO work_location VALUES (?,?)")) { + statement.setString(1, work.id()); statement.setString(2, folder); statement.executeUpdate(); + } + SqliteRecords.put(root, work.id(), "work", work.id(), work, Work.class, false, 1); + return null; + }); + } +} diff --git a/src/main/java/net/intrepid/aiengineering/work/WorkService.java b/src/main/java/net/intrepid/aiengineering/work/WorkService.java index af6b0f5..7e67e49 100644 --- a/src/main/java/net/intrepid/aiengineering/work/WorkService.java +++ b/src/main/java/net/intrepid/aiengineering/work/WorkService.java @@ -10,6 +10,7 @@ public final class WorkService { private final ProjectService projects = new ProjectService(); public Path workspace(Path root) { return Filespace.resolve(root, ".ai-engineering/works"); } public List list(Path root) { + if (SqliteDatabase.active(root)) return SqliteWorkStore.list(root); var seen = new HashSet(); var result = new ArrayList(); for (Path folder : Filespace.children(workspace(root))) { Path safe = Filespace.resolve(root, root.relativize(folder).toString()); @@ -23,10 +24,15 @@ public final class WorkService { } public Work load(Path root, String id) { Work.identifier(id, "WRK"); + if (SqliteDatabase.active(root)) return SqliteWorkStore.load(root, id); return list(root).stream().filter(w -> w.id().equals(id)).findFirst() .orElseThrow(() -> ProtocolException.missing("Work not found: " + id)); } public Path folder(Path root, String id) { + if (SqliteDatabase.active(root)) { + Work.identifier(id, "WRK"); + return Filespace.resolve(workspace(root), SqliteWorkStore.folder(root, id)); + } load(root, id); return Filespace.children(workspace(root)).stream().filter(p -> p.getFileName().toString().startsWith(id + "-")) .map(p -> Filespace.resolve(root, root.relativize(p).toString())).findFirst().orElseThrow(); @@ -45,6 +51,7 @@ public final class WorkService { public Work createPrepared(Path root, String title, String description, String goal, String motivation, List constraints, List criteria, List repositories, String author, java.util.function.BiFunction prepare) { + if (SqliteDatabase.active(root)) return createSqlite(root, title, description, goal, motivation, constraints, criteria, repositories, author, prepare); return Filespace.locked(root, () -> { list(root); // Refuse to allocate an ID in a corrupt project. // The sequence is canonical; a crash may leave gaps, but identities are never reused. @@ -73,6 +80,40 @@ public final class WorkService { Filespace.moveDirectory(staging, target); return prepared; }); } + private Work createSqlite(Path root, String title, String description, String goal, String motivation, + List constraints, List criteria, List repositories, String author, + java.util.function.BiFunction prepare) { + var revisions = projects.revisions(root, repositories); + return Filespace.locked(root, () -> { + String id = SqliteWorkStore.allocate(root), now = Instant.now().toString(); + var work = new Work(1, id, title, description, goal.isBlank() ? title : goal, motivation, constraints, criteria, + Work.Status.OPEN, now, now, author, revisions, List.of(), List.of(), List.of(), List.of(), List.of(), List.of(), false, + List.of(), List.of(), List.of(), List.of(), false); + if (guidanceContract(root)) work = work.withGuidance(WorkGuidance.pending()); + String name = id + "-" + ProjectService.slug(title); + Path target = Filespace.resolve(workspace(root), name); + if (Files.exists(target)) throw ProtocolException.validation("Work files already exist; inspect the interrupted publication: " + target); + Filespace.directory(target); + SqliteDatabase.afterRollback(root, () -> { + // Child publication recoveries run first. Preserve any unknown/nonempty residue. + try (var paths = Filespace.io(() -> Files.walk(target))) { + for (Path path : paths.sorted(Comparator.reverseOrder()).toList()) if (Files.isDirectory(path, LinkOption.NOFOLLOW_LINKS)) + Filespace.io(() -> { + try { Files.delete(path); } catch (DirectoryNotEmptyException retained) { /* Inspect retained files deliberately. */ } + return null; + }); + } + }); + for (String dir : List.of("discussions", "decisions", "plans", "artifacts/references", "artifacts/experiments", "artifacts/evidence", "artifacts/outputs", "runs")) + Filespace.directory(Filespace.resolve(target, dir)); + SqliteWorkStore.register(root, work, name); + var prepared = prepare.apply(target, work); + if (!prepared.id().equals(work.id()) || !prepared.createdAt().equals(work.createdAt()) || prepared.status() != Work.Status.OPEN) + throw ProtocolException.validation("Prepared Work changed its identity or initial state"); + SqliteRecords.put(root, id, "work", id, prepared, Work.class, true, 1); + return prepared; + }); + } public record Sequence(int schemaVersion, String lastWork) { public Sequence { if (schemaVersion == 1) { @@ -88,7 +129,7 @@ public final class WorkService { } /** Called inside the caller's project lock after publishing the referenced file. */ public void addReference(Path root, String id, String kind, String reference) { - Documents.replaceFrontMatter(Filespace.resolve(folder(root, id), "work.md"), load(root, id).reference(kind, reference)); + RecordStorage.frontMatter(Filespace.resolve(folder(root, id), "work.md"), load(root, id).reference(kind, reference), Work.class); } public Work status(Path root, String id, Work.Status value) { return status(root, id, value, "human", "Status set to " + value); @@ -96,13 +137,13 @@ public final class WorkService { public Work status(Path root, String id, Work.Status value, String by, String reason) { return Filespace.locked(root, () -> { Work updated = load(root, id).withStatus(value, by, reason); - Documents.replaceFrontMatter(Filespace.resolve(folder(root, id), "work.md"), updated); return updated; + RecordStorage.frontMatter(Filespace.resolve(folder(root, id), "work.md"), updated, Work.class); return updated; }); } public Work update(Path root, String id, Work.Update change) { return Filespace.locked(root, () -> { Work original = load(root, id); Work updated = original.update(change); - if (!updated.equals(original)) Documents.replaceFrontMatter(Filespace.resolve(folder(root, id), "work.md"), updated); + if (!updated.equals(original)) RecordStorage.frontMatter(Filespace.resolve(folder(root, id), "work.md"), updated, Work.class); return updated; }); } @@ -145,7 +186,7 @@ public final class WorkService { public Work recordCompletion(Path root, String id, Work.Completion completion) { Work work = load(root, id).complete(completion); save(root, work); return work; } - private void save(Path root, Work work) { Documents.replaceFrontMatter(Filespace.resolve(folder(root, work.id()), "work.md"), work); } + private void save(Path root, Work work) { RecordStorage.frontMatter(Filespace.resolve(folder(root, work.id()), "work.md"), work, Work.class); } public Work archive(Path root, String id, String by, String reason) { return Filespace.locked(root, () -> { Work work = load(root, id).archive(by, reason); save(root, work); return work; }); } diff --git a/src/main/resources/protocol/AGENTS.md b/src/main/resources/protocol/AGENTS.md index 4303073..b5370b5 100644 --- a/src/main/resources/protocol/AGENTS.md +++ b/src/main/resources/protocol/AGENTS.md @@ -13,3 +13,13 @@ approval is the default; a Work-wide waiver must be explicit and recorded. Follo guidance across sessions and never infer authority from task simplicity or model output. During implementation, use experiments and evidence when needed, adapt within the DEC, and revisit questioned commitments before affected execution. + +SQLite is the default local memory; use a contract-4 CLI to read and mutate it. +If unavailable, report the tool gap after reading bootstrap instructions. Never +assume unreadable memory is empty. State is outside Git by default; do not install +new tools or migrate a consumer merely because new code exists. + +Required project/Work gates must actually pass for the evaluated state. Keep +required attachments until checks finish; retain short results and let eligible +temporary inputs retire after completion. Requested outputs belong outside AIE +state. Legitimate historical retirement is different from missing current input. diff --git a/src/main/resources/protocol/README.md b/src/main/resources/protocol/README.md index 68a19f6..f47d2a8 100644 --- a/src/main/resources/protocol/README.md +++ b/src/main/resources/protocol/README.md @@ -17,7 +17,8 @@ Use `ai-engineering` (or its installed alias `aie`). No server or model API is n payloads, decisions and plan history when relevant; context references are not the payload itself. Follow the Work guidance. Ask the human for DIRECT or EXPLORATORY when missing; never infer a choice or approval. Carry a recorded - choice into future sessions. Without a CLI, inspect the portable files directly. + choice into future sessions. SQLite memory requires a compatible CLI. Without it, + read bootstrap guidance and report the tool gap; never infer an empty workspace. 4. Distinguish observations verified now, historical evidence, assumptions and proposals. Record refinement with `discussion add --text` or `--text-file`, choosing an explicit `--author`. Resolve questions with RESPONSE/CONCLUSION @@ -30,7 +31,7 @@ Use `ai-engineering` (or its installed alias `aie`). No server or model API is n Run `aie project compatibility --format json` before considering an update. `status` includes a compatibility summary and the diagnostic command. The diagnostic is -read-only: it inspects actual canonical files and record revisions, without locks, +read-only: it inspects actual typed records and their revisions (or legacy files), without locks, backups, model calls or migrations. It includes AIE completion receipts, while ignored runs, local backups and ordinary artifact payloads are excluded. Use `project validate` for integrity. @@ -54,18 +55,19 @@ rewrite a completed Work merely to materialize current fields, topics or surveys `aie onboard` refreshes the entry instructions and manifest, with backups, while leaving Works, evidence and revision history unchanged. A newer unsupported manifest -or contract is refused rather than overwritten; use a compatible CLI. No required -migration is registered in this release. Future conversions must have an explicit -public command, scope, preview, backups and repeatable execution. Do not invent a -migration or inspect AIE source code to discover consumer update procedures; report -public-interface gaps with evidence instead. +or contract is refused rather than overwritten; use a compatible CLI. Legacy reading does not require conversion. `storage migrate --format json` previews +an optional supported legacy-to-SQLite conversion; `--apply --expect HASH` applies +only that reviewed state. Originals and historical hashes/approvals are preserved. +`--recover` or `--rollback` use the operation fingerprint after interruption. Rollback +refuses to lose new SQLite writes. Installation/onboard/reads never migrate storage. +Use the public command and documentation rather than inferring a procedure from code. -The current entry contract is 3 and advertises Work guidance, human DEC requests, -and optional Plan experiments in addition to DF open-agenda import. Contract 1 -projects remain readable without Work migration. An import-enabled manifest needs -contract 2 and the `discussion-import` capability; older CLIs must be updated before -reading it. Refresh entry files with `onboard` after compatibility inspection, -preserving historical Works and their approvals. +The current entry contract is 4. It declares SQLite/local memory, quality gates and +temporary artifacts, preserving contract-3 guidance and Plan experiments. Contracts +1, 2 and 3 remain readable on the legacy backend. A SQLite workspace requires the +matching contract 4 and database schema; incompatible combinations are refused. +`init` selects SQLite and adds `/.ai-engineering/` to .gitignore without requiring +Git. `--version-state` leaves ignore policy to the developer; it never untracks files. ## Work conduct and human authority @@ -208,7 +210,7 @@ the requester. An important child reopening reopens RESULTS ancestors, retaining history; optional changes do not. Explicit EPIC reopening suspends automatic authority so replanning is possible; child-caused reopening preserves unchanged-scope authority. `epic show/check/history` inspects state. `epic reconcile [WRK] --requester NAME ---request-id KEY` recovers missed propagation from files; repeated checks do not +--request-id KEY` recovers missed propagation from persisted state; repeated checks do not duplicate completion/receipts. Reads never invoke an adapter or perform transitions. Publication is per file; corrupt records and interrupted orphan publication may still need deliberate repair. Use public CLI/Verification lifecycle APIs for notification; @@ -281,8 +283,8 @@ success from a status label. Respect read-only repository policy and the OS sand ## Verification and closure When the last required step completes, AIE consolidates its Plan and rechecks the -Work's Plans. All required Plans completed, with no pending questions/surveys or -draft DECs, completes the Work automatically. Criteria/results/evidence belong to +Work's Plans. All required Plans completed, with current required gates passed and no pending +questions/surveys or draft DECs, completes the Work automatically. Criteria/results/evidence belong to the Plans/steps; no new Work-level checklist or model call is required. Completion records SYSTEM_PLANS origin, humanApproved=false and an owned receipt identifying the exact Plan revisions. Empty sets and explicit BLOCKED/CANCELLED states remain @@ -309,7 +311,7 @@ Do not mark COMPLETED through a generic status change. Use disposable test data; never confuse a historical report with a test run performed now. Update canonical code, tests, specs and documentation. There is no mandatory Lesson -entity. `work archive` retains all files/history; `work reopen --by NAME --reason TEXT` +entity. `work archive` retains useful memory/history; `work reopen --by NAME --reason TEXT` allows new evidence and reorientation while retaining earlier completion records. Never delete history as housekeeping. `import discussion --source ID=PATH` previews DF DSCs with AGDs open; repeat sources for a multi-project umbrella and use @@ -321,15 +323,44 @@ are skipped and changed inputs require review without overwriting. Prepared Work publish individually; after partial publication, preview again to resume without duplicates. Closed agendas, DECs, Plans and Lessons are not imported. -## Portable files and errors +## Storage, temporary artifacts and errors + +SQLite owns operational Work memory in `.ai-engineering/aie.db`. Store typed fields, +prose and relationships, never files encoded as BLOB/base64 or equivalent TEXT. +Small configuration and entry files bootstrap discovery. New revisions and related +references commit in one transaction; related reads share a snapshot. Writer waits +are bounded. RUN application failure rolls back the proposal and separately records +its diagnostic, with no reverted applied references. Work IDs are uppercase hexadecimal; child IDs are Work-local decimal identifiers. -Discussion and new decision/plan prose use Markdown bodies with versioned YAML front -matter. Use CLI mutations for IDs and references; human-authored prose remains portable. -Revisions live beside their records in `.history`, with SHA-256 links. `.local` stores -locks/backups and is not canonical state. Writes are atomic per file, not across all -records; validation diagnoses interrupted cross-record publication. Preserve backups -and repair deliberately, rather than silently dropping missing references. +Legacy Markdown/YAML and `.history` remain readable on the file backend. Explicit +migration retains original bytes externally when historical hashes need them. +Legacy originals retained in place are not a second writable authority. -Exit codes: 0 success, 1 unexpected I/O/runtime error, 2 invalid input, 3 missing -resource, 4 validation/readiness failure. Read `--help` for exact command options. +Required project gates and additional Work gates are cumulative. Configure with +`gate configure ID --title TEXT --procedure TEXT --input PATH --by NAME`, adding +`--work WRK` for a Work-specific gate and `--require-evidence` when needed. Read +`gate status WRK` to obtain the evaluatedHash before running the procedure externally. +Record the actual result with `gate record WRK project/ID --expect HASH +--invocation TEXT --outcome PASS|FAIL --summary TEXT --by NAME --observed +[--evidence ART]`. Human DEC approval is separate. Files, Work scope/guidance, DEC +revisions or gate-definition changes require current evaluation. Gate history and +delivery snapshots retain the short observed result; the CLI does not execute or +semantically verify repository commands. + +Temporary evidence stays on the filesystem while checks need it. Work completion +persists validation before discarding eligible payloads after commit. Context exposes +AVAILABLE, DISCARD_PENDING, DISCARDED, STRUCTURED or RETAINED_LEGACY. Missing input +before a check is an error; retired evidence cannot satisfy a fresh evaluation after +reopening. `artifact recover WRK` finishes interrupted publication/cleanup. Reads do +not clean up or mark checks passed. Unknown residue requires inspection. + +New Plan/EPIC receipts are structured database facts, with no extra payload file. +Legacy originals and migration safety copies are preserved. Requested outputs belong +at their delivery destination outside AIE state; cleanup never targets their source. +Raw transport, credentials, environment and complete logs are not retained as memory. +Git synchronization, Git LFS, Work/DEC export and backup as a feature are outside this +local version. The migration safety copy is specifically for conversion recovery. + +Exit codes: 0 success, 1 I/O/runtime error, 2 invalid input, 3 missing resource, +4 validation/readiness failure. Read `--help` for exact command options. diff --git a/src/main/resources/protocol/protocol.json b/src/main/resources/protocol/protocol.json index b34bdda..96d2418 100644 --- a/src/main/resources/protocol/protocol.json +++ b/src/main/resources/protocol/protocol.json @@ -1,6 +1,6 @@ { "schemaVersion": 1, - "protocolVersion": 3, + "protocolVersion": 4, "protocol": "ai-engineering", "entrypoint": "README.md", "instructions": "AGENTS.md", @@ -9,7 +9,7 @@ "command": "ai-engineering", "aliases": ["aie"], "startup": ["status --format json", "next-actions --format json", "work context --format markdown"], - "capabilities": ["protocol-compatibility", "work-guidance", "human-decision-request", "plan-experiments", "work", "discussion", "topics", "surveys", "answer-history", "proposal-dispositions", "fixture-adapters", "local-cli-adapters", "guided-agent-setup", "agent-doctor", "agent-routing", "run-provenance", "epic", "epic-policy-authorization", "epic-propagation", "epic-reconciliation", "decision-approval", "decision-history", "plan-decision-promotion", "discussion-import", "import-preview", "import-provenance", "planning", "step-dependencies", "evidence", "completion", "plan-consolidation", "cancelled-scope-review", "work-reconciliation", "archive", "reopen"], + "capabilities": ["sqlite-storage", "local-memory", "quality-gates", "temporary-artifacts", "storage-migration", "protocol-compatibility", "work-guidance", "human-decision-request", "plan-experiments", "work", "discussion", "topics", "surveys", "answer-history", "proposal-dispositions", "fixture-adapters", "local-cli-adapters", "guided-agent-setup", "agent-doctor", "agent-routing", "run-provenance", "epic", "epic-policy-authorization", "epic-propagation", "epic-reconciliation", "decision-approval", "decision-history", "plan-decision-promotion", "discussion-import", "import-preview", "import-provenance", "planning", "step-dependencies", "evidence", "completion", "plan-consolidation", "cancelled-scope-review", "work-reconciliation", "archive", "reopen"], "humanApproval": "explicit-attestation", "execution": "external-human-or-agent", "legacyImport": true diff --git a/src/main/resources/sqlite/schema-v1.sql b/src/main/resources/sqlite/schema-v1.sql new file mode 100644 index 0000000..6812cb9 --- /dev/null +++ b/src/main/resources/sqlite/schema-v1.sql @@ -0,0 +1,135 @@ +-- Ownership, identity and revision foundation. Domain tables extend these keys. +CREATE TABLE aie_schema ( + singleton INTEGER PRIMARY KEY CHECK (singleton=1), + schema_version INTEGER NOT NULL CHECK (schema_version=1) +); +INSERT INTO aie_schema VALUES (1, 1); + +CREATE TABLE work_identity ( + work_id TEXT PRIMARY KEY NOT NULL +); +CREATE TABLE work_location ( + work_id TEXT PRIMARY KEY NOT NULL REFERENCES work_identity(work_id), + folder TEXT NOT NULL UNIQUE +); +CREATE TABLE epic_link ( + parent_work_id TEXT NOT NULL REFERENCES work_identity(work_id), + child_work_id TEXT NOT NULL UNIQUE REFERENCES work_identity(work_id), + important INTEGER NOT NULL CHECK(important IN (0,1)), + PRIMARY KEY(parent_work_id,child_work_id), + CHECK(parent_work_id<>child_work_id) +); + +CREATE TABLE identity_sequence ( + scope TEXT NOT NULL, + kind TEXT NOT NULL, + high_water INTEGER NOT NULL CHECK (high_water>=0), + PRIMARY KEY (scope, kind) +); +INSERT INTO identity_sequence VALUES ('project', 'work', 0); + +CREATE TABLE quality_gate ( + scope TEXT NOT NULL, + gate_id TEXT NOT NULL, + work_id TEXT REFERENCES work_identity(work_id), + title TEXT NOT NULL, + procedure TEXT NOT NULL, + evidence_required INTEGER NOT NULL CHECK(evidence_required IN (0,1)), + revision INTEGER NOT NULL CHECK(revision>0), + updated_by TEXT NOT NULL, + PRIMARY KEY(scope,gate_id), + CHECK((scope='project' AND work_id IS NULL) OR (work_id IS NOT NULL AND scope=work_id)) +); +CREATE TABLE quality_gate_input ( + scope TEXT NOT NULL, + gate_id TEXT NOT NULL, + ordinal INTEGER NOT NULL CHECK(ordinal>=0), + path TEXT NOT NULL, + PRIMARY KEY(scope,gate_id,ordinal), + FOREIGN KEY(scope,gate_id) REFERENCES quality_gate(scope,gate_id) +); +CREATE TABLE quality_delivery ( + work_id TEXT NOT NULL REFERENCES work_identity(work_id), + completed_at TEXT NOT NULL, + gate_count INTEGER NOT NULL CHECK(gate_count>=0), + PRIMARY KEY(work_id,completed_at) +); +CREATE TABLE quality_delivery_gate ( + work_id TEXT NOT NULL, + completed_at TEXT NOT NULL, + gate_key TEXT NOT NULL, + result_id TEXT NOT NULL, + result_sha256 TEXT NOT NULL, + result_kind TEXT NOT NULL DEFAULT 'gate' CHECK(result_kind='gate'), + result_revision INTEGER NOT NULL DEFAULT 1 CHECK(result_revision=1), + PRIMARY KEY(work_id,completed_at,gate_key), + FOREIGN KEY(work_id,completed_at) REFERENCES quality_delivery(work_id,completed_at), + FOREIGN KEY(work_id,result_kind,result_id,result_revision) REFERENCES record_identity(work_id,kind,local_id,revision) DEFERRABLE INITIALLY DEFERRED +); + +CREATE TABLE record_identity ( + work_id TEXT NOT NULL, + kind TEXT NOT NULL CHECK (kind IN ('work','discussion','topic','survey','disposition','decision','plan','epic','run','artifact','gate','receipt')), + local_id TEXT NOT NULL, + revision INTEGER NOT NULL CHECK (revision>0), + PRIMARY KEY (work_id,kind,local_id,revision), + FOREIGN KEY (work_id) REFERENCES work_identity(work_id) DEFERRABLE INITIALLY DEFERRED +); +CREATE INDEX record_by_kind ON record_identity(kind,work_id,local_id,revision); + +CREATE TABLE current_record ( + work_id TEXT NOT NULL, + kind TEXT NOT NULL, + local_id TEXT NOT NULL, + revision INTEGER NOT NULL, + PRIMARY KEY (work_id,kind,local_id), + FOREIGN KEY (work_id,kind,local_id,revision) + REFERENCES record_identity(work_id,kind,local_id,revision) DEFERRABLE INITIALLY DEFERRED +); + +CREATE TABLE record_reference ( + work_id TEXT NOT NULL, + kind TEXT NOT NULL, + local_id TEXT NOT NULL, + revision INTEGER NOT NULL, + field TEXT NOT NULL, + ordinal INTEGER NOT NULL CHECK (ordinal>=0), + target_work_id TEXT NOT NULL, + target_kind TEXT NOT NULL, + target_id TEXT NOT NULL, + target_revision INTEGER NOT NULL, + PRIMARY KEY (work_id,kind,local_id,revision,field,ordinal), + FOREIGN KEY (work_id,kind,local_id,revision) + REFERENCES record_identity(work_id,kind,local_id,revision) DEFERRABLE INITIALLY DEFERRED, + FOREIGN KEY (target_work_id,target_kind,target_id,target_revision) + REFERENCES record_identity(work_id,kind,local_id,revision) DEFERRABLE INITIALLY DEFERRED +); +CREATE INDEX references_to_record ON record_reference(target_work_id,target_kind,target_id,target_revision); + +CREATE TABLE record_format ( + work_id TEXT NOT NULL, + kind TEXT NOT NULL, + local_id TEXT NOT NULL, + revision INTEGER NOT NULL, + document_version INTEGER NOT NULL CHECK(document_version IN (1,2)), + original_path TEXT, + original_sha256 TEXT, + PRIMARY KEY (work_id,kind,local_id,revision), + CHECK((original_path IS NULL)=(original_sha256 IS NULL)), + FOREIGN KEY (work_id,kind,local_id,revision) + REFERENCES record_identity(work_id,kind,local_id,revision) DEFERRABLE INITIALLY DEFERRED +); + +CREATE TABLE artifact_lifecycle ( + work_id TEXT NOT NULL, + artifact_id TEXT NOT NULL, + kind TEXT NOT NULL DEFAULT 'artifact' CHECK(kind='artifact'), + revision INTEGER NOT NULL DEFAULT 1 CHECK(revision=1), + state TEXT NOT NULL CHECK(state IN ('AVAILABLE','DISCARD_PENDING','DISCARDED','RETAINED_LEGACY','STRUCTURED')), + checked_sha256 TEXT, + checked_at TEXT, + PRIMARY KEY(work_id,artifact_id), + CHECK((checked_sha256 IS NULL)=(checked_at IS NULL)), + CHECK(state NOT IN ('DISCARD_PENDING','DISCARDED','STRUCTURED') OR checked_sha256 IS NOT NULL), + FOREIGN KEY(work_id,kind,artifact_id,revision) REFERENCES record_identity(work_id,kind,local_id,revision) DEFERRABLE INITIALLY DEFERRED +); diff --git a/src/sqliteProbe/java/net/intrepid/aiengineering/probe/SqliteProbe.java b/src/sqliteProbe/java/net/intrepid/aiengineering/probe/SqliteProbe.java new file mode 100644 index 0000000..c32c30d --- /dev/null +++ b/src/sqliteProbe/java/net/intrepid/aiengineering/probe/SqliteProbe.java @@ -0,0 +1,83 @@ +package net.intrepid.aiengineering.probe; + +import java.nio.file.Files; +import java.nio.file.LinkOption; +import java.nio.file.Path; +import java.sql.DriverManager; +import org.sqlite.JDBC; +import net.intrepid.aiengineering.filesystem.SqliteDatabase; +import net.intrepid.aiengineering.project.ProjectService; +import net.intrepid.aiengineering.work.WorkService; +import net.intrepid.aiengineering.discussion.DiscussionService; +import net.intrepid.aiengineering.discussion.DiscussionEntry; +import java.util.List; + +/** Build-only probe: never discovers, creates or migrates an AIE project. */ +public final class SqliteProbe { + public static void main(String[] args) throws Exception { + if (args.length != 1) throw new IllegalArgumentException("Supply a disposable database path"); + Path path = Path.of(args[0]).toAbsolutePath().normalize(); + if (!Files.isDirectory(path.getParent()) || Files.isSymbolicLink(path) + || path.getFileName().toString().equals("aie.db")) + throw new IllegalArgumentException("Use an existing disposable directory and a probe database filename"); + boolean exists = Files.exists(path, LinkOption.NOFOLLOW_LINKS); + // Explicit registration also proves that the native entry point reaches the JDBC driver. + DriverManager.registerDriver(new JDBC()); + try (var connection = DriverManager.getConnection("jdbc:sqlite:" + path)) { + try (var statement = connection.createStatement()) { + statement.execute("PRAGMA foreign_keys=ON"); + if (!exists) { + statement.execute("CREATE TABLE probe (id INTEGER PRIMARY KEY, value TEXT NOT NULL)"); + try (var insert = connection.prepareStatement("INSERT INTO probe VALUES (?, ?)")) { + insert.setInt(1, 1); insert.setString(2, "memória de engenharia — SQLite"); + insert.executeUpdate(); + } + } + try (var rows = statement.executeQuery("SELECT value FROM probe WHERE id=1")) { + if (!rows.next() || !rows.getString(1).equals("memória de engenharia — SQLite")) + throw new IllegalStateException("Persisted UTF-8 value differs"); + } + } + connection.setAutoCommit(false); + try (var insert = connection.prepareStatement("INSERT INTO probe VALUES (?, ?)")) { + insert.setInt(1, 2); insert.setString(2, "must roll back"); insert.executeUpdate(); + } + connection.rollback(); connection.setAutoCommit(true); + try (var statement = connection.createStatement(); + var rows = statement.executeQuery("SELECT count(*) FROM probe")) { + if (!rows.next() || rows.getInt(1) != 1) throw new IllegalStateException("Rollback failed"); + } + System.out.println("SQLite " + connection.getMetaData().getDatabaseProductVersion() + + " " + (exists ? "reopened" : "created") + "; UTF-8 and rollback verified"); + } + Path foundation = Files.createDirectories(path.getParent().resolve("foundation")); + if (!Files.exists(SqliteDatabase.path(foundation))) { + SqliteDatabase.initialize(foundation); + SqliteDatabase.write(foundation, connection -> { + try (var statement = connection.createStatement()) { + statement.executeUpdate("INSERT INTO work_identity VALUES ('WRK-0001')"); + } + return null; + }); + } + long count = SqliteDatabase.read(foundation, connection -> { + try (var statement = connection.createStatement(); var rows = statement.executeQuery("SELECT count(*) FROM work_identity")) { + rows.next(); return rows.getLong(1); + } + }); + if (count != 1) throw new IllegalStateException("AIE transaction infrastructure did not preserve identity"); + System.out.println("AIE schema and transaction infrastructure verified"); + Path investigation = Files.createDirectories(path.getParent().resolve("investigation")); + var works = new WorkService(); + if (!Files.exists(SqliteDatabase.path(investigation))) { + new ProjectService().initializeSqlite(investigation, "Disposable native investigation"); + var work = works.create(investigation, "Native Work", "", "Persist context", "", List.of(), List.of(), List.of(), "fixture"); + new DiscussionService().add(investigation, work.id(), "Memória útil — UTF-8", DiscussionEntry.Kind.NOTE, "fixture", "main", null); + } + var work = works.load(investigation, "WRK-0001"); + var entries = new DiscussionService().list(investigation, work.id()); + if (entries.size() != 1 || !entries.getFirst().text().equals("Memória útil — UTF-8")) + throw new IllegalStateException("Native domain persistence did not preserve discussion"); + System.out.println("AIE Work and discussion typed persistence verified"); + } +} diff --git a/src/test/java/net/intrepid/aiengineering/CompatibilityTest.java b/src/test/java/net/intrepid/aiengineering/CompatibilityTest.java index 57b3b58..e88b0dd 100644 --- a/src/test/java/net/intrepid/aiengineering/CompatibilityTest.java +++ b/src/test/java/net/intrepid/aiengineering/CompatibilityTest.java @@ -25,7 +25,7 @@ class CompatibilityTest { private String ok(String... args) { var result = run(args); assertThat(result.code()).as(result.err() + result.out()).isZero(); return result.out(); } - private void init() { ok("init", "--name", "Test"); } + private void init() { ok("init", "--storage", "legacy", "--name", "Test"); } private Path work() { return root.resolve(".ai-engineering/works/WRK-0001-delivered-baseline"); } private CompatibilityService.Report inspect() { return new CompatibilityService().inspect(root); } private Map snapshot(Path directory) throws Exception { @@ -52,7 +52,7 @@ class CompatibilityTest { var report = inspect(); assertThat(report.state()).isEqualTo(CURRENT); assertThat(report.readable()).isTrue(); assertThat(report.migrationRequired()).isFalse(); - assertThat(report.currentProtocolVersion()).isEqualTo(3); + assertThat(report.currentProtocolVersion()).isEqualTo(4); assertThat(report.formats()).contains(FormatVersions.SEQUENCE, FormatVersions.DOCUMENT); assertThat(ok("project", "compatibility", "--format", "json")).contains("\"cliVersion\"", "\"readableVersions\"", "\"migrationRequired\" : false"); assertThat(ok("status", "--format", "json")).contains("\"compatibility\"", "\"state\" : \"CURRENT\""); diff --git a/src/test/java/net/intrepid/aiengineering/DiscussionImportTest.java b/src/test/java/net/intrepid/aiengineering/DiscussionImportTest.java index 7f99b19..9518f5b 100644 --- a/src/test/java/net/intrepid/aiengineering/DiscussionImportTest.java +++ b/src/test/java/net/intrepid/aiengineering/DiscussionImportTest.java @@ -25,7 +25,7 @@ class DiscussionImportTest { final WorkService works = new WorkService(); void init() throws Exception { root = Files.createDirectory(temp.resolve("destination")).toRealPath(); - new ProjectService().initialize(root, "Import destination"); + new ProjectService().initializeLegacy(root, "Import destination"); alpha = copyFixture("alpha", Files.createDirectory(temp.resolve("alpha"))); beta = copyFixture("beta", Files.createDirectory(temp.resolve("beta"))); } @@ -240,10 +240,10 @@ class DiscussionImportTest { String advertised = Files.readString(manifest); assertThat(advertised).contains("\"legacyImport\": true", "discussion-import"); assertThat(new VerificationService().project(root).valid()).isTrue(); - Files.writeString(manifest, advertised.replace("\"legacyImport\": true", "\"legacyImport\": false").replace("\"protocolVersion\": 3", "\"protocolVersion\": 1")); + Files.writeString(manifest, advertised.replace("\"legacyImport\": true", "\"legacyImport\": false").replace("\"protocolVersion\": 4", "\"protocolVersion\": 1")); assertThat(new VerificationService().project(root).valid()).isTrue(); assertThat(new CompatibilityService().inspect(root).state()).isEqualTo(CompatibilityService.State.LEGACY_COMPATIBLE); - Files.writeString(manifest, advertised.replace("\"protocolVersion\": 3", "\"protocolVersion\": 1")); + Files.writeString(manifest, advertised.replace("\"protocolVersion\": 4", "\"protocolVersion\": 1")); assertThat(new VerificationService().project(root).valid()).isFalse(); Files.writeString(manifest, advertised.replace("discussion-import", "unsupported-import")); assertThat(new CompatibilityService().inspect(root).readable()).isFalse(); diff --git a/src/test/java/net/intrepid/aiengineering/DiscussionMarkdownTest.java b/src/test/java/net/intrepid/aiengineering/DiscussionMarkdownTest.java index 16a2429..0578cbe 100644 --- a/src/test/java/net/intrepid/aiengineering/DiscussionMarkdownTest.java +++ b/src/test/java/net/intrepid/aiengineering/DiscussionMarkdownTest.java @@ -16,7 +16,7 @@ class DiscussionMarkdownTest { private final DiscussionService discussions = new DiscussionService(); private final WorkService works = new WorkService(); private void initialize() { - new ProjectService().initialize(root, "Test"); + new ProjectService().initializeLegacy(root, "Test"); works.create(root, "One", "", "Goal", "", List.of(), List.of(), List.of(), "human"); } private DiscussionEntry add(String text) { diff --git a/src/test/java/net/intrepid/aiengineering/DiscussionRefinementTest.java b/src/test/java/net/intrepid/aiengineering/DiscussionRefinementTest.java index b75b034..c1b952c 100644 --- a/src/test/java/net/intrepid/aiengineering/DiscussionRefinementTest.java +++ b/src/test/java/net/intrepid/aiengineering/DiscussionRefinementTest.java @@ -17,7 +17,7 @@ class DiscussionRefinementTest { } private void ok(String... args) { int code = cli(args); assertThat(code).as(output).isZero(); } private Path work() { return root.resolve(".ai-engineering/works/WRK-0001-one"); } - private void init() { ok("init", "--name", "Fixture"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One", "--acceptance", "Continuity"); } + private void init() { ok("init", "--storage", "legacy", "--name", "Fixture"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One", "--acceptance", "Continuity"); } @Test void legacyTopicViewDoesNotRewriteFilesAndSurveyAnswersKeepHistory() throws Exception { init(); byte[] original = Files.readAllBytes(work().resolve("work.md")); ok("topic", "list", "WRK-0001", "--format", "json"); assertThat(output).contains("main", "implicit"); diff --git a/src/test/java/net/intrepid/aiengineering/DiscussionTextFileTest.java b/src/test/java/net/intrepid/aiengineering/DiscussionTextFileTest.java index ea88208..0fb4280 100644 --- a/src/test/java/net/intrepid/aiengineering/DiscussionTextFileTest.java +++ b/src/test/java/net/intrepid/aiengineering/DiscussionTextFileTest.java @@ -19,7 +19,7 @@ class DiscussionTextFileTest { output = out + err.toString(); return code; } private void ok(String... args) { int code = cli(root, args); assertThat(code).as(output).isZero(); } - private void initialize() { ok("init", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); } + private void initialize() { ok("init", "--storage", "legacy", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); } @Test void importsExactUtf8TextRelativeToInvocationDirectoryAndPersistsIndependently() throws Exception { initialize(); ok("discussion", "add", "WRK-0001", "--kind", "QUESTION", "--text", "Which approach?"); String prose = "\n## Proposta — árvore 日本語\r\n\r\n- First limit\n- Second limit\n\n```yaml\n---\nkey: value\n```\n"; diff --git a/src/test/java/net/intrepid/aiengineering/EpicSafetyTest.java b/src/test/java/net/intrepid/aiengineering/EpicSafetyTest.java index c163736..48515c4 100644 --- a/src/test/java/net/intrepid/aiengineering/EpicSafetyTest.java +++ b/src/test/java/net/intrepid/aiengineering/EpicSafetyTest.java @@ -21,7 +21,7 @@ class EpicSafetyTest { private Work work(String id) { return new WorkService().load(root, id); } private Path folder(String id) { return new WorkService().folder(root, id); } private void init() throws Exception { - ok("init", "--name", "Safety"); + ok("init", "--storage", "legacy", "--name", "Safety"); for (String name : new String[]{"Parent", "Child", "Other"}) ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", name, "--acceptance", "Reviewed fixture result"); Files.writeString(root.resolve("evidence.txt"), "Synthetic observation\n"); } diff --git a/src/test/java/net/intrepid/aiengineering/EpicWorkflowTest.java b/src/test/java/net/intrepid/aiengineering/EpicWorkflowTest.java index b6a2214..8fe641e 100644 --- a/src/test/java/net/intrepid/aiengineering/EpicWorkflowTest.java +++ b/src/test/java/net/intrepid/aiengineering/EpicWorkflowTest.java @@ -19,7 +19,7 @@ class EpicWorkflowTest { } private void ok(String... args) { assertThat(cli(args)).as(output).isZero(); } private void init(int count) throws Exception { - ok("init", "--name", "EPIC fixture"); + ok("init", "--storage", "legacy", "--name", "EPIC fixture"); for (int i = 1; i <= count; i++) ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "Work " + i, "--acceptance", "Verified bounded delivery"); Files.writeString(root.resolve("evidence.txt"), "Explicitly synthetic delivery evidence\n"); } diff --git a/src/test/java/net/intrepid/aiengineering/IntegrityTest.java b/src/test/java/net/intrepid/aiengineering/IntegrityTest.java index 8789476..9daed71 100644 --- a/src/test/java/net/intrepid/aiengineering/IntegrityTest.java +++ b/src/test/java/net/intrepid/aiengineering/IntegrityTest.java @@ -17,7 +17,7 @@ class IntegrityTest { } private void ok(String... args) { assertThat(cli(args)).as(lastOutput).isZero(); } private Path work() { return root.resolve(".ai-engineering/works/WRK-0001-one"); } - private void initWork() { ok("init", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); } + private void initWork() { ok("init", "--storage", "legacy", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); } @Test void missingPayloadAndTamperedEvidenceAreDetected() throws Exception { initWork(); Path source = Files.writeString(root.resolve("source.txt"), "abc"); ok("artifact", "add", "WRK-0001", "--file", source.toString(), "--purpose", "Test integrity"); diff --git a/src/test/java/net/intrepid/aiengineering/ListingTest.java b/src/test/java/net/intrepid/aiengineering/ListingTest.java index 4f4a375..167ef74 100644 --- a/src/test/java/net/intrepid/aiengineering/ListingTest.java +++ b/src/test/java/net/intrepid/aiengineering/ListingTest.java @@ -25,7 +25,7 @@ class ListingTest { } private String ok(String... args) { assertThat(cli(args)).as(output).isZero(); return output; } private JsonNode json(String text) { return Documents.parseJson(text, JsonNode.class); } - private void init() { ok("init", "--name", "List project"); } + private void init() { ok("init", "--storage", "legacy", "--name", "List project"); } private void create(String title) { ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", title, "--acceptance", "Verified fixture"); } private void evidence(String work) throws Exception { Path result = Files.writeString(root.resolve("result.txt"), "Observed fixture result\n"); diff --git a/src/test/java/net/intrepid/aiengineering/LocalCliAcceptanceTest.java b/src/test/java/net/intrepid/aiengineering/LocalCliAcceptanceTest.java index 6c7d26a..6b2d382 100644 --- a/src/test/java/net/intrepid/aiengineering/LocalCliAcceptanceTest.java +++ b/src/test/java/net/intrepid/aiengineering/LocalCliAcceptanceTest.java @@ -22,7 +22,7 @@ class LocalCliAcceptanceTest { assertThat(output).contains("codex-cli", "claude-cli", "fixture-general", "fixture-reviewer"); } @Test void realExecutorConfigurationIsPortableBoundedAndDoesNotRequireAnInstalledCli() throws Exception { - ok("init", "--name", "Test"); + ok("init", "--storage", "legacy", "--name", "Test"); ok("agent", "configure", "--adapter", "codex-cli", "--profile", "general", "--model", "default", "--timeout", "30"); ok("agent", "configure", "--activity", "analyze", "--adapter", "claude-cli", "--profile", "reviewer"); Path config = root.resolve(".ai-engineering/ai-engineering.yaml"); String before = Files.readString(config); @@ -34,7 +34,7 @@ class LocalCliAcceptanceTest { @Test void guidedInitPersistsGeneralAndSpecializationWithoutCallingAModel() { var out = new StringWriter(); var err = new StringWriter(); var input = new StringReader("1\ngeneral\ndefault\n60\n1\n3\nreviewer\ndefault\n90\n1\n"); - int code = new EngineeringCli(root, input).execute(new PrintWriter(out), new PrintWriter(err), "init", ".", "--name", "Guided", "--interactive"); + int code = new EngineeringCli(root, input).execute(new PrintWriter(out), new PrintWriter(err), "init", "--storage", "legacy", ".", "--name", "Guided", "--interactive"); assertThat(code).as(err.toString()).isZero(); var config = new ProjectService().load(root).agents(); assertThat(config.general().adapter()).isEqualTo("codex-cli"); @@ -43,12 +43,12 @@ class LocalCliAcceptanceTest { } @Test void guidedInitWithoutConsoleNeverPublishesAPartialProject() { org.junit.jupiter.api.Assumptions.assumeTrue(System.console() == null); - assertThat(cli("init", "--name", "No console", "--interactive")).isEqualTo(2); + assertThat(cli("init", "--storage", "legacy", "--name", "No console", "--interactive")).isEqualTo(2); assertThat(output).contains("console"); assertThat(Files.exists(root.resolve(".ai-engineering"))).isFalse(); } @Test void incompleteGuidedAnswersDoNotPublishAProject() { var out = new StringWriter(); var err = new StringWriter(); - int code = new EngineeringCli(root, new StringReader("1\ngeneral\n")).execute(new PrintWriter(out), new PrintWriter(err), "init", ".", "--name", "Incomplete", "--interactive"); + int code = new EngineeringCli(root, new StringReader("1\ngeneral\n")).execute(new PrintWriter(out), new PrintWriter(err), "init", "--storage", "legacy", ".", "--name", "Incomplete", "--interactive"); assertThat(code).isEqualTo(2); assertThat(err.toString()).contains("input ended"); assertThat(Files.exists(root.resolve(".ai-engineering"))).isFalse(); } diff --git a/src/test/java/net/intrepid/aiengineering/OperationalSafetyTest.java b/src/test/java/net/intrepid/aiengineering/OperationalSafetyTest.java index e72d6a5..dd5af49 100644 --- a/src/test/java/net/intrepid/aiengineering/OperationalSafetyTest.java +++ b/src/test/java/net/intrepid/aiengineering/OperationalSafetyTest.java @@ -23,7 +23,7 @@ class OperationalSafetyTest { output = out + err.toString(); return code; } private void ok(String... args) { int code = cli(args); assertThat(code).as(output).isZero(); } - private void init() { ok("init", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One", "--acceptance", "A reproducible result"); } + private void init() { ok("init", "--storage", "legacy", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One", "--acceptance", "A reproducible result"); } private Path folder() { return root.resolve(".ai-engineering/works/WRK-0001-one"); } private void artifact() throws Exception { Files.writeString(root.resolve("result.txt"), "Observed test run and command\n"); @@ -57,7 +57,7 @@ class OperationalSafetyTest { } @Test void malformedInstructionBlockDoesNotPublishNewProject() throws Exception { Files.writeString(root.resolve("AGENTS.md"), ""); - assertThat(cli("init", "--name", "Test")).isEqualTo(4); + assertThat(cli("init", "--storage", "legacy", "--name", "Test")).isEqualTo(4); assertThat(Files.exists(root.resolve(".ai-engineering"))).isFalse(); ok("guide"); assertThat(output).contains("agent entry point"); } diff --git a/src/test/java/net/intrepid/aiengineering/OperationalWorkflowTest.java b/src/test/java/net/intrepid/aiengineering/OperationalWorkflowTest.java index 6607184..446b2bc 100644 --- a/src/test/java/net/intrepid/aiengineering/OperationalWorkflowTest.java +++ b/src/test/java/net/intrepid/aiengineering/OperationalWorkflowTest.java @@ -18,7 +18,7 @@ class OperationalWorkflowTest { private void ok(String... args) { int code = cli(args); assertThat(code).as(output).isZero(); } @Test void discoveryApprovalPlanningCompletionArchiveAndReopening() throws Exception { Files.writeString(root.resolve("AGENTS.md"), "# Project rules\n\nPreserve the game save.\n"); - ok("init", "--name", "Operational project"); + ok("init", "--storage", "legacy", "--name", "Operational project"); assertThat(Files.readString(root.resolve("AGENTS.md"))).startsWith("# Project rules\n\nPreserve the game save.\n") .contains(".ai-engineering/README.md", "ai-engineering:start"); assertThat(Files.readString(root.resolve(".ai-engineering/README.md"))).contains("next-actions", "human-approved", "work context"); @@ -61,7 +61,7 @@ class OperationalWorkflowTest { ok("project", "validate"); } @Test void acceptedDecisionsCanBeSupersededWithoutLosingHistory() { - ok("init", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); + ok("init", "--storage", "legacy", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); ok("decision", "draft", "WRK-0001", "--title", "First", "--context", "Problem", "--approach", "A", "--rationale", "Reason"); ok("decision", "accept", "WRK-0001", "DEC-0001", "--by", "owner", "--reason", "Agreed", "--human-approved"); ok("decision", "revise", "WRK-0001", "DEC-0001", "--by", "agent", "--reason", "New evidence"); @@ -71,7 +71,7 @@ class OperationalWorkflowTest { ok("project", "validate"); } @Test void revisionTamperingIsDiagnosedAndReadinessShowsPendingWork() throws Exception { - ok("init", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); + ok("init", "--storage", "legacy", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); ok("next-actions", "WRK-0001", "--format", "json"); assertThat(output).contains("REFINE_SCOPE"); ok("decision", "draft", "WRK-0001", "--title", "First"); ok("decision", "update", "WRK-0001", "DEC-0001", "--context", "Problem", "--by", "agent", "--reason", "Refinement"); diff --git a/src/test/java/net/intrepid/aiengineering/PersistenceTest.java b/src/test/java/net/intrepid/aiengineering/PersistenceTest.java index 81270ff..e25e282 100644 --- a/src/test/java/net/intrepid/aiengineering/PersistenceTest.java +++ b/src/test/java/net/intrepid/aiengineering/PersistenceTest.java @@ -21,7 +21,7 @@ class PersistenceTest { try (var files = Files.list(root)) { assertThat(files.map(p -> p.getFileName().toString())).containsExactly("state.yaml"); } } @Test void workIdentityReservationSurvivesRemovalAndModelsAreImmutable() throws Exception { - var projects = new ProjectService(); projects.initialize(root, "Test"); var works = new WorkService(); + var projects = new ProjectService(); projects.initializeLegacy(root, "Test"); var works = new WorkService(); var constraints = new ArrayList<>(List.of("Original")); var one = works.create(root, "One", "", "Goal", "", constraints, List.of(), List.of(), "human"); constraints.add("Changed"); assertThat(one.constraints()).containsExactly("Original"); @@ -41,13 +41,13 @@ class PersistenceTest { assertThatThrownBy(() -> new ProjectConfig.Access(false, true)).isInstanceOf(ProtocolException.class); } @Test void numericLifecycleValuesAreRejected() { - var projects = new ProjectService(); projects.initialize(root, "Test"); var works = new WorkService(); + var projects = new ProjectService(); projects.initializeLegacy(root, "Test"); var works = new WorkService(); var work = works.create(root, "One", "", "Goal", "", List.of(), List.of(), List.of(), "human"); String invalid = Documents.yaml(work).replaceAll("(?m)^status:.*$", "status: 0"); assertThatThrownBy(() -> Documents.parse(invalid, Work.class)).isInstanceOf(ProtocolException.class); } @Test void realGitSubmoduleCanBeRegisteredWithoutReconfiguration() throws Exception { - var projects = new ProjectService(); projects.initialize(root, "Test"); + var projects = new ProjectService(); projects.initializeLegacy(root, "Test"); Path upstream = Files.createTempDirectory("aie-upstream-"); git("init", upstream.toString()); git("-C", upstream.toString(), "-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", "commit", "--allow-empty", "-m", "fixture"); diff --git a/src/test/java/net/intrepid/aiengineering/PlanConsolidationSafetyTest.java b/src/test/java/net/intrepid/aiengineering/PlanConsolidationSafetyTest.java index c1254e3..da4a25a 100644 --- a/src/test/java/net/intrepid/aiengineering/PlanConsolidationSafetyTest.java +++ b/src/test/java/net/intrepid/aiengineering/PlanConsolidationSafetyTest.java @@ -23,7 +23,7 @@ class PlanConsolidationSafetyTest { private Work work() { return new WorkService().load(root, "WRK-0001"); } private Plan plan(String id) { return new PlanService().get(root, "WRK-0001", id); } private void init() throws Exception { - ok("init", "--name", "Safety"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "Delivery", "--acceptance", "Recorded execution"); + ok("init", "--storage", "legacy", "--name", "Safety"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "Delivery", "--acceptance", "Recorded execution"); Files.writeString(root.resolve("evidence.txt"), "Synthetic result\n"); ok("artifact", "add", "WRK-0001", "--file", "evidence.txt", "--purpose", "Fixture result"); } diff --git a/src/test/java/net/intrepid/aiengineering/PlanConsolidationTest.java b/src/test/java/net/intrepid/aiengineering/PlanConsolidationTest.java index b092843..d3256d2 100644 --- a/src/test/java/net/intrepid/aiengineering/PlanConsolidationTest.java +++ b/src/test/java/net/intrepid/aiengineering/PlanConsolidationTest.java @@ -23,7 +23,7 @@ class PlanConsolidationTest { private Work work() { return new WorkService().load(root, "WRK-0001"); } private Plan plan(String id) { return new PlanService().get(root, "WRK-0001", id); } private void init() throws Exception { - ok("init", "--name", "Consolidation"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "Delivery"); + ok("init", "--storage", "legacy", "--name", "Consolidation"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "Delivery"); Files.writeString(root.resolve("evidence.txt"), "Synthetic verified result\n"); ok("artifact", "add", "WRK-0001", "--file", "evidence.txt", "--purpose", "Fixture result"); } diff --git a/src/test/java/net/intrepid/aiengineering/PlanDecisionPromotionTest.java b/src/test/java/net/intrepid/aiengineering/PlanDecisionPromotionTest.java index b0c19c2..e024fa9 100644 --- a/src/test/java/net/intrepid/aiengineering/PlanDecisionPromotionTest.java +++ b/src/test/java/net/intrepid/aiengineering/PlanDecisionPromotionTest.java @@ -20,7 +20,7 @@ class PlanDecisionPromotionTest { output = out + err.toString(); return code; } private void ok(String... args) { assertThat(cli(args)).as(output).isZero(); } - private void init() { ok("init", "--name", "Promotion"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); } + private void init() { ok("init", "--storage", "legacy", "--name", "Promotion"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One"); } private void draft(String title) { ok("decision", "draft", "WRK-0001", "--title", title, "--context", "Problem", "--approach", "Approach", "--rationale", "Reason"); } diff --git a/src/test/java/net/intrepid/aiengineering/PlanExperimentsTest.java b/src/test/java/net/intrepid/aiengineering/PlanExperimentsTest.java index 16d3f55..856ad94 100644 --- a/src/test/java/net/intrepid/aiengineering/PlanExperimentsTest.java +++ b/src/test/java/net/intrepid/aiengineering/PlanExperimentsTest.java @@ -21,7 +21,7 @@ class PlanExperimentsTest { private void ok(String... args) { assertThat(cli(args)).as(output).isZero(); } private Plan plan() { return new PlanService().get(root, "WRK-0001", "PLN-0001"); } private void init() throws Exception { - ok("init", "--name", "Experiments"); ok("work", "create", "Delivery"); + ok("init", "--storage", "legacy", "--name", "Experiments"); ok("work", "create", "Delivery"); ok("work", "guidance", "WRK-0001", "--mode", "DIRECT", "--by", "fixture-human", "--reason", "Explicit fixture choice", "--human-approved"); ok("decision", "draft", "WRK-0001", "--title", "Choose approach", "--context", "Latency problem", "--approach", "Measure and optimize", "--rationale", "Preserve compatibility"); ok("decision", "accept", "WRK-0001", "DEC-0001", "--by", "fixture-human", "--reason", "Approve concrete DEC", "--human-approved"); diff --git a/src/test/java/net/intrepid/aiengineering/ProcessContinuityTest.java b/src/test/java/net/intrepid/aiengineering/ProcessContinuityTest.java index 938b4f6..cf167ca 100644 --- a/src/test/java/net/intrepid/aiengineering/ProcessContinuityTest.java +++ b/src/test/java/net/intrepid/aiengineering/ProcessContinuityTest.java @@ -110,10 +110,11 @@ class ProcessContinuityTest { assertThat(cliWithoutGit("work", "context", "WRK-0001")).isEqualTo(markdown); cliWithoutGit("work", "reopen", "WRK-0002", "--by", "fixture-owner", "--reason", "New evidence"); assertThat(cliWithoutGit("work", "show", "WRK-0001", "--format", "json")).contains("\"status\" : \"ACTIVE\""); - cliWithoutGit("work", "complete", "WRK-0002", "--by", "fixture-owner", "--summary", "Reviewed new fixture", "--human-approved", "--criterion", "1=ART-0001", "--no-integration-needed", "Disposable fixture"); - Path work = root.resolve(".ai-engineering/works/WRK-0001-parent/work.md"); byte[] before = Files.readAllBytes(work); + cliWithoutGit("artifact", "add", "WRK-0002", "--file", "result.txt", "--purpose", "Current evaluation after reopening"); + cliWithoutGit("work", "complete", "WRK-0002", "--by", "fixture-owner", "--summary", "Reviewed new fixture", "--human-approved", "--criterion", "1=ART-0002", "--no-integration-needed", "Disposable fixture"); + var works = new net.intrepid.aiengineering.work.WorkService(); var before = works.load(root, "WRK-0001"); cliWithoutGit("epic", "reconcile", "WRK-0001", "--requester", "another-agent", "--request-id", "resumed"); - assertThat(Files.readAllBytes(work)).isEqualTo(before); + assertThat(works.load(root, "WRK-0001")).isEqualTo(before); cliWithoutGit("project", "validate"); assertThat(Files.exists(root.resolve(".git"))).isFalse(); } @Test void guidedSetupSurvivesIndependentExecutionsWithoutProviderOrGitOnPath() throws Exception { diff --git a/src/test/java/net/intrepid/aiengineering/ProtocolIntegrationTest.java b/src/test/java/net/intrepid/aiengineering/ProtocolIntegrationTest.java index 32a6822..d8c298d 100644 --- a/src/test/java/net/intrepid/aiengineering/ProtocolIntegrationTest.java +++ b/src/test/java/net/intrepid/aiengineering/ProtocolIntegrationTest.java @@ -19,7 +19,7 @@ class ProtocolIntegrationTest { var r = run(root, args); assertThat(r.code()).as(r.err()).isZero(); return r; } - void init() { ok("init", "--name", "Test Project"); } + void init() { ok("init", "--storage", "legacy", "--name", "Test Project"); } void repository(String name) throws Exception { Path path = Files.createDirectory(root.resolve(name)); var process = new ProcessBuilder("git", "init", path.toString()).redirectErrorStream(true).start(); @@ -79,7 +79,7 @@ class ProtocolIntegrationTest { } @Test void invalidIdentifiersMissingResourcesAndNoOverwrite() throws Exception { init(); - assertThat(run(root, "init", "--name", "Again").code()).isEqualTo(2); + assertThat(run(root, "init", "--storage", "legacy", "--name", "Again").code()).isEqualTo(2); assertThat(run(root, "work", "show", "../../escape").code()).isEqualTo(2); assertThat(run(root, "work", "show", "WRK-9999").code()).isEqualTo(3); assertThat(run(root, "repo", "add", "missing", "--path", "missing").code()).isEqualTo(3); @@ -105,7 +105,7 @@ class ProtocolIntegrationTest { } @Test void cliSmokeAndHelpForEveryCommand() { assertThat(ok("--version").out()).isEqualTo("ai-engineering 0.1.0\n"); - for (String command : new String[]{"", "init", "project", "project show", "project validate", "project compatibility", "repo", "repo add", "repo list", + for (String command : new String[]{"", "init", "--storage", "legacy", "project", "project show", "project validate", "project compatibility", "repo", "repo add", "repo list", "work", "work create", "work update", "work list", "work show", "work validate", "work context", "discussion", "discussion add", "discussion list", "discussion migrate", "decision", "decision draft", "decision list", "decision show", "decision update", "decision accept", "decision reject", "decision revise", "decision history", "artifact", "artifact add", diff --git a/src/test/java/net/intrepid/aiengineering/RefinementSafetyTest.java b/src/test/java/net/intrepid/aiengineering/RefinementSafetyTest.java index 74dfb5c..d0bbcdd 100644 --- a/src/test/java/net/intrepid/aiengineering/RefinementSafetyTest.java +++ b/src/test/java/net/intrepid/aiengineering/RefinementSafetyTest.java @@ -20,7 +20,7 @@ class RefinementSafetyTest { int code=new EngineeringCli(root).execute(new PrintWriter(out),new PrintWriter(err),args); output=out+err.toString(); return code; } private void ok(String... args) { int code=cli(args); assertThat(code).as(output).isZero(); } - private void init() { ok("init","--name","Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy","One"); } + private void init() { ok("init", "--storage", "legacy","--name","Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy","One"); } private Path work() { return root.resolve(".ai-engineering/works/WRK-0001-one"); } @Test void malformedBundleIsFullyPreflightedBeforeAnyMutation() throws Exception { init(); diff --git a/src/test/java/net/intrepid/aiengineering/SqliteArtifactLifecycleTest.java b/src/test/java/net/intrepid/aiengineering/SqliteArtifactLifecycleTest.java new file mode 100644 index 0000000..4b1b4c6 --- /dev/null +++ b/src/test/java/net/intrepid/aiengineering/SqliteArtifactLifecycleTest.java @@ -0,0 +1,137 @@ +package net.intrepid.aiengineering; + +import net.intrepid.aiengineering.artifact.*; +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.project.ProjectService; +import net.intrepid.aiengineering.verification.*; +import net.intrepid.aiengineering.work.*; +import java.nio.file.*; +import java.util.List; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import static org.assertj.core.api.Assertions.*; + +class SqliteArtifactLifecycleTest { + @TempDir Path root; + private final WorkService works = new WorkService(); + private final ArtifactService artifacts = new ArtifactService(); + private final VerificationService verification = new VerificationService(); + private String init() { + new ProjectService().initializeSqlite(root, "Retention"); + var work = works.create(root, "Deliver", "", "Check", "", List.of(), List.of("Checked"), List.of(), "fixture"); + works.guidance(root, work.id(), WorkGuidance.Mode.DIRECT, WorkGuidance.ApprovalPolicy.WAIVED, "fixture-owner", "Explicit synthetic policy", true); + return work.id(); + } + private Artifact evidence(String work) { return artifacts.attachBytes(root, work, "Observed result".getBytes(java.nio.charset.StandardCharsets.UTF_8), "Check", "fixture", "fixture"); } + private Path payload(Artifact artifact) { return works.folder(root, artifact.workId()).resolve(artifact.path()); } + private void complete(String work, String artifact) { verification.complete(root, work, "fixture-owner", "Reviewed", true, List.of("1=" + artifact), List.of(), "Inspection only"); } + @Test void temporaryEvidenceRetiresOnlyAfterCompletionAndRequestedOutputRemainsAtItsDestination() throws Exception { + String work = init(); Path output = root.resolve("requested-output.md"); Files.writeString(output, "Requested delivery"); + var artifact = artifacts.attach(root, work, output, "Temporary check copy", null, "fixture"); + assertThat(payload(artifact)).exists(); + assertThatThrownBy(() -> ArtifactLifecycle.prepareCompleted(root, work)).hasMessageContaining("Pending Work"); + complete(work, artifact.id()); + assertThat(payload(artifact)).doesNotExist(); + assertThat(ArtifactLifecycle.state(root, work, artifact.id())).isEqualTo("DISCARDED"); + assertThat(Files.readString(output)).isEqualTo("Requested delivery"); + assertThat(verification.work(root, work).issues()).isEmpty(); + assertThat(verification.context(root, work).work().status()).isEqualTo(Work.Status.COMPLETED); + } + @Test void missingEvidenceBeforeTheCheckCannotBeRecordedAsLegitimateRetirement() throws Exception { + String work = init(); var artifact = evidence(work); Files.delete(payload(artifact)); + assertThatThrownBy(() -> complete(work, artifact.id())).hasMessageContaining("Missing artifact payload"); + assertThat(works.load(root, work).status()).isEqualTo(Work.Status.OPEN); + assertThat(ArtifactLifecycle.state(root, work, artifact.id())).isEqualTo("AVAILABLE"); + assertThat(verification.work(root, work).valid()).isFalse(); + } + @Test void rollbackKeepsCheckInputsAndRevertsCompletionAndRetirementTogether() { + String work = init(); var artifact = evidence(work); + assertThatThrownBy(() -> Filespace.locked(root, () -> { + complete(work, artifact.id()); throw new IllegalStateException("Interrupted before commit"); + })).hasMessageContaining("Interrupted before commit"); + assertThat(works.load(root, work).status()).isEqualTo(Work.Status.OPEN); + assertThat(works.load(root, work).completions()).isEmpty(); + assertThat(ArtifactLifecycle.state(root, work, artifact.id())).isEqualTo("AVAILABLE"); + assertThat(payload(artifact)).exists(); + complete(work, artifact.id()); assertThat(payload(artifact)).doesNotExist(); + } + @Test void interruptedPostCommitCleanupIsRecoverableEvenIfThePayloadWasAlreadyRemoved() throws Exception { + String work = init(); var artifact = evidence(work); + assertThatThrownBy(() -> SqliteDatabase.write(root, connection -> { + SqliteDatabase.afterCommit(root, () -> { throw new IllegalStateException("Synthetic crash boundary"); }); + complete(work, artifact.id()); return null; + })).hasMessageContaining("change committed"); + assertThat(works.load(root, work).status()).isEqualTo(Work.Status.COMPLETED); + assertThat(ArtifactLifecycle.state(root, work, artifact.id())).isEqualTo("DISCARD_PENDING"); + assertThat(payload(artifact)).exists(); + assertThat(verification.work(root, work).issues()).isEmpty(); + // Exact crash boundary: unlink happened, metadata acknowledgement did not. + Files.delete(payload(artifact)); + assertThat(ArtifactLifecycle.recover(root, work)).isEqualTo(1); + assertThat(ArtifactLifecycle.recover(root, work)).isZero(); + assertThat(verification.work(root, work).issues()).isEmpty(); + } + @Test void retiredEvidenceCannotBeReusedAsFreshInputAfterReopening() { + String work = init(); var artifact = evidence(work); complete(work, artifact.id()); + verification.reopen(root, work, "fixture-owner", "New observations", "fixture-owner", "reopen"); + assertThatThrownBy(() -> complete(work, artifact.id())).hasMessageContaining("already retired"); + assertThatThrownBy(() -> artifacts.requireAvailable(root, work, List.of(artifact.id()))).hasMessageContaining("already retired"); + var current = evidence(work); complete(work, current.id()); + assertThat(works.load(root, work).completions()).hasSize(2); + assertThat(verification.work(root, work).issues()).isEmpty(); + } + @Test void rolledBackPublicationRemovesOnlyItsOwnPayloadAndAllowsTheSameIdToRetry() { + String work = init(); var original = evidence(work); + assertThatThrownBy(() -> Filespace.locked(root, () -> { + evidence(work); throw new IllegalStateException("Reject related operation"); + })).hasMessageContaining("Reject related operation"); + assertThat(payload(original)).exists(); + assertThat(works.folder(root, work).resolve("artifacts/evidence/ART-0002")).doesNotExist(); + assertThat(artifacts.list(root, work)).hasSize(1); + assertThat(evidence(work).id()).isEqualTo("ART-0002"); + assertThat(ArtifactPublication.recover(root)).isZero(); + } + @Test void importedOriginalsArePreservedAndInternalReceiptsNeedNoPayloadFile() { + String work = init(); + var original = artifacts.attachBytes(root, work, "Legacy original".getBytes(java.nio.charset.StandardCharsets.UTF_8), "Preserve import", "discussion-framework:fixture:AGD-001", "fixture"); + var normal = evidence(work); complete(work, normal.id()); + assertThat(payload(original)).exists(); + verification.reopen(root, work, "fixture-owner", "Receipt fixture", "fixture-owner", "reopen"); + var source = new PlanCoordinator.PlanSource("PLN-0001", 1, Revisions.hash("Plan fixture")); + var receipt = new PlanCoordinator.Receipt(1, work, Revisions.hash("Inputs"), List.of(source)); + var stored = artifacts.attachReceipt(root, work, receipt, "Internal facts", "fixture-receipt", "system:plans"); + assertThat(payload(stored)).doesNotExist(); + assertThat(artifacts.readReceipt(root, work, stored, PlanCoordinator.Receipt.class)).isEqualTo(receipt); + artifacts.validate(root, work); + assertThat(ArtifactLifecycle.state(root, work, stored.id())).isEqualTo("STRUCTURED"); + } + @Test void crashPublicationJournalDistinguishesOrphanFromCommittedPayload() throws Exception { + String work = init(); var original = evidence(work); Path folder = works.folder(root, work); + var orphan = new Artifact(1, "ART-0002", work, "fixture", "Interrupted", "artifacts/evidence/ART-0002/payload", + original.sha256(), original.size(), "fixture", original.createdAt()); + Path target = folder.resolve("artifacts/evidence/ART-0002"); Files.createDirectory(target); + Files.copy(payload(original), target.resolve("payload")); + Path journals = root.resolve(".ai-engineering/.local/artifact-publications"); Files.createDirectories(journals); + Path journal = journals.resolve(java.util.UUID.randomUUID() + ".json"); + Files.writeString(journal, Documents.json(new ArtifactPublication.Intent(orphan, root.relativize(target).toString(), + root.relativize(target.resolveSibling(".ART-0002-interrupted.tmp")).toString()))); + assertThat(ArtifactPublication.recover(root)).isEqualTo(1); + assertThat(target).doesNotExist(); assertThat(payload(original)).exists(); + Files.writeString(journal, Documents.json(new ArtifactPublication.Intent(original, + root.relativize(payload(original).getParent()).toString(), + root.relativize(target.resolveSibling(".ART-0001-interrupted.tmp")).toString()))); + assertThat(ArtifactPublication.recover(root)).isEqualTo(1); + assertThat(payload(original)).exists(); + assertThat(ArtifactPublication.recover(root)).isZero(); + } + @Test void rejectedPreparedWorkDoesNotLeakItsArtifactOrReserveAnIdentity() { + new ProjectService().initializeSqlite(root, "Rejected"); + assertThatThrownBy(() -> works.createPrepared(root, "One", "", "Check", "", List.of(), List.of(), List.of(), "fixture", (folder, work) -> { + artifacts.writePrepared(folder, work.id(), "ART-0001", "Temporary".getBytes(java.nio.charset.StandardCharsets.UTF_8), "Check", "fixture", "fixture"); + throw new IllegalStateException("Reject preparation"); + })).hasMessageContaining("Reject preparation"); + assertThat(works.list(root)).isEmpty(); + assertThat(root.resolve(".ai-engineering/works/WRK-0001-one")).doesNotExist(); + assertThat(works.create(root, "One", "", "Check", "", List.of(), List.of(), List.of(), "fixture").id()).isEqualTo("WRK-0001"); + } +} diff --git a/src/test/java/net/intrepid/aiengineering/SqliteCoordinationTest.java b/src/test/java/net/intrepid/aiengineering/SqliteCoordinationTest.java new file mode 100644 index 0000000..d52049f --- /dev/null +++ b/src/test/java/net/intrepid/aiengineering/SqliteCoordinationTest.java @@ -0,0 +1,125 @@ +package net.intrepid.aiengineering; + +import net.intrepid.aiengineering.agent.*; +import net.intrepid.aiengineering.artifact.*; +import net.intrepid.aiengineering.decision.*; +import net.intrepid.aiengineering.discussion.*; +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.planning.*; +import net.intrepid.aiengineering.project.*; +import net.intrepid.aiengineering.verification.*; +import net.intrepid.aiengineering.work.*; +import java.nio.file.Path; +import java.util.*; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import static org.assertj.core.api.Assertions.*; + +class SqliteCoordinationTest { + @TempDir Path root; + private final WorkService works = new WorkService(); + private final EpicService epics = new EpicService(); + private void init() { new ProjectService().initializeSqlite(root, "Coordination"); } + private Work work(String title) { + var work = works.create(root, title, "", "Deliver", "", List.of(), List.of("Checked"), List.of(), "fixture"); + return works.guidance(root, work.id(), WorkGuidance.Mode.DIRECT, WorkGuidance.ApprovalPolicy.WAIVED, + "fixture-owner", "Explicit synthetic policy", true); + } + private String evidence(String id) { return new ArtifactService().attachBytes(root, id, "Observed".getBytes(java.nio.charset.StandardCharsets.UTF_8), "Check", "fixture", "fixture").id(); } + private void complete(String id) { + new VerificationService().complete(root, id, "fixture-owner", "Reviewed", true, + List.of("1=" + evidence(id)), List.of(), "Inspection only"); + } + @Test void runsRemainIdempotentAndSourceFreshnessIsDerivedFromPersistedContext() { + init(); String id = work("Investigate").id(); var agents = new AgentService(); + agents.configure(root, "general", "fixture-general", null, null, null); + var run = agents.run(root, id, "summarize current context", null, "fixture-owner", "summary"); + assertThat(new AgentService().get(root, id, run.id())).isEqualTo(run); + assertThat(agents.views(root, id).getFirst().stale()).isFalse(); + assertThat(agents.run(root, id, run.task(), null, "fixture-owner", "summary")).isEqualTo(run); + assertThatThrownBy(() -> agents.run(root, id, "Different", null, "fixture-owner", "summary")).hasMessageContaining("different input"); + new DiscussionService().add(root, id, "New observation", DiscussionEntry.Kind.NOTE, "fixture", "main", null); + assertThat(agents.views(root, id).getFirst().stale()).isTrue(); + var refine = agents.run(root, id, "Storage: Compare options", null, "fixture-owner", "refine"); + assertThat(refine.status()).isEqualTo(AgentRun.Status.COMPLETED); + assertThat(refine.applied()).isNotEmpty(); + assertThat(works.folder(root, id).resolve("agent-runs/RUN-0001.md")).doesNotExist(); + assertThat(new VerificationService().work(root, id).issues()).isEmpty(); + } + @Test void failedProposalRollsBackEveryAppliedRecordAndKeepsOnlyFailureDiagnostic() { + init(); String id = work("Investigate").id(); + new TopicService().create(root, id, "Existing", "", List.of(), "fixture"); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { + statement.execute("CREATE TRIGGER reject_second BEFORE INSERT ON data_topic WHEN NEW.f_title='Second' BEGIN SELECT RAISE(ABORT,'Synthetic publication failure'); END"); + } + return null; + }); + AgentAdapter adapter = new AgentAdapter() { + public String id() { return "failing-fixture"; } + public String classify(AgentContext context, String task) { return "refine"; } + public AgentProposal propose(AgentContext context, Request request) { + return new AgentProposal(id(), true, "Apply two topics", List.of( + new AgentProposal.TopicDraft("first", "First", "", List.of("@request")), + new AgentProposal.TopicDraft("second", "Second", "", List.of("@request"))), List.of(), List.of(), List.of(), null); + } + }; + var agents = new AgentService(Map.of(adapter.id(), adapter)); + agents.configure(root, "general", adapter.id(), "test", "test", null); + assertThatThrownBy(() -> agents.run(root, id, "Input", null, "fixture-owner", "failed")) + .hasMessageContaining("rolled back"); + assertThat(new TopicService().list(root, id)).extracting(Topic::title).containsExactly("Existing"); + assertThat(works.load(root, id).discussions()).isEmpty(); + var failed = agents.history(root, id).getFirst(); + assertThat(failed.status()).isEqualTo(AgentRun.Status.FAILED); + assertThat(failed.applied()).isEmpty(); + assertThat(failed.error()).contains("Synthetic publication failure"); + assertThatThrownBy(() -> agents.run(root, id, "Input", null, "fixture-owner", "failed")).hasMessageContaining("incomplete/failed"); + assertThat(new VerificationService().work(root, id).issues()).isEmpty(); + } + @Test void epicAuthorityHistoryAndCompletionPropagateWithoutDuplicateReceipts() { + init(); String parent = work("Parent").id(), child = work("Child").id(); + epics.configure(root, parent, Epic.Mode.RESULTS, "fixture-owner", "Aggregate"); + epics.link(root, parent, child, "fixture-owner", "Required"); + assertThatThrownBy(() -> epics.authorize(root, parent, "fixture", "No attestation", false)).hasMessageContaining("human-approved"); + epics.authorize(root, parent, "fixture-owner", "Reviewed", true); + String hash = epics.policyHash(root, parent); + assertThat(epics.byHash(root, parent, hash).authorization().humanApproved()).isTrue(); + complete(child); + assertThat(works.load(root, parent).status()).isEqualTo(Work.Status.COMPLETED); + assertThat(works.load(root, parent).completions().getLast().origin()).isEqualTo(Work.CompletionOrigin.SYSTEM_EPIC); + new EpicCoordinator().reconcile(root, child, "fixture", "same-inputs"); + assertThat(works.load(root, parent).completions()).hasSize(1); + assertThat(new ArtifactService().list(root, parent)).hasSize(1); + assertThat(new VerificationService().work(root, parent).issues()).isEmpty(); + new VerificationService().reopen(root, child, "fixture-owner", "New observation", "fixture-owner", "reopen"); + assertThat(works.load(root, parent).status()).isEqualTo(Work.Status.ACTIVE); + complete(child); + assertThat(works.load(root, parent).completions()).hasSize(2); + assertThat(epics.history(root, parent)).hasSize(3); + assertThat(new VerificationService().work(root, parent).issues()).isEmpty(); + assertThat(works.folder(root, parent).resolve("epic/" + parent + ".md")).doesNotExist(); + } + @Test void planCompletionAndReconciliationUseTheSameTransactionalSources() { + init(); String id = work("Implement").id(); var plans = new PlanService(); + var decision = new DecisionService().draft(root, id, "Approach", "Context", "Change", "Reason", List.of(), "fixture"); + var plan = plans.create(root, id, "Deliver", "", List.of(decision.id()), "fixture"); + plans.addStep(root, id, plan.id(), "Do", "", List.of(), List.of(), "fixture", "Scope"); + String art = evidence(id); var coordinator = new PlanCoordinator(); + coordinator.change(root, id, "fixture", "finish", () -> plans.stepStatus(root, id, plan.id(), "TSK-0001", Plan.Status.COMPLETED, "fixture", "Checked", List.of(art))); + assertThat(works.load(root, id).status()).isEqualTo(Work.Status.COMPLETED); + coordinator.reconcile(root, id, "fixture", "finish"); + assertThat(works.load(root, id).completions()).hasSize(1); + assertThat(new VerificationService().work(root, id).issues()).isEmpty(); + } + @Test void decompositionNeverAggregatesAndChangedScopeRevokesResultsAuthority() { + init(); String parent = work("Parent").id(), child = work("Child").id(); + epics.configure(root, parent, Epic.Mode.DECOMPOSITION, "fixture-owner", "Independent"); + epics.link(root, parent, child, "fixture-owner", "Related"); + complete(child); + assertThat(works.load(root, parent).status()).isEqualTo(Work.Status.OPEN); + complete(parent); + assertThat(works.load(root, parent).completions().getLast().origin()).isEqualTo(Work.CompletionOrigin.HUMAN); + assertThat(new VerificationService().work(root, parent).issues()).isEmpty(); + } +} diff --git a/src/test/java/net/intrepid/aiengineering/SqliteDatabaseTest.java b/src/test/java/net/intrepid/aiengineering/SqliteDatabaseTest.java new file mode 100644 index 0000000..87acc20 --- /dev/null +++ b/src/test/java/net/intrepid/aiengineering/SqliteDatabaseTest.java @@ -0,0 +1,181 @@ +package net.intrepid.aiengineering; + +import net.intrepid.aiengineering.filesystem.*; +import java.nio.file.*; +import java.util.concurrent.*; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import static org.assertj.core.api.Assertions.*; + +class SqliteDatabaseTest { + @TempDir Path root; + + private long count() { + return SqliteDatabase.read(root, connection -> { + try (var statement = connection.createStatement(); var rows = statement.executeQuery("SELECT count(*) FROM work_identity")) { + rows.next(); return rows.getLong(1); + } + }); + } + + @Test void missingDatabaseDoesNotCreateFilesDuringReadOrWrite() { + assertThatThrownBy(() -> SqliteDatabase.read(root, connection -> null)).isInstanceOf(ProtocolException.class).hasMessageContaining("Missing"); + assertThatThrownBy(() -> SqliteDatabase.write(root, connection -> null)).isInstanceOf(ProtocolException.class).hasMessageContaining("Missing"); + assertThat(root.resolve(".ai-engineering")).doesNotExist(); + } + @Test void initializeIsExplicitAndReopenPreservesTypedData() throws Exception { + SqliteDatabase.initialize(root); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.prepareStatement("INSERT INTO work_identity VALUES (?)")) { + statement.setString(1, "WRK-0001 — memória"); statement.executeUpdate(); + } + return null; + }); + assertThat(count()).isEqualTo(1); + assertThatThrownBy(() -> SqliteDatabase.initialize(root)).isInstanceOf(ProtocolException.class).hasMessageContaining("already exists"); + assertThat(count()).isEqualTo(1); + } + @Test void encodedRootNamesAreUsedAsPathsRatherThanJdbcOptions() throws Exception { + Path encoded = Files.createDirectory(root.resolve("space ? # —")); + SqliteDatabase.initialize(encoded); + String product = SqliteDatabase.read(encoded, connection -> connection.getMetaData().getDatabaseProductName()); + assertThat(product).isEqualTo("SQLite"); + assertThat(encoded.resolve(".ai-engineering/aie.db")).isRegularFile(); + assertThat(root.resolve("space ")).doesNotExist(); + } + @Test void foreignKeysAreEnabledOnEveryConnectionAndFailedCommitRollsBack() { + SqliteDatabase.initialize(root); + assertThatThrownBy(() -> SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { + statement.executeUpdate("INSERT INTO work_identity VALUES ('WRK-0001')"); + statement.executeUpdate("INSERT INTO record_identity VALUES ('WRK-0002','discussion','DSC-0001',1)"); + } + return null; + })).isInstanceOf(ProtocolException.class).hasMessageContaining("integrity"); + assertThat(count()).isZero(); + } + @Test void referencesAreOwnedAndMayBePublishedTogetherInOneTransaction() { + SqliteDatabase.initialize(root); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { + statement.executeUpdate("INSERT INTO work_identity VALUES ('WRK-0001')"); + // Deferred constraints permit publication order within the same operation. + statement.executeUpdate("INSERT INTO current_record VALUES ('WRK-0001','discussion','DSC-0001',1)"); + statement.executeUpdate("INSERT INTO record_identity VALUES ('WRK-0001','discussion','DSC-0001',1)"); + } + return null; + }); + assertThatThrownBy(() -> SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { + statement.executeUpdate("INSERT INTO record_reference VALUES ('WRK-0001','discussion','DSC-0001',1,'response',0,'WRK-0002','discussion','DSC-0001',1)"); + } + return null; + })).isInstanceOf(ProtocolException.class).hasMessageContaining("integrity"); + assertThat(count()).isEqualTo(1); + } + @Test void nestedOperationsShareConnectionAndCaughtFailureCannotCommitPartialChanges() { + SqliteDatabase.initialize(root); + assertThatThrownBy(() -> SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { statement.executeUpdate("INSERT INTO work_identity VALUES ('WRK-0001')"); } + try { + SqliteDatabase.write(root, nested -> { + assertThat(nested).isSameAs(connection); + try (var statement = nested.createStatement()) { statement.executeUpdate("INSERT INTO work_identity VALUES ('WRK-0002')"); } + throw new IllegalStateException("reject inner operation"); + }); + } catch (IllegalStateException expected) { /* An outer service might translate a rejected inner operation. */ } + return null; + })).isInstanceOf(ProtocolException.class).hasMessageContaining("nested operation failed"); + assertThat(count()).isZero(); + } + @Test void readOnlyTransactionCannotWriteOrBeUpgraded() { + SqliteDatabase.initialize(root); + assertThatThrownBy(() -> SqliteDatabase.read(root, connection -> { + try (var statement = connection.createStatement()) { statement.executeUpdate("INSERT INTO work_identity VALUES ('WRK-0001')"); } + return null; + })).isInstanceOf(ProtocolException.class); + assertThatThrownBy(() -> SqliteDatabase.read(root, connection -> SqliteDatabase.write(root, ignored -> null))) + .isInstanceOf(ProtocolException.class).hasMessageContaining("inside a read"); + assertThat(count()).isZero(); + } + @Test void readSnapshotRemainsConsistentWhenAnotherWriterCommits() throws Exception { + SqliteDatabase.initialize(root); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { statement.executeUpdate("INSERT INTO work_identity VALUES ('WRK-0001')"); } + return null; + }); + var observed = new CountDownLatch(1); var committed = new CountDownLatch(1); + try (var executor = Executors.newSingleThreadExecutor()) { + var writer = executor.submit(() -> { + try { + if (!observed.await(5, TimeUnit.SECONDS)) throw new AssertionError("Reader did not start"); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { statement.executeUpdate("INSERT INTO work_identity VALUES ('WRK-0002')"); } + return null; + }); + committed.countDown(); + } catch (InterruptedException failure) { throw new AssertionError(failure); } + }); + SqliteDatabase.read(root, connection -> { + assertThat(count()).isEqualTo(1); observed.countDown(); + try { assertThat(committed.await(5, TimeUnit.SECONDS)).isTrue(); } + catch (InterruptedException failure) { throw new AssertionError(failure); } + assertThat(count()).isEqualTo(1); + return null; + }); + writer.get(5, TimeUnit.SECONDS); + } + assertThat(count()).isEqualTo(2); + } + @Test void writerContentionIsBoundedAndDoesNotPublishAnotherIdentity() throws Exception { + SqliteDatabase.initialize(root); + var locked = new CountDownLatch(1); var release = new CountDownLatch(1); + try (var executor = Executors.newSingleThreadExecutor()) { + var owner = executor.submit(() -> SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { statement.executeUpdate("INSERT INTO work_identity VALUES ('WRK-0001')"); } + locked.countDown(); + try { assertThat(release.await(5, TimeUnit.SECONDS)).isTrue(); } + catch (InterruptedException failure) { throw new AssertionError(failure); } + return null; + })); + try { + assertThat(locked.await(5, TimeUnit.SECONDS)).isTrue(); + assertThatThrownBy(() -> SqliteDatabase.write(root, 75, connection -> null)) + .isInstanceOf(ProtocolException.class).hasMessageContaining("busy").hasMessageContaining("75 ms"); + } finally { release.countDown(); } + owner.get(5, TimeUnit.SECONDS); + } + assertThat(count()).isEqualTo(1); + } + @Test void futureSchemaIsRefusedWithoutRewritingIt() { + SqliteDatabase.initialize(root); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { statement.execute("PRAGMA user_version=99"); } + return null; + }); + assertThatThrownBy(() -> SqliteDatabase.read(root, connection -> null)) + .isInstanceOf(ProtocolException.class).hasMessageContaining("Unsupported"); + assertThatThrownBy(() -> SqliteDatabase.write(root, connection -> null)) + .isInstanceOf(ProtocolException.class).hasMessageContaining("Unsupported"); + } + @Test void databaseAndSidecarSymlinksAreRejectedWithoutFollowingTargets() throws Exception { + Files.createDirectories(root.resolve(".ai-engineering")); + Path outside = Files.writeString(root.resolve("private.txt"), "PRIVATE TARGET"); + Path db = root.resolve(".ai-engineering/aie.db"); + Files.createSymbolicLink(db, outside); + assertThatThrownBy(() -> SqliteDatabase.read(root, connection -> null)) + .isInstanceOf(ProtocolException.class).hasMessageContaining("Symlink rejected").hasMessageNotContaining("PRIVATE TARGET"); + Files.delete(db); SqliteDatabase.initialize(root); + Files.createSymbolicLink(root.resolve(".ai-engineering/aie.db-wal"), outside); + assertThatThrownBy(() -> SqliteDatabase.write(root, connection -> null)) + .isInstanceOf(ProtocolException.class).hasMessageContaining("Symlink rejected"); + assertThat(Files.readString(outside)).isEqualTo("PRIVATE TARGET"); + } + @Test void initializationDoesNotReplaceAnOrphanSidecar() throws Exception { + Files.createDirectories(root.resolve(".ai-engineering")); + Path orphan = Files.writeString(root.resolve(".ai-engineering/aie.db-wal"), "inspect me"); + assertThatThrownBy(() -> SqliteDatabase.initialize(root)).isInstanceOf(ProtocolException.class).hasMessageContaining("requires inspection"); + assertThat(Files.readString(orphan)).isEqualTo("inspect me"); + assertThat(SqliteDatabase.path(root)).doesNotExist(); + } +} diff --git a/src/test/java/net/intrepid/aiengineering/SqliteImplementationTest.java b/src/test/java/net/intrepid/aiengineering/SqliteImplementationTest.java new file mode 100644 index 0000000..c5f336a --- /dev/null +++ b/src/test/java/net/intrepid/aiengineering/SqliteImplementationTest.java @@ -0,0 +1,124 @@ +package net.intrepid.aiengineering; + +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.project.ProjectService; +import net.intrepid.aiengineering.work.*; +import net.intrepid.aiengineering.decision.*; +import net.intrepid.aiengineering.planning.*; +import net.intrepid.aiengineering.discussion.*; +import net.intrepid.aiengineering.artifact.ArtifactService; +import java.nio.charset.StandardCharsets; +import java.nio.file.Path; +import java.util.List; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import static org.assertj.core.api.Assertions.*; + +class SqliteImplementationTest { + @TempDir Path root; + private final WorkService works = new WorkService(); + private final DecisionService decisions = new DecisionService(); + private final PlanService plans = new PlanService(); + private Work init(boolean waived) { + new ProjectService().initializeSqlite(root, "Implementation"); + var work = works.create(root, "Deliver", "", "Keep quality", "", List.of(), List.of("Gate met"), List.of(), "fixture"); + return works.guidance(root, work.id(), WorkGuidance.Mode.DIRECT, + waived ? WorkGuidance.ApprovalPolicy.WAIVED : WorkGuidance.ApprovalPolicy.REQUIRED, + "fixture-owner", "Explicit synthetic fixture policy", true); + } + private Decision draft(String work) { return decisions.draft(root, work, "Approach", "Context", "Small change", "Bounded", List.of(), "fixture", "Useful narrative — UTF-8"); } + private Decision accepted(String work) { + var decision = draft(work); return decisions.accept(root, work, decision.id(), "fixture-owner", "Reviewed", true); + } + private String evidence(String work) { + return new ArtifactService().attachBytes(root, work, "Observed result — UTF-8".getBytes(StandardCharsets.UTF_8), "Check result", "fixture", "fixture").id(); + } + + @Test void approvalRemainsExplicitAndAcceptedContentCannotBeSilentlyChanged() { + var work = init(false); var draft = draft(work.id()); + assertThatThrownBy(() -> plans.create(root, work.id(), "Forbidden", "", List.of(draft.id()), "fixture")) + .isInstanceOf(ProtocolException.class).hasMessageContaining("Human approval"); + assertThatThrownBy(() -> decisions.accept(root, work.id(), draft.id(), "fixture-owner", "No attestation", false)) + .isInstanceOf(ProtocolException.class); + assertThat(decisions.get(root, work.id(), draft.id()).revision()).isEqualTo(1); + var accepted = decisions.accept(root, work.id(), draft.id(), "fixture-owner", "Reviewed", true); + assertThat(accepted.approvals().getLast().humanApproved()).isTrue(); + assertThat(decisions.history(root, work.id(), draft.id())).hasSize(2); + assertThat(accepted.text()).isEqualTo(draft.text()); + assertThatThrownBy(() -> decisions.update(root, work.id(), draft.id(), + new Decision.Update("Silent replacement", null, null, null, null, null, null, null, null), "fixture", "Attempt")) + .isInstanceOf(ProtocolException.class).hasMessageContaining("immutable"); + assertThat(works.folder(root, work.id()).resolve("decisions/DEC-0001.md")).doesNotExist(); + } + @Test void planDependenciesExperimentsAndEvidenceSurviveRevisions() { + var work = init(false); var decision = accepted(work.id()); String art = evidence(work.id()); + var plan = plans.create(root, work.id(), "Delivery", "Implementation cycle", List.of(decision.id()), "fixture"); + plans.addStep(root, work.id(), plan.id(), "First", "", List.of("Criterion"), List.of(), "fixture", "Refine"); + plans.addStep(root, work.id(), plan.id(), "Second", "", List.of(), List.of("TSK-0001"), "fixture", "Refine"); + assertThatThrownBy(() -> plans.stepStatus(root, work.id(), plan.id(), "TSK-0002", Plan.Status.ACTIVE, "fixture", "Start early", List.of())) + .isInstanceOf(ProtocolException.class); + plans.startExperiment(root, work.id(), plan.id(), "TSK-0001", "Hypothesis", "Pass", "fixture command", null, null, "fixture", "Investigate"); + assertThatThrownBy(() -> plans.stepStatus(root, work.id(), plan.id(), "TSK-0001", Plan.Status.COMPLETED, "fixture", "Too early", List.of(art))) + .isInstanceOf(ProtocolException.class).hasMessageContaining("EXP-0001"); + plans.finishExperiment(root, work.id(), plan.id(), "EXP-0001", Experiment.Outcome.CONFIRMED, "Observed", "Interpreted", "Proceed", List.of(art), null, "fixture", "Finish"); + plans.stepStatus(root, work.id(), plan.id(), "TSK-0001", Plan.Status.COMPLETED, "fixture", "Checked first", List.of(art)); + plans.stepStatus(root, work.id(), plan.id(), "TSK-0002", Plan.Status.COMPLETED, "fixture", "Checked second", List.of(art)); + plans.status(root, work.id(), plan.id(), Plan.Status.COMPLETED, "fixture", "Both done"); + var loaded = new PlanService().get(root, work.id(), plan.id()); + assertThat(loaded.status()).isEqualTo(Plan.Status.COMPLETED); + assertThat(loaded.steps()).allMatch(step -> step.status() == Plan.Status.COMPLETED); + assertThat(loaded.experiments().getFirst().outcome()).isEqualTo(Experiment.Outcome.CONFIRMED); + assertThat(plans.history(root, work.id(), plan.id()).size()).isGreaterThan(6); + assertThat(works.folder(root, work.id()).resolve("plans/PLN-0001.md")).doesNotExist(); + assertThat(works.folder(root, work.id()).resolve("artifacts/evidence/" + art + "/artifact.yaml")).doesNotExist(); + } + @Test void supersessionInvalidatesExecutionUntilThePlanReferencesAcceptedReplacement() { + var work = init(false); var original = accepted(work.id()); + var plan = plans.create(root, work.id(), "Delivery", "", List.of(original.id()), "fixture"); + plans.addStep(root, work.id(), plan.id(), "Implement", "", List.of(), List.of(), "fixture", "Scope"); + var replacement = decisions.revise(root, work.id(), original.id(), "fixture-owner", "New evidence"); + decisions.accept(root, work.id(), replacement.id(), "fixture-owner", "Reviewed replacement", true); + assertThat(decisions.get(root, work.id(), original.id()).approvalStatus()).isEqualTo(Decision.Status.SUPERSEDED); + assertThat(decisions.get(root, work.id(), original.id()).supersededBy()).isEqualTo(replacement.id()); + assertThatThrownBy(() -> plans.stepStatus(root, work.id(), plan.id(), "TSK-0001", Plan.Status.ACTIVE, "fixture", "Stale authority", List.of())) + .isInstanceOf(ProtocolException.class).hasMessageContaining("accepted decision"); + plans.update(root, work.id(), plan.id(), null, null, List.of(replacement.id()), "fixture", "Reconsider Plan"); + assertThat(plans.stepStatus(root, work.id(), plan.id(), "TSK-0001", Plan.Status.ACTIVE, "fixture", "Start", List.of()).steps().getFirst().status()) + .isEqualTo(Plan.Status.ACTIVE); + assertThat(decisions.history(root, work.id(), original.id())).hasSize(3); + } + @Test void failedPublicationRollsBackSystemPromotionAndPlanTogether() { + var work = init(true); var draft = draft(work.id()); + assertThatThrownBy(() -> Filespace.locked(root, () -> { + plans.create(root, work.id(), "Must roll back", "", List.of(draft.id()), "fixture"); + throw new IllegalStateException("Interrupted publication"); + })).isInstanceOf(IllegalStateException.class); + var unchanged = decisions.get(root, work.id(), draft.id()); + assertThat(unchanged.approvalStatus()).isEqualTo(Decision.Status.DRAFT); + assertThat(unchanged.approvals()).isEmpty(); + assertThat(unchanged.revision()).isEqualTo(1); + assertThat(works.load(root, work.id()).plans()).isEmpty(); + assertThat(SqliteRecords.ids(root, "plan", work.id())).isEmpty(); + var retry = plans.create(root, work.id(), "Retry", "", List.of(draft.id()), "fixture"); + var promoted = decisions.get(root, work.id(), draft.id()).approvals().getLast(); + assertThat(promoted.origin()).isEqualTo(Decision.ApprovalOrigin.SYSTEM_PLAN); + assertThat(promoted.humanApproved()).isFalse(); + assertThat(promoted.planId()).isEqualTo(retry.id()); + } + @Test void pendingDiscussionAndFailedExperimentRetainTheirPlanningBlocks() { + var work = init(false); var decision = accepted(work.id()); String art = evidence(work.id()); + var discussion = new DiscussionService(); + var question = discussion.add(root, work.id(), "Unresolved", DiscussionEntry.Kind.QUESTION, "fixture", "main", null); + assertThatThrownBy(() -> plans.create(root, work.id(), "Premature", "", List.of(decision.id()), "fixture")) + .isInstanceOf(ProtocolException.class).hasMessageContaining("pending"); + discussion.add(root, work.id(), "Resolved", DiscussionEntry.Kind.CONCLUSION, "fixture", "main", question.id()); + var plan = plans.create(root, work.id(), "Investigate", "", List.of(decision.id()), "fixture"); + plans.startExperiment(root, work.id(), plan.id(), null, "Hypothesis", "Pass", "check", null, null, "fixture", "Start"); + plans.finishExperiment(root, work.id(), plan.id(), "EXP-0001", Experiment.Outcome.REFUTED, "Failed", "Reconsider", "Change assumption", List.of(art), null, "fixture", "Result"); + assertThatThrownBy(() -> plans.startExperiment(root, work.id(), plan.id(), null, "Hypothesis", "Pass", "check", null, null, "fixture", "Repeat")) + .isInstanceOf(ProtocolException.class).hasMessageContaining("Reconsider"); + var retried = plans.startExperiment(root, work.id(), plan.id(), null, "Hypothesis", "Pass after correction", "check corrected", "EXP-0001", "Changed input based on observation", "fixture", "Retry"); + assertThat(retried.experiments()).hasSize(2); + assertThat(retried.experiments().getLast().retryOf()).isEqualTo("EXP-0001"); + } +} diff --git a/src/test/java/net/intrepid/aiengineering/SqliteInitTest.java b/src/test/java/net/intrepid/aiengineering/SqliteInitTest.java new file mode 100644 index 0000000..3ef48cb --- /dev/null +++ b/src/test/java/net/intrepid/aiengineering/SqliteInitTest.java @@ -0,0 +1,66 @@ +package net.intrepid.aiengineering; + +import net.intrepid.aiengineering.cli.EngineeringCli; +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.project.*; +import net.intrepid.aiengineering.verification.*; +import net.intrepid.aiengineering.work.WorkService; +import java.io.*; +import java.nio.file.*; +import java.util.List; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import static org.assertj.core.api.Assertions.*; + +class SqliteInitTest { + @TempDir Path root; + private String output; + private int cli(String... args) { + var out = new StringWriter(); var err = new StringWriter(); + int code = new EngineeringCli(root).execute(new PrintWriter(out), new PrintWriter(err), args); output = out + err.toString(); return code; + } + @Test void defaultInitPublishesACompleteLocalDatabaseWithoutGitAndPreservesExternalRules() throws Exception { + Files.writeString(root.resolve("AGENTS.md"), "Keep the project conventions.\n"); + Files.writeString(root.resolve(".gitignore"), "# Existing rules\nbuild/"); + assertThat(cli("init", "--name", "Local memory")).as(output).isZero(); + assertThat(SqliteDatabase.active(root)).isTrue(); assertThat(root.resolve(".git")).doesNotExist(); + assertThat(Files.readString(root.resolve(".gitignore"))).isEqualTo("# Existing rules\nbuild/\n/.ai-engineering/\n"); + assertThat(Files.readString(root.resolve("AGENTS.md"))).startsWith("Keep the project conventions.\n"); + assertThat(new VerificationService().project(root).issues()).isEmpty(); + var work = new WorkService().create(root, "One", "", "Read", "", List.of(), List.of(), List.of(), "fixture"); + assertThat(new WorkService().folder(root, work.id()).resolve("work.md")).doesNotExist(); + String ignore = Files.readString(root.resolve(".gitignore")); var previous = new WorkService().load(root, work.id()); + assertThat(cli("init", "--name", "Again")).isEqualTo(2); + assertThat(Files.readString(root.resolve(".gitignore"))).isEqualTo(ignore); + assertThat(new WorkService().load(root, work.id())).isEqualTo(previous); + try (var entries = Files.list(root)) { assertThat(entries).noneMatch(path -> path.getFileName().toString().startsWith(".aie-bootstrap-")); } + } + @Test void explicitVersioningChoiceLeavesExistingIgnoreRulesToTheDeveloper() throws Exception { + Files.writeString(root.resolve(".gitignore"), "# Own policy\n"); + assertThat(cli("init", "--name", "Versioned", "--version-state")).as(output).isZero(); + assertThat(Files.readString(root.resolve(".gitignore"))).isEqualTo("# Own policy\n"); + assertThat(SqliteDatabase.active(root)).isTrue(); + } + @Test void invalidBootstrapIsRejectedBeforeAnyDatabaseOrIgnoreMutation() throws Exception { + Files.writeString(root.resolve("AGENTS.md"), "Keep rules\n\nAmbiguous block\n"); + Files.writeString(root.resolve(".gitignore"), "Existing\n"); + assertThat(cli("init", "--name", "Invalid")).isEqualTo(4); + assertThat(root.resolve(".ai-engineering")).doesNotExist(); + assertThat(Files.readString(root.resolve(".gitignore"))).isEqualTo("Existing\n"); + } + @Test void incompatibleBootstrapCannotCreateAWorkOrAlterTheDatabase() throws Exception { + new ProjectService().initialize(root, "Compatibility"); Path db = SqliteDatabase.path(root); + String before = Revisions.hash(Files.readAllBytes(db)); Path manifest = root.resolve(".ai-engineering/protocol.json"); + var metadata = Documents.readJson(manifest, tools.jackson.databind.node.ObjectNode.class); metadata.put("protocolVersion", 3); + Files.writeString(manifest, Documents.json(metadata)); + assertThat(cli("work", "create", "Forbidden")).isEqualTo(4); assertThat(output).contains("contract 4"); + assertThat(Revisions.hash(Files.readAllBytes(db))).isEqualTo(before); + assertThat(new CompatibilityService().inspect(root).readable()).isFalse(); + } + @Test void legacyRemainsExplicitAndOnboardingDoesNotConvertIt() { + assertThat(cli("init", "--storage", "legacy", "--name", "Legacy")).as(output).isZero(); + assertThat(SqliteDatabase.active(root)).isFalse(); assertThat(SqliteDatabase.path(root)).doesNotExist(); + assertThat(cli("onboard")).as(output).isZero(); + assertThat(SqliteDatabase.active(root)).isFalse(); assertThat(SqliteDatabase.path(root)).doesNotExist(); + } +} diff --git a/src/test/java/net/intrepid/aiengineering/SqliteInvestigationTest.java b/src/test/java/net/intrepid/aiengineering/SqliteInvestigationTest.java new file mode 100644 index 0000000..ae38ec9 --- /dev/null +++ b/src/test/java/net/intrepid/aiengineering/SqliteInvestigationTest.java @@ -0,0 +1,117 @@ +package net.intrepid.aiengineering; + +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.project.*; +import net.intrepid.aiengineering.work.*; +import net.intrepid.aiengineering.discussion.*; +import java.nio.file.*; +import java.util.*; +import java.util.concurrent.*; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import static org.assertj.core.api.Assertions.*; + +class SqliteInvestigationTest { + @TempDir Path root; + private final WorkService works = new WorkService(); + private Work create(String title) { return works.create(root, title, "", "Goal", "", List.of("Constraint"), List.of("Criterion"), List.of(), "owner"); } + private Work init() { new ProjectService().initializeSqlite(root, "SQLite investigation"); return create("One"); } + + @Test void workAndDiscussionRetainAuthorityAndUtf8WithoutCanonicalMarkdownFiles() throws Exception { + var work = init(); + assertThat(work.guidance().mode()).isEqualTo(WorkGuidance.Mode.UNSPECIFIED); + works.guidance(root, work.id(), WorkGuidance.Mode.EXPLORATORY, null, "owner", "Chosen", true); + works.requestDecision(root, work.id(), "owner", "Ready for DEC-0001", true); + var discussion = new DiscussionService(); + var question = discussion.add(root, work.id(), "Como preservar memória?\n\n**UTF-8** — útil.", DiscussionEntry.Kind.QUESTION, "owner", "main", null); + discussion.add(root, work.id(), "Resposta registrada", DiscussionEntry.Kind.CONCLUSION, "agent", "main", question.id()); + assertThat(new DiscussionService().list(root, work.id())).hasSize(2); + assertThat(new DiscussionService().hasPending(root, work.id())).isFalse(); + var loaded = new WorkService().load(root, work.id()); + assertThat(loaded.guidance().mode()).isEqualTo(WorkGuidance.Mode.EXPLORATORY); + assertThat(loaded.guidance().history()).hasSize(1); + assertThat(loaded.guidance().decisionRequests()).extracting(WorkGuidance.Request::decisionId).containsExactly("DEC-0001"); + assertThat(loaded.constraints()).containsExactly("Constraint"); + assertThat(works.folder(root, work.id()).resolve("work.md")).doesNotExist(); + assertThat(works.folder(root, work.id()).resolve("discussions/DSC-0001.md")).doesNotExist(); + assertThat(discussion.list(root, work.id()).getFirst().text()).isEqualTo(question.text()); + } + @Test void topicAndSurveyRevisionsKeepHashChainsAndAnswerHistory() { + var work = init(); var discussion = new DiscussionService(); + var source = discussion.add(root, work.id(), "Investigação", DiscussionEntry.Kind.NOTE, "owner", "main", null); + var topics = new TopicService(); + var topic = topics.create(root, work.id(), "Topic", "Initial", List.of(source.id()), "owner"); + topics.update(root, work.id(), topic.id(), "Refined", null, "owner", "Refine the scope"); + assertThat(new TopicService().get(root, work.id(), topic.id()).revision()).isEqualTo(2); + var surveys = new SurveyService(); + var survey = surveys.create(root, work.id(), "Question", "Purpose", "owner"); + surveys.question(root, work.id(), survey.id(), topic.id(), "Choose", List.of("First", "Second"), false, "1", List.of(source.id()), "owner"); + surveys.answer(root, work.id(), survey.id(), "QST-0001", List.of("2"), "", "owner"); + surveys.answer(root, work.id(), survey.id(), "QST-0001", List.of(), "Changed — free text", "owner"); + var loaded = new SurveyService().get(root, work.id(), survey.id()); + assertThat(loaded.answers()).hasSize(2); + assertThat(loaded.latest("QST-0001").supersedes()).isEqualTo("ANS-0001"); + assertThat(loaded.latest("QST-0001").text()).isEqualTo("Changed — free text"); + assertThat(surveys.history(root, work.id(), survey.id())).hasSize(4); + assertThat(works.folder(root, work.id()).resolve("surveys/.history")).doesNotExist(); + } + @Test void rejectedChildPublicationDoesNotLeaveItsRowOrWorkReference() { + var work = init(); + assertThatThrownBy(() -> Filespace.locked(root, () -> { + new DiscussionService().add(root, work.id(), "Must roll back", DiscussionEntry.Kind.NOTE, "owner", "main", null); + throw new IllegalStateException("reject outer operation"); + })).isInstanceOf(IllegalStateException.class); + assertThat(works.load(root, work.id()).discussions()).isEmpty(); + assertThat(SqliteRecords.ids(root, "discussion", work.id())).isEmpty(); + assertThat(new DiscussionService().add(root, work.id(), "Retry", DiscussionEntry.Kind.NOTE, "owner", "main", null).id()).isEqualTo("DSC-0001"); + } + @Test void unknownOwnedReferenceCannotPublishAndAnotherWorkIsNotParsedOnSelectedLoad() { + var work = init(); var other = create("Two"); + assertThatThrownBy(() -> Filespace.locked(root, () -> { + works.addReference(root, work.id(), "discussions", "DSC-9999"); return null; + })).isInstanceOf(ProtocolException.class).hasMessageContaining("Missing owned record"); + assertThat(works.load(root, work.id()).discussions()).isEmpty(); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.prepareStatement("UPDATE data_work SET f_title=NULL WHERE local_id=?")) { + statement.setString(1, other.id()); statement.executeUpdate(); + } + return null; + }); + assertThat(works.load(root, work.id()).id()).isEqualTo(work.id()); + var verification = new net.intrepid.aiengineering.verification.VerificationService(); + assertThat(verification.context(root, work.id()).work().id()).isEqualTo(work.id()); + assertThat(verification.nextActions(root, work.id())).isNotEmpty(); + assertThatThrownBy(() -> works.load(root, other.id())).isInstanceOf(ProtocolException.class); + } + @Test void concurrentLocalCreationAllocatesDifferentIdentitiesAndRenameKeepsLocation() throws Exception { + init(); + try (var executor = Executors.newFixedThreadPool(2)) { + var first = executor.submit(() -> create("Concurrent one")); + var second = executor.submit(() -> create("Concurrent two")); + Work a = first.get(10, TimeUnit.SECONDS), b = second.get(10, TimeUnit.SECONDS); + assertThat(a.id()).isNotEqualTo(b.id()); + assertThat(works.list(root)).hasSize(3); + Path folder = works.folder(root, a.id()); + works.update(root, a.id(), new Work.Update("New title", null, null, null, null, null)); + assertThat(works.folder(root, a.id())).isEqualTo(folder); + assertThat(works.load(root, a.id()).title()).isEqualTo("New title"); + } + } + @Test void freshJvmReconstructsSqliteDiscussionAndSurvey() throws Exception { + var work = init(); + new DiscussionService().add(root, work.id(), "Persisted — UTF-8", DiscussionEntry.Kind.NOTE, "owner", "main", null); + var surveys = new SurveyService(); var survey = surveys.create(root, work.id(), "Persisted survey", "", "owner"); + surveys.question(root, work.id(), survey.id(), "main", "Choose", List.of("A", "B"), false, null, List.of(), "owner"); + Path out = root.resolve("context.json"), err = root.resolve("errors.txt"); + var process = new ProcessBuilder(Path.of(System.getProperty("java.home"), "bin/java").toString(), + "--enable-native-access=ALL-UNNAMED", "-jar", System.getProperty("cli.jar"), "work", "context", work.id(), "--format", "json") + .directory(root.toFile()).redirectOutput(out.toFile()).redirectError(err.toFile()).start(); + boolean done = process.waitFor(30, TimeUnit.SECONDS); + if (!done) process.destroyForcibly(); + assertThat(done).isTrue(); assertThat(process.exitValue()).as(Files.readString(err)).isZero(); + var context = Documents.readJson(out, net.intrepid.aiengineering.verification.VerificationService.Context.class); + assertThat(context.discussionHistory()).extracting(DiscussionEntry::text).containsExactly("Persisted — UTF-8"); + assertThat(context.surveys()).hasSize(1); + assertThat(context.outstandingQuestions()).anyMatch(s -> s.contains("QST-0001")); + } +} diff --git a/src/test/java/net/intrepid/aiengineering/SqliteQualityGatesTest.java b/src/test/java/net/intrepid/aiengineering/SqliteQualityGatesTest.java new file mode 100644 index 0000000..8005626 --- /dev/null +++ b/src/test/java/net/intrepid/aiengineering/SqliteQualityGatesTest.java @@ -0,0 +1,113 @@ +package net.intrepid.aiengineering; + +import net.intrepid.aiengineering.artifact.*; +import net.intrepid.aiengineering.cli.EngineeringCli; +import net.intrepid.aiengineering.decision.DecisionService; +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.planning.*; +import net.intrepid.aiengineering.project.ProjectService; +import net.intrepid.aiengineering.verification.*; +import net.intrepid.aiengineering.work.*; +import java.io.*; +import java.nio.file.*; +import java.util.List; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import static org.assertj.core.api.Assertions.*; + +class SqliteQualityGatesTest { + @TempDir Path root; + private final WorkService works = new WorkService(); + private final QualityGates gates = new QualityGates(); + private String init() throws IOException { + new ProjectService().initializeSqlite(root, "Quality"); + Files.writeString(root.resolve("source.txt"), "Initial source"); + var w = works.create(root, "Deliver", "", "Quality", "", List.of(), List.of("Checked"), List.of(), "fixture"); + works.guidance(root, w.id(), WorkGuidance.Mode.DIRECT, WorkGuidance.ApprovalPolicy.WAIVED, "fixture-owner", "Synthetic explicit policy", true); + return w.id(); + } + private QualityGates.Definition gate(String scope, String id, boolean evidence) { + return gates.configure(root, scope, id, "Check " + id, "external-check " + id, List.of("source.txt"), evidence, "fixture-owner"); + } + private QualityGates.Result record(String work, QualityGates.Definition definition, QualityGates.Outcome outcome, List evidence) { + return gates.record(root, work, definition.key(), gates.fingerprint(root, work, definition), definition.procedure(), outcome, "Observed synthetic fixture result", evidence, "fixture-observer", true); + } + private String evidence(String work) { return new ArtifactService().attachBytes(root, work, "Check detail".getBytes(java.nio.charset.StandardCharsets.UTF_8), "Temporary evidence", "fixture", "fixture").id(); } + private void complete(String work, String evidence) { + new VerificationService().complete(root, work, "fixture-owner", "Reviewed", true, List.of("1=" + evidence), List.of(), "Inspection only"); + } + @Test void projectAndWorkChecksAreCumulativeAndFailedChecksBlockHumanCompletion() throws IOException { + String work = init(); var project = gate("project", "tests", false); var extra = gate(work, "tests", false); + String art = evidence(work); + assertThat(gates.pending(root, work)).hasSize(2); + assertThatThrownBy(() -> complete(work, art)).hasMessageContaining("Gate"); + record(work, extra, QualityGates.Outcome.PASS, List.of()); + record(work, project, QualityGates.Outcome.FAIL, List.of()); + assertThat(gates.pending(root, work)).singleElement().asString().contains("project/tests", "failed"); + assertThatThrownBy(() -> complete(work, art)).hasMessageContaining("Gate"); + record(work, project, QualityGates.Outcome.PASS, List.of()); + complete(work, art); + assertThat(works.load(root, work).status()).isEqualTo(Work.Status.COMPLETED); + assertThat(new VerificationService().work(root, work).issues()).isEmpty(); + assertThat(gates.history(root, work)).hasSize(3); + } + @Test void contentChangesMissingInputsAndReconfigurationInvalidateCurrentResults() throws IOException { + String work = init(); var definition = gate("project", "tests", false); + String previous = gates.fingerprint(root, work, definition); + record(work, definition, QualityGates.Outcome.PASS, List.of()); + works.status(root, work, Work.Status.ACTIVE, "fixture", "Bookkeeping"); + assertThat(gates.pending(root, work)).isEmpty(); + Files.writeString(root.resolve("source.txt"), "Changed source"); + assertThat(gates.pending(root, work)).hasSize(1); + assertThatThrownBy(() -> gates.record(root, work, definition.key(), previous, "external-check tests", QualityGates.Outcome.PASS, "Old result", List.of(), "fixture", true)) + .hasMessageContaining("state changed"); + record(work, definition, QualityGates.Outcome.PASS, List.of()); + var updated = gate("project", "tests", false); + assertThat(updated.revision()).isEqualTo(2); + assertThat(gates.pending(root, work)).hasSize(1); + record(work, updated, QualityGates.Outcome.PASS, List.of()); + Files.delete(root.resolve("source.txt")); + assertThat(gates.pending(root, work)).singleElement().asString().contains("Missing gate input"); + } + @Test void evidenceMustExistAndPassIntegrityBeforeAnActualEvaluationIsRecorded() throws IOException { + String work = init(); var definition = gate("project", "tests", true); + assertThatThrownBy(() -> record(work, definition, QualityGates.Outcome.PASS, List.of())).hasMessageContaining("requires temporary evidence"); + String art = evidence(work); + Files.writeString(works.folder(root, work).resolve("artifacts/evidence/" + art + "/payload"), "Tampered"); + assertThatThrownBy(() -> record(work, definition, QualityGates.Outcome.PASS, List.of(art))).hasMessageContaining("mismatch"); + assertThat(gates.history(root, work)).isEmpty(); + assertThatThrownBy(() -> gates.record(root, work, definition.key(), gates.fingerprint(root, work, definition), "check", QualityGates.Outcome.PASS, "Unobserved", List.of(art), "fixture", false)) + .hasMessageContaining("--observed"); + } + @Test void automaticPlanCompletionWaitsForGatesAndHistoryKeepsDeliveredResults() throws IOException { + String work = init(); var definition = gate("project", "tests", false); String art = evidence(work); + var decisions = new DecisionService(); var plans = new PlanService(); + var decision = decisions.draft(root, work, "Approach", "Context", "Change", "Reason", List.of(), "fixture"); + var plan = plans.create(root, work, "Deliver", "", List.of(decision.id()), "fixture"); + plans.addStep(root, work, plan.id(), "Implement", "", List.of(), List.of(), "fixture", "Scope"); + new PlanCoordinator().change(root, work, "fixture", "finish", () -> plans.stepStatus(root, work, plan.id(), "TSK-0001", Plan.Status.COMPLETED, "fixture", "Checked", List.of(art))); + assertThat(works.load(root, work).status()).isNotEqualTo(Work.Status.COMPLETED); + record(work, definition, QualityGates.Outcome.PASS, List.of()); + new PlanCoordinator().reconcile(root, work, "fixture", "gates-met"); + assertThat(works.load(root, work).status()).isEqualTo(Work.Status.COMPLETED); + // Later policy/source changes do not pretend the historical delivery ran these new checks. + gate("project", "extra", false); Files.writeString(root.resolve("source.txt"), "Next work"); + assertThat(new VerificationService().work(root, work).issues()).isEmpty(); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { statement.executeUpdate("UPDATE data_gate SET f_summary='Changed historic observation'"); } + return null; + }); + assertThat(new VerificationService().work(root, work).issues()).anyMatch(issue -> issue.contains("delivered gate")); + } + @Test void cliRequiresObservationAndRecordsAStateBoundResultWithoutExecutingTheProcedure() throws IOException { + String work = init(); var definition = gate("project", "manual", false); + var output = new StringWriter(); var errors = new StringWriter(); + var cli = new EngineeringCli(root); String hash = gates.fingerprint(root, work, definition); + String[] args = {"gate", "record", work, definition.key(), "--expect", hash, "--invocation", "external-check manual", + "--outcome", "PASS", "--summary", "Observed fixture", "--by", "fixture", "--observed", "--format", "json"}; + assertThat(cli.execute(new PrintWriter(output), new PrintWriter(errors), args)).as(errors.toString()).isZero(); + assertThat(output.toString()).contains("PASS", "evaluatedHash"); + assertThat(gates.pending(root, work)).isEmpty(); + assertThat(root.resolve("external-check")).doesNotExist(); + } +} diff --git a/src/test/java/net/intrepid/aiengineering/SqliteQueriesTest.java b/src/test/java/net/intrepid/aiengineering/SqliteQueriesTest.java new file mode 100644 index 0000000..df8ece4 --- /dev/null +++ b/src/test/java/net/intrepid/aiengineering/SqliteQueriesTest.java @@ -0,0 +1,76 @@ +package net.intrepid.aiengineering; + +import net.intrepid.aiengineering.artifact.*; +import net.intrepid.aiengineering.discussion.*; +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.project.ProjectService; +import net.intrepid.aiengineering.verification.*; +import net.intrepid.aiengineering.work.*; +import java.nio.file.*; +import java.util.List; +import java.util.concurrent.*; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import static org.assertj.core.api.Assertions.*; + +class SqliteQueriesTest { + @TempDir Path root; + private final WorkService works = new WorkService(); + private final VerificationService verification = new VerificationService(); + private String init() { + new ProjectService().initializeSqlite(root, "Queries"); + var w = works.create(root, "Before", "", "Read", "", List.of(), List.of("Checked"), List.of(), "fixture"); + works.guidance(root, w.id(), WorkGuidance.Mode.DIRECT, WorkGuidance.ApprovalPolicy.WAIVED, "fixture-owner", "Explicit fixture policy", true); + return w.id(); + } + @Test void projectValidationAndCompatibilityReadTypedRowsAndHistoricalFormats() { + String work = init(); var topics = new TopicService(); + var topic = topics.create(root, work, "Topic", "Useful text", List.of(), "fixture"); + topics.update(root, work, topic.id(), "Refined", null, "fixture", "Refine"); + var compatibility = new CompatibilityService(); var before = compatibility.inspect(root); + assertThat(before.state()).isEqualTo(CompatibilityService.State.CURRENT); + assertThat(before.findings()).anyMatch(f -> f.path().contains("#" + work + "/topic/TOP-0001/r1")); + assertThat(verification.project(root).issues()).isEmpty(); + SqliteDatabase.write(root, connection -> { + try (var statement = connection.createStatement()) { statement.executeUpdate("UPDATE data_topic SET f_schemaVersion=99 WHERE storage_revision=1"); } + return null; + }); + assertThat(compatibility.inspect(root).state()).isEqualTo(CompatibilityService.State.UNSUPPORTED); + assertThat(verification.work(root, work).valid()).isFalse(); + } + @Test void relatedReadsUseOneSnapshotWhileAnotherLocalWriterCommits() throws Exception { + String work = init(); + try (var executor = Executors.newSingleThreadExecutor()) { + SqliteDatabase.read(root, connection -> { + assertThat(works.load(root, work).title()).isEqualTo("Before"); + var writer = executor.submit(() -> Filespace.locked(root, () -> { + works.update(root, work, new Work.Update("After", null, null, null, null, null)); + new DiscussionService().add(root, work, "Same transaction", DiscussionEntry.Kind.NOTE, "fixture", "main", null); + return null; + })); + try { writer.get(10, TimeUnit.SECONDS); } catch (Exception failure) { throw new IllegalStateException(failure); } + var snapshot = verification.context(root, work); + assertThat(snapshot.work().title()).isEqualTo("Before"); + assertThat(snapshot.discussionHistory()).isEmpty(); + return null; + }); + } + var current = verification.context(root, work); + assertThat(current.work().title()).isEqualTo("After"); + assertThat(current.discussionHistory()).hasSize(1); + } + @Test void readsExposeInterruptedCleanupWithoutPerformingIt() { + String work = init(); var artifacts = new ArtifactService(); + var artifact = artifacts.attachBytes(root, work, "Evidence".getBytes(java.nio.charset.StandardCharsets.UTF_8), "Check", "fixture", "fixture"); + assertThatThrownBy(() -> SqliteDatabase.write(root, connection -> { + SqliteDatabase.afterCommit(root, () -> { throw new IllegalStateException("Interrupted cleanup"); }); + verification.complete(root, work, "fixture-owner", "Reviewed", true, List.of("1=" + artifact.id()), List.of(), "Inspection only"); + return null; + })).hasMessageContaining("committed"); + assertThat(verification.context(root, work).artifactStates()).containsEntry(artifact.id(), "DISCARD_PENDING"); + assertThat(verification.nextActions(root, work)).anyMatch(action -> action.code().equals("RECOVER_ARTIFACTS")); + assertThat(works.folder(root, work).resolve(artifact.path())).exists(); + assertThat(ArtifactLifecycle.pending(root, work)).isEqualTo(1); + assertThat(verification.project(root).issues()).isEmpty(); + } +} diff --git a/src/test/java/net/intrepid/aiengineering/WorkGuidanceTest.java b/src/test/java/net/intrepid/aiengineering/WorkGuidanceTest.java index 60877a1..abbe1b6 100644 --- a/src/test/java/net/intrepid/aiengineering/WorkGuidanceTest.java +++ b/src/test/java/net/intrepid/aiengineering/WorkGuidanceTest.java @@ -21,7 +21,7 @@ class WorkGuidanceTest { } private void ok(String... args) { assertThat(cli(args)).as(output).isZero(); } private Work work() { return new WorkService().load(root, "WRK-0001"); } - private void init() { ok("init", "--name", "Guidance"); ok("work", "create", "Delivery"); } + private void init() { ok("init", "--storage", "legacy", "--name", "Guidance"); ok("work", "create", "Delivery"); } private void mode(String mode) { ok("work", "guidance", "WRK-0001", "--mode", mode, "--by", "fixture-human", "--reason", "Explicit fixture choice", "--human-approved"); } private void policy(String value) { ok("work", "guidance", "WRK-0001", "--approval", value, "--by", "fixture-human", "--reason", "Explicit fixture policy", "--human-approved"); } private void request() { ok("work", "request-decision", "WRK-0001", "--by", "fixture-human", "--reason", "Discussion concluded; prepare next DEC", "--human-approved"); } diff --git a/src/test/java/net/intrepid/aiengineering/WorkHexadecimalTest.java b/src/test/java/net/intrepid/aiengineering/WorkHexadecimalTest.java index cf3b374..1bf1fb0 100644 --- a/src/test/java/net/intrepid/aiengineering/WorkHexadecimalTest.java +++ b/src/test/java/net/intrepid/aiengineering/WorkHexadecimalTest.java @@ -16,7 +16,7 @@ class WorkHexadecimalTest { @TempDir Path root; private final WorkService works = new WorkService(); private String output; - private void init() { new ProjectService().initialize(root, "Test"); } + private void init() { new ProjectService().initializeLegacy(root, "Test"); } private Work create(String title) { return works.create(root, title, "", "Goal", "", List.of(), List.of(), List.of(), "human"); } private Path counter() { return root.resolve(".ai-engineering/works/.sequence.yaml"); } private void sequence(String yaml) throws Exception { Files.writeString(counter(), yaml); } diff --git a/src/test/java/net/intrepid/aiengineering/WorkUpdateTest.java b/src/test/java/net/intrepid/aiengineering/WorkUpdateTest.java index 0cd95d1..9dfb27d 100644 --- a/src/test/java/net/intrepid/aiengineering/WorkUpdateTest.java +++ b/src/test/java/net/intrepid/aiengineering/WorkUpdateTest.java @@ -22,7 +22,7 @@ class WorkUpdateTest { } private void ok(String... args) { int code = cli(args); assertThat(code).as(output).isZero(); } private void initialize() { - ok("init", "--name", "Test"); + ok("init", "--storage", "legacy", "--name", "Test"); ok("work", "create", "--mode", "DIRECT", "--approval", "WAIVED", "--human-approved", "--choice-reason", "Explicit synthetic fixture policy", "One", "--description", "Description", "--goal", "Original goal", "--motivation", "Motivation", "--constraint", "Original constraint", "--acceptance", "Original criterion", "--author", "creator"); } diff --git a/src/test/java/net/intrepid/aiengineering/agent/CliTransportTest.java b/src/test/java/net/intrepid/aiengineering/agent/CliTransportTest.java index b4515cc..01e9771 100644 --- a/src/test/java/net/intrepid/aiengineering/agent/CliTransportTest.java +++ b/src/test/java/net/intrepid/aiengineering/agent/CliTransportTest.java @@ -16,7 +16,7 @@ class CliTransportTest { @TempDir Path root; private Path trace; private void init() throws Exception { - new ProjectService().initialize(root, "Provider fixture"); + new ProjectService().initializeLegacy(root, "Provider fixture"); new WorkService().create(root, "One", "", "Portable state", "", List.of(), List.of("Continuity"), List.of(), "fixture-human"); new DiscussionService().add(root, "WRK-0001", "Original context", DiscussionEntry.Kind.NOTE, "fixture-human", "main", null); trace = root.resolve("invocations.txt"); diff --git a/src/test/java/net/intrepid/aiengineering/legacyimport/DiscussionImportRecoveryTest.java b/src/test/java/net/intrepid/aiengineering/legacyimport/DiscussionImportRecoveryTest.java index 0a8a9a5..25ebbff 100644 --- a/src/test/java/net/intrepid/aiengineering/legacyimport/DiscussionImportRecoveryTest.java +++ b/src/test/java/net/intrepid/aiengineering/legacyimport/DiscussionImportRecoveryTest.java @@ -13,8 +13,28 @@ import static org.assertj.core.api.Assertions.*; class DiscussionImportRecoveryTest { @TempDir Path temp; + @Test void sqliteBatchRollbackRemovesOwnedPayloadsAndRetryPreservesImportProvenance() throws Exception { + Path root = Files.createDirectory(temp.resolve("sqlite")).toRealPath(); new ProjectService().initialize(root, "SQLite target"); + var sources = new ArrayList(); + for (String id : List.of("alpha", "beta")) { + Path fixture = Path.of(Objects.requireNonNull(getClass().getResource("/discussion-import/" + id)).toURI()); + sources.add(new Source(id, fixture.toRealPath().toString(), null)); + } + var faulty = new DiscussionImportService(work -> { throw new ProtocolException(1, "Interrupted batch"); }); + var preview = faulty.preview(root, sources); + assertThatThrownBy(() -> faulty.apply(root, sources, preview.fingerprint(), "fixture-owner")).hasMessageContaining("No Works from this transaction committed"); + assertThat(new WorkService().list(root)).isEmpty(); + assertThat(Filespace.children(root.resolve(".ai-engineering/works"))).isEmpty(); + var importer = new DiscussionImportService(); var retry = importer.preview(root, sources); + var applied = importer.apply(root, sources, retry.fingerprint(), "fixture-owner"); + assertThat(applied.publishedWorks()).hasSize(2); + for (var work : new WorkService().list(root)) assertThat(importer.receipts(root, work.id())).hasSize(1); + assertThat(new VerificationService().project(root).issues()).isEmpty(); + var repeated = importer.preview(root, sources); + assertThat(repeated.discussions()).filteredOn(entry -> entry.action() == Action.CREATE).isEmpty(); + } @Test void interruptionBetweenPublishedWorksResumesWithoutDuplicationOrRewriting() throws Exception { - Path root = Files.createDirectory(temp.resolve("target")).toRealPath(); new ProjectService().initialize(root, "Target"); + Path root = Files.createDirectory(temp.resolve("target")).toRealPath(); new ProjectService().initializeLegacy(root, "Target"); var sources = new ArrayList(); for (String id : List.of("alpha", "beta")) { Path from = Path.of(Objects.requireNonNull(getClass().getResource("/discussion-import/" + id)).toURI()); diff --git a/src/test/java/net/intrepid/aiengineering/verification/StorageMigrationTest.java b/src/test/java/net/intrepid/aiengineering/verification/StorageMigrationTest.java new file mode 100644 index 0000000..3e22fb0 --- /dev/null +++ b/src/test/java/net/intrepid/aiengineering/verification/StorageMigrationTest.java @@ -0,0 +1,165 @@ +package net.intrepid.aiengineering.verification; + +import net.intrepid.aiengineering.artifact.*; +import net.intrepid.aiengineering.agent.AgentService; +import net.intrepid.aiengineering.cli.EngineeringCli; +import net.intrepid.aiengineering.decision.*; +import net.intrepid.aiengineering.discussion.*; +import net.intrepid.aiengineering.filesystem.*; +import net.intrepid.aiengineering.planning.*; +import net.intrepid.aiengineering.project.*; +import net.intrepid.aiengineering.work.*; +import java.io.*; +import java.nio.file.*; +import java.util.*; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; +import static org.assertj.core.api.Assertions.*; + +class StorageMigrationTest { + @TempDir Path root; + private final WorkService works = new WorkService(); + private final StorageMigration migration = new StorageMigration(); + private String init() { + new ProjectService().initializeLegacy(root, "Legacy fixture"); + var w = works.create(root, "One", "", "Preserve", "", List.of(), List.of("Checked"), List.of(), "fixture"); + works.guidance(root, w.id(), WorkGuidance.Mode.DIRECT, WorkGuidance.ApprovalPolicy.WAIVED, "fixture-owner", "Explicit synthetic policy", true); + return w.id(); + } + private Map files(Path directory) throws IOException { + var result = new TreeMap(); + try (var paths = Files.walk(directory)) { + for (var path : paths.filter(Files::isRegularFile).toList()) result.put(directory.relativize(path).toString(), Revisions.hash(Files.readAllBytes(path))); + } + return result; + } + private void baseline() throws Exception { + new ProjectService().initializeLegacy(root, "Baseline"); + works.create(root, "Delivered baseline", "", "Preserve", "", List.of(), List.of(), List.of(), "fixture"); + Path corpus = Path.of(getClass().getResource("/compatibility/baseline-v1/.ai-engineering").toURI()); + try (var paths = Files.walk(corpus)) { + for (Path file : paths.filter(Files::isRegularFile).toList()) { + Path target = root.resolve(".ai-engineering").resolve(corpus.relativize(file)); + Files.createDirectories(target.getParent()); Files.copy(file, target, StandardCopyOption.REPLACE_EXISTING); + } + } + } + @Test void previewIsReadOnlyAndChangedInputCannotApplyAnOldFingerprint() throws Exception { + String work = init(); var before = files(root); var preview = migration.preview(root); + assertThat(preview.valid()).as(preview.issues().toString()).isTrue(); + assertThat(files(root)).isEqualTo(before); + new DiscussionService().add(root, work, "New observation", DiscussionEntry.Kind.NOTE, "fixture", "main", null); + assertThatThrownBy(() -> migration.apply(root, preview.fingerprint())).hasMessageContaining("preview changed"); + assertThat(SqliteDatabase.path(root)).doesNotExist(); + } + @Test void frozenCompletionPreservesHashesApprovalsOriginalBytesAndLegacyPayloads() throws Exception { + baseline(); var verification = new VerificationService(); var before = verification.context(root, "WRK-0001"); + var historical = files(root.resolve(".ai-engineering/works")); + var preview = migration.preview(root); assertThat(preview.valid()).as(preview.issues().toString()).isTrue(); + var applied = migration.apply(root, preview.fingerprint()); assertThat(applied.phase()).isEqualTo("APPLIED"); + assertThat(root.resolve(applied.backup()).getParent().resolve("stage")).doesNotExist(); + var after = verification.context(root, "WRK-0001"); + assertThat(after.work()).isEqualTo(before.work()); assertThat(after.decisions()).isEqualTo(before.decisions()); + assertThat(after.artifacts()).isEqualTo(before.artifacts()); + assertThat(verification.scopeHash(root, after.work())).isEqualTo("72d5803add0b8714d7dc4bf7e63ad55cc3259df910aa8b03790657eac4c2bd02"); + assertThat(after.decisions().getFirst().approvals().getFirst().humanApproved()).isTrue(); + assertThat(new DecisionService().history(root, "WRK-0001", "DEC-0001")).hasSize(2); + assertThat(ArtifactLifecycle.state(root, "WRK-0001", "ART-0001")).isEqualTo("RETAINED_LEGACY"); + assertThat(files(root.resolve(applied.backup()).resolve(".ai-engineering/works"))).isEqualTo(historical); + // Existing tracked source documents stay in place and remain byte-identical. + for (var entry : historical.entrySet()) assertThat(Revisions.hash(Files.readAllBytes(root.resolve(".ai-engineering/works").resolve(entry.getKey())))).isEqualTo(entry.getValue()); + assertThat(root.resolve(".ai-engineering/works/SQLITE-STORAGE")).exists(); + assertThat(verification.project(root).issues()).isEmpty(); + assertThat(migration.apply(root, preview.fingerprint()).phase()).isEqualTo("APPLIED"); + assertThat(works.list(root)).hasSize(1); + } + @ParameterizedTest @ValueSource(strings = {"BACKUP_READY", "STAGE_VALIDATED", "ENTRY_GUARDED", "DATABASE_PUBLISHED", "ACTIVATED"}) + void interruptedPublicationResumesWithoutDuplicatingWork(String phase) { + String work = init(); var preview = migration.preview(root); + var interrupted = new StorageMigration(at -> { if (at.equals(phase)) throw new IllegalStateException("Synthetic interruption at " + phase); }); + assertThatThrownBy(() -> interrupted.apply(root, preview.fingerprint())).hasMessageContaining("Migration interrupted"); + assertThatThrownBy(() -> StorageMigration.requireStable(root)).hasMessageContaining("migration"); + var applied = migration.recover(root, preview.fingerprint(), false); + assertThat(applied.phase()).isEqualTo("APPLIED"); + assertThat(works.list(root)).hasSize(1); assertThat(works.load(root, work).guidance().waived()).isTrue(); + assertThat(new VerificationService().project(root).issues()).isEmpty(); + assertThat(migration.recover(root, preview.fingerprint(), false).phase()).isEqualTo("APPLIED"); + } + @Test void rollbackRestoresLegacyAndRefusesToLoseNewEngineeringMemory() throws Exception { + String work = init(); var source = files(root); var preview = migration.preview(root); + migration.apply(root, preview.fingerprint()); + assertThat(migration.recover(root, preview.fingerprint(), true).phase()).isEqualTo("ROLLED_BACK"); + assertThat(SqliteDatabase.active(root)).isFalse(); assertThat(SqliteDatabase.path(root)).doesNotExist(); + for (var entry : source.entrySet()) assertThat(Revisions.hash(Files.readAllBytes(root.resolve(entry.getKey())))).isEqualTo(entry.getValue()); + assertThat(root.resolve(".ai-engineering/works/SQLITE-STORAGE")).doesNotExist(); + assertThat(new VerificationService().project(root).issues()).isEmpty(); + var retry = migration.preview(root); migration.apply(root, retry.fingerprint()); + new DiscussionService().add(root, work, "New engineering memory", DiscussionEntry.Kind.NOTE, "fixture", "main", null); + assertThatThrownBy(() -> migration.recover(root, retry.fingerprint(), true)).hasMessageContaining("would lose engineering memory"); + assertThat(new DiscussionService().list(root, work)).extracting(DiscussionEntry::text).contains("New engineering memory"); + } + @Test void activePlanSurveyAndRevisionChainsContinueAfterMigration() { + String work = init(); var surveys = new SurveyService(); var topics = new TopicService(); + var topic = topics.create(root, work, "Investigate", "Context", List.of(), "fixture"); + topics.update(root, work, topic.id(), "Refined", null, "fixture", "Refine"); + var survey = surveys.create(root, work, "Choose", "Context", "fixture"); + surveys.question(root, work, survey.id(), topic.id(), "Which?", List.of("A", "B"), false, null, List.of(), "fixture"); + surveys.answer(root, work, survey.id(), "QST-0001", List.of("1"), "", "fixture-owner"); + var decision = new DecisionService().draft(root, work, "Approach", "Context", "Change", "Reason", List.of(), "fixture"); + var plans = new PlanService(); var plan = plans.create(root, work, "Deliver", "", List.of(decision.id()), "fixture"); + plans.addStep(root, work, plan.id(), "Do", "", List.of(), List.of(), "fixture", "Scope"); + var expected = new VerificationService().context(root, work); + var preview = migration.preview(root); migration.apply(root, preview.fingerprint()); + var actual = new VerificationService().context(root, work); + assertThat(actual.work()).isEqualTo(expected.work()); assertThat(actual.plans()).isEqualTo(expected.plans()); + assertThat(actual.surveys()).isEqualTo(expected.surveys()); + surveys.answer(root, work, survey.id(), "QST-0001", List.of("2"), "New evidence", "fixture-owner"); + assertThat(surveys.history(root, work, survey.id())).hasSize(4); + var artifact = new ArtifactService().attachBytes(root, work, "Checked".getBytes(java.nio.charset.StandardCharsets.UTF_8), "Check", "fixture", "fixture"); + new PlanCoordinator().change(root, work, "fixture", "finish", () -> plans.stepStatus(root, work, plan.id(), "TSK-0001", Plan.Status.COMPLETED, "fixture", "Checked", List.of(artifact.id()))); + assertThat(works.load(root, work).status()).isEqualTo(Work.Status.COMPLETED); + assertThat(new VerificationService().project(root).issues()).isEmpty(); + } + @Test void cliExposesReadOnlyPreviewAndRequiresAnExplicitApplyFingerprint() { + init(); var output = new StringWriter(); var errors = new StringWriter(); + assertThat(new EngineeringCli(root).execute(new PrintWriter(output), new PrintWriter(errors), "storage", "migrate", "--format", "json")).as(errors.toString()).isZero(); + assertThat(output.toString()).contains("LEGACY", "fingerprint"); assertThat(SqliteDatabase.path(root)).doesNotExist(); + assertThat(new EngineeringCli(root).execute(new PrintWriter(output), new PrintWriter(errors), "storage", "migrate", "--apply")).isEqualTo(2); + } + @Test void legacyChangesAfterAStagedInterruptionRequireNewPreviewAndSurviveRollback() { + String work = init(); var preview = migration.preview(root); + var interrupted = new StorageMigration(at -> { if (at.equals("STAGE_VALIDATED")) throw new IllegalStateException("Pause before guard"); }); + assertThatThrownBy(() -> interrupted.apply(root, preview.fingerprint())).hasMessageContaining("interrupted"); + // Simulate an already installed legacy writer that does not know the new journal. + new DiscussionService().add(root, work, "Keep this legacy observation", DiscussionEntry.Kind.NOTE, "fixture", "main", null); + assertThatThrownBy(() -> migration.recover(root, preview.fingerprint(), false)).hasMessageContaining("Source changed"); + assertThat(migration.recover(root, preview.fingerprint(), true).phase()).isEqualTo("ROLLED_BACK"); + assertThat(new DiscussionService().list(root, work)).extracting(DiscussionEntry::text).containsExactly("Keep this legacy observation"); + var updated = migration.preview(root); migration.apply(root, updated.fingerprint()); + assertThat(new DiscussionService().list(root, work)).hasSize(1); + } + @Test void epicCompletionReceiptsAndRunProvenanceMigrateWithoutNewApprovals() { + String parent = init(); var w = works.create(root, "Child", "", "Deliver", "", List.of(), List.of("Checked"), List.of(), "fixture"); + String child = w.id(); + works.guidance(root, child, WorkGuidance.Mode.DIRECT, WorkGuidance.ApprovalPolicy.WAIVED, "fixture-owner", "Explicit fixture policy", true); + var agents = new AgentService(); agents.configure(root, "general", "fixture-general", null, null, null); + var run = agents.run(root, child, "summarize context", null, "fixture-owner", "summary"); + var epics = new EpicService(); epics.configure(root, parent, Epic.Mode.RESULTS, "fixture-owner", "Aggregate"); + epics.link(root, parent, child, "fixture-owner", "Important"); epics.authorize(root, parent, "fixture-owner", "Reviewed", true); + var art = new ArtifactService().attachBytes(root, child, "Checked".getBytes(java.nio.charset.StandardCharsets.UTF_8), "Check", "fixture", "fixture"); + new VerificationService().complete(root, child, "fixture-owner", "Reviewed", true, List.of("1=" + art.id()), List.of(), "Inspection only"); + var before = new VerificationService().context(root, parent); var priorViews = agents.views(root, child); + var preview = migration.preview(root); assertThat(preview.valid()).as(preview.issues().toString()).isTrue(); + migration.apply(root, preview.fingerprint()); + assertThat(new VerificationService().context(root, parent).work()).isEqualTo(before.work()); + assertThat(agents.get(root, child, run.id())).isEqualTo(run); assertThat(agents.views(root, child)).isEqualTo(priorViews); + assertThat(new VerificationService().project(root).issues()).isEmpty(); + } + @Test void reservedLegacyIdsAreNotReusedAfterConversion() { + init(); Filespace.write(root.resolve(".ai-engineering/works/.sequence.yaml"), Documents.yaml(new WorkService.Sequence(2, "00F0")), true); + var preview = migration.preview(root); migration.apply(root, preview.fingerprint()); + assertThat(works.create(root, "Next", "", "Deliver", "", List.of(), List.of(), List.of(), "fixture").id()).isEqualTo("WRK-00F1"); + } +}