# Nextcraft — REQUIREMENTS.md

## v0.3 Requirements (Credential Engines)

### Sandbox & Telemetry

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-3-001 | Sandbox fabric: isolated per-learner execution environments (sandboxed IDE, design tool, simulation) with lifecycle management | critical | 1 | complete |
| REQ-3-002 | Sandbox isolation + resource limits: per-learner isolation boundary, CPU/memory quotas (rlimits), wall-clock time quota, disk-quota via per-sandbox workdir usage sweep (best-effort, not kernel-enforced), no cross-tenant access, snapshot support. **Known gap (v0.3): per-sandbox pids and hard disk caps are NOT kernel-enforceable without cgroup delegation/sudo — documented as accepted risk** | critical | 1 | complete |
| REQ-3-003 | Live build telemetry: in-environment capture of process events (commands, file diffs, run/test results, activity) streamed reliably to ai-service with per-learner trace persistence | critical | 2 | complete |

### Credential Engines

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-3-004 | Process-trace grading engine: grade artifacts from their full process traces; rubric-aligned structured scores; feeds Assessor real inputs | critical | 3 | complete |
| REQ-3-005 | Variant task generation: per-learner task variants (no two learners get identical prompts); variant seed registry; difficulty normalization | high | 4 | complete |
| REQ-3-006 | Oral/voice defense: AI examiner conducts spoken defense (STT → dialogue → TTS); transcript + integrity signals captured; feeds Proctor/Mentor | high | 5 | pending |

### Agent Re-grounding & Integration

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-3-007 | Agent re-grounding: Lab consumes live telemetry; Assessor consumes grading-engine output; Proctor consumes telemetry + defense integrity signals (replace v0.2 mocks) | critical | 6 | pending |
| REQ-3-008 | Learner surface integration: sandbox mockup → real in-browser build/run with live telemetry; assessment mockup → live defense + live grading | critical | 6 | pending |

---

## v0.2 Requirements (Complete — AI Tutor Architecture)

### AI Service Infrastructure

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-2-001 | apps/ai-service scaffolding: Python FastAPI app, pydantic settings, uvicorn, health endpoint, CORS, pytest setup, pnpm/turbo integration scripts | critical | 1 | complete |
| REQ-2-002 | Provider-agnostic LLM client: OpenAI-compatible provider interface with ollama-cloud (default), local-endpoint, and deterministic mock providers; key resolution from env files | critical | 1 | complete |
| REQ-2-003 | SSE streaming endpoint plumbing: chat completion streaming from provider through FastAPI to the Next.js client | critical | 1 | complete |
| REQ-2-004 | Agent framework: base agent contracts, session/state store, prompt management, streaming pipeline, structured output support | critical | 2 | complete |

### AI Tutor Agents

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-2-005 | Coach agent (REQ-F-001): pacing, motivation, retrieval practice — full LLM implementation | critical | 3 | complete |
| REQ-2-006 | Tutor agent (REQ-F-002): concept delivery, Socratic questioning — full LLM implementation | critical | 3 | complete |
| REQ-2-007 | Lab agent (REQ-F-003): in-flow feedback over simulated sandbox telemetry (mock inputs) | high | 4 | complete |
| REQ-2-008 | Assessor agent (REQ-F-004): rubric application to pre-baked artifacts and defense transcripts (mock inputs) | high | 4 | complete |
| REQ-2-009 | Proctor agent (REQ-F-005): integrity signals from mock telemetry, coaching interventions | high | 5 | complete |
| REQ-2-010 | Mentor agent (REQ-F-006): long-horizon career narrative | high | 5 | complete |

### Learner Surface Integration

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-2-011 | Learner chat UI wired to real service: streaming responses, agent routing, error and loading states | critical | 6 | complete |
| REQ-2-012 | Byte tutorial viewer, build sandbox, and assessment mockups surface Lab/Assessor/Proctor outputs (mock engine inputs) | high | 6 | complete |

---

## v0.1 Requirements (Complete)

### Infrastructure

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-001 | Monorepo scaffolding: pnpm workspaces, turborepo, Next.js app, TypeScript config, ESLint, Prettier | critical | 1 | complete |
| REQ-002 | Shared component library: design tokens, Button, Input, Card, Badge, Avatar, Dialog, Navigation, Table, Tabs, Progress, Tooltip, Skeleton, Toast | critical | 1 | pending |
| REQ-003 | Mock data layer: typed mock data for competency stacks, job listings, candidate profiles, employers, learner progress | critical | 1 | pending |
| REQ-004 | Routing and navigation: App Router route groups for (learner), (marketplace), (employer), (admin); shared layout components; cross-surface navigation | critical | 1 | pending |
| REQ-005 | Responsive layout system: mobile, tablet, desktop breakpoints; container components; grid system | high | 1 | pending |

### Learner Surface

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-006 | Landing page: hero, value proposition, program highlights, how-it-works (Byte→Build→Demonstrate→Defend), testimonials mockup, CTA to program catalog | critical | 2 | pending |
| REQ-007 | Program catalog: grid of competency stacks (AI Orchestration Engineer, AI Safety & Governance Lead, Human-AI Product Designer, AI-Augmented Field Operator, Computational Sciences Practitioner); stack cards with role descriptions | critical | 2 | pending |
| REQ-008 | Competency stack view: selected stack detail with 12-18 competencies listed, progress indicators, microcredential badges, mastery status | critical | 2 | pending |
| REQ-009 | Learner dashboard: active competencies, progress graph, recent artifacts, upcoming defenses, AI tutor chat mockup, milestone tracker | critical | 2 | pending |
| REQ-010 | Byte tutorial viewer: 3-7 minute micro-tutorial layout with concept panel, worked example panel, code/design/simulation viewer mockup | high | 2 | pending |
| REQ-011 | Build sandbox mockup: sandboxed IDE/design tool/simulation UI mockup with toolbar, file explorer, editor area, telemetry sidebar (process capture indicators) | high | 2 | pending |
| REQ-012 | Assessment/defense mockup: rubric display, AI reviewer panel, oral defense interface (voice/mic mockup), process trace timeline, artifact viewer | high | 2 | pending |

### Marketplace Surface

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-013 | Job board listing: searchable grid of AI-era job listings, filter sidebar (skills, seniority, location, salary), result cards with match score | critical | 3 | pending |
| REQ-014 | Job detail page: full job description, required competencies, employer info, application CTA, related jobs, AI-matched skills breakdown | critical | 3 | pending |
| REQ-015 | Employer profile: company overview, logo, description, social links, open positions, company culture mockup | high | 3 | pending |
| REQ-016 | Search/filter UI: semantic search bar, skill tags, category filters, seniority filter, remote/on-site toggle, saved searches mockup | critical | 3 | pending |
| REQ-017 | Pricing page: job posting packages (single, bundle, enterprise), talent access plans, subscription tiers, feature comparison table | high | 3 | pending |

### Employer Dashboard

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-018 | Employer dashboard overview: active postings, applicant pipeline, talent matches, analytics mockup (charts, placement stats) | critical | 4 | pending |
| REQ-019 | Talent search: searchable candidate database with AI-matched filters, candidate cards showing competency stack, microcredentials, artifact count, defense score | critical | 4 | pending |
| REQ-020 | Candidate profile view: full candidate profile with artifact gallery, process trace summary, oral defense transcripts, competency graph, microcredential verification | high | 4 | pending |
| REQ-021 | Posting management: create/edit/delete job postings, posting status tracking, applicant list per posting, interview pipeline mockup | high | 4 | pending |

### Admin Surface

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-022 | Admin overview: platform metrics (learners, employers, placements, completion rate, NPS), recent activity feed, system health mockup | critical | 5 | pending |
| REQ-023 | Learner management: searchable learner table, learner detail view, progress tracking, competency completion status, credential issuance log | high | 5 | pending |
| REQ-024 | Competency graph viewer: interactive visualization of competency stacks and their relationships, node/edge graph using react-flow, stack details on node click | high | 5 | pending |
| REQ-025 | Marketplace moderation: job posting review queue, employer verification queue, flagged content, content moderation tools mockup | high | 5 | pending |

### Polish & Integration

| ID | Description | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-026 | Cross-surface navigation: role switcher (learner/employer/admin), breadcrumbs, consistent header/footer across all surfaces | critical | 6 | pending |
| REQ-027 | Visual consistency audit: typography scale, color palette, spacing system, dark mode toggle, accessibility baseline (WCAG AA contrast) | high | 6 | pending |
| REQ-028 | Component library finalization: Storybook setup, component documentation, prop tables, usage examples | medium | 6 | pending |

---

## v2 Requirements (Future Milestones — Deferred)

### Assessment Engine

| ID | Description | Priority | Milestone | Status |
|----|-------------|----------|-----------|--------|
| REQ-F-007 | Process-trace grading engine → activated as REQ-3-004 | high | v0.3 | activated |
| REQ-F-008 | Per-learner variant task generation → activated as REQ-3-005 | high | v0.3 | activated |
| REQ-F-009 | Oral/voice defense with AI examiner → activated as REQ-3-006 | high | v0.3 | activated |
| REQ-F-010 | Live in-environment build with telemetry → activated as REQ-3-003 | high | v0.3 | activated |
| REQ-F-021 | Sandbox fabric: sandboxed IDE, design tool, simulation → activated as REQ-3-001/002 | high | v0.3 | activated |

### Marketplace Engine

| ID | Description | Priority | Milestone | Status |
|----|-------------|----------|-----------|--------|
| REQ-F-011 | AI job aggregation pipeline (3M+ jobs from 120K companies) | high | v0.4+ | deferred |
| REQ-F-012 | AI-powered tagging (skills, categories, seniority) | high | v0.4+ | deferred |
| REQ-F-013 | Semantic vector search for role matching | high | v0.4+ | deferred |
| REQ-F-014 | AI company enrichment (logos, descriptions, social links) | medium | v0.4+ | deferred |
| REQ-F-015 | AI resume parsing (profile auto-fill) | medium | v0.4+ | deferred |
| REQ-F-016 | SEO-optimized programmatic pages | medium | v0.4+ | deferred |

### Platform Infrastructure

| ID | Description | Priority | Milestone | Status |
|----|-------------|----------|-----------|--------|
| REQ-F-017 | Identity verification and age-gating (16+/18+) — real KYC backend | high | v0.4+ | deferred (deferred from v0.3 per founder directive) |
| REQ-F-018 | Payment processing and subscription management | high | v0.3+ | deferred |
| REQ-F-019 | Human tutor marketplace (third-party courses) | medium | v0.4+ | deferred |
| REQ-F-020 | CIRR-style placement tracking and audit | medium | v0.5+ | deferred |

---

## Out of Scope (Per Vision Doctrine)

| Feature | Reason |
|---------|--------|
| Traditional accreditation | Not sought, not pursued, not revisited (Principle 4) |
| Under-16 learners | COPPA avoidance; AI school floor is 16+ |
| Marketplace for under-18 | Marketplace restricted to 18+ with verified identity |
| Human tutors in core school | Humans exist only in open marketplace as third-party sellers |
| Graded written exams without process trace | Trivially solvable by frontier AI; process-trace + oral defense more valid |
| Legacy job titles in curriculum | Programs train for AI-era roles, not obsolete ones |
| Junk advertising | Ad quality enforced algorithmically; relevant ads only |

---

## Traceability Matrix

### v0.3 (current milestone)

| Requirement | Phase | Status |
|-------------|-------|--------|
| REQ-3-001 | 1 | complete |
| REQ-3-002 | 1 | complete |
| REQ-3-003 | 2 | complete |
| REQ-3-004 | 3 | complete |
| REQ-3-005 | 4 | complete |
| REQ-3-006 | 5 | pending |
| REQ-3-007 | 6 | pending |
| REQ-3-008 | 6 | pending |

### v0.2 (complete)

| Requirement | Phase | Status |
|-------------|-------|--------|
| REQ-2-001 | 1 | complete |
| REQ-2-002 | 1 | complete |
| REQ-2-003 | 1 | complete |
| REQ-2-004 | 2 | complete |
| REQ-2-005 | 3 | complete |
| REQ-2-006 | 3 | complete |
| REQ-2-007 | 4 | complete |
| REQ-2-008 | 4 | complete |
| REQ-2-009 | 5 | complete |
| REQ-2-010 | 5 | complete |
| REQ-2-011 | 6 | complete |
| REQ-2-012 | 6 | complete |

### v0.1 (complete)

| Requirement | Phase | Status |
|-------------|-------|--------|
| REQ-001 | 1 | complete |
| REQ-002 | 1 | complete |
| REQ-003 | 1 | complete |
| REQ-004 | 1 | complete |
| REQ-005 | 1 | complete |
| REQ-006 | 2 | complete |
| REQ-007 | 2 | complete |
| REQ-008 | 2 | complete |
| REQ-009 | 2 | complete |
| REQ-010 | 2 | complete |
| REQ-011 | 2 | complete |
| REQ-012 | 2 | complete |
| REQ-013 | 3 | complete |
| REQ-014 | 3 | complete |
| REQ-015 | 3 | complete |
| REQ-016 | 3 | complete |
| REQ-017 | 3 | complete |
| REQ-018 | 4 | complete |
| REQ-019 | 4 | complete |
| REQ-020 | 4 | complete |
| REQ-021 | 4 | complete |
| REQ-022 | 5 | complete |
| REQ-023 | 5 | complete |
| REQ-024 | 5 | complete |
| REQ-025 | 5 | complete |
| REQ-026 | 6 | complete |
| REQ-027 | 6 | complete |
| REQ-028 | 6 | complete |