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.).
This commit is contained in:
@@ -39,6 +39,18 @@ The 3-entity cap is load-bearing: it makes the relationship graph fully enumerab
|
||||
- **Data layout**: everything under `<repo>/data/` — `chat.db`, `backups/`, `snapshots/`, `exports/`, `config.toml`. The whole tree is `.gitignore`d. `CHAT_DB_PATH` env var honored as override.
|
||||
- **Auth**: bind to `127.0.0.1` only in v1. No auth.
|
||||
|
||||
## Behavioral defaults (locked in v1 brainstorm round 2)
|
||||
|
||||
- **Significance scale**: 0=Routine, 1=Notable, 2=Significant, 3=Pivotal. Score-3 turns auto-pin per witness. Drives retrieval ranking, compression, JSON exports.
|
||||
- **Edge updates**: per-turn deltas (`affinity_delta`, `trust_delta`, `knowledge_facts`, `last_interaction`); per-scene-close summary rewrite. Every mutation goes through the event log as `edge_update`.
|
||||
- **Classifier failure handling**: Pydantic-constrained → 1 retry with stricter reminder → schema-default fallback. 10s timeout. Never block the play loop. Refusals trigger fallback-model swap for that one call. Failures logged to `classifier_failures` table.
|
||||
- **Activity verbs**: open string + classifier-extracted `interruptible`, `required_attention`, `expected_duration`. Attention is optional free-form; omit from prompt when empty.
|
||||
- **Containers**: parse-and-extend. Per-chat scoped. Kickoff parse seeds initial; transitions create new.
|
||||
- **Pinning**: soft cap 8 / bot. Pivotal (score 3) = auto-pin. Manual pins never auto-evicted.
|
||||
- **Snapshots**: periodic every 100 events / 30 min; pre-rewind always. 5 periodic retained; pre-rewind retained 14 days.
|
||||
- **Streaming**: Stop button on streaming row; mid-stream disconnect commits partial with `truncated: true`; Send disabled mid-stream; multi-tab streaming via per-chat SSE channel.
|
||||
- **Display**: lightweight markdown; `*action*` italic; OOC `((parens))` shown dimmed/italic, never sent to bot.
|
||||
|
||||
## Core concepts (vocabulary)
|
||||
|
||||
- **Entity**: `you | botA | botB`. Has identity (immutable), state (mood/goals/status), activity, per-POV memory.
|
||||
|
||||
Reference in New Issue
Block a user