1
trsthales
3 min de leitura ·

Pitch: Criei o pactx: Uma ferramenta Open Source para resolver a amnésia e perda de contexto de IAs em projetos longos

pactx

Fala pessoal!

Desenvolvendo um projeto educacional usando ChatGPT, Claude e Gemini no dia a dia, comecei a bater repetidamente no mesmo gargalo: a perda de contexto e a deriva das IAs em sessões longas.

O ritual comum de pedir "Resume o que fizemos até aqui" é falho: pedir para uma IA com contexto saturado resumir o próprio estado gera alucinações e perda silenciosa de decisões de arquitetura.

A partir dessa dor, construí o pactx (@trsthales/pactx), um motor de continuidade de contexto em loop fechado (Closed-Loop State Engine) em TypeScript com persistência transacional.

A Tese Central:
"LLMs são motores de processamento sem estado (stateless compute). O repositório é estado persistente."

Em vez de confiar na memória volátil de threads de chat, o repositório Git passa a ser a única autoridade canônica da verdade.

Como Funciona o Ciclo de Vida:

  1. Egress (npx @trsthales/pactx): Em cerca de 1 segundo, inspeciona o estado do Git (branch atual, commits recentes, diffs) e a pasta canônica .ai-context/ (regras invariantes, requisitos, ADRs vigentes, glossário e hipóteses descartadas) e gera um Context Pack compacto em Markdown (~400 tokens) direto no Clipboard.

  2. Trabalho normal com a IA: Você cola no chat e a IA inicializa sabendo exatamente a tarefa, as restrições e o que ela NÃO deve fazer.

  3. Ingress (npx @trsthales/pactx update): No final da sessão, você pede /handoff. A IA emite um bloco estruturado. Você roda o comando no terminal e o pactx valida a segurança e persiste as decisões de forma atômica no repositório com revisão humana em texto integral.

Engenharia & Suíte de Governança (v0.3):

  • TransactionEngine com WAL: Toda mutação passa por Write-Ahead Logging durável (PREPARED -> APPLYING -> COMMITTED), com escritas atômicas (Write-to-Temp + Rename) e auto-recovery no boot contra kill -9 ou quedas de energia.
  • Modelo de Requisitos (requirements.md): Separa o espaço do problema (regras de negócio) do espaço da solução (ADRs), com vínculo bidirecional satisfies.
  • Zero-Trust Filesystem Jail: Proteção estrita contra Path Traversal, Anti-Symlink/Hardlink overwrite (lstatSync), sanitização de tags XML/HTML e regexes imunes a ReDoS.
  • Suíte Completa de Comandos:
    • pactx status: Dashboard visual executivo no terminal (e suporte a --json).
    • pactx doctor: Diagnóstico automatizado de regras de integridade com autocorreção (--fix).
    • pactx diff: Pré-visualização colorida de propostas de mutação antes de aplicar.
    • pactx rollback: Reversão determinística de transações com análise de dependências no grafo.

Testando em 1 minuto:

  1. Inicializa a estrutura no seu projeto:
    npx @trsthales/pactx init

  2. Empacota o contexto para o clipboard:
    npx @trsthales/pactx

  3. No final da sessão de IA, copie a resposta do /handoff e rode:
    npx @trsthales/pactx update

Links do Projeto:

Gostaria muito do feedback da comunidade sobre a arquitetura transacional e o modelo de estado!

Carregando publicação patrocinada...