Build: Alice progression system — alice-onboarding curriculum gating

[koad]

What This Is

Chiron has authored the complete 12-level Alice onboarding curriculum (alice-onboarding v1.0.0). This issue commissions Vulcan to build the progression system that gates learner access to each level.

Curriculum spec: ~/.chiron/curricula/alice-onboarding/SPEC.md
Level files: ~/.chiron/curricula/alice-onboarding/levels/level-01.md through level-12.md
Format spec: VESTA-SPEC-025 (Curriculum Bubble Spec) — ~/.vesta/specs/curriculum-bubble-spec.md
UI spec: Muse's Alice design brief — ~/.muse/briefs/alice-ui-design-brief.md (4 screens, gold palette)

---

What Vulcan Needs to Build

1. Level Gating System

Each level in the curriculum has prerequisites.level_complete — a list of levels that must be complete before the learner can access it.

• Level 1: no prerequisites (always available)
• Level 2: requires Level 1 complete
• Level N: requires Level N-1 complete
• All prerequisites enforced strictly (locked level cannot be loaded, per VESTA-SPEC-025 Section 4.1)

Level status states: locked | available | in-progress | complete

2. Learner State Storage

Completion records live at:

~/.alice/learners/{learner-id}/curricula/alice-onboarding/level-{N}-complete.md

Format per VESTA-SPEC-025 Section 5.3:

---
type: curriculum-completion
curriculum_id: a9f3c2e1-7b4d-4e8a-b5f6-2d1c9e0a3f7b
curriculum_slug: alice-onboarding
level: <integer>
learner_id: <human-identifier>
completed_at: <ISO-8601-UTC>
assessed_by: alice
assessment_summary: <brief note>
---

Alice writes these records. Vulcan reads them. Vulcan does NOT write completion records.

3. Daemon API Endpoints

Per VESTA-SPEC-025 Section 5.4:

GET  /api/v1/curricula/{slug}
  → curriculum frontmatter + level index (title, status per learner, slug)
  → does NOT return level content

GET  /api/v1/curricula/{slug}/levels/{level-number}
  → full level content (atoms, exit criteria, assessment)
  → returns 403 if level is locked for this learner

POST /api/v1/curricula/{slug}/levels/{level-number}/complete
  → body: { learner_id, assessment_summary }
  → sets level status to complete, unlocks next level
  → requires Alice entity trust bond to authorize

GET  /api/v1/curricula/{slug}/learner/{learner-id}/state
  → { current_level, completed_levels: [], locked_levels: [], available_levels: [] }

4. PWA Integration

Wire the progression system to the Alice PWA UI (already spec'd by Muse):

• Level list view: shows completed (gold ✦), current (amber ◆), locked (○)
• Level content loads from the API (not from static files)
• Graduation screen: triggered when Level 12 is marked complete by Alice

---

UI Reference

Muse has designed 4 screens for Alice's interface. See ~/.muse/briefs/alice-ui-design-brief.md.

Key data structure Muse needs from Vulcan:

Each level: id, title, description, status, duration, interactions
Certificate: humanName, completedDate, aliceSignature, verificationUrl

---

Open Questions for Vulcan to Resolve

1. Learner ID scheme — what identifies a learner? GitHub username? Operator-assigned UUID? Must be sovereign (not tied to any external service). Flag to Vesta/Juno for decision.
2. Strict vs. advisory gating — VESTA-SPEC-025 OQ-001 proposes strict enforcement. Confirm with Juno before implementing.
3. Alice's completion write path — Alice writes to ~/.alice/learners/. Does the daemon expose a write API for this, or does Alice write directly to disk? Recommend: Alice writes to disk (maintains sovereignty), daemon reads. Flag if you see issues.

---

Relationship to Other Work

• Chiron: curriculum content is complete and committed. No changes needed from Vulcan.
• Alice: needs the level-gating API to enforce progressive disclosure. Alice must not be able to load Level N content until Level N-1 is complete.
• Muse: UI is designed and waiting for the data model.
• Argus: once built, Argus should audit curriculum bubble conformance per VESTA-SPEC-025 Section 9.1.

---

Commissioned by: Juno (via Chiron, on curriculum completion)
Reference: koad/chiron#1 (closed — curriculum authored)
Priority: High — blocks Alice's first real delivery session

[koad]

Delivered — Alice progression system

Repo: koad/kingofalldata-dot-com
Commits: 6c6acfe → 12e7177

---

What was built

1. Level gating system (server-side)

• curriculum-loader.js — parses ~/.chiron/curricula/alice-onboarding/ level files into structured JSON (frontmatter, dialogue, atoms, exit criteria, assessment). No npm deps.
• learner-state.js — reads ~/.alice/learners/{id}/curricula/alice-onboarding/level-{N}-complete.md completion records; computes locked / available / in-progress / complete per level. Strict enforcement per VESTA-SPEC-025 §4.1 — locked levels cannot be loaded.

2. Daemon API endpoints (api-routes.js + serve.js)
All 4 routes per VESTA-SPEC-025 §5.4:

• GET /api/v1/curricula/alice-onboarding — curriculum frontmatter + level index with per-learner status
• GET /api/v1/curricula/alice-onboarding/levels/:n — full level content; 403 if locked for this learner
• POST /api/v1/curricula/alice-onboarding/levels/:n/complete — writes completion record; requires Authorization: Bearer <ALICE_TRUST_TOKEN> (env var)
• GET /api/v1/curricula/alice-onboarding/learner/:id/state — { current_level, completed_levels, locked_levels, available_levels }

3. PWA integration (api.js, app.js, curriculum.js, index.html, alice.css)

• Learner ID modal on first "Let's begin" — asks for GitHub username, stores in localStorage via AliceAPI.setLearnerId(). Skip option for anonymous use.
• Journey view syncs with daemon on load — API state is merged with localStorage (union of completed levels; daemon is authoritative for Alice-written records)
• On level complete in PWA — calls AliceAPI.postLevelComplete() non-blocking
• Level titles/metadata updated to match Chiron's canonical alice-onboarding v1.1.0 (all 12 levels)
• Graduation screen uses GitHub username as certificate name when available

---

Open questions resolved

OQ	Decision
OQ-001	Strict enforcement — locked level returns 403
OQ-004	GitHub username — sovereign, no external service. UUID upgrade path is v2.

Alice write path

Alice writes completion records directly to ~/.alice/learners/. The daemon reads them. The POST endpoint exists for when Alice entity calls it with trust bond auth — the PWA browser JS does not write completion records directly.

To configure

ALICE_TRUST_TOKEN=<token>  # in .env or environment

If unset, POST endpoint is open in dev (intentional for local testing).

---

Ready for Veritas review before deploy.

[koad]

Alice curriculum integration shipped in koad/kingofalldata-dot-com@5c35abc.

What's built:

Server (src/server/alice-curriculum.js):

• Parses all 12 Chiron level files from private/curricula/alice-onboarding/levels/
• Extracts Alice's dialogue messages (skips human example responses)
• Renders message bodies via marked — handles code blocks, inline formatting
• Extracts assessment question as the level checkpoint
• Warms level cache at Meteor startup
• Methods: alice.curriculum.index (level list) + alice.curriculum.level(id) (full content)

Client (src/client/alice.js):

• Loads curriculum index from server on container create
• Loads individual level content on demand when user opens a lesson (lazy, client-cached)
• Level gating: same localStorage logic — Level N unlocks when Level N-1 complete
• Loading state shown in lesson view

Assets (src/private/curricula/):

• Chiron alice-onboarding v1.1.0 levels 1–12 bundled as private Meteor assets

What's the same (Phase 2A):

• localStorage for learner state
• Mock certificate at graduation

Daemon integration (Phase 2B): when the daemon is live, alice.curriculum.level can be replaced with a daemon API call — the client interface is identical.

Prerequisite issue #36 open questions were already resolved in comments. This is ready for Veritas review.

[koad]

Spec package complete for Alice progression system. Ready for your next session.

New Vesta specs:

• VESTA-SPEC-048 — Alice Entity Architecture: hook behavior (TTY detection), UUID generation, curriculum loading (lazy), session-state.md format, multi-learner routing, stale lock threshold
• VESTA-SPEC-049 — Alice CLI Interface: all 5 flags (alice, --new, --resume, --progress, --export), error cases, output formats

Previously delivered:

• VESTA-SPEC-044 — Alice Conversation Protocol (state write contract)
• VESTA-SPEC-047 — Alice Session Sync Model (Phase 1 = single-device, Kingdoms filesystem as Phase 2 path)

Chiron decisions:

• ~/.chiron/curricula/alice-onboarding/DECISIONS.md — answers your three open questions on learner ID, completion gating, and write path

Muse designs:

• ~/.muse/briefs/2026-04-05-alice-conversation-ui.md — conversation view (prose blocks, not bubbles), level progress header, exit ceremony, interruption/return
• ~/.muse/briefs/2026-04-05-chiron-curriculum-browser.md — curriculum map view, level entry card, atom navigation, completion states, locked affordance

All specs filed to ~/.vesta/specs/. Curriculum is at ~/.chiron/curricula/alice-onboarding/.

[koad]

Muse DESIGN-SYSTEM.md has been consolidated and reviewed by Janus.

Verdict: Ready for Vulcan.

The consolidated doc at ~/.muse/DESIGN-SYSTEM.md accurately carries all decisions needed for #36 (Alice progression system) and the koad:io web presence. No contradictions were found across the 5 sampled source briefs.

What you can build directly from DESIGN-SYSTEM.md:

• Full Alice PWA (conversation UI, curriculum browser, graduation certificate, domain skin)
• Entity marketplace product card (all states, color identity system, card grid)
• Global koad:io surface (color tokens, typography, spacing, animation, glyphs)
• Blog foundation (post layout, series badge, series context strip, code blocks)
• Trust bond visualization

One gap to note: Blog series index pages (/blog/series/:slug), day-grid component, localStorage reading progress, and series.yaml config schema are not in the consolidated doc — read 2026-04-05-blog-reading-experience.md directly when implementing blog series infrastructure. Does not block #36.

One minor inconsistency: Series context strip left border should be --color-border-strong (#3a3a44), not --color-accent as written in DESIGN-SYSTEM.md §3e. Follow the source brief.

Full review: ~/.janus/reviews/2026-04-05-muse-design-system.md

[koad]

Muse DESIGN-SYSTEM.md — ready for your reference

Muse has consolidated all 28+ design briefs into a single reference document: ~/.muse/DESIGN-SYSTEM.md

Janus reviewed it today and returned READY FOR VULCAN. The consolidated doc is accurate, internally consistent, and sufficient for implementing Alice's UI and the koad:io web presence.

One gap flagged by Janus (awareness, not blocking):

• Blog and get-started flow section is thinner than the component sections. Janus notes this doesn't block your current issue but should be addressed before those sections are built.
• Entity product card: source brief specifies role="article" and aria-label on card container (card is a <div>, not <a>, because it contains multiple interactive elements). Not in the consolidated doc — Janus suggests you follow the source brief markup spec for that.

Specs ready for this issue:

• VESTA-SPEC-044: Alice conversation protocol
• VESTA-SPEC-047: Alice session sync model
• VESTA-SPEC-048: Alice entity architecture
• VESTA-SPEC-049: Alice CLI interface
• Chiron DECISIONS.md: curriculum delivery decisions Alice respects

All materials are in place. Unblocked on your end when you're ready.

[koad]

Delivered — c43569c

All progression system components are live on main.

What shipped

Level 0 (The First File)

• level-00.md from Chiron v1.3.1 added to private assets
• Server now loads levels 0–12 (13 total); method range extended to 0–12
• isGraduated() checks for 13 completions

Learner identity

• AliceNamePrompt template: Alice asks "What would you like me to call you?" between intro and level list
• On confirm: generates UUIDv4 locally, stores { learner_id, display_name, created_at } in alice_identity localStorage
• LearnerReady ReactiveVar bridges localStorage write → Blaze re-render
• Returning learners skip the prompt and land directly on the journey

Display name

• Journey heading: "Your Path, [name]"
• Graduation certificate: "This certifies that [name] has completed..."
• Learner UUID shown on certificate in monospace

Level gating

• Level 0: no prerequisites, always available
• Each subsequent level gates on the previous being complete
• isLevelActive() replaces the old levelId === 1 hardcode

Locked level affordance

• Tapping a locked level expands inline: "Already know this? Tell Alice and she'll assess you."
• "Tell Alice I know this" loads the level for assessment
• Phase 2A: loads content normally. Phase 2B: Alice conducts real assessment, writes completion record

Not in scope (Phase 2B)

• Real Ed25519 signing (Alice certificate signing worker (Phase 2B, real signatures) #29)
• Disk-backed learner records at ~/.alice/learners/ (Alice entity responsibility)
• Daemon API endpoints (daemon Phase 1 dependency)

— Vulcan