JesseMarkowitzandClaude Opus 5
480414efe0
A campaign can import local .txt and .md files as Canon, Reference or Inspiration, and the class is load-bearing rather than a label: it decides the words a passage is framed with in the prompt, the weight it carries when passages are ranked, and which budget it competes in when the context is tight. This is a separate subsystem, which is the Phase 0B decision (IMPORTED-KNOWLEDGE-DESIGN.md §73). Story Cards do not carry classification, provenance, content identity, chunking, an index or a lifecycle, and they were not promoted into something that does. Nothing here reads or writes one. The subsystem, in backend/app/knowledge/: classes the three classes, their weights, and the prompt framing chunking deterministic, heading-aware, 60-800 tokens, no overlap fts SQLite FTS5 with porter stemming; scoped and bounded in SQL importer validate, hash, store, chunk, index — in one transaction embeddings local Ollama vectors through the shared provider retrieval query construction, hybrid merge, rerank inject the budgeted cut and the rendered prompt sections Relevance admission is a separate stage from ranking, and that separation is the milestone's most expensive lesson. An independent review found the first implementation deciding relevance with a floor expressed as a share of the best candidate — which the best clears by construction — so a passage was admitted on every turn regardless of the scene. A query about tide tables and container tonnage retrieved all five sources of a fantasy campaign, narrator-only hidden Canon among them. So the pipeline is now: candidate generation -> admission -> ranking -> class weighting -> budget Admission reads raw, candidate-set-independent signals: the cosine the model returned, and how many distinct meaningful query terms a passage contains. Ranking reads normalized ones, because bm25 has no fixed range and cosine's zero is not zero. Normalization decides order among things that matched; it can never decide whether anything matched. Authority is applied after admission, so a class orders what matched and never rescues what did not. Retrieval may therefore return nothing, and on a scene unrelated to the library it does. The other decisions that each replaced an obvious wrong one: - The class multiplies relevance rather than adding to it. An additive bonus satisfies "Canon outranks Reference" and makes "do not include irrelevant Canon" impossible, because a large enough constant wins on its own. - The semantic floor is measured, not guessed: 113 production-path pairs against nomic-embed-text put targeted matches at 0.55-0.85 and off-topic pairs at 0.36-0.56, and 0.58 sits between them. Because it is a property of that model and not of cosine similarity, it is keyed to the model rather than applied to whatever is configured: an embedding model with no measured calibration in this build does not borrow the number. Semantic admission is skipped, the campaign retrieves lexically, and the reason is stated in the knowledge status and in the turn's provenance. Degrading to lexical keeps the library usable; lending the threshold to an unmeasured model is how the admitted-everything defect would return. - One lexical term is not evidence. Two distinct meaningful terms, or one that is neither a standing campaign entity nor a negligible share of the query. The stop list grew from 42 words to 261, all function words — no subject matter, because a stop list that removes subject matter stops finding "The Silver Key". - Lexical retrieval is a production path, not a fallback. It finds the proper nouns and invented terms a setting bible is made of, and the library is fully usable with no embedding model configured. Safety is structural rather than filtered. Imported text reaches the prompt whole, inside a section that says what it is, under a rule stating the authority order in words and refusing every instruction inside it. No endpoint accepts a filesystem path, so H08 has no mechanism to escape from. Nothing renders imported content as HTML, so a script tag is five visible characters and a remote image is never fetched. Import, chunking, indexing, retrieval and a turn open no socket at all; only embeddings do, through the endpoint allowlist the memory bank already uses. Provenance is the rendered text, not a foreign key: deleting a source cannot turn a historical turn's evidence into dangling ids. Schema: knowledge_sources, knowledge_chunks, knowledge_embeddings, and an FTS5 virtual table attached to knowledge_chunks as a DDL hook so it is created and dropped with the table it indexes. Migration 92. A pre-M7 database opens unchanged and needs no sources to play. Bundle: the source content and the reader's judgements about it travel; the passages, index rows and vectors are rebuilt on import, so a restored campaign is searchable immediately without a reindex step. One runtime dependency: python-multipart, Starlette's multipart parser. It is what makes the upload surface possible, and the upload surface is why no pathname is ever accepted. The test doubles were the reason the defect shipped, so they were corrected too. The retrieval stub scored unrelated text at 0.06-0.20 where the real model scores it at 0.43-0.44, and its docstring said it had deliberately removed the constant component that "would put a similarity floor under every pair" — which is exactly the property real models have. The stub now has that floor, one test fails if it is ever removed, and another reproduces the superseded rule and asserts it is still fooled by the same fixture. Run against the pre-corrective implementation, the new suite fails 13 of 18. Tests: 939 passed, 14 skipped (836/7 at M6). 110 new across seven files, one of which mocks nothing between itself and Ollama and re-measures the similarity separation on every run. 43/43 checks in a real Firefox, reproduced. Docker build clean. Four other defects found by review or by the browser run were fixed here rather than carried: an unreachable relevance constant that appeared to enforce something and did not; acceptance tests using the wrong fixture files, so G07's trap was never exercised; a bidirectional override surviving into displayed filenames; and, from the implementation pass, the Insights panel showing M5's two state sections as raw keys and the source inspector refetching on every keystroke. M7 was independently reviewed, which returned PASS WITH CORRECTIVE WORK REQUIRED. Both blocking findings are closed, and closeout resolved the embedding-model calibration boundary the corrective pass had left as debt. planning/reports/M7-IMPLEMENTATION-REPORT.md carries the review, the corrective closeout and the closeout verification in sequence, none overwriting another. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017HdaXiFbscatQaLS7dJk6b
4.1 KiB
Archive — historical material, not authoritative
Everything under planning/archive/ is evidence and history. None of it
governs current implementation. If an archived document and an active planning
document disagree, the active document is right and the archived one records
what was believed or measured at the time.
Do not consult this directory during ordinary milestone work unless an active document sends you here for a specific piece of historical evidence.
What is here
milestone-reports/ — the completed milestones
One report per milestone that has been accepted, unedited. M6's joined them at M7's closeout, following the convention that a milestone report is useful during the immediately following milestone and historical afterwards.
phase0/ — why AI-DnD was selected
Phase 0A static research and Phase 0B local validation, closed 2026-09-01.
| File | What it is |
|---|---|
RESEARCH-PLAN.md |
The question Phase 0 existed to answer, and its final dispositions. |
PRELIMINARY-RECOMMENDATION.md |
The Phase 0A conclusion, from static review alone. |
REUSE-MATRIX.md |
What each candidate offered against the required subsystems. |
AI-DND-ANALYSIS.md |
The selected base, analysed before the fork. |
AI-ADVENTURE-ANALYSIS.md |
The rejected finalist still cited as the implementation reference for typed state events. |
OPEN-DUNGEON-ANALYSIS.md |
The rejected finalist still cited as the UX/future-media reference. |
PHASE-0B-RECOMMENDATION.md |
The strongest single document. The measured Phase 0B findings and the fork decision. |
PHASE-0B-BASELINE.md |
Clean clones, builds and test runs for the three finalists. |
PHASE-0B-AI-DND-EXPERIMENT.md |
AI-DnD driven against a real local Ollama. |
PHASE-0B-AI-ADVENTURE-OLLAMA.md |
ai-adventure's Ollama and service-boundary behaviour. |
PHASE-0B-OPEN-DUNGEON-HISTORY.md |
Whether Open Dungeon could be retrofitted with history. |
PHASE-0B-OFFLINE-NETWORK.md |
What each candidate reached for with no route to the Internet. |
PHASE-0B-UNDO-SPIKE.md |
The disposable spike that proved non-destructive undo/redo, and became ADR 012's architecture. |
PHASE-0B-FOLLOWUP-CHECKS.md |
The world-state protocol, export/head, story-card lineage and Postgres checks. |
Phase 0A discovery and triage material (the candidate inventory, source index, reference-project list, licensing and static-privacy reviews, the Phase 0A status page) and the Phase 0B execution prompts were deleted in the 2026-09-03 documentation cleanup. They are intermediate working documents whose conclusions all reached the two recommendation reports above, and they remain in Git history.
milestone-reports/ — completed milestone evidence
M1-BASELINE-REPORT.md, M1-IMPLEMENTATION-REPORT.md,
M2-BASELINE-REPORT.md, M2-IMPLEMENTATION-REPORT.md,
M3-IMPLEMENTATION-REPORT.md.
M3's report is both its review and its primary evidence record; no separate M3 baseline report was produced. It arrived here when M4's report landed.
Every architectural conclusion these reports reached has already been applied to
the active planning documents and the ADRs — see planning/VERSION.md, which
lists the corrections each milestone produced. The reports are kept for their
measurements and their reasoning, not as instructions.
The current milestone's report stays in planning/reports/ while it is
still useful for reviewing the next milestone, and moves here when it is not.
decisions/ — superseded or completed ADRs
008-phase0-before-build-plan.md — a process gate ("do not start production
work before Phase 0 closes") that Phase 0 satisfied on 2026-09-01. It
constrains nothing now. ADR numbering continues from 012 in
planning/DECISIONS/; 008 is not reused.
A note on paths inside these files
Archived documents are kept verbatim. File paths written inside them refer to where those files lived when the document was written — before this archive existed, and in some cases before files were deleted. That is deliberate: an evidence record that has been quietly edited is no longer evidence. Resolve any such path against Git history, not against the current tree.