docs(P00): create phase plans — v0.4 NFR (P1..P4, 12 tasks)
P1 lexicon+const hardening (REQ-029/030). P2 lifecycle divergence docs+ guard (REQ-031). P3 docs build CI (REQ-032). P4 final review+audit+ship. D-001 refinement-only filter governs all tasks. NFR purity gate in P4. Tags v0.3.x. No cross-phase hard blockers (independent vertical slices). ---ci--- project: oy phase: 0 milestone: v0.4 status: plan tag_base: v0.3.x milestone_type: nfr ---/ci---
This commit is contained in:
@@ -1,11 +1,11 @@
|
||||
{
|
||||
"phase": 0,
|
||||
"stage": "research",
|
||||
"stage": "plan",
|
||||
"milestone": "v0.4",
|
||||
"milestone_type": "nfr",
|
||||
"tag_base": "v0.3.x",
|
||||
"phase_role": "pre_execution",
|
||||
"project": "oy",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-17T22:45:00Z"
|
||||
"updated_at": "2026-08-17T22:48:00Z"
|
||||
}
|
||||
+208
-1
@@ -789,4 +789,211 @@ The v0.3 Phase 0 clarify/ideate/research stages produced 13 clarification decisi
|
||||
| A-311 | OY-SAT surveillance-resistant LOCKED true; OY-QR one-shot | P4-03-01 |
|
||||
| A-312 | HubServiceCount=3 | P5-01-01 |
|
||||
| A-313 | OrderSideCount=2, OrderStatusCount=3 | P5-03-01 |
|
||||
| A-315 | v0.2 cosmos-engineer/security-engineer NOT reactivated | Persona assignments (backend-engineer owns all P4/P5) |
|
||||
| A-315 | v0.2 cosmos-engineer/security-engineer NOT reactivated | Persona assignments (backend-engineer owns all P4/P5) |
|
||||
|
||||
---
|
||||
|
||||
## Milestone v0.4 — Refinement (NFR) — Phase Plan
|
||||
|
||||
### Milestone Summary
|
||||
|
||||
- **Milestone**: v0.4 — Refinement (NFR)
|
||||
- **Type**: NFR (zero `feat:` phases by construction; D-047). Final-phase audit enforces the NFR purity gate (`git log --grep "^feat:"` on the milestone range returns zero).
|
||||
- **Tag base**: `v0.3.x` patch line. P0 ships as `v0.3.0`; execution phases `v0.3.1..v0.3.3`; final phase P4 patch `v0.3.4` IS the milestone release. No separate minor tag (D-008).
|
||||
- **Phases**: 4 execution + 1 final = 5. Phase 0 (this PLAN) is pre-execution.
|
||||
- **Depth**: refinement-only — refactor + test + docs + chore. No new production types, no new enum types, no behavioral changes. All work passes the D-001 refinement-only filter.
|
||||
- **Coverage target**: ≥80% on any modified package; do NOT reduce existing coverage (v0.3 floor is 93.3%).
|
||||
- **New modules**: ZERO. Touched files: `lexicon/lexicon.go` (add helper), `lexicon_meta_test.go` + `lexicon_meta_docs/lexicon_meta_docs_test.go` (refactor to consume helper), `x/hub/types/cross_const_test.go` (NEW test file), `x/council/types/types_test.go` (add intent test), `.ciagent/oy/ARCHITECTURE.md` (docs), `.gitea/workflows/docs-build.yml` (NEW CI).
|
||||
- **Phase ordering** (D-052): P1 lexicon+const hardening → P2 lifecycle divergence docs+guard → P3 docs build CI → P4 final review/audit/ship. P1 is firewall-first (highest-severity regression risk); each phase independently shippable (vertical slices).
|
||||
- **Personas**: backend-engineer (P1, P2 code), lead-developer (P2 docs, P3 CI, P4 review/ship). v0.3 frontend-engineer + docs-writer deactivated.
|
||||
|
||||
### Cross-Phase Dependency Map
|
||||
|
||||
```
|
||||
P1 (lexicon helper, cross-const test) ──► P4 (review)
|
||||
P2 (lifecycle docs + regression guard) ─► P4 (review)
|
||||
P3 (docs build CI) ─► P4 (review)
|
||||
```
|
||||
|
||||
No hard cross-phase blockers (all three execution phases are independent vertical slices). P4 depends on P1+P2+P3 completion only.
|
||||
|
||||
### D-001 Refinement-Only Filter (governs every v0.4 task)
|
||||
|
||||
- **Accept**: refactor, test, docs, chore, quality, architecture (drift fix only).
|
||||
- **Reject**: `add_requirement` + `feat:`-class signal (new enum type, new production type, new capability, new CLI, new distribution channel).
|
||||
- **Pre-seeded NFR REQs** (REQ-029..REQ-032) are exempt — already in REQUIREMENTS.md before PLAN.
|
||||
|
||||
---
|
||||
|
||||
## Phase P1 — Lexicon + Const Hardening
|
||||
|
||||
- **Slug**: `lexicon-const-hardening`
|
||||
- **Branch**: `oy/phase/01-lexicon-const-hardening`
|
||||
- **REQs covered**: REQ-029 (lexicon shared helper), REQ-030 (cross-const test)
|
||||
- **Tag**: `v0.3.1`
|
||||
- **Goal**: Close the G-014 lexicon-firewall drift risk (shared synthetic-string helper) and the A-304 hub↔bond const drift risk (cross-package equality test). Both are refactor+test; no behavioral change.
|
||||
|
||||
### Wave 1 — Shared helper + cross-const test (parallel; no internal deps)
|
||||
|
||||
| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
|
||||
|---|---|---|---|---|---|---|
|
||||
| P1-01-01 | REQ-029 | backend-engineer | `lexicon/lexicon.go` | Add `SyntheticBannedStrings() []string` returning the 10 synthetic strings currently duplicated in both meta-tests. Each string embeds exactly one banned term (from `BannedTerms()`) in a plausible sentence context. Source uses `BannedTerms()` so the lexicon package's own source stays lexicon-clean (fragment-assembled). Add a doc comment cross-referencing G-014 and both consuming meta-tests. | `go build ./lexicon/...` succeeds; `SyntheticBannedStrings()` returns exactly `len(BannedTerms())` strings; each returned string triggers `FindBannedTerm` (self-verifiable in a new test); lexicon package source stays lexicon-clean (the existing `lexicon_meta_test.go` x/ scan does not scan `lexicon/` itself, but the helper must not introduce a banned-term literal). | — |
|
||||
| P1-01-02 | REQ-029 | backend-engineer | `lexicon_meta_test.go`, `lexicon_meta_docs/lexicon_meta_docs_test.go` | Refactor `TestLexiconMetaSelfTestTable` and `TestLexiconMetaDocsSelfTestTable` to consume `lexicon.SyntheticBannedStrings()` instead of building their own `synthetic` slice. Remove the duplicated 10-string table from both. Keep the per-string `FindBannedTerm` assertion loop (detection coverage unchanged). Keep the `len(terms) == 10` assertion from `BannedTerms()`. Add a `len(synthetic) == len(terms)` assertion derived from the helper. | `go test ./lexicon_meta... ./lexicon_meta_docs/...` passes; both tests still fail if detection breaks; the duplicated table is gone (grep for the old literal sentence fragments returns zero matches in meta-test files); coverage on both meta-tests does not decrease. | P1-01-01 |
|
||||
| P1-02-01 | REQ-030 | backend-engineer | `x/hub/types/cross_const_test.go` (NEW) | New test file, package `types` (same package as `x/hub/types`). Test-only import `github.com/oy/openyield/x/bond/types` (G-003 test-exempt). Tests: (1) `TestLendingCouponCapMatchesBondCap` asserts `hub.LendingCouponCapBps == bond.CouponCapBps`; (2) `TestLendingCouponFloorMatchesBondFloor` asserts `hub.LendingCouponFloorBps == bond.CouponFloorBps`; (3) `TestConstsAreMissionLocked800And0` asserts both caps == 800 and both floors == 0 (regression guard for the mission-locked values). Doc comment cross-references A-304 and the G-003 test-exemption. | `go test ./x/hub/types/...` passes; all three tests green at current values (800/0); test fails closed if either const drifts; NO production file in `x/hub/types/` imports `x/bond/types` (G-003 production firewall intact — verified by a grep of non-test `.go` files). | — |
|
||||
|
||||
### Wave 2 — Verification (blocked-by Wave 1)
|
||||
|
||||
| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
|
||||
|---|---|---|---|---|---|---|
|
||||
| P1-99-01 | REQ-029, REQ-030 | lead-developer | — (verification only) | Run `go test ./...` (all packages, both lexicon firewalls + cross-const test + all v0.3 baseline tests); run `grep -rn "open a .* here\|make a .* now\|compounding .* rate" lexicon_meta_test.go lexicon_meta_docs/` and confirm zero matches (old duplicated table fully removed); confirm `go.mod` unchanged (zero deps, G-006). | `go test ./...` exits 0; grep returns zero; `go.mod` diff is empty. | P1-01-02, P1-02-01 |
|
||||
|
||||
### P1 Must-Haves (verification gate before SHIP)
|
||||
|
||||
- [ ] `lexicon.SyntheticBannedStrings()` exists and returns 10 strings.
|
||||
- [ ] Both meta-tests consume the helper (no duplicated table).
|
||||
- [ ] `x/hub/types/cross_const_test.go` exists and passes.
|
||||
- [ ] `go test ./...` green (all v0.3 baseline + v0.4 new tests).
|
||||
- [ ] `go.mod` unchanged.
|
||||
- [ ] No `feat:` commits in P1 (D-001 filter).
|
||||
|
||||
---
|
||||
|
||||
## Phase P2 — Lifecycle Divergence Documentation + Regression Guard
|
||||
|
||||
- **Slug**: `lifecycle-divergence-docs`
|
||||
- **Branch**: `oy/phase/02-lifecycle-divergence-docs`
|
||||
- **REQs covered**: REQ-031
|
||||
- **Tag**: `v0.3.2`
|
||||
- **Goal**: Document the AUDIT §193 council lifecycle type divergences (P1-1 Proposal/VoteOption absent; P1-2 SignalKind 4-vs-5) in ARCHITECTURE.md and add an intent-assertion test guarding the current `SignalKindCount==4` shape. No enum additions, no locked-const changes (D-050).
|
||||
|
||||
### Wave 1 — Docs + regression guard (parallel; no internal deps)
|
||||
|
||||
| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
|
||||
|---|---|---|---|---|---|---|
|
||||
| P2-01-01 | REQ-031 | lead-developer | `.ciagent/oy/ARCHITECTURE.md` | Add a "Council Voice/Council Interface — Lifecycle Type Divergence Decisions (v0.4)" subsection under the v0.4 Architecture section. Document: (a) P1-1 `Proposal`/`ProposalStatus`/`VoteOption` absent — deferred to v0.5+ governance runtime (feat:-class, rejected by D-001); (b) P1-2 `SignalKind` 4 sources (Stash/Standing/Vouch/Capital) vs spec `VoiceSource` 5 sources — the AUDIT rationale (Freeholder is eligibility, Guild is council tier, Capital is committed-capital per vision §9.1) and the decision to KEEP the 4-source shape; (c) the Bearers `ValidateGenesis` no-op is correct per spec (P2, no action). Cross-reference AUDIT §193 P1-1/P1-2/P2. | The ARCHITECTURE.md section exists and names both P1 divergences + the P2 no-action; a reader can find why Proposal/VoteOption are absent and why SignalKind is 4-not-5 without re-reading AUDIT. | — |
|
||||
| P2-02-01 | REQ-031 | backend-engineer | `x/council/types/types_test.go` | Add `TestSignalKindShapeIntentional` — an intent-assertion test that documents and guards the 4-source `SignalKind` shape. Asserts: `SignalKindCount == 4`; `AllSignalKinds()` returns exactly [Stash, Standing, Vouch, Capital]; a doc-comment block above the test explaining the AUDIT §193 P1-2 rationale (why Freeholder and Guild are NOT signal kinds, why Capital IS) so a future agent does not "fix" the divergence by silently changing the locked const. This is a regression GUARD, not a shape change — the existing `TestSignalKindCountLockedConst` already locks the count; this test adds the INTENT documentation. | `go test ./x/council/types/...` passes; the new test fails if `SignalKindCount` changes from 4; the test's doc comment explains the rationale. | — |
|
||||
|
||||
### Wave 2 — Verification (blocked-by Wave 1)
|
||||
|
||||
| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
|
||||
|---|---|---|---|---|---|---|
|
||||
| P2-99-01 | REQ-031 | lead-developer | — (verification only) | Run `go test ./...`; confirm ARCHITECTURE.md subsection present; confirm no production `.go` file was modified in P2 (only a `_test.go` file + a `.ciagent/` doc). | `go test ./...` exits 0; `git diff --name-only <p2-base> HEAD -- 'x/**/*.go'` returns only `x/council/types/types_test.go` (no production files). | P2-01-01, P2-02-01 |
|
||||
|
||||
### P2 Must-Haves (verification gate before SHIP)
|
||||
|
||||
- [ ] ARCHITECTURE.md has the Council lifecycle divergence subsection.
|
||||
- [ ] `TestSignalKindShapeIntentional` exists and passes.
|
||||
- [ ] `SignalKindCount` unchanged (still 4).
|
||||
- [ ] No production `.go` files modified in P2 (test + docs only).
|
||||
- [ ] No `feat:` commits in P2 (D-001 filter).
|
||||
|
||||
---
|
||||
|
||||
## Phase P3 — Docs Build CI
|
||||
|
||||
- **Slug**: `docs-build-ci`
|
||||
- **Branch**: `oy/phase/03-docs-build-ci`
|
||||
- **REQs covered**: REQ-032
|
||||
- **Tag**: `v0.3.3`
|
||||
- **Goal**: Ship a Gitea Actions workflow that runs the lexicon firewall (`go test ./...`) + builds the docs site (`mkdocs build`) on every push, uploading `site/` as a CI artifact. Full Gitea Pages publishing deferred (no hosting target configured, D-051). The workflow file is `chore` (CI config), not `feat:`.
|
||||
|
||||
### Wave 1 — CI workflow (single task; no internal deps)
|
||||
|
||||
| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
|
||||
|---|---|---|---|---|---|---|
|
||||
| P3-01-01 | REQ-032 | lead-developer | `.gitea/workflows/docs-build.yml` (NEW) | Gitea Actions workflow (YAML). Triggers: on push (all branches). Jobs: (1) `go-test` — setup Go 1.22, `go test ./...` (runs lexicon firewall + all x/* tests); (2) `docs-build` — setup Python, `pip install mkdocs mkdocs-material`, `mkdocs build` (produces `site/`), upload `site/` as an artifact. The two jobs run in parallel (no dependency). `go.mod` is NOT modified (Python deps are isolated to the `docs-build` job). Doc comment in the YAML references D-046 (forward-reference) and D-051 (no Pages publish). | YAML parses (validate with a YAML linter or `python -c "import yaml; yaml.safe_load(open('.gitea/workflows/docs-build.yml'))"`); `go test ./...` command matches the local green baseline; `mkdocs build` command matches the README's local build invocation; no `go.mod` change. | — |
|
||||
|
||||
### Wave 2 — Verification (blocked-by Wave 1)
|
||||
|
||||
| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
|
||||
|---|---|---|---|---|---|---|
|
||||
| P3-99-01 | REQ-032 | lead-developer | — (verification only) | Validate the workflow YAML parses; confirm `go test ./...` still green locally (the workflow does not change Go source); confirm `mkdocs build` succeeds locally (mkdocs installed); confirm `go.mod` unchanged. | YAML parse OK; `go test ./...` exits 0; `mkdocs build` produces `site/`; `go.mod` diff empty. | P3-01-01 |
|
||||
|
||||
### P3 Must-Haves (verification gate before SHIP)
|
||||
|
||||
- [ ] `.gitea/workflows/docs-build.yml` exists and parses.
|
||||
- [ ] Workflow runs `go test ./...` and `mkdocs build`.
|
||||
- [ ] `go.mod` unchanged.
|
||||
- [ ] No `feat:` commits in P3 (D-001 filter; the workflow is `chore`).
|
||||
|
||||
---
|
||||
|
||||
## Phase P4 — Final Review + Audit + Milestone Ship
|
||||
|
||||
- **Slug**: `final-review-ship`
|
||||
- **Branch**: `oy/phase/04-final-review-ship`
|
||||
- **REQs covered**: all v0.4 REQs (REQ-029..REQ-032) — final coverage accounting
|
||||
- **Tag**: `v0.3.4` (IS the v0.4 milestone release; D-008)
|
||||
- **Goal**: Multi-persona review across P1..P3, audit (reconstruction test + NFR purity gate), milestone ship (merge to main, tag v0.3.4, release, delete all milestone branches).
|
||||
|
||||
### Wave 1 — Review + Audit (parallel; no internal deps)
|
||||
|
||||
| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
|
||||
|---|---|---|---|---|---|---|
|
||||
| P4-01-01 | — | lead-developer (review) | `.ciagent/oy/REVIEW.md` (NEW for v0.4) | Multi-persona code review across P1..P3. Adversarial probes: (1) does the shared helper actually dedupe (grep for old table); (2) does the cross-const test fail closed on drift; (3) does the regression guard lock the 4-signal shape; (4) does the CI workflow YAML parse. Auto-apply P0 fixes; flag P1+ for post-hoc. | REVIEW.md written; P0 issues (if any) fixed in P4; P1+ flagged. | P1, P2, P3 |
|
||||
| P4-02-01 | — | ci-security-auditor (audit) | `.ciagent/oy/AUDIT.md` (v0.4 section) | Audit: (1) reconstruction test (git log ↔ `.ciagent/` files for v0.4); (2) file/branch/commit discipline; (3) **NFR purity gate** — `git log --grep "^feat:" $(git rev-list --tags=v0.3.0..v0.3.4)` returns zero (or the equivalent milestone-range grep); (4) coverage did not decrease on any modified package. | AUDIT.md v0.4 section written; NFR purity gate GREEN (zero feat: commits); reconstruction test passes. | P1, P2, P3 |
|
||||
|
||||
### Wave 2 — Ship (blocked-by Wave 1)
|
||||
|
||||
| Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
|
||||
|---|---|---|---|---|---|---|
|
||||
| P4-03-01 | REQ-029..REQ-032 | lead-developer (ship) | `.ciagent/oy/REQUIREMENTS.md`, `.ciagent/oy/ROADMAP.md`, `.ciagent/CHECKPOINT.json` | Milestone ship via `ciagent ship 4` (or ShipWorkflow fallback). Merge `oy/phase/04` → `oy/milestone/v0.4-refinement` → `main`. Tag `v0.3.4`. Create release (best-effort via `resolveSecret(GITEA_TOKEN)`). Delete all milestone branches (local + remote). Update REQUIREMENTS.md (v0.4 REQs → Complete) + ROADMAP.md (v0.4 → COMPLETE). Commit `docs(milestone): complete v0.4`. Clear CHECKPOINT. | Tag `v0.3.4` created; milestone branch merged to main; release created (or local-only fallback); all `oy/phase/*` and `oy/milestone/v0.4-refinement` branches deleted; REQUIREMENTS.md + ROADMAP.md updated; checkpoint cleared. | P4-01-01, P4-02-01 |
|
||||
|
||||
### P4 Must-Haves (verification gate before milestone complete)
|
||||
|
||||
- [ ] REVIEW.md v0.4 section written; P0 fixes applied.
|
||||
- [ ] AUDIT.md v0.4 section written; reconstruction test passes.
|
||||
- [ ] **NFR purity gate GREEN**: zero `feat:` commits in the v0.4 milestone range.
|
||||
- [ ] Tag `v0.3.4` created (= milestone release).
|
||||
- [ ] Milestone branch merged to `main`.
|
||||
- [ ] All milestone branches deleted (local + remote).
|
||||
- [ ] REQUIREMENTS.md + ROADMAP.md mark v0.4 COMPLETE.
|
||||
- [ ] CHECKPOINT.json cleared (milestone complete).
|
||||
|
||||
---
|
||||
|
||||
## Coverage Targets (D-033) — v0.4
|
||||
|
||||
v0.4 does not lower the v0.3 coverage floor (93.3% on the lowest package). The modified packages must not decrease:
|
||||
- `lexicon` (if coverage applies — it's a helper package): maintain or improve.
|
||||
- `lexicon_meta` / `lexicon_meta_docs`: maintain 100% (test-only packages).
|
||||
- `x/hub/types`: the new `cross_const_test.go` ADDS coverage; do not decrease.
|
||||
- `x/council/types`: the new intent test ADDS coverage; do not decrease.
|
||||
|
||||
No new packages are created, so no new 80% floor is set.
|
||||
|
||||
## Task Count Summary — v0.4
|
||||
|
||||
| Phase | Tasks | Personas | Tag |
|
||||
|-------|-------|----------|-----|
|
||||
| P0 | (pre-execution, this plan) | lead-developer | v0.3.0 |
|
||||
| P1 | 4 (3 code + 1 verify) | backend-engineer, lead-developer | v0.3.1 |
|
||||
| P2 | 3 (2 deliver + 1 verify) | backend-engineer, lead-developer | v0.3.2 |
|
||||
| P3 | 2 (1 deliver + 1 verify) | lead-developer | v0.3.3 |
|
||||
| P4 | 3 (review + audit + ship) | lead-developer, ci-security-auditor | v0.3.4 |
|
||||
| **Total** | **12 tasks** | | |
|
||||
|
||||
## Per-Phase REQ Coverage — v0.4
|
||||
|
||||
| Phase | REQs covered | Status after phase |
|
||||
|-------|--------------|--------------------|
|
||||
| P1 | REQ-029, REQ-030 | Complete (shipped as v0.3.1) |
|
||||
| P2 | REQ-031 | Complete (shipped as v0.3.2) |
|
||||
| P3 | REQ-032 | Complete (shipped as v0.3.3) |
|
||||
| P4 | (all v0.4 REQs final accounting) | Complete (shipped as v0.3.4) |
|
||||
|
||||
## Cross-Phase Blockers (hard) — v0.4
|
||||
|
||||
None. P1, P2, P3 are independent vertical slices. P4 depends on P1+P2+P3 completion only (soft ordering for shippable slices).
|
||||
|
||||
## v0.4 Decisions Applied (D-047..D-053)
|
||||
|
||||
| Decision | Application |
|
||||
|----------|-------------|
|
||||
| D-047 | v0.4 NFR type, tags v0.3.x, zero feat: phases | Milestone summary |
|
||||
| D-048 | REQ-029 lexicon shared helper | P1-01-01, P1-01-02 |
|
||||
| D-049 | REQ-030 cross-const test (G-003 test-exempt import) | P1-02-01 |
|
||||
| D-050 | REQ-031 = document only, no feat: enum additions | P2-01-01, P2-02-01 |
|
||||
| D-051 | REQ-032 docs CI = .gitea/workflows build+artifact, no Pages | P3-01-01 |
|
||||
| D-052 | Phase ordering P1→P2→P3→P4 | Phase ordering |
|
||||
| D-053 | No IDEATE in v0.4 (no --ideate flag) | (no IDEATE stage run) |
|
||||
Reference in New Issue
Block a user