audit — auditoria trimestral

audit — a varredura trimestral

analysis enxerga o repositório; audit enxerga o que um visitante e um rastreador veem: o HTML ao vivo, os códigos de status reais, os redirecionamentos, o sitemap como é servido. Tudo o que encontra ou se torna um item de backlog que a skill fix pode executar mecanicamente, ou uma linha na lista de proprietários para coisas que nenhuma skill deve tocar (navegação, layouts, páginas de preços e legais, hospedagem). Nunca edita um artigo e nunca abre um PR.

Scripts: ${CLAUDE_PLUGIN_ROOT}/scripts/{crawl,inventory,sitecheck}.js. Defina P=${CLAUDE_PLUGIN_ROOT}.

Argumentos: --origin <url> (padrão: https://<dominio> de seo/brand.json, senão o host da linha Preview), --max <n> páginas (500), --external <n> links externos a verificar (200), --cwv (consulta o PageSpeed Insights para a home e hubs de cluster; precisa de rede para googleapis.com, PAGESPEED_API_KEY opcional), --no-items (apenas relatório, não escreve nada no backlog), --dry-run (varre e relata, não comita nada).

0. Pré-condições

Raiz do repositório do produto; git status --porcelain vazio; no branch padrão; seo/strategy.md e o bloco ## Agente SEO existem. Execute node $P/scripts/inventory.js --root . primeiro para que a varredura possa mapear caminhos para arquivos e tipos. Não precisa de gh.

1. Varredura

PREV=$(ls seo/data/crawl/*.json 2>/dev/null | sort | tail -1)
node $P/scripts/crawl.js --root . --origin <origem> --max <n> --external <n> [--cwv] --save seo/data/crawl ${PREV:+--diff $PREV} --quiet

Leia o JSON: summary (páginas, descobertas por código, truncated), findings[] (code, severity fix|report, path, file, msg, to), sitemap (count, error, missing), external[], cwv[], diff (new, resolved desde a auditoria anterior). Uma chave error no nível superior ou sitemap.error → informe e pare; um site fora do ar é problema do proprietário, não um item de backlog. truncated: true → informe que a varredura atingiu --max e quais caminhos ainda estavam na fila.

Em seguida, execute também node $P/scripts/sitecheck.js --root .: ele enxerga a fonte (argumentos Blade, rotas, frames) que o HTML ao vivo esconde, e os dois juntos formam o quadro completo.

2. Triagem

Três grupos, nesta ordem:

1. Itens fix — descobertas com severity: fix (códigos title, description, canonical, alt, link, sitemap) em uma página cuja entrada de inventário possui um file do tipo guia, artigo ou ferramenta. Um item por página, exatamente como a analysis §1c os escreve, com duas diferenças: - evidence: audit <data>: <n> findings e cada linha fixes: termina com (audit <data>) para que fix saiba confirmá-la no site ao vivo em vez de no sitecheck:

   ### [B-nnn] fix: <caminho>
   - type: fix
   - target: <caminho>
   - score: <n> (potential <p> × ease 10 × fit <f>)      ← potential 3, ou o gsc_potential da página do snapshot seo/data/gsc mais recente; fit da prioridade do cluster
   - evidence: audit <data>: <n> findings
   - status: open
   - fixes:
     link: internal link /old-path redirects to /new-path: link the final URL (audit <data>)
     description: no meta description (audit <data>)
   

   Uma página que já possui um item fix aberto/reivindicado/em revisão → acrescente as novas linhas fixes: a ele (pule linhas já presentes pelo código + to). Uma página pertencente a um item refresh aberto → owned by B-nnn, sem item de correção. Uma descoberta que o sitecheck também relata (mesma página, mesmo código) é listada uma vez, a partir da auditoria, com a tag (audit <data>).
2. Itens link — descobertas orphan em páginas de artigo: um item link por cluster (formato $P/skills/analysis/SKILL.md §1c, linhas - links: /hub → /orphan (orphan, audit <data>)); um cluster com um item link aberto recebe os pares acrescentados. Órfãos sem cluster (nenhum hub corresponde) vão para a lista de proprietários.
3. Lista de proprietários — todo o resto: broken-external, redirect-chain, duplicate-title/duplicate-description, noindex-in-sitemap, sitemap-404, thin, h1, mixed-content, slow, server-error, todas as descobertas em uma página que não é de artigo (home, preços, legal, layouts), sitemap.missing e as linhas de CWV. Agrupe por código, piores primeiro, ≤ 3 caminhos de exemplo por código; nomeie o arquivo quando o inventário o conhecer. thin em um artigo é um sinal de atualização, não uma correção: informe e deixe para a analysis.

--no-items → apenas grupo 3, com a contagem dos itens que seriam criados.

3. Commit

A menos que --dry-run: git add seo/data/crawl/<data>.json seo/backlog.md e comite seo: audit <data> — <páginas> páginas, <descobertas> descobertas, <k> itens fix, <m> itens link no branch padrão (arquivos de planejamento comitam diretamente); faça push se o branch tiver um upstream. Nenhum PR.

4. Relatório (≤ 15 linhas)

• audit <data>: <páginas> páginas varridas (<html> html, <truncated?>), <descobertas> descobertas (<corrigíveis> corrigíveis); sitemap <contagem> URLs, <faltando> ausentes ou com falha
• Descobertas por código, uma linha, contagens
• Diff vs <anterior>: <novas> novas, <resolvidas> resolvidas (nomeie as novas se ≤ 5)
• Itens: ids fix com caminhos; ids link com clusters; notas owned by / already open
• Lista de proprietários: ≤ 8 linhas, piores primeiro (um 5xx ou uma cadeia de redirecionamento na navegação antes de uma descrição longa)
• Tabela CWV quando --cwv: caminho, LCP, CLS, INP, desempenho, origem
• Próximo: fix executa os itens na sexta-feira (ou /seo-agent:fix agora); a próxima auditoria é daqui a 3 meses

Regras rígidas

• Somente leitura no site: GET/HEAD com o user agent seo-agent-audit, uma origem, --max páginas, --delay entre requisições; nunca envie formulários, nunca faça login, nunca varra outro host
• Nunca edite artigos, layouts ou o sitemap; nunca abra um PR; escreva apenas em seo/data/crawl/ e seo/backlog.md
• Itens de backlog apenas para páginas de artigo que a skill fix pode editar; todo o resto é do proprietário
• Determinístico: as descobertas vêm do crawl.js; nenhuma descoberta é adicionada pela leitura manual do HTML
• thin nunca é um item de correção