🧾 Subagentes, manifesto e falhas

No kit, você não roda os coletores à mão um por um: chama a skill /<slug>-coletar e o Claude Code faz a fase 1. A instrução central da skill é "um subagente por fonte, em paralelo". Cada subagente usa só o coletor do seu tipo, devolve uma linha de resultado e some. A sessão principal não se enche de saída de download; ela só junta os resultados e roda o stats.py no fim.

O manifesto é a lista oficial do acervo. Cada coletor, ao terminar uma fonte, acrescenta um item. Este é um item real do mentor do Nei, exatamente como está no arquivo:

{
  "id": "guia-maestro-roteador-triagem-de-modelo-e-esforco-para-ded1b",
  "tipo": "guia",
  "url": "https://inematds.github.io/maestro-roteador/guia/",
  "titulo": "maestro-roteador — triagem de modelo e esforço para Claude Code",
  "arquivo": "raw/guia/maestro-roteador-triagem-de-modelo-e-esforco-para--ded1bc.md",
  "coletado_em": "2026-10-05",
  "palavras": 1418,
  "sha256": "b8540f7c45b432d3779817b05f659e1a84a82a9d46c33d38a00d8ecc0b351039"
}

python3 - <<'EOF'
import hashlib, json
for i in json.load(open("raw/MANIFESTO.json")):
    atual = hashlib.sha256(open(i["arquivo"], "rb").read()).hexdigest()
    print("ok   " if atual == i["sha256"] else "MUDOU", i["palavras"], i["arquivo"])
EOF

Uma coleta que só mostra sucessos esconde o que ficou de fora. Por isso todo coletor, ao falhar, escreve uma linha em raw/RELATORIO-FALHAS.md: data, tipo, origem e motivo. O relatório do piloto tem uma única linha, e ela conta uma história inteira:

# Relatório de falhas da coleta

| data | tipo | origem | motivo |
|---|---|---|---|
| 2026-10-05 | video | https://www.youtube.com/watch?v=Zb8TRf97zt8 | sem legenda |

"Acho que já coletei bastante" não é critério. No kit, a fase 1 está pronta quando python3 tools/stats.py sai com exit 0. As metas ficam em metas_coleta no config, por tipo, em itens e em palavras. As do piloto eram estas:

"metas_coleta": {
  "video": { "itens": 10, "palavras": 60000 },
  "guia":  { "itens": 5,  "palavras": 8000 }
}

A fase 1 do piloto, hora a hora

tipo          itens   palavras   meta
guia              6       7269   ≥5 itens / ≥8000 pal.
video            13     169937   ≥10 itens / ≥60000 pal.
TOTAL            19     177206

REPROVADO:
  - meta não batida em 'guia': faltam 731 palavras

No kit 1.1, a skill mandava coletar com um subagente por fonte em paralelo. Na sessão do piloto, o agente não obedeceu — e estava certo. Ele leu _comum.py, viu que registrar_item lia o manifesto inteiro, acrescentava um item e regravava o arquivo, sem trava nenhuma. Rodou os coletores em sequência e explicou o porquê. O diário marcou: "paralelo perderia entradas".

O kit 1.2 corrigiu com duas proteções em _comum.py: uma trava de arquivo (fcntl.flock em raw/.manifesto.lock) em volta do ler-alterar-gravar, e escrita atômica: grava num arquivo temporário e troca de uma vez com os.replace, para que ninguém leia um manifesto pela metade. O trecho real:

def _gravar_atomico(destino: Path, conteudo: str) -> None:
    fd, tmp = tempfile.mkstemp(dir=destino.parent, prefix=".tmp-", suffix=destino.suffix)
    with os.fdopen(fd, "w", encoding="utf-8") as f:
        f.write(conteudo)
    os.replace(tmp, destino)

# dentro de registrar_item(...)
    with trava(raiz):
        itens = [i for i in ler_manifesto(raiz) if i.get("arquivo") != rel] + [item]
        _gravar_atomico(raiz / "raw" / "MANIFESTO.json", json.dumps(itens, ensure_ascii=False, indent=2) + "\n")

python3 novo-mentor.py teste --nome x --dominio y --destino /tmp/paralelo
cd /tmp/paralelo/mentor-teste
for i in $(seq 1 12); do yes "texto $i" | head -50 > /tmp/paralelo/f$i.txt; done
for i in $(seq 1 12); do python3 tools/coletar_arquivo.py /tmp/paralelo/f$i.txt --tipo notas & done; wait
python3 -c "import json;print(len(json.load(open('raw/MANIFESTO.json'))))"

Às 16:05, a transcrição local da live sem legenda funcionou: 8.045 palavras em 7,7 minutos. Mas o arquivo foi salvo como raw/videos/transcript.txt — o nome que o transcritor deu, não um nome do vídeo. Na próxima live transcrita, o transcritor geraria outro transcript.txt, o coletor gravaria por cima, e o manifesto trocaria o item antigo pelo novo (lembre: o arquivo é a chave de atualização). Uma fonte sumiria sem aviso. O diário marcou gravidade alta.

A correção é uma linha de coletar_video.py, com o comentário que conta a história:

# nome pelo vídeo (título + id), nunca pelo arquivo do transcritor: "transcript.txt" sobrescrevia o anterior
titulo = titulo or info
sufixo = vid or hashlib.sha1(url.encode()).hexdigest()[:8]
destino = raiz / "raw" / "videos" / f"{slugificar(titulo, 50)}-{re.sub(r'[^A-Za-z0-9_-]', '', sufixo)[:20]}.txt"

ls raw/videos | grep -Ei '^(transcript|output|audio|video|legenda)[^a-z]*\.(txt|srt|vtt)$' \
  || echo "nenhum nome genérico"