convez.ai
AgenteAutomaçãoAvançado
hchava

Anvil – Agente de Código IA com Gates Determinísticos

hchava/anvil

Código IA confiável: determinístico, auditável, testado antes de commitar

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent harness que envolve Claude Code e Codex em um controlador determinístico com validação por schema, ledgers de evidência, worktrees isoladas e gates de qualidade. Transforma workflows de código assistido por IA em processos auditáveis com testes obrigatórios, planos de rollback e escalonamento humano.

Instalação

$npx convez-ai hchava/anvil

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

  • Garantir qualidade de código gerado por Claude/Codex antes de merge
  • Implementar workflows de engenharia com validação e evidence gates
  • Automação de tarefas de código com determinismo e rastreabilidade total
  • Escalonamento humano em loops de revisão crítica de IA

Veredito

Anvil resolve um problema real e crítico: confiabilidade de agentes de código em produção. Excelente para engenheiros que já usam Claude Code/Codex mas precisam de governança, auditoria e gates determinísticos antes de executar mudanças. Projeto bem arquitetado, status estável (Milestone 3 concluído), mas ainda em desenvolvimento ativo para modo paralelo.

README

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

Anvil

Where AI-generated code gets hardened before it ships.

Anvil is an evidence-gated agent harness for reliable AI-assisted engineering. It wraps Claude Code, Codex, and future coding agents inside a deterministic controller with schema gates, evidence ledgers, scoped worktrees, validation commands, and human-in-the-loop escalation.

This project is a clean-room public version of a Claude Code + Codex collaboration pattern used extensively in production engineering workflows. It contains no proprietary code, prompts, data, or internal system details.


Why Anvil?

AI coding agents are powerful but unreliable at scale. They hallucinate references, overlook edge cases, rubber-stamp their own work, and silently degrade when context windows fill up.

Anvil addresses this by treating LLMs as reasoning workers inside a deterministic control plane — not as the runtime authority. Every claim needs evidence. Every plan gets cross-validated. Every gate is enforced by code, not by model agreement.

The core principle: no claim, plan, or code change advances unless it satisfies deterministic gates, evidence thresholds, guardrail compliance, test passage, and unresolved-issue closure.

Current Status

  • ✅ Milestone 0: Schema fixtures and validation foundation
  • ✅ Milestone 0.5: Local runtime registry and controller state model
  • ✅ Milestone 1: Deterministic controller dry run
  • ✅ Milestone 2: Claude/Codex contract loop
  • ✅ Milestone 3: Single work-order execution
  • 🚧 Milestone 4: Standard Mode MVP
  • ⏳ Milestone 5: Parallel work orders and merge protocol
  • ⏳ Milestone 6: Critical Mode expansion

Why this matters

Modern AI coding agents can generate code quickly, but production teams still need evidence, tests, rollback plans, scoped execution, and reviewable decisions. Anvil turns AI-assisted development from an open-ended chat workflow into an auditable engineering workflow.

It is designed for developers who use Claude Code, Codex, or similar coding agents but want deterministic quality gates before trusting AI-generated changes.


Architecture

User Task
   │
   ▼
┌─────────────────────────────────────────────────────┐
│              Deterministic Controller                │
│                                                     │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────┐  │
│  │   SQLite     │  │ JSON Schema  │  │ Worktree  │  │
│  │  Registry    │  │    Gates     │  │  Manager  │  │
│  └─────────────┘  └──────────────┘  └───────────┘  │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────┐  │
│  │  Command     │  │ Validation   │  │  Event    │  │
│  │   Policy     │  │   Runner     │  │   Log     │  │
│  └─────────────┘  └──────────────┘  └───────────┘  │
└──────────────────────┬──────────────────────────────┘
                       │
            ┌──────────┴──────────┐
            ▼                     ▼
     Claude Worker          Codex Validator
     (research, plan,       (blind-spot scan,
      execute, review)       cross-validation,
                             commit review)
            │                     │
            └──────────┬──────────┘
                       ▼
                  Work Orders
            (scoped, negotiated,
             with acceptance criteria)
                       │
                       ▼
               Scoped Execution
            (per-run worktrees,
             file locking, leases)
                       │
                       ▼
            Validation + Scorecard
            (baseline diff, tests,
             linters, secret scan)

Runtime Model

Installation
  └── Project
        └── Repo Binding
              └── Task Scope
                    └── Run
                          └── Work Order
                                └── Lease

A project is not a repo. A repo is a shared resource. A task scope is a bounded operating area inside a repo. Two different projects can safely use the same repo.


What makes Anvil different?

Most AI coding tools focus on generation. Anvil focuses on trust.

  • LLMs are workers, not runtime authorities
  • Every accepted claim must cite evidence
  • Disagreements become structured issues, not chat arguments
  • Code changes execute only through scoped work orders
  • Validation is deterministic: tests, linting, type checks, secret scans, baseline diffs
  • Every run produces reviewable artifacts and a scorecard

Key Concepts

Deterministic Controller

The controller is a state machine that owns all gate transitions, schema validation, file locks, test execution, retries, and scoring. LLMs propose; the controller decides.

Evidence Ledgers

Every research claim must cite specific evidence — file paths, line ranges, commit SHAs, content hashes. Claims without evidence cannot pass gates.

Issue-Based Debate

Disagreements between Claude and Codex become tracked issues with severity levels, evidence requirements, and closure criteria — not open-ended prose debates.

Negotiated Work Orders

Before any code is written, Claude and Codex co-negotiate atomic work orders with allowed files, forbidden files, acceptance criteria, validation commands, and rollback plans.

Risk-Routed Modes

Not every task needs the full adversarial pipeline. A numeric risk score routes tasks to Fast, Standard, or Critical mode — matching rigor to complexity.

ModeWhenPipeline Depth
FastConfig tweaks, typo fixes, simple refactorsLightweight plan → execute → validate
StandardNormal feature work, moderate refactorsFull research → review → negotiate → execute → validate
CriticalProduction-critical, security-sensitive, cross-system changesFull adversarial pipeline with human escalation

Anti-Rationalization

LLM evaluators consistently identify problems then talk themselves into approving anyway. Every evaluator agent in Anvil receives explicit instructions: "If a criterion is unmet, fail it. Do not rationalize. Approval requires criterion-by-criterion evidence."


Quick Start

Anvil is in active development. The CLI below shows the intended developer experience; package installation will be enabled in an upcoming milestone.

# Planned package name
pip install anvil-harness
# Initialize local installation
anvil init
# Register a repo
anvil repo register --path /path/to/your/repo --name my-service
# Create a project
anvil project create --name my-feature --repo my-service
# Run the harness
anvil run --project my-feature --task "Add input validation to the config parser"
# Check status
anvil status
# View active leases
anvil leases --repo my-service
# Health check
anvil doctor

Pipeline Layers (Critical Mode)

LayerNamePurpose
-1Run InitCreate workspace, capture baseline, allocate worktree
-0.5Task ContractDefine goals, non-goals, constraints, acceptance criteria
0Source DiscoveryDeterministic tools first, then LLM semantic expansion
0.5Gap AnalysisStructured coverage matrix — are sources sufficient?
1Deep ResearchClaim ledger with evidence references
1.5Codex Blind-Spot ScanIndependent research catches Claude's blind spots early
2Claim Stress TestWhy-chain + counter-evidence search + executable validation
3Cross-ValidationIssue-based debate with severity and closure criteria
4Implementation PlanningTranslate research into actionable plans
5Specialized Review5-agent panel: correctness, performance, security, quality, integration
5.5Work-Order NegotiationClaude and Codex co-produce atomic execution specs
6ExecutionScoped code generation in isolated worktrees
7Commit ReviewCodex review + deterministic validation + baseline diff

Core Artifacts

Every run produces structured, schema-validated JSON artifacts:

ArtifactPurpose
run_manifest.jsonImmutable run metadata — models, commit, mode, prompt versions
task_contract.jsonGoals, non-goals, constraints, acceptance criteria
source_manifest.jsonAll discovered sources with freshness metadata
claim_ledger.jsonResearch claims with evidence, counter-evidence, confidence
issue_ledger.jsonTracked disagreements with severity and closure status
guardrail_matrix.jsonApplicable guardrails with pass/fail status
execution_work_orders.jsonAtomic execution tasks — co-negotiated by Claude and Codex
validation_results.jsonCentralized test/lint/type-check results
run_scorecard.jsonPer-run metrics for measurement and pruning
event_log.jsonlAppend-only audit log of all pipeline events

Project Status

Anvil is in active development. See the roadmap for the full build plan.

MilestoneStatusDescription
0✅ CompleteSchema fixtures and validation foundation
0.5✅ CompleteLocal runtime registry and controller state model
1✅ CompleteDeterministic controller dry run
2✅ CompleteClaude/Codex contract loop
3✅ CompleteSingle work-order execution
4🚧 NextStandard Mode MVP
5⏳ PlannedParallel work orders and merge protocol
6⏳ PlannedCritical Mode expansion
7⏳ PlannedTeam mode — artifact export and PR integration
8⏳ PlannedMeasurement and pruning

Design Philosophy

Anvil's design was refined through six rounds of adversarial cross-validation between Claude, Codex (ChatGPT), and GPT — the same multi-model review process it implements. Key design influences:

  • Anthropic's harness research — generator-evaluator separation, context anxiety, sprint contracts, harness simplification principle

  • Production-inspired engineering workflow — based on extensive use of Claude Code + Codex collaboration patterns in real-world data engineering work, rewritten here as a clean-room public implementation.

  • Adversarial review — every architectural decision challenged by at least two independent models

See docs/architecture.md for the full design document.


Documentation


License

Apache 2.0 — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados