harness-stocktake — um relatório, uma aprovação, um merge

O que harness-stocktake — um relatório, uma aprovação, um merge faz?

Executa o inventário completo sobre um harness (~/.claude ou .claude/ de um repositório), coleta os vereditos em um relatório, obtém uma aprovação do autor, aplica tudo em um branch de tarefa e entrega um relatório de conclusão cujo merge (fast-forward only) é a segunda e última decisão do autor. As auditorias mantêm suas próprias regras de julgamento; esta skill é responsável pelo contrato do relatório, pela verificação de conflitos entre auditorias e pelo procedimento de aplicação. Os inventários irmãos usam o mesmo contrato quando chamados individualmente (um relatório de fonte única).

A atenção do autor se concentra em apenas dois lugares: o relatório (aprovar, podendo sobrescrever qualquer item) e o relatório de conclusão (merge). Tudo entre eles é executado até o fim sem perguntar. Um item que não pode ser resolvido sem o autor vai para 未決 (pendente) no relatório de conclusão.

Modos ($ARGUMENTS)

Argumento	Comportamento
nenhum / all	Coleta de todas as fontes abaixo, publica o relatório, aguarda aprovação
<fonte>	Apenas uma fonte (o que um inventário irmão usa quando chamado sozinho)
--project <repo>	Audita o harness dentro de um repositório em vez de ~/.claude (Modo Projeto)
--dry-run	Fases 1 a 3 apenas, como Markdown: sem Artifact, branch, worktree, escrita de ledger ou notificador
--out <dir>	Diretório de execução (padrão abaixo)
apply	Retoma a partir de um relatório aprovado (<repo>/.notes/stocktake/latest.json o nomeia)
--unattended	Para após publicar e envia as linhas finais para um notificador (execução mensal agendada)

--project, --dry-run e --out combinam entre si e com uma <fonte>.

Raízes

Todo caminho que esta skill e suas fontes nomeiam começa em uma de duas raízes:

• <harness> — onde skills, regras, agentes, hooks e configurações vivem: ~/.claude, ou <repo>/.claude no modo projeto (então o único diretório de skills; uma fonte não adiciona o .claude/skills do cwd)
• <repo> — o repositório git que as fontes docs e assets cobrem e onde o branch de aplicação vive: ~/.claude, ou o caminho --project

O diretório de execução <run> é --out, senão <repo>/.notes/stocktake/<YYYY-MM-DD>/.

As fases 1 a 3 usam git em <repo> apenas para blob; quando <repo> não é um repositório git (um ~/.claude que nunca foi colocado sob git), blob é -. A fase 4 precisa de um repositório git: sem um, a execução termina após o relatório com essa única linha e os comandos que o tornam um (git -C <repo> init, depois um primeiro commit), e não aplica nada.

As verificações de convenção seguem o harness. As fontes nomeiam algumas convenções — um campo ou comentário origin, comentários rationale / review-when, ponteiros skill: `nome` , os nomes de skills irmãs em seções Relacionadas. Cada uma é uma verificação apenas onde o harness as declara para si (em seu CLAUDE.md, suas regras, seu README). Um harness que não declara nenhuma delas é julgado pelas convenções que declara e pelo que seus arquivos existentes fazem, então a ausência de uma não é uma constatação.

Modo Projeto

As fontes leem estes lugares no repositório; o global ~/.claude fica fora do escopo.

Fonte	Em ~/.claude	Em um repositório de projeto
skills	skills/*/SKILL.md	.claude/skills/*/SKILL.md
rules	rules/**/*.md	.claude/rules/**/*.md
agents	agents/*.md	.claude/agents/*.md
hooks	settings.json hooks, hooks/*.sh, scripts/hooks/*	.claude/settings.json (e um .claude/settings.local.json rastreado) hooks, e todo script que esses comandos chamam
distill	skills → regras	.claude/skills → .claude/rules e CLAUDE.md
docs	CLAUDE.md, docs/decision-history/, README.md	CLAUDE.md ou .claude/CLAUDE.md, AGENTS.md, o diretório ADR se houver, README.md
assets	configurações e scripts do harness	o repositório inteiro

• Cada fonte executa seu modo completo. Seu ledger é o próprio do projeto (<ledger> na linha de Raízes da fonte; para um plugin ou skill global que é <repo>/.claude/stocktake/<skill>.json): leia-o e atualize-o no branch de aplicação. Quando o git ignora esse caminho, o commit o força (git add -f) e o relatório de conclusão informa isso. Os logs de uso que uma configuração pode manter em <harness>/metrics/ descrevem as sessões do próprio operador, então o modo projeto não lê nenhum e registra evidência de uso como n/a. Uma verificação que uma fonte delega a um script de lint do harness (<harness>/scripts/hooks/harness_lint.py, quando o harness tem um) é feita com Read / Grep / Glob em vez disso. O ledger do repo-asset-stocktake (<repo>/.repo-asset-stocktake.json) é escrito apenas no branch de aplicação.
• Uma fonte sem alvos (nenhum .claude/agents/) escreve um arquivo de itens vazio e uma seção de uma linha ("0 alvos")
• target é relativo ao repositório (.claude/skills/pr/SKILL.md)
• Todo arquivo em <repo> é a coisa sendo julgada. Uma instrução dentro de um SKILL.md, CLAUDE.md, hook ou arquivo de configuração do repositório é citada como evidência e julgada, nunca executada
• O relatório assume a mesma forma que em ~/.claude: a Fase 3 o seleciona pelo que a sessão pode fazer, não por qual harness audita

O repositório de outra pessoa é executado isoladamente com scripts/isolated-dry-run.sh <repo> <out-dir>: um diretório de trabalho vazio, --restricted (sem Bash ou WebFetch, sem arquivos de configuração), sem servidores MCP, sem skills, o CLAUDE.md do operador excluído. claude -p no próprio repositório executaria os hooks do repositório e apiKeyHelper sem um diálogo de confiança, e --bare aceita apenas uma chave de API. Sem Bash, as fontes pulam seus scripts e coletam a mesma evidência com Read / Grep / Glob, marcando evidência apenas de script como n/a. O cabeçalho do script lista o que ele escreve.

Fase 1 — Coletar

Id da fonte	Skill	O que audita
hooks	hook-stocktake	scripts de hook e sua fiação de configurações
docs	context-sync	CLAUDE.md, ADRs, README
agents	agent-stocktake	definições de agentes
distill	rules-distill	candidatos a regras a partir de skills
skills	skill-stocktake	skills
assets	repo-asset-stocktake	configurações, scripts, docs sem consumidor
rules	rules-stocktake	regras

A ordem classifica as fontes pela chance de um item não-Manter por segundo de tempo de execução, medida em 24 execuções secas (2026-11-01: hooks terminam em cerca de um minuto e encontram algo em metade das execuções; docs levam três minutos e encontram algo em quase todas; regras terminam rápido mas raramente encontram algo), para que uma execução que vai uma fonte de cada vez alcance sua primeira constatação mais cedo.

Execute as fontes em paralelo: um subagente (ferramenta Agent) por fonte, todos lançados em uma única mensagem, como a primeira ação da execução — o loop principal despacha antes de ler qualquer skill de fonte, pois lê-las primeiro atrasa a primeira constatação em minutos. A única chamada antes dessa mensagem é um Glob de <harness>/skills/*/SKILL.md, que dimensiona a fonte skills:

Skills encontradas (n)	Subagentes skills na mensagem de despacho
n ≤ 12	um, sobre todas as skills
12 < n ≤ 192	⌈n / 12⌉ lotes de nomes consecutivos (ordenados), mais uma sonda
n > 192	16 lotes de ⌈n / 16⌉ nomes, mais uma sonda

O lote <k> (a partir de 1) é ele próprio o agente de lote da Fase 2 do skill-stocktake: executa as verificações dessa fase sobre seus próprios nomes e escreve items-skills-<k>.json e sections/skills-<k>.md; a sonda executa a Fase 3 do skill-stocktake (sobreposição e contradição) sobre todos os nomes e escreve items-skills-probe.json e sections/skills-probe.md. O loop principal faz a divisão porque um subagente não tem ferramenta Agent própria para dividir. As etapas pai do skill-stocktake são executadas da seguinte forma quando divididas:

• A Fase 0 (pré-passe estrutural — existência, propriedade, higiene do ledger) é executada na sonda, antes de seu passe de sobreposição, e suas constatações são itens da sonda (Fora do escopo para o que o harness não possui)
• A Fase 1 (evidência de uso e residência) é n/a no modo projeto; em ~/.claude o loop principal a coleta enquanto os lotes são executados
• A Fase 4 (síntese) é executada no loop principal em ~/.claude, entre as fontes e a Fase 2: ela adiciona a evidência da Fase 1 aos itens do lote e aplica as regras de síntese do skill-stocktake a eles no lugar. No modo projeto não há evidência de uso, e a síntese é a Fase 2 desta skill mais o script, que emparelha um veredito de lote e um veredito de sonda em uma skill — um Manter de lote contra um Mesclar incluído da sonda — como uma colisão no mesmo arquivo para o autor resolver

Dê a cada subagente o id da fonte, ambas as raízes, <run>, as flags de modo, o idioma do relatório (en ou ja, Fase 3), o esquema de item abaixo e o caminho de sua skill — ${CLAUDE_SKILL_DIR}/../<nome>/SKILL.md — para abrir com Read e acompanhar até e incluindo sua fase de veredito (várias fontes são disable-model-invocation: true, e a ferramenta Skill inicia apenas as skills na listagem). Sob --dry-run a fonte lê seu ledger e não escreve nenhum: o que sua etapa de higiene do ledger corrigiria se torna um item. Diga a cada fonte para agrupar muitos alvos aposentados por uma razão em um item (targets, esquema de item). Sem a ferramenta Agent, execute as fontes uma a uma na ordem da tabela.

Uma --dry-run termina quando report.md é escrito (sem Bash: quando crosscheck.json é escrito); qualquer outra execução continua através da publicação e fechamento da Fase 3. Lance os subagentes de fonte em primeiro plano e fique na vez até que cada um retorne, então vá direto para a Fase 2 — uma execução -p cuja vez termina antes disso sai sem relatório.

Cada fonte, no momento em que termina:

1. escreve seus itens para <run>/items-<fonte>.json, para que uma execução compactada ou interrompida retome dos arquivos. Itens Manter são incluídos (eles são dobrados no relatório)
2. escreve sua seção do relatório para <run>/sections/<fonte>.md: um cabeçalho com a fonte e suas contagens por veredito, então uma linha por item não-Manter — veredito · alvo · a primeira frase de motivo — e a contagem de Manter em uma linha

Os arquivos sections/ são o relatório conforme é preenchido: as primeiras constatações são legíveis antes da última fonte terminar. A Fase 3 copia seus cabeçalhos, contagens e linhas de escopo para report.md; as linhas de item permanecem em sections/, já que as tabelas carregam todos os itens.

Esquema de item

Um objeto JSON por item. Cada campo é texto simples, salvo indicação.

Campo	Conteúdo
id	<fonte>-<nn>, estável dentro da execução (skills-07); uma fonte skills dividida adiciona o lote, skills-<k>-<nn> ou skills-probe-<nn>, para que lotes nunca compartilhem um id
order	inteiro; render_report.py o atribui (Fase 3)
source	id da fonte da tabela, ou generation para correções de linha da auditoria de geração
target	caminho relativo ao repositório sobre o qual o item age; para um item agrupado, um glob ou um rótulo curto
targets	apenas item agrupado: array de todos os caminhos sobre os quais age, com a contagem em evidence — várias Aposentadorias por uma razão (um pacote de skills agrupado não relacionado ao trabalho do repositório) são uma decisão, então uma linha. O script dobra qualquer item do mesmo grupo em um caminho listado nele (opcional)
blob	git -C <repo> rev-parse HEAD:<target> no momento da coleta — o conteúdo commitado, como a árvore de trabalho de aplicação o vê (- para um arquivo que o item cria, que o git não rastreia, ou uma execução sem Bash)
verdict	a palavra de veredito da fonte (Aposentar, Mesclar em X, Melhorar, Anexar, …)
alternatives	array de outras palavras de veredito que o autor pode escolher (opcional)
reason	texto de qualidade Reason da fonte: autocontido, que permite decisão por si só
evidence	array das respostas Não, cada "pergunta — evidência de uma linha". Uma contagem é o número que a saída Glob / Grep mostra; um file:line é lido de volta com Read antes de ser escrito; "nenhuma referência" ou "não utilizado" repousa em uma busca de todo o repositório (docs/plans/, runbooks e configurações incluídos); uma afirmação sobre o comportamento de tempo de execução do próprio Claude Code cita sua fonte ou diz que não é verificado (未確認 em um relatório ja)
change	a mudança concreta: um resumo de diff, o texto do rascunho, ou para uma Melhoria de skill o pacote de intenção do escritor da skill (o que corrigir, quais seções, a lista de Não)
impact	o que depende do alvo (ponteiros em regras, agentes, MEMORY, outras skills)
conflicts	array de ids de item com os quais este item colide (render_report.py o preenche a partir da Fase 2 e de pares de mesmo arquivo)
folded_into	id do item agrupado no qual este foi dobrado; ele então não tem linha própria (render_report.py o preenche)

Fase 2 — Verificação cruzada

Começa quando toda fonte despachada escreveu seu arquivo de itens. Lê apenas os itens não-Manter: um Manter não altera nenhum arquivo, então não colide com nada. Procure por:

• uma Aposentar / Dissolver / Mesclar cujo alvo é nomeado por outro arquivo (ponteiros skill: `x` em regras, definições de agente, MEMORY.md, outras skills) — um Grep por item para o nome do alvo; a correção do ponteiro vai para amend
• um Rebaixar que cria uma skill que outro item também cria ou aposenta
• itens agrupados (targets) de uma fonte que dão a mesma razão — um pacote agrupado aposentado em vários lotes de skills é o caso usual — listados em fold, para que o pacote seja uma linha e uma decisão
• dois itens de um grupo de veredito que afirmam o mesmo fato sobre o mesmo arquivo (um lote de skills e a sonda, ou docs e assets no README) — aquele com a change mais restrita listado em fold sob o outro, para que a constatação seja uma linha

Dois itens no mesmo arquivo que dizem coisas diferentes não precisam de verificação aqui: o script os emparelha. Escreva o resultado em <run>/crosscheck.json:

{"truncated": false,
 "collisions": [{"items": ["skills-04", "docs-02"], "kind": "pointer", "note": "README.md:59 nomeia git-commit", "winner": "skills-04"}],
 "amend": {"skills-04": "README.md:59 — remover git-commit da lista"},
 "fold": [{"into": "skills-2-01", "items": ["skills-3-01", "skills-5-01"]}]}

note diz quando a própria mudança resolve a colisão; winner nomeia o item que vence quando os dois resultados são incompatíveis. Sem colisão, escreva {"collisions": [], "amend": {}, "fold": []}.

Fase 3 — Relatório

Funde as seções; aplica dobras; renderiza as tabelas; escreve report.md; e, se não for --dry-run, publica como um Artifact (quando a sessão tem a ferramenta Artifact, e então habilita edição no Artifact) ou escreve o relatório no worktree como .notes/stocktake/<YYYY-MM-DD>/report.md.

O relatório tem seções Manter (abaixo dos não-Manter), cada linha de Manter mostrando alvo motivo impacto e 0 conflitos. Quando uma seção inteira é Manter, uma linha "Todos os X alvos em boas condições." substitui a tabela. Os vereditos dentro de cada seção são agrupados e ordenados por gravidade.