diff --git a/blueprint/implementations/v1.2.0/technical-debt-backlog.md b/blueprint/implementations/v1.2.0/technical-debt-backlog.md new file mode 100644 index 0000000..f0fec8e --- /dev/null +++ b/blueprint/implementations/v1.2.0/technical-debt-backlog.md @@ -0,0 +1,26 @@ +# Nexus — Technical Debt Backlog (post-v1.1.0) + +> Every item is **evidence-backed** — observed during the v1.1.0 operational bring-up (2026-06-25). +> No speculative debt. Source reports in `blueprint/implementations/v1.1.0/`. + +--- + +| # | Debt | Severity | Evidence (v1.1.0) | Resolution direction | +|---|---|---|---|---| +| D-1 | Free-tier LLM rate-limits under sustained load | High | OpenRouter 402 (no credits) then free-tier 429; mitigated by Groq→Zenmux→OpenRouter chain but not eliminated | Paid/BYOK key path + provider-exhaustion alerting | +| D-2 | `create_all`-only schema management | High | On-disk schema drift required a manual DB backup + recreate during bring-up; Alembic incomplete | Adopt Alembic migrations; runbook removes manual recreate | +| D-3 | Discord channel routing not config-driven | Medium | `.env` `DISCORD_*_CHANNEL` ids unread; delivery relied on `settings.discord.channels` name resolution | Read channel ids into `settings.discord.channels` | +| D-4 | Gemini / Claude runtimes are generic shell runners | Medium | Classified Experimental; no real model integration | Implement + validate real CLI runtime integration | +| D-5 | No production web SearchProvider | Medium | Agent web tools lack a real provider | Integrate a production search backend | +| D-6 | In-code version string stale (`0.1.0`) | Low | `nexus/__init__.py` / `pyproject.toml` read `0.1.0` while tag is `v1.1.0`; pre-existing, carried from v1.0.x | Align version strings to release tags | +| D-7 | J5/J6 health jobs are read-only snapshots without alerting | Low | Outbox/checkpoint health gauges recorded but no alerting; no soak test run | Add alerting + multi-hour soak validation | +| D-8 | Email double-STARTTLS class of transport fragility | Low (fixed) | One-line `start_tls=False` fix applied + delivered live; broader transport-matrix tests absent | Add SMTP transport-config regression tests (465 vs 587) | + +## Notes + +- D-8's defect is **already fixed and live-validated** in v1.1.0; the residual debt is test coverage + for the transport matrix, not the bug itself. +- None of D-1…D-7 block Pilot operation; collectively they define the Production Ready gate (see + `v1.2-planning-charter.md` §6). +- This backlog is the **sole** authorized seed for the v1.2 roadmap — no items beyond observed + evidence. diff --git a/blueprint/implementations/v1.2.0/v1.2-planning-charter.md b/blueprint/implementations/v1.2.0/v1.2-planning-charter.md new file mode 100644 index 0000000..b5b06ef --- /dev/null +++ b/blueprint/implementations/v1.2.0/v1.2-planning-charter.md @@ -0,0 +1,61 @@ +# Nexus v1.2.0 — Planning Charter + +> **Status:** Planning (not started). **Branch:** `v1.2.0-planning` (from tag `v1.1.0`, `26fc0fd`). +> **Predecessor:** v1.1.0 "Containment" — Pilot Ready, 9/9 stages live-validated. +> Seeded **only** from verified operational evidence collected during the v1.1.0 bring-up. No +> speculative features. + +--- + +## 1. Mission + +Advance Nexus from **Pilot Ready** to **Production Ready** by closing the specific, evidence-backed +gaps observed during the v1.1.0 operational bring-up. v1.2 is a **hardening and durability** release, +not a feature-expansion release. + +## 2. Context (what v1.1.0 proved) + +The control plane boots, onboards, governs, schedules, researches, briefs, executes, recovers, and +notifies (email + Discord) on real infrastructure. Pilot operation is viable today. The barriers to +unattended production operation are **durability, capacity, and integration completeness** — each +already observed and documented, not hypothesized. + +## 3. Scope (in) + +Every in-scope item traces to a verified v1.1.0 limitation (see `technical-debt-backlog.md`): + +1. **Durable LLM capacity** — eliminate residual free-tier 429s (paid/BYOK path + rate-limit alerting). +2. **Managed schema migrations** — adopt Alembic; retire manual `create_all` recreate. +3. **Deterministic Discord routing** — read `.env` `DISCORD_*_CHANNEL` ids into config. +4. **Real Gemini/Claude CLI runtimes** — replace generic shell runners. +5. **Production web SearchProvider** — for the agent's research tools. +6. **Version-string alignment** — `nexus/__init__.py` / `pyproject.toml` to match release tags. +7. **Soak/load testing + health alerting** — on J5 (outbox) / J6 (checkpoint) metrics. + +## 4. Scope (out) + +- No architectural redesign; preserve registry, governance, sandbox, scheduler-port, and + event-sourced memory boundaries and ADR history. +- No new product surfaces, no speculative capabilities, no opportunistic refactoring. +- No changes to the frozen v1.1.0 evidence record. + +## 5. Operating constraints (carried from v1.1.0) + +- Evidence-first: every change traces to a verified finding; produce validation per change. +- `.env` is the single source of truth — never rewritten, never duplicated, secrets never printed. +- A-001 owner authorization must remain fail-closed; sandbox must remain default-secure. +- Blueprint memory stays synchronized; ADR or implementation report per change. + +## 6. Success criteria (Production Ready gate) + +- LLM gateway sustains target load with no unhandled 429; alerting on provider exhaustion. +- Schema changes applied via migrations; no manual DB recreate in any runbook. +- Discord routing deterministic from config. +- At least one real CLI runtime (Gemini or Claude) integrated and validated live. +- Soak test (multi-hour unattended) passes with health alerting proven. +- Version strings consistent across source, config, and tags. + +## 7. Deliverables (planned) + +`blueprint/implementations/v1.2.0/` — charter (this), roadmap, technical-debt backlog, then +per-track design + implementation + validation reports once planning is approved. diff --git a/blueprint/implementations/v1.2.0/v1.2-roadmap.md b/blueprint/implementations/v1.2.0/v1.2-roadmap.md new file mode 100644 index 0000000..c88fd38 --- /dev/null +++ b/blueprint/implementations/v1.2.0/v1.2-roadmap.md @@ -0,0 +1,54 @@ +# Nexus v1.2.0 — Roadmap + +> **Status:** Planning (not started). Seeded **only** from `technical-debt-backlog.md` (verified +> v1.1.0 operational evidence). No speculative features. Theme: **Pilot Ready → Production Ready**. + +--- + +## Tracks (each maps 1:1 to an evidence-backed debt item) + +### Track L — Durable LLM Capacity *(D-1, High)* +- Paid/BYOK provider path alongside the existing Groq→Zenmux→OpenRouter free chain. +- Provider-exhaustion detection + alerting; per-provider budget/quota awareness. +- **Exit:** target load sustained with zero unhandled 429; alert fires on exhaustion. + +### Track M — Managed Schema Migrations *(D-2, High)* +- Adopt Alembic; baseline current models; forward migration workflow. +- Remove manual DB recreate from all runbooks. +- **Exit:** schema changes ship as migrations; no manual recreate anywhere. + +### Track R — Real CLI Runtimes *(D-4, Medium)* +- Implement + live-validate at least one of Gemini / Claude CLI runtimes (replace shell stubs). +- **Exit:** one real CLI runtime reaches Pilot (governed execution + artifacts, live). + +### Track N — Deterministic Notifications *(D-3, Medium)* +- Read `.env` `DISCORD_*_CHANNEL` ids into config for deterministic routing. +- SMTP transport-matrix regression tests (465 vs 587) — closes D-8 residual. +- **Exit:** Discord routing config-driven; transport tests green. + +### Track S2 — Production Search *(D-5, Medium)* +- Integrate a production web `SearchProvider` for the agent's research tools. +- **Exit:** agent web search backed by a real provider, live-validated. + +### Track O — Operability & Soak *(D-6, D-7, Low)* +- Align version strings (`nexus/__init__.py`, `pyproject.toml`) to release tags. +- Alerting on J5/J6 health metrics; multi-hour unattended soak test. +- **Exit:** version consistent; soak passes with alerting proven. + +## Sequencing (proposed) + +1. **Phase 1 — Durability foundation:** Track L + Track M (the two High-severity production blockers). +2. **Phase 2 — Integration completeness:** Track R + Track S2. +3. **Phase 3 — Operability:** Track N + Track O, then a consolidated soak run. +4. **Phase 4 — Production readiness assessment & release** once all exit criteria are met. + +## Production Ready gate + +All tracks' exit criteria met → re-run the operational bring-up + a soak test → if green, reclassify +subsystems and cut v1.2.0 as the first **Production Ready** release. (Mirror the v1.1.0 evidence-first +release process.) + +## Out of scope + +No architectural redesign, no new product surfaces, no opportunistic refactoring. Anything not traced +to `technical-debt-backlog.md` is **not** in this roadmap.