Repository navigation
fix(mcp): bloquear conclusões quando o índice não estiver fresh - #32
Conversation
The master plan (section 7) is explicit that "the service name is architecture-map, not lexnotify-map" -- the server was already generic (single --repo-root arg, no LexNotify-specific logic), just mislabeled. Renames the FastMCP instance and its primary tool names to match section 7.1 (search_capability, get_component, get_map_status), keeping the old names as deprecated aliases for backward compatibility. Adds verify_references, the one tool from section 7.1 that had no implementation at all (evidence cross-checking per section 3.5). find_similar and get_impact_graph remain unimplemented -- both need import-edge extraction the scanner doesn't produce yet, documented as a known gap in the module docstring rather than silently missing. Companion PR in LexNotify-Web (#805) updates map-guardian.md to the new tool names.
…liases Review feedback on this PR: the only confirmed consumer org-wide (map-guardian.md in LexNotify-Web, the sole hit for `lexnotify-map` across a full gh api search/code sweep) is already migrated to the new names in the companion PR (LexNotify/LexNotify-Web#805). Keeping unvalidated duplicate tools around for a consumer that doesn't exist just doubles the tool surface an agent has to parse, with no repoId validation on the old path -- not backward compatibility, just dead weight from day one. Follow-up filed to add test coverage for mcp_server.py (had none before or after this PR).
# Conflicts: # src/aak/mcp_server.py
Checkpoint de revisão Fase 4Este PR foi revisado na base empilhada exata e permanece draft/mergeável, sem review humano ou thread pendente. A pilha combinada termina em CI combinada: Python 3.10/3.12 e dependency audit/SBOM verdes no run https://github.com/MHX-Digital/agent-architecture-kit/actions/runs/30477544972. Validação local final: 123/123, secret scan 0 matches, compileall/diff check verdes. Correções foram mantidas no PR que introduziu o comportamento: binding explícito do golden corpus ao commit no #32; fronteira autenticada sanitizada do corpus no #37. Nenhum gate foi relaxado. Estado: implementado/testado; aguardando revisão humana; não integrado; não implantado. Rollback por revert dos commits da unidade, sem mutação de índice ou ambiente externo. |
Integração ordenada concluída — 2026-07-30 UTC
O #40 já havia sido empilhado no #38; portanto seu conteúdo chegou a Validação no SHA finalRun manual exato: https://github.com/MHX-Digital/agent-architecture-kit/actions/runs/30570028307
Artefatos novos, vinculados somente ao SHA final
Os artefatos da RC anterior não foram reutilizados ou reatribuídos. Estado: integrado e validado localmente/na CI; não implantado; canário não executado. Próximo gate: autorização humana explícita para o canário sanitizado. |
…s added since PR #42 PRs #37 (auth) and #32/#36 (index freshness) merged into main after this test file was written. The mcp_repo fixture now inits a real git repo and commits it so ARCHITECTURE_MAP.json's sourceSha can match HEAD, and every tool call passes expectedCommit accordingly. get_adr()'s return shape also changed to a trust-wrapped dict; updated the two assertions that relied on the old plain-string return.
1 participant
Resultado
Implementa e endurece o contrato de freshness da issue
LexNotify/LexNotify-Web#791sobre a API canônicaarchitecture-map.Parent Epic:
LexNotify/LexNotify-Web#780Causa-raiz e achado da revisão forense
O índice expunha
sourceSha, mas nenhuma tool comparava esse SHA com uma precondição confiável do chamador. A primeira versão do PR ainda permitia um bypass: quandoexpectedCommitera omitido, o servidor substituía silenciosamente o valor pelo HEAD observado e podia declararfreshsem precondição externa.A revisão corrigiu esse bypass: ausência de
expectedCommitagora resulta emunknowne bloqueio fail-closed. Não há comparação por prefixo; somente SHA completo de 40 caracteres, existente e ancestral do checkout servido, é aceito.Alterações
get_map_statusretorna repositório, branch, commit esperado/observado/indexado, timestamp, schema, contagens, escopos, freshness e motivo;fresh,stale,unknown,incompatible,indexing,failed;INDEX_NOT_FRESHquando o estado não éfresh;.indexingimpede conclusões durante construção isolada;Matriz resumida
freshstaleunknownincompatibleindexingfailedCompatibilidade e escopo
Preserva os nomes das sete tools observadas.
expectedCommitcontinua interpretável como parâmetro opcional para clientes antigos, mas a omissão não autoriza conclusão: falha fechada. Auth, reindexação e carga permanecem em PRs separados (#37, #36 e #38).Testes locais
git diff --check: limpo;a660745cc7e755d43144be65bcf22d6afef97123.Cobertura inclui todos os estados, SHA ausente/curto/inválido/inexistente, commit de outra branch/anterior/divergente, marker ausente/corrompido, schema incompatível, backend indisponível e bypass por omissão.
Riscos e gates
Clientes que omitem a precondição deixam de receber resposta conclusiva. Isso é intencional. O PR permanece draft: não há revisão humana nem checks de CI observados no repositório do kit; rollout depende da integração ordenada #32 → #36 → #37 → #38 e dos gates do Epic.
Rollback
Reverter os commits desta branch. Nenhum deploy, merge, migration ou produção foi executado.