nextcraft/.ciagent/ROADMAP.md

Nextcraft — ROADMAP.md

Overview

Milestone v0.4 — COMPLETE (shipped as v0.3.4, 2026-09-13). Distribution & Bootstrap CLI: nextcraft CLI (doctor/bootstrap/verify/dev) shipped as a linux x64 SEA binary, one-liner install script with checksum + version integrity gates, and binaries published on every ongoing release (v0.3.2 onward). Next milestone: v0.5 (real server STT/TTS + KYC/identity + design/simulation sandbox environments + exec-telemetry seq-lease — the seams deferred out of v0.4 by founder directive D-016).

Milestone v0.3 — Credential Engines: complete, shipped as v0.2.8 (2026-09-12). Real sandbox fabric, live build telemetry, process-trace grading, per-learner variants, oral defense, real learner surfaces.

Deferred per founder directive (D-016): REQ-F-017 identity verification + age-gating (real KYC backend), real server STT/TTS, design/simulation sandbox environments, and the exec-telemetry seq-lease are deferred to v0.5. 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 CLI + distribution pipeline) Tag line: v0.3.x (patches on the v0.3 line; milestone release as the final v0.3.x patch) Branch: milestone/v0.4-distribution

---

Phase List

#	Name	Status	Depends On	Requirements	Success Criteria
0	Pre-execution	complete	—	—	Specification, clarify, research, plan complete; .ciagent/ files updated for v0.4
1	Bootstrap CLI core	complete	0	REQ-4-001, REQ-4-002	nextcraft doctor/bootstrap/verify/dev work against a fresh clone; unit tests green
2	Binary build + release pipeline	complete	1	REQ-4-003, REQ-4-004	Reproducible linux x64 binary + sha256 checksum; one-liner install script; assets uploaded to the Gitea release
3	Install docs + fresh-clone E2E	complete	2	REQ-4-005	README quickstart verified end-to-end from a clean environment; fresh clone reaches running stack
4	Final review + ship	complete	3	—	Code review clean; audit passes; milestone tagged (v0.3.x final patch); release with binary assets created on Gitea

---

Phase Details

Phase 0: Pre-execution

Goal: Establish v0.4 specification (founder directive D-016), clarify ambiguities, research the binary toolchain + Gitea release-asset API + existing bootstrap scripts, create detailed plans, grill adversarially.

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.4; phase 0 shipped as v0.3.0.

---

Phase 1: Bootstrap CLI Core

Goal: A working nextcraft CLI with doctor/bootstrap/verify/dev commands, unit-tested against the real monorepo.

Requirements: REQ-4-001, REQ-4-002

Key deliverables:

• apps/cli package: nextcraft executable (source-runnable in dev, binary-built in P2)
• doctor: checks node ≥18, pnpm, python3 ≥3.11, git, unshare availability — actionable errors, exit codes
• bootstrap: idempotent — pnpm install, ai-service venv + pinned deps (reuses scripts/bootstrap.sh logic), .env from .env.example templates, key validation (warnings not blockers for optional keys), .env.secrets handling
• verify: health check — venv imports, pnpm build readiness, ports free, env vars present
• dev: thin passthrough to scripts/dev.sh (no orchestration logic duplicated)
• Unit tests: doctor/bootstrap parsing + command dispatch, against fixtures (never modifying the real repo state)

Success criteria:

• nextcraft doctor reports each prerequisite with actionable guidance
• nextcraft bootstrap on a fresh clone reaches a state where verify passes
• All commands have --help, exit non-zero on failure, no shell-out without timeout
• pnpm build, pnpm typecheck, pnpm ai:test green

---

Phase 2: Binary Build + Release Pipeline

Goal: Reproducible linux x64 binary + one-liner install + release-asset upload wired into the ship flow.

Requirements: REQ-4-003, REQ-4-004

Key deliverables:

• Build script producing nextcraft-linux-x64 + nextcraft-linux-x64.sha256 (toolchain probe-verified at RESEARCH; embedded script assets)
• One-liner install script install.sh served from the repo: detect linux x64, resolve latest release via Gitea API, download + verify checksum, install to ~/.local/bin, PATH hint, source-bootstrap fallback when no binary/asset
• Ship integration: every release from v0.4 onward attaches the binary + checksum as release assets (the "ongoing binaries" requirement)
• Asset-upload helper using the Gitea token from .env* files only (never shell env)

Success criteria:

• Binary runs on this box: ./nextcraft-linux-x64 doctor green against the repo
• Install script verified end-to-end against the real Gitea release (or local dry-run if release pending)
• Checksum verification rejects a corrupted download (tested)
• Release assets present on the phase ship

---

Phase 3: Install Docs + Fresh-Clone E2E

Goal: Documentation and end-to-end proof that a fresh consumer reaches a running stack via the one-liner.

Requirements: REQ-4-005

Key deliverables:

• README quickstart: one-liner → nextcraft doctor → nextcraft bootstrap → nextcraft dev
• CLI command reference (all flags, exit codes)
• Fresh-clone E2E test: clean temp clone → doctor → bootstrap → verify → build green (sandboxed; no network beyond package registries already used)
• Install-script docs: prerequisites, offline/manual install, troubleshooting

Success criteria:

• A fresh clone bootstraps to a passing verify with one command sequence
• README quickstart matches the actual tested flow exactly
• E2E test green in CI-equivalent local run

---

Phase 4: Final Review + Ship

Goal: Code review, audit, milestone release with binary assets.

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.3.x patch, create Gitea release WITH binary + checksum assets, verify assets downloadable

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 with nextcraft-linux-x64 + .sha256 assets attached — the first of the ongoing binary releases

---

v0.4 (Complete — Shipped as v0.3.4)

Distribution & Bootstrap CLI: nextcraft CLI (doctor/bootstrap/verify/dev) as a self-contained linux x64 SEA binary, one-liner install with sha256 + version integrity gates, release-asset pipeline attaching binaries to every ongoing release (v0.3.2 onward), install/quickstart docs backed by a fresh-clone E2E test. 5 phases (P0–P4). All 5 requirements (REQ-4-001..005) complete. Tags v0.3.0–v0.3.3 per phase, milestone release v0.3.4.

v0.3 (Complete — Shipped as v0.2.8)

Credential Engines: real sandbox fabric (Linux namespaces), live build telemetry (at-least-once/exactly-once), process-trace grading (G-4 gated), seeded per-learner variants (fairness anchors wired to grading), oral defense with integrity signals (mock-first voice, browser fallback), and real learner build/defense/grading surfaces. 8 phases. All 8 requirements (REQ-3-001..008) complete. Tags v0.2.1–v0.2.7 per phase, milestone release v0.2.8.

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.