praxis/.ciagent/PLAN-v0.4-operator-tier.md

# Praxis — v0.4 Execution Plan (Operator Tier — Cohort Dashboard + Auth + Postgres)

> **Milestone:** v0.4 (Operator tier — cohort dashboard, auth, Postgres)
> **Phases:** 2 execution phases (P1: operator foundation — Postgres + auth; P2: cohort dashboard + aggregation) + final phase (P3: review + ship)
> **Ship:** v0.1.6 (Phase 0, already staged) → v0.1.7 (P1) → v0.1.8 (P2) → v0.1.9 (P3 = v0.4 milestone release)
> **Status:** plan
> **Autonomy:** full
> **Parallelization:** enabled, max 5 concurrent agents
> **Personas active (6):** lead-developer, backend-engineer, frontend-engineer (REACTIVATED), data-engineer (EXPANDED), security-engineer (RETAINED), devops-engineer (REACTIVATED)
> **Date:** 2026-08-04

---

## Phase Split Rationale

v0.4 is split into 2 execution phases + final review, following the ROADMAP:

- **P1 (Operator Foundation — Postgres + Auth):** docker-compose Postgres 16 service, asyncpg pool, Postgres operator-tier schema (5 tables), operator auth (argon2id + signed stateless cookies + slowapi rate limit), VC issuer key migration SQLite→Postgres (archive v0.3 public key as `superseded`, fresh v0.4 keypair), operator bootstrap CLI. No UI. Shippable as `v0.1.7`. Covers: REQ-MT-01, REQ-AUTH-01, REQ-NFR-AUTH-01, REQ-NFR-MT-01 + REQ-MT-02 (schema foundation).
- **P2 (Cohort Dashboard + Aggregation):** cohort aggregation pipeline (on-session-end async hook + nightly reconciliation at 03:00 CT, k-anonymity ≥ 10 write-time suppression), React cohort dashboard (3 views: practice/mastery/failure-patterns), `/api/operator/*` cohort endpoints (auth-gated), React Router + SPA fallback. Shippable as `v0.1.8`. Covers: REQ-DASH-01, REQ-NFR-DASH-01, REQ-NFR-DASH-02 + REQ-MT-02 (pipeline completion).
- **P3 (Final — Review + Ship):** multi-persona review, audit, merge to main, milestone release `v0.1.9` = v0.4.

The split keeps P1 a clean infra/auth milestone (no UI, verifiable by tests + CLI), and P2 a clean feature milestone (dashboard + pipeline, verifiable by UI + API tests).

---

## Key Decisions Honored (D-050..D-057 + research)

| Decision | Honored in | How |
|----------|-----------|-----|
| D-050 (asyncpg pool min 1/max 10 on app.state.pg_pool via lifespan) | SLICE-01 | lifespan creates pool on startup, closes on shutdown |
| D-051 (VC key migration — fresh keypair in Postgres, v0.3 public key archived as superseded) | SLICE-04, SLICE-06 | migration script archives v0.3 pubkey + generates v0.4 key; e2e test verifies old VC |
| D-052 (scripts/create-operator.py CLI) | SLICE-05 | idempotent insert, argon2id hash, env-provided credentials |
| D-053 (3 dashboard views) | SLICE-08, SLICE-09 | practice/mastery/failure-patterns endpoints + React components |
| D-054 (async fire-and-forget hook + nightly 03:00 CT) | SLICE-07 | asyncio.Task on session end + in-process scheduler loop |
| D-055 (nightly pg_dump to volume, 7-day retention) | SLICE-02 | host-side cron script, %u rolling 7-file |
| D-056 (signed stateless cookies, Starlette SessionMiddleware) | SLICE-03 | itsdangerous HMAC-SHA256, no sessions table |
| D-057 (server-side auth on every /api/operator/* + React guard) | SLICE-03, SLICE-09 | router-level dependencies + GET /api/operator/me on mount |
| R-AUTH-01 (config-driven PRAXIS_COOKIE_SECURE) | SLICE-03 | env var default true; false for HTTP pilot with logged WARNING |
| SPA fallback for React Router /operator/* | SLICE-10 | catch-all route before StaticFiles mount |
| Inline SVG sparklines (zero-dep) | SLICE-09 | ~50 LOC component, no chart library |
| cohort_aggregates plain table (not partitioned) | SLICE-01 | schema ships with (path, window_start) index, no partitioning |

---

# Phase 1 — Operator Foundation (Postgres + Auth)

**Branch:** `phase/01-operator-foundation` → merged to `milestone/v0.4-operator-tier`
**Ship:** `v0.1.7` (patch release, feature milestone type)
**REQ-IDs covered:** REQ-MT-01, REQ-AUTH-01, REQ-NFR-AUTH-01, REQ-NFR-MT-01, REQ-MT-02 (schema foundation)
**Slices:** 6 vertical slices in 3 waves
**Total tasks:** 29

| Wave | Slices | Parallel slots | Description |
|------|--------|----------------|-------------|
| 1 | SLICE-01, SLICE-02 | 2 | Postgres DB foundation (compose + pool + schema + PgStore) + devops config (.env.example + CT bump + backup script) — disjoint file territories |
| 2 | SLICE-03, SLICE-04, SLICE-05 | 3 | Operator auth module + VC issuer key migration + bootstrap CLI — all depend on SLICE-01 schema/pool; disjoint module territories |
| 3 | SLICE-06 | 1 | P1 integration — __main__.py wiring (lifespan+pool, SessionMiddleware, auth routes, verification store swap) + integration tests + VC migration e2e |

### Wave dependency graph (P1)

```
Wave 1 ──────────────────────────────────────────────────────
  SLICE-01 (Postgres DB foundation: compose + pool + schema + PgStore)
  SLICE-02 (devops config: .env.example + CT bump + backup cron)
        │
        ▼
Wave 2 ──────────────────────────────────────────────────────
  SLICE-03 (operator auth: argon2id + cookies + rate limit + deps)  ← depends on SLICE-01 (operators table + PgStore)
  SLICE-04 (VC key migration: IssuerKeyStore + archive v0.3 key)    ← depends on SLICE-01 (issuer_keys table + PgStore)
  SLICE-05 (operator bootstrap CLI: create-operator.py)             ← depends on SLICE-01 (PgStore + operators table)
        │
        ▼
Wave 3 ──────────────────────────────────────────────────────
  SLICE-06 (P1 integration: __main__.py wiring + e2e tests)  ← depends on SLICE-03, SLICE-04, SLICE-05
```

### Persona load distribution (P1)

| Persona | Tasks | Primary territory |
|---------|-------|-------------------|
| lead-developer | 5 | docker-compose.yml, pyproject.toml, integration orchestration |
| data-engineer | 8 | db/pg_schema.sql, db/pg_migrations/, db/pg_migrate.py, db/pg_store.py |
| backend-engineer | 5 | server/__main__.py (lifespan + wiring), integration tests |
| security-engineer | 8 | server/auth/ (argon2 + cookies + rate limit + deps), server/vc/ (IssuerKeyStore + migration) |
| devops-engineer | 5 | .env.example, scripts/proxmox/lxc-clone.sh, scripts/backup-pg.sh, scripts/create-operator.py |
| frontend-engineer | 0 | not active in P1 (no UI) |

---

## SLICE-01: Postgres DB Foundation (W1)

- **Goal:** Stand up Postgres 16 as a second Docker service with asyncpg pool, migration runner, and the full operator-tier schema (5 tables). The critical-path foundation for all P1/P2 work.
- **REQ-IDs covered:** REQ-MT-01 (Postgres store), REQ-NFR-MT-01 (Postgres-in-LXC without destabilizing learner service), REQ-MT-02 (schema foundation — cohort_aggregates table)
- **Wave:** 1
- **Dependencies:** none
- **Primary persona:** lead-developer
- **Supporting personas:** data-engineer (schema + migrations + pg_store + pg_migrate), backend-engineer (pool lifespan), devops-engineer (compose volumes/network consultation)

### Tasks

#### TASK-01-01 — docker-compose Postgres service + praxis-net + volumes
- **Persona:** lead-developer
- **File:** `docker-compose.yml` (extend)
- **Content:** Add `postgres` service (postgres:16-slim, restart: unless-stopped, env: POSTGRES_USER/PASSWORD/DB/PGDATA, env_file server.env, pgdata+pgbackups volumes, pg_isready healthcheck 10s/5ret/5s timeout, praxis-net network, no published ports). Add `praxis` service `depends_on: { postgres: { condition: service_healthy } }` + `networks: [praxis-net]`. Add `pgdata`, `pgbackups` named volumes + `praxis-net` bridge network. Keep existing `praxis-data` volume + all v0.2 env vars.
- **Acceptance criteria:** `docker compose config` validates; `docker compose up -d postgres` → healthcheck passes within 30s; praxis service starts after postgres healthy; no published port on postgres (verified `docker port` shows nothing).

#### TASK-01-02 — pyproject.toml new deps
- **Persona:** lead-developer
- **File:** `pyproject.toml` (extend)
- **Content:** Add `asyncpg>=0.29`, `argon2-cffi>=23.1`, `slowapi>=0.1` to dependencies. These are the 3 new v0.4 pip deps (RESEARCH-v0.4 §new-deps).
- **Acceptance criteria:** `pip install -e .` succeeds; `import asyncpg`, `import argon2`, `import slowapi` all work.

#### TASK-01-03 — asyncpg pool lifespan in server/__main__.py
- **Persona:** backend-engineer
- **File:** `server/__main__.py` (extend — add lifespan)
- **Content:** Add `@asynccontextmanager async def lifespan(app)` that creates `asyncpg.create_pool(dsn=os.environ["PRAXIS_PG_DSN"], min_size=1, max_size=10, command_timeout=10)` on `app.state.pg_pool`, runs `pg_migrate.apply_pg_migrations(pool)` on startup, closes pool on shutdown. Pass `lifespan=lifespan` to `FastAPI(...)`. If `PRAXIS_PG_DSN` is unset, log WARNING and skip pool (graceful — dev mode without Postgres). The existing `_store` (PraxisStore/SQLite) remains for learner state.
- **Acceptance criteria:** With Postgres running, `app.state.pg_pool` is an asyncpg.Pool instance on startup; migrations applied (tables exist); pool closed cleanly on shutdown. Without Postgres (no DSN), server starts with WARNING, learner voice loop still works (SQLite unaffected).

#### TASK-01-04 — db/pg_migrate.py — asyncpg migration runner
- **Persona:** data-engineer
- **File:** `db/pg_migrate.py` (new)
- **Content:** Mirror `db/migrate.py` pattern. `async def apply_pg_migrations(pool: asyncpg.Pool) -> list[str]` — creates `_pg_migrations` tracking table, reads `db/pg_migrations/*.sql` in sorted order, applies pending migrations within a transaction, records in `_pg_migrations`. Idempotent — no-op if all applied. Retries on connection failure (3 attempts, 2s backoff — R-MT-02 mitigation).
- **Acceptance criteria:** Re-running `apply_pg_migrations(pool)` is a no-op (returns empty list). Migration files apply in order. Connection failure retries 3x then raises.

#### TASK-01-05 — db/pg_schema.sql + db/pg_migrations/0001_operator_tier.sql
- **Persona:** data-engineer
- **Files:** `db/pg_schema.sql` (new — reference), `db/pg_migrations/0001_operator_tier.sql` (new — applied by pg_migrate)
- **Content:** 5 tables per ARCHITECTURE.md §Postgres Schema:
  - `operators` (id UUID DEFAULT gen_random_uuid() PK, username TEXT UNIQUE NOT NULL, password_hash TEXT NOT NULL, display_name TEXT, role TEXT DEFAULT 'operator', is_active BOOLEAN DEFAULT TRUE, created_at TIMESTAMPTZ DEFAULT now(), last_login_at TIMESTAMPTZ)
  - `issued_credentials` (id UUID PK, operator_id UUID REFERENCES operators, learner_ref TEXT NOT NULL, vc_type TEXT, payload_jsonb JSONB NOT NULL, signature_b64 TEXT NOT NULL, status TEXT DEFAULT 'active', issued_at TIMESTAMPTZ DEFAULT now(), revoked_at TIMESTAMPTZ)
  - `mastery_gate_events` (id UUID DEFAULT gen_random_uuid() PK, learner_ref TEXT NOT NULL, scenario_id TEXT, path_id TEXT NOT NULL, gate_outcome TEXT, rubric_scores_jsonb JSONB, recorded_at TIMESTAMPTZ DEFAULT now(), source TEXT DEFAULT 'sync')
  - `cohort_aggregates` (path TEXT NOT NULL, metric TEXT NOT NULL, window_start DATE NOT NULL, window_end DATE NOT NULL, value NUMERIC, cell_count INTEGER NOT NULL DEFAULT 0, cell_suppressed BOOLEAN NOT NULL DEFAULT FALSE, updated_at TIMESTAMPTZ DEFAULT now(), PRIMARY KEY (path, metric, window_start)) — **plain table, NOT partitioned** (D-050..D-053; RESEARCH-v0.4 §1.7). Index on `(path, window_start)`.
  - `issuer_keys` (id TEXT PK, public_key TEXT NOT NULL, private_key_enc BYTEA, status TEXT NOT NULL DEFAULT 'active', created_at TIMESTAMPTZ DEFAULT now())
  - All use `gen_random_uuid()` (PG16 core, no extension — R-MT-05 verified).
- **Acceptance criteria:** `apply_pg_migrations(pool)` creates all 5 tables + `_pg_migrations` tracking table. `\d operators` in psql shows expected columns. `gen_random_uuid()` works without extension. `cohort_aggregates` has no partitioning (confirmed via `\d+`).

#### TASK-01-06 — db/pg_store.py — PgStore class
- **Persona:** data-engineer
- **File:** `db/pg_store.py` (new)
- **Content:** `class PgStore` — accepts an `asyncpg.Pool` in constructor. Methods:
  - Operator CRUD: `get_operator_by_username(username) -> dict | None`, `get_operator_by_id(id) -> dict | None`, `update_last_login(id)`, `insert_operator(username, password_hash, display_name) -> str` (ON CONFLICT DO NOTHING, returns id).
  - Cohort aggregate read: `get_cohort_aggregates(path, metric, since_date) -> list[dict]` (returns rows with value, cell_count, cell_suppressed, updated_at).
  - Cohort aggregate write: `upsert_cohort_aggregate(path, metric, window_start, window_end, value, cell_count, cell_suppressed)` (ON CONFLICT (path, metric, window_start) DO UPDATE).
  - Issuer key methods (implements IssuerKeyStore protocol — SLICE-04): `init_issuer_key(key_id, public_key, private_key_enc)`, `get_active_signing_key_row() -> dict | None`, `get_public_key_row(key_id) -> dict | None`, `set_issuer_key_superseded(key_id)`.
  - Credential methods: `insert_credential(...)`, `get_credential(id) -> dict | None`, `set_credential_status(id, status)`.
  - Mastery gate event: `record_gate_event(learner_ref, path_id, scenario_id, gate_outcome, rubric_scores_jsonb)`.
  - All async, use `pool.acquire()` context manager.
- **Acceptance criteria:** Each method has a unit test with a real Postgres pool (testcontainers or local PG). Round-trip insert+query works. ON CONFLICT upsert is idempotent. No cross-DB joins (D-031). `learner_ref` is opaque string (not FK).

#### TASK-01-07 — PgStore + pool integration test
- **Persona:** data-engineer
- **File:** `tests/test_pg_store.py` (new)
- **Content:** Integration test requiring a Postgres instance (skip if `PRAXIS_PG_DSN` not set). Tests: pool creation, migration application, operator insert+query, cohort_aggregate upsert idempotency, issuer_key insert+query, credential insert+query. Verifies the full DB stack works end-to-end.
- **Acceptance criteria:** All tests pass when Postgres is available; tests skip gracefully when `PRAXIS_PG_DSN` is unset (no hard CI dependency on Postgres).

---

## SLICE-02: DevOps Config — .env.example + CT Bump + Backup (W1)

- **Goal:** Update deployment config for Postgres-in-LXC: operator env vars, CT memory bump (4→6GB), nightly backup cron script.
- **REQ-IDs covered:** REQ-NFR-MT-01 (Postgres-in-LXC without destabilizing — CT sizing + backup)
- **Wave:** 1
- **Dependencies:** none (parallel with SLICE-01 — disjoint files: .env.example, scripts/proxmox/ vs docker-compose.yml, db/, server/)
- **Primary persona:** devops-engineer
- **Supporting personas:** lead-developer (compose env consultation)

### Tasks

#### TASK-02-01 — .env.example operator vars
- **Persona:** devops-engineer
- **File:** `.env.example` (extend)
- **Content:** Add v0.4 operator vars with documentation comments:
  - `PRAXIS_PG_PASSWORD` (Postgres password — secret)
  - `PRAXIS_PG_DSN` (full DSN: `postgresql://praxis:${PRAXIS_PG_PASSWORD}@postgres:5432/praxis`)
  - `PRAXIS_COOKIE_SECRET` (≥32 bytes random — secret)
  - `PRAXIS_COOKIE_SECURE` (default `true`; set `false` for HTTP pilot — R-AUTH-01)
  - `PRAXIS_BOOTSTRAP_OPERATOR_USER` (initial operator username — secret)
  - `PRAXIS_BOOTSTRAP_OPERATOR_PASS` (initial operator password — secret)
  - `PRAXIS_VC_ISSUER_KEY` (VC issuer root key — already in v0.3, document for v0.4 migration)
- **Acceptance criteria:** `.env.example` is documentation-only (no real secrets). All vars have comments explaining purpose + when to set. File is gitignored-safe (`.env.example` is committed, `.env.secrets` is not — verified in `.gitignore`).

#### TASK-02-02 — CT memory bump in lxc-clone.sh
- **Persona:** devops-engineer
- **File:** `scripts/proxmox/lxc-clone.sh` (extend)
- **Content:** Change `memory=${PROXMOX_MEMORY_MB:-4096}` → `memory=${PROXMOX_MEMORY_MB:-6144}` (4GB→6GB per REQ-NFR-MT-01, RESEARCH-v0.4 §1.1). Add comment explaining Postgres ~400MB + praxis ~500MB + Docker ~200MB + build headroom ~1GB + margin.
- **Acceptance criteria:** `lxc-clone.sh` defaults to 6144MB. Existing override via `PROXMOX_MEMORY_MB` env still works. Bats tests (if any check memory) updated.

#### TASK-02-03 — Backup cron script
- **Persona:** devops-engineer
- **File:** `scripts/backup-pg.sh` (new)
- **Content:** Host-side cron script (decoupled from praxis service uptime — RESEARCH-v0.4 §1.5). Runs `docker compose exec -T postgres pg_dump -U praxis -Fc praxis -f /backups/praxis-$(date +%u).dump`. The `%u` = day-of-week 1-7 → rolling 7-file retention with zero cleanup logic (D-055). Includes a restore drill comment block: `pg_restore --clean --if-exists /backups/praxis_3.dump` (never restore into live DB without stopping praxis first). Script is idempotent — overwrites the day-of-week file.
- **Acceptance criteria:** Script executes without error when postgres is running. Produces a compressed dump file at `/backups/praxis-<dow>.dump`. Re-running overwrites the same file. Restore drill documented in comments. Script is POSIX-sh compatible (no bashisms).

---

## SLICE-03: Operator Auth Module (W2)

- **Goal:** Implement the operator auth stack: argon2id password hashing, signed stateless cookies (Starlette SessionMiddleware), slowapi rate limiting, and the `current_operator` dependency. The auth route handlers (login/logout/me) are in this slice; __main__.py mounting is in SLICE-06.
- **REQ-IDs covered:** REQ-AUTH-01, REQ-NFR-AUTH-01
- **Wave:** 2
- **Dependencies:** SLICE-01 (operators table + PgStore for operator lookup)
- **Primary persona:** security-engineer
- **Supporting personas:** backend-engineer (FastAPI route patterns)

### Tasks

#### TASK-03-01 — argon2id password hashing
- **Persona:** security-engineer
- **File:** `server/auth/passwords.py` (new)
- **Content:** `from argon2 import PasswordHasher`. `_ph = PasswordHasher()` (defaults: time_cost=3, memory_cost=64MiB, parallelism=4 — exceeds OWASP minimums per RESEARCH-v0.4 §2.1). `hash_password(plain: str) -> str`, `verify_password(stored_hash: str, plain: str) -> bool` (catches VerifyMismatchError → False), `needs_rehash(stored_hash: str) -> bool` (delegates to `_ph.check_needs_rehash`). Login flow calls `needs_rehash` after successful verify → rehash if params bumped.
- **Acceptance criteria:** hash→verify round-trip works. Wrong password returns False (no exception). `needs_rehash` returns False for current defaults, True if params are bumped. Hashing latency < 1s (R-AUTH-02 — single operator, low frequency).

#### TASK-03-02 — Signed cookie configuration (SessionMiddleware)
- **Persona:** security-engineer
- **File:** `server/auth/cookies.py` (new)
- **Content:** `def get_session_middleware_kwargs() -> dict` — returns kwargs for `SessionMiddleware`: `secret_key=os.environ["PRAXIS_COOKIE_SECRET"]`, `session_cookie="praxis_op"`, `max_age=28800` (8h — D-041), `httponly=True`, `samesite="strict"`, `secure=_env_bool("PRAXIS_COOKIE_SECURE", True)`, `path="/"`. If `PRAXIS_COOKIE_SECURE=false`, log WARNING: "Cookie Secure flag disabled — HTTP pilot mode (R-AUTH-01). Do not use in production." `_env_bool` parses "true"/"false"/"1"/"0". If `PRAXIS_COOKIE_SECRET` is unset, generate a random one + log WARNING (dev only — not for pilot).
- **Acceptance criteria:** Cookie kwargs match D-041/D-056 spec. `secure=False` logs WARNING. Missing secret generates random + WARNING. Cookie name is `praxis_op` (distinct from any future learner cookie).

#### TASK-03-03 — Login rate limiter (slowapi)
- **Persona:** security-engineer
- **File:** `server/auth/rate_limit.py` (new)
- **Content:** `from slowapi import Limiter`. `limiter = Limiter(key_func=get_remote_address)` (in-memory backend, single-instance — D-041). `def rate_limit_login() -> callable` — returns a decorator `@limiter.limit("5/minute")` for the login route. 429 + `Retry-After` header on exceed. Document the hand-rolled counter fallback in comments (RESEARCH-v0.4 §2.5).
- **Acceptance criteria:** 6th login attempt within 1 minute returns 429 with Retry-After. Rate limit is per-IP. Counter resets after 1 minute. R-AUTH-03 (in-memory lost on restart) documented as accepted pilot risk.

#### TASK-03-04 — current_operator dependency
- **Persona:** security-engineer
- **File:** `server/auth/dependencies.py` (new)
- **Content:** `async def current_operator(request: Request) -> Operator` — reads `request.session.get("operator_id")`; if missing → raise `HTTPException(401, "not authenticated")`; fetches operator from PgStore by id; if not found or `is_active=False` → 401 + clear session; returns `Operator` dataclass (id, username, display_name, role). This is the server-side auth enforcement (D-057) — every `/api/operator/*` protected route uses `Depends(current_operator)`.
- **Acceptance criteria:** No cookie → 401. Invalid/expired cookie → 401. Valid cookie + active operator → returns Operator. Valid cookie + inactive operator → 401 + session cleared. The dependency never trusts the client (D-057).

#### TASK-03-05 — Auth route handlers (login, logout, me)
- **Persona:** security-engineer
- **File:** `server/auth/routes.py` (new)
- **Content:** `APIRouter(prefix="/api/operator")` with:
  - `POST /login` — rate-limited (TASK-03-03). Body: `{username, password}`. Fetches operator from PgStore, `verify_password`, on success sets `request.session["operator_id"] = op.id`, updates `last_login_at`, returns `{operator: {id, username, display_name}}`. On failure → 401. If `needs_rehash` → rehash + update store.
  - `POST /logout` — `Depends(current_operator)` — clears `request.session`, returns `{ok: true}`. (Stateless — client also clears cookie; D-056.)
  - `GET /me` — `Depends(current_operator)` — returns `{operator: {id, username, display_name, role}}`. This is the React route guard endpoint (D-057).
  - Login + logout are outside the protected router (login is rate-limited, not auth-gated; logout is auth-gated but on the same router).
- **Acceptance criteria:** Login with correct creds → 200 + cookie set. Login with wrong creds → 401 + no cookie. 6th attempt → 429. `/me` with valid cookie → 200. `/me` without cookie → 401. `/logout` clears session.

#### TASK-03-06 — Auth unit tests
- **Persona:** security-engineer
- **File:** `tests/test_auth.py` (new)
- **Content:** Unit tests for passwords (hash/verify/rehash), cookie config (secure flag logic, warning on false), rate limiter (5/min threshold), current_operator dependency (401 cases, active/inactive), login/logout/me route handlers (with mocked PgStore). Tests do not require a real Postgres (mock PgStore).
- **Acceptance criteria:** All tests pass with mocked PgStore. Coverage: password verify fail, rate limit, 401 on missing/invalid/expired cookie, 401 on inactive operator, rehash on login.

---

## SLICE-04: VC Issuer Key Migration (W2)

- **Goal:** Migrate the VC issuer key store from SQLite to Postgres. Refactor `issuer_keys.py` to an `IssuerKeyStore` protocol (both PraxisStore and PgStore implement it). Archive the v0.3 public key as `superseded` in Postgres. Generate a fresh v0.4 keypair. Update verification to use PgStore.
- **REQ-IDs covered:** REQ-MT-01 (issuer_keys in Postgres — partial)
- **Wave:** 2
- **Dependencies:** SLICE-01 (issuer_keys table + PgStore issuer key methods)
- **Primary persona:** security-engineer
- **Supporting personas:** data-engineer (PgStore issuer key implementation)

### Tasks

#### TASK-04-01 — IssuerKeyStore protocol/ABC
- **Persona:** security-engineer
- **File:** `server/vc/issuer_keys.py` (refactor)
- **Content:** Define `class IssuerKeyStore(Protocol)` with methods: `init_issuer_key(key_id, public_key, private_key_enc)`, `get_active_signing_key_row() -> dict | None`, `get_public_key_row(key_id) -> dict | None`, `set_issuer_key_superseded(key_id)`. Refactor existing functions (`init_issuer_key`, `get_active_signing_key`, `get_public_key_for_verification`, `rotate_key`) to accept `IssuerKeyStore` instead of `PraxisStore`. The existing `PraxisStore` already implements these methods (duck-typing) — the protocol formalizes the interface. Keep `_encrypt_private_key`, `_decrypt_private_key`, `_verification_method`, `KeyPair` unchanged. R-VC-MIG-03 mitigation: both stores implement the same protocol.
- **Acceptance criteria:** `PraxisStore` passes `isinstance(store, IssuerKeyStore)` (or structural check). `PgStore` passes the same. Existing v0.3 tests still pass (PraxisStore path unchanged). No breaking change to function signatures beyond the type annotation.

#### TASK-04-02 — PgStore issuer key methods
- **Persona:** data-engineer
- **File:** `db/pg_store.py` (extend — SLICE-01 stubs, now full implementation)
- **Content:** Full implementation of the 4 IssuerKeyStore methods using asyncpg. `init_issuer_key` → INSERT with `gen_random_uuid()` or provided key_id. `get_active_signing_key_row` → SELECT WHERE status='active' ORDER BY created_at DESC LIMIT 1. `get_public_key_row` → SELECT WHERE id=$1 (queries by id, not status — **this is the superseded key fallback** per D-051). `set_issuer_key_superseded` → UPDATE status='superseded' WHERE id=$1. `private_key_enc` is BYTEA in Postgres (vs BLOB in SQLite).
- **Acceptance criteria:** All 4 methods work with real Postgres. `get_public_key_row` finds both active AND superseded keys by id (R-VC-MIG-01 mitigation — verification fallback). Round-trip: init → get_active → set_superseded → get_public_key(superseded id) still returns the row.

#### TASK-04-03 — VC key migration script
- **Persona:** security-engineer
- **File:** `server/vc/migrate_keys.py` (new)
- **Content:** `async def migrate_issuer_keys(sqlite_store: PraxisStore, pg_store: PgStore, root_key: bytes) -> dict` — the one-time migration procedure (D-051):
  1. Read v0.3 active public key from SQLite `issuer_keys` (status='active').
  2. Insert that public key into Postgres `issuer_keys` with status='superseded' (private key NOT migrated — only public key archived for verification).
  3. Generate a fresh Ed25519 keypair in Postgres `issuer_keys` with status='active' (encrypted at rest with root key — same nacl.SecretBox pattern).
  4. Return `{archived_key_id, new_key_id}`.
  Idempotent: if Postgres already has an active key, skip steps 2-3 (no-op). If Postgres has a superseded key matching the v0.3 key_id, skip step 2.
  **R-VC-MIG-01 mitigation: archive the v0.3 public key BEFORE activating the new key.** The script does step 2 before step 3.
- **Acceptance criteria:** Running the migration on a fresh Postgres: v0.3 public key appears as superseded, fresh key appears as active. Re-running is a no-op. v0.3 VCs still verify against the archived (superseded) public key.

#### TASK-04-04 — Verification endpoint store swap
- **Persona:** security-engineer
- **File:** `server/vc/verification.py` (extend)
- **Content:** `verify_credential` currently takes `PraxisStore`. Refactor to accept either `PraxisStore` (v0.3 SQLite) or `PgStore` (v0.4 Postgres) via the IssuerKeyStore protocol for key lookup. For credential lookup: try Postgres `issued_credentials` first; if not found, fall back to SQLite `issued_credentials` (v0.3 credentials remain in SQLite — no data migration per D-051 "no re-issuance"). The key lookup always uses the passed store. Add a `store` parameter that implements both credential + key lookup. **The __main__.py wiring (passing PgStore) is in SLICE-06.**
- **Acceptance criteria:** `verify_credential` works with PraxisStore (v0.3 path — existing tests pass). `verify_credential` works with PgStore (v0.4 path — new test). v0.3 credential in SQLite + v0.3 key archived as superseded in Postgres → verifies ✓.

#### TASK-04-05 — VC migration unit tests
- **Persona:** security-engineer
- **File:** `tests/test_vc_migration.py` (new)
- **Content:** Tests with mocked stores:
  - Migration script: v0.3 key archived as superseded, fresh key active. Idempotent re-run.
  - Verification with PgStore: v0.4 VC (active key) verifies ✓. v0.3 VC (superseded key) verifies ✓ (R-VC-MIG-01 — the critical test).
  - Verification fallback: `get_public_key_row` finds superseded key by id.
  - Root key handling: v0.4 active key encrypted with v0.4 root key (R-VC-MIG-02 — v0.3 root key kept for v0.3 SQLite path).
- **Acceptance criteria:** All tests pass. R-VC-MIG-01 explicitly tested: a v0.3 VC verifies against a Postgres store with the v0.3 public key archived as superseded.

---

## SLICE-05: Operator Bootstrap CLI (W2)

- **Goal:** Implement `scripts/create-operator.py` — the first-run CLI that creates the initial operator from env-provided credentials (D-052).
- **REQ-IDs covered:** REQ-AUTH-01 (operator account provisioning — partial)
- **Wave:** 2
- **Dependencies:** SLICE-01 (PgStore + operators table), SLICE-03 (argon2id hashing — TASK-03-01)
- **Primary persona:** devops-engineer
- **Supporting personas:** security-engineer (argon2id hashing pattern)

### Tasks

#### TASK-05-01 — scripts/create-operator.py
- **Persona:** devops-engineer
- **File:** `scripts/create-operator.py` (new)
- **Content:** CLI script that:
  1. Reads `PRAXIS_BOOTSTRAP_OPERATOR_USER` + `PRAXIS_BOOTSTRAP_OPERATOR_PASS` from env. If either missing → print error + exit 1 (R-BOOT-02).
  2. Reads `PRAXIS_PG_DSN` from env. If missing → print error + exit 1.
  3. Creates asyncpg pool, applies migrations (ensure schema exists).
  4. Hashes password with `argon2.PasswordHasher().hash(password)` (same defaults as TASK-03-01).
  5. `INSERT INTO operators (username, password_hash, display_name) VALUES ($1, $2, $3) ON CONFLICT (username) DO NOTHING` (idempotent — D-052).
  6. Prints `created` or `already exists` + exits 0.
  7. `--update` flag: `ON CONFLICT (username) DO UPDATE SET password_hash = excluded.password_hash` (force rehash — RESEARCH-v0.4 §open-questions #4).
  8. Retries on connection failure (3 attempts, 5s backoff — R-BOOT-01).
- **Acceptance criteria:** Running with valid env vars creates the operator. Re-running prints "already exists" (no password update). `--update` flag rehashes + updates. Missing env var → clear error + exit 1. Connection failure → retries 3x then clear error.

#### TASK-05-02 — config.json secrets scope + .env.secrets template
- **Persona:** devops-engineer
- **File:** `.ciagent/config.json` (extend secrets.scopes), `.ciagent/.env.secrets.example` (new — template, not the real secrets)
- **Content:** Add `operator` scope to `config.json` secrets.scopes: `{"name": "operator", "env_vars": ["PRAXIS_PG_PASSWORD", "PRAXIS_COOKIE_SECRET", "PRAXIS_BOOTSTRAP_OPERATOR_USER", "PRAXIS_BOOTSTRAP_OPERATOR_PASS", "PRAXIS_VC_ISSUER_KEY"]}`. Create `.env.secrets.example` documenting all operator secret vars (committed; the real `.env.secrets` is gitignored).
- **Acceptance criteria:** `config.json` validates. New scope appears in secrets.scopes. `.env.secrets.example` is committed (no real secrets). `.env.secrets` is gitignored (verified).

#### TASK-05-03 — Bootstrap CLI test
- **Persona:** devops-engineer
- **File:** `tests/test_create_operator.py` (new)
- **Content:** Test with mocked PgStore: create operator → verify exists in store. Re-run → "already exists" (no password update). `--update` → password updated. Missing env → exit 1. Verify password is argon2id hashed (not plaintext).
- **Acceptance criteria:** All tests pass with mocked PgStore. Password hash starts with `$argon2id$` (not plaintext). Idempotent on re-run.

---

## SLICE-06: P1 Integration (W3)

- **Goal:** Wire all P1 modules into `server/__main__.py`: lifespan pool, SessionMiddleware, auth routes, verification store swap. Run end-to-end P1 integration tests including the critical VC migration e2e test (R-VC-MIG-01).
- **REQ-IDs covered:** REQ-MT-01 (full integration), REQ-AUTH-01 (auth wired), REQ-NFR-AUTH-01 (auth NFRs verified end-to-end), REQ-NFR-MT-01 (Postgres + learner service coexist)
- **Wave:** 3
- **Dependencies:** SLICE-03 (auth module), SLICE-04 (VC migration), SLICE-05 (bootstrap CLI)
- **Primary persona:** backend-engineer
- **Supporting personas:** lead-developer (integration orchestration), security-engineer (VC migration e2e)

### Tasks

#### TASK-06-01 — __main__.py — mount SessionMiddleware + lifespan pool
- **Persona:** backend-engineer
- **File:** `server/__main__.py` (extend)
- **Content:** Add `SessionMiddleware` with kwargs from `server.auth.cookies.get_session_middleware_kwargs()`. Add the lifespan context manager (from TASK-01-03) to the FastAPI app. The lifespan creates the asyncpg pool + runs pg_migrate. Create a `PgStore(pool)` instance on `app.state.pg_store` when pool is available. Keep the existing `_store` (PraxisStore/SQLite) for learner state. `SessionMiddleware` is added BEFORE CORS middleware (middleware order: outermost first — SessionMiddleware should be outermost to sign cookies before CORS headers).
- **Acceptance criteria:** With Postgres: `app.state.pg_pool` + `app.state.pg_store` populated on startup. Without Postgres: server starts with WARNING, voice loop works, auth routes return 503 (service unavailable — no operator store). Cookie `praxis_op` is signed (itsdangerous).

#### TASK-06-02 — __main__.py — mount auth routes
- **Persona:** backend-engineer
- **File:** `server/__main__.py` (extend)
- **Content:** `from server.auth.routes import router as auth_router`. `app.include_router(auth_router)` — mounts `/api/operator/login`, `/api/operator/logout`, `/api/operator/me`. The auth routes use `app.state.pg_store` for operator lookup. If `pg_store` is None (no Postgres), auth routes return 503. Register auth routes BEFORE the StaticFiles mount (routes-before-static-mount constraint — carry-forward from v0.2).
- **Acceptance criteria:** `POST /api/operator/login` with valid creds → 200 + cookie. `GET /api/operator/me` with cookie → 200. Without cookie → 401. Routes are matched before StaticFiles (verified: `/api/operator/login` returns JSON, not index.html).

#### TASK-06-03 — __main__.py — swap verification endpoint to PgStore
- **Persona:** backend-engineer
- **File:** `server/__main__.py` (extend)
- **Content:** Update the existing `/vc/verify/{credential_id}` route: if `app.state.pg_store` is available, use it for issuer key lookup (PgStore) + credential lookup (try Postgres first, fall back to SQLite for v0.3 credentials per TASK-04-04). If `pg_store` is None (no Postgres), fall back to the existing PraxisStore path (v0.3 compat). Run the VC key migration on first boot: if PgStore has no active issuer key, call `migrate_issuer_keys(_store, pg_store, root_key)` (from TASK-04-03).
- **Acceptance criteria:** With Postgres: `/vc/verify/<v0.3-credential-id>` → verifies against archived superseded key in Postgres ✓. `/vc/verify/<v0.4-credential-id>` → verifies against active key in Postgres ✓. Without Postgres: `/vc/verify` falls back to SQLite (v0.3 compat). VC key migration runs once on first boot (idempotent).

#### TASK-06-04 — P1 integration test (auth end-to-end)
- **Persona:** backend-engineer
- **File:** `tests/test_p1_auth_integration.py` (new — requires Postgres, skip if no DSN)
- **Content:** End-to-end auth flow: create operator via bootstrap CLI → POST /login → GET /me → POST /logout → GET /me (401). Test rate limiting (6th attempt → 429). Test cookie attributes (httpOnly, SameSite=Strict, secure per PRAXIS_COOKIE_SECURE). Test 8h expiry (mock time or check max_age). Test that learner voice loop (`/health`, `/pipecat/webrtc`) is unaffected by auth (REQ-NFR-MT-01 — Postgres + learner service coexist).
- **Acceptance criteria:** Full auth flow works. Rate limit enforces 5/min. Cookie attributes match D-041/D-056. Learner voice loop unaffected (health check passes, WebRTC offer accepted — Postgres presence doesn't destabilize).

#### TASK-06-05 — VC migration e2e test (R-VC-MIG-01 — critical)
- **Persona:** security-engineer
- **File:** `tests/test_p1_vc_migration_e2e.py` (new — requires Postgres, skip if no DSN)
- **Content:** The critical R-VC-MIG-01 test:
  1. Seed SQLite with a v0.3 issuer key + a v0.3-issued credential (or use existing test fixtures).
  2. Start the server with Postgres → migration runs automatically.
  3. Verify Postgres has: 1 superseded key (v0.3 public key) + 1 active key (v0.4 fresh keypair).
  4. `GET /vc/verify/<v0.3-credential-id>` → `valid: true` (verifies against archived superseded key — **R-VC-MIG-01 PASS**).
  5. Issue a new v0.4 credential (via mastery flow or test helper) → `GET /vc/verify/<v0.4-credential-id>` → `valid: true`.
  6. Tamper v0.3 credential → verify fails.
  7. Re-run server → migration is no-op (idempotent).
- **Acceptance criteria:** v0.3 VC verifies against Postgres store with archived superseded key (R-VC-MIG-01 explicitly verified). v0.4 VC verifies against active key. Migration is idempotent. Tamper detection works.

---

# Phase 2 — Cohort Dashboard + Aggregation

**Branch:** `phase/02-cohort-dashboard` → merged to `milestone/v0.4-operator-tier`
**Ship:** `v0.1.8` (patch release, feature milestone type)
**REQ-IDs covered:** REQ-DASH-01, REQ-NFR-DASH-01, REQ-NFR-DASH-02, REQ-MT-02 (pipeline completion)
**Slices:** 4 vertical slices in 2 waves
**Total tasks:** 23

| Wave | Slices | Parallel slots | Description |
|------|--------|----------------|-------------|
| 1 | SLICE-07, SLICE-08, SLICE-09 | 3 | Cohort aggregation pipeline + operator API endpoints + React dashboard (parallel — disjoint file territories: server/cohort/ + session_recorder.py, server/operator/, client/) |
| 2 | SLICE-10 | 1 | P2 integration — __main__.py wiring (SPA fallback + operator router mount) + end-to-end aggregation→endpoint→dashboard tests |

### Wave dependency graph (P2)

```
Wave 1 ──────────────────────────────────────────────────────
  SLICE-07 (aggregation pipeline: hook + nightly + k-anon)   ← depends on P1 SLICE-01 (cohort_aggregates schema + PgStore)
  SLICE-08 (operator API endpoints: cohort/mastery/failure)  ← depends on P1 SLICE-03 (auth deps) + SLICE-01 (PgStore)
  SLICE-09 (React dashboard + Router + sparklines)           ← depends on P1 SLICE-03 (auth API contract) + API contract from SLICE-08
        │
        ▼
Wave 2 ──────────────────────────────────────────────────────
  SLICE-10 (P2 integration: SPA fallback + router mount + e2e tests)  ← depends on SLICE-07, SLICE-08, SLICE-09
```

### Persona load distribution (P2)

| Persona | Tasks | Primary territory |
|---------|-------|-------------------|
| backend-engineer | 11 | server/cohort/ (aggregation), server/operator/ (endpoints), server/__main__.py (SPA fallback + router mount), session_recorder.py |
| frontend-engineer | 7 | client/src/operator/, client/src/App.tsx, client/package.json |
| data-engineer | 3 | k-anonymity suppression SQL (supporting), cohort query optimization (supporting) |
| security-engineer | 1 | auth-gated endpoint verification (supporting in integration) |
| lead-developer | 1 | integration orchestration |

---

## SLICE-07: Cohort Aggregation Pipeline (W1)

- **Goal:** Implement the cohort aggregation pipeline: on-session-end async fire-and-forget hook, nightly reconciliation job at 03:00 CT, k-anonymity ≥ 10 write-time suppression. Chain the hook into `session_recorder.py` after the mastery flow.
- **REQ-IDs covered:** REQ-MT-02 (pipeline completion), REQ-NFR-DASH-02 (freshness ≤ 24h)
- **Wave:** 1
- **Dependencies:** P1 SLICE-01 (cohort_aggregates table + PgStore upsert method)
- **Primary persona:** backend-engineer
- **Supporting personas:** data-engineer (k-anonymity suppression SQL), security-engineer (learner_ref opaque — no PII)

### Tasks

#### TASK-07-01 — Aggregation logic + k-anonymity suppression
- **Persona:** backend-engineer
- **File:** `server/cohort/aggregator.py` (new)
- **Supporting:** data-engineer (suppression SQL)
- **Content:** `async def aggregate_session(pg_store: PgStore, session_outcome: dict) -> None` — computes k-anonymized aggregates for the affected `(path, metric, window_start)` bins and upserts to `cohort_aggregates`. The `session_outcome` dict contains: learner_ref (opaque string — D-031), path, scenario_id, outcome (pass/fail), rubric_scores, failure_mode, branch_path, timestamp.
  - Metrics computed: `sessions_count`, `active_learners_count`, `gate_open_rate`, `median_mastery_score`, `failure_mode_frequency`, `rubric_criterion_means`, `week_distribution`.
  - **k-anonymity suppression (D-034, REQ-NFR-DASH-01):** `COUNT(DISTINCT learner_ref) >= 10` check per cell. If < 10 → `cell_suppressed=TRUE`, `value=NULL`. Suppression is at write time (auditable — RESEARCH-v0.4 §3.1).
  - **Idempotent upsert:** `ON CONFLICT (path, metric, window_start) DO UPDATE SET value=excluded.value, cell_count=excluded.cell_count, cell_suppressed=excluded.cell_suppressed, updated_at=now()`.
  - **No raw learner PII in Postgres** (D-031): only aggregates + opaque `learner_ref` for distinct counting.
  - **7-day rolling window:** `window_start = today::date - 6`, `window_end = today::date`.
  - Pre-defined 2-D views only (path × week, path × outcome) — no arbitrary filters (R-DASH-02 mitigation).
- **Acceptance criteria:** Aggregate upsert is idempotent (re-run produces same result). Cells with < 10 distinct learners are suppressed (cell_suppressed=TRUE, value=NULL). No raw PII in Postgres (only aggregates + opaque learner_ref). 7-day window computed correctly.

#### TASK-07-02 — On-session-end async hook
- **Persona:** backend-engineer
- **File:** `server/cohort/hook.py` (new)
- **Content:** `async def on_session_end(pg_store: PgStore, session_outcome: dict) -> None` — calls `aggregator.aggregate_session`. Designed to be chained as an `asyncio.create_task` (fire-and-forget — D-054). Failures log + nightly job reconciles (no exception propagation to the caller). The hook is non-blocking — the session-end response returns immediately. If `pg_store` is None (no Postgres), no-op + log WARNING.
- **Acceptance criteria:** Hook is non-blocking (caller returns immediately). Hook failure logs but does not raise. No-Postgres → no-op + WARNING. Hook is idempotent (re-running with same session_outcome produces same aggregate).

#### TASK-07-03 — Nightly reconciliation job
- **Persona:** backend-engineer
- **File:** `server/cohort/nightly.py` (new)
- **Content:** `class NightlyScheduler` — in-process asyncio scheduler (no APScheduler — RESEARCH-v0.4 §3.4). `async def start(self, pg_store)` — loops: compute seconds until next 03:00 CT → `asyncio.sleep(seconds)` → `await self._reconcile(pg_store)` → repeat. `async def _reconcile(self, pg_store)` — recomputes all 7-day windows for all paths (idempotent upsert). If the service restarts, the scheduler resumes on startup (computes next 03:00). Failures log + retry next night (R-DASH-04). The reconciliation guarantees REQ-NFR-DASH-02 (freshness ≤ 24h — the nightly job runs at least once/day).
- **Acceptance criteria:** Scheduler computes correct seconds until 03:00 CT. Reconciliation recomputes all windows (idempotent). Scheduler resumes after restart. Job failure logs + retries next night. Max staleness = 24h (nightly job + on-session-end hook — REQ-NFR-DASH-02).

#### TASK-07-04 — Chain aggregation hook into session_recorder.py
- **Persona:** backend-engineer
- **File:** `server/session_recorder.py` (extend)
- **Content:** After the mastery flow (line ~143, `asyncio.create_task(self._run_mastery_flow_guarded(mastery_deps))`), chain the aggregation hook: `asyncio.create_task(self._run_cohort_aggregation(pg_store, session_outcome))`. The `session_outcome` dict is built from the mastery result (scenario_id, path, outcome, rubric_scores, failure_mode, branch_path, learner_ref=self.learner_id). The hook is fire-and-forget (D-054). If `pg_store` is None (no Postgres), skip. The hook runs in parallel with the mastery flow (aggregation only needs the session outcome + rubric scores, which are available after the session ends — it does not need to wait for mastery completion). **Off the voice path (C-8, D-054).**
- **Acceptance criteria:** Aggregation hook fires after session end. Voice loop latency unaffected (hook is async, non-blocking). Hook runs in parallel with mastery flow. No-Postgres → skip. session_recorder.py changes are backward-compatible (existing mastery flow unchanged).

#### TASK-07-05 — Aggregation unit tests
- **Persona:** backend-engineer
- **File:** `tests/test_cohort_aggregation.py` (new)
- **Content:** Tests with mocked PgStore:
  - k-anonymity suppression: 9 learners → cell_suppressed=TRUE, value=NULL. 10 learners → cell_suppressed=FALSE, value=computed. 11 learners → not suppressed.
  - Idempotent upsert: same session_outcome twice → same aggregate.
  - 7-day window computation: window_start/window_end correct.
  - Multiple metrics: sessions_count, active_learners_count, gate_open_rate, etc.
  - No PII: only aggregates + opaque learner_ref in upsert calls.
- **Acceptance criteria:** k-anon threshold exactly at 10 (9 suppressed, 10 not). Idempotent. All metrics computed correctly. No PII in any upsert call.

#### TASK-07-06 — Nightly job + hook integration test
- **Persona:** backend-engineer
- **File:** `tests/test_cohort_nightly.py` (new)
- **Content:** Tests with mocked PgStore:
  - Scheduler computes correct seconds until 03:00 CT (mock datetime).
  - Reconciliation recomputes all windows (verify upsert calls for all paths × metrics).
  - Hook failure → log + nightly job reconciles (simulate hook failure, run nightly, verify aggregate is correct).
  - R-DASH-04: nightly job failure → logs + retries next night (mock failure, verify scheduler continues).
- **Acceptance criteria:** Scheduler timing correct. Reconciliation covers all paths. Hook failure + nightly reconciliation = correct final state. Nightly failure doesn't crash the scheduler.

---

## SLICE-08: Operator API Cohort Endpoints (W1)

- **Goal:** Implement the 4 auth-gated operator API endpoints for the cohort dashboard: practice volume, mastery progression, failure patterns, and credential management.
- **REQ-IDs covered:** REQ-DASH-01 (API layer — partial), REQ-NFR-DASH-01 (k-anon display — partial)
- **Wave:** 1
- **Dependencies:** P1 SLICE-03 (current_operator dependency), P1 SLICE-01 (PgStore cohort_aggregates read)
- **Primary persona:** backend-engineer
- **Supporting personas:** data-engineer (k-anon query optimization)

### Tasks

#### TASK-08-01 — GET /api/operator/cohort (practice volume)
- **Persona:** backend-engineer
- **File:** `server/operator/cohort.py` (new)
- **Content:** `APIRouter` endpoint `GET /api/operator/cohort` with `dependencies=[Depends(current_operator)]` (D-057). Queries `cohort_aggregates` for practice volume metrics: sessions/day per path, total sessions in window, active learners (suppressed if < 10). Returns JSON: `{views: [{path, metrics: [{metric, window_start, window_end, value, cell_count, cell_suppressed, updated_at}]}], last_updated: "2026-08-04T03:00:00Z"}`. Suppressed cells have `value: null, cell_suppressed: true` — the frontend renders "— (<10 learners)" (D-053). No per-learner drill-down (R-DASH-02).
- **Acceptance criteria:** Auth-gated (401 without cookie). Returns k-anonymized data. Suppressed cells have value=null. `last_updated` = max(updated_at) across returned rows (freshness indicator — REQ-NFR-DASH-02). No per-learner data.

#### TASK-08-02 — GET /api/operator/mastery (mastery progression)
- **Persona:** backend-engineer
- **File:** `server/operator/mastery.py` (new)
- **Content:** `GET /api/operator/mastery` — auth-gated. Returns mastery progression metrics: % learners at each week (1-6), gate-open rate, median mastery_score, rubric criterion mean scores. Same JSON shape as TASK-08-01. All cells k-anonymized (suppressed if < 10).
- **Acceptance criteria:** Auth-gated. Returns week distribution + gate-open rate + rubric criterion means. Suppressed cells have value=null. No per-learner data.

#### TASK-08-03 — GET /api/operator/failure-patterns
- **Persona:** backend-engineer
- **File:** `server/operator/failure_patterns.py` (new)
- **Content:** `GET /api/operator/failure-patterns` — auth-gated. Returns failure pattern metrics: top failure_modes by frequency, rubric criteria with mean < 3.0 (weak-spots), branch outcome distribution (escalate vs accept). Same JSON shape. All k-anonymized.
- **Acceptance criteria:** Auth-gated. Returns failure_mode frequency + weak criteria + branch distribution. Suppressed cells have value=null. No per-learner data.

#### TASK-08-04 — GET/POST /api/operator/credentials (VC management)
- **Persona:** backend-engineer
- **File:** `server/operator/credentials.py` (new)
- **Content:** `GET /api/operator/credentials` — auth-gated. Lists issued VCs from Postgres `issued_credentials` (operator's issuance log). Returns `[{id, learner_ref, vc_type, status, issued_at, revoked_at}]`. `POST /api/operator/credentials/{id}/revoke` — auth-gated. Revokes a VC (sets status='revoked', revoked_at=now()). Updates the Bitstring Status List. This is the operator-side credential management (D-057 — VC issuance endpoints are auth-gated).
- **Acceptance criteria:** Auth-gated. GET returns credential list (no PII beyond what the credential asserts — D-043). POST revoke → credential status='revoked'. Revoked credential fails verification (`GET /vc/verify/<id>` → valid: false, status: revoked).

#### TASK-08-05 — Endpoint unit tests
- **Persona:** backend-engineer
- **File:** `tests/test_operator_endpoints.py` (new)
- **Content:** Tests with mocked PgStore + mocked current_operator:
  - All 4 endpoints return 401 without cookie.
  - All 4 endpoints return 200 with valid cookie.
  - Suppressed cells (cell_suppressed=TRUE) have value=null in response.
  - `last_updated` is the max(updated_at) across rows.
  - Credential revoke → status='revoked' in store + verification fails.
  - No per-learner data in any response (R-DASH-02).
- **Acceptance criteria:** All endpoints auth-gated. Suppressed cells displayed correctly. Credential revoke works. No per-learner drill-down possible.

---

## SLICE-09: React Cohort Dashboard + Router (W1)

- **Goal:** Implement the React cohort dashboard UI: React Router for `/operator/*` routes, login form, dashboard with 3 k-anonymized views, inline SVG sparklines, auth gate. The SPA fallback in `__main__.py` is in SLICE-10 (integration).
- **REQ-IDs covered:** REQ-DASH-01 (UI layer — partial), REQ-NFR-DASH-01 (display suppressed cells — partial)
- **Wave:** 1
- **Dependencies:** P1 SLICE-03 (auth API contract: POST /login, GET /me), SLICE-08 (API contract: cohort/mastery/failure-patterns response shapes — implements against contract, not live API)
- **Primary persona:** frontend-engineer
- **Supporting personas:** backend-engineer (SPA fallback in SLICE-10, API contract consultation)

### Tasks

#### TASK-09-01 — Add react-router-dom to client/package.json
- **Persona:** frontend-engineer
- **File:** `client/package.json` (extend)
- **Content:** Add `react-router-dom@^7` to dependencies. Run `npm install`. No chart library (inline SVG sparklines — zero deps, RESEARCH-v0.4 §4.3).
- **Acceptance criteria:** `npm install` succeeds. `npm run build` succeeds. `react-router-dom` in `node_modules`. Bundle size increase is reasonable (< 20KB for react-router-dom).

#### TASK-09-02 — BrowserRouter wrapper + route switch in App.tsx
- **Persona:** frontend-engineer
- **File:** `client/src/main.tsx` (extend), `client/src/App.tsx` (extend)
- **Content:** Wrap `App` in `<BrowserRouter>`. In `App.tsx`, add `<Routes>`: 
  - `/` → existing voice session UI (start→live→debrief — unchanged)
  - `/operator/login` → `Login` component
  - `/operator/dashboard` → `Dashboard` component (auth-gated)
  - `*` (catch-all) → voice session UI (fallback for unknown routes — SPA fallback)
  - R-DASH-05 mitigation: the existing voice UI at `/` is unchanged. The catch-all route serves the voice UI, not a 404.
- **Acceptance criteria:** Voice UI at `/` works exactly as before (R-DASH-05). `/operator/login` renders login form. `/operator/dashboard` renders dashboard (or redirects to login). `npm run build` succeeds. No regressions in voice UI.

#### TASK-09-03 — Login form component
- **Persona:** frontend-engineer
- **File:** `client/src/operator/Login.tsx` (new)
- **Content:** Login form: username + password fields + submit button. `POST /api/operator/login` on submit. On success → navigate to `/operator/dashboard`. On failure → show error. On 429 → show "Too many attempts, try again in a minute." Minimal CSS (reuse App.css patterns — no Tailwind/bootstrap). Form is accessible (label associations, keyboard navigation).
- **Acceptance criteria:** Login form renders. Successful login navigates to dashboard. Failed login shows error. Rate limit (429) shows retry message. Form is keyboard-accessible.

#### TASK-09-04 — Dashboard shell + auth gate
- **Persona:** frontend-engineer
- **File:** `client/src/operator/Dashboard.tsx` (new)
- **Content:** Dashboard shell: on mount, `GET /api/operator/me` → if 401, redirect to `/operator/login` (D-057 — React route guard, UX only). If 200, render dashboard with: operator name in header, 3 view tabs (Practice Volume, Mastery Progression, Failure Patterns), freshness indicator ("Last updated: Xh ago" from `last_updated` in API response — REQ-NFR-DASH-02), logout button (POST /api/operator/logout → redirect to login). View content fetched from respective `/api/operator/<view>` endpoints.
- **Acceptance criteria:** Auth gate redirects to login on 401. Dashboard renders operator name. 3 view tabs switch. Freshness indicator shows "Last updated: Xh ago". Logout redirects to login. No PII displayed (only k-anonymized aggregates — D-031).

#### TASK-09-05 — Inline SVG sparkline component
- **Persona:** frontend-engineer
- **File:** `client/src/operator/Sparkline.tsx` (new)
- **Content:** `<Sparkline data={number[]} width={60} height={20} />` — renders an SVG polyline from the data array. ~50 LOC, zero deps (RESEARCH-v0.4 §4.3). Handles edge cases: empty data (renders nothing), single point (renders a dot), all-same values (renders a flat line). Color: stroke=currentColor (inherits from parent). No axes, no tooltips (sparklines are compact trend indicators, not full charts).
- **Acceptance criteria:** Renders SVG polyline for 7-30 data points. Empty data → no render. Single point → dot. All-same → flat line. No external deps. ~50 LOC.

#### TASK-09-06 — 3 dashboard view components
- **Persona:** frontend-engineer
- **Files:** `client/src/operator/views/PracticeVolume.tsx` (new), `client/src/operator/views/MasteryProgression.tsx` (new), `client/src/operator/views/FailurePatterns.tsx` (new)
- **Content:** Each view: fetches its `/api/operator/<view>` endpoint, renders read-only tables + sparklines.
  - **PracticeVolume:** sessions/day per path (table + sparkline), total sessions, active learners. Suppressed cells → "— (<10 learners)" (REQ-NFR-DASH-01 display).
  - **MasteryProgression:** % learners at each week (bar-like table), gate-open rate, median mastery_score, rubric criterion means (table + sparkline). Suppressed cells → "— (<10 learners)".
  - **FailurePatterns:** top failure_modes by frequency (sorted table), rubric criteria with mean < 3.0 (highlighted as weak-spots), branch outcome distribution. Suppressed cells → "— (<10 learners)".
  - All views: loading state, error state, no-data state. Read-only (no filters, no drill-down — R-DASH-02).
- **Acceptance criteria:** Each view fetches + renders k-anonymized data. Suppressed cells display "— (<10 learners)". Tables are read-only. Sparklines render in table rows. Loading/error/no-data states handled. No per-learner drill-down.

#### TASK-09-07 — Dashboard unit tests
- **Persona:** frontend-engineer
- **File:** `client/src/operator/__tests__/Dashboard.test.tsx` (new — or co-located per project convention)
- **Content:** Tests:
  - Auth gate: 401 on /me → redirect to /operator/login.
  - Login form: submit → POST /login → navigate to dashboard.
  - Suppressed cell display: cell_suppressed=true → "— (<10 learners)" rendered.
  - Sparkline: renders SVG polyline for given data.
  - Freshness indicator: "Last updated: Xh ago" computed from last_updated.
  - No PII: only aggregate values in rendered DOM.
- **Acceptance criteria:** All tests pass. Auth gate works. Suppressed cells display correctly. Sparkline renders. No PII in DOM.

---

## SLICE-10: P2 Integration (W2)

- **Goal:** Wire P2 modules into `server/__main__.py`: SPA fallback catch-all route (before StaticFiles), operator API router mount (cohort/mastery/failure-patterns/credentials), nightly scheduler start. Run end-to-end aggregation→endpoint→dashboard integration tests.
- **REQ-IDs covered:** REQ-DASH-01 (full integration), REQ-NFR-DASH-01 (k-anon e2e), REQ-NFR-DASH-02 (freshness e2e), REQ-MT-02 (pipeline e2e)
- **Wave:** 2
- **Dependencies:** SLICE-07 (aggregation pipeline), SLICE-08 (operator endpoints), SLICE-09 (React dashboard)
- **Primary persona:** backend-engineer
- **Supporting personas:** lead-developer (integration orchestration), frontend-engineer (SPA fallback verification)

### Tasks

#### TASK-10-01 — __main__.py — SPA fallback catch-all route
- **Persona:** backend-engineer
- **File:** `server/__main__.py` (extend)
- **Content:** Add a catch-all route BEFORE the StaticFiles mount: `@app.get("/{path:path}")` that returns `FileResponse("client/dist/index.html")` for any path not matching an API route (`/health`, `/pipecat/*`, `/vc/*`, `/api/operator/*`). This is the SPA fallback for React Router `/operator/*` routes (R-DASH-03). **R-DASH-03 mitigation: the catch-all is BEFORE the StaticFiles mount, and the existing API routes are registered before the catch-all.** The StaticFiles mount remains for serving JS/CSS/assets (the catch-all only serves index.html for client-side routes). Test: `/` still serves the voice UI (index.html, which loads the voice app); `/operator/dashboard` serves index.html (React Router handles the route client-side); `/api/operator/cohort` still returns JSON (not index.html).
- **Acceptance criteria:** `GET /` → index.html (voice UI loads). `GET /operator/dashboard` → index.html (React Router handles it). `GET /operator/login` → index.html. `GET /api/operator/cohort` → JSON (not index.html — API routes take precedence). `GET /health` → JSON. `GET /vc/verify/123` → JSON. `GET /static.js` → served by StaticFiles (not the catch-all). R-DASH-03 verified: voice UI at `/` unchanged.

#### TASK-10-02 — __main__.py — mount operator API router + nightly scheduler
- **Persona:** backend-engineer
- **File:** `server/__main__.py` (extend)
- **Content:** `from server.operator.cohort import router as cohort_router`, `from server.operator.mastery import router as mastery_router`, `from server.operator.failure_patterns import router as failure_router`, `from server.operator.credentials import router as credentials_router`. `app.include_router(...)` for each. All use `prefix="/api/operator"` + `dependencies=[Depends(current_operator)]` (auth-gated — D-057). Mount BEFORE the SPA fallback catch-all. Start the nightly scheduler in the lifespan: `asyncio.create_task(nightly_scheduler.start(pg_store))` (if pg_store available). Cancel the scheduler task on shutdown.
- **Acceptance criteria:** `GET /api/operator/cohort` with valid cookie → JSON. Without cookie → 401. Nightly scheduler starts on app startup (if Postgres). Scheduler cancelled on shutdown. API routes matched before SPA fallback.

#### TASK-10-03 — P2 integration test (aggregation → endpoint → response)
- **Persona:** backend-engineer
- **File:** `tests/test_p2_aggregation_integration.py` (new — requires Postgres, skip if no DSN)
- **Content:** End-to-end:
  1. Seed 15 mock sessions (12 distinct learners — above k-anon threshold) for a path.
  2. Run the aggregation hook for each session → `cohort_aggregates` populated.
  3. `GET /api/operator/cohort` (with auth cookie) → returns practice volume with non-suppressed cells (12 ≥ 10).
  4. Seed 5 more sessions from 5 NEW distinct learners for a different path → `GET /api/operator/cohort` for that path → suppressed cells (5 < 10, value=null, cell_suppressed=true). REQ-NFR-DASH-01 verified.
  5. Run nightly reconciliation → all windows recomputed → `last_updated` updated.
  6. `GET /api/operator/mastery` → mastery progression data.
  7. `GET /api/operator/failure-patterns` → failure pattern data.
  8. Verify `last_updated` in response ≤ 24h old (REQ-NFR-DASH-02).
- **Acceptance criteria:** k-anon threshold enforced (12 learners → not suppressed, 5 → suppressed). All 3 endpoints return k-anonymized data. Nightly reconciliation updates `last_updated`. Freshness ≤ 24h (REQ-NFR-DASH-02). No per-learner data in any response.

#### TASK-10-04 — P2 integration test (SPA fallback + voice UI coexist)
- **Persona:** backend-engineer
- **File:** `tests/test_p2_spa_fallback.py` (new)
- **Content:** Tests against the running server (or TestClient):
  1. `GET /` → 200, `content-type: text/html`, contains `<div id="root">` (voice UI loads).
  2. `GET /operator/dashboard` → 200, `content-type: text/html`, contains `<div id="root">` (SPA fallback serves index.html).
  3. `GET /operator/login` → 200, `text/html` (SPA fallback).
  4. `GET /api/operator/cohort` → JSON (API route, not SPA fallback).
  5. `GET /health` → JSON (API route).
  6. `GET /pipecat/webrtc` → 405 (method not allowed — POST only, but route exists, not SPA fallback).
  7. `GET /vc/verify/nonexistent` → 404 (API route, not SPA fallback).
  8. `GET /assets/index.js` → served by StaticFiles (not SPA fallback).
  **R-DASH-03 verified: SPA fallback serves index.html for client-side routes; API routes + StaticFiles assets are unaffected.**
- **Acceptance criteria:** All 8 assertions pass. R-DASH-03 verified: voice UI at `/` unchanged, operator routes serve index.html, API routes return JSON, assets served by StaticFiles.

#### TASK-10-05 — P2 verification matrix
- **Persona:** lead-developer
- **File:** `.ciagent/VERIFY-P2.md` (new — pre-verify checklist for the verify stage)
- **Content:** REQ-ID → test mapping for P2. Confirm all P2 REQ-IDs (REQ-DASH-01, REQ-NFR-DASH-01, REQ-NFR-DASH-02, REQ-MT-02) have covering tests. List each test file + what it verifies. Cross-reference with P1 VERIFY (if any).
- **Acceptance criteria:** Every P2 REQ-ID has at least one covering test listed. Matrix is complete (no gaps).

---

# Final Phase (P3) — Review + Audit + Milestone Ship

**Branch:** `phase/03-final-review-ship` → merged to `milestone/v0.4-operator-tier` → merged to `main`
**Ship:** `v0.1.9` (final patch = v0.4 milestone release)
**REQ-IDs covered:** all v0.4 REQ-IDs (milestone-complete verification)

### Tasks (delegated to ciagent-review + ciagent-audit + ciagent-ship)

1. Run branch gate → create `phase/03-final-review-ship`
2. `ciagent-review` — multi-persona review across P1 + P2; auto-apply P0 fixes, flag P1+
   - **Security-engineer review focus:** auth stack (argon2id, cookies, rate limit), VC key migration (R-VC-MIG-01), R-AUTH-01 (Secure cookie + no-TLS — config-driven flag documented in GRILL-v0.4.md)
   - **Data-engineer review focus:** k-anonymity suppression (write-time, ≥10 threshold), no PII in Postgres, no cross-DB joins
   - **Frontend-engineer review focus:** auth gate (UX-only, server is authority), suppressed cell display, SPA fallback (R-DASH-03)
3. `ciagent-audit` — reconstruction test, file discipline, branch hygiene, commit discipline
4. `ciagent-ship` — merge phase/03 → milestone/v0.4-operator-tier → main; tag v0.1.9; create release with full milestone summary
5. Update REQUIREMENTS.md (all v0.4 REQ → complete), ROADMAP.md (v0.4 → complete; v0.5 = Live Assist)
6. Commit: `docs(milestone): complete v0.4-operator-tier`
7. Clear checkpoint

---

# REQ-ID Coverage Matrix

| REQ-ID | Phase | Slice(s) | Coverage |
|--------|-------|----------|----------|
| REQ-MT-01 | P1 | SLICE-01, SLICE-06 | Postgres store (5 tables) + pool + migration runner + integration |
| REQ-MT-02 | P1 (schema) + P2 (pipeline) | SLICE-01 (schema), SLICE-07 (pipeline), SLICE-10 (e2e) | Cohort aggregation pipeline — schema in P1, hook + nightly + k-anon in P2 |
| REQ-AUTH-01 | P1 | SLICE-03, SLICE-05, SLICE-06 | Operator auth (argon2id + cookies + rate limit) + bootstrap CLI + integration |
| REQ-DASH-01 | P2 | SLICE-08, SLICE-09, SLICE-10 | Cohort dashboard — API endpoints + React UI + integration |
| REQ-NFR-AUTH-01 | P1 | SLICE-03, SLICE-06 | argon2id + httpOnly + secure + SameSite=Strict + rate-limited + 8h expiry |
| REQ-NFR-MT-01 | P1 | SLICE-01, SLICE-02, SLICE-06 | Postgres-in-LXC (second service, internal network, 6GB CT, backup) + learner service coexist test |
| REQ-NFR-DASH-01 | P2 | SLICE-07, SLICE-08, SLICE-09, SLICE-10 | k-anonymity ≥ 10 (write-time suppression + query + display + e2e test) |
| REQ-NFR-DASH-02 | P2 | SLICE-07, SLICE-10 | Freshness ≤ 24h (nightly job + on-session-end hook + e2e test) |

**v0.4 total: 8/8 REQ-IDs covered (4 functional + 4 NFR). 0 partial. 0 deferred within v0.4.**

---

# Risk Mitigation Matrix

| Risk ID | Severity | Slice(s) | Mitigation |
|---------|----------|----------|------------|
| **R-VC-MIG-01** | high | SLICE-04, SLICE-06 | Archive v0.3 public key as superseded BEFORE activating new key; verification queries by key_id (not status); e2e test verifies v0.3 VC against Postgres store |
| R-MT-01 | medium | SLICE-02, SLICE-07 | CT memory bump 6GB; nightly jobs at 03:00 CT (low activity); aggregation is incremental upsert (not full scan) |
| R-MT-02 | medium | SLICE-01 | pg_isready healthcheck + 5 retries; depends_on: service_healthy; pg_migrate retries on connection failure (3x, 2s backoff) |
| R-AUTH-01 | medium | SLICE-03 | Config-driven PRAXIS_COOKIE_SECURE (default true; false for HTTP pilot with logged WARNING); cohort dashboard reads only k-anonymized aggregates (no PII leak even if cookie sniffed); grill must sign off |
| R-DASH-01 | medium | SLICE-07, SLICE-09 | Write-time suppression (cell_suppressed=TRUE, value=NULL); dashboard shows "— (<10 learners)" transparently; 7-day window can be widened to 14-day if too many cells suppressed |
| R-DASH-02 | medium | SLICE-07, SLICE-08 | Pre-defined 2-D views only (path × week, path × outcome); no arbitrary filters; no per-learner drill-down (D-053) |
| R-DASH-03 | medium | SLICE-10 | Catch-all route BEFORE StaticFiles mount; test `/` still serves voice UI; test `/operator/dashboard` serves index.html; test API routes return JSON (not index.html) |
| R-DASH-05 | medium | SLICE-09 | BrowserRouter wrapper + catch-all route serves voice UI at `/`; test voice UI unchanged after Router addition |
| R-VC-MIG-02 | medium | SLICE-04 | v0.3 private key NOT migrated (only public key archived); v0.4 active key generated fresh with v0.4 root key; v0.3 root key kept in secrets until v0.3 VCs expire |
| R-VC-MIG-03 | medium | SLICE-04, SLICE-06 | IssuerKeyStore protocol/ABC; both PraxisStore and PgStore implement it; e2e test verifies v0.3 VC against Postgres store with archived key |
| R-MT-03 | low | SLICE-01 | Network change (default bridge → praxis-net) recreates praxis container (~5-15s downtime); SQLite volume untouched → learner state preserved; documented in compose comments |
| R-MT-04 | low | SLICE-02 | Named volumes stable on Docker-in-LXC with nesting=1; nightly pg_dump provides backup; restore drill documented |
| R-MT-05 | low | SLICE-01 | Verified: gen_random_uuid() is PG13+ core (no extension). PG16 confirmed |
| R-AUTH-02 | low | SLICE-03 | Single operator login is low-frequency; ~80ms argon2id is acceptable on event loop. Not a v0.4 concern |
| R-AUTH-03 | low | SLICE-03 | In-memory rate limit lost on restart (single-instance pilot; restarts are rare + operator-initiated). Documented as accepted pilot risk |
| R-AUTH-04 | low | SLICE-03 | Cookie secret rotation invalidates all sessions (pilot: acceptable — one operator re-logs in). Documented |
| R-AUTH-05 | low | SLICE-03 | No server-side session revocation (D-056 explicit — stateless cookies). Forced-logout = cookie secret rotation. Deferred |
| R-DASH-04 | low | SLICE-07 | Nightly job failure → logs + retries next night; on-session-end hook keeps data fresh in the meantime |
| R-BOOT-01 | low | SLICE-05 | create-operator.py retries on connection failure (3 attempts, 5s backoff); run after postgres healthcheck passes |
| R-BOOT-02 | low | SLICE-05 | Script checks env var presence + exits with clear error if missing. Documented in .env.example |

**Coverage: 1/1 high risk + 9/9 medium risks + 11/11 low risks addressed. 20/20 total.**

---

# Open Questions Deferred to EXECUTE

1. **v0.3 issued_credentials migration:** The verification endpoint needs to find v0.3 credentials (in SQLite) AND v0.4 credentials (in Postgres). SLICE-04 TASK-04-04 implements a try-Postgres-first-fall-back-to-SQLite approach. Alternative: migrate v0.3 credential rows to Postgres (data migration, not re-signing). The executor should choose the simpler approach — the fallback-to-SQLite is simpler (no data migration) but means the verification endpoint queries two stores. Confirm in SLICE-04/SLICE-06.

2. **SPA fallback implementation:** Catch-all route (`@app.get("/{path:path}")`) before StaticFiles, or a custom StaticFiles subclass that returns index.html for non-file paths? SLICE-10 TASK-10-01 uses the catch-all route (simpler). The executor should verify the catch-all doesn't shadow StaticFiles asset serving (JS/CSS files). The test in TASK-10-04 verifies this.

3. **Cohort aggregation `learner_ref` source:** The existing `HARDCODED_LEARNER_ID = "learner-1"` (db/store.py:29). For v0.4 (single learner), k-anonymity will suppress everything (1 < 10). This is expected at pilot scale (R-DASH-01). The aggregation pipeline groups by `learner_ref` so k-anon counts distinct learners. Multi-learner-per-device is deferred. Confirm the dashboard shows "— (suppressed, <10 learners)" for all cells in the single-learner pilot. The executor should seed test data with ≥10 mock learners to verify the non-suppressed path.

4. **Nightly scheduler timezone:** 03:00 CT (Central Time — Canada pilot is CT?). The scheduler uses `datetime.now()` with a timezone-aware approach. The executor should use `zoneinfo.ZoneInfo("America/Winnipeg")` or similar for CT. Confirm in SLICE-07 TASK-07-03.

5. **`create-operator.py` `--update` flag:** SLICE-05 TASK-05-01 includes a `--update` flag for force-rehash. The executor should decide if this is a positional arg or a `--update` flag. Keep it simple: `--update` flag.

6. **Cookie `path` scope:** RESEARCH-v0.4 §open-questions #5 recommends `path="/"` (cookie sent to all routes) so the React `/operator/*` routes can call `/api/operator/me` on mount. SLICE-03 TASK-03-02 uses `path="/"`. Confirm.

7. **Aggregation hook parallel vs sequential with mastery flow:** SLICE-07 TASK-07-04 chains the aggregation hook in parallel with the mastery flow (both are `asyncio.create_task`). The aggregation only needs the session outcome (available after session end), not the mastery scoring result. However, some metrics (rubric criterion means) need the rubric scores from the mastery flow. The executor should decide: chain the aggregation AFTER mastery completion (sequential) or run in parallel and have the nightly job fill in rubric-dependent metrics. Recommendation: run in parallel + nightly job reconciles rubric-dependent metrics (simpler, freshness ≤ 24h guaranteed by nightly).

---

# Summary

| Metric | Value |
|--------|-------|
| Execution phases | 2 (P1: operator foundation, P2: cohort dashboard) + 1 final (P3: review + ship) |
| Slices | 10 (6 in P1, 4 in P2) |
| Tasks | 52 (29 in P1, 23 in P2) |
| REQ-IDs covered | 8/8 (REQ-MT-01, REQ-MT-02, REQ-AUTH-01, REQ-DASH-01, REQ-NFR-AUTH-01, REQ-NFR-MT-01, REQ-NFR-DASH-01, REQ-NFR-DASH-02) |
| Risks addressed | 20/20 (1 high, 9 medium, 11 low) |
| Waves | P1: 3 waves (2+3+1 parallel slots), P2: 2 waves (3+1 parallel slots) |
| Max parallelism | 3 slices per wave (within 5-agent limit) |
| Personas active | 6 (lead-developer, backend-engineer, frontend-engineer, data-engineer, security-engineer, devops-engineer) |
| New pip deps | 3 (asyncpg, argon2-cffi, slowapi) |
| New npm deps | 1 (react-router-dom@^7) |
| Ship targets | v0.1.7 (P1), v0.1.8 (P2), v0.1.9 (P3 = v0.4 milestone release) |