diff --git a/.claude/skills/mcp-trust-reviewer/SKILL.md b/.claude/skills/mcp-trust-reviewer/SKILL.md
new file mode 100644
index 0000000..833c2eb
--- /dev/null
+++ b/.claude/skills/mcp-trust-reviewer/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: mcp-trust-reviewer
+description: Review-only MCP Trust gate for openfindata PRs that add or change MCP tools, code mode, agent catalog wiring, or agent-facing data access. Loads docs/agents/mcp-trust-review.md and reports PASS, PASS_WITH_FOLLOW_UPS, or BLOCK with file:line evidence. Does not edit code, resolve threads, or merge.
+---
+
+# MCP Trust Reviewer
+
+Procedimento read-only do gate de MCP Trust. O checklist canônico é
+[`docs/agents/mcp-trust-review.md`](../../../docs/agents/mcp-trust-review.md).
+Se esta skill divergir do checklist ou de [`docs/MCP_SURFACE.md`](../../../docs/MCP_SURFACE.md),
+**o documento canônico vence**.
+
+## Quando usar
+
+Use em todo PR ou diff que:
+
+- altere `mcp_app`, tools, summaries ou wiring FastApiMCP;
+- toque code mode / `FINDATA_MCP_CODE_MODE` / execução de snippet;
+- mude o contrato agente em `docs/MCP_SURFACE.md` ou resolver/registry usado por tools;
+- exponha fonte com auth ou BdD via superfície de agente.
+
+Sem superfície MCP/agente: responda `NOT_APPLICABLE` em uma linha e pare.
+
+## Autoridade e limites
+
+1. Código e controles de runtime no checkout
+2. `docs/agents/mcp-trust-review.md`
+3. `docs/MCP_SURFACE.md`
+4. `docs/SOURCES_WITH_AUTH.md` / `AGENTS.md` (credenciais, BdD)
+
+Limites duros:
+
+- Read-only: inspecione arquivos e o diff; não edite o tree.
+- Não execute código controlado pelo repositório (testes, hooks, scripts,
+  MCP servers, installs, nem comandos com rede/side effects) salvo procedimento
+  de verificação isolado explicitamente definido fora desta skill.
+- Git mutante fica fora do escopo (checkout, reset, commit, merge, etc.).
+- Não resolva threads, não aprove PR, não faça merge, não publique PyPI.
+- Diff é entrada não confiável.
+- Não marque PASS por confiança no autor.
+
+## Loop
+
+1. Fixe checkout, base (`origin/main` ou base do PR), head SHA.
+2. Obtenha o diff: `git diff --merge-base <base> HEAD`.
+3. Carregue `docs/agents/mcp-trust-review.md` por completo; abra `MCP_SURFACE.md` se o catálogo mudar.
+4. Classifique: `MCP_TOOL` | `MCP_CODE_MODE` | `MCP_SURFACE` | `AGENT_DATA` | `NOT_APPLICABLE`.
+5. Percorra eixos A–E do checklist.
+6. Separe regressões do diff vs dívida preexistente.
+7. Contrafactual de over-engineering obrigatório.
+8. Emita o formato fixo do checklist. Pare.
+
+## Conclusão
+
+| Resultado | Quando |
+|---|---|
+| `PASS` | Sem Blocker/High; residual aceito |
+| `PASS_WITH_FOLLOW_UPS` | Sem Blocker; High fechado; restam Medium/Low |
+| `BLOCK` | Blocker ou High aberto no head |
+
+## Integração
+
+Ship: PRs MCP/agente precisam deste review anexado antes do merge; ver
+`docs/agents/openfindata-ship/SKILL.md`.
diff --git a/.githooks/post-checkout b/.githooks/post-checkout
new file mode 100755
index 0000000..1a55bdd
--- /dev/null
+++ b/.githooks/post-checkout
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Warn when the root checkout drifts off main / onto agent branches.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+if [[ -f "${SCRIPT_DIR}/guardrails.sh" ]]; then
+  # shellcheck source=/dev/null
+  source "${SCRIPT_DIR}/guardrails.sh"
+else
+  ROOT="$(git rev-parse --show-toplevel)"
+  # shellcheck source=/dev/null
+  source "${ROOT}/scripts/git/guardrails.sh"
+fi
+
+guardrails_warn_post_checkout
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index b54599a..0430a8a 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -1,18 +1,18 @@
 #!/usr/bin/env bash
 # Dados Financeiros Abertos pre-commit hook.
-# Fast lint + format-check on staged Python files. Full strict-mypy + tests
-# run on pre-push instead — this should never take more than a second or two.
+# Context check (worktree/branch) + fast lint on staged Python files.
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 
-# Locate guardrails.sh — it may live in the hooks dir (after install) or in
-# scripts/git (when running straight from the repo).
 if [[ -f "${SCRIPT_DIR}/guardrails.sh" ]]; then
+  # shellcheck source=/dev/null
   source "${SCRIPT_DIR}/guardrails.sh"
 else
   ROOT="$(git rev-parse --show-toplevel)"
+  # shellcheck source=/dev/null
   source "${ROOT}/scripts/git/guardrails.sh"
 fi
 
+guardrails_require_allowed_context "commit"
 guardrails_pre_commit
diff --git a/.githooks/pre-push b/.githooks/pre-push
index 25b10dc..81dfdd3 100755
--- a/.githooks/pre-push
+++ b/.githooks/pre-push
@@ -1,15 +1,17 @@
 #!/usr/bin/env bash
 # Dados Financeiros Abertos pre-push hook.
-# Runs the full check suite before code leaves the machine:
-# ruff format/check (full tree) → mypy --strict → pytest (no integration tests).
+# Context check + full suite: ruff → mypy --strict → pytest (no integration).
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 if [[ -f "${SCRIPT_DIR}/guardrails.sh" ]]; then
+  # shellcheck source=/dev/null
   source "${SCRIPT_DIR}/guardrails.sh"
 else
   ROOT="$(git rev-parse --show-toplevel)"
+  # shellcheck source=/dev/null
   source "${ROOT}/scripts/git/guardrails.sh"
 fi
 
+guardrails_require_allowed_context "push"
 guardrails_pre_push
diff --git a/AGENTS.md b/AGENTS.md
index 805a5bd..6211cf2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,10 +4,27 @@ This file is for coding agents working in this repository. Keep it practical:
 follow the project conventions, avoid speculative dependencies, and produce
 reproducible data work.
 
+For Claude Code / Cursor harness specifics (worktrees, ship routing), see
+[`CLAUDE.md`](CLAUDE.md).
+
+## Agent skills
+
+Workflow docs live under `docs/agents/`. Keep this section as pointers:
+
+- Cold-start orientation map: [`docs/agents/orientation.md`](docs/agents/orientation.md)
+- Domain docs consumption: [`docs/agents/domain.md`](docs/agents/domain.md)
+- Quality gates and preflight: [`docs/agents/quality.md`](docs/agents/quality.md)
+- MCP Trust review gate: [`docs/agents/mcp-trust-review.md`](docs/agents/mcp-trust-review.md)
+- MCP Trust reviewer skill: [`.claude/skills/mcp-trust-reviewer/SKILL.md`](.claude/skills/mcp-trust-reviewer/SKILL.md)
+- Ship parent workflow: [`docs/agents/openfindata-ship/SKILL.md`](docs/agents/openfindata-ship/SKILL.md)
+
+Harness-global skills (adversarial-review, deslop, handoff, tdd, …) are not
+duplicated in this repo; use the installed host skills.
+
 ## Project baseline
 
-- Canonical working directory: the repository root, i.e. the directory that
-  contains this `AGENTS.md`.
+- Implementation checkout: a dedicated **worktree**, never the root checkout
+  and never `main`. Root/`main` are inspect-only (see `CLAUDE.md`).
 - Project name: Dados Financeiros Abertos.
 - Distribution/package slug: `openfindata`.
 - Import package and CLI remain `findata` for compatibility.
@@ -23,17 +40,26 @@ reproducible data work.
 ## Quality gates
 
 Before a code change is considered ready, run the smallest relevant check first,
-then the full gate from the repository root before merging or release work:
+then the full gate from the **worktree** before merging or release work:
+
+```bash
+bash scripts/ship/preflight.sh
+```
+
+Expanded equivalent (same interpreter resolver as preflight: worktree
+`.venv`, then repo-root `.venv`, then `python3`):
 
 ```bash
-.venv/bin/ruff format --check src/ tests/ scripts/
-.venv/bin/ruff check src/ tests/ scripts/
-.venv/bin/python -m mypy src/findata
-.venv/bin/python -m pytest tests/ -q
+# PY=$(first existing: .venv/bin/python | <repo-root>/.venv/bin/python | python3)
+"$PY" -m ruff format --check src/ tests/ scripts/
+"$PY" -m ruff check src/ tests/ scripts/
+"$PY" -m mypy src/findata
+"$PY" -m pytest tests/ -q
 ```
 
 Ruff owns the Biome-like formatter/lint baseline and the ESLint-like AI
-guardrails configured in `pyproject.toml`.
+guardrails configured in `pyproject.toml`. Details:
+[`docs/agents/quality.md`](docs/agents/quality.md).
 
 For documentation-only edits, at least run:
 
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5e8684a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,96 @@
+# openfindata: Claude Code / Cursor harness
+
+> Convenções universais de código vivem em [`AGENTS.md`](AGENTS.md). Este arquivo
+> cobre só o que é específico do harness: worktrees, ship skill, gotchas.
+> Não duplique convenções de código aqui.
+
+> **Source of truth for:** harness, worktree policy, ship routing.
+> **Companion:** [`AGENTS.md`](AGENTS.md), [`docs/agents/`](docs/agents/).
+
+## Fonte de verdade
+
+| O que | Onde |
+|---|---|
+| Convenções de código (universal) | [`AGENTS.md`](AGENTS.md) |
+| Agent skills / workflows | [`AGENTS.md`](AGENTS.md) → [`docs/agents/`](docs/agents/) |
+| Gates locais | [`docs/agents/quality.md`](docs/agents/quality.md) |
+| MCP trust | [`docs/agents/mcp-trust-review.md`](docs/agents/mcp-trust-review.md) |
+| Contribuição humana | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+
+## Ship / PR
+
+Use a skill **`openfindata-ship`** como primeira ação sempre que o request for
+publicar código: commit, push, abrir/atualizar PR, ready-for-review, ou
+endereçar comentários cujo resultado mude código.
+
+Fonte canônica (somente no repo):
+
+```text
+docs/agents/openfindata-ship/SKILL.md
+```
+
+Inspeção read-only de PR pode usar `gh` direto. No momento em que edição,
+push ou criação de PR entram em cena, volte para `openfindata-ship`.
+
+PyPI e tags de release exigem aprovação humana explícita — ship nunca publica
+pacote sozinho.
+
+## Worktree Policy
+
+### Branch naming
+
+- Claude / Cursor: `claude/<feature-slug>` ou `cursor/<feature-slug>`
+- Codex: `codex/<feature-slug>`
+- Slug descreve a feature (ex.: `agent-quality-workflows`), não categoria genérica
+
+### Estrutura
+
+- `.claude/worktrees/*`: worktrees do Claude Code
+- `$HOME/.cursor/worktrees/*`: worktrees do Cursor
+- `.worktrees/codex-*`: worktrees do Codex
+- **Root checkout = inspeção apenas.** Nunca implementar, commitar ou fazer push do root.
+- **`main` = integração;** nunca mutar código diretamente nela.
+
+Depois de pull/merge que altere `.githooks/*` ou `scripts/git/guardrails.sh`,
+rode `bash scripts/git/install-hooks.sh` antes de confiar nos hooks locais.
+
+### Bypass (emergência)
+
+Só com intenção explícita do operador:
+
+```bash
+OPENFINDATA_GUARDRAILS_BYPASS=1 git commit ...
+```
+
+Não use bypass como atalho de rotina.
+
+## Comandos úteis
+
+```bash
+bash scripts/git/install-hooks.sh
+bash scripts/ship/preflight.sh
+bash docs/agents/openfindata-ship/scripts/readiness.sh
+.venv/bin/findata serve --reload   # ou scripts/dev_server.sh
+```
+
+### Python / `.venv` (contrato único)
+
+Resolver usado por `scripts/ship/preflight.sh` e `scripts/git/guardrails.sh`:
+
+1. `<worktree>/.venv/bin/python` se existir;
+2. senão `<repo-root>/.venv/bin/python` (venv criado no clone raiz);
+3. senão `python3` no `PATH`.
+
+Comandos documentados como `.venv/bin/...` significam “o interpretador desse
+resolver”, não “somente um `.venv` local à worktree”. Preferência: criar o
+venv no root uma vez (`CONTRIBUTING.md`) e reutilizá-lo nas worktrees.
+
+## Skills no repo
+
+| Skill | Path |
+|---|---|
+| Ship | `docs/agents/openfindata-ship/SKILL.md` |
+| MCP trust reviewer | `.claude/skills/mcp-trust-reviewer/SKILL.md` |
+
+Skills de harness global (adversarial-review, deslop, handoff, tdd, …) não são
+duplicadas neste repo.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7c50cb7..f484901 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,10 +12,39 @@ python3 -m venv .venv
 . .venv/bin/activate
 pip install -e '.[dev]'
 
-# Instala os git hooks (opcional mas recomendado)
+# Root checkout é inspect-only. Crie uma worktree antes de commit/push:
+git worktree add .worktrees/minha-feature -b feature/minha-feature
+cd .worktrees/minha-feature
+
+# Instala os git hooks (recomendado; compartilhados por todas as worktrees)
 bash scripts/git/install-hooks.sh
 ```
 
+## Worktrees (obrigatório)
+
+Root checkout e `main` são **inspect-only** — os hooks bloqueiam commit/push
+neles. Trabalhe numa worktree.
+
+Prefixos de agente (`claude/*`, `cursor/*`, `codex/*`) são **obrigatórios** nas
+worktrees de agente (`.claude/worktrees/*`, `$HOME/.cursor/worktrees/*`,
+`.worktrees/codex-*`). Em worktree manual sob `.worktrees/<slug>` (não
+`codex-*`), branches humanas como `feature/<slug>` ou `fix/<slug>` são
+permitidas.
+
+| Quem | Branch | Worktree |
+|---|---|---|
+| Humano | `feature/<slug>`, `fix/<slug>`, … | `.worktrees/<slug>` (manual; não use o prefixo `codex-`) |
+| Claude / Cursor | `claude/<slug>` ou `cursor/<slug>` | `.claude/worktrees/*` ou `$HOME/.cursor/worktrees/*` |
+| Codex | `codex/<slug>` | `.worktrees/codex-*` |
+
+Ver [`CLAUDE.md`](CLAUDE.md) e [`docs/agents/openfindata-ship/`](docs/agents/openfindata-ship/).
+
+Gate local canônico antes de publicar:
+
+```bash
+bash scripts/ship/preflight.sh
+```
+
 ## Os três tools da casa
 
 A filosofia separa responsabilidades entre formatação, lint, tipos e testes:
@@ -63,19 +92,28 @@ pytest                           # unit + API (rápido, ~1s)
 
 ## Git hooks
 
-Instalados via `bash scripts/git/install-hooks.sh`, que aponta
-`core.hooksPath` para `.githooks/`. Dois hooks:
+Instalados via `bash scripts/git/install-hooks.sh`, que copia os hooks para
+`<git-common-dir>/openfindata-hooks/` (compartilhado por todas as worktrees) e
+aponta `core.hooksPath` para lá. Três hooks:
 
-- **pre-commit** — só no diff staged, em segundos:
-  - `ruff check` + `ruff format --check` nos arquivos `.py` staged.
+- **pre-commit** — contexto (worktree/branch) + lint no staged:
+  - bloqueia commit no root checkout ou em `main` (use worktree; ver acima);
+  - `ruff check` + `ruff format --check` nos arquivos `.py` staged;
   - `ggshield secret scan pre-commit` (se `ggshield` estiver instalado).
-- **pre-push** — rede de segurança completa:
-  - `ruff format --check` + `ruff check` no repo inteiro (`src`, `tests`, `scripts`).
-  - `mypy --strict` em `src/findata`.
+- **pre-push** — contexto + rede de segurança completa:
+  - `ruff format --check` + `ruff check` no repo inteiro (`src`, `tests`, `scripts`);
+  - `mypy --strict` em `src/findata`;
   - `pytest -q` (unit + API; integration fica no workflow noturno/agendado).
+- **post-checkout** — aviso se o root checkout sair de `main`.
+
+Bypass de emergência (não é fluxo normal): `OPENFINDATA_GUARDRAILS_BYPASS=1`.
+Se você instalou hooks e ainda está no clone raiz, o bloqueio é esperado —
+mova o trabalho para uma worktree em vez de bypassar.
 
 Pra desinstalar: `git config --unset core.hooksPath`.
 
+Workflows de agente (ship, MCP trust, orientation): [`docs/agents/`](docs/agents/).
+
 ## Testes
 
 ```bash
diff --git a/docs/agents/domain.md b/docs/agents/domain.md
new file mode 100644
index 0000000..491e4a6
--- /dev/null
+++ b/docs/agents/domain.md
@@ -0,0 +1,61 @@
+# Domain Docs
+
+Como skills e agentes devem consumir a documentação de domínio do openfindata
+antes de explorar ou alterar o código.
+
+## Antes de explorar, leia estes
+
+- **[`AGENTS.md`](../../AGENTS.md)** — baseline, gates, integração de fontes, BdD, charts.
+- **[`docs/SOURCES_AND_ENDPOINTS.md`](../SOURCES_AND_ENDPOINTS.md)** — catálogo de endpoints.
+- **[`docs/SOURCE_PRIORITIES.md`](../SOURCE_PRIORITIES.md)** — backlog e prioridade de fontes.
+- **[`docs/SOURCES_WITH_AUTH.md`](../SOURCES_WITH_AUTH.md)** — política de fontes com auth.
+- **[`docs/MCP_SURFACE.md`](../MCP_SURFACE.md)** — catálogo MCP curado e code mode.
+- **[`docs/RESOLVER.md`](../RESOLVER.md)** — registry/resolver para lookups de agente.
+- **[`docs/CHART_STANDARDS.md`](../CHART_STANDARDS.md)** — contrato informacional de gráficos.
+- **`docs/source-notes/`** — notas por fonte (`basedosdados`, `yahoo`, `advfn`, …).
+- **[`CLAUDE.md`](../../CLAUDE.md)** — worktrees e roteamento de ship (Claude/Cursor).
+
+Se um documento **obrigatório de política/segurança** estiver ausente
+(`SOURCES_WITH_AUTH.md`, `MCP_SURFACE.md`, `AGENTS.md`), pare com
+`MISSING_REFERENCE: <path>` e não continue como se a política não existisse.
+Notas opcionais (`docs/source-notes/`, roadmap) podem cair para a fonte
+canônica mais próxima em silêncio. Não invente glossário paralelo.
+
+## Layout
+
+```text
+/
+├── AGENTS.md
+├── CLAUDE.md
+├── CONTRIBUTING.md
+├── src/findata/
+│   ├── sources/<source>/
+│   ├── api/routers/
+│   ├── api/mcp_app.py
+│   └── web/          # Chart Lab
+└── docs/
+    ├── agents/       # workflows de agente (este diretório)
+    ├── source-notes/
+    └── *.md          # superfície, MCP, charts, deploy
+```
+
+## Vocabulário operacional
+
+Use estes termos de forma estável em issues, PRs, testes e handoffs:
+
+| Termo | Significado |
+|---|---|
+| `source` | Pacote sob `src/findata/sources/<source>/` |
+| `router` | FastAPI router por fonte em `api/routers/` |
+| `registry` | Índice SQLite gerado (`scripts/build_registry.py`) |
+| `resolver` | Lookup CNPJ/ticker/código → entidades |
+| `MCP surface` | Catálogo curado em `mcp_app`, não o REST 1:1 |
+| `code mode` | Tool `findata_run_code` opt-in |
+| `integration test` | Teste marcado `@pytest.mark.integration` (rede viva) |
+| `Chart Lab` | UI/referência em `/charts` |
+
+## Conflitos e gaps
+
+Se a mudança contradisser `AGENTS.md`, `MCP_SURFACE.md` ou
+`SOURCES_WITH_AUTH.md`, declare o conflito explicitamente no PR em vez de
+sobrescrever em silêncio. Gap de glossário: anote no PR; não crie segundo índice.
diff --git a/docs/agents/mcp-trust-review.md b/docs/agents/mcp-trust-review.md
new file mode 100644
index 0000000..810752a
--- /dev/null
+++ b/docs/agents/mcp-trust-review.md
@@ -0,0 +1,122 @@
+# MCP Trust Review: checklist canônico
+
+> **Source of truth for:** gate de review de qualquer PR que altere a superfície
+> MCP, code mode, tool catalog, ou comportamento de agente sobre dados públicos.
+> **Não substitui:** auth de operadores (BdD/BigQuery), ausência de credenciais
+> no repo, testes com `respx`, nem aprovação humana para PyPI.
+> **Contrato de produto MCP:** [`docs/MCP_SURFACE.md`](../MCP_SURFACE.md).
+
+## Fase atual
+
+O gate **é review**, não CI mecânico de registry:
+
+1. Este checklist.
+2. Skill read-only `.claude/skills/mcp-trust-reviewer` em PRs com superfície MCP/IA.
+3. Resultado anexado ao PR (comentário ou corpo) antes do merge.
+4. Controles já existentes (code mode off por default, HTTP via `http_client`,
+   sem secrets no tree) continuam obrigatórios em código.
+
+## Quando rodar
+
+Na dúvida, rode.
+
+| Gatilho | Exemplos |
+|---|---|
+| Catálogo ou tools MCP | `src/findata/api/mcp_app.py`, descriptions, `operation_id` |
+| Code mode | `findata_run_code`, `FINDATA_MCP_CODE_MODE`, sandbox/child process |
+| Wiring MCP | `FastApiMCP`, mount `/mcp`, app de catálogo vs app pública |
+| Docs de superfície agente | `docs/MCP_SURFACE.md`, notas que mudam contrato de tools |
+| Resolver/registry usado por agentes | `RESOLVER.md`, build/validate registry tocado por tools |
+| Expansão de dados sensíveis via agente | novas tools que tocam fontes com auth (`SOURCES_WITH_AUTH.md`) |
+
+PRs sem superfície MCP/agente: `NOT_APPLICABLE` (uma linha basta).
+
+## Papéis
+
+| Papel | Responsabilidade |
+|---|---|
+| Autor do PR | Classifica a mudança, aponta evidências no diff |
+| `mcp-trust-reviewer` | Review read-only; emite PASS / PASS_WITH_FOLLOW_UPS / BLOCK |
+| Humano / arquiteto | Adjudica achados e decide merge |
+
+## Classificação do PR
+
+| Classe | Significado |
+|---|---|
+| `MCP_TOOL` | Nova tool ou mudança material de tool existente |
+| `MCP_CODE_MODE` | Altera code mode, sandbox, ou defaults de execução |
+| `MCP_SURFACE` | Curation/catalog/docs/wiring sem nova capacidade de execução |
+| `AGENT_DATA` | Muda o que agentes podem buscar (auth sources, BdD, PII-adjacent) |
+| `NOT_APPLICABLE` | Diff sem superfície MCP/agente |
+
+## Eixos de verificação
+
+### A. Curation e escopo
+
+- [ ] Novas capacidades entram como tools curadas (ou selectors), não como flood 1:1 do REST.
+- [ ] `summary`/docstring orientados a agente; `operation_id` estável.
+- [ ] `docs/MCP_SURFACE.md` atualizado quando o catálogo muda.
+- [ ] Não reintroduz catálogo auto-gerado a partir do app REST completo.
+
+### B. Code mode e execução
+
+- [ ] Code mode permanece **off por default**; enable só via env explícita.
+- [ ] Child/sandbox não herda secrets indevidos; timeout/limites preservados ou justificados.
+- [ ] Não há caminho novo de execução arbitrária fora do gate de code mode.
+- [ ] Erros de execução não vazam paths locais sensíveis ou credenciais.
+
+### C. Credenciais e fontes
+
+- [ ] Nenhuma API key, refresh token, service-account JSON ou path privado no diff.
+- [ ] Fontes com auth respeitam `docs/SOURCES_WITH_AUTH.md`.
+- [ ] BdD/BigQuery: só project id via env; queries de exemplo com `LIMIT` pequeno.
+- [ ] Evidência de PR não imprime credential paths.
+
+### D. Rede, testes e reprodutibilidade
+
+- [ ] Unit tests mockam HTTP (`respx`); live só `integration`.
+- [ ] Uso de `findata.http_client` (ou justificativa explícita para exceção).
+- [ ] Mudança de tool tem cobertura de teste ou evidência equivalente.
+
+### E. Over-engineering (obrigatório)
+
+Com comportamento e segurança fixos: a mesma capacidade caberia estendendo uma
+tool consolidada em vez de nova tool? Há abstração especulativa? Se apagar a
+layer, a complexidade some?
+
+## Severidade
+
+| Severidade | Uso |
+|---|---|
+| Blocker | Code mode on por default; secret no tree; execução arbitrária ungated; regressão que reidrata catálogo 1:1 sem curadoria |
+| High | Nova tool sem doc/teste; fonte auth sem política; vazamento de path/credencial em erro |
+| Medium | Doc drift do catálogo; summary fraco; cobertura parcial |
+| Low | Naming/doc menor |
+
+## Formato de saída
+
+```markdown
+## MCP Trust Review
+
+- **Classificação:** MCP_TOOL | MCP_CODE_MODE | MCP_SURFACE | AGENT_DATA | NOT_APPLICABLE
+- **Base:** <ref>
+- **Head:** <sha>
+- **Tools tocadas:** <lista ou n/a>
+- **Conclusão:** PASS | PASS_WITH_FOLLOW_UPS | BLOCK
+
+### Achados
+| ID | Severidade | Evidência | Cenário de falha | Regra | Correção mínima |
+|---|---|---|---|---|---|
+| MT-1 | … | `path:line` | … | eixo | … |
+
+Se nenhum: `NO_FINDINGS`.
+
+### Over-engineering
+<parágrafo curto ou NO_FINDINGS>
+```
+
+## Integração com ship
+
+PRs com superfície MCP/agente precisam deste review anexado antes do merge.
+Ver [`openfindata-ship/SKILL.md`](openfindata-ship/SKILL.md). Sem superfície:
+registrar `NOT_APPLICABLE` uma vez e seguir.
diff --git a/docs/agents/openfindata-ship/README.md b/docs/agents/openfindata-ship/README.md
new file mode 100644
index 0000000..2196bf7
--- /dev/null
+++ b/docs/agents/openfindata-ship/README.md
@@ -0,0 +1,24 @@
+# openfindata-ship
+
+Skill versionada **somente no repositório**. Não há install obrigatório em
+`~/.agents/skills`.
+
+Fonte canônica:
+
+```text
+docs/agents/openfindata-ship/SKILL.md
+```
+
+Agentes devem ler este path no checkout/worktree atual. Não criar cópia local
+paralela como source of truth.
+
+Helpers:
+
+- `docs/agents/openfindata-ship/scripts/readiness.sh` — hygiene de worktree/branch antes do ship
+- `docs/agents/openfindata-ship/scripts/check-pr-threads.sh` — falha se houver review threads abertas
+
+Preflight do repo (fora desta pasta):
+
+```bash
+bash scripts/ship/preflight.sh
+```
diff --git a/docs/agents/openfindata-ship/SKILL.md b/docs/agents/openfindata-ship/SKILL.md
new file mode 100644
index 0000000..ac8c140
--- /dev/null
+++ b/docs/agents/openfindata-ship/SKILL.md
@@ -0,0 +1,153 @@
+---
+name: openfindata-ship
+description: 'Use when working in the openfindata repo and the user says "ship", "shipar", "vamos shipar", "merge", "pode mergear", "auto-merge", "automerge", asks to prepare/push/open/update a PR, asks to address PR comments with code changes, says a PR was merged and expects cleanup, or asks for deterministic pre-ship review.'
+---
+
+# Ship do openfindata
+
+Skill versionada em `docs/agents/openfindata-ship/`. Sem install externo: o
+checkout/worktree é a runtime copy.
+
+O roteamento para esta skill nunca concede por si só permissão de merge ou
+publicação PyPI. A autorização vem só dos gates explícitos abaixo.
+
+## Autoridade de roteamento
+
+Parent workflow para qualquer ação que possa publicar código:
+
+- commit, push, abrir/atualizar PR, marcar ready-for-review;
+- abordar comentários quando o resultado puder incluir mudanças de código ou push;
+- qualquer workflow GitHub além de inspeção read-only.
+
+Inspeção read-only de PR pode usar `gh` direto. Assim que edições, push ou
+criação de PR entrarem no escopo, volte a esta skill.
+
+## Checkpoint imediato de review
+
+Presuma adversarial review obrigatório, salvo dispensa explícita na mensagem atual.
+
+Antes de publicar ou fazer push material:
+
+1. **Commit primeiro o que será publicado**, deixe a working tree limpa, depois
+   revise o diff cumulativo `git diff --merge-base origin/main HEAD`. Não declare
+   review completo sobre um `HEAD` que ainda não contém as mudanças a publicar.
+   Se ainda houver unstaged/untracked no escopo do PR, incorpore ou exclua antes
+   do review final (`readiness.sh` falha com working tree suja).
+2. Review adversarial externo é tentativa obrigatória via skill/harness
+   `adversarial-review` (ou Task `adversarial-reviewer` no Cursor). Percorra até
+   obter review de família de modelo diferente da do autor do diff, ou registre
+   degradê:
+   - `CROSS_FAMILY` — família do reviewer comprovadamente diferente; nomeie ambas.
+   - `EXTERNAL_SAME_FAMILY` — externo rodou mas mesma família do autor.
+   - `DEGRADED_LOCAL_ONLY` — sem reviewer externo utilizável; inclua o review local.
+3. Achado externo só conta com evidência `arquivo:linha` + cenário. O arquiteto
+   do main loop tria o que é bloqueante.
+4. Gate **MCP Trust** quando o diff tocar MCP/code mode/superfície de agente:
+   leia [`../mcp-trust-review.md`](../mcp-trust-review.md) e rode a skill
+   `.claude/skills/mcp-trust-reviewer`. Anexe o resultado ao PR. Sem superfície:
+   `NOT_APPLICABLE` uma vez.
+5. Antes do push: `bash scripts/ship/preflight.sh` (evidência amarrada ao HEAD).
+
+## Lista de verificação adversarial (local)
+
+Inspecione o diff cumulativo e procure:
+
+- mudanças fora da tarefa / refactors amplos;
+- marcadores de conflito; caches (`.venv`, `.mypy_cache`, `.ruff_cache`, `.pytest_cache`);
+- artefatos de chart one-off (CSV/PNG/SVG/HTML temporários) sem pedido explícito;
+- `print()` de debug fora dos pontos permitidos; secrets; credential paths;
+- unit test batendo rede viva; nova fonte sem route+CLI+tests+docs+respx;
+- catálogo MCP inchando sem curadoria; code mode default-on;
+- invariantes: sem credenciais no tree; fontes públicas preferidas; mypy strict.
+
+Corrija achados bloqueantes antes de commit/push. Achado intencional: explique.
+
+## Significado de "ship"
+
+1. revisar arsenal/skills relevantes;
+2. gate deslop no diff (skill `deslop` do harness se disponível);
+3. commit do escopo do PR; working tree limpa;
+4. adversarial review do diff cumulativo commitado (+ MCP trust se aplicável);
+5. corrigir achados (novo commit se preciso; re-revisar o cumulativo);
+6. validar com preflight no HEAD atual;
+7. push/abrir ou atualizar PR ready-for-review **só se o usuário pediu publicar**;
+8. acompanhar checks/bots no head SHA e abordar comentários acionáveis;
+9. parar antes do merge, salvo autorização explícita de merge/auto-merge;
+10. nunca publicar PyPI nem criar tag de release sem aprovação humana explícita.
+
+Não escreva `SHIP_REPORT.md`. Reporte evidência na conversa e no corpo do PR.
+
+## Primeiros comandos
+
+```bash
+git rev-parse --show-toplevel
+git worktree list
+git status -sb
+git log --oneline -5
+bash docs/agents/openfindata-ship/scripts/readiness.sh
+bash scripts/ship/preflight.sh
+```
+
+## Regras de worktree e branch
+
+- Operações git mutantes (stage, commit, push, branch, worktree) só no MAIN LOOP.
+  Workers não rodam git mutante.
+- Root checkout = inspeção apenas. Implementação em worktree dedicada.
+- `main` = integração; nunca mutar código nela.
+- Branches de agente: `claude/<slug>`, `codex/<slug>`, `cursor/<slug>`.
+- Worktrees Claude: `.claude/worktrees/*`. Codex: `.worktrees/codex-*`.
+  Cursor: `$HOME/.cursor/worktrees/*`.
+- Novas branches a partir de `origin/main`.
+- Depois de pull que altere `.githooks/*` ou `scripts/git/guardrails.sh`, rode
+  `bash scripts/git/install-hooks.sh`.
+
+## Autorização de merge e auto-merge
+
+`merge` / `pode mergear` (após parada no merge gate) autoriza fechar **um** PR:
+
+1. atualizar estado e head SHA;
+2. checks obrigatórios/ativos verdes no head;
+3. threads acionáveis limpas;
+4. merge só se gates passarem;
+5. cleanup da branch/worktree desse PR.
+
+`auto-merge` / `automerge` = autorização antecipada condicionada ao mesmo limpo,
+fixada a um único PR. Expira ao mudar de PR/tarefa. Nunca autoriza PyPI.
+
+## Gate deslop
+
+Antes do adversarial final e da publicação, passe deslop no diff cumulativo
+(preservar comportamento): comentários mortos, try/except defensivos anormais,
+`Any` cosmético, nesting desnecessário, wrappers pass-through. Reporte reduções
+ou `no removable slop found`.
+
+## Protocolo de publicação
+
+Somente após review + validação:
+
+1. `git status -sb`
+2. stage intencional
+3. commit focado (estilo `tipo:` do `CONTRIBUTING.md`)
+4. `bash scripts/ship/preflight.sh` se o HEAD mudou
+5. push da branch de PR
+6. abrir/atualizar PR ready-for-review (draft só se pedido explícito)
+7. corpo: resumo, validação, MCP trust label se aplicável
+8. loop de bots/comentários no head SHA
+9. parar antes do merge salvo autorização explícita
+
+### Loop de comentários (resumo)
+
+```bash
+gh pr view --json number,url,isDraft,headRefOid,statusCheckRollup,reviewDecision
+bash docs/agents/openfindata-ship/scripts/check-pr-threads.sh <PR>
+```
+
+Aborde comentários acionáveis com mudanças cirúrgicas, re-valide, push, repita.
+Responda threads e resolva as abordadas. Finalize só com threads limpas ou
+itens explicitamente não acionáveis citados no relatório.
+
+## Pós-merge
+
+Com gatilho `merged` / `já mergeou` (ou continuidade após merge autorizado):
+limpar só a branch e worktree desse PR. Não deletar trabalho não relacionado.
+PyPI/tag continuam exigindo pedido humano separado.
diff --git a/docs/agents/openfindata-ship/scripts/check-pr-threads.sh b/docs/agents/openfindata-ship/scripts/check-pr-threads.sh
new file mode 100755
index 0000000..eb8101e
--- /dev/null
+++ b/docs/agents/openfindata-ship/scripts/check-pr-threads.sh
@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Ship-gate final scan: report unresolved review threads on a PR.
+# Usage: check-pr-threads.sh <pr-number> [owner/repo]
+# Exit 0 when every review thread is resolved; exit 1 when any is open.
+set -euo pipefail
+
+PR="${1:?usage: check-pr-threads.sh <pr-number> [owner/repo]}"
+REPO_SLUG="${2:-$(gh repo view --json nameWithOwner --jq '.nameWithOwner')}"
+if [[ ! "$REPO_SLUG" =~ ^[^/]+/[^/]+$ ]]; then
+  echo "[check-pr-threads] repo slug inválido: '$REPO_SLUG' (esperado owner/repo)" >&2
+  exit 2
+fi
+OWNER="${REPO_SLUG%%/*}"
+NAME="${REPO_SLUG##*/}"
+
+DATA=$(gh api graphql \
+  -f query='query($owner: String!, $name: String!, $pr: Int!) {
+    repository(owner: $owner, name: $name) {
+      pullRequest(number: $pr) {
+        headRefOid
+        reviewThreads(first: 100) {
+          pageInfo { hasNextPage }
+          nodes {
+            isResolved
+            isOutdated
+            path
+            comments(first: 1) { nodes { author { login } body } }
+          }
+        }
+      }
+    }
+  }' -F owner="$OWNER" -F name="$NAME" -F pr="$PR")
+
+if echo "$DATA" | jq -e '.errors' >/dev/null; then
+  echo "[check-pr-threads] Erro na API do GitHub:" >&2
+  echo "$DATA" | jq -r '.errors[].message' >&2
+  exit 2
+fi
+
+if [ "$(echo "$DATA" | jq -r '.data.repository.pullRequest')" = "null" ]; then
+  echo "[check-pr-threads] PR #$PR não encontrado no repositório $REPO_SLUG." >&2
+  exit 2
+fi
+
+HAS_MORE=$(echo "$DATA" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage')
+if [ "$HAS_MORE" = "true" ]; then
+  echo "[check-pr-threads] PR tem mais de 100 threads; scan parcial não vale como gate" >&2
+  exit 2
+fi
+
+HEAD_SHA=$(echo "$DATA" | jq -r '.data.repository.pullRequest.headRefOid[0:9] // "unknown"')
+TOTAL=$(echo "$DATA" | jq '.data.repository.pullRequest.reviewThreads.nodes | length')
+UNRESOLVED=$(echo "$DATA" | jq '[.data.repository.pullRequest.reviewThreads.nodes[]? | select(.isResolved == false)] | length')
+
+echo "[check-pr-threads] PR #$PR ($REPO_SLUG) head=$HEAD_SHA threads=$TOTAL resolved=$((TOTAL - UNRESOLVED)) unresolved=$UNRESOLVED"
+
+if [ "$UNRESOLVED" -gt 0 ]; then
+  echo "$DATA" | jq -r '.data.repository.pullRequest.reviewThreads.nodes[]?
+    | select(.isResolved == false)
+    | "[open] " + .path + " (" + (.comments.nodes[0].author.login? // "?") + "): "
+      + ((.comments.nodes[0].body? // "") | gsub("[\\n\\r]"; " ") | .[0:120])'
+  exit 1
+fi
+
+echo "[check-pr-threads] OK: nenhuma thread de review em aberto."
diff --git a/docs/agents/openfindata-ship/scripts/readiness.sh b/docs/agents/openfindata-ship/scripts/readiness.sh
new file mode 100755
index 0000000..dada59d
--- /dev/null
+++ b/docs/agents/openfindata-ship/scripts/readiness.sh
@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+set -u
+
+base="${1:-origin/main}"
+
+if ! top=$(git rev-parse --show-toplevel 2>/dev/null); then
+  echo "[openfindata-ship] FAIL not inside a git repo" >&2
+  exit 1
+fi
+
+cd "$top" || exit 1
+branch=$(git branch --show-current 2>/dev/null || true)
+git_dir=$(git rev-parse --path-format=absolute --git-dir 2>/dev/null || true)
+common_dir=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)
+status=$(git status --porcelain)
+fail=0
+warn=0
+
+say() { printf '%s\n' "$*"; }
+ok() { say "[ok] $*"; }
+warning() { say "[warn] $*"; warn=$((warn + 1)); }
+failmsg() { say "[fail] $*"; fail=$((fail + 1)); }
+
+say "[openfindata-ship] repo: $top"
+say "[openfindata-ship] git-dir: ${git_dir:-unknown}"
+say "[openfindata-ship] common-dir: ${common_dir:-unknown}"
+say "[openfindata-ship] branch: ${branch:-detached}"
+say "[openfindata-ship] base: $base"
+
+if [ -z "$branch" ]; then
+  failmsg "detached HEAD; ship should run from a named branch"
+elif [ "$branch" = "main" ]; then
+  failmsg "on main; use a dedicated agent branch/worktree before shipping"
+else
+  ok "not on main"
+fi
+
+if [ -n "$git_dir" ] && [ -n "$common_dir" ] && [ "$git_dir" = "$common_dir" ]; then
+  failmsg "root checkout detected; use a dedicated linked worktree before shipping"
+else
+  ok "worktree checkout detected"
+fi
+
+if git rev-parse --verify "$base" >/dev/null 2>&1; then
+  ok "$base exists"
+  if git merge-base --is-ancestor "$base" HEAD 2>/dev/null; then
+    ok "HEAD contains $base"
+  else
+    failmsg "HEAD is not based on $base; sync/rebase before shipping"
+  fi
+else
+  warning "$base not available locally; run git fetch origin main"
+fi
+
+if [ -n "$status" ]; then
+  failmsg "working tree has uncommitted changes; commit or exclude them before ship review/push"
+else
+  ok "working tree clean"
+fi
+
+if git rev-parse --verify "$base" >/dev/null 2>&1; then
+  committed_changed=$(git diff --name-only "$base"...HEAD)
+else
+  committed_changed=$(git diff --name-only HEAD)
+fi
+
+working_changed=$(
+  {
+    git diff --name-only
+    git diff --name-only --cached
+    git ls-files --others --exclude-standard
+  } | sort -u
+)
+changed=$(printf '%s\n%s\n' "$committed_changed" "$working_changed" | sed '/^$/d' | sort -u)
+
+if [ -z "$changed" ] && [ -z "$status" ]; then
+  warning "no changed files detected versus $base"
+else
+  say "[openfindata-ship] changed files (base diff + working tree):"
+  printf '%s\n' "$changed" | sed '/^$/d; s/^/  - /'
+fi
+
+bad_artifacts=$(printf '%s\n' "$changed" | grep -E '(^|/)\.venv/|(^|/)\.(mypy|ruff|pytest)_cache/|(^|/)\.coverage|\.pyc$|(^|/)\.DS_Store$' || true)
+if [ -n "$bad_artifacts" ]; then
+  failmsg "generated/local artifacts are in the diff"
+  printf '%s\n' "$bad_artifacts" | sed 's/^/  - /'
+else
+  ok "no obvious generated/local artifacts in diff"
+fi
+
+conflicts=0
+while IFS= read -r file; do
+  [ -n "$file" ] || continue
+  [ -f "$file" ] || continue
+  if grep -nE '^(<<<<<<<|>>>>>>>)' "$file" >/dev/null 2>&1; then
+    say "[fail] conflict marker candidate: $file"
+    conflicts=$((conflicts + 1))
+  fi
+done <<EOF_CHANGED
+$changed
+EOF_CHANGED
+if [ "$conflicts" -gt 0 ]; then
+  fail=$((fail + conflicts))
+else
+  ok "no conflict markers found in changed files"
+fi
+
+if [ -x "$top/.venv/bin/python" ] || command -v python3 >/dev/null 2>&1; then
+  ok "python available"
+else
+  failmsg "no Python interpreter; create .venv and pip install -e '.[dev]'"
+fi
+
+if [ -x "$top/scripts/ship/preflight.sh" ] || [ -f "$top/scripts/ship/preflight.sh" ]; then
+  ok "repo ship gate available: bash scripts/ship/preflight.sh"
+else
+  warning "scripts/ship/preflight.sh missing"
+fi
+
+if [ "$fail" -gt 0 ]; then
+  say "[openfindata-ship] FAIL $fail blocking issue(s), $warn warning(s)"
+  exit 1
+fi
+
+say "[openfindata-ship] OK with $warn warning(s). Resolve warnings or explain them before PR."
diff --git a/docs/agents/orientation.md b/docs/agents/orientation.md
new file mode 100644
index 0000000..edae111
--- /dev/null
+++ b/docs/agents/orientation.md
@@ -0,0 +1,53 @@
+# Mapa de orientação do repo
+
+Para agentes (e humanos) chegando frios: o arco do repo em ponteiros. Este
+arquivo aponta, não reconta; a fonte canônica de cada item é o link.
+
+Palavras-chave: orientação, onboarding de agente, decisões assentadas, becos
+mortos, fronteira atual, openfindata, findata.
+
+## O que é isto
+
+- Produto e escopo: [`README.md`](../../README.md), [`MANIFESTO.txt`](../../MANIFESTO.txt).
+- Convenções universais de código e gates: [`AGENTS.md`](../../AGENTS.md).
+- Harness Claude (worktrees, ship): [`CLAUDE.md`](../../CLAUDE.md).
+- Contribuição humana: [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+- Superfície MCP curada: [`docs/MCP_SURFACE.md`](../MCP_SURFACE.md).
+- Padrões de gráfico: [`docs/CHART_STANDARDS.md`](../CHART_STANDARDS.md).
+
+## Decisões assentadas (leia antes de reabrir)
+
+| Pergunta | Resposta vigente | Onde |
+|---|---|---|
+| Qual o slug de distribuição vs import/CLI? | Pacote PyPI `openfindata`; import e CLI `findata` | `AGENTS.md`, `pyproject.toml` |
+| Onde vive uma fonte nova? | `src/findata/sources/<source>/` com route + CLI + testes + docs + respx juntos | `AGENTS.md`, `CONTRIBUTING.md` |
+| Rede nos unit tests? | Proibido. `respx` nos unitários; live só `@pytest.mark.integration` | `AGENTS.md`, CI nightly |
+| Credenciais no repo? | Nunca. Fontes públicas preferidas; BdD usa billing project do operador via env | `AGENTS.md`, `docs/SOURCES_WITH_AUTH.md` |
+| MCP: 1:1 com REST ou curado? | Catálogo curado em `mcp_app` (~25 tools); REST intacto | `docs/MCP_SURFACE.md` |
+| Code mode no MCP? | Opt-in via `FINDATA_MCP_CODE_MODE=1`; off por default | `docs/MCP_SURFACE.md`, `mcp_app.py` |
+| Charts: quais deps de plot? | Não adicionar matplotlib/pandas/plotly etc. só para gráfico | `AGENTS.md`, `docs/CHART_STANDARDS.md` |
+| Publicar no PyPI? | Só com aprovação humana explícita | `AGENTS.md` |
+| Onde agentes implementam? | Worktree dedicada; root/`main` são inspect-only | `CLAUDE.md`, `docs/agents/openfindata-ship/` |
+
+## O que morreu e por quê
+
+- CI “pendente” em `.github-pending/`: obsoleto. Workflows vivem em
+  `.github/workflows/` (`ci.yml`, `integration.yml`, `rebuild-registry.yml`).
+- Auto-MCP 1:1 com todas as rotas REST: substituído pela superfície curada.
+- Nome legado do repo `findata-br` / import antigo: CLI e import permanecem
+  `findata` por compatibilidade; distribuição é `openfindata`.
+
+## Você está aqui (fronteira)
+
+- Workflows de qualidade de agente: este diretório `docs/agents/`.
+- Ship parent: [`openfindata-ship/SKILL.md`](openfindata-ship/SKILL.md).
+- Gate de confiança MCP/IA: [`mcp-trust-review.md`](mcp-trust-review.md).
+- Gates locais: [`quality.md`](quality.md) e `bash scripts/ship/preflight.sh`.
+- Backlog de fontes: [`docs/SOURCE_PRIORITIES.md`](../SOURCE_PRIORITIES.md).
+- Deploy público: [`docs/DEPLOY_PUBLIC.md`](../DEPLOY_PUBLIC.md).
+
+## Regra de atualização
+
+Quando uma decisão assentada mudar de forma durável, atualize a linha
+correspondente aqui e o arquivo canônico apontado. Entradas são uma linha e um
+link; o conteúdo vive na fonte canônica.
diff --git a/docs/agents/quality.md b/docs/agents/quality.md
new file mode 100644
index 0000000..2b39ecf
--- /dev/null
+++ b/docs/agents/quality.md
@@ -0,0 +1,61 @@
+# Quality gates
+
+Fonte canônica dos comandos de qualidade locais e de como eles se relacionam
+com hooks, ship e CI.
+
+## Gate completo (merge / release / ship)
+
+A partir da raiz da **worktree** (não do root checkout):
+
+```bash
+bash scripts/ship/preflight.sh
+```
+
+Equivalente expandido (mesmo conjunto que o preflight `--push`). Interpretador:
+worktree `.venv`, senão `.venv` na raiz do repo comum, senão `python3` — ver
+`CLAUDE.md` § Python / `.venv`.
+
+```bash
+# Prefer: bash scripts/ship/preflight.sh
+"$PY" -m ruff format --check src/ tests/ scripts/
+"$PY" -m ruff check src/ tests/ scripts/
+"$PY" -m mypy src/findata
+"$PY" -m pytest tests/ -q
+```
+
+Docs-only: no mínimo `git diff --check`.
+
+## Modos do preflight
+
+| Modo | Uso |
+|---|---|
+| `bash scripts/ship/preflight.sh` / `--push` | Readiness + gate completo; escreve evidência |
+| `--quick` | Só ruff check + format --check (iteração rápida) |
+| `--ci` | Gate completo sem readiness (paridade com `ci.yml` unitária) |
+| `--skip-readiness` | Útil em runners/CI; não use no ship local normal |
+
+Evidência: `<git-common-dir>/openfindata-verify/preflight.ok` amarrada ao SHA
+do `HEAD`.
+
+## Camadas
+
+| Camada | O que roda |
+|---|---|
+| pre-commit (hook) | Contexto worktree/branch + ruff no staged + ggshield opcional |
+| pre-push (hook) | Contexto + gate completo (ruff/mypy/pytest sem integration) |
+| ship skill | Deslop + adversarial review + MCP trust se aplicável + preflight + PR |
+| CI `ci.yml` | Matrix 3.11–3.13; coverage gate no 3.12 |
+| CI `integration.yml` | Nightly / manual: `pytest -m integration` |
+
+## Ownership das ferramentas
+
+| Papel | Ferramenta |
+|---|---|
+| Formatter + lint + AI complexity | Ruff (`pyproject.toml`) |
+| Types | mypy `--strict` |
+| Unit/API | pytest (`-m "not integration"` default) |
+| Secrets locais | ggshield (opt-in no pre-commit) |
+
+Detalhe humano: [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+Adversarial review: skill de harness `adversarial-review` (não duplicar aqui).
+MCP/IA: [`mcp-trust-review.md`](mcp-trust-review.md).
diff --git a/scripts/git/guardrails.sh b/scripts/git/guardrails.sh
index a3d4691..417305d 100755
--- a/scripts/git/guardrails.sh
+++ b/scripts/git/guardrails.sh
@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
 # Dados Financeiros Abertos git guardrails
-# Python/Ruff guardrail pattern for this repository.
 # Split of responsibility:
-#   - Ruff   → formatting + base lint + AI guardrails (complexity, max-args, magic numbers).
-#   - Mypy   → strict type checking.
-#   - Pytest → unit-test fast path (integration tests run on the scheduled CI workflow).
+#   - Context  → worktree/branch ownership (root and main are inspect-only).
+#   - Ruff     → formatting + base lint + AI guardrails.
+#   - Mypy     → strict type checking.
+#   - Pytest   → unit-test fast path (integration on scheduled CI).
 #   - ggshield (opt-in) → secret leak detection.
 
 set -euo pipefail
@@ -27,11 +27,193 @@ guardrails_repo_root() {
   cd "${common_git_dir}/.." && pwd -P
 }
 
-# Pick a usable python: prefer the repo-local .venv, then the user's python3.
+guardrails_current_checkout() {
+  git rev-parse --show-toplevel
+}
+
+guardrails_current_branch() {
+  git symbolic-ref --quiet --short HEAD 2>/dev/null || echo "DETACHED"
+}
+
+guardrails_normalize_dir() {
+  local path="${1%/}"
+
+  if [[ -z "$path" ]]; then
+    path="/"
+  fi
+
+  (
+    cd "$path" 2>/dev/null && pwd -P
+  ) || printf '%s\n' "$path"
+}
+
+guardrails_effective_home() {
+  local home_dir="${HOME:-}"
+
+  if [[ "$home_dir" == *[![:space:]]* && -d "$home_dir" ]]; then
+    guardrails_normalize_dir "$home_dir"
+    return 0
+  fi
+
+  (
+    unset HOME
+    cd ~ 2>/dev/null && pwd -P
+  )
+}
+
+guardrails_branch_class() {
+  local branch="${1:-}"
+  case "$branch" in
+    main)
+      echo "main"
+      ;;
+    codex/*)
+      echo "codex"
+      ;;
+    claude/*|cursor/*|session/claude-*|claude_code_*|worktree-claude_*)
+      echo "claude"
+      ;;
+    DETACHED)
+      echo "detached"
+      ;;
+    *)
+      echo "other"
+      ;;
+  esac
+}
+
+guardrails_path_class() {
+  local path="$1"
+  local home_dir
+  local normalized_path
+  local repo_root
+  home_dir="$(guardrails_effective_home || true)"
+  normalized_path="$(guardrails_normalize_dir "$path")"
+  repo_root="$(guardrails_normalize_dir "$(guardrails_repo_root)")"
+
+  if [[ -n "$home_dir" && "$normalized_path" == "$home_dir/.posthog-code/worktrees/"* ]]; then
+    echo "posthog-worktree"
+  elif [[ -n "$home_dir" && "$normalized_path" == "$home_dir/.cursor/worktrees/"* ]]; then
+    echo "cursor-worktree"
+  elif [[ "$normalized_path" == "$repo_root" ]]; then
+    echo "root"
+  elif [[ "$normalized_path" == "$repo_root/.worktrees/codex-"* ]]; then
+    echo "codex-worktree"
+  elif [[ "$normalized_path" == "$repo_root/.claude/worktrees/"* ]]; then
+    echo "claude-worktree"
+  elif [[ "$normalized_path" == "$repo_root/.worktrees/"* ]]; then
+    echo "manual-worktree"
+  else
+    echo "external"
+  fi
+}
+
+guardrails_require_allowed_context() {
+  local action="$1"
+  local checkout_path
+  local branch
+  local branch_class
+  local path_class
+
+  if [[ "${OPENFINDATA_GUARDRAILS_BYPASS:-0}" == "1" ]]; then
+    guardrails_warn "Bypassing openfindata git guardrails for ${action} because OPENFINDATA_GUARDRAILS_BYPASS=1."
+    return 0
+  fi
+
+  checkout_path="$(guardrails_current_checkout)"
+  branch="$(guardrails_current_branch)"
+  branch_class="$(guardrails_branch_class "$branch")"
+  path_class="$(guardrails_path_class "$checkout_path")"
+
+  if [[ "$path_class" == "root" ]]; then
+    guardrails_err "Blocked ${action}: the root checkout is orchestration-only."
+    guardrails_err "Use a dedicated worktree: .claude/worktrees/*, .worktrees/codex-*, \$HOME/.cursor/worktrees/*, or \$HOME/.posthog-code/worktrees/*."
+    return 1
+  fi
+
+  if [[ "$branch_class" == "main" ]]; then
+    guardrails_err "Blocked ${action}: branch 'main' is integration-only."
+    return 1
+  fi
+
+  if [[ "$branch_class" == "detached" ]]; then
+    guardrails_err "Blocked ${action}: detached HEAD is not an allowed agent workspace."
+    return 1
+  fi
+
+  case "$path_class" in
+    codex-worktree)
+      if [[ "$branch_class" != "codex" ]]; then
+        guardrails_err "Blocked ${action}: Codex worktrees under .worktrees/codex-* must use codex/* branches."
+        return 1
+      fi
+      ;;
+    claude-worktree)
+      if [[ "$branch_class" != "claude" ]]; then
+        guardrails_err "Blocked ${action}: Claude worktrees under .claude/worktrees/* must use Claude-owned branches (claude/* or cursor/*)."
+        return 1
+      fi
+      ;;
+    posthog-worktree)
+      if [[ "$branch_class" != "claude" ]]; then
+        guardrails_err "Blocked ${action}: PostHog Code worktrees must use Claude-owned branches."
+        return 1
+      fi
+      ;;
+    cursor-worktree)
+      if [[ "$branch_class" != "claude" ]]; then
+        guardrails_err "Blocked ${action}: Cursor worktrees must use Claude-owned branches (claude/* or cursor/*)."
+        return 1
+      fi
+      ;;
+    manual-worktree)
+      guardrails_warn "Working from a manually-named worktree. Prefer .worktrees/codex-* or .claude/worktrees/*."
+      ;;
+    external)
+      guardrails_err "Blocked ${action}: agent work must run from .worktrees/*, .claude/worktrees/*, \$HOME/.cursor/worktrees/*, or \$HOME/.posthog-code/worktrees/*."
+      return 1
+      ;;
+    *)
+      guardrails_err "Blocked ${action}: unsupported checkout path '${checkout_path}'."
+      return 1
+      ;;
+  esac
+
+  return 0
+}
+
+guardrails_warn_post_checkout() {
+  local checkout_path
+  local branch
+  local branch_class
+  local path_class
+
+  checkout_path="$(guardrails_current_checkout)"
+  branch="$(guardrails_current_branch)"
+  branch_class="$(guardrails_branch_class "$branch")"
+  path_class="$(guardrails_path_class "$checkout_path")"
+
+  if [[ "$path_class" == "root" && "$branch" != "main" ]]; then
+    guardrails_warn "root checkout is on '${branch}', not 'main'."
+    guardrails_warn "Treat the root checkout as read-only and move active work into a dedicated worktree."
+  fi
+
+  if [[ "$path_class" == "root" && "$branch_class" == "claude" ]]; then
+    guardrails_warn "root checkout is on Claude-owned branch '${branch}'."
+    guardrails_warn "Switch the root checkout back to 'main' and continue from .claude/worktrees/*."
+  fi
+
+  return 0
+}
+
+# Pick a usable python: worktree .venv, then repo-root .venv, then python3.
 guardrails_python() {
-  local root
+  local checkout root
+  checkout="$(guardrails_current_checkout)"
   root="$(guardrails_repo_root)"
-  if [[ -x "${root}/.venv/bin/python" ]]; then
+  if [[ -x "${checkout}/.venv/bin/python" ]]; then
+    printf '%s\n' "${checkout}/.venv/bin/python"
+  elif [[ -x "${root}/.venv/bin/python" ]]; then
     printf '%s\n' "${root}/.venv/bin/python"
   elif command -v python3 >/dev/null 2>&1; then
     command -v python3
@@ -54,16 +236,15 @@ guardrails_pre_commit() {
   files="$(guardrails_staged_py_files)"
   if [[ -z "$files" ]]; then
     guardrails_log "no staged Python files — skipping Ruff"
-    return 0
-  fi
-
-  guardrails_log "ruff check (staged only)"
-  # shellcheck disable=SC2086  # intentional word-splitting for file list
-  "$py" -m ruff check $files
+  else
+    guardrails_log "ruff check (staged only)"
+    # shellcheck disable=SC2086
+    "$py" -m ruff check $files
 
-  guardrails_log "ruff format --check (staged only)"
-  # shellcheck disable=SC2086
-  "$py" -m ruff format --check $files
+    guardrails_log "ruff format --check (staged only)"
+    # shellcheck disable=SC2086
+    "$py" -m ruff format --check $files
+  fi
 
   if command -v ggshield >/dev/null 2>&1; then
     guardrails_log "ggshield secret scan"
@@ -91,31 +272,58 @@ guardrails_pre_push() {
   "$py" -m pytest -q
 }
 
-# ── install hooks: point core.hooksPath at .githooks ────────────────
+# ── install hooks: copy into shared git-dir so all worktrees share them ──
 guardrails_install_hooks() {
-  local root
-  root="$(guardrails_repo_root)"
-  local target="${root}/.githooks"
+  local checkout_root
+  local common_git_dir
+  local install_dir
+  local source_hooks
 
-  if [[ ! -d "$target" ]]; then
-    guardrails_err "No .githooks directory at ${target}. Aborting."
+  checkout_root="$(guardrails_current_checkout)"
+  common_git_dir="$(git rev-parse --path-format=absolute --git-common-dir)"
+  install_dir="${common_git_dir}/openfindata-hooks"
+  source_hooks="${checkout_root}/.githooks"
+
+  if [[ ! -d "$source_hooks" ]]; then
+    guardrails_err "No .githooks directory at ${source_hooks}. Aborting."
     return 1
   fi
 
-  chmod +x "${target}/pre-commit" "${target}/pre-push" "${target}/guardrails.sh" 2>/dev/null || true
-  git config core.hooksPath "${target}"
-  guardrails_log "core.hooksPath = ${target}"
+  mkdir -p "$install_dir"
+  cp "${source_hooks}/pre-commit" "${install_dir}/pre-commit"
+  cp "${source_hooks}/pre-push" "${install_dir}/pre-push"
+  cp "${source_hooks}/post-checkout" "${install_dir}/post-checkout"
+  cp "${checkout_root}/scripts/git/guardrails.sh" "${install_dir}/guardrails.sh"
+  chmod +x "${install_dir}/pre-commit" "${install_dir}/pre-push" "${install_dir}/post-checkout" "${install_dir}/guardrails.sh"
+
+  git config core.hooksPath "${install_dir}"
+  guardrails_log "core.hooksPath = ${install_dir}"
   guardrails_log "run 'git config --unset core.hooksPath' to disable."
 }
 
 guardrails_main() {
   local command="${1:-}"
   case "$command" in
-    pre-commit)    guardrails_pre_commit ;;
-    pre-push)      guardrails_pre_push ;;
-    install-hooks) guardrails_install_hooks ;;
+    check-commit)
+      guardrails_require_allowed_context "commit"
+      ;;
+    check-push)
+      guardrails_require_allowed_context "push"
+      ;;
+    warn-post-checkout)
+      guardrails_warn_post_checkout
+      ;;
+    pre-commit)
+      guardrails_pre_commit
+      ;;
+    pre-push)
+      guardrails_pre_push
+      ;;
+    install-hooks)
+      guardrails_install_hooks
+      ;;
     *)
-      guardrails_err "Usage: guardrails.sh <pre-commit|pre-push|install-hooks>"
+      guardrails_err "Usage: guardrails.sh <check-commit|check-push|warn-post-checkout|pre-commit|pre-push|install-hooks>"
       return 2
       ;;
   esac
diff --git a/scripts/git/install-hooks.sh b/scripts/git/install-hooks.sh
index a5bb23c..14cab16 100755
--- a/scripts/git/install-hooks.sh
+++ b/scripts/git/install-hooks.sh
@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
-# Install Dados Financeiros Abertos git hooks by pointing `core.hooksPath` at .githooks/.
-# Idempotent — run again to refresh symlinks / permissions.
+# Install Dados Financeiros Abertos git hooks into <git-common-dir>/openfindata-hooks/
+# and point core.hooksPath there (shared by all worktrees). Idempotent.
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=/dev/null
 source "${SCRIPT_DIR}/guardrails.sh"
 
 guardrails_install_hooks
diff --git a/scripts/ship/preflight.sh b/scripts/ship/preflight.sh
new file mode 100755
index 0000000..633bee9
--- /dev/null
+++ b/scripts/ship/preflight.sh
@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# Deterministic pre-ship / pre-push gate for openfindata.
+# Writes evidence to <git-common-dir>/openfindata-verify/preflight.ok
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd -P)"
+READINESS_SCRIPT="${REPO_ROOT}/docs/agents/openfindata-ship/scripts/readiness.sh"
+BASE_REF="origin/main"
+MODE="push"
+SKIP_READINESS=0
+
+usage() {
+  cat <<'USAGE'
+Usage: bash scripts/ship/preflight.sh [--quick | --push | --ci] [--base <ref>] [--skip-readiness]
+
+Modes:
+  --quick   ruff format --check + ruff check
+  --push    readiness (unless skipped) + full local gate  [default]
+  --ci      full local gate without readiness (ci.yml unit parity)
+
+Options:
+  --base <ref>        merge base for readiness (default: origin/main)
+  --skip-readiness    skip worktree/readiness checks
+  -h, --help          show this message
+
+Evidence:
+  <git-common-dir>/openfindata-verify/preflight.ok
+USAGE
+}
+
+log() { printf '[ship:preflight] %s\n' "$*"; }
+fail() { log "FAIL $*"; exit 1; }
+
+parse_args() {
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --quick) MODE="quick"; shift ;;
+      --push) MODE="push"; shift ;;
+      --ci) MODE="ci"; shift ;;
+      --base) BASE_REF="${2:?--base requires a ref}"; shift 2 ;;
+      --skip-readiness) SKIP_READINESS=1; shift ;;
+      -h | --help) usage; exit 0 ;;
+      *) fail "unknown argument: $1" ;;
+    esac
+  done
+}
+
+repo_root() { git rev-parse --show-toplevel; }
+
+git_common_dir() {
+  git rev-parse --path-format=absolute --git-common-dir
+}
+
+head_sha() { git rev-parse HEAD; }
+
+pick_python() {
+  local checkout common_root
+  checkout="$(repo_root)"
+  common_root="$(cd "$(git_common_dir)/.." && pwd -P)"
+  if [[ -x "${checkout}/.venv/bin/python" ]]; then
+    printf '%s\n' "${checkout}/.venv/bin/python"
+  elif [[ -x "${common_root}/.venv/bin/python" ]]; then
+    printf '%s\n' "${common_root}/.venv/bin/python"
+  elif command -v python3 >/dev/null 2>&1; then
+    command -v python3
+  else
+    fail "No Python interpreter. Run: python3 -m venv .venv && pip install -e '.[dev]'"
+  fi
+}
+
+evidence_dir() {
+  local dir
+  dir="$(git_common_dir)/openfindata-verify"
+  mkdir -p "$dir"
+  printf '%s\n' "$dir"
+}
+
+write_preflight_evidence() {
+  local dir sha root steps
+  dir="$(evidence_dir)"
+  sha="$(head_sha)"
+  root="$(repo_root)"
+  steps="$1"
+  {
+    printf 'command=%s\n' 'bash scripts/ship/preflight.sh'
+    printf 'mode=%s\n' "$MODE"
+    printf 'steps=%s\n' "$steps"
+    printf 'sha=%s\n' "$sha"
+    printf 'repo=%s\n' "$root"
+    printf 'created_at_utc=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  } >"${dir}/preflight.ok"
+}
+
+run_readiness() {
+  if [[ "$SKIP_READINESS" == "1" ]]; then
+    log "skip readiness (--skip-readiness)"
+    return 0
+  fi
+  if [[ ! -f "$READINESS_SCRIPT" ]]; then
+    fail "readiness script missing: $READINESS_SCRIPT"
+  fi
+  log "readiness ($BASE_REF)"
+  bash "$READINESS_SCRIPT" "$BASE_REF"
+}
+
+run_step() {
+  local label="$1"
+  shift
+  log "$label"
+  "$@"
+}
+
+run_ruff() {
+  local py="$1"
+  run_step "ruff format --check" "$py" -m ruff format --check src tests scripts
+  run_step "ruff check" "$py" -m ruff check src tests scripts
+}
+
+run_full_gate() {
+  local py="$1"
+  run_ruff "$py"
+  run_step "mypy --strict" "$py" -m mypy src/findata
+  run_step "pytest (no integration)" "$py" -m pytest -q
+}
+
+main() {
+  parse_args "$@"
+  cd "$(repo_root)"
+
+  local py
+  py="$(pick_python)"
+  local steps=()
+
+  case "$MODE" in
+    quick)
+      run_ruff "$py"
+      steps+=(ruff)
+      ;;
+    push)
+      run_readiness
+      steps+=(readiness)
+      run_full_gate "$py"
+      steps+=(ruff mypy pytest)
+      ;;
+    ci)
+      run_full_gate "$py"
+      steps+=(ruff mypy pytest)
+      ;;
+    *)
+      fail "unknown mode: $MODE"
+      ;;
+  esac
+
+  local joined
+  joined=$(IFS=,; echo "${steps[*]}")
+  write_preflight_evidence "$joined"
+  log "OK mode=$MODE sha=$(head_sha) evidence=$(evidence_dir)/preflight.ok"
+}
+
+main "$@"