# 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.