diff --git a/rfcs/GRADUATION_RULES.md b/rfcs/GRADUATION_RULES.md new file mode 100644 index 0000000..20e45a0 --- /dev/null +++ b/rfcs/GRADUATION_RULES.md @@ -0,0 +1,168 @@ +# Spec → RFC → On-chain Proposal: Graduation Rules + +This document defines the **lifecycle and promotion rules** for the three artifact types that govern the agentic-tokenomics → forum → on-chain pipeline. Together they form the deliberation chamber of the bicameral R&D pipeline. + +Companion documents: +- [`_template.md`](./_template.md) — copyable RFC template +- [`schema/`](./schema/) — machine-readable governance review schema for agent + human reviewers + +## The three artifact types + +The agentic-tokenomics repo houses three distinct artifact types, with three distinct lifecycles. Each has a **purpose**, an **audience**, an **author scope** (who can write it), and a **decision scope** (what it commits the system to). + +| | Spec | RFC | On-chain Proposal | +|---|---|---|---| +| **Purpose** | Explore a mechanism design — what could exist | Decide a question — what should exist | Execute a change — what now exists | +| **Audience** | Designers, contributors | Stewards, $REGEN stakers, partners | Validators, on-chain governance | +| **Author scope** | Anyone (humans + agents) | Humans + agents (with human sponsor) | Humans only (no agent-authored proposals to chain — for now) | +| **Decision scope** | Non-binding; specs can branch and proliferate | Binding within the repo; one ratified RFC per question | Binding on-chain; irreversible without superseding proposal | +| **Location** | `mechanisms//SPEC.md`, `phase-N/...` | `rfcs/RFC-XXXX.md` | `phase-4/proposals/RFC-XXXX-proposal.json` | +| **Lifecycle states** | draft → merged → superseded | draft → forum-posted → ratified → enacted (or parked / withdrawn) | drafted → submitted → voting → passed/rejected → enacted | +| **Versioning** | semver per spec; multiple drafts allowed | sequential RFC IDs; one canonical RFC per question; supersession rather than re-versioning | one proposal per attempt; if rejected, file a new one with new ID | + +## Why three layers, not one? + +Two failure modes this is designed to avoid: + +1. **The "everything is a spec" problem.** When everything is a spec, nothing is decisive. Specs accumulate, branch, become impossible to navigate. There needs to be a graduation point where the system says "this is the canonical answer to this question, dispute it via supersession." + +2. **The "specs go directly to chain" problem.** When specs become on-chain proposals without a deliberation step, the chain inherits the noise of design exploration. Validators get asked to vote on under-deliberated changes. Either they reject by default (chilling effect) or they rubber-stamp (loss of governance legitimacy). + +The RFC layer is the **deliberation chamber**. It's where claims get sharpened, evidence gets challenged, and a human sponsor takes accountability before anything reaches chain. + +## Promotion criteria + +### Spec → RFC + +A spec graduates to an RFC when **all** of the following are true: + +1. **There is a decisive claim to be made.** The spec is no longer exploring "what could M013's fee split look like" — it is asserting "M013's fee split should be 15/30/50/5". If the work is still exploratory, it stays in `mechanisms/`. +2. **A human sponsor has volunteered.** No spec graduates without a named human accountable for shepherding the RFC to ratification or withdrawal. +3. **At least one decisive evidence item exists.** Per the RFC template's §2 (Sufficiency assertion), there must be at least one piece of evidence that, if invalidated, would invalidate the claim. Pure-design RFCs without empirical or simulation evidence are not allowed. +4. **The audience tier is declared, and the reference accessibility gate is passable.** If the RFC is targeted at `public`, every evidence URL must already resolve for a public reader, OR there must be a plan to elevate references before forum-posting. +5. **No live conflicting RFC.** If there's an unresolved RFC on the same question, that one must be ratified, withdrawn, or superseded first. + +**Author scope:** anyone. **Decision authority:** the named sponsor (proposes promotion) + a steward confirms. + +### RFC → forum-posted + +An RFC graduates from `draft` to `forum-posted` when: + +1. **The sponsor has prepared a forum post** with all references audience-accessible to the forum's reader population. (For commonwealth.im threads, that's a "public-or-commons" audience.) +2. **The discussion deadline is set** in the RFC's §5 — minimum 7 days, recommended 14, longer for high-stakes proposals. +3. **The RFC is linked from the forum post**, and the forum thread URL is added to the RFC. + +**Author scope:** sponsor only. **Decision authority:** sponsor. + +### RFC → ratified + +An RFC graduates from `forum-posted` to `ratified` when: + +1. **The discussion deadline has passed.** +2. **All key counter-positions raised in §5 have been addressed** — either incorporated into the RFC's claim/methodology, or explicitly noted as "considered and rejected because ". +3. **All open questions in §8 are either resolved or explicitly carried as known limitations.** +4. **The decisive evidence in §2 has not been invalidated** during the discussion period. +5. **A ratifier (a steward distinct from the sponsor) signs off.** The ratifier's job is to confirm the deliberation was sufficient — not to re-litigate the claim. Two-eyes principle. + +**Author scope:** sponsor + ratifier. **Decision authority:** ratifier. + +### RFC → enacted + +An RFC graduates from `ratified` to `enacted` when: + +1. **An on-chain proposal generated from the RFC has passed** (or, for off-chain ratified RFCs that don't require chain action, when the corresponding code/process change is merged and live). +2. **The RFC's §7 (On-chain enactment) is filled out** with the actual proposal ID, voting result, and post-enactment notes. +3. **The lineage in §4 is updated** to reflect the realized outcome. + +**Author scope:** sponsor or proposer. **Decision authority:** automatic once on-chain proposal passes. + +### RFC → on-chain proposal + +A `ratified` RFC produces an on-chain proposal when: + +1. **A human proposer (typically the sponsor) generates the proposal artifact** from the RFC — using deterministic generation rules from §7 wherever possible. +2. **Pre-flight checks listed in §7 have all passed.** (Unit tests, integration tests, simulation reruns, etc.) +3. **The proposal references the RFC** by ID and KOI IRI in its on-chain `description` field. +4. **The proposer commits the deposit** and submits via `regen tx gov submit-proposal`. + +**Critical rule:** **agents do not submit on-chain proposals.** They can draft the JSON, run pre-flight checks, and surface the proposal for human review — but the `submit-proposal` transaction must be signed by a human key. This is the accountability boundary. + +## Demotion / parking / withdrawal + +Some RFCs don't progress. The lifecycle accommodates this: + +- **Parked.** The sponsor can move an RFC from `draft` or `forum-posted` to `parked` if it's blocked on an external dependency (e.g., waiting on M012 enactment before M013 makes sense). Parked RFCs retain their ID and can be revived later by the sponsor; the parking reason is logged in §6. +- **Withdrawn.** The sponsor can withdraw at any state before `enacted`. Withdrawn RFCs are not deleted; their ID is permanently retired. A new RFC on the same question gets a new ID. +- **Superseded.** A new RFC can supersede a `ratified` or `enacted` RFC. The new RFC must explicitly cite the superseded one in its header and explain the delta. The old RFC's status moves to `superseded`. (For `enacted` RFCs, supersession requires a new on-chain proposal.) + +## Author roles: agents vs humans + +This is where the accountability chain lives. Mapping each role to who can occupy it: + +| Role | Codex agent | ElizaOS agent | Human contributor | Human steward | +|---|---|---|---|---| +| Spec author | yes | yes | yes | yes | +| RFC author | yes (with sponsor) | yes (with sponsor) | yes | yes | +| RFC sponsor | no | no | yes | yes | +| RFC ratifier | no | no | no | yes | +| Forum poster | drafts only — sponsor posts | drafts only — sponsor posts | yes | yes | +| On-chain proposer | no | no | yes | yes | + +The pattern: **agents accelerate the cheap parts (drafting, evidence-gathering, JSON generation, pre-flight checks); humans hold the accountable parts (sponsorship, ratification, on-chain submission).** + +## How this integrates with the rest of the system + +- **KOI** indexes specs, RFCs, simulation runs, forum threads, and on-chain proposals under stable IRIs. The `koi:rfc:RFC-XXXX` namespace becomes the canonical reference for RFC artifacts. Cross-document lineage (per §4 of the template) is queryable as graph traversal. + +- **Claims engine** uses the same 4-layer schema (claim, evidence, methodology, status) for ecological credits as the RFC template uses for governance. Same shape, different domain. This means tooling built for one chamber works on the other. + +- **RegenOS** is the coordinator. It watches: + - new RFCs (notifies stewards of incoming sponsorship requests) + - RFCs at `forum-posted` reaching their discussion deadline (prompts ratifier) + - RFCs at `ratified` (prompts proposer to generate on-chain proposal) + - RFCs at `enacted` (closes the loop, updates lineage) + +- **Reference accessibility gate** is the publication gate for any RFC graduating from `draft` to `forum-posted`. The audience tier in the RFC header drives the gate's strictness. + +- **Codex agent** plugs in at the spec layer and at the RFC drafting layer. Its PRs that touch governance-relevant surface (specs, simulations, contract behavior) are flagged for RFC twin generation; its PRs that don't (CI, lint, tests, docs) merge directly. This is the filter that converts agent throughput from "merge volume" into "candidate proposals worth elevating." + +## Governance Review Schema + +The graduation criteria above are designed so an agent can mechanically judge whether an RFC meets them. The canonical review schema lives in [`schema/rfc-review-schema.yaml`](./schema/rfc-review-schema.yaml), with the corresponding judgment output shape in [`schema/rfc-review-judgment.yaml`](./schema/rfc-review-judgment.yaml). See [`schema/README.md`](./schema/README.md) for how agents and human reviewers use them. + +The schema is structured as: + +- **`always` rules** — apply to any RFC at any state ≥ `draft`. Cover header completeness, claim decisiveness, evidence sufficiency, methodology lineage, append-only status log. +- **Gate-specific rules** — `spec-to-rfc`, `rfc-to-forum-posted`, `rfc-to-ratified`, `rfc-to-enacted`. Each gate's rules map directly to the corresponding §Promotion criteria section above. +- **Severities** — `blocker` (prevents graduation), `warning` (must be acknowledged but not blocking), `info` (advisory). + +A reviewer (agent or human) emits a structured judgment with verdict (`pass | needs-revision | fail`), per-rule findings with citations, and a `next_action` directive. This converts "is this RFC ready?" from a vibes-check into a structured checklist with citations, so reviewer attention concentrates on the 3–4 judgment-heavy rules per gate rather than mechanical hygiene. + +**What the schema deliberately does NOT do:** + +- It does not decide ratification. The schema can verify that ratification *criteria are met* but the ratifier (a human steward) still signs the §6 log row. This preserves the two-eyes principle. +- It does not resolve substantive disputes. If two reviewers disagree on whether a counter-position has been "addressed", the schema will flag both findings; humans arbitrate. The schema is a checklist, not a judge of philosophical adequacy. +- It does not handle on-chain submission. Schema rules verify post-hoc that the proposer was human, but never authorize submission. + +## Smallest possible first cut + +If the goal is to ship the smallest viable version of this: + +1. ✅ Create `rfcs/` directory with `_template.md`, `GRADUATION_RULES.md`, and `schema/` (this commit). +2. Pick **one** existing live question — e.g., the M013 fee split (28/25/45/2 vs. 15/30/50/5) — and write **RFC-0001** for it. This forces the template through real use and surfaces what's missing. +3. Run the full lifecycle once (draft → forum-posted → ratified → enacted) before scaling the pattern to the agent stack. +4. Then, and only then, retrofit the Codex agent's PR pipeline with the spec/RFC filter. + +The risk of designing the whole pipeline before running one RFC end-to-end is that the template will be wrong in ways that aren't visible until lived experience reveals them. + +## Open questions for these rules + +- **Who are the stewards / ratifiers?** This document assumes RND PBC members + designated community stewards. Needs explicit roster and rotation rules. +- **How do we handle RFCs that span multiple repos?** (e.g., a fee-split change touches agentic-tokenomics + regen-ledger + a frontend). Proposed: RFC lives in agentic-tokenomics if it's primarily a tokenomics decision; if multi-domain, sponsor decides repo and cross-references. +- **Dispute escalation.** What happens if the sponsor and ratifier disagree on whether deliberation was sufficient? Proposed: third steward arbitrates; if no resolution, RFC parks. +- **Relationship to existing forum governance.** Today, $REGEN governance has its own forum norms. This RFC track needs to either replace or sit alongside that. Recommendation: sit alongside initially, and let lived use determine whether it absorbs the existing track. +- **Relationship to DUNA / Regen Commons governance.** That's a parallel deliberation chamber for the Commons; this is for tokenomics. They likely converge over time but don't need to start unified. + +## Status + +This is `v0.1` of the graduation rules. Expect refinement through 1.0 as RFC-0001 surfaces gaps in real use. diff --git a/rfcs/README.md b/rfcs/README.md new file mode 100644 index 0000000..e21452f --- /dev/null +++ b/rfcs/README.md @@ -0,0 +1,47 @@ +# RFCs + +This directory holds Request-for-Comment documents for agentic-tokenomics — the **deliberation chamber** of the agentic-tokenomics → forum → on-chain pipeline. + +## What's an RFC here? + +An RFC is a decisive claim about the system, supported by evidence and methodology, with a named human sponsor accountable for shepherding it through deliberation. RFCs sit between **specs** (exploratory designs in `mechanisms/`, `phase-1..5/`) and **on-chain proposals** (executable transactions in `phase-4/proposals/`). + +Three artifact types, three purposes: + +| | Spec | RFC | On-chain Proposal | +|---|---|---|---| +| **Purpose** | Explore — what could exist | Decide — what should exist | Execute — what now exists | +| **Audience** | Designers, contributors | Stewards, $REGEN stakers, partners | Validators, on-chain governance | +| **Author scope** | Anyone (humans + agents) | Humans + agents (with human sponsor) | Humans only | +| **Location** | `mechanisms/`, `phase-N/` | `rfcs/RFC-XXXX.md` | `phase-4/proposals/RFC-XXXX-proposal.json` | + +The why and the full lifecycle are in [`GRADUATION_RULES.md`](./GRADUATION_RULES.md). + +## How to author an RFC + +1. **Read** [`GRADUATION_RULES.md`](./GRADUATION_RULES.md) and confirm a sponsor is willing. +2. **Copy** [`_template.md`](./_template.md) → `RFC-XXXX.md` (next sequential ID). +3. **Fill in** §0 Header, §1 Claim, §2 Evidence, §3 Methodology — the four load-bearing sections. +4. **Self-review** against the [governance review schema](./schema/) before requesting human review. If your draft has any `blocker`-severity failures, fix them first; this concentrates reviewer attention on substantive judgment, not mechanical hygiene. +5. **Open a PR.** A reviewer (agent or human) emits a structured judgment per the schema. Sponsor addresses findings, iterates. +6. **Graduate** through the lifecycle (`draft` → `forum-posted` → `ratified` → `enacted`) per the rules. + +## Index + +*Empty — this is the bootstrap commit. RFC-0001 will be the first concrete RFC; tracking begins here.* + +| ID | Title | Status | Sponsor | Last update | +|---|---|---|---|---| + +## Why this exists + +Today the code chamber of agentic-tokenomics works — agents ship PRs, CI gates merges, mechanism specs accumulate. The deliberation chamber barely exists in the repo. Without a structured deliberation step, two failure modes appear: + +1. **Specs accumulate without becoming decisive.** The repo becomes a great library of design exploration with no clear path from "we considered X" to "we decided X." +2. **Specs go directly to chain without deliberation.** Validators get asked to vote on under-deliberated changes; either they reject by default (chilling effect) or rubber-stamp (loss of governance legitimacy). + +The RFC layer closes both gaps. It's where claims get sharpened, evidence gets challenged, and a human sponsor takes accountability before anything reaches chain. + +## Status + +This is `v0.1` of the RFC process. Expect the template, graduation rules, and schema to evolve through 1.0 as the first RFCs are run end-to-end. Schema versions should themselves be governed by an RFC once the system is mature enough to bootstrap on itself. diff --git a/rfcs/_template.md b/rfcs/_template.md new file mode 100644 index 0000000..0eb7ef0 --- /dev/null +++ b/rfcs/_template.md @@ -0,0 +1,104 @@ +# RFC-XXXX — + + + +## 0. Header +- **ID:** RFC-XXXX +- **Title:** +- **Status:** draft +- **Author(s):** +- **Sponsor:** +- **Audience:** internal | partner | commons | public +- **Last updated:** YYYY-MM-DD +- **Supersedes:** +- **Superseded by:** + +## 1. Claim + +*One paragraph. The decisive proposition this RFC asserts. Not "we're exploring X" — that's a spec. RFCs make a claim that can be ratified or rejected. State it sharp.* + +Example: "REGEN's fee router (M013) should split protocol fees 15/30/50/5 between burn / treasury / validator / community pool, replacing the interim 28/25/45/2 split, because ." + +## 2. Evidence + +*Every claim has supporting evidence. Use the table below. Every evidence item must resolve for the audience tier declared in §0 (see the Reference Accessibility Gate in the workspace CLAUDE.md). KOI IRIs are preferred where available.* + +| # | Evidence | Type | Source | KOI IRI | URL (audience-accessible) | +|---|---|---|---|---|---| +| E1 | | simulation | simulations/M013/run-2026-04-20 | `koi:sim:m013-fee-split-2026-04-20` | | +| E2 | | empirical | regen-network mainnet | `koi:onchain:fee-dist-q1-2026` | | +| E3 | | deliberative | commonwealth.im | `koi:forum:thread-NNN` | | + +**Sufficiency assertion:** *Why this evidence is sufficient for the claim. State explicitly which evidence is **decisive** (load-bearing for ratification) vs. **supporting** (corroborates but doesn't independently establish).* + +## 3. Methodology + +*How the claim was derived from the evidence. Cite the spec(s), simulation runs, contract behaviors, or analytic frameworks involved. This section is where the lineage to the **code chamber** lives — every methodology entry should resolve to a path in `mechanisms/`, `simulations/`, `contracts/`, or an external method (with KOI IRI).* + +- **Spec lineage:** `mechanisms/m013-value-based-fee-routing/SPEC.md` §5.2 +- **Simulation lineage:** `simulations/M013/scenarios/fee-split-sweep.py` (run hash ``) +- **Contract lineage:** `contracts/fee-router/src/contract.rs` (commit ``) +- **External methodology:** + +## 4. Lineage + +*Where this RFC sits in the broader pipeline. Both directions:* + +- **Inbound:** specs / prior RFCs / claims this RFC depends on +- **Outbound:** RFCs / on-chain proposals / contract changes that depend on this one + +```mermaid +graph LR + M013[mechanisms/m013 SPEC] --> RFC[RFC-XXXX] + RFC --> Forum[Forum thread #NNN] + Forum --> Prop[On-chain proposal #MMM] + Prop --> ChainUpgrade[regen-1 upgrade] +``` + +## 5. Discussion surface + +*How and where this RFC is being deliberated.* + +- **Forum thread:** +- **Discussion deadline:** YYYY-MM-DD +- **Key counter-positions raised:** + +## 6. Status transitions (lifecycle log) + +*Append-only log. Each transition is a row. Never edit prior rows. The graduation rules (`rfcs/GRADUATION_RULES.md`) define the criteria for each move.* + +| Date | From | To | Trigger | Approver | +|---|---|---|---|---| +| YYYY-MM-DD | — | draft | author drafted | | + +## 7. On-chain enactment + +*Filled in only when status reaches `ratified`. Must specify: (a) the type of on-chain action; (b) deterministic generation rules so the proposal text can be reconstructed from this RFC.* + +- **Action type:** +- **Target chain:** regen-1 | redwood-1 | other +- **Generated proposal artifact:** `phase-4/proposals/RFC-XXXX-proposal.json` +- **Voting period:** +- **Pre-flight checks:** +- **Proposer (must be human):** +- **On-chain proposal ID:** +- **Result:** + +## 8. Open questions + +*Things that need resolution before this RFC graduates further. Each should have an owner and a target date. All must be resolved or explicitly carried as known limitations before graduating to ratified.* + +- [ ] OQ1 — (owner: , by: YYYY-MM-DD) +- [ ] OQ2 — + +## 9. References + +*Audience-accessibility-checked. No phantom references. If the §0 audience is `public`, only public URLs allowed. If `internal`, internal Drives are okay but unpack the substance inline. See the Reference Accessibility Gate in the workspace CLAUDE.md.* + +- [E1] +- [E2] +- [E3] diff --git a/rfcs/schema/README.md b/rfcs/schema/README.md new file mode 100644 index 0000000..9625575 --- /dev/null +++ b/rfcs/schema/README.md @@ -0,0 +1,41 @@ +# RFC Governance Review Schema + +Machine-readable schema for reviewing RFCs against the agentic-tokenomics graduation rules. Designed so an agent (or human reviewer) can mechanically check whether an RFC meets process and content criteria for any given lifecycle gate, then emit a structured judgment. + +## Files + +| File | Purpose | +|---|---| +| [`rfc-review-schema.yaml`](./rfc-review-schema.yaml) | The rules an agent runs over an RFC. Grouped into `always` rules + per-gate rules. Each rule has id, category, severity, pass/fail criteria, and citations back to graduation rules. | +| [`rfc-review-judgment.yaml`](./rfc-review-judgment.yaml) | The output shape — what the reviewer emits. Includes verdict, per-rule findings, recommendations, next_action, and audit trail. | + +## How agents use this + +The flow for an agent doing a review: + +1. **Locate the RFC** by path or ID; read the file at the requested commit SHA. +2. **Determine the gate** — the agent is asked to evaluate either: (a) a specific transition (e.g., "is this RFC ready for `forum-posted`?"), or (b) general validity (`always` rules only). +3. **Run rules** in order: `always` rules first, then gate rules. Short-circuit blockers if desired, but prefer to run all rules and emit a complete finding list — humans want to see the full picture, not just the first failure. +4. **Emit judgment** in the schema above. Persist to KOI (`koi:judgment:::`) so reviews are queryable historically. +5. **Notify the next actor** per `next_action`. RegenOS handles the routing. + +## Division of labor + +Not all rules are equally automatable. The expected division: + +- **Mechanical checks** (`R-HEADER-*`, `R-LIFECYCLE-*`, `R-EVIDENCE-002`, `R-G-FP-001..002`, `R-G-ENA-001..003`) — agents run these reliably; humans should rarely need to verify. +- **Judgment-heavy checks** (`R-CLAIM-001`, `R-EVIDENCE-001`, `R-G-RAT-002..004`) — agents flag candidates; humans make the final call. The schema is a checklist for sponsors and ratifiers, not a substitute for them. + +## What this schema deliberately does NOT do + +- **It does not decide ratification.** The schema can verify that ratification *criteria are met* but the ratifier (a human steward) still signs the §6 log row. This preserves the two-eyes principle. +- **It does not resolve substantive disputes.** If two reviewers disagree on whether a counter-position has been "addressed", the schema will flag both findings; humans arbitrate. The schema is a checklist, not a judge of philosophical adequacy. +- **It does not handle on-chain submission.** Schema rules verify post-hoc that the proposer was human, but never authorize submission. That remains a human action. + +## Recommended self-review before requesting human review + +Before opening a PR to add or transition an RFC, run the schema against your draft. If your draft has any `blocker`-severity failures, fix them before requesting human review. This concentrates reviewer attention on substantive judgment (does this claim hold?) rather than mechanical hygiene (is the header complete?). + +## Schema evolution + +This is `schema_version: 0.1`. Expect breaking changes through 1.0 as the first concrete RFCs (starting with the proposed RFC-0001 — M013 fee split, see `GRADUATION_RULES.md` §Smallest possible first cut) expose gaps. Schema versions should themselves be governed by an RFC once the system is mature enough to bootstrap on itself. diff --git a/rfcs/schema/rfc-review-judgment.yaml b/rfcs/schema/rfc-review-judgment.yaml new file mode 100644 index 0000000..ae438f9 --- /dev/null +++ b/rfcs/schema/rfc-review-judgment.yaml @@ -0,0 +1,60 @@ +# RFC Review Judgment — output schema +# Shape an agent or human reviewer emits after running rfc-review-schema.yaml +# against an RFC. Persisted under koi:judgment:::. + +# Example judgment (non-passing) for an RFC at the rfc-to-forum-posted gate: + +judgment: + schema_version: "0.1" + rfc_id: RFC-0001 + rfc_path: rfcs/RFC-0001.md + rfc_commit_sha: # snapshot reviewed + gate_evaluated: rfc-to-forum-posted # which gate's rules were run + evaluated_by: agent-001-registry-reviewer # agent ID or human handle + evaluated_at: 2026-04-25T19:30:00Z + + # Verdict semantics: + # pass — every blocker rule passed; any warnings acknowledged + # needs-revision — at least one blocker failed but failure is fixable by author + # fail — at least one blocker failed and failure is structural (e.g., no sponsor exists) + verdict: needs-revision + + findings: + - rule_id: R-HEADER-001 + status: pass # pass | fail | n-a + citation: "Header §0 — all required fields present" + + - rule_id: R-CLAIM-001 + status: fail + severity: blocker + citation: "§1 reads 'this RFC investigates whether the M013 fee split should change' — exploratory framing" + excerpt: "This RFC investigates whether the M013 fee split should change to reflect the new distribution targets..." + recommendation: "Rewrite §1 as a decisive claim, e.g., 'M013's fee split should be 15/30/50/5, replacing the interim 28/25/45/2.'" + + - rule_id: R-EVIDENCE-002 + status: fail + severity: warning + citation: "Evidence row E2 has no URL or KOI IRI" + recommendation: "Add koi:onchain:fee-dist-q1-2026 IRI or a public URL to E2" + + - rule_id: R-G-FP-002 + status: fail + severity: blocker + citation: "§5 discussion deadline is 2026-04-28; forum-posted log entry is 2026-04-25 — only 3 days, minimum is 7" + recommendation: "Extend discussion deadline to >= 2026-05-02" + + summary: | + RFC-0001 is structurally sound but cannot graduate to forum-posted yet. + Two blockers (R-CLAIM-001, R-G-FP-002) need author fix; one warning + (R-EVIDENCE-002) should be addressed but does not block. Estimated + revision effort: ~30 minutes. + + next_action: + actor: sponsor # who needs to act next + action: "Revise §1 to a decisive claim and extend §5 deadline; re-request review" + + audit_trail: + rules_evaluated: 14 + rules_passed: 11 + rules_failed: 3 + rules_skipped: 0 diff --git a/rfcs/schema/rfc-review-schema.yaml b/rfcs/schema/rfc-review-schema.yaml new file mode 100644 index 0000000..b2540b8 --- /dev/null +++ b/rfcs/schema/rfc-review-schema.yaml @@ -0,0 +1,223 @@ +# RFC Review Schema +# Canonical machine-readable review schema for the agentic-tokenomics RFC +# process. An agent or human reviewer runs the rules below over an RFC +# document and emits a structured judgment per rfc-review-judgment.yaml. +# +# Source of truth: rfcs/GRADUATION_RULES.md + +meta: + schema_version: "0.1" + applies_to: rfcs/RFC-*.md + review_authority: "any agent or human reviewer; binding decisions still require the human roles in GRADUATION_RULES.md §Author roles" + source: rfcs/GRADUATION_RULES.md + +categories: + process: "structural / format / completeness checks; mostly mechanical" + content: "substantive claim/evidence/methodology checks; require LLM judgment" + +severities: + blocker: "rule failure prevents graduation; verdict cannot be 'pass'" + warning: "rule failure does not block but must be acknowledged in judgment" + info: "advisory; does not affect verdict" + +# ───────────────────────────────────────────────────────────────── +# Always-on rules (apply to any RFC at any state >= draft) +# ───────────────────────────────────────────────────────────────── + +always: + - id: R-HEADER-001 + category: process + severity: blocker + rule: "Header §0 contains all required fields with non-empty values" + required_fields: [id, title, status, authors, sponsor, audience, last_updated] + passes_when: "every required field is present and non-empty" + fails_when: "any required field is missing or blank" + + - id: R-HEADER-002 + category: process + severity: blocker + rule: "Sponsor is human, not an agent ID" + passes_when: "sponsor field resolves to a human contributor" + fails_when: "sponsor matches agent-id pattern (codex-*, eliza-*, brawlaphant, *-bot)" + cite: "GRADUATION_RULES.md §Author roles" + + - id: R-HEADER-003 + category: process + severity: blocker + rule: "Status field is one of the allowed lifecycle states" + allowed_values: [draft, forum-posted, ratified, enacted, parked, withdrawn, superseded] + passes_when: "status is in allowed_values" + fails_when: "status is anything else" + + - id: R-HEADER-004 + category: process + severity: blocker + rule: "Audience tier is declared and valid" + allowed_values: [internal, partner, commons, public] + passes_when: "audience is in allowed_values" + + - id: R-LIFECYCLE-001 + category: process + severity: blocker + rule: "Status transition log §6 is append-only and consistent with current status" + passes_when: "the most recent log row's `to` field equals the header status; no row has been edited (per git history)" + fails_when: "header status disagrees with last log row, or rows have been retroactively edited" + + - id: R-CLAIM-001 + category: content + severity: blocker + rule: "§1 contains a decisive claim, not exploratory framing" + passes_when: "§1 is a single declarative statement asserting what should be done; can be a paragraph but must commit to a position" + fails_when: "§1 uses exploratory hedges ('we could', 'might consider', 'is exploring', 'this RFC investigates')" + cite: "GRADUATION_RULES.md §Promotion criteria — Spec → RFC, item 1" + + - id: R-EVIDENCE-001 + category: content + severity: blocker + rule: "§2 declares at least one decisive evidence item" + passes_when: "the §2 sufficiency assertion explicitly identifies >=1 evidence row as decisive (load-bearing for ratification)" + fails_when: "no evidence is marked decisive, or sufficiency assertion is missing" + + - id: R-EVIDENCE-002 + category: process + severity: warning + rule: "Each evidence row provides at minimum one resolvable reference (URL or KOI IRI)" + passes_when: "every row has a non-empty URL or KOI IRI column" + fails_when: "any row has neither a URL nor an IRI" + + - id: R-METHODOLOGY-001 + category: content + severity: blocker + rule: "§3 cites at least one repo path (spec, simulation, or contract) that supports the claim" + passes_when: "at least one path under mechanisms/, simulations/, or contracts/ is cited and resolves" + fails_when: "no repo path cited, or cited paths do not resolve in the current commit" + + - id: R-LINEAGE-001 + category: process + severity: warning + rule: "§4 declares at least inbound lineage (specs/RFCs this depends on)" + passes_when: "§4 has at least one inbound entry; can be 'none' if explicitly stated" + fails_when: "§4 is empty or omitted" + +# ───────────────────────────────────────────────────────────────── +# Gate-specific rules +# ───────────────────────────────────────────────────────────────── + +gates: + + spec-to-rfc: + description: "A spec graduates into RFC draft." + cite: "GRADUATION_RULES.md §Promotion criteria — Spec → RFC" + rules: + - id: R-G-S2R-001 + category: process + severity: blocker + rule: "A human sponsor has volunteered (header §0 Sponsor is non-empty and human)" + delegates_to: [R-HEADER-002] + + - id: R-G-S2R-002 + category: content + severity: blocker + rule: "No live conflicting RFC exists on the same question" + passes_when: "no RFC in state in {draft, forum-posted, ratified} addresses the same decision" + fails_when: "one or more conflicting RFCs exist; must be resolved/withdrawn first" + check_method: "scan rfcs/ for RFCs whose claim semantically overlaps; surface candidates for human disambiguation" + + - id: R-G-S2R-003 + category: content + severity: blocker + rule: "Reference accessibility gate is passable for declared audience tier" + passes_when: "every reference in §9 either resolves at the declared audience tier, OR has a noted elevation plan" + fails_when: "any reference is workspace-local or otherwise inaccessible to declared audience without an elevation plan" + cite: "workspace CLAUDE.md — Reference Accessibility Gate" + + rfc-to-forum-posted: + description: "Draft RFC moves to forum-posted state." + cite: "GRADUATION_RULES.md §RFC → forum-posted" + rules: + - id: R-G-FP-001 + category: process + severity: blocker + rule: "Forum thread URL is present in §5" + passes_when: "§5 forum thread field is a resolvable URL on commonwealth.im (or equivalent forum)" + + - id: R-G-FP-002 + category: process + severity: blocker + rule: "Discussion deadline is set and >=7 days from forum-post date" + passes_when: "§5 deadline is a future date >=7 days after the forum-posted log entry" + + - id: R-G-FP-003 + category: content + severity: blocker + rule: "Forum post references this RFC by ID and KOI IRI" + passes_when: "fetched forum thread body contains the RFC ID and koi:rfc:RFC-XXXX" + check_method: "fetch forum URL and grep for RFC ID + KOI IRI" + + rfc-to-ratified: + description: "Forum-posted RFC moves to ratified." + cite: "GRADUATION_RULES.md §RFC → ratified" + rules: + - id: R-G-RAT-001 + category: process + severity: blocker + rule: "Discussion deadline has passed" + passes_when: "today >= §5 deadline" + + - id: R-G-RAT-002 + category: content + severity: blocker + rule: "Every key counter-position in §5 has been addressed" + passes_when: "each entry in §5 counter-positions has either: (a) been incorporated into claim/methodology with a §6 log entry, or (b) been explicitly noted as 'considered and rejected because '" + fails_when: "any counter-position is unaddressed or noted as 'TODO'" + + - id: R-G-RAT-003 + category: content + severity: blocker + rule: "All §8 open questions are resolved or carried as known limitations" + passes_when: "every checkbox in §8 is either checked, or annotated 'carried as known limitation: '" + + - id: R-G-RAT-004 + category: content + severity: blocker + rule: "Decisive evidence in §2 has not been invalidated during discussion" + passes_when: "no §6 log entry or §5 counter-position invalidates a §2 row marked decisive without a replacement" + check_method: "LLM judgment over discussion + evidence delta" + + - id: R-G-RAT-005 + category: process + severity: blocker + rule: "Ratifier is named and distinct from sponsor" + passes_when: "the §6 log row transitioning to ratified has a non-empty Approver field that is not the sponsor" + cite: "GRADUATION_RULES.md §RFC → ratified, item 5 — two-eyes principle" + + rfc-to-enacted: + description: "Ratified RFC moves to enacted (on-chain proposal passed)." + cite: "GRADUATION_RULES.md §RFC → enacted" + rules: + - id: R-G-ENA-001 + category: process + severity: blocker + rule: "§7 on-chain enactment is fully filled out" + required_fields: [action_type, target_chain, generated_proposal_artifact, voting_period, pre_flight_checks] + passes_when: "all required_fields are present and non-empty" + + - id: R-G-ENA-002 + category: process + severity: blocker + rule: "On-chain proposal has a passed result" + passes_when: "queried chain returns proposal status = PASSED for the proposal ID cited in §7" + check_method: "use ledger MCP get_governance_proposal with cited proposal ID" + + - id: R-G-ENA-003 + category: process + severity: blocker + rule: "Pre-flight checks listed in §7 all show passing in CI" + passes_when: "every pre-flight check resolves to a green CI run on the merge commit prior to proposal submission" + + - id: R-G-ENA-004 + category: process + severity: blocker + rule: "On-chain proposer is human" + passes_when: "the on-chain submission tx is signed by a human key (not an agent service key)" + cite: "GRADUATION_RULES.md §RFC → on-chain proposal, critical rule"