diff --git a/CHANGELOG.md b/CHANGELOG.md index c1a799a..2b2f95e 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.en.md b/README.en.md index 854ace8..26056a3 100644 --- a/README.en.md +++ b/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()` 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. diff --git a/README.md b/README.md index 01a79ad..5f22a75 100644 --- a/README.md +++ b/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()` 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 diff --git a/docs/archify-folder-reorg-research.md b/docs/archify-folder-reorg-research.md new file mode 100644 index 0000000..f421af7 --- /dev/null +++ b/docs/archify-folder-reorg-research.md @@ -0,0 +1,155 @@ +# Research: Archify e reorganização de pastas + +Pesquisa consolidada para responder: **como a skill Archify contribui para reorganizar a arquitetura das pastas do codebase, no contexto do workflow local de codebase-cleanup?** + +Fontes consultadas em **2026-08-12**. Afirmações sobre Archify vêm do clone em `/tmp/archify-research` (`tt-a1i/archify@a3bf80c`, release **v2.14.0**, 2026-08-11). Afirmações sobre a faxina local vêm do snapshot pedido (`/Users/rangel/.claude/skills/codebase-cleanup-workspace/skill-snapshot/…`) e, onde útil para o produto atual do repo, de `/Users/rangel/GitHub/codebase-cleanup`. Onde a fonte não diz, está escrito que não diz. + +## Pergunta + +Como a skill Archify (https://github.com/tt-a1i/archify) contribui para reorganizar a arquitetura das pastas do codebase, no contexto do workflow local de codebase-cleanup? + +## Fontes + +| ID | Fonte | Papel | +|---|---|---| +| A1 | https://github.com/tt-a1i/archify — `README.md` (clone `@a3bf80c`) | Posicionamento do produto, tipos de diagrama, escopo explícito | +| A2 | `archify/SKILL.md` | Contrato da skill: o que o agente deve fazer | +| A3 | `PRODUCT.md` | Propósito de produto e anti-referências | +| A4 | `archify/references/authoring-contract.md` — seção Repository evidence | Como Archify usa evidência de repositório | +| A5 | `docs/research-architecture-delta-pr-proof-2026-07-23.md` | Significado de `moved` no Architecture Delta | +| A6 | Metadados GitHub (`gh api repos/tt-a1i/archify`) | Descrição oficial, tópicos, licença MIT | +| A7 | `archify/package.json` | Versão estável (`2.14.0`), runtime Node (`>=18`) | +| A8 | https://github.com/tt-a1i/archify/issues/24 · https://github.com/tt-a1i/archify/issues/59 | Limitações abertas de layout (architecture) e escopo de repo evidence | +| B1 | `/Users/rangel/.claude/skills/codebase-cleanup-workspace/skill-snapshot/SKILL.md` | Pipeline de faxina (3 fases no snapshot) | +| B2 | `…/skill-snapshot/references/fase-3-estrutura.md` | Protocolo da fase de pastas | +| C1 | `/Users/rangel/GitHub/codebase-cleanup/SKILL.md` + `references/phase-3-structure.md` + `agents/cleanup-phase-3-survey.md` | Evolução do produto no repo (4 fases; checkpoint na fase 3) | +| C2 | `/Users/rangel/GitHub/codebase-cleanup/docs/*-research.md` | Convenção de notas de pesquisa neste repo | + +## Resumo executivo + +**Archify não reorganiza pastas.** Ele transforma descrição de sistema ou evidência de repositório em **mapa técnico interativo** (HTML + JSON tipado), com validação determinística e artefatos compartilháveis ([A1], [A2], [A3], [A6]). + +A **Fase 3** da skill local faz o oposto operacional: **diagnostica a árvore de diretórios, escolhe um padrão (feature / camada / convenção da linguagem) e executa `git mv` com gate** ([B1], [B2]). + +A contribuição real do Archify, relativa à Fase 3, é **complementar e anterior à execução**: ajudar a *ver* e *comunicar* a arquitetura de runtime/sistema (e, opcionalmente, um delta Before/After de fatos autorados). **Não substitui** plano de pastas, `git mv`, aliases, CODEOWNERS nem rollback atômico. Usar Archify *no lugar* da Fase 3 seria confundir mapa visual com mutação da árvore. + +## O que o Archify faz + +### Produto + +- Skill de agente que gera diagramas **architecture, workflow, sequence, dataflow e lifecycle** como HTML autocontido com SVG, temas, motion opcional e export ([A1], [A2], [A6]). +- Fluxo resumido: o agente escreve **JSON IR tipado** → `validate` → `deliver` → artefato verificado ([A1], [A2]). +- Propósito declarado: o leitor entende a história principal, inspeciona relações autoradas e leva o artefato (ou um Route/Reach Share Card) para review/docs/apresentação ([A3]). +- **Não é** editor WYSIWYG geral, tema Mermaid, nem auto-layout genérico; parsing automático de Mermaid, sharing hospedado e edição WYSIWYG estão **fora do escopo** ([A1], [A3]). + +### Instalação e runtime + +- Instalação global genérica (comando do Archify; pin de versão é da doc + deles, não desta skill): `npx skills@latest add tt-a1i/archify -g` ([A1]). +- Cursor (explícito, não interativo): `npx -y skills@latest add tt-a1i/archify --skill archify --agent cursor --global --copy --yes` ([A1]). +- Runtime: **Node ≥ 18** (`engines.node` em `archify/package.json`) ([A7]). +- Versão estável citada nesta pesquisa: **v2.14.0** (2026-08-11) ([A1], [A7]). + +### Caminho de autorar (CLI / skill) + +O produto autoriza **diagramas**, não pastas. O caminho documentado em SKILL.md e README ([A1], [A2]): + +1. Escolher o tipo (`architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`). +2. Ler o schema correspondente em `schemas/` e um exemplo JSON em `examples/`. +3. Escrever o candidato **JSON IR** (artefato primeiro; coordenadas exatas não são planejadas em prosa). +4. `node bin/archify.mjs validate --quality showcase --json`. +5. **Preview opcional** (`preview`) — loop desktop que só publica revisões verificadas; nunca é o default ([A2]). +6. `node bin/archify.mjs deliver --quality showcase --json` — aceitação final; bytes congelados após passar. +7. **Compare opcional** (só `architecture`): `node bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json` → Architecture Delta Before / Delta / After ([A1]). + +### Relação com “arquitetura” e código + +- Pode **inspecionar o repositório** quando o diagrama deve refletir código real: entrypoints, boundaries de runtime, storage, transports, config de deploy; registrar só evidência verificada; não inferir causalidade de runtime só por proximidade de arquivo ou nome ([A4]). +- **Limites da repo evidence (v2.14.0):** modo **Architecture only** — `meta.repository`, node `sources` e `--repo-root` não se aplicam a workflow/sequence/dataflow/lifecycle; exige URL **pública do GitHub** e **commit SHA completo** (40 caracteres); repositórios privados, revisões não pinadas e paths locais no artefato ficam fora do contrato ([A1], docs internos de repo evidence). Issue aberta para estender evidence aos outros tipos: https://github.com/tt-a1i/archify/issues/59 ([A8]). +- Architecture Delta compara dois JSON de architecture já validados (Before / Delta / After) com fatos added/removed/changed/**moved**/rerouted — **`moved` aqui é geometria/posição de componente no diagrama**, não `git mv` de arquivo ([A1], [A5]). +- O contrato de PR Proof deixa explícito que a primeira versão **não** analisa impacto de código nem afirma segurança de merge ([A5]). + +### O que a fonte **não** afirma + +Em README, SKILL, PRODUCT, authoring-contract e ROADMAP amostrado **não há** protocolo de reorganização de pastas, escolha feature-vs-camada, `git mv`, atualização de path aliases, CODEOWNERS ou commits atômicos por pasta. A descrição GitHub fala em diagramas de arquitetura/workflow/etc., não em cleanup estrutural da árvore ([A6]). + +**Saídas explicitamente fora de escopo** (não aparecem como produto Archify): plano de pastas, patches de rename, árvore `src/` reorganizada, nem commits Git no repositório fonte — o `deliver` do CLI congela snapshot/HTML do diagrama, não muta o codebase inspecionado ([A1], [A2], [A3]). + +**Lacuna de vocabulário:** nas fontes primárias Archify (README, SKILL, PRODUCT, authoring-contract) **não há** linguagem de “deep modules”, fronteiras de pacote no código, ou protocolo de colocation/feature-folder — o vocabulário é de componentes runtime, boundaries de diagrama, JSON IR e validação de layout ([A1]–[A4]). + +## O que a skill codebase-cleanup já faz (fase pastas) + +### No snapshot pedido (B1/B2) — três fases + +Ordem fixa: **Limpar o morto → decidir fronteiras → mover arquivos** ([B1]). + +**Fase 3 — Estrutura de pastas** ([B1], [B2]): + +1. Diagnóstico antes de mover: mapa atual, ciclos, módulos-deus, abstrações vazando, estrutura alvo, plano faseado. +2. Escolha de padrão: por feature (colocation), por camada, ou convenção da linguagem. +3. Execução: uma pasta por commit com `git mv`; preferir path aliases a reescrever imports em massa; typecheck; rollback com `git reset --hard` se o gate falhar. +4. Atualizar configs que quebram em silêncio (tsconfig, bundler, knip, CI, CODEOWNERS, imports dinâmicos, `CLAUDE.md`). + +No snapshot, o **único checkpoint humano obrigatório** do pipeline é a Fase 2 (consolidação); em nível VERDE, a Fase 3 **executa o plano sem perguntar** ([B1]). + +### Nota sobre o repo de produto (C1) + +O workspace `/Users/rangel/GitHub/codebase-cleanup` evoluiu para **quatro fases** e, na Fase 3 VERDE, exige **checkpoint humano antes de qualquer `git mv`**, com agente `cleanup-phase-3-survey` só-leitura para o plano ([C1]). A comparação abaixo usa o snapshot (B) como contrato pedido; C1 importa só para integração com o produto atual. + +## Contribuição do Archify (mapa claro) + +| Capacidade Archify | Ajuda a “reorganizar pastas”? | Como encaixa na faxina | +|---|---|---| +| Mapa runtime/sistema (8–12 componentes) | Indiretamente | Pode informar o *diagnóstico* da Fase 3 (quem depende de quem no runtime), sem mover arquivos ([A1], [A4]) | +| Evidence-backed nodes (`SRC n`, commit pinado) | Indiretamente | Ancora o mapa em arquivos reais; ainda não decide destino de pasta ([A1], [A4]) | +| Architecture Delta (Before/After) | Comunicação / review | Mostra mudança de *fatos autorados* do diagrama — útil pós-faxina ou para explicar fronteiras; **não** executa movimentos de árvore ([A1], [A5]) | +| Workflow / sequence / dataflow / lifecycle | Fora do job da Fase 3 | Útil para explicar fluxos; não é protocolo de pastas ([A2]) | +| `git mv`, aliases, gates, commits atômicos | **Não** | Ausente nas fontes Archify | + +**Contribuição única relativa à Fase 3:** artefato de comunicação e exploração de topologia **autorada/verificada**, com validação e share cards — algo que a Fase 3 não produz. A Fase 3, por sua vez, **muta** a árvore com disciplina operacional que Archify não cobre. + +## Comparativo + +| Dimensão | Archify | Fase 3 (snapshot) | +|---|---|---| +| Job-to-be-done | Explicar/visualizar sistema | Tornar a árvore de pastas legível e coerente | +| Input | Descrição ou evidência de repo → JSON IR | Mapa de diretórios + ciclos + fronteiras pós-Fase 2 | +| Output | HTML + JSON + exports | Commits `git mv` + configs atualizadas | +| “Moved” | Geometria de nó no delta de diagrama ([A5]) | Arquivo/pasta no Git ([B1], [B2]) | +| Gate de verdade | Schema/layout/artifact checks do CLI ([A2]) | Typecheck + testes; rollback ao último commit verde ([B1]) | +| Decisão de domínio | Layout e ênfase do diagrama (agente) | Feature vs camada vs convenção ([B2]); no snapshot, consolidação (Fase 2) é o checkpoint humano ([B1]) | +| Overlap real | Ambos usam a palavra “arquitetura” e podem olhar o repo | Overlap operacional **baixo** | + +## Recomendação de uso + +**Não substituir a Fase 3.** Archify não implementa o job da Fase 3 ([A1]–[A3] vs [B1]–[B2]). + +**Complementar, opcionalmente:** + +1. **Antes do plano de pastas (diagnóstico):** mapa runtime de alto nível quando o time não enxerga fronteiras reais (serviços, stores, boundaries) e o grafo de pastas sozinho engana — com a restrição de não inferir causalidade por proximidade de arquivo ([A4]). +2. **No checkpoint humano (produto atual C1):** anexar o HTML Archify ao plano de `cleanup-phase-3-survey` para o humano validar a *história* do sistema, não como prova de que o `git mv` é seguro. +3. **Depois da faxina:** Architecture Delta Before/After como comunicação de PR/release da mudança de entendimento arquitetural — sem confundir com diff de pastas ([A5]). + +**Só a skill local basta quando:** o padrão alvo já é claro (ex.: esvaziar `utils/` global para features), ciclos já vêm do knip/madge, e o trabalho é mover com gate — o caso nominal da Fase 3 ([B2]). + +**Ignorar Archify na faxina quando:** o custo de autorar/validar um diagrama showcase atrasa um plano de pastas já óbvio, ou quando se esperaria que Archify “sugerisse a árvore nova” — a fonte não oferece esse produto. + +## Limitações e questões abertas + +1. **Risco de falsa equivalência:** “architecture map” ≠ “folder architecture”. Usar Archify como oráculo de destinos de pasta viola o próprio authoring contract (não inferir runtime por naming/proximidade) ([A4]). +2. **Escopo limitado do mapa:** recomendação de 8–12 componentes ([A1]) — útil para overview, insuficiente como inventário completo da árvore. +3. **Delta não prova segurança de merge** nem blast radius de código ([A5]). +4. **Divergência snapshot × repo:** o snapshot executa Fase 3 sem checkpoint em VERDE ([B1]); o produto em `codebase-cleanup` exige aprovação do plano ([C1]). Qualquer integração deve alinhar ao contrato vigente do plugin instalado. +5. **Layout em architecture mode:** conexões podem rotear *através* de componentes não relacionados sem erro de `validate`/`render`, distorcendo topologia visualmente (workflow já rejeita isso desde v2.8). Issue aberta: https://github.com/tt-a1i/archify/issues/24 ([A8]). +6. **Repo evidence só em architecture:** estender `--repo-root` / `meta.repository` a sequence, dataflow e lifecycle é pedido de feature, não bug — ver https://github.com/tt-a1i/archify/issues/59 ([A8]). +7. **Questão aberta:** vale um gancho formal (“opcional: gerar artefato Archify no survey da Fase 3”) no `SKILL.md` do produto, ou basta menção em docs? As fontes Archify não definem integração com skills de cleanup; isso seria decisão de produto local, não feature Archify. + +## Referências + +- https://github.com/tt-a1i/archify — README.md, PRODUCT.md, `archify/SKILL.md`, `archify/package.json`, `archify/references/authoring-contract.md`, `docs/research-architecture-delta-pr-proof-2026-07-23.md`, `docs/research-repo-evidence-passport-2026-07-23.md` (clone `@a3bf80c`, release v2.14.0, 2026-08-12) +- https://github.com/tt-a1i/archify/issues/24 — architecture: rotas atravessando componentes não relacionados +- https://github.com/tt-a1i/archify/issues/59 — repo evidence limitada a architecture +- https://tt-a1i.github.io/archify/ — página do projeto / Proof Lab (citada pelo README) +- `/Users/rangel/.claude/skills/codebase-cleanup-workspace/skill-snapshot/SKILL.md` +- `/Users/rangel/.claude/skills/codebase-cleanup-workspace/skill-snapshot/references/fase-3-estrutura.md` +- `/Users/rangel/GitHub/codebase-cleanup/SKILL.md`, `references/phase-3-structure.md`, `agents/cleanup-phase-3-survey.md`, `docs/`