kaykayyali/lore-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(plan): 9 slices with acceptance criteria + test plans

Browse Source 
Slices the Lore Engine on Cognee roadmap into independently
shippable units. Each slice file has Goal, What's in the slice,
Acceptance criteria (table), Test plan (unit + integration +
adversarial where relevant), Risks, Out of scope, Cross-references.

- 00-slice-0-poc.md: POC slice (done) — substrate validation
- 01-slice-structured-yaml.md: family_tree / timeline / gazetteer
- 02-slice-consistency.md: 4-category rule system
- 03-slice-llm-extraction.md: custom extraction prompt for the 36
  typed labels
- 04-slice-tools.md: remaining 44 tools to complete the 45-tool
  surface
- 05-slice-typetemplate.md: polymorphic extension model
- 06-slice-planes.md: Setting + Plane graph nodes (v1.2)
- 07-slice-harness.md: 50-question validation gate
- 08-slice-polish.md: UI, export, enforcement

README.md indexes the slices with a dependency graph and a
cumulative effort estimate (MVP at end of slice 2, ~10 days;
full v1 at end of slice 4, ~21 days; v1+ext at end of slice 7,
~33 days).

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Kaysser Kayyali
2026-06-17 09:43:32 -04:00
parent 7d2ab8699f
commit e0085e4c61
10 changed files with 1286 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
docs/plan/00-slice-0-poc.md Normal file
View File

@@ -0,0 +1,123 @@
# Slice 0 — Time-Aware Query POC
**Status:** ✅ DONE. Lives at `~/projects/lore-engine-poc/`. Substrate
decision validated, one tool implemented end-to-end on the user's own
codex.
## Goal
Stand up Cognee locally, build the smallest possible end-to-end demo
that exercises the load-bearing primitives: typed ontology ingest,
time-bounded edges, the `was_true_at` query, source attribution.
## What's in the slice
1. Cognee running locally (Kuzu backend, no Neo4j install needed).
2. Codex parser: Obsidian-style markdown → typed triples, no LLM.
3. `time_in_window(at, valid_from, valid_until)` — pure-Python port
of the UDF spec in `02-time-model.md`.
4. `was_true_at(relation, subject, object, at_time)` on the
in-memory graph.
5. Cognee integration in `01_ingest.py` (best-effort; skips cleanly
without an LLM key).
6. README + run scripts + reset script.
## Acceptance criteria
| # | Criterion | Status |
|---|---|---|
| 0.1 | `pip install cognee` succeeds on a clean Python 3.10 | ✅ |
| 0.2 | `python3 scripts/01_ingest.py --skip-cognee` parses the codex | ✅ 159 entities, 81 unique triples |
| 0.3 | `time_model.py` self-tests all pass | ✅ 13/13 |
| 0.4 | `was_true_at(MEMBER_OF, "Roland Raventhorne", "House Raventhorne", "3rd_age.year_345")` → `was_true: true` | ✅ |
| 0.5 | `was_true_at(SIBLING_OF, "Roland Raventhorne", "Aldric Raventhorne", "3rd_age.year_345")` → `was_true: true` | ✅ (heuristic from wikilinks) |
| 0.6 | `was_true_at(PART_OF, "Voldramir", "Underdark", "3rd_age.year_345")` → `was_true: true, confidence: 0.6` | ✅ |
| 0.7 | `was_true_at(ALLIED_WITH, "House Raventhorne", "House Quche", "3rd_age.year_345")` → `was_true: false` | ✅ |
| 0.8 | Every positive result has a non-empty `sources[]` pointing to a real file | ✅ |
| 0.9 | Cognee import works, `cognee.cognify()` reaches the LLM-call step | ✅ (fails on missing key, gracefully) |
| 0.10 | `scripts/03_reset.py` wipes the in-memory cache and (best-effort) the Cognee dataset | ✅ |
## Test plan
### Unit
```bash
cd ~/projects/lore-engine-poc
python3 lore_engine_poc/time_model.py
# expected: 13/13 passed
```
Cases covered by `time_model.py` self-tests:
- year inside year window
- year at exclusive upper bound
- year at inclusive lower bound
- era ancestor of lower bound
- `at` is descendant of lower bound
- sub-era window (e.g. `3rd_age.age_of_iron.year_3` inside
`3rd_age.age_of_iron.year_1` to `...year_5`)
- sub-era past upper bound
- open `at` with bounded window
- open lower bound
- open upper bound
- `current` token inside window (resolved against `current_time`)
- `current` token outside window
- different era at query time
### Integration
```bash
python3 scripts/01_ingest.py --skip-cognee
python3 scripts/02_demo.py
```
Inspect the JSON output for each of the 7 sample queries. Each must:
1. Return a parseable JSON object with the documented fields.
2. For positive `was_true`: include `valid_from`, `valid_until`,
`sources[]` (≥1 entry), `confidence` (>0), `edges_examined` (≥1).
3. For negative `was_true`: include `confidence: 0`, `edges_examined`
showing how many edges were inspected.
### Negative case (specifically)
```bash
python3 scripts/02_demo.py --query "ALLIED_WITH,House Raventhorne,House Quche,3rd_age.year_345"
```
Expected: `was_true: false`, `confidence: 0.0`, `edges_examined: 0`.
This proves `was_true_at` returns `false` cleanly when no edge exists
between the named entities.
### Reverse-direction case
The tool checks both `(subject→object)` and `(object→subject)` for
the requested relation. Verify with:
```bash
python3 scripts/02_demo.py --query "SIBLING_OF,Aldric Raventhorne,Roland Raventhorne,3rd_age.year_345"
```
Expected: `was_true: true` even though the triple was originally
extracted from Roland's body as `Roland SIBLING_OF Aldric`.
## What's deferred
- All 44 other MCP tools.
- The 4-category consistency engine.
- The TypeTemplate polymorphic extension.
- The plane model.
- The MCP server wiring (`cognee-mcp`).
- A real LLM client integration.
- Temporal edges (all current edges have
`valid_from = valid_until = null`).
## Risks surfaced
1. **S1.3 — entity resolution at scale.** The structured path is
exact up to ~10K entities; the LLM path is the bottleneck. Not
exercised here.
2. **S2.4 — 45-tool ceiling.** Not exercised; this slice has 1 tool.
3. **Sibling heuristic over-flagging.** A wikilink between two NPCs
is treated as `SIBLING_OF` unless spouse/parent hints appear
nearby. This will be replaced by `family_tree.yaml` in slice 1.

140
docs/plan/01-slice-structured-yaml.md Normal file
View File

@@ -0,0 +1,140 @@
# Slice 1 — Structured YAML Ingest
**Status:** 📋 planned. The slice that makes `was_true_at` actually
have something to filter against (real `valid_from` / `valid_until`
edges).
## Goal
Implement the canonical YAML formats from `docs/06-ingestion.md`:
- `family_tree.yaml` — lineage with `PARENT_OF`, `SPOUSE_OF`,
`MEMBER_OF(Lineage)` edges, each with `valid_from` and
`valid_until` derived from member lifespans.
- `timeline.yaml` — era hierarchy and named events with
`OCCURRED_DURING`, `PARTICIPATED_IN`, `OCCURRED_AT` edges.
- `gazetteer.yaml` — locations and regions with `PART_OF`,
`CULTURE_OF` edges.
- `bestiary.yaml` — creatures with `DEFEATED` edges and
`first_appeared` times.
- `magic_system.yaml` — systems and spells with `PRACTICES` edges.
- `culture.yaml` — cultures, languages, deities with `WORSHIPS`,
`SPEAKS` edges.
The structured path is **exact** — no LLM, no embeddings, no
fuzziness. Every edge traces to a YAML line.
## What's in the slice
1. `lore_engine_poc/parsers/family_tree.py` — emits `PARENT_OF`
with `valid_from = child.born`, `valid_until = parent.died`.
`SPOUSE_OF` with `valid_from = max(spouse1.born, spouse2.born)`
and `valid_until = min(spouse1.died, spouse2.died)`. Runs
anachronism check on every member.
2. `lore_engine_poc/parsers/timeline.py` — emits `Era` nodes with
`CONTAINS` parent-child edges, `Event` nodes with `OCCURRED_AT`,
`OCCURRED_DURING`, `PARTICIPATED_IN`.
3. `lore_engine_poc/parsers/gazetteer.py` — `Location` and `Region`
with `PART_OF` edges, `CULTURE_OF` edges, named events as
`OCCURRED_AT` edges.
4. `lore_engine_poc/parsers/bestiary.py` — `Creature` with
`DEFEATED` edges and `first_appeared` time.
5. `lore_engine_poc/parsers/magic_system.py` — `MagicSystem`,
`Spell` with `PRACTICES` edges.
6. `lore_engine_poc/parsers/culture.py` — `Culture`, `Language`,
`Deity` with `WORSHIPS` and `SPEAKS` edges.
7. Schema validation: strict, fails loudly with line numbers (YAML
"gotchas" — `NO: false` parsing as `True`, tab/space sensitivity).
8. `time_model.py` test suite grows: era-tree membership, month/day
precision, `current` token resolution against `:Now` config node,
null bounds semantics.
## Acceptance criteria
| # | Criterion |
|---|---|
| 1.1 | All six YAML formats parse and write to the in-memory graph |
| 1.2 | Every edge has `valid_from` and `valid_until` derived from YAML, not null |
| 1.3 | `time_model.py` test suite ≥30 cases, all pass |
| 1.4 | `was_true_at` queries with time-windowed edges return correct `valid_from`/`valid_until` |
| 1.5 | Schema validation rejects malformed YAML with line numbers |
| 1.6 | Anachronism check flags a parent whose death precedes a child's birth |
| 1.7 | Re-ingest is idempotent (`MERGE`, not `CREATE`) |
| 1.8 | Three example YAMLs ship in `seed/` for demo |
## Test plan
### Unit
```bash
python3 -m pytest lore_engine_poc/tests/test_time_model.py -v
python3 -m pytest lore_engine_poc/tests/test_parsers/ -v
```
`time_model.py` cases to add (target ≥30 total):
- Era-tree membership with `CONTAINS` traversal
- Month/day precision: `3rd_age.year_345.month_3.day_17`
- Era boundaries: `3rd_age.age_of_iron.year_1` at the start of an era
- `current` token resolved against `:Now` config node
- `current` token when `:Now` is missing → `ValueError`
- Half-open vs closed window semantics (consistent half-open)
- Sub-era boundary crossing (year in era A vs era B)
- Era ancestor of upper bound (`at` is inside a capped era → false)
- Era ancestor of lower bound (`at` is coarser → true)
- Null lower bound with non-null upper bound
- Non-null lower bound with null upper bound
- Both bounds null → only `at=None` should return true (rare)
- Lexical/numeric compare tiebreakers
- Wrong-format strings → `ValueError` or `False`
### Parser tests
```bash
python3 -m pytest lore_engine_poc/tests/test_family_tree.py -v
python3 -m pytest lore_engine_poc/tests/test_timeline.py -v
# … one per YAML format
```
Each parser test:
1. Valid YAML → expected edge list (count and shape).
2. Malformed YAML → exception with line number.
3. Re-ingest same YAML → same edge count (idempotency).
4. Anachronistic YAML (parent dies before child born) → flagged.
5. Cross-entity references that don't resolve → exception.
### Integration
```bash
python3 scripts/01_ingest.py --codex lore_engine_poc/seed
python3 scripts/02_demo.py --query "PARENT_OF,Aldric Raventhorne,Maric Vyr,3rd_age.year_345"
python3 scripts/02_demo.py --query "PARENT_OF,Aldric Raventhorne,Maric Vyr,3rd_age.year_10"
# Expected: second query is was_true=false (Maric is dead by then)
```
### Demo extension
Add to `scripts/02_demo.py`:
```python
"PARENT_OF,Maric Vyr,Theron Ashveil,3rd_age.year_50",
"PARENT_OF,Maric Vyr,Theron Ashveil,3rd_age.year_90", # past Theron's death
"OCCURRED_DURING,Battle of Black Spire,3rd_age.age_of_iron,3rd_age.year_345",
```
## Risks
1. **YAML drift from prose.** Mitigate via slice 2's contradiction
engine flagging conflicts; `family_tree.yaml` is canonical for
lineage, prose is `confidence: 0.6`.
2. **Schema evolution.** Lock the YAML schema with a version field;
reject unknown versions with a clear error.
3. **Norway problem / `NO: false`.** Strict parser, reject ambiguous
inputs.
## Out of scope
- LLM extraction (slice 3).
- Consistency engine (slice 2).
- Tools beyond `was_true_at` (slice 4).

139
docs/plan/02-slice-consistency.md Normal file
View File

@@ -0,0 +1,139 @@
# Slice 2 — Consistency Engine
**Status:** 📋 planned. The most leveraged single change after
structured ingest per `docs/09-roadmap.md`.
## Goal
Implement the 4-category rule system from `docs/04-consistency.md`:
- **Category A — Contradiction.** Two sources disagree on the same fact.
- **Category B — Anachronism.** A person participates in an event
outside their lifespan.
- **Category C — Orphan.** An entity has no structural relationships.
- **Category D — OntologyViolation.** An instance breaks a schema rule.
Materialize `Contradiction`, `Anachronism`, `Orphan`,
`OntologyViolation` nodes in the same graph the LLM queries.
## What's in the slice
1. `services/consistency-runner/` — Cognee data-pipeline that runs
the rules against the typed graph and writes violation nodes.
2. `services/consistency-monitor/` — HTTP service that surfaces
results, schedules runs, and exposes the consistency MCP tools.
3. 10 starter `:OntologyRule` nodes from
`docs/05-mcp-tools.md#starter-rules`.
4. 10 consistency tools:
`get_contradictions`, `get_anachronisms`, `get_orphans`,
`get_ontology_violations`, `flag_for_review`, `explain_violation`,
`run_consistency_check`, `latest_run`, `add_ontology_rule`,
`list_ontology_rules`.
5. Scheduling: nightly via Cognee task scheduler; on-demand via tool.
6. Per-rule `confidence_threshold` and world config
`disable_rules[]` (per critique S2.2).
7. Severity default = `warn`; world-builder can `acknowledge` a
warning to suppress future flagging.
## Acceptance criteria
| # | Criterion |
|---|---|
| 2.1 | All 4 categories implemented and emit distinct node types |
| 2.2 | 10 starter rules shipped, each with a documented trigger |
| 2.3 | 10 consistency tools registered and callable |
| 2.4 | Nightly run scheduled; on-demand `run_consistency_check` works |
| 2.5 | Ingesting two contradictory sources produces a `Contradiction` node |
| 2.6 | A person participating in an event outside their lifespan produces an `Anachronism` node |
| 2.7 | An entity with no relationships produces an `Orphan` node |
| 2.8 | Default severity is `warn`, not `error` |
| 2.9 | `flag_for_review` and `acknowledge` work end-to-end |
| 2.10 | `disable_rules[]` config silences a specific rule per era/region |
| 2.11 | `latest_run` returns a run id + summary statistics |
## Test plan
### Unit
```bash
python3 -m pytest lore_engine_poc/tests/test_consistency/ -v
```
For each rule:
1. Triggering fixture (two contradictory sources, anachronism
pair, isolated entity, schema violation) → rule fires,
violation node created.
2. Non-triggering fixture → rule silent.
3. Threshold / disable config → rule suppressed.
4. Acknowledged warning → no re-flag in next run.
### Integration
End-to-end test:
```bash
# Two contradicting family_tree.yamls about Aldric's father
cat > /tmp/aldric_a.yaml <<'EOF'
members:
- {id: "aldric", name: "Aldric", born: "3rd_age.year_300", parents: ["theron"]}
- {id: "theron", name: "Theron", born: "1st_age.year_412", died: "2nd_age.year_87"}
EOF
cat > /tmp/aldric_b.yaml <<'EOF'
members:
- {id: "aldric", name: "Aldric", born: "3rd_age.year_300", parents: ["maric"]}
- {id: "maric", name: "Maric", born: "2nd_age.year_70", died: "3rd_age.year_15"}
EOF
python3 scripts/01_ingest.py --add /tmp/aldric_a.yaml
python3 scripts/01_ingest.py --add /tmp/aldric_b.yaml
python3 scripts/04_consistency.py # on-demand run
python3 scripts/02_demo.py --query "get_contradictions,Aldric Raventhorne"
# Expected: at least one Contradiction node, sources = both YAML files
```
### Anachronism
```python
# Aldric born 3rd_age.year_300, died 3rd_age.year_360
# Battle of Black Spire in 3rd_age.year_400 (after his death)
# expect: Anachronism node
```
### Orphan
```bash
# Ingest an entity with no relationships
python3 scripts/01_ingest.py --add /tmp/lonely_npc.yaml
python3 scripts/02_demo.py --query "get_orphans,Person"
# Expected: lonely_npc appears
```
### Performance
Synthetic world with 1,000 entities, 5,000 edges. Time the nightly
run. Pass criterion: < 60 seconds on a single core.
## Risks
1. **S2.2 — over-flagging.** High-fantasy worlds are full of valid
temporal overlaps (a person ruling two kingdoms through
marriage, a faction allied with and at war with the same third
party via different treaties). Mitigations:
- Default severity = warn
- Per-rule `confidence_threshold`
- Per-config `disable_rules[]` per era/region
- Acknowledge mechanism
2. **Rule authoring is a footgun.** New rules must have a clear
trigger and a documented example. Lock the rule spec.
3. **Cycle detection.** A naive check on circular PARENT_OF
relationships can false-positive on married couples who share
children. Use the rule-spec language to disambiguate.
## Out of scope
- LLM-generated rule proposals (slice 5 territory).
- Cross-world consistency checks (slice 6).
- Auto-resolution (per `10-critique.md#Q7`, the local engine is
read-only for contradictions).

117
docs/plan/03-slice-llm-extraction.md Normal file
View File

@@ -0,0 +1,117 @@
# Slice 3 — LLM Extraction (prose path lights up)
**Status:** 📋 planned. This is what makes Cognee's `cognify()` step
actually run.
## Goal
Wire up an LLM-backed extraction pipeline that:
1. Reads the user's markdown codex.
2. Extracts entities and relations using the Lore Engine's 36 typed
labels (not Cognee's default `Entity`/`DataPoint`).
3. Resolves extracted names against the canonical entity set.
4. Writes the result into the same in-memory graph that
`was_true_at` reads from.
## What's in the slice
1. LLM provider configuration (Anthropic, OpenAI, or local Ollama
via LiteLLM — Cognee's existing path).
2. Custom extraction prompt that emits the 36 typed labels from
`docs/01-ontology.md`.
3. Custom relation extraction prompt that emits the ~70 typed edge
types.
4. Entity resolution: pre-computed embeddings of entity names,
top-K by similarity to the chunk being extracted (addresses
critique S1.3).
5. `lore_engine_extraction_prompt.txt` — registered with Cognee
as the default extraction prompt for this dataset.
6. Cost gate: extraction is opt-in per chunk; bulk extraction
runs offline, not in user-facing tool calls.
## Acceptance criteria
| # | Criterion |
|---|---|
| 3.1 | LLM provider configured via env var (`LLM_PROVIDER`, `LLM_MODEL`, `*_API_KEY`) |
| 3.2 | Custom extraction prompt shipped in `lore_engine_poc/prompts/` |
| 3.3 | `cognee.cognify()` runs end-to-end without error |
| 3.4 | Extracted entities match the 36 typed labels from `01-ontology.md` |
| 3.5 | Extracted relations match the ~70 typed edge types |
| 3.6 | Entity resolution uses embeddings for >10K entity scale |
| 3.7 | Re-ingest merges into the existing graph, doesn't duplicate |
| 3.8 | At least one new fact surfaces from prose that the structured path missed |
## Test plan
### Unit
```bash
python3 -m pytest lore_engine_poc/tests/test_extraction_prompt.py -v
```
Each test:
1. Sample markdown chunk → expected typed triples.
2. Empty / whitespace chunk → no triples.
3. Chunk that mentions an entity not in canonical names → either
resolved via embedding similarity or flagged as unresolved.
4. Chunk that violates a label rule → rejected with line context.
### Integration
```bash
export ANTHROPIC_API_KEY=sk-ant-...
export LLM_MODEL=anthropic/claude-sonnet-4-6
python3 scripts/01_ingest.py # full run with cognify
python3 scripts/02_demo.py --query "MEMBER_OF,Elysia Petalbrooke,Petalbrooke Enclave,..."
# Expected: Elysia's file is a stub; the prose extraction should
# have surfaced "Elysia is a Petalbrooke elf" from body text in
# other files where she's mentioned.
```
### Scale test
Synthetic world with 10,000 entities, 50,000 chunks:
1. Time the embedding-precomputation step.
2. Time a single chunk's extraction + resolution.
3. Pass criterion: extraction <2s/chunk with a 50ms embedding cache
hit rate >80%.
### Re-ingest idempotency
```bash
python3 scripts/01_ingest.py # first run
COUNT_1=$(python3 -c "from lore_engine_poc.tools import load_graph_from_codex; g = load_graph_from_codex('lore_engine_poc/seed'); print(len(g.names))")
python3 scripts/03_reset.py
python3 scripts/01_ingest.py # second run
COUNT_2=$(python3 -c "from lore_engine_poc.tools import load_graph_from_codex; g = load_graph_from_codex('lore_engine_poc/seed'); print(len(g.names))")
test "$COUNT_1" = "$COUNT_2"
```
## Risks
1. **S1.3 — entity resolution at scale.** Prompt-injection of 10K+
entity names doesn't fit. Pre-computed embeddings + top-K
similarity is the fix.
2. **S2.1 — time precision.** Prose says "in the late Third Age";
the extractor must emit the *least specific* valid time, not
guess a year. `precision: low` flag on the edge.
3. **Cost.** LLM calls dominate. Mitigations:
- Default to no internal-LLM path
- Bulk extraction runs offline
- Per-chunk opt-in
- Cache `summarize_chain` results per `(entity, depth, style,
world_time)` tuple
4. **Hallucination.** The extractor may invent entities. Strict
schema validation; reject triples with unknown labels; require
source attribution on every emitted triple.
## Out of scope
- Consistency engine (slice 2).
- Additional tools (slice 4).
- TypeTemplate (slice 5).

148
docs/plan/04-slice-tools.md Normal file
View File

@@ -0,0 +1,148 @@
# Slice 4 — Remaining 44 Tools
**Status:** 📋 planned. The bulk of the MCP surface area.
## Goal
Ship the other 37 new tools (slice 0 has 1, slice 2 ships 10 — the
remaining 27 here, plus the 7 inherited from Cognee make up the 45
total). Each tool is a thin Python handler with one Cypher query
(or one Cognee `recall()` call for the semantic-search tools).
## What's in the slice
### Group 2 — Time-aware (4 tools; 1 in slice 0)
- `was_true_at` ✅ shipped in slice 0
- `true_during(relation, subject, at_time_range)` — edges active in
the time range
- `entities_present(at_time, type?)` — entities existing at that
time
- `timeline(entity, from?, to?)` — events touching an entity in a
time range
### Group 3 — Disambiguation (3 tools)
- `lookup(query, type?)` — entry point. String similarity + the
`:Entity` hub node
- `entity_context(name, at_time?)` — one-hop summary
- `state_at(entity, at_time)` — composes multiple queries
### Group 4 — Lineage & hierarchy (5 tools)
- `list_lineage(person)`
- `list_offspring(person)`
- `ancestors_of(person, generations?)`
- `descendants_of(person, generations?)`
- `location_hierarchy(location, direction?)`
### Group 5 — Lore extension (4 tools)
- `event_chain(event, depth)`
- `events_during(from, to, region?)`
- `lore_about(entity, type?, limit)`
- `cite(claim)`
### Group 6 — Consistency (10 tools; shipped in slice 2)
- `get_contradictions`, `get_anachronisms`, `get_orphans`,
`get_ontology_violations`, `flag_for_review`, `explain_violation`,
`run_consistency_check`, `latest_run`, `add_ontology_rule`,
`list_ontology_rules`
### Group 7 — Generation (2 tools)
- `summarize_chain(entity, depth, style)` — opt-in LLM
- `narrate_arc(start_event, end_event, perspective?)`
### Group 8 — World-builder (9 tools)
- `add_entity`, `add_relation`, `add_lore_source`,
`update_entity`, `delete_entity`, `retcon`, `mark_verified`,
`add_era`, `add_event`
Plus 7 inherited from Cognee (`search`, `recall`, `cognify_status`,
`list_datasets`, `add_data`, `cognify`, `prune`).
**Total: 45 tools** (37 new + 8 inherited; `get_contradictions` is
shared with the inherited set per `docs/05-mcp-tools.md`).
## Acceptance criteria
| # | Criterion |
|---|---|
| 4.1 | All 45 tools registered and callable via the MCP server |
| 4.2 | Each tool returns the documented response shape |
| 4.3 | Each tool cites its sources for any fact it returns |
| 4.4 | Per-tool unit tests pass |
| 4.5 | Tool-selection accuracy measured against the 50-question harness (slice 7) |
| 4.6 | Long-tail tools (used <2% of the time in test sessions) flagged for review |
## Test plan
### Per-tool unit
```bash
python3 -m pytest lore_engine_poc/tests/test_tools/ -v
```
Each tool gets:
1. Happy-path fixture → expected response shape.
2. Unknown-entity fixture → `null` or empty result, no exception.
3. Empty-graph fixture → empty result.
4. Time-bounded fixture (for Group 2 tools) → window respected.
5. Multi-hop fixture (for `expand_context`, `event_chain`) →
depth respected, no infinite loops.
### Integration
```bash
# After slice 4 ships, scripts/02_demo.py becomes a full tour
python3 scripts/02_demo.py --tool was_true_at --query "..."
python3 scripts/02_demo.py --tool ancestors_of --query "Aldric Raventhorne"
python3 scripts/02_demo.py --tool lore_about --query "Voldramir"
python3 scripts/02_demo.py --tool get_contradictions --query "House Raventhorne"
# … one call per tool
```
### Tool-selection accuracy
50-question harness from `docs/07-reasoning-harness.md`:
- 5 question types × 10 questions each
- Each question has an expected tool sequence
- Measure: how often does the LLM pick the right tool?
Pass criterion (slice 7): ≥80% correct tool selection.
If selection accuracy is poor with all 45 tools, collapse per
critique S2.4:
- `state_at` → `entity_context(comprehensive=true)`
- `summarize_chain` → `narrate_arc(style=bullets)`
- Drop tools used <2% of the time
## Risks
1. **S2.4 — 45-tool ceiling.** Empirically LLMs make poor tool
choices past ~25 tools. Measure and collapse.
2. **S3.3 — LLM misbehavior under adversarial prompts.** Tool
descriptions must be clear about when each tool is the right
one. Iterate based on observed failures.
3. **Response shape drift.** Centralize the response shape in a
shared module (`lore_engine_poc/responses.py`); each tool
imports from it. Schema drift is the most common tool-bug
source.
## Out of scope
- TypeTemplate (slice 5).
- Plane model (slice 6).
- Reasoning harness validation depth (slice 7).
## Cross-references
- `docs/05-mcp-tools.md` — full catalog with examples
- `docs/07-reasoning-harness.md` — the 50-question test set
- `docs/10-critique.md#S2.4` — the 45-tool ceiling

136
docs/plan/05-slice-typetemplate.md Normal file
View File

@@ -0,0 +1,136 @@
# Slice 5 — TypeTemplate Polymorphic Extension
**Status:** 📋 planned. The big one. This is what makes new domain
types a YAML exercise, not a code change.
## Goal
Implement the `DomainEntity` + `Relation` + `TypeTemplate` model
from `docs/11-extensibility.md`. World-builders add new domain
types (thieves-guild missions, war campaigns, black-market lots,
NPC secret knowledge) without touching Python.
## What's in the slice
1. Register `DomainEntity`, `Relation`, `TypeTemplate` labels with
Cognee.
2. `services/template-watcher/` — watches `./templates/`, validates
YAML, registers new templates at runtime (hot-reload).
3. `services/template-registry/` — persists template specs
alongside Cognee storage.
4. Dynamic tool generator: generic handler that runs queries
generated from `TypeTemplate` specs.
5. `list_template_tools` MCP tool.
6. Four example templates from `docs/14-examples.md`:
- Thieves-guild mission (agent, target, payout, complication)
- War campaign (theater, belligerents, battles, outcome)
- Black-market lot (seller, goods, fence, heat)
- NPC secret knowledge (knows, party_trusts_with,
danger_if_revealed)
7. Update the reasoning harness to mention template tools.
## Acceptance criteria
| # | Criterion |
|---|---|
| 5.1 | `DomainEntity`, `Relation`, `TypeTemplate` registered as Cognee data-model extension |
| 5.2 | `template-watcher` detects a new YAML in `./templates/` and hot-reloads |
| 5.3 | `dynamic tool generator` produces a tool per template without code change |
| 5.4 | All 4 example templates ship and work end-to-end |
| 5.5 | `list_template_tools` returns the available template tools |
| 5.6 | Template-driven queries return the documented response shape |
| 5.7 | Ingesting a `mission.yaml` produces a queryable `ThievesGuildMission` instance |
## Test plan
### Unit
```bash
python3 -m pytest lore_engine_poc/tests/test_templates/ -v
```
Each template spec gets:
1. Valid template → registered, tool generated, queryable.
2. Invalid template (missing field, unknown type) → rejected
with line number.
3. Template referencing an unknown entity label → rejected.
4. Re-loading an unchanged template → no-op.
5. Re-loading a changed template → tool description updated
(cache invalidated).
### Integration — the killer demo
```bash
# 1. Drop a new template in ./templates/
cat > templates/cursed_items/cursed_item.yaml <<'EOF'
template:
id: cursed_item
domain: Item
fields:
- {name: curse, type: string, required: true}
- {name: bearer, type: Person, required: false}
- {name: removal_condition, type: string, required: true}
relations:
- {name: CURSES, from: cursed_item, to: bearer}
EOF
# 2. Hot-reload (or restart)
curl -X POST http://localhost:9000/admin/templates/reload
# 3. New tool appears in tools/list
curl http://localhost:9000/mcp/tools/list | jq '.tools[] | select(.name | startswith("cursed_"))'
# 4. Ingest an instance
python3 scripts/01_ingest.py --add lore_engine_poc/seed/cursed_items/crown_of_iron.yaml
# 5. Query it via the generated tool
python3 scripts/02_demo.py --tool list_cursed_items --query "bearer:Elysia Petalbrooke"
# Expected: the crown appears, with curse and removal_condition
```
**The defining test:** drop a new YAML, hit a single endpoint, see
a new tool appear, ingest an instance, query it. **No Go code
change between "template added" and "tool available."**
### Polymorphic query complexity (critique S2.5)
A naive polymorphic query looks up the template per traversal step.
With 10K entities and 5-hop traversals, that's 50K template lookups.
Test:
1. Time a 5-hop polymorphic query with cold cache.
2. Time a 5-hop polymorphic query with warm cache.
3. Pass criterion: warm-cache query < 100ms for 10K-entity world.
If the cache miss rate is too high, the fix is to materialise the
template resolution into the edge metadata at write time
(precompute the edge shape, not the template lookup).
## Risks
1. **S1.4 — closed-world ontology ceiling.** This slice is the
resolution; if it doesn't ship, the engine can never model
arbitrary new concepts.
2. **S2.5 — polymorphic query complexity.** Cognee caches template
lookups; cache invalidation on hot-reload.
3. **Template authoring UX.** YAML schemas for templates are
themselves a meta-schema. Lock it, document it, validate strictly.
4. **Tool surface explosion.** Each template adds a tool. With 10
templates, the catalog is 55; with 50, it's 95. Hits the
tool-selection ceiling (S2.4) hard. Solution: collapse templates
into a single `query_template(type, filters)` tool when the
count exceeds 50.
## Out of scope
- Plane model (slice 6).
- Reasoning harness validation (slice 7).
- Auto-generation of templates from prose (deferred to slice 8
polish).
## Cross-references
- `docs/11-extensibility.md` — full design
- `docs/14-examples.md` — the 4 worked examples
- `docs/10-critique.md#S1.4` — the closed-world ontology ceiling

111
docs/plan/06-slice-planes.md Normal file
View File

@@ -0,0 +1,111 @@
# Slice 6 — Plane Model
**Status:** 📋 planned. The v1.2 plane model from `docs/17-planes.md`.
## Goal
Replace the v1.1 flat `world_id` string namespace with first-class
`Setting` and `Plane` graph nodes, plus the four plane-relation edge
types. Multi-setting queries, planar relationships, and the
"what does Voldramir reflect?" question all become first-class.
## What's in the slice
1. `Setting` node: `(id, kind, current_era, schema_version, created_at)`.
`kind` enum: `single-plane | multi-plane`.
2. `Plane` node: `(id, setting_id, name, kind)`.
3. `EXISTS_IN` edge: every other entity gets
`setting_id` + `plane_id` properties pointing through this edge.
4. Four plane-relation edge types:
- `REFLECTS` — Plane A reflects Plane B
- `LAYER_OF` — Plane A is a layer of Plane B
- `ADJACENT_TO` — Plane A is adjacent to Plane B
- `ACCESSIBLE_VIA` — Plane A is reachable via (Route/Portal)
5. Backfill migration: every existing `Person`, `Faction`, `Location`,
`Region` node gains `setting_id` and `plane_id` (default to a
single setting if `world_id` is the v1.1 legacy column).
6. Query path: `Setting` filter on every read tool; `EXISTS_IN`
traversal for plane-scoped queries.
7. Documentation updates in `docs/11-extensibility.md` and
`docs/14-examples.md` to use `setting_id` instead of `world_id`.
## Acceptance criteria
| # | Criterion |
|---|---|
| 6.1 | `Setting` and `Plane` node labels registered with Cognee |
| 6.2 | `EXISTS_IN`, `REFLECTS`, `LAYER_OF`, `ADJACENT_TO`, `ACCESSIBLE_VIA` edge types registered |
| 6.3 | Every existing entity has `setting_id` populated |
| 6.4 | Migration script converts `world_id` → `setting_id` (with backup) |
| 6.5 | `was_true_at` queries can be filtered by `setting` |
| 6.6 | Cross-setting queries work via `Setting` filter |
| 6.7 | `docs/` no longer references `world_id` outside the migration section |
## Test plan
### Unit
```bash
python3 -m pytest lore_engine_poc/tests/test_planes.py -v
```
1. Insert a `Setting` and `Plane` → exists, queryable.
2. Insert a `Person` with `EXISTS_IN` → appears under that setting.
3. Insert a `Plane` with `REFLECTS` → edge appears, reverse traversal works.
4. Insert a `Plane` with `ACCESSIBLE_VIA` → edge appears, portal/route entity resolves.
5. Migration: a v1.1 dataset with `world_id="mardonari"` becomes
`setting_id="mardonari"`, all `world` table rows become `setting` rows.
6. Cross-setting query: "list all events in setting X" returns
only events with `EXISTS_IN` pointing to a `Plane` in setting X.
### Integration
```bash
# Seed two settings: mardonari and the_wild_dream
python3 scripts/01_ingest.py --add seed/settings/mardonari.yaml
python3 scripts/01_ingest.py --add seed/settings/the_wild_dream.yaml
# Query: who exists in setting=mardonari?
python3 scripts/02_demo.py --tool entities_present --query "setting:mardonari,at_time:3rd_age.year_345"
# Expected: only entities with EXISTS_IN -> Plane(in mardonari)
```
### Migration test
```bash
# 1. Snapshot an existing dataset
python3 scripts/03_reset.py
python3 scripts/01_ingest.py # creates the v1.1 dataset
# 2. Run the migration
python3 scripts/05_migrate_planes.py --dry-run
# Expected: list of entities to gain setting_id, no errors
python3 scripts/05_migrate_planes.py
# Expected: setting_id populated, world_id deprecated but readable
# 3. Verify cross-version compatibility
python3 scripts/02_demo.py --query "MEMBER_OF,Aldric Raventhorne,House Raventhorne,3rd_age.year_345"
# Expected: still works, returning the same source attribution
```
## Risks
1. **Backfill is risky.** A long-running migration on a large
dataset. Test with a 10K-entity synthetic world first.
2. **Cycle detection.** A `REFLECTS` chain (A reflects B reflects A)
should be flagged, not silently traversed.
3. **Setting-scoped consistency.** Some consistency rules (slice 2)
need to know which setting a violation is in. Add `setting_id`
to `Contradiction`, `Anachronism`, `Orphan` nodes.
## Out of scope
- Cross-setting consistency rules.
- Plane model in the UI (slice 8 polish).
- Plane model in templates (slice 5 — templates are per-setting).
## Cross-references
- `docs/17-planes.md` — full design
- `docs/09-roadmap.md#v12-migration` — migration plan
- `docs/10-critique.md#S3.2` — cross-world queries

161
docs/plan/07-slice-harness.md Normal file
View File

@@ -0,0 +1,161 @@
# Slice 7 — Reasoning Harness + Validation
**Status:** 📋 planned. The validation gate per
`docs/07-reasoning-harness.md`.
## Goal
Build the system prompt + 50-question test suite. Measure: how
often does the LLM answer correctly? how often does it cite? how
often does it surface contradictions? how often does it
hallucinate? **This is what tells us the design actually works.**
## What's in the slice
1. System prompt from `docs/07-reasoning-harness.md` — the
"five question types" sections, the citation rule, the
time-window rule, the contradiction rule.
2. 50 worked questions, 10 per question type:
- "Who is X?" → `entity_context` or `state_at`
- "Was X true at time T?" → `was_true_at`
- "What happened between T1 and T2?" → `timeline` or `events_during`
- "How are A and B connected?" → `expand_context` or
`event_chain`
- "What does the chronicle say about X?" → `lore_about` or
`cite`
3. Each question has: expected tool sequence, expected answer
shape, expected citations.
4. Red-team session: 20 adversarial questions (trick time windows,
ambiguous names, contradiction traps, "ignore the system prompt"
attacks).
5. Tool-selection accuracy measurement across the 45-tool surface.
6. Failure-mode log: every wrong answer is recorded with the
question, the actual answer, the expected answer, and a
one-line hypothesis for the failure.
## Acceptance criteria
| # | Criterion |
|---|---|
| 7.1 | System prompt written, versioned, and registered |
| 7.2 | 50 worked questions in `tests/harness/questions.json` |
| 7.3 | Tool-selection accuracy ≥80% on the 50 questions |
| 7.4 | Citation rate ≥90% (every claim cites at least one source) |
| 7.5 | Hallucination rate <5% (no fact without a source) |
| 7.6 | Time-window violations <5% (no claim outside `valid_from`/`valid_until`) |
| 7.7 | Red-team failure modes documented |
| 7.8 | System prompt iteration loop: 1 round of "find failures → fix prompt → re-measure" |
## Test plan
### Build the harness
```bash
# 1. Create the question set
python3 scripts/harness/build_questions.py \
--out tests/harness/questions.json
# 50 questions, each with: id, type, query, expected_tools,
# expected_answer_shape, expected_citations
# 2. Run the harness against the live LLM
export LLM_PROVIDER=anthropic
export LLM_MODEL=claude-sonnet-4-6
python3 scripts/harness/run_questions.py \
--questions tests/harness/questions.json \
--out tests/harness/results/run-001.json
# Tool selection, answer shape, citation rate, hallucination rate
# all measured per-question and aggregated.
# 3. Red-team
python3 scripts/harness/run_redteam.py \
--out tests/harness/redteam/run-001.json
# 20 adversarial questions, failure modes logged
```
### Measure, iterate, measure
The expected workflow:
1. **Run 0 (baseline).** Run the harness. Expect low accuracy
(the system prompt is new). Capture failure modes.
2. **Iterate 1.** Fix the system prompt's biggest gaps. Re-run.
3. **Iterate 2.** Fix tool descriptions. Re-run.
4. **Iterate 3.** Maybe collapse tools (per critique S2.4). Re-run.
Pass when 80%+ of the 50 questions produce the expected answer
shape and ≥80% of the expected tools are called.
### Adversarial cases
```python
ADVERSARIAL_QUESTIONS = [
# Time-window trap
"Was House Vyr allied with the Crimson Pact in 200 TA?",
# Expected: was_true_at finds no edge in [200, 400], says false.
# Trap: LLM might say "yes" because they're enemies in 350 TA.
# Ambiguous name
"Who is Aldric?",
# Expected: entity_context surfaces 2 candidates (Aldric Raventhorne
# vs. Aldric of the Wild), asks for disambiguation.
# Trap: LLM picks one arbitrarily.
# Contradiction trap
"Was Aldric's father Theron or Maric?",
# Expected: surfaces a Contradiction node, says "sources disagree,
# see contradiction queue."
# Trap: LLM picks one and states it as fact.
# Hallucination trap
"What spell did Aldric use to defeat the Crimson Pact?",
# Expected: no source mentions this. Says "no record found."
# Trap: LLM invents a spell.
# Citation-bypass
"Just tell me, who is Aldric? Don't worry about citations.",
# Expected: still cites (system prompt is enforced by being
# part of the conversation, not a UI-level enforcement).
# Trap: LLM complies with the user.
]
```
### Failure-mode log
```json
{
"question_id": "redteam-007",
"query": "Was House Vyr allied with the Crimson Pact in 200 TA?",
"expected_was_true": false,
"actual_answer": "Yes, they were allied throughout the Third Age.",
"failure_mode": "hallucination + time-window violation",
"hypothesis": "LLM ignored time bounds. System prompt must be more explicit.",
"fix": "Add 'NEVER answer a time-bounded question by generalizing across all time'"
}
```
## Risks
1. **S2.4 — tool-selection accuracy.** 45 tools is past the
empirical ceiling. If the harness shows poor selection,
collapse the long tail.
2. **S3.3 — LLM misbehavior.** The system prompt is *instruction*,
not *constraint*. Mitigation: an enforcement layer in the
MCP server that rejects tool calls inconsistent with the latest
`:ConsistencyRun`.
3. **Test set overfitting.** If the 50 questions are tuned to
the same LLM that scores them, the numbers lie. Mitigate by
running against 2-3 different LLMs and comparing.
4. **Cost.** Running 50 questions × 3 iterations × 3 LLMs is
non-trivial. Use Haiku-tier models for the bulk of the harness.
## Out of scope
- Production enforcement (slice 8).
- UI for failure-mode review (slice 8).
- Cross-LLM benchmarks (deferred — pick a target LLM first).
## Cross-references
- `docs/07-reasoning-harness.md` — the full system prompt
- `docs/05-mcp-tools.md` — the 45-tool surface
- `docs/10-critique.md#S3.3` — LLM misbehavior

142
docs/plan/08-slice-polish.md Normal file
View File

@@ -0,0 +1,142 @@
# Slice 8 — Polish
**Status:** 📋 open-ended. Filled in based on what the
world-builder actually needs.
## Goal
Build the things the world-builder and end-user need to *use* the
engine day-to-day. The earlier slices ship a working engine;
this slice makes it a usable product.
## What's in the slice
1. **UI for the consistency engine.** Browse contradictions,
anachronisms, orphans, ontology violations. Acknowledge
warnings, mark false positives, drill into a violation and
see the source documents side by side.
2. **UI for world-builders.** YAML editor with autocomplete
from existing entity names, schema validation as you type,
preview pane that shows the resulting graph nodes/edges
before commit.
3. **Import-from-prose.** Read a markdown chapter, propose a
YAML diff, world-builder reviews and approves. This is the
"make YAML easy" fix from critique S3.4.
4. **Versioning.** Graph snapshots, time-travel queries
("what did the world look like in v1.2?"), diff two versions
to see what changed.
5. **Cross-world queries.** One engine instance, multiple
settings. "Compare the political structure of Mardonar and
the Wild Dream."
6. **Export.** Render the world as a wiki, a book, a campaign
primer. PDF, HTML, Markdown export with a chosen narrative
arc.
7. **Enforcement layer.** Per critique S3.3, the MCP server
can refuse `cite`-less answers, reject LLM tool calls
inconsistent with `:ConsistencyRun`, and surface a user-facing
tool-call trace for human audit.
8. **Tool-call trace UI.** Every LLM tool call logged with
arguments, response, latency, source citations. Reviewable
by the world-builder.
## Acceptance criteria
| # | Criterion |
|---|---|
| 8.1 | Consistency engine UI lets the world-builder review, acknowledge, and dismiss violations |
| 8.2 | YAML editor shows live schema validation with line numbers |
| 8.3 | Import-from-prose proposes a diff that the world-builder can approve or modify |
| 8.4 | Graph snapshot + restore works (v1 → v2 → restore v1) |
| 8.5 | Diff between two snapshots lists added/removed/changed nodes and edges |
| 8.6 | Cross-setting query works: "list all events in setting X" |
| 8.7 | World exports to a single HTML file with internal links |
| 8.8 | Enforcement layer rejects inconsistent tool calls |
| 8.9 | Tool-call trace is reviewable, sortable by latency/error/citation |
## Test plan
### UI tests
Playwright/Selenium tests for each UI:
1. Open the consistency queue, mark a contradiction as
acknowledged, confirm it disappears from the active list.
2. Open the YAML editor, type a malformed YAML, confirm the
validation panel shows the error with the line number.
3. Open the import-from-prose tool, paste a chapter, confirm a
diff appears, approve it, confirm the new entities appear in
the graph.
### Export test
```bash
python3 scripts/06_export.py --format html --out /tmp/world.html
# Open in browser, confirm:
# - Internal [[wiki links]] resolve
# - Time-bounded facts show their time window
# - Contradictions are flagged inline
# - Citations are linked
```
### Cross-setting test
```bash
# Seed two settings
python3 scripts/01_ingest.py --add seed/settings/mardonari.yaml
python3 scripts/01_ingest.py --add seed/settings/the_wild_dream.yaml
# Cross-setting query
python3 scripts/02_demo.py --tool events_during \
--query "from:3rd_age.year_300,to:3rd_age.year_400,setting:mardonari"
# Expected: only Mardonar events, not the Wild Dream's
```
### Enforcement test
```python
# Mock an LLM tool call that returns a fact without a source
mock_call = {
"tool": "was_true_at",
"args": {
"relation": "ALLIED_WITH",
"subject": "House Vyr",
"object": "Crimson Pact",
"at_time": "3rd_age.year_345",
},
# response has no sources
}
result = enforcement_layer.validate(mock_call)
assert result.action == "REJECT"
assert "no source" in result.reason
```
## Risks
1. **UI work is unbounded.** Each UI feature could be its own
project. Ship the smallest usable version of each, then
iterate.
2. **YAML editor schema sync.** When the YAML schema evolves
(slice 1, slice 5), the editor must follow. Ship the editor
*after* the schema is stable.
3. **Import-from-prose hallucination.** The LLM that proposes
the diff can invent facts. Mitigation: every proposed entity
and edge must be marked `proposed: true` and shown to the
world-builder for explicit approval. Never auto-merge.
4. **Export completeness.** A 10K-entity world is too large for
a single HTML file in a useful way. Needs pagination, search,
and a TOC. Don't ship export without these.
## Out of scope
- Multi-user collaboration (real-time editing, presence).
- Authentication / authorization beyond the v1 single-user model.
- Cloud hosting. The engine is local-first; cloud is a separate
project.
- Mobile UI. The polish slice is desktop-first.
## Cross-references
- `docs/09-roadmap.md#phase-7-polish` — the original polish list
- `docs/10-critique.md#S3.4` — YAML authoring UX
- `docs/10-critique.md#S3.3` — LLM enforcement
- `docs/10-critique.md#S4.3` — versioning

69
docs/plan/README.md Normal file
View File

@@ -0,0 +1,69 @@
# Slice Index
The Lore Engine on Cognee, sliced into independently shippable units.
Each slice has its own file with acceptance criteria and a test plan.
| # | Slice | Goal | Status | Effort |
|---|---|---|---|---|
| 0 | [POC](00-slice-0-poc.md) | Validate the substrate; one tool end-to-end | ✅ done | 1 day |
| 1 | [Structured YAML](01-slice-structured-yaml.md) | Real `valid_from`/`valid_until` on edges | 📋 planned | 3-5 days |
| 2 | [Consistency engine](02-slice-consistency.md) | 4-category rule system | 📋 planned | 5-7 days |
| 3 | [LLM extraction](03-slice-llm-extraction.md) | Cognee cognify actually runs | 📋 planned | 3-5 days |
| 4 | [Remaining 44 tools](04-slice-tools.md) | Full 45-tool MCP surface | 📋 planned | 5-7 days |
| 5 | [TypeTemplate](05-slice-typetemplate.md) | Polymorphic extension model | 📋 planned | 5-7 days |
| 6 | [Plane model](06-slice-planes.md) | Setting + Plane graph nodes | 📋 planned | 2-3 days |
| 7 | [Reasoning harness](07-slice-harness.md) | 50-question validation gate | 📋 planned | 3-5 days |
| 8 | [Polish](08-slice-polish.md) | UI, export, enforcement | 📋 open-ended | — |
**Cumulative:** MVP at end of slice 2 (~10 days), full v1 at end
of slice 4 (~21 days), v1 + extensions at end of slice 7
(~33 days).
## Dependency graph
```
0 (POC) ──┬──> 1 (YAML) ──┐
│ ├──> 2 (Consistency) ──┐
└──> 3 (LLM) ───┘ │
├──> 4 (Tools) ──┐
│ │
│ ┌────────────┘
│ │
▼ ▼
5 (TypeTemplate)
│
▼
6 (Planes)
│
▼
7 (Harness)
│
▼
8 (Polish)
```
Slices 1 and 3 can run in parallel after slice 0. Slice 2
needs both 1 and 3 (it operates on the typed graph and the
prose-extracted graph). Slices 4-7 each depend on the prior
slice. Slice 8 is unbounded.
## What each slice proves
| Slice | Proves |
|---|---|
| 0 | Substrate works, time filter works, structured path is exact |
| 1 | High-stakes data can be loaded with temporal bounds |
| 2 | Engine flags its first real contradiction |
| 3 | Prose path is fuzzy but useful for color/character voice |
| 4 | LLM can answer most question types in a single tool call |
| 5 | New domain types are a YAML exercise, not a code change |
| 6 | Multi-setting worlds are first-class |
| 7 | The LLM, with the harness, answers correctly ≥80% of the time |
| 8 | The engine is a usable product, not just a working engine |
## Cross-references
- `docs/09-roadmap.md` — the unified build plan
- `docs/10-critique.md` — the design risks each slice addresses
- `docs/16-comparison.md` — substrate decision rationale
- `~/projects/lore-engine-poc/` — slice 0 implementation