repopact 1.4.0

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

RepoPact

RepoPact is a repository-native operating system for durable agent work. It makes authority, intent, evidence, and architectural drift visible in the filesystem so that a new contributor or agent can recover the state of the project without depending on a prior conversation.

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

Why "pact"

Conventions like AGENTS.md, ADRs, and issue trackers each capture a fragment of project knowledge, but none of them makes the binding part explicit — the guarantees an agent must not silently weaken. RepoPact's wedge is the binding invariant: a declared guarantee with a rationale, an escalation path, and (where possible) a machine enforcer. That, plus evidence-gated completion and a filesystem state machine, is what turns a folder convention into a contract.

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 to change.
3. Scopes & roles: layered AGENTS.md files plus a role/scope map in governance/owners.json.
4. Work items: narrative README.md plus machine-readable work-item.json, with evidence-linked acceptance criteria.
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. Reconciliation: audits and a generated dashboard that surface drift and review staleness rather than hand-maintaining it.

Quick start

pip install -r requirements.txt
python scripts/validate_repo.py
python scripts/generate_dashboard.py
python -m unittest discover -s tests -v
python scripts/check_frozen_surface.py --base origin/main

Records are validated against schemas/*.json (structure) and by the validator (cross-record semantics). See decision 0003.

Begin with AGENTS.md, then read governance/charter.md and governance/workflow.md.

Adopt into a new repository

Install the CLI, then bootstrap:

pipx install git+https://github.com/ForgeWireLabs/repopact   # or: pip install .
repopact init --target ../your-repo                          # seed a valid RepoPact
cd ../your-repo
repopact new work-item "Title of the work"                   # stamp records from templates/
repopact validate

repopact dispatches init, adopt, validate, new, dashboard, spec, and check-frozen against the current repository. The loose-script form still works (python scripts/init_repo.py --target ...) for repos that vendor the scripts.

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

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 the first evidence run. It is idempotent — re-running skips records that already exist.

init_repo.py writes the minimal valid source records, copies the schemas and tooling, and validates the result. Templates for every record type live in templates/. RepoPact is licensed under Apache-2.0 (see LICENSE and decision 0002); its spec version is in VERSION.

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 and audit-freshness views are derived; the only hand-maintained files are genuine sources (charter, invariants, frozen surface, schemas, owners, work items, evidence, decisions, policies). See policy 001.