repopact 2.0.2

A repository-native standard for durable agent work: binding invariants, evidence-gated work items, and drift audits.

RepoPact

RepoPact is a repository-native governance kernel for durable agent work. It keeps the load-bearing state of a project — intent, authority, evidence, decisions, and drift — as typed, version-controlled records in the filesystem, so a new contributor or agent can recover where things stand without a prior conversation, and so the guarantees that matter cannot be silently weakened.

The repository is the pact: authority, intent, evidence, and history that survive every session.

pip install repopact · Apache-2.0 · current release 2.0.2 (changelog).

How it relates to AGENTS.md

AGENTS.md (and CLAUDE.md, editor rules) tell an agent what to do — they're instructions, plain Markdown, with no enforcement. RepoPact is the layer above them:

AGENTS.md tells an agent how to behave. RepoPact enforces and records whether the work respected the contract.

RepoPact's distinguishing primitive is the binding invariant — a declared guarantee with a rationale, an escalation path, and (where its logical type permits) a machine enforcer. That, plus evidence-gated completion and a filesystem state machine, is what turns a folder convention into a contract. repopact adopt ingests an existing AGENTS.md rather than replacing it (decision 0020).

Core loop

intent -> scoped authority -> work item -> implementation -> evidence -> audit -> history

Primitives

1. Charter & invariants — principles (judgment) and binding invariants (escalation-gated) in governance/.
2. Frozen surface — paths and symbols that require operator approval (--ack) to change.
3. Scopes & roles — layered AGENTS.md contracts plus a role/scope map in governance/owners.json.
4. Work items — narrative README.md + machine-readable work-item.json with evidence-linked acceptance criteria. Mandatory preflight (2.0): a work item must be recorded before implementation begins (repopact new stamps the marker).
5. Evidence — immutable run manifests under evidence/runs/.
6. Decisions & policies — durable choices (decisions/) and operating rules (governance/policies/) whose rationale outlives any single work item.
7. Provenance (2.0) — every record is concrete, provisional, or inferred. adopt emits provisional/inferred records (honest, not fabricated); doctor ratchets them to concrete as real evidence arrives. See 2.0 changes below.
8. Reconciliation — audits and a generated dashboard surface drift and review staleness rather than hand-maintaining it.

Install & quick start

pip install repopact                # the CLI + reference validator, from PyPI
repopact init --target ../your-repo # seed a valid RepoPact in a new repo
cd ../your-repo
repopact new work-item "Title of the work"   # stamps records (incl. the preflight marker)
repopact validate
repopact dashboard

repopact dispatches init, adopt, validate, new, dashboard, spec, check-frozen, import-plan, and doctor. Records are validated against schemas/*.json (structure) and by the validator (cross-record semantics; decision 0003). Begin with AGENTS.md, then governance/charter.md and governance/workflow.md.

Alternative implementations can run the published conformance suite:

python scripts/run_conformance.py --command "your-validator --root {repo}"

See CONFORMANCE.md and conformance/.

Adopt an existing repository

For a project that already has CODEOWNERS, CI workflows, and nested AGENTS.md contracts, adopt maps those existing signals into RepoPact records without overwriting anything:

repopact adopt --target ../existing-repo --dry-run   # preview the plan, write nothing
repopact adopt --target ../existing-repo             # create records, then validate
repopact doctor                                      # diagnose + repair drift; migrate on upgrade

CODEOWNERS becomes scopes and roles; each .github/workflows/* becomes a binding-gate policy (plus invariant INV-2 and a frozen-surface entry); every nested AGENTS.md is registered as a contract; git history seeds a first inferred evidence run, and the adoption record is recorded as provisional — honestly typed, not a fabricated "completed" claim. Adoption is idempotent.

2.0: mandatory preflight + provenance-typed records

Decision 0021 (supersedes 0018):

• Mandatory preflight (default on). No work begins until a work item exists and propagates through the pact; repopact new stamps the marker. Existing repos grandfather their pre-2.0 items automatically — adopt/init set a preflight epoch and doctor migrates on upgrade. This is a breaking change: run repopact doctor after upgrading.
• Provenance typing (concrete / provisional / inferred, default concrete). This is the principled escape from the adoption trilemma: adopt emits provisional/inferred records so the result is both valid and faithful (reconstruction is labelled, not faked). Completion still requires concrete evidence; doctor ratchets when it arrives.

Status is a filesystem transition

Work moves between work/active, work/blocked, work/deferred, and work/completed; its work-item.json status must match its directory. Moving a work item never deletes its reasoning, decisions, or evidence links.

Derive over declare

Anything computable from source records is generated, not authored by hand (the dashboard, audit-freshness views, and the derived blocks of SPEC.md). Only genuine sources are hand-maintained. See policy 001.

Evaluation, formal model & the Proving Ground

RepoPact is developed against its own evidence, not assertion. The research/ lab notebook holds a formal model (the L0–L5 kernel, the typed invariant lattice, the adoption trilemma), the pre-registered experiment protocol and benchmark protocol (hypotheses H1–H13, falsification criteria, threats to validity), a findings register, and the current paper.

PactBench — the runnable benchmark suite (pre-registered tasks measuring whether RepoPact enforcement reduces silent guarantee drift, with a model-agnostic harness and an S5 drift harness) — lives in the RepoPact Proving Ground, a throwaway-but-real project that consumes RepoPact from PyPI and is driven across every primitive, including cases designed to break it. RepoPact defines the protocol (research/); the Proving Ground hosts the runnable suite. RepoPact defines the pact; the Proving Ground tests whether the pact holds under agent pressure.

Ecosystem

RepoPact is the work-governance layer of ForgeWire Labs — inspectable agentic infrastructure (inspect the work, bound the authority, preserve the evidence). It composes with Fabric (execution governance) and ForgeLink (human-agent communication governance), but is independently useful on its own.

License & version

Apache-2.0 (LICENSE, decision 0002). The spec version is in VERSION; templates for every record type live in templates/.