Enhance retrieval policy and documentation

- Updated the `.gitignore` to include `.pytest_cache/`.
- Improved the `README.md` to clarify the strict local mode of the ACL, detailing the hard stop mechanisms and retrieval policies.
- Modified `api/routes.py` to include the decision in the streaming response.
- Enhanced `documentation.md` to explain the retrieval decision process and hard stop scenarios.
- Updated `core/config.py` to add retrieval thresholds for better configuration management.
- Refactored `engine/chat_provider.py` and `engine/context.py` to implement hard stop logic and improve context management.
- Revised `engine/search.py` to separate retrieval logic and maintain backward compatibility with the old search API.
- Added new evaluation questions and answers to `evaluation/questions_answers.json` for testing retrieval scenarios.

Author: GaabDevWeb

.gitignore

@@ -1,5 +1,7 @@
 .env
 
+.pytest_cache/
+
 **/__pycache__/
 *.py[cod]
 *$py.class

README.md

@@ -2,6 +2,8 @@
 
 Agente de contexto local com RAG (BM25) sobre **MySQL**, interface em `templates/` e respostas em streaming via OpenRouter.
 
+**Modo local estrito (padrão):** desde a mitigação descrita em `.cursor/plans/rag_acl_incremental_6951b55f.plan.md`, o ACL opera por padrão em modo `strict`. A geração só acontece quando a decisão de retrieval permitir; pergunta sem base não chama LLM, `/content` não injeta mais `scope_chunks[:5]` e respostas que passam pelos gates mas falham no sanity check pós-geração são substituídas por hard stop `post_generation_misalignment`. A regra central é: na dúvida, não responder.
+
 ## Requisitos
 
 - Python 3.10+
@@ -85,10 +87,58 @@ O projeto usa `logging` da biblioteca padrão com loggers prefixados `kernelbots
 ## Comandos no chat
 
 - `/reload` — reconstrói o índice BM25 a partir do MySQL.
-- `/content …` — força uso da base local (com fallback para os primeiros chunks se não houver hit BM25).
-- `/doc …` — injeta o conteúdo da documentação quando disponível no índice.
+- `/content …` — busca global explícita; **sem fallback** de primeiros chunks. Se não houver hit forte o bastante, retorna hard stop com reformulação guiada.
+- `/doc …` — injeta o conteúdo da documentação quando disponível no índice; fluxo determinístico (não passa pela política de decisão).
 - `/python …`, `/visualizacao-sql …`, `/projeto-bloco …`, `/planejamento-curso-carreira …` — filtra por disciplina.
 
+## Política de retrieval e hard stop
+
+A camada `engine/retrieval.py` separa recuperação lexical bruta (`SearchEngine.search_candidates`) da decisão de suficiência (`build_decision`). A decisão devolve `RetrievalDecision` com `allow_generation`, `reason`, `confidence` e `trace` estruturado, exposto no SSE como `[ACL_META]`.
+
+Hard stops possíveis:
+
+| `reason` | Quando dispara |
+|---|---|
+| `insufficient_context` | Sem hits ou `top_score < MIN_SCORE` |
+| `underspecified_query` | Menos que `MIN_TERMS` termos informativos (strict) |
+| `vague_but_high_risk` | Termo vago (`performance`, `erro`, `timeout`) sem domínio específico |
+| `ambiguous_retrieval` | `top_score - second_score < MIN_SCORE_MARGIN` |
+| `context_misaligned` | `coverage < MIN_COVERAGE` no melhor chunk |
+| `low_confidence` | Coverage ponderada baixa ou termo central ausente no modo strict |
+| `post_generation_misalignment` | Sanity check pós-geração detectou resposta fora dos chunks |
+| `provider_error` | Todos os modelos OpenRouter falharam |
+
+Thresholds configuráveis via `.env` (ver `core/config.py`):
+
+| Variável | Default | Efeito |
+|---|---|---|
+| `ACL_RETRIEVAL_MIN_SCORE` | 1.5 | Hard stop se `top_score` bruto for menor |
+| `ACL_RETRIEVAL_MIN_SCORE_MARGIN` | 0.15 | Margem mínima entre top1 e top2 |
+| `ACL_RETRIEVAL_MIN_COVERAGE` | 0.34 | Overlap mínimo de termos informativos |
+| `ACL_RETRIEVAL_MIN_COVERAGE_WEIGHTED` | 0.34 | Idem, com centrais valendo 2x |
+| `ACL_RETRIEVAL_MIN_TERMS` | 2 | Termos informativos mínimos em `strict` |
+| `ACL_RETRIEVAL_CANDIDATE_K` | 8 | Quantos candidatos o retrieval devolve |
+| `ACL_RETRIEVAL_TOP_K` | 4 | Quantos vão para o prompt |
+| `ACL_RETRIEVAL_MAX_CHUNKS_PER_SOURCE` | 2 | Diversidade de fonte |
+
+## Calibração e avaliação
+
+A pasta `evaluation/` contém a ferramenta que gera o artefato exigido pelo plano incremental:
+
+```bash
+python -m evaluation.calibration_runner --questions evaluation/all.md --out evaluation/calibration_traces.jsonl --limit 20
+python -m evaluation.calibration_summary --traces evaluation/calibration_traces.jsonl
+```
+
+O runner produz um JSONL com trace completo por query (scores, coverage, termos, fontes, decisão) e um placeholder `manual_label` para revisão humana. O summary imprime percentis de scores e as taxas `Stop vs Answer`, `Ambiguous Retrieval`, `Underspecified Query`, `Vague But High Risk`.
+
+## Limitações conhecidas
+
+- **BM25-only é mitigação temporária.** O módulo `engine/retrieval.py` deixa explícito (`retrieval_mode = "bm25_lexical_temporary"`). A evolução correta é busca híbrida (BM25 + embeddings + reranking), fora do escopo inicial.
+- **Coverage lexical** aproxima alinhamento semântico, não resolve. Por isso a Fase 3 adiciona sanity check pós-geração como último firewall.
+- **Calibração manual de 20 casos é bootstrap**, não prova final. A evolução prevista é 100–200 casos semi-automatizados.
+- **Modo `assistive`** existe como flag, mas não é ativado por padrão. A mitigação estabiliza o modo `strict` primeiro.
+
 ## Fluxo de dados
 
 ```

api/routes.py

@@ -105,7 +105,11 @@ async def _reload_stream() -> AsyncGenerator[str, None]:
     )
 
     return StreamingResponse(
-        services.chat_provider.stream_response(built.messages, trace=built.trace),
+        services.chat_provider.stream_response(
+            built.messages,
+            trace=built.trace,
+            decision=built.decision,
+        ),
         media_type="text/event-stream",
         headers={
             "Cache-Control": "no-cache",