plan(v1.2.0): planning charter, roadmap, and evidence-backed tech-deb…

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.

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.

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.