Nexus v2.5.0 — Accountable Goal Execution

Nexus v2.5.0 — Accountable Goal Execution

This stable minor release adds an operator-supervised path from a goal to a grounded plan, explicitly approved constrained repository actions, independent outcome validation, and evidence-bound Knowledge updates. It covers Phases 1–6 and builds on the v2.0.0 constitutional spine.

The controlled Phase 6 pilot used one operator and five disposable fixture repositories. P1–P3 passed independent evidence checks and were rated useful; the deliberately incorrect P4 was rejected; P5 required review because its required JUnit report was missing. The operator reported zero false denials. All five runs retained complete event lineage; backup/restore and fresh-process replay were verified.

The strict live-Claude suite passed 3,261 tests with -W error, zero warnings, and zero skips. The pilot is limited evidence: it does not establish reliability on arbitrary repositories, sustained operation, or autonomous repair. The deterministic Intent route needed a recorded software-domain prefix for each pilot request. The v1 and v2 codebases remain independent; this release neither migrates v1 data nor introduces a durable schema migration.

Release scope and evidence: v2.5.0 release report, Phase 6 review, and changelog.

CI on the release commit: Core CI · Nexus CI.

Nexus v2.0 — Constitutional Spine

Nexus v2.0

The first complete release of Nexus v2 — the constitutional reasoning spine architecture. An independent, from-scratch rebuild (nexus_*, 31 packages) that does not supersede v1; the two run as separate processes sharing one repository.

Highlights

• Constitutional AI Control Plane — thirteen single-owner capabilities (Understand → Reason → Ground → Contextualize → Plan → Coordinate → Execute → Act → Observe → Validate → Recover → Reflect → Learn), fused into one deterministic Goal→Knowledge driver, governed throughout by the Policy Engine and Human Interaction.
• Deterministic execution — every stage is replayable; reasoning is confined to Understand/Reason/Estimation and always emits an immutable recorded decision.
• Policy-governed autonomy — the Constitutional Scheduler drives one-time, recurring, and delayed goal dispatch under fully-automatic or human-governed AutonomyMode, fronted by the Approval Exchange.
• Replay & restart — an append-only, event-sourced SQLite/WAL log is the single source of truth; all state is a deterministic projection of that log, enabling exact replay and restart from any interruption point.
• Runtime abstraction — a provider-agnostic Runtime Adapter contract (Claude, Gemini, Shell shipped) with a discovery/selection layer independent of any concrete provider.
• Human Interaction — the operator-facing façade over the constitutional pipeline and Approval Exchange.
• Scheduler — durable, restart-safe autonomous goal dispatch.
• Operations — a read-only projection plane over the durable event log for observability of every session, runtime, and replay.
• Documentation — a full architecture portal: ADR audit and traceability, benchmarks and operational evidence, production examples, and a contributor/release governance guide.
• Examples — 10 runnable, self-contained example scripts covering the full constitutional pipeline, policy governance, runtime selection, memory, scheduling, approval, replay, recovery, and autonomous workflows.
• Tutorials — 10 companion tutorials walking the same ground step by step, from install through autonomous workflow.
• Benchmarks — documented guarantees, persistence/replay characteristics, scheduler behavior, and quality gates with operational evidence.

Links

• README
• Documentation
• Architecture
• Examples
• Tutorials

Validation (this release)

• ruff check: clean
• ruff format --check: clean (all files touched by this release)
• mypy --strict: clean — 388 source files across all v2 packages
• pytest: 2941 passed, 1 skipped (opt-in live-API smoke test), 175 warnings
• coverage: 97.97% (gate: 95%)
• uv build (sdist + wheel): succeeds from a clean checkout

Known Limitations

(Reproduced verbatim from CHANGELOG.md's [2.0.0] entry — see there and docs/v2/RC2_EXECUTION_IDENTITY_REPORT.md for full detail.)

• No v1→v2 data migration tool. The two strata use entirely different persistence models and remain fully isolated. ADR-008-shadow-migration.md documents a designed-but-unbuilt migration path. v2 today only supports a greenfield (empty durable log) start.
• Durable schema is unversioned. nexus_infra/durable.py uses CREATE TABLE IF NOT EXISTS only — idempotent bootstrap, no migration mechanism. A future schema change has no upgrade path for an existing durable file.
• ADR-009 (INV-37 runtime-selection ownership) remains unratified — Proposed status, carried forward from RC1.
• Two frozen-contract candidates remain un-frozen despite meeting the freeze trigger: engineering_strategy and repository_understanding. Their shape can still change without the formal process the other 18 frozen contracts get.
• nexus_briefings and nexus_operator remain unwired into the running product (real, tested code; zero live callers) — flagged since P17, unchanged.
• A latent, not-currently-triggered identity-collision shape remains in GraphNode.identifier and its checkpoint reference — safe today only because every consumer looks them up inside an already goal-scoped container; documented in docs/v2/RC2_EXECUTION_IDENTITY_REPORT.md §9 as a fast-follow, not a defect in the current code path.
• ConstitutionalPipeline.execution_graph()/execution_state() (read-only inspection methods) share the same un-scoped-reconstruction shape RC2 fixed on the restart path — dormant, not fixed, documented as a fast-follow.
• Recovery is invoked with checkpoint_ref=None unconditionally — an independent INV-18 gap noted during RC2's audit, unrelated to identity, not in RC2's scope.

Nexus v1.1.0 — Containment

Nexus v1.1.0 — Containment

Executive Summary

Nexus v1.1.0 "Containment" is the first Pilot operational release of the AI Orchestration
Control Plane. It was validated through a real, end-to-end operational bring-up — not a mock harness —
exercising all nine subsystems on live infrastructure: boot, operator onboarding, scheduler, email,
research, briefing, runtime execution, checkpoint recovery, and Discord. The autonomous agent
runtime, developed under the internal codename "Hermes", is promoted to a first-class Nexus Agent.

Classification: Pilot Ready (9/9 stages live-validated). Not yet Production Ready — see Known
Limitations.

Major Features

• Nexus Agent (Hermes → Nexus rebranding) — registry id nexus, back-compat alias for legacy
  hermes records and imports; third-party Nous Research references intentionally preserved.
• Nexus Agent: Experimental → Pilot — fail-fast init, tunable step budget, honest terminal
  lifecycle, cancellation, and resume-from-checkpoint (H-2/H-4).
• Sandbox: Pilot Safe — default-secure containment, fail-closed execution, S-3 startup gate.
• Live operator onboarding — python -m nexus onboard, safe read-only staged validation.
• Multi-provider LLM gateway — Groq → Zenmux → OpenRouter (free) fallback chain.
• Email + Discord notifications — both delivering on real infrastructure.

Architecture Improvements

• No architectural redesign — registry, governance, sandbox, scheduler-port, and event-sourced
  memory boundaries preserved; ADR history intact.
• Orchestrator exit-status finalization honors the agent's truthful terminal status (H-4).
• Config alignment reads deployed .env keys (DISCORD_OWNER_ID, NOTIFY_SMTP_*,
  NOTIFY_EMAIL_FROM) without a parallel credential store; .env remains the single source of truth.

Operational Validation Results (9/9)

Stage	Verdict
Boot (A-001 + S-3 gates)	✅
Operator onboarding	✅
Scheduler	✅
Email (SMTP)	✅
Research	✅
Briefing	✅
Runtime (Nexus Agent)	✅
Recovery (checkpoint resume)	✅
Discord	✅

Live Integration Results

• Email: real SMTP delivery to operator (smtp.gmail.com:587) after a one-line double-STARTTLS fix.
• Discord: bot connected to guild, "Welcome to Nexus" embed posted to #general,
  message_id 1519643857816649821.
• Research: 20 findings parsed from a live RSS feed, LLM-scored and persisted.
• Recovery: interrupt → timed_out → fresh-adapter resume → completed, no corruption.

Performance Metrics (observed 2026-06-25)

• Tests: 219 passed (~45 s); ruff clean; mypy clean (61 files).
• LLM latency (Groq primary): ~120 ms.
• Email delivery: ~8.8 s incl. handshake.
• Scheduler: 4 jobs executed (started:4/completed:4).
• Checkpoints persisted: 39; executions: 3; agent steps: 5.

Upgrade Notes

• No database migration required. Fresh schema from current models via create_all; existing
  v1.1.0-column databases need no change.
• Legacy runner="hermes" / hermes_agent still resolve; import the runtime from
  nexus.execution.runners.nexus_agent (old hermes module path removed).
• LLM defaults are now free OpenRouter models; set GROQ_API_KEY / ZENMUX_API for the full
  fallback chain or a paid/BYOK OpenRouter key for sustained load.
• Singular DISCORD_OWNER_ID env key now supported for A-001 owner resolution.

Known Limitations

• Free-tier LLM rate-limits under sustained load (mitigated, not eliminated).
• create_all-only schema management; Alembic migrations incomplete.
• .env DISCORD_*_CHANNEL ids not yet read into config (delivery works via channel resolution).
• Gemini / Claude runtimes remain generic shell runners (Experimental).
• No production web SearchProvider for agent tools.
• In-code version string still reads 0.1.0 (pre-existing debt; deferred to v1.2).

Roadmap toward v1.2

• Durable/BYOK LLM capacity and rate-limit alerting.
• Adopt a real schema-migration tool (Alembic) and retire manual recreate.
• Map .env Discord channel ids into config for deterministic routing.
• Real Gemini/Claude CLI runtime integration.
• Production SearchProvider.
• Version-string alignment; broader soak/load testing on J5/J6 health metrics.

v1.0.0

Nexus v1.0.0 — Operational Intelligence

Nexus Control Plane v1.0.0

Operational Intelligence

Highlights:
* Runtime Registry
* Gemini Runtime
* Claude Runtime
* Hermes Runtime
* Governance Layer
* Approval Workflows
* Persistent Memory
* Research Engine
* Daily Briefing Engine
* Communication Outbox
* Metrics Persistence
* Docker Sandboxing
* Recovery Framework
* Operational Validation
* Pilot Approval

Status:
RELEASED

Verdict:
GO