Imported from benvenker/gitbad (AGENTS.md). Install upstream with npx skills add benvenker/gitbad. Copyright stays with the author.

AGENTS.md

This repository is a design and evidence repository for a proposed software forge. It is not a working implementation. Read README.md, the complete COMPREHENSIVE_PLAN_FOR_FRANKENGIT.md, and the relevant registries before changing architecture or claims.

Constitutional rules

1. Do not turn target-state prose into a shipped claim. Every document that describes the finished system must retain a prominent status boundary until evidence proves the corresponding gate.
2. Git remains the compatibility kernel. Replacing upstream Git on a critical path requires a declared conformance profile, differential evidence, and measured benefit.
3. The Repository Ledger is authoritative. Materializers, SQL, search, graph, caches, and UI projections are reconstructible views. Do not introduce a second ref authority.
4. Acknowledgement follows publication. An operation may be reported committed only after required immutable payload durability and authoritative root publication.
5. Statistics never prove safety. RaptorQ, conformal prediction, e-processes, machine learning, and heuristics must stay inside the roles assigned in the plan.
6. One semantic transaction where atomicity matters. Ref and forge effects that must not split belong to one RepoTransaction; unrelated activity should not be forced through that boundary.
7. No copied donor code without rights. The inspected Franken repositories have nonstandard rider terms. Use public ideas and standards as research; implement independently unless written permission is recorded.
8. “FrankenGit” is a codename. Do not represent it as a cleared service mark or launch a paid service under that name without written clearance.
9. No process theater. Add only documents, registries, abstractions, and gates that prevent a concrete failure, settle an important decision, or make evidence reproducible.
10. Prefer a narrow verified slice over a broad scaffold. G1 is a lossless stock-Git push/clone/rebuild path, not a generated web application.

Same-change requirements

A durable-format change must update its registry row, schema or canonical layout, golden vector plan, compatibility reader/migration notes, and threat limits. An invariant change must update the invariant registry, enforcement design, model/oracle, tests, and operator response. A compatibility claim must update the compatibility matrix and evidence. A performance claim must update operation costs, workload, environment, raw evidence, and README wording. A new adaptive policy must include deterministic fallback, shadow/canary/rollback, and calibration assumptions.

Editing style

Use exact terms and complete sentences. Distinguish implemented, planned, measured, modeled, and hypothesized. Name the linearization point, authority, failure mode, and evidence for any distributed-systems claim. Avoid “self-healing,” “compatible,” “secure,” “deterministic,” “unlimited,” or “zero-copy” without a scoped definition.

Keep headings stable where possible because registries and future review tools will link to them. Prefer append-only ADRs over silently reversing a constitutional decision. Keep external research in docs/RESEARCH_NOTES.md and the plan bibliography; prefer primary sources.

Required checks

Run:

make validate

A green validator proves only internal consistency of the planning repository. It is not implementation evidence.