Alice: extend signal protocol beyond <<LEVEL_COMPLETE>> to arbitrary session state updates

[koad]

Context

Project: `/.forge/websites/kingofalldata.com` (note: PRIMER.md still says `/.kingdom/websites/...` — stale path, please update PRIMER while you're in there)

Alice currently has exactly one signal she can send from her LLM output back to the browser: `<<LEVEL_COMPLETE>>`. It's handled in `src/client/alice.js` around line 418 — detected, stripped from the rendered message, and triggers the level-complete UI.

koad wants to generalize this. Alice should be able to emit arbitrary session state updates mid-conversation, not just level-complete. Example use case:

Alice asks the student "do you have a computer, and if so what OS?" Student answers "Windows." Alice now knows something worth remembering for the rest of the session, and should be able to emit a signal like `session.set('student', {os: 'windows'})`.

Requirements

1. Signal format — design a simple inline signal Alice can emit in her response that gets parsed out and stripped before the message renders to the user. Suggest something like `<<SESSION_SET student {"os":"windows"}>>` or `<>` — pick whatever is easiest for the LLM to emit reliably and easiest to parse robustly. Must survive streaming SSE (signals may arrive in chunks — buffer until complete).

2. Merge, don't overwrite — this is the critical semantic. If `session.get('student')` is already `{name: 'Dave', level: 3}`, then `session.set('student', {os: 'windows'})` must result in `{name: 'Dave', level: 3, os: 'windows'}`. Deep merge preferred for nested objects. Never clobber.

3. Keep `<<LEVEL_COMPLETE>>` working — either re-express it inside the new signal scheme or keep it as a special case alongside. Don't break existing level progression.

4. Persistence — session state should live alongside existing chat persistence (localStorage today, eventually namespace profile). Student data collected this way is part of the content bubble that will be transferred on koad:io install. Treat it as permanent-until-user-clears.

5. Curriculum side — Alice's system prompt / curriculum instructions in `src/server/alice-curriculum.js` need to teach her when to emit these signals. Don't make her emit state for every message — only when she learns something worth remembering (OS, hardware, prior experience, name, goal, commitments, GTD readiness, etc.).

6. Debuggability — log signals to console on client when parsed, so we can watch Alice actually using them during development.

Out of scope (do not do in this pass)

• Server-side persistence to MongoDB — keep it localStorage for now, same as chat
• Exposing session state back into Alice's prompt context — that's a follow-up (she'll want to read what she knows about the student, but let's land the write path first)
• Namespace profile integration — still blocked on kingofalldata.com: namespace routing — blocked on DNS, SSL, Sponsors API token #53

Deliverables

• Signal parser in `src/client/alice.js` (or a sibling module if it gets big)
• `Session` helper with `get` / `set` (merge) / `clear` / `dump` — pick a clean name, session is already a loaded word in Meteor so maybe `StudentState` or `AliceMemory`
• Curriculum update in `src/server/alice-curriculum.js` teaching Alice the signal vocabulary
• PRIMER.md path fix (`/.kingdom` → `/.forge`)
• Short note in the issue comment describing the final signal format you chose and why

Context on why this matters

This is the groundwork for the "content bubble" — everything Alice learns about the student in the browser eventually transfers to their sovereign entity dir on koad:io install. The more Alice can remember during the course, the richer the handoff. Signals are how Alice writes to that bubble.

Assigning: Vulcan

[koad]

Shipped locally (commit dffc1f8, not pushed — matches the repo's current unpushed backlog).

Signal format

<<SET key {"json":"value"}>>

Examples:
<<SET student {"os":"windows"}>>
<<SET student {"experience":{"terminal":"never"}}>>
<<SET student {"goal":"organise research notes"}>>

Why this shape

• Matches the existing <<...>> sigil from <<LEVEL_COMPLETE>> — one protocol, two flavours.
• SET key JSON is trivial for the LLM to emit reliably (verified against the usual Grok failure modes: it won't accidentally break it with prose inside the braces because the parser validates with JSON.parse, not brace counting).
• Space-delimited key is cleaner than dot paths or URL-style args, and the parser regex is boring: /<<SET\s+([\w.-]+)\s+(\{[\s\S]*?\})>>/.
• <<LEVEL_COMPLETE>> is kept alive as a legacy shorthand; internally it now writes progress.levelComplete=true into the same store, so there's one code path for progression.

Merge semantics

AliceMemory.set('student', {os: 'windows'}) on top of {name: 'Dave', level: 3} yields {name: 'Dave', level: 3, os: 'windows'}. Nested plain objects deep-merge; arrays and scalars replace. Never clobbers. Walked through this mentally with the exact case from the brief.

Streaming

New createStreamBuffer() in alice-memory.js holds back any trailing << until the signal closes, so a signal split across SSE chunks (e.g. <<SET stu / dent {"os":"mac"} / >>) parses cleanly and never briefly flashes to the DOM mid-stream. Belt-and-braces: parseAndStrip() runs again on the full final text when the stream ends.

Files touched

• src/client/alice-memory.js — new helper module (get/set/clear/dump, parseAndStrip, createStreamBuffer). Exposed on window.AliceMemory for dev-console poking. Logs every parsed signal.
• src/client/alice.js — imports AliceMemory, routes chunks through the stream buffer, resolves level-complete via progress.levelComplete, seeds student.name into memory when identity is set.
• src/server/alice-curriculum.js — owns SIGNAL_VOCABULARY and exposes it via alice.curriculum.signalVocabulary Meteor method. Client fetches once per page load and prepends it to the first user message of each lesson.
• PRIMER.md — ~/.kingdom → ~/.forge.

Scope notes (unchanged)

• localStorage only (key alice_memory_v1). No MongoDB.
• Write-path only — Alice doesn't read back what she already knows this pass.
• No namespace routing changes (still blocked on kingofalldata.com: namespace routing — blocked on DNS, SSL, Sponsors API token #53).
• Left the unstaged OS-selector work in logic.js/styles.css/templates.html alone — not mine, not touching it.

Vulcan.