a06f90a164
docs: add Phase 4.5 cleanup plan (all 24 backlog items)
...
16 tasks across 9 waves consolidating all 24 items in CLAUDE.md
Phase 4.5/5 backlog. Mix of:
- Wave 1 (parallel 6-way): trivial polish across 6 different files
- Wave 2 (single): schema migration 0014 (FK CASCADE + memories.event_id)
- Wave 3 (single): drawer bundle (event_id guard + html.escape + modal
partial + bulk significance re-rate)
- Wave 4 (single): search UX (FTS snippet highlight + deep-link)
- Wave 5 (single): real embedding model swap (LLMClient.embed protocol)
- Wave 6 (single): branching read-side filter (riskiest — cross-cutting)
- Wave 7 (single): regenerate lifecycle rollback
- Wave 8 (single): sqlite-vec swap [ENVIRONMENTAL — may defer to Phase 5
if Python rebuild / apsw not feasible]
- Wave 9 (parallel 3-way): structured fixture builder + integration tests + docs
Schema baseline 13 -> 14 (or 15 with T115). Big tasks (T112 real embed,
T113 branching filter, T114 lifecycle rollback) advance the engine
beyond Phase 4's metadata-only state. T115 environmental decision
captured in pre-flight; the other 13 tasks ship without it.
Uses task ids T103-T118 to avoid collision with prior phases.
2026-04-27 04:22:08 -04:00
b6119879e5
docs: phase 4 status, behavioral defaults, deferred items (T102)
2026-04-27 03:56:45 -04:00
bffd9a2f38
docs: add Phase 4 implementation plan (vector retrieval + branching + polish)
...
15 tasks across 8 waves landing the Phase 4 deliverables per
requirements doc §13 + §14:
- Vector retrieval via sqlite-vec (new external dependency)
- Branching UI (event log forks)
- Drawer-edit on every field (significance review, hide-from-view,
surgical delete with cascade preview, branching affordances)
- Backup tooling (snapshot UX surface)
- Cross-chat search
Plus the 3 Phase 3.6 carry-over fixes (T90 bundle).
Wave structure:
- W1 (parallel 3-way): schema foundation + carry-overs
- W2 (parallel 3-way): embedding/search services
- W3 (parallel 2-way): branching + delete services
- W4 (single): combined retrieval ranking
- W5 (single): memory write hook + backfill
- W6 (single): drawer Phase 4 bundle (5 sub-features)
- W7 (parallel 2-way): snapshot UX + cross-chat search UX
- W8 (parallel 2-way): integration tests + docs
External dependency: sqlite-vec must be installed BEFORE Wave 1.
Embedding model choice (384-dim default) pinned in T91 before dispatch
since the migration hardcodes the dimension.
Schema baseline: 11 -> 13 (adds 0012_embeddings.sql + 0013_branches.sql).
Task ids T88-T102 to avoid collision with prior phases.
2026-04-27 02:03:08 -04:00
fb7e97260b
docs: add Phase 3.5 cleanup plan (Phase 2.6/3 + 3.5/4 backlog burn-down)
...
12 tasks across 7 waves consolidating the 17-item backlog tracked in
CLAUDE.md (7 from Phase 2.6/3 + 10 from Phase 3.5/4). Items are
grouped by file ownership so each wave stays file-disjoint:
- Wave 1 (parallel 4-way): trivial single-line/single-file fixes
(timeout_s plumbing, Literal type, docstring, defensive None)
- Wave 2 (single): scene_summarize.py polish bundle (5 T58 items)
- Wave 3 (single): typed ChatNotFoundError for skip routes
- Wave 4 (single): turns.py wiring (consume_pending_meanwhile_digests
+ natural-language skip runs scene close detection)
- Wave 5 (single): regenerate.py polish (cancel hook + DRY +
sibling query + lifecycle rollback documentation + ordering)
- Wave 6 (parallel 3-way): unified record_turn_memory API + JSON
audit + frontend turn_html_replace SSE handler
- Wave 7 (single): docs sweep
No schema migrations. Bundled tasks split into per-item sub-commits
for clean review bisection. Uses task ids T76-T87 to avoid collision
with prior phases (Phase 3 used T49-T67, Phase 2.5 used T68-T75).
2026-04-26 21:33:16 -04:00
af6c54dd05
docs: phase 3 status, behavioral defaults, deferred items (T67)
2026-04-26 21:10:49 -04:00
e05f28e9d5
docs: add Phase 2.5 cleanup plan (Phase 1.5 + 2.5/3 backlog)
...
8 tasks across 5 waves consolidating the 15-item backlog tracked in
CLAUDE.md (5 from Phase 1.5 cleanup + 10 from Phase 2.5/3). Items are
grouped by file ownership so each wave stays file-disjoint:
- Wave 1 (parallel): open_db refactor, bot_reset orphan cleanup,
LLM-merged group meta-summary
- Wave 2 (single): prompt.py polish — witness role parametric, single
ACTIVITIES block, NICE trim documented
- Wave 3 (single): drawer polish — deferred v1 edits, first-meeting
gate, witness flag editing
- Wave 4 (parallel): regenerate.py polish (SSE + interjection
regenerate + stale-guest cleanup); turn-flow polish + new addressee
service (classifier addressee + significance for interjection +
scene-close-on-cancel pinned + stale-guest cleanup)
- Wave 5 (single): docs sweep
No schema migrations. Bundled tasks split into per-item sub-commits
for clean review bisection. Uses task ids T68-T75 to avoid collision
with Phase 3 plan (T49-T67) regardless of merge order.
2026-04-26 17:02:46 -04:00
379054755a
docs: add Phase 3 implementation plan with parallel-safe waves
...
19 tasks across 8 waves covering events with lifecycles, time skips
(elision + jump), active threads, significance/retrieval refinements,
and meanwhile scenes (host+guest with no 'you'). Mirrors the Phase 2
plan structure: pre-flight, parallel-execution strategy with worktree
isolation, file-disjointness analysis per wave, and per-task TDD spec
with commit messages.
Phase 3 schema: adds 0009_events.sql, 0010_threads.sql,
0011_meanwhile_scenes.sql (final version 11). Builds on Phase 2's
3-entity scene support and event-sourced architecture.
2026-04-26 16:55:50 -04:00
321810fa54
docs: phase 2 status, behavioral defaults, deferred items
2026-04-26 16:28:14 -04:00
b8335895e1
docs: add Phase 2 implementation plan with parallel-safe waves
...
13 tasks across 6 waves (1, 2, 3, 4a, 4b, 5). Designed for parallel
subagent execution where file-disjointness allows.
Waves 1, 2, 4a, and 5 each contain 2-3 tasks that touch disjoint files
and can be dispatched concurrently via the Agent tool with
isolation: "worktree". Waves 3 (drawer guest support) and 4b (multi-
entity turn flow) are single-task because they touch hot files
(_drawer.html, turns.py) that cannot be safely co-modified.
Plan covers:
- T36: group_node schema + handlers (new migration 0008)
- T37: guest_added / guest_removed event handlers (modifies world.py)
- T38: relationship-seed service ("have they met?")
- T39: interjection classifier service
- T40: multi-entity state-update coordinator (6 directed pairs)
- T41: multi-witness memory write helper
- T42: drawer guest add/remove UI + render
- T43: multi-entity prompt assembly (extends T18)
- T44: multi-entity turn flow (rewrites post_turn)
- T45: multi-entity per-POV summaries on scene close
- T46: witness filter cross-coverage tests
- T47: bot_reset cascades to guest references
- T48: Phase 2 documentation update
Plan also documents:
- Worktree-per-subagent dispatch pattern using Agent isolation flag
- Merge ordering per wave (file-disjointness = conflict-free merges)
- Failure recovery (cancel failed parallel task, re-dispatch as solo)
- Conflict prevention checklist (verify Files sections disjoint per wave)
Tasks file (.tasks.json) carries dependency DAG with `blockedBy` and
`parallelGroup` so a future executing-plans run can dispatch correctly.
NOT EXECUTING. Plan only.
2026-04-26 15:37:07 -04:00
7e6c2985dd
docs: fix Task 6 plan snippet: PRAGMA table_info name index is c[1] not c[0]
2026-04-26 11:48:30 -04:00
f0594c24d2
docs: add Phase 1 implementation plan with 36 TDD tasks
...
Bite-sized, TDD-driven plan covering all v1 deliverables from the
requirements doc §13. Each task has: file paths, failing test,
verify-fail step, minimal implementation, verify-pass step, and a
single commit.
Phases:
- 1A Foundation: project skeleton, config, migrations, LLM client, classifier
- 1B State machine: event log, projector, entities, edges, memory, world
- 1C Authoring: kickoff parser, bot form, settings, kickoff confirm
- 1D Chat (single bot): nav, chat shell, SSE, turn parse, prompt assembly,
narrative streaming
- 1E Per-turn updates: state-update, memory writes, significance, retrieval
- 1F Drawer & scenes: read-only drawer, drawer edits, scene close, per-POV
summary
- 1G Rollback: rewind w/ impact preview, regenerate, reset
- 1H Ops & polish: snapshots, backups, display, streaming UX, errors,
first-run
Companion tasks.json captures dependency DAG for resumable execution.
2026-04-26 11:19:33 -04:00
8a6b48be11
docs: flesh out behavioral specs in v1 requirements (round 2)
...
Resolves the deferred operational and UX semantics from round 2 of the
brainstorm. Decisions 22–43 in the appendix decisions log.
New / expanded sections:
- §3.3 Classifier failure handling (Pydantic-constrained + retry + schema-
default fallback, 10s timeout, refusal triggers fallback-model swap).
- §3.4 Edge update granularity (per-turn deltas + per-scene-close summary
rewrite; all mutations go through edge_update events).
- §4.3 Chat clock format (stored ISO 8601 UTC; displayed friendly relative).
- §5.1 Authoring expanded (voice samples format, trait list as free-form
phrases, backstory length target).
- §5.4 "You" entity authoring (one-time, shared).
- §6.4 Drawer expanded (v1 editable fields cut: activity, edges, memory;
read-only: container, identity, witness, structural; manual_edit events).
- §6.5 Activity record specifics (open verb + classifier-extracted props).
- §7.4 Container authoring (parse-and-extend, per-chat scoped).
- §7.5 Guest leaves mid-scene (auto close + new scene with you+host).
- §8.5 Pinning (soft cap 8, score-3 auto-pin, manual pins never auto-evict).
- §10 Rollback expanded with full impact-preview modal, snapshot frequency
(100 events / 30 min periodic, pre-rewind always), inline regenerate UX
with edit-then-regenerate.
- §11.1 Significance rubric (0=Routine, 1=Notable, 2=Significant,
3=Pivotal) with usage and tie-breakers.
- §16 UI Shape & Flow (top-level nav, first-run experience, display
formatting, streaming UX, error UX).
CLAUDE.md adds a "Behavioral defaults (round 2)" section flagging the
load-bearing rules for future Claude sessions.
§14 Open / Deferred Decisions trimmed to the genuinely-still-open list
(embedding model, vector index choice, prompt templates, search, etc.).
2026-04-26 11:11:46 -04:00
5869f1c5ce
docs: lock remaining v1 design decisions
...
Resolves the open/deferred decisions from the v1 requirements brainstorm:
runtime stack, classifier model, token budgets, OOC marker, data layout.
- Runtime: FastAPI + HTMX + SSE (multi-tab sync is a Phase 1 requirement,
not a polish item). 127.0.0.1 only, no auth in v1.
- Classifier model: NousResearch/Hermes-3-Llama-3.1-8B with documented
fallback chain (dolphin-2.9.4-llama3-8b, Meta-Llama-3.1-8B-abliterated).
- Token budgets: 8K hard / 6K soft for narrative, 4K hard for classifier;
Must/Should/Nice trimming tiers spelled out in §3.2.
- OOC marker locked to ((double parens)), configurable.
- All runtime data lives under <repo>/data/ (DB, backups, snapshots,
exports, config). Tree is gitignored. CHAT_DB_PATH env var honored.
CLAUDE.md and the requirements doc updated to match. Decisions log in
the requirements doc appendix extended with the new locks (#17–21).
2026-04-26 10:56:51 -04:00
2f94ba7291
docs: add v1 requirements design + project README
...
- docs/plans/2026-04-26-v1-requirements-design.md captures the v1
product requirements and behavioral spec from the initial brainstorm
(use case, scope, data model, authoring, play loop, memory, time,
rollback, phase cut, non-negotiable rules).
- README.md introduces the project for the gitea repo.
- CLAUDE.md updated to reference the requirements doc.
- .gitignore added for macOS metadata.
2026-04-26 10:46:03 -04:00
Joseph Doherty