From 2c0e95388121e49ab3a6a128a3e94efc5555a8cd Mon Sep 17 00:00:00 2001 From: cloudinit-bot Date: Tue, 18 Aug 2026 23:23:09 +0000 Subject: [PATCH] =?UTF-8?q?docs(P00):=20add=20oy-spec-template.md=20?= =?UTF-8?q?=E2=80=94=20blank=20skeleton=20for=20fresh=20milestone=20cycles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit OY-specific template the PO copies to .ciagent/oy/oy-spec (no .md) when starting a fresh milestone cycle. Pre-fills the locked baseline that does not change between milestones (Six Principles §3, Constraints §5, Lexicon §6, REQ-001..REQ-021 locked-vision rows in §4, Rules + Commit convention blocks). Clears the per-milestone content the PO must fill (§1 Objective, §2 Vision source locked-sections, §4 acceptance criteria, §4 new REQ-022+ rows, §7 Milestone intent, §8 Open questions, §9 Changelog). Each placeholder is a comment so the PO can grep for unfilled slots. The header comment block explains what is pre-filled vs what the PO fills, and points to oy-state §2 for the current max REQ-ID before adding new rows. Lives at .ciagent/oy/oy-spec-template.md (.md extension because it is a reference file the PO reads in an editor, not ingested by the ciagent — the working oy-spec / oy-state keep the bare-stem convention for ingestion). ---ci--- phase: 0 milestone: v0.6 status: execute project: oy ---/ci--- --- .ciagent/oy/oy-spec-template.md | 176 ++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 .ciagent/oy/oy-spec-template.md diff --git a/.ciagent/oy/oy-spec-template.md b/.ciagent/oy/oy-spec-template.md new file mode 100644 index 0000000..8295e31 --- /dev/null +++ b/.ciagent/oy/oy-spec-template.md @@ -0,0 +1,176 @@ +` placeholder and commit + with a `docs(spec):` Conventional Commit (see the commit convention block at + the bottom of this file). + + What is pre-filled (do NOT edit unless the locked baseline itself changes): + - §3 Principles [locked] (Six Principles) + - §5 Constraints (project invariants) + - §6 Lexicon [locked] (banned terms + replacements) + - §4 REQ-001..REQ-021 (locked-vision baseline rows — acceptance criteria + still need filling on first use) + - Rules + Commit convention blocks + + What the PO must fill per milestone: + - §1 Objective + - §2 Vision source (locked sections list) + - §4 acceptance criteria for every REQ the milestone implements + - §4 new REQ-NNN rows for milestone-specific additions (continuing the ID + sequence from the last shipped REQ — check `oy-state` §2 for the current + max REQ-ID) + - §7 Milestone intent (current shipped, next target, out-of-scope) + - §8 Open questions for the ciagent + - §9 Changelog (one row per spec revision) +--> + +# OpenYield Spec — spec-vN +Owner: +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 + + +## 2. Vision source +- Document: Vision v3.0 (22 sections) +- Locked commitments (non-amendable sections): + + +## 3. Principles [locked] +1. Real value +2. Sustainability +3. Mission-lock +4. Openness +5. Ownership +6. Self-service + + +## 4. Requirements + +| ID | Title | Vision § | Priority | Locked? | Acceptance criteria | +|----|-------|----------|---------|---------|---------------------| +| REQ-001 | Enforce Six Principles | §2 | High | yes | | +| REQ-002 | Fee ceiling 0.1% / floor 0.01% / 1-Grain min | §18 | High | yes | | +| REQ-003 | Bloom from real production only (Root Basket) | §6 | High | yes | | +| REQ-004 | 9 Watchers, 6-of-9 quorum | §7 | High | yes | | +| REQ-005 | Four Freeholder signals | §9.1 | High | yes | | +| REQ-006 | Standing anti-gaming formula | §9.2 | High | yes | | +| REQ-007 | FCFS processing | §15 | High | yes | | +| REQ-008 | OY Chain (Layer 1) | §7 | High | yes | | +| REQ-009 | Satellite chains (Layer 2) | §7 | Medium | no | | +| REQ-010 | Exit layer (Layer 3) | §7 | Medium | no | | +| REQ-011 | Three Councils with Mission Lock | §19 | High | yes | | +| REQ-012 | Lexicon compliance | §3 | High | yes | | +| REQ-013 | Bread unit with scale | §4 | High | yes | | +| REQ-014 | Three pools of storage | §5 | High | yes | | +| REQ-015 | Window primitive | §10 | High | no | | +| REQ-016 | Nine Stand types | §11 | Medium | yes | | +| REQ-017 | Guilds with free Hand-Passes | §12 | Medium | yes | | +| REQ-018 | Four-tier Partner Spectrum | §13 | Medium | no | | +| REQ-019 | Six bearers via Unified Bearer Layer | §14 | Medium | yes | | +| REQ-020 | Six Pacts | §16 | Medium | no | | +| REQ-021 | Mesh Bond Market with 8% cap | §17 | Medium | yes | | +| | | | | | | +| | | | | | | + +## 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: +- Next: +- Out-of-scope this milestone: + + +## 8. Open questions for the ciagent + + +## 9. Changelog + +| Spec-v | Date | Commit (docs(spec):) | What changed | REQs affected | +|--------|------|----------------------|--------------|---------------| +| v1 | | | | | + +--- + +## 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): + + =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. \ No newline at end of file