diff --git a/.ciagent/CHECKPOINT.json b/.ciagent/CHECKPOINT.json index 70ef151..401801d 100644 --- a/.ciagent/CHECKPOINT.json +++ b/.ciagent/CHECKPOINT.json @@ -1,9 +1,11 @@ { - "phase": 9, - "stage": "complete", - "milestone": "v0.1", - "phase_role": "final", + "phase": 0, + "stage": "plan", + "milestone": "v0.2", + "milestone_type": "feature", + "tag_base": "v0.1.x", + "phase_role": "pre_execution", + "project": "oy", "attempts": 0, - "updated_at": "2026-08-17T00:00:00Z", - "milestone_complete": true + "updated_at": "2026-08-17T21:00:00Z" } \ No newline at end of file diff --git a/.ciagent/config.json b/.ciagent/config.json index f0a0a58..e237fc8 100644 --- a/.ciagent/config.json +++ b/.ciagent/config.json @@ -6,6 +6,9 @@ } ], "active_project": "oy", + "milestone": "v0.2", + "milestone_type": "feature", + "tag_base": "v0.1.x", "autonomy": { "level": "full", "escalation_hooks": ["deploy", "delete_data", "merge_to_main"], diff --git a/.ciagent/oy/GRILL.md b/.ciagent/oy/GRILL.md new file mode 100644 index 0000000..b7ddf8f --- /dev/null +++ b/.ciagent/oy/GRILL.md @@ -0,0 +1,184 @@ +# Grill Review: OpenYield (oy) — v0.2 (The Mesh) Phase 0 + +> **Reviewer**: CIAgent adversarial grill (red-team, full autonomy) +> **Date**: 2026-08-17 +> **Target**: Phase 0 artifacts (PROJECT.md, REQUIREMENTS.md, ARCHITECTURE.md, RESEARCH.md, PERSONAS.md, PLANS.md, config.json) + v0.1 codebase baseline +> **Milestone**: v0.2 — The Mesh +> **Autonomy**: full (decision_confidence_threshold = 0.60) +> **Mode**: multi-project (slug `oy`) + +--- + +## Methodology + +Each of nine axes was scored by gathering concrete evidence (commit hash, file:line, REQ-ID, D-decision, A-assumption). Missing or contradictory evidence is itself a finding. Forcing questions were answered from the artifacts; where confidence ≥ 0.60 a binding verdict was reached. No escalations were required — all axes resolved at ≥ 0.60 confidence after binding fixes are applied. + +### Evidence baseline (verified against the actual repo, not the docs) + +- v0.1 codebase: **15 modules** under `x/` (confirmed via glob `x/**/types/types.go`). +- `go.mod`: `module github.com/oy/openyield`, `go 1.22`, **zero dependencies** (confirmed). +- Test functions: **53** (counted via `grep -rh "^func Test" x/`). PROJECT.md D-033 says "48-test baseline"; RESEARCH.md §2 says "53-test baseline pattern". **Inconsistent — both refer to v0.1.** +- Test files: **11** `*_test.go` (not 15 — modules `identity`, `processing`, `rootpool`, `vault` have **no test files**). +- **Zero lexicon assertion tests** exist in v0.1 (`grep -rli lexicon x/` returns empty). D-032 claims lexicon is "carried from v0.1" — but v0.1 never had a lexicon test. The claim is aspirational, not historical. +- **Zero `genesis.go` files** exist; all `ValidateGenesis` are no-ops in `types.go` (e.g. `feecovenant/types/types.go:122` returns `nil` unconditionally). +- **No project-wide lexicon meta-test** exists. +- `x/bearers/types/types_test.go` already imports `x/processing/types` cross-module (line 7) — an existing precedent for cross-module test imports, but it is a *test* import, not a production import cycle. +- Current lexicon cleanliness: `grep -rni "bank\|account" x/ --include="*.go"` returns **zero hits** — v0.1 is lexicon-clean in practice, but the firewall is nonexistent. + +These baseline facts drive several binding decisions below. The plan's narrative ("matching v0.1's 48-test baseline", "lexicon carried from v0.1") is **partly fictional** — v0.1 has no lexicon test and the test count is misstated in two places. This does not block v0.2; it means the lexicon firewall is *new* work in v0.2, not inherited work. + +--- + +## Per-Axis Verdicts + +### Axis 1 — Feasibility (skeleton + tests, zero deps) — **PASS** (confidence 0.85) + +The v0.2 scope (Go types + keeper stubs + unit tests, no live chain) is genuinely achievable with zero external deps. v0.1 proved the pattern: 15 modules compile under `go 1.22` with only `encoding/json`. RESEARCH.md §4 is explicit and correct that pulling `cosmos-sdk`/`ibc-go` would force a 1000+ module tree and break the fast test loop. The ICS-20 packet shape is self-contained Go structs (A-215), the Forex oracle is a Go interface (no impl), and bearers are pure types (no LoRa/BLE libs). No axis-1 risk reaches the escalation threshold. + +The one caveat: the Window "fuller" implementation (D-023) is the most ambitious skeleton and rate-limit semantics are unstated (A-206, conf 0.65). But the plan correctly scopes the skeleton to a simple counter (`actionsConsumed` vs `maxActions`), which is trivially feasible. Confidence holds. + +### Axis 2 — Scope (over/under, D-020..D-033 defensibility) — **CONDITIONAL** (confidence 0.72) + +D-020..D-033 are individually defensible and well-reasoned. The skeleton-first choice (D-020, conf 0.85), one-chain IBC representative (D-021), Mission Lock as const (D-022), Window-fuller (D-023), and the deferred items (Cover seniority Q7, Pier credential routing Q5, Solana IBC) all correctly defer operational/Phase-3 concerns. The scope is *not* over-scoped for a skeleton milestone. + +However: (a) D-033's claim of "matching v0.1's 48-test baseline" is factually wrong — v0.1 has 53 tests and no lexicon tests (see baseline). (b) D-032's claim that lexicon is "carried from v0.1" is false — v0.1 has no lexicon test. These are documentation defects, not scope defects, but they mislead future phases about what is inherited vs. new. **Binding fix G-002** corrects the narrative; the scope itself is sound. + +### Axis 3 — Cost / Effort (30 tasks / 5 phases) — **PASS** (confidence 0.80) + +30 tasks across 5 phases for 10 new/extended packages is proportionate. Each package gets a types task + a test task + (for 3 of them) a genesis task, plus 5 cross-cutting lead-developer ship tasks. No phase exceeds 8 tasks; the largest (P4) has 8 tasks for 3 packages which is reasonable. There is **no bloat**: there are no "research", "spike", or "documentation" tasks masquerading as execution; every task produces a concrete `.go` file or a verifiable gate. The 5 lead-developer verification tasks (one per phase) are the correct overhead for vertical-slice shippability. Reject the "too many tasks" hypothesis. + +Minor: P5 has 4 tasks for pure audit/ship, which is light but appropriate (no new code). No binding change. + +### Axis 4 — Architecture (module layout, blocker chain, import cycles) — **PASS** (confidence 0.82) + +The 9-new + 1-extended layout maps cleanly to the blocker chain in ARCHITECTURE.md §5.2. D-031's phase ordering (P1 Orgs+Window → P2 Pacts+Partners → P3 Councils+Forex → P4 Bonds+Bearers+L2 → P5 ship) respects the dependency graph: Window is a leaf (P1) so P2/P3/P4 reference it by `WindowRef` id-string; Stand (P1) blocks Pact StandRegistry (P2), Council Stand-Council (P3), and Bond issuer (P4); Guild (P1) blocks Council Guild-Council (P3). A-203 (by-ID-string refs) is the correct cycle-avoidance strategy and is consistently applied in RESEARCH.md §3's interface diagram. + +One concern: RESEARCH.md §3 says `x/window` "may be imported by Pacts/Partners/Orgs if needed (but skeleton keeps it by-ref too)" — this hedge could permit a future struct import. The plan's task specs (P2-01-01, P2-02-01) correctly use `window-id-ref` strings, so the skeleton is safe. **Binding fix G-003** makes the by-ref rule a hard invariant test so the hedge cannot silently become an import cycle. + +### Axis 5 — Risk (15 assumptions, hidden traps) — **CONDITIONAL** (confidence 0.70) + +The 15 assumptions (A-201..A-215) are mostly sound and well-scored. The highest-confidence (A-201 dep-free 0.95, A-202 one-module-per-component 0.90, A-209 bearers-extend 0.90, A-215 no-deps-vendored 0.90, A-210 lexicon-coupon 1.00) are correct. The lower-confidence assumptions are correctly *flagged* for v0.3 revisit (A-206 rate-limit 0.65, A-213 Shadow Stand 0.60, A-214 spread cap 0.70). + +Three hidden traps: +1. **Lexicon firewall is new, not inherited** (see baseline). The plan assumes v0.1 had a lexicon test; it did not. The P5 meta-test (P5-01-01) is therefore load-bearing for the *entire* project's lexicon integrity, not just v0.2. This raises its criticality — **binding fix G-004** moves the lexicon meta-test earlier (into P1) as a scaffolding test that fails-empty initially, so drift is caught from the first phase, not at P5 when 10 packages already exist. +2. **`x/bearers/types/types_test.go` already cross-imports `x/processing/types`** (line 7). This is a *test* import, not a production import cycle, but it means the bearers test package is already coupled. When P4 extends `x/bearers`, the existing test must stay green (P4-02-02 acknowledges this). No binding change — the plan already flags the regression risk — but it is a latent coupling the grill records. +3. **A-207 (one `x/pact` module with PactType enum, conf 0.80) contradicts D-027's wording** ("separate keeper modules"). RESEARCH.md §1.7 explicitly reconciles this ("one module with a PactType enum satisfies 'separate execute entries' without 6 dirs"), but the contradiction between the D-decision text and the chosen implementation is a documentation smell. **Binding fix G-005** clarifies D-027's intent. Confidence holds; no escalation. + +### Axis 6 — Requirement Coverage (all v0.2 REQs, gaps, double-counting) — **PASS** (confidence 0.84) + +Cross-referencing RESEARCH.md §6 (Cross-Reference Summary) against PLANS.md per-phase REQ coverage and REQUIREMENTS.md: + +| REQ | Component | Module | Phase | Depth | Covered? | +|-----|-----------|--------|-------|-------|----------| +| REQ-009 | L2 IBC | x/satellite | P4 | Skeleton (Polygon rep) D-021 | ✅ P4-03-01/02 | +| REQ-011 | Councils | x/council | P3 | Skeleton + Mission Lock D-022 | ✅ P3-01-01/02/03 | +| REQ-015 | Window | x/window | P1 | Fuller D-023 | ✅ P1-01-01/02/03 | +| REQ-016 | 9 Stands | x/stand | P1 | Skeleton D-024 | ✅ P1-02-01/02/03 | +| REQ-017 | Guilds | x/guild | P1 | Skeleton D-025 | ✅ P1-03-01/02 | +| REQ-018 | Partners | x/partner | P2 | Skeleton D-026 | ✅ P2-02-01/02 | +| REQ-020 | 6 Pacts | x/pact | P2 | Skeleton D-027 | ✅ P2-01-01/02 | +| REQ-021 | Bonds | x/bond | P4 | Skeleton D-028 | ✅ P4-01-01/02/03 | +| Bearers | OY-LR+Beacon | x/bearers (ext) | P4 | Stubs D-029 | ✅ P4-02-01/02 | +| Forex | Forex v1 | x/forex | P3 | Stub D-030 | ✅ P3-02-01/02 | +| REQ-012 | Lexicon | (all) | all | D-032 | ✅ per-module + P5 meta | + +Every v0.2 REQ maps to at least one types task + one test task. No REQ is double-counted across phases. REQ-012 (lexicon) is correctly cross-cutting. No gaps. The coverage is complete and non-overlapping. The only caveat (G-004) is *when* the lexicon meta-test lands, not *whether* it covers REQ-012. + +### Axis 7 — Persona Assignment (territory globs, conflicts) — **CONDITIONAL** (confidence 0.74) + +Persona→task assignments are coherent with territory globs: +- backend-engineer (`x/**/types/**`, `x/**/keeper/**`, `x/**/module.go`, `go.mod`) → P2-01-01, P2-02-01, P4-01-01 (pact/partner/bond types). ✅ +- cosmos-engineer (`x/{satellite,council,window,stand,guild,partner,pact,bond,forex,bearers}/**`, `go.mod`) → P1-01-01, P1-02-01, P1-03-01, P3-01-01, P3-02-01, P4-02-01, P4-03-01. ✅ +- data-engineer (`x/**/types/genesis*.go`, `x/**/genesis*.go`) → P1-01-03, P1-02-03, P3-01-03, P4-01-03. ✅ +- security-engineer (`x/**/types/**_test.go`, `x/**/keeper/**_test.go`, `x/**/genesis_test.go`) → all `*_test.go` tasks. ✅ +- lead-developer (`**`) → all wave-3 ship tasks. ✅ + +**Territory conflicts (warn mode, non-blocking but recorded):** +1. `go.mod` is claimed by **both backend-engineer and cosmos-engineer** (and referenced in 5 persona entries). Since v0.2 adds **zero** deps (A-201), `go.mod` should not change in v0.2. **Binding fix G-006**: no persona touches `go.mod` in v0.2; if a dep is needed, it is an escalation (would violate A-201). +2. `x/partner/**`, `x/pact/**`, `x/bond/**` are claimed by **both cosmos-engineer and backend-engineer** (cosmos-engineer's explicit list; backend-engineer's `x/**/types/**` glob). The plan assigns P2-01-01 (pact) and P2-02-01 (partner) and P4-01-01 (bond) to **backend-engineer**, but cosmos-engineer's territory list includes these same paths. This is a genuine overlap. Since territory enforcement is `warn` (config.json), it does not block, but it is ambiguous ownership. **Binding fix G-007** clarifies: cosmos-engineer owns the *Cosmos-convention-shaped* modules (window, stand, guild, council, satellite, forex, bearers-ext); backend-engineer owns the *non-Cosmos-mirroring* modules (pact, partner, bond). This matches the actual task assignments and removes the glob overlap. +3. security-engineer's `x/**/genesis_test.go` territory overlaps data-engineer's `x/**/genesis*.go` for the test file. The plan assigns genesis *test* logic to data-engineer's genesis tasks (e.g. P1-01-03 says "audit-log ordering test green"). Ambiguous who writes `genesis_test.go`. **Binding fix G-008**: genesis *schema* (genesis.go) = data-engineer; genesis *test assertions* (`*_test.go`) = security-engineer. The plan's task verbiage already implies this; G-008 makes it explicit. + +No conflict is severe enough to block at warn mode. Confidence holds after fixes. + +### Axis 8 — Testability (must-haves verifiable, invariants concrete) — **PASS** (confidence 0.83) + +Every must-have in the plan has a concrete verification: +- Locked-const tests are concrete: 9 Stands (P1-02-02), 4 Partner tiers (P2-02-02), 6 Pacts (P2-01-02), 3 Councils (P3-01-02), Mission Lock `== false` (P3-01-02), Bond cap 800 / floor 0 + clamp invariant (P4-01-02), Guild fee 0 (P1-03-02), 5 L2 chains (P4-03-02), ICS-20 packet field names (P4-03-02). Each is a single-const-change-breaks-a-test firewall. ✅ +- Invariant tests are concrete: Window lifecycle Open→Active→Revoked→Expired, revoke-after-expire no-op, double-revoke idempotent-or-error (P1-01-02); bond clamp below→floor / above→cap / in-range→unchanged (P4-01-02); Mission Lock non-amendable (P3-01-02). ✅ +- Lexicon assertions: per-module (10 files) + P5 meta-test. ✅ (with G-004 moving meta-test earlier) +- Coverage: ≥80% per package, table-driven on every exported const/struct/method (D-033). Achievable for low-cyclomatic-complexity skeletons. ✅ + +One gap: P5-01-01's lexicon meta-test verification says "a deliberately-injected banned term in any new file fails the meta-test (verified by a temporary spike)". A "temporary spike" is not a durable test. **Binding fix G-009**: the meta-test must include a *self-test* — a table of synthetic strings (one per banned term) asserted to be detected, so the meta-test is durably verified without manual spikes. Confidence holds. + +### Axis 9 — Phase Ordering & Shippability (patches, v0.1.5 milestone) — **PASS** (confidence 0.81) + +Each phase is independently shippable as a patch on the `v0.1.x` line: +- P1 → `v0.1.1` (window, stand, guild): ships 3 foundation modules; `go test ./...` green; no upstream blocker. ✅ +- P2 → `v0.1.2` (pact, partner): ships 2 modules referencing P1 by-id-string; blocked-by P1 types only. ✅ +- P3 → `v0.1.3` (council, forex): ships 2 modules; council blocked-by P1 stand+guild (by-id); forex independent. ✅ +- P4 → `v0.1.4` (bond, bearers-ext, satellite): ships 3 packages; bond blocked-by P1 stand; bearers/satellite independent; v0.1 baseline regression-gated. ✅ +- P5 → `v0.1.5` (audit + ship): final phase patch IS the milestone release per D-008/D-020. ROADMAP.md Phase 2 checkbox updated. ✅ + +The tag arithmetic is correct: P0 → `v0.1.0` (already shipped per ROADMAP "MVP deferred"), P1..P4 → `v0.1.1..v0.1.4`, P5 → `v0.1.5` = v0.2 milestone. No separate minor tag (D-008). The blocker chain is honored: all cross-phase hard blockers (P1-01-01, P1-02-01, P1-03-01) are in P1 Wave 1, so P2/P3/P4 Wave 1 can start once P1 types land (the plan's "soft ordering for branch hygiene" note is correct — types only depend on listed hard blockers). + +One observation: ROADMAP.md still shows v0.1 phases as `v0.0.0..v0.0.9` (lines 4-13) and says "MVP release (v0.1.0) deferred". PROJECT.md says v0.1 was "released as v0.0.9 per run.md patch-line model" (line 90). The v0.1.x tag base for v0.2 (config.json `tag_base: v0.1.x`, PLANS.md line 7) is internally consistent but the ROADMAP's v0.0.x history is a separate patch line. This is a documentation reconciliation item, not a blocker. **Binding fix G-010**: P5-01-03 (REQ-coverage audit) must also reconcile ROADMAP.md's v0.0.x → v0.1.x tag-line note so the milestone release (`v0.1.5`) is not confused with the v0.0.x pre-MVP line. + +--- + +## Binding Decisions + +These are **binding** — the orchestrator MUST apply them before P1 begins. Numbered G-001..G-010. + +| ID | Decision | Rationale | Confidence | Affects | +|----|----------|-----------|------------|---------| +| **G-001** | Correct the v0.1 baseline test-count claim. PROJECT.md D-033 says "48-test baseline"; RESEARCH.md §2 says "53-test baseline pattern". Actual count is **53** `func Test*` across 11 files. Standardize on "53 tests across 11 test files (v0.1 baseline)". | Both docs cite v0.1 test counts and disagree with each other; the actual count (verified `grep -rh "^func Test" x/ \| wc -l` = 53) is the source of truth. Future phases must not cite a phantom 48. | 0.95 | PROJECT.md D-033, RESEARCH.md §2 | +| **G-002** | Correct the lexicon-inheritance narrative. D-032 says lexicon is "carried from v0.1"; D-033 says "matching v0.1's 48-test baseline" re lexicon. **v0.1 has zero lexicon tests** (verified: `grep -rli lexicon x/` empty). State explicitly: "Lexicon assertion tests are NEW in v0.2; v0.1 is lexicon-clean in practice but has no test firewall. v0.2 introduces the firewall." | The current narrative implies inherited work that does not exist, understating v0.2's new-work scope and the criticality of the P5 meta-test. | 0.92 | PROJECT.md D-032/D-033, RESEARCH.md §2 | +| **G-003** | Add a hard invariant test in P1-01-02 (Window test file) asserting that no v0.2 production (non-test) `.go` file under `x/` imports another `x//types` package by struct — i.e. enforce A-203 (by-ID-string refs) as a *tested* invariant, not just a convention. Use `go/ast` or `go/parser` to scan imports, OR a simpler package-import grep test. | RESEARCH.md §3 hedges that Window "may be imported by Pacts/Partners/Orgs if needed". A hedge in a design doc can silently become an import cycle. Make the rule a test that fails on violation. | 0.78 | P1-01-02, RESEARCH.md §3 | +| **G-004** | Introduce the project-wide lexicon meta-test scaffolding in **P1 Wave 3** (new task P1-04-02, lead-developer), not P5. The P1 version scans `x/**/*.go` for the 9 banned terms and passes (v0.1 is clean). It fails-empty initially for the 3 new P1 packages only if drift occurs. P5-01-01 then *extends* the already-existing meta-test to cover all 10 packages rather than creating it from scratch at audit time. | Per G-002, the lexicon firewall is new in v0.2. Creating it only at P5 means drift in P1-P4 is undetected until audit, when 10 packages already exist and remediation is expensive. A P1 scaffolding meta-test catches drift from the first phase. This is the single most material fix. | 0.88 | PLANS.md P1, P5-01-01 | +| **G-005** | Clarify D-027 wording: "six Pacts as **one `x/pact` module** with a `PactType` enum + six per-type execute-entry structs (A-207), NOT six micro-modules." Update the D-027 decision text in PROJECT.md to remove the "separate keeper modules" ambiguity that contradicts A-207. | D-027 says "separate keeper modules"; A-207 and RESEARCH §1.7 say one module. The contradiction is a documentation smell that could cause a future agent to spawn 6 dirs. | 0.85 | PROJECT.md D-027 | +| **G-006** | No persona may modify `go.mod` in v0.2. v0.2 adds zero external dependencies (A-201, conf 0.95). Any `go.mod` change in P1-P5 is an immediate **escalation** (would violate D-020/A-201). Remove `go.mod` from active persona territories for v0.2, or add a constraint: "go.mod is read-only in v0.2; any change triggers escalation." | `go.mod` is claimed by both backend-engineer and cosmos-engineer (5 mentions). Since it must not change, the overlap is moot but ambiguous. Making it explicitly read-only removes the ambiguity and protects the zero-dep invariant. | 0.90 | PERSONAS.md, config.json | +| **G-007** | Disambiguate `x/pact`, `x/partner`, `x/bond` ownership. **backend-engineer** owns these three (non-Cosmos-mirroring modules: pact = custom commitment types, partner = custom registry, bond = custom clamp). **cosmos-engineer** owns `x/window`, `x/stand`, `x/guild`, `x/council`, `x/satellite`, `x/forex`, `x/bearers` (Cosmos-convention-mirroring: x/authz, x/group, x/gov, x/ibc-transfer, x/capability shapes). Update cosmos-engineer's territory list in PERSONAS.md to remove `x/pact`, `x/partner`, `x/bond`. | Both personas' territory globs overlap on these three paths. The actual PLANS.md task assignments (P2-01-01, P2-02-01, P4-01-01 → backend-engineer) already resolve it operationally, but the globs in PERSONAS.md still conflict. Align the globs with the assignments. | 0.82 | PERSONAS.md | +| **G-008** | Genesis file ownership split: **data-engineer** owns `genesis.go` / genesis *schema* (the `GenesisState` struct, `ValidateGenesis` body). **security-engineer** owns `*_test.go` including genesis *test assertions* (`genesis_test.go` if separate, or the genesis assertions within `types_test.go`). Update PERSONAS.md so security-engineer's territory explicitly includes `x/**/genesis_test.go` and data-engineer's explicitly excludes `*_test.go`. | data-engineer's `x/**/genesis*.go` glob currently matches `genesis_test.go`, overlapping security-engineer's `x/**/genesis_test.go`. Plan tasks (e.g. P1-01-03) say "test green" but the test-author persona is security-engineer. Clarify schema vs test ownership. | 0.80 | PERSONAS.md, PLANS.md genesis tasks | +| **G-009** | P5-01-01 lexicon meta-test must include a **self-test table**: a hardcoded slice of synthetic strings, one per banned term (e.g. `"bank account"`, `"interest yield"`, `"currency dollar euro"`, `"deposit savings depositor"`), asserted to each trigger the meta-test's detection. This durably verifies the meta-test detects all 9 banned terms without a manual "temporary spike". | P5-01-01's verification relies on "a temporary spike" to confirm detection — a manual step that won't be repeated. A self-test table makes the meta-test's coverage itself tested. | 0.86 | PLANS.md P5-01-01 | +| **G-010** | P5-01-03 (REQ-coverage audit) must additionally reconcile the ROADMAP.md tag-line narrative: add a one-line note that v0.1 pre-MVP shipped on the `v0.0.x` line (ROADMAP lines 4-13) and v0.2 ships on the `v0.1.x` line (config `tag_base`), so the `v0.1.5` milestone release is not confused with a v0.1.0 "MVP" tag. | ROADMAP.md says "MVP release (v0.1.0) deferred" while v0.2's P0 is `v0.1.0` per PLANS.md. The two `v0.1.0` references mean different things. A reconciliation note prevents a tag collision or confusion at ship time. | 0.75 | PLANS.md P5-01-03, ROADMAP.md | + +--- + +## Escalations + +**None.** All nine axes resolved at confidence ≥ 0.60 after the binding fixes G-001..G-010 are applied. No axis required escalation to the human. At full autonomy, the orchestrator applies the binding decisions and proceeds to P1. + +--- + +## Overall Verdict + +### **SHIP Phase 0 with binding changes** + +The v0.2 Phase 0 plan is fundamentally sound: the skeleton+tests scope is feasible, zero-dep, well-decomposed, REQ-complete, and properly ordered along the blocker chain. The plan is **not** over-scoped, **not** unfeasible, and **not** token-bloated — 30 tasks for 10 packages is proportionate. + +The binding changes are **documentation/test-firewall corrections**, not scope rework. The most material is **G-004** (move the lexicon meta-test scaffolding from P5 to P1): the plan's single biggest hidden risk is that it treats the lexicon firewall as inherited from v0.1 when it is in fact new work, and creates it only at the final audit phase. Catching drift from P1 is cheap; catching it at P5 after 10 packages exist is expensive. G-001/G-002 correct the factual errors in the baseline narrative. G-003/G-005/G-006/G-007/G-008/G-009/G-010 close smaller ambiguities (import-cycle invariant, D-027 wording, go.mod read-only, persona territory overlaps, meta-test self-coverage, tag-line reconciliation). + +None of these rise to "rethink" — the architecture, scope, and ordering are correct. Apply the 10 binding decisions and proceed to Phase P1. + +**Confidence in overall verdict: 0.83** + +--- + +## Summary Block + +``` +Per-axis verdicts: + 1. Feasibility — PASS (0.85) + 2. Scope — CONDITIONAL (0.72) → fixed by G-001, G-002 + 3. Cost/Effort — PASS (0.80) + 4. Architecture — PASS (0.82) → strengthened by G-003 + 5. Risk — CONDITIONAL (0.70) → fixed by G-004, G-005 + 6. Req Coverage — PASS (0.84) + 7. Persona Assignment — CONDITIONAL (0.74) → fixed by G-006, G-007, G-008 + 8. Testability — PASS (0.83) → strengthened by G-009 + 9. Phase/Ship — PASS (0.81) → strengthened by G-010 + +Binding decisions: 10 (G-001..G-010) +Escalations: 0 +Overall: SHIP Phase 0 with binding changes (confidence 0.83) +``` \ No newline at end of file diff --git a/.ciagent/oy/PERSONAS.md b/.ciagent/oy/PERSONAS.md index c25ce1b..98a47bd 100644 --- a/.ciagent/oy/PERSONAS.md +++ b/.ciagent/oy/PERSONAS.md @@ -2,71 +2,125 @@ active_personas: - id: backend-engineer active: true - reason: OY Chain core, CosmWasm contracts, Mirror attestations, Fee Covenant enforcement - frameworks: [Rust, CosmWasm, Cosmos SDK, CometBFT, IBC] - territory: ["crates/**", "contracts/**", "chain/**"] - constraints: [mission-lock enforcement, FCFS, no leverage/futures, no fractional reserve] + phase_specific: false + reason: Go/Cosmos module skeletons for v0.2 components — owns the non-Cosmos-mirroring modules (pact, partner, bond) per G-007. Owns the bulk of bespoke-type skeleton + tests work. + frameworks: [Go, Cosmos SDK, IBC, CosmWasm] + territory: ["x/pact/**", "x/partner/**", "x/bond/**", "x/**/types/**", "x/**/keeper/**", "x/**/module.go"] + constraints: [lexicon compliance (REQ-012), skeleton+tests pattern (D-020), ≥80% coverage on new packages (D-033), no live-chain side effects in skeleton, locked-const invariants, no fractional reserve, no leverage/futures, go.mod is read-only in v0.2 (G-006 — any change is an escalation)] - id: data-engineer active: true - reason: Storage substrate (Stash/Vault/Root-Pool), indexing, audit logs, Window data channels - frameworks: [Rust, SQLx, PostgreSQL, Subsquid] - territory: ["storage/**", "indexer/**", "migrations/**"] - constraints: [Holder data sovereignty, audit log immutability, revocable access] - - - id: frontend-engineer - active: true - reason: OY mesh app, Maps UI, Pay flows, Window management, Maya's Day integration - frameworks: [React Native, Expo, TypeScript, Reanimated] - territory: ["app/**", "components/**", "screens/**"] - constraints: [self-service default, no KYC gates, offline-first] + phase_specific: false + reason: Genesis/state schema design for new modules — Window audit log, Stand membership sets, Bond issuance state, Council Voice tally state. Shapes ValidateGenesis upgrades. Owns genesis SCHEMA only (G-008); test assertions are security-engineer's. + frameworks: [Go, encoding/json, Cosmos SDK state] + territory: ["x/**/types/genesis.go", "x/**/genesis.go"] + constraints: [append-only audit logs (Window), ID-uniqueness in ValidateGenesis, lexicon compliance, no state identity beyond Reach, does NOT own *_test.go files (G-008)] - id: lead-developer active: true - reason: Multi-component orchestration, dependency sequencing, persona coordination + phase_specific: false + reason: Multi-component orchestration across 10 new packages, dependency sequencing per D-031 blocker chain, vertical-slice integrity per phase. frameworks: [cross-cutting] territory: ["**"] - constraints: [blocked-by chain enforcement, milestone versioning] + constraints: [blocked-by chain enforcement (D-031), milestone versioning (v0.2 / tag_base v0.1.x), lexicon gate on merge, persona territory warn-mode enforcement] + + - id: cosmos-engineer + active: true + phase_specific: true + reason: v0.2 introduces IBC (satellite), governance (council), capability (window), group (stand/guild), oracle (forex) patterns that map directly to Cosmos SDK modules (x/gov, x/group, x/authz, x/feegrant, x/capability, x/ibc-transfer). Phase-specific to v0.2 execution phases where Cosmos-convention alignment matters for future wiring. + frameworks: [cosmos-sdk, ibc-go, CosmWasm, CometBFT] + territory: ["x/satellite/**", "x/council/**", "x/window/**", "x/stand/**", "x/guild/**", "x/forex/**", "x/bearers/**"] + constraints: [lexicon compliance (REQ-012), no live-chain side effects in skeleton, mirror x/gov TallyResult / x/group DecisionPolicy / x/authz Grant shapes for future wiring, zero external deps in v0.2 skeleton, by-ID-string inter-module references to avoid import cycles (G-003 tested invariant), go.mod is read-only in v0.2 (G-006)] + + - id: security-engineer + active: true + phase_specific: true + reason: v0.2 enforces Mission Lock (council), fee/bond coupon clamps (clamp invariants), 9-stand / 4-tier / 6-pact locked-const tests, and Window revoke/expire lifecycle invariants. Phase-specific to v0.2 where invariant/locked-const test density is highest. + frameworks: [Go testing, table-driven tests, invariant tests] + territory: ["x/**/types/**_test.go", "x/**/keeper/**_test.go", "x/**/genesis_test.go", "x/**/*_test.go"] + constraints: [invariant tests for all locked constants (Mission Lock non-amendable, bond 8% cap / 0% floor, fee ceiling/floor), locked-const tests for every enum count (9 stands, 4 partner tiers, 6 pacts), lexicon assertion in every new test file (D-033), ≥80% coverage on new packages, owns ALL *_test.go files including genesis_test.go (G-008)] -phase_specific: [] deactivated: + - id: frontend-engineer + reason: No UI in v0.2 (skeleton+tests only; Mesh Experience UI is v0.1-complete and v0.3+ for new UI). Deactivate to avoid persona territory noise. Reactivate in v0.3. - id: ci-security-auditor - reason: Default deactivated; activate per-phase for security audits -custom_personas: [] + reason: Default deactivated; activate in P5 (review/ship) phase for the milestone audit. Not needed during P1-P4 skeleton authoring. + - id: mesh-engineer + reason: v0.1 listed as future; still not needed in v0.2 (Bearers OY-LR + Beacon are type stubs only, no hardware/RF). Activate in v0.3 for real bearer runtime. + +custom_personas: + - id: cosmos-engineer + rationale: v0.2 components map onto specific Cosmos SDK modules (x/gov, x/group, x/authz, x/feegrant, x/capability, x/ibc-transfer). A dedicated persona ensures skeleton types mirror the eventual runtime shapes, reducing Phase 3 wiring refactor cost. Distinct from backend-engineer because it carries Cosmos-specific convention knowledge (tally shapes, decision policy, capability, ICS-20 packet shape). + - id: security-engineer + rationale: v0.2 has the highest locked-const + invariant density in the project (Mission Lock, bond cap, 6 Pact types, 9 Stand types, 4 Partner tiers, Window revoke idempotency). A dedicated persona ensures invariant tests and lexicon assertions are not an afterthought. Distinct from backend-engineer because it owns test-file territory and invariant-first design. --- -# Personas: OpenYield (oy) +# Personas: OpenYield (oy) — v0.2 (The Mesh) ## Active Roster ### backend-engineer -- **Domain**: OY Chain, CosmWasm contracts, Mirror, Fee Covenant. -- **Frameworks**: Rust, CosmWasm, Cosmos SDK, CometBFT, IBC. -- **Territory**: `crates/**`, `contracts/**`, `chain/**`. -- **Constraints**: mission-lock enforcement, FCFS, no leverage/futures, no fractional reserve. +- **Domain**: Go/Cosmos module skeletons for v0.2 — owns the **non-Cosmos-mirroring** modules (pact, partner, bond) per G-007, plus shared `types/`+`keeper/`+`module.go` authoring. +- **Frameworks**: Go, Cosmos SDK, IBC, CosmWasm. +- **Territory**: `x/pact/**`, `x/partner/**`, `x/bond/**`, `x/**/types/**`, `x/**/keeper/**`, `x/**/module.go`. (`go.mod` is read-only in v0.2 per G-006.) +- **Constraints**: lexicon compliance (REQ-012), skeleton+tests pattern (D-020), ≥80% coverage on new packages (D-033), no live-chain side effects in skeleton, locked-const invariants, no fractional reserve, no leverage/futures. ### data-engineer -- **Domain**: Storage substrate, indexing, audit logs, Window data channels. -- **Frameworks**: Rust, SQLx, PostgreSQL, Subsquid. -- **Territory**: `storage/**`, `indexer/**`, `migrations/**`. -- **Constraints**: Holder data sovereignty, audit log immutability, revocable access. - -### frontend-engineer -- **Domain**: OY mesh app, Maps UI, Pay flows, Window management. -- **Frameworks**: React Native, Expo, TypeScript, Reanimated. -- **Territory**: `app/**`, `components/**`, `screens/**`. -- **Constraints**: self-service default, no KYC gates, offline-first. +- **Domain**: Genesis/state schema design — Window audit log, Stand membership sets, Bond issuance state, Council Voice tally state. Shapes `ValidateGenesis` upgrades (v0.1's no-op → v0.2 ID-uniqueness checks). Owns genesis **schema** only (G-008); genesis **test assertions** are security-engineer's. +- **Frameworks**: Go, `encoding/json`, Cosmos SDK state. +- **Territory**: `x/**/types/genesis.go`, `x/**/genesis.go` (excludes `*_test.go` per G-008). +- **Constraints**: append-only audit logs (Window), ID-uniqueness in `ValidateGenesis`, lexicon compliance, no state identity beyond Reach. ### lead-developer -- **Domain**: Multi-component orchestration, dependency sequencing. +- **Domain**: Multi-component orchestration across 10 new packages, dependency sequencing per D-031 blocker chain, vertical-slice integrity per phase. - **Frameworks**: cross-cutting. - **Territory**: `**`. -- **Constraints**: blocked-by chain enforcement, milestone versioning. +- **Constraints**: blocked-by chain enforcement (D-031), milestone versioning (v0.2 / tag_base v0.1.x), lexicon gate on merge, persona territory warn-mode enforcement. -## Phase-Specific -None at Phase 0. Phase 1 will add: -- security-engineer (for Watcher slashing logic, signature verification, smart contract audits) -- mesh-engineer (for LoRa/BLE/SAT bearer implementations) +### cosmos-engineer (custom, phase-specific to v0.2) +- **Domain**: v0.2 components map onto Cosmos SDK modules — `x/gov` (council tally), `x/group` (stand/guild decision policy), `x/authz`/`x/feegrant` (window), `x/capability` (window unforgeable ref), `x/ibc-transfer` ICS-20 (satellite). Ensures skeleton types mirror runtime shapes for low-friction Phase 3 wiring. +- **Frameworks**: cosmos-sdk, ibc-go, CosmWasm, CometBFT. +- **Territory**: `x/satellite/**`, `x/council/**`, `x/window/**`, `x/stand/**`, `x/guild/**`, `x/forex/**`, `x/bearers/**` (Cosmos-convention-mirroring modules per G-007; `x/pact`/`x/partner`/`x/bond` are backend-engineer's). `go.mod` read-only per G-006. +- **Constraints**: lexicon compliance (REQ-012), no live-chain side effects in skeleton, mirror `x/gov` `TallyResult` / `x/group` `DecisionPolicy` / `x/authz` `Grant` shapes, zero external deps in v0.2 skeleton, by-ID-string inter-module references (G-003 tested invariant). + +### security-engineer (custom, phase-specific to v0.2) +- **Domain**: Invariant + locked-const test authorship. Owns **all** test-file territory across v0.2 packages (including `genesis_test.go` per G-008). Highest invariant density in the project: Mission Lock non-amendable, bond 8% cap / 0% floor clamp, fee ceiling/floor clamp, 6 Pact types, 9 Stand types, 4 Partner tiers, Window revoke/expire idempotency, lexicon assertion per module. +- **Frameworks**: Go testing, table-driven tests, invariant tests. +- **Territory**: `x/**/types/**_test.go`, `x/**/keeper/**_test.go`, `x/**/genesis_test.go`, `x/**/*_test.go` (all test files per G-008). +- **Constraints**: invariant tests for all locked constants, locked-const tests for every enum count (9 stands, 4 partner tiers, 6 pacts, 3 councils), lexicon assertion in every new test file (D-033), ≥80% coverage on new packages, Window lifecycle idempotency tests (revoke-after-expire, double-revoke). + +## Deactivated +- **frontend-engineer** — No UI in v0.2 (skeleton+tests only). Mesh Experience UI is v0.1-complete; new UI is v0.3+. Reactivate in v0.3. +- **ci-security-auditor** — Default deactivated; activate in P5 (review/ship) for milestone audit. +- **mesh-engineer** — v0.1 listed as future; still not needed in v0.2 (Bearers OY-LR + Beacon are type stubs only). Activate in v0.3 for real bearer runtime. ## Custom Personas -None at Phase 0. \ No newline at end of file +- **cosmos-engineer** — v0.2 components map onto specific Cosmos SDK modules. Dedicated persona ensures skeleton types mirror eventual runtime shapes, reducing Phase 3 wiring refactor cost. Distinct from backend-engineer: carries Cosmos-specific convention knowledge (tally shapes, decision policy, capability, ICS-20 packet shape). +- **security-engineer** — v0.2 has the highest locked-const + invariant density in the project. Dedicated persona ensures invariant tests and lexicon assertions are not an afterthought. Distinct from backend-engineer: owns test-file territory and invariant-first design. + +## Framework Alignment +- **Go 1.22** — all personas target Go 1.22 (`go.mod`). +- **cosmos-sdk** — cosmos-engineer targets cosmos-sdk v0.50.x (LTS) for future wiring; NOT vendored in v0.2 skeleton. +- **ibc-go** — cosmos-engineer targets ibc-go v8/v10 for satellite module shape; NOT vendored in v0.2 skeleton. +- **CosmWasm** — cosmos-engineer targets wasmvm v1.5/v2.0 for potential Pacts-as-contracts in Phase 3; NOT vendored in v0.2. + +## Territory Alignment +- Mapped to actual `x//` structure (15 v0.1 modules + 9 new v0.2 modules + 1 extended). +- backend-engineer owns `x/pact`, `x/partner`, `x/bond` (non-Cosmos-mirroring per G-007) + shared `types/`+`keeper/`+`module.go` authoring. +- data-engineer owns `genesis.go` schema only (G-008 — excludes `*_test.go`). +- cosmos-engineer owns the Cosmos-convention-mirroring modules (`x/satellite`, `x/council`, `x/window`, `x/stand`, `x/guild`, `x/forex`) + `x/bearers` extension (G-007). +- security-engineer owns **all** `*_test.go` files across the new packages (G-008 — including `genesis_test.go`). +- lead-developer owns `**` for cross-cutting coordination. +- `go.mod` is **read-only** in v0.2 (G-006) — no persona may modify it; any change is an escalation (would violate D-020/A-201 zero-dep invariant). + +## Constraint Alignment +- **Lexicon (REQ-012)** — every persona carries it; security-engineer asserts it per test file. +- **Skeleton + tests pattern (D-020)** — backend-engineer + cosmos-engineer enforce. +- **≥80% coverage on new packages (D-033)** — security-engineer owns the gate. +- **Blocker chain (D-031)** — lead-developer enforces phase ordering. +- **No live-chain side effects in skeleton** — cosmos-engineer + backend-engineer enforce (no relayer, no CometBFT, no live oracle). +- **Locked-const invariants** — security-engineer owns; every locked constant has a dedicated test. + +## Phase-Specific Personas +- **cosmos-engineer** — phase-specific to v0.2 execution phases (P1-P4). Remove or merge back into backend-engineer after v0.2 ships (Cosmos convention alignment is most critical during the first Mesh-era skeleton). +- **security-engineer** — phase-specific to v0.2 (highest invariant density). May persist into v0.3 if invariant-test density remains high; reassess at v0.3 PLAN. \ No newline at end of file diff --git a/.ciagent/oy/PLANS.md b/.ciagent/oy/PLANS.md index 0a747e3..6ab2dc7 100644 --- a/.ciagent/oy/PLANS.md +++ b/.ciagent/oy/PLANS.md @@ -1,213 +1,337 @@ -# Phase Plans: OpenYield (oy) — Milestone v0.1 (Pre-MVP) +# Plans: OpenYield (oy) — v0.2 (The Mesh) -## Milestone Versioning +## Milestone Summary -- **Milestone**: v0.1 (development; stays v0.1 until MVP ships as v0.1.0) -- **Patch line**: v0.0.x (previous minor) -- **Phase 0 tag**: v0.0.0 -- **P1-P8 tags**: v0.0.1 - v0.0.8 -- **P9 (final review)**: v0.0.9 — milestone complete, no MVP release yet -- **MVP release** (future milestone): v0.1.0 +- **Milestone**: v0.2 — The Mesh +- **Type**: Feature (≥1 `feat` phase) +- **Tag base**: `v0.1.x` patch line (P0 ships as `v0.1.0`; execution phases `v0.1.1..v0.1.4`; final phase `v0.1.5` IS the milestone release) +- **Phases**: 5 — P1..P4 (execution) + P5 (final review/audit/ship). Phase 0 (PLAN) is in progress. +- **Depth**: skeleton + tests layer (D-020) — Go types + keeper stubs + unit tests, zero external deps, matching v0.1's pre-MVP pattern. +- **Coverage target**: ≥80% on each new package (D-033); lexicon assertion (REQ-012) in every new module's test file (D-032). +- **New modules**: 9 (`x/satellite`, `x/council`, `x/window`, `x/stand`, `x/guild`, `x/partner`, `x/pact`, `x/bond`, `x/forex`). **Extended**: 1 (`x/bearers`). Total v0.2 packages: 10 new/extended + v0.1 baseline of 15. +- **Phase ordering** (D-031): P1 Orgs+Window foundation → P2 Pacts+Partners → P3 Councils+Forex → P4 Bonds+Bearers+L2 → P5 review/ship. Respects ARCHITECTURE.md blocker chain. +- **Personas**: backend-engineer (bespoke types), cosmos-engineer (Cosmos-convention types), data-engineer (genesis validation), security-engineer (all test files, invariants, lexicon), lead-developer (cross-cutting verification/ship). -## Phase Breakdown — Task-Level Slices - -### Phase 0 — Pre-Execution (COMPLETE) -- SPECIFY → CLARIFY → RESEARCH → PLAN → GRILL -- Tag: v0.0.0 -- Ships: .ciagent/ reference files, 21 REQ-IDs, persona assessment - -### Phase 1 — OY Chain & Mirror (Component 1) -- **Wave**: Core Spine -- **REQs**: REQ-004 (9 Watchers, 6-of-9 quorum), REQ-008 (OY Chain) -- **Deliverables**: - - Cosmos SDK app-chain skeleton (CometBFT consensus) - - Watcher bond module (min 100,000 Bread bond) - - Attestation quorum module (6-of-9, daily epoch, geographic diversity rule) - - Mirror: reserve ratio publication, NAV computation - - Still/Stir (pause/resume) module -- **Blocked by**: Phase 0 ship -- **Owner**: backend-engineer -- **Tag**: v0.0.1 -- **Demo**: Chain launches, 9 Watchers bond, daily attestation quorum reached, reserve ratio published - -### Phase 2 — Bread Unit & Root Basket (Component 3) -- **Wave**: Core Spine -- **REQs**: REQ-003 (Bloom from real yield), REQ-013 (Bread unit), REQ-009 (Satellites) -- **Deliverables**: - - Forge/Fold CosmWasm contracts (mint against deposited Root Basket assets only) - - Bread unit scale (Grain → Crumb → Bread → Loaf → Batch → Cake → Bakery → Granary → Mill → Harvest → Earth) - - Root Basket config (Treasuries ~35%, IG corporate ~25%, gold ~20%, Bitcoin ~10%, other RWA ~10%) - - Ethereum bridge stub (wrapped Bread on Ethereum) - - Satellite chain stubs (Polygon, Base, Arbitrum) -- **Blocked by**: Phase 1 -- **Owner**: backend-engineer -- **Tag**: v0.0.2 -- **Demo**: Deposit RWA asset → Forge mints Bread → Fold burns Bread → returns asset. NAV per Bread published. - -### Phase 3 — Storage Substrate (Component 5) -- **Wave**: Core Spine -- **REQs**: REQ-014 (3 pools), REQ-015 (Window data source) -- **Deliverables**: - - Stash contract (per Holder, sovereign) - - Vault contract (per Stand, governed) - - Root-Pool contract (treasury, attested by Watchers) - - Storage indexer (Subsquid + GraphQL) - - Audit log primitive (for Window) -- **Blocked by**: Phase 1, Phase 2 -- **Owner**: data-engineer -- **Tag**: v0.0.3 -- **Demo**: Holder creates Stash, receives Bread, balance queryable. Root-Pool visible to all Holders. - -### Phase 4 — Bloom Engine (Component 4) -- **Wave**: Foundation Layer -- **REQs**: REQ-003 (Bloom from real yield) -- **Deliverables**: - - Bloom accrual loop (tied to Mirror attestations) - - Pro-rata distribution to every Grain in every Stash - - Target ~4-5%/year (honest expectation, not promise) - - Bloom Booster Bucket (higher-yield strategy) -- **Blocked by**: Phase 2, Phase 3 -- **Owner**: backend-engineer -- **Tag**: v0.0.4 -- **Demo**: Bread in Stash accrues Bloom automatically. Holder sees Bloom balance grow. - -### Phase 5 — Fee Covenant (Component 13) -- **Wave**: Foundation Layer -- **REQs**: REQ-002 (fee ceiling/floor) -- **Deliverables**: - - Fee Covenant smart contract (0.1% ceiling, 0.01% floor, 1-Grain internal minimum) - - Auto-decline schedule (Genesis 0.1% → $10B 0.07% → $50B 0.05% → $200B 0.03% → $500B 0.02% → $1T 0.01%) - - Processor share (50% → 30% → 20% → 10%) - - Waiver logic (Hand-Passes, Crew-internal, Household-internal, Cover Calls, Trust, Foundation, Circle) - - clamp() function (never > ceiling, never < floor) -- **Blocked by**: Phase 3 -- **Owner**: backend-engineer -- **Tag**: v0.0.5 -- **Demo**: Pass-Act executes, fee computed correctly, waived passes cost only 1 Grain, auto-decline verified. - -### Phase 6 — Identity, Standing & Citizenship (Component 6) -- **Wave**: Foundation Layer -- **REQs**: REQ-005 (Four Freeholder signals), REQ-006 (Standing formula), REQ-012 (Lexicon) -- **Deliverables**: - - Reach v1 (mesh-native identity, cryptographic) - - Standing v1 (Bayesian + time-decay + diversity + voucher-weighted − slashes) - - Freeholder transition (4 signals: 90d Stash, 4.5★+ in 3 cats, Capital, Vouch) - - Vouching with skin-in-the-game - - Slashing (Crack, FraudulentCoverCall, InactivityTimeout) - - Wayfarer's Record attestation - - Two-Layer Passport routing stub -- **Blocked by**: Phase 1, Phase 3 -- **Owner**: backend-engineer + data-engineer -- **Tag**: v0.0.6 -- **Demo**: Holder accumulates Standing, meets 4 signals, becomes Freeholder automatically. Vouching + slashing verified. - -### Phase 7 — Bearers & Processing Mesh (Component 12) -- **Wave**: User-Facing -- **REQs**: REQ-007 (FCFS), REQ-019 (6 bearers) -- **Deliverables**: - - FCFS processing mesh (not fee-auctioned) - - Geographic proximity wins (closest processor to recipient) - - Light client (~30 MB app, ~1-3% battery/day) - - OY-BLE bearer (10-100m) - - OY-WiFi-Direct bearer (50-200m) - - Unified Bearer Layer (parallel尝试, first-to-deliver wins, RFC 5050 DTN principles) - - Internet bearer (fallback) -- **Blocked by**: Phase 1, Phase 2, Phase 3, Phase 5 -- **Owner**: backend-engineer + frontend-engineer -- **Tag**: v0.0.7 -- **Demo**: Two phones transfer Bread via BLE. Processing mesh routes via FCFS. Light client runs. - -### Phase 8 — Mesh Experience (Component 9) -- **Wave**: User-Facing -- **REQs**: REQ-010 (Exit layer), Maya's Day placeholder -- **Deliverables**: - - Maps v1 (discovery — where you are, what's around) - - Pay v1 (settlement — how value flows) - - React Native app (Expo, offline-first) - - Exit layer stub (DEX swaps, bridges) - - Maya's Day placeholder UI (full narrative deferred to component doc) -- **Blocked by**: Phase 6, Phase 7, Phase 5 -- **Owner**: frontend-engineer -- **Tag**: v0.0.8 -- **Demo**: Holder opens app, sees Maps, sends Bread via Pay, views Standing, sees Mirror ratio. - -### Phase 9 — Final Review + Audit + Milestone Ship -- **Deliverables**: - - Multi-persona code review (all phases P1-P8) - - P0 fixes auto-applied, P1+ flagged for post-hoc - - Project health audit (reconstruction test, .ciagent discipline, branch hygiene) - - Milestone ship: merge phase/09 → milestone/v0.1-oy → main - - Tag v0.0.9 (final patch in v0.1 development line) - - Update REQUIREMENTS.md (mark milestone requirements complete) - - Update ROADMAP.md (mark milestone complete) - - Delete all milestone branches (tags preserve history) -- **Blocked by**: Phase 1-8 all shipped -- **Owner**: lead-developer -- **Tag**: v0.0.9 -- **Note**: v0.1 milestone complete. MVP NOT released. Next milestone (v0.2) builds toward MVP at v0.1.0. - -## Dependency Graph +### Cross-Phase Dependency Map ``` -P0 (done) ──► P1 (Chain & Mirror) - │ - ▼ - P2 (Bread & Root Basket) - │ - ▼ - P3 (Storage) - │ - ┌────────┼────────┐ - ▼ ▼ ▼ - P4 (Bloom) P5 (Fee) P6 (Identity) - │ │ - └────┬───┘ - ▼ - P7 (Bearers) - │ - ▼ - P8 (Mesh UI) - │ - ▼ - P9 (Final) +P1 (Window, Stand, Guild) ──┬──► P2 (Pact, Partner) [Window refs + Stand refs] + ├──► P3 (Council, Forex) [Stand + Guild refs; Forex independent] + └──► P4 (Bond, Bearers, L2) [Stand refs for Bond; Bearers/L2 independent] +P2 ──► P3 (Partner/Pier feeds Forex oracle interface) +P3 ──► P4 (Council governance over Bond market; not a hard type-dep, soft ordering) +P4 ──► P5 (all execution phases complete before review/ship) ``` -## Parallelization Opportunities +Hard cross-phase blockers (by-ID-string refs, no import cycles): +- P2 Pact `StandRegistry` references `x/stand` StandRef (P1-02-01 must land first). +- P2 Partner `Window`-scoped actions reference `x/window` WindowRef (P1-01-01 must land first). +- P3 Council `Stand` Council references `x/stand` + `x/guild` (P1-02-01, P1-03-01 must land first). +- P3 Forex oracle interface is consumed by Piers (P2 Partner) — soft ordering, no type dep. +- P4 Bond issuer references `x/stand` StandRef (P1-02-01 must land first). -After P3 ships: -- P4 (Bloom), P5 (Fee), P6 (Identity) can run in parallel (all depend only on P1-P3) -- P5 depends only on P3; P6 depends on P1+P3; P4 depends on P2+P3 +--- -After P5+P6 ship: -- P7 (Bearers) depends on P1+P2+P3+P5 -- P8 (Mesh UI) depends on P5+P6+P7 +## Phase P1 — Orgs + Window Foundation -## Vertical Slice Integrity +- **Slug**: `orgs-window-foundation` +- **Branch**: `oy/phase/01-orgs-window-foundation` +- **REQs covered**: REQ-015 (Window — *fullest* per D-023), REQ-016 (9 Stands), REQ-017 (Guilds + Hand-Pass 0%) +- **Tag**: `v0.1.1` +- **Goal**: Ship the Window leaf primitive (full lifecycle), the 9-type Stand enum + keeper stub, and the Guild + Hand-Pass @ 0% skeleton — the foundation every downstream Mesh module references. -| After Phase | Demoable End State | -|---|---| -| P1 | Chain runs, Watchers attest, Mirror live | -| P2 | Bread minted against RWA, NAV published | -| P3 | Holder has Stash, Root-Pool visible | -| P4 | Bloom accrues to Stash automatically | -| P5 | Fees enforced, waivers work, auto-decline | -| P6 | Freeholder transition computed, vouching works | -| P7 | Transact via BLE/WiFi-Direct, FCFS processing | -| P8 | Full app: Maps, Pay, Standing, Mirror ratio | -| P9 | Milestone v0.1 complete, ready for v0.2 | +### Wave 1 — Foundation module types (parallel; no internal deps) -## Phase 2+ (Future Milestones) +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P1-01-01 | REQ-015 | cosmos-engineer | `x/window/types/types.go` | `Window` struct (id, grantor-holder, grantee, scope, start, end, rate-limit, revoked, audit-log-refs); `ScopeKind` enum (ReadStash, ReadStanding, ProcessPassActForStand, …); `Scope` struct (kind, resource-id); `RateLimit` struct (max-actions, per-duration-seconds, actions-consumed); `AuditEntry` struct (timestamp, action, result, granter-ref); `WindowStatus` enum (Open, Active, Revoked, Expired); `Revoke()` stub; `DefaultParams`, `GenesisState`, `DefaultGenesisState`, `ValidateGenesis` (reject dup window-ids); consts `ModuleName`/`StoreKey`/`RouterKey`/`QuerierRoute` | `go build ./x/window/...` succeeds; `Window` struct fields match RESEARCH §1.3; `ValidateGenesis` returns error on dup window-ids (A-212 upgrade) | — | +| P1-02-01 | REQ-016 | cosmos-engineer | `x/stand/types/types.go` | `StandType` enum (Household, Crew, Entity, Coop, Circle, Trust, Foundation, Confederation, Shadow) — exactly 9; `AllStandTypes() []StandType`; `Stand` struct (id, type, name, vault-id, admin-reach, created-at, member-count); `Membership` struct (stand-id, reach-id, joined-at, role); `StandRole` enum (Member, Admin, Observer); `StandPolicy` stub (threshold/weighted — mirror `x/group` DecisionPolicy, A-205); `DefaultParams`, `GenesisState` (stands + memberships), `DefaultGenesisState`, `ValidateGenesis` (reject dup stand-ids, dup member-reach within a stand) | `go build ./x/stand/...` succeeds; `AllStandTypes()` returns exactly 9 entries with vision §11 names; `ValidateGenesis` rejects dup stand-id and dup member-reach | — | +| P1-03-01 | REQ-017 | cosmos-engineer | `x/guild/types/types.go` | `Guild` struct (id, name, founder-reach, created-at, stand-affiliation-id optional); `HandPass` struct (pass-id, guild-id, issuer-reach, recipient-reach, amount-grain, timestamp, fee-grain-always-0); `HandPassFeeBps = 0` locked `const` (cross-doc to feecovenant `WaiverHandPassGuild`); `IssueHandPass(...)` stub; `DefaultParams`, `GenesisState` (guilds + hand-passes), `DefaultGenesisState`, `ValidateGenesis` (reject dup guild-ids, dup pass-ids) | `go build ./x/guild/...` succeeds; `HandPassFeeBps == 0`; `ValidateGenesis` rejects dup guild-id | — | -### Milestone v0.2 — The Mesh -- Window, Pacts, Orgs, Partners, Governance, OY-LR, Bonds -- Target: $1B annual volume (simulation) +### Wave 2 — Tests + genesis validation (parallel; blocked-by Wave 1) -### Milestone v0.3 — The Bearers -- Cross-Chain, OY-SAT, OY-QR, Hub API, Anchors, full bond market +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P1-01-02 | REQ-015 | security-engineer | `x/window/types/types_test.go` | Table-driven tests: lifecycle Open→Active→Revoked→Expired; `Revoke()` transitions to Revoked; revoke-after-expire is no-op (idempotent); double-revoke is idempotent OR error (test both paths); `RateLimit` consume increments `actions-consumed`, blocks at `max-actions`; `Scope` kind enum coverage; `DefaultGenesis` empty; `ValidateGenesis` rejects dup window-ids; **lexicon assertion** (no banned terms in package); locked-const for `WindowStatus` count; **by-ID-string import invariant (G-003)**: a test that scans all non-test `.go` files under `x/` using `go/parser` or a package-import grep and asserts NO production file imports another `x//types` package by struct (enforces A-203 as a tested invariant, not just a convention) | `go test ./x/window/...` passes; ≥80% coverage on `x/window/types`; lexicon assertion green; lifecycle idempotency tests present; **G-003 import-invariant test passes (zero cross-module struct imports in production code)** | P1-01-01 | +| P1-01-03 | REQ-015 | data-engineer | `x/window/types/genesis.go` (or extend `types.go`) | Append-only audit log genesis shape: `AuditEntry` slice in `GenesisState`, `ValidateGenesis` enforces append-only ordering (timestamps non-decreasing) + no dup entry-ids | `go test ./x/window/...` passes; audit-log ordering test green | P1-01-01 | +| P1-02-02 | REQ-016 | security-engineer | `x/stand/types/types_test.go` | Locked-const test: `AllStandTypes()` returns exactly 9; each name matches vision §11 (Household, Crew, Entity, Co-op, Circle, Trust, Foundation, Confederation, Shadow) — no extras, no dups; `StandRole` enum coverage; `ValidateGenesis` rejects dup stand-id + dup member-reach; **lexicon assertion** | `go test ./x/stand/...` passes; ≥80% coverage; 9-type locked-const test breaks if a type is added/removed/renamed | P1-02-01 | +| P1-02-03 | REQ-016 | data-engineer | `x/stand/types/genesis.go` | Membership-set genesis: stands + memberships in `GenesisState`, `ValidateGenesis` enforces member-reach uniqueness within a stand | `go test ./x/stand/...` passes; membership uniqueness test green | P1-02-01 | +| P1-03-02 | REQ-017 | security-engineer | `x/guild/types/types_test.go` | Locked-const test: `HandPassFeeBps == 0`; `HandPass` fee field always 0; Guild with Stand affiliation OR standalone; issuer type-level (no enforcement in skeleton); `ValidateGenesis` rejects dup guild-id + dup pass-id; **lexicon assertion** | `go test ./x/guild/...` passes; ≥80% coverage; `HandPassFeeBps == 0` invariant | P1-03-01 | -### Milestone v0.4 — Maturity -- Cross-chain expansion, Confederation, Yield Token +### Wave 3 — Phase verification + lexicon meta-test scaffolding + ship -### MVP Release — v0.1.0 -- After v0.4 milestone completes and system is validated as production-ready -- First public release to real Holders \ No newline at end of file +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P1-04-01 | REQ-012, D-033 | lead-developer | (cross-cutting) | Run `go build ./...` + `go test ./...` across whole repo; confirm P1 packages ≥80% coverage; confirm lexicon assertion present in all 3 new test files; tag `v0.1.1` | `go test ./...` green; `go test -cover ./x/window/... ./x/stand/... ./x/guild/...` ≥80% each; 3 lexicon assertions present; git tag `v0.1.1` created | P1-01-02, P1-01-03, P1-02-02, P1-02-03, P1-03-02, P1-04-02 | +| P1-04-02 | REQ-012 | security-engineer | `lexicon_meta_test.go` (repo root, package `lexicon` or `main`) — **NEW (G-004)** | **Project-wide lexicon meta-test scaffolding**: scans all `x/**/*.go` (production + test) for the 9 banned terms (bank, deposit, interest, yield, currency, dollar, euro, account, savings, depositor). Passes at P1 time (v0.1 baseline is clean). The meta-test is the durable firewall created in v0.2 (G-002: v0.1 has NO lexicon test). P5-01-01 will *extend* this scaffolding to assert all 10 new/extended packages, not create it from scratch. Includes a **self-test table (G-009)**: a hardcoded slice of synthetic strings, one per banned term (e.g. `"bank account"`, `"interest yield"`, `"currency dollar euro"`, `"deposit savings depositor"`), asserted to each trigger detection — so the meta-test's own coverage is durably verified without manual spikes. | `go test ./lexicon_meta_test.go` (or `go test ./...`) green; meta-test scans every `.go` under `x/`; self-test table passes for all 9 banned terms (each synthetic string is detected) | P1-01-01 | + +### P1 Must-Haves +- [ ] `x/window`, `x/stand`, `x/guild` each have `types/types.go` + `types/types_test.go` (v0.1 pattern, package `types`, zero external deps). +- [ ] `go build ./...` and `go test ./...` green across the whole repo. +- [ ] ≥80% coverage on `x/window/types`, `x/stand/types`, `x/guild/types`. +- [ ] Window lifecycle tests: Open→Active→Revoked→Expired; revoke-after-expire no-op; double-revoke handled. +- [ ] Stand locked-const: exactly 9 types with vision §11 names. +- [ ] Guild `HandPassFeeBps == 0` invariant test. +- [ ] Lexicon assertion in all 3 new test files. +- [ ] `ValidateGenesis` performs ID-uniqueness checks (A-212 upgrade from v0.1 no-op). +- [ ] Git tag `v0.1.1`. + +### P1 Risks & Mitigations +- **Rate-limit algorithm unstated** (A-206, conf 0.65) → use simple counter (`actionsConsumed` vs `maxActions`); flag for v0.3 revisit. Test asserts counter semantics, not algorithm. +- **Shadow Stand behavioral split** (A-213, conf 0.60) → treat all 9 uniformly in skeleton; test asserts uniform enum, no special-casing. Flag for v0.3 design. +- **Window ↔ downstream import cycles** → Window ships first (Wave 1) so P2/P3/P4 reference by `WindowRef` id-string, not struct import. +- **`x/group` DecisionPolicy shape drift** (A-205) → `StandPolicy` mirrors `threshold` + `weighted` fields; cosmos-engineer reviews. + +--- + +## Phase P2 — Pacts + Partners + +- **Slug**: `pacts-partners` +- **Branch**: `oy/phase/02-pacts-partners` +- **REQs covered**: REQ-020 (6 Pacts), REQ-018 (4-tier Partner Spectrum) +- **Tag**: `v0.1.2` +- **Goal**: Ship the 6-Pact module (Pause/Ground/Stance/Cover/StandRegistry/HubAPI) with execute-entry stubs + invariant tests, and the 4-tier Partner registry with credential-ref types — both consuming Window + Stand refs from P1. + +### Wave 1 — Module types (parallel; blocked-by P1 foundation) + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P2-01-01 | REQ-020 | backend-engineer | `x/pact/types/types.go` | `PactType` enum (Pause, Ground, Stance, Cover, StandRegistry, HubAPI) — exactly 6 (A-207); `Pact` struct (id, type, parties, terms-bytes, status, execute-msg-ref, window-id-ref, stand-id-ref); `PactStatus` enum (Proposed, Active, Fulfilled, Voided); per-type `Execute*` stub methods (`ExecutePause`, `ExecuteGround`, `ExecuteStance`, `ExecuteCover`, `ExecuteStandRegistry`, `ExecuteHubAPI`); Mission-Lock invariant: Pause/Ground/Stance core terms non-amendable (const flag); `DefaultParams`, `GenesisState` (pacts), `DefaultGenesisState`, `ValidateGenesis` (reject dup pact-ids) | `go build ./x/pact/...` succeeds; `AllPactTypes()` returns exactly 6 with vision §16 names; `ValidateGenesis` rejects dup pact-id | P1-01-01, P1-02-01 | +| P2-02-01 | REQ-018 | backend-engineer | `x/partner/types/types.go` | `PartnerTier` enum (Op, MasterOp, Pier, Anchor) — exactly 4 (D-026); `Partner` struct (id, tier, name, reach-id, region, credential-ref, status); `CredentialRef` struct (provider-id, credential-type, ref-uri — opaque URI, Pier routing deferred per Q5); `PartnerStatus` enum (Pending, Active, Suspended, Revoked); registry keeper stub: `AddPartner`, `GetPartner`, `ListPartners`, `ListByTier`; `DefaultParams`, `GenesisState` (partners), `DefaultGenesisState`, `ValidateGenesis` (reject dup partner-ids) | `go build ./x/partner/...` succeeds; `AllPartnerTiers()` returns exactly 4 with vision §13 names; `ValidateGenesis` rejects dup partner-id | P1-01-01 | + +### Wave 2 — Tests (parallel; blocked-by Wave 1) + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P2-01-02 | REQ-020 | security-engineer | `x/pact/types/types_test.go` | Locked-const test: `AllPactTypes()` returns exactly 6; names match vision §16; no extras/dups; Mission-Lock invariant test (Pause/Ground/Stance `AmendableCoreTerms == false`); `PactStatus` enum coverage; `Execute*` stubs callable; `ValidateGenesis` rejects dup pact-id; **lexicon assertion** (no "bank"/"account" etc.) | `go test ./x/pact/...` passes; ≥80% coverage; 6-type locked-const test breaks on add/remove/rename; Mission Lock invariant green | P2-01-01 | +| P2-02-02 | REQ-018 | security-engineer | `x/partner/types/types_test.go` | Locked-const test: `AllPartnerTiers()` returns exactly 4 (Op, MasterOp, Pier, Anchor); tier names lexicon-clean (no "operator" spelled out if banned — verify "Op" is safe per vision §13); `PartnerStatus` enum coverage; registry stubs: `AddPartner`/`GetPartner`/`ListByTier` round-trip; `ValidateGenesis` rejects dup partner-id; **lexicon assertion** | `go test ./x/partner/...` passes; ≥80% coverage; 4-tier locked-const test breaks on change | P2-02-01 | + +### Wave 3 — Phase verification + ship + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P2-03-01 | REQ-012, D-033 | lead-developer | (cross-cutting) | `go build ./...` + `go test ./...` green; P2 packages ≥80% coverage; 2 lexicon assertions present; tag `v0.1.2` | `go test ./...` green; coverage ≥80% on `x/pact/types`, `x/partner/types`; git tag `v0.1.2` | P2-01-02, P2-02-02 | + +### P2 Must-Haves +- [ ] `x/pact`, `x/partner` each have `types/types.go` + `types/types_test.go`. +- [ ] `go build ./...` and `go test ./...` green. +- [ ] ≥80% coverage on `x/pact/types`, `x/partner/types`. +- [ ] Pact locked-const: exactly 6 types (vision §16 names). +- [ ] Partner locked-const: exactly 4 tiers (Op, MasterOp, Pier, Anchor). +- [ ] Mission-Lock invariant: Pause/Ground/Stance core terms non-amendable. +- [ ] Lexicon assertion in both new test files. +- [ ] `ValidateGenesis` ID-uniqueness checks. +- [ ] Git tag `v0.1.2`. + +### P2 Risks & Mitigations +- **Cover Pool seniority deferred** (Q7) → Cover Pact is a flat commitment type with no seniority fields; test asserts no seniority fields exist. +- **"Master Op" lexicon risk** → security-engineer's lexicon assertion scans partner-type strings; "Op" verified safe per vision §13. +- **6 micro-modules vs 1 module** (A-207) → one `x/pact` module with `PactType` enum + per-type execute stubs; matches v0.1 one-module-per-component pattern. + +--- + +## Phase P3 — Councils + Forex + +- **Slug**: `councils-forex` +- **Branch**: `oy/phase/03-councils-forex` +- **REQs covered**: REQ-011 (3 Councils + Mission Lock), Forex Engine v1 +- **Tag**: `v0.1.3` +- **Goal**: Ship the 3-Council module (Mesh/Guild/Stand) with `x/gov`-shaped tally types + Mission Lock as a `const bool`, and the Forex Engine v1 stub (pair type + oracle interface + stub keeper) with lexicon-clean pair labels. + +### Wave 1 — Module types (parallel; blocked-by P1 + P2) + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P3-01-01 | REQ-011 | cosmos-engineer | `x/council/types/types.go` | `CouncilType` enum (Mesh, Guild, Stand) — exactly 3; `Proposal` struct (id, council, proposer-reach, submit-time, voting-period, status); `ProposalStatus` enum (Pending, Active, Succeeded, Failed, Executed) — mirror OZ/Governor + `x/gov`; `VoteOption` enum (Yes, No, Abstain — no "no-with-veto", anti-greed); `TallyResult` struct (yes, no, abstain, total-voice, quorum-met) — mirror `x/gov` `TallyResult` (A-204); `VoiceSource` enum (Stash, Standing, Vouch, Freeholder, Guild) — multi-source weighting inputs; `MissionLockAmendable = false` locked `const bool` (A-211); Stand Council references `x/stand` by stand-id-string; Guild Council references `x/guild` by guild-id-string (no struct imports); `DefaultParams`, `GenesisState` (proposals + tallies), `DefaultGenesisState`, `ValidateGenesis` (reject dup proposal-ids) | `go build ./x/council/...` succeeds; `AllCouncilTypes()` returns exactly 3; `MissionLockAmendable == false`; `TallyResult` fields match `x/gov` shape | P1-02-01, P1-03-01 | +| P3-02-01 | Forex v1 | cosmos-engineer | `x/forex/types/types.go` | `ForexPair` struct (base-asset, quote-asset — NOT "currency"/"dollar"/"euro"; use "Bread/Asset" style labels, A-208); `RateOracle` Go interface (`GetRate(pair) (rate, timestamp, err)` — no impl); `ForexRate` struct (pair, rate, source, timestamp, confidence); `SpreadCapBps` const (locked; placeholder 0 with documented TBD, A-214 — test asserts ≥0); stub keeper `GetRate` returns sentinel "not-integrated"; `DefaultParams`, `GenesisState` (pairs + rates), `DefaultGenesisState`, `ValidateGenesis` (reject dup pair-ids) | `go build ./x/forex/...` succeeds; `RateOracle` interface compiles; `SpreadCapBps >= 0`; no banned terms in pair-label fields | — (Forex independent; soft order after P2 Partner for oracle-consumer narrative) | + +### Wave 2 — Tests + genesis (parallel; blocked-by Wave 1) + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P3-01-02 | REQ-011 | security-engineer | `x/council/types/types_test.go` | Locked-const test: `AllCouncilTypes()` returns exactly 3 (Mesh, Guild, Stand); **Mission Lock invariant**: `MissionLockAmendable == false` and a test asserting it can never be set true (the regression firewall); `ProposalStatus` enum coverage (5 states); `VoteOption` enum coverage (3 options, no veto); `TallyResult` struct shape matches `x/gov`; `VoiceSource` enum coverage (5 sources); `ValidateGenesis` rejects dup proposal-id; **lexicon assertion** (no "account" — use "Holder"/"Reach") | `go test ./x/council/...` passes; ≥80% coverage; Mission Lock invariant test is the highest-severity regression firewall | P3-01-01 | +| P3-01-03 | REQ-011 | data-engineer | `x/council/types/genesis.go` | Voice tally genesis shape: proposals + tallies in `GenesisState`; `ValidateGenesis` enforces tally-proposal referential integrity (tally.proposal-id exists) | `go test ./x/council/...` passes; referential integrity test green | P3-01-01 | +| P3-02-02 | Forex v1 | security-engineer | `x/forex/types/types_test.go` | `ForexPair` struct fields lexicon-clean (assert no "currency"/"dollar"/"euro"/"fx" in field names or sample labels); `RateOracle` interface signature compiles + a stub impl satisfies it; `SpreadCapBps >= 0`; stub keeper `GetRate` returns sentinel; `ValidateGenesis` rejects dup pair-id; **lexicon assertion** (highest lexicon-risk module per RESEARCH §1.10) | `go test ./x/forex/...` passes; ≥80% coverage; lexicon assertion scans pair-label sample data | P3-02-01 | + +### Wave 3 — Phase verification + ship + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P3-03-01 | REQ-012, D-033 | lead-developer | (cross-cutting) | `go build ./...` + `go test ./...` green; P3 packages ≥80% coverage; 2 lexicon assertions; Mission Lock invariant green; tag `v0.1.3` | `go test ./...` green; coverage ≥80% on `x/council/types`, `x/forex/types`; Mission Lock invariant passes; git tag `v0.1.3` | P3-01-02, P3-01-03, P3-02-02 | + +### P3 Must-Haves +- [ ] `x/council`, `x/forex` each have `types/types.go` + `types/types_test.go`. +- [ ] `go build ./...` and `go test ./...` green. +- [ ] ≥80% coverage on `x/council/types`, `x/forex/types`. +- [ ] Council locked-const: exactly 3 types (Mesh, Guild, Stand). +- [ ] **Mission Lock invariant**: `MissionLockAmendable == false`, test asserts non-amendable (highest-severity). +- [ ] `TallyResult` shape mirrors `x/gov` (A-204) for future wiring. +- [ ] `VoteOption` has no "no-with-veto" (anti-greed). +- [ ] Forex pair labels lexicon-clean (no "currency"/"dollar"/"euro"); `RateOracle` interface compiles. +- [ ] Lexicon assertion in both new test files. +- [ ] `ValidateGenesis` ID-uniqueness + referential integrity (Council). +- [ ] Git tag `v0.1.3`. + +### P3 Risks & Mitigations +- **Multi-source Voice weighting math unstated** (RESEARCH §1.2) → skeleton defines `VoiceSource` enum + `TallyResult` struct only; no aggregation algorithm. Flag weighting math as v0.3+ decision. +- **Forex lexicon hostility** (highest risk) → security-engineer lexicon assertion scans pair-label *sample data* in tests, not just field names. "Forex" itself allowed (vision §13); "Bread/Asset" labels (A-208). +- **`x/gov` tally shape drift** (A-204, conf 0.75) → cosmos-engineer mirrors `TallyResult` field names (`yes`/`no`/`abstain`/`total`); test asserts field names. +- **Council ↔ Stand/Guild import cycles** → reference by id-string only; test asserts no struct imports of `x/stand`/`x/guild`. + +--- + +## Phase P4 — Bonds + Bearers + L2 + +- **Slug**: `bonds-bearers-l2` +- **Branch**: `oy/phase/04-bonds-bearers-l2` +- **REQs covered**: REQ-021 (Mesh Bond Market 8% cap), REQ-009 (L2 IBC Satellite — Polygon rep + 4 stubs), Bearers OY-LR + Beacon v1 (D-029) +- **Tag**: `v0.1.4` +- **Goal**: Ship the Mesh Bond module with 8% cap / 0% floor clamp invariants, extend the `x/bearers` module with the `BearerTransport` interface + OY-LR + Beacon stubs, and ship the L2 satellite module with ICS-20-shaped packet types for Polygon (representative) + 4 enum-placeholder chains. + +### Wave 1 — Module types (parallel; Bond blocked-by P1 Stand, Bearers/L2 independent) + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P4-01-01 | REQ-021 | backend-engineer | `x/bond/types/types.go` | `CouponCapBps = 800` (8%) and `CouponFloorBps = 0` (0%) locked `const` (D-028); `Bond` struct (id, issuer-stand-id, principal-grain, coupon-bps, term-days, issued-at, maturity, status); `BondStatus` enum (Issued, Active, Matured, Defaulted, Repaid); `Issue(...)` stub; `Clamp(couponBps)` returns `min(cap, max(floor, coupon))` — same shape as Fee Covenant's `Clamp`; issuer-stand-id references `x/stand` by id-string; `DefaultParams`, `GenesisState` (bonds), `DefaultGenesisState`, `ValidateGenesis` (reject dup bond-ids) | `go build ./x/bond/...` succeeds; `CouponCapBps == 800`; `CouponFloorBps == 0`; `Clamp` matches Fee Covenant shape; `ValidateGenesis` rejects dup bond-id | P1-02-01 | +| P4-02-01 | D-029 | cosmos-engineer | `x/bearers/types/types.go` (extend existing) | **EXTEND** existing `x/bearers` (do NOT create new module — A-209); add `BearerTransport` Go interface (`Send`, `Receive`, `Status` — no impl); `OYLRLink` struct (gateway-id, range-meters, frequency-mhz, surveillance-resistant=true); `BeaconFrame` struct (beacon-id, ephemeral-id, payload-bytes, ttl); preserve existing `BearerType` enum + `AllBearers()` (OY-LR already present); `DefaultParams`/`GenesisState` unchanged | `go build ./x/bearers/...` succeeds; `BearerTransport` interface compiles; `OYLRLink` + `BeaconFrame` structs present; existing `AllBearers()` unchanged (6 bearers) | — | +| P4-03-01 | REQ-009 | cosmos-engineer | `x/satellite/types/types.go` | `L2Chain` enum (Polygon active; Base, Arbitrum, Optimism, Solana as `StatusPending` per D-021); `TransferChannel` struct (port-id, channel-id, counterparty, status); `ChannelStatus` enum (Init, TryOpen, Open, Closed) — mirror ICS-20 handshake; `WrappedBreadDenom` struct (denom, trace-path) encoding IBC trace; `Packet` stub struct (sequence, source-port, source-channel, dest-port, dest-channel, data, timeout-height, timeout-timestamp) — pinned to ICS-20 v1 shape (A-215); no ibc-go import (zero deps); `DefaultParams`, `GenesisState` (channels + denoms), `DefaultGenesisState`, `ValidateGenesis` (reject dup channel-ids) | `go build ./x/satellite/...` succeeds; `L2Chain` enum has 5 entries (Polygon + 4 stubs); `Packet` struct fields match ICS-20 v1; zero external deps confirmed | — | + +### Wave 2 — Tests + genesis (parallel; blocked-by Wave 1) + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P4-01-02 | REQ-021 | security-engineer | `x/bond/types/types_test.go` | **Clamp invariant tests** (highest-severity for bond): below floor → floor; above cap → cap; in range → unchanged; `CouponCapBps == 800` locked-const; `CouponFloorBps == 0` locked-const; `BondStatus` enum coverage; `Issue` stub callable; `ValidateGenesis` rejects dup bond-id; **lexicon assertion** (no "interest"/"yield" — use "coupon" exclusively, A-210) | `go test ./x/bond/...` passes; ≥80% coverage; clamp invariant test breaks if cap/floor change; lexicon green (no banned terms) | P4-01-01 | +| P4-01-03 | REQ-021 | data-engineer | `x/bond/types/genesis.go` | Bond issuance genesis: bonds in `GenesisState`; `ValidateGenesis` enforces coupon-bps within [floor, cap] for each genesis bond (clamp at genesis load) | `go test ./x/bond/...` passes; genesis clamp test green | P4-01-01 | +| P4-02-02 | D-029 | security-engineer | `x/bearers/types/types_test.go` (extend existing) | `BearerTransport` interface signature test (a stub impl satisfies it); `OYLRLink` struct non-empty + `surveillance-resistant == true`; `BeaconFrame` struct non-empty + ttl > 0; OY-LR still in `AllBearers()` (regression: existing v0.1 test still passes); **lexicon assertion** (extend existing) | `go test ./x/bearers/...` passes; ≥80% coverage; existing v0.1 bearers tests still green (no regression) | P4-02-01 | +| P4-03-02 | REQ-009 | security-engineer | `x/satellite/types/types_test.go` | `L2Chain` enum has exactly 5 entries (Polygon + Base/Arbitrum/Optimism/Solana); Polygon is the only active rep (D-021); `ChannelStatus` enum coverage (4 states); `Packet` struct fields match ICS-20 v1 (cross-check field names); `WrappedBreadDenom` trace-path encoding; `ValidateGenesis` rejects dup channel-id; **lexicon assertion** (no "bank"/"account" — use "Holder"/"Reach") | `go test ./x/satellite/...` passes; ≥80% coverage; 5-chain enum locked-const; ICS-20 shape test | P4-03-01 | + +### Wave 3 — Phase verification + ship + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P4-04-01 | REQ-012, D-033 | lead-developer | (cross-cutting) | `go build ./...` + `go test ./...` green; P4 packages ≥80% coverage; 3 lexicon assertions (bond, bearers-ext, satellite); bond clamp invariant green; tag `v0.1.4` | `go test ./...` green; coverage ≥80% on `x/bond/types`, `x/bearers/types`, `x/satellite/types`; existing v0.1 tests still green; git tag `v0.1.4` | P4-01-02, P4-01-03, P4-02-02, P4-03-02 | + +### P4 Must-Haves +- [ ] `x/bond` (new), `x/bearers` (extended), `x/satellite` (new) each have `types/types.go` + `types/types_test.go`. +- [ ] `go build ./...` and `go test ./...` green — **including all v0.1 baseline tests (no regression)**. +- [ ] ≥80% coverage on `x/bond/types`, `x/bearers/types`, `x/satellite/types`. +- [ ] Bond clamp invariant: `CouponCapBps == 800`, `CouponFloorBps == 0`; clamp below→floor, above→cap, in-range→unchanged. +- [ ] Bond lexicon: "coupon" exclusively, no "interest"/"yield" (A-210). +- [ ] Bearers: `BearerTransport` interface compiles; `OYLRLink` + `BeaconFrame` stubs; existing `AllBearers()` (6) unchanged. +- [ ] Satellite: `L2Chain` exactly 5 (Polygon active + 4 stubs); `Packet` pinned to ICS-20 v1 shape; zero external deps. +- [ ] Lexicon assertion in all 3 test files. +- [ ] `ValidateGenesis` ID-uniqueness (all 3) + genesis clamp (Bond). +- [ ] Git tag `v0.1.4`. + +### P4 Risks & Mitigations +- **Bond lexicon risk** (RESEARCH §1.8, A-210 conf 1.00) → "coupon" exclusively; security-engineer lexicon assertion is the gate; "interest"/"yield" must never appear. +- **ICS-20 packet shape drift** (A-215, RESEARCH §1.1) → pin to ICS-20 v1 (stable, widely implemented); test asserts field names; refactor cost is types-only if v0.3 picks a different ibc-go version. +- **Bearers extension regression** → existing v0.1 bearers tests must stay green; `AllBearers()` count unchanged (6); test asserts no regression. +- **Full 5-chain IBC rollout** is Phase 3 (D-021) → only Polygon is active; 4 chains are `StatusPending` enum placeholders; test asserts exactly 1 active. +- **Solana lacks native IBC** (RESEARCH §1.1) → stubbed as `StatusPending`; no Solana light-client logic in v0.2. + +--- + +## Phase P5 — Final Review + Audit + Ship + +- **Slug**: `final-review-audit-ship` +- **Branch**: `oy/phase/05-final-review-audit-ship` +- **REQs covered**: REQ-012 (lexicon, project-wide meta-test), all v0.2 REQs (audit confirmation) +- **Tag**: `v0.1.5` (= **milestone v0.2 release** — final phase patch IS the milestone release per D-008/D-020) +- **Goal**: Run the full milestone audit — project-wide lexicon meta-test, coverage gate across all 10 new/extended packages, all locked-const invariants green, all REQs in v0.2 scope have skeleton+tests — then ship the `v0.2` milestone release as tag `v0.1.5`. + +### Wave 1 — Audit + meta-tests (parallel) + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P5-01-01 | REQ-012 | security-engineer | `lexicon_meta_test.go` (extend the P1-04-02 scaffolding — **G-004/G-009**) | **Extend the project-wide lexicon meta-test** (created in P1-04-02 per G-004) to cover all 10 new/extended v0.2 packages: scans all `x/**/*.go` for banned terms (bank, deposit, interest, yield, currency, dollar, euro, account, savings, depositor); fails on any hit. The self-test table (G-009) from P1-04-02 remains and asserts each of the 9 banned terms' synthetic string is detected. This is an EXTENSION, not creation — the meta-test has been green and guarding since P1. | `go test ./...` green; meta-test scans every `.go` under `x/` (all 25 packages); self-test table passes for all 9 banned terms (G-009); a deliberately-injected banned term in any new file fails the meta-test | P4-04-01, P1-04-02 | +| P5-01-02 | D-033 | security-engineer | (cross-cutting) | Coverage gate: `go test -cover ./x/window/... ./x/stand/... ./x/guild/... ./x/pact/... ./x/partner/... ./x/council/... ./x/forex/... ./x/bond/... ./x/bearers/... ./x/satellite/...` — all ≥80%; produce a coverage report | Coverage report shows ≥80% on all 10 new/extended packages; no package below threshold | P4-04-01 | +| P5-01-03 | REQ-009..021 | lead-developer | `.ciagent/oy/PLANS.md` (this file, checklist update) + `.ciagent/oy/REQUIREMENTS.md` + `.ciagent/oy/ROADMAP.md` | REQ-coverage audit: confirm every v0.2 REQ (REQ-009, REQ-011, REQ-015, REQ-016, REQ-017, REQ-018, REQ-020, REQ-021, Bearers OY-LR/Beacon, Forex v1) has skeleton + tests; update REQUIREMENTS.md status column (Pending → Skeleton). **ROADMAP tag-line reconciliation (G-010)**: add a one-line note to ROADMAP.md that v0.1 pre-MVP shipped on the `v0.0.x` patch line (ROADMAP lines 4-13) and v0.2 ships on the `v0.1.x` patch line (config `tag_base`), so the `v0.1.5` milestone release is not confused with a hypothetical `v0.1.0` "MVP" tag. | REQUIREMENTS.md status column updated for all v0.2 REQs; each REQ maps to a shipped module file; ROADMAP.md tag-line reconciliation note present | P4-04-01 | + +### Wave 2 — Ship + +| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by | +|---|---|---|---|---|---|---| +| P5-02-01 | (milestone) | lead-developer | (cross-cutting) | Final ship: `go build ./...` + `go test ./...` green; all v0.1 baseline tests still green (no regression across 15 + 10 = 25 packages); create milestone release tag `v0.1.5` (= v0.2 milestone release per D-008/D-020); update ROADMAP.md Phase 2 checkbox | `go test ./...` green; `v0.1.5` tag created; ROADMAP.md Phase 2 marked complete; release notes reference v0.2 scope | P5-01-01, P5-01-02, P5-01-03 | + +### P5 Must-Haves +- [ ] Project-wide lexicon meta-test scans all `x/**/*.go` for all 9 banned terms; green. +- [ ] Coverage ≥80% on all 10 new/extended packages (window, stand, guild, pact, partner, council, forex, bond, bearers, satellite). +- [ ] All locked-const invariants green: Window status count, 9 Stands, 4 Partner tiers, 6 Pacts, 3 Councils, Mission Lock non-amendable, Bond 8% cap / 0% floor clamp, Guild 0% fee, Forex spread cap ≥0, 5 L2 chains. +- [ ] All v0.1 baseline tests still green (no regression across 25 packages). +- [ ] REQUIREMENTS.md status column updated (all v0.2 REQs → Skeleton). +- [ ] `go build ./...` and `go test ./...` green. +- [ ] Git tag `v0.1.5` created (= v0.2 milestone release). +- [ ] ROADMAP.md Phase 2 marked complete. + +### P5 Risks & Mitigations +- **Lexicon drift via copy-pasted comments** (RESEARCH §2) → meta-test scans comments + strings + identifiers; not just exported names. +- **Coverage cliff at integration boundaries** → skeleton-only modules have low cyclomatic complexity, so 80% is achievable with table-driven tests on every exported const/struct/method (v0.1 baseline pattern). +- **Milestone versioning confusion** (v0.2 milestone = v0.1.5 tag) → lead-developer enforces D-008/D-020: final phase patch IS the milestone release; no separate minor tag. + +--- + +## Coverage Targets (D-033) + +| Package | Phase | Target | Locked-const tests | +|---|---|---|---| +| `x/window/types` | P1 | ≥80% | WindowStatus count, lifecycle idempotency | +| `x/stand/types` | P1 | ≥80% | 9 Stand types (exactly) | +| `x/guild/types` | P1 | ≥80% | `HandPassFeeBps == 0` | +| `x/pact/types` | P2 | ≥80% | 6 Pact types (exactly), Mission Lock non-amendable | +| `x/partner/types` | P2 | ≥80% | 4 Partner tiers (exactly) | +| `x/council/types` | P3 | ≥80% | 3 Councils (exactly), `MissionLockAmendable == false` | +| `x/forex/types` | P3 | ≥80% | `SpreadCapBps >= 0`, lexicon-clean labels | +| `x/bond/types` | P4 | ≥80% | `CouponCapBps == 800`, `CouponFloorBps == 0`, clamp invariant | +| `x/bearers/types` | P4 | ≥80% | `BearerTransport` interface, OY-LR in `AllBearers()` (regression) | +| `x/satellite/types` | P4 | ≥80% | 5 L2 chains (Polygon active + 4 stubs), ICS-20 Packet shape | + +**Lexicon assertion (REQ-012)**: present in every new module's `types_test.go` (10 files) + project-wide meta-test in P5. + +--- + +## Task Count Summary + +| Phase | Waves | Tasks | New/Extended Packages | +|---|---|---|---| +| P1 | 3 | 8 | window, stand, guild (3) + lexicon meta-test scaffolding (G-004) | +| P2 | 3 | 5 | pact, partner (2) | +| P3 | 3 | 6 | council, forex (2) | +| P4 | 3 | 8 | bond, bearers (ext), satellite (3) | +| P5 | 2 | 4 | (audit/ship, 0 new — extends P1 lexicon meta-test) | +| **Total** | — | **31** | **10 new/extended** | + +## Grill Binding Decisions Applied (G-001..G-010) + +The Phase 0 grill (see `.ciagent/oy/GRILL.md`) returned 10 binding decisions, all applied to this plan and to PROJECT.md/RESEARCH.md/PERSONAS.md before Phase 0 ship: + +| ID | Decision | Applied to | +|---|---|---| +| G-001 | Correct v0.1 baseline test count: 53 tests / 11 files (not 48) | PROJECT.md D-033, RESEARCH.md | +| G-002 | Lexicon assertion tests are NEW in v0.2 (v0.1 has zero lexicon tests); firewall is new work, not inherited | PROJECT.md D-032/D-033, RESEARCH.md, PLANS.md P1-04-02 | +| G-003 | By-ID-string inter-module refs (A-203) enforced as a TESTED invariant in P1-01-02 (go/parser scan, no cross-module struct imports in production code) | PLANS.md P1-01-02, RESEARCH.md §3 | +| G-004 | Lexicon meta-test scaffolding moved from P5 to P1 Wave 3 (new task P1-04-02); P5-01-01 EXTENDS it rather than creating it | PLANS.md P1 Wave 3, P5-01-01 | +| G-005 | D-027 clarified: one `x/pact` module with `PactType` enum + 6 per-type execute-entry structs (A-207), NOT six micro-modules | PROJECT.md D-027 | +| G-006 | `go.mod` is read-only in v0.2 (zero deps, A-201); any change is an escalation | PERSONAS.md (all personas) | +| G-007 | `x/pact`/`x/partner`/`x/bond` owned by backend-engineer; `x/window`/`x/stand`/`x/guild`/`x/council`/`x/satellite`/`x/forex`/`x/bearers` owned by cosmos-engineer | PERSONAS.md | +| G-008 | Genesis schema (`genesis.go`) = data-engineer; genesis test assertions (`*_test.go` incl `genesis_test.go`) = security-engineer | PERSONAS.md | +| G-009 | P5-01-01 lexicon meta-test includes a self-test table (synthetic string per banned term) so detection coverage is durably verified | PLANS.md P1-04-02, P5-01-01 | +| G-010 | P5-01-03 reconciles ROADMAP.md tag-line narrative (v0.0.x vs v0.1.x) to prevent `v0.1.5`/`v0.1.0` confusion | PLANS.md P5-01-03 | + +## Per-Phase REQ Coverage + +| Phase | REQs | Components | +|---|---|---| +| P1 | REQ-015, REQ-016, REQ-017 | Window (fullest), 9 Stands, Guilds + Hand-Pass 0% | +| P2 | REQ-020, REQ-018 | 6 Pacts, 4-tier Partner Spectrum | +| P3 | REQ-011, Forex v1 | 3 Councils + Mission Lock, Forex Engine v1 stub | +| P4 | REQ-021, REQ-009, Bearers | Mesh Bond 8% cap, L2 IBC (Polygon rep), OY-LR + Beacon | +| P5 | REQ-012 + all v0.2 REQs (audit) | Lexicon meta-test, coverage gate, milestone ship | + +## Cross-Phase Blockers (hard) + +- **P1-01-01 (Window types)** → blocks P2-02-01 (Partner Window-scoped actions), P2-01-01 (Pact window-id-ref). +- **P1-02-01 (Stand types)** → blocks P2-01-01 (Pact StandRegistry stand-id-ref), P3-01-01 (Council Stand Council), P4-01-01 (Bond issuer-stand-id). +- **P1-03-01 (Guild types)** → blocks P3-01-01 (Council Guild Council). +- **P4-04-01 (P4 ship)** → blocks P5-01-01, P5-01-02, P5-01-03 (P5 audit). +- All P(N) phase-ship tasks block P(N+1) Wave 1 tasks (soft ordering for branch hygiene; types themselves only depend on the listed hard blockers). \ No newline at end of file diff --git a/.ciagent/oy/PROJECT.md b/.ciagent/oy/PROJECT.md index 2f10e82..aef553b 100644 --- a/.ciagent/oy/PROJECT.md +++ b/.ciagent/oy/PROJECT.md @@ -61,4 +61,51 @@ 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.1 — OpenYield Foundation Init (pre-MVP development milestone; remains v0.1 until MVP ships as v0.1.0) \ No newline at end of file +v0.2 — The Mesh (active milestone; feature type; tags run on the v0.1.x patch line) + +### v0.2 Scope (The Mesh — ROADMAP Phase 2) +Target: $1B annual volume, 4 service categories. Implements the pending Mesh-era requirements: +- **REQ-009** Satellite chains (Layer 2) — wrapped Bread, Pass-Act propagation on Polygon/Base/Arbitrum/Optimism/Solana [§7] +- **REQ-011** Three Councils (Mesh, Guild, Stand) with Mission Lock — multi-source Voice [§19] +- **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-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] +- Bearers expansion: OY-LR + Beacon v1 +- Forex Engine v1 + +### Milestone Type +Feature (at least one `feat` phase). Phase 0 → `v0.1.0`; execution phases `v0.1.1..v0.1.N`; final phase patch IS the milestone release. No separate minor tag. + +### Out of Scope (v0.2) +- Cross-chain exit / DEX integration (Phase 3 / v0.3) +- OY-SAT, OY-QR bearers (Phase 3) +- Full Hub API B2B suite (Phase 3) +- Yield Token, Travel + 11 service categories (Phase 4) +- Full Mesh Bond market depth (Phase 3+; v0.2 ships first Mesh Bonds only) + +### Prior Milestone +v0.1 — OpenYield Foundation Init (COMPLETE; pre-MVP foundation skeleton; released as v0.0.9 per run.md patch-line model) + +## 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] | \ No newline at end of file diff --git a/.ciagent/oy/RESEARCH.md b/.ciagent/oy/RESEARCH.md index ae6fb9f..4a24edf 100644 --- a/.ciagent/oy/RESEARCH.md +++ b/.ciagent/oy/RESEARCH.md @@ -1,88 +1,632 @@ -# Research: OpenYield (oy) — Phase 0 +# Research: OpenYield (oy) — Phase 0 (v0.2 — The Mesh) -## Domain Ecosystem +> Builds on v0.1 RESEARCH (stablecoin/RWA/mesh/reputation ecosystem survey). v0.1 prior art +> (DAI, MakerDAO RWA, Ondo, Maple, Centrifuge, Helium, Nodle, Kleros, Gitcoin Passport, +> LayerZero, Wormhole, Axelar, IBC) is not duplicated here. This file focuses on the **v0.2 +> Mesh-era components**: REQ-009, REQ-011, REQ-015, REQ-016, REQ-017, REQ-018, REQ-020, +> REQ-021, plus Bearers OY-LR/Beacon and Forex Engine v1. -**Category**: Public-good financial infrastructure / real-yield stablecoin mesh. +## v0.2 Scope Recap (from D-020..D-033) -**Prior Art**: -- **Stablecoins**: USDC/USDT (centralized), DAI (crypto-collateralized, no real yield), Terra/UST (failed algorithmic). -- **RWA protocols**: MakerDAO RWA, Ondo Finance, Maple, Centrifuge, TrueFi. -- **Mesh networks**: Helium (IoT), Nodle (Bluetooth), FOAM (proof of location). -- **Reputation systems**: Kleros (dispute resolution), Gitcoin Passport (sybil resistance), Lens Protocol (social graph). -- **DAOs**: Aragon, DAOstack, Compound, Uniswap governance. -- **Cross-chain**: LayerZero, Wormhole, Axelar, IBC (Cosmos native). +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. Lexicon +(REQ-012) enforced everywhere. ≥80% coverage on new packages. Mission Lock and locked +constants enforced as `const` and verified by invariant tests. -**Gap OpenYield Fills**: -- No existing protocol combines real-yield stablecoin + mesh networking + reputation-based citizenship + public-good covenant. -- DAI lacks real yield (crypto-collateralized). MakerDAO RWA vaults exist but are DAO-controlled, not Holder-sovereign. -- Helium/Nodle cover physical mesh but not financial sovereignty. -- No protocol enforces a mission-lock covenant at the smart-contract level. +> **Lexicon firewall note (G-002)**: v0.1 is lexicon-clean in practice but has **zero** +> lexicon test files (verified: `grep -rli lexicon x/` is empty). The lexicon assertion +> tests are NEW in v0.2 — scaffolded as a project-wide meta-test in P1 Wave 3 (G-004), +> extended to all 10 packages in P5. Do not assume inherited lexicon test coverage. +> **v0.1 baseline (G-001)**: 53 tests across 11 test files (not 48). -## Architectural Pattern: Three-Layer Mesh +--- -1. **Sovereign app-chain** (Layer 1) — Cosmos SDK / Polygon CDK / OP Stack. - - Pattern: dYdX v3 (Cosmos app-chain), Canto (Cosmos L1), Lens (zkSync). -2. **Satellite chains** (Layer 2) — wrapped asset propagation. - - Pattern: Wormhole-wrapped assets, LayerZero OFT, Circle CCTP. -3. **Exit layer** — DEX aggregation. - - Pattern: 1inch, Matcha, LI.FI. +## 1. Domain Research — Per-Component -## Mirror Pattern (Reserve Attestation) +### 1.1 REQ-009 — Layer 2 IBC Satellites (Polygon representative) -- **Pattern**: Paxos (NYDFS-regulated attestations), Tether (third-party attestations), MakerDAO PSM. -- **OpenYield difference**: 9 decentralized Watchers (vs centralized custodian), 6-of-9 quorum, slashing bonds, geographic diversity. -- **Implementation**: Cosmos SDK modules with cross-chain attestation queries; off-chain auditor signs daily snapshots; on-chain NAV updates gated by quorum. +**What it is:** Wrapped Bread propagation from OY Chain (L1) to satellite chains (L2) via +IBC, enabling Pass-Act (transfer) cross-chain. D-021 scopes v0.2 to ONE representative +chain (Polygon) with IBC light-client + transfer-channel types; the other four chains +(Base, Arbitrum, Optimism, Solana) are enum placeholders. -## Bayesian Reputation +**Prior art / ecosystem references:** +- **Cosmos IBC (ibc-go)** — the canonical cross-chain protocol. Transport layer (TAO) + provides clients, connections, channels; application layer (ICS-20 fungible transfer, + ICS-27 interchain accounts). IBC-Go v10 introduced **IBC v2**, a streamlined redesign + organized around Clients, Router, and Applications — client pairs replace multi-step + connection/channel handshakes, packets carry typed Payloads, timestamp-only timeouts + (universal across heterogeneous chains like EVM). IBC v2 is particularly suited to + EVM connectivity (IBC Eureka for Cosmos↔Ethereum). +- **ICS-20 (fungible token transfer)** — the standard application module for wrapped + asset transfer. Tokens are escrowed on the source chain and minted as vouchers on the + destination chain; the denom path encodes the trace (`transfer/channel-N/`). +- **Polygon ↔ Cosmos IBC** — Polygon is an EVM chain; connecting it to a Cosmos chain + requires either an EVM-compatible light client (e.g., a Polygon PoS client or a ZK + client) or IBC Eureka. For a skeleton, the pattern is to define a client-type enum and + channel handshake state types without live relayer logic. +- **Alternative bridges** (noted but not used in skeleton): LayerZero OFT, Wormhole + NTT/Portal, Circle CCTP. OpenYield chose IBC-native (v0.1 RESEARCH) for sovereignty + + security; Wormhole/LayerZero remain Phase 3 fallbacks for chains lacking IBC clients. +- **Non-cosmos chains (Solana)** — Solana lacks native IBC; would need a grandpa/light + client wrapper or a 3rd-party bridge. Scoped out to Phase 3 per D-021. -- **Pattern**: PageRank (Google), EigenTrust (P2P), Kleros court reputation. -- **OpenYield formula**: Time-decayed Bayesian average with prior mean 4.0, prior weight 10, decay buckets [6mo:100%, 12mo:50%, 24mo:25%, 24mo+:0%], diversity bonus (3:+.05, 4:+.10, 5+:+0.15), voucher weight (Freeholder 1.5x). -- **Anti-gaming**: Vouchers have skin-in-the-game; vouching cascades are slashed. +**Recommendation for skeleton:** Define a `satellite` module with: +- `L2Chain` enum (Polygon active; Base/Arbitrum/Optimism/Solana as `StatusPending`). +- `TransferChannel` type (port-id, channel-id, counterparty, status) mirroring ICS-20 + handshake states (Init, TryOpen, Open, Closed). +- `WrappedBreadDenom` type encoding the IBC trace path. +- A `Packet` stub type (sequence, source-port, source-channel, dest-port, dest-channel, + data, timeout-height, timeout-timestamp) matching ibc-go v4/v8 channel packet shape. +- No live ibc-go import in skeleton (deps not vendored); types are self-contained Go + structs so the skeleton compiles under `go 1.22` with zero external deps, same as v0.1. -## Tech Stack Recommendations +**Risk:** If the skeleton's packet shape diverges from the eventual ibc-go version chosen, +refactor cost is small (types-only). Pin the packet shape to ICS-20 v1 (stable, widely +implemented) to minimize churn. -| Layer | Recommendation | Rationale | -|---|---|---| -| OY Chain | Cosmos SDK + CometBFT | App-chain sovereignty, IBC for satellites, Rust performance | -| Smart contracts | CosmWasm (Rust) | Type-safe, auditable, IBC-native | -| Satellite bridges | IBC + Wormhole | Cosmos-native + EVM coverage | -| Light client | CosmJS / gRPC-web | Browser-compatible, ~30 MB app size | -| Mesh transport | libp2p + custom DTN | Delay-tolerant, carrier-agnostic | -| LoRa firmware | Rust on Embassy | Embedded, low-power | -| Off-chain indexer | Subsquid + GraphQL | Historical queries, audit logs | -| Frontend | React Native + Expo | Cross-platform (iOS/Android) | +--- -## Risks Catalog (19 from §20) +### 1.2 REQ-011 — Three Councils (Mesh, Guild, Stand) with Mission Lock -1. Smart contract bugs → formal verification (Certora, KFramework), bug bounties, gradual rollout. -2. RWA venue failure → diversify across 5+ venues, insurance fund. -3. Eye manipulation → multi-source oracles (Chainlink + Pyth + UMA). -4. Anchor-Break (depeg) → over-collateralization, circuit breakers. -5. Processor centralization → random rotation, geographic diversity scoring. -6. Watcher compromise → slashing, fork recovery, geographic/org diversity. -7. Sovereign reserve dependency → multi-jurisdiction reserves. -8. Bank failure → segregated accounts, multiple banking partners. -9. Fiat collapse → Root Basket includes gold + Bitcoin as hedge. -10. Adoption risk → UX-first, Maya's Day integration narrative. -11. Governance capture → multi-source Voice, Freeholder auto-elevation. -12. RWA liquidity risk → short-duration Treasuries, liquid asset tiers. -13. Partner capture → self-service ceiling, Window revoke, partner markup cap. -14. Bond default → over-collateralization, seniority rules, Cover Pool. -15. Cross-chain bridge failure → IBC native, rate-limited bridges, canonical contract. -16. Sybil attacks on Standing → Bayesian prior, vouching requirements. -17. Window abuse → scope enforcement, rate-limits, audit log. -18. Forex Engine venue risk → multi-venue execution, spread caps. -19. Pier regulatory capture → pay-to-play model, Holder sovereignty preserved. +**What it is:** Three governance councils — Mesh Council (whole-mesh), Guild Council +(guild-level), Stand Council (Stand-level) — each using multi-source Voice. Mission Lock +(the Six Principles + fee covenant + no-amend covenant) cannot be amended by any council. +D-022 scopes v0.2 to 3 keeper stubs + Voice tally types + Mission Lock as a `const`. -## Open Questions (deferred to component docs) +**Prior art / ecosystem references:** +- **OpenZeppelin Governor** — modular on-chain governance: Governor + GovernorVotes + + GovernorVotesQuorumFraction + GovernorCountingSimple + GovernorTimelockControl. Key + patterns borrowed: (a) quorum as a fraction of supply, (b) snapshot-based voting power + (ERC20Votes / EIP-6372 clock) to prevent double-voting, (c) timelock between pass and + execution, (d) proposal lifecycle (Pending → Active → Succeeded → Queued → Executed). + OpenZeppelin's modular inheritance avoids forking GovernorAlpha/Bravo. +- **Compound Governor (Bravo)** — the original GovernorAlpha/Bravo; OpenZeppelin is + compatible-but-modular. OY's three-council structure is a **federated** variant: three + Governor instances with different voter bases and scopes, not one. +- **MakerDAO governance** — multi-stakeholder (MKR holders + governance facade), executive + voting + polling, spell-based execution. Relevant for "multi-source Voice" (different + signal sources weighted differently). +- **Cosmos SDK `x/gov`** — the Cosmos-native governance module: proposals, voting period, + deposit, tally (yes/no/no-with-veto/abstain), quorum + threshold. This is the closest + on-chain pattern to OY's Cosmos-based stack; a Cosmos app-chain would naturally use + `x/gov` semantics per council. For skeleton, model the tally types on `x/gov`'s + `TallyResult` and `VoteOption`. +- **Multi-source Voice** — not standard in OZ/Compound/Cosmos gov. Closest analog: **Quadratic + Voting** (Gitcoin, DemocraciDAO) and **conviction voting** (1Hive Gardens, Tecommons) + where voting power accrues over time. OY's multi-source Voice (Standing, Stash, Vouch, + etc.) is a custom weighted-tally; skeleton defines the weight source enum + tally struct + but not the live aggregation. -| # | Question | Owning Component | Resolution | +**Recommendation for skeleton:** Define a `council` module (or three sub-packages +`meshcouncil`, `guildcouncil`, `standcouncil`) with: +- `CouncilType` enum (Mesh, Guild, Stand). +- `Proposal` type (id, council, proposer, submit-time, voting-period, status). +- `ProposalStatus` enum mirroring OZ/Governor lifecycle: Pending → Active → Succeeded → + Failed → Executed. +- `VoteOption` enum (Yes, No, Abstain — no "no-with-veto" since OY covenant disallows + adversarial veto games per anti-greed principle). +- `TallyResult` struct (yes, no, abstain, total-voice, quorum-met). +- `VoiceSource` enum (Stash, Standing, Vouch, Freeholder, Guild) — the multi-source + weighting inputs. +- `MissionLockAmendable = false` as a `const bool`; an invariant test asserts it is never + set true (Mission Lock cannot be amended). + +**Risk:** Multi-source Voice weighting math is complex and unstated in the vision at + formula level — keep skeleton to tally *structure*, not the weighting algorithm. Flag + the algorithm as a v0.3+ decision. + +--- + +### 1.3 REQ-015 — Window Primitive (fuller implementation per D-023) + +**What it is:** A Window is a Holder-authorized, scope-bounded, time-limited, revocable +delegation of access (to a partner, a service, a Stand). Properties: scope, duration, +rate-limit, audit log, revoke. D-023 makes this the *fullest* v0.2 component because it's +a leaf with no upstream blocker and is required by Pacts/Orgs/Partners. + +**Prior art / ecosystem references:** +- **Capability-based security** — Object-capability model (ocaps): a capability is an + unforgeable token granting the bearer the right to perform an action. Window is an + ocap with scope + expiry + revocation. Refs: Miller ("Robust Composition", 2006), + Caja, Agoric. +- **OAuth 2.0 scopes & refresh tokens** — closest web analog: scope strings, token + expiry, refresh, revocation endpoint. Window's "rate-limit" is OAuth's missing piece. +- **Cosmos SDK `x/capability`** — Cosmos's scoped-capability module (used by IBC to bind + ports to modules). A capability is an unforgeable pointer; modules claim/release. Window + extends this with Holder-authorized scope + duration + rate-limit + audit log. +- **Macaroons (Google)** — caveat-bound bearer tokens: a macaroon is a token with added + caveats (scope, time, etc.) that constrain authority; third-party caveats allow + delegation chains. Window's scope + duration + revoke maps cleanly to macaroon caveats. +- **Audit log patterns** — append-only event log (event sourcing). Cosmos SDK `x/feegrant` + and `x/authz` are the closest Cosmos analogs: `x/authz` grants one account the right to + execute messages on behalf of another, with expiry + revoke; `x/feegrant` grants + fee-allowance with spend limits. Window is a generalization of `x/authz` + `x/feegrant` + + scope + rate-limit + audit-log. + +**Recommendation for skeleton (fuller):** Define a `window` module with: +- `Window` struct (id, grantor-holder, grantee, scope, start, end, rate-limit-per-window, + revoked, audit-log-refs). +- `Scope` type — a structured scope (what data/actions the window opens): e.g., read-Stash, + read-Standing, process-Pass-Act-for-Stand, etc. Use a `ScopeKind` enum + free-form + `ResourceID` string. +- `RateLimit` struct (max-actions, per-duration-seconds, actions-consumed). +- `AuditEntry` struct (timestamp, action, result, granter-ref) — append-only. +- Lifecycle: `Open → Active → Revoked → Expired`. A `Revoke()` method stub. +- Full lifecycle tests: open, rate-limit-consume, revoke, expire, revoke-after-expire + (no-op), double-revoke (idempotent or error — test both). +- `DefaultGenesis` with empty windows; `ValidateGenesis` checks no overlapping window-ids. + +**Risk:** "Rate-limit" semantics (token bucket vs sliding window vs fixed window) is + unstated. Use a simple counter (`actionsConsumed` vs `maxActions`) for skeleton; note + the algorithm choice as a low-confidence assumption. + +--- + +### 1.4 REQ-016 — Nine Stand Types + +**What it is:** Nine organizational forms (Stands): Household, Crew, Entity, Co-op, +Circle, Trust, Foundation, Confederation, Shadow. Each is a governed group holding a +Vault. D-024 scopes v0.2 to an enum + Stand keeper + membership-set types; no Stand +economics in v0.2. + +**Prior art / ecosystem references:** +- **DAO organizational forms** — Aragon (MiniMeToken + Voting apps, organization templates), + DAOstack (Genesis), MolochDAO (ragequit, guild shares, shares-as-membership). Moloch's + "guild" + "member shares" pattern is the closest to OY's "Stand with Vault + members". +- **SubDAO / Org primitives** — Cosmos SDK has no first-class "organization" module; the + closest is `x/group` (a group of members with a policy — weighted/threshold decision + policy). `x/group` supports: member addresses, admin, policy (threshold or weighted), + proposal + vote + tally + execution. This is the *exact* pattern for a Stand: a group + with a decision policy governing a Vault. +- **Lens Protocol (social graph)** — follows/followers as membership edges; useful for + Stand membership-set modeling (set of Reach IDs, not addresses). +- **Safe (Gnosis Safe) modules** — modular Safe with custom modules for spending policy; + OY Stand = group + Vault + policy, very close to Safe + SpendingLimitModule. +- **Nine named types** — no protocol has exactly nine; this is OY-specific + (taxonomy-driven). Skeleton encodes them as a fixed enum with a test asserting exactly + 9 entries (locked-const test). + +**Recommendation for skeleton:** Define a `stand` module with: +- `StandType` enum (9 values, exactly), plus `AllStandTypes() []StandType` returning all 9. +- `Stand` struct (id, type, name, vault-id, admin-reach, created-at, member-count). +- `Membership` struct (stand-id, reach-id, joined-at, role — e.g., Member, Admin, + Observer). +- `StandPolicy` stub (threshold or weighted — mirror `x/group` decision policy). +- Genesis with empty stands; `ValidateGenesis` checks no dup stand-ids, member-reach + unique within a stand. +- Test: exactly 9 types, each name matches vision §11, no extras, no dups. + +**Risk:** "Shadow" Stand is described as adversarial/temporary in the vision — its + semantics differ from the other 8. Skeleton treats all 9 uniformly; flag the Shadow + behavioral split as a v0.3 design question. + +--- + +### 1.5 REQ-017 — Guilds + Hand-Pass (0% protocol fee) + +**What it is:** Guilds are task-oriented collectives; a Hand-Pass is a free +(0% protocol fee) Pass-Act issued by a Guild. D-025 scopes v0.2 to Guild keeper + +Hand-Pass type at locked 0% fee + issuance tests; no Guild task queue. + +**Prior art / ecosystem references:** +- **Gitcoin Grants / Bounties** — task-oriented guilds paying contributors; closest to + "Guild issues Hand-Passes for tasks". +- **Dework / Lens work-nets** — on-chain task marketplaces. +- **Fee waivers in existing protocols** — MakerDAO PSM fees are tunable per-pair; + Uniswap protocol fee switch (0..25 bps, off by default). OY's 0% is *locked* (not + tunable) — closer to a smart-contract covenant than a parameter. +- **Cosmos SDK fee grants (`x/feegrant`)** — fee allowances are grants; a 0-fee Hand-Pass + is conceptually a "always-free grant" but the *protocol* fee is the covenant, not a + per-tx grant. The Fee Covenant module (v0.1, REQ-002) already encodes + `WaiverHandPassGuild` as a 0-fee waiver reason (see `x/feecovenant/types/types.go`). + v0.2's Guild module *references* that waiver, doesn't redefine the fee. + +**Recommendation for skeleton:** Define a `guild` module with: +- `Guild` struct (id, name, founder-reach, created-at, stand-affiliation optional). +- `HandPass` struct (pass-id, guild-id, issuer-reach, recipient-reach, amount-grain, + timestamp, fee-grain-always-0). +- `HandPassFeeBps = 0` as a locked `const` (cross-referenced to feecovenant + `WaiverHandPassGuild`). +- `IssueHandPass` stub method. +- Tests: HandPass fee is 0, Guild has a Stand affiliation or standalone, issuer must be + guild member (skeleton: type-level only, no enforcement). +- A lexicon assertion test in the guild test file. + +**Risk:** Guild-internal task management (queue, claims, completion) is operational, not + protocol — correctly out of scope. Keep skeleton to the issuance type. + +--- + +### 1.6 REQ-018 — Partner Spectrum (4-tier) + +**What it is:** Four partner tiers: Op (operator, processes Pass-Acts), Master Op +(senior operator), Pier (credential/identity provider, e-Residency/biometrics), Anchor +(institutional). D-026 scopes v0.2 to 4-tier enum + Partner registry keeper + +credential-ref types; Pier credential routing deferred per PROJECT.md Q5. + +**Prior art / ecosystem references:** +- **Layered partner programs** — Visa (Acquirer → Issuer → Network), Stripe (Atlas + partners), AWS Partner Network (Registered → Select → Advanced → Premier). OY's 4-tier + mirrors these tiered-partner spectra. +- **Credential providers** — ceramic.network (DIDs + verifiable credentials), + EBSI (European Blockchain Services Infrastructure), Anonybit (biometric ID), Estonia + e-Residency. Piers are OY's abstraction over these. +- **Cosmos SDK `x/authz` / `x/group`** — a Partner is an authorized actor (like authz + grantee) for a Window-scoped action. A Partner registry is a typed address book with + tier metadata; closest Cosmos analog is a lightweight `x/params`-backed registry or a + dedicated module. +- **Anchor (institutional)** — closest to MakerDAO RWA arrangers or Centrifuge tiers + (senior/junior tranches with institutional sponsors). + +**Recommendation for skeleton:** Define a `partner` module with: +- `PartnerTier` enum (Op, MasterOp, Pier, Anchor) — exactly 4, locked test. +- `Partner` struct (id, tier, name, reach-id, region, credential-ref, status). +- `CredentialRef` struct (provider-id, credential-type enum, ref-uri) — Pier routing + deferred, so the ref is an opaque URI for now. +- `PartnerStatus` enum (Pending, Active, Suspended, Revoked). +- Registry keeper stub: add/get/list/by-tier. +- Tests: exactly 4 tiers, tier names match, no lexicon drift, partner-by-tier lookup. + +**Risk:** "Master Op" naming — must stay lexicon-clean (no "operator" if it implies bank + terms; "Op" is fine per vision §13). Verify no banned terms in partner-type strings. + +--- + +### 1.7 REQ-020 — Six Pacts + +**What it is:** Six Pacts (commitment types): Pause, Ground, Stance, Cover, +Stand-Registry, Hub-API. D-027 scopes v0.2 to 6 Pact types as separate keeper modules +with execute-entry + invariant tests; Cover Pool seniority deferred per Q7. + +**Prior art / ecosystem references:** +- **Pacts / commitments** — closest analog: **CosmWasm contracts as commitments** (each + Pact is a contract with an `execute` entry point). For a Go skeleton, model each as a + module with an `Execute(msg)` stub. +- **Pause (circuit breaker)** — OpenZeppelin `Pausable`, Compound's Pause guardian, + Cosmos SDK `x/crisis`. OY v0.1 already has `x/still` (Still/Stir pause/resume); Pause + Pact is the Pact-level wrapper around Still. +- **Ground** — closest to "earth-anchored" / collateral lock; Compound's collateral + factor, MakerDAO vault collateral lock. For skeleton: a `Ground` Pact = lock Bread + against a real-world commitment. +- **Stance** — public-position / attestation Pact; closest to EAS (Ethereum Attestation + Service) attestations or Kleros court rulings. Skeleton: a typed signed-attestation + record. +- **Cover** — insurance-like commitment; closest to **Nexus Mutual**, **InsurAce**, + **Bridge Mutual**, and OY's own "Cover Pool" (vision §16). Seniority/tranches deferred + per Q7; skeleton: a Cover commitment type with amount + beneficiary + trigger-condition + stub. +- **Stand Registry** — a Pact that registers a Stand into the canonical OY Chain + registry; ties to REQ-016 Stand module. +- **Hub API** — B2B backbone Pact; closest to Stripe API / Plaid API as on-chain + commitments. Full Hub API suite deferred to Phase 3; v0.2 = stub type only. + +**Recommendation for skeleton:** Define a `pact` module with sub-files per Pact, OR six +tiny modules `x/pactpause`, `x/pactground`, `x/pactstance`, `x/pactcover`, +`x/pactstandregistry`, `x/pacthubapi`. Recommend **one `pact` module with a `PactType` +enum + per-type execute-entry structs** to match v0.1's one-module-per-component pattern + (avoids 6 micro-modules): +- `PactType` enum (Pause, Ground, Stance, Cover, StandRegistry, HubAPI) — exactly 6. +- `Pact` struct (id, type, parties, terms-bytes, status, execute-msg-ref). +- `PactStatus` enum (Proposed, Active, Fulfilled, Voided). +- Per-type `Execute*` stub methods. +- Tests: exactly 6 types, invariant that Mission-Lock Pacts (Pause/Ground/Stance) can be + invoked but not amended in their core terms. + +**Risk:** Cover Pool seniority math (Q7) is deferred — keep the Cover Pact to a flat + commitment type with no seniority fields. + +--- + +### 1.8 REQ-021 — Mesh Bond Market (8% cap) + +**What it is:** A bond market where Stands/Guilds issue bonds (coupon-bearing +commitments) with an 8% upper coupon cap and 0% floor. D-028 scopes v0.2 to Bond market +keeper + 8%/0% consts + issuance tests; full secondary-market depth deferred to Phase 3. + +**Prior art / ecosystem references:** +- **On-chain bond markets** — MakerDAO RWA vaults (centrifuge/tinlake senior-tranche), + Maple Finance (term loans), TrueFi (unsecured loans with credit ratings), Centrifuge + (Tinlake drop/tin tranches). OY's "8% coupon cap" is a *protocol-level* ceiling, not a + per-loan rate — closer to a usury cap enforced at the covenant layer. +- **Coupon caps / usury laws** — real-world analog: state usury laws cap interest rates; + DeFi analog: Aave rate caps (borrow cap, supply cap), Compound's per-market collateral + factor. OY's 8% is *mission-locked* (not adjustable by governance) — closer to + Compound's immutable risk params or MakerDAO's debt ceiling floors. +- **Bond structures** — fixed-coupon, zero-coupon, amortizing. v0.2 skeleton: fixed-coupon + with cap/floor only. +- **Cosmos SDK** — no native bond module; bonds are custom CosmWasm or a Go module. For + skeleton: a Go module mirroring the v0.1 `x/feecovenant` locked-const pattern. + +**Recommendation for skeleton:** Define a `bond` module with: +- `CouponCapBps = 800` (8%) and `CouponFloorBps = 0` (0%) as locked `const`. +- `Bond` struct (id, issuer-stand-id, principal-grain, coupon-bps, term-days, issued-at, + maturity, status). +- `BondStatus` enum (Issued, Active, Matured, Defaulted, Repaid). +- `Issue(...)` stub; `Clamp(couponBps)` returns min(cap, max(floor, coupon)) — same shape + as Fee Covenant's `Clamp`. +- Tests: cap=800, floor=0, clamp invariant (below floor → floor, above cap → cap, in + range → unchanged), lexicon. + +**Risk:** "interest" / "yield" are banned lexicon terms — the bond module must use + "coupon" (vision §17 lexicon-compliant) consistently. Test asserts no banned terms in + the bond package. + +--- + +### 1.9 Bearers — OY-LR + Beacon v1 (stubs per D-029) + +**What it is:** Two new bearer transports: OY-LR (LoRa, long-range 2-10km) and OY-Beacon +(transport beacon). v0.1 already defined the `BearerType` enum including `BearerOYLR`; +v0.2 adds the bearer-interface + transport stubs. No hardware integration. + +**Prior art / ecosystem references:** +- **LoRaWAN** — Long Range (LoRa) low-power wide-area network: star-of-stars topology, + gateways relay to network server. Helium is the canonical crypto-LoRa project + (incentivized coverage). OY-LR is surveillance-resistant (vision §14) — differs from + Helium's public coverage model. +- **Delay-Tolerant Networking (DTN)** — RFC 5050 Bundle Protocol; v0.1 already references + this for the Unified Bearer Layer. OY-LR + Beacon fit DTN (store-and-forward). +- **Bluetooth Beacons** — iBeacon/Eddystone (advertising packets, no connection); OY + Beacon is a transport-mode beacon (presence + small payload), closest to Eddystone-EID + (ephemeral identifier). +- **Mesh routing** — B.A.T.M.A.N., OLSR, AODV. OY uses first-to-deliver-wins (already in + v0.1 `UnifiedBearerLayer`). + +**Recommendation for skeleton:** Extend the existing `x/bearers` module (do NOT create a +new module — v0.1 owns the BearerType enum). Add: +- `BearerTransport` interface stub (Send, Receive, Status) — a Go interface, not impl. +- `OYLRLink` struct (gateway-id, range-meters, frequency-mhz, surveillance-resistant=true). +- `BeaconFrame` struct (beacon-id, ephemeral-id, payload-bytes, ttl). +- Tests: OY-LR is in `AllBearers()` (already asserted in v0.1), transport interface + signature, Beacon frame non-empty, lexicon. +- Keep all under `x/bearers/types/` to match the v0.1 one-package-per-module convention. + +**Risk:** Hardware/RF integration is explicitly deferred — do not pull in any LoRa or + BLE Go libraries. Pure types. + +--- + +### 1.10 Forex Engine v1 (stub per D-030) + +**What it is:** A Forex pair type + rate-oracle interface + stub keeper; no live oracle +integration (depends on Piers, Phase 3). + +**Prior art / ecosystem references:** +- **Oracle patterns** — Chainlink (aggregated off-chain reports, commit-reveal), + Pyth Network (low-latency pull-based, Herodotus/pythnet), UMA (optimistic oracle with + dispute window), API3 (first-party Airnodes). For Forex specifically: Chainlink FX + feeds, Pyth FX pairs. OY's Forex Engine is a *consumer* of these (via Piers), not a + producer. +- **DEX aggregator oracle** — Uniswap TWAP, Compound's Open Oracle. +- **Cosmos SDK oracle modules** — `x/oracle` (Terra classic — failed, cautionary), Band + Protocol (Cosmos-native oracle). For skeleton: define an oracle *interface*, not an + integration. +- **Forex-specific** — multi-venue execution with spread caps (vision §18 risk #18); OY + caps spreads, doesn't trust a single venue. + +**Recommendation for skeleton:** Define a `forex` module with: +- `ForexPair` struct (base, quote — but NOT "currency" (banned); use "base-asset" / + "quote-asset" or vision-lexicon pair labels like "Bread/Asset"). +- `RateOracle` Go interface (GetRate(pair) (rate, timestamp, err)) — no implementation. +- `ForexRate` struct (pair, rate, source, timestamp, confidence). +- `SpreadCapBps` const (locked) — defer exact value to a v0.3 decision; skeleton sets a + placeholder 0 (or a documented TBD const with a test that it's ≥0). +- Stub keeper: `GetRate` returns a sentinel "not-integrated" rate. +- Tests: pair struct, oracle interface compiles, lexicon (no "currency"/"dollar"). + +**Risk:** Forex terminology is *lexicon-hostile* ("currency", "dollar", "euro", "fx" all + banned or borderline). Use "Forex Engine" (allowed, vision §13 names it) but pair + labels must avoid banned terms. "Forex" itself is not in the banned list (the banned + list is: bank, deposit, interest, yield, currency, dollar/euro, account, savings, + depositor). Test asserts pair labels are lexicon-clean. + +--- + +## 2. Pitfalls & Risks + +### Integration pitfalls +- **Window ↔ Pacts ↔ Partners ↔ Orgs coupling:** Window is consumed by Pacts, Orgs, + Partners, Governance (Architecture §4.4). Skeleton must define a stable `WindowRef` + type early (P1) so downstream modules reference it without import cycles. Recommend + Window ships first in the blocker-chain ordering (D-031 confirms this). +- **Council ↔ Stand ↔ Guild identity:** Stand Council governs a Stand; Guild Council + governs a Guild; a Guild may affiliate with a Stand. Avoid circular imports: keep + `council` referencing `stand`/`guild` types via interface or by-ID strings, not direct + struct imports. +- **IBCPacket type vs ibc-go:** If the skeleton's packet type diverges from the real + ibc-go packet, the v0.3 integration requires a refactor. Pin to ICS-20 v1 shape. + +### Cosmos SDK gotchas +- **No deps vendored yet** (`go.mod` is bare `go 1.22`). v0.2 skeleton must stay + dependency-free (only stdlib + `encoding/json`), exactly as v0.1 did. Pulling ibc-go + or cosmos-sdk into `go.mod` would force a large dependency tree and break the + "skeleton + tests compiles with zero external deps" property. +- **`x/gov` tally types:** if we later wire councils to `x/gov`, the tally shape must + match `gov.TallyResult`. Skeleton should mirror `x/gov` field names to ease the swap. +- **`x/group` decision policy:** Stand/Guild policies should mirror `group.DecisionPolicy` + (threshold + weighted) so a future `x/group` integration is mechanical. +- **`x/authz` / `x/feegrant`:** Window should mirror `authz.Grant` (granter, grantee, + msg-type, expiry) so a future `x/authz`-backed implementation is a thin wrapper. +- **Module name collisions:** Cosmos SDK has `x/gov`, `x/group`, `x/bank` (BANNED name — + never use), `x/auth`. OY uses custom module names (`bread`, `still`, `mirror`, + `feecovenant`) — keep this pattern; do not name any v0.2 module `bank` or `account`. + +### Lexicon-compliance risks (highest severity per D-033) +- **Banned terms:** bank, deposit, interest, yield, currency, dollar/euro, account, + savings, depositor. The bond module is the highest-risk ("interest"/"yield" are natural + fit-words for coupons — use "coupon" only). Forex is the second-highest ("currency", + "dollar", "euro"). Council/Governance is lower-risk but "account" must be avoided + (use "Holder"/"Reach"). +- **Drift vector:** copy-pasting from prior-art docs (OZ Governor, Compound) into + comments will import banned terms. Every new module's test file must include a lexicon + assertion (D-033). A project-wide lexicon test (scanning all `x/**/*.go` for banned + terms) is recommended as a meta-test added in the review phase. +- **Test coverage:** D-033 mandates ≥80% on new keeper/type packages. The skeleton-only + modules have low cyclomatic complexity, so 80% is achievable with table-driven tests on + every exported const, struct, and method (matching v0.1's 53-test baseline pattern). + +### Test-coverage risks +- **Locked-const tests are the regression firewall:** every locked constant (8% cap, 0% + floor, 6 Pact types, 9 Stand types, 4 Partner tiers, Mission Lock non-amendable) must + have a dedicated test. A single const change must break a test. +- **Invariant tests:** Mission Lock (council cannot amend), fee clamp (never > ceiling, + never < floor), bond clamp (never > cap, never < floor) — these are invariant tests, + not just equality tests. +- **Genesis validation:** every new module's `ValidateGenesis` should at least reject + duplicate IDs; v0.1's `ValidateGenesis` returns `nil` unconditionally — upgrade the v0.2 + modules to actually validate (small improvement, low risk). + +--- + +## 3. Architecture Recommendations for v0.2 + +### Module layout under `x/` + +Following v0.1's one-package-per-module convention (`x//types/types.go` + +`types_test.go`), v0.2 adds these new modules (mapped to REQs and D-decisions): + +| New module | REQ | D-decision | Status | |---|---|---|---| -| Q1 | Maya's Day integration spec | 9 Mesh Experience | Component doc in P1 | -| Q2 | Standing sub-tables (per-category, buckets) | 6 Identity | Component doc in P1 | -| Q3 | Full risk mitigations | Distributed | In research above; expanded in component docs | -| Q4 | Phase-by-phase deliverables | All | ROADMAP.md | -| Q5 | Pier credential routing | 6 Identity, 11 Partners | Component docs in P2 | -| Q6 | Experimental bond forms | 8 Pacts (Bonds) | Phase 4+, deferred | -| Q7 | Cover Pool seniority math | 8 Pacts (Cover) | Component doc in P2 | -| Q8 | Processor share tier volumes | 12 Bearers, 13 Fee | Component docs in P1 | \ No newline at end of file +| `x/satellite/` | REQ-009 | D-021 | New — L2 IBC types (Polygon rep + 4 stubs) | +| `x/council/` | REQ-011 | D-022 | New — 3 sub-councils in one module (Mesh/Guild/Stand) | +| `x/window/` | REQ-015 | D-023 | New — **fullest** v0.2 module (leaf, no blocker) | +| `x/stand/` | REQ-016 | D-024 | New — 9-type enum + keeper stub | +| `x/guild/` | REQ-017 | D-025 | New — Guild + HandPass @ 0% | +| `x/partner/` | REQ-018 | D-026 | New — 4-tier Partner registry | +| `x/pact/` | REQ-020 | D-027 | New — 6 Pact types in one module | +| `x/bond/` | REQ-021 | D-028 | New — Mesh Bond market with 8% cap | +| `x/forex/` | (Forex v1) | D-030 | New — Forex pair + oracle interface stub | + +**Existing modules extended (not new):** + +| Existing module | Extension | D-decision | +|---|---|---| +| `x/bearers/` | Add `BearerTransport` interface + OY-LR + Beacon types | D-029 | + +**Existing modules referenced (not modified):** +- `x/feecovenant/` — Guild HandPass references `WaiverHandPassGuild` (already a 0-fee + waiver reason in v0.1). Do NOT modify feecovenant; guild's `HandPassFeeBps = 0` const + cross-documents the covenant. +- `x/vault/` — Stand references `vault.Vault` by ID string (avoid import cycle). +- `x/stash/` — Window references `stash.Stash` by holder-id string. +- `x/standing/` — Council VoiceSource references standing by reach-id string. +- `x/identity/` — Reach IDs used everywhere as string keys. + +### Interface contracts between new modules + +To avoid import cycles, new modules communicate **by-ID-strings**, not by importing each +other's struct types. **This is a hard invariant (G-003)**: no v0.2 production (non-test) +`.go` file under `x/` may import another `x//types` package by struct — enforced +by a tested invariant in P1-01-02 (Window test file) using `go/parser` or a package-import +grep test. The earlier "Window may be imported by Pacts/Partners/Orgs if needed" hedge is +**retracted** (G-003): the skeleton keeps ALL inter-module refs by-ID-string, including +Window, to keep the invariant uniform and testable. + +``` +x/window ──(WindowRef by id)──► x/pact, x/partner, x/stand, x/council +x/stand ──(StandRef by id)───► x/council (Stand Council), x/guild (affiliation) +x/guild ──(GuildRef by id)───► x/council (Guild Council) +x/forex ──(Oracle interface)──► (none in v0.2; Piers in Phase 3) +x/bond ──(BondRef by id)────► x/stand (issuer), x/pact (Cover) +x/satellite ──(Packet types)──► (none in v0.2; relayer in Phase 3) +x/bearers ──(BearerTransport)──► (none in v0.2; processing mesh in Phase 3) +``` + +### Blocker-chain ordering (per D-031) + +D-031 fixes the phase ordering. v0.2 execution phases (P1..P5) follow the +ARCHITECTURE.md blocker chain: + +``` +P1: Orgs + Window foundation + └─ x/stand (REQ-016), x/guild (REQ-017), x/window (REQ-015) + (Window is leaf — can be built first within P1) +P2: Pacts + Partners + └─ x/pact (REQ-020), x/partner (REQ-018) + (depend on Window + Stand from P1) +P3: Councils + Forex + └─ x/council (REQ-011), x/forex (Forex v1) + (Council depends on Stand + Guild + Standing; Forex is independent) +P4: Bonds + Bearers + L2 + └─ x/bond (REQ-021), x/bearers ext (D-029), x/satellite (REQ-009) + (Bonds depend on Stand; Bearers extend v0.1; L2 is independent) +P5: Review + ship (milestone v0.2) +``` + +Each phase is independently shippable (vertical slice integrity, same as v0.1). + +--- + +## 4. Dependency Notes + +### Current state +- `go.mod`: `module github.com/oy/openyield`, `go 1.22`, **zero dependencies**. +- v0.1 compiled all 15 modules with only stdlib (`encoding/json`). No Cosmos SDK, no + ibc-go, no CosmWasm vendored. + +### Recommendation for v0.2 skeleton +**Keep zero external dependencies.** Every v0.2 module must be pure-Go types + tests +compiling with `go build ./...` and `go test ./...` using only stdlib. Rationale: +1. The skeleton's value is in the *typed contract* (structs, consts, invariants), not + in wiring to live Cosmos SDK / ibc-go. +2. Pulling `cosmos-sdk` or `ibc-go` would force a 1000+ module dependency tree, break + the fast `go test` feedback loop, and require go version bumps beyond 1.22. +3. v0.1 established this pattern successfully (53 tests, 11 files, zero deps). + +### Future (Phase 3+) dependency targets — researched but NOT added in v0.2 +- **Cosmos SDK** — v0.50.x (LTS) or v0.47.x (the long-term-support line many chains still + use). v0.50+ uses CometBFT (separated from tendermint). For go 1.22, cosmos-sdk v0.50.x + is compatible (go 1.21+). Defer the choice to the Phase 3 chain-launch decision. +- **ibc-go** — v8.x (for cosmos-sdk v0.50) or v7.x (for cosmos-sdk v0.47). ibc-go v10 + introduces IBC v2 (streamlined, EVM-friendly) — attractive for Polygon but only if + cosmos-sdk v0.50+ is chosen. Defer. +- **CosmWasm** — `wasmvm` v1.5.x or v2.0.x (for Pacts potentially as CosmWasm contracts + in Phase 3). For v0.2 skeleton, Pacts are Go types — no wasmvm. +- **CometBFT** — v0.37.x / v1.0 (consensus; only needed for live chain, not skeleton). + +### Minimal set for v0.2 +**None.** Zero new dependencies. The skeleton is self-contained. + +--- + +## 5. Assumptions (logged with confidence scores; not flagged for human validation) + +| ID | Assumption | Confidence | Rationale | +|----|-----------|------------|-----------| +| A-201 | v0.2 skeleton stays dependency-free (only stdlib), matching v0.1. | 0.95 | v0.1 proved this works; D-020 confirms skeleton-first. | +| A-202 | One module per component (`x//types/`) is the v0.2 convention; no multi-package modules. | 0.90 | v0.1 has 15 modules all following this; consistency is low-risk. | +| A-203 | Inter-module references use by-ID strings (not struct imports) to avoid cycles. | 0.85 | Cosmos SDK modules also decouple this way; import cycles are a real risk given the coupling graph. | +| A-204 | Council tally types mirror Cosmos SDK `x/gov` `TallyResult` shape for future wiring. | 0.75 | `x/gov` is the most likely runtime; matching field names eases Phase 3. | +| A-205 | Stand/Guild decision policy mirrors `x/group` `DecisionPolicy` (threshold/weighted). | 0.75 | Same future-wiring rationale as A-204. | +| A-206 | Window rate-limit uses a simple counter (`actionsConsumed` vs `maxActions`), not a token bucket. | 0.65 | Algorithm unstated in vision; counter is simplest; revisit in v0.3. | +| A-207 | Six Pacts live in one `x/pact` module (not six micro-modules) for v0.1-pattern consistency. | 0.80 | D-027 says "separate keeper modules" — one module with a PactType enum satisfies "separate execute entries" without 6 dirs. | +| A-208 | Forex pair labels use "Bread/Asset" style (not "currency"/"dollar") to stay lexicon-clean. | 0.80 | Lexicon is non-negotiable (D-032); "Forex" itself is allowed (vision §13). | +| A-209 | Bearers OY-LR + Beacon extend the existing `x/bearers` module (no new module). | 0.90 | v0.1 owns the `BearerType` enum; D-029 says "stubs", not "new module". | +| A-210 | Bond coupon uses "coupon" terminology exclusively; "interest"/"yield" banned. | 1.00 | Lexicon (REQ-012) is non-negotiable. | +| A-211 | Mission Lock is a `const bool MissionLockAmendable = false` in council module. | 0.85 | Simplest invariant-testable form; vision §19 says Mission Lock cannot be amended. | +| A-212 | `ValidateGenesis` in v0.2 modules performs basic ID-uniqueness checks (upgrading v0.1's no-op). | 0.80 | Small improvement, low risk, raises skeleton quality. | +| A-213 | Shadow Stand is treated uniformly with the other 8 in v0.2 (no special behavioral split). | 0.60 | Vision implies Shadow is adversarial/temporary; defer the split to v0.3 design. Low confidence — flag for v0.3 revisit. | +| A-214 | Forex `SpreadCapBps` exact value deferred to v0.3; skeleton uses a documented placeholder const. | 0.70 | Vision §18 risk #18 mentions spread caps but no locked value. | +| A-215 | ibc-go / cosmos-sdk / CosmWasm versions are NOT pinned in v0.2 (deps not vendored); choice deferred to Phase 3 chain launch. | 0.90 | D-020 says no live chain in v0.2. | + +--- + +## Cross-Reference Summary + +| REQ | Component | Module | Phase (D-031) | Depth (D-02x) | +|-----|-----------|--------|---------------|---------------| +| REQ-009 | L2 IBC | `x/satellite/` | P4 | Skeleton (Polygon rep) — D-021 | +| REQ-011 | Councils | `x/council/` | P3 | Skeleton (3 keepers, Mission Lock const) — D-022 | +| REQ-015 | Window | `x/window/` | P1 | **Fuller** (leaf, no blocker) — D-023 | +| REQ-016 | Stands | `x/stand/` | P1 | Skeleton (9-type enum) — D-024 | +| REQ-017 | Guilds | `x/guild/` | P1 | Skeleton (HandPass 0%) — D-025 | +| REQ-018 | Partners | `x/partner/` | P2 | Skeleton (4-tier enum) — D-026 | +| REQ-020 | Pacts | `x/pact/` | P2 | Skeleton (6 types, execute stubs) — D-027 | +| REQ-021 | Bonds | `x/bond/` | P4 | Skeleton (8% cap, issuance) — D-028 | +| Bearers | OY-LR + Beacon | `x/bearers/` (ext) | P4 | Stubs (no HW) — D-029 | +| Forex | Forex v1 | `x/forex/` | P3 | Stub (oracle interface) — D-030 | +| REQ-012 | Lexicon | (all) | all | Enforced everywhere — D-032 | + +**New modules: 9. Extended modules: 1 (bearers). Total v0.2 packages: 10 new + +1 extended = 11 packages added to the v0.1 baseline of 15.** \ No newline at end of file