Status: ACCEPTED (2026-07-17). Companion checklist:
HATHOR_YEMAYA_IDEATION_SOTA_TODOS_2026-07-17.md (repo root; the checklist's
checkboxes are the execution ledger; this document records the decisions the
checklist builds on).
1. Goals#
Build the blank-page-to-canon pipeline the 2026-07-17 audit found missing: a first-class surface that owns capture → divergent generation → convergent selection → development → promotion into canon, for AAA games, film, and series work, on top of the real engines hathor/yemaya already have (world versioning + merge, culture/economy/politics simulation, lore validators, Sophia grounding, the yemaya QA analyzer battery, presentation-compiler, TTS).
Product stance:
- Ideas are first-class entities with lineage, revisions, and decision records — not notes in a doc.
- Every generator produces option sets, never a single answer, and every selection step records why the winner won and the losers lost.
- Speculation never dirties canon: promotion lands on world branches; merging is the act of canonization.
- Deterministic tier before model tier, everywhere (rationale §6).
2. Non-goals#
- Not a general note-taking or docs product (Notion/Neith territory). Only idea-shaped artifacts with the ideation lifecycle.
- Not a screenwriting editor. We ladder up to beat outlines / treatments and
interop via Fountain/FDX (P16.7); full script drafting stays in
libs/hathor/pre-productionscriptwriting and external tools. - Not legal clearance. Title/premise-similarity search is advisory and labeled as such (P15.4).
- Not likeness synthesis. Casting sheets and voice reads reference real people descriptively only; anything likeness-bearing routes through the existing consent machinery (P10.3, P14.6, P14.8).
- No autonomous canon mutation. Every gate that changes canon or advances a stage has a human sign-off (HITL, P15.3).
3. Glossary#
| Term | Meaning |
|---|---|
| Spark | Any captured idea fragment, pre-triage (inbox state captured). |
| Idea | The core entity; one of 13 kinds (premise, logline, what_if, character_concept, culture_seed, world_seed, location_seed, faction_seed, quest_seed, theme, title, image_ref, fragment). |
| Option set | N ≥ 3 sibling ideas produced by one generator invocation, compared as a unit. |
| Board | A curated working collection of ideas (kanban/canvas view). |
| Tournament | A pairwise-judgment session producing Bradley-Terry/Elo ratings over an option set or board. |
| Rubric | Weighted multi-criteria scoring configuration applied to options. |
| Decision record | Immutable record of a selection/kill/gate decision: winner, rejected siblings, scores at decision time, stated reason, decider. |
| Ladder | The development sequence logline → synopsis → treatment → beat outline (each rung a versioned artifact). |
| Promotion | Converting an idea/ladder artifact into a draft canonical entity (character, culture, world entity on a branch, quest). |
| Gate | A stage boundary (concept → develop → greenlight) requiring artifacts + human sign-off. |
| Graveyard | Killed ideas, queryable and revivable with lineage intact. |
4. Namespace decision (task 0.2)#
Decision: libs/hathor/ideation (new library) + routes added to
apps/hathor/narrative-api. UI lands in apps/hathor/workbench (pages) with
studio back-parity per P6.7.
Considered:
| Option | Verdict | Reasoning |
|---|---|---|
New apps/hathor/ideation-api service |
Rejected | Service sprawl: a fourth hathor service for a surface whose consumers (workbench, studio) already speak to narrative-api; nothing in the ideation workload (low QPS, no long jobs — simulation previews delegate to simulation-worker) justifies an isolated deployable. |
Extend world-api |
Rejected | world-api's contract is canonical world state + versioning/merge; ideation is pre-canon by definition. Mixing lifecycles (speculative vs. canonical) in one service blurs the promotion boundary we want sharp. |
Extend narrative-api (chosen) |
Accepted | It already owns authoring-adjacent, pre-runtime surfaces (quests, dialogues, story-graphs, validation routes). Ideation routes (/ideation/*) sit beside them; blast radius is one service redeploy; the promotion flows call world-api/narrative-api internals the same way validation already does. |
| Yemaya-side lib | Rejected | Ideation's grounding objects are hathor's (worlds, cultures, canon validators). Yemaya assets (QA analyzers, presentation-compiler, TTS, collaboration) are consumed through their public packages — dependency direction hathor→yemaya packages is already established (e.g. workbench uses yemaya UI patterns). |
Library shape: TypeScript, Vitest, tsup, path-mapped in tsconfig.base.json,
scope:hathor tag — identical scaffold conventions to libs/hathor/validation.
5. Storage design (task 0.3)#
Prisma models in libs/hathor/database/prisma/schema.prisma (the hathor
schema/DB), one migration. Entity summary (authoritative DDL in the schema
file):
- Idea — id (cuid), kind (enum, 13 values), status (enum: CAPTURED, DEVELOPING, SHORTLISTED, SELECTED, PROMOTED, KILLED, ARCHIVED), title, body (text), structured payload (Json — premise slots etc.), tags (String[]), boardId?, worldId? (grounding anchor), embedding metadata (Json?; vectors live behind the provider seam, not in this table), createdBy, timestamps. Indexed on (status, boardId), (kind), (worldId).
- IdeaRevision — ideaId FK, seq (int, unique per idea), author, diffSummary, snapshot (Json), createdAt. Append-only.
- IdeaLink — fromId, toId, linkType (enum: DERIVED_FROM, MERGED_FROM, INSPIRED_BY, CONTRADICTS, PROMOTED_TO), note?, createdAt. Unique on (fromId, toId, linkType). DAG enforced in the domain layer (cycle check on insert), not in SQL.
- IdeaBoard — id, name, purpose?, layout (Json — canvas positions), archived flag.
- OptionSet — id, generatorId, generatorParamsHash, prompt metadata (Json), createdAt; OptionSetMember — optionSetId, ideaId, ordinal.
- Tournament — id, optionSetId? | boardId?, method (enum: ELO, BRADLEY_TERRY), status, config (Json: K, scheduling), createdAt; Judgment — tournamentId, judgeId, aId, bId, winner (A|B|TIE), createdAt. Ratings are derived (recomputed from judgments — the fit is deterministic), cached in Tournament.resultCache (Json) with the judgment count it was computed at; never hand-written.
- RubricScore — ideaId, rubricId, criterionKey, score, weightAtTime, source (enum: HUMAN, CRITIC_AGENT, ANALYZER), sourceDetail, createdAt.
- DecisionRecord — id, subjectIdeaId, decision (enum: SELECTED, KILLED, REVIVED, GATE_ADVANCED, GATE_HELD, OVERRIDE), rejectedIdeaIds (String[]), scoresSnapshot (Json), reason (text, required), decidedBy, gate? (enum), createdAt. Append-only, no updates.
- PromotionRecord — ideaId, targetType (enum: CHARACTER, CULTURE, WORLD_ENTITY, QUEST, PROTOTYPE_BRIEF, BIBLE), targetId, worldBranchId?, validationFindings (Json — the lore-validator output at promotion), createdAt.
- IdeationNote (P14.7) — subjectType+subjectId, body, severity, author, state (enum: OPEN, ADDRESSED, REBUTTED, DEFERRED), resolutionLink?, createdAt/resolvedAt.
Conventions carried from the existing hathor schema: cuid ids, soft delete only via status (KILLED/ARCHIVED), Json for polymorphic payloads with Zod validation at the boundary, no cross-schema FKs (world/quest references are ids validated at the service layer, same as the rest of hathor).
6. LLM seam (task 0.4)#
One interface, defined in libs/hathor/ideation/src/provider.ts, consumed by
every generator/critic; no other module talks to a model.
export interface IdeationModelProvider {
/** Freeform generation under a fenced, structured prompt. */
generate(request: {
task: IdeationTask; // discriminated union per generator
fencedContext: FencedBlock[]; // user text, canon excerpts, sources — always fenced
options: { n: number; maxTokens: number; temperature?: number };
}): Promise<IdeationGenerateResult>; // n candidates + usage + modelId
/** Structured critique of one artifact (writers-room, critic pass). */
critique(request: {
persona: CriticPersona; // data-defined, not code forks
artifact: FencedBlock;
focus: string[];
}): Promise<IdeationCritiqueResult>;
/** Embedding for dedupe/clustering/semantic search. */
embed(texts: string[]): Promise<number[][]>;
}
Wiring rules (the V2/SAFETY-001 lessons, made structural):
- Fencing — every non-system string (user idea text, canon excerpts, Sophia
passages) enters prompts inside delimited fenced blocks with an
injection-resistant preamble; nothing user-controlled is ever spliced into
instruction text. Reuse the fencing helpers from
libs/hathor/llm-npcrather than new ones. - Safety filter invoked, always — provider outputs pass through
libs/yemaya/safetyContentFilterManager.checkContentbefore persistence (P10.1); the call is in the ideation service layer so no generator can skip it. - Fail-loud absence — no provider configured ⇒
generate/critiquethrowIdeationError('not_configured', …);embedunavailability degrades features to their labeled lexical fallback (dedupe via the credited feature-hashing fallback) or honest "unavailable", never fake vectors. - Provider chain reuse — the default implementation adapts
libs/hathor/llm-npc/provider-chain(health tracking, circuit breaker, fallback order) rather than a new chain. - Attribution — every generate/critique result stores modelId, paramsHash, and prompt hash on the produced options (P12.3) and flows into AI-attribution records (P10.3).
7. Threat & safety review (task 0.5)#
Prompt injection. User-supplied idea text and imported web content (2.5b)
are attacker-controlled; both are fenced (rule 1 above) and the content filter's
injection detector screens text that will be routed into prompts (P10.1). Sophia
passages are treated as untrusted quotes, fenced and cited, never as
instructions. Generated-content risk. All model output is filtered
pre-persist; blocked output is stored as a redacted tombstone with the category
result — auditable, not silently dropped. Likeness/consent. Character
concepts resembling real people, cloned voices for table reads, and casting
references are gated on EthicsManager consent records before promotion or
synthesis; stock synthetic voices are exempt but labeled. Canon integrity.
Ideation writes never touch canonical tables; promotion targets world
branches and runs the lore validators, with conflicts blocking-with-override
and every override captured in a DecisionRecord. Access control. Distinct
ideation.read/write/judge/promote permissions via libs/yemaya/rbac; promote
additionally requires the gate's HITL sign-off. Data retention. Killed ideas
persist (graveyard) — deletion requests route through the existing organizations
data-lifecycle surfaces rather than a bespoke purge.
8. UX skeleton (task 0.6)#
Five core surfaces, workbench-first (apps/hathor/workbench), studio
back-parity per P6.7. Layout language follows the existing workbench (left nav,
list+detail, modal editors).
INBOX (P2.3) BOARD (P6.5)
┌──────────┬───────────────────────┐ ┌────────────────────────────────┐
│ nav │ [spark] title │ │ board: "S2 villains" [+ gen ▾]│
│ │ raw text… │ │ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │
│ Inbox(12)│ similar: 3 ideas ⚠ │ │ │card│ │card│ │card│ │card│ │
│ Boards │ ┌─────────────────┐ │ │ └────┘ └────┘ └────┘ └────┘ │
│ Tourn. │ │keep→kind+board │ │ │ columns: captured│dev│short │
│ Ladder │ │merge→picker │ │ │ [tournament] [rubric] [board▾] │
│ Graveyard│ │kill→reason │ │ └────────────────────────────────┘
│ │ └─────────────────┘ │
│ │ keys: j/k/enter │
└──────────┴───────────────────────┘
GENERATOR CONSOLE (P6.5) TOURNAMENT (P4.2c)
┌────────────────────────────────┐ ┌────────────────────────────────┐
│ engine: [premise ▾] │ │ pair 7/21 judge: ama │
│ seed world: [Veilborn ▾] │ │ ┌───── A ─────┐ ┌───── B ─────┐│
│ grounding docs: [+] │ │ │ logline… │ │ logline… ││
│ tier: ◉ deterministic ○ model │ │ │ premise slots│ │ premise slots││
│ (model not configured) │ │ └─────────────┘ └─────────────┘│
│ [generate 5 options] │ │ [← A wins] [tie] [B wins →]│
│ → OptionSet grid, per-option: │ │ leaderboard (live BT ratings) │
│ [develop] [critique] [kill] │ └────────────────────────────────┘
└────────────────────────────────┘
DEVELOP LADDER (P5)
┌──────────────────────────────────────────────┐
│ logline ── synopsis ── treatment ── beats │
│ v3 v1 — — │
│ [framework: Save the Cat ▾] [corkboard ⇄] │
│ diagnostics: tension ▂▄▆▄█ pacing ok │
│ notes(2 open) │ critics(1 refuted) │ promote │
└──────────────────────────────────────────────┘
Interaction commitments: keyboard-first triage (j/k/enter), every destructive
action requires a reason (feeds DecisionRecords), every model-tier control shows
honest availability (disabled + tooltip when not_configured), canvas surfaces
get keyboard equivalents (a11y, P11.4).
9. SOTA benchmark dispositions (task 0.1)#
Disposition of every row in the checklist's benchmark table. COVERED = planned as mapped; no row is rejected outright; two are explicitly descoped in part, noted below.
| # | Capability row | Disposition |
|---|---|---|
| 1 | Frictionless capture | COVERED — P2 (hotkey modal, inbox, zero-form path). |
| 2 | Mood boards & reference libraries | COVERED — P8.1 via maya/inspirations bridge (2.5a); no duplicate library. |
| 3 | Premise/logline formulas | COVERED — P3.1 (deterministic slot grammar + lints + model tier). |
| 4 | Hierarchical story generation | COVERED — P5.1/5.2 ladder; scene-level generation DESCOPED (non-goal §2: script drafting stays in pre-production/external tools; ladder stops at beats/treatment). |
| 5 | What-if over canon | COVERED — P3.2 (structural mutation operators + simulator-backed consequences + tree UI). |
| 6 | Creativity operators | COVERED — P3.3 (SCAMPER as typed transforms, Zwicky box, stimulus deck, hats). |
| 7 | Diversity-guaranteed generation | COVERED — P3.4 (MAP-Elites grid over genre/tone/scope/era/conflict descriptors). |
| 8 | Multi-agent writers' room | COVERED — P3.5 (genre-agnostic generalization of case-writers-room; Canon-Keeper calls real validators). |
| 9 | Research-grounded ideation | COVERED — P3.6 (Sophia citations; fail-loud without client). |
| 10 | Culture-aware onomastics | COVERED — P3.7 (phonotactic profiles on culture entities; seeded RNG). |
| 11 | Pairwise/tournament selection | COVERED — P4.2 (BT/Elo, information-maximizing scheduling). |
| 12 | Multi-criteria scoring | COVERED — P4.3 (weighted rubric + sensitivity solve). |
| 13 | Diversity-aware shortlisting | COVERED — P4.4 (MMR; DPP considered and rejected — MMR is sufficient, simpler, and testable; revisit only if shortlists degenerate in practice). |
| 14 | Adversarial critic panels | COVERED — P4.5 (sequential refuting critics; human-only mode when unconfigured). |
| 15 | Decision records | COVERED — P4.6 (immutable, graveyard revival keeps lineage). |
| 16 | Development ladder | COVERED — P5.1. |
| 17 | Multiple narrative frameworks | COVERED — P5.2 (six frameworks, single source of truth shared with theory lib). |
| 18 | Promotion with provenance | COVERED — P5.4 (drafts on world branches; validators at the gate). |
| 19 | Real-time collaborative boards | COVERED — P7.1 (Yjs via yemaya/collaboration). |
| 20 | Idea versioning & lineage | COVERED — P1.3/1.4. |
| 21 | Canon guardrails during ideation | COVERED — P10.2 (advisory at capture, blocking-with-override at promotion). |
| 22 | AI attribution & consent | COVERED — P10.3 (EthicsManager labeling + consent gating). |
| 23 | Funnel analytics & win-rates | COVERED — P12. |
| 24 | Pillars & core loops (MDA) | COVERED — P13.1/13.2 (real theory-lib engine). |
| 25 | Comps & positioning | COVERED — P13.3 (+ P15.4 for clearance-flavored search). |
| 26 | Mechanic/systems concepting w/ sim preview | COVERED — P13.4 (honest labels; unsimulated sketches stay labeled drafts). |
| 27 | Level/biome/encounter briefs | COVERED — P13.5/13.6. |
| 28 | Prototype briefs w/ kill criteria | COVERED — P13.7. |
| 29 | Scope & branching-cost estimation | COVERED — P13.8 (existing estimators; labeled estimates). |
| 30 | Series bible / season arc / episode grid | COVERED — P14.2–14.4. |
| 31 | Corkboard beat board | COVERED — P6.8 (+P14.4 specialization). |
| 32 | Character arc design | COVERED — P5.7 (existing arc validator wired). |
| 33 | Ensemble balance | COVERED — P6.9 (real Gini/representation analyzers). |
| 34 | Voiced table reads | COVERED — P14.6 (tts-integration; consent-gated; fail-loud). |
| 35 | Pitch decks/one-pagers/lookbooks | COVERED — P14.5 (presentation-compiler; assembled from real artifacts only). |
| 36 | Notes workflow | COVERED — P14.7 (blocking gates on unresolved blocking notes). |
| 37 | Title/logline A/B testing | COVERED — P4.7 (existing ab-variant machinery). |
| 38 | Craft critic battery | COVERED — P4.8/P5.6 (adapters over the existing yemaya analyzers; reuse-first rule). |
| 39 | Franchise routing & slate balance | COVERED — P15.1/15.2. |
| 40 | Stage-gate greenlight w/ HITL | COVERED — P15.3 (gates never auto-advance). |
| 41 | Title clearance & similarity | COVERED (advisory-only, labeled) — P15.4; legal clearance is a non-goal (§2). |
| 42 | Cultural sensitivity & representation | COVERED — P15.5 (existing validators; evidence-carrying findings). |
| 43 | Locale-aware naming | COVERED — P15.6 (honest scope: only locales with lexicons, listed). |
| 44 | Fountain/FDX interop | COVERED — P16.7 (import extends existing parser; FDX export new). |
| 45 | Command palette / search / templates / mobile capture | COVERED — P16.1–16.5. |
Partial descopes on record: row 4 (scene-level drafting → pre-production/ external, by non-goal) and row 13 (DPP → MMR, simplicity + testability). Everything else lands as mapped or the checklist row gets re-opened.
10. Sequencing#
As in the checklist's "Sequencing & dependency notes" — P0→P1→P2 strictly sequential; P3 engines independent after P2 (3.1 first); P6.0a/6.0b before any parity page; P10/P11 apply from the first line of code.