Plan: .ciagent/PLAN.md Phase 5 (waves 5-1/5-2); manager verdict nextcraft#1 (hep, 2026-10-19T19:29Z). P5 vertical slice per the binding wave order: store reads -> routes -> web wiring -> tests in the same wave.
Phase 1 complete: the 9th D-027 store (PlacementRow partial-unique
active guard + PlacementEventRow global sha256 hash chain with the
UNIQUE(prev_hash) fork backstop), the D-099 matrix + event
vocabulary, the ONE transactional transition_application (D-100,
flush-then-hash-then-commit), main.py/deps wiring, the 22-test
adversarial suite (tamper/fork/concurrency/no-delete-path), the
security review fixes (tz conversion, actor vocabulary, conftest
topology), verify four-layers PASS. Ships as v0.10.1.
---ci---
phase: 1
milestone: v0.11
status: complete
requirements:
covered: [REQ-11-001]
partial: []
---/ci---
The v0.10 milestone: employers become principals of the marketplace
(REQ-F-019 activated as REQ-10-001..005 per D-085). Employer auth
with scrypt password hashing, hashed session tokens, and login/
register throttles (G-311/G-312/G-315); employer identity as claim/
verify over the v0.6 marketplace entities with advisory evidence
adjudication and admin approval (D-089/D-089/G-316/G-317); the
dashboard converted to real data with honest empty/pending/
processing states (no mock charts); self-serve postings through
the shared D-091 entitlement gate byte-identical with the admin
path (G-318/G-319); self-serve checkout over the v0.9 catalog
through the REAL webhook path with the own-session mock-complete
closing the G-301 class (G-302/G-303/G-304 carried forward); and
the admin network overview — accounts, claim queue, and audit in
one panel (D-094). Final review verdict SHIP: 2 P0s found and
fixed (the /me claim-state leak, the dead billing confirm button),
3 P1s dispositioned; audit PASS — reconstruction clean, discipline
green. Tags v0.9.0..v0.9.6 on the v0.9.x line; the tag lane builds
every release's full asset matrix per D-064.
---ci---
phase: 6
milestone: v0.10
status: complete
requirements:
covered: [REQ-10-001, REQ-10-002, REQ-10-003, REQ-10-004, REQ-10-005]
partial: []
---/ci---
The v0.9 milestone: payment processing and subscription management
(REQ-F-018 activated as REQ-9-001..005 per D-074). The billing module
(ai_service/billing/ — PaymentProvider protocol with deterministic
mock + Stripe-compatible REST over the shared pool, the 7th D-027
store with 7 tables, the HMAC-SHA256 webhook core per D-077), the
seeded catalog + /v1/billing routes, the pricing page's runtime
conversion, posting entitlement enforcement with honest 402 upgrade
CTAs, and the full subscription lifecycle with a queryable audit
trail. Operator-mediated checkout at pilot (D-076); grants exactly-
once per session (G-303); webhook state resolved from local rows only
(G-302); consumption as a single conditional UPDATE (G-304). Tags
v0.8.0..v0.8.6 on the v0.8.x line; the tag lane built every release's
full asset matrix + registry image (D-064).
---ci---
phase: 6
milestone: v0.9
status: complete
requirements:
covered: [REQ-9-001, REQ-9-002, REQ-9-003, REQ-9-004, REQ-9-005]
partial: []
---/ci---
The v0.8 milestone: installable on any Debian-based server via docker
(Gitea registry image, honest sandbox degrade), deb (amd64+arm64,
advisory postinst), and arch-aware binary — with release consistency
enforced by pre-commit hooks + Gitea Actions (3-runner fleet on CT 113,
machine-made releases with the full 8-asset matrix + registry image), the
CLI carrying the full suite (guide, channel-aware doctor), and the admin
runbook (deploy/README.md, evidence-backed recipes).
---ci---
phase: 6
milestone: v0.8
status: complete
requirements:
covered: [REQ-8-001, REQ-8-002, REQ-8-003, REQ-8-004, REQ-8-005]
partial: []
---/ci---
Escalation note: merge_to_main hook — proceeding per full autonomy +
founder report (deploy on the host reported success without updating;
the fix makes the failure loud and adds the freshness gate).
---ci---
phase: hotfix
milestone: v0.6
status: complete
type: hotfix
---/ci---
P1-1 WS ingest auth (grading DoS): the ingest socket is a grading input,
LAN-reachable in network mode, and identity params were self-asserted —
anyone could poison or flood a learner's trace. New HMAC ingest token
(telemetry/tokens.py): the sandbox manager mints it into NC_INGEST_URL
(bound to learner+task+sandbox, length-prefixed binding — no delimiter
injection), the WS endpoint verifies before accept. Mint/verify share one
app.state instance (per-boot random secret when
AI_TELEMETRY_INGEST_SECRET is unset; env-set for multi-process deploys).
Untokened/bad/cross-identity dials close 1008 storing nothing.
P1-2 defense-id collision: `dfn-{ms:x}` collided on same-millisecond
starts — the insert-only store's PK then 500'd the second start
permanently (the identity-resubmit P0-C1 class). Nonce+counter mint
(the identity/mock.py pattern); ids stay opaque, PII-free.
P1-3 browser-mode SR/TTS client gap: the mode="browser" descriptor has
advertised client-native SpeechRecognition + speechSynthesis since v0.5
(D-030/CUT-1) — the client never implemented it, so browser-mode voice
posted audio the server had no provider to transcribe. New pure module
apps/web/lib/browser-voice.ts (recognizeOnce + speakText, injectable
seams); the defense session uses it when descriptor.mode === 'browser'
(text answers; examiner questions spoken via speechSynthesis), keeps
MediaRecorder upload for server/mock modes, honest 'unsupported' state.
P1-4 browser-mode audio coverage: 8 node:test pins for the module
(transcript roundtrip, silent-user, permission/unsupported error maps,
timeout overrun, TTS absent/empty/cancel-prior/resolve-on-end).
488 backend tests (+10); web 22/22 (+8); CLI 61/61; typecheck 8/8;
ruff clean; export builds.
---ci---
phase: hotfix
milestone: v0.5
status: complete
type: hotfix
---/ci---
The host dogfood run, bug three: pnpm came from PNPM_HOME while node
lives in nvm — the prefix carried only pnpm's dir, so `pnpm build`
spawned turbo, which exec'd bare `node` and died rc 127. The
discovered prefix now includes every candidate dir carrying node OR
pnpm (pnpm's own dir first), so pnpm children resolve the same node
family on split installs — the exact production-host layout.
CLI 61/61 (+1 split-install regression pin).
---ci---
phase: hotfix
milestone: v0.5
status: complete
type: hotfix
---/ci---
The host dogfood run caught the second first-run bug: `git checkout
origin/main` detaches HEAD, and `git pull --ff-only` refuses to run on a
detached HEAD — deploy dead-ended on the production clone. origin/main
now resolves through local main (checkout main; checkout -B main
origin/main when absent), pulls only on that branch; --ref tags are
immutable checkouts (no pull attempted).
CLI 60/60 (+1 detached-HEAD regression).
---ci---
phase: hotfix
milestone: v0.5
status: complete
type: hotfix
---/ci---
Two first-run bugs found deploying v0.4.6 to the host (the dogfood run):
- run() filtered flags EVERYWHERE, so `deploy --service` never reached
the command ("unknown flag: --service" + help) — the exact command the
installer tells the user to run. Global flags are now only those
BEFORE the command name; subcommands own their own flags. doctor and
bootstrap gained arg validation (they previously ignored unknown
flags silently) to keep the exit-2 contract the old dispatcher gave.
- verify's web-export check failed fresh DEV clones (bootstrap → verify
→ exit 1: no export until pnpm build, by design in dev mode). Now
warn-only when absent; the runtime catch is the live mount probe +
the loud boot warning. Deploy builds the export before verify runs,
so single-port deploys keep the hard guarantee.
CLI 59/59 (fresh-clone E2E green against the rebuilt SEA binary).
---ci---
phase: hotfix
milestone: v0.5
status: complete
type: hotfix
---/ci---
The domain root (nextcraft.coreci.dev) served the API's JSON 404 for three
releases. Root cause (probe-verified on the host): the deployed uvicorn ran
without AI_WEB_STATIC_DIR because apps/web/out was never built — dev.ts
auto-wiring silently skips when the export is absent, and NOTHING detects
the mount-less boot. HAProxy was never the problem; the JSON 404 at / IS
the mount-less signature (pinned by test_web_static.py since v0.3.6).
Class fixes (the deploy experience, per founder directive):
- toolchain discovery (lib/toolchain.ts): node/pnpm behind nvm,
PNPM_HOME, or corepack are FOUND even when non-interactive shells
can't see them — the host had pnpm the whole time; doctor, bootstrap
and deploy all resolve through it (PATH → nvm → PNPM_HOME → corepack).
- nextcraft deploy: the one command the installer hands off to —
clone-or-update → pnpm install → venv → web export build → restart →
verify. Fails LOUDLY if the site isn't actually served. Idempotent:
same command for first install and upgrades. deploy --service installs
a generated systemd unit (real paths, Restart=always, enabled) so the
stack survives reboots; systemd becomes the supervisor (dev -d and
stop respect it).
- create_app(): a mount-less boot now WARNs naming the fix (G-11
doctrine — the failure was silent for three releases).
- verify: web-export presence check + LIVE MOUNT PROBE — when :8420 is
serving, GET / must return HTML, not the API's JSON 404. This is the
check that would have caught every prior outage.
- install.sh next-steps → `nextcraft deploy --service`; README +
deploy/README rewritten around the one-command flow.
478 backend tests (+1 loud-boot pin); CLI 59 (45→59: toolchain discovery
x7, deploy x4, verify probes x3, hermeticity fixes); web 14/14;
typecheck 8/8; ruff clean; static export builds.
---ci---
phase: hotfix
milestone: v0.5
status: complete
type: hotfix
---/ci---
P0-C1: mock identity ids were hash(learner, DOB)-deterministic — resubmit
after a TERMINAL verdict collided on the insert-only PK → unhandled 500,
permanently blocking re-verification (the D1 lockout one path deeper).
Ids now mint uniquely per submit (nonce + counter, PII-free); verdict
determinism preserved in poll(). Regression: resubmit-after-reject → 200
fresh pending → G-13 409.
P0-C2: defense audio answers 500'd on every default deployment — the mock
provider's empty transcript queue raised MockVoiceFailure (unhandled) the
first time a learner used the mic; same for a real endpoint outage.
transcribe() now maps provider RuntimeErrors to honest 502s (house
pattern); typed answers unaffected. Regression: unscripted mock → 502,
then typed answer → 200 on the same defense.
P0-C3: v0.5's variant_record columns brick a pre-v0.5 DB (create_all
never ALTERs) — every variant read/write raised OperationalError after an
in-place upgrade. Idempotent _ensure_v05_columns() backfill in the store
constructor (PRAGMA table_info → ALTER ADD COLUMN with defaults; legacy
rows read as build-kind). Regression: literal v0.4 table → open → read →
write → reopen idempotent. deploy/README documents the in-place note
(fresh-state directive still honored).
477 backend tests (+3); ruff clean; typecheck 8/8.
P1 flags recorded for pre-public hardening (non-blocking): unauthenticated
WS ingest on LAN (grading DoS), browser-mode SR/TTS client gap, defense-id
ms collision, browser-mode audio E2E.
---ci---
phase: 5
milestone: v0.5
status: review
---/ci---
P1: templates said 'python X' — the in-ns PATH resolves only python3 (no
bare python on the box); the declared harness would have failed with rc 127
in every real tracked sandbox. Templates + UI fallbacks now use python3
(caught by the new MH-4d real-server E2E, exactly as the verifier
predicted).
P2: the exec policy now unions the template's DECLARED harness argv[0]
into the allowed set (a future non-python harness template must not reject
its own Run command); 'python' removed from the generic set (deliberately
— in-ns resolves python3 only; pip absent: no network in the namespace).
MH-4c: web pins — test() derives from variant.test_command (whitespace
split, no shlex import); TaskVariant environment + test_command REQUIRED
(a-11); the build-surface header shows the kind (· build/design/
simulation) instead of the hardcoded '· build'.
MH-4d: test_design_kind_e2e_real_server — real uvicorn + real namespace:
design variant → starter files via the file API → in-ns harness exec
(python3 validate_flow.py; validator reports ISSUES on the starter flow —
by design, the learner edits it) → out-of-policy 422 → contiguous seq
chain stored (0..N, ordered, unique). G-17 satisfied: concrete
assertions, no hope-shaped must-haves.
474 backend tests (+1 E2E); web 14/14 (+2); CLI 45/45; typecheck 8/8;
export builds; ruff clean.
---ci---
phase: 4
milestone: v0.5
status: verify
requirements: {covered: [REQ-5-005, REQ-5-006], partial: []}
---/ci---
D1 (P1, security): malformed DOB previously reached derive_age_band on the
verify path → ValueError 500 whose traceback echoed the raw DOB into
uvicorn.error logs (A-305 violated) — and the poisoned pending record made
every resubmit 409: a REMOTE, PERMANENT lockout of any learner id (self-
asserted learner_id means anyone could poison anyone). Now: pydantic
boundary validation (422 before anything touches the value) + an app-level
RequestValidationError handler that redacts PII field inputs and strips
non-serializable ctx (keeps every other route's 422 shape JSON-safe).
Pinned: no 500, no echo in response OR logs, no poisoned record, resubmit
still 200.
D2 (P1, security): require_verified_age fail-OPENED on non-canonical bands
(None/'banana'/'under-16' passed the 18+ marketplace gate). Now fail-CLOSED:
only canonical bands pass; min_age>16 requires exactly '18+'. Pinned with
raw-SQL planted rows (the future-vendor/direct-write path).
D3 (P2): store now refuses non-canonical bands on insert AND mark_verified
(transitions validate like inserts). D4 (P3): latest_for_learner tiebreaks
by rowid (deterministic last-inserted-wins); dead school_gate/marketplace_
gate factories removed (require_verified_adult alias per D-043);
SubmitResponse mock comes from record provenance, not hardcoded. D5 (P3):
store docstring honesty (@validates claim corrected; read paths re-label tz
like the family). D6 (P3): .env.example documents AI_IDENTITY_*; the build
surface renders the verify-CTA LINK on identity-gate 403s (G-10 → hook
state.verifyCta), not just the message.
463 backend tests (+4: D1/D2/D3/D4 pins); web 12/12; typecheck 8/8;
export builds; ruff clean.
---ci---
phase: 3
milestone: v0.5
status: verify
requirements: {covered: [REQ-5-003, REQ-5-004], partial: []}
---/ci---
P0-1: recorder.start(1000) fires ondataavailable PER CHUNK; the handler
posted each 1s slice as a complete answer and killed the stream — every
voice answer truncated to ~1s (or split into two turns). Chunks now
buffer into chunksRef until onstop posts ONE complete blob; stop is the
single completion signal; the G-12 auto-stop bound is now reachable.
P0-2: jsonFetch forced Content-Type: application/json over FormData bytes
— every real audio answer died as 422 (provide {text} or audio). FormData
now sets its own multipart boundary; pinned by a header-assertion test.
P1-1: voice_tts_format as a pydantic Literal raised ValidationError at
Settings construction, BEFORE main.py's G-11 fallback could see it — a
typo'd env crashed the unattended boot (exit 1, verified). Now str +
mode-after validator: unknown values normalize to mp3 with a loud
warning (G-16 + G-11 consistency).
P1-2: timeout pin added (ReadTimeout is httpx.HTTPError — sanitized path).
P1-3: badge + auto-stop pins added (voice-badge.ts pure module:
voiceBadgeLabel truth table + MAX_RECORD_SECONDS=180).
P2s: non-dict 200 body context-wrapped; stale 'v0.4' docstrings/hints
corrected across base/browser/mock/defense (the MOCK_DESCRIPTOR hint test
now pins v0.5); hardcoded 180 in JSX uses the constant.
439 backend tests (+3); web 9/9; typecheck 8/8; ruff clean; export builds.
---ci---
phase: 2
milestone: v0.5
status: verify
requirements: {covered: [REQ-5-001, REQ-5-002], partial: []}
---/ci---
D-1 (P0/P1): _flush_locked no longer compacts the spool to [last_sent] —
that discarded sent-but-unacked lines before any ack could arrive, exactly
the in-flight window REQ-5-007 exists to close (a burst into a dying socket
lost lines 1..N-1). Post-fix the spool retains everything unacked;
replay_margin requeues the FULL unacked window on disconnect; trim_to_ack
(server seq_ack) is the only spool shrinker; server dedup absorbs replays.
Pinned by test_burst_into_ack_withholding_link_loses_nothing.
D-2 (P0): dropped-overflow docstring claimed 'status event + logs' — the
agent has no logging; corrected to the true surface.
D-3 (P2, latent): emit() held a non-reentrant _emit_lock across sends; a
send failure re-entered via _drop_conn -> replay_margin and hung the
emitting thread >8s in the verifier probe. Now an RLock.
422 backend tests green (421 + D-1 regression); mid-burst regression green
post-fix; ruff clean.
---ci---
phase: 1
milestone: v0.5
status: verify
requirements: {covered: [REQ-5-007], partial: []}
---/ci---
The public site (nextcraft.coreci.dev) 404s because HAProxy forwards the
domain to the ai-service alone and the web app was never reachable (only
:8420 is open). This makes ONE port serve BOTH surfaces:
- Web: `output: 'export'` static build (apps/web/out) with generateStaticParams
for all 7 dynamic routes; NEXT_PUBLIC_AI_SERVICE_URL=self bakes relative
same-origin fetches (engine-base-url "" base; engine-client already
concatenates). No CORS, no mixed content, no Node web server in prod.
- API: optional AI_WEB_STATIC_DIR StaticFiles(html=True) mount AFTER all
routers (API wins; / serves index.html; unknown paths serve the export's
404.html with status 404; set-but-missing dir fails startup loudly).
Default unset — dev/tests unchanged.
- CLI: `dev -d/--detach` (daemon; ~/.nextcraft/run/<clone-hash>/dev.{pid,log},
refuses double-start, auto-wires AI_WEB_STATIC_DIR when out/ exists),
`stop` (SIGTERM→SIGKILL 5s), `log` (-n N lines, -f follow). stdlib only.
Founder directives (this hotfix):
- unattended/daemonized dev with a tail command — dev -d / log / stop
- only 8420 reachable — single-port same-origin topology
- runtime state must NOT live in the repo — db_path default moves to
~/.nextcraft/data/nextcraft.db, sandbox_dir to ~/.nextcraft/sandboxes/;
expanduser validator (AI_DB_PATH=~/... works); .env.example stops pinning
repo paths; daemon pid/log also under ~/.nextcraft.
Test hygiene: conftest settings fixture pins stores to tmp_path (was silently
using repo defaults); sandbox tests use a bind-mount-safe sandbox_dir fixture
(overlayfs /tmp breaks userns bind mounts with ENODEV — home ext4 works).
Gates: typecheck 8/8; pnpm build emits out/ (all 73 pages static); web tests
5/5; cli tests green incl. real daemon lifecycle; backend 413 passed
(+4 static-mount tests); ruff clean.
---ci---
phase: hotfix
milestone: v0.4
status: complete
type: hotfix
---/ci---
---ci---
phase: 7
milestone: v0.3
status: audit
lessons:
- P0 reconstruction: tags v0.2.1/v0.2.2 pointed at the pre-migration first attempt (818d8c3/32af0fb) orphaned at the 2026-09-12 forge cutover — NOT ancestors of HEAD; re-pointed to the shipped phase commits (45b2162 / f0df185) matching the v0.2.3..v0.2.7 series convention; all v0.2.x tags now ancestors of HEAD
- P1 roadmap: phase 0 status stuck at in-progress after the P0 ship; phase 7 pending despite the P07 review commit; both corrected (complete / in-progress)
- P1 requirements: 27 v0.1 requirement rows (REQ-002..028) still said pending — contradicting the traceability matrix in the same file, PROJECT.md, and ROADMAP (v0.1 shipped as v0.1.0); all set complete
- P1 grill consistency: GRILL CUT-2 (no xterm in v0.3) never propagated to PERSONAS.md (frontend frameworks listed @xterm/xterm) and ARCHITECTURE.md build order (xterm.js build/run); PROJECT.md A-103 still claimed a WebSocket xterm terminal on a bwrap sandbox; all aligned to the shipped read-only exec-output panel (CUT-2/G-8, D-024 unshare)
- P1 architecture drift: api/ row missing the five v0.3 routers (sandboxes/telemetry/variants/defense + grade endpoint); voice/ row missing factory.py + defense_store.py; agents/ row missing examiner.py; main.py row missing engine-store lifespan wiring; ui/types rows missing the v0.3 primitives and engine type modules; data-flow section still described the v0.2 mock-agent flow as current
- P2 docstring: IngestSession still documented the pre-P7 len(get_trace) O(n²) flood-cap count that the P07 fix replaced with TraceStore.count()
---/ci---
---ci---
phase: 7
milestone: v0.3
status: review
lessons:
- P0 CORS: allow_methods lacked PUT while the build surface writes files with PUT — every cross-origin Save failed preflight; pinned with tests/api/test_cors.py
- P0 ingest leak: queue-overflow flood path returned without the disconnect sentinel, parking the drainer forever (one leaked task-set per flooded trace); sentinel now always enqueued, real-server regression test added
- P1 perf: flood cap counted rows via len(get_trace(...)) — O(trace) per append, O(n²) per session; TraceStore.count() (COUNT(*)) added and wired
- P0 security: file routes followed exec-planted symlinks out of the workspace bind; _resolve_in_workspace refuses escapes (422), read/write now 404 on unknown sandboxes (was 500)
- P1 security: WS ingest accepted any browser Origin (CORS middleware does not cover WS); localhost dev origins + no-Origin (capture agent) allowed, others 1008
- P1 correctness: use-sandbox-session leaked a created sandbox on any mid-start failure (per-learner cap 1 → all retries 429 forever); failed starts now destroy what they created
- P2 testing: reconnect-flush test killed mid-burst (nondeterministic under load, reproduced on pre-change code); now waits for server-side observation of the pre-kill burst — the underlying one-line replay-margin/ACK gap is documented for v0.4
- maintainability: grading-store/templates/grading.ts docstrings claimed grading is variant-blind (stale pre-P4 text) — updated; ARCHITECTURE.md referenced nonexistent voice/openai_audio.py; dead if TYPE_CHECKING: pass blocks removed
---/ci---
The defend page fabricated taskId = `task-${competencyId}`, but variant
task_ids are `task-<seed[:16]>` (D-029) — so in the real browser flow the
defense ran against an empty trace (no digest grounding) and Grade My Work
always returned UNGRADABLE_EMPTY_TRACE. The E2E test masked this by passing
the real task_id directly.
Fix: DefenseSession resolves the learner's stored variant by competency
via GET /v1/variants?learner_id (new listVariants client), defends + grades
under the variant's real task_id, and shows an honest empty state when no
build session exists for the competency yet.
---ci---
phase: 6
milestone: v0.3
status: verify
requirements:
covered: [REQ-3-008]
partial: []
lessons:
- A green E2E test can still mask a broken UI wiring when the test hand-picks
the join key the UI is supposed to derive; verify browser flows against the
ids the pages actually construct, not the engine contract alone.
---/ci---
coreci-nextcraft-po
CIAgent