docs: OCR complementarity patterns and coverage discipline

CHANGELOG.md

@@ -9,6 +9,29 @@ do manifesto é a chave de cache que decide se uma instalação enxerga
 atualização, e esquecer o bump falha em silêncio dos dois lados — ninguém
 recebe erro, a correção só nunca chega.
 
+## [Unreleased]
+
+### Adicionado
+
+- Pesquisa de comparação com OpenCodeReview:
+  `docs/open-code-review-comparison-research.md` (vizinhos vs substitutos,
+  o que a skill absorveu como disciplina de processo e o que permanece
+  ferramenta externa).
+- Documentação de complementaridade com OpenCodeReview (CLI opcional Apache-2.0,
+  sem vendoring): `references/complementarity-opencodereview.md`, receita
+  `ocr review` / `ocr delegate` na branch `cleanup/`, e menção no relatório
+  final.
+- **Coverage mandate** nas varreduras 1.4 e 1.5: checklist
+  `reviewed|skipped+reason` e `coverage_rate` em `CLEANUP_PROGRESS.md`.
+- **Preview** nomeado antes da primeira mutação da fase 1.3 (lista no log,
+  commit próprio; GREEN segue autónomo).
+- Seção **Residual risks** com severidade no relatório final.
+
+### Alterado
+
+- `LICENSE`: notice de que o OCR é ferramenta externa opcional; o código deste
+  repositório permanece MIT.
+
 ## [0.9.0] — 2026-08-11
 
 Quatro decisões de texto normativo tomadas com medição, e um terceiro mecanismo do mesmo defeito

LICENSE

@@ -26,3 +26,10 @@ Third-party notice: portions of references/audit.md are derived from
 tech-debt-audit by ksimback (https://github.com/ksimback/tech-debt-skill),
 licensed under the MIT License — Copyright (c) ksimback. The permission
 notice above applies to those portions as well.
+
+Optional external tool (not incorporated): documentation in this repository
+may describe using the OpenCodeReview CLI
+(https://github.com/alibaba/open-code-review), licensed under the Apache
+License 2.0, as an optional post-cleanup review step. That CLI is not
+vendored, bundled, or required to run this skill; this project's own source
+and documentation remain under the MIT License above.

README.en.md

@@ -136,12 +136,14 @@ codebase-cleanup/
 │   └── cleanup-phase-4-impl.md       applies tier A and the approved tier B
 ├── docs/
 │   ├── plugin-spec-research.md       host limits, official advice and mere habit
-│   └── attribution-frontier.md       what the skill buys and what the model already brings
+│   ├── attribution-frontier.md       what the skill buys and what the model already brings
+│   └── open-code-review-comparison-research.md  complementarity with OpenCodeReview
 ├── hooks/
 │   └── hooks.json                    registers the guard on the PreToolUse event
 ├── references/
 │   ├── gate.md                       the gate contract: exit codes, watchdog, scripts
 │   ├── audit.md                      phase 1.4 audit protocol
+│   ├── complementarity-opencodereview.md  optional OCR on the cleanup/ branch
 │   ├── final-report.md               the report template and how to fill it
 │   ├── knip-config.md                knip configuration without pitfalls
 │   ├── duplication.md                duplicate functions and the churn rule
@@ -393,25 +395,44 @@ With the level announced, it creates the cleanup branch and proceeds:
 
 - **Phase 1 — dead code.** Configures knip until the hints reach zero, runs
   in production mode and deletes in atomic commits, one per category: unused
-  deps, orphan files, dead exports. Each step stages only pathspecs of that
-  step's artifacts (`git add -- …`, never `git add -A`), and only lands with a
-  green gate. At the end, it produces an audit of what is left.
+  deps, orphan files, dead exports. Before the first deletion, it writes an
+  explicit **Preview (phase 1.3)** into `CLEANUP_PROGRESS.md` — the concrete
+  deps, files and exports the report would remove — and commits that log
+  update alone (`chore: preview phase 1 deletions`). On GREEN it proceeds
+  without asking after that record exists; on YELLOW the preview simply omits
+  what the level will not touch. Each delete step stages only pathspecs of
+  that step's artifacts (`git add -- …`, never `git add -A`), and only lands
+  with a green gate. At the end, phase **1.4** produces a full audit; every
+  unit in the sweep ends `reviewed` or `skipped` with a reason, and the
+  counts plus `coverage_rate` land under `## Coverage` in the progress log —
+  a rate below 100% without a recorded Decisions gap leaves the step
+  incomplete.
 - **Phase 1.5 — duplicate functions** (closes phase 1). Sweeps for functions
   with different names doing the same thing (similarity-ts or fallow on
   JS/TS, jscpd on other stacks) and applies the churn rule: a pair that
   changes together in git is real duplication and becomes a phase 2
   candidate; a pair that evolves independently is structural coincidence and
-  is left alone. Report only — nothing is deleted here.
+  is left alone. The same **coverage mandate** applies: every detector pair
+  is `reviewed` or `skipped` with a reason and a `coverage_rate` before the
+  survey commit. Report only — nothing is deleted here.
 - **Phase 2 — consolidation.** Surfaces up to 5 shallow module candidates
   (starting from the phase 1.5 pairs), recommends one and asks a single
   question. Answer "go" and it implements.
 - **Phase 3 — structure.** Diagnosis of the folder tree, plan, and moves with
   `git mv`, one folder per commit.
 
+The final report (template in `references/final-report.md`) includes open
+findings from the 1.4 audit as **Residual risks**, each with the audit's own
+severity (`Critical` / `High` / `Medium` / `Low`) — unfinished business from
+the cleanup, not a second audit. When the run left a `cleanup/` branch, the
+summary may point to an optional OCR review under **Optional next step**
+(see [Complementarity with OpenCodeReview](#complementarity-with-opencodereview));
+never as a required protocol stage.
+
 Between phases the skill asks for `/clear` — context accumulated from one
 phase degrades the judgment of the next. Progress lives in
-`CLEANUP_PROGRESS.md` at the repo root, so the next session resumes where it
-stopped without you re-explaining anything. In environments with subagents,
+`CLEANUP_PROGRESS.md` at the repo root (including Preview and Coverage), so
+the next session resumes where it stopped without you re-explaining anything. In environments with subagents,
 the skill runs as an orchestrator and dispatches each phase to a disposable
 context. Installed as a plugin, those subagents come declared in `agents/`:
 `cleanup-phase-1` (phases 1 and 1.5), plus a survey and an implementation
@@ -420,6 +441,22 @@ how the checkpoint stops depending on good intentions: the question reaches you
 before anything changed, and the implementation only starts after your answer.
 The protocol is in Step 0.2 of SKILL.md.
 
+### Complementarity with OpenCodeReview
+
+This skill and [Alibaba OpenCodeReview](https://github.com/alibaba/open-code-review)
+(OCR) solve different jobs. Cleanup mutates the tree behind a gate — dead
+code, shallow modules, folders, local reshaping. OCR reviews a diff or PR
+and leaves line-level comments; auto-fix without a human is out of its
+roadmap. They are neighbours, not substitutes: OCR's "dead code" heuristics
+on a diff are not a replacement for knip or vulture.
+
+The skill does **not** install, vendor, or call the OCR Go binary. OCR stays
+an optional CLI you install yourself when you want review QA after a cleanup.
+The recipe — `ocr review` / `ocr delegate` against `cleanup/YYYYMMDD` — lives
+in `references/complementarity-opencodereview.md`. When a run produced that
+branch, the final summary may mention it as an optional next step; it is
+never required.
+
 ### How to revert
 
 Each category lives in its own commit. If something breaks later:
@@ -546,12 +583,23 @@ Skills and materials used in building this one:
 - [Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing),
   from Wikipedia's WikiProject AI Cleanup — the basis of the local adaptation
   `humanizer-pt-br`, used to write this README.
+- [OpenCodeReview](https://github.com/alibaba/open-code-review), by Alibaba
+  (Apache-2.0) — not embedded here; its review discipline (preview before
+  spend, coverage checklists, severity on findings) informed the named
+  preview, coverage mandate and residual-risks sections of this protocol.
+  Optional post-cleanup QA recipe:
+  `references/complementarity-opencodereview.md`.
 
 None of them is a runtime dependency: they were sources and development
 tools — nothing beyond this folder needs to be installed to use
-codebase-cleanup.
+codebase-cleanup. OCR remains optional and external if you choose to run it.
 
 ## License
 
 MIT — use, copy, modify and redistribute freely. Full text in
 [LICENSE](LICENSE).
+
+The optional OpenCodeReview CLI is licensed under Apache-2.0 and is **not**
+vendored, bundled, or required by this skill. Describing how to use it does
+not relicense this repository; this project's own source and documentation
+stay MIT.

README.md

@@ -133,12 +133,14 @@ codebase-cleanup/
 │   └── cleanup-phase-4-impl.md       aplica tier A e o tier B aprovado
 ├── docs/
 │   ├── plugin-spec-research.md       o que é limite do host, conselho e hábito
-│   └── attribution-frontier.md       o que a skill compra e o que o modelo já traz
+│   ├── attribution-frontier.md       o que a skill compra e o que o modelo já traz
+│   └── open-code-review-comparison-research.md  complementaridade com OpenCodeReview
 ├── hooks/
 │   └── hooks.json                    registra o guarda no evento PreToolUse
 ├── references/
 │   ├── gate.md                       o contrato do gate: exit codes, watchdog, scripts
 │   ├── audit.md                      protocolo de auditoria da fase 1.4
+│   ├── complementarity-opencodereview.md  OCR opcional na branch cleanup/
 │   ├── final-report.md               o modelo do relatório e como preenchê-lo
 │   ├── knip-config.md                configuração do knip sem armadilhas
 │   ├── duplication.md                funções duplicadas e a regra do churn
@@ -270,6 +272,23 @@ o vocabulário de consolidação da fase 2 em
 créditos não muda o comportamento em runtime; elas são fonte, não
 dependência.
 
+### Vizinho opcional: OpenCodeReview
+
+Esta skill e o [OpenCodeReview](https://github.com/alibaba/open-code-review)
+(OCR) da Alibaba resolvem trabalhos diferentes — são **vizinhos**, não
+substitutos. A cleanup mexe na árvore (código morto, módulos rasos, pastas,
+remodelagem local) atrás de gate e branch `cleanup/`. O OCR comenta risco e
+defeito em diff/PR, linha a linha; não é o caminho para apagar o que o knip
+ou o vulture marcam como inalcançável.
+
+A skill **não** instala, chama nem embute o binário Go do OCR, nem copia
+prompts ou regras dele. Quem quiser review de QA depois da faxina instala o
+CLI por conta (Apache-2.0; requisitos como Git ≥ 2.41 e endpoint de LLM são
+do OCR). A receita opcional — `ocr review` / `ocr delegate` contra a branch
+`cleanup/` — está em `references/complementarity-opencodereview.md`. O
+relatório final pode citar esse passo sob "Optional next step"; nunca como
+obrigação do protocolo.
+
 ### O que o `SKILL.md` carrega, e o que ele adia
 
 Todo byte do `SKILL.md` é pago em **toda** invocação: ele entra inteiro no
@@ -390,23 +409,40 @@ Com o nível anunciado, ela cria a branch de limpeza e segue:
 
 - **Fase 1 — código morto.** Configura o knip até os hints zerarem, roda em
   modo produção e deleta em commits atômicos, um por categoria: deps não
-  usadas, arquivos órfãos, exports mortos. Cada passo faz stage só com
-  pathspecs dos artefatos daquele passo (`git add -- …`, nunca `git add -A`),
-  e só entra com gate verde. No fim, produz uma auditoria do que sobrou.
+  usadas, arquivos órfãos, exports mortos. Antes da primeira mutação da
+  fase 1.3, grava um **preview** em `CLEANUP_PROGRESS.md` (lista concreta
+  por categoria, commit próprio `chore: preview phase 1 deletions`) — no
+  GREEN segue sozinha depois desse registro; no YELLOW o preview só omite o
+  que o nível já proíbe. Cada passo faz stage só com pathspecs dos
+  artefatos daquele passo (`git add -- …`, nunca `git add -A`), e só entra
+  com gate verde. No fim, produz uma auditoria do que sobrou (fase 1.4),
+  com **coverage mandate**: cada unidade da varredura fecha como
+  `reviewed` ou `skipped` com motivo, e o `coverage_rate` vai no log —
+  taxa abaixo de 100% sem gap registrado em Decisions deixa o passo
+  incompleto.
 - **Fase 1.5 — funções duplicadas** (fecha a fase 1). Varre funções com nomes
   diferentes fazendo a mesma coisa (similarity-ts ou fallow em JS/TS, jscpd
   nos demais stacks) e aplica a regra do churn: par que muda junto no git é
   duplicação real e vira candidato da fase 2; par que evolui separado é
-  coincidência estrutural e fica em paz. Só relatório — nada é deletado aqui.
+  coincidência estrutural e fica em paz. O mesmo mandate de cobertura vale
+  para cada par que o detector emitiu. Só relatório — nada é deletado aqui.
 - **Fase 2 — consolidação.** Levanta até 5 candidatos de módulos rasos
   (começando pelos pares da fase 1.5), recomenda um e faz uma única pergunta.
   Respondeu "vai", ela implementa.
 - **Fase 3 — estrutura.** Diagnóstico da árvore de pastas, plano, e movimentos
   com `git mv`, uma pasta por commit.
 
+O relatório final traz **Residual risks**: achados abertos da auditoria 1.4
+que a limpeza não fechou, cada um com a severidade do audit (`Critical` /
+`High` / `Medium` / `Low`) — não é uma segunda auditoria, é o que ficou
+pendente. Quando a run deixou branch `cleanup/`, o sumário pode apontar um
+passo opcional de review com OCR (seção [Vizinho opcional](#vizinho-opcional-opencodereview));
+nunca como etapa obrigatória.
+
 Entre as fases a skill pede `/clear` — contexto acumulado de uma fase piora o
 julgamento da seguinte. O progresso fica em `CLEANUP_PROGRESS.md` na raiz do
-repo, então a sessão seguinte retoma de onde parou sem você reexplicar nada.
+repo (incluindo Preview e Coverage), então a sessão seguinte retoma de onde
+parou sem você reexplicar nada.
 Em ambientes com subagentes, a skill roda como orquestrador e despacha cada
 fase para um contexto descartável. Instalada como plugin, esses subagentes
 vêm declarados em `agents/`: `cleanup-phase-1` (fases 1 e 1.5), e mais um par
@@ -540,6 +576,13 @@ Skills e materiais usados na construção desta:
   do WikiProject AI Cleanup da Wikipedia — base da adaptação local
   `humanizer-pt-br`, usada na escrita deste README.
 
+Ferramenta complementar (opcional, sem vendoring):
+
+- [OpenCodeReview](https://github.com/alibaba/open-code-review) (Alibaba,
+  Apache-2.0) — CLI de review de diff/PR que a documentação desta skill
+  pode citar como passo opcional depois da branch `cleanup/`. Não entra no
+  runtime; a receita está em `references/complementarity-opencodereview.md`.
+
 Nenhuma delas é dependência de runtime: são fontes e ferramentas de
 desenvolvimento — nada além desta pasta precisa estar instalado para usar a
 codebase-cleanup.
@@ -548,3 +591,8 @@ codebase-cleanup.
 
 MIT — use, copie, modifique e redistribua à vontade. Texto completo em
 [LICENSE](LICENSE).
+
+O CLI OpenCodeReview, quando você o instala à parte, é Apache-2.0 e
+permanece ferramenta externa: este repositório não o vende, não o embute e
+não o exige. Usá-lo não relicencia o código desta skill; o notice correspondente
+está no final do [LICENSE](LICENSE).