codecartographer

CodeCartographer é um framework para entender uma base de código desconhecida com um agente de codificação de IA e produzir uma especificação de reimplementação validada e agnóstica de linguagem. É distribuído como uma extensão Pi, um servidor MCP ou um template `.codecarto/` de arquivos Markdown e YAML. Como funciona: o "código" é Markdown estruturado mais YAML dentro de `.codecarto/`. `GUIDE.md` é o ponto de entrada do LLM, `workflow/pipeline.yaml` define fases e dependências, `workflow/status.yaml` mantém estado mutável por projeto e `workflow/VALIDATE.md` descreve o protocolo de validação. As fases formam um DAG — contratos e protocolos podem rodar em paralelo após a arquitetura, a portabilidade espera por ambos e a especificação de reimplementação é a última. O host lê o pipeline ativo, encontra a próxima fase cujas dependências estão completas, entrega as instruções dessa fase ao LLM, valida a saída e avança o status. Evidência e validação: cada fase escreve um artefato menor, modelado e com tags de evidência sob `.codecarto/findings/`, e fases posteriores releem os arquivos upstream específicos de que precisam. Os achados são marcados como fato observado, inferência forte, risco de portabilidade, alegação de comportamento externo ou questão em aberto. Cada saída de fase termina com uma tabela `## Validation` marcando cada critério de conclusão como PASS, PARTIAL ou FAIL com evidência; a validação analisa essa tabela e verifica cruzadamente o pareamento evidência/ação e as saídas secundárias declaradas, recusando-se a avançar em caso de FAIL, saída ausente ou veredito ilegível. Os artefatos produzidos incluem um mapa de arquitetura, relatório de defeitos, rastreador de correção de defeitos, contratos comportamentais, protocolos e estado, um pacote de portabilidade e a especificação final de reimplementação com módulos, cenários de aceitação e incógnitas conhecidas. Variantes de pipeline: o padrão é uma execução de auditoria profunda de 7 fases que divide a varredura de defeitos em passadas mecânica e semântica. Outras variantes incluem scout-first (8 fases), full-with-audit (6), full (5), defect scan (2), lite (3), architecture-only (1) e synthesis (4). As variantes podem ser trocadas no lugar sem excluir achados ou progresso. Resiliência de contexto: o sistema de arquivos, não a conversa, é a memória durável. Cada fase recebe uma janela de contexto nova; achados concluídos vivem em disco; `status.yaml` registra progresso, questões em aberto, itens de transporte e um backlog pós-pipeline. As transcrições de fase do Pi são apoiadas em arquivos e permanecem disponíveis via `/resume`, `/tree` e `/export`. Resumos de compactação com consciência de fase são salvos em checkpoint sob `.codecarto/scratch/checkpoints/`. O README observa que a pressão de contexto intra-fase é limitada, não eliminada. Superfícies e recursos: a extensão Pi adiciona comandos de barra, um widget de agentes ao vivo, sessões de fase apoiadas em arquivos, resumos de conclusão de fase, prompts iniciais opcionais guiados por LLM, rastreamento de uso por fase e interceptação de ferramentas (bash bloqueado; edição/gravação confinada a `.codecarto/`). O servidor MCP expõe prompts de fase, validação e operações experimentais de publicação/lista/reindexação de biblioteca para outros agentes capazes de MCP. Um painel HTML de arquivo único agrega progresso, links, uso e um resumo narrativo opcional. A síntese direta combina uma visão de produto com especificações de biblioteca confirmadas por humanos em um plano de projeto com proveniência, com verificações de pré-execução em tempo de execução exigindo confirmação humana explícita antes de mesclagem ou finalização.