teqo-backup/docs/plans/ops85-changelog-e-docs-externos.md

# OPS85 — Estratégia para eliminar conflitos de merge no changelog e reavaliar migração da documentação para fora do repo

Status: rascunho
Atualizado em: 2026-08-24
Issue: #830
Priority: P1
Impeccable: A — N/A (sem UI)
Rascunho UI: N/A — sem UI
Appetite: ~1–2 dias eng; um outcome verificável + uma decisão documentada
Responsável: —

## Intenção

O `CHANGELOG-AGENTS.md` continua gerando conflitos de merge toda vez que dois agentes entregam em paralelo — cada PR reescreve o mesmo agregado no mesmo anchor e o rebase cobra a fatura. O plano antecessor (#713/OPS44) já resolveu as entradas por arquivo, mas deixou em aberto se o agregado commitado compensa; a evidência do dia a dia responde: não compensa. Quero eliminar essa classe de conflito de vez e, em paralelo, decidir com evidência se vale migrar a documentação de leitura humana para fora do repo — ou arquivar a ideia explicitamente.

## Persona e fluxo

- **Persona / contexto:** agentes paralelos (worktrees `plans/*`/`work/*`) fazendo claim→plano→PR ao mesmo tempo; humano revisando gates.
- **Job principal:** entregar uma PR sem gastar ciclo em rebase de changelog, e saber onde mora a verdade do histórico.
- **Fluxo desejado:** cada entrega grava sua entrada em `docs/changelog/<data>-<id>.md` (já imune); o agregado "Recently resolved" deixa de ser arquivo de conflito — vira leitura sob demanda (comando ou artefato não-commitado); a decisão sobre docs externos sai deste item documentada, com implementação ou arquivamento explícito.
- **Anti-goals de produto:** não perder a leitura "Recently resolved" estabelecida; não virar cerimônia de merge (mais passos por PR); não quebrar o ciclo claim→plano→PR (paths locais em skills/Issue body); não criar segundo "single source of truth" desincronizado; não tocar o núcleo do `AGENTS.md` além do apontamento mínimo.

## Objetivo e aceite

- Zero conflito em arquivo de changelog em N dias de agentes paralelos (N ≥ 14) — e o guard de sync deixa de ser requisito de CI.
- Leitura do histórico preservada: "Recently resolved" continua acessível, por comando ou artefato regenerável, com o mesmo conteúdo.
- Decisão sobre documentação externa documentada com evidência (prova de conceito mínima OU arquivamento explícito com motivo), sem deixar a pergunta "aberta para sempre".

## Dados (intenção)

- **Vou apresentar dados?** Não — sem superfície nova; evidência é do fluxo de trabalho (contagem de conflitos/rebases observados e custo do guard).
- **Decisões desbloqueadas:** executor → escolha do mecanismo de leitura agregada pós-morte do arquivo; humano → migrar ou não docs agent-facing para fora (registro no changelog).
- **Forma:** N/A — sem métrica de produto nova.

## Direção no codebase (hipótese)

- **Áreas prováveis:** `scripts/build-changelog.mjs` (+ `scripts/lib/changelog.mjs`) — agregado vira build under-demand; `scripts/gate-ci.mjs`/`ci-pr.yml` (`build-changelog.mjs --check` em `docs-guards`, OPS63) — guard de sync sai ou vira check de sanitidade; `docs/AGENT-OPS.md`, `AGENTS.md` (bullet do changelog), skills `plan-issue`/`work-issue` (contrato de entrada) — atualização de contrato.
- **Precedente a olhar:** #713 (`docs/plans/redesenhar-fluxo-reduzir-conflitos.md` L86 — questão reaberta), OPS44, OPS63 (`docs/plans/ops63-doc-guard-no-pre-push.md`), `docs/plans/restaurar-entradas-changelog-b183-c102.md` (a classe de perda que o guard protege).
- **Risco de acoplamento:** append-only do agregado protege contra perda silenciosa de entradas (incidente B183/C102) — a nova forma deve preservar essa garantia sem o arquivo commitado (ex.: guard por-arquivo + verificador de conjunto); `changelog-rewrite:` é escape CI-only e pode morrer com o arquivo.

## Dependências

- Nenhuma dura. Leitura: #713 (decisão antecessora). Candidatos externos dependem de decisão de infra do homeserver (nenhuma nova serviço instalado neste item — só avaliação, a menos que o gate escolha implementar).

## Fora de escopo

- Migrar o corpo inteiro de `docs/` para fora do repo — só a decisão (implementar um alvo OU arquivar) sai deste item; migração em massa, se escolhida, é Issue própria com plano dedicado.
- Tocar `docs/plans/` (o registro por-issue que funciona) ou as 647+ entradas históricas.
- Instalar/configurar serviço novo no homeserver como parte do plano — no máximo spike de avaliação se o gate decidir.
- Mudar o ciclo claim→plano→PR, o merge por rebase ou os guards não-changelog (marcadores de conflito em `docs/`, plans-only-closes).

## Rabbit holes de produto

- **"Migrar tudo para fora"** — 12 skills com paths hardcoded, Issue body com `Plano: docs/plans/...`, guards amarrados: explosão de escopo que não ataca a causa do conflito. **Corte neste item:** docs agent-facing (registro de entregas) permanece no repo; avaliação externa é só para leitura humana.
- **"Guard mais esperto em vez de matar o arquivo"** — merge driver git ou cerimônia nova apenas desloca o custo. **Corte:** a classe de conflito morre só quando o arquivo compartilhado deixa de ser commitado; alternativa de merge driver entra só como opção documentada, não implementada.
- **"Segunda fonte de verdade"** — wiki externa com docs agent-facing que os guards não enxergam vira registro desincronizado. **Corte:** se houver alvo externo, escopo restrito a leitura humana; agente continua lendo o repo.

## Questões em aberto (produto)

- **O agregado commitado deve morrer?** **Opções:** A) matar: `docs/changelog/` vira o único registro; "Recently resolved" é gerado sob demanda (`pnpm changelog:build` sem commit, ou artefato gitignored); guard de sync sai do CI; append-only preservado por guard por-arquivo. B) manter arquivo + merge driver git (`git merge drivers`) para resolver o anchor automaticamente. C) manter como está, com `serializes`/rebase (custo atual). **Recomendação:** **A** — elimina 100% da classe de conflito com custo mínimo e zero infra nova; preserva a leitura (comando) e a garantia append-only (por-arquivo + verificador de conjunto); B desloca o custo para uma máquina que ainda escreve o mesmo arquivo e C é a evidência do humano provando que não funciona. _(assumido — validar no gate se a perda do "arquivo sempre-presente" incomoda a leitura humana)._
- **Docs agent-facing (changelog, plans) migram para fora?** **Opções:** A) permanecem no repo — o conflito era do agregado, não das entradas por-arquivo; migração custaria reescrever 12+ skills e o ciclo de Issues com paths locais. B) migram — com plano próprio e migração em fases. **Recomendação:** **A** — documentar a rejeição com a evidência da questão 1 (causa eliminada); a migração externa fica arquivada como ideia revisitável só se um custo novo aparecer. _(assumido — confirmar com o humano no gate)._
- **Se externo um dia, qual alvo?** **Opções:** Wiki.js (Node+DB, revisões, edição paralela) | Docmost (OSS, colaborativo) | Outline (OSS, Postgres+Redis+MinIO — mais pesado) | BookStack (PHP) | coleção `Doc` versionada no próprio Payload (self-hosted, versioning nativo, mas acopla docs ao app e muda o fluxo de leitura dos agentes) | Pages estático (gera de um repo git — ainda conflita no git). **Recomendação:** se o gate algum dia implementar, **Wiki.js** no homeserver (postgres/registry já existentes; revisões por página = histórico preservado; edição paralela sem git); Outline fica como segunda opção quando o custo de infra adicional se justificar; Pages estático é a resposta errada para a classe "conflito de git"; Payload `Doc` é barato de nascer mas troca conflito de merge por conflito de deploy (docs presas ao ciclo do app). _Posição registrada neste plano; nada é instalado neste item._

## Referências

- GitHub Issue #713 (OPS44) — `docs/plans/redesenhar-fluxo-reduzir-conflitos.md` (L86: questão do agregado em aberto) e `-impl.md`
- OPS63 — `docs/plans/ops63-doc-guard-no-pre-push.md` (docs-guards no pre-push, `build-changelog.mjs --check`)
- OPS44 — entrada em `docs/changelog/2026-08-13-ops44.md`; contrato em `docs/AGENT-OPS.md` (escape `changelog-rewrite:`)
- Incidente que o append-only protege: `docs/plans/restaurar-entradas-changelog-b183-c102.md`
- Para o executor abrir primeiro: `scripts/build-changelog.mjs`, `scripts/lib/changelog.mjs`, `scripts/check-changelog-append-only.mjs`, `scripts/gate-ci.mjs` (L91-93), `AGENTS.md` (bullet do changelog)