archgate review-context

Pré-computa o contexto de revisão com briefings de ADRs para arquivos alterados. Projetado para integrações de CI e plugins de editor que precisam de um resumo de quais ADRs se aplicam aos arquivos sendo alterados.

archgate review-context [options]

Opções

Opção	Descrição
--staged	Incluir apenas arquivos no git stage
--base [ref]	Comparar arquivos alterados contra uma ref base (auto-detecta quando omitido)
--run-checks	Incluir resultados de verificação de ADR
--domain <domain>	Filtrar por um único domínio
--verbose	Incluir o texto de Decisão e Do’s/Don’ts de cada ADR
--strict	Sair com código 1 quando resumos foram truncados, ou (com --run-checks) quando check encontrou achados relevantes para o modo estrito

Exemplo

archgate review-context --staged

Quais arquivos contam como alterados

Mesmo sem nenhuma flag, este comando funciona em relação a uma ref base, e não apenas à árvore de trabalho: o conjunto de arquivos alterados é a diferença do branch (git diff <base>...HEAD) unida aos arquivos staged, unstaged e não rastreados (não ignorados). A ref base é resolvida da mesma forma que em archgate check:

Prioridade	Origem	Arquivos alterados
1	--staged	Apenas arquivos staged — nenhuma ref base é resolvida
2	--base <ref>	git diff <ref>...HEAD + alterações na árvore de trabalho
3	baseBranch em .archgate/config.json	git diff <resolved-ref>...HEAD + alterações na árvore de trabalho
4	Auto-detecção	git diff <detected-ref>...HEAD + alterações na árvore de trabalho

A auto-detecção tenta origin/HEAD, depois origin/main, origin/master, main local e, por fim, master local, e o resultado é persistido em .archgate/config.json para que execuções futuras pulem essa sondagem. --base sem valor se comporta da mesma forma que omiti-lo: primeiro a configuração, depois a auto-detecção. Quando nenhuma ref base pode ser resolvida, apenas as alterações na árvore de trabalho são usadas.

Modo estrito

Passe --strict para que este comando falhe (código de saída 1) em vez de apenas relatar: ele falha quando truncatedBriefings não está vazio (requer --verbose para haver algo a truncar), ou, com --run-checks, quando o checkSummary.warningsExceeded ou checkSummary.strictAdvisoryExceeded reaproveitado é true. --strict não falha em violações de regra comuns (checkSummary.failed/ruleErrors) — este comando permanece um gerador de contexto para agentes, não um segundo portão de conformidade; use archgate check para bloquear em violações de regra. Uma falha de --strict imprime o payload JSON completo primeiro, depois registra o motivo em stderr antes de sair.

--strict é resolvido da mesma forma que archgate check --strict: flag de linha de comando, depois uma chave strict: boolean em .archgate/config.json, depois desligado.

Tamanho da saída

Por padrão, cada ADR é identificado apenas por id, title, domain, files e rules — o suficiente para saber quais ADRs se aplicam aos arquivos alterados. Leia os que você precisar com archgate adr show <id>.

Use --verbose para incorporar na resposta o texto de Decisão e Do’s/Don’ts de cada ADR aplicável. Esse texto cresce conforme o número de ADRs correspondentes e domina o payload — em um repositório com muitos ADRs, fica grande o bastante para que agentes de IA deixem de exibir o resultado inline. Prefira o padrão e busque os detalhes sob demanda; use --verbose apenas quando um único payload autocontido for realmente necessário.

Resumos truncados

O texto dos resumos tem um limite por seção. Quando uma seção de Decisão ou de Do’s and Don’ts excede o limite, ela é cortada e a omissão é relatada de quatro formas:

• O ponto de corte é marcado no texto com [... truncated — read full ADR via adr://<id>].
• O resumo do próprio ADR lista os nomes das seções afetadas em truncatedSections.
• Todos os ids de ADR afetados são reunidos no array truncatedBriefings de nível superior. Ele é preenchido após a filtragem por --domain, portanto nomeia apenas ADRs presentes na resposta.
• Um aviso nomeando esses ADRs é escrito em stderr, mantendo o stdout como JSON válido.

Interprete qualquer um desses sinais como indicação de que o texto normativo do ADR está incompleto: as regras que ele estabelece podem estar na parte que foi cortada. Leia o documento completo com archgate adr show <id> antes de confiar no resumo.

Outros dois limites truncam este payload, cada um com seu próprio aviso em stderr. truncatedFiles é definido quando a lista de arquivos alterados excede seu limite, de modo que os arquivos além dele ficam ausentes de todos os domínios. Com --run-checks, checkSummary.truncated é definido quando uma regra relatou mais violações do que o limite por regra — execute archgate check para a lista completa.

Quando --run-checks é usado, checkSummary segue a mesma regra de archgate check --output json: seu array results contém apenas as regras que têm algo a relatar, enquanto os contadores ao lado continuam cobrindo todas as regras executadas.