praxis/.ciagent/REQUIREMENTS.md

Praxis — Requirements

Milestone: v0.3 (Mastery scoring + competency rubrics + verifiable credentials) Status: complete — milestone released as v0.1.5 (13/13 v0.3 REQ covered, 8 deferred to v0.4)

Formal requirements with REQ-IDs. Scoped to the active milestone unless noted. v0.1/v0.2 requirements (complete) are retained for reference with their final status. Later-milestone requirements are marked deferred.

v0.3 Active Requirements

Mastery & Assessment (v0.3 core)

REQ-ID	Requirement	Priority	Phase	Status
REQ-MAST-01	Competency rubric per skill — a typed rubric model (criteria, 5-level scale, per-skill weights) authored as YAML, mapped to scenarios (D-036). At least one rubric for the Customer Service path in v0.3.	must	P1	active
REQ-MAST-02	Mastery Score updated after each session — computed from rubric scores + varied-scenario-success gate (D-032: N=3 distinct scenarios, rubric mean ≥ 3.5/5.0). Score persisted per learner per path. Mastery gate opens when condition met.	must	P1	active
REQ-MAST-03	Portable verifiable credentials on mastery — W3C VC Data Model 2.0, platform-issued Ed25519 signatures, status-list revocation (D-033). Issued when a mastery gate opens. Verifiable by third parties via a public verification endpoint.	must	P1	active
REQ-MAST-04	No quizzes — assessment built into scenarios	principle	—	accepted

Scenario Engine (v0.3 extensions)

REQ-ID	Requirement	Priority	Phase	Status
REQ-SCEN-02	Dynamic difficulty adjustment based on learner performance — IRT 1PL/Rasch, Bayesian θ update per session (D-035). Difficulty selection picks next scenario targeting ~50% expected success for current θ.	must	P1	active
REQ-SCEN-03	Scenario library tagged by skill, difficulty, failure mode, rubric criteria — YAML directory + scenarios/index.yaml manifest (D-036). v0.3 ships ≥6 scenarios for the Customer Service path (one per week minimum).	must	P1	active
REQ-SCEN-04	Expert-authored scenario format with AI-generated variations — extends D-018 YAML DSL with rubric mapping + generated_from backref for AI variations. Expert-authored = canonical; AI variations = same schema, flagged, reviewable.	must	P1	active

Skill Paths (v0.3)

REQ-ID	Requirement	Priority	Phase	Status
REQ-PATH-02	Path structured as a job — 6-week structure per PRD §6.4, mastery-paced (D-037). Path = paths/<slug>.yaml defining weeks, each week = scenarios + a mastery gate. v0.3 ships the Customer Service path fully (6 weeks, ≥1 scenario/week).	must	P1	active

Employer / Program Dashboard (deferred to v0.4 — per GRILL-v0.3.md Axis 2)

REQ-ID	Requirement	Priority	Phase	Status
REQ-DASH-01	Anonymized cohort view (practice, mastery progression, failure patterns) for training operators — k-anonymity ≥ 10, 7-day aggregation window (D-034). Operator UI (React) reads from operator-tier Postgres. Forces multi-tenant + operator auth (D-031).	must	v0.4	deferred-to-v0.4

Auth & Multi-Tenancy (deferred to v0.4 — per GRILL-v0.3.md Axis 2)

REQ-ID	Requirement	Priority	Phase	Status
REQ-AUTH-01	Operator-tier auth — session-based, single operator role in v0.3. Operator accounts in Postgres. Login endpoint + session cookie. Protects cohort dashboard + credential issuance.	must	v0.4	deferred-to-v0.4
REQ-MT-01	Operator-tier Postgres store — cohort aggregations, operator accounts, issued credentials, mastery-gate audit log. Separate from learner-local SQLite (D-007 preserved for learner surface). Migration path: SQLite stays for learner; Postgres added for operator.	must	v0.4	deferred-to-v0.4
REQ-MT-02	Cohort aggregation pipeline — scheduled job (or on-session-end hook) writes k-anonymized aggregates to Postgres from learner sessions. No raw learner PII in Postgres.	must	v0.4	deferred-to-v0.4

v0.3 Non-Functional Requirements

REQ-ID	Requirement	Target	Phase	Status
REQ-NFR-MAST-01	Rubric scoring determinism — same session + rubric → same score (no LLM non-determinism in the scoring path; LLM may assist rubric criterion extraction but final score is rule-based)	must	P1	active
REQ-NFR-MAST-02	Mastery gate auditability — every gate-open event recorded with evidence (which 3 scenarios, rubric scores, timestamp)	must	P1	active
REQ-NFR-VC-01	Verifiable credential tamper-evidence — Ed25519 signature, issuer key in operator-tier secrets (not committed), verification endpoint validates signature + status + interop test against external W3C verifier (grill Axis 3)	must	P1	active
REQ-NFR-VC-02	Credential revocation latency — revoked credential must fail verification within 1 sync of the status list (next verify call — no cache)	must	P1	active
REQ-NFR-AUTH-01	Operator auth — passwords hashed (argon2id), session cookie httpOnly + secure, login rate-limited	must	v0.4	deferred-to-v0.4
REQ-NFR-MT-01	Postgres-in-LXC — operator Postgres runs as a second Docker service in the existing LXC CT (or sidecar) without destabilizing the learner-facing praxis service	must	v0.4	deferred-to-v0.4
REQ-NFR-IRT-01	IRT θ update latency — < 100ms (in-process, no LLM call)	must	P1	active
REQ-NFR-DASH-01	Cohort dashboard k-anonymity ≥ 10 — any cohort view cell with < 10 learners is suppressed	must	v0.4	deferred-to-v0.4
REQ-NFR-DASH-02	Cohort dashboard freshness — aggregates ≤ 24h stale	must	v0.4	deferred-to-v0.4

Constraints (binding — carry forward from v0.1/v0.2)

• C-1 Voice is primary interface; text is fallback only
• C-2 Must work on $100 Android phone over 2G/3G (relaxed for v0.1 Canada pilot)
• C-3 Cost ≤ $3/active learner/month (relaxed for v0.1 pilot)
• C-4 Audio-only in v1
• C-5 Open-weights LLM via Ollama catalog — gemma4:cloud + deepseek-v4-flash:cloud
• C-6 Domain safety guardrails + HITL + disclaimers for safety-sensitive domains
• C-7 Scenarios authored by domain experts + learning designers; AI generates variations only
• C-8 Latency budget < 600ms end-to-end (ASR → LLM → TTS) — mastery scoring must not be on the voice path

v0.3 Out of Scope (still deferred)

• REQ-PATH-01 (full multi-path launch) — v0.3 ships Customer Service path only
• REQ-DASH-01 (cohort dashboard) — deferred to v0.4 per GRILL-v0.3.md Axis 2 (was v0.8 on original ROADMAP)
• REQ-AUTH-01, REQ-MT-01, REQ-MT-02 (operator auth + Postgres) — deferred to v0.4 (operator tier)
• REQ-NFR-DASH-01, REQ-NFR-DASH-02, REQ-NFR-AUTH-01, REQ-NFR-MT-01 — deferred to v0.4
• REQ-DASH-02 (full operator-suite dashboard) — later milestone
• REQ-ASSIST-01..03 (Live Assist) — later milestone
• REQ-LOWBW-01..03 (WhatsApp/USSD/offline) — later milestone
• REQ-VOICE-05/06 (multi-language, persona switching) — later milestone
• Third-party credential issuers (university/agency) — v0.9 credentialing milestone
• Learner auth / multi-learner-per-device — operator auth is v0.4; learner auth later
• Active failure injection (D-009) — evaluated in v0.3 RESEARCH (D-049), stays off
• Dynamic rubric weight re-weighting on branch outcome — static weights in v0.3, dynamic is a future feature (grill Axis 9)

---

v0.2 Requirements (complete — retained for reference)

Functional Requirements

Voice Conversation Engine

REQ-ID	Requirement	Priority	Phase	Status
REQ-VOICE-01	Real-time streaming ASR accepting accented, noisy speech (Canadian English pilot)	must	P1	complete
REQ-VOICE-02	Streaming TTS with natural prosody, one voice persona (single voice for both mentor and role-play character per D-006)	must	P1	complete
REQ-VOICE-03	End-to-end voice round-trip < 600ms (ASR → LLM → TTS first audio)	must	P1	complete
REQ-VOICE-04	Interruptibility — learner can cut the AI off mid-sentence (abort-and-yield semantics per D-008)	must	P1	complete
REQ-VOICE-05	Multi-language support (10+ launch languages)	later	deferred	deferred
REQ-VOICE-06	Persona switching — same AI becomes customer/colleague/patient/mentor	later	deferred	deferred

Scenario Engine

REQ-ID	Requirement	Priority	Phase	Status
REQ-SCEN-01	One branching Customer Service role-play scenario (Canada context): "Angry customer requesting refund on damaged product" with one branch point (escalate vs accept), defined success criteria, common mistakes, and a failure_mode field present but not actively provoked in v0.1 (per D-009, D-010)	must	P1	complete
REQ-SCEN-02	Dynamic difficulty adjustment based on learner performance	later	deferred	deferred
REQ-SCEN-03	Scenario library tagged by skill, difficulty, failure mode	later	deferred	deferred
REQ-SCEN-04	Expert-authored scenario format with AI-generated variations	later	deferred	deferred

Mastery & Assessment

REQ-ID	Requirement	Priority	Phase	Status
REQ-MAST-01	Competency rubric per skill	later	deferred	deferred
REQ-MAST-02	Mastery Score updated after each session, requiring varied-scenario success	later	deferred	deferred
REQ-MAST-03	Portable verifiable credentials on mastery	later	deferred	deferred
REQ-MAST-04	No quizzes — assessment built into scenarios	principle	—	accepted

Skill Paths

REQ-ID	Requirement	Priority	Phase	Status
REQ-PATH-01	Launch paths: Customer Service, Retail Sales, Hospitality Front Desk, Home Health Aide, Basic English for Work, Auto-Rickshaw/Taxi	later	deferred	deferred
REQ-PATH-02	Path structured as a job (6-week example structure per PRD §6.4)	later	deferred	deferred

Live Assist

REQ-ID	Requirement	Priority	Phase	Status
REQ-ASSIST-01	Hands-free voice companion invocable while working	later	deferred	deferred
REQ-ASSIST-02	Context-aware (knows current scenario/skill)	later	deferred	deferred
REQ-ASSIST-03	Guardrails: coaches, does not do the job; never lies to real customers	later	deferred	deferred

Low-Bandwidth Surfaces

REQ-ID	Requirement	Priority	Phase	Status
REQ-LOWBW-01	WhatsApp/SMS bot thin entry point (2-min voice-note scenarios)	later	deferred	deferred
REQ-LOWBW-02	USSD fallback for feature phones	later	deferred	deferred
REQ-LOWBW-03	Offline cache for pre-downloaded scenarios and voices	later	deferred	deferred

Employer / Program Dashboard

REQ-ID	Requirement	Priority	Phase	Status
REQ-DASH-01	Anonymized cohort view (practice, mastery progression, failure patterns)	later	deferred	deferred
REQ-DASH-02	For training operators and SME HR, not individual learners	later	deferred	deferred

Learner State

REQ-ID	Requirement	Priority	Phase	Status
REQ-STATE-01	Single-learner session log with progress and session history (v0.1: local SQLite persistence, no auth, no multi-tenant per D-007)	must	P1	complete

Coaching Debrief

REQ-ID	Requirement	Priority	Phase	Status
REQ-DEBRIEF-01	End-of-session single text+voice summary (not full multi-moment replay) per D-011	must	P1	complete

LLM Foundation

REQ-ID	Requirement	Priority	Phase	Status
REQ-LLM-01	Ollama-hosted gemma4:cloud model callable for edge/fast-path persona responses (via Ollama Cloud direct API per D-020)	must	P1	complete
REQ-LLM-02	Ollama-hosted deepseek-v4-flash:cloud model callable for complex coaching/debrief (no-think mode for latency per D-020)	must	P1	complete
REQ-LLM-03	Open-weights foundation enabling on-prem option for partners (model-call layer swappable per D-020)	principle	—	accepted

Orchestration & Pipeline (research-derived D-017)

REQ-ID	Requirement	Priority	Phase	Status
REQ-ORCH-01	Pipecat server orchestrates ASR→LLM→TTS pipeline with Silero VAD + interruptibility (D-017)	must	P1	complete
REQ-ORCH-02	Pluggable guardrail layer with Customer Service ruleset (D-019): no legal/financial/medical advice, no real-company impersonation, stay-in-role, session-start disclaimer	must	P1	complete

Scenario Format (research-derived D-018)

REQ-ID	Requirement	Priority	Phase	Status
REQ-SCEN-FMT-01	YAML DSL scenario definition → Pydantic model → Pipecat Flows consumption (D-018); supports failure_mode field (D-009)	must	P1	complete

Non-Functional Requirements

REQ-ID	Requirement	Target	Phase	Status
REQ-NFR-LAT-01	End-to-end voice round-trip latency	< 600ms	P1	complete
REQ-NFR-COST-01	Cost per active learner per month	≤ $3 (target markets; no enforced ceiling in v0.1 Canada pilot per D-012, but architecture must not preclude it). Log actual per-session cost in v0.1.	P1 (logging only)	complete
REQ-NFR-SAFE-01	Domain safety guardrails + disclaimers for safety-sensitive scenarios	baseline for v0.1 (Customer Service lower risk)	P1	complete
REQ-NFR-BW-01	Usable on 2G/3G bandwidth	target	later	deferred
REQ-NFR-DEVICE-01	Usable on $100 Android phone	target	later	deferred
REQ-NFR-AUDIO-01	Audio-only in v1 (no large video assets)	principle	—	accepted

Constraints (binding)

• C-1 Voice is primary interface; text is fallback only
• C-2 Must work on $100 Android phone over 2G/3G (relaxed for v0.1 Canada pilot)
• C-3 Cost ≤ $3/active learner/month (relaxed for v0.1 pilot)
• C-4 Audio-only in v1
• C-5 Open-weights LLM via Ollama catalog — gemma4:cloud + deepseek-v4-flash:cloud
• C-6 Domain safety guardrails + HITL + disclaimers for safety-sensitive domains
• C-7 Scenarios authored by domain experts + learning designers; AI generates variations only
• C-8 Latency budget < 600ms end-to-end

Deployment (v0.2 — Proxmox LXC)

REQ-ID	Requirement	Priority	Phase	Status
REQ-DEPLOY-01	Multi-stage Dockerfile: Node stage builds client/dist via npm run build, Python stage runs the Pipecat server and serves client/dist via FastAPI StaticFiles (D-022, D-023)	must	P1	complete
REQ-DEPLOY-02	docker-compose.yml defining the praxis service with volume for SQLite DB (praxis.db), env injection, port mapping (8789), restart policy	must	P1	complete
REQ-DEPLOY-03	Port scripts/proxmox/api.sh from coreci verbatim (PVE REST helpers: pve_curl, pve_poll, pve_nextid, pve_get, pve_env, pve_lxc_env_args)	must	P1	complete
REQ-DEPLOY-04	Port scripts/proxmox/lxc-clone.sh adapted for praxis (hostname=praxis, port 8789, features=nesting=1 for Docker-in-LXC)	must	P1	complete
REQ-DEPLOY-05	Port scripts/proxmox/lxc-config.sh adapted: hookscript snippet, lxc.environment injects GITEA_TOKEN + DEEPGRAM_API_KEY + voice-service env vars (empty if unprovisioned), PRAXIS_PORT=8789	must	P1	complete
REQ-DEPLOY-06	Port scripts/proxmox/firstboot-hook.sh adapted: host-builds Docker image (or loads pre-built), pct exec runs docker compose up -d inside the CT, health-checks /health :8789	must	P1	complete
REQ-DEPLOY-07	Port scripts/proxmox/health-check.sh adapted for praxis: polls http://<bridge-ip>:8789/health (not coreci's /healthz :18080)	must	P1	complete
REQ-DEPLOY-08	Port scripts/proxmox/{lxc-start,rollback,stage-snippet,timing}.sh from coreci (adapted for praxis snippet name)	must	P1	complete
REQ-DEPLOY-09	Port scripts/proxmox/lxc-deploy.sh orchestrator: clone → config → start → health-check → rollback-on-failure, with idempotency (--recreate/--reconfigure)	must	P1	complete
REQ-DEPLOY-10	scripts/install-service.sh adapted: creates praxis user, data/log dirs, env file, systemd unit (praxis.service) that runs docker compose up -d, health-checks /health :8789	must	P1	complete
REQ-DEPLOY-11	scripts/proxmox/praxis.service systemd unit running docker compose up -d with Restart=on-failure	must	P1	complete
REQ-DEPLOY-12	Secret wiring: extend config.json secrets.scopes with proxmox + voice scopes; source PROXMOX_* from ~/coreci/.ciagent/.env.secrets	must	P1	complete
REQ-DEPLOY-13	FastAPI server/__main__.py mounts client/dist as StaticFiles at / (serving the React client from the same port as the API)	must	P1	complete
REQ-DEPLOY-14	.env.example updated with PROXMOX_* + deployment env vars (documented, not secret)	must	P1	complete
REQ-DEPLOY-15	E2E deploy verification: scripts/proxmox/test/ bats tests (mirroring coreci's test structure) + health-check + smoke against live CT	must	P1	complete
REQ-DEPLOY-16	.dockerignore excluding node_modules, .git, __pycache__, .pytest_cache, client/dist (rebuilt in image), .ciagent/.env* (secrets)	must	P1	complete

Non-Functional Requirements (v0.2)

REQ-ID	Requirement	Target	Phase	Status
REQ-NFR-DEPLOY-01	Deploy idempotency — re-running lxc-deploy.sh against a healthy CT is a no-op; unhealthy CT requires explicit --recreate/--reconfigure	must	P1	complete
REQ-NFR-DEPLOY-02	Deploy rollback — any stage failure (clone/config/start/health) triggers rollback.sh (stop + destroy the partial CT)	must	P1	complete
REQ-NFR-DEPLOY-03	First-boot install time	< 5 min (Docker image load + compose up + health)	P1	deferred (live cluster required)
REQ-NFR-DEPLOY-04	Secrets never committed to git (.ciagent/.env* in .gitignore, secrets injected via lxc.environment at runtime)	must	P1	complete

Out of Scope (v0.1)

• Mastery scoring, competency rubrics, verifiable credentials
• Multi-language (launch: Canadian English only)
• Employer dashboard
• Live Assist mode
• WhatsApp/SMS/USSD surfaces
• Drill Mode, Review Mode
• Scenario authoring marketplace
• B2B SaaS
• Voice cloning of real individuals
• Early childhood education, medical procedures (permanent per PRD §11.6)