From d8355cf0c4c1cd38f9282a285099995bef03b8e4 Mon Sep 17 00:00:00 2001 From: Jodson Graves Date: Sun, 12 Jul 2026 09:33:29 -0400 Subject: [PATCH] docs: JFA conformance self-description + repo discipline CONFORMANCE.md declares the repo's role (the reference economy of the Economy & Education layer) in the architecture's terms and states the invariant table honestly as of main: the member-economy machinery (Mycelium per-operator logs, witness checkpoint stub, operator model, net-zero accounting) is in review on refactor branches, not on main; escrow-first is the standing posture and the credit switch is governance. CLAUDE.md carries the per-layer invariants, the refuse-or-flag list, and the tension protocol for agent-assisted work. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 43 +++++++++++++++++++++++++++++++++++++++++++ CONFORMANCE.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 CLAUDE.md create mode 100644 CONFORMANCE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cc7e994 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# CLAUDE.md — Agrinet + +## What this repo is + +The **reference economy** of Janus-Facing Architecture's Economy & Education layer: agricultural coordination and exchange over a per-operator dialog ledger (Mycelium), the covenant's assessment scale (LBTAS), and escrow settlement. Read `CONFORMANCE.md` first — it is the role declaration and the invariant table, stated honestly as of `main`, and it must be updated in the same PR as any change that alters a binding. + +## Non-negotiable invariants + +Not negotiable by feature request. + +**Record (Mycelium)** +- Append-only: no update, no delete, no edit-to-resolve-a-dispute. Corrections and dismissals are new, visible entries. +- The dialog is the atomic unit; it seals only complete-and-quiescent. A clock never force-seals over an open harm claim. +- No PII in the commons: the chain commits structure and references; narrative stays member-local and erasable. +- Per-operator logs; no global chain, no consensus layer. Witnessing is the non-equivocation model, and a single-witness deployment is labeled the stand-in it is. + +**Covenant (LBTAS adoption)** +- Never average ratings; carry `{distribution, total}`. No single score, no average-ranked lists — those APIs were removed in LBTAS v2 and must not be reimplemented locally. +- The lowest rating is the breach itself; volume never absolves it. +- Every claim answerable, both directions; dismissals annotate. + +**Economy** +- Balances are a deterministic function of the sealed record; every exchange nets to zero. +- Settlement is escrow. The escrow-to-credit switch is a governed configuration change requiring Board approval, membership notice, and a completed regulatory review — never a code default, never Claude's to flip. +- No redeemability, no purchasable credit, no cross-economy convertibility. Fiat escrow is walled from any member-issued unit. + +**Identity** +- Single participant identity: one member, simultaneously contributor and consumer. Never split. + +## Change discipline + +1. Branch → PR → CI green → human review. The author never merges their own PR. +2. `CONFORMANCE.md` rides along with any binding change. +3. The working tree may carry in-flight refactors — never commit, stash, or clean work you did not author; branch from `origin/main` via worktree for independent changes. +4. Never force-push, rewrite published history, or move a published tag. + +## Requests to refuse or flag + +Stop, name the tension, and surface it: average ratings or add a score; edit/delete ledger entries; store dispute narrative on the chain; flip escrow to credit; make credits purchasable or redeemable; merge fiat and member-credit paths; drop provenance fields on federation import; silent last-write-wins without an audit trail. + +## Tension protocol + +If you notice yourself reframing an invariant so a feature becomes convenient, implementing a stand-in without labeling it, or routing around an open problem instead of noting it — stop. Name the tension, attach it to the invariant or open problem by name, and propose the minimal conformant move. Surface it; do not absorb it. diff --git a/CONFORMANCE.md b/CONFORMANCE.md new file mode 100644 index 0000000..f3b9f0a --- /dev/null +++ b/CONFORMANCE.md @@ -0,0 +1,45 @@ +# Conformance — Janus-Facing Architecture + +The repo's self-description in the architecture's own terms, stated **before** anything product-specific, per the architecture's ordering rule. Every conformance claim is bound to the mechanism and check that enforces it, or it is labeled a stand-in or in-review. Unbound prose is marketing. + +The architecture is **Janus-Facing Architecture (JFA)** — NTARI's unified architecture document, free documentation under the project's AGPL-3.0 commons. + +## Role declaration + +Agrinet is an **economy** of the JFA **Economy & Education layer** — the reference economy instance: agricultural coordination and exchange, applying the four layers beneath (substrate, record, covenant, governance) to a specific socioeconomic activity. It carries its own per-operator record instance and adopts the covenant's assessment scale at the economic level. + +| This repo's term | Architecture role | +|---|---| +| Mycelium | the **per-operator dialog ledger** — append-only, hash-chained, dialog-sealed | +| Operator | an **operator**: one platform instance keeping its own log | +| LBTAS adoption | the **covenant** at the economic level — distributions, never averages | +| Escrow settlement | the economy's **phase-one** posture: escrow now, credit later, by governance | + +## Invariants and their bindings — as of `main` + +Honesty first: **the JFA member-economy machinery is in review, not on `main`.** The per-operator log scoping, witness checkpoint stub, operator model, and net-zero exchange accounting live on open refactor branches; `main` today is the application without them. Each invariant below binds when its branch lands, and this table is updated in the same PR (the rides-along rule). + +| Invariant (architecture) | Status | Committed mechanism | +|---|---|---| +| The ledger is **append-only**; corrections are new entries; a dismissal annotates, never erases | In review | Mycelium: hash-chained per-exchange logs; no update, no delete | +| The atomic unit is the **dialog**, sealed complete-and-quiescent | In review | Dialog seal held open by unresolved harm claims; non-raters assigned a marked default | +| **No PII in the commons** | In review | The chain commits the shape of an exchange; narrative is referenced, member-local, erasable | +| Each operator keeps its **own log**; no global chain | In review | Per-operator log scoping; witnessing (not consensus) as the non-equivocation model | +| Witnessing with independence; single-witness deployments are **labeled stand-ins** | In review (stand-in) | Witness checkpoint stub; federation is open problem 2 | +| Reputation carried as a **full distribution**, never averaged | In review | LBTAS v2 (the no-averaging release) is the adoption floor | +| Balances a **deterministic function of the sealed record**; exchanges net to zero | In review | Net-zero exchange accounting | +| Settlement is **escrow**; the credit switch is governance, never a code default | Standing posture | Escrow-first; any move to member-issued credit requires Board approval, membership notice, and a completed regulatory review | + +## Stand-ins and open residuals + +- **Single-witness stand-in.** Until independent witnesses countersign the operator's checkpoints, the record's non-equivocation is self-attested and labeled as such. +- **Credit is not switched on.** Escrow is the opposite of credit and is described plainly as such; the three-phase bootstrap (volume and displayed integrity first) governs when that changes. +- **Cross-operator federation** exists in interim form (registry-enrolled peers, acknowledged interim conflict handling); witnessed checkpoints are the named target for cross-operator non-equivocation. + +## Dependency declaration + +Adopts the covenant scale (LBTAS, v2 floor) and carries its own record instance. Independent of the compute substrate's coordinator — an economy depends on the layers beneath it, never on a sibling economy or a particular coordinator. + +## Product-specific notes (last, per the ordering rule) + +The reference economy. Its operator/federation model is the named reference for the substrate's frontend-as-operator design target.