Repository-native governance for durable human–agent software engineering.
Keep project intent, authority, and evidence in the repository so the next contributor can resume from the same state.
RepoPact gives people and coding agents a shared, inspectable record of what a project intends, what work is authorized, which constraints bind, what remains open, and what evidence supports completion. The records travel with a clone; they do not depend on one session, model, or private memory.
Install the CLI · Follow the adoption tutorial · Read the specification · Explore the research · Open RepoPact Workbench
RepoPact Core contains the repopact CLI, canonical semantic engine, schemas, conformance suite, and reference records. It is open source under Apache-2.0; the stable CLI package is available on PyPI. RepoPact Workbench is a separate native interface that consumes Core and is not included in the PyPI package.
Source code usually survives a handoff. The governing state around that code often does not. A session ends, another contributor takes over, or work moves to another machine. They can see the files but may not know what was authorized, which constraints must hold, what choices are settled, what evidence supports a completion claim, or where the prior worker was uncertain.
RepoPact treats this as governance discontinuity: the loss or divergence of project authority and intent across people, tools, and sessions. Its response is to make that state inspectable and versioned beside the code.
| When project context is… | RepoPact makes it… |
|---|---|
| Held in a chat or one contributor’s memory | Recoverable from repository records |
| Reconstructed differently by each tool | Shared through typed, version-controlled records |
| Marked “done” without showing why | Verifiable through acceptance criteria and linked evidence |
| Implicit about authority and protected paths | Explicit through roles, scopes, invariants, and frozen surfaces |
| Inferred from an older repository | Honest about provenance and remaining uncertainty |
| Reflected in stale dashboards or indexes | Reconciled from authoritative source records |
That makes engineering work easier to resume, review, and verify across human and AI contributors.
Install the stable Core CLI, then initialize a project:
python -m pip install repopactCreate a governed repository and record a unit of work:
repopact init --target ./your-repo
cd ./your-repo
repopact validateThen follow the adoption tutorial to define project governance, create a work item, record verification evidence, and complete the item with evidence.
Preview the proposed changes first:
repopact adopt --target ./existing-repo --dry-runReview the preview. If it matches the repository's needs, run
repopact adopt --target ./existing-repo, then inspect and validate the new
records. Adoption can preserve uncertainty as provisional or inferred rather
than presenting a reconstruction as a known fact. See the adoption guide.
RepoPact is not tied to a particular agent host. Give the agent access to the
repository's AGENTS.md, active work item, applicable governance, and relevant
decisions. The repository records provide durable shared context; the agent
still needs appropriate tool permissions, and RepoPact does not turn written
rules into an operating-system sandbox. See the contributor workflow
and the optional pre-execution admission guide.
Read the specification and formal model for the semantics. Research protocols, findings, and threats to validity are linked in the Research section.
RepoPact does not require a particular coding agent, model provider, editor, CI vendor, or cloud account. The records are ordinary repository files and can be used by humans and tools that read them.
intent → scoped authority → work item → implementation → evidence → audit → history
RepoPact organizes the parts of engineering work that should survive a handoff:
- Intent and decisions record goals and durable choices, including rejected alternatives.
- Roles and scopes describe who can change which parts of a repository.
- Work items record ownership, affected scopes, dependencies, acceptance criteria, and lifecycle.
- Invariants and frozen surfaces make important guarantees and protected paths visible.
- Evidence and provenance connect completion claims to observations, and distinguish concrete facts from provisional or inferred records.
- Audits and dashboards expose drift and provide a useful view of the records.
In a governed repository, human-readable work-item notes explain intent while machine-readable JSON holds lifecycle and relationship state. Decisions preserve material choices; evidence records what actually ran or was observed. Core validates the records and their relationships, including dependencies and completion evidence.
RepoPact gives each fact an authoritative home in the repository: governance records, work items, decisions, evidence, code, or explicitly governed configuration. Dashboards, the optional Repository Orientation Graph (ROG), generated specification sections, and Workbench screens are derived views. They help people navigate; they do not overrule the source records. If a view disagrees with its source, it is stale or wrong and should be reconciled.
ROG is a bounded, deterministic index for questions such as which work depends on a record, which tests relate to a package, or which governance applies. It is optional and does not need a model, embeddings, or a cloud service. Learn about the graph.
A principle guides judgment; a binding invariant is a guarantee that must not be silently weakened. Where the invariant has a defined machine check, validation is the backstop. Where it does not, the record names an escalation path for human review. Ownership and frozen-surface rules make boundaries explicit, but do not themselves grant operating-system security.
Provenance keeps uncertainty visible during brownfield adoption. A record can be concrete, provisional, or inferred; reconstruction does not become fact merely because it has been written down. Acceptance criteria can require linked evidence before work is considered complete.
RepoPact distinguishes documented instructions, session-start checks, pre-action checks on covered operations, and an operating-system boundary that actually constrains a process. The portable reference baseline for the optional admission plane is pre-action: it checks a covered action before that action runs. It does not establish arbitrary-process filesystem confinement. A sandbox/process-enforced claim requires independent, platform-specific native proof. See the enforcement guide and decision 0060.
Core is the semantic authority shared by command-line and graphical clients. The canonical validator and typed repository operations are implemented in Rust and distributed with the stable command-line package. The Python package provides the CLI and compatibility surfaces; the historical Python validator is an explicit comparator, not a second semantic authority.
The repository contains the Rust workspace, packaged schemas and templates, the 3.1.3 conformance corpus, documentation, and reference governance records. The conformance contract defines what it means to claim compatibility with a specific RepoPact version. A conformance result is scoped to that version; it does not make claims about future versions.
View the Core architecture and authority boundaries
The diagram distinguishes source records from projections. CLI and Workbench clients ask Core to interpret records and perform supported typed operations; dashboards, graph indexes, and screens help people navigate the resulting state. Optional host integrations have only the enforcement boundary they can demonstrate. See the concrete work-item walkthrough for a proposal-to-evidence handoff grounded in the actual Core record shape and commands.
Core owns governance schemas and interpretation, validation, graph and analysis semantics, and typed mutation behavior. Workbench owns its interface, application orchestration, session handling, filesystem observation, and native desktop/mobile integration. It consumes one immutable Core revision and must not create a competing governance engine.
Install the CLI with pip install repopact. The current release is 3.1.3 (PyPI). Workbench is a separate Tauri application with its own build and platform evidence; see its repository for current instructions. There are no Workbench installers in the PyPI package.
Repositories can define their own verification profiles and run them locally through Core. Hosted CI/CD is an optional adapter and is disabled by default in this repository’s verification policy. A passing local run is evidence for that run; it does not prove remote branch protection or a hosted admission boundary. Verification, building artifacts, and publication are separate operations.
RepoPact is both a usable tool and an ongoing software-engineering research project. The repository contains a paper draft, a formal model, the adversarial research protocol, a separate comparative benchmark protocol, the Proving Ground lab notebook, a findings register, and threats to validity. These materials distinguish hypotheses and registered methods from observed findings; the existence of a protocol or harness is not itself a completed comparative result. Research findings have bounded scope and documented validity threats; they do not establish universal effectiveness.
The machine-readable conformance suite provides version-scoped compatibility cases. Conformance is an implementation contract, not experimental evidence for the research hypotheses.
- Adopt RepoPact — tutorial for new and existing repositories.
- Documentation map — guidance for use, concepts, integration, and development.
- Concepts — authority, lifecycle, provenance, evidence, and assurance boundaries.
- Repository Orientation Graph — optional derived index and queries.
- Specification and conformance contract — normative model and version compatibility.
- Contributing — development and contribution guidance.
- Security policy — how to report a security concern.
RepoPact is not an AI agent, model provider, issue tracker, hosted CI service, or operating-system sandbox. It complements Git, test frameworks, coding tools, and external authorization systems by giving them a shared, durable governance layer.
RepoPact Core is licensed under Apache-2.0.