Release notes.

Relevância, entrega compacta e observabilidade

Added

• Site de release notes da branch 3.0 com comparação rastreável à main, guia de migração do índice, configuração copiável do MCP e explicação do Jev, custos e fronteira de dados. Disponível em docs/release-notes.html.

• ATLAS_RELEVANCE_GATE=identifier dispensa o Jev para toda consulta que seja um identificador (reason=identifier_query). Opcional e desligado: no replay de 24/09, cortou as chamadas de 28 para 13, mas baixou o MRR de 0,613 para 0,569 e subiu os tokens de metadados em 32%, porque essas consultas perdem o corte e a rubrica v2.

Changed

• Site do Atlas recriado com a identidade visual, tipografia e logos do CodeSteer, narrativa sobre contexto do repositório e navegação responsiva. A documentação técnica completa permanece disponível em docs/documentacao.html.
• Guia de primeiros passos e documentação técnica alinhados à mesma identidade do site, com navegação compartilhada, diagramas na nova paleta e leitura responsiva de exemplos e tabelas.

• Respostas compactas (atlas_search e atlas_context no perfil compacto, e atlas_expand) só trazem o bloco budget quando algo foi cortado para caber; o perfil full, atlas_graph e atlas_brief não mudam. No replay de 24/09 (v2 + corte), os metadados de top_k=5 caíram de 9.933 para 6.879 tokens (−31%) e os de top_k=10 de 14.163 para 11.100 (−22%); os cenários com expansão, de 24.184 para 21.123 (−13%), com os mesmos 8 completos.
• Em atlas_expand, classe com mais de 6.000 caracteres e métodos indexados abre como cabeçalho + outline (métodos com ref, symbol, type e lines); next_ref segue o corpo inteiro e ATLAS_EXPAND_OUTLINE=0 desliga. StorageBackend foi de 4.819 tokens na primeira página (19.065 inteira) para 1.965, e ASTChunker de 4.528 (13.453) para 1.433.
• A rubrica default do Jev passa a ser a v2: 4 níveis concretos com what e examples, instruções que admitem consulta em português ou identificador, e kind/language no estado de cada candidato. ATLAS_RELEVANCE_RUBRIC=v1 volta à rubrica anterior; atlas_status.relevance.rubric declara a versão. Os limiares viram frações do nível mais alto da escala. No replay de 24/09 (top_k=10, com o corte), o MRR foi de 0,500 para 0,613, linguagem natural de 0,073 para 0,312 e os cenários completos de 7 para 8. A v2 custa ~2,3× por chamada (~US$ 0,001 por busca com top_k=10). Validado fora da amostra, com o Jev de verdade em 38 consultas novas (holdout): MRR 0,697 contra 0,507 do ranking local e 0,558 da v1 em top_k=10, com 39% menos tokens e nenhum alvo perdido.
• Uma chamada ao Jev leva o pool inteiro: o teto por requisição passa de 24 KB para 192 KB, abaixo do limite do modelo. Com top_k=10, a v1 fazia 2 chamadas sequenciais.
• Com o Jev ligado, o perfil compacto faz do top_k um teto: entre os top_k primeiros na ordem Jev, sai quem tem score abaixo da metade da escala (1,5 na v2, 1,0 na v1), sem repor a vaga nem cedê-la a commits. Exatos e candidatos sem avaliação ficam; omitted.relevance conta os cortes e atlas_status.relevance.cut declara a política. É o default; ATLAS_RELEVANCE_CUT=0 volta à seleção conservadora. Com as notas Jev de 24/09 reaplicadas no caminho de produção (v2), os metadados de top_k=10 caíram 38% e os cenários com expansão 32%, sem perder alvo (estudo).
• AGENTS.md é a única fonte das instruções de agente e da arquitetura; CLAUDE.md apenas importa esse arquivo.

Fixed

• Explicação do Jev no site sincronizada com a rubrica v2, lotes de 192 KB, corte padrão do perfil compacto sem reposição e gates opcionais. O guia passa a mostrar a ativação com a fronteira de dados e o custo de API explícitos.

• Com o Jev ligado, o pool chega ao Jev já na ordem do rerank lexical, e o candidato que ele não avalia com confiança fica nessa ordem, não mais na posição RRF crua. O cross-encoder continua só no fallback. No replay de 24/09, identificadores parciais voltam de MRR 0,400 para 0,781, e o total em top_k=10 vai de 0,375 para 0,496 (0,500 com o corte), acima dos 0,431 sem Jev. Sem Jev, o ranking não muda.
• Orientação de expansão começa com uma ou duas refs e exige lacuna de evidência para abrir mais; continuações deixam de recomendar leitura integral automática.

• atlas_expand recupera o intervalo original do símbolo, inclusive conteúdo truncado no índice, validando hash e caminho. Respostas grandes oferecem next_ref sem cache, vinculado ao hash, e offsets de conteúdo; continuações após alteração do arquivo são rejeitadas. O harness segue as páginas e só contabiliza evidência completa após receber a cadeia inteira.
• Avaliação pareada de expansão: 6/12 cenários completos contra 2/12 com conteúdo indexado; comparação inclui busca e expansões, sem chamadas Jev.

• Orientação de ferramentas e agentes esclarece que response_profile=full sobrescreve a flag de compactação; chamadas normais devem omitir o parâmetro.

• Perfil compacto usa chunk_id curto e mantém expansão de referências Base64 antigas, validando manifesto, hash atual e isolamento do workspace. A seleção considera o pool antes do top_k, preserva incertos e exatos e usa fallback local quando tudo é rejeitado. Defaults e limiares Jev permanecem iguais.
• Servidor e harness compartilham montagem e finalização; contadores de omissão entram antes do corte definitivo. Telemetria mede o texto retornado e distingue sucesso de processamento de mudança de ranking. Benchmark separa projeção, deduplicação e seleção e contabiliza expansões e evidências incompletas.
• Medição em 28 consultas: perfil compacto final reduziu 31,66% dos tokens de metadados e 12,21% com conteúdo, mantendo MRR/recall por classe sobre os mesmos candidatos (Jev desligado).

Added

• ATLAS_RELEVANCE_GATE opt-in (default off) evita Jev para função, método ou classe de nome exato único no pool, mantendo promoção determinística do alvo. Configuração aparece no status e motivo de dispensa no ledger sem custo remoto.
• Orientação de expansão seletiva (um ou dois símbolos por necessidade) e harness pareado de gate/expansão em lotes de 5, 2 e 1. Uma avaliação remota por consulta; custos contrafactuais separados dos reais, com parada em custo desconhecido. Avaliação pareada: 7,63% menos tokens em metadados com gate e lote dois, com mais chamadas de expansão; métricas de qualidade iguais entre variantes, com lacunas explicitadas por classe.

• Perfil compacto de contexto (ATLAS_CONTEXT_OPTIMIZATION, default False): atlas_search e atlas_context aceitam response_profile (default|compact|full). No compacto: projeção enxuta com ref de expansão, deduplicação conservadora por cobertura de conteúdo, orçamento a 70% do teto vigente e, com Jev ligado, seleção que só remove candidatos com score ≤ 0,25 e confiança ≥ 0,90. Nova tool atlas_expand resolve até 5 refs por id no índice (sem embedding/Jev), valida hash do arquivo e path no workspace. Independente de ATLAS_RELEVANCE. Exemplo MCP default OFF.
• Avaliador opcional de relevância Jev (ATLAS_RELEVANCE, default False): quando ligado, atlas_search envia a consulta e os candidatos do pool pós-RRF à API System One do OpenRouter e reordena por evidência antes do top_k e do orçamento existentes. Lotes de até 24 KB (máx. 2 chamadas, timeout compartilhado de 3 s); baixa confiança isola o candidato sem invalidar o lote. Falha de contrato ou timeout volta ao reranker local para o lote afetado. Cada busca emite uma linha JSON de custo em stderr (conhecido, parcialmente conhecido, zero sem chamada, ou desconhecido); atlas_status.relevance declara configuração sem rede. ATLAS_RERANK=0 continua desligando toda reordenação. Modelo via ATLAS_RELEVANCE_MODEL (default ~typesafe/jev-latest; pin versionado typesafe/jev-1.13 permanece aceito). probabilities de Score segue o contrato TypeSafe (chaves "0".."n-1" + legend).
• Guia de primeiros passos em português, com configuração por editor, primeira busca e ajuda com erros comuns, acessível pelo README e pela documentação visual.
• Observabilidade de tokens por consulta (ATLAS_OBSERVABILITY=1, opt-in): mede a string JSON final devolvida por atlas_search, atlas_context, atlas_brief e atlas_graph — caracteres/bytes exatos e tokens (exatos via tokenizer local embarcado ou ATLAS_TOKENIZER_PATH, com estimativa ceil(chars/4) apenas se indisponível, identificada como tal). Evento v1 em memória (último por tool) e JSONL local com retenção limitada (.code-index/observability/events.jsonl, ≤3 MiB com rotação). Bloco atlas_status.observability só aparece quando o flag está ligado.
• Teto global de resposta em atlas_search (24.000 caracteres/bytes, 6.000 tokens exatos com tokenizer configurado): corte determinístico de resultados inteiros pela cauda, preservando ordem/identidade dos sobreviventes; truncated.results declara quantos foram removidos. atlas_context/atlas_brief/atlas_graph reaproveitam seus tetos de caracteres existentes e ganham o mesmo bloco budget (mode, max_chars, max_bytes, max_tokens, tokenizer_sha256, used_chars) na resposta.
• scripts/eval_search.py --delivery: mede MRR/recall@5 da resposta REALMENTE ENTREGUE (pós-montagem e pós-orçamento) nos modos metadata/content, sobre os mesmos candidatos do ranking pré-budget — nunca altera a medição histórica. --benchmark mede o overhead de observabilidade (desligada / estimativa / tokenizer local) sobre payloads sintéticos fixos.
• Dependência direta tokenizers>=0.22.2,<0.23 (já transitiva via fastembed).
• Tokenizer padrão embarcado: SmolLM2-135M (Apache-2.0, revisão e SHA-256 fixos) incluído no pacote, carregado de forma preguiçosa, sem download em runtime. ATLAS_OBSERVABILITY=1 basta para registrar contagem exata segundo essa referência; ATLAS_TOKENIZER_PATH substitui o padrão. Eventos identificam origem (bundled/custom), nome, revisão e hash, sem registrar paths. Os limites de tokens das respostas passam a valer por padrão mesmo com o registro desligado; falha no recurso/override degrada para estimativa e limite por bytes. A contagem não representa faturamento do modelo cliente.

Fixed

• Corrigidos os 13 erros de tipagem reportados pelo mypy nos contratos de links Markdown, grafo, histórico e status. O fallback de sampling fora de workers AnyIO agora aceita objetos awaitable além de corrotinas nativas.
• Wikilinks Obsidian com caminho de vault ([[meta/glossary#termo]]) passam a resolver a partir dos arquivos indexados (sufixo a partir da raiz da vault), em vez de concatenar no diretório da nota de origem. #heading vira aresta links_to no nó section correspondente e preenche resolved_section; se o heading não existir, a aresta cai no doc. Alvo inexistente continua sem nó fantasma; [[nota]] / [[nota|alias]] e .//../ não mudam.
• budget.used_chars agora representa o comprimento real do JSON final devolvido (antes era calculado antes de o próprio valor ser gravado, ficando sempre uma medição defasada). Em produção o campo é montado pelo finalizador compartilhado (response_budget.finalize_response), que substitui o bloco parcial que context.py monta para seus chamadores diretos (ex.: testes).
• background_reindex.log passa a ter teto de 256 KiB: o spawn recorta o final do arquivo antes de appendar o run novo, para o log de reindex em background não crescer sem limite.

Contexto por tarefa, semântica e histórico Git

Corte major: Fase 1 omitida do 2.2.0, mais as camadas 4 (semântica opt-in) e 5 (arqueologia de Git). Sem flag nova para a história: a janela é constante (GIT_HISTORY_MAX_COMMITS_PER_FILE / GIT_HISTORY_MAX_MONTHS). Watcher, SCIP, rerank e o braço estrutural já estão em [2.2.0].

Added

• atlas_context — pacote da tarefa em uma chamada (target + intent ∈ edit/debug/review/understand), com teto CONTEXT_RESPONSE_MAX_CHARS. Substitui encadear atlas_graph + atlas_brief quando o símbolo já é conhecido.
• atlas_graph(mode="affected") — raio de impacto por BFS reversa. Um commit é história, não dependência: affected e hubs ignoram nós commit e arestas touches (não entram no grau).
• Camada semântica opt-in (semantic.py), ligada só com ATLAS_SEMANTIC=1. Cadeia de origem: sampling MCP síncrono → ATLAS_SEMANTIC_LOCAL_URL → ATLAS_SEMANTIC_API_URL. ATLAS_SEMANTIC_API_KEY vai só no header; ATLAS_SEMANTIC_MODEL troca o payload para model + messages (OpenAI-compatible / OpenRouter). Sem origem, o índice estrutural permanece completo. atlas_status.semantic declara enabled, origin, egress, index e last_generation. Warnings de busca: semantic_layer_unavailable e semantic_arm_unavailable (vector+FTS seguem disponíveis).
• Arqueologia de Git (local, sem env). A indexação lê a janela do repositório e publica .code-index/history.json + tabela commits_*. atlas_search pode devolver hits type="commit" / language="git". atlas_context(intent="debug") projeta sections.recent_history (commits ligados por touches). Degradação declarada: git_history_unavailable, git_history_partial, git_history_stale, git_history_empty. atlas_index reporta git_history_status, git_history_commits e git_history_touches.

Changed

• CURRENT_INDEX_VERSION passa de 2.2.0 para 2.3.0 (campos purpose / purpose_hash / purpose_vector e sidecar semantic.json). MIN_INDEX_VERSION continua 2.0.0: índices 2.0.x–2.2.x seguem buscáveis. Converter para 2.3.0 exige atlas-index --full sem --paths — recorte incremental não mistura schemas.

Fase 3 do roadmap — "o índice reflete a realidade". Watcher, grafo de chamadas via SCIP e imports multi-linguagem. As duas capacidades novas entram desligadas por padrão: sem as flags, o comportamento é idêntico ao de 2.1.x. Esta versão também publica os estágios opt-in da Fase 2 (recuperação medida), já mesclados na branch antes do corte.

Added

• Watcher de workspace (watcher.py), ativado por ATLAS_WATCH=1. Observa o workspace numa thread daemon do watchdog, coalesce a rajada de eventos em uma janela de WATCH_DEBOUNCE_S (2 s) e delega a reindexação incremental ao mesmo subprocesso já usado no startup — nunca indexa dentro do processo do servidor. Eventos filtrados por should_ignore + .atlasignore, o que inclui .code-index/ e impede o loop de auto-reindexação. watchdog é um extra opcional (pip install "codesteer-atlas[watch]"); ausente, o servidor sobe igual e atlas_status reporta watch: "unavailable".
• Ingestão SCIP (scip_ingest.py), ativada por ATLAS_SCIP=1. Detecta o indexador da linguagem (scip-python, scip-typescript, scip-go, rust-analyzer), invoca-o em subprocesso com timeout e lê o index.scip com um leitor próprio do wire format do protobuf — sem dependência nova. Produz as primeiras arestas kind: "calls" do grafo, com origin: "scip".
• Imports multi-linguagem no grafo: Go, Java, C#, Kotlin, Scala, Rust, PHP, Ruby e Swift passam a produzir arestas imports (antes só Python/JS/TS). As famílias de namespace (Java, C#, Kotlin, Scala) resolvem por manifest.files_declares; as de convenção de path resolvem pela raiz do pacote inferida do manifesto de build (go.mod, pom.xml, *.csproj, Cargo.toml).
• origin por aresta ("scip" | "treesitter"), presente apenas em calls e imports — os kinds em que a qualidade da resolução varia. explain e affected reportam origin: "unknown" quando o campo não existe.
• resolution_coverage no graph.json e em atlas_status: quais linguagens do índice resolvem por scip, quais por treesitter, quais não resolvem (none) e quantos arquivos ficaram sem resolução (Princípio VI — degradação explícita).
• watch reportado por atlas_status (∈ active|disabled|unavailable|failed) e scip_status/scip_edges reportados por atlas_index (scip_status ∈ ok|disabled|toolchain_missing|timeout|parse_failed).
• graph.html distingue a origem da aresta pelo traço (scip sólida, treesitter tracejada, sem origem pontilhada) e traz na legenda os tiers de cobertura, incluindo as linguagens que o índice não resolve. Segue autocontido e offline.
• Extra opcional watch = ["watchdog>=4.0,<7"] em [project.optional-dependencies]. [project].dependencies permanece inalterado — nenhuma dependência obrigatória nova.
• (Fase 2) Cross-encoder ONNX opt-in na reordenação pós-RRF, via ATLAS_RERANK_MODEL (reranker.CrossEncoderReranker, fastembed já presente). Ausente, o rerank lexical de ranking.py permanece inalterado. Falha de carga emite cross_encoder_unavailable e cai no lexical. Ver dec-008.
• (Fase 2) Braço estrutural opt-in na fusão RRF, via atlas_search(..., structural=True) (default False). Spreading activation sobre graph.json; grafo ausente emite structural_arm_unavailable. Ver dec-009.
• (Fase 2) Harness scripts/eval_search.py --structural e registro do reranker ativo no relatório. Baseline recapturada em tests/eval/baseline.json (1644 chunks, MRR 0.4289, defaults de produção).

Changed

• CURRENT_INDEX_VERSION passa de 2.1.0 para 2.2.0 (novo campo files_declares no manifest). MIN_INDEX_VERSION continua 2.0.0: índices 2.0.x e 2.1.0 seguem buscáveis, sem reindexação forçada. Um grafo anterior a 2.2.0 simplesmente não tem origin nem resolution_coverage, e atlas_status responde {"status": "unknown", "reason": "index_version_below_2_2_0"} em vez de listas vazias.

Fixed

• uvx --from git+... atlas-serve morria no import com ImportError: cannot import name 'McpError' from 'mcp.shared.exceptions'. Causa: uvx ignora o uv.lock e, com mcp>=1.24.0,<3 no pyproject, resolve mcp 2.x (SDK 2, McpError → MCPError) e recua fastmcp==2.14.1 (ainda importa McpError). Correção: restaurar o teto mcp>=1.24.0,<2. Smoke tests/test_mcp_pin.py impede o teto <3 de voltar sem teste falhar.

Added

• Script doc_agent.py para automatizar a criação de notas da knowledge base a partir de metadados de PR.

Fixed

• Backend de armazenamento LanceDB corrigido para busca híbrida e escrita atômica de manifest.

Changed

• Migração da documentação para o modelo de knowledge base e busca com retorno somente de metadados por padrão.
• Instruções de busca de código (CLAUDE.md) revisadas.

Added

• Resolução do diretório de índice via MCP roots (roots/list) como fallback quando o servidor é registrado globalmente (sem CLAUDE_PROJECT_DIR/WORKSPACE_FOLDER_PATHS), evitando que o índice caia em HOME.
• Cabeçalhos com timestamp no log de reindex em background.

Added

• Resolução do diretório de índice a partir de variáveis de ambiente de projeto do editor (CLAUDE_PROJECT_DIR, WORKSPACE_FOLDER_PATHS).
• Resolução de wikilinks do Obsidian em referências markdown retornadas por atlas_search.

Changed

• CLAUDE.md/README.md atualizados com boas práticas de uso do MCP codesteer-atlas.
• Instruções de instalação do plugin/Power e configuração de variáveis de ambiente no README.

Added

• Resultados de atlas_search em Markdown enriquecidos com referências cruzadas entre documentos (markdown_references).
• CONTRIBUTING.md com instruções de setup de desenvolvimento.

Changed

• Docstring de atlas_status refinada para deixar claro que é apenas diagnóstico, não pré-requisito para atlas_search.
• Docstring de atlas_search refinada quanto a uso e tratamento de erros.

Added

• Documentação visual do MCP (docs/index.html + docs/styles.css).

Changed

• Docstrings de atlas_search/atlas_map reforçadas para uso proativo das ferramentas.

Changed

• Tratamento de erros e logging mais robustos em operações Git e no mecanismo de lock (get_git_head_sha, is_reindex_locked toleram falhas de SO sem quebrar o fluxo).

Release inicial do CodeSteer Atlas.

Added

• Indexação por AST via Tree-sitter (ASTChunker), chunking em granularidade de classe/função/método, com fallback para chunk de módulo inteiro.
• Embeddings locais (fastembed, all-MiniLM-L6-v2, 384 dimensões) com lazy loading e carregamento thread-safe.
• Armazenamento em LanceDB embutido (StorageBackend), com escrita atômica de manifest.json.
• Busca híbrida (vetorial + BM25) fundida via Reciprocal Rank Fusion (RRF).
• Servidor MCP (FastMCP) expondo atlas_search, atlas_map, atlas_status, atlas_index.
• Indexação incremental por hash sha256, com fast path por mtime/tamanho para pular releitura de arquivos inalterados.
• Suporte a .atlasignore para exclusão declarativa de arquivos.
• Lock entre processos (reindex_lock) para coordenar reindexações concorrentes.
• Reindex automático em background no startup do servidor, rodando em subprocesso separado (evita contenção de GIL e corrupção do protocolo stdio JSON-RPC).
• Suporte multi-linguagem: Python, JavaScript, TypeScript/TSX, Go, Java, C#, Dart, Pascal, VB6, Razor, XML, Markdown, SQL, entre outros.
• Script de deploy (deploy_mcp.py) para registrar o servidor em Cursor, Claude Desktop, Cline e Claude Code CLI.