plan(OPS92): consolidar MCPs do opencode (intenção)

docs/plans/ops92-consolidar-mcps.md

@@ -0,0 +1,80 @@
+# Consolidar MCPs do opencode: global fica só com playwright + jina; penpot/postgres viram subagentes; GitHub MCP morre (CLI gh); forgejo/jobspy/office-word/stalwart re-homed para os projetos donos
+
+Status: plano — registrado (blocked até plano em main)
+Atualizado em: 2026-08-24
+Issue: #857
+Priority: P2
+Impeccable: A — N/A sem UI
+Rascunho UI: N/A — sem UI
+Appetite: ~0,5–1 dia, config-only (global + arquivos locais + 2 subagentes + docs)
+Responsável: —
+
+## Intenção
+
+Cada MCP declarado no config global do opencode soma tokens de contexto em **toda** sessão do agente, mesmo quando a ferramenta não é usada. O global de hoje carrega sete MCPs, e quase todos são específicos de um projeto ou já estão mortos na prática: o GitHub MCP está desativado desde 17/08 (OAuth nunca autorizado — `gh` CLI já é o fallback real), e forgejo/jobspy/office-word/stalwart só têm dono em projetos irmãos. Quero chegar a um estado em que abrir o opencode no Teqo custa o mínimo de contexto: **apenas playwright + jina no global**. O resto vai para o lugar que o usa — Penpot e Postgres ficam no Teqo mas só dentro de subagentes dedicados (são ferramentas deste projeto: design do site e banco local), e os demais voltam para os repositórios que os consomem.
+
+## Persona e fluxo
+
+- **Persona / contexto:** dono do repo/opencode local (fsolla), abrindo sessões do opencode em vários projetos na mesma máquina.
+- **Job principal:** abrir uma sessão do opencode no Teqo com o menor contexto possível, sem perder acesso a ferramentas quando precisar delas.
+- **Fluxo desejado:** abre o opencode no Teqo → sessão expõe só jina, playwright e as tools padrão; precisa desenhar/cobrir o mapa do site → chama o subagente `penpot`, que enxerga o MCP; precisa checar o banco local → chama o subagente `postgres`; precisa de GitHub → usa `gh` no terminal ou scripts do repo.
+- **Anti-goals de produto:** esta entrega NÃO é um gerenciador de MCPs, não automatiza o config global (continua edição manual do dono, como o OPS89), e não vira auditoria/limpeza geral de configs de outros projetos.
+
+## Objetivo e aceite
+
+- Abrir o opencode no Teqo expõe apenas playwright + jina (e built-ins) — nenhum MCP de GitHub, forgejo, jobspy, office-word ou stalwart ativo.
+- O subagente `penpot` consegue usar as tools do Penpot numa sessão do Teqo.
+- O subagente `postgres` consegue consultar o banco local `teqo` numa sessão do Teqo.
+- Tarefas de GitHub funcionam via `gh` CLI (instalado e autenticado), sem perder nenhuma capacidade que o MCP morto teria.
+- Cada projeto dono tem seu MCP local funcionando (decisões do gate): forgejo em `lei-mercados-digitais`, `infra-solla` e `iara-pwa` (os três têm o tracker de Issues no Forgejo e usam o MCP); jobspy em `jobs`; office-word em `lei-mercados-digitais` (só — o infra-solla perde e seu AGENTS.md sai coerente); stalwart em `infra-solla` (só — a iara-pwa já desabilita stalwart no próprio `opencode.jsonc`, decisão Issue #5 dela: "e-mail pessoal").
+- Nada quebra: dev server, launch de worktrees (a cópia de secrets continua necessária — penpot permanece declarado no repo) e a documentação que cita o penpot MCP como ativo fica coerente com o novo desenho.
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Não — é tooling de desenvolvimento, sem dado de negócio.
+- **Decisões desbloqueadas:** N/A — nenhuma decisão de produto depende deste item.
+- **Forma:** N/A.
+
+## Direção no codebase (hipótese)
+
+- **Áreas prováveis:** `~/.config/opencode/opencode.jsonc` (global, não commitado — edição manual, fora do git), `opencode.json` do repo Teqo (MCPs penpot/postgres com tools gated), novos `.opencode/agent/penpot.md` e `.opencode/agent/postgres.md` (subagentes, precedente nos subagentes existentes do repo), e os configs dos projetos irmãos — `jobs/opencode.json` (adicionar jobspy), `lei-mercados-digitais/opencode.json` (adicionar forgejo + office-word), `infra-solla/opencode.jsonc` (declarar forgejo + stalwart; remover pin morto de postgres; AGENTS.md sem office-word), `iara-pwa/opencode.jsonc` (declarar forgejo; limpar pins mortos de postgres/stalwart).
+- **Precedente a olhar:** OPS89 (mesmo padrão: edição manual do global, nenhum gate/CI lê `opencode.json` estruturalmente — já provado); subagentes existentes em `.opencode/agent/*.md`; `scripts/worktree.mjs` (cópia de secrets que vira no-op).
+- **Risco de acoplamento:** o mecanismo oficial de gate de tools por agente (`tools` + `agent.<nome>.tools`) está marcado como deprecated no schema em favor de `permission` — o executor valida o mecanismo vigente na hora, sem inventar paralelo.
+
+## Dependências
+
+- Nenhuma.
+
+## Fora de escopo
+
+- Não mexer em auth/credenciais além do necessário para mover os blocos (nenhum token novo).
+- Não tocar nos MCPs eur-lex / mcp-brasil do `lei-mercados-digitais`.
+- Não automatizar o config global (continua manual).
+- Não auditar nem "limpar" configs de projetos que não recebem MCP nesta entrega.
+
+## Rabbit holes de produto
+
+- **Subagente que vira gerenciador de MCPs.** Se alguém "só completar": nasce um sistema de descoberta/habilitação de MCPs, o oposto da simplificação. **Corte neste item:** dois subagentes fixos (penpot, postgres), nada dinâmico.
+- **Mexer no que não é do item.** Se alguém "só completar": edita credenciais em claro ou reestrutura configs de projetos irmãos além dos blocos nomeados. **Corte neste item:** mover os blocos e só; validar a config lendo, não reformatando.
+- **Re-home forçado.** Se alguém "só completar": coloca forgejo/stalwart em projetos cujo dono não confirmou uso, criando config morta — o mesmo desperdício que estamos eliminando. **Corte neste item:** só os destinos confirmados no gate.
+
+## Questões em aberto (produto)
+
+Todas resolvidas no gate de 2026-08-24:
+
+- **Um item único ou split?** **Decisão:** único OPS92.
+- **Forgejo: destinos?** **Decisão:** `lei-mercados-digitais` (único que vive só no Forgejo) + `infra-solla` e `iara-pwa` (ambos usam o MCP ativamente — tracker de Issues no Forgejo, confirmado nos AGENTS.md de cada um).
+- **Stalwart no `iara-pwa`?** **Decisão:** não — a iara-pwa já desabilita stalwart no próprio `opencode.jsonc` (Issue #5 dela, "e-mail pessoal; fora do fluxo de dev da Iara"); re-homar lá contradiria a decisão versionada do projeto. Stalwart vai só para `infra-solla` (dono do server). Reaproveita o mesmo server — nada duplicado.
+- **Subagentes penpot/postgres: repo Teqo ou global?** **Decisão:** repo Teqo (`opencode.json` + `.opencode/agent/*.md`).
+- **office-word também no infra-solla?** **Decisão:** não — só `lei-mercados-digitais`; o AGENTS.md do infra-solla é atualizado para remover office-word da lista de "em uso".
+- **Corrigir as menções "(MCP/`pnpm issue`)" nas skills?** **Decisão:** sim.
+
+## Referências
+
+- `~/.config/opencode/opencode.jsonc` — global atual (GitHub desativado, jina, playwright, postgres, forgejo, stalwart, office-word, jobspy).
+- `opencode.json` (repo Teqo) — `$schema` + `mcp.penpot` com token em `.opencode/secrets/` (gitignored).
+- `scripts/worktree.mjs` (linhas ~239–258, 345) — cópia de `.opencode/secrets/*`; vira no-op sem penpot no config.
+- `AGENTS-infra.md` e `docs/campanha/prompt-montagem-home.md` — citam o penpot MCP como ativo; atualizar se o desenho mudar.
+- `scripts/check-changelog-append-only.mjs` e `scripts/check-plans-only-pr-closes.mjs` — precedentes de `gh` CLI como fallback.
+- Projetos irmãos: `lei-mercados-digitais/opencode.json` (eur-lex + mcp-brasil), `infra-solla/opencode.jsonc` (usa forgejo/stalwart/office-word herdados; pins postgres), `iara-pwa/opencode.jsonc` (usa forgejo; desabilita postgres/stalwart — Issue #5 dela), `jobs/opencode.json` (só provider).
+- `AGENTS.md` — Teqo não usa Forgejo (zero refs nos workflows).