docs: alinhar READMEs à fase 4 e à pesquisa Archify

CHANGELOG.md

@@ -17,6 +17,8 @@ recebe erro, a correção só nunca chega.
   `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).
+- Pesquisa Archify × Fase 3: `docs/archify-folder-reorg-research.md` (mapa
+  visual complementar; não substitui `git mv` nem o plano de pastas).
 - 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
@@ -31,6 +33,9 @@ recebe erro, a correção só nunca chega.
 
 - `LICENSE`: notice de que o OCR é ferramenta externa opcional; o código deste
   repositório permanece MIT.
+- READMEs (PT/EN): a fase 4 entra no fluxo "o que acontece ao rodar" e nos
+  subagentes (antes só aparecia na tabela de níveis); árvore de `docs/` e a
+  linha validada passam a 525/525 invariantes.
 
 ## [0.9.0] — 2026-08-11
 

README.en.md

@@ -137,7 +137,8 @@ codebase-cleanup/
 ├── 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
-│   └── open-code-review-comparison-research.md  complementarity with OpenCodeReview
+│   ├── open-code-review-comparison-research.md  complementarity with OpenCodeReview
+│   └── archify-folder-reorg-research.md  Archify as a map, not as Phase 3
 ├── hooks/
 │   └── hooks.json                    registers the guard on the PreToolUse event
 ├── references/
@@ -250,7 +251,7 @@ exercises the real GNU `timeout` instead of the perl backend:
 docker run --rm -v "$PWD":/repo:ro node:22-bookworm bash -c \
   'apt-get update -qq && apt-get install -y -qq procps && cd /repo && bash scripts/test.sh'
 # validated 2026-08: 145/145 cases, 47/47 guard cases, 5/5 properties,
-# 37/37 metrics cases, 463/463 invariants, 14/14 mutations caught
+# 37/37 metrics cases, 525/525 invariants, 14/14 mutations caught
 ```
 
 The .NET heuristic was validated against the real SDK
@@ -298,9 +299,12 @@ v0.3.5   44,801 bytes   ~15.7k on-invoke     (~370 always-on)
 v0.4.0   41,241 bytes   ~14.3k on-invoke     (~370 always-on)
 ```
 
-**~1,400 fewer tokens on every invocation.** The two measurements sit on
-different byte counts on purpose: between them the file *grew* with the #55
-fixes, and hiding that would make the extraction look larger than it was.
+**~1,400 fewer tokens on every invocation** from that extraction. The two
+measurements sit on different byte counts on purpose: between them the file
+*grew* with the #55 fixes, and hiding that would make the extraction look
+larger than it was. Since then `SKILL.md` has grown again with the phases and
+the measured rules (today ~48 KB / ~880 lines at v0.9.0): the criterion remains
+when the text is read, not a byte ceiling.
 
 The arithmetic that preceded the measurement was wrong, and it is worth
 recording how. Estimated from the file's average rate (2.85 bytes/token) the
@@ -421,6 +425,13 @@ With the level announced, it creates the cleanup branch and proceeds:
   question. Answer "go" and it implements.
 - **Phase 3 — structure.** Diagnosis of the folder tree, plan, and moves with
   `git mv`, one folder per commit.
+- **Phase 4 — local reshaping.** Inherits targets from the 1.4 audit and from
+  the 1.5 pairs phase 2 did not take, filtered by churn. The safety net is
+  per target (is that function covered?), not the whole repository. Tier A
+  runs on its own — up to 5 operations per session; tier B stops at a
+  checkpoint and applies at most 1. One `refactor(<operation-id>)` per
+  commit. Uncovered target: skip and record it, or write a characterization
+  test as its own commit and then proceed — there is no third exit.
 
 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
@@ -437,7 +448,7 @@ the next session resumes where it stopped without you re-explaining anything. In
 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
-agent for each of phases 2 and 3. The two survey agents cannot write — that is
+agent for each of phases 2, 3 and 4. The survey agents cannot write — that is
 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.

README.md

@@ -134,7 +134,8 @@ codebase-cleanup/
 ├── 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
-│   └── open-code-review-comparison-research.md  complementaridade com OpenCodeReview
+│   ├── open-code-review-comparison-research.md  complementaridade com OpenCodeReview
+│   └── archify-folder-reorg-research.md  Archify como mapa, não como Fase 3
 ├── hooks/
 │   └── hooks.json                    registra o guarda no evento PreToolUse
 ├── references/
@@ -248,7 +249,7 @@ exercita o GNU `timeout` real em vez do backend perl:
 docker run --rm -v "$PWD":/repo:ro node:22-bookworm bash -c \
   'apt-get update -qq && apt-get install -y -qq procps && cd /repo && bash scripts/test.sh'
 # validado em 08/2026: 145/145 casos, 47/47 casos do guarda, 5/5 propriedades,
-# 37/37 casos de métrica, 463/463 invariantes, 14/14 mutações pegas
+# 37/37 casos de métrica, 525/525 invariantes, 14/14 mutações pegas
 ```
 
 A heurística .NET foi validada contra o SDK real (`mcr.microsoft.com/dotnet/sdk:8.0`
@@ -313,9 +314,12 @@ v0.3.5   44.801 bytes   ~15,7k on-invoke     (~370 always-on)
 v0.4.0   41.241 bytes   ~14,3k on-invoke     (~370 always-on)
 ```
 
-**~1.400 tokens a menos em cada invocação.** As duas medições têm bases de bytes
-diferentes de propósito: entre uma e outra o arquivo *cresceu* com os consertos
-da #55, e esconder isso deixaria a extração parecer maior do que foi.
+**~1.400 tokens a menos em cada invocação** naquela extração. As duas medições
+têm bases de bytes diferentes de propósito: entre uma e outra o arquivo
+*cresceu* com os consertos da #55, e esconder isso deixaria a extração parecer
+maior do que foi. Desde então o `SKILL.md` voltou a crescer com as fases e as
+regras medidas (hoje ~48 KB / ~880 linhas na v0.9.0): o critério continua sendo
+momento de leitura, não um teto de bytes.
 
 Vale registrar o erro da conta que antecedeu a medição. Estimando pela taxa
 média do arquivo (2,85 bytes/token) o ganho projetado era ~1.550 tokens, 11%
@@ -432,6 +436,13 @@ Com o nível anunciado, ela cria a branch de limpeza e segue:
   Respondeu "vai", ela implementa.
 - **Fase 3 — estrutura.** Diagnóstico da árvore de pastas, plano, e movimentos
   com `git mv`, uma pasta por commit.
+- **Fase 4 — remodelagem local.** Herda alvos da auditoria 1.4 e dos pares da
+  1.5 que a fase 2 não consumiu, filtrados por churn. A rede de segurança é
+  por alvo (a função está coberta?), não pelo repositório inteiro. Tier A
+  corre sozinho — até 5 operações por sessão; tier B para no checkpoint e
+  aplica no máximo 1. Um `refactor(<operation-id>)` por commit. Alvo sem
+  cobertura: pula e registra, ou escreve um characterization test num commit
+  próprio e segue — não há terceira saída.
 
 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` /
@@ -446,8 +457,8 @@ 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
-de survey e implementação para cada uma das fases 2 e 3. Os dois de survey não
+vêm declarados em `agents/`: `cleanup-phase-1` (fases 1 e 1.5), e um par de
+survey e implementação para cada uma das fases 2, 3 e 4. Os de survey não
 conseguem escrever — é assim que o checkpoint deixa de depender de boa
 vontade: a pergunta chega até você antes de qualquer mudança, e a
 implementação só começa depois da sua resposta. O protocolo está na seção