Repository-native governance for durable human-agent software engineering.
AI coding tools can change software faster than teams can preserve the governing context around those changes. Intent, decisions, authority, acceptance criteria, evidence, constraints, and unfinished work often live in chat histories, agent memory, issue trackers, local tooling, or one person's head.
RepoPact makes that load-bearing engineering state part of the repository itself.
A fresh human or agent can clone a governed repository and recover not only the source tree, but also the represented work state, authority boundaries, invariants, decisions, evidence, provenance, and known violations needed to continue responsibly.
The repository is the pact.
Humans, agents, and tools rendezvous through durable repository state rather than relying on one session or vendor to remember the project correctly.
pip install repopact · Apache-2.0 · stable release 3.1.3 (changelog)
Important
PyPI is the authoritative source for the latest stable RepoPact CLI/headless package. pip install --upgrade repopact installs the Python command/compatibility surface and the platform-native canonical repopact-engine Rust executable. PyPI does not currently distribute the Tauri Workbench GUI, Android application, or the rest of the repository's development/research surfaces. GitHub's Latest Release entry tracks the same stable version as PyPI.
To get the full RepoPact source tree, including the Workbench, mobile code, research, governance records, and development/reference surfaces, clone this repository. Use the v3.1.3 tag when you want source aligned with the current stable PyPI release, or main when you want the newest development state.
Stable source matching PyPI 3.1.3:
git clone --branch v3.1.3 --depth 1 https://github.com/ForgeWireLabs/repopact.git
cd repopactNewest development tree:
git clone https://github.com/ForgeWireLabs/repopact.git
cd repopactBuild or run the desktop Workbench from the source checkout:
cd rust/apps/repopact-desktop
npm ci
npm run tauri -- devBuild a native desktop bundle/installable artifact:
npm run tauri -- buildThe Workbench build requires Node/npm, Rust/Cargo, and the normal Tauri 2 platform prerequisites for your operating system. Optional GitHub remote-auth integration has additional build-time registration described in docs/guides/github-app-setup.md.
Android uses the same Tauri application after the Android SDK/NDK, JDK, Rust Android targets, and Tauri mobile prerequisites are installed:
cd rust/apps/repopact-desktop
npm ci
npx tauri android dev
npx tauri android buildNative bring-up/operator evidence currently exists for Windows, Linux, and Android. macOS and iOS remain intended targets but do not yet have equivalent native validation evidence.
Documentation · Paper draft · Formal model · Conformance · Research protocol
RepoPact addresses governance discontinuity by making the repository the durable rendezvous point between workers and sessions.
Source code usually survives a handoff. The governing state around that code often does not.
A coding session ends. Another model takes over. A different developer opens the repository. Work moves to another machine. The new worker can see the files, but may not know what was authorized, why a constraint exists, which decisions are already settled, what evidence supports a claim, what is still uncertain, or what must happen before the work is actually complete.
RepoPact treats that as a software-engineering problem, not just a memory problem. The paper calls it governance discontinuity.
| Common failure mode | RepoPact's response |
|---|---|
| Agent or session memory resets | Durable governed state travels with the repository |
| Different tools reconstruct different project context | Humans and agents read the same typed, version-controlled records |
| "Done" means an agent said it was done | Acceptance criteria can require linked evidence before completion |
| Authority is implicit or scattered | Roles, scopes, frozen surfaces, invariants, and optional admission policy make boundaries explicit |
| Brownfield reconstruction is uncertain | Provenance distinguishes concrete, provisional, and inferred state |
| Generated views drift from source records | Dashboard and other derived projections are regenerated and validated |
| Verification is tied to one hosted provider | Repository-defined local verification is canonical; hosted CI/CD is optional |
The goal is not to slow AI-assisted development back down. The goal is to make higher implementation throughput inspectable, recoverable, and sustainable across humans, agents, machines, providers, and sessions.
The stable 3.1.3 package creates or adopts governed repository state, runs the canonical validator, and exposes repository-defined local verification and release surfaces.
pip install repopact
# Start a new governed repository
repopact init --target ../your-repo
cd ../your-repo
# Record work before implementation begins
repopact new work-item "Add retry policy"
repopact new work-item "Possible cache redesign" --status proposed
# Check the pact and refresh the derived view
repopact validate
repopact dashboardFor an existing repository:
repopact adopt --target ../existing-repo --dry-run
repopact adopt --target ../existing-repo
repopact doctorRepoPact does not require a particular model, coding agent, agent framework, editor, CI vendor, or cloud provider.
For the next step, use the documentation map: Use RepoPact, Understand RepoPact, Integrate RepoPact, or Develop RepoPact.
intent -> scoped authority -> work item -> implementation -> evidence -> audit -> history
RepoPact stores the parts of engineering state that need to survive a worker or session change:
- Intent and decisions: what the project is trying to accomplish and what choices are already settled.
- Authority: who or what may change which parts of the repository.
- Work state:
proposed,active,blocked,deferred, andcompletedare durable lifecycle states rather than chat labels. - Acceptance criteria and evidence: completion can be tied to concrete run records instead of narrative confidence.
- Binding invariants: guarantees with rationale, escalation, and machine enforcement where their logical type permits it.
- Frozen surfaces: paths or symbols that cannot be casually changed without explicit review.
- Provenance: reconstructed state can remain visibly provisional or inferred instead of being promoted to fact.
- Reconciliation: generated views and audits expose drift instead of hiding it.
A work item is a narrative README.md plus machine-readable work-item.json. Evidence lives under evidence/runs/. Decisions and policies remain durable after the implementation session is gone. The validator checks structural and cross-record semantics, and the dashboard is generated from source records rather than maintained by hand.
RepoPact's distinguishing primitive is the binding invariant: a declared guarantee coupled to rationale, escalation, and, where logically possible, an enforcer. The invariant is the thing a later worker must not silently weaken.
RepoPact deliberately separates authority from convenience.
Authoritative project state comes from the governed source records and repository state that own a fact: governance/, work/, decisions/, evidence/, source code, and explicitly governed configuration. Different record types own different kinds of truth.
The dashboard, Repository Orientation Graph (ROG), Workbench views, generated specification blocks, indexes, and similar read models are derived. They can make the repository dramatically easier to inspect and operate, but they do not gain authority merely because they are easier to query.
If a derived view conflicts with the source records it projects, the derived view is stale or wrong and must be regenerated or reconciled.
RepoPact does not describe every integration as simply "enforced" or "not enforced." The assurance class must match the boundary that actually exists.
| Class | What it means |
|---|---|
instruction-only |
Durable rules and state exist, but no pre-execution host boundary is claimed. |
session-start |
A covered integration gates creation or start of a session/child process. |
pre-action |
A covered mutation is checked before its callback or action begins. |
sandbox/process-enforced |
A real OS-backed boundary constrains the launched process tree for the capability being claimed. |
The portable reference baseline for RepoPact's optional admission plane is pre-action. That is a real pre-execution guarantee for covered actions, but it does not imply arbitrary-process filesystem confinement.
A higher sandbox/process-enforced class requires independent native proof of the operating-system boundary. The Linux Landlock work demonstrates the intended distinction, while remaining platform/reference work is tracked separately. RepoPact never silently upgrades a weaker adapter into a stronger assurance claim.
See Pre-execution admission and decision 0060.
RepoPact is not intended to be a JSON-editing exercise for human operators. The repository also contains a Tauri 2 Workbench that presents governed state through a human-facing interface while the Rust semantic engine remains the semantic authority.
The Workbench supports repository selection, inspection, work-item views, typed create/edit/lifecycle operations, validation, graph-backed repository views, plan/preview/apply mutation flow, refresh, and stale-plan/session rejection.
Native bring-up and operator evidence currently exist for Windows, Linux, and Android. macOS and iOS remain intended targets but do not yet have equivalent native validation evidence.
Prebuilt Workbench installers are attached to the v3.1.3 GitHub Release:
| Platform | Artifact | Notes |
|---|---|---|
| Windows | RepoPact-Workbench-3.1.3-x64-setup.exe (NSIS) or RepoPact-Workbench-3.1.3-x64.msi |
Unsigned — SmartScreen will warn on first run. NSIS installs per-user (no admin required); MSI installs per-machine (requires admin). |
| Linux (Debian/Ubuntu) | RepoPact-Workbench-3.1.3-amd64.deb |
sudo dpkg -i RepoPact-Workbench-3.1.3-amd64.deb |
| Android | RepoPact-Workbench-3.1.3-android-universal.apk |
Signed with RepoPact's own release key (not Google Play). Enable "install unknown apps" for your browser/file manager to sideload. |
macOS and iOS builds are not yet available — see the platform-support note above.
Workbench source: rust/apps/repopact-desktop/
The screenshot is a capture-time view of the implementation. It is not a claim that Workbench installers or Android artifacts are part of the stable PyPI 3.1.3 package contract.
RepoPact is not AGENTS.md++, and it does not replace instruction files.
AGENTS.md, CLAUDE.md, editor rules, skills, and system prompts tell an agent how it should behave. RepoPact records the durable project state around that behavior and validates, and where the relevant boundary exists can enforce, whether the repository still respects its declared contract.
Instruction files can participate in the pact. They are not the whole governance substrate.
That distinction matters when work moves between Claude, Codex, ChatGPT, local models, human developers, or future tools. The next worker should not need the previous worker's private conversation in order to recover the represented engineering state.
repopact adopt maps existing signals such as nested AGENTS.md, CODEOWNERS-style ownership, repository structure, and history into RepoPact records without treating reconstruction as omniscient truth.
This is why RepoPact has provenance types:
concrete: directly established state or evidence;provisional: usable but not yet fully ratified;inferred: reconstructed from indirect evidence.
The point is not to manufacture a clean story for an old repository. It is to make uncertainty explicit and allow later evidence to ratchet it toward concrete state.
See decision 0021 and the paper's brownfield adoption discussion for the formal treatment.
RepoPact keeps verification semantics in the repository instead of making a hosted provider the source of truth.
The stable 3.1.3 package includes repository-defined verification profiles and local release operations:
repopact verify quick
repopact verify ci
repopact verify release
repopact release verify
repopact release build --outdir release-out
repopact release inspect --dist release-outGitHub Actions is an optional hosted adapter, disabled by default. Hosted validation requires REPOPACT_GITHUB_CI=true; hosted publication requires the independent REPOPACT_GITHUB_CD=true switch. A local passing run is local evidence, not proof that a remote branch-protection or admission boundary is closed.
Verification, artifact construction, inspection, and publication remain separate operations. Publication requires explicit operator intent and credentials supplied outside the repository.
This local-first architecture was completed under WI046. Workbench, mobile applications, active research surfaces, and stronger platform-specific enforcement retain their own validation and packaging boundaries rather than being silently folded into the PyPI artifact contract.
See docs/guides/local-ci-cd.md.
The optional Repository Orientation Graph (ROG) is a bounded, versioned, derived representation used for orientation, impact, dependency, test, and governance queries.
The graph can be durable and incrementally maintained without becoming a second source of truth. Repository and governance records remain authoritative; graph freshness, coverage, and excluded boundaries are explicit. If the graph and authoritative source disagree, rebuild or reconcile the graph.
See docs/repository-orientation-graph.md. WI063 remains the governing work record for unfinished graph evaluation and closeout obligations.
RepoPact is both a working tool and an ongoing software-engineering research project. The research program is deliberately set up so the claims can fail.
The repository includes:
- the current paper draft, RepoPact: Repository-Native Governance for Durable Human-Agent Software Engineering;
- a formal model covering the L0-L5 kernel, governance continuity, invariant classes, and brownfield adoption;
- a pre-registered experiment protocol and benchmark protocol;
- explicit threats to validity and a findings register;
- a machine-checkable conformance suite;
- the public RepoPact Proving Ground, where runnable PactBench work is exercised against a real adopter.
Comparative cross-model results remain separate from the existence of benchmark infrastructure. They are reported only when the corresponding runs and evidence exist.
RepoPact defines the pact. The Proving Ground tests whether the pact holds under agent pressure.
RepoPact is not an AI agent, model provider, agent runtime, distributed compute fabric, chat-memory store, general-purpose issue tracker, hosted CI service, IDE, or general-purpose sandbox.
It does not try to replace Git, compilers, test frameworks, agent orchestrators, operating-system security boundaries, or external authorization systems.
It is the durable governance layer those systems can share.
Optional admission and protected-execution integrations can consume RepoPact authority and enforce a covered boundary, but those integrations do not become a second work ledger or a new source of project truth.
docs/README.md: audience-oriented documentation mapSPEC.md: normative repository model and machine-enforced rulesCONFORMANCE.md: implementation-independent conformance contractgovernance/charter.md: principles and non-goalsgovernance/workflow.md: repository workflowdocs/repository-orientation-graph.md: optional derived Repository Orientation Graphdocs/guides/pre-execution-admission.md: optional enforcement/admission integrationdecisions/: durable architecture and policy decisionsresearch/: formal model, protocols, findings, and paperwork/: the project's own RepoPact-governed work ledger
The default conformance path exercises the canonical Rust semantic engine. The historical Python validator remains an explicit comparator/compatibility surface rather than a second product authority.
RepoPact is the repository-governance layer of ForgeWire Labs: inspect the work, bound the authority, preserve the evidence.
It is independently useful, but it also composes with the wider ForgeWire ecosystem where runtime execution, human communication, and broader agent orchestration are separate concerns.
Apache-2.0. See LICENSE and decision 0002.