wendkeep 0.85.1 → 0.87.0

package/docs/pt-BR/commands/commit.md

@@ -0,0 +1,159 @@
+# Commits baseados em evidências
+
+**PT-BR** · [English](../../en/commands/commit.md)
+
+## Objetivo
+
+Produzir a mesma mensagem auditável em Codex, Claude Code ou outro cliente Git, usando somente
+entrada tipada, referências públicas e o resumo do index staged. O kernel é determinístico e não
+lê o Vault, `.brain`, registros de sessão ou rede.
+
+## Quando usar
+
+Use antes de commits de implementação `feat`, `fix`, `refactor` ou `perf` que precisam registrar
+autoridade causal, tarefas, testes, escopo e evidência verificável de forma equivalente entre
+harnesses.
+
+## Quando não usar
+
+Não use para inventar prova, publicar conteúdo privado, reescrever histórico ou automatizar push.
+Commits `docs`, `test` e `chore` dispensam contexto somente quando todos os arquivos alterados são
+objetivamente documentação/testes. Alteração de produto exige o corpo governado mesmo com outro tipo.
+
+## Pré-requisitos
+
+Execute dentro de um repositório Git, com o WendKeep instalado localmente e os arquivos do produto
+já selecionados no index staged.
+
+## Sintaxe
+
+```bash
+npx --no-install wendkeep commit context --input <json|-> [--json]
+npx --no-install wendkeep commit context --clear [--json]
+npx --no-install wendkeep commit render --input <json|->
+npx --no-install wendkeep commit prepare --message-file <path> [--source <source>]
+npx --no-install wendkeep commit validate --message-file <path> [--json]
+```
+
+## Opções e códigos de saída
+
+- Exit `0`: contexto escrito/limpo ou mensagem válida.
+- Exit `1`: mensagem governada inválida.
+- Exit `2`: argumento, JSON, Git, privacidade ou contexto inválido/stale.
+- `--consume-context` é reservado ao wrapper `commit-msg`; remove o contexto após validação verde.
+
+## Instalação opt-in
+
+Os hooks Git não são ativados pelo `init` padrão. Para copiar os wrappers portáteis e configurar
+`core.hooksPath=.githooks` somente neste repositório:
+
+```bash
+npx --no-install wendkeep init --git-commit-hooks --yes
+```
+
+Hooks personalizados nunca são sobrescritos silenciosamente. Se o `init` encontrar conflito, ele
+preserva o arquivo. Revise-o e, somente se quiser substituí-lo, execute novamente com `--force`; o
+arquivo anterior fica em `.bak`.
+Um `core.hooksPath` customizado também é conflito: sem `--force` ele permanece intocado.
+
+## Exemplos
+
+### Preparar um commit
+
+Crie um JSON conforme `schema/commit-message-v1.schema.json`. Declare autoridade e referências de
+evidência, mas não envie `tasks`, `tests`, `fresh` ou `verified`. O runtime deriva tarefas do
+checklist canônico com Task Contracts concluídos. Testes vêm somente de sensores declarados por
+`[sensor:<id>]` e executados pelo coletor; `[phase:verify]`
+sozinho nunca é resultado. Sensors declarados no Envelope devem corresponder exatamente em IDs,
+configuração, comando, severidade e resultado à reexecução canônica; apenas essa reexecução gera a
+linha `Tests`. O gate remoto reexecuta o sensor no checkout do SHA correspondente.
+Cada referência publicada recebe digest SHA-256 rederivado. ADR/design validam
+ID/path/artefato. Tasks com `[req:]` exigem uma referência `spec` versionada e sanitizada que defina
+cada requisito. Evidence Envelope, Verdict, receipt e TDD attestation podem participar da validação
+local, mas são omitidos da Evidence remota: não há publicação de IDs de worktree/sessão/branch nem
+promoção de consistência autocontida para prova. Se uma mensagem os alegar como `fresh`/`verified`,
+o range rejeita `WENDKEEP_COMMIT_REMOTE_PROOF_UNAVAILABLE`. Os trailers fixos
+`Remote-Proof-Scope: git,authority,tasks,spec,sensors` e `Local-Causal-Proof: unpublished` tornam
+essa fronteira explícita. No range, authority/artefatos, task/spec, `Scope` Git e config/sensors são
+rederivados do SHA, e apenas a reexecução canônica gera `Tests`. `Co-Authored-By` é
+omitido enquanto não houver identidade registrada confiável.
+
+A autoridade normal é a ADR causal:
+
+```json
+{ "authority": { "kind": "adr", "adr": "ADR-1234", "ref": "docs/ADR-1234.md", "issue": "#123" } }
+```
+
+Somente quando não existe change/ADR causal, o harness nativo pode declarar o fallback abaixo.
+`issue` deve ser `#NNN` e `design` precisa estar versionado no mesmo commit sob
+`docs/superpowers/specs/` ou `plans/`:
+
+```json
+{
+  "authority": {
+    "kind": "native",
+    "issue": "#40",
+    "design": "docs/superpowers/specs/design-aprovado.md"
+  }
+}
+```
+
+O runtime confirma perfil efetivo `OFF`, ausência de context/change/lease e ADR causal reais, além
+da issue no design. Esse modo gera trailers únicos `Authority: native-no-causal-change`, `Issue` e `Design`. Texto solto,
+design não versionado, prova stale/unverified, corpo ou testes ausentes falham fechados.
+
+```bash
+git add <arquivos-do-produto>
+npx --no-install wendkeep commit context --input commit-input.json
+git commit -m "feat(escopo): rascunho"
+```
+
+`commit context` calcula o hash SHA-256 do diff staged e guarda o contexto sanitizado em
+`.git/wendkeep-commit-input.json`, fora do working tree. `prepare-commit-msg` substitui o rascunho
+pela mensagem canônica; `commit-msg` valida e consome o contexto. Se o index mudar, o contexto fica
+stale e deve ser recriado.
+O `commit-msg` relê o contexto, compara a mensagem inteira e o hash/files staged, e só consome o
+contexto após sucesso. `merge`, `squash` e amend limpam contexto incompatível para não contaminar o
+commit seguinte. `--message-file` fica contido no repositório ou git-dir.
+
+Outros comandos:
+
+```bash
+npx --no-install wendkeep commit render --input commit-input.json
+npx --no-install wendkeep commit validate --message-file .git/COMMIT_EDITMSG
+npx --no-install wendkeep commit context --clear
+```
+
+Commits realmente triviais permanecem intactos. Commits de implementação
+`feat`, `fix`, `refactor` e `perf` exigem assunto Conventional Commit com ADR ou o fallback nativo
+restrito acima, seções Capability, Evidence, Tasks, Tests e Scope, hash staged e trailer
+`WendKeep-Commit: v1`. Amend, merge e squash não recebem corpo duplicado ou prova inventada.
+
+## Privacidade e falha segura
+
+- Caminhos absolutos mesmo embutidos, qualquer Vault configurado/default, `.brain`, registros de sessão, PII e segredos são
+  rejeitados antes da persistência.
+- Evidência `reported`, `legacy-unbound`, `stale` ou `unproven` não pode ser apresentada como prova.
+- O contexto contém referências sanitizadas e metadados do diff, nunca o conteúdo privado do Vault.
+- `--no-verify` não é um fluxo aceito: o CI valida cada commit novo, inclusive merges e resoluções inéditas.
+
+## Resultado esperado
+
+Uma mensagem determinística, autocontida, sem material privado, com hash do mesmo index que foi
+commitado e trailers causais coerentes.
+
+## Erros comuns e diagnóstico
+
+`wendkeep doctor` mostra `[commit-hooks] healthy`, `disabled`, `missing` ou `drift` e permanece
+read-only. Para recuperar arquivos ausentes ou divergentes após revisão:
+
+```bash
+npx --no-install wendkeep init --git-commit-hooks --force --yes
+```
+
+Se um commit for abandonado, limpe apenas o contexto transitório com
+`wendkeep commit context --clear`. Nenhum comando reescreve histórico ou faz push automaticamente.
+
+## Próximos passos
+
+Revise a mensagem gerada, faça o commit e deixe o gate de range do PR validar qualquer bypass local.

package/docs/pt-BR/commands/evidence-embeddings.md

@@ -0,0 +1,244 @@
+# Plugin opcional de embeddings de evidências
+
+[English](../../en/commands/evidence-embeddings.md)
+
+## Objetivo
+
+Definir uma fronteira programática para reranqueamento semântico local sem adicionar modelo,
+runtime de ML, vector database, cliente HTTP ou dependência de provider ao Core do WendKeep.
+
+Esta superfície **não é um comando CLI**. Ela é exportada por `wendkeep/vault` para plugins locais
+carregados explicitamente pelo composition root da aplicação.
+
+## Quando usar
+
+Use esta API quando um composition root confiável precisar reranquear um conjunto pequeno de
+candidatos que o recall lexical/FTS já filtrou, mantendo o modelo e o adapter fora do Core.
+
+Embeddings ficam desligados por padrão.
+
+```js
+const result = await rerankEvidenceCandidatesWithEmbedding(rows, query);
+// result.metrics.status === 'disabled'
+```
+
+O Core:
+
+- não procura plugins em `node_modules`;
+- não executa `import()` a partir de configuração do Vault;
+- não baixa modelos;
+- não abre conexão de rede;
+- não persiste vetores;
+- não entrega o corpus inteiro ao plugin.
+
+Um plugin só recebe dados quando o chamador fornece o objeto do plugin e define `enabled: true`.
+
+## Quando não usar
+
+Não use o plugin como índice autoritativo, mecanismo de ampliação de escopo, autoload de código ou
+substituto para filtros/recall lexical. Também não use provider remoto: o contrato exige execução
+local, in-process, sem rede e sem retenção.
+
+### Contrato de autoridade
+
+A ordem de autoridade permanece:
+
+```text
+Markdown/JSONL do Vault → índice incremental → candidatos lexical/FTS → reranqueamento opcional
+```
+
+O plugin atua somente sobre um prefixo bounded de candidatos já filtrados. Ele não pode:
+
+- tornar seu índice ou cache a autoridade;
+- ampliar silenciosamente o escopo de projeto, sessão, change ou logical path;
+- ocultar `authority`, `validity` ou proveniência;
+- remover candidatos não processados — eles permanecem no final, na ordem original;
+- alterar os objetos-fonte retornados pelo Core.
+
+## Pré-requisitos
+
+- plugin local revisado e carregado explicitamente pela aplicação;
+- modelo/configuração fixados por fingerprint SHA-256;
+- budgets de batch e bytes definidos;
+- candidatos já filtrados pelo recall lexical/FTS.
+
+### Manifest versionado
+
+Use `buildEvidenceEmbeddingManifest()` para criar o manifest e
+`createEvidenceEmbeddingPlugin()` para vinculá-lo à função `embed`.
+
+Campos obrigatórios:
+
+| Campo | Regra |
+|---|---|
+| `schema_version` | `1` |
+| `protocol_version` | `1` |
+| `plugin_id` | identificador estável e local |
+| `plugin_version` | versão do adapter |
+| `model_id` | identificador do modelo |
+| `model_revision` | revisão imutável usada pelo adapter |
+| `model_fingerprint` | `sha256:<64 hex>` do modelo/configuração efetiva |
+| `dimensions` | 1 a 65536 |
+| `locality` | exatamente `local` |
+| `transport` | exatamente `in-process` |
+| `network` | exatamente `forbidden` |
+| `retention` | exatamente `none` |
+| `max_batch_size` | 1 a 512 documentos |
+| `max_input_bytes` | 1 a 4 MiB |
+| `integrity` | hash do payload canônico do manifest |
+
+O manifest é declarativo. JavaScript arbitrário não pode ser sandboxado pelo Core; portanto, instale
+somente plugins locais confiáveis e revise seu código. O WendKeep impede carregamento automático e
+valida o contrato antes de entregar qualquer evidência, mas não transforma código de terceiros em
+código confiável.
+
+## Sintaxe
+
+```text
+buildEvidenceEmbeddingManifest(options)
+createEvidenceEmbeddingPlugin({ manifest, embed })
+verifyEvidenceEmbeddingPlugin(plugin)
+rerankEvidenceCandidatesWithEmbedding(rows, query, options)
+```
+
+## Exemplos
+
+```js
+import {
+  buildEvidenceEmbeddingManifest,
+  createEvidenceEmbeddingPlugin,
+  rerankEvidenceCandidatesWithEmbedding,
+} from 'wendkeep/vault';
+
+const manifest = buildEvidenceEmbeddingManifest({
+  plugin_id: 'local.minha-embedding',
+  plugin_version: '1.0.0',
+  model_id: 'local.meu-modelo',
+  model_revision: '2026.08.27',
+  model_fingerprint: 'sha256:<hash-do-modelo-e-configuracao>',
+  dimensions: 384,
+  max_batch_size: 64,
+  max_input_bytes: 262144,
+});
+
+const plugin = createEvidenceEmbeddingPlugin({
+  manifest,
+  async embed(request, { signal }) {
+    // Adapter local: nenhum acesso de rede e nenhuma retenção de texto.
+    // Deve devolver exatamente uma query vector e um vector para cada document.id.
+    return {
+      schema_version: 1,
+      model_fingerprint: manifest.model_fingerprint,
+      query_vector: await localModel.embed(request.query.text, { signal }),
+      document_vectors: await Promise.all(request.documents.map(async (document) => ({
+        id: document.id,
+        vector: await localModel.embed(document.text, { signal }),
+      }))),
+    };
+  },
+});
+
+const reranked = await rerankEvidenceCandidatesWithEmbedding(rows, query, {
+  enabled: true,
+  plugin,
+  maxCandidates: 64,
+  maxInputBytes: 262144,
+});
+```
+
+O request contém somente:
+
+```json
+{
+  "schema_version": 1,
+  "model_fingerprint": "sha256:...",
+  "query": { "text": "..." },
+  "documents": [
+    { "id": "<chunk_id>", "text": "<title + heading + content>" }
+  ]
+}
+```
+
+`logical_path` não é enviado ao plugin. A proveniência completa permanece nos objetos-fonte e volta
+com a ordem reranqueada.
+
+## Resultado esperado
+
+A resposta é fail-closed e deve conter apenas:
+
+```json
+{
+  "schema_version": 1,
+  "model_fingerprint": "sha256:...",
+  "query_vector": [0.1, 0.2],
+  "document_vectors": [
+    { "id": "<chunk_id>", "vector": [0.3, 0.4] }
+  ]
+}
+```
+
+O Core rejeita:
+
+- dimensão diferente do manifest;
+- `NaN`, infinito ou vetor de norma zero;
+- fingerprint de modelo divergente;
+- documento ausente, duplicado ou desconhecido;
+- campos adicionais no envelope;
+- quantidade de vetores diferente da quantidade de documentos.
+
+A similaridade usada pelo adapter canônico é cosseno. Empates preservam a ordem original.
+
+## Opções e códigos de saída
+
+O limite efetivo é sempre o menor entre o chamador e o manifest do plugin.
+
+- `maxCandidates`: padrão 128; máximo 512;
+- `maxInputBytes`: padrão 256 KiB; máximo 4 MiB;
+- documentos que não couberem permanecem depois do prefixo reranqueado;
+- o Core nunca envia parcialmente um documento;
+- query ou primeiro documento que não cabem produzem
+  `EVIDENCE_EMBEDDING_BUDGET_EXCEEDED`.
+
+Com `required: false` — padrão — erro de contrato, budget, resposta ou execução devolve a ordem
+lexical original e `metrics.status: "fallback"`. Com `required: true`, o erro tipado é propagado.
+
+Códigos principais:
+
+- `EVIDENCE_EMBEDDING_PLUGIN_INVALID`;
+- `EVIDENCE_EMBEDDING_BUDGET_EXCEEDED`;
+- `EVIDENCE_EMBEDDING_RESPONSE_INVALID`;
+- `EVIDENCE_EMBEDDING_EXECUTION_FAILED`.
+
+## Operação segura
+
+1. Mantenha `enabled: false` até validar o plugin e o hash do modelo.
+2. Execute `verifyEvidenceEmbeddingPlugin(plugin)` antes de registrar o adapter.
+3. Fixe `plugin_version`, `model_revision` e `model_fingerprint`; não use alias mutável como
+   `latest`.
+4. Comece com budgets pequenos e compare a ordem com o recall lexical/FTS.
+5. Registre apenas métricas — IDs, contagens, bytes e tempos — nunca query, texto ou vetores.
+6. Trate mudança de fingerprint como uma geração nova de qualquer cache pertencente ao plugin.
+
+## Erros comuns e diagnóstico
+
+Quando `metrics.status` for `fallback`:
+
+1. desative o plugin; o recall lexical/FTS continua sendo a rota segura;
+2. valide o manifest e confira `metrics.reason`;
+3. confirme dimensão, fingerprint e quantidade dos vetores;
+4. descarte somente caches pertencentes ao plugin e reconstrua-os pela autoridade
+   `EVIDENCE_INDEX.jsonl`;
+5. nunca apague ou edite `EVIDENCE_INDEX.jsonl`, Markdown ou sidecars do Core para reparar um
+   provider de embeddings;
+6. reative com `required: false` e promova para `required: true` apenas em um ambiente que realmente
+   exige o provider.
+
+## Próximos passos
+
+Este contrato não instala um modelo nem integra embeddings automaticamente ao MCP, doctor ou
+Observer. Ele define a fronteira segura e testável para um adapter irmão futuro. O Core continua
+completo e funcional sem qualquer plugin.
+
+Use o guia de [MCP nativo](mcp.md) para a superfície paginada/lexical já exposta e o guia de
+[manutenção e diagnóstico](maintenance-and-diagnostics.md) para inspecionar a saúde dos artefatos
+derivados sem reconstruí-los.

package/docs/pt-BR/commands/mcp.md

@@ -63,20 +63,71 @@ O `init` gera a entrada genérica reproduzível:
 ```
 
 Reads: `wendkeep_project_status`, `wendkeep_context_status`, `wendkeep_memory_recall`,
-`wendkeep_memory_conflicts`, `wendkeep_change_list`, `wendkeep_change_show`,
-`wendkeep_change_status`, `wendkeep_spec_effective`, `wendkeep_task_show`,
-`wendkeep_task_evaluate`, `wendkeep_handoff_current`, `wendkeep_evidence_latest` e
-`wendkeep_observer_query`.
+`wendkeep_evidence_recall`, `wendkeep_memory_conflicts`, `wendkeep_change_list`,
+`wendkeep_change_show`, `wendkeep_change_status`, `wendkeep_spec_effective`,
+`wendkeep_task_show`, `wendkeep_task_evaluate`, `wendkeep_handoff_current`,
+`wendkeep_evidence_latest` e `wendkeep_observer_query`.
 
 Writes: `wendkeep_memory_assert`, `wendkeep_checkpoint_create`, `wendkeep_context_select`,
 `wendkeep_task_claim`, `wendkeep_task_complete` e `wendkeep_handoff_publish`.
 
+## Recall paginado e indexado de evidências
+
+`wendkeep_evidence_recall` é a superfície bounded para recuperar evidências do Vault. Ela seleciona
+candidatos pelo sidecar lexical persistente ou pelo SQLite/FTS5 opcional, reranqueia com o scorer
+canônico e devolve uma página compacta. `wendkeep_memory_recall` permanece disponível como API
+legada e não ganha silenciosamente o novo contrato.
+
+Entrada principal:
+
+- `project_root` e `query` são obrigatórios;
+- `limit` aceita 1 a 100 resultados por página;
+- `cursor` é opaco e só vale para a mesma consulta, filtros e índice lógico;
+- `max_bytes` aceita 2 a 524288 e limita exatamente o JSON serializado de `results`; o padrão é
+  64 KiB;
+- `candidate_limit` aceita 1 a 4096 candidatos;
+- `posting_budget` aceita 1 a 1048576 postings visitados;
+- `backend` aceita `auto`, `sqlite` ou `lexical`;
+- `filters` aceita igualdade por `authority`, `validity`, `entity_type`, `project_id`,
+  `change_slug`, `session_id`, `work_session_id` e `logical_path`, além de
+  `logical_path_prefix`. Cada filtro pode ser string ou lista de strings.
+
+Exemplo de chamada:
+
+```json
+{
+  "name": "wendkeep_evidence_recall",
+  "arguments": {
+    "project_root": "<projeto>",
+    "query": "contrato de autenticação",
+    "limit": 5,
+    "max_bytes": 65536,
+    "candidate_limit": 512,
+    "posting_budget": 65536,
+    "backend": "auto",
+    "filters": {
+      "authority": "verified",
+      "validity": "active",
+      "logical_path_prefix": "04-Decisões/"
+    }
+  }
+}
+```
+
+A resposta contém `results`, `next_cursor`, `has_more`, `as_of`, contagens e bytes da página. Cada
+resultado omite `content`, informa `content_bytes`, mantém um `excerpt` bounded e substitui
+`logical_path` por `logical_ref`, uma referência relativa ao Vault — nunca um caminho absoluto. O
+bloco `candidates` expõe backend, quantidade, postings, rebuild e fallback. Quando o orçamento de
+candidatos não cobriu todo o conjunto possível, `complete_candidate_set` é `false`; isso impede que
+o consumidor interprete uma seleção truncada como exaustiva.
+
 ## Resultado esperado
 
 O handshake e `tools/list` retornam JSON-RPC válido. Cada tool declara effect/capability e schemas
 versionados. Reads conhecidas não entram no mutation gate, mas mantêm binding explícito de
-projeto/worktree, paginação por cursor, budget padrão de 1 MiB, redaction, timeout e cancelamento.
-Observer aparece indisponível abaixo de Node 22.13 sem impedir Core no Node 18.
+projeto/worktree, paginação por cursor, budgets, redaction, timeout e cancelamento. Observer aparece
+indisponível abaixo de Node 22.13 sem impedir Core no Node 18. O recall indexado também funciona no
+Node 18 pelo fallback lexical; SQLite/FTS5 permanece opcional.
 
 Writes exigem `project_root`, `session_id`, `active_context_id`, `actor`, `reason`, capability exata
 e `lease.id`/`lease.expires_at`; o executor revalida a autorização causal e os gates da CLI. A
@@ -89,8 +140,16 @@ código e duração — nunca argumentos ou payload.
 - `MCP_CAPABILITY_REQUIRED` / `MCP_SCOPE_AUTH_REQUIRED`: capability ausente ou não autorizada.
 - `MCP_LEASE_EXPIRED`: obtenha autorização/lease nova; não altere timestamp manualmente.
 - `MCP_PROJECT_SCOPE_MISMATCH`: `project_root` e `worktree_root` pertencem a bindings diferentes.
-- `MCP_REQUEST_TOO_LARGE` / `MCP_RESPONSE_TOO_LARGE`: use `limit` e o cursor retornado.
+- `MCP_REQUEST_TOO_LARGE` / `MCP_RESPONSE_TOO_LARGE`: reduza os budgets e continue pelo cursor.
 - `MCP_RUNTIME_UNSUPPORTED`: use Node 22.13+ para Observer; Core permanece disponível.
+- `MCP_EVIDENCE_QUERY_REQUIRED`: informe uma consulta não vazia.
+- `MCP_EVIDENCE_CURSOR_INVALID`: cursor adulterado, stale ou usado com outra consulta/filtros.
+- `MCP_EVIDENCE_BUDGET_TOO_SMALL`: nem os metadados mínimos do próximo resultado cabem em
+  `max_bytes`.
+- `MCP_EVIDENCE_BACKEND_UNAVAILABLE`: o backend SQLite foi exigido, mas FTS5 não está disponível;
+  use `auto` ou `lexical`.
+- `MCP_EVIDENCE_ARTIFACT_UNSAFE`: um artefato derivado violou a fronteira física do Vault.
+- `MCP_EVIDENCE_RECALL_INVALID`: filtro, backend ou limite fora do contrato.
 
 ## Próximos passos
 

package/hooks/evidence-context.mjs

@@ -2,7 +2,13 @@
 // UserPromptSubmit: bounded, read-only retrieval from the local evidence index.
 import { pathToFileURL } from 'node:url';
 import { readHookInput, readSessionRegistry, writeHookOutput } from './obsidian-common.mjs';
-import { loadEvidenceIndex, recallEvidence, renderEvidenceContext } from './evidence-recall.mjs';
+import {
+  EVIDENCE_SEARCH_MAX_CANDIDATES,
+  loadEvidenceIndex,
+  recallEvidence,
+  renderEvidenceContext,
+  searchEvidenceCandidates,
+} from './evidence-recall.mjs';
 import { sanitizeMemoryText } from './memory-schema.mjs';
 import { resolveHookOperatingProfile } from './operating-profile-runtime.mjs';
 import {
@@ -11,16 +17,44 @@ import {
 } from './active-context-handoff-evidence.mjs';
 import { isBootstrapPrompt } from '../packages/integrations/src/prompt-content.mjs';
 
+function scopedRows(rows, activeContext, registry) {
+  return scopeEvidenceRows(rows, { activeContext, registry });
+}
+
+function indexedScopedEvidence(vaultBase, query, topK, activeContext, registry) {
+  const initialLimit = Math.min(
+    EVIDENCE_SEARCH_MAX_CANDIDATES,
+    Math.max(512, Number(topK || 0) * 64),
+  );
+  const first = searchEvidenceCandidates(vaultBase, query, {
+    candidateLimit: initialLimit,
+  });
+  let scoped = scopedRows(first.rows, activeContext, registry);
+  if (scoped.length >= topK || !first.has_more
+      || initialLimit >= EVIDENCE_SEARCH_MAX_CANDIDATES) return scoped;
+  const expanded = searchEvidenceCandidates(vaultBase, query, {
+    candidateLimit: EVIDENCE_SEARCH_MAX_CANDIDATES,
+  });
+  scoped = scopedRows(expanded.rows, activeContext, registry);
+  return scoped;
+}
+
 export function buildPromptEvidenceContext(vaultBase, prompt, {
   topK = 3, maxBytes = 3072, rows = null, activeContext = null, registry = null,
 } = {}) {
   const query = sanitizeMemoryText(String(prompt || '')).trim();
   if (!query || isBootstrapPrompt(query)) return '';
-  const evidence = rows || loadEvidenceIndex(vaultBase);
-  const scoped = scopeEvidenceRows(evidence, {
-    activeContext,
-    registry: registry || readSessionRegistry(vaultBase),
-  });
+  const effectiveRegistry = registry || readSessionRegistry(vaultBase);
+  let scoped;
+  if (rows) {
+    scoped = scopedRows(rows, activeContext, effectiveRegistry);
+  } else {
+    try {
+      scoped = indexedScopedEvidence(vaultBase, query, topK, activeContext, effectiveRegistry);
+    } catch {
+      scoped = scopedRows(loadEvidenceIndex(vaultBase), activeContext, effectiveRegistry);
+    }
+  }
   if (!scoped.length) return '';
   return sanitizeMemoryText(renderEvidenceContext(
     recallEvidence(scoped, query, { topK }),
@@ -53,4 +87,4 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
   } catch {
     writeHookOutput({});
   }
-}
+}

package/hooks/evidence-recall.mjs

@@ -1 +1,11 @@
 export * from '../packages/vault/src/evidence-recall.mjs';
+export * from '../packages/vault/src/evidence-recall-page.mjs';
+export * from '../packages/vault/src/evidence-search-index.mjs';
+export {
+  EVIDENCE_INDEX_STATE_FILE,
+  EVIDENCE_INDEX_STATE_VERSION,
+  buildIncrementalEvidenceIndex,
+  buildIncrementalEvidenceIndex as buildEvidenceIndex,
+  loadEvidenceIndexState,
+  refreshEvidenceIndex,
+} from '../packages/vault/src/evidence-index-store.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.85.1",
+  "version": "0.87.0",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -9,6 +9,7 @@
   "exports": {
     "./harness": "./packages/harness/src/index.mjs",
     "./vault": "./packages/vault/src/index.mjs",
+    "./commit": "./packages/commit/src/index.mjs",
     "./hooks/*": "./hooks/*",
     "./src/*": "./src/*",
     "./bin/*": "./bin/*",
@@ -28,8 +29,10 @@
     "bin",
     "src",
     "hooks",
+    ".githooks",
     "packages",
     "schema",
+    "scripts/validate-commit-range.mjs",
     "web/observer",
     "docs/pt-BR/commands/*.md",
     "docs/en/commands/*.md",
@@ -42,7 +45,7 @@
   },
   "scripts": {
     "precheck": "node --check src/capabilities.mjs && node --check src/host-capabilities.mjs && node --check src/task-contracts.mjs && node --check src/task-leases.mjs && node --check src/task.mjs && node --check src/change.mjs && node --check src/archive-operation-lock.mjs && node --check src/worktree.mjs && node --check src/worktree-cleanup.mjs && node --check src/provenance-gate.mjs && node --check src/provenance-sources.mjs && node --check src/receipt-ledger.mjs && node --check src/evidence-envelope.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check hooks/session-stop.mjs && node --check packages/vault/src/worktree-metadata.mjs && node --check packages/vault/src/evidence-envelope.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/integrations/src/capabilities.mjs && node --check packages/pi/src/index.mjs && node --check src/sync-protocol.mjs && node --check src/sync-outbox.mjs && node --check src/sync-adapters.mjs && node --check src/sync-protocol-cli.mjs && node --check packages/mcp/src/sync.mjs && node --check src/portable.mjs && node --check src/tdd.mjs && node --check src/tdd-attestation.mjs && node --check src/tdd-attestation-store.mjs",
-    "check": "node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check scripts/release-provenance.mjs && node --check scripts/run-scope.mjs && node --check src/release-provenance.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/mcp.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/active-context-health.mjs && node --check src/project-vault.mjs && node --check src/observer-auth.mjs && node --check src/observer-privacy.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-memory.mjs && node --check src/observer-memory-publish.mjs && node --check src/observer-sql-store.mjs && node --check src/observer-sql-migrate.mjs && node --check src/observer-sql-publish.mjs && node --check src/observer-transcript-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check src/work-kind.mjs && node --check src/delivery.mjs && node --check web/observer/app.mjs && node --check hooks/observer-publish.mjs && node --check hooks/evidence-context.mjs && node --check hooks/active-context-handoff-evidence.mjs && node --check hooks/evidence-recall.mjs && node --check hooks/memory-scope.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/audit.mjs && node --check packages/mcp/src/cli.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/effects.mjs && node --check packages/mcp/src/executor.mjs && node --check packages/mcp/src/server.mjs && node --check packages/mcp/src/stdio.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-scope.mjs && node --check packages/vault/src/memory-candidate-policy.mjs && node --check packages/vault/src/evidence-recall.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
+    "check": "node --check scripts/validate-commit-range.mjs && node --check packages/commit/src/index.mjs && node --check packages/commit/src/cli.mjs && node --check packages/commit/src/git-runtime.mjs && node --check src/git-commit-hooks.mjs && node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check scripts/release-provenance.mjs && node --check scripts/run-scope.mjs && node --check src/release-provenance.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/mcp.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/active-context-health.mjs && node --check src/project-vault.mjs && node --check src/observer-auth.mjs && node --check src/observer-privacy.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-memory.mjs && node --check src/observer-memory-publish.mjs && node --check src/observer-sql-store.mjs && node --check src/observer-sql-migrate.mjs && node --check src/observer-sql-publish.mjs && node --check src/observer-transcript-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check src/work-kind.mjs && node --check src/delivery.mjs && node --check web/observer/app.mjs && node --check hooks/observer-publish.mjs && node --check hooks/evidence-context.mjs && node --check hooks/active-context-handoff-evidence.mjs && node --check hooks/evidence-recall.mjs && node --check hooks/memory-scope.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/audit.mjs && node --check packages/mcp/src/cli.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/effects.mjs && node --check packages/mcp/src/executor.mjs && node --check packages/mcp/src/server.mjs && node --check packages/mcp/src/stdio.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-scope.mjs && node --check packages/vault/src/memory-candidate-policy.mjs && node --check packages/vault/src/evidence-recall.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
     "test": "node --test --test-concurrency=2",
     "test:core": "node scripts/run-scope.mjs core",
     "release": "node scripts/release.mjs",