project-lyra/docs/ROADMAP.md

# Lyra — Roadmap / To-Do

Living doc. Working priorities and open threads, organized by area. Not a spec —
specs live in `docs/` and `docs/superpowers/specs/`; this is the map of what's
done, what's next, and what's parked.

- **Last updated:** 2026-07-11
- **Frame (the load-bearing lens):** Lyra is the AI-with-tools (unchanged). The
  **pokerlog is its own separable system-of-record** — she's a *client* of it via
  tools, not its container. The logger must be correct/trustworthy first; Lyra's
  value (memory, recall, scouting, coaching) rides on top. Two kinds of memory,
  kept distinct: the **ledger** (facts: hands/villains/stats) vs the
  **relationship** (her memory of the sessions). See the `poker-copilot` memory +
  `docs/poker-logging-service` spec.

Status key: ✅ done · 🔨 in progress · ⬜ queued · ⏸ blocked/waiting · 💭 decision open

---

## Prompting (poker mode)

Spec: `docs/superpowers/specs/2026-07-01-poker-prompts-design.md`

- ✅ **Phase A — pipeline fixes.** Suppress the mode-menu note + the false-tilt
  mood nudge in poker_cash.
- ✅ **Phase B — classifier + fragments.** `lyra/poker_prompts.py`: pure
  `classify(msg, roster_handles)` (READ|HAND|TABLE|MENTAL|STATUS|LOG|CHAT), lean
  always-on `BASE`, per-type `FRAGMENTS`. Wired into `build_messages`; the
  ~100-line `_CASH_CARD` monolith is sharded out (`CASH.card=""`).
- ✅ **Deleted the dead `_CASH_CARD`** monolith (modes.py 256→161 lines).
- ✅ **Classifier hardening (round 1).** Fixed 6 real gaps found by probing
  live-style phrasings (-ing action forms, "the whale" bare descriptor, player
  departures→TABLE, "stack" leaking questions into LOG, thin MENTAL lexicon). 18
  unit tests. Still a heuristic + swappable seam — upgrade to an LLM/MI50
  classifier only if live misses justify it; keep tuning against real transcripts.
- ✅ **Phase C — MI50 tool-calling (LIVE 2026-07-06).** Added `--jinja` to the
  lyra-brain llama.cpp launch (`/opt/models/docker-compose.yml` in CT202, so it's
  reboot-resilient); Qwen2.5-32B confirmed emitting real `tool_calls`. Flipped
  `TOOL_BACKENDS=cloud,mi50` in `.env`. MI50 chat turns now get the same tool
  contract as cloud. (Untested in a real poker session on the mi50 backend — worth
  a live check that tool-calling holds up under the full poker prompt.)

## Persona (the "person" layer)

The persona core is always-on (~719 tok). Identity legitimately earns always-on
status, but there's fat.

- ⬜ **Streamline `How you talk`.** It's 439 tok (61% of the core) with loose
  prose. Keep the load-bearing rules (prose-not-listicle, give opinions, no
  reflexive sign-offs, own your moods) but tighten to ~250 tok. ~180 tok saved,
  zero substance lost. (Brian flagged 2026-07-05.)
- ⬜ **Broader persona review.** Take a full pass at `lyra/personas/lyra.md` — is
  each section earning its place, always-on vs situational split right, anything
  stale or redundant? (Brian flagged 2026-07-05.)
- ⬜ **Fix/demote the stale `Right now` section.** It asserts "stats tracking,
  player profiling… are coming" — both are SHIPPED. It's status prose that
  shouldn't be always-on and drifts stale. Demote from core → situational (loads
  only when she's asked what she can do), or fold into the tool-self-knowledge
  layer below. −74 tok/turn + stops asserting wrong status.

## Tool self-knowledge ("a person with strong tools")

She can *call* tools but doesn't *know*, as a person, what she can do — no standing
self-knowledge of her hands.

- ⬜ **Capability self-knowledge, generated from the tool registry.** A
  `tools.capability_summary()` rendering the live `TOOLS` dict into a grouped,
  first-person "here's what I can do" — self-maintaining, can't drift. Inject in
  the self/meta persona sections (occasional, NOT every turn — keeps the hot path
  lean).
- ⬜ **Grounding principle (level 2).** Lean always-on line: facts come from
  tools/memory, never confabulate, "let me check" is always allowed. Reinforces
  BASE's log-first rule; important under the system-of-record frame.
- ⬜ **Agency framing (level 3).** Tools are HERS — reached for because she wants
  to help, not an external API. Tone in the persona.
- Note: composes with the prompting work — capability self-knowledge = IDENTITY
  (occasional); BASE = operational routing (always-on poker). Don't duplicate the
  tool list across both registers.

## Pokerlog separation (architecture)

The domain is well-isolated (`lyra/poker.py`, one 2000-line pack) but still an
in-process module sharing `lyra.db` and reaching into `lyra.memory`/`llm`.

- 💭 **Decide how far to physically separate now** (Brian, not yet decided):
  - **A. Logical API boundary** — everything goes through a defined interface,
    still in `lyra.db`. Cheapest.
  - **B. Own datastore + package, same repo** (my rec) — own DB, no reach-back
    into Lyra; standalone-able without a second service to run. Biggest concrete
    change: poker tables currently live IN `lyra.db`.
  - **C. Full standalone MCP/HTTP service** — separate process, agent-agnostic
    (any harness could drive it). Purist end; most work.
- Origin of the frame: Lyra-as-poker-agent was contingent (ChatGPT couldn't call
  tools, Lyra could). The real need was "an agent that can drive my pokerlog" →
  the logger should be agent-agnostic. See `docs/poker-logging-service` spec.

## Poker logger (the ledger — features)

- 🔨 **Roster active/seen (two lists).** `session_players.active` already backs
  it; surface the seen side. `session_roster()` = active; add `session_seen()` =
  active=0; HUD shows 🪑 At the table + 👋 Seen tonight. Re-seating flips seen→
  active. Classifier's READ↔HAND match should check active + seen handles. (Brian's
  idea, 2026-07-05.)
- ⬜ **Human-editability sweep.** System-of-record must be fixable. Hand editor +
  disown ✅, `/players` browser + identity queue ✅. Audit for gaps (session-level
  edits, read edits, bulk fixes).
- ⬜ **Roster → hand seat/name resolution.** When a logged hand references a
  *position* (CO, BTN…) that maps to a seated roster player, fill in their name +
  link the observation — so "the CO 3-bet me" attaches to TAG without Brian naming
  him. The hard part: hand positions ROTATE every hand while the roster tracks
  fixed physical seats, so it needs seat-number + button-position tracking per hand
  to map position→person (a wrong guess mislabels a villain — worse than blank).
  Real feature, not a fill. (Brian's idea, 2026-07-11.) Pairs with the roster
  active/seen work above.
- Shipped this stretch: scouting desk (proactive recall + nameless-villain
  identity, all 6 phases), roster seat/unseat/clear, observed-hand fix + hand
  editor, villain-dup fix, conversation export (+ tool events), session-scoped
  notes, no-cache app-shell header. **2026-07-11:** guaranteed hand logging
  (force + tool-visible history), showdown reads via `analyze_spot` + de-mush,
  idempotent hand logging, any-seat straddle capture, hero-stack auto-fill from the
  stack log, and turn de-duplication (killed the SSE-stream + blocking-fallback
  double execution).

## Parked / longer-horizon

### Parked feature branches (real, half-built work — to explore later)

Both are pushed to origin (gitea), so they're safe to leave dormant. Not cruft —
resume when the moment's right; don't delete.

- ⏸ **`feat/hand-recorder`** — tap-to-build hand recorder V1 (`recorder.js/css`,
  `POST /hands`, straddle support, notch/safe-area fixes). 8 commits. Shelved
  because V1 was too tedious vs. narrating a hand in chat, so it was superseded by
  the chat-narration `record_hand` flow. Still want to revisit the *idea* (a fast
  structured recorder), just not that UI. See `docs/RECORDER.md` on the branch.
- ⏸ **`feat/decision-log`** — data layer for a **"Decide mode"** (a learning layer:
  log your decisions to learn from them). 1 commit, never merged; adds
  `docs/DECISION_LOG.md` + `tests/test_decisions.py`. A genuine future feature, not
  abandoned. See `docs/DECISION_LOG.md` on the branch.
- Retired 2026-07-10: `feat/thought-loop` (fully shipped — `lyra/thoughts.py` is
  live), `feat/prompting` + `feat/poker-mode-prompts` (renamed → `feat/poker`).

### Moonshots

- Moonshots live in `docs/PARKED_IDEAS.md` (own model, memory-as-vectors, prompt
  compression, RTO/cfr-core solver tooling).
- Metacognitive reflection loop (self-model Part 2) — queued self/experiment work.
- PLO/Omaha strategic analysis (equity engine) — non-goal for now; PLO hands are
  logged/replayed but not NLH-analyzed.