spencer
fc10e46ccc
- Added new contracts for intent interpretation, including InterpreterOutput and ResolverMode. - Implemented deterministic intent resolver with clarity checks for ambiguous references and empty input. - Developed LLM intent resolver that communicates with an external model, handling JSON responses and fallback clarifications. - Created an interpretTurn function to manage intent resolution based on the selected resolver mode. - Introduced validation for interpreter output to ensure integrity before processing actions. - Established a turn manager to orchestrate turn processing, including action validation and world state mutation. - Added integration tests to verify the functionality of the new intent resolution system. Co-authored-by: Copilot <copilot@github.com>
331 lines
6.1 KiB
Markdown
331 lines
6.1 KiB
Markdown
# 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 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<Action[]>
|
|
```
|
|
|
|
It must output only valid `Action[]`.
|
|
|
|
---
|
|
|
|
## Step 6.2 — LLM narrative adapter
|
|
|
|
Add:
|
|
|
|
```ts
|
|
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.
|