# OpenYield Spec — spec-v1
Owner: <product owner>
Status: draft
Ingested as: oy-spec

> This is the **only** document the product owner (PO) sends to the ciagent for
> implementation. The ciagent consumes it to regenerate PROJECT.md,
> REQUIREMENTS.md, and ARCHITECTURE.md. Nothing else is read from upstream.
>
> In return the ciagent maintains **one** sibling file — `oy-state` — that tells
> the PO what exists, what's locked, what's deferred, and what drift exists
> between this spec and the shipped code. Read `oy-state` before editing
> `oy-spec`; it prevents re-proposing shipped or explicitly-deferred REQs.
>
> `oy-spec` and `oy-state` are the only two docs that cross the PO<->ciagent
> boundary. All other `.ciagent/oy/*.md` files are ciagent-internal working
> memory — do not edit them.

## 1. Objective
<!-- <=3 sentences: what the mesh is and who it serves -->

## 2. Vision source
- Document: Vision v3.0 (22 sections)
- Locked commitments (non-amendable sections):
  <!-- list section numbers that are non-amendable -->

## 3. Principles [locked]
1. Real value
2. Sustainability
3. Mission-lock
4. Openness
5. Ownership
6. Self-service
<!-- one line per principle — the ciagent enforces these as REQ-001 -->

## 4. Requirements
<!-- Each row: ID | Title | Vision § | Priority | Locked? | Acceptance criteria -->
| ID | Title | Vision § | Priority | Locked? | Acceptance criteria |
|----|-------|----------|---------|---------|---------------------|
| REQ-001 | Enforce Six Principles | §2 | High | yes | <!-- criteria --> |
| REQ-002 | Fee ceiling 0.1% / floor 0.01% / 1-Grain min | §18 | High | yes | <!-- criteria --> |
| REQ-003 | Bloom from real production only (Root Basket) | §6 | High | yes | <!-- criteria --> |
| REQ-004 | 9 Watchers, 6-of-9 quorum | §7 | High | yes | <!-- criteria --> |
| REQ-005 | Four Freeholder signals | §9.1 | High | yes | <!-- criteria --> |
| REQ-006 | Standing anti-gaming formula | §9.2 | High | yes | <!-- criteria --> |
| REQ-007 | FCFS processing | §15 | High | yes | <!-- criteria --> |
| REQ-008 | OY Chain (Layer 1) | §7 | High | yes | <!-- criteria --> |
| REQ-009 | Satellite chains (Layer 2) | §7 | Medium | no | <!-- criteria --> |
| REQ-010 | Exit layer (Layer 3) | §7 | Medium | no | <!-- criteria --> |
| REQ-011 | Three Councils with Mission Lock | §19 | High | yes | <!-- criteria --> |
| REQ-012 | Lexicon compliance | §3 | High | yes | <!-- criteria --> |
| REQ-013 | Bread unit with scale | §4 | High | yes | <!-- criteria --> |
| REQ-014 | Three pools of storage | §5 | High | yes | <!-- criteria --> |
| REQ-015 | Window primitive | §10 | High | no | <!-- criteria --> |
| REQ-016 | Nine Stand types | §11 | Medium | yes | <!-- criteria --> |
| REQ-017 | Guilds with free Hand-Passes | §12 | Medium | yes | <!-- criteria --> |
| REQ-018 | Four-tier Partner Spectrum | §13 | Medium | no | <!-- criteria --> |
| REQ-019 | Six bearers via Unified Bearer Layer | §14 | Medium | yes | <!-- criteria --> |
| REQ-020 | Six Pacts | §16 | Medium | no | <!-- criteria --> |
| REQ-021 | Mesh Bond Market with 8% cap | §17 | Medium | yes | <!-- criteria --> |

## 5. Constraints
- 14 modular components, 6 cross-component interfaces
- Mission Lock non-amendable
- Lexicon firewall: banned terms = bank, deposit, interest, yield, currency, dollar/euro, account, savings, depositor
- Skeleton-first until mainnet gate (D-020 pattern)
- Zero Go deps except GRILL-approved runtime exceptions
- Coverage >=80% on shipped packages
- Multi-project mode active; project slug = `oy`

## 6. Lexicon [locked]
- Banned: bank, deposit, interest, yield, currency, dollar, euro, account, savings, depositor
- Required replacements: account -> Reach, deposit -> receive-asset, interest -> coupon, yield -> bloom, currency -> asset

## 7. Milestone intent
- Current shipped: v0.6 (Nomad Web UI) — COMPLETE
- Next: <!-- v0.7 target — one paragraph + the REQ-IDs it draws from -->
- Out-of-scope this milestone:
  <!-- list -->

## 8. Open questions for the ciagent
<!-- bulleted; the ciagent logs assumptions if unanswered at autonomy=full -->

## 9. Changelog
<!-- Every spec revision MUST be a `docs(spec):` commit (see Rules below). -->
| Spec-v | Date | Commit (docs(spec):) | What changed | REQs affected |
|--------|------|----------------------|--------------|---------------|
| v1 | <!-- date --> | <!-- docs(spec): initial spec --> | baseline (backfilled from shipped v0.6 state) | all existing |

---

## Rules (PO <-> ciagent contract)

- **One document each way.** No slides, sidecar notes, or direct edits to
  generated docs. If you want to change product intent, edit `oy-spec`; if you
  want to know what the ciagent did, read `oy-state`.
- **Every REQ the ciagent implements must appear in §4 with acceptance
  criteria.** Vague criteria -> vague implementation.
- **Mark a REQ `[locked]`** only if a future spec revision must not change it
  without an explicit override line in §9. Locked REQs map to const firewalls
  the ciagent defends with regression tests (listed in `oy-state` §3).
- **The ciagent regenerates `oy-state` at every milestone ship AND at P0 of the
  next milestone if `oy-spec` changed since the last `oy-state`.** `oy-state`
  is authoritative for "what exists"; PROJECT.md is internal working memory.
- **Before proposing a new REQ in §4, grep `oy-state` §2 (coverage) and §4
  (deferred).** Re-proposing an existing or explicitly-deferred REQ is a no-op
  and will be flagged as drift in the next `oy-state` §5.
- **When §4 or §6 change,** the ciagent regenerates PROJECT/REQUIREMENTS and
  flags drift. When §3/§5 only change, no regeneration is needed.

## Commit convention (mandatory for `oy-spec`)

- Every commit that modifies `oy-spec` MUST use a Conventional Commit message:

  ```
  docs(spec): <imperative summary <=72 chars>

  <optional body: what changed in §4/§6 and why; >=1 line per REQ affected>
  ```

- Examples:
  ```
  docs(spec): add REQ-046 governance spam deposit (§4)

  Opens REQ-046 per oy-state §4 deferred item "governance spam deposit".
  Acceptance: proposal deposit >= 1 Loaf, slashable on spam.
  ```
  ```
  docs(spec): lock REQ-002 fee ceiling — overrideable only via §9

  REQ-002 fee covenant locked per vision §18; any future change requires an
  explicit §9 changelog override line.
  ```

- The ciagent will **REJECT** any `oy-spec` commit whose subject does not match
  `docs(spec): ...`. This makes spec changes grep-able and ties each
  implementation milestone back to the spec revision that authorized it (via
  the §9 Changelog row referenced in the commit body).
- **No squash merges, `fixup!`, or empty commits** for `oy-spec`. Every edit
  is a real `docs(spec):` commit on the default branch.