reins — deixe ao quest CLI apenas o domínio, o ratchet vira framework

reins — deixe ao quest CLI apenas o domínio, o ratchet vira framework Image: AI generated

how-make-quest ensinava a construir um quest CLI com as próprias mãos. O que é o ratchet, como pendurar o gate, como bloquear o cheese. Você dá um único texto ao agente e sai um CLI em Go baseado em cobra.

Mas o que acontece quando você constrói o segundo quest CLI. Você reescreve a mesma máquina de estados unidirecional. Reescreve o mesmo scan/next/submit/status/export. Reescreve o mesmo bloqueio de PASS, o mesmo decréscimo monotônico de remaining, o mesmo export JSONL. O que muda é só o gate, e mesmo assim você reescreve todo o resto a cada vez. Esse é o imposto de boilerplate que se paga a cada novo quest construído.

O padrão era reutilizável. O código não era. reins fecha essa lacuna.

O que é invariante e o que é domínio

Sobreponha dois quest CLIs e olhe a diferença (差分): a fronteira fica nítida.

invariante (todo quest compartilha)       domínio (varia por quest)
─────────────────────────────────         ─────────────────────
ratchet: TODO→PASS irreversível            o que é um quest
esqueleto de comandos: scan/next/submit…   o que é um "fato"
agregação de nível: Fail/Review→verdict    qual cheese precisa ser bloqueado
progresso persistente·resumable
export: emissão única

A esquerda é exatamente o que how-make-quest provou — seja o domínio um nome de empresa, um endpoint ou uma função, o dente do ratchet engata igual. Só a direita o ser humano conhece. reins fornece a esquerda como framework e deixa a você apenas a direita.

Isto não é uma afirmação nova, mas um princípio antigo que reins impõe em código — a separação entre decisão e implementação. O gate é a decisão (o que é verdadeiro neste domínio), e o ratchet, o CLI e a agregação são a implementação. Reescrever a implementação a cada vez é o fracasso de atar a decisão à implementação.

Implementa-se apenas o gate

Fazer um quest com reins é preencher os quatro métodos de uma única interface.

type Definition interface {
    Seed(args []string) ([]*quest.Item, error)            // entrada → seeds iniciais de TODO
    Render(it *quest.Item) (string, error)                // prompt de criação + contexto de verificação que next exibe
    Prepare(it *quest.Item, raw []byte) (gate.Context, *quest.Verdict, error) // decodifica a submissão
    Rules() []gate.Rule                                   // catálogo de regras de violação do gate
}

func main() { cli.NewQuestCmd("myquest", myDef{}, cli.Options{}).Execute() }

Uma linha de main fornece o ratchet, os seis comandos, a agregação, o export e a sessão resumable inteira. O que você escreveu foram apenas quatro pedaços de domínio. O agente ainda só precisa conhecer dois comandos — recebe com next e entrega com submit. O resto a máquina decide.

O gate é um catálogo de regras de defesa contra o cheese

O cerne de how-make-quest era “projete um gate à prova de cheese”. reins transforma esse projeto em estrutura de dados — gate = catálogo de regras. Uma regra é um detector de cheese. Ao encontrar uma violação, dispara (true) e carrega um fato (Fact).

// Uma regra de defesa contra o cheese de um quest de extração de eventos de notícias.
// "o who-anchor existe de fato no original" — se o agente inventa uma pessoa, é flagrado.
var whoAnchorPresent = gate.Rule{
    Meta: gate.RuleMeta{ID: "who-anchor-present", Level: gate.LevelFail, Desc: "o who-anchor obrigatório existe no original"},
    Check: func(ctx gate.Context) (bool, quest.Fact) {
        sub := ctx.Submission.(*Event)
        if miss := textmatch.MissingTokens(ctx.Source, sub.Who.Anchors); len(miss) > 0 {
            return true, quest.Fact{Where: "who.anchors", Expected: "substring do original", Actual: miss[0]}
        }
        return false, quest.Fact{}
    },
}

A virtude dessa estrutura é que ela cresce. A cada novo cheese descoberto, você adiciona uma regra e o gate fica mais sólido nessa medida. E o catálogo se documenta a si mesmo — quando o comando rules imprime a lista de regras, isso é a “lista auditável do cheese que estou bloqueando”. Não existe gate que não saiba o que bloqueia.

A severidade não é um peso, mas um nível. Um único Fail já é FAIL. A violação decisiva não se negocia — nove violações de 99 pontos não cobrem um único Fail. Evaluate agrega as regras disparadas por nível: se houver qualquer Fail, FAIL; senão, se houver Review, REVIEW; se tudo passar, PASS.

Impõe-se a assimetria de autoridade por tipo

A linha mais importante de how-make-quest era “só a máquina trava o PASS”. reins crava isso não como convenção, mas como tipo.

L1 máquina (determinismo)   a única autoridade para travar o PASS
L2 IA (cética)              só REVIEW — levanta a suspeita, mas não concede a conclusão
L3 pessoa                   o resíduo que ambos deixaram passar

O gate de máquina emite PASS. Mesmo que você coloque um verificador de IA no gate, o máximo que ele pode fazer é tirar para REVIEW. Torna-se a coisa errada impossível desde o início — se o framework não fornece à IA uma API que conceda autoridade de PASS, você não pode, nem por engano, deixar o julgamento nas mãos de um amigo bêbado.

O segundo backend — o defeat graph

Para muitos gates, basta a agregação de nível de regras independentes. Mas, quando as regras começam a competir entre si — “esta violação só faz sentido na presença daquela”, “a causa-raiz desta falha é, na verdade, aquela” —, guardas if-else escritas à mão corroem o gate. Não é onde o gate fraco quebra, mas onde o gate complexo apodrece.

O segundo backend de gate de reins transfere essa competição para um grafo declarativo — toulmin h-Categoriser. O modelo de argumentação de Toulmin vira a própria estrutura de dados:

Warrant — tautology PASS. O fundamento de “se não há refutação, passa”.
Counter — uma violação ataca o warrant.
Supersedes — prioridade entre regras. Qual refutação vence qual refutação.

As cláusulas de guarda escritas à mão evaporam em arestas Attacks·Supersedes. E, com 0 arestas, este grafo é exatamente equivalente à agregação de nível — a complexidade é um custo que só liga quando necessário (opt-in) (liga quando Definition implementa gate.Evaluator).

O verdadeiro presente do grafo não é o veredicto, mas o feedback. A avaliação do grafo devolve ao agente um guia de estratégia direto — Verdict.Feedback: “por que perdeu, e o que mudar para vencer.” Não um mero “FAIL”, mas a causa-raiz calculada a partir da estrutura do argumento.

Aqui o paradoxo de how-make-quest opera de novo. O modelo bajula — segue dócil as instruções. Na opinião a bajulação é veneno, mas no fato a bajulação é um ativo. O guia de estratégia não é opinião (“isto está meio estranho”), mas fato (“who.anchors não está no original, mude isto”). Quanto mais bajulador o modelo, mais dócil aceita esse fato e converge. Grafo determinístico + LLM bajulador = um loop com convergência garantida.

Os efeitos colaterais ficam isolados — ground e avaliação staged

Para que o gate seja determinístico, a rede não pode estar dentro do gate. Uma regra que chama net/http diretamente é impossível de testar unitariamente, e o julgamento oscila conforme as condições da linha.

reins empurra os efeitos colaterais para pkg/ground — primitivas como HTTPBody·MXResolves que possuem a consulta externa por meio de um Resolver injetável e de um snapshot por requisição. A regra permanece pura, e o mundo externo é responsabilidade de ground.

E a avaliação staged: as checagens baratas rodam primeiro e, se falharem, o fetch de rede simplesmente não acontece. Não há razão para consultar o DNS numa submissão de formato errado. Coloca-se o caro e instável atrás do barato e certeiro.

Proibida a abstração N=1

Uma das convenções de reins revela com a maior precisão o caráter deste framework — não extraia uma abstração de um único consumidor. Uma nova abstração só é congelada depois de validada por um segundo consumidor.

Isto não é exigência, é primeiro princípio. A abstração extraída de um único caso confunde o acaso daquele caso com a essência. Só quando um segundo domínio exige a mesma abstração é que se prova que ela é invariante. O framework aplica “não a afirmação, mas a verificação” até à própria evolução. Assim como o gate não acredita na afirmação do agente, a abstração não acredita na afirmação de um único caso.

A mesma frase, virada biblioteca

reins se ergue sobre os sete pacotes de pkg/ — textmatch (primitivas anti-alucinação), temporal (normalização temporal), quest (núcleo do ratchet), gate (contrato do gate), graph (defeat graph), ground (isolamento de rede), cli (scaffold em cobra). Passa em go build·go test, com cobertura de todas as funções. E toulmin está acoplado unidirecionalmente apenas ao backend de grafo, de modo que um consumidor que não use o grafo nem chega a linkar toulmin.

Código: github.com/park-jun-woo/reins

Se how-make-quest foi uma única frase — a geração pode ser probabilística, a verificação deve ser determinística — reins é essa frase solidificada numa forma compilável. O gate reverifica os fatos do domínio, o ratchet trava o que passou, o grafo devolve em fato a razão da derrota, e o modelo bajulador se conforma a esse fato.

Da próxima vez que precisar de um quest CLI, não reescreva o ratchet. Escreva só o gate do seu domínio, e tome emprestadas as rédeas.

Leituras complementares

O princípio que reins solidificou em código — a geração é probabilística, a verificação deve ser determinística — não é uma descoberta só de reins. Pessoas que não se conheciam bateram no mesmo muro e chegaram à mesma conclusão. Os projetos de convergência independente reunidos por how-make-quest são a prova disso.

episteme — força uma Reasoning Surface antes de operações irreversíveis. A mesma intuição do ratchet de reins — o PASS verifica antes de travar.
MagLab — “o LLM só raciocina, os números ficam com a ferramenta determinística”. A mesma separação com que reins isola os efeitos colaterais em pkg/ground.
Manifesto — “Agent proposes, World verifies.” Resume numa frase a assimetria de autoridade de reins (só a L1 trava o PASS).
oh-my-kamisama — “diffs beat claims.” O mesmo princípio de o gate reverificar o fato, e não a alegação, do agente.

E a raiz do backend de defeat graph é a teoria da argumentação — a linhagem Toulmin·Dung·Amgoud das referências abaixo. O pkg/graph de reins é essa lógica formal de mais de 60 anos transposta para estruturas de dados em Go.

Referências

Toulmin, S. (1958). The Uses of Argument. Cambridge University Press. — o modelo de argumentação de onde o defeat graph extraiu, tal e qual, Warrant·Ground·Backing.
Dung, P.M. (1995). “On the Acceptability of Arguments and its Fundamental Role in Nonmonotonic Reasoning, Logic Programming and n-Person Games.” Artificial Intelligence, 77(2), 321–357. — a fonte original do framework de argumentação abstrato e do grafo de attack (defeat).
Amgoud, L. & Ben-Naim, J. (2013). “Ranking-based semantics for argumentation frameworks.” SUM 2013, LNCS 8078, 134–147. — o weighted h-Categoriser adotado por pkg/graph. A propriedade de Compensation, em que um nó atacado recupera aceitabilidade ao ser defendido de novo, e a garantia de convergência.
Nute, D. (1994). “Defeasible Logic.” In Handbook of Logic in Artificial Intelligence and Logic Programming, Vol. 3. Oxford University Press. — a classificação strict/defeasible/defeater. A raiz formal dos níveis de regra de reins (Fail/Review) e da prioridade Supersedes.
Modgil, S. & Prakken, H. (2014). “The ASPIC+ Framework for Structured Argumentation: A Tutorial.” Argument & Computation, 5(1), 31–62. — o sistema de argumentação que estrutura a classificação de Nute dentro do framework de Dung. A genealogia do defeat graph.
Gabriel, V.O. et al. (2020). “Reasoning in BDI agents using Toulmin’s argumentation model.” Theoretical Computer Science, 805, 76–91. — um precedente que implementou o modelo de Toulmin em software (agentes BDI). O pkg/graph de reins o transpõe para o julgamento do gate.
Von Neumann, J. (1956). “Probabilistic Logics and the Synthesis of Reliable Organisms from Unreliable Components.” Automata Studies, Princeton University Press. — o princípio de erguer um protocolo confiável sobre componentes instáveis (a premissa de reins).
Stechly, K., Valmeekam, K., & Kambhampati, S. (2024). “On the Self-Verification Limitations of Large Language Models.” arXiv:2402.08115 — a auto-verificação quase não eleva o desempenho → a razão de a autoridade de PASS ficar na máquina L1.
McKee-Reid, L. et al. (2024). “Honesty to Subterfuge: In-Context RL Can Make Honest Models Reward Hack.” arXiv:2410.06491 — mesmo um modelo honesto manipula a função quando julga a própria recompensa → o fundamento da assimetria de autoridade.
Bondarenko, A. et al. (2025). “Demonstrating Specification Gaming in Reasoning Models.” arXiv:2502.13295 — quanto maior a capacidade, melhor se encontram as brechas do gate → a razão de o gate=catálogo de regras precisar crescer.
Thaman, K. (2026). “Reward Hacking Benchmark: Measuring Exploits in LLM Agents with Tool Use.” arXiv:2605.02964 — endurecer o gate intencionalmente reduziu os exploits em 87,7%.
Fanous, A. et al. (2025). “SycEval: Evaluating LLM Sycophancy.” AAAI/ACM AIES 2025. arXiv:2502.08177 — medição da taxa de capitulação por bajulação. Os dois lados de “no fato, a bajulação é um ativo”.
Shapira, I. et al. (2026). “How RLHF Amplifies Sycophancy.” arXiv:2602.01002 — o teorema de que o RLHF amplifica a bajulação. A premissa do loop de convergência feedback de fato + bajulação.
Deque Systems (2021). “Automated Testing Study Identifies 57 Percent of Digital Accessibility Issues.” — a fronteira entre a área julgável por máquina (57%) e o resíduo humano (20%).

Relacionados

Como criar um Quest CLI — a metodologia que reins solidificou em framework. Do princípio (por quê) ao esqueleto de comandos (como).
Reins Engineering — a IA com rédeas — o harness é a cerca, o quest são as rédeas. A separação entre decisão e implementação que reins cravou em código.
Ratchet Pattern — como fazer o agente ir até o fim — a obra principal sobre o bloqueio unidirecional·decréscimo monotônico que pkg/quest implementa.
toulmin — o motor de regras que computa o contrato — o h-Categoriser do backend de defeat graph. Trata a afirmação não como fato, mas como claim refutável.
Triplas não são fatos, são afirmações — um caso de aplicação do mesmo motor de argumentação a grafos de conhecimento. Outro palco para Warrant·Counter·Supersedes.
huma — o ratchet que não pula endpoints — uma instância de domínio que preencheu os quatro métodos de Definition. A prova de que basta trocar o gate para virar outra ferramenta.
Topologia de feedback acima do QI do modelo — o que decide o resultado não é o modelo, é a estrutura do feedback. O pano de fundo teórico do guia de estratégia que o grafo devolve.
Pré-condições para melhorar a precisão de multiagentes LLM — por que a verificação por IA L2 só funciona se tiver independência. O fundamento teórico da assimetria de autoridade.

Changelog

2026-06-05: Versão inicial