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