CharacterGardenStack/Implementation_plan.md

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_<item_id> 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:

parseTextToActionsWithLLM(text: string, worldState: WorldState): Promise<Action[]>

It must output only valid Action[].

---

Step 6.2 — LLM narrative adapter

Add:

generateNarrative(turn: Turn, worldState: WorldState): Promise<string>

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.