nextcraft/.ciagent/ROADMAP.md

Nextcraft — ROADMAP.md

Overview

Milestone v0.3 — Credential Engines: Replace v0.2's mock engine inputs with real credential engines. Build the sandbox fabric (sandboxed IDE / design tool / simulation), the live in-environment build-telemetry pipeline, the process-trace grading engine, per-learner variant task generation, and the oral/voice defense with AI examiner. Lab/Assessor/Proctor agents move from mock inputs to real engine inputs.

Deferred per founder directive: REQ-F-017 identity verification + age-gating (real KYC backend) is deferred beyond v0.3. Age-gating remains the v0.1 visual flow mockup.

Prior milestone: v0.2 (ai-tutor-architecture) — complete, shipped as v0.2.0, six tutor agents live over mock engine inputs (D-015).

Milestone type: Feature (new credential-engine services + real agent inputs) Tag line: v0.2.x (patches on the v0.2 line; milestone release as the final v0.2.x patch) Branch: milestone/v0.3-credential-engines

---

Phase List

#	Name	Status	Depends On	Requirements	Success Criteria
0	Pre-execution	in-progress	—	—	Specification, clarify, research, plan complete; .ciagent/ files updated for v0.3
1	Sandbox fabric	complete	0	REQ-3-001, REQ-3-002	Isolated per-learner sandbox environments provisioned (IDE / design / simulation); lifecycle API (create/destroy/snapshot); resource limits enforced; no cross-tenant access
2	Live build telemetry	complete	1	REQ-3-003	In-environment capture of process events (commands, file diffs, run/test results, keystroke-level activity) streamed to ai-service; reliable transport; per-learner trace persistence
3	Process-trace grading engine	complete	2	REQ-3-004	Grades artifacts from their full process traces (not just final output); emits structured rubric-aligned scores; feeds Assessor real inputs
4	Variant task generation	complete	1	REQ-3-005	Per-learner task variants generated so no two learners receive identical prompts; variant seed recorded for grading fairness
5	Oral / voice defense	pending	3	REQ-3-006	AI examiner conducts spoken defense of submitted work; STT → dialogue → TTS; transcript + integrity signals captured; feeds Proctor/Mentor
6	Agent re-grounding + learner surface integration	pending	2,3,4,5	REQ-3-007, REQ-3-008	Lab/Assessor/Proctor consume real engine inputs; v0.1 sandbox + assessment mockups wired to real engines (in-browser build/run, live telemetry, live defense)
7	Final review + ship	pending	6	—	Code review clean; audit passes; milestone tagged (v0.2.x final patch); release created on Gitea

---

Phase Details

Phase 0: Pre-execution

Goal: Establish v0.3 specification, clarify ambiguities, research credential-engine architecture (sandbox isolation, telemetry transport, trace grading, variant generation, voice IO), create detailed plans.

Stages: SPECIFY → CLARIFY → RESEARCH → PLAN → GRILL → MVP/UX CHECK → SHIP

Deliverables:

• Updated .ciagent/config.json, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, ARCHITECTURE.md, PERSONAS.md, PLAN.md

Success criteria: All .ciagent/ files updated for v0.3; phase 0 shipped as first v0.2.x patch.

---

Phase 1: Sandbox Fabric

Goal: Provision and manage isolated per-learner execution environments.

Requirements: REQ-3-001, REQ-3-002

Key deliverables:

• Sandbox orchestrator service: create/list/destroy/snapshot sandbox instances (IDE, design tool, simulation)
• Isolation boundary: per-learner containerization or VM-grade isolation; no cross-tenant filesystem/network access
• Resource limits: CPU/memory/disk/time quotas per sandbox
• Sandbox lifecycle API consumed by ai-service and the web learner surface

Success criteria:

• A sandbox can be created, written to, snapshotted, and destroyed via API
• Isolation verified: a sandbox cannot read another learner's data
• Resource limits enforced and observable — enforcement mechanism: rlimits (memory/CPU) + wall-clock reaper + workdir-size sweep; per-sandbox pids and hard-disk-quota are accepted v0.3 gaps (no cgroup delegation/sudo on this box, G-1)

---

Phase 2: Live Build Telemetry

Goal: Capture in-environment process events and stream them to ai-service reliably.

Requirements: REQ-3-003

Key deliverables:

• Telemetry capture agent (in-sandbox): commands, file diffs, run/test results, keystroke-level/activity events
• Telemetry transport: durable, ordered, resumable stream to ai-service ingestion endpoint
• Trace persistence: per-learner, per-task process traces stored for grading and proctoring
• Transport hardening: retries, backpressure, exactly-once-or-at-least-once semantics documented

Success criteria:

• Sandbox activity produces a complete ordered process trace in ai-service
• Stream survives transient network failure without trace loss
• Trace retrievable by learner+task ID for grading

---

Phase 3: Process-Trace Grading Engine

Goal: Grade learner artifacts from their full process traces.

Requirements: REQ-3-004

Key deliverables:

• Trace analyzer: reconstructs build/decision timeline from a process trace
• Grading engine: rubric-aligned scoring over the trace (process quality, not just final artifact)
• Structured score output consumable by the Assessor agent
• Calibration against v0.2 mock corpora to validate grading dimensions

Success criteria:

• Engine emits structured rubric-aligned scores from a real process trace
• Scores distinguish process quality (e.g., iterative debugging vs. paste-and-run)
• Output feeds Assessor; replaces pre-baked artifact corpus inputs

---

Phase 4: Variant Task Generation

Goal: Generate per-learner task variants so no two learners receive identical prompts.

Requirements: REQ-3-005

Key deliverables:

• Variant generator: parameterized task templates → unique per-learner instances
• Variant seed registry: record variant parameters for grading fairness and proctoring
• Difficulty normalization: variants calibrated to equivalent difficulty

Success criteria:

• Two learners requesting the same competency receive distinct task variants
• Variant parameters persisted and auditable
• Grading engine scores variants equitably

---

Phase 5: Oral / Voice Defense

Goal: AI examiner conducts a spoken defense of the learner's submitted work.

Requirements: REQ-3-006

Key deliverables:

• Voice pipeline: STT → defense dialogue (LLM examiner) → TTS
• Examiner agent: probes understanding, challenges process choices from the trace
• Transcript + integrity signals captured for Proctor/Mentor
• Latency budget: defense feels conversational (bounded turn latency)

Success criteria:

• A spoken defense runs end-to-end (speak → examiner question → learner response → verdict)
• Transcript + integrity signals persisted and consumable by Proctor
• Turn latency within the documented budget

---

Phase 6: Agent Re-grounding + Learner Surface Integration

Goal: Move Lab/Assessor/Proctor to real engine inputs; wire learner surface to the real engines.

Requirements: REQ-3-007, REQ-3-008

Key deliverables:

• Lab agent consumes live sandbox telemetry (replaces v0.2 mock telemetry)
• Assessor agent consumes grading-engine output (replaces pre-baked artifacts)
• Proctor consumes telemetry + defense integrity signals (replaces mock telemetry)
• Learner sandbox mockup → real in-browser build/run; assessment mockup → live defense + live grading

Success criteria:

• Lab/Assessor/Proctor operate on real inputs with no mock fallback in the learner path
• Learner can build in-browser and see live telemetry + live feedback
• Assessment surface runs a live defense and shows live grading
• pnpm build and pnpm typecheck pass

---

Phase 7: Final Review + Ship

Goal: Code review, audit, milestone release.

Key deliverables:

• Multi-persona code review (correctness, testing, security, performance, maintainability)
• Project health audit (reconstruction test, .ciagent/ file discipline, branch hygiene, commit discipline)
• Milestone ship: merge milestone → main, tag final v0.2.x patch, create Gitea release

Success criteria:

• Code review: P0 fixes applied, P1+ documented
• Audit: all checks pass, project state reconstructable from git log
• Ship: milestone tagged, branch merged to main, Gitea release created — release note states identity/age-gating (KYC) is deferred and age-gating remains a visual mockup
• All v0.3 requirements marked complete

---

v0.2 (Complete — Shipped as v0.2.0)

AI Tutor Architecture: Six AI tutor agents (Coach, Tutor, Lab, Assessor, Proctor, Mentor) as real LLM-backed services over mock engine inputs, wired into the learner surface with streaming. 7 phases. All 12 requirements complete. Milestone release v0.2.0.

v0.1 (Complete — Shipped as v0.1.0)

UI/UX Prototype: High-fidelity interactive prototype of all four Nextcraft surfaces. 7 phases (P0 + P1-P6 execution + P7 final). All 28 requirements complete. Tags v0.0.1–v0.0.7, milestone release v0.1.0.