Compare commits
10 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 cloudinit-bot
|
315ccb3fdc | ||
|
cloudinit-bot
|
977d2a1d24 | ||
|
cloudinit-bot
|
08dc139b5c | ||
|
cloudinit-bot
|
398609dabb | ||
|
cloudinit-bot
|
f57c49f7ad | ||
|
cloudinit-bot
|
ea11991ec7 | ||
|
cloudinit-bot
|
d10bf5eb24 | ||
|
cloudinit-bot
|
2c0e953881 | ||
|
cloudinit-bot
|
9e5e98f22e | ||
|
cloudinit-bot
|
aa66e58f95 |
+16
-11
@@ -1,14 +1,19 @@
|
||||
{
|
||||
"phase": 6,
|
||||
"stage": "complete",
|
||||
"milestone": "v0.6",
|
||||
"milestone_type": "feature",
|
||||
"tag_base": "v0.5.x",
|
||||
"phase_role": "final",
|
||||
"milestone": "v0.7",
|
||||
"milestone_complete": false,
|
||||
"milestone_release_tag": null,
|
||||
"release_id": 776,
|
||||
"project": "oy",
|
||||
"phase": 0,
|
||||
"phase_role": "pre_execution",
|
||||
"stage": "grill",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-18T15:00:00Z",
|
||||
"milestone_complete": true,
|
||||
"milestone_release_tag": "v0.5.6",
|
||||
"requirements_covered": ["REQ-040", "REQ-041", "REQ-042", "REQ-043", "REQ-044", "REQ-045"]
|
||||
}
|
||||
"updated_at": "2026-08-19T00:04:00Z",
|
||||
"next_milestone": null,
|
||||
"previous_milestone": {
|
||||
"milestone": "v0.6",
|
||||
"milestone_complete": true,
|
||||
"milestone_release_tag": "v0.5.6",
|
||||
"release_id": 776
|
||||
}
|
||||
}
|
||||
@@ -1,3 +1,4 @@
|
||||
<!-- Auto-generated from .ciagent/oy/oy-spec — PO edits oy-spec, not this file; see oy-state for current shipped state. -->
|
||||
# Architecture: OpenYield (oy) — Phase 0 Index
|
||||
|
||||
## Source
|
||||
@@ -511,4 +512,101 @@ skeleton-only in v0.3):
|
||||
Standing by reach-id at runtime (the v0.3 by-ID-string field becomes a
|
||||
query).
|
||||
- **Forge/Fold** — unchanged in v0.5 (no forge/fold runtime promotion this
|
||||
milestone).
|
||||
milestone).
|
||||
|
||||
---
|
||||
|
||||
## v0.7 Architecture (Fraternal Groups Foundation)
|
||||
|
||||
This section appends the v0.7 component map. v0.7 introduces a NEW module
|
||||
`x/cover` (D-084, D-039 precedent) and extends 4 existing modules. No
|
||||
breaking schema changes to locked-const firewall; G-003 production firewall
|
||||
intact; G-006 go.mod unchanged (`x/cover` uses existing cosmos-sdk substrate).
|
||||
|
||||
### v0.7 Component Index (new + extended modules)
|
||||
|
||||
| # | Component | Vision § | v0.7 Module | New/Ext | Phase | v0.7 Runtime Depth |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 8 | Cover Pool Factory (Pact #4 Cover graduated) | §16 | `x/cover` | New | P1-P5 | CoverPool + CoverCharter + CoverCall + CoverFeeTag structs + Factory keeper + Anti-Crowding-Out firewall + Anti-Capture Bill of Rights (13 rights) + Cover Claims Voucher role + Pool governance hybrid + category staging; simtest-grade runtime (D-020) |
|
||||
| 8 | Mutual Aid Bond (Pact #5 Bonds extended) | §17 | `x/bond` | Extended | P4 | MAB struct (anonymous embed of Bond) + CouponDenom enum (CoverCall/MutualAidCredit/Bread-rejected) + 3× annual surplus ceiling + tagged streaming use-of-proceeds (D-080); simtest |
|
||||
| 10 | Chapter Federation (Orgs extended) | §12 | `x/guild` | Extended | P3 | ParentGuildID + IsChapter + SecessionTermsHash + GoodStandingLiens fields on Guild + SecessionTerms struct + cooling consts (21d/14d) + Household simplified + Confederation Voice; simtest |
|
||||
| 6 | Shadow vouch weight + Cover Claims Voucher slash | §9.1, §9.4 | `x/standing` | Extended | P4 | ShadowVouchWeightMultiplier=0.5 const + IsShadow field on Vouch + SlashReasonFraudulentCoverCall const; simtest |
|
||||
| 10 | Stand→Pier boundary + Household/Confederation keeper logic | §11, §13 | `x/stand` | Extended | P3, P5 | StandPierEscalationAnnualPassVolumeCents const + Household one-tap exit + Confederation Voice aggregation (switch on existing StandType, no struct change); simtest |
|
||||
| 8 | Pact Cover cross-reference (no change) | §16 | `x/pact` | Unchanged | — | PactCover enum value stays as cross-reference (D-084, mirrors PactHubAPI ↔ x/hub); ExecuteCover() stub stays |
|
||||
|
||||
> The Cover Pool Factory is Pact #4 (Cover) per REQ-020/D-027. v0.2 stubbed
|
||||
> it as a PactType enum value inside `x/pact`; v0.7 promotes it to its own
|
||||
> `x/cover` module for the Factory + Charter + Bill of Rights + Voucher
|
||||
> runtime (D-084). The `x/pact` PactCover enum value stays as a
|
||||
> cross-reference; `x/cover` owns the runtime surface. This mirrors the
|
||||
> D-039 precedent (`x/hub` split from `x/pact`'s PactHubAPI in v0.3).
|
||||
|
||||
### v0.7 Cross-Component Dependencies (within v0.7)
|
||||
|
||||
Per the G-003 invariant (by-ID-string inter-module references; no struct
|
||||
imports across `x/<module>/types`), v0.7 components reference each other and
|
||||
the v0.2-v0.6 baseline by ID string only. The dependency edges that affect
|
||||
v0.7 phase ordering:
|
||||
|
||||
```
|
||||
x/cover ──(StandingKeeper shim)──► x/standing (P1: gate query; G-003 expected_keepers.go)
|
||||
x/cover ──(WatcherKeeper shim)──► x/watcher (P1: attestation pipeline; P4: MAB release witness)
|
||||
x/cover ──(BondKeeper shim)──► x/bond (P4: MAB issuance ceiling query)
|
||||
x/bond ──(CoverKeeper shim)──► x/cover (P4: MAB MsgDebitMABProceeds queries CoverKeeper.GetPoolReserveAccount; D-089(2) reverse edge — no import cycle, interface only)
|
||||
x/bond ──(Stand by id)──► x/stand (v0.2 baseline; MAB issuer-stand-id, unchanged)
|
||||
x/guild ──(Stand by id)──► x/stand (v0.2 baseline; Guild StandAffiliationID, unchanged)
|
||||
x/guild ──(Cover Pool by id)──► x/cover (P3: Chapter Federation liens reference Cover Pool covenants)
|
||||
x/cover ──(StillKeeper stub)──► x/still (P1: auto-pause on below-floor; P4: auto-Still on MAB misuse; D-089(1) simtest-local stub, NOT a real x/still keeper — x/still is NOT extended this milestone)
|
||||
x/cover ──(PactCover by id)──► x/pact (cross-reference only; no struct import)
|
||||
```
|
||||
|
||||
**Phase-ordering implication (informs D-082):** `x/cover` P1 lands the
|
||||
Factory + firewall + locked floors + gates + tagging first (firewall-first
|
||||
pattern). P2 extends `x/cover` with Charter + governance + staging. P3
|
||||
extends `x/guild` (Chapter Federation depends on Cover Pool existing for
|
||||
lien/covenant references). P4 extends `x/bond` (MAB depends on Cover Pool
|
||||
reserve existing for use-of-proceeds) + `x/standing` (Shadow vouch + Voucher
|
||||
slash). P5 lands the Anti-Capture Bill (cross-cutting; constrains all prior
|
||||
surfaces) + secession cooling + Pier boundary. Confidence 0.82.
|
||||
|
||||
### v0.7 Interface Contracts (6 cross-component — extended this milestone)
|
||||
|
||||
The six cross-component interfaces are EXTENDED in v0.7:
|
||||
|
||||
- **Standing API** — `x/cover` Factory queries Standing via expected-keeper
|
||||
shim (StandingKeeper.GetStandingBucket) for the Cover Pool Standing gate
|
||||
(REQ-049, D-077). By-ID-string at type level (G-003).
|
||||
- **Watcher Attestation Interface** — `x/cover` Factory + MAB release invoke
|
||||
Watcher attestation via WatcherKeeper shim. Cover-Charter signed by Pool
|
||||
Host + witnessed by Watcher (REQ-052). MAB proceeds release requires
|
||||
Watcher quorum (D-080).
|
||||
- **Window Lifecycle Interface** — unchanged in v0.7 (Cover-Charter
|
||||
amendments cooling uses the existing Window Duration semantics; secession
|
||||
cooling is a separate const-based mechanism, not a Window).
|
||||
- **Fee Covenant Interface** — unchanged in v0.7 (Cover-Fees are a separate
|
||||
tagging surface, not a Fee-Covenant route; the Anti-Crowding-Out firewall
|
||||
enforces the separation).
|
||||
- **Voice/Council Interface** — `x/cover` Pool governance hybrid (REQ-062)
|
||||
= Pool Host + 3 elected Masons + Watcher observer. No Anchor seat (§5
|
||||
Anchor no-Voice). MAB holders have NO Voice (REQ-063). Confederation Voice
|
||||
(REQ-058) aggregates one-per-Stand.
|
||||
- **Forge/Fold** — unchanged in v0.7.
|
||||
|
||||
### v0.7 Locked-Const Firewall Additions (GRILL-ratified D-086..D-090)
|
||||
|
||||
Per oy-state §3 + GRILL D-087, v0.7 adds 12 new locked consts (all net-new, no amendments to existing consts):
|
||||
|
||||
| Const | Value | Module | REQ |
|
||||
|-------|-------|--------|-----|
|
||||
| CoverReserveFloorAnnualContribX | 1.5 | x/cover | REQ-047 (locked) |
|
||||
| CoverReserveCeilingAnnualContribX | 2.5 | x/cover | REQ-048 (not locked) |
|
||||
| CoverStandingGateTrusted | 4.0 | x/cover | REQ-049 (locked) |
|
||||
| CoverStandingGatePreferred | 4.5 | x/cover | REQ-049 (locked) |
|
||||
| MABIssuanceCeilingAnnualSurplusMultiple | 3 | x/bond | REQ-054 (locked) |
|
||||
| CoolingSecessionCoverActiveDays | 21 | x/guild | REQ-064 (locked) |
|
||||
| CoolingSecessionNonCoverDays | 14 | x/guild | REQ-064 (locked) |
|
||||
| StandPierEscalationAnnualPassVolumeCents | 10000000 | x/stand | REQ-059 (not locked) |
|
||||
| CoverClaimsVoucherBondMultipleAvgCall | 10 | x/cover | REQ-055 (not locked) |
|
||||
| AntiCaptureBillOfRightsCount | 13 | x/cover | REQ-056 (locked) |
|
||||
| ShadowVouchWeightMultiplier | 0.5 | x/standing | REQ-060 (locked) |
|
||||
| PierCarriesVoice | false | x/guild | REQ-053 / FR-VOICE-6 (locked, D-087) |
|
||||
+54
-110
@@ -3,131 +3,75 @@ active_personas:
|
||||
- id: backend-engineer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Owns the v0.5 runtime promotion across P1..P7 — every keeper MsgServer message handler + simtest end-to-end flow for x/exit, x/bridge, x/bearers, x/partner, x/hub, x/services, x/bond, and x/council. This is the bulk of the milestone: the v0.3 skeletons were types + in-memory keeper stubs (verified — e.g. `x/partner/types/types.go:101 type Keeper struct{...}` with `NewKeeper()` returning `&Keeper{partners: make(map[string]Partner)}`, zero cosmos-sdk imports in `x/`). v0.5 adds `keeper/keeper.go` (store-backed), `keeper/msg_server.go` (one handler per `Msg*`), `types/msg_*.go` (`sdk.Msg` impls), `module.go` (RegisterServices), and a simtest exercising each handler against an in-memory `sdk.Context`. backend-engineer is the single persona that spans all seven runtime phases (P1..P7) plus the lexicon/locked-const regression guards that carry forward from v0.4. The reactivated cosmos-engineer/security-engineer/mesh-engineer personas advise on conventions and invariants but the implementation is backend-engineer's territory.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x (D-055 GRILL-approved), ibc-go v8.x, Go testing, simtest, lexicon firewall, locked-const invariant tests]
|
||||
territory: ["x/exit/**", "x/bridge/**", "x/bearers/**", "x/partner/**", "x/hub/**", "x/services/**", "x/bond/**", "x/council/**", "lexicon/**", "lexicon_meta_test.go", "lexicon_meta_docs/**"]
|
||||
constraints: ["G-003 production firewall intact — keeper-to-keeper cross-module calls use expected_keepers.go interface shims (ibc-go convention), NOT struct imports of x/<module>/types; by-ID-string rule preserved at the type level", "G-006 controlled exception (D-055) — go.mod gains cosmos-sdk v0.50.x + ibc-go v8.x (GRILL-ratified); types/ packages gain sdk.Msg imports for Msg* types but invariant/lexicon tests stay stdlib-only and green", "locked-const invariants unchanged — 8%/0% bond cap (D-028), 6 bearers, 4 Partner tiers, MissionLockAmendable=false, SignalKindCount=4 (P1-2 defensible), BearerTypeCount=6, BridgeStatusCount=4, ExitStatusCount=5, etc. — v0.5 ADDS ProposalKind/ProposalStatus/VoteOption enums (AUDIT §193 P1-1) but does NOT change existing locked consts", "lexicon firewall stays green on both x/ and docs/ after runtime promotion — Msg* struct names are the new lexicon surface (e.g. AVOID 'deposit' in x/hub custody message names; use MsgCustodyReceiveAsset/MsgCustodyReleaseAsset per A-542)", "simtest NOT mainnet (D-054) — handlers exercised against in-memory sdk.Context + dbm in-memory store; no real IBC light clients, no real MPC, no real bearer hardware, no real DEX venues, no real Watcher attestations (all stubbed)", "≥80% coverage on runtime packages (D-033 carries forward) — every keeper/msg_server.go + simtest must hit the bar; table-driven handler tests per Msg*", "Mission Lock const firewall intact (G-003) — MissionLockAmendment-Rejected ProposalKind is rejected at ValidateBasic (A-572); the const + the ValidateBasic gate are the dual firewall"]
|
||||
reason: "Owns the v0.7 runtime across all execution phases — the bulk of the milestone. v0.7 introduces a NEW module `x/cover` (Cover Pool Factory + Anti-Crowding-Out firewall + Anti-Capture Bill of Rights, per D-084) following the D-039 precedent (`x/hub` split from `x/pact` in v0.3). backend-engineer builds the `x/cover` types/ + keeper/ + module.go + expected_keepers.go + msg_server.go + simtest, mirroring the x/hub layout. Also owns EXTENSIONS: `x/bond` (MAB as anonymous-embed extension, mirroring GrowthBond), `x/guild` (ParentGuildID + IsChapter + SecessionTermsHash + GoodStandingLiens), `x/standing` (ShadowVouchWeightMultiplier const + IsShadow field + SlashReasonFraudulentCoverCall const), `x/stand` (Household/Confederation keeper logic — switch on existing StandType, no struct change), `x/pact` (PactCover stays as cross-reference, no change)."
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x (D-055), ibc-go v8.x, Go testing, simtest, lexicon firewall, locked-const invariant tests]
|
||||
territory: ["x/cover/**", "x/bond/**", "x/guild/**", "x/standing/**", "x/stand/**", "x/pact/**", "lexicon/**", "lexicon_meta_test.go", "lexicon_meta_docs/**", "lexicon_meta_web/**"]
|
||||
constraints:
|
||||
- "G-003 production firewall intact — x/cover references x/standing (StandingKeeper shim), x/watcher (WatcherKeeper shim), x/bond (BondKeeper shim) via expected_keepers.go interfaces; by-ID-string rule at type level; x/pact.PactCover stays as cross-reference (D-084, mirrors x/pact.PactHubAPI ↔ x/hub)"
|
||||
- "G-006 controlled exception (D-055) — go.mod unchanged in v0.7 (x/cover uses existing cosmos-sdk substrate); target G-028 diff baseline EMPTY"
|
||||
- "locked-const invariants — v0.7 ADDS consts (CoverReserveFloorAnnualContribX=1.5, CoverStandingGateTrusted=4.0, CoverStandingGatePreferred=4.5, MABIssuanceCeilingAnnualSurplusMultiple=3, CoolingSecessionCoverActiveDays=21, CoolingSecessionNonCoverDays=14, CoverClaimsVoucherBondMultipleAvgCall=10, AntiCaptureBillOfRightsCount=13, ShadowVouchWeightMultiplier=0.5, StandPierEscalationAnnualPassVolumeCents=10000000) but does NOT change existing locked consts"
|
||||
- "lexicon firewall stays green — Msg* names avoid banned terms (no 'deposit', no 'account', no 'insurance' — use 'Cover', 'Cover-Fee', 'Cover Call', 'Cover-Charter')"
|
||||
- "simtest NOT mainnet (D-054 continues) — x/cover keeper handlers exercised against in-memory sdk.Context"
|
||||
- "≥80% coverage on x/cover + extensions (D-033 carries forward)"
|
||||
- "Anti-Crowding-Out firewall (D-079) — x/cover/firewall subpackage rejects Cover-Fee routing outside contributor-pool semantics"
|
||||
- "MAB use-of-proceeds (D-080) — tagged streaming + Watcher-witnessed release; auto-Still on misuse"
|
||||
|
||||
- id: lead-developer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Coordinates v0.5 phase decomposition (P1 exit+bridge → P2 bearers → P3 anchors → P4 hub → P5 services → P6 bond → P7 council → P8 final review/audit/ship per D-056), territory enforcement (warn mode per config.json), and the final-phase feature purity gate audit (no breaking schema changes; locked-const firewall intact; G-003 production firewall intact). Owns the v0.5 ROADMAP.md / REQUIREMENTS.md status updates at milestone completion and the milestone ship. Also owns the GRILL-ratification follow-through for the cosmos-sdk version pin (A-504) and the planner-escalation items (A-562 reject-vs-clamp, A-572 reject-at-ValidateBasic, A-574 Watcher Veto quorum value) — these are escalated through the normal decision flow, not auto-decided.
|
||||
reason: "Coordinates v0.7 phase decomposition (P1..P6), territory enforcement (warn mode), and the final-phase feature purity gate audit. Owns the D-085 escalation (13th right identification — confidence 0.55; surfaced through normal decision flow before P5). Owns the §7 acceptance 'pen-test ≥1 independent third party' — at full autonomy, runs self-administered adversarial review (ci-griller) and logs as assumption unless PO rules otherwise."
|
||||
frameworks: [cross-cutting, Gitea Actions, Markdown, YAML, git]
|
||||
territory: [".ciagent/**", ".gitea/workflows/**", ".ciagent/oy/ARCHITECTURE.md", ".ciagent/oy/ROADMAP.md", ".ciagent/oy/REQUIREMENTS.md"]
|
||||
constraints: ["D-056 phase ordering (P1 exit → P2 bearers → P3 anchors → P4 hub → P5 services → P6 bond → P7 council → P8 final); each phase independently shippable (vertical slices)", "milestone versioning (v0.5 feature / tag_base v0.4.x); final-phase patch IS the milestone release (D-008)", "feature purity gate: zero breaking schema changes; zero locked-const amendments (Mission Lock non-amendable; SignalKind 4-not-5 unchanged); G-003 production firewall intact; G-006 controlled exception GRILL-ratified", "persona territory warn-mode enforcement (config.json)", "planner-escalation items (A-504 cosmos-sdk version pin, A-562 bond match reject-vs-clamp, A-572 MissionLockAmendment ValidateBasic rejection, A-574 Watcher Veto quorum) surfaced through the normal decision flow, not auto-decided"]
|
||||
constraints:
|
||||
- "D-082 phase ordering — P1 Cover Factory (foundation+firewall) → P2 Charter/governance/staging → P3 Federation/Household/Confederation → P4 MAB/Voucher/Shadow → P5 Bill of Rights/secession/Pier → P6 final; each phase independently shippable"
|
||||
- "milestone versioning (v0.7 feature / tag_base v0.6.x); final-phase patch IS the milestone release (D-008)"
|
||||
- "feature purity gate: zero breaking schema changes; zero locked-const amendments to EXISTING consts; G-003 intact; G-006/G-028 go.mod diff EMPTY"
|
||||
- "D-085 escalation (13th right) — low-confidence (0.55); surface to PO via normal decision flow before P5"
|
||||
- "§7 pen-test acceptance — self-administered adversarial review if no external third party; log as assumption"
|
||||
|
||||
- id: security-engineer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: REACTIVATED for v0.5. Owns the security-critical invariant surfaces introduced by runtime promotion: (1) the CustodyKeyring interface boundary in x/hub (D-058) — the Sign/Derive/Status contract + the in-memory memKeyring test impl, with key-rotation semantics (Status reports active key version; no caching across blocks); (2) the CLOB mission-lock clamp in x/bond (D-057) — the per-match coupon clamp to [0, 800] bps via the v0.3 Clamp helper, with a match above 800 REJECTED (fails closed, A-562; planner confirms reject-vs-clamp before P6); (3) IBC packet replay protection in x/bridge — the delete-on-ack / refund-on-timeout contract mirroring ibc-go (the CVE-class pitfall); simtest must cover both replay and timeout-refund; (4) the governance Mission-Lock const firewall in x/council (G-003) — MissionLockAmendable=false unchanged, the MissionLockAmendment-Rejected ProposalKind rejected at ValidateBasic (A-572), and the Watcher Veto quorum semantics (single Veto does NOT block; quorum-based, default 6 per REQ-004 6-of-9; A-574). The v0.3/v0.4 locked-const regression tests (TestMissionLockAmendableFalse, TestSignalKindShapeIntentional, the REQ-030 cross-const test) stay green.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x, ibc-go v8.x, Go testing, simtest, locked-const invariant tests, lexicon firewall]
|
||||
territory: ["x/hub/types/keyring.go", "x/hub/keeper/keyring_mem*.go", "x/bond/types/types.go", "x/bond/keeper/**", "x/bridge/keeper/**", "x/council/types/types.go", "x/council/keeper/**", "lexicon/**"]
|
||||
constraints: ["CustodyKeyring interface supports key rotation (Status reports active key version; handler consults keyring per operation, no cross-block caching)", "CLOB per-match coupon clamp to [0, 800] bps (D-028/D-057); match above 800 REJECTED (fails closed, A-562) — planner confirms reject-vs-clamp before P6", "IBC ack/timeout replay protection mirrors ibc-go (delete-on-ack, refund-on-timeout); simtest MUST cover both replay and timeout-refund cases (CVE-class pitfall)", "Mission Lock const firewall intact (G-003): MissionLockAmendable=false unchanged; MissionLockAmendment-Rejected ProposalKind rejected at ValidateBasic (A-572); Watcher Veto quorum-based (default 6, REQ-004 6-of-9), single Veto does NOT block (anti-greed, vision §19)", "locked-const regression tests stay green: TestMissionLockAmendableFalse, TestSignalKindShapeIntentional, the REQ-030 cross-const test (hub.LendingCouponCapBps==bond.CouponCapBps)", "compliance-before-custody ordering enforced in x/hub (withdrawal checks compliance status before the custody debit, A-544)", "lexicon firewall stays green — Msg* names avoid banned terms (e.g. 'deposit' banned; use MsgCustodyReceiveAsset/MsgCustodyReleaseAsset)"]
|
||||
reason: "REACTIVATED for v0.7 (carried from v0.5). v0.7 has the HIGHEST security-critical density since v0.5: (1) Anti-Capture Bill of Rights v0.2 (REQ-056) — 13 non-amendable, non-waivable rights as const firewall + ValidateBasic gate (mirroring MissionLockAmendable=false + MissionLockAmendmentRejected); (2) Anti-Crowding-Out firewall (D-079) — x/cover/firewall + lexicon_meta_cover meta-test; (3) Cover Claims Voucher slashing (REQ-055) — bond 10× avg Call size, no self-adjudication (FR-CPCV-2), slash via x/standing.Slash cross-Pool; (4) MAB use-of-proceeds lock (D-080) — tagged streaming + Watcher-witnessed release + auto-Still; (5) secession cooling + lien bounding (REQ-064/REQ-081); (6) Cover Pool reserve floor 1.5× (REQ-047) below-floor auto-pause."
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x, Go testing, simtest, locked-const invariant tests, lexicon firewall]
|
||||
territory: ["x/cover/types/rights.go", "x/cover/firewall/**", "x/cover/keeper/**", "x/bond/keeper/**", "x/bond/types/types.go", "x/guild/types/types.go", "x/standing/types/types.go", "x/council/types/types.go", "lexicon/**"]
|
||||
constraints:
|
||||
- "Bill of Rights = 13 separate RightID consts + 13 Waivable* bool consts (all false) + RightIsWaivable(id) always returns false (dual firewall: const + ValidateBasic gate on Cover-Charter waiver list)"
|
||||
- "Anti-Crowding-Out firewall = x/cover/firewall subpackage (runtime CheckCoverFeeRouting) + lexicon_meta_cover meta-test (test-time doc-drift rejection) — defense in depth (D-079)"
|
||||
- "Cover Claims Voucher: CoverClaimsVoucher struct in x/cover/types (NOT x/standing); bond = CoverClaimsVoucherBondMultipleAvgCall=10 × avg Call size; slash via x/standing.Slash with SlashReasonFraudulentCoverCall const; cross-Pool via Standing bucket drop"
|
||||
- "MAB coupons NEVER Bread — CouponDenom enum with CouponDenomBread rejected at ValidateBasic (MissionLockAmendmentRejected pattern)"
|
||||
- "Secession cooling consts secured at founding, not reducible (REQ-064 locked); GoodStandingLiens SecuredAtFounding=true not freely increasable (REQ-053/REQ-081)"
|
||||
|
||||
- id: cosmos-engineer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: REACTIVATED for v0.5. cosmos-sdk is now a load-bearing dependency (D-055 GRILL-approved controlled exception to G-006), so Cosmos-SDK convention alignment is owned rather than advisory. Owns: (1) the MsgServer promotion pattern across all 8 target modules — keeper/keeper.go (store-backed, wraps sdk.KVStore), types/msg_*.go (sdk.Msg: ValidateBasic + GetSigners), keeper/msg_server.go (one *Response,error method per Msg*), module.go (AppModule + RegisterServices), simtest exercising each handler against an in-memory sdk.Context; (2) the IBC v2 / IBC Eureka patterns in x/bridge (OnRecvPacket/OnAcknowledgementPacket/OnTimeoutPacket, timestamp-only timeouts for EVM chains, the ICS-20 v1 payload parser); (3) the expected_keepers.go shim convention (ibc-go standard for breaking cross-module keeper dep cycles — e.g. x/exit/types/expected_keepers.go defines a BridgeKeeper interface that the x/bridge keeper satisfies structurally; preserves G-003 by-ID-string rule at the type level); (4) the simtest scaffolding (in-memory store, sdk.Context construction, event emission assertions). The v0.3 in-memory Keeper stubs (in types/types.go) are retired or wrapped as test helpers — the types/ public API is not broken.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x (D-055), ibc-go v8.x, cometbft (simtest in-memory store only), Go testing, simtest]
|
||||
territory: ["x/exit/keeper/**", "x/exit/types/msg_*.go", "x/exit/types/expected_keepers.go", "x/exit/module.go", "x/bridge/keeper/**", "x/bridge/types/msg_*.go", "x/bridge/types/expected_keepers.go", "x/bridge/module.go", "x/bearers/keeper/**", "x/bearers/types/msg_*.go", "x/bearers/module.go", "x/partner/keeper/**", "x/partner/types/msg_*.go", "x/partner/types/expected_keepers.go", "x/partner/module.go", "x/hub/keeper/**", "x/hub/types/msg_*.go", "x/hub/types/expected_keepers.go", "x/hub/module.go", "x/services/keeper/**", "x/services/types/msg_*.go", "x/services/types/expected_keepers.go", "x/services/module.go", "x/bond/keeper/**", "x/bond/types/msg_*.go", "x/bond/types/expected_keepers.go", "x/bond/module.go", "x/council/keeper/**", "x/council/types/msg_*.go", "x/council/types/expected_keepers.go", "x/council/module.go"]
|
||||
constraints: ["MsgServer convention (cosmos-sdk v0.40+ Stargate): MsgServer struct wraps the module Keeper; one method per Msg* returning (*Response, error); routed by base app MsgServiceRouter", "sdk.Msg contract: ValidateBasic (stateless gate, runs before handler), GetSigners (authz), ProtoMessage/JSONCodec registration", "handler state-machine ordering: (1) ValidateBasic (in msg), (2) keeper authz check, (3) state mutation under store, (4) ctx.EventManager().EmitEvent — reordering causes double-spend/replay", "expected_keepers.go convention: cross-module keeper deps are INTERFACES defined in the consuming module's types/ (e.g. x/exit/types/expected_keepers.go BridgeKeeper); the concrete keeper satisfies it structurally; NOT a struct import of x/bridge/types — G-003 preserved", "IBC handlers implement the ibc-go IBCModule / PacketExecutor contract (OnRecvPacket/OnAcknowledgementPacket/OnTimeoutPacket); ICS-20 v1 payload pinned to the v0.2 satellite packet shape", "simtest uses SDK in-memory store (dbm in-memory backend) + sdk.NewContext; no live CometBFT node, no real IBC light clients (D-054)", "version pin (A-504, planner/GRILL confirms): cosmos-sdk v0.50.x LTS + ibc-go v8.x (stable); ibc-go v10 IBC-v2/Eureka is the documented pattern but a newer pin"]
|
||||
reason: "Advisory-density for v0.7. The `x/cover` module is new but follows the established x/hub D-039 pattern (types/ + keeper/ + module.go + expected_keepers.go + msg_server.go + simtest). The MsgServer promotion pattern is established (v0.5). cosmos-engineer reviews the x/cover AppModule wiring, RegisterServices, MsgServer() accessor, and the expected_keepers.go interface shims (StandingKeeper, WatcherKeeper, BondKeeper) for G-003 compliance. Less novel than v0.5 (where cosmos-sdk was first introduced)."
|
||||
frameworks: [cosmos-sdk v0.50.x, ibc-go v8.x, Go testing, simtest]
|
||||
territory: ["x/cover/keeper/**", "x/cover/types/msg_*.go", "x/cover/types/expected_keepers.go", "x/cover/module.go"]
|
||||
constraints:
|
||||
- "x/cover module follows x/hub layout (D-039 precedent): module.go AppModule + RegisterServices + MsgServer() accessor"
|
||||
- "expected_keepers.go interfaces for cross-module keeper access (G-003): StandingKeeper.GetStandingBucket, WatcherKeeper.Attest, BondKeeper.GetBond"
|
||||
- "Msg* structs implement sdk.Msg; ValidateBasic on each (cover-firewall, category-tag, standing-gate, reserve-floor, MAB-ceiling, rights-waiver-rejection)"
|
||||
- "simtest pattern: msg_server_simtest_test.go exercising handlers against in-memory sdk.Context (x/hub/keeper/msg_server_simtest_test.go precedent)"
|
||||
|
||||
- id: mesh-engineer
|
||||
active: true
|
||||
phase_specific: true
|
||||
reason: REACTIVATED for the bearer transport runtime in P2 (REQ-034). Owns the OY-SAT + OY-QR message handlers in x/bearers: MsgSendOYSATFrame, MsgReceiveOYSATFrame, MsgIssueOYQR, MsgConsumeOYQR, and the session lifecycle (Open/Active/Closed/Revoked). The v0.3 OYSATLink (surveillance-resistant=true locked) and OYQRCode (one-shot consumed flag) become the handler state objects. Key mesh-specific invariants: (1) OY-QR is one-shot — MsgConsumeOYQR flips consumed BEFORE the transfer effect (replay rejected idempotently, A-521); (2) the surveillance-resistant const is a runtime invariant — the handler must NOT emit geolocation or sender physical location (simtest asserts the event set has NO geolocation fields, a negative test); (3) the BearerTransport interface gains a store-backed impl (the keeper acts as the transport in simtest; no hardware/RF dep, D-054). Hardware integration is explicitly deferred. mesh-engineer is phase-specific (P2 only) — outside P2 the bearer transport territory reverts to backend-engineer.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x, Go testing, simtest, lexicon firewall]
|
||||
territory: ["x/bearers/keeper/**", "x/bearers/types/msg_bearer*.go", "x/bearers/types/types.go", "x/bearers/module.go", "x/bearers/simtest/**"]
|
||||
constraints: ["OY-QR one-shot: MsgConsumeOYQR flips consumed BEFORE the transfer effect (atomic per-tx; replay finds consumed==true and returns error idempotently, A-521)", "surveillance-resistant const is a runtime invariant — handler emits NO geolocation / sender physical location; simtest negative-test asserts the event set is geolocation-free", "BearerTransport interface gets a store-backed impl (keeper as transport in simtest); NO hardware/RF/LoRa/BLE/satellite Go libraries (D-054 — runtime = message-handling + session lifecycle, not hardware)", "session lifecycle mirrors the v0.2 Window lifecycle (Open/Active/Closed/Revoked) for consistency; frames received on Closed/Revoked sessions are rejected", "lexicon-safe: 'session', 'frame', 'bearer', 'QR', 'SAT' are safe; AVOID 'account'/'deposit' (use reach-id/Stash by ID)"]
|
||||
|
||||
phase_specific_personas:
|
||||
- id: data-engineer
|
||||
active: true
|
||||
phase_specific: true
|
||||
reason: REACTIVATED for P4 (Hub API runtime) ONLY — owns the hub custody state via an in-memory test store (the memKeyring + the keeper's store-backed custody asset records). The custody asset records are the closest thing to a data store in v0.5; there is NO real database and NO migration (the SDK in-memory store is the substrate). data-engineer's role is narrow: ensure the custody state shape (assetID → custody entry + sig ref + key version) is consistent with the CustodyKeyring interface and supports rotation. Removed after P4 (the hub runtime ships; later phases do not touch custody state shape). This mirrors the v0.3 data-engineer pattern (genesis schemas) but scoped to the P4 custody store.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x store, Go testing]
|
||||
territory: ["x/hub/keeper/keyring_mem*.go", "x/hub/keeper/custody_state*.go"]
|
||||
constraints: ["in-memory test store ONLY — no real database, no migration (D-054 simtest grade)", "custody state shape consistent with CustodyKeyring interface (assetID → custody entry + sig ref + key version); supports rotation", "removed after P4 (hub runtime ships; later phases do not touch custody state shape)"]
|
||||
|
||||
deactivated:
|
||||
deactivated_personas:
|
||||
- id: frontend-engineer
|
||||
reason: INACTIVE for v0.5. The v0.3 docs site (docs/**, mkdocs.yml) is COMPLETE; v0.5 has no UI/docs-content work. The docs build CI (REQ-032, v0.4) already covers docs-build on every push. Reactivate in v0.6+ if docs content is restructured or i18n is added.
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: "v0.7 is protocol-heavy, zero UI. The v0.6 web UI (web/) is complete; v0.7 does not touch web/. No frontend work in REQ-046..REQ-066."
|
||||
- id: docs-writer
|
||||
reason: INACTIVE for v0.5. Same reason as frontend-engineer — v0.3's docs-writer owned page content authoring; v0.5 has zero new docs pages. The only documentation work is the ARCHITECTURE.md v0.5 runtime section + this PERSONAS.md + RESEARCH.md, which is lead-developer/researcher architecture territory, not audience-content authoring. Reactivate if a future milestone adds docs pages.
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: "No docs-content work in v0.7. The only docs work is ARCHITECTURE.md v0.7 section + PERSONAS.md + RESEARCH.md, which is lead-developer territory."
|
||||
- id: mesh-engineer
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: "No bearer transport work in v0.7. The bearer runtime shipped in v0.5 and is untouched. Cover Pools are a protocol/financial surface, not a bearer/transport surface."
|
||||
- id: data-engineer
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: "No genesis-schema or custody-state work in v0.7. x/cover uses the SDK in-memory store pattern from v0.5; no new data-shape work."
|
||||
- id: ci-security-auditor
|
||||
reason: Default deactivated; activate in P8 (final review/audit/ship) for the v0.5 milestone audit and feature purity gate enforcement (no breaking schema changes; locked-const firewall intact; G-003 production firewall intact; G-006 controlled exception GRILL-ratified).
|
||||
|
||||
custom_personas: []
|
||||
---
|
||||
|
||||
# Personas: OpenYield (oy) — v0.5 (Bearers Runtime — Feature)
|
||||
|
||||
> This file supersedes the v0.4 PERSONAS.md for the v0.5 milestone. v0.5 is a
|
||||
> **feature** milestone (D-054): the v0.3 Bearers skeletons are promoted
|
||||
> from types + in-memory keeper stubs + invariant tests to live keeper
|
||||
> MsgServer message handlers + simtest-grade end-to-end flows. This is
|
||||
> NOT mainnet — D-020 continues to govern network deployment; runtime =
|
||||
> simtest-grade handlers, not live chain.
|
||||
>
|
||||
> The active roster is **backend-engineer + lead-developer + security-
|
||||
> engineer (REACTIVATED) + cosmos-engineer (REACTIVATED) + mesh-engineer
|
||||
> (REACTIVATED, P2 phase-specific)**. The v0.3 docs personas (frontend-
|
||||
> engineer, docs-writer) are deactivated because v0.5 has no docs-content
|
||||
> work (the docs site is complete from v0.3; the docs build CI is complete
|
||||
> from v0.4). data-engineer is reactivated as a P4-phase-specific persona
|
||||
> for the hub custody state (in-memory test store only; removed after P4).
|
||||
> ci-security-auditor is default off; activate in P8 for the final audit.
|
||||
>
|
||||
> cosmos-sdk is now a load-bearing dependency (D-055 GRILL-approved
|
||||
> controlled exception to G-006); go.mod gains cosmos-sdk v0.50.x +
|
||||
> ibc-go v8.x (A-504, planner/GRILL confirms the exact pin).
|
||||
|
||||
## Active Roster
|
||||
|
||||
| Persona | Active | Phase-specific | Territory |
|
||||
|---------|--------|-----------------|-----------|
|
||||
| backend-engineer | yes | no (all runtime phases P1..P7) | `x/{exit,bridge,bearers,partner,hub,services,bond,council}/**`, `lexicon*` |
|
||||
| lead-developer | yes | no (all phases) | `.ciagent/**`, `.gitea/workflows/**` |
|
||||
| security-engineer | yes | no (all runtime phases) | `x/hub` keyring, `x/bond` keeper, `x/bridge` keeper, `x/council` keeper, `lexicon/**` |
|
||||
| cosmos-engineer | yes | no (all runtime phases) | `keeper/**`, `types/msg_*.go`, `types/expected_keepers.go`, `module.go` across all 8 target modules |
|
||||
| mesh-engineer | yes | yes (P2 only) | `x/bearers/keeper/**`, `x/bearers/types/msg_bearer*.go`, `x/bearers/simtest/**` |
|
||||
| data-engineer | yes | yes (P4 only) | `x/hub/keeper/keyring_mem*.go`, `x/hub/keeper/custody_state*.go` |
|
||||
|
||||
## Phase-Persona Matrix
|
||||
|
||||
| Phase | Personas | Work |
|
||||
|-------|----------|------|
|
||||
| P0 (pre-execution) | lead-developer (spec/clarify/research/plan/grill/mvp-ux + ship) | this file + RESEARCH.md + ARCHITECTURE.md v0.5 sections; planner-escalation items surfaced |
|
||||
| P1 (exit + bridge runtime) | backend-engineer + cosmos-engineer + security-engineer | REQ-033: `x/exit` DEX swap routing + `x/bridge` L2↔L1 IBC packet handlers (5 L2 chains, D-059); ibc-go IBCModule contract; Solana wormhole-adapter branch; replay/timeout simtest |
|
||||
| P2 (bearers transport runtime) | backend-engineer + cosmos-engineer + mesh-engineer (phase-specific) | REQ-034: OY-SAT + OY-QR message handlers; session lifecycle; OY-QR one-shot consumed-before-transfer; surveillance-resistant invariant |
|
||||
| P3 (anchors onboarding runtime) | backend-engineer + cosmos-engineer + security-engineer | REQ-035: `x/partner` Anchor credential issuance + revocation handlers; Watcher-quorum authz via expected-keeper shim; P3→P4 hub dep broken by HubKeeper interface shim |
|
||||
| P4 (hub API B2B runtime) | backend-engineer + cosmos-engineer + security-engineer + data-engineer (phase-specific) | REQ-036: custody/lending/compliance handlers; CustodyKeyring interface + memKeyring (D-058); lending coupon clamp [0,800]; compliance-before-custody ordering; lexicon (avoid 'deposit' in Msg names) |
|
||||
| P5 (services runtime) | backend-engineer + cosmos-engineer | REQ-037: Care/SIM/Vault/Mail service lifecycle handlers; per-kind Msg* (typed dispatch); window-grant checked on every op |
|
||||
| P6 (bond market runtime) | backend-engineer + cosmos-engineer + security-engineer | REQ-038: Growth Bond issuance + secondary-market CLOB matching (D-057); per-match coupon clamp [0,800] (A-562 reject-above-cap, planner confirms); price-time priority FCFS (REQ-007); no AMM |
|
||||
| P7 (council governance runtime) | backend-engineer + cosmos-engineer + security-engineer | REQ-039: Proposal/VoteOption enums (AUDIT §193 P1-1); Voice lifecycle handlers; MissionLockAmendment-Rejected rejected at ValidateBasic (A-572); Watcher Veto quorum (A-574, default 6); SignalKind stays 4 |
|
||||
| P8 (final review/audit/ship) | lead-developer + ci-security-auditor (activated) | feature purity gate audit; locked-const firewall verification; G-003 + G-006 (D-055 exception) verification; milestone ship |
|
||||
|
||||
## Constraints Carried Forward
|
||||
|
||||
- **G-003 production firewall intact**: keeper-to-keeper cross-module calls use `expected_keepers.go` interface shims (ibc-go convention), NOT struct imports of `x/<module>/types`. The by-ID-string rule is preserved at the type level. Test-only cross-package imports remain exempt (the G-003 test exemption, used by REQ-030 in v0.4; simtest may import multiple `x/*/keeper` packages to wire shims).
|
||||
- **G-006 controlled exception (D-055)**: `go.mod` gains `cosmos-sdk v0.50.x` + `ibc-go v8.x` (GRILL-ratified). Scoped to runtime phases P1..P7; P0 + P8 stay dep-neutral where possible. `types/` packages gain `sdk.Msg` imports for `Msg*` types (isolated in `types/msg_*.go`); invariant/lexicon tests stay stdlib-only and green. Exact version pin is A-504 (planner/GRILL confirms).
|
||||
- **Locked-const invariants unchanged**: v0.5 ADDS `ProposalKind` (4) / `ProposalStatus` (5) / `VoteOption` (4) enums to `x/council/types` (AUDIT §193 P1-1 promotion, D-060) but does NOT change existing locked consts — `CouponCapBps=800` / `CouponFloorBps=0` (D-028), `BearerTypeCount=6`, `PartnerTierCount=4`, `MissionLockAmendable=false`, `SignalKindCount=4` (P1-2 defensible; v0.4 `TestSignalKindShapeIntentional` stays green), `BridgeStatusCount=4`, `ExitStatusCount=5`, `ServiceKindCount=4`, `HubServiceCount=3`, `CouncilKindCount=3`, etc. The REQ-030 cross-const test (`hub.LendingCouponCapBps==bond.CouponCapBps`) stays green.
|
||||
- **Lexicon firewall stays green**: the `lexicon_meta_test.go` (x/**/*.go) + `lexicon_meta_docs_test.go` (docs) automatically cover the new `keeper/`, `msg_server.go`, `simtest/` files. The new `Msg*` struct names are the lexicon surface — AVOID "deposit" in `x/hub` custody message names (use `MsgCustodyReceiveAsset`/`MsgCustodyReleaseAsset`, A-542); "coupon" not "interest"/"yield" in `x/bond`; "session"/"frame" safe in `x/bearers`; "veto" safe in `x/council`. Per-module lexicon assertions added to each new `keeper/` package.
|
||||
- **Simtest NOT mainnet (D-054)**: handlers exercised against in-memory `sdk.Context` + dbm in-memory store; no real IBC light clients, no real MPC, no real bearer hardware, no real DEX venues, no real Watcher attestations (all stubbed). The simtest does NOT assert front-running safety (out of scope for simtest-grade runtime; the CLOB handler is documented as NOT front-running-safe for mainnet, a Year-3+ concern).
|
||||
- **≥80% coverage on runtime packages (D-033 carries forward)**: every `keeper/msg_server.go` + simtest must hit the bar; table-driven handler tests per `Msg*`.
|
||||
|
||||
## Planner-Escalation Items (low-confidence assumptions, surfaced through the normal decision flow)
|
||||
|
||||
These are NOT auto-decided; the planner must resolve them before the corresponding phase lands:
|
||||
|
||||
1. **A-504** — cosmos-sdk / ibc-go version pin (proposed: cosmos-sdk v0.50.x + ibc-go v8.x; alternative: ibc-go v10 IBC-v2/Eureka). GRILL review. Confidence 0.78.
|
||||
2. **A-562** — bond CLOB match above 800 bps: REJECT (fails closed, proposed) vs CLAMP-with-refund (D-057 says "clamp"). Resolve before P6. Confidence 0.70.
|
||||
3. **A-572** — `MissionLockAmendment-Rejected` ProposalKind: reject at `ValidateBasic` (proposed, the message never reaches the handler) vs propose-then-fail (record Pending → auto-transition Failed with event). Resolve before P7. Confidence 0.80.
|
||||
4. **A-574** — Watcher Veto quorum value (proposed default: 6, matching REQ-004 6-of-9). Resolve before P7. Confidence 0.75.
|
||||
|
||||
## Removal Notes
|
||||
|
||||
- frontend-engineer and docs-writer were deactivated in v0.4 (no docs-content phase); they remain deactivated in v0.5 for the same reason (the docs site is complete from v0.3; the docs build CI is complete from v0.4). They will reactivate in v0.6+ if docs content is restructured or i18n is added.
|
||||
- cosmos-engineer, security-engineer, and mesh-engineer were deactivated in v0.3/v0.4 (lower Cosmos-convention / invariant density, no bearer hardware runtime); they are REACTIVATED in v0.5 because cosmos-sdk is now load-bearing (D-055), the runtime introduces new security-critical invariant surfaces (CustodyKeyring, CLOB clamp, IBC replay, Mission-Lock const firewall), and the bearer transport gets live handlers (P2).
|
||||
- data-engineer is reactivated as a P4-phase-specific persona (hub custody state, in-memory test store only) and removed after P4. This mirrors the v0.3 genesis-schema pattern but scoped narrowly to the P4 custody store.
|
||||
- ci-security-auditor is default off; activate in P8 for the final audit + feature purity gate.
|
||||
active: false
|
||||
phase_specific: true
|
||||
reason: "Default off; activates in P6 (final review/audit/ship) for the feature purity gate + the §7 acceptance pen-test (self-administered adversarial review)."
|
||||
+250
-1
@@ -2149,4 +2149,253 @@ The v0.6 deliverable MUST meet these explicit criteria (verified in P6 audit):
|
||||
5. **Standing score computed from locked formula constants**: the Standing screen score uses `x/standing/types` constants (`PriorMean=4.0`, `PriorWeight=10`, decay buckets, `ComputeDiversityBonus`, `GetVoucherWeight`, `GetStandingBucket`) — NOT hardcoded; the standing-score computed-from-locked-constants test (P4-03-01) asserts this.
|
||||
6. **Freeholder-eligible badge reflects `IsFreeholderEligible()`**: the Standing screen badge is green when `FreeholderSignals.IsFreeholderEligible()==true` and grey when false; the Freeholder-eligible badge test (P4-03-01) asserts the rendered badge matches the method output.
|
||||
7. **Window lifecycle transitions match `Window.Activate/Revoke/Expire`**: the Window screen lifecycle buttons call the real `x/window/types.Window.Activate/Revoke/Expire` methods (NOT a reimplementation); `Revoke()` on an Expired window is a no-op (v0.2 type contract); the lifecycle correctness test (P3-03-01) asserts the real methods are invoked.
|
||||
8. **No banned terms in any rendered page**: the per-handler rendered-HTML lexicon checks (P1-04-03, P2-03-01, P3-03-01, P4-03-01, P5-03-01) scan each screen's HTTP response body via `lexicon.FindBannedTerm` and pass; the `lexicon_meta_web/` file-scan firewall passes on all `web/**/*.{html,js,go}` files.
|
||||
8. **No banned terms in any rendered page**: the per-handler rendered-HTML lexicon checks (P1-04-03, P2-03-01, P3-03-01, P4-03-01, P5-03-01) scan each screen's HTTP response body via `lexicon.FindBannedTerm` and pass; the `lexicon_meta_web/` file-scan firewall passes on all `web/**/*.{html,js,go}` files.
|
||||
|
||||
---
|
||||
|
||||
# Plans: OpenYield (oy) — v0.7 (Fraternal Groups Foundation)
|
||||
|
||||
## Milestone Summary
|
||||
|
||||
- **Milestone**: v0.7 — Fraternal Groups Foundation
|
||||
- **Type**: Feature (≥1 `feat` phase; REQ-046..REQ-066 are feat-class primitives + a test adjunct for the Anti-Crowding-Out firewall in P1)
|
||||
- **Tag base**: `v0.6.x` patch line (P0 ships as `v0.6.0`; execution phases `v0.6.1..v0.6.5`; final phase `v0.6.6` IS the v0.7 milestone release per D-008)
|
||||
- **Phases**: 6 — P1..P5 (execution) + P6 (final review/audit/ship). Phase 0 (PLAN) is in progress.
|
||||
- **Depth**: simtest-grade runtime (D-054 continues) — keeper MsgServer handlers + simtest end-to-end flows for `x/cover` (NEW) + extensions to `x/bond`, `x/guild`, `x/standing`, `x/stand`. No live chain launch, no `app.go`/`cmd/oyd`.
|
||||
- **Coverage target**: ≥80% on `x/cover` + extensions (D-033 carries forward); lexicon assertion (REQ-012) in `x/cover` test file + the 4th meta-test (`lexicon_meta_cover`) for the Anti-Crowding-Out firewall doc-drift (D-079).
|
||||
- **New modules**: 1 (`x/cover` — Cover Pool Factory + Anti-Crowding-Out firewall + Anti-Capture Bill of Rights + Cover Claims Voucher). **Extended**: 4 (`x/bond` MAB, `x/guild` Chapter Federation, `x/standing` Shadow vouch + slash reason, `x/stand` Household/Confederation keeper logic + Stand→Pier const). **Unchanged**: 1 (`x/pact` — PactCover enum stays as cross-reference, D-084).
|
||||
- **Phase ordering** (D-082): P1 Cover Pool Factory + firewall + locked floors + gates + tagging (firewall-first) → P2 Cover-Charter + Pool governance + category staging → P3 Guild Charter + Chapter Federation + Household/Confederation + disclaimer → P4 MAB + Cover Claims Voucher + Shadow vouch + MAB seniority → P5 Anti-Capture Bill + secession cooling + Stand→Pier boundary + Pier selection → P6 final review/audit/ship.
|
||||
- **Personas**: backend-engineer (all phases), lead-developer (all phases — coordination + D-085 escalation + pen-test assumption), security-engineer (all phases — highest security density since v0.5), cosmos-engineer (all phases — advisory; x/cover follows x/hub pattern).
|
||||
|
||||
### Cross-Phase Dependency Map
|
||||
|
||||
```
|
||||
P1 (x/cover Factory + firewall + floors + gates + tagging)
|
||||
│
|
||||
├─► P2 (x/cover Charter + governance hybrid + category staging)
|
||||
│ │
|
||||
│ └─► P3 (x/guild Chapter Federation + Household + Confederation + disclaimer)
|
||||
│ │ (Chapter liens reference Cover Pool covenants)
|
||||
│ │
|
||||
│ └─► P5 (x/cover Anti-Capture Bill + x/guild secession cooling + x/stand Pier boundary + Pier selection)
|
||||
│
|
||||
└─► P4 (x/bond MAB + x/cover Cover Claims Voucher + x/standing Shadow vouch + MAB seniority)
|
||||
│ (MAB depends on Cover Pool reserve for use-of-proceeds;
|
||||
│ Voucher slash depends on x/standing.Slash existing)
|
||||
│
|
||||
└─► P5 (Anti-Capture Bill constrains MAB no-Voice + Voucher independence + secession)
|
||||
```
|
||||
|
||||
### v0.7 Locked-Const Firewall Additions (GRILL-ratified D-086..D-090)
|
||||
|
||||
12 new locked consts (all net-new, no amendments to existing consts — per oy-state §3 + ARCHITECTURE.md v0.7 section + GRILL D-087 adding PierCarriesVoice as 12th):
|
||||
|
||||
| Const | Value | Module | REQ | Locked? |
|
||||
|-------|-------|--------|-----|---------|
|
||||
| CoverReserveFloorAnnualContribX | 1.5 | x/cover | REQ-047 | yes |
|
||||
| CoverReserveCeilingAnnualContribX | 2.5 | x/cover | REQ-048 | no (bounded [1.5, 2.5]) |
|
||||
| CoverStandingGateTrusted | 4.0 | x/cover | REQ-049 | yes |
|
||||
| CoverStandingGatePreferred | 4.5 | x/cover | REQ-049 | yes |
|
||||
| MABIssuanceCeilingAnnualSurplusMultiple | 3 | x/bond | REQ-054 | yes |
|
||||
| CoolingSecessionCoverActiveDays | 21 | x/guild | REQ-064 | yes |
|
||||
| CoolingSecessionNonCoverDays | 14 | x/guild | REQ-064 | yes |
|
||||
| StandPierEscalationAnnualPassVolumeCents | 10000000 | x/stand | REQ-059 | no |
|
||||
| CoverClaimsVoucherBondMultipleAvgCall | 10 | x/cover | REQ-055 | no |
|
||||
| AntiCaptureBillOfRightsCount | 13 | x/cover | REQ-056 | yes |
|
||||
| ShadowVouchWeightMultiplier | 0.5 | x/standing | REQ-060 | yes |
|
||||
| PierCarriesVoice | false | x/guild | REQ-053 (FR-VOICE-6) | yes (D-087) |
|
||||
|
||||
---
|
||||
|
||||
## Phase P0 — Pre-Execution
|
||||
|
||||
- **Type**: docs
|
||||
- **Tag**: `v0.6.0`
|
||||
- **REQs**: none (pre-execution)
|
||||
- **Status**: IN PROGRESS (SPECIFY ✓, CLARIFY ✓, RESEARCH ✓, PLAN in progress, GRILL pending, MVP/UX pending, SHIP pending)
|
||||
|
||||
---
|
||||
|
||||
## Phase P1 — Cover Pool Factory + Firewall + Locked Floors + Gates + Tagging
|
||||
|
||||
- **Type**: feat + test (firewall-first vertical slice)
|
||||
- **Tag**: `v0.6.1`
|
||||
- **REQs**: REQ-046, REQ-047, REQ-049, REQ-050
|
||||
- **Module**: NEW `x/cover` (mirrors x/hub D-039 layout)
|
||||
- **Personas**: backend-engineer (types + keeper + module + simtest), security-engineer (firewall + locked floors + gates), cosmos-engineer (AppModule + expected_keepers + Msg*), lead-developer (regression guards)
|
||||
|
||||
### P1 Must-Haves
|
||||
|
||||
1. **`x/cover` module skeleton** — `x/cover/types/types.go` (CoverPool, CoverFeeTag, CoverCategory, CoverCategoryPhase structs + locked consts), `x/cover/types/expected_keepers.go` (StandingKeeper, WatcherKeeper, BondKeeper, StillKeeper interfaces — G-003 shims), `x/cover/types/msg_cover.go` (MsgLaunchCoverPool, MsgRouteCoverFee, MsgFileCoverCall — `sdk.Msg` impls with ValidateBasic), `x/cover/keeper/keeper.go` (store-backed), `x/cover/keeper/msg_server.go` (one handler per Msg*), `x/cover/keeper/firewall.go` (Anti-Crowding-Out firewall enforcement), `x/cover/module.go` (AppModule + RegisterServices + MsgServer() accessor). Layout mirrors `x/hub/` (D-039 precedent).
|
||||
2. **Anti-Crowding-Out firewall (D-079)** — `x/cover/firewall/` subpackage with `CheckCoverFeeRouting(path) error` that rejects any code path routing Cover-Fees outside contributor-pool semantics. Called at the start of every `MsgRouteCoverFee` handler. PLUS `lexicon_meta_cover/` meta-test (4th lexicon meta-test, mirrors `lexicon_meta_web/` pattern) scanning `x/cover/**` docstrings + `x/cover/firewall/**` for doc drift. Defense in depth: runtime rejects code path, meta-test rejects doc drift.
|
||||
3. **Reserve floor 1.5× (REQ-047 locked)** — `CoverReserveFloorAnnualContribX = 1.5` const in `x/cover/types`. `MsgRouteCoverFee` handler invokes `checkReserveFloor(ctx, poolID)`; if `pool.ReserveAnnualContribRatio < 1.5`, REJECT routing AND emit `PoolBelowFloor` event that triggers auto-pause for subsequent routings until reserve replenished. Below-floor auto-pause = the handler sets a `PoolPaused bool` on the CoverPool; subsequent `MsgRouteCoverFee` handlers reject while paused.
|
||||
4. **Standing gate minimums (REQ-049 locked, D-077)** — `CoverStandingGateTrusted = 4.0` + `CoverStandingGatePreferred = 4.5` consts in `x/cover/types` (cross-documented to `x/standing.BucketTrusted`/`BucketPreferred`). `MsgLaunchCoverPool` handler invokes `StandingKeeper.GetStandingBucket(hostReachID, category)` for each category the Pool covers; if any category's gate is below the locked minimum (Trusted 4.0 for Travel, Preferred 4.5 for Health-MCS), REJECT the launch. Gate binds at Factory runtime (D-077). Pool MAY tighten (a `PoolStandingGate` Params field ≥ protocol minimum); NEVER loosen (the const floor).
|
||||
5. **Cover-Fee category tagging (REQ-050 locked)** — `CoverFeeTag` struct in `x/cover/types` (`{GrainAmount int64, CategoryTag string, PoolID string}`). `MsgRouteCoverFee` handler validates the tag against the Pool's allowed categories; category-mismatch → REJECT (FR-COVER-11). Pool-level fungibility preserved for net-reserve accounting.
|
||||
6. **Factory runtime (REQ-046)** — `MsgLaunchCoverPool` handler: validates reserve floor (REQ-047), validates Standing gate per category (REQ-049), validates category is in an allowed phase (REQ-065 staging — **D-086: P1 Factory is functional for Phase-2 categories ONLY** [Travel/HealthMCS/IncomePause]; `FactoryAllowedPhases` Params field is set to `[Phase2]` only in P1; Phase3/Phase4 categories are REJECTED in P1. P2 extends `FactoryAllowedPhases` to `[Phase2, Phase3, Phase4]` with full staging), witnesses Cover-Charter (REQ-052 — **D-090(1): Charter types + `RightID` + 13 `Waivable*` consts + `RightIsWaivable()` + `ValidateBasic` gate land in P2, NOT P1**; P1 Factory accepts a Charter hash placeholder only, with no `WaivedRights` field validation until P2). Watcher attestation pipeline: `WatcherKeeper.Attest(poolID, launchPayload)` called at launch; stubbed in simtest.
|
||||
7. **Simtest** — `x/cover/keeper/msg_server_simtest_test.go` exercising: (a) successful Pool launch with valid Standing + reserve; (b) rejected launch below Standing gate; (c) rejected launch below reserve floor; (d) rejected Cover-Fee routing with category mismatch; (e) auto-pause on below-floor + recovery on reserve replenishment; (f) firewall rejection of an out-of-pool routing path; **(g) D-086: rejected out-of-phase category launch (Phase 3 category rejected in P1 because only Phase 2 is allowed)**.
|
||||
8. **Lexicon + locked-const regression** — `x/cover/types/types_test.go` asserts the 4 new consts + lexicon assertion (no banned terms in `x/cover/**` — "Cover", "Cover-Fee", "Cover Call", "Cover-Charter" are the lexicon-clean names; NOT "insurance", "premium", "claim", "policy" per **D-088: `lexicon_meta_cover` uses a new `lexicon.CoverBannedTerms()` helper** [scoping the 4 Cover-specific terms to the Cover surface, avoiding false positives in non-Cover modules where "claim" is a common English word]). The `lexicon_meta_cover/` meta-test is the 4th lexicon firewall. **D-088(3) optional cleanup: replace `x/pact` "insurance-like" docstrings (`x/pact/types/types.go:36,158`) with "Cover-like" as a P1 doc-fix** (low-risk, no behavior change, removes latent lexicon debt).
|
||||
9. **Coverage ≥80%** on `x/cover/types` + `x/cover/keeper` + `x/cover/firewall`.
|
||||
10. **D-089(1): `StillKeeper` is satisfied by a simtest-local stub** (test-only, G-003 exempt), NOT a real `x/still` keeper. `x/still` is NOT extended this milestone. The P1 below-floor auto-pause invokes `StillKeeper.Still(poolID, "below floor")` on the stub.
|
||||
|
||||
### P1 Firewall-First Rationale
|
||||
|
||||
P1 lands the Anti-Crowding-Out firewall + locked floors + Standing gates BEFORE any Cover surface that could route around them (P2 Charter, P3 Federation, P4 MAB, P5 Bill of Rights). This is the D-044/D-069 firewall-first pattern: the firewall is in place before the content it guards.
|
||||
|
||||
---
|
||||
|
||||
## Phase P2 — Cover-Charter + Pool Governance Hybrid + Category Staging
|
||||
|
||||
- **Type**: feat
|
||||
- **Tag**: `v0.6.2`
|
||||
- **REQs**: REQ-048, REQ-052, REQ-062, REQ-065
|
||||
- **Modules**: extends `x/cover` (Charter + governance + staging) + `x/council` (Pool Council seat — no struct change, keeper logic)
|
||||
- **Personas**: backend-engineer (Charter + staging types + keeper), security-engineer (Charter validation + governance observer quorum), cosmos-engineer (Msg* + keeper handlers)
|
||||
|
||||
### P2 Must-Haves
|
||||
|
||||
1. **Cover-Charter (REQ-052 locked) + D-090(1) Bill of Rights types land HERE** — `CoverCharter` struct in `x/cover/types` (`{CharterID, PoolID, StatementOfBeliefsHash []byte, DisputePath string, Gate string, HoldingPeriodDays uint32, HostReachID string, WatcherWitnessHash []byte, Amendments []CharterAmendment, WaivedRights []RightID}`). `MsgSignCoverCharter` handler: signed by Pool Host + witnessed by Watcher. Amendments require Pool supermajority + 7-day cooling + Watcher + Counsel. **Protocol does NOT enforce SoB content** (FR-CHTR-5). **D-090(1) Bill of Rights temporal-gap fix:** `x/cover/types/rights.go` lands in P2 (NOT P5): 13 `RightID` consts + 13 `Waivable*` bool consts (all `false`) + `RightIsWaivable(id RightID) bool` (always returns `false`) + `AntiCaptureBillOfRightsCount = 13` const. The `MsgSignCoverCharter.ValidateBasic` gate rejects any `WaivedRights` element (dual firewall: const + ValidateBasic, mirroring MissionLockAmendable + MissionLockAmendmentRejected). **The 12 enumerated rights + D-085 13th-right candidate (`RightNonParticipationNoDenial`, confidence 0.55) all land in P2.** P5 then adds the *ceremony* surface (Counsel review handler, full Bill-of-Rights simtest cases). **D-090(4): D-085 escalation window tightened to before P2** — lead-developer surfaces D-085 to PO before P2; fallback at P2: log `RightNonParticipationNoDenial` as the 13th right and proceed.
|
||||
2. **Reserve ceiling 2.5× (REQ-048 not locked)** — `CoverReserveCeilingAnnualContribX = 2.5` const (the bounded upper limit). Pool Council MAY vote within [1.5×, 2.5×] via a `PoolReserveTarget` Params field. Watcher escalation to 2.5× after 12 months operating history. The 1.5× floor (P1) is NOT tunable. **D-090(3): the `CoverStandingGateTrusted`/`CoverStandingGatePreferred` floor is enforced at BOTH (a) the `MsgLaunchCoverPool` handler AND (b) the `MsgAmendPoolStandingGate` (Params-amendment) `ValidateBasic`** — a Pool must not be able to *store* a below-floor gate even if the launch would reject it. Same dual-check applies to the reserve target (amendment ValidateBasic rejects below 1.5× or above 2.5×).
|
||||
3. **Pool governance hybrid (REQ-062 locked)** — `PoolCouncil` struct in `x/cover/types` (`{PoolID, HostReachID, ElectedMasonReachIDs [3]string, WatcherObserverReachID string}`). `MsgElectPoolMason` handler (Pool-eligible Masons elect 3). `MsgVoteCoverCall` handler: majority required with Watcher observer present. **No Anchor seat** (§5). No MAB-holder seat (REQ-063 — lands in P4 but the governance struct excludes them now).
|
||||
4. **Category staging (REQ-065 locked)** — `CoverCategoryPhase` enum in `x/cover/types` (`Phase2`/`Phase3`/`Phase4`). `CoverCategory` enum (`Travel`/`HealthMCS`/`IncomePause`/`EquipmentLoss`/`LifeBurial`/`RoadSide`/`CyberSkimming`/`GuildInternalMutualAid`). Phase 2 = Travel + HealthMCS + IncomePause; Phase 3 = EquipmentLoss + LifeBurial + RoadSide; Phase 4 = CyberSkimming + GuildInternalMutualAid. **D-086: `FactoryAllowedPhases` Params field extended from P1's `[Phase2]` to `[Phase2, Phase3, Phase4]`** with full staging rejection of out-of-phase launches.
|
||||
5. **Simtest** — (a) successful Charter signing + Watcher witness; **(b) D-090(1) Charter with `WaivedRights` non-empty → REJECTED at ValidateBasic**; (c) Charter amendment with 7-day cooling + supermajority; (d) Pool Council election (3 Masons); (e) Cover Call vote with Watcher observer present (succeeds) + absent (rejects); **(f) D-086 Factory rejects out-of-phase category launch (Phase 4 category when only Phase 2/3 allowed)**; (g) reserve ceiling escalation after 12-month age check; **(h) D-090(3) Pool Standing gate amendment below floor → REJECTED at ValidateBasic**.
|
||||
6. **Lexicon + locked-const regression** — `x/cover/types/types_test.go` extended with the ceiling + phase + category consts + `AntiCaptureBillOfRightsCount=13` + 13 `Waivable*` consts all false + `RightIsWaivable` always false. Lexicon assertion on new Msg* names.
|
||||
7. **Coverage ≥80%** on the extended `x/cover` surface.
|
||||
|
||||
---
|
||||
|
||||
## Phase P3 — Guild Charter + Chapter Federation + Household/Confederation + Disclaimer
|
||||
|
||||
- **Type**: feat
|
||||
- **Tag**: `v0.6.3`
|
||||
- **REQs**: REQ-051, REQ-053, REQ-057, REQ-058, REQ-061
|
||||
- **Modules**: extends `x/guild` (Parent/Chapter + secession terms + liens + Household + Confederation) + `x/stand` (Household/Confederation keeper logic)
|
||||
- **Personas**: backend-engineer (Guild extension + keeper), security-engineer (lien bounding + secession cooling consts), cosmos-engineer (Msg* + keeper handlers)
|
||||
|
||||
### P3 Must-Haves
|
||||
|
||||
1. **Guild Charter + Common Bond (REQ-051 locked)** — extend `x/guild/types.Guild` with `CommonBondHash []byte` + `PublicProfile GuildPublicProfile` fields. `GuildPublicProfile` struct (`{BondSummary string, Disclaimers []string, MasonCount uint32_or_Private bool, PierWrapperID string}`). `MsgCreateGuild` handler (extended): Common Bond declared + hash-pinned at creation; Public Profile published. `MasonCount` is either a count or a `"private"` sentinel.
|
||||
2. **Chapter Federation (REQ-053) + D-087 PierCarriesVoice const** — extend `x/guild/types.Guild` with `ParentGuildID string` (empty for Parent Guilds) + `IsChapter bool` + `SecessionTermsHash []byte` + `GoodStandingLiens []Lien`. `Lien` struct (`{Amount int64, CreditorReachID string, SecuredAtFounding bool}`). `MsgCreateChapter` handler: Parent Guild + Chapter model; Chapter inherits Parent's policies + MAY tighten but NOT loosen. Secession terms coded at founding (a `SecessionTerms` struct: `{CoolingCoverActiveDays uint32, CoolingNonCoverDays uint32, LienAuditRequired bool, CovenantClearanceRequired bool}` — hash-pinned at creation, immutable). Good-standing liens at founding (NOT freely increasable — `SecuredAtFounding=true` liens reject `MsgAddLien`). **D-087: `PierCarriesVoice = false` const in `x/guild/types`** (the 12th locked const per the GRILL-ratified table — FR-VOICE-6: Pier does NOT carry Voice; mission-locked invariant). Chapter retains mesh-level Voice (the const enforces that the Pier wrapper does NOT carry Voice regardless of fiduciary role).
|
||||
3. **Household simplified (REQ-057)** — `x/stand` keeper: `IsHousehold(standID)` check (switch on `StandType == StandHousehold`). Household Stands skip the formal-Council requirement. `MsgOneTapExitStand` handler — the dispute path for Household. One-tap exit = the Stand is dissolved + assets returned to the Holder's Stash; no Council vote required.
|
||||
4. **Confederation Voice (REQ-058 locked)** — `x/stand` keeper: `GetConfederationVoice(confederationStandID) []Voice` aggregates member-Stand Voice one-per-Stand. Internal bundle delegation via §19 delegation (existing `x/council` Voice mechanics — a `MsgDelegateConfederationVoice` handler). One-Stand-one-Vote: each member Stand gets exactly 1 Voice in the Confederation's aggregate, regardless of size.
|
||||
5. **Disclaimer cadence (REQ-061 locked)** — `MsgCreateGuild` + `MsgCreateChapter` + `MsgSignCoverCharter` handlers all surface a jurisdictional disclaimer at every charter signing (a `Disclaimer string` field on each Msg; the handler returns the disclaimer in the response). NOT session-bounded.
|
||||
6. **Simtest** — (a) Guild creation with Common Bond hash + Public Profile; (b) Chapter creation with secession terms hash-pinned + good-standing liens; (c) Chapter inherits Parent policy + tightens (allowed) + loosens (rejected); (d) Household one-tap exit; (e) Confederation Voice aggregation (one-per-Stand); (f) disclaimer surfaced at every signing.
|
||||
7. **Lexicon + locked-const regression** — `x/guild/types/types_test.go` extended with the cooling consts (`CoolingSecessionCoverActiveDays=21`, `CoolingSecessionNonCoverDays=14`). Lexicon assertion on new Msg* names.
|
||||
8. **Coverage ≥80%** on the extended `x/guild` + `x/stand` surfaces.
|
||||
|
||||
---
|
||||
|
||||
## Phase P4 — Mutual Aid Bond + Cover Claims Voucher + Shadow Vouch + MAB Seniority
|
||||
|
||||
- **Type**: feat
|
||||
- **Tag**: `v0.6.4`
|
||||
- **REQs**: REQ-054, REQ-055, REQ-060, REQ-063
|
||||
- **Modules**: extends `x/bond` (MAB), `x/cover` (Cover Claims Voucher + MAB seniority waterfall), `x/standing` (Shadow vouch weight + slash reason)
|
||||
- **Personas**: backend-engineer (MAB + Voucher + Shadow vouch types + keeper), security-engineer (MAB use-of-proceeds lock + Voucher slashing + Shadow vouch const), cosmos-engineer (Msg* + keeper handlers)
|
||||
|
||||
### P4 Must-Haves
|
||||
|
||||
1. **Mutual Aid Bond (REQ-054 locked)** — `MAB` struct in `x/bond/types` (anonymous embed of `Bond` + `CouponKind CouponDenom` + `AnnualSurplusAtIssuance int64` + `UseOfProceedsTag string`). `CouponDenom` enum (`CouponDenomCoverCall`/`CouponDenomMutualAidCredit`/`CouponDenomBread` — the last exists ONLY to be rejected at `ValidateBasic` with "FR-MAB-3: MAB coupons NEVER Bread", mirroring `MissionLockAmendmentRejected`). `MABIssuanceCeilingAnnualSurplusMultiple = 3` const in `x/bond/types`. `MsgIssueMAB` handler: `checkMABIssuanceCeiling(ctx, poolID, newPrincipal)` asserts `sum(issuedMABPrincipal) + newPrincipal <= 3 × AnnualSurplus` (re-check at every issuance). Coupon rate bounded by `CouponCapBps=800` (existing locked const — no new const, cross-const test extends).
|
||||
2. **D-080 tagged streaming + Watcher-witnessed release** — `UseOfProceedsTag` field locked to `"reserve_build_out"` (a const `MABUseOfProceedsReserveBuildOut`). `MsgDebitMABProceeds` handler: checks destination account is the Pool's `ReserveAccount`; else invokes `StillKeeper.Still(poolID, "MAB misuse")` for auto-Still. `MsgWitnessMABProceedsRelease` handler: requires Watcher quorum (6-of-9, `x/watcher/types/types.go:23` `Quorum=6`) before proceeds move from tagged staging to reserve. Watcher attestation at deployment + quarterly audit (a `MsgWatcherAttestMAB` handler).
|
||||
3. **Cover Claims Voucher (REQ-055) + D-090(2) cold-start fix** — `CoverClaimsVoucher` struct in `x/cover/types` (`{VoucherReachID string, PoolID string, BondAmount int64, BondMultipleAvgCall uint32}`). `CoverClaimsVoucherBondMultipleAvgCall = 10` const. **D-090(2): `bond = max(CoverClaimsVoucherBondMultipleAvgCall × avgCallSize, MinimumVoucherBond)` where `MinimumVoucherBond` is a Params field with a non-zero default** — the cold-start fallback when no Calls have been filed yet (avg = 0 → bond = MinimumVoucherBond, NOT zero). `MsgRegisterCoverClaimsVoucher` handler: bonds the Voucher. `MsgFileCoverCall` handler: assigns a Call to a Voucher; **no self-adjudication** (FR-CPCV-2) — rejects if `voucherReachID == claimantReachID`. Slashing via existing `x/standing.Slash` struct with new `SlashReasonFraudulentCoverCall` const — cross-Pool applicability (the slash drops the Voucher's Standing bucket, disqualifying them from other Pools). Bounded earnings (a `MaxVoucherEarningsPerCall` Params field).
|
||||
4. **Shadow vouch 50% weight (REQ-060 locked)** — extend `x/standing/types.Vouch` with `IsShadow bool` field. `ShadowVouchWeightMultiplier = 0.5` const in `x/standing/types`. Modify `GetVoucherWeight` to apply the multiplier as a post-step: `if isShadow { weight *= ShadowVouchWeightMultiplier }`. The const makes the 0.5× mission-locked (REQ-060 locked) and regression-testable. New test `TestShadowVouchWeight` in `x/standing/types/types_test.go`.
|
||||
5. **MAB holder seniority no-Voice (REQ-063 locked)** — `PoolDissolutionWaterfall` function in `x/cover/keeper`: returns `[{Tier: "CoverFeeContributors", ...}, {Tier: "MABHolders", ...}, {Tier: "BreadHolders", ...}]` (FR-MAB-4 seniority chain). MAB holders excluded from the Pool Council voice set (the `PoolCouncil` struct from P2 already excludes them; P4 adds the waterfall + a `MsgDissolveCoverPool` handler that invokes the waterfall). MAB holders have NO Voice in dissolution decisions.
|
||||
6. **D-089(2): `x/bond → x/cover` CoverKeeper reverse edge** — `x/bond/types/expected_keepers.go` gains a `CoverKeeper` interface (`GetPoolReserveAccount(poolID) string`) used by the `MsgDebitMABProceeds` handler to validate the destination. No import cycle (interface only). Documented in ARCHITECTURE.md v0.7 dependency map.
|
||||
7. **D-089(1): `StillKeeper` simtest stub** — the MAB auto-Still hook (`MsgDebitMABProceeds` misuse → `StillKeeper.Still`) is satisfied by a simtest-local stub (test-only, G-003 exempt). `x/still` is NOT extended this milestone.
|
||||
8. **Simtest** — (a) MAB issuance with valid Cover-Call coupons; (b) MAB issuance rejected with Bread coupons (FR-MAB-3); (c) MAB issuance rejected above 3× annual surplus ceiling; (d) tagged streaming misuse → auto-Still; (e) Watcher-witnessed release (quorum present: succeeds; absent: rejects); (f) Cover Claims Voucher registration + bond; **(g) D-090(2) Voucher cold-start: bond = MinimumVoucherBond when no Calls exist**; (h) Cover Call adjudication (no self-adjudication); (i) Voucher slash for fraudulent Call → Standing bucket drop; (j) Shadow vouch 0.5× weight applied; (k) Pool dissolution waterfall (Cover-Fee contributors > MAB > Bread holders).
|
||||
9. **Lexicon + locked-const regression** — `x/bond/types/types_test.go` extended with `MABIssuanceCeilingAnnualSurplusMultiple=3` + `CouponDenom` enum count. `x/standing/types/types_test.go` extended with `ShadowVouchWeightMultiplier=0.5`. `x/cover/types/types_test.go` extended with `CoverClaimsVoucherBondMultipleAvgCall=10`. Cross-const test: MAB coupon cap == `CouponCapBps` (extends REQ-030 pattern).
|
||||
10. **Coverage ≥80%** on the extended `x/bond` + `x/cover` (Voucher + waterfall) + `x/standing` (Shadow vouch) surfaces.
|
||||
|
||||
---
|
||||
|
||||
## Phase P5 — Anti-Capture Bill of Rights + Secession Cooling + Stand→Pier Boundary + Pier Selection
|
||||
|
||||
- **Type**: feat
|
||||
- **Tag**: `v0.6.5`
|
||||
- **REQs**: REQ-056, REQ-059, REQ-064, REQ-066
|
||||
- **Modules**: extends `x/cover` (Anti-Capture Bill of Rights + Pier Selection Index), `x/guild` (secession cooling enforcement), `x/stand` (Stand→Pier boundary const + escalation)
|
||||
- **Personas**: backend-engineer (Bill of Rights + secession + Pier types + keeper), security-engineer (Bill of Rights firewall + secession lien audit + Pier Selection Index), lead-developer (D-085 escalation — 13th right identification before P5 lands), cosmos-engineer (Msg* + keeper handlers)
|
||||
|
||||
### P5 Must-Haves
|
||||
|
||||
1. **Anti-Capture Bill of Rights v0.2 ceremony (REQ-056 locked) + D-090(1) types already in P2** — the `RightID` type + 13 `Waivable*` consts + `RightIsWaivable()` + `AntiCaptureBillOfRightsCount=13` const + the `MsgSignCoverCharter.ValidateBasic` gate ALL landed in P2 (D-090(1) temporal-gap fix). **P5 adds the *ceremony* surface:** the `MsgCounselReviewBillOfRights` handler (the "bonded Counsel review" §7 acceptance criterion — the Counsel's Standing bond is staked; the handler records the review result). P5 also adds the full Bill-of-Rights simtest cases (the P2 simtest covered the ValidateBasic gate; P5 covers the Counsel review + the 13-rights regression test asserting all 13 `Waivable*` consts are `false` + `RightIsWaivable` returns `false` for all 13). The 12 enumerated rights + D-085 13th-right candidate (`RightNonParticipationNoDenial`) are all in P2; P5 does NOT re-declare them.
|
||||
2. **Dual firewall (const + ValidateBasic) — ALREADY IN P2** — the `MsgSignCoverCharter.ValidateBasic` gate rejecting `WaivedRights` landed in P2 (D-090(1)). P5's contribution is the Counsel review ceremony + the full regression test suite.
|
||||
3. **Secession cooling enforcement (REQ-064 locked)** — `x/guild/keeper`: `MsgInitiateSecession` handler records `secessionStartedAt` + invokes `lienAudit(poolID)`. `MsgCompleteSecession` handler checks: (a) `now >= secessionStartedAt + coolingSeconds` where `coolingSeconds = CoolingSecessionCoverActiveDays*86400` (21d) if the Chapter is Cover-active, else `CoolingSecessionNonCoverDays*86400` (14d); (b) lien-audit-passed; (c) Cover Call / Bond covenant clearance passed. Cooling secured at founding (the `SecessionTerms` from P3 is immutable), NOT reducible. Parent Guild Treasury receives pro-rata Cover-Fee settlement for in-flight Cover Calls (a `ProRataSettlement` function in `x/cover/keeper`).
|
||||
4. **Stand→Pier boundary (REQ-059, D-074)** — `StandPierEscalationAnnualPassVolumeCents = 10000000` const in `x/stand/types` (placeholder for $100k in Grain-cents at simtest; the PO ruling D-074 is $100k USD which is converted at the current USD/Grain oracle rate — but no oracle exists in simtest). The handler `MsgEscalateStandToPier` (or a keeper-level `checkStandPierEscalation(standID)` invoked on Pass routing): when annual Pass volume > the const, the Stand is *invited* to Hub API (a `StandPierEligible bool` flag + a `MsgAcceptPierInvitation` handler). Soft upgrade, not a ban — the Stand may decline.
|
||||
5. **Pier selection (REQ-066)** — `PierSelectionIndex` struct in `x/cover/types` (`{PierID string, JurisdictionalReliabilityScore float64, FiduciaryRecordHash []byte, IntegrationQualityScore float64, OverallScore float64}`). `MsgSelectPier` handler: Guild Council chooses Pier at formation. `MsgRevokePierSelection` handler: reversible by Cover Pool supermajority + Counsel witness. Mesh maintains the Pier Selection Index (a keeper-level `GetPierSelectionIndex(pierID)` query). **Pier-Routed Legal Wrapper is OPTIONAL** (§5 default-no-wrapper — no code required; a `PierWrapperID string` field on Guild from P3 is optional, empty by default).
|
||||
6. **Simtest** — (a) Charter signing with waived rights → REJECT (dual firewall — **already in P2, P5 re-verified**); (b) Charter signing with no waived rights → succeeds; (c) `RightIsWaivable` returns false for all 13 rights; (d) `MsgCounselReviewBillOfRights` ceremony (bonded Counsel staked + review recorded); (e) secession initiation + 21d cooling (Cover-active) + lien audit + covenant clearance + completion; (f) secession rejected before cooling expires; (g) secession rejected with outstanding liens; (h) Stand→Pier escalation at >10M Grain-cents annual Pass volume; (i) Stand declines Pier invitation (soft upgrade); (j) Pier selection by Guild Council; (k) Pier selection revoked by Cover Pool supermajority + Counsel.
|
||||
7. **Lexicon + locked-const regression** — `x/cover/types/types_test.go` extended with `AntiCaptureBillOfRightsCount=13` + 13 `Waivable*` consts all false (P2 landed them; P5 adds the full regression suite). `x/stand/types/types_test.go` extended with `StandPierEscalationAnnualPassVolumeCents=10000000`. Lexicon assertion on new Msg* names.
|
||||
8. **Coverage ≥80%** on the extended `x/cover` (Bill of Rights ceremony + Pier Index) + `x/guild` (secession) + `x/stand` (Pier boundary) surfaces.
|
||||
|
||||
---
|
||||
|
||||
## Phase P6 — Final Review + Audit + Milestone Ship
|
||||
|
||||
- **Type**: final (REVIEW + AUDIT + milestone SHIP)
|
||||
- **Tag**: `v0.6.6` (= v0.7 milestone release per D-008)
|
||||
- **REQs**: all REQ-046..REQ-066 marked complete
|
||||
- **Personas**: lead-developer (review + audit + ship), ci-security-auditor (REACTIVATED — feature purity gate + pen-test), backend-engineer (P1+ fixes if review flags), security-engineer (P1+ fixes if review flags)
|
||||
|
||||
### P6 Must-Haves
|
||||
|
||||
1. **`ciagent-review`** — multi-persona code review across P1..P5. Reviews all changes in `milestone/v0.7-fraternal-groups`. Auto-applies P0 fixes, flags P1+ for post-hoc review. If P1+ issues found: fix in P6.
|
||||
2. **`ciagent-audit`** — reconstruction test (git log matches `.ciagent/` files), `.ciagent/` file discipline, branch hygiene, commit discipline.
|
||||
3. **Feature purity gate** — no breaking schema changes to EXISTING locked consts; G-003 production firewall intact; G-006/G-028 go.mod diff EMPTY; lexicon firewall green (4 meta-tests: x/, docs/, web/, cover/). The 11 new locked consts are net-new (not amendments).
|
||||
4. **§7 acceptance criteria verified**:
|
||||
- ≥1 Cover Pool live on testnet with reserve enforcement + Standing gate + category tagging (simtest-grade — P1+P2)
|
||||
- ≥1 Parent Guild with Chapter in secession-eligible formation with good-standing liens declared at founding (P3)
|
||||
- ≥1 Mutual Aid Bond issuance with Cover-Call coupon settlement + use-of-proceeds lock to reserve build-out (P4)
|
||||
- Anti-Capture Bill v0.2 reviewed by bonded Counsel (simtest — the Counsel review is a `MsgCounselReviewBillOfRights` handler; "bonded" = the Counsel's Standing bond is staked)
|
||||
- **pen-test ≥1 independent third party** — at full autonomy with no external third party available, run self-administered adversarial review (ci-griller persona) and log as assumption (oy-state §7 remaining-open item 4). The ci-griller red-teams the Anti-Capture Bill + Anti-Crowding-Out firewall + MAB use-of-proceeds lock + secession cooling + Voucher slashing.
|
||||
- high/critical findings remediated (the ci-griller's binding P0 fixes are applied in P6; P1+ flagged for post-hoc review)
|
||||
5. **`ciagent-ship` (milestone ship)** — merge `phase/06` → `milestone/v0.7-fraternal-groups` → `main`. Tag `v0.6.6` (= v0.7 milestone release). Create release with full milestone summary. Delete all milestone branches (local + remote).
|
||||
6. **Milestone completion** — REQUIREMENTS.md marks REQ-046..REQ-066 complete. ROADMAP.md marks v0.7 complete. Commit `docs(milestone): complete v0.7-fraternal-groups-foundation`. Clear CHECKPOINT.json.
|
||||
|
||||
---
|
||||
|
||||
## User-Facing Surface
|
||||
|
||||
(MVP/UX CHECK section 1 of 3 — per run.md MVP/UX CHECK gate)
|
||||
|
||||
v0.7 is a protocol milestone with NO user-facing UI surface (the v0.6 web UI is complete; v0.7 does not touch `web/`). The user-facing surface for v0.7 is the **simtest** — the `x/cover/keeper/msg_server_simtest_test.go` file is the executable demonstration that a Cover Pool can be launched, a Charter signed, a MAB issued, a Cover Call adjudicated, and a Chapter seceded. The simtest IS the "user-facing surface" for a protocol milestone: it's the artifact a developer reads to understand the Cover Pool lifecycle.
|
||||
|
||||
- **CLI flag**: none (no `oyd` daemon exists; D-020 continues). The simtest is run via `go test ./x/cover/keeper/...`.
|
||||
- **README quickstart**: the v0.7 milestone adds a section to `docs/reference/` (lead-developer territory, not v0.7 scope — docs-content is deactivated per PERSONAS.md; the ARCHITECTURE.md v0.7 section is the reference). The simtest is the quickstart.
|
||||
- **Docs**: `.ciagent/oy/ARCHITECTURE.md` v0.7 section (the component index + cross-component dependencies + locked-const additions) is the developer-facing reference for the Cover Pool surface.
|
||||
- **`.feature` Scenario**: the simtest functions are named as scenarios: `TestCoverPoolLaunch_ValidStanding`, `TestCoverPoolLaunch_BelowStandingGate_Rejected`, `TestMABIssuance_BreadCoupons_Rejected`, `TestSecession_21DayCooling_CoverActive`, `TestAntiCaptureBill_WaivedRights_Rejected`, etc.
|
||||
|
||||
## Happy Path
|
||||
|
||||
(MVP/UX CHECK section 2 of 3 — per run.md MVP/UX CHECK gate)
|
||||
|
||||
The v0.7 happy path (end-to-end scenario, written BEFORE execute, verified by simtest in P6):
|
||||
|
||||
1. **A Guild Council creates a Cover Pool** via `MsgLaunchCoverPool` for the Travel category (Phase 2). The Factory validates: reserve floor 1.5× (REQ-047), Standing gate Trusted 4.0 for the Pool Host (REQ-049), category Travel is in Phase 2 (REQ-065). The Watcher attests the launch. The Pool is live (simtest-grade).
|
||||
2. **The Pool Host signs a Cover-Charter** via `MsgSignCoverCharter` with a Statement-of-Beliefs hash, a dispute path, a 30-day holding period, and a Watcher witness. The Charter is distinct from the Guild's governance charter. The protocol does NOT parse the SoB content (FR-CHTR-5). The Anti-Capture Bill of Rights is non-waivable — the Charter's `WaivedRights` field is empty (REQ-056).
|
||||
3. **Pool-eligible Masons elect 3 Masons to the Pool Council** via `MsgElectPoolMason`. The Pool Council = Pool Host + 3 elected + Watcher observer. No Anchor seat (§5). No MAB-holder seat (REQ-063).
|
||||
4. **Cover-Fees are routed to the Pool** via `MsgRouteCoverFee` with a `CoverFeeTag{CategoryTag: "Travel", PoolID: "pool-1"}`. The Anti-Crowding-Out firewall (D-079) checks the routing path — the fee goes to the Pool's contributor-pool reserve, NOT to Root-Pool operating expenses. The reserve floor check passes (1.5×). The category-tag matches the Pool's allowed categories (FR-COVER-11).
|
||||
5. **The Pool issues a Mutual Aid Bond** via `MsgIssueMAB` with `CouponKind: CouponDenomCoverCall`, `PrincipalGrain: 50000000`, `UseOfProceedsTag: "reserve_build_out"`. The issuance ceiling check passes (`sum(existing MAB principal) + 50M <= 3 × AnnualSurplus`). The coupon rate is bounded by `CouponCapBps=800` (8%). The proceeds are tagged for reserve build-out (D-080).
|
||||
6. **The MAB proceeds are released** via `MsgWitnessMABProceedsRelease` — the Watcher quorum (6-of-9) witnesses the release. The proceeds move from the tagged staging account to the Pool's reserve account. If the proceeds were routed elsewhere, the auto-Still would fire (simtest tests this in a negative case).
|
||||
7. **A Cover Call is filed** via `MsgFileCoverCall` — a Holder files a Cover Call against the Travel Pool. A Cover Claims Voucher is assigned (bond 10× avg Call size). The Voucher is NOT the claimant (FR-CPCV-2 no self-adjudication). The Voucher adjudicates the Call. If the Voucher commits fraud, they are slashed via `x/standing.Slash` with `SlashReasonFraudulentCoverCall` — the Standing bucket drops, disqualifying them from other Pools (cross-Pool applicability).
|
||||
8. **A Parent Guild's Chapter secedes** — the Chapter was founded with `SecessionTerms{CoolingCoverActiveDays: 21, LienAuditRequired: true, CovenantClearanceRequired: true}` + a good-standing lien secured at founding. The Chapter initiates secession via `MsgInitiateSecession`. After 21 Mesh-days (Cover-active), the lien audit passes, the Cover Call / Bond covenants are cleared, and the secession completes via `MsgCompleteSecession`. The Parent Guild Treasury receives pro-rata Cover-Fee settlement for in-flight Cover Calls.
|
||||
9. **A Stand's annual Pass volume exceeds $100k** (10M Grain-cents) — the Stand is invited to the Hub API via `MsgEscalateStandToPier`. The Stand accepts the Pier invitation. The Stand→Pier boundary is a soft upgrade, not a ban.
|
||||
10. **The Pool dissolves** — the Pool Council (Host + 3 elected + Watcher observer, MAB holders excluded) votes to dissolve. The `PoolDissolutionWaterfall` pays: Cover-Fee contributors first, MAB holders second, Bread holders third (FR-MAB-4 seniority). MAB holders have NO Voice in the dissolution decision (REQ-063).
|
||||
|
||||
This happy path is verified by the P6 simtest suite. The simtest is the executable spec.
|
||||
|
||||
## UX Acceptance Criteria
|
||||
|
||||
(MVP/UX CHECK section 3 of 3 — per run.md MVP/UX CHECK gate)
|
||||
|
||||
The v0.7 deliverable MUST meet these explicit criteria (verified in P6 audit):
|
||||
|
||||
1. **`go build ./...` + `go test ./...` GREEN** — all packages (v0.1-v0.6 baseline + v0.7 `x/cover` + extensions). No FAIL. The simtest is the executable demonstration.
|
||||
2. **`x/cover` module exists with the full Cover surface** — Factory + firewall + floors + gates + tagging (P1) + Charter + governance + staging (P2) + Bill of Rights + Voucher + Pier Index (P5). Layout mirrors `x/hub` (D-039 precedent verified at `x/hub/types/types.go:33-57`).
|
||||
3. **Anti-Crowding-Out firewall operational** — `x/cover/firewall/` subpackage rejects any code path routing Cover-Fees outside contributor-pool semantics; `lexicon_meta_cover/` meta-test rejects doc drift. 4 lexicon meta-tests green (x/, docs/, web/, cover/). Defense in depth (D-079).
|
||||
4. **11 new locked consts in place + regression tests** — all 11 consts from the v0.7 const firewall additions table, with regression tests asserting their values. No existing locked consts amended.
|
||||
5. **MAB coupons NEVER Bread** — `CouponDenomBread` rejected at `ValidateBasic` (FR-MAB-3). The simtest `TestMABIssuance_BreadCoupons_Rejected` passes. MAB issuance ceiling 3× annual surplus enforced at keeper (`TestMABIssuance_AboveCeiling_Rejected` passes).
|
||||
6. **Anti-Capture Bill of Rights = 13 rights, non-amendable, non-waivable** — `RightIsWaivable` always returns false; Charter `WaivedRights` field rejected at `ValidateBasic` (REQ-056). `AntiCaptureBillOfRightsCount=13` regression test passes. D-085 (13th right) logged as assumption with `RightNonParticipationNoDenial` candidate if PO did not rule before P5.
|
||||
7. **Coverage ≥80%** on `x/cover` + all extensions (`x/bond`, `x/guild`, `x/standing`, `x/stand`).
|
||||
8. **G-003 production firewall intact** — `x/cover` references `x/standing`/`x/watcher`/`x/bond`/`x/still` via `expected_keepers.go` shims; no struct imports across `x/<module>/types`. Verified by the lexicon_meta + a G-003 regression test. `x/pact.PactCover` stays as cross-reference (D-084).
|
||||
9. **G-006/G-028 go.mod diff EMPTY** — no new Go deps; `x/cover` uses existing cosmos-sdk v0.50.8 + ibc-go v8.2.1. `git diff v0.5.6..v0.6.6 -- go.mod` shows no new require lines.
|
||||
10. **Pen-test (self-administered adversarial review via ci-griller)** — the ci-griller red-teams the Anti-Capture Bill + Anti-Crowding-Out firewall + MAB use-of-proceeds lock + secession cooling + Voucher slashing. High/critical findings remediated in P6; P1+ flagged for post-hoc review. Logged as assumption per oy-state §7 remaining-open item 4.
|
||||
11. **§7 acceptance criteria met** — ≥1 Cover Pool live (simtest), ≥1 Parent+Chapter secession-eligible (simtest), ≥1 MAB issuance (simtest), Anti-Capture Bill reviewed by bonded Counsel (simtest `MsgCounselReviewBillOfRights` handler), pen-test complete (self-administered), high/critical remediated.
|
||||
+154
-2
@@ -1,3 +1,4 @@
|
||||
<!-- Auto-generated from .ciagent/oy/oy-spec — PO edits oy-spec, not this file; see oy-state for current shipped state. -->
|
||||
# Project: OpenYield (oy)
|
||||
|
||||
## Objective
|
||||
@@ -61,7 +62,124 @@ OpenYield (OY) is a durable, anti-greed, jurisdiction-light financial layer —
|
||||
- D-009: Rebased history to fix v1.0 → v0.1 in ---ci--- blocks
|
||||
|
||||
## Milestone
|
||||
v0.6 — Nomad Web UI (in progress; feature type; tags run on the v0.5.x patch line)
|
||||
v0.7 — Fraternal Groups Foundation (in progress; feature type; tags run on the v0.6.x patch line)
|
||||
|
||||
### v0.7 Scope (Fraternal Groups Foundation — Cover Pools + Chapter Federation + Mutual Aid Bonds + Anti-Capture Bill v0.2)
|
||||
|
||||
v0.7 adapts the 1890–1930 fraternal benefit-society model for borderless
|
||||
digital service. It delivers Cover Pools (insurance-like commitment pools
|
||||
with mission-locked reserve floors + Standing gates), Chapter Federation
|
||||
(Parent/Chapter Guild model with secession terms + good-standing liens
|
||||
declared at founding), Mutual Aid Bonds (Cover-Call-couponed bonds with
|
||||
issuance ceiling 3× annual surplus, use-of-proceeds locked to reserve
|
||||
build-out), and the Anti-Capture Bill of Rights v0.2 (13 rights codified,
|
||||
non-amendable, non-waivable by any Charter). This is the milestone that
|
||||
unblocks the v0.1 Q7 "Cover Pool seniority mechanics" deferred item —
|
||||
REQ-046..REQ-050 supply the seniority/gate math and promote `x/pact` Cover
|
||||
from skeleton to a dedicated `x/cover` module runtime (D-039 precedent:
|
||||
`x/hub` split out of `x/pact`'s `PactHubAPI` in v0.3).
|
||||
|
||||
Simtest-grade runtime (D-020 pattern continues — no live chain launch, no
|
||||
mainnet). Cover Pool "live on testnet" (§7 acceptance) = `x/cover` keeper
|
||||
message handlers + simtest-grade end-to-end flows, not mainnet deployment.
|
||||
No `app.go`/`cmd/oyd` exists in the repo; v0.7 does not create one.
|
||||
|
||||
New module: `x/cover` (Cover Pool Factory + Anti-Crowding-Out firewall +
|
||||
Anti-Capture Bill of Rights). The existing `x/pact` `PactCover` enum value
|
||||
remains as a cross-reference (G-003 by-ID-string pattern).
|
||||
|
||||
- **REQ-046** Cover Pool Factory runtime — Factory rejects category launches below in-force reserve floor; supports Cover-Charter deployment; Watcher attestation pipeline operational; category staging per REQ-065.
|
||||
- **REQ-047** Cover Pool reserve target floor 1.5× annual contributions — LOCKED; mission-lock semantic enforced; below-floor auto-pause of Cover-Fee routing.
|
||||
- **REQ-048** Cover Pool reserve target ceiling 2.5× (governance-tunable within 1.5×–2.5×) — Watcher escalation after 12 months; Pool Council MAY vote within bounded range.
|
||||
- **REQ-049** Cover Pool Standing gate minimums — LOCKED; Travel ≥ Trusted 4.0; Health-MCS ≥ Preferred 4.5; Pool MAY tighten but NEVER loosen below protocol minimum. Binds at Factory runtime (D-077).
|
||||
- **REQ-050** Cover-Fee tagging at protocol layer — LOCKED; Cover-Fee Grains carry `category_tag`; settlement rejects category-mismatched Calls (FR-COVER-11); Pool-level fungibility preserved for net-reserve accounting.
|
||||
- **REQ-051** Guild Charter + Common Bond requirement — LOCKED; at formation: Common Bond declared + hash-pinned; Public Profile published (bond summary, disclaimers, Mason count or "private", Pier wrapper if any).
|
||||
- **REQ-052** Cover-Charter (SoB, dispute path, gate, holding period) — LOCKED; distinct from governance charter; signed by Pool Host + witnessed by Watcher at deployment; amendments require Pool supermajority + 7-day cooling + Watcher + Counsel; protocol does NOT enforce SoB content (FR-CHTR-5).
|
||||
- **REQ-053** Chapter Federation (Parent/Chapter, secession terms, liens at founding) — Parent Guild + Chapters; Chapters inherit + may tighten but not loosen; secession terms coded at founding; good-standing liens at founding (not freely increasable); Chapter retains mesh-level Voice (Pier does NOT carry Voice per FR-VOICE-6).
|
||||
- **REQ-054** Mutual Aid Bond (issuance ceiling 1×–3×, coupons in Cover Calls) — LOCKED; issuance ceiling mission-locked at 3× annual surplus; coupons payable in Cover Calls or mutual-aid credits (NEVER Bread); coupon rate bounded by `CouponCapBps=800`; use-of-proceeds locked to reserve build-out; default recapture per FR-MAB-7; Watcher attestation at deployment + quarterly audit. Enforcement: tagged streaming + Watcher-witnessed release (D-080, defense in depth).
|
||||
- **REQ-055** Cover Claims Voucher role + bond + slashing — Specialization of Voucher role; bond default 10× avg Call size per Pool; reviews each Call independently (no self-adjudication, FR-CPCV-2); slashing via §9.4 mechanism with cross-Pool applicability (NFR-SEC-8); bounded earnings.
|
||||
- **REQ-056** Anti-Capture Bill of Rights v0.2 — LOCKED; 13 rights codified in code; cannot be amended or waived by any Charter; covers one-tap exit, no tax on personal Stash, audit-able Voice, cooling, Watcher inspection, Freeholder voucher, Counsel escalation, Anchored-Bread conversion, Wayfarer's Record, secession (founding terms), non-Cover-access, category-mismatch refusal.
|
||||
- **REQ-057** Household simplified — no formal Council, one-tap exit — Household Stand may operate without formal Council; one-tap exit is the dispute path.
|
||||
- **REQ-058** Confederation Voice — one-Stand-one-Vote, internal bundle — LOCKED; Confederation aggregates member Stand Voice one-per-Stand; member Stands may bundle delegated Voice internally via §19 delegation.
|
||||
- **REQ-059** Stand→Pier-customer boundary — escalation rule ($100k per D-074) — When annual Pass volume > $100k, Stand is invited to Hub API; soft upgrade, not a ban.
|
||||
- **REQ-060** Shadow vouch partial credit — 50% weight in Freeholder signal — LOCKED; Shadow vouch weight = 0.5× in Community Endorsement signal (vs 1.0× for non-Shadow vouch).
|
||||
- **REQ-061** Disclaimer cadence — per charter signing — LOCKED; jurisdictional disclaimer surfaced at every charter signing; not session-bounded.
|
||||
- **REQ-062** Pool governance hybrid (Host + 3 elected + Watcher observer) — LOCKED; Cover Pool Council = Pool Host + 3 Masons elected by Pool-eligible Masons + Watcher observer seat; Cover Calls require majority with Watcher observer present. No Anchor seat (Anchor no-Voice §5).
|
||||
- **REQ-063** MAB holder — surplus seniority only, no Voice at dissolution — LOCKED; Mutual Aid Bond holders rank after Cover-Fee contributors but before Bread holders in Pool-surplus distributions (FR-MAB-4); NO Voice in Pool dissolution decisions (claimants, not Masons).
|
||||
- **REQ-064** Secession cooling — 21d Cover-active / 14d non-Cover — LOCKED; Chapter secession cooling: 21 Mesh-days if Cover-active, 14 Mesh-days if non-Cover; secured at founding, not reducible; lien audit required; Cover Call / Bond covenant clearance required before secession completes.
|
||||
- **REQ-065** Cover Pool category staging — Phase 2/3/4 — LOCKED; Phase 2: Travel + Health-MCS + Income-Pause; Phase 3: Equipment/Loss + Life-Burial + Road-Side; Phase 4: Cyber-Skimming + Guild-Internal-Mutual-Aid; Factory respects staging and rejects out-of-phase launches.
|
||||
- **REQ-066** Pier selection — Guild Council chooses, reversible, Pier Selection Index — Guild Council chooses Pier at formation; reversible by Cover Pool supermajority + Counsel witness; mesh maintains Pier Selection Index; Pier-Routed Legal Wrapper OPTIONAL (§5 default-no-wrapper).
|
||||
|
||||
### Milestone Type
|
||||
Feature (REQ-046..REQ-066 are feat-class primitives + test adjuncts for the firewall). Phase 0 → `v0.6.0`; execution phases `v0.6.1..v0.6.5`; final phase patch `v0.6.6` IS the v0.7 milestone release. No separate minor tag. The final-phase audit enforces the feature purity gate (no breaking schema changes; G-003 production firewall intact; G-006 go.mod unchanged — `x/cover` keeper uses existing cosmos-sdk runtime substrate).
|
||||
|
||||
### Out of Scope (v0.7)
|
||||
- Real blockchain interaction / mainnet / IBC / real bearer transports (D-020 continues; runtime = simtest-grade keeper handlers)
|
||||
- A real `oyd` daemon / `app.go` / `cmd/oyd` (no chain runtime exists; deferred to v0.8+)
|
||||
- Sovereign Anchor SPEC (`oy-sovereign-anchors` forthcoming; experimental, not load-bearing per §5/D-076)
|
||||
- USZ classification runtime (v0.8 — depends on Anchor pre-commitment framework, REQ-095)
|
||||
- Cluster A–E + Infrastructure Economics (REQ-067..REQ-097, all v0.8 per D-081)
|
||||
- Pier-Routed Legal Wrapper (OPTIONAL per §5; default-no-wrapper; not implemented as code)
|
||||
- Authentication / sessions / real key management (mock; deferred to v0.8+)
|
||||
- Persistence (mock store; deferred to v0.8+)
|
||||
- The 5 P1+ mainnet-readiness items deferred from v0.5 (governance spam deposit, CLOB batch auction, real IBC simtest, CLOB perf, emitMatchEventHook) — those are v0.8+ mainnet-readiness
|
||||
- SignalKind 4→5 expansion (deferred to v0.8+ governance vote)
|
||||
|
||||
### Prior Milestones
|
||||
- v0.1 — OpenYield Foundation Init (COMPLETE; pre-MVP foundation skeleton; released as v0.0.9)
|
||||
- v0.2 — The Mesh (COMPLETE; skeleton + tests; released as v0.1.5)
|
||||
- v0.3 — Bearers & Documentation (COMPLETE; feature; released as v0.2.6)
|
||||
- v0.4 — Refinement (COMPLETE; NFR; released as v0.3.4)
|
||||
- v0.5 — Bearers Runtime (COMPLETE; feature; released as v0.4.8)
|
||||
- v0.6 — Nomad Web UI (COMPLETE; feature; released as v0.5.6)
|
||||
|
||||
## Prior Milestone
|
||||
v0.6 — Nomad Web UI (complete; feature type; tags ran on the v0.5.x patch line)
|
||||
|
||||
### v0.6 Scope (Nomad Web UI MVP — generated test data, no real chain)
|
||||
|
||||
v0.6 is the project's first UI milestone. It delivers a working prototype Web
|
||||
UI where a person can sign up to be a Nomad (create a Reach + open a Stash)
|
||||
and exercise basic functionality around the (Reach, Stash) components, plus
|
||||
Window authorization, Standing progress, and Bloom accrual views. All data is
|
||||
generated as test fixtures — there is no real blockchain interaction, no live
|
||||
chain launch, no real bearer transports (D-020 continues to govern network
|
||||
deployment). The UI is a greenfield Go `html/template` + HTMX layer served by
|
||||
a Go mock HTTP server that instantiates the real `x/*/types` structs (Reach,
|
||||
Stash, Window, FreeholderSignals, BloomRecord) populated from in-memory
|
||||
fixtures. No keeper, no Cosmos runtime, no `app.go` (none exists in the repo).
|
||||
|
||||
This milestone is the prerequisite for real-world MVP testing: it makes the
|
||||
Nomad path visible and exercisable in a browser. Wiring the UI to a real `oyd`
|
||||
daemon (once one exists) is deferred to v0.7+ (no `app.go`, `cmd/`, or `main.go`
|
||||
exists in the repo today).
|
||||
|
||||
- **REQ-040** Nomad Reach signup Web UI — Go HTTP mock server (`web/`) + "Create a Reach" form + Reach list/detail; grounds the UI in `x/identity/types.Reach`. "Sign up" maps to "Create a Reach" (the word "account" is banned per REQ-012).
|
||||
- **REQ-041** Stash dashboard Web UI — balance in Grain + Bread-scale conversion (using `x/bread/types.BreadScaleAll()`) + 90-day maturity progress bar (`x/stash/types.StashActivity.IsMature`).
|
||||
- **REQ-042** Window authorization Web UI — form to open a Window (scope + duration + rate-limit), lifecycle view (Open→Active→Revoked/Expired via `x/window/types.Window.Activate/Revoke/Expire`), audit log.
|
||||
- **REQ-043** Standing + Freeholder signals progress Web UI — computed from mock `Rating`/`Vouch`/`Slash` records using the locked constants + `GetStandingBucket`/`ComputeDiversityBonus`/`GetVoucherWeight`; 4-signal progress (`FreeholderSignals.IsFreeholderEligible`).
|
||||
- **REQ-044** Bloom accrual Web UI — per-Stash `BloomRecord` view (`AccruedGrain`, `RateBasisPoints`), computed from mock data; shows the 4.5% target rate.
|
||||
- **REQ-045** Extend REQ-012 lexicon firewall to scan `web/templates/**` + `web/static/**` (new `lexicon_meta_web_test.go`). Firewall-first: lands in P1 before content.
|
||||
|
||||
### Milestone Type
|
||||
Feature (all execution phases are `feat` except REQ-045 which is `test`). Phase 0 → `v0.5.0`; execution phases `v0.5.1..v0.5.5`; final phase patch `v0.5.6` IS the v0.6 milestone release. No separate minor tag. The final-phase audit enforces the feature purity gate (no breaking schema changes; G-003 production firewall intact; G-006 go.mod unchanged unless a runtime dep is GRILL-approved — HTMX is a vendored static asset, not a Go dep).
|
||||
|
||||
### Out of Scope (v0.6)
|
||||
- Real blockchain interaction / mainnet / IBC / real bearer transports (D-020 continues)
|
||||
- A real `oyd` daemon / `app.go` / `cmd/oyd` (no chain runtime exists; deferred to v0.7+)
|
||||
- Real Anchors onboarding / Hub API B2B / real custody (simtest/mock only)
|
||||
- Authentication / sessions / real key management (mock; a Reach is created by form submission, stored in-memory)
|
||||
- Persistence (mock store is in-memory; resets on restart)
|
||||
- i18n / multi-language UI
|
||||
- Real Standing oracle / real Bloom accrual engine (computed from fixtures using locked constants)
|
||||
- The 5 P1+ mainnet-readiness items deferred from v0.5 (governance spam deposit, CLOB front-running, real IBC simtest, CLOB perf, emitMatchEventHook testability) — those are v0.7+ mainnet-readiness, not UI work
|
||||
|
||||
### Prior Milestones
|
||||
- v0.1 — OpenYield Foundation Init (COMPLETE; pre-MVP foundation skeleton; released as v0.0.9)
|
||||
- v0.2 — The Mesh (COMPLETE; skeleton + tests; released as v0.1.5)
|
||||
- v0.3 — Bearers & Documentation (COMPLETE; feature; released as v0.2.6)
|
||||
- v0.4 — Refinement (COMPLETE; NFR; released as v0.3.4)
|
||||
- v0.5 — Bearers Runtime (COMPLETE; feature; released as v0.4.8)
|
||||
|
||||
### v0.6 Scope (Nomad Web UI MVP — generated test data, no real chain)
|
||||
|
||||
@@ -306,4 +424,38 @@ Auto-decided defaults logged per clarify workflow Step 4 (full autonomy → acce
|
||||
| D-070 | **G-003 firewall scope: `web/` importing `x/*/types` is app-layer consumption, not a cross-`x/` production import.** G-003 (production import firewall) prohibits production struct imports across `x/<module>/types` packages. `web/` is not an `x/` module — it is the application layer that consumes protocol types, exactly as a future `cmd/oyd` would. The G-003 firewall stays intact: no `x/` module gains a production import of another `x/` module's types via `web/`. GRILL reviews this boundary. | G-003's intent is to prevent cross-module coupling inside the protocol layer. The application layer consuming types is the intended consumption direction. `web/` importing `x/identity/types` is no different from `cmd/oyd` importing it (when one exists). | 0.85 | [treat `web/` as an `x/` module (wrong — it is not protocol); forbid `web/` from importing `x/*/types` (would force TS/JSON fixtures, losing the grounding in locked constants)] |
|
||||
| D-071 | **"Sign up" = create a Reach + open a Stash atomically.** The Nomad entry path per `docs/nomads/reach.md` is "a Nomad starts with a Reach and a Stash". The signup form creates both atomically: a `Reach` with `IsNomad=true` + a `Stash` with `HolderID` matching the Reach's `HolderID` and `BalanceGrain` seeded to a test value (e.g., 500,000 Grain = 50 Bread). No KYC, no custodian (REQ-001 self-service principle). The UI labels this "Create a Reach" (lexicon-clean; "account" is banned). | The docs define the Nomad starting state as Reach + Stash. Creating only a Reach would leave the Nomad unable to view a Stash dashboard (P2) — the atomic creation matches the docs and makes the happy path contiguous. | 0.82 | [create Reach only, defer Stash creation to a separate flow (fractures the happy path); create Reach + Stash + Window all at signup (over-scope for an MVP)] |
|
||||
| D-072 | **Phase ordering** (provisional, planner finalizes): P1 Web foundation + Reach signup + lexicon firewall extension (REQ-040 + REQ-045 — same `web/` territory, vertical slice, firewall-first) → P2 Stash dashboard (REQ-041, depends on Reach existing) → P3 Window authorization (REQ-042, depends on Stash existing) → P4 Standing + Freeholder signals (REQ-043, depends on Reach existing) → P5 Bloom accrual (REQ-044, depends on Stash existing) → P6 final review + audit + milestone ship. Each phase independently shippable; P1 lands the foundation + firewall first (lexicon-clean by construction). | P1 bundles the web foundation + Reach signup + the firewall extension (same `web/` territory, vertical slice). P2..P5 each add one screen, ordered by the Nomad happy path (Reach → Stash → Window → Standing → Bloom). Vertical slices, each phase shippable. | 0.82 | [different wave ordering; bundle Stash + Window in one phase] |
|
||||
| D-073 | **Bread-scale source of truth = `x/bread/types` code constants, NOT `docs/shared/bread-scale.md`.** The code constants (`GrainsPerBread=10000`, `BreadScaleAll()` table) are the locked, tested values; the docs table is aspirational/outdated (states 1,000× ratios that do not match the code). The UI uses the code constants for all Bread-scale conversions. A doc-fix for `docs/shared/bread-scale.md` is flagged as a P1+ follow-up (not a v0.6 deliverable — docs were a v0.3 deliverable; this is a doc-drift fix, not a UI feature). | The code constants are tested (`x/bread/types/types_test.go` asserts them); the docs are not. Using the code as the source of truth keeps the UI consistent with the protocol layer. | 0.90 | [use the docs table (wrong — not tested, disagrees with code); fix the docs in v0.6 (out of scope — doc-drift fix, not a UI feature)] |
|
||||
| D-073 | **Bread-scale source of truth = `x/bread/types` code constants, NOT `docs/shared/bread-scale.md`.** The code constants (`GrainsPerBread=10000`, `BreadScaleAll()` table) are the locked, tested values; the docs table is aspirational/outdated (states 1,000× ratios that do not match the code). The UI uses the code constants for all Bread-scale conversions. A doc-fix for `docs/shared/bread-scale.md` is flagged as a P1+ follow-up (not a v0.6 deliverable — docs were a v0.3 deliverable; this is a doc-drift fix, not a UI feature). | The code constants are tested (`x/bread/types/types_test.go` asserts them); the docs are not. Using the code as the source of truth keeps the UI consistent with the protocol layer. | 0.90 | [use the docs table (wrong — not tested, disagrees with code); fix the docs in v0.6 (out of scope — doc-drift fix, not a UI feature)] |
|
||||
|
||||
## Clarification Decisions (Phase 0 v0.7 — CLARIFY, autonomy=full)
|
||||
|
||||
Auto-decided defaults logged per clarify workflow Step 4 (full autonomy → accept defaults, log decisions). No `--ideate` flag this run; v0.7 scope is pre-seeded from oy-spec v3 §7 (Fraternal Groups Foundation, REQ-046..REQ-066) and ratified at CLARIFY. All 8 §8 open questions resolved by accepting PO recommendations as binding (D-074..D-081). The D-001 refinement-only filter does NOT apply (v0.7 is a feature milestone). Three scope-shaping questions were validated interactively with the user before CLARIFY:
|
||||
|
||||
1. **v0.7 scope (§7 vs §8 Q4)** — user ruled: §7 only (REQ-046..REQ-066, 21 REQs). Cluster A+B+C are v0.8 (D-081).
|
||||
2. **Accept all other PO recommendations** — user ruled: yes, accept all 7 (D-074..D-080) as binding.
|
||||
3. **Generate oy-state v2 at P0 start** — user ruled: yes (done at SPECIFY).
|
||||
|
||||
| ID | Decision | Rationale | Confidence | Alternatives |
|
||||
|----|----------|-----------|------------|--------------|
|
||||
| D-074 | **TBD-X = $100k annual Pass volume** for Stand→Pier-customer boundary escalation (REQ-059). When a Stand's annual Pass volume exceeds $100k (10,000,000 Grain-cents at GrainsPerBread=10000), the Stand is invited to the Hub API as a soft upgrade (not a ban). The threshold is a new `x/stand` const `StandPierEscalationAnnualPassVolumeCents=10000000` (not locked — Pool/Council may tune within bounds). | §8 Q1 PO rec accepted at full autonomy. $100k is the natural inflection where a Stand's activity volume resembles a small Pier-customer more than a personal Holder; soft upgrade preserves self-service (Principle 6). | 0.85 | [$50k (too aggressive — flags mature Households); $250k (too lax — delays Hub API onboarding)] |
|
||||
| D-075 | **TBD-Z density formula for USZ classification (REQ-095, v0.8)** = `<10 Holders per km² AND strategic value ≥ mission score, OR sovereign request, OR mission-aligned override via Mesh Council supermajority`. The formula is locked now (oy-state §3) but the USZ runtime is v0.8 (depends on Anchor pre-commitment framework). | §8 Q2 PO rec accepted. The 3-criteria OR structure matches the spec's "≥3 criteria" requirement (density + strategic value + mission-aligned override) while allowing sovereign request as a separate path. | 0.80 | [pure density threshold (ignores strategic value); Mesh Council sole arbiter (no objective floor)] |
|
||||
| D-076 | **Sovereign Anchors = separate SPEC `oy-sovereign-anchors`**, not folded into `oy-pier`. v0.7 status: experimental, not load-bearing. The `oy-spec` §5 constraint forbids USZ infrastructure financing via Sovereign Anchor partnerships from being load-bearing until the separate SPEC ships. | §8 Q3 PO rec accepted. Sovereign Anchors are infrastructure-scale (reserve entities, banking partners, multi-jurisdiction custody) — a different design surface than the Pier-Routed Legal Wrapper (which is OPTIONAL per §5). Folding them into `oy-pier` would conflate legal-wrapper-scale with infrastructure-scale. | 0.85 | [fold into oy-pier (conflates scales); fold into oy-spec (too large for the net-new-only diff)] |
|
||||
| D-077 | **Standing gate enforcement timing = Cover Pool Factory runtime (v0.7/P1)**, not first live Cover Pool deployment. The `CoverStandingGateTrusted=4.0` and `CoverStandingGatePreferred=4.5` consts bind at the `x/cover` Factory layer — every Pool the Factory launches inherits the protocol minimum; Pool Council MAY tighten but the Factory rejects any launch below the floor. | §8 Q5 PO rec accepted. Gates are protocol-layer invariants (REQ-049 locked=yes); deferring them to first-live-Pool would allow a window where a Pool could launch below the floor. Factory-runtime binding closes the window. | 0.88 | [first-live-Pool binding (allows a below-floor window); per-Pool configurable with no floor (violates REQ-049 locked)] |
|
||||
| D-078 | **Watcher/Voucher operating-expense compensation cap = 5% of Root-Pool Bloom annually** (REQ-096, v0.8). The absolute $TBD-W cap is deferred to v0.8 P0 (needs Root-Pool Bloom size estimate). v0.7 does not implement Watcher/Voucher compensation (Cluster E + Infra Economics are v0.8 per D-081). | §8 Q6 PO rec accepted. 5% Bloom is bounded by the protocol's own yield (not a transfer-payment analog); the absolute cap prevents Bloom-rate collapse if Bloom grows large. Deferring $TBD-W avoids hardcoding a USD figure that depends on mainnet Bloom size. | 0.82 | [10% (too high — risks Bloom-rate dilution); 1% (too low — may not cover Watcher ops); no absolute cap (unbounded if Bloom grows)] |
|
||||
| D-079 | **Anti-Crowding-Out Covenant enforcement = separate `x/cover/firewall` package (runtime) + `lexicon_meta_cover`-style meta-test (test-time)**, defense in depth. The runtime subpackage rejects any code path that would route Cover-Fees outside contributor-pool semantics (e.g., to Root-Pool operating expenses, transfer payments, or non-Cover destinations). The meta-test rejects doc/string drift that would describe such routing. This parallels the lexicon_meta pattern (D-044/D-069 firewall-first). | §8 Q7 PO rec accepted. The covenant is a §1/§2.3 SPEC-001 invariant — "Cover-Fees never crowd out the contributor pool". A separate firewall (not embedded in Factory validation) makes the invariant visible, testable, and resistant to Factory-layer refactors. Defense in depth: runtime rejects the code path, meta-test rejects the doc drift. | 0.84 | [embed in Factory validation (invisible, refactorable); meta-test only (no runtime gate — docs clean but code could route around)] |
|
||||
| D-080 | **MAB use-of-proceeds lock enforcement = tagged streaming + Watcher-witnessed release**, defense in depth. MAB proceeds are tagged with `use_of_proceeds=reserve_build_out` at issuance; the `x/bond` keeper streams tagged Grain to the `x/cover` reserve only, with auto-Still on any misuse detection (attempt to route to a non-reserve destination). Watcher attestation witnesses each release at quarterly audit (REQ-054). | §8 Q8 PO rec accepted. Tagged streaming makes the lock enforceable at the keeper layer (not just auditable post-hoc); Watcher-witnessed release adds the human-attestation layer. Defense in depth: keeper auto-Stills on misuse, Watcher catches what the keeper misses. | 0.85 | [Watcher-quorum-only release (no runtime gate — relies on Watcher catching misuse after the fact); unrestricted + audit-only (no enforcement, just detection)] |
|
||||
| D-081 | **v0.7 scope = §7 authoritative — REQ-046..REQ-066 only (21 REQs).** Cluster A+B+C (REQ-067..REQ-081) are v0.8, NOT v0.7, despite §8 Q4 PO rec suggesting Cluster A+B+C ship in v0.7. The §7 v0.7 acceptance text lists only REQ-046..REQ-066; the §7 v0.8 acceptance text lists REQ-067..REQ-097 with the const firewall extensions. §7 is the milestone contract; §8 Q4 was a recommendation the PO can override — and did, by accepting the "§7 only" interactive ruling before CLARIFY. | §7 acceptance text is the authoritative milestone contract (it lists the REQs and the acceptance criteria). §8 Q4 was a sequencing recommendation, not a binding scope ruling. Shipping 36 REQs in v0.7 would create a mega-milestone with coupled territories (fraternal primitives + their risk mitigations are different vertical slices). v0.7 = foundation; v0.8 = hardening. | 0.90 | [§8 Q4 — Cluster A+B+C in v0.7 (36 REQs, coupled territories); §7 + partial Cluster A only (REQ-067..072, 27 REQs — still couples fraternal + trust-minimization)] |
|
||||
| D-082 | **v0.7 phase ordering** (provisional, planner finalizes): P1 Cover Pool firewall + foundation (REQ-046/047/049/050 — firewall-first, same `x/cover` territory) → P2 Cover-Charter + Council + staging (REQ-048/052/062/065 — extends `x/cover` + `x/council`) → P3 Guild Charter + Chapter Federation (REQ-051/053/057/058/061 — extends `x/guild`, `x/stand`) → P4 MAB + Cover Claims Voucher (REQ-054/055/060/063 — extends `x/bond`, `x/standing`, `x/cover`) → P5 Anti-Capture Bill + secession + Pier (REQ-056/059/064/066 — cross-cutting, lands last as it constrains all prior surfaces) → P6 final review + audit + milestone ship. Each phase independently shippable; P1 lands the firewall + locked floors first (firewall-first pattern per D-044/D-069/D-079). | The 21 REQs cluster into 5 vertical slices by module territory + dependency. P1 is the spine (Factory + firewall + locked floors + gates + tagging); everything else hangs off it. P5 lands last because the Anti-Capture Bill constrains all prior surfaces (non-amendable rights that P1-P4 code must not violate). | 0.82 | [governance-first (REQ-062 first — but it depends on Factory); MAB-first (REQ-054 — but it depends on Cover Pool reserve existing); single mega-phase (couples territories)] |
|
||||
| D-083 | **No IDEATE stage in v0.7** (no `--ideate` flag this run). The feature scope was pre-seeded from oy-spec v3 §7 (REQ-046..REQ-066) and ratified at CLARIFY with all 8 §8 questions resolved. The D-001 refinement-only filter does NOT apply (v0.7 is a feature milestone). | run.md §IDEATE is conditional on `--ideate`. This invocation has no `--ideate`. | 1.00 | [run IDEATE anyway] |
|
||||
| D-084 | **New module `x/cover`** (Cover Pool Factory + Anti-Crowding-Out firewall + Anti-Capture Bill of Rights). The existing `x/pact` `PactCover` enum value remains as a cross-reference (G-003 by-ID-string pattern). This mirrors the D-039 precedent (`x/hub` split out of `x/pact`'s `PactHubAPI` in v0.3) — when a PactType grows into a first-class protocol surface with its own keeper + firewall, it graduates to a dedicated module. The `x/pact` `PactCover` enum value stays as a typed cross-reference so `x/pact` tests still pass; `x/cover` owns the runtime. | REQ-046 (Factory runtime), REQ-047 (reserve floor in `x/pact/cover` per spec text — interpreted as `x/cover` since that's where the Factory lives), REQ-050 (Cover-Fee tagging at protocol layer), REQ-052 (Cover-Charter), REQ-055 (Cover Claims Voucher), REQ-056 (Anti-Capture Bill) all need a home. A dedicated `x/cover` module is the D-039 pattern; keeping them in `x/pact` would overload `x/pact` (which is a 6-Pact enum skeleton, not a Cover Pool runtime). The spec text "codified in `x/pact/cover`" is read as "the Cover surface, which graduated from `x/pact`" — `x/cover` is the graduated module. GRILL ratifies. | 0.82 | [keep everything in `x/pact` (overloads the 6-Pact enum module); create 3 micro-modules (`x/coverpool`, `x/covercharter`, `x/anticapture` — fragments the Cover surface)] |
|
||||
|
||||
## GRILL Decisions (Phase 0 v0.7 — GRILL, autonomy=full)
|
||||
|
||||
The ci-griller red-teamed the v0.7 plan across 9 axes + 7 specific probes. Overall verdict: **CONDITIONAL PASS** (confidence 0.72) with 5 binding decisions (D-086..D-090) and 3 escalations to PO. The plan does NOT proceed to P1 until D-086..D-090 are applied (they are applied to PLANS.md + ARCHITECTURE.md + this file). This grill IS the self-administered adversarial review (pen-test) per oy-state §7 remaining-open item 4.
|
||||
|
||||
| ID | Decision | Rationale | Confidence | Affects |
|
||||
|----|----------|-----------|------------|--------|
|
||||
| D-086 | **P1 Factory scope clarification** — P1's `MsgLaunchCoverPool` is *functional for Phase-2 categories ONLY* (Travel/HealthMCS/IncomePause). `FactoryAllowedPhases` Params field set to `[Phase2]` only in P1; Phase3/Phase4 categories REJECTED in P1. P2 extends to `[Phase2, Phase3, Phase4]`. P1 simtest includes negative case: out-of-phase category launch rejected. | The plan's "placeholder" language was ambiguous. Pinning P1 to Phase-2-only makes the vertical slice honest: P1 ships a working Factory for the Phase-2 subset, not a half-Factory. | 0.82 | PLANS P1 |
|
||||
| D-087 | **`PierCarriesVoice` const reconciliation** — P3 introduces `PierCarriesVoice bool const false` in `x/guild/types` (FR-VOICE-6: Pier does NOT carry Voice). Added as the **12th locked const** to the v0.7 const additions table (was 11; now 12). Mission-locked invariant — const is the correct firewall shape (not a field). | The plan and the const table disagreed by 1. A const that exists in code but not in the firewall table is invisible to the regression firewall. | 0.80 | PLANS const table, oy-state §3, ARCHITECTURE const table |
|
||||
| D-088 | **`lexicon_meta_cover` banned-term list + firewall shape** — (1) The `lexicon_meta_cover/` meta-test uses a NEW `lexicon.CoverBannedTerms()` helper banning `insurance`, `premium`, `claim`, `policy` scoped to the Cover surface (NOT project-wide — avoids false positives in non-Cover modules where "claim" is a common English word). (2) The `x/cover/firewall/` runtime subpackage shape is pinned to an **allow-list of permitted routing destinations** (the Pool's `ReserveAccount`), checked via string-equality at the start of every `MsgRouteCoverFee` handler. (3) **Optional cleanup:** replace `x/pact` "insurance-like" docstrings (`x/pact/types/types.go:36,158`) with "Cover-like" as a P1 doc-fix. | (1) Without a defined banned-term list, the `lexicon_meta_cover` meta-test was a paper tiger — it scanned but didn't ban the terms the plan said are banned. (2) The firewall's "rejects any code path" language was aspirational; an allow-list is the simtest-grade concrete form. (3) The `x/pact` "insurance-like" string is latent lexicon debt. | 0.78 | PLANS P1, `lexicon/lexicon.go`, `x/pact/types/types.go` |
|
||||
| D-089 | **`StillKeeper` stub + `x/bond → x/cover` CoverKeeper reverse edge** — (1) `StillKeeper.Still(poolID, reason)` is satisfied by a **simtest-local stub** (test-only, G-003 exempt), NOT a real `x/still` keeper. `x/still` is NOT extended this milestone (verified: `x/still/keeper/` is empty). (2) ARCHITECTURE.md v0.7 dependency map adds the reverse edge: `x/bond ──(CoverKeeper shim)──► x/cover` (the MAB `MsgDebitMABProceeds` handler queries `CoverKeeper.GetPoolReserveAccount(poolID)`). NEW expected-keeper interface in `x/bond/types/expected_keepers.go`. No import cycle (interface only). | (1) The auto-Still hook references a method that doesn't exist; without a documented stub, P4 cannot wire the simtest. (2) The reverse dependency edge is real (MAB handler must query the Pool's reserve account) but undocumented — a hidden architecture coupling. | 0.76 | PLANS P1/P4, ARCHITECTURE dependency map, `x/bond/types/expected_keepers.go` |
|
||||
| D-090 | **Bill of Rights temporal gap + Voucher cold-start + Standing-gate dual check + D-085 window** — (1) **Bill of Rights temporal-gap fix (most serious):** the `RightID` type + 13 `Waivable*` consts (all `false`) + `RightIsWaivable(id) bool` (always `false`) + `MsgSignCoverCharter.ValidateBasic` gate rejecting any `WaivedRights` element land in **P2** (before the first Charter can be signed), NOT P5. P5 adds the *ceremony* surface (Counsel review handler, full simtest). (2) **Voucher bond cold-start fix:** `bond = max(CoverClaimsVoucherBondMultipleAvgCall × avgCallSize, MinimumVoucherBond)` where `MinimumVoucherBond` is a Params field with a non-zero default. (3) **Standing-gate dual check:** the `CoverStandingGateTrusted`/`CoverStandingGatePreferred` floor is enforced at BOTH the `MsgLaunchCoverPool` handler AND the `MsgAmendPoolStandingGate` (Params-amendment) `ValidateBasic`. (4) **D-085 escalation window tightened to before P2** (because D-090(1) moves the RightID + 13 consts to P2). Fallback at P2: log `RightNonParticipationNoDenial` as the 13th right at confidence 0.55 and proceed. | (1) The P2→P5 temporal gap was a real security hole — rights waivable between P2 and P5. (2) Zero-bond cold-start was a Voucher bypass. (3) A Params-only check left the amendment path open. (4) The escalation window must match the new P2 deadline. | 0.72 | PLANS P2, P4, P5, RESEARCH D-085 |
|
||||
@@ -1,3 +1,4 @@
|
||||
<!-- Auto-generated from .ciagent/oy/oy-spec — PO edits oy-spec, not this file; see oy-state for current shipped state. -->
|
||||
# Requirements: OpenYield (oy)
|
||||
|
||||
| ID | Requirement | Vision § | Priority | Status | Phase |
|
||||
@@ -138,7 +139,72 @@ fixtures. No keeper, no Cosmos runtime, no `app.go`.
|
||||
> module); G-006 go.mod unchanged (HTMX is a vendored static asset, not a Go
|
||||
> dep). The final-phase audit enforces the feature purity gate.
|
||||
|
||||
## IDEATE Traceability (Phase 0 v0.6 — IDEATE stage, autonomy=full)
|
||||
## v0.7 Milestone Requirements (Fraternal Groups Foundation — Feature)
|
||||
|
||||
v0.7 adapts the 1890–1930 fraternal benefit-society model for borderless
|
||||
digital service. It delivers Cover Pools (mission-locked reserve floors +
|
||||
Standing gates), Chapter Federation (Parent/Chapter Guild model with
|
||||
secession terms + good-standing liens at founding), Mutual Aid Bonds
|
||||
(Cover-Call-couponed, 3× annual surplus ceiling, use-of-proceeds locked to
|
||||
reserve build-out), and the Anti-Capture Bill of Rights v0.2 (13 rights
|
||||
codified, non-amendable, non-waivable). This milestone unblocks the v0.1 Q7
|
||||
"Cover Pool seniority mechanics" deferred item — REQ-046..REQ-050 supply the
|
||||
seniority/gate math and promote `x/pact` Cover from skeleton to a dedicated
|
||||
`x/cover` module runtime (D-084, D-039 precedent).
|
||||
|
||||
Simtest-grade runtime (D-020 pattern continues — no live chain launch, no
|
||||
mainnet). Cover Pool "live on testnet" (§7 acceptance) = `x/cover` keeper
|
||||
message handlers + simtest-grade end-to-end flows. No `app.go`/`cmd/oyd`
|
||||
exists; v0.7 does not create one. New module: `x/cover` (Factory + Anti-
|
||||
Crowding-Out firewall + Anti-Capture Bill of Rights). The existing `x/pact`
|
||||
`PactCover` enum value remains as a cross-reference (G-003 by-ID-string).
|
||||
|
||||
| ID | Requirement | Vision § | Priority | Status | Phase |
|
||||
|----|-------------|----------|----------|--------|-------|
|
||||
| REQ-046 | Cover Pool Factory runtime — Factory rejects category launches below in-force reserve floor; supports Cover-Charter deployment; Watcher attestation pipeline operational; category staging per REQ-065 | §16 | High | Not started | v0.7/P1 |
|
||||
| REQ-047 | Cover Pool reserve target floor 1.5× annual contributions — LOCKED; mission-lock semantic enforced; below-floor auto-pause of Cover-Fee routing | §16 | High | Not started | v0.7/P1 |
|
||||
| REQ-048 | Cover Pool reserve target ceiling 2.5× (governance-tunable within 1.5×–2.5×) — Watcher escalation after 12 months; Pool Council MAY vote within bounded range | §16 | High | Not started | v0.7/P2 |
|
||||
| REQ-049 | Cover Pool Standing gate minimums — LOCKED; Travel ≥ Trusted 4.0; Health-MCS ≥ Preferred 4.5; Pool MAY tighten but NEVER loosen below protocol minimum. Binds at Factory runtime (D-077) | §16, §9.3 | High | Not started | v0.7/P1 |
|
||||
| REQ-050 | Cover-Fee tagging at protocol layer — LOCKED; Cover-Fee Grains carry `category_tag`; settlement rejects category-mismatched Calls (FR-COVER-11); Pool-level fungibility preserved for net-reserve accounting | §16 | High | Not started | v0.7/P1 |
|
||||
| REQ-051 | Guild Charter + Common Bond requirement — LOCKED; at formation: Common Bond declared + hash-pinned; Public Profile published (bond summary, disclaimers, Mason count or "private", Pier wrapper if any) | §12 | Medium | Not started | v0.7/P3 |
|
||||
| REQ-052 | Cover-Charter (SoB, dispute path, gate, holding period) — LOCKED; distinct from governance charter; signed by Pool Host + witnessed by Watcher at deployment; amendments require Pool supermajority + 7-day cooling + Watcher + Counsel; protocol does NOT enforce SoB content (FR-CHTR-5) | §16 | High | Not started | v0.7/P2 |
|
||||
| REQ-053 | Chapter Federation (Parent/Chapter, secession terms, liens at founding) — Parent Guild + Chapters; Chapters inherit + may tighten but not loosen; secession terms coded at founding; good-standing liens at founding (not freely increasable); Chapter retains mesh-level Voice (Pier does NOT carry Voice per FR-VOICE-6) | §12 | High | Not started | v0.7/P3 |
|
||||
| REQ-054 | Mutual Aid Bond (issuance ceiling 1×–3×, coupons in Cover Calls) — LOCKED; issuance ceiling mission-locked at 3× annual surplus; coupons payable in Cover Calls or mutual-aid credits (NEVER Bread); coupon rate bounded by `CouponCapBps=800`; use-of-proceeds locked to reserve build-out; default recapture per FR-MAB-7; Watcher attestation at deployment + quarterly audit. Enforcement: tagged streaming + Watcher-witnessed release (D-080) | §17 | High | Not started | v0.7/P4 |
|
||||
| REQ-055 | Cover Claims Voucher role + bond + slashing — Specialization of Voucher role; bond default 10× avg Call size per Pool; reviews each Call independently (no self-adjudication, FR-CPCV-2); slashing via §9.4 mechanism with cross-Pool applicability (NFR-SEC-8); bounded earnings | §9.4, §15 | High | Not started | v0.7/P4 |
|
||||
| REQ-056 | Anti-Capture Bill of Rights v0.2 — LOCKED; 13 rights codified in code; cannot be amended or waived by any Charter; covers one-tap exit, no tax on personal Stash, audit-able Voice, cooling, Watcher inspection, Freeholder voucher, Counsel escalation, Anchored-Bread conversion, Wayfarer's Record, secession (founding terms), non-Cover-access, category-mismatch refusal | §8.2 [3] | High | Not started | v0.7/P5 |
|
||||
| REQ-057 | Household simplified — no formal Council, one-tap exit — Household Stand may operate without formal Council; one-tap exit is the dispute path | §11 | Low | Not started | v0.7/P3 |
|
||||
| REQ-058 | Confederation Voice — one-Stand-one-Vote, internal bundle — LOCKED; Confederation aggregates member Stand Voice one-per-Stand; member Stands may bundle delegated Voice internally via §19 delegation | §11 | Medium | Not started | v0.7/P3 |
|
||||
| REQ-059 | Stand→Pier-customer boundary — escalation rule ($100k per D-074) — When annual Pass volume > $100k (10M Grain-cents), Stand is invited to Hub API; soft upgrade, not a ban | §11, §13 | Medium | Not started | v0.7/P5 |
|
||||
| REQ-060 | Shadow vouch partial credit — 50% weight in Freeholder signal — LOCKED; Shadow vouch weight = 0.5× in Community Endorsement signal (vs 1.0× for non-Shadow vouch) | §9.1 | Medium | Not started | v0.7/P4 |
|
||||
| REQ-061 | Disclaimer cadence — per charter signing — LOCKED; jurisdictional disclaimer surfaced at every charter signing; not session-bounded | §11 | Low | Not started | v0.7/P3 |
|
||||
| REQ-062 | Pool governance hybrid (Host + 3 elected + Watcher observer) — LOCKED; Cover Pool Council = Pool Host + 3 Masons elected by Pool-eligible Masons + Watcher observer seat; Cover Calls require majority with Watcher observer present. No Anchor seat (Anchor no-Voice §5) | §16 | High | Not started | v0.7/P2 |
|
||||
| REQ-063 | MAB holder — surplus seniority only, no Voice at dissolution — LOCKED; MAB holders rank after Cover-Fee contributors but before Bread holders in Pool-surplus distributions (FR-MAB-4); NO Voice in Pool dissolution decisions (claimants, not Masons) | §17 | Medium | Not started | v0.7/P4 |
|
||||
| REQ-064 | Secession cooling — 21d Cover-active / 14d non-Cover — LOCKED; Chapter secession cooling: 21 Mesh-days if Cover-active, 14 Mesh-days if non-Cover; secured at founding, not reducible; lien audit required; Cover Call / Bond covenant clearance required before secession completes | §4.6 [3] | Medium | Not started | v0.7/P5 |
|
||||
| REQ-065 | Cover Pool category staging — Phase 2/3/4 — LOCKED; Phase 2: Travel + Health-MCS + Income-Pause; Phase 3: Equipment/Loss + Life-Burial + Road-Side; Phase 4: Cyber-Skimming + Guild-Internal-Mutual-Aid; Factory respects staging and rejects out-of-phase launches | §16 | High | Not started | v0.7/P2 |
|
||||
| REQ-066 | Pier selection — Guild Council chooses, reversible, Pier Selection Index — Guild Council chooses Pier at formation; reversible by Cover Pool supermajority + Counsel witness; mesh maintains Pier Selection Index; Pier-Routed Legal Wrapper OPTIONAL (§5 default-no-wrapper) | §13 | Medium | Not started | v0.7/P5 |
|
||||
|
||||
> REQ-046..REQ-066 are NEW in v0.7. All are `feat`-class primitives (Cover
|
||||
> Pool Factory, Cover-Charter, Chapter Federation, MAB, Cover Claims Voucher,
|
||||
> Anti-Capture Bill) + a `test` adjunct for the Anti-Crowding-Out firewall
|
||||
> (D-079, ships in P1 firewall-first). No breaking schema changes to the
|
||||
> locked-const firewall; G-003 production firewall intact (`x/cover` is a new
|
||||
> module that references `x/pact`/`x/standing`/`x/bond` by ID-string only);
|
||||
> G-006 go.mod unchanged (`x/cover` keeper uses existing cosmos-sdk runtime
|
||||
> substrate). The final-phase audit enforces the feature purity gate.
|
||||
|
||||
### v0.8+ Milestone Requirements (Risk Mitigations + Infrastructure Economics — Deferred)
|
||||
|
||||
> All 31 REQs (REQ-067..REQ-097) are deferred to v0.8 per D-081 (§7
|
||||
> authoritative). Listed here for traceability; not started this milestone.
|
||||
|
||||
| ID | Requirement | Vision § | Priority | Status | Target milestone |
|
||||
|----|-------------|----------|----------|--------|------------------|
|
||||
| REQ-067..REQ-072 | Cluster A — Trust-minimization attacks (audit cadence, bridge pause, Eye quorum, Watcher fork-recovery, Anchor concentration cap, RWA venue) | §7, §16, §20, §6 | High | Deferred | v0.8 |
|
||||
| REQ-073..REQ-076 | Cluster B — Economic structural (sovereign reserve, Root Basket liquidity, MAB default recapture, Forex multi-venue) | §6, §13, §17 | High/Medium | Deferred | v0.8 |
|
||||
| REQ-077..REQ-081 | Cluster C — Capture & centralization (governance capture, Processor FCFS, Partner/Pier capture, Pool governance capture, secession abuse) | §19, §15, §13, §16, §4.6 | High/Medium | Deferred | v0.8 |
|
||||
| REQ-082..REQ-086 | Cluster D — Identity & reputation (Sybil, Window abuse, vouching cascade, norm chilling, registry identity) | §9.2, §10, §9.1, §9.4, §4.9, §11 | High/Medium | Deferred | v0.8 |
|
||||
| REQ-087..REQ-091 | Cluster E — Adoption & organic (cycle defaults, charter ambiguity, cross-chain drift, fee-covenant override, adverse selection) | §16, §11, §7, §20, §18, §19 | Medium/High | Deferred | v0.8 |
|
||||
| REQ-092..REQ-097 | Infrastructure Economics (relay fee schedule, coverage standing bonus, IYB with subordination, USZ classification, Watcher/Voucher compensation, Anchor no-Voice) | §15, §9.1, §17, §13, §7, §19 | High/Medium | Deferred | v0.8 |
|
||||
|
||||
The IDEATE stage ran the three ideation tiers (mechanical, backend-enriched,
|
||||
cross-project) on the v0.6 milestone scope and ratified 6 ideas (IDEATE-09..
|
||||
|
||||
+144
-4
@@ -2720,7 +2720,147 @@ component map → per-concern firewall/dep sections → interface contracts).
|
||||
POST (form submit) + path params (`/reaches/{id}`) is the full routing
|
||||
surface; no middleware, no wildcard host matching needed. Confidence
|
||||
0.95.
|
||||
5. **`web/main.go` is the entrypoint (not `cmd/oyd-ui/main.go`)** — D-068
|
||||
says `web/` contains `main.go` (or `cmd/oyd-ui/main.go`); the simpler
|
||||
`web/main.go` matches the mock-server scope (single binary, no
|
||||
subcommands). Confidence 0.80.
|
||||
5. **`web/main.go` is the entrypoint (not `cmd/oyd-ui/main.go`)** — D-068
|
||||
says `web/` contains `main.go` (or `cmd/oyd-ui/main.go`); the simpler
|
||||
`web/main.go` matches the mock-server scope (single binary, no
|
||||
subcommands). Confidence 0.80.
|
||||
|
||||
---
|
||||
|
||||
## v0.7 Research — Fraternal Groups Foundation (Phase 0, RESEARCH stage)
|
||||
|
||||
Scope: REQ-046..REQ-066 (21 REQs). Feature milestone. Tags run on v0.6.x
|
||||
patch line. Simtest-grade runtime only (D-020 continues). Research covered
|
||||
7 areas: (1) fraternal benefit society historical prior art, (2) Cover Pool
|
||||
runtime design, (3) MAB mechanics, (4) Anti-Capture Bill of Rights, (5)
|
||||
Chapter Federation + secession, (6) anti-gaming/Sybil surfaces, (7) persona
|
||||
assessment. Full findings in ci-researcher subagent output; key decisions
|
||||
and design recommendations summarized here.
|
||||
|
||||
### D-085 escalation candidate (13th Anti-Capture right)
|
||||
|
||||
The spec enumerates 12 of 13 rights in REQ-056 acceptance criteria: one-tap
|
||||
exit, no tax on personal Stash, audit-able Voice, cooling, Watcher
|
||||
inspection, Freeholder voucher, Counsel escalation, Anchored-Bread
|
||||
conversion, Wayfarer's Record, secession (founding terms), non-Cover-access,
|
||||
category-mismatch refusal. The 13th is NOT enumerated. Best candidate
|
||||
(confidence 0.55): "non-participation MUST NOT deny other mesh products"
|
||||
(REQ-085 / FR-NORM-4 norm-chilling defense). Alternatives: "Standing
|
||||
portability", "Mesh migration". This is a low-confidence assumption —
|
||||
escalated through normal decision flow; NOT auto-decided. The lead-developer
|
||||
must surface D-085 to the PO before P5 (Anti-Capture Bill lands in P5). If
|
||||
unresolved at full autonomy by P5, log as assumption with the
|
||||
NonParticipationNoDenial candidate and proceed.
|
||||
|
||||
### Design recommendations (grounded in codebase)
|
||||
|
||||
1. **`x/cover` module layout mirrors `x/hub` (D-039 precedent, D-084).**
|
||||
Verified at `x/hub/types/types.go:33-57` + `x/hub/module.go:32-55`. Layout:
|
||||
`x/cover/{module.go, types/{types.go,rights.go,firewall.go,expected_keepers.go,msg_cover.go}, keeper/{keeper.go,msg_server.go,firewall.go,msg_server_simtest_test.go}}`.
|
||||
The `x/pact` `PactCover` enum value (`x/pact/types/types.go:36`) stays as
|
||||
cross-reference; `x/cover` owns the runtime. Confidence 0.90.
|
||||
|
||||
2. **Cover-Fee category tagging in `x/cover`, NOT `x/bread` (REQ-050).** No
|
||||
`Grain` struct exists today (`x/bread/types/types.go` has only
|
||||
`BreadScale`/`Params`/`GenesisState`). Adding a tag field to `x/bread`
|
||||
risks the `GrainsPerBread=10000` locked-const firewall. A `CoverFeeTag`
|
||||
struct in `x/cover/types` (`{GrainAmount int64, CategoryTag string,
|
||||
PoolID string}`) is schema-additive and puts the tag where the
|
||||
category-mismatch rejection (FR-COVER-11) lives. Confidence 0.82.
|
||||
|
||||
3. **Standing gate via expected-keeper shim (G-003, D-077).** `x/cover`
|
||||
defines a `StandingKeeper` interface
|
||||
(`GetStandingBucket(reachID, category string) (bucket string, score
|
||||
float64, err error)`); the `x/standing` keeper satisfies it structurally.
|
||||
The gate compares the returned bucket string against LOCAL `x/cover`
|
||||
consts `CoverStandingGateTrusted=4.0` / `CoverStandingGatePreferred=4.5`
|
||||
(cross-documented to `x/standing.BucketTrusted`/`BucketPreferred`).
|
||||
Mirrors `x/bond/types/expected_keepers.go:43-49` `StandKeeper` pattern.
|
||||
Confidence 0.88.
|
||||
|
||||
4. **MAB as `x/bond` extension (anonymous embed), NOT a new module.**
|
||||
`MAB struct { Bond; CouponKind CouponDenom; AnnualSurplusAtIssuance
|
||||
int64; UseOfProceedsTag string }` in `x/bond/types`. Mirrors GrowthBond
|
||||
at `x/bond/types/types.go:262-265`. `CouponDenom` enum with
|
||||
`CouponDenomBread` rejected at `ValidateBasic` (MissionLockAmendmentRejected
|
||||
pattern at `x/council/types/types.go:242`). 3× ceiling as keeper-level
|
||||
runtime check against current annual surplus. Confidence 0.88.
|
||||
|
||||
5. **D-080 tagged streaming + Watcher-witnessed release.** `UseOfProceedsTag`
|
||||
field locked to `"reserve_build_out"` at issuance; keeper enforces
|
||||
proceeds only debit to `CoverPool.ReserveAccount`; misuse → auto-Still
|
||||
(`x/still` exists). `MsgWitnessMABProceedsRelease` requires Watcher quorum
|
||||
(6-of-9, `x/watcher/types/types.go:23`). Confidence 0.84.
|
||||
|
||||
6. **Anti-Capture Bill of Rights = 13 RightID consts + 13 Waivable* bool
|
||||
consts (all false) + `RightIsWaivable(id)` always returns false.** Dual
|
||||
firewall: const + `ValidateBasic` gate on Cover-Charter `WaivedRights`
|
||||
field (mirrors `MissionLockAmendable=false` +
|
||||
`MissionLockAmendmentRejected`). In `x/cover/types/rights.go` (NOT a
|
||||
separate `x/cover/rights` package — D-079 specifies separate
|
||||
`x/cover/firewall` package for enforcement, but rights *declaration* is a
|
||||
type/const surface). Confidence 0.90.
|
||||
|
||||
7. **Anti-Crowding-Out firewall (D-079) = `x/cover/firewall` subpackage
|
||||
(runtime `CheckCoverFeeRouting`) + `lexicon_meta_cover` meta-test
|
||||
(test-time doc-drift rejection).** Defense in depth. The firewall is the
|
||||
enforcement mechanism for the `RightNoTaxOnPersonalStash` right (the
|
||||
right is policy; the firewall is implementation). Confidence 0.82.
|
||||
|
||||
8. **Guild extension: `ParentGuildID string` + `IsChapter bool` +
|
||||
`SecessionTermsHash []byte` + `GoodStandingLiens []Lien`.** No `GuildKind`
|
||||
enum (schema-additive without a new locked-const count).
|
||||
`SecessionTerms` struct hash-pinned at creation (immutable).
|
||||
`Lien.SecuredAtFounding=true` liens NOT freely increasable. Cooling consts
|
||||
`CoolingSecessionCoverActiveDays=21` / `CoolingSecessionNonCoverDays=14`
|
||||
in `x/guild/types` (protocol minimum; Chapter MAY specify longer, NOT
|
||||
shorter). Confidence 0.85.
|
||||
|
||||
9. **Shadow vouch 50% weight (REQ-060) = new const
|
||||
`ShadowVouchWeightMultiplier=0.5` + new `IsShadow bool` field on `Vouch`
|
||||
+ post-multiplier branch in `GetVoucherWeight`.** The const makes the 0.5×
|
||||
mission-locked (REQ-060 locked) and regression-testable. A hardcoded 0.5
|
||||
in a branch is invisible to the locked-const firewall. Confidence 0.85.
|
||||
|
||||
10. **Cover Claims Voucher (REQ-055) = `CoverClaimsVoucher` struct in
|
||||
`x/cover/types` (NOT `x/standing`).** Bond =
|
||||
`CoverClaimsVoucherBondMultipleAvgCall=10` × Pool avg Call size. Slash
|
||||
via existing `x/standing.Slash` with new
|
||||
`SlashReasonFraudulentCoverCall` const (cross-Pool via Standing bucket
|
||||
drop). No self-adjudication: `MsgFileCoverCall` handler rejects if
|
||||
`voucherReachID == claimantReachID` (FR-CPCV-2). Confidence 0.82.
|
||||
|
||||
### Persona assessment
|
||||
|
||||
Active for v0.7: backend-engineer (all phases — the bulk), lead-developer
|
||||
(all phases — coordination + D-085 escalation + pen-test assumption),
|
||||
security-engineer (all phases — highest security density since v0.5),
|
||||
cosmos-engineer (all phases — advisory; x/cover follows x/hub pattern).
|
||||
|
||||
Deactivated: frontend-engineer (zero UI), docs-writer (no docs-content),
|
||||
mesh-engineer (no bearer work), data-engineer (no genesis-schema work).
|
||||
ci-security-auditor: off until P6 (final review/audit/ship).
|
||||
|
||||
Full PERSONAS.md written to `.ciagent/oy/PERSONAS.md`.
|
||||
|
||||
### Pitfalls (avoid)
|
||||
|
||||
- Do NOT centralize Cover risk at the Root-Pool (historic AOUW collapse
|
||||
reproduced; Anti-Crowding-Out firewall is the defense).
|
||||
- Do NOT enforce uniform SoB content (historic centralization; FR-CHTR-5).
|
||||
- Do NOT add `CategoryTag` to `x/bread/types.Grain` (risks GrainsPerBread
|
||||
locked-const firewall; use CoverFeeTag in x/cover).
|
||||
- Do NOT import `x/standing/types` structs in `x/cover` (G-003; use
|
||||
expected-keeper shim).
|
||||
- Do NOT retire `x/pact.PactCover` enum value (stays as cross-reference).
|
||||
- Do NOT make 1.5× floor a Params field (locked const; only 2.5× ceiling is
|
||||
governance-tunable within bounds).
|
||||
- Do NOT allow `CouponDenomBread` MAB (rejected at ValidateBasic).
|
||||
- Do NOT give MAB holders Voice (REQ-063 locked; claimants, not Masons).
|
||||
- Do NOT add a `GuildKind` enum (bool IsChapter + ParentGuildID string is
|
||||
schema-additive without a new locked-const count).
|
||||
- Do NOT make cooling periods reducible (REQ-064 locked; secured at founding).
|
||||
- Do NOT implement Shadow vouch 50% without a const (locked-const firewall
|
||||
invisibility).
|
||||
- Do NOT put `CoverClaimsVoucher` in `x/standing` (role is Cover-specific).
|
||||
- Do NOT auto-decide the 13th right (D-085 escalation; confidence 0.55).
|
||||
@@ -0,0 +1,179 @@
|
||||
# OpenYield Spec — spec-v3 (net new only)
|
||||
Owner: <product owner>
|
||||
Status: draft
|
||||
Ingested as: oy-spec
|
||||
|
||||
> This spec contains ONLY net new requirements, constraints, and decisions for v0.7+ scope. Locked-vision baseline (REQ-001..REQ-021), shipped REQs (REQ-022..REQ-045 per `oy-state` §2), Principles [locked], Lexicon [locked], and pre-filled project invariants are NOT restated; they remain in force per vision v3.0 and prior spec revisions. This is the diff against spec-v2.
|
||||
|
||||
## 1. Objective
|
||||
|
||||
The v0.7 milestone delivers **Fraternal Groups Foundation** — Cover Pools, Chapter Federation, Mutual Aid Bonds, and the Anti-Capture Bill of Rights v0.2 — adapting the 1890–1930 fraternal benefit-society model for borderless digital service [3]. The v0.8+ roadmap layers in **Risk Mitigations + Infrastructure Economics** — Cluster A–E risk register closures, infrastructure underwriting primitives (Relay Fee Schedule, Coverage Standing Bonus, IYB with subordination, USZ classification), Watcher/Voucher compensation, and the Anchor no-Voice clause. Two PO rulings bind this revision: **no subsidies** (Root-Pool operating-expense subsidies and transfer-payment analogs are forbidden), and **Anchor no-Voice** (Anchors — including Sovereign Anchors — receive preferred contract terms only, never governance Voice).
|
||||
|
||||
## 2. Vision source
|
||||
Vision v3.0 [1]; SPEC-001 `oy-fraternal-groups` v0.2 [3]. All locked commitments remain in force; **no vision amendments proposed**.
|
||||
|
||||
## 3. Principles [locked]
|
||||
Locked per vision v3.0 §2. Not restated.
|
||||
|
||||
## 4. Requirements (net new)
|
||||
|
||||
> REQ-001..REQ-021 are locked-vision baseline (in force, not restated). REQ-022..REQ-045 are shipped per `oy-state` §2 (not restated). New REQs continue from REQ-046.
|
||||
|
||||
### v0.7 — Fraternal Groups Foundation (REQ-046..REQ-066)
|
||||
|
||||
#### Fraternal Group Primitives (REQ-046..REQ-056)
|
||||
|
||||
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|
||||
|----|-------|----------|---------|---------|---------------------|
|
||||
| REQ-046 | Cover Pool Factory runtime | §16 | High | no | Factory rejects category launches below in-force reserve floor; supports Cover-Charter deployment; Watcher attestation pipeline operational; category staging per REQ-065 |
|
||||
| REQ-047 | Cover Pool reserve target floor 1.5× annual contributions | §16 | High | yes | 1.5× minimum reserve codified in `x/pact/cover`; mission-lock semantic enforced; below-floor auto-pause of Cover-Fee routing |
|
||||
| REQ-048 | Cover Pool reserve target ceiling 2.5× (governance-tunable within bounds) | §16 | High | no | Watcher escalation to 2.5× after 12 months operating history; Pool Council MAY vote within bounded range 1.5×–2.5× |
|
||||
| REQ-049 | Cover Pool Standing gate minimums | §16, §9.3 | High | yes | Travel ≥ Trusted 4.0; Health-MCS ≥ Preferred 4.5; Pool Council MAY tighten but NEVER loosen below protocol minimum |
|
||||
| REQ-050 | Cover-Fee tagging at protocol layer | §16 | High | yes | Cover-Fee Grains carry `category_tag`; settlement engine rejects category-mismatched Calls (FR-COVER-11); Pool-level fungibility preserved for net-reserve accounting |
|
||||
| REQ-051 | Guild Charter + Common Bond requirement | §12 | Medium | yes | At formation: Common Bond declared + hash-pinned; Public Profile published (bond summary, disclaimers, Mason count or "private", Pier wrapper if any) |
|
||||
| REQ-052 | Cover-Charter (Statement of Beliefs, dispute path, gate, holding period) | §16 | High | yes | Cover-Charter distinct from governance charter; signed by Cover Pool Host + witnessed by Watcher at deployment; amendments require Pool supermajority + 7-day cooling + Watcher + Counsel; protocol does NOT enforce SoB content (FR-CHTR-5) |
|
||||
| REQ-053 | Chapter Federation (Parent/Chapter, secession terms, liens at founding) | §12 | High | no | Parent Guild + Chapters model; Chapters inherit + may tighten but not loosen; secession terms coded at founding; good-standing liens at founding (not freely increasable); Chapter retains mesh-level Voice (Pier does NOT carry Voice per FR-VOICE-6) |
|
||||
| REQ-054 | Mutual Aid Bond (issuance ceiling 1×–3×, coupons in Cover Calls) | §17 | High | yes | Issuance ceiling mission-locked at 3× annual surplus; coupons payable in Cover Calls or mutual-aid credits (NEVER Bread); coupon rate bounded by `CouponCapBps=800`; use-of-proceeds locked to reserve build-out; default recapture per FR-MAB-7; Watcher attestation at deployment + quarterly audit |
|
||||
| REQ-055 | Cover Claims Voucher role + bond + slashing | §9.4, §15 | High | no | Specialization of Voucher role; bond default 10× avg Call size per Pool; reviews each Call independently (no self-adjudication, FR-CPCV-2); slashing via §9.4 mechanism with cross-Pool applicability (NFR-SEC-8); bounded earnings |
|
||||
| REQ-056 | Anti-Capture Bill of Rights v0.2 | §8.2 [3] | High | yes | 13 rights codified in code; cannot be amended or waived by any Charter; covers one-tap exit, no tax on personal Stash, audit-able Voice, cooling, Watcher inspection, Freeholder voucher, Counsel escalation, Anchored-Bread conversion, Wayfarer's Record, secession (founding terms), non-Cover-access, category-mismatch refusal |
|
||||
|
||||
#### Architect Recommendations Q1–Q10 (REQ-057..REQ-066)
|
||||
|
||||
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|
||||
|----|-------|----------|---------|---------|---------------------|
|
||||
| REQ-057 | Household simplified — no formal Council, one-tap exit | §11 | Low | no | Household Stand may operate without formal Council; one-tap exit is the dispute path |
|
||||
| REQ-058 | Confederation Voice — one-Stand-one-Vote, internal bundle | §11 | Medium | yes | Confederation aggregates member Stand Voice one-per-Stand; member Stands may bundle delegated Voice internally via §19 delegation |
|
||||
| REQ-059 | Stand→Pier-customer boundary — escalation rule (TBD-X volume threshold) | §11, §13 | Medium | no | When annual volume > TBD-X, Stand is invited to Hub API; soft upgrade, not a ban. **TBD-X = PO ruling needed (§8)** |
|
||||
| REQ-060 | Shadow vouch partial credit — 50% weight in Freeholder signal | §9.1 | Medium | yes | Shadow vouch weight = 0.5× in Community Endorsement signal (vs 1.0× for non-Shadow vouch) |
|
||||
| REQ-061 | Disclaimer cadence — per charter signing | §11 | Low | yes | Jurisdictional disclaimer surfaced at every charter signing; not session-bounded |
|
||||
| REQ-062 | Pool governance hybrid (Host + 3 elected + Watcher observer) | §16 | High | yes | Cover Pool Council = Pool Host + 3 Masons elected by Pool-eligible Masons + Watcher observer seat; Cover Calls require majority with Watcher observer present |
|
||||
| REQ-063 | MAB holder — surplus seniority only, no Voice at dissolution | §17 | Medium | yes | Mutual Aid Bond holders rank after Cover-Fee contributors but before Bread holders in Pool-surplus distributions (FR-MAB-4); NO Voice in Pool dissolution decisions (claimants, not Masons) |
|
||||
| REQ-064 | Secession cooling — 21d Cover-active / 14d non-Cover | §4.6 [3] | Medium | yes | Chapter secession cooling: 21 Mesh-days if Cover-active, 14 Mesh-days if non-Cover; secured at founding, not reducible; lien audit required; Cover Call / Bond covenant clearance required before secession completes |
|
||||
| REQ-065 | Cover Pool category staging — Phase 2/3/4 | §16 | High | yes | Phase 2: Travel + Health-MCS + Income-Pause; Phase 3: Equipment/Loss + Life-Burial + Road-Side; Phase 4: Cyber-Skimming + Guild-Internal-Mutual-Aid; Factory respects staging and rejects out-of-phase launches |
|
||||
| REQ-066 | Pier selection — Guild Council chooses, reversible, Pier Selection Index | §13 | Medium | no | Guild Council chooses Pier at formation; reversible by Cover Pool supermajority + Counsel witness; mesh maintains Pier Selection Index (jurisdictional reliability, fiduciary record, integration quality); SPEC-001 §8.3 Pier-Routed Legal Wrapper remains OPTIONAL with default-no-wrapper stance |
|
||||
|
||||
### v0.8+ — Risk Mitigations + Infrastructure Economics (REQ-067..REQ-097)
|
||||
|
||||
> All REQs in this section are LOCKED unless otherwise specified. Each maps to a Cluster A–E mitigation in the risk register.
|
||||
|
||||
#### Cluster A — Trust-minimization attacks (REQ-067..REQ-072)
|
||||
|
||||
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|
||||
|----|-------|----------|---------|---------|---------------------|
|
||||
| REQ-067 | Smart contract audit cadence + bounty + Still/Stir | §20 | High | yes | ≥2 independent audits before each Phase transition (high/critical remediated pre-launch); severity-graded bounty (Cat >$1M, Crit >$100k); module-level Still/Stir with Watcher-witnessed halt; canary 5→25→100% on parameter changes; >72h time-lock on parameter changes unless emergency Mesh Council + Watcher witness |
|
||||
| REQ-068 | Bridge pause semantics + multi-path + daily Watcher attestation | §7 | High | yes | `BridgeStatusCount=4` (Active→Paused→Frozen→Sunset); rate-limit per bridge per cycle; ≥2 independent paths for any mission-critical satellite; Watcher daily attestation of bridge balances (mismatch → auto-Still); Root-Pool-funded insurance pool |
|
||||
| REQ-069 | Eye quorum ≥7 + diversity + TWAP | §16 | High | yes | ≥7 Eyes per asset class; median (not mean); geographic/organizational diversity (no single Eye jurisdiction >25% weight); TWAP minimum 1-hour window; outlier rejection at 2σ, alerts at 1σ; Eye reputation with slashing bond (Watcher model); mesh-level Still per asset class on variance breach |
|
||||
| REQ-070 | Watcher 6-of-9 + 100k bond + daily cadence + fork-recovery | §7 | High | yes | All vision §7 + fork-recovery path: governance can fork from a captured Watcher set within Mission Lock bounds; rotation on instability metric (missed attestations, peer-deviation); slashing at 100,000 Bread bond per bad attestation |
|
||||
| REQ-071 | Anchor concentration cap 20% + redemption gate + auto-Still | §6 | High | yes | Any single Anchored-Bread ≤20% of Root Basket (governance-tunable within bounds); 24–72h redemption gate when anchor deviates >2% from peg; quarterly stress tests Watcher-witnessed; auto-Still for the affected stream |
|
||||
| REQ-072 | RWA venue multi-custodian + multi-jurisdiction minimum + Watcher attestation | §6 | High | yes | ≥3 independent custodians with segregated accounts; jurisdictional spread preferred (≥2 jurisdictions where commercially feasible) but NOT load-bearing; Watcher attestation per venue (reserves, NAV, audit reports); Watcher + Counsel sign-off substitution path within 30 days; insurance where commercially available |
|
||||
|
||||
#### Cluster B — Economic structural (REQ-073..REQ-076)
|
||||
|
||||
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|
||||
|----|-------|----------|---------|---------|---------------------|
|
||||
| REQ-073 | Sovereign reserve — ≥2 independent entities | §6, §13 | High | yes | ≥2 independent reserve entities (different legal forms; jurisdiction selection driven by legal robustness + banking reliability + regulatory clarity — NOT by jurisdiction count); segregated accounts; quarterly third-party audits; ≥2 banking partners per currency; cash-equivalents only at entity level |
|
||||
| REQ-074 | Root Basket liquidity tier 7-day 10%-redemption target | §6 | Medium | yes | Short-duration T-bills ~35% working (liquidity tier); 7-day, 10%-redemption stress test target <1% slippage; staged redemption gates above $X with 24h hold; facility lines at banking partners where feasible |
|
||||
| REQ-075 | Mutual Aid Bond default recapture + seniority | §17 | High | yes | MAB coupons in Cover Calls (NEVER Bread, FR-MAB-3); seniority per FR-MAB-4 (Cover-Fee contributors > MAB > Bread holders); Watcher quarterly review + red-flag escalation on miss; default recapture per FR-MAB-7; mission-lock on bond covenant upper 8% lower 0% (REQ-021) |
|
||||
| REQ-076 | Forex Engine multi-venue + Watcher daily attestation | §13 | Medium | yes | ≥3 counterparties per major currency corridor; annual counterparty due diligence; real-time exposure caps per counterparty; Watcher daily attestation on Forex reserve balances; governance substitution within composition bounds |
|
||||
|
||||
#### Cluster C — Capture & centralization (REQ-077..REQ-081)
|
||||
|
||||
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|
||||
|----|-------|----------|---------|---------|---------------------|
|
||||
| REQ-077 | Governance capture — multi-source Voice + Mission Lock + supermajority + cooling | §19 | High | yes | Multi-source Voice per §19 (Bread 1/1000, Freeholder full Voice, one-Mason-one-Vote opt-in, Guild delegation); Mission Lock list enforced (six non-amendable items); supermajority ≥67% + 7-day cooling on any governance action affecting funds; Watcher right of inspection on governance logs; `MissionLockAmendmentRejected` ProposalKind reverts amendment vote at protocol layer (D-064) |
|
||||
| REQ-078 | Processor FCFS + dynamic share (parity with Processors, extended to relay operators per REQ-092) | §15 | High | yes | FCFS (not fee-auctioned); geographic proximity wins; light client ~30MB / 1-3% battery/day; dynamic processor share auto-declining 50→30→20→10% as volume grows |
|
||||
| REQ-079 | Partner/Pier capture — self-service default + Window revoke + pay-to-play | §13 | High | yes | Self-service default (Principle 6) — no Partner required for any product; Window one-tap revoke; pay-to-play model (Piers pay OY, not reverse); mesh-level Pier Selection Index; Cover-Charter amendments require Watcher witness + Counsel signature; Chapter retains mesh-level Voice regardless of Pier fiduciary role |
|
||||
| REQ-080 | Pool governance capture — hybrid + Cover Claims Voucher + Chapter secession | §16 | High | yes | Hybrid Pool governance (REQ-062); Cover Calls require majority with Watcher observer; Cover Claims Voucher independent adjudication (REQ-055); Chapter secession right (founding terms, REQ-064); MAB holders have NO Voice (REQ-063) |
|
||||
| REQ-081 | Secession abuse — lien-bounding + cooling + lien audit | §4.6 [3] | Medium | yes | Good-standing liens codified at founding, not freely increasable (FR-CHAP-7); cooling periods 21d Cover-active / 14d non-Cover (REQ-064); secession requires Chapter Head signature + Good-Standing Lien audit; Cover Call / Bond covenant clearance required before secession completes; Parent Guild Treasury receives pro-rata Cover-Fee settlement for in-flight Cover Calls |
|
||||
|
||||
#### Cluster D — Identity & reputation (REQ-082..REQ-086)
|
||||
|
||||
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|
||||
|----|-------|----------|---------|---------|---------------------|
|
||||
| REQ-082 | Sybil on Standing — Bayesian prior + distinct counterparties + time decay | §9.2 | High | yes | Bayesian prior weight 10 (§9.2); minimum distinct counterparties 3/10/30; time-decayed Bayesian average penalizes burst-rating; Diversity Bonus × Voucher Weight resists amplification; Watcher attestation on Freeholder transition; 90-day Stash Maturity signal |
|
||||
| REQ-083 | Window abuse — 5-property semantics + rate-limit enforcement | §10 | High | yes | Window enforces 5 properties (Scope, Duration, Rate-limit, Audit log, Revoke); one-tap revoke works mid-service; audit log exportable to Holder's Stash at any time; rate-limit enforcement is protocol-layer with Watcher-witnessed violations; Partner abuse triggers Window closure + Partner status review |
|
||||
| REQ-084 | Vouching cascade — vouch slashes voucher + Watcher detection | §9.1, §9.4 | Medium | yes | Vouch requires skin-in-the-game — vouchee's Crack slashes voucher's Standing; Freeholder min-counterparties = 10 makes cascade hard to bootstrap; Watcher detection on rapid vouch sequences; Voucher Weight tapers with chain depth |
|
||||
| REQ-085 | Norm chilling — Cover opt-in + dispute path + public profile | §4.9 [3] | Medium | yes | Cover opt-in (FR-NORM-4); non-participation MUST NOT deny other mesh products; norms enforced only through dispute path (FR-NORM-2), never unilateral Council; norm violations counted toward §9.4 slashing history (visible reputation consequence); Pool Public Profile must publish Statement if any (FR-CHTR-4 + FR-GLD-11); protocol never enforces SoB content |
|
||||
| REQ-086 | Registry as identity — Shadow pseudonymity + schema minimalism | §11 | Medium | yes | Shadow Stand pseudonymous at protocol layer (FR-SHADOW-2 + §11); public/private visibility Holder-chosen (not Registry-mandated); Window reads explicit + rate-limited + logged + revocable (NFR-PRI-3); Watcher witness on private Stand registry access; Registry base schema excludes identity-grade fields (no names, no biometrics, no Pier credentials) |
|
||||
|
||||
#### Cluster E — Adoption & organic (REQ-087..REQ-091)
|
||||
|
||||
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|
||||
|----|-------|----------|---------|---------|---------------------|
|
||||
| REQ-087 | Cycle defaults — Cover integration + hash-committed order | §16, §11 | Medium | yes | Cover Pool integration with default ranking (SPEC-001 §12.1); Cycle Host order hash-committed (FR-CIRCLE-1); Counsel-mediated dispute path (FR-CIRCLE-4); Circle pauses via Still on default; restarts after resolution |
|
||||
| REQ-088 | Charter ambiguity — linter + Counsel review | §11 | Low | yes | Charter-template linter at Registry submission (covers common fields); Counsel review at chartering for any non-standard Charter; Counsel right to amend within 30-day ambiguity window without unanimous Mason approval |
|
||||
| REQ-089 | Cross-chain drift — Watcher per-chain attestation + canonical routing | §7, §20 | Medium | yes | Watchers re-attest per chain (per REQ-068 daily cadence + `BridgeStatusCount=4`); cross-chain Mirror registry with rolling snapshots per cycle for Stand Registry reads; Stand Registry reads route to canonical source via Window; drift triggers Paused bridge-status |
|
||||
| REQ-090 | Fee-Covenant override — Mission Lock + smart-contract enforcement + Council vote revert | §18, §19 | High | yes | Fee ceiling 0.1%, floor 0.01%, 1-Grain minimum non-amendable (Mission Lock); smart-contract enforcement with Watcher attestation; `MissionLockAmendmentRejected` ProposalKind reverts any Council vote to amend (D-064); structural ceiling on governance capture |
|
||||
| REQ-091 | Adverse selection — Standing gate + holding period + Pool tightening | §16 | High | yes | Standing-gate minimums mission-locked (REQ-049: Trusted 4.0 Travel / Preferred 4.5 Health-MCS); 30-day default holding period (FR-COVER-9); Pool tightening permitted but not loosening below protocol minimum; Cover Claims Voucher independent review of high-risk claims; aggregate statistics public (NFR-PRI-4) to drive Pool-level gate tuning |
|
||||
|
||||
#### Infrastructure Economics (REQ-092..REQ-097)
|
||||
|
||||
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|
||||
|----|-------|----------|---------|---------|---------------------|
|
||||
| REQ-092 | Relay Fee Schedule (parity with Processors, auto-declining) | §15 | High | yes | Per-packet relay fee for OY-LR / OY-BLE / OY-WiFi-Direct relay operators; paid in Bread from protocol-fee pool; auto-declining on same schedule as Processor share (50→30→20→10%); self-balancing supply (dense zones saturate, sparse zones attract premium) |
|
||||
| REQ-093 | Coverage Standing Bonus (supplement Committed Capital, not replace) | §9.1 | Medium | yes | Sustained infrastructure provision (90-day rolling relay uptime, Watcher attestation) counts as a Standing signal; supplements (does NOT replace) Committed Capital (which remains 1+ active Pact OR 60+ day Guild per §9.1); same anti-gaming rules apply |
|
||||
| REQ-094 | Infrastructure Yield Bond (with structural subordination) | §17 | Medium | yes | IYB coupon from Root-Pool infrastructure budget; bounded by `CouponCapBps=800`; use-of-proceeds locked to infrastructure build-out; standard IYB for high-density (commercial trade routes, dense corridors); subordinated IYB for transitional USZs (Anchor takes first loss, local fee revenue takes upside); Watcher attestation at deployment + every quarterly audit |
|
||||
| REQ-095 | Universal Service Zone classification (no subsidies) | §13 | Medium | yes | USZ designation via Mesh Council vote within bounds; ≥3 criteria (density, strategic value, mission-aligned override); opt-in (zones choose to be USZs); **NO SUBSIDIES** — infrastructure capital sourced EXCLUSIVELY from (a) Anchor pre-commitment, (b) Sovereign Anchor partnerships, (c) subordinated IYB; market decides whether USZ infrastructure is built; **TBD-Z density formula = PO ruling needed (§8)** |
|
||||
| REQ-096 | Watcher/Voucher operating-expense compensation (capped) | §7, §19 | Medium | yes | Watcher + Voucher compensation paid from Root-Pool operating budget; capped annually by Mesh Council vote within bounds; NOT from Bond Market fees (avoids fee-maximization race); audited quarterly by Watchers; Counsel = civic contribution, no operating-expense compensation |
|
||||
| REQ-097 | Anchor no-Voice clause (Anchor = preferred terms, zero Voice) | §13, §19 | High | yes | Anchors (commercial per §13) — and Sovereign Anchors — receive preferred contract terms only; ZERO Voice in any Council; no Voice transfer to underlying governments or institutions; Pier Selection Index surfaces Anchor reputation; no "no masters" violation, no matter the Anchor's institutional weight |
|
||||
|
||||
## 5. Constraints (net new)
|
||||
|
||||
> Pre-filled project invariants (14 components, lexicon firewall, Mission Lock non-amendable, etc.) remain in force per spec-v2 and prior revisions; not restated.
|
||||
|
||||
Net new for spec-v3:
|
||||
|
||||
- **No subsidies.** Root-Pool operating-expense subsidies, transfer-payment analogs, and welfare-state derivatives are **FORBIDDEN**. Capital for infrastructure is sourced exclusively from Anchor pre-commitment underwriting, Sovereign Anchor partnerships, and subordinated Infrastructure Yield Bond structures. *(oy-spec-v3, PO ruling 2026-08-18)*
|
||||
- **Anchor no-Voice.** Anchors (per §13) — including Sovereign Anchors — receive preferred contract terms only. **ZERO Voice in any Council.** No Voice transfer to underlying governments or institutions. *(oy-spec-v3, PO ruling 2026-08-18)*
|
||||
- **Sovereign Anchors require separate SPEC.** The Sovereign Anchor framework is too infrastructure-scale to fold into oy-spec. Forthcoming SPEC: `oy-sovereign-anchors`. Until that SPEC ships, USZ infrastructure financing via Sovereign Anchor partnerships is **experimental, not load-bearing**. *(oy-spec-v3, PO ruling 2026-08-18)*
|
||||
- **Pier-Routed Legal Wrapper is OPTIONAL.** Default stance: no wrapper required. SPEC-001 §8.3 menu is value-add for Chapters/Guilds that want a legal seat, not a requirement. *(oy-spec-v3, per session refactor)*
|
||||
|
||||
## 6. Lexicon [locked]
|
||||
Locked per vision v3.0 §3. Not restated.
|
||||
|
||||
## 7. Milestone intent
|
||||
|
||||
- **Current shipped:** v0.6 (Nomad Web UI) — v0.5.6 — COMPLETE [2]
|
||||
- **Next: v0.7 — Fraternal Groups Foundation.** Ships REQ-046..REQ-056 (Cover Pool Factory + Cover-Charter + Chapter Federation + Mutual Aid Bond + Cover Claims Voucher + Anti-Capture Bill v0.2) + REQ-057..REQ-066 (architect recommendations Q1–Q10).
|
||||
- *Acceptance:* ≥1 Cover Pool live on testnet with reserve enforcement + Standing gate + category tagging; ≥1 Parent Guild with Chapter in secession-eligible formation with good-standing liens declared at founding; ≥1 Mutual Aid Bond issuance with Cover-Call coupon settlement + use-of-proceeds lock to reserve build-out; Anti-Capture Bill v0.2 reviewed by bonded Counsel; pen-test ≥1 independent third party; high/critical findings remediated.
|
||||
- **v0.8 — Risk Mitigations + Infrastructure Economics.** Ships REQ-067..REQ-097 (Cluster A–E mitigations + Relay Fee Schedule + Coverage Standing Bonus + IYB + USZ classification + Watcher/Voucher compensation + Anchor no-Voice).
|
||||
- *Acceptance:* all listed REQs in §4 v0.8+ implemented with regression tests; `oy-state` §3 const firewall extended with `EyeQuorumMin=7`, `AnchorConcentrationCapBps=2000`, `MABCouponMaxAnnualSurplusMultiple=3`, `BondIssuerSurplusCeilings={1×, 2×, 3×}`, `CoolingSecessionCoverActive=21 days`, `CoolingSecessionNonCover=14 days`, `CoverReserveFloorAnnualContribX=1.5`.
|
||||
- **Out-of-scope additions for v0.7:**
|
||||
- Sovereign Anchor SPEC (forthcoming; experimental only this milestone per §5)
|
||||
- USZ classification runtime (deferred to v0.8 — depends on Anchor pre-commitment framework)
|
||||
- Pre-existing deferred items per `oy-state` §4 remain deferred (not restated here)
|
||||
|
||||
## 8. Open questions (net new)
|
||||
|
||||
> Pre-existing PO decisions tracked in `oy-state` §7 remain open unless addressed here.
|
||||
|
||||
1. **TBD-X volume threshold** for Stand→Pier-customer boundary escalation (REQ-059). PO recommendation: **$100k annual Pass volume**.
|
||||
2. **TBD-Z density formula** for USZ classification (REQ-095). PO recommendation: **<10 Holders per km² AND strategic value ≥ mission score, OR sovereign request, OR mission-aligned override via Mesh Council supermajority**.
|
||||
3. **Sovereign Anchor SPEC scope decision.** Separate SPEC (`oy-sovereign-anchors`) or fold into `oy-pier`? PO recommendation: **separate SPEC** — Sovereign Anchors are infrastructure-scale, not legal-wrapper-scale; v0.7 status is *experimental, not load-bearing* per §5.
|
||||
4. **Risk mitigation sequencing.** Which of REQ-067..REQ-091 ship in v0.7 vs deferred to v0.8? PO recommendation: **Cluster A + B + C ship in v0.7 (immediate existential + economic + capture risks); Cluster D + E + REQ-092..REQ-097 ship in v0.8 (immune-system + adoption + infrastructure economics).**
|
||||
5. **Standing gate enforcement timing.** When does REQ-049 (Cover Pool Standing gate minimums) bind? At Cover Pool Factory runtime (v0.7) or at first live Cover Pool deployment (v0.7 acceptance)? PO recommendation: **Factory runtime — gates are protocol-layer.**
|
||||
6. **Watcher/Voucher operating-expense cap.** Mesh Council vote within bounds; PO recommendation: **annual cap = 5% of Root-Pool Bloom, capped at $TBD-W absolute**.
|
||||
7. **Anti-Crowding-Out Covenant enforcement code.** The covenant is in §1 / §2.3 of SPEC-001 [3]; does the ciagent codify it as a separate `x/cover` package firewall (parallel to lexicon_meta tests), or embed it in Cover Pool Factory validation? PO recommendation: **separate firewall** — parallel to lexicon meta-tests; rejects any code path that would route Cover-Fees outside contributor-pool semantics.
|
||||
8. **MAB use-of-proceeds lock enforcement.** Per REQ-054, MAB proceeds are locked to reserve build-out. Does the ciagent codify this as tagged streaming with auto-Still on misuse detection, or as a Watcher-quorum-only release? PO recommendation: **tagged streaming + Watcher-witnessed release** (defense in depth).
|
||||
|
||||
The ciagent logs assumptions if these are unanswered at autonomy=full (decision_confidence_threshold 0.6, clarify_budget 10).
|
||||
|
||||
## 9. Changelog
|
||||
|
||||
| Spec-v | Date | Commit (docs(spec):) | What changed | REQs affected |
|
||||
|--------|------|----------------------|--------------|---------------|
|
||||
| v1 | (template date) | docs(spec): initial spec | Pre-filled REQ-001..REQ-021 locked-vision baseline; §1, §2, §5, §6 placeholders | REQ-001..REQ-021 |
|
||||
| v2 | 2026-08-18 | docs(spec): v0.7 fraternal groups + risk mitigations + infrastructure economics, no subsidies, anchor no-voice | Comprehensive revision — added REQ-046..REQ-097 (52 new REQs); folded SPEC-001 v0.2 §4 functional requirements and §12.2 architect recommendations as protocol REQs; eliminated Root-Pool subsidy layer; added Anchor no-Voice clause and Sovereign Anchors as separate SPEC; Pier-Routed Legal Wrapper downgraded to OPTIONAL; three new constraints added to §5; §1 expanded with fraternal scope; §7 split into v0.7 + v0.8 plan; 8 open questions logged | REQ-046..REQ-097 (new); §1, §5, §7, §8 |
|
||||
| **v3** | **2026-08-18** | **docs(spec): net new only — trim restated sections** | **Trim: removed restated REQ-001..REQ-021 baseline table (locked, in force), locked Principles restatement, locked Lexicon restatement, pre-filled project invariants from §5; §2 reduced to vision document reference only; §6 reduced to locked-pointer; §7 reduced to v0.7 + v0.8 milestone plan + new out-of-scope additions. Keep: REQ-046..REQ-097 unchanged; new §5 constraints unchanged; 8 new §8 questions unchanged.** | **No new REQs; net-new-only diff against spec-v2** |
|
||||
|
||||
---
|
||||
|
||||
## Rules (PO ↔ ciagent contract)
|
||||
Locked per spec-v2 / template. Not restated.
|
||||
|
||||
## Commit convention
|
||||
Locked per spec-v2 / template. Not restated.
|
||||
|
||||
---
|
||||
|
||||
End of `oy-spec` v3 — net-new-only diff against spec-v2. Awaiting ciagent acknowledgment + P0 generation of new `oy-state` per regeneration rule in §7.
|
||||
@@ -0,0 +1,176 @@
|
||||
<!--
|
||||
OpenYield Spec Template
|
||||
=======================
|
||||
Copy this file to `.ciagent/oy/oy-spec` (no .md extension) when starting a
|
||||
fresh milestone cycle. Then fill every `<!-- TODO -->` placeholder and commit
|
||||
with a `docs(spec):` Conventional Commit (see the commit convention block at
|
||||
the bottom of this file).
|
||||
|
||||
What is pre-filled (do NOT edit unless the locked baseline itself changes):
|
||||
- §3 Principles [locked] (Six Principles)
|
||||
- §5 Constraints (project invariants)
|
||||
- §6 Lexicon [locked] (banned terms + replacements)
|
||||
- §4 REQ-001..REQ-021 (locked-vision baseline rows — acceptance criteria
|
||||
still need filling on first use)
|
||||
- Rules + Commit convention blocks
|
||||
|
||||
What the PO must fill per milestone:
|
||||
- §1 Objective
|
||||
- §2 Vision source (locked sections list)
|
||||
- §4 acceptance criteria for every REQ the milestone implements
|
||||
- §4 new REQ-NNN rows for milestone-specific additions (continuing the ID
|
||||
sequence from the last shipped REQ — check `oy-state` §2 for the current
|
||||
max REQ-ID)
|
||||
- §7 Milestone intent (current shipped, next target, out-of-scope)
|
||||
- §8 Open questions for the ciagent
|
||||
- §9 Changelog (one row per spec revision)
|
||||
-->
|
||||
|
||||
# OpenYield Spec — spec-vN
|
||||
Owner: <product owner>
|
||||
Status: draft
|
||||
Ingested as: oy-spec
|
||||
|
||||
> This is the **only** document the product owner (PO) sends to the ciagent for
|
||||
> implementation. The ciagent consumes it to regenerate PROJECT.md,
|
||||
> REQUIREMENTS.md, and ARCHITECTURE.md. Nothing else is read from upstream.
|
||||
>
|
||||
> In return the ciagent maintains **one** sibling file — `oy-state` — that tells
|
||||
> the PO what exists, what's locked, what's deferred, and what drift exists
|
||||
> between this spec and the shipped code. Read `oy-state` before editing
|
||||
> `oy-spec`; it prevents re-proposing shipped or explicitly-deferred REQs.
|
||||
>
|
||||
> `oy-spec` and `oy-state` are the only two docs that cross the PO<->ciagent
|
||||
> boundary. All other `.ciagent/oy/*.md` files are ciagent-internal working
|
||||
> memory — do not edit them.
|
||||
|
||||
## 1. Objective
|
||||
<!-- TODO: <=3 sentences — what the mesh is and who it serves -->
|
||||
|
||||
## 2. Vision source
|
||||
- Document: Vision v3.0 (22 sections)
|
||||
- Locked commitments (non-amendable sections):
|
||||
<!-- TODO: list section numbers that are non-amendable -->
|
||||
|
||||
## 3. Principles [locked]
|
||||
1. Real value
|
||||
2. Sustainability
|
||||
3. Mission-lock
|
||||
4. Openness
|
||||
5. Ownership
|
||||
6. Self-service
|
||||
<!-- Do not edit — the ciagent enforces these as REQ-001. -->
|
||||
|
||||
## 4. Requirements
|
||||
<!-- Each row: ID | Title | Vision § | Priority | Locked? | Acceptance criteria
|
||||
REQ-001..REQ-021 are the locked-vision baseline — fill their acceptance
|
||||
criteria on first use, do not change their Locked? column without an
|
||||
explicit §9 changelog override.
|
||||
Add new milestone-specific REQs below REQ-021, continuing the ID sequence
|
||||
from the last shipped REQ (check `oy-state` §2 for the current max). -->
|
||||
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|
||||
|----|-------|----------|---------|---------|---------------------|
|
||||
| REQ-001 | Enforce Six Principles | §2 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-002 | Fee ceiling 0.1% / floor 0.01% / 1-Grain min | §18 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-003 | Bloom from real production only (Root Basket) | §6 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-004 | 9 Watchers, 6-of-9 quorum | §7 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-005 | Four Freeholder signals | §9.1 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-006 | Standing anti-gaming formula | §9.2 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-007 | FCFS processing | §15 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-008 | OY Chain (Layer 1) | §7 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-009 | Satellite chains (Layer 2) | §7 | Medium | no | <!-- TODO: criteria --> |
|
||||
| REQ-010 | Exit layer (Layer 3) | §7 | Medium | no | <!-- TODO: criteria --> |
|
||||
| REQ-011 | Three Councils with Mission Lock | §19 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-012 | Lexicon compliance | §3 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-013 | Bread unit with scale | §4 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-014 | Three pools of storage | §5 | High | yes | <!-- TODO: criteria --> |
|
||||
| REQ-015 | Window primitive | §10 | High | no | <!-- TODO: criteria --> |
|
||||
| REQ-016 | Nine Stand types | §11 | Medium | yes | <!-- TODO: criteria --> |
|
||||
| REQ-017 | Guilds with free Hand-Passes | §12 | Medium | yes | <!-- TODO: criteria --> |
|
||||
| REQ-018 | Four-tier Partner Spectrum | §13 | Medium | no | <!-- TODO: criteria --> |
|
||||
| REQ-019 | Six bearers via Unified Bearer Layer | §14 | Medium | yes | <!-- TODO: criteria --> |
|
||||
| REQ-020 | Six Pacts | §16 | Medium | no | <!-- TODO: criteria --> |
|
||||
| REQ-021 | Mesh Bond Market with 8% cap | §17 | Medium | yes | <!-- TODO: criteria --> |
|
||||
| <!-- TODO: REQ-022 --> | <!-- TODO: title --> | <!-- TODO: vision § --> | <!-- TODO: priority --> | <!-- TODO: locked? --> | <!-- TODO: criteria --> |
|
||||
| <!-- TODO: REQ-023 --> | <!-- TODO: title --> | <!-- TODO: vision § --> | <!-- TODO: priority --> | <!-- TODO: locked? --> | <!-- TODO: criteria --> |
|
||||
|
||||
## 5. Constraints
|
||||
- 14 modular components, 6 cross-component interfaces
|
||||
- Mission Lock non-amendable
|
||||
- Lexicon firewall: banned terms = bank, deposit, interest, yield, currency, dollar/euro, account, savings, depositor
|
||||
- Skeleton-first until mainnet gate (D-020 pattern)
|
||||
- Zero Go deps except GRILL-approved runtime exceptions
|
||||
- Coverage >=80% on shipped packages
|
||||
- Multi-project mode active; project slug = `oy`
|
||||
|
||||
## 6. Lexicon [locked]
|
||||
- Banned: bank, deposit, interest, yield, currency, dollar, euro, account, savings, depositor
|
||||
- Required replacements: account -> Reach, deposit -> receive-asset, interest -> coupon, yield -> bloom, currency -> asset
|
||||
|
||||
## 7. Milestone intent
|
||||
- Current shipped: <!-- TODO: last shipped milestone tag, e.g. v0.6 (v0.5.6) — COMPLETE -->
|
||||
- Next: <!-- TODO: next milestone target — one paragraph + the REQ-IDs it draws from -->
|
||||
- Out-of-scope this milestone:
|
||||
<!-- TODO: list — cross-reference `oy-state` §4 (deferred) to avoid re-proposing -->
|
||||
|
||||
## 8. Open questions for the ciagent
|
||||
<!-- TODO: bulleted; the ciagent logs assumptions if unanswered at autonomy=full -->
|
||||
|
||||
## 9. Changelog
|
||||
<!-- Every spec revision MUST be a `docs(spec):` commit (see commit convention
|
||||
block below). One row per revision. -->
|
||||
| Spec-v | Date | Commit (docs(spec):) | What changed | REQs affected |
|
||||
|--------|------|----------------------|--------------|---------------|
|
||||
| v1 | <!-- TODO: date --> | <!-- TODO: docs(spec): initial spec --> | <!-- TODO: summary --> | <!-- TODO: REQ-IDs --> |
|
||||
|
||||
---
|
||||
|
||||
## Rules (PO <-> ciagent contract)
|
||||
|
||||
- **One document each way.** No slides, sidecar notes, or direct edits to
|
||||
generated docs. If you want to change product intent, edit `oy-spec`; if you
|
||||
want to know what the ciagent did, read `oy-state`.
|
||||
- **Every REQ the ciagent implements must appear in §4 with acceptance
|
||||
criteria.** Vague criteria -> vague implementation.
|
||||
- **Mark a REQ `[locked]`** only if a future spec revision must not change it
|
||||
without an explicit override line in §9. Locked REQs map to const firewalls
|
||||
the ciagent defends with regression tests (listed in `oy-state` §3).
|
||||
- **The ciagent regenerates `oy-state` at every milestone ship AND at P0 of the
|
||||
next milestone if `oy-spec` changed since the last `oy-state`.** `oy-state`
|
||||
is authoritative for "what exists"; PROJECT.md is internal working memory.
|
||||
- **Before proposing a new REQ in §4, grep `oy-state` §2 (coverage) and §4
|
||||
(deferred).** Re-proposing an existing or explicitly-deferred REQ is a no-op
|
||||
and will be flagged as drift in the next `oy-state` §5.
|
||||
- **When §4 or §6 change,** the ciagent regenerates PROJECT/REQUIREMENTS and
|
||||
flags drift. When §3/§5 only change, no regeneration is needed.
|
||||
|
||||
## Commit convention (mandatory for `oy-spec`)
|
||||
|
||||
- Every commit that modifies `oy-spec` MUST use a Conventional Commit message:
|
||||
|
||||
```
|
||||
docs(spec): <imperative summary <=72 chars>
|
||||
|
||||
<optional body: what changed in §4/§6 and why; >=1 line per REQ affected>
|
||||
```
|
||||
|
||||
- Examples:
|
||||
```
|
||||
docs(spec): add REQ-046 governance spam deposit (§4)
|
||||
|
||||
Opens REQ-046 per oy-state §4 deferred item "governance spam deposit".
|
||||
Acceptance: proposal deposit >= 1 Loaf, slashable on spam.
|
||||
```
|
||||
```
|
||||
docs(spec): lock REQ-002 fee ceiling — overrideable only via §9
|
||||
|
||||
REQ-002 fee covenant locked per vision §18; any future change requires an
|
||||
explicit §9 changelog override line.
|
||||
```
|
||||
|
||||
- The ciagent will **REJECT** any `oy-spec` commit whose subject does not match
|
||||
`docs(spec): ...`. This makes spec changes grep-able and ties each
|
||||
implementation milestone back to the spec revision that authorized it (via
|
||||
the §9 Changelog row referenced in the commit body).
|
||||
- **No squash merges, `fixup!`, or empty commits** for `oy-spec`. Every edit
|
||||
is a real `docs(spec):` commit on the default branch.
|
||||
@@ -0,0 +1,245 @@
|
||||
# OpenYield State — state-v2
|
||||
Generated: 2026-08-19
|
||||
Milestone: v0.7 (Fraternal Groups Foundation) — IN PROGRESS (P0 SPECIFY)
|
||||
Tag: v0.6.x patch line (P0 → v0.6.0)
|
||||
Ingested as: oy-state
|
||||
|
||||
> This is the **only** document the ciagent sends to the product owner (PO)
|
||||
> to communicate current project state. The PO reads it before editing
|
||||
> `oy-spec`. `oy-spec` and `oy-state` are the only two docs that cross the
|
||||
> PO<->ciagent boundary; all other `.ciagent/oy/*.md` files are ciagent-internal
|
||||
> working memory.
|
||||
>
|
||||
> Regeneration rule: the ciagent regenerates this file at every milestone ship
|
||||
> AND at P0 of the next milestone if `oy-spec` changed since the last `oy-state`.
|
||||
> `oy-state` is authoritative for "what exists"; PROJECT.md is internal working
|
||||
> memory.
|
||||
|
||||
## 1. Current position
|
||||
- Last shipped: v0.6 (Nomad Web UI) — COMPLETE — tag v0.5.6 (release_id 776)
|
||||
- Next queued: v0.7 — Fraternal Groups Foundation (REQ-046..REQ-066, 21 REQs)
|
||||
- Release forge: Gitea (git.cloudinit.dev/oy/openyield), release_id 776
|
||||
- Autonomy: full (decision_confidence_threshold 0.6, clarify_budget 10)
|
||||
- Open `oy-spec` §8 questions answered by ciagent: 8 (D-074..D-081 — all PO recommendations accepted as binding; see §7)
|
||||
- v0.7 tag line: v0.6.x (previous minor's patch line per branch-strategy). P0 → v0.6.0; P1..P5 → v0.6.1..v0.6.5; P6 final → v0.6.6 (= v0.7 milestone release). No separate minor tag (D-008).
|
||||
- v0.7 milestone type: feature (REQ-046..REQ-066 are feat-class primitives + a small number of test/docs adjuncts)
|
||||
- v0.7 scope ruling (D-081): §7 is authoritative — v0.7 ships REQ-046..REQ-066 only; Cluster A–E + Infrastructure Economics (REQ-067..REQ-097) all defer to v0.8.
|
||||
|
||||
### Milestone history (compact)
|
||||
| Milestone | Type | Tag | Status |
|
||||
|-----------|------|-----|--------|
|
||||
| v0.1 Foundation Init | feat | v0.0.9 | COMPLETE |
|
||||
| v0.2 The Mesh | feat | v0.1.5 | COMPLETE |
|
||||
| v0.3 Bearers & Docs | feat | v0.2.6 | COMPLETE |
|
||||
| v0.4 Refinement | NFR | v0.3.4 | COMPLETE |
|
||||
| v0.5 Bearers Runtime | feat | v0.4.8 | COMPLETE |
|
||||
| v0.6 Nomad Web UI | feat | v0.5.6 | COMPLETE |
|
||||
| v0.7 Fraternal Groups Foundation | feat | v0.6.x (in progress) | IN PROGRESS — P0 SPECIFY |
|
||||
|
||||
## 2. Requirement coverage
|
||||
<!-- Mirror of oy-spec §4. Status: Not started | Skeleton | Runtime | Complete | Deferred | Rejected -->
|
||||
|
||||
### Shipped baseline (REQ-001..REQ-045) — per state-v1, unchanged this regeneration
|
||||
| REQ | Title | Status | Shipped in | Module(s) | Locked? |
|
||||
|-----|-------|--------|-----------|----------|---------|
|
||||
| REQ-001 | Enforce Six Principles | Skeleton | v0.1 | x/* | yes |
|
||||
| REQ-002 | Fee ceiling 0.1% / floor 0.01% / 1-Grain min | Complete | v0.1 | x/feecovenant | yes |
|
||||
| REQ-003 | Bloom from real production only (Root Basket) | Complete | v0.2 | x/bread, x/bloom | yes |
|
||||
| REQ-004 | 9 Watchers, 6-of-9 quorum | Complete | v0.1 | x/watcher | yes |
|
||||
| REQ-005 | Four Freeholder signals | Complete | v0.2 | x/standing | yes |
|
||||
| REQ-006 | Standing anti-gaming formula | Complete | v0.2 | x/standing | yes |
|
||||
| REQ-007 | FCFS processing | Complete | v0.1 | x/bearers | yes |
|
||||
| REQ-008 | OY Chain (Layer 1) | Skeleton | v0.1 | x/* (no app.go yet) | yes |
|
||||
| REQ-009 | Satellite chains (Layer 2) | Skeleton | v0.2 | x/satellite | no |
|
||||
| REQ-010 | Exit layer (Layer 3) | Runtime | v0.5 | x/exit, x/bridge | no |
|
||||
| REQ-011 | Three Councils with Mission Lock | Runtime | v0.5 | x/council | yes |
|
||||
| REQ-012 | Lexicon compliance | Complete | v0.1 (x/), v0.3 (docs/), v0.6 (web/) | lexicon_meta_test, lexicon_meta_docs, lexicon_meta_web | yes |
|
||||
| REQ-013 | Bread unit with scale | Complete | v0.1 | x/bread | yes |
|
||||
| REQ-014 | Three pools of storage | Complete | v0.1 | x/stash, x/vault, x/rootpool | yes |
|
||||
| REQ-015 | Window primitive | Runtime | v0.2 (skeleton), v0.6 (UI) | x/window | no |
|
||||
| REQ-016 | Nine Stand types | Skeleton | v0.2 | x/stand | yes |
|
||||
| REQ-017 | Guilds with free Hand-Passes | Skeleton | v0.2 | x/guild | yes |
|
||||
| REQ-018 | Four-tier Partner Spectrum | Runtime | v0.5 | x/partner | no |
|
||||
| REQ-019 | Six bearers via Unified Bearer Layer | Runtime | v0.5 | x/bearers | yes |
|
||||
| REQ-020 | Six Pacts | Skeleton | v0.2 | x/pact | no |
|
||||
| REQ-021 | Mesh Bond Market with 8% cap | Runtime | v0.5 | x/bond | yes |
|
||||
| REQ-022..REQ-045 | (shipped v0.3..v0.6 — see state-v1 §2 for full table) | Complete | v0.3..v0.6 | various | mixed |
|
||||
|
||||
### v0.7 — Fraternal Groups Foundation (REQ-046..REQ-066) — Not started
|
||||
| REQ | Title | Vision § | Priority | Locked? | Status | Target phase |
|
||||
|-----|-------|----------|---------|---------|--------|--------------|
|
||||
| REQ-046 | Cover Pool Factory runtime | §16 | High | no | Not started | v0.7/P1 |
|
||||
| REQ-047 | Cover Pool reserve target floor 1.5× annual contributions | §16 | High | yes | Not started | v0.7/P1 |
|
||||
| REQ-048 | Cover Pool reserve target ceiling 2.5× (governance-tunable) | §16 | High | no | Not started | v0.7/P2 |
|
||||
| REQ-049 | Cover Pool Standing gate minimums | §16, §9.3 | High | yes | Not started | v0.7/P1 |
|
||||
| REQ-050 | Cover-Fee tagging at protocol layer | §16 | High | yes | Not started | v0.7/P1 |
|
||||
| REQ-051 | Guild Charter + Common Bond requirement | §12 | Medium | yes | Not started | v0.7/P3 |
|
||||
| REQ-052 | Cover-Charter (SoB, dispute path, gate, holding period) | §16 | High | yes | Not started | v0.7/P2 |
|
||||
| REQ-053 | Chapter Federation (Parent/Chapter, secession terms, liens) | §12 | High | no | Not started | v0.7/P3 |
|
||||
| REQ-054 | Mutual Aid Bond (issuance ceiling 1×–3×, coupons in Cover Calls) | §17 | High | yes | Not started | v0.7/P4 |
|
||||
| REQ-055 | Cover Claims Voucher role + bond + slashing | §9.4, §15 | High | no | Not started | v0.7/P4 |
|
||||
| REQ-056 | Anti-Capture Bill of Rights v0.2 | §8.2 [3] | High | yes | Not started | v0.7/P5 |
|
||||
| REQ-057 | Household simplified — no formal Council, one-tap exit | §11 | Low | no | Not started | v0.7/P3 |
|
||||
| REQ-058 | Confederation Voice — one-Stand-one-Vote, internal bundle | §11 | Medium | yes | Not started | v0.7/P3 |
|
||||
| REQ-059 | Stand→Pier-customer boundary — escalation rule ($100k per D-074) | §11, §13 | Medium | no | Not started | v0.7/P5 |
|
||||
| REQ-060 | Shadow vouch partial credit — 50% weight in Freeholder signal | §9.1 | Medium | yes | Not started | v0.7/P4 |
|
||||
| REQ-061 | Disclaimer cadence — per charter signing | §11 | Low | yes | Not started | v0.7/P3 |
|
||||
| REQ-062 | Pool governance hybrid (Host + 3 elected + Watcher observer) | §16 | High | yes | Not started | v0.7/P2 |
|
||||
| REQ-063 | MAB holder — surplus seniority only, no Voice at dissolution | §17 | Medium | yes | Not started | v0.7/P4 |
|
||||
| REQ-064 | Secession cooling — 21d Cover-active / 14d non-Cover | §4.6 [3] | Medium | yes | Not started | v0.7/P5 |
|
||||
| REQ-065 | Cover Pool category staging — Phase 2/3/4 | §16 | High | yes | Not started | v0.7/P2 |
|
||||
| REQ-066 | Pier selection — Guild Council chooses, reversible, Pier Selection Index | §13 | Medium | no | Not started | v0.7/P5 |
|
||||
|
||||
### v0.8+ — Risk Mitigations + Infrastructure Economics (REQ-067..REQ-097) — Deferred to v0.8
|
||||
> All 31 REQs deferred to v0.8 per D-081 (§7 authoritative). Listed here for visibility; not started this milestone.
|
||||
| REQ | Title | Status | Target milestone |
|
||||
|-----|-------|--------|-----------------|
|
||||
| REQ-067..REQ-072 | Cluster A — Trust-minimization attacks | Deferred | v0.8 |
|
||||
| REQ-073..REQ-076 | Cluster B — Economic structural | Deferred | v0.8 |
|
||||
| REQ-077..REQ-081 | Cluster C — Capture & centralization | Deferred | v0.8 |
|
||||
| REQ-082..REQ-086 | Cluster D — Identity & reputation | Deferred | v0.8 |
|
||||
| REQ-087..REQ-091 | Cluster E — Adoption & organic | Deferred | v0.8 |
|
||||
| REQ-092..REQ-097 | Infrastructure Economics | Deferred | v0.8 |
|
||||
|
||||
## 3. Locked constants (const firewall)
|
||||
<!-- Amending any row requires an explicit override line in oy-spec §9. -->
|
||||
| Const | Value | Module | Why locked |
|
||||
|-------|-------|--------|-----------|
|
||||
| MissionLockAmendable | false | x/council | vision §19 — non-amendable |
|
||||
| CouponCapBps | 800 (8%) | x/bond | vision §17, D-028 |
|
||||
| CouponFloorBps | 0 (0%) | x/bond | vision §17, D-028 |
|
||||
| LendingCouponCapBps | 800 | x/hub | D-028 mirror (REQ-030 cross-const test) |
|
||||
| LendingCouponFloorBps | 0 | x/hub | D-028 mirror (REQ-030 cross-const test) |
|
||||
| HandPassFeeBps | 0 | x/guild | vision §12, D-025 |
|
||||
| FeeCeilingBps | 10 (0.1%) | x/feecovenant | vision §18, REQ-002 |
|
||||
| FeeFloorBps | 1 (0.01%) | x/feecovenant | vision §18, REQ-002 |
|
||||
| SignalKindCount | 4 | x/standing | AUDIT §193 P1-2 (defensible; expansion deferred to v0.7+ governance) |
|
||||
| BearerTypeCount | 6 | x/bearers | vision §14, REQ-019 |
|
||||
| BridgeStatusCount | 4 | x/bridge | D-036 |
|
||||
| ExitStatusCount | 5 | x/exit | D-036 |
|
||||
| PartnerTierCount | 4 | x/partner | vision §13, REQ-018 |
|
||||
| StandTypeCount | 9 | x/stand | vision §11, REQ-016 |
|
||||
| PactTypeCount | 6 | x/pact | vision §16, REQ-020 |
|
||||
| CouncilKindCount | 3 | x/council | vision §19, REQ-011 |
|
||||
| WatcherQuorum | 6-of-9 | x/watcher | vision §7, REQ-004 |
|
||||
| WatcherVetoQuorum | 6 (param-tunable [2,9]) | x/council | D-065 |
|
||||
| MaturityThresholdDays | 90 | x/stash | vision §9.1, REQ-005 |
|
||||
| GrainsPerBread | 10000 | x/bread | vision §4, REQ-013 |
|
||||
| TargetBloomRateBasisPoints | 450 (4.5%) | x/bloom | vision §6 |
|
||||
| AnchorCredentialStatusCount | 4 | x/partner | v0.5 addition (additive) |
|
||||
| OYSATLink.SurveillanceResistant | true | x/bearers | vision §14, locked |
|
||||
| ServiceKindCount | 4 | x/services | D-040 |
|
||||
| HubServiceCount | 3 | x/hub | D-039 |
|
||||
|
||||
### v0.7 planned const additions (GRILL-ratified D-086..D-090)
|
||||
| Const | Value | Module | REQ | Why locked |
|
||||
|-------|-------|--------|-----|-----------|
|
||||
| CoverReserveFloorAnnualContribX | 1.5 | x/cover (NEW) | REQ-047 (locked) | vision §16 — 1.5× annual contributions floor, mission-locked |
|
||||
| CoverReserveCeilingAnnualContribX | 2.5 | x/cover (NEW) | REQ-048 (not locked — governance-tunable within 1.5×–2.5×) | vision §16 — upper bound of bounded range |
|
||||
| CoverStandingGateTrusted | 4.0 (Trusted bucket) | x/cover (NEW) | REQ-049 (locked) | vision §16, §9.3 — Travel gate minimum (Pool MAY tighten, NEVER loosen). D-090(3): enforced at BOTH launch handler AND Params-amendment ValidateBasic. |
|
||||
| CoverStandingGatePreferred | 4.5 (Preferred bucket) | x/cover (NEW) | REQ-049 (locked) | vision §16, §9.3 — Health-MCS gate minimum. D-090(3): dual check. |
|
||||
| MABIssuanceCeilingAnnualSurplusMultiple | 3 | x/bond (extended) | REQ-054 (locked) | vision §17 — 3× annual surplus mission-locked ceiling |
|
||||
| MABCouponCapBps | 800 (reuse CouponCapBps) | x/bond | REQ-054 (locked) | coupon bounded by existing CouponCapBps (D-028) — no new const, cross-const test extends |
|
||||
| CoolingSecessionCoverActiveDays | 21 | x/guild (extended) | REQ-064 (locked) | vision §4.6 — secession cooling, secured at founding, not reducible |
|
||||
| CoolingSecessionNonCoverDays | 14 | x/guild (extended) | REQ-064 (locked) | vision §4.6 — secession cooling, secured at founding, not reducible |
|
||||
| StandPierEscalationAnnualPassVolumeCents | 10000000 ($100k in Grain-cents) | x/stand (extended) | REQ-059 (not locked) | D-074 ruling — TBD-X = $100k annual Pass volume; simtest placeholder (no USD/Grain oracle) |
|
||||
| CoverClaimsVoucherBondMultipleAvgCall | 10 | x/cover (NEW) | REQ-055 (not locked) | §9.4, §15 — bond default 10× avg Call size per Pool. D-090(2): bond = max(10× avg, MinimumVoucherBond) — cold-start fallback. |
|
||||
| AntiCaptureBillOfRightsCount | 13 | x/cover (NEW) | REQ-056 (locked) | §8.2 — 13 rights codified, non-amendable, non-waivable. D-090(1): RightID type + 13 Waivable* consts + ValidateBasic gate land in P2 (NOT P5). |
|
||||
| ShadowVouchWeightMultiplier | 0.5 | x/standing (extended) | REQ-060 (locked) | vision §9.1 — Shadow vouch 50% weight in Community Endorsement signal |
|
||||
| PierCarriesVoice | false | x/guild (extended) | REQ-053 / FR-VOICE-6 (locked, D-087) | vision §12 — Pier does NOT carry Voice; mission-locked invariant (12th const per GRILL D-087) |
|
||||
|
||||
> Note: the v0.8 const firewall extensions named in oy-spec §7 v0.8 acceptance
|
||||
> (`EyeQuorumMin=7`, `AnchorConcentrationCapBps=2000`,
|
||||
> `MABCouponMaxAnnualSurplusMultiple=3`, `BondIssuerSurplusCeilings={1×,2×,3×}`,
|
||||
> `CoolingSecessionCoverActive=21 days`, `CoolingSecessionNonCover=14 days`,
|
||||
> `CoverReserveFloorAnnualContribX=1.5`) overlap with v0.7's REQ-047/049/054/
|
||||
> 064 const additions. The v0.7 additions above land the v0.7-locked subset
|
||||
> (REQ-047/049/054/064 locked=yes); the v0.8 acceptance list is the v0.8
|
||||
> consolidated const firewall update that will add the remaining Cluster A–E
|
||||
> consts (`EyeQuorumMin`, `AnchorConcentrationCapBps`, etc.). The cooling
|
||||
> consts and CoverReserveFloor land in v0.7 because their REQs are v0.7;
|
||||
> v0.8's acceptance row re-lists them as a consolidated checkpoint, not a
|
||||
> re-introduction.
|
||||
|
||||
## 4. Deferred / out-of-scope (do NOT re-propose without §9 override)
|
||||
| Item | Deferred from | Reason | Revisit at |
|
||||
|------|--------------|--------|------------|
|
||||
| Cover Pool seniority mechanics | v0.1 Q7 | unstated math | **UNBLOCKED v0.7** — REQ-046..REQ-050 now supply the seniority/gate math; promoting to runtime this milestone |
|
||||
| SignalKind 4->5 enum expansion | v0.4 AUDIT §193 P1-2 | locked-const change; defensible at 4 | v0.8+ governance vote (not v0.7 scope) |
|
||||
| Governance spam deposit/bond | v0.5 REVIEW P1 | mainnet-readiness | v0.8+ (Cluster C, REQ-077 adjacent) |
|
||||
| CLOB per-tx front-running (batch auction) | v0.5 REVIEW P1 | mainnet-readiness | v0.8+ |
|
||||
| Real IBC light-client simtest | v0.5 REVIEW P1 | mainnet-readiness | v0.8+ (Cluster A, REQ-068 adjacent) |
|
||||
| CLOB `restingBookForBond` O(n) -> prefix-key | v0.5 REVIEW P2 | mainnet perf | v0.8+ |
|
||||
| `emitMatchEventHook` testability | v0.5 REVIEW P2 | minor | v0.8+ |
|
||||
| Live chain launch / mainnet / real IBC channels | v0.1 (D-020) | skeleton-first until mainnet gate | v0.8+ (Year 3 target) |
|
||||
| Real `oyd` daemon / `app.go` / `cmd/oyd` | v0.6 OOS | no chain runtime exists | v0.8+ (v0.7 Cover Pool "live on testnet" = simtest-grade keeper runtime, not mainnet) |
|
||||
| Real institutional Anchors onboarding | v0.5 OOS | credential lifecycle in simtest only | v0.8+ |
|
||||
| Real bearer transports (hardware/RF) | v0.5 OOS | message handlers + simtest only | v0.8+ (Year 3) |
|
||||
| Authentication / sessions / real key mgmt | v0.6 OOS | mock; Reach created by form submission | v0.8+ |
|
||||
| Persistence (in-memory mock store) | v0.6 OOS | resets on restart | v0.8+ |
|
||||
| i18n / multi-language UI | v0.3/v0.6 OOS | single-language | v0.8+ |
|
||||
| Yield Token, Travel + 11 service categories | ROADMAP Phase 4 | Maturity (Years 4-5) | Year 4+ |
|
||||
| Maya's Day integration spec | v0.1 Q1 | Mesh Experience component | Phase 2 |
|
||||
| Standing anti-gaming sub-tables | v0.1 Q2 | formula locked; sub-tables deferred | v0.8+ |
|
||||
| Pier credential routing (e-Residency, biometrics) | v0.1 Q5 | deferred | v0.8+ |
|
||||
| Experimental bond forms | v0.1 Q6 | Phase 4+ only | Year 4+ |
|
||||
| Processor share tier boundary exact volumes | v0.1 Q8 | deferred | v0.8+ |
|
||||
| Docs bread-scale.md fix (outdated vs code consts) | v0.6 P1+ | doc-drift fix, not UI feature | next docs touch |
|
||||
| **Sovereign Anchor SPEC** (`oy-sovereign-anchors`) | v0.7 §5 | infrastructure-scale, separate SPEC; experimental, not load-bearing | post-v0.7 (PO D-076) |
|
||||
| **USZ classification runtime** | v0.7 §7 | depends on Anchor pre-commitment framework (v0.8 REQ-095) | v0.8 |
|
||||
| **Cluster A–E + Infrastructure Economics (REQ-067..REQ-097)** | v0.7 §7 / D-081 | §7 authoritative — v0.7 ships REQ-046..066 only | v0.8 |
|
||||
| **Pier-Routed Legal Wrapper** | v0.7 §5 | OPTIONAL per PO; default-no-wrapper; not implemented as code | never (optional value-add) |
|
||||
| **Watcher/Voucher operating-expense compensation absolute cap ($TBD-W)** | v0.7 §8 Q6 | v0.8 REQ-096; annual 5% Bloom cap ruled (D-078), absolute cap deferred | v0.8 |
|
||||
|
||||
## 5. Drift flags (ciagent -> PO)
|
||||
<!-- Differences between oy-spec (latest) and what the ciagent has shipped. -->
|
||||
- Lexicon drift: **none**
|
||||
- Locked-const drift: **none** (v0.7 const additions are net-new, not amendments)
|
||||
- REQ-shape drift: **none** (oy-spec v3 net-new-only diff ingested; REQ-046..REQ-097 added to coverage §2; baseline REQ-001..REQ-045 unchanged)
|
||||
- Architecture drift: **planned** — v0.7 introduces a NEW module `x/cover` (Cover Pool Factory + Anti-Crowding-Out firewall + Anti-Capture Bill of Rights). The existing `x/pact` `PactCover` enum value remains as a cross-reference (G-003 by-ID-string). This mirrors the D-039 precedent (`x/hub` split out of `x/pact`'s `PactHubAPI` in v0.3). Will be ratified at GRILL (P0).
|
||||
- Spec-version drift: **none** — oy-spec v3 ingested at commit d10bf5e; this state-v2 reflects it.
|
||||
|
||||
## 6. Constraints honored (firewall status)
|
||||
- **G-003** production import firewall: GREEN (by-ID-string rule at type level; expected_keepers.go shims for keeper cross-calls). v0.7 `x/cover` will follow the same pattern — no production struct imports across `x/<module>/types`.
|
||||
- **G-006** go.mod zero-dep: CONTROLLED EXCEPTION — cosmos-sdk v0.50.8 + ibc-go v8.2.1 added in v0.5 (D-055 GRILL-approved, scoped to runtime phases; types/ packages stay dep-free). v0.7 `x/cover` keeper will use the same SDK runtime substrate; no new Go deps expected.
|
||||
- **G-028** go.mod diff baseline (v0.6 vs v0.5.0): EMPTY. v0.7 target: EMPTY (no new Go deps; `x/cover` keeper uses existing SDK).
|
||||
- **REQ-012** lexicon firewall: GREEN — 3 meta-tests (x/, docs/, web/) all passing. v0.7 will extend to a 4th meta-test if Cover surfaces add user-facing strings (pending RESEARCH); otherwise the existing 3 suffice.
|
||||
- **Mission Lock** non-amendable: GREEN — `MissionLockAmendable=false` unchanged; `MissionLockAmendmentRejected` ProposalKind rejected at ValidateBasic (D-064). v0.7 Anti-Capture Bill (REQ-056) extends this: 13 rights non-amendable + non-waivable by any Charter.
|
||||
- **Coverage** >=80% on shipped packages: GREEN (v0.5 keepers 82.1%-92.5%; v0.6 web/store 98.1%, web/handlers 89.2%, lexicon_meta_web 100%). v0.7 target: `x/cover` + extensions >=80%.
|
||||
- **Feature purity gate** (v0.7): GREEN target — no breaking schema changes to locked-const firewall; G-003 intact; go.mod unchanged.
|
||||
- **No subsidies** (v0.7 §5 NEW): GREEN by construction — v0.7 does not introduce any Root-Pool operating-expense subsidy or transfer-payment analog. The Anti-Crowding-Out firewall (D-079, REQ-047/050) rejects any code path routing Cover-Fees outside contributor-pool semantics. Infrastructure financing is out of v0.7 scope (v0.8 REQ-092..095).
|
||||
- **Anchor no-Voice** (v0.7 §5 NEW): GREEN by construction — v0.7 does not grant Voice to any Anchor. The Cover Pool Council (REQ-062) = Pool Host + 3 elected Masons + Watcher observer; no Anchor seat. MAB holders (REQ-063) have NO Voice. Sovereign Anchors are out of v0.7 scope (experimental per §5).
|
||||
|
||||
## 7. Open PO decisions before next milestone
|
||||
<!-- The PO should rule on these in oy-spec §8 or §7 before v0.7 P0. -->
|
||||
|
||||
### Resolved this regeneration (D-074..D-081 — PO recommendations accepted as binding at full autonomy)
|
||||
| ID | §8 Q | Decision | Rationale | Confidence | Affects |
|
||||
|----|------|----------|-----------|------------|--------|
|
||||
| D-074 | Q1 (TBD-X) | **$100k annual Pass volume** for Stand→Pier-customer escalation | PO rec accepted; soft upgrade not ban | 0.85 | REQ-059 (v0.7/P5) |
|
||||
| D-075 | Q2 (TBD-Z) | **<10 Holders/km² AND strategic value ≥ mission score, OR sovereign request, OR Mesh Council supermajority** | PO rec accepted; formula locked for v0.8 USZ | 0.80 | REQ-095 (v0.8) |
|
||||
| D-076 | Q3 (Sovereign Anchor SPEC) | **Separate SPEC `oy-sovereign-anchors`**; experimental, not load-bearing v0.7 | PO rec accepted; infrastructure-scale ≠ legal-wrapper-scale | 0.85 | §5 constraint (v0.7) |
|
||||
| D-077 | Q5 (Standing gate timing) | **Factory runtime** — gates are protocol-layer | PO rec accepted; gates bind at x/cover Factory, not first live Pool | 0.88 | REQ-049 (v0.7/P1) |
|
||||
| D-078 | Q6 (Watcher/Voucher cap) | **Annual cap = 5% of Root-Pool Bloom**; absolute $TBD-W deferred to v0.8 | PO rec accepted; 5% Bloom ruled now, absolute cap later | 0.82 | REQ-096 (v0.8) |
|
||||
| D-079 | Q7 (Anti-Crowding-Out firewall) | **Separate `x/cover/firewall` package + `lexicon_meta_cover`-style meta-test** (defense in depth) | PO rec "separate firewall" accepted; runtime subpackage rejects code paths + meta-test rejects doc drift | 0.84 | REQ-047/050 (v0.7/P1) |
|
||||
| D-080 | Q8 (MAB use-of-proceeds) | **Tagged streaming + Watcher-witnessed release** (defense in depth) | PO rec accepted; tagged streaming auto-Stills on misuse, Watcher witnesses release | 0.85 | REQ-054 (v0.7/P4) |
|
||||
| D-081 | Q4 (Risk mitigation sequencing) | **§7 authoritative** — v0.7 ships REQ-046..066 only; Cluster A+B+C are v0.8 | PO rec overridden by §7 acceptance text; §7 is the milestone contract | 0.90 | v0.7 scope (all REQ-046..066) |
|
||||
|
||||
### Remaining open (post-v0.7 — for v0.8 P0)
|
||||
1. **$TBD-W absolute Watcher/Voucher cap** — deferred to v0.8 REQ-096 (D-078 partial ruling).
|
||||
2. **Sovereign Anchor SPEC scope** — `oy-sovereign-anchors` to be authored by PO before v0.8 P0 (D-076).
|
||||
3. **v0.8 Cluster A–E sequencing within v0.8** — which of REQ-067..REQ-097 ship in v0.8 P1..PN? PO should pick a subset or rule "all 31 in v0.8".
|
||||
4. **Pen-test third party** — v0.7 §7 acceptance requires "pen-test ≥1 independent third party"; at full autonomy with no external third party available, the ciagent will run a self-administered adversarial review (ci-griller persona) and log this as an assumption unless the PO rules otherwise before P6.
|
||||
5. **`oyd` daemon** — still no `app.go`/`cmd/oyd`; v0.7 Cover Pool "live on testnet" = simtest-grade keeper runtime. PO should decide whether v0.8 starts the daemon or continues simtest-only.
|
||||
6. **SignalKind 4->5 expansion** — still deferred to v0.8+ governance vote (not v0.7 scope).
|
||||
|
||||
## 8. Build/test status
|
||||
- `go build ./...`: GREEN (baseline confirmed 2026-08-19 on main @ d10bf5e)
|
||||
- `go test ./...`: GREEN (all packages; v0.5 keepers + v0.6 web + lexicon meta-tests all passing)
|
||||
- Coverage: all shipped keeper packages >=80%; web packages >=89%
|
||||
- Lexicon meta-tests: 3/3 GREEN (x/, docs/, web/)
|
||||
- Last green commit: d10bf5e (docs(spec): v3 net-new-only)
|
||||
|
||||
---
|
||||
|
||||
_`oy-state` is regenerated by the ciagent. Do not edit by hand._
|
||||
Reference in New Issue
Block a user