# Revisão de planos e trilha de auditoria Recupere restrições de projetos, compare planos propostos com evidências, acompanhe resultados do ciclo de vida (planejado, enviado, mesclado, lançado, verificado) e salve resultados aprovados com procedência. - Canonical: https://docs.xmemo.dev/pt-br/docs/guides/plan-review-and-audit - Locale: pt-BR - Content-Locale: pt-BR - Canonical-Content-Digest: 175b0b54be778ea414d888fa51982bb437637db88fc7fe769ca86ce36f314e63 - Edition-Digest: 0b776c19cb54dbb5b87d89f4704c83b3e6070d0f43ff9d2f50df92d9c1acaad7 - Source-Revision: sha256:fe7c573aca1054f57d1a9a3473cb5469fb99b6d0edc9e97966d5f99565482dbd ## 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: ```bash 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: ```bash 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. ## Usuário do ChatGPT Dê ao ChatGPT acesso duradouro às suas preferências do XMemo, fatos do projeto, decisões e TODOs sem colar tokens bearer no chat. Conecte o servidor MCP hospedado do XMemo pelo fluxo OAuth do app ChatGPT/OpenAI e aprove a concessão memory:read e memory:write para sua conta do XMemo. Salve uma preferência de teste ou anotação de projeto, inicie um novo chat e peça ao ChatGPT para recuperá-la via XMemo antes de prosseguir. Se o OAuth falhar ou as ferramentas não aparecerem, saia do servidor MCP no app host, reconecte a URL do servidor XMemo e tente novamente antes de criar tokens diretos. ## Desenvolvedor Copilot / Codex Transfira decisões do repositório, convenções de código, notas de correção de bugs e histórico de tarefas entre agentes de IDE e CLI. Use OAuth para VS Code / GitHub Copilot e Gemini CLI quando disponível. Para Copilot CLI, Codex, Cursor ou outros clientes MCP diretos, mantenha XMEMO_KEY no ambiente local ou cofre de segredos e defina um XMEMO_AGENT_INSTANCE_ID estável. Registre uma decisão da base de código ou correção de bug e peça ao próximo agente de IDE ou CLI para recuperar o contexto relevante do XMemo antes de editar. Se as recuperações estiverem vazias, verifique o caminho da configuração MCP selecionada, a variável de ambiente XMEMO_KEY para clientes diretos e eventuais credenciais OAuth desatualizadas no app host. ## Líder de piloto de equipe / corporativo Avalie a memória compartilhada com controles de conta, atribuição de origem, fluxos de exportação/exclusão e evidências de configuração seguras para revisores. Crie ou acesse o espaço de trabalho protegido do XMemo, convide usuários aprovados e conecte cada cliente via OAuth ou credencial direta com escopo de acordo com os selos de disponibilidade. Peça para um membro do piloto salvar uma memória de equipe de teste, confirme a atribuição de origem no XMemo e revise os caminhos de exclusão/exportação e suporte. Se um membro não conseguir se conectar, verifique as permissões de função, aprovação OAuth, status de prontidão do cliente e orientações de suporte antes de emitir um novo token. ## Operador de agentes autônomos Permita que agentes headless ou agendados registrem progresso, recuperem decisões anteriores e mantenham uma identidade estável e não secreta de instância. Obtenha /api/v1/mcp/config/autonomous-agent. Prefira auth_modes.oauth quando o executor suportar OAuth + cabeçalhos personalizados; use auth_modes.xmemo_key com XMEMO_KEY de um cofre de segredos apenas para executores totalmente headless. Execute uma tarefa de teste que grave progresso no XMemo, reinicie o executor e confirme se ele recupera esse progresso usando o mesmo XMEMO_AGENT_INSTANCE_ID. Se a atribuição mudar ou as recuperações se dividirem entre instâncias, persista XMEMO_AGENT_INSTANCE_ID fora do git e verifique se o executor não o está gerando a cada início.