openyield/.ciagent/oy/PROJECT.md

Project: OpenYield (oy)

Objective

OpenYield (OY) is a durable, anti-greed, jurisdiction-light financial layer — a public-good mesh owned by its Holders, run by its Guilds, defended by code, and sustained by the real yield of the real economy.

Vision Source

• Vision v3.0 (22 sections, locked commitments, covenant preserved)
• Primary Architecture Document v0.1 (14 modular components, 6 cross-component interfaces)

Requirements

• REQ-001: Mesh must enforce the Six Principles (real value, sustainability, mission-lock, openness, ownership, self-service). [§2]
• REQ-002: Fee ceiling 0.1% / floor 0.01% / 1-Grain internal minimum, mission-locked, enforced by smart contract. [§18]
• REQ-003: Bloom must originate only from real yield (Root Basket: Treasuries ~35%, IG corporate ~25%, tokenized gold ~20%, Bitcoin ~10%, other RWAs ~10%). [§6]
• REQ-004: 9 Watchers, 6-of-9 quorum, daily attestations, 100,000 Bread bond each. [§7]
• REQ-005: Four Freeholder signals locked (90d Stash, 4.5★+ in 3 cats, Capital, Vouch). [§9.1]
• REQ-006: Standing anti-gaming formula locked (Bayesian + time-decay + diversity + voucher-weighted − slashes). [§9.2]
• REQ-007: FCFS processing (not fee-auctioned), geographic proximity wins. [§15]
• REQ-008: OY Chain (Layer 1) — canonical state for Root-Pool, Root Basket, Forge/Fold, Pacts, Bloom, Voucher bonds, Watcher attestations, Partner registry. [§7]
• REQ-009: Satellite chains (Layer 2) — wrapped Bread, Pass-Act propagation on Polygon/Base/Arbitrum/Optimism/Solana. [§7]
• REQ-010: Exit layer (Layer 3) — DEX swaps, bridges, off-mesh services (Holder-initiated). [§7]
• REQ-011: Three Councils (Mesh, Guild, Stand) with multi-source Voice. Mission Lock cannot be amended. [§19]
• REQ-012: Lexicon compliance — never use: bank, deposit, interest, yield, currency, dollar/euro, account, savings, depositor. [§3]
• REQ-013: Bread unit with scale: Grain → Crumb → Bread → Loaf → Batch → Cake → Bakery → Granary → Mill → Harvest → Earth. [§4]
• REQ-014: Three pools of storage: Stash (Holder), Vault (Stand), Root-Pool (treasury). [§5]
• REQ-015: Window primitive — scope, duration, rate-limit, audit log, revoke. [§10]
• REQ-016: Nine Stand types (Household, Crew, Entity, Co-op, Circle, Trust, Foundation, Confederation, Shadow). [§11]
• REQ-017: Guilds with Hand-Passes at 0% protocol fee. [§12]
• REQ-018: Four-tier Partner Spectrum (Op, Master Op, Pier, Anchor). [§13]
• REQ-019: Six bearers (Internet, OY-LR, OY-BLE, OY-WiFi-Direct, OY-SAT, OY-QR) via Unified Bearer Layer. [§14]
• REQ-020: Six Pacts (Pause, Ground, Stance, Cover, Stand Registry, Hub API). [§16]
• REQ-021: Mesh Bond Market with 8% upper coupon cap, 0% floor. [§17]

Constraints

• 14 modular component docs govern subsystem development. [Architecture §3]
• Six cross-component interfaces (Standing, Forge/Fold, Mirror, Window, Fee Covenant, Voice/Council) are the integration contract. [Architecture §4]
• Hardest blocker chain: OY Chain → Bread/Root Basket → Storage → Identity/Standing → {Window, Pacts, Orgs, Partners, Governance}. [Architecture §5.2]
• Phase 0 must ship before any execution phases.
• Multi-project mode active; project slug = oy.

Out of Scope (Phase 0)

• Maya's Day integration spec (deferred to Mesh Experience component) [Architecture Q1]
• Full sub-tables for Standing anti-gaming (formula locked; sub-tables deferred) [Architecture Q2]
• Full risk mitigations for 19 risk items (listed, distributed across components) [Architecture Q3]
• Detailed phase deliverables beyond high-level roadmap [Architecture Q4]
• Pier credential routing details (e-Residency, biometric IDs) [Architecture Q5]
• Experimental bond forms (Phase 4+ only) [Architecture Q6]
• Cover Pool seniority mechanics and over-pledging math [Architecture Q7]
• Processor share tier boundary exact volumes [Architecture Q8]

Phase 0 Deliverables

• .ciagent/oy/PROJECT.md — this file
• .ciagent/oy/ARCHITECTURE.md — initial architecture index
• .ciagent/oy/ROADMAP.md — phase breakdown
• .ciagent/oy/REQUIREMENTS.md — REQ-IDs
• Persona assessment
• Phase plans

Key Decisions

• D-002: OY Chain = Cosmos SDK + CosmWasm (confidence: 1.0, confirmed)
• D-008: Milestone stays v0.1 until MVP; MVP ships as v0.1.0
• D-009: Rebased history to fix v1.0 → v0.1 in ---ci--- blocks

Milestone

v0.3 — Bearers & Documentation (active milestone; feature type; tags run on the v0.2.x patch line)

v0.3 Scope (Bearers skeleton + Docs site — ROADMAP Phase 3 partial, plus a docs deliverable)

This milestone bundles two parallel work-streams under one feature milestone:

(A) Bearers skeleton (D-020 pattern continued) — implements the v0.1 PROJECT.md out-of-scope items now promoted to v0.3 (ROADMAP Phase 3 "The Bearers" subset), as skeleton + tests (Go types + keeper stubs + invariant tests; no live chain):

• REQ-010 Exit layer (Layer 3) — DEX swaps, bridges, off-mesh services (§7). Promoted from Skeleton to a fuller skeleton: x/exit (exit-route types) + x/bridge (L2↔L1 bridge types). Live runtime deferred to v0.4.
• Bearers expansion — OY-SAT (satellite) + OY-QR bearer transport types, extending x/bearers (D-029 pattern). Hardware integration deferred.
• Anchors — first institutional Partner tier (x/partner extension: Anchor credential types). REQ-018 promoted from Skeleton → fuller skeleton.
• Hub API — B2B backbone: custody, lending primitive, compliance types (x/hub). Full B2B suite deferred to v0.4.
• Services — Care / SIM / Vault / Mail service types (x/services). Live services deferred.
• Bond market depth — Growth Bonds + secondary-market types, extending x/bond (REQ-021 promoted from Skeleton → fuller skeleton). Full market depth deferred.

(B) Documentation deliverable — README.md + docs site in docs/ for nomads and freeholders:

• Repo-root README.md (lexicon-clean project overview).
• MkDocs Material site (mkdocs.yml + docs/), organized by audience:
  • docs/nomads/ — Reach path, Stash, bearers, Maps/Pay, six Pacts, standing basics.
  • docs/freeholders/ — Four Freeholder signals, Bayesian Standing, Stands/Guilds, Councils/Voice, Bonds, Partner spectrum.
  • docs/shared/ — Six Principles, Bread Scale, Storage pools, Watchers/Mirror, Lexicon glossary, Vision overview.
  • docs/reference/ — architecture index, component map.
• REQ-012 firewall extension — extend the lexicon meta-test to scan README.md + docs/**/*.md (new sibling lexicon_meta_docs_test.go), so the docs site is durably lexicon-clean. This is a feat/test phase.

Milestone Type

Feature (Bearers phases are feat; docs phases are docs/test). Phase 0 → v0.2.0; execution phases v0.2.1..v0.2.5; final phase patch v0.2.6 IS the milestone release. No separate minor tag.

Out of Scope (v0.3)

• Live chain launch / real IBC channels / real bearer transports (D-020 pattern continues)
• DEX integration runtime, full Hub API B2B suite runtime (types only in v0.3)
• Yield Token, Travel + 11 service categories (ROADMAP Phase 4)
• i18n / versioning in MkDocs (single-language v0.3)
• Cover Pool seniority mechanics (still deferred per PROJECT.md Q7)

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)

Clarification Decisions (Phase 0 — CLARIFY, autonomy=full)

Auto-decided defaults logged per clarify workflow Step 4 (full autonomy → accept defaults, log decisions).

ID	Decision	Rationale	Confidence	Alternatives
D-020	v0.2 ships a skeleton + tests layer (Go types + keeper stubs + unit tests) for each Mesh-era component, matching v0.1's pre-MVP approach; no live chain launch in v0.2	v0.1 established the skeleton-first pattern; ROADMAP "Year 2" targets are aspirational, not v0.2 deliverables. Consistency with v0.1 reduces risk.	0.85	[full Go implementations, live Cosmos chain launch]
D-021	REQ-009 L2 satellites: skeleton = IBC light-client + transfer-channel types for ONE L2 (Polygon) as representative; remaining 4 chains stubbed as enum placeholders	Full 5-chain IBC rollout is Phase 3 scope; v0.2 proves the pattern with one chain.	0.80	[all 5 chains in v0.2, defer all L2 to v0.3]
D-022	REQ-011 Three Councils: skeleton = 3 module stubs (mesh/guild/stand council keeper + Voice tally types), Mission Lock enforced as a const; no live governance in v0.2	Governance activation needs Holders (Year 2 target); v0.2 lands the typed scaffold + Mission Lock invariant tests.	0.82	[full governance runtime, defer to v0.4]
D-023	REQ-015 Window: full primitive — scope/duration/rate-limit/audit-log/revoke types + keeper + lifecycle tests. This is a leaf component with no upstream blocker, so it can be more complete.	Window is self-contained and required by Pacts/Orgs/Partners; a fuller implementation unblocks v0.3.	0.75	[skeleton-only Window]
D-024	REQ-016 Nine Stands: enum (9 named types) + Stand keeper + membership-set types; no Stand-internal economics in v0.2	Stand economics (revenue distribution, bonding) is Phase 3+.	0.80	[full Stand economics]
D-025	REQ-017 Guilds: Guild keeper + Hand-Pass type at 0% protocol fee (locked const) + issuance tests; no Guild-internal task queue	Guild task management is operational, not protocol-level.	0.78	[full Guild ops runtime]
D-026	REQ-018 Partner Spectrum: 4-tier enum (Op/MasterOp/Pier/Anchor) + Partner registry keeper + credential-ref types; Pier credential routing (e-Residency, biometrics) deferred per PROJECT.md out-of-scope Q5	Credential routing was explicitly deferred in v0.1 PROJECT.md.	0.85	[include credential routing now]
D-027	REQ-020 Six Pacts: one x/pact module with a PactType enum (Pause/Ground/Stance/Cover/Stand-Registry/Hub-API) + six per-type execute-entry structs (per A-207), NOT six micro-modules. Each execute-entry has invariant tests; Cover Pool seniority deferred per Q7	Cover Pool seniority is explicitly out-of-scope (PROJECT.md Q7); one module with enum satisfies "separate execute entries" without 6 dirs	0.80	[full Cover Pool mechanics, six separate modules]
D-028	REQ-021 Mesh Bonds: Bond market keeper + 8% cap / 0% floor consts + issuance tests; full secondary-market depth deferred to Phase 3	ROADMAP Phase 2 says "First Mesh Bonds" — first issuance, not full market.	0.82	[full bond market in v0.2]
D-029	Bearers OY-LR + Beacon v1: skeleton bearer-interface types + OY-LR (long-range) + Beacon transport stubs; no hardware integration	Hardware/RF integration is not a v0.2 software deliverable.	0.85	[real bearer runtime, defer all bearers]
D-030	Forex Engine v1: Forex pair type + rate-oracle interface + stub keeper; no live oracle integration	Live oracle integration depends on external partners (Piers), Phase 3.	0.80	[live oracle integration]
D-031	Phase ordering follows ARCHITECTURE.md blocker chain: P1 Orgs+Window foundation → P2 Pacts+Partners → P3 Councils+Forex → P4 Bonds+Bearers+L2. The final phase (P5) is review/ship.	Respects dependency graph; vertical slices keep each phase independently shippable.	0.80	[different wave ordering]
D-032	Lexicon enforced project-wide; all new modules must pass the lexicon assertion test (no banned terms). Non-negotiable. Note (G-002): lexicon assertion tests are NEW in v0.2 — v0.1 is lexicon-clean in practice but has NO lexicon test firewall. v0.2 introduces the firewall (scaffolded in P1 per G-004, extended in P5).	REQ-012 is All phases.	1.00	[—]
D-033	Test coverage target: ≥80% on new keeper/type packages. v0.1 baseline = 53 tests across 11 test files (corrected per G-001; not 48). Add lexicon assertion to each new module's test file.	Consistency with v0.1 quality bar (53 tests verified); lexicon drift is the highest-severity regression.	0.85	[lower coverage bar]

v0.3 Clarification Decisions (Phase 0 — CLARIFY, autonomy=full)

Auto-decided defaults logged per clarify workflow Step 4 (full autonomy → accept defaults, log decisions).

ID	Decision	Rationale	Confidence	Alternatives
D-034	v0.3 milestone bundles Bearers skeleton (D-020 pattern) + docs deliverable under one feature milestone, rather than two separate NFR+feature milestones. Bearers phases are feat; docs phases are docs/test. Tags run on v0.2.x.	User request (--ideate) is docs-only but ROADMAP Phase 3 (Bearers) is the next queued feature work; bundling keeps the milestone cadence and avoids an NFR-only milestone that would not advance the protocol. Feature type because Bearers phases are feat.	0.82	[separate v0.3 docs NFR + v0.4 Bearers feature; or docs as patches on v0.2 line]
D-035	Bearers skeleton continues the D-020 skeleton+tests pattern (Go types + keeper stubs + invariant tests; no live chain, no real IBC channels, no real bearer transports). Live runtime for any Bearers component deferred to v0.4+.	v0.1/v0.2 both shipped skeleton-first; v0.3 stays consistent. Live runtime needs Watchers + Root Basket backing (Year 3 target).	0.85	[fuller keeper implementations in v0.3]
D-036	REQ-010 Exit layer: skeleton = x/exit (ExitRoute, DEXSwap types) + x/bridge (L2↔L1 bridge types, BridgeStatus enum). No live DEX integration. REQ-010 promoted from v0.1 Skeleton → v0.3 fuller skeleton (two packages instead of one).	Exit runtime needs Anchor partners + L2 bridges; v0.3 lands the typed shape.	0.80	[single x/exit package, defer all exit to v0.4]
D-037	REQ-022 Bearers OY-SAT + OY-QR: extend x/bearers/types with OYSAT + OYQR bearer transport types (BearerTransport interface already in v0.2). No hardware/RF runtime. D-029 pattern continued.	Hardware integration is not a software deliverable; v0.3 completes the 6-bearer type set (v0.2 had 4: Internet/OY-BLE/OY-WiFi-Direct + OY-LR/Beacon).	0.82	[real bearer runtime, defer OY-SAT/OY-QR to v0.4]
D-038	REQ-023 Anchors: extend x/partner/types with Anchor tier credential types (REQ-018 had the 4-tier enum; v0.3 adds Anchor-specific credential fields). No live institutional onboarding.	Anchors need Watchers + Hub API backing; v0.3 lands the credential shape.	0.78	[separate x/anchor module, defer Anchors to v0.4]
D-039	REQ-024 Hub API: new x/hub module — custody, lending-primitive, compliance type stubs (HubService enum + per-service structs). No live B2B runtime. Full Hub API B2B suite deferred to v0.4.	Hub API needs Anchors + Watchers; v0.3 lands the typed scaffold.	0.80	[full Hub API runtime in v0.3]
D-040	REQ-025 Services: new x/services module — Care/SIM/Vault/Mail service type stubs (ServiceKind enum + per-service structs). No live services.	Services are operational, not protocol-level; v0.3 lands the typed shape.	0.78	[full services runtime in v0.3]
D-041	REQ-026 Bond market depth: extend x/bond/types with GrowthBond type + secondary-market order types. 8% cap / 0% floor consts (D-028) unchanged. Full secondary-market matching deferred to v0.4.	v0.2 shipped first issuance; v0.3 adds depth types without a live matching engine.	0.80	[full bond market in v0.3]
D-042	Docs deliverable (REQ-027): repo-root README.md + MkDocs Material site (mkdocs.yml + docs/). mkdocs.yml at repo root; docs/ organized by audience: docs/nomads/, docs/freeholders/, docs/shared/, docs/reference/. Build-only Python dep (mkdocs + material); go.mod stays zero-dep.	User chose MkDocs Material + audience organization. MkDocs is Markdown-native, lightest toolchain; build-only dep does not affect Go modules (G-006).	0.85	[Hugo, Docusaurus, plain Markdown no generator]
D-043	REQ-028 lexicon firewall extension: new sibling test lexicon_meta_docs_test.go (package lexicon_meta_docs) scanning README.md + docs/**/*.md for the 10 banned terms, using the same lexicon.FindBannedTerm + word-boundary regex. Self-exclusion + fragment pattern preserved. .ciagent/ files are NOT scanned (they are firewall meta-files, not user-facing docs).	REQ-012 is All phases and docs are user-facing; the firewall must cover docs to be durable. Extending the existing meta-test (not modifying it) preserves v0.2 coverage.	0.88	[single combined meta-test scanning both x/ and docs/]
D-044	Phase ordering: P1 docs foundation + firewall extension → P2 nomads docs → P3 freeholders docs → P4 Bearers skeleton I (exit/bridge/bearers/partner) → P5 Bearers skeleton II (hub/services/bond) → P6 final review/ship. Firewall lands in P1 BEFORE content (P2/P3) so docs are checked as authored.	Firewall-first ensures docs content is lexicon-clean by construction, not by retrofit. Bearers split across P4/P5 keeps each phase independently shippable (vertical slices).	0.82	[Bearers first then docs, or all docs in one phase]
D-045	Docs depth per audience: each audience section (nomads, freeholders) gets 5-8 Markdown pages covering its core REQs (nomads: Reach/Stash/bearers/Maps-Pay/Pacts/standing-basics; freeholders: 4 signals/Bayesian Standing/Stands-Guilds/Councils-Voice/Bonds/Partner spectrum). docs/shared/ gets 5-6 concept pages. docs/reference/ gets architecture index + component map. Total ~20-25 pages.	Enough depth to be a real docs site, not a placeholder; bounded to keep P1-P3 phases shippable.	0.80	[deeper (40+ pages), shallower (10 pages)]
D-046	No docs-site publishing CI in v0.3 — mkdocs.yml is buildable locally (mkdocs serve / mkdocs build); CI publishing to GitHub Pages/Gitea Pages is deferred to v0.4. v0.3 ships the source + a build invocation in the README.	Publishing CI needs deployment secrets + a hosting target; v0.3 lands the content.	0.82	[include publishing CI in v0.3]

Ideation outcome (Phase 0 — IDEATE stage, autonomy=full)

IDEATE stage ratified 8 ideas (IDEATE-01..IDEATE-08) at full autonomy, mapped to REQ-010/REQ-022..REQ-028. Docs deliverable (IDEATE-01/02) is the user's --ideate request; Bearers ideas (IDEATE-03..08) are the ROADMAP Phase 3 subset. Three ideation tiers ran (mechanical, backend-enriched, cross-project); mechanical tier found no lessons:/compound: tags in v0.1/v0.2 history (convention unused) and v0.2 closed clean (9/9 REQs, 303 tests, ≥95.9% coverage). Defaults accepted per full autonomy; traceability recorded in .ciagent/oy/REQUIREMENTS.md (IDEATE Traceability section).