# CharacterGarden — Iterative Implementation Plan (Updated) ## Planning Rules Work in small, reviewable steps. After each completed step: 1. Update thoughts.md 2. Record files changed 3. Record assumptions made 4. Record next step 5. Do not skip ahead unless the current step is complete Do not redesign the project without updating this plan. --- # Phase 0 — Completed Baseline Status: COMPLETE - Contracts are established under app/src/contracts/ - Deterministic truth engine is active - Rulebook-driven validation is active and editable - Core actions supported: inspect, move, open, take, introduce, describe, transfer - take createIfMissing path implemented with rulebook authorization - transfer action implemented with ownership/location checks - Turn orchestration moved behind turn manager seam - Interpreter contract and first interpreter module created - Docker container builds are passing for app and frontend ## Phase 0 Structural Cleanup (April 2026) — COMPLETE - Deleted turns/processTurn.ts (was a pointless shim over runTurnManager) - Deleted truthEngine.ts (was a thin wrapper over rulebookEngine.validateWithRulebook) - Extracted world/seedWorld.ts — seed world logic out of app.ts; app factory is now lean - Fixed db.listTurns() to return real actions and validation results (previously always empty arrays) - Fixed worldState.rulebookId persistence — active rulebook now survives restarts - Generalized has_ in applyActions — no longer hardcoded to key_1 only --- # Phase 1 — Intent Interpreter Boundary Hardening Status: IN PROGRESS ## Step 1.1 — Strict interpreter envelope validation Goal: - Validate InterpreterOutput shape before it reaches validation/mutation. - Reject malformed interpreter payloads deterministically. Target files: - app/src/contracts/intent.ts - app/src/interpreter/interpretTurn.ts - app/src/turns/turnManager.ts ## Step 1.2 — Clarification model expansion Goal: - Add structured clarification options and optional entity candidates. - Distinguish unrecognized-intent from reference ambiguity consistently. Target files: - app/src/contracts/intent.ts - app/src/interpreter/interpretTurn.ts ## Step 1.3 — API compatibility for unresolved turns Goal: - Ensure /api/turn returns interpreter status and clarification payload reliably. - Keep existing fields backward-compatible for current frontend behavior. Target files: - app/src/turns/processTurn.ts - app/src/index.ts --- # Phase 2 — Turn Trace and Persistence Enrichment Status: NOT STARTED ## Step 2.1 — Persist interpreter envelope per turn Goal: - Persist interpreter status, diagnostics, and clarification metadata. Target files: - app/src/db.ts - app/src/contracts/turn.ts - app/src/turns/turnManager.ts ## Step 2.2 — Extend read models and API snapshots Goal: - Include interpreter trace data in turn history returned by /api/state. Target files: - app/src/db.ts - app/src/app.ts - app/src/index.ts ## Step 2.3 — Frontend turn inspector updates Goal: - Display interpreter status and clarification prompts in timeline and latest result. Target files: - frontend/src/App.tsx --- # Phase 3 — Resolver Plug-in Architecture Status: COMPLETE ## Step 3.1 — Introduce resolver interface Goal: - Define a stable resolver interface that returns InterpreterOutput. Target files: - app/src/interpreter/resolveIntent.ts (new) - app/src/interpreter/interpretTurn.ts ## Step 3.2 — Deterministic adapter extraction Goal: - Move current parser-backed behavior into a deterministic adapter. Target files: - app/src/interpreter/adapters/deterministicResolver.ts (new) - app/src/interpreter/interpretTurn.ts ## Step 3.3 — LLM resolver adapter Goal: - Add LLM adapter behind config, without making it authoritative over deterministic validation. Target files: - app/src/interpreter/adapters/llmResolver.ts (new) - app/src/app.ts ## Step 3.4 — Fallback strategy Goal: - Support deterministic fallback when LLM resolver fails or is low confidence. Target files: - app/src/interpreter/interpretTurn.ts --- # Phase 4 — Rulebook Governance and Compatibility Status: IN PROGRESS ## Step 4.1 — Rulebook versioning Goal: - Add version field and migration path for existing saved rulebooks. Status: COMPLETE Target files: - app/src/contracts/rulebook.ts - app/src/defaultRulebook.ts - app/src/db.ts ## Step 4.2 — Policy pack structure Goal: - Organize rules into policy packs (creation, transfer, social) while retaining current behavior. Target files: - app/src/defaultRulebook.ts ## Step 4.3 — Rulebook editor affordances Goal: - Surface policy grouping and version in the frontend editor. Target files: - frontend/src/App.tsx --- # Phase 5 — Docker-First Test Harness Status: NOT STARTED ## Step 5.1 — Backend integration tests Goal: - Cover deterministic scenarios: - unauthorized createIfMissing denied - authorized createIfMissing allowed - transfer success and failure matrix - unresolved intent clarification behavior Target files: - app/src/** tests (new) ## Step 5.2 — Containerized test commands Goal: - Provide canonical Docker commands for app/frontend build and tests. Target files: - charactergarden/docker-compose.yml - project.md - thoughts.md ## Step 5.3 — CI readiness checklist Goal: - Ensure all checks are containerized and reproducible. Deliverable: - One documented command sequence that reproduces local validation. --- # Phase 6 — LLM Adapter Reintroduction Only after deterministic flow works. ## Step 6.1 — LLM parser adapter Add optional LLM parser: ```ts parseTextToActionsWithLLM(text: string, worldState: WorldState): Promise ``` It must output only valid `Action[]`. --- ## Step 6.2 — LLM narrative adapter Add: ```ts generateNarrative(turn: Turn, worldState: WorldState): Promise ``` The narrative adapter may describe results but must not alter them. --- # Phase 7 — Frontend Debug UI ## Step 7.1 — Show raw text input User can submit a turn. --- ## Step 7.2 — Show parsed actions Display action JSON. --- ## Step 7.3 — Show validation results Display success/failure reasons. --- ## Step 7.4 — Show world state Display current world state JSON. --- # MVP Completion Criteria MVP is complete when this works: 1. User enters: `take key` 2. Parser returns a `take` action 3. Truth engine validates it 4. World state moves key to inventory 5. User enters: `open door` 6. Truth engine verifies key ownership 7. Door becomes open 8. All steps are visible in debug UI 9. All turns are persisted --- # Do Not Do Yet Do not implement: * autonomous agents * complex memory retrieval * embeddings * relationship simulation * long-term summaries * branching timelines Until the deterministic MVP is working.