pi-flow

Orquestrador programático reutilizável sobre o SDK do Pi. O pi-flow transforma uma intenção em uma mudança isolada, validada, revisada e pronta para aplicação controlada.

intenção → preflight → worktree → sandbox → implementação → validação
         → revisão independente → correção limitada → revisão final
         → inspeção → reconciliação → apply → cleanup

Estado atual: produto pré-1.0 (0.2.0) preparado para publicação pública no npm. Não há push nem deploy automático.

Garantias principais

• analyze e review são somente leitura e não recebem bash, edit ou write;
• implement trabalha em branch e worktree exclusivos;
• Bash só é disponibilizado em Bubblewrap ou Docker seguro, sem fallback irrestrito;
• revisão usa uma sessão independente e somente leitura;
• há no máximo uma correção automática por ciclo;
• a origem Git deve estar limpa e não é alterada durante a implementação;
• integração ocorre somente por apply, para outcome satisfied, usando git merge --ff-only;
• estado, evidências, tentativas, locks, reparos e migrações são auditáveis;
• operações mutantes da API passam por RunLifecycleService e operation lock;
• worktrees são preservados por padrão.

Requisitos

• Node.js >=22.19.0;
• Git;
• credenciais e modelo configurados para o Pi;
• Docker funcional ou Bubblewrap compatível para tarefas que precisam de Bash;
• projeto-alvo Git na raiz, limpo e com AGENTS.md.

Neste host, Bubblewrap não consegue criar o namespace de usuário. O fallback Docker está validado. A rede do container permanece desabilitada por padrão.

Instalação

npm install --global @igor-guari/pi-flow
pi-flow --help

Como biblioteca TypeScript:

npm install @igor-guari/pi-flow

O pacote é publicado como @igor-guari/pi-flow; o binário instalado continua sendo pi-flow.

Instalação para desenvolvimento

npm install
npm run build
npm link
pi-flow --help

Sem link global:

npm run dev -- --help
npm run dev -- analyze /caminho/projeto "Mapeie a arquitetura"

Comandos

Criar uma execução

pi-flow analyze <projeto> "<tarefa>"
pi-flow review <projeto> "<tarefa>"
pi-flow implement <projeto> "<tarefa>" [--timeout-ms <ms>]

• analyze: leitura e análise do projeto;
• review: revisão somente leitura;
• implement: cria worktree, implementa, valida, revisa e, quando permitido, corrige uma vez.

Exemplos:

pi-flow analyze ./api "Explique o fluxo de autenticação"
pi-flow review ./api "Revise tratamento de erros e cobertura"
pi-flow implement ./api "Adicione paginação com testes"

Inspecionar e reconciliar

pi-flow inspect <run-id|diretório> [--format text|json]
pi-flow reconcile <run-id|diretório> [--format text|json]

inspect apresenta schema, revisão, workflow, outcome, Git, delivery, cleanup e locks. reconcile compara run.json com Git e filesystem.

Status e códigos de reconciliação:

| Status | Código | |---|---:| | consistent | 0 | | recoverable | 10 | | diverged | 11 | | missing | 12 |

Reparos disponíveis, sempre com confirmação:

pi-flow reconcile <run> --repair cleanup-state --confirm-repair
pi-flow reconcile <run> --repair branch --confirm-repair
pi-flow reconcile <run> --repair delivery-state --confirm-repair

Reparos não descartam alterações nem reescrevem histórico.

Retomar e repetir etapas

pi-flow resume <run> [--timeout-ms <ms>]
pi-flow retry <run> --from review [--timeout-ms <ms>]
pi-flow retry <run> --from correction --confirm-correction [--timeout-ms <ms>]
pi-flow retry <run> --from final_review [--timeout-ms <ms>]

resume continua a primeira etapa incompleta no mesmo worktree. retry reseta apenas a etapa escolhida e posteriores. Runs aplicadas não podem ser modificadas. Artefatos anteriores são preservados por tentativa.

Aplicar e limpar

pi-flow apply <run>
pi-flow apply <run> --continue
pi-flow cleanup <run> [--delete-branch]

apply exige execução concluída, outcome satisfied, reconciliação consistente e origem limpa no commit-base. Ele cria o commit no worktree e aplica somente por fast-forward. O estado intermediário applying permite recuperação após crash com --continue.

cleanup remove o worktree apenas quando seguro. A branch só é removida com --delete-branch. Ambos os comandos são idempotentes.

Schema e locks

pi-flow migrate <run> --to 1 --confirm-migration
pi-flow unlock <run> --confirm-stale-lock

A migração de run legada cria run.json.backup-<timestamp> e registra auditoria. Não existe migração silenciosa.

unlock remove somente lock local comprovadamente órfão. Locks ativos, remotos ou inválidos nunca são removidos automaticamente.

Ajuda e versão

pi-flow --help
pi-flow --version

A versão exibida vem do package.json do pacote instalado.

O parser rejeita flags desconhecidas, duplicadas, sem valor ou usadas em combinações incompatíveis, retornando código 2. inspect e reconcile oferecem JSON versionado (outputVersion: 1) em stdout, adequado para workers e automações sem parsing da apresentação textual.

Estados e outcomes

Status operacional e resultado semântico são independentes:

OperationalStatus: running | completed | failed | cancelled
Outcome: satisfied | partial | blocked | not_satisfied | unknown

Uma sessão terminar tecnicamente não significa que a tarefa foi satisfeita. Critérios de aceite precisam referenciar evidências registradas; referências inválidas produzem fallback seguro para unknown.

Etapas persistidas do workflow:

preflight → worktree → implementation → review → correction
          → final_review → completed

Cada etapa registra status, tentativas, início, fim e erro.

Evidências e artefatos

Cada run fica em runs/<id>/. Dependendo do modo e das tentativas, contém:

runs/<id>/
├── run.json
├── output.txt
├── review-output.txt
├── correction-output.txt
├── final-review-output.txt
└── *-attempt-<n>.txt

run.json inclui:

• status, outcome e critérios de aceite;
• evidências de ferramentas com argumentos sanitizados, duração e status;
• snapshot Git inicial/final, arquivos alterados e diff;
• worktree, branch e commit-base;
• workflow e tentativas;
• revisão, correção e revisão final;
• delivery, cleanup, reconciliação e auditorias;
• schemaVersion e revision.

A gravação é atômica (tmp → fsync → rename → fsync do diretório) e usa concorrência otimista por revision.

Sandbox

Seleção fail-closed:

Bubblewrap funcional → Bubblewrap
senão Docker seguro → Docker
senão → Bash indisponível

Política Docker:

• rede none;
• raiz somente leitura;
• apenas o worktree gravável;
• capabilities removidas;
• no-new-privileges;
• usuário sem root;
• /tmp temporário e limitado.

Imagem configurável:

PI_FLOW_SANDBOX_IMAGE=minha-imagem pi-flow implement ...

Como a rede é desabilitada, dependências precisam estar disponíveis na imagem ou em cache autorizado.

Cancelamento e códigos de saída

implement, resume e retry aceitam timeout e sinais. O cancelamento aborta a sessão, drena logs, persiste cancelled e preserva o worktree.

| Situação | Código | |---|---:| | satisfied | 0 | | falha operacional | 1 | | uso inválido | 2 | | partial | 3 | | not_satisfied | 4 | | blocked | 5 | | unknown ou outcome ausente | 6 | | timeout | 124 | | SIGINT | 130 | | SIGTERM | 143 |

Os códigos semânticos são aplicados aos comandos de workflow (analyze, implement e review). Com --format json, sucessos e resultados semânticos usam pi-flow.workflow; erros usam pi-flow.error, sempre com outputVersion: 1.

API TypeScript

API pública versionada:

import {
  PI_FLOW_API_VERSION,
  RunLifecycleService,
  inspectRun,
  loadRun,
  runLifecycleService,
} from "pi-flow";

console.log(PI_FLOW_API_VERSION); // 1

A API pública oferece leitura, inspeção, tipos, utilitários de retry e a fachada segura para operações mutantes. Funções internas sem operation lock e subpaths como pi-flow/dist/lifecycle.js não são exportados.

Exemplo:

const { runDirectory, record } = await loadRun("minha-run");
const report = await runLifecycleService.reconcile(runDirectory, record);
console.log(report.status);

Atualmente a API pública gerencia o lifecycle de runs existentes; a criação programática de workflows ainda não faz parte do contrato público.

Desenvolvimento e validação

npm run typecheck
npm test
npm run check
npm run test:package
npm audit --omit=dev --audit-level=high

test:package executa npm pack, instala o .tgz num consumidor temporário, compila TypeScript, testa import ESM, bloqueio de subpaths e o binário instalado.

Hooks locais:

pre-commit → npm run typecheck
pre-push   → npm run check

GitHub Actions executa instalação limpa, audit de produção, build, testes e contrato do pacote. A CI é a validação autoritativa.

Limitações atuais

• sem --runs-dir, --model, --thinking ou --dry-run;
• findings estruturados possuem severidade, localização, bloqueio e evidências; critical nunca é autocorrigido, somente medium/low é elegível, e critical/high bloqueante impede apply;
• sem políticas completas para arquivos sensíveis e comandos destrutivos;
• sem limites explícitos de CPU, memória, processos ou quantidade de ferramentas;
• operation lock possui heartbeat periódico e ownership verificado; ainda faltam lease remoto e política configurável de expiração;
• sem checkpoints opcionais de aprovação de plano/diff;
• sem integração com GitHub/GitLab, tickets, PRs, API HTTP, filas ou dashboard;
• rede do sandbox Docker desabilitada, sem política final de cache/mirror;
• o override/pós-instalação de [email protected] é temporário até o SDK trazer a árvore corrigida.

Documentação adicional

• ROADMAP.md: estado atual e próximas entregas;
• PILOT-RESULTS.md: histórico dos experimentos e aprendizados.