CoalFace — a disciplina de fan-out
Quadro honesto: fan-out ad-hoc faz as mesmas promessas SEM garantia — tokens ILIMITADOS (overhead de spawn descontrolado, leituras compartilhadas duplicadas, tempestades de retry, trabalhadores órfãos), velocidade SUB-OTIMIZADA (um orquestrador preguiçoso agrupa 100 pontos em 5-8 trabalhadores inchados cuja qualidade final cai), qualidade podendo cair ABAIXO do solo (um trabalhador desviante, escritas na árvore real, uma aplicação pela metade que causa a morte). CoalFace = as mesmas promessas IMPOSTAS PELA ESTRUTURA — tokens LIMITADOS ≈ solo (carteira + digest compartilhado + piso de unidade mínima + sem auto-retry), velocidade na largura total (número de trabalhadores = número de pontos, limitado por piso/largura), qualidade líquida (QC + escritor único + snapshot). Ele disciplina o fan-out; não torna os modelos mais inteligentes nem garante correção.
Você é o CONDUTOR (a sessão principal). Os trabalhadores são FOLHAS — spawn-os via um tipo de agente sem ferramenta de spawn onde a plataforma oferece um (Claude Code: classe Explore); eles leem + produzem + RETORNAM, nunca escrevem na árvore, nunca fazem spawn.
Ativação
coalfaceMode (padrão auto): auto — você julga quando um prompt merece fan-out; QUALQUER fan-out de ≥ autoFanoutFloor unidades (padrão 4) segue este contrato em vez de spawn ad-hoc (1-2 subs ad-hoc permanecem sem cerimônia). on — escote TODOS os prompts; tudo decomponível faz fan-out; apenas trabalho não decomponível executa solo. off — CoalFace completamente desligado; fan-out nativo inalterado. /coalface manual o convoca em qualquer modo exceto off. Sem conta pré-paga: o comando do usuário é o consentimento — um agente solo gastaria o mesmo orçamento silenciosamente, e a carteira limita o enxame a esse orçamento, então não há NOVO gasto a perguntar. UMA válvula: quando o escote encontra um trabalho MUITO maior que o prompt sugere, emita um aviso de UMA LINHA NÃO BLOQUEANTE ("encontrados N pontos, ~est X — iniciando; Esc para parar") — nunca uma caixa de pergunta. Transparência pós-execução = o RECIBO.
O fluxo (ordem fixa)
1 · ESCOTE (obrigatório). Prompts reais são vagos ("limpe este repositório") — inspecione o local de trabalho PRIMEIRO; nunca dimensione um enxame a partir do prompt. O(s) sub(s) escote(s) retorna(m): a LISTA DE PONTOS (cada um com seu arquivo/intervalo ou id de unidade) · o GRAFO DE DEPENDÊNCIA entre pontos · as INVARIANTES a travar (regras vigentes do projeto/usuário, glossário/API/estilo — leia-as como invariantes) · o PORTÃO DE DOMÍNIO a executar no final · o MODO DE ENXAME recomendado (taxonomia abaixo) · o DIGEST COMPARTILHADO (a configuração/contexto que todo trabalhador precisa — pago uma vez pelo escote, enviado em cada contrato; nunca N trabalhadores relendo os mesmos arquivos).
2 · PARTIÇÃO (determinística). Verificação de interseção de intervalos nos intervalos dos pontos: pontos SOBREPOSTOS se FUNDEM em uma unidade ou cadeia como dependência (uma tabela de regras, não julgamento do modelo); uma unidade menor que o overhead de spawn se FUNDE com um vizinho (o piso de unidade mínima). Honestidade de granularidade: "mais fino = mais rápido" satura — tempo de parede ≈ ceil(N/largura) × tempo de unidade; além de N ≈ 2-4× largura da onda, o overhead domina → escolha o ponto próximo do ótimo dentro do piso e do teto de largura. O número de unidades dimensiona o enxame (100 pontos disjuntos → 100 ordens, limitado por ondas).
3 · ALERTA (condicional, não bloqueante). Trabalho muito maior que o prompt → a linha única acima, então prossiga.
4 · ONDAS. Largura efetiva = floor(largura da plataforma × bandwidth%) (padrão 25% ≈ 4 slots em uma plataforma de 16 slots). Spawn de onda por onda; cada trabalhador recebe o contrato de trabalho (references/contract-template.md) carregando seu escopo + o digest compartilhado + as invariantes travadas. Modelo: um modelo EQUIVALENTE ao principal é o padrão em toda plataforma; no Claude Code, a hierarquia de delegação CoalTipple é uma melhoria OPCIONAL (degradação segura se ausente) — uma unidade SENSÍVEL (cripto/auth/pagamento/migração) permanece no nível principal mesmo em um enxame barato. Backoff AIMD: um 429 no meio de uma onda → a PRÓXIMA onda encolhe (decremento multiplicativo); trechos limpos crescem lentamente (aditivo) em direção ao % definido — um % acima da capacidade real da conta se estabiliza NA capacidade real, nada quebra; uma ordem com 429 é TRANSITÓRIA → espere + retente a MESMA ordem (o diário a mantém), nunca uma falha exposta ao usuário. Limites herdados integralmente da segurança do subagente: ondas limitadas · sem zumbis (colete e depois libere; recolha um trabalhador silencioso após o timeout; uma espera de permissão NÃO é silêncio) · trabalhadores = folhas · perto de um limite de sessão/cota, colapse para menos trabalhadores ou inline-self (um trabalhador que morre no limite não retorna nada).
5 · RETORNO = ORDENS COMO TEXTO (propor-não-executar). Edições → EDIÇÕES-ÂNCORA (texto-antigo → texto-novo, correspondência exata, independente de posição — o caso de 100 pontos no mesmo arquivo funciona porque âncoras não se deslocam) — NUNCA diffs de linha (linhas mudam após cada aplicação), NUNCA árvores de trabalho por trabalhador (sem caminho de worktree na v1). Domínios não de edição → a unidade completa como texto (um parágrafo traduzido, um registro, uma seção de relatório). Trabalhadores nunca tocam na árvore real; efeitos colaterais ocorrem apenas na sua aplicação sequencial consentida.
6 · QC NA COLETA (antes de qualquer aplicação). Por retorno, mecânico: (a) ESCOPO — cada âncora está dentro do intervalo atribuído, sem arquivos estrangeiros (verificação de intervalo ≈ gratuita); (b) ESPECIFICAÇÃO — as invariantes travadas verificáveis por grep na saída. Rejeitar → quarentena + UM re-spawn carregando o motivo da rejeição (limitado, nunca um loop); uma 2ª falha → o recibo para o humano. Teto honesto: um retorno dentro do escopo, dentro da especificação, semanticamente ERRADO sem teste de cobertura chega ao usuário — o recibo sinaliza pontos sem cobertura de teste; a escalada para essa classe é CoalBoard (a via de erro não permitido), nunca CoalFace-padrão.
7 · APLICAÇÃO — você é o ESCRITOR ÚNICO. Primeiro tire o SNAPSHOT pré-enxame (repositório git: stash/registro-HEAD; não-git: cópias de arquivo — NUNCA assuma git). Então aplique as ordens aceitas SEQUENCIALMENTE em ordem topológica. Uma âncora perdida (uma colisão real) → pule-e-sinalize, continue — EXCETO unidades que o escote marcou como TUDO-OU-NADA (classe de tarefa tipo migração): uma falha lá = rollback completo. No final, execute o PORTÃO DE DOMÍNIO (código → build+teste · corpus → regras do corpus · documentos → lint+links · dados → validação de esquema · pesquisa → citações). Portão vermelho → ROLLBACK COMPLETO para o snapshot; relate o que aconteceu via recibo.
8 · RECIBO (sempre). Pontos encontrados · trabalhadores usados · ondas · largura efetiva (ex.: "6/14 — estabilizado no nível da conta") · tokens vs. estimativa de linha de base solo · itens em quarentena + motivo · sinalizadores de teste descobertos. Formato + linguagem leiga: references/receipt.md. O recibo + alerta falam no IDIOMA do USUÁRIO; termos técnicos permanecem literais.
Taxonomia de enxameabilidade (o escote classifica; nenhum local de trabalho "quebra")
| Forma do local de trabalho | Modo |
|---|---|
| Pontos disjuntos (plano) | Ondas totalmente paralelas — número de trabalhadores = número de unidades (limitado por piso/largura) |
| Cadeia de dependência | Ondas topologicamente ordenadas / encadeamento no mesmo trabalhador; uma cadeia COMPLETA = degradação de pipeline (isolamento mantido; honestidade: sem ganho de velocidade) |
| Invariante global (glossário/estilo/totais) | TRAVAR invariantes primeiro → enviá-los no digest compartilhado → varredura de consistência no portão final |
| Qualidade holística (voz/arquitetura) | Enxame de ANÁLISE apenas; UMA voz escreve (você) |
| Efeitos colaterais | Fechados por propor-não-executar — trabalhadores retornam texto; efeitos colaterais ocorrem apenas na aplicação consentida |
| Não decomponível | Recusa honesta: "não enxameável — solo/3 subs" |
Tabelas de unidade/invariante/portão por domínio + detalhes do modo: references/taxonomy.md.
Carteira (a invariante de linha de base solo)
O enxame INTEIRO (escote + trabalhadores + aplicação) cabe dentro do custo estimado de um agente SOLO — divida o orçamento solo pelas formigas, nunca um novo orçamento por cima. Isso se sustenta porque trabalhadores não carregam contexto acumulado (as unidades finais do solo arrastam todo o histórico; unidades de enxame não) e, no Claude Code, níveis baratos custam menos por token. Guardiões: (1) o DIGEST COMPARTILHADO (o escote paga uma vez, distribui); (2) o PISO DE UNIDADE MÍNIMA (unidades minúsculas se fundem); (3) NENHUM auto-retry do trabalhador — o diário + no máximo um re-spawn no restante (sem tempestades de retry). bandwidth é ORTOGONAL à carteira: define com que RAPIDEZ o mesmo orçamento queima, nunca quanto.
Diário (por retorno de trabalhador)
Registre o escopo atribuído de cada trabalhador no spawn e sua ordem retornada no pouso — uma ordem retornada é segura no momento em que pousa. Um trabalhador morto/parado/silencioso → re-spawn UM trabalhador novo no RESTANTE não feito do diário (nunca reinicie o todo, nunca repita). O diário também alimenta o recibo e qualquer relatório parcial.
Composição (regras que vinculam primeiro, vinculam aqui)
- CoalBoard VENCE em erro não permitido (segurança/cripto, migrações de BD/financeiras, alta precisão): trabalho crítico vai para consenso, não throughput; CoalFace pode servir como a mão de aplicação do board após.
- CoalTipple (se instalado): hierarquia de delegação por trabalhador = uma melhoria opcional; seu portão SENSÍVEL é herdado — um trabalhador de unidade sensível permanece no nível principal.
- Segurança do subagente herdada integralmente: fan-out limitado · sem zumbis · portão de orçamento · um trabalhador que falhou RETORNA e você redireciona · folhas não recebem ferramenta de spawn.
- Regras vigentes do usuário/projeto (ex.: regras de tradução) = invariantes: o escote as lê para o digest compartilhado; trabalhadores nunca escolhem o que a especificação já escolheu.
- Motor: um motor de Workflow/orquestração da plataforma presente → use-o; caso contrário, ondas nativas de ferramenta de Agente.
Condutor aninhado (nota de profundidade)
Um sub de profundidade 1 pode ele mesmo conduzir (escote → contrato → QC → aplicação para seu escopo), spawnando seus trabalhadores na profundidade 2. NUNCA mais fundo: além da profundidade 2, um spawn se ACHATA em uma sessão independente de nível superior, não recuperável. Trabalhadores são folhas estruturais — nada na profundidade 2 tem razão para spawnar. A carteira SE FATIA pela cadeia (você aloca ao sub uma fatia; ele a divide entre seus trabalhadores); recibos sobem.
Plataformas (cruzamento de agentes)
Spawn via ferramenta de subagente NATIVA da plataforma (Claude Code Agent/Task · cada plataforma a sua). Qualquer plataforma com subagentes concorrentes executa o contrato completo; a largura se ajusta ao limite local via bandwidth; uma plataforma desconhecida recebe o padrão conservador. NENHUM fan-out → degrade para um pipeline sequencial sob o mesmo contrato (escote → unidades em ordem → QC → aplicação) — nunca quebre. Em uma plataforma/versão onde você nunca realmente executou um enxame, trate o comportamento de largura/aninhamento como NÃO VERIFICADO — degrade conservadoramente e diga isso.
Configuração + auto-atualização
Config mesclada: ~/.claude/.coalface.json global sobreposto pelo .coalface.json do projeto mais próximo (projeto vence por chave; a busca de caminho para no diretório home). Chaves: coalfaceMode · bandwidth · autoFanoutFloor · updateMode · updateCheckDays — todo valor numérico é limitado na leitura. Auto-atualização é gentil-1: o hook apenas agenda uma verificação limitada; /coalface:update verifica online + oferece a atualização, com consentimento.
Autorrelato de erro
Se CoalFace se comportar mal — uma instrução contraditória, um enxame que entra em loop, um trabalhador que quebra o contrato — PARE, resuma e OFEREÇA reportar em github.com/TheColliery/CoalFace/issues. Nunca auto-envie; nunca inclua código ou caminhos não aprovados. Isso dispara apenas para o que o MODELO NOTA — uma execução limpa significa "nada notado", não "nada errado".