# release: 1.1.0-agentic — Phase H + Phase I shipped

## TL;DR

This PR brings `main` up to `1.1.0-agentic` — the agentic-AI release
on top of `1.0.0-rebuild`. Phase H added production-grade hardening
(cost meter + budget guard, eval harness with LLM-as-judge, Playwright
e2e against the live stack, single-VM deploy target — originally
Oracle Always Free, pivoted to AWS EC2 t4g.small after capacity
exhaustion, README rewrite for agentic positioning, prod security
guards, AI-trace observability).
Phase I added the agentic-AI signature layer (Lumen MCP server,
multi-agent tutor, self-critique authoring agent, learner-facing trace
surfaces, personalized learning-path agent). 627/627 backend tests
pass, frontend typecheck clean, coverage 73.7% (gate at 70%). Demo
deploy + Loom + hero screenshot land in follow-up activation tasks
before this PR merges to `legacy`.

## What shipped

The full release notes are below, copied verbatim from `CHANGELOG.md`.

```
## [1.1.0-agentic] - 2026-05-22

Phase H (production-grade hardening) + Phase I (agentic-AI signature
features) shipped on top of `1.0.0-rebuild`. 627/627 backend tests
pass, frontend typecheck clean, coverage 73.7% (gate at 70%).

### Added (v2 phase I — agentic features)
- **I1: Lumen MCP server.** New `apps/backend/app/mcp/` package
  exposes Lumen's surface as 9 MCP tools (`list_courses`,
  `get_course`, `search_lesson_content`, `ask_tutor`,
  `list_my_due_reviews`, `grade_review_card`, `create_course_draft`,
  `ingest_url_to_draft`, `list_my_progress`) over stdio (Claude
  Desktop) and streamable-HTTP (`claude mcp add lumen`) transports.
  OAuth 2.0 client-credentials flow with argon2-hashed secrets, RFC
  8414 metadata at `/.well-known/oauth-authorization-server`,
  15-minute JWT access tokens. Admin CRUD at
  `/api/v1/admin/mcp-clients`. CLI: `make mcp-token` mints a fresh
  client. `docs/mcp.md` is the operator guide; README install
  snippet replaces the `MCP_INSTALL_TBD` placeholder from H5.
- **I5: Personalized learning-path agent.** `/dashboard/path` —
  learner states a goal in plain English; a single LLM call
  consumes mastery + FSRS load + 20-course catalog digest and emits
  a structured plan (`milestones[]` + `next_action_today` +
  `rationale`). Validated against existing course slugs with
  one-shot retry on hallucinations. Monthly Celery beat job
  re-plans every active path whose `replanned_at` is older than 30
  days. Tables: `learning_paths` (partial-unique on
  `status='active'`) + `learning_path_steps`. Frontend: server
  component overview + client `TodayWidget` + `MilestoneTable`.
- **I2: Multi-agent tutor.** The Phase E1 single-shot RAG tutor is
  now a planner-orchestrator loop. Planner picks among 5 sub-agents
  per turn: `retriever` (wraps the E0 RAG with `audit=True`),
  `web_searcher` (Tavily free tier; gracefully no-ops when
  `TAVILY_API_KEY` is unset), `code_runner` (RestrictedPython 8.x
  sandbox, stdlib `math`/`statistics` only, 5 s hard timeout),
  `quiz_generator`, `concept_explainer`. Hard caps: 5 tool-call
  rounds + 3 orchestrator LLM round-trips per turn. Every step
  writes an `agent_traces` row via H7. Tutor API response gained
  `agent_trace[]` + `confidence` fields (backwards compatible).
  Frontend `AgentReasoningPanel` shows the per-turn plan + tool
  calls inline; first turn auto-expanded so the demo reads the
  agent thinking immediately.
- **I3: Self-critique authoring agent.** The Phase E2 outline
  generator is now a researcher → outliner → critic ↺ reviser →
  lesson-drafter → final-critic loop. Researcher pulls Tavily
  snippets + catalog neighbours into a 200-token research bundle.
  Critic scores `coverage`/`learning_arc`/`scope` on 0-5; reviser
  fires when mean < 4, max 3 revisions. Lesson-drafter reuses the
  existing `generate_lesson_body` + `generate_quiz` per accepted
  lesson. Final-critic rates the full course before the instructor
  publishes. Every step persists a `course_draft_traces` row.
  Frontend `/studio/draft/[courseId]` renders the timeline + final
  score badge + "Publish anyway" escape hatch. New endpoint
  `POST /api/v1/studio/ai/draft-course`.
- **I4: Learner-facing agent-trace surface.** Two read-only
  drill-down routes built on top of the H7 tables:
  `/dashboard/tutor/{conversation_id}/turn/{message_id}` (Surface
  A — learner sees the full per-turn agent thinking, owner-only)
  and `/studio/draft/{course_id}/replay` (Surface B — instructor
  steps through the draft's reasoning with play/pause/scrub,
  owner-or-admin). Shared `TraceTimeline` / `TraceStepCard` /
  `RetrievalChunkList` / `CostBadge` components carry the
  Workbench tokens through. Wires a "See the full trace →" link
  from I2's inline `AgentReasoningPanel`. `docs/agent-traces.md`
  documents the privacy model + retention policy.

### Added (v2 phase H — wave 2)
- **H4: Single-VM live demo deployment** (originally Oracle Always
  Free A1; pivoted to AWS EC2 t4g.small on 2026-05-25 after Frankfurt
  A1 capacity stayed saturated for 24h and Oracle's PAYG region-cap
  blocked the Stockholm fallback). One ARM Ubuntu 24.04 VM runs the
  unmodified `docker-compose.prod.yml` (web + worker + beat + postgres
  + redis + qdrant) behind Caddy 2 for automatic Let's Encrypt TLS;
  Cloudflare in front is optional for DDoS / cache. See
  `docs/deployment/aws-vps.md` for the current runbook
  (`scripts/aws-bootstrap.sh` provisions the host in one pass: 4 GB
  swapfile, non-root admin, ufw, fail2ban, Docker, Caddy, the compose
  stack). The same stack works unmodified on Oracle A1 / Hetzner CAX11
  / other ARM64 Ubuntu 24.04 boxes — only the VM acquisition step
  changes. Cost target on AWS: **$0/mo** on a new-account Free Plan
  (6 months, up to $200 credits) through Dec 31 2026.
- **H5: README rewrite for agentic-AI positioning.** 11-section
  README with Mermaid architecture diagram, agentic-patterns resume
  bullets, eval-scores block, single-VM deploy summary (currently
  AWS t4g.small), MCP install snippet, "Built by" footer.
- **H7: AI-trace observability surface.** New tables `agent_traces`
  + `retrieval_audits` (migration `0023`), `app.services.agent_tracer`
  with SAVEPOINT-isolated writes, OpenLLMetry auto-instrumentation,
  admin observability dashboard at `/admin/observability`.

### Added (v2 phase H — wave 1)
- **H1: LLM cost meter + per-user budget guard.** `llm_calls` table
  + `BudgetExceededError` (HTTP 429) at the rolling-24h spend cap
  (`$1.00` default).
- **H2: Eval harness with LLM-as-judge + golden datasets.** Three
  suites under `apps/backend/evals/` (tutor / authoring / ingest).
  CI smoke runs 3 items per PR.
- **H3: Playwright e2e against the live stack.** Five spec files
  + helpers under `apps/frontend/tests/e2e/` + `e2e.yml` workflow.
- **H6: Production-exposure security pass.** Refresh-reuse alarm,
  `prod_guards.assert_production_safe()` lifespan check, CORS
  loopback filter, `docs/security.md` threat model.

### Fixed (rebuild phase G)
G1–G6 land contrast / test-isolation / docker-rebuild / test-staleness
fixes from the rebuild track — full per-issue details retained in
`CHANGELOG.md`.
```

> **Note:** the bullets above under Phase H wave 1/2 are condensed for
> PR readability. The unabridged per-feature notes live in
> `CHANGELOG.md` under the same `[1.1.0-agentic]` section.

## Architecture diff vs `1.0.0-rebuild`

The agentic layer that `1.1.0-agentic` adds on top of the rebuild:

- **Multi-agent tutor (I2)** — planner-orchestrator loop with 5
  sub-agents (`retriever`, `web_searcher`, `code_runner`,
  `quiz_generator`, `concept_explainer`) replaces the single-shot RAG
  tutor; hard-capped at 5 tool rounds + 3 orchestrator round-trips.
- **Lumen MCP server (I1)** — Lumen's surface exposed as 9 MCP tools
  over stdio + streamable-HTTP, OAuth client-credentials with
  argon2-hashed secrets, RFC 8414 metadata, admin CRUD.
- **Self-critique authoring (I3)** — researcher → outliner → critic ↺
  reviser → lesson-drafter → final-critic loop with `course_draft_traces`
  persistence; replaces the Phase E2 single-shot outline generator.
- **Personalized learning-path agent (I5)** — goal-conditioned planner
  consuming mastery + FSRS + catalog; monthly Celery beat re-plan.
- **Agent-trace observability (H7 + I4)** — `agent_traces` +
  `retrieval_audits` tables, SAVEPOINT-isolated writes, learner-facing
  Surface A drill-down and instructor-facing Surface B replay.
- **Eval harness (H2)** — three golden-dataset suites with
  LLM-as-judge, JSONL reports, admin dashboard, CI smoke gate.
- **Production hardening (H1 + H6)** — per-user 24h budget guard,
  prod-boot guards, refresh-reuse alarm, CORS loopback filter.

## Verification

This release passed the following gates locally on the rebuild branch
before the cut commit:

- Backend `pytest`: **627 / 627** passing.
- Backend coverage: **73.7%** (gate at 70%).
- Frontend `pnpm typecheck`: clean.
- Frontend `pnpm test` (vitest): passing.
- Playwright e2e suite (`make test.e2e`): the five `H3` spec files
  exercise register→verify→reset, enrol→quiz→certificate+badge,
  studio draft→AI-outline→publish→analytics, tutor citations vs
  catalog, and multi-modal ingest→commit→drafts against the live
  docker stack.
- WCAG 2.2 AA axe-core gate (`make a11y`): G1 light-mode primary fix
  unblocked the seven previously-failing routes.

Activation tasks (Loom recording, real eval-score backfill, hero
screenshot, deploy verification) run in parallel before merge to
`legacy` — see the checklist below.

## Definition of done (operator checklist)

- [ ] `main` pushed to `origin/main` (fast-forward from
      `f698610` → `15cb431` or a descendant).
- [ ] AWS t4g.small VM live and demo URL works in incognito.
- [ ] MCP server submitted to `registry.modelcontextprotocol.io` and
      `claude mcp add lumen` works against the live demo.
- [ ] Real eval score in README replaces the placeholder
      (`tutor eval: X/5`).
- [ ] 90-second Loom recorded + linked from the README hero band.
- [ ] Hero screenshot committed (A5 owns the capture — verify the PR
      diff includes `docs/screenshots/hero.png` or equivalent).
- [ ] Applications sent (the portfolio-activation milestone this
      release was built for).

## Merge strategy

**Recommended: `merge-commit` (not squash).** The 60+ commits between
`f698610` (origin/main) and `15cb431` (this release) are the
auditable, phase-tagged record of the rebuild + Phase H + Phase I
work. Squashing them would collapse the architectural story into a
single opaque commit, which defeats the point of a portfolio anchor.

Operator command when ready to merge:

```bash
gh pr merge --merge \
  --subject "release: 1.1.0-agentic — Phase H + Phase I shipped" \
  --body-file docs/release/1.1.0-agentic-pr-body.md
```

(Drop `--body-file` if GitHub already shows the PR body inline — `gh
pr merge --merge` will reuse the PR title + body by default.)

## Footer — the commands wrapped by `make publish-rewrite`

The Makefile target `publish-rewrite` (Phase A6 activation) runs these
two commands after a `git log` preview + an interactive `[y/N]`
prompt:

```bash
git push origin main
gh pr create \
  --base legacy \
  --head main \
  --title "release: 1.1.0-agentic — Phase H + Phase I shipped" \
  --body-file docs/release/1.1.0-agentic-pr-body.md
```

`origin/main` is an ancestor of local `main` (fast-forward
push — no `--force` flag), so the push is non-destructive.
