Revisão de planos e trilha de auditoria

Objetivo do usuário e limites do fluxo de trabalho

Este fluxo de trabalho prático orienta desenvolvedores e agentes revisores na auditoria de propostas de software, especificações técnicas e planos arquiteturais em relação às evidências empíricas do repositório. Os revisores comparam declarações de planos com restrições armazenadas de projetos, rastreiam alterações em estágios discretos do ciclo de vida (planned, submitted, merged, released, verified) e persistem decisões de consenso aprovadas com atribuição imutável de procedência.

Disponibilidade e pré-requisitos

Os recursos de auditoria e revisão de planos são fornecidos nos perfis de cliente MCP e na CLI da Skill autônoma:

• Perfis MCP cursor-plugin e ordinary-full: oferecem recursos abrangentes de revisão: get_project_context (pacote de projeto somente leitura), recall_context, search_knowledge, update_project_decision (transições de decisões: resolve, supersede, reopen), update_project_todo (transições de itens de trabalho: accept, assign, block, unblock, complete, cancel) e query_audit (audita eventos e registros de consolidação).
• Perfil MCP claude-plugin: inclui get_project_context, recall_context, create_pending_decision, resolve_decision, record_event, remember, recall e todo.
• Perfis MCP generic-public, chatgpt-public e public-only: suportam get_project_summary(project_id, focus) com focus="blockers" ou focus="status" para resumos rápidos, e memory_overview para estatísticas.
• Skill autônoma (Claude Code, Codex, OpenClaw): comandos textuais da versão 1.1.35 servida de help.mjs: recall-context (linhas 84-87), search (linhas 80-83), remember (linhas 72-75), update (linhas 44-47), todo-add/list/done (linhas 112-123) e activity/stats (linhas 64-71).
• Pré-requisitos: escopo de leitura (memory:read) para consultar contextos de projetos e histórico de auditoria; escopo de gravação (memory:write) para registrar decisões e atualizar itens de trabalho.

Uma tarefa completa: auditoria de um plano de migração de serviço

Neste passo a passo de auditoria sintética, um agente revisa uma proposta de atualização de autenticação para o projeto proj_security_core, valida declarações em relação às restrições do repositório, realiza a transição de itens de trabalho e armazena o resultado aprovado.

Recuperar restrições do projeto e histórico de auditoria

Recupere diretrizes estabelecidas do projeto e inspecione a procedência de decisões anteriores usando recall-context ou get_project_context:

node scripts/xmemo-skill.mjs recall-context --query "token revocation policy session lifetime proj_security_core" --max_items 6 --max_tokens 2500

Transicionar status do item de trabalho e registrar decisão

Marque o TODO de revisão como concluído e salve a resolução definitiva com procedência:

node scripts/xmemo-skill.mjs todo-done --id todo_rev_401
node scripts/xmemo-skill.mjs remember --content "Approved plan auth_migration_v3: enforced 24h token revocation, strict mutual TLS, and zero unauthenticated fallback. Verified by reviewer audit." --path "plans/auth_migration_v3"

Resultado observável

Uma auditoria estruturada de planos gera uma trilha imutável e verificável que reflete marcos discretos do ciclo de vida:

• Cinco estados distintos de marcos: planos e itens de trabalho avançam por estágios explícitos: planned (especificação esboçada) -> submitted (revisão formal solicitada) -> merged (implementação integrada) -> released (empacotado e implantado) -> verified (validação pós-implantação aprovada). Nunca confunda planned com released ou verified.
• Trilha de auditoria determinística: query_audit retorna registros estruturados contendo registro de data e hora do evento, agent_id atuante, ID da memória/decisão de destino e diferenças de estado antes/depois.
• Preservação da procedência: ao consultar memórias com recall ou recall_context, o resultado expõe metadados imutáveis de procedência identificando a sessão de autorização e o registro de data e hora exatos.

O que os agentes podem acessar

Agentes que realizam revisão de planos e auditorias interagem com representações estruturadas e delimitadas:

• Log de auditoria somente de acréscimo: logs de eventos de auditoria operam somente por anexação (append-only). Os agentes não podem sobrescrever, adulterar ou excluir registros históricos de auditoria de decisões.
• DAGs de versão e substituição: atualizar uma decisão ou memória existente cria uma nova versão vinculada ao seu predecessor; estados anteriores permanecem recuperáveis como versões substituídas (list_memory_versions em cursor-plugin / ordinary-full).
• Contexto fundamentado em evidências: as ferramentas de recall retornam evidências factuais extraídas de memórias de projetos, impedindo que os agentes confundam inferências de modelo não verificadas com decisões de projetos registradas.

Limites de compartilhamento e armazenamento

Registros de auditoria e decisões são regidos por limites estritos de multilocação e projetos:

• Delimitação de escopo do projeto: decisões e itens de trabalho vinculados a project:proj_security_core permanecem isolados de projetos pessoais não relacionados ou espaços de equipe externos.
• Exclusão de rascunhos: blocos de rascunho temporários de desenvolvedores (scratchpads), logs locais de depuração e pensamentos transitórios não devem ser gravados em registros de decisões duradouros.
• Imutabilidade de atribuição: o servidor carimba cada decisão com as identidades autenticadas do chamador owner_identity e source_identity; clientes não podem falsificar ou se passar por outros agentes.

Recuperação de falhas

Gerencie discrepâncias de auditoria e conflitos de revisão usando fluxos de resolução padrão:

• Declarações de planos não verificadas ou contradições: se um plano proposto contradisser decisões arquiteturais existentes, não resolva a decisão. Realize a transição da decisão com action="supersede" ou action="reopen" acompanhada de uma resolution_note detalhada descrevendo a discrepância.
• ID de item de trabalho ou decisão ausente: quando um todo_id ou decision_id referenciado não puder ser encontrado, consulte itens ativos usando todo-list (Skill) ou get_project_context(project_id="proj_security_core") para localizar o ID canônico.
• Permissão de escopo negada: se um agente não tiver permissões de gravação no projeto de destino, update_project_decision retornará HTTP 403 Forbidden. Escale para o administrador do projeto para atribuição de função.

Referência relacionada

Para conceitos de segurança associados, detalhes de procedência e gerenciamento de itens de trabalho, consulte os seguintes guias:

• Procedência e atribuição: /docs/concepts/provenance-attribution para detalhes de atribuição do chamador.
• Referência de itens de trabalho TODO: /docs/tools/todos para rastreamento de tarefas de projetos.
• Referência de transações do livro-razão: /docs/tools/ledger para auditoria financeira e de recursos.
• Retomada e transferência de agentes: /docs/guides/resume-and-handoff para fluxos de trabalho de pontos de verificação de sessão.
• Guia de projetos: /docs/concepts/projects para organização de espaços de trabalho de projetos.