Skip to content

README.md

Latest commit

 

History

History
233 lines (173 loc) · 5.86 KB

README.md

File metadata and controls

233 lines (173 loc) · 5.86 KB

ProofGatedAgents

Deterministic, governed multi-agent systems — by design, not by hope.

Most “autonomous agent” frameworks trust non-deterministic LLM output and fix problems after failure.

ProofGatedAgents does the opposite.

This framework treats LLMs as untrusted proposal generators and enforces correctness through deterministic verification, explicit policy, and machine-verifiable proofs.

If an agent cannot prove its work, the system stops.

No silent drift.
No hidden writes.
No runaway autonomy.

Why this exists

The current agent ecosystem optimizes for demos, not systems.

Most frameworks implicitly assume:

  • LLM output is “good enough”
  • retries will eventually converge
  • autonomy is a feature, not a risk

In production environments, these assumptions fail.

The hard problems nobody enforces

  • How do you prove an agent respected policy?
  • How do you detect silent drift between runs?
  • How do you prevent “helpful” self-modification?
  • How do you stop infinite retry loops and escalate failure?

ProofGatedAgents exists to answer these questions explicitly.

It introduces:

  • machine-verifiable proofs as first-class artifacts
  • deterministic envelopes around non-deterministic models
  • locked governance contracts that agents cannot rewrite
  • explicit stop rules and escalation paths
  • bounded, proposal-only self-improvement

This is not an agent toy.
It is an execution framework for systems that must be auditable, reproducible, and governable.

What this is

A governed autonomous multi-agent framework with:

  • Stage-based execution
  • Proof-gated verification
    (machine-readable JSON proofs + human-readable reports)
  • Policy-bounded write scope with drift guards
  • Bounded repair loops with explicit stop conditions
  • Controlled post-run self-improvement (“Sophia-lite”)
    that proposes small framework improvements between runs

LLM outputs are treated as non-deterministic suggestions and validated through deterministic mechanisms:

  • tests and checks
  • fixed evaluation slices and stable seeds (when applicable)
  • hashes of critical artifacts
  • locked governance files
  • explicit escalation rules

What makes this different

Typical agent frameworks ProofGatedAgents
Trust LLM output Treat output as untrusted
Retry until it works Hard stop on failed proof
Mutable runtime state Locked contracts + drift guard
Implicit behavior Explicit policy + escalation
Self-modifying agents Proposal-only self-improvement

Repository structure (source of truth)

Core contracts (locked during normal operation)

  • AGENT.md
  • ORCHESTRATOR.md
  • Orchestrator_Dispatch_Contract.md
  • ARCHITECTAGENT.md
  • BUILDERAGENT.md
  • VERIFIERAGENT.md
  • REPAIRAGENT.md
  • policy/policy.json
  • schemas/*.schema.json

Governance and operating documentation

  • docs/SYSTEM_ARCHITECTURE.md
  • docs/DETERMINISM_ENVELOPE.md
  • docs/LOOP_POLICY.md
  • docs/SCORING_RUBRIC.md
  • docs/self_improvement/IMPROVEMENT_POLICY.md
  • docs/self_improvement/POSTRUN_SOPHIA.md

Project templates

  • templates/PRODUCT_SPEC.template.md
  • templates/stage_spec.template.md
  • templates/handoff.template.json
  • templates/postrun_report.template.json
  • templates/loop_state.template.json

Deterministic helper scripts (standard library only)

  • scripts/hash_drift_guard.py
  • scripts/deterministic_env_snapshot.py
  • scripts/postrun_analyze.py

Deliverables (end-of-run artifacts)

  • deliverables/*.md

Quickstart (prompt-native)

1. Create a project specification

Copy:

templates/PRODUCT_SPEC.template.md → PRODUCT_SPEC.md

Fill in scope, constraints, success criteria, and non-goals.

2. Define your stage chain

For each stage:

stages/<STAGE_NAME>/SPEC.md

Use:

templates/stage_spec.template.md

3. Initialize runtime state

Copy:

templates/handoff.template.json → .handoff.json

Populate:

  • run_id
  • governance hashes
  • next_allowed_stage

4. Execute the pipeline

The Orchestrator:

  • reads locked contracts and policy
  • follows the dispatch table
  • enforces write scopes and stop rules

For each stage:

  • BuilderAgent produces artifacts
  • VerifierAgent emits:
    • outputs/proofs/<stage>_proof.json
    • evidence under outputs/diagnostics/<stage>/
  • RepairAgent attempts minimal, policy-compliant fixes only if verification fails

If proof fails after bounded attempts → HARD STOP

5. Post-run analysis (Sophia-lite)

Run:

python scripts/postrun_analyze.py   --proofs-dir outputs/proofs   --out-dir outputs/sophia

This generates:

  • outputs/sophia/postrun_report.json
  • outputs/sophia/proposals/ARIP-*.json

6. Apply improvements (bounded)

  • Only proposals compliant with IMPROVEMENT_POLICY.md may be applied
  • Locked governance files are proposal-only
  • Any structural change requires explicit human approval

Determinism and evidence

Authoritative references:

  • docs/DETERMINISM_ENVELOPE.md
  • docs/LOOP_POLICY.md

Generate drift guard hashes:

python scripts/hash_drift_guard.py   --policy policy/policy.json   --output outputs/env/drift_guard_manifest.json

Generate environment snapshot:

python scripts/deterministic_env_snapshot.py   --output outputs/env/environment_snapshot.json

Security model

  • Default-deny write paths
  • Explicitly locked governance files
  • Network disabled by default
    (policy.offline_by_default = true)
  • Any deviation from policy or drift rules triggers an immediate HARD STOP

Design philosophy

  • Autonomy is bounded
  • Verification is mandatory
  • Governance is explicit
  • Improvement is proposal-based, not self-executing

LLMs suggest.
The system decides.

License

Project-specific. See LICENSE for details.