feat: Sprints 24-29A — comprehensive review, security, a11y, skills, UI components

.env.example

@@ -64,11 +64,15 @@ ELEVENLABS_API_KEY=""
 GOOGLE_TTS_KEY=""
 HANDTALK_API_KEY=""
 
+# === Auth (JWT) ===
+# Generate a production secret with: python -c 'import secrets; print(secrets.token_urlsafe(48))'
+AILINE_JWT_SECRET=""
+
 # === Dev Mode (enables X-Teacher-ID header bypass for local dev) ===
-AILINE_DEV_MODE="false"
+AILINE_DEV_MODE="true"
 
-# === Demo Mode ===
-AILINE_DEMO_MODE="0"
+# === Demo Mode (enables /demo/* endpoints and demo login) ===
+AILINE_DEMO_MODE="1"
 
 # === Rate Limiting ===
 AILINE_RATE_LIMIT_RPM="60"

.github/workflows/ci.yml

@@ -209,22 +209,22 @@ jobs:
 
       - name: Audit Python runtime deps
         working-directory: runtime
-        run: uv run pip-audit --desc || true
+        run: uv run pip-audit --desc
 
       - name: Install frontend deps
         working-directory: frontend
         run: pnpm install --frozen-lockfile
 
       - name: Audit npm deps
         working-directory: frontend
-        run: pnpm audit --audit-level=high || true
+        run: pnpm audit --audit-level=high
 
   # ---------------------------------------------------------------------------
   # Docker Compose build validation
   # ---------------------------------------------------------------------------
   docker-build:
     runs-on: ubuntu-latest
-    needs: [backend-lint, backend-typecheck, backend-test, agents-test, frontend-lint, frontend-typecheck, frontend-test]
+    needs: [backend-lint, backend-typecheck, backend-test, agents-test, frontend-lint, frontend-typecheck, frontend-test, security-scan]
     steps:
       - uses: actions/checkout@v4
 

agents/pyproject.toml

@@ -8,16 +8,16 @@ version = "0.1.0"
 description = "AiLine agent framework: Pydantic AI agents + LangGraph workflows"
 requires-python = ">=3.11"
 dependencies = [
-  "pydantic-ai>=1.58.0,<2",
+  "pydantic-ai>=1.63.0,<2",
   "langgraph==1.0.8",
   "pydantic>=2.10,<3",
-  "pydantic-settings>=2.7,<3",
+  "pydantic-settings>=2.13,<3",
   "structlog>=24,<26",
   "deepagents==0.4.1",
   "langchain-anthropic>=1.3.2,<2",
   "langchain-core>=1.2.10,<2",
-  "anthropic>=0.79.0,<1",
-  "fastapi>=0.128,<1",
+  "anthropic>=0.84.0,<1",
+  "fastapi>=0.133.0,<1",
   "sse-starlette>=3.2,<4",
   "httpx>=0.28,<1",
   "tenacity>=9,<10",
@@ -33,11 +33,11 @@ all = ["ailine-agents[anthropic,openai,gemini]"]
 
 [dependency-groups]
 dev = [
-  "pytest>=8,<9",
-  "pytest-asyncio>=0.24,<1",
+  "pytest>=9,<10",
+  "pytest-asyncio>=1.3,<2",
   "pytest-cov>=6,<7",
-  "ruff>=0.9,<1",
-  "mypy>=1.14,<2",
+  "ruff>=0.15,<1",
+  "mypy>=1.19,<2",
   "aiosqlite>=0.20,<1",
   "ailine-runtime",
 ]
@@ -46,14 +46,14 @@ dev = [
 packages = ["ailine_agents"]
 
 [tool.ruff]
-target-version = "py311"
+target-version = "py313"
 line-length = 120
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "RUF"]
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.13"
 strict = false
 warn_return_any = true
 plugins = ["pydantic.mypy"]

control_docs/CHANGELOG.md

@@ -1,6 +1,53 @@
 # Changelog
 All notable changes documented here. Format: [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.14.0] - 2026-02-20 (Sprint 27 — Critical Fixes, Demo Auth, Visual Polish)
+
+### Added
+- POST /auth/demo-login endpoint — proper JWT auth flow for demo profiles, accepts both long keys (teacher-ms-johnson) and short aliases (teacher), 7 new tests (F-247)
+- Demo users seeded with hashed password (demo123) so email login also works (F-248)
+- demoLogin() async helper in frontend api.ts — calls demo-login, stores JWT in auth store (F-247)
+- Pipeline SVG connectors with animated dash-flow on active edges + arrow heads (F-234)
+- Node glow effects on pipeline (active=warning glow, completed=success, failed=error) (F-234)
+- Motor accessibility: pill-shaped buttons (28px radius), 3px focus halos with 8px tap zone indicators, bottom action bar padding (F-235)
+- btn-press micro-interaction (scale 0.97 + inset shadow on active), slide-in-right animation for SSE notifications (F-236)
+
+### Fixed
+- **P0:** VALID_DEMO_PROFILES expanded to include both short (login page) and long (landing page) key formats (F-243)
+- **P0:** EvidencePanel aria-labelledby — added missing id attribute on toggle button (F-244)
+- **P0:** PreferencesPanel stale-closure focus restore — replaced cleanup pattern with direct branch (F-245)
+- **HIGH:** JWT iss/aud claims now minted when AILINE_JWT_ISSUER/AUDIENCE env vars configured (F-246)
+- Login rate limit raised from 5/min to 20/min for demo-friendly Docker testing (F-249)
+
+### Changed
+- Docker frontend memory 512M → 2G with NODE_OPTIONS=--max-old-space-size=1536 (F-250)
+- Frontend healthcheck: wget || curl fallback
+- Landing + login pages upgraded to JWT-first demo login (X-Teacher-ID fallback preserved)
+- /auth/demo-login excluded from tenant middleware
+- Total: 2,413 backend + 1,411 frontend = **3,824 tests passing**, 0 lint/type errors
+
+## [0.13.0] - 2026-02-19 (Comprehensive Review & Polish)
+
+### Added
+- A11y Status Badge — floating "Make the Invisible Visible" indicator showing active persona + features count, expandable detail panel with ARIA compliance (F-223, 11 tests)
+- Persona Explainer Banner — "Why this adaptation?" context banner below topbar with persona-specific hints, aria-live polite (F-224, 8 tests)
+- GET /capabilities endpoint — platform feature discovery (LLM, TTS, image gen, vector search, braille, skills, demo mode), excluded from auth/rate-limit (F-225, 3 tests)
+- Enhanced focus states — WCAG outline+offset indicators with forced-colors mode for Windows High Contrast (F-226)
+- Theme color preview chips — 3 color circles (bg, primary, text) next to each theme in preferences panel (F-227)
+- Config validation at startup — Settings.validate_environment() called before Container.build() with structured warnings (F-228)
+- 16 new test files covering login phases, auth store, sign language selector, wizard steps, settings, API, demo data (F-229, 133 tests)
+
+### Fixed
+- useTranslations mock: stable function references per namespace (OOM fix in vitest)
+- test_tenant_context: HS256-signed JWTs with dev secret for proper verification
+- exports/page.test.tsx: removed importActual causing OOM
+- JWT middleware: dev-secret fallback with proper HS256 verification
+- Demo mode: _require_demo_mode guard fix
+
+### Changed
+- Expert reviews by GPT-5.2 (backend architecture) and GPT-5.2 (frontend UX) — Sprint 27 plan created with 13 features across 4 phases
+- Total: 2,406 backend + 1,397 frontend = **~3,803 tests passing**, 0 lint/type errors
+
 ## [0.12.0] - 2026-02-19 (Sprint 26 — "Make the Invisible Visible")
 
 ### Added

control_docs/FEATURES.md

@@ -84,6 +84,89 @@ F-156 to F-162 (7 features): Sign Language Interpreter Skill, Multi-Language Ada
 - [F-221] Braille Download + Copy — Download .brf file + copy to clipboard buttons added to BraillePreview component
 - [F-222] Inclusive Classroom Mode — "One Lesson, Four Adapted Plans" 2x2 teacher cockpit grid (Lucas/ASD, Sofia/ADHD, Pedro/Dyslexia, Ana/Hearing) with accent colors and accommodation badges
 
+### Improvements Branch — Comprehensive Review & Polish (Feb 19, 2026)
+- [F-223] A11y Status Badge — Floating "Make the Invisible Visible" indicator showing active persona + features count, expandable detail panel, ARIA-compliant (11 tests)
+- [F-224] Persona Explainer Banner — "Why this adaptation?" context banner below topbar, shows persona icon/name/hints, aria-live polite (8 tests)
+- [F-225] Capabilities Endpoint — GET /capabilities returns platform feature availability (LLM, TTS, image gen, vector search, braille, skills, demo mode), excluded from auth/rate-limit (3 tests)
+- [F-226] Enhanced Focus States — WCAG-compliant outline+offset focus indicators, forced-colors mode support for Windows High Contrast
+- [F-227] Theme Color Preview Chips — 3 color circles (bg, primary, text) next to each theme in preferences panel
+- [F-228] Config Validation at Startup — Settings.validate_environment() called before Container.build(), fail-fast with structured warnings
+- [F-229] Comprehensive Test Expansion — 16 new test files, 133 new tests covering login phases, auth store, sign language selector, wizard steps, settings, API, demo data
+
+### Sprint 27 — Production-Grade Polish (Feb 20, 2026)
+- [F-230] PostgresUserRepository — SessionFactoryUserRepository with DI wiring for persistent user storage
+- [F-231] JWT Hardening — RS256/HS256 algorithm selection, jti claim + Redis blacklist, POST /auth/logout, configurable TTL
+- [F-232] Health Diagnostics Split — public /health/diagnostics vs private /internal/diagnostics with auth
+- [F-233] Before/After Accessibility Compare Slider — draggable theme comparison, keyboard accessible
+- [F-234] Pipeline Edge Animations — SVG stroke-dashoffset flow + node glow states
+- [F-235] Motor Accessibility Mode — MotorStickyToolbar with 56px targets, pill shapes, focus halos
+- [F-236] Micro-interactions — btn-press scale(0.97), slide-in animation, dash-flow keyframe
+- [F-237] Run Resource Model — GET /runs (list + filter + pagination), GET /runs/{id} (detail)
+- [F-238] RFC 7807 Error Model — already implemented (error_handler.py, application/problem+json)
+- [F-239] TenantContext Explicit Dependencies — all routers use Depends(require_authenticated)
+- [F-240] Config Deduplication — AiLineConfig deprecated with DeprecationWarning, Settings is canonical
+- [F-241] Cache Skill Registry — _get_skills_info() cached once, used by diagnostics + capabilities
+- [F-242] Demo Storyboard — 2 tracks (Teacher/Accessibility), 5 steps each, full i18n
+- [F-243] Demo Profile Key Mismatch — VALID_DEMO_PROFILES includes both short and long keys
+- [F-244] EvidencePanel aria-labelledby Fix — missing id on toggle button
+- [F-245] PreferencesPanel Focus Restore — stale closure fix
+- [F-246] JWT iss/aud Claims — mint when env vars configured
+- [F-247] /auth/demo-login Endpoint — proper JWT flow with short/long key aliases
+- [F-248] Demo Users Seeded — hashed password (demo123), email login works
+- [F-249] Login Rate Limit — raised to 20/min for demo-friendly Docker testing
+- [F-250] Docker Frontend Memory — 512M to 2G, NODE_OPTIONS=--max-old-space-size=1536
+
+### Sprint 28 — Security Containment + Docs Sync (Feb 21, 2026)
+- [F-251] Demo Login Privilege Escalation Fix — _validate_role() enforcement + admin profiles removed from DEMO_PROFILES
+- [F-252] TraceStore Tenant Integrity — append_node/update_run no longer auto-create RunTrace
+- [F-253] Dev Mode Default OFF — AILINE_DEV_MODE defaults to false in Docker Compose
+- [F-254] JWT Dev Secret Module — Shared jwt_dev_secret.py replaces hardcoded fallback secrets
+- [F-255] Demo Login Rate Limiting — Per-IP rate limit (20/min) on /auth/demo-login
+- [F-256] Diagnostics Admin-Only — /internal/diagnostics restricted to admin role
+- [F-257] Rate Limiter Docs Alignment — Docstrings corrected to 20 attempts/minute
+- [F-258] Redis Access Encapsulation — EventBus.get_redis_client() protocol method replaces private _redis
+- [F-259] TraceStore Server-Side Filtering — list_recent() accepts status parameter
+- [F-260] Seed Import Unification — All imports use demo_profiles module directly
+- [F-261] Role Validation 422 — _validate_role() raises HTTP 422 for invalid roles
+- [F-262] Body Immutability — plans_stream uses Pydantic model_copy instead of mutation
+- [F-263] SessionStorage JWT Cleanup — Removed insecure sessionStorage fallback
+- [F-264] Docker Port Hardening — DB/Redis ports bound to 127.0.0.1
+- [F-265] SYSTEM_DESIGN.md Version Sync — Tailwind, motion, next-intl, pydantic-ai versions corrected
+- [F-266] FEATURES.md Sprint 27 — Added Sprint 27 section (F-230 to F-250)
+- [F-267] SECURITY.md Roles Update — Corrected to 5 roles (super_admin through parent)
+- [F-268] RUN_DEPLOY.md Port Defaults — Fixed port defaults (8011/3011/5411/6311)
+- [F-269] TEST.md Counts Update — Updated to ~3,889 tests, fixed pytest command
+- [F-270] Frontend CLAUDE.md Sync — Tailwind and motion versions corrected
+- [F-271] I18N Diacritics Fix — 7 pt-BR + 1 es diacritics corrected
+
+## Planned — Sprint 29: Design System, SVG Illustrations, Core Views & Emotional UX ("Soft Clay")
+F-272→F-310 (39 stories, 6 phases, 3 weeks). HIGHEST PRIORITY. Design: "Soft Clay 2.5D Organic" via Gemini-3.1-Pro (6 consultations). Benchmarks: Khan Academy, Duolingo, Seesaw, Google Classroom. Phase 1: design system (tokens, tailwind-variants, lucide-react, Inter+Jakarta Sans, Azure/Sage/Amber). Phase 2: SVG illustration system (38+ Gemini-generated SVGs — empty states, onboarding, landing, personas, a11y icons). Phase 3: 3 CRITICAL missing views (Learning Analytics Dashboard, Student Learning View, Parent Progress Report + Recharts a11y infra). Phase 4: page redesigns (landing, dashboard, tablet, dark theme, onboarding). Phase 5: emotional safety (neutral errors, visual timer, Quiet Mode, ADHD support, Dyslexia rows). Phase 6: engagement (drag-and-drop, PWA, Learning Rhythm gamification). Stretch: Constellation map, push notifications, multimodal responses, Transition Passport.
+
+## Planned — Sprint 30: Backend Production, Observability & Compliance
+F-311→F-330 (20 stories, 6 phases, 2-3 weeks). Architecture: GPT-5.3-codex (3 consultations). GDPR/LGPD verified. Phase 1 (Day 1): GEMINI_API_KEY fix (config.py AliasChoices), PII log redaction, Google paid-service guard. Phase 2: audit log + PII encryption. Phase 3: OTEL Redis, trace-ID correlation, LLM baggage. Phase 4: distributed idempotency, SmartRouter failover, SSE backpressure, graceful shutdown, K8s probes. Phase 5: split app.py/auth.py/models.py + remove AiLineConfig. Phase 6: Docker CI + Playwright CI.
+
+## Planned — Sprint 31: Architecture Evolution & Agent Maturity
+F-331→F-345 (15 stories, 4 phases, 2-3 weeks). Phase 1: service layer (Commands/Queries), domain events, arq worker. Phase 2: API versioning (/v1/), cursor pagination. Phase 3: prompt registry, per-tenant cost tracking, content safety guardrails, semantic AI caching. Phase 4: persistent stores, embedding fix, InMemoryStore base, PgVectorStore cleanup, global state docs.
+
+## Planned — Sprint 32A: Privacy Compliance (LGPD/GDPR)
+F-346→F-355 (10 stories, 2 weeks). Data tier classification, portability export (LGPD Art.18), deletion/anonymization pipeline, minor consent (LGPD Art.14), retention engine, incident response (ANPD 3d/GDPR 72h), provider DPA register, Redis eviction safety, Postgres RLS, notification service.
+
+## Planned — Sprint 33+: Advanced Features
+F-356→F-375 (20 stories, 4-6 weeks). Gamification: Learning Rhythm, Skill Nodes, Constellation. Educational intelligence: spaced repetition, IEP tracking, AI Social Stories (ASD), predictive accommodations, cognitive simplification. Platform: feature flags, CQRS, A/B testing, personalization engine. Infra: Meilisearch, API SDK generation, admin dashboard, batch operations, webhooks, Git LFS, AT testing.
+
+## Planned — Sprint 34: Emotional Safety & Executive Function (Empowerment Pillar 1)
+F-376→F-393 (18 stories, 4 phases, 3 weeks). SAMHSA 6 Trauma-Informed Principles + 6-subsystem Executive Function Support. Architecture: Gemini-3.1-Pro (3 consultation rounds). Phase 1 (P0): transition warnings ASD (aria-live="assertive"), task decomposition "Stepping Stones" SVG, safe feedback (amber not red, no "wrong" language), global undo + auto-save. Phase 2 (P0): working memory "Where was I?", initiation support "Just Start", emotional check-in (energy/pleasantness grid), frustration detection + de-escalation, breathing exercise, parking lot (distracting thoughts). Phase 3 (P1): productive struggle indicator, dignity-preserving celebrations (per-persona: TEA=text-only), self-assessment emoji scale. Phase 4 (P2): asset-based parent reports (no deficit language), growth portfolio, store integration, i18n 40+ keys, test suite. New: 12 DB tables, 15 API endpoints, 7 Zustand stores, CSS token changes (--color-feedback-safe).
+
+## Planned — Sprint 35: AI Educational Intelligence Tools (Empowerment Pillar 2)
+F-394→F-411 (18 stories, 3 phases, 3 weeks). 3 AI-powered tools closing accommodation→empowerment gap. Architecture: Gemini-3.1-Pro (3 rounds). Phase 1 (P0): SocialStoryAgent (Carol Gray 10.2 methodology, deterministic 4:1 ratio validation, 10 scenario templates, multi-format export: text/audio/PDF/cards, StoryCardViewer). Phase 2 (P0-P1): readability analysis (Flesch-Kincaid/Gunning Fog deterministic), 4-level SimplificationAgent (Original→Simplified→Highly Simplified→Symbol-Supported), ComplexitySlider UI, plan_workflow/tutor_workflow integration. Phase 3 (P1): telemetry ingestion (7 signal types, partitioned, Redis buffer), BehavioralAnalyzer (rolling windows, 0-1 normalized), AccommodationPredictor (heuristic rules, dignity framing, NEVER auto-activate), ZPD adaptive difficulty (Vygotsky, frustration ceiling), teacher insights dashboard. New: 2 Pydantic AI agents, 3 skills, 1 LangGraph workflow, 5 DB tables, 14 API endpoints.
+
+## Planned — Sprint 36: IEP/MTSS, SM-2 Spaced Repetition, Mastery & Personalization (Empowerment Pillar 3)
+F-412→F-447 (36 stories, 5 phases, 4-6 weeks). Educational data intelligence backbone. Architecture: GPT-5.3-codex (2 rounds) + GPT-5.2 thinkdeep. Phase 1 (P0): IEP document lifecycle (7 states), SMART goals (curriculum-linked), 6 accommodation categories, progress monitoring (4 evidence types), services tracking, team/notifications, domain entities + repository. Phase 2 (P0): MTSS 3-tier system, evidence-based intervention catalog (4 evidence levels), student interventions + fidelity tracking, screening + meetings, domain entities. Phase 3 (P0): consent management (IDEA + LGPD Art. 14, 6 consent types), immutable audit ledger (SHA-256 hashes), data retention policies (IEP 7yr, MTSS 5yr, reviews 3yr). Phase 4 (P1): review items (7 modalities), student review profiles (processing speed matrix: 7 needs × 7 modalities), SM-2 inclusive adaptation (calibration period, streak bonus, PSF), fatigue detection (3 rules), due reviews, review sessions, health dashboard, tutor integration (review_check_node). Phase 5 (P1-P2): mastery map (5 levels, ZPD bounds), evidence collection (5 sources), skill gap analysis, learning profiles, AI recommendations engine (heuristic-first, teacher approval), auto-generation from mastery, data retention enforcement, privacy dashboard. New: 24 DB tables, 38 API endpoints, 6 domain entity files, 6 repository ports + adapters, migration 0006.
+
 ## Backlog
-- [F-035] Sign Language Post-MVP Path — SPOTER transformer + VLibrasBD NMT dataset (ADR-047)
-- [F-178] Teacher Skill Sets — Per-teacher skill configurations with presets
+- [F-035] Sign Language Post-MVP — SPOTER transformer + VLibrasBD NMT
+- [F-178] Teacher Skill Sets — per-teacher presets
+- Braille Grade 2 via liblouis
+- Symbol-Supported Text (PCS pictograms)
+- Synchronized word-level TTS highlighting
+- Haptic/Vibrational feedback (Web Haptics API)