CIAgent
1a68d808fb
---ci--- phase: 4 milestone: v0.4 status: complete requirements: covered: [REQ-4-001, REQ-4-002, REQ-4-003, REQ-4-004, REQ-4-005] partial: [] ---/ci---
142 lines
8.2 KiB
Markdown
142 lines
8.2 KiB
Markdown
# 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. |