convez.ai
AgenteAutomaçãoAvançado
nilssontsai

Enforcement Engineering

nilssontsai/enforcement-engineering

Enforce discipline em agentes via harness-layer hooks, não apenas prompts

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent que implementa disciplina em modelos de IA através de hooks executáveis e harnesses em vez de apenas prompts. Fornece camadas de enforcement (advisory, injected, enforced) para garantir que agentes Claude sigam regras no momento em que pensamento vira ação. Inclui loop de auto-improvement, validação de epistemologia e ponte para sessões live de Claude Code.

Instalação

$npx convez-ai nilssontsai/enforcement-engineering

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Validar ações de agentes antes de executar (deploy, bash, writes)
  • Implementar loops de auto-melhoria com medição e avaliação isolada
  • Gerenciar memória e estado de agentes com epistemologia auditável
  • Orquestrar sessões live de Claude Code com controle de harness

Veredito

Repositório de engenharia sólida para quem precisa de agentes confiáveis em produção. Implementa a tese de que disciplina deve estar na arquitetura (harness), não no prompt — abordagem pragmática e bem documentada, mas requer JavaScript/Node.js e entendimento profundo de arquitetura de agentes.

README

A tradução para o português deste README ainda está na fila.

Enforcement Engineering

You can't prompt an LLM into discipline — you have to enforce it.

This repo is the runnable companion to a three-post series on making AI agents reliable by engineering the harness — the scaffolding around the model — instead of writing ever-longer prompt rules the model can skip:

  1. You Can't Prompt an LLM Into Discipline — You Have to Enforce It — the thesis: advisory / injected / enforced tiers, and the principle of enforcing at the boundary where a thought becomes an action.
  2. Recursive Self-Improvement You Can Build Today — at the Harness Layer — Forge, a measure → propose → isolated-eval → human-gated merge loop.
  3. One Database, Two Writers — a war story about keeping an agent's memory honest.

(Links go live as the posts are published.)

The idea in three tiers

TierMechanismBinds because…
Advisorya rule in the promptthe model chooses to comply (weakest; decays as context fills)
Injecteda hook detects the relevant moment and injects the reminder right thentimely advice beats buried advice
Enforceda pre-action hook that can refuse the callthe model doesn't get a vote

The principle that keeps this from lobotomizing the agent: don't constrain the thinking — constrain the moment thinking becomes a durable artifact or an irreversible action. And the honest limit: a denylist is a fence, not a wall (allowlists fail closed; denylists fail open), and mechanical rules check form, not truth — know what each gate can honestly promise.

What's here

hooks/
  pre-bash-guard.js         # Tier 3: deploy/ssh must name a target; docker build
                            #   must name a platform; bash file-readers routed to
                            #   structured tools. Host vocabulary is configurable.
  pre-write-epistemics.js   # Tier 3: no unmarked "Root cause:" claims in markdown —
                            #   declare an epistemic status a human can audit.
  pre-claim-verify.js       # Tier 2: state-query prompts get a timely
                            #   "verify against live state first" injection.
  stop-failure-memo.js      # Feedback loop: repeated guard blocks at session end
                            #   prompt a written lesson (promote/demote sensor).
  settings.example.json     # Wiring + a deterministic permissions floor
                            #   (deny rules hold even when everything else is down).

forge/                      # The harness-RSI loop's measurement substrate:
                            #   generic grader, bench runner, example cases, and
                            #   the honesty rules that make the numbers mean
                            #   something. The propose/eval/merge stages are an
                            #   agent-executed procedure — see forge/README.md.

cc-relay/                   # Drive sibling *live* Claude Code tmux sessions:
                            #   send a prompt, wait, capture the reply. Zero setup
                            #   on the target side.

Install (Claude Code)

cp hooks/*.js ~/.claude/hooks/
# merge hooks/settings.example.json into ~/.claude/settings.json
# REQUIRED if you ssh via bare aliases (`ssh prod`): list them, or the guard
# won't recognize them as explicit targets (default accepts user@host /
# --context <ctx> / literal IPv4 only):
#   echo 'prod|staging-[a-z]+' >> ~/.claude/hooks/host-tokens.txt
cp -r forge ~/.claude/forge
install -m 0755 cc-relay/cc-relay.sh ~/.claude/scripts/cc-relay.sh

Everything fails open on errors — a broken guard must never brick the agent — and the genuinely destructive rules belong in permissions.deny, which is evaluated before any hook or mode and holds even when everything else is down.

Design rules these tools follow

  • Fail-open hooks, fail-closed permissions. Hooks are advisory infrastructure; the deterministic deny floor is where hard guarantees live.
  • Ask before deny. New gates ship as "ask", get audited via the journal for false positives, and are promoted to deny only with evidence.
  • Unattended-aware. Advisory "ask" gates auto-downgrade to allow-with-audit when CLAUDE_UNATTENDED=1, because an unanswerable prompt stalls a cron agent. Safety rules for unattended agents belong in the deterministic layers, not in advisory ones.
  • Every block is logged. The journal feeds the promote/demote loop: a rule that is neither practiced nor enforced is dead text.
Ver o original no GitHub

Bom para

Relacionados