The ClockWork Dark

What’s new (v0.9)

The world is no longer static scenery — it reacts.

• The reactive world — Doom Clock beats reshape the map: flags, discoveries, rumors, and NPC relocations fire as beats cross. The tunnels open new ground; villagers flee to the square; the notice board pins the Dark’s own bounties.
• Set-pieces — authored, world-gated challenges you descend into: the tunnel-mouth (a branching underground decision tree with per-node scene art) and the warden barrow at Hollow Hill (learn the older name — or trust the faceless Assistant, who points at the wrong star).
• The convergence payoff — the older name learned in Hollow Hill sharpens the unmake reckoning at the tower. The narrative spine is complete: tunnels open → descend → Hollow Hill → name the Hollow Crown → carry the older name → unmake the Dark.
• NPCs move with the Dark — Aldric, Greta, the gate — named villagers relocate as beats fire. Maris does not move.
• The Forge — Brann Holt’s smithy, station-gated recipes (warded blade, reforged relic), the mundane counterpart to Maris’s oven.
• The world map — a “known reaches” overlay: a hand-painted overview map above a list of every location, the current one lit, visited ones marked.
• Cutscenes & dice faces — tunnel entrance reveal, tunnel descent, Hollow Hill arrival, and forge cutscenes wired; the dice toast shows the exact rolled d20 face as a still.
• Reactive notice board — the board’s face changes as the Dark spreads; bounties pin themselves up as their beat-flags fire.
• Frontend a11y — Escape-to-close, focus-trap, focus-restore on all dialogs; :focus-visible; prefers-reduced-motion.
• CI pipeline — pytest, vitest+jsdom, Playwright e2e on every push.
• 393 backend tests, 19 vitest tests, 48 OKFS concepts.

Architecture

A deterministic engine holds all mechanical truth; two autonomous LLM agents improvise on top; a governance layer reins them in; OKFS feeds them canon; media renders it.

flowchart TB
    subgraph HARD["Hard Engine — engine/game/ (the only authority)"]
        STATE["GameState · dice · combat · crafting · travel<br/>evil_ticker · DoomClock · challenges · contracts"]
        SKILLS["@skill registry — engine/skills/<br/>roll_dice · resolve_combat · craft_item · move_to · confront_darkness"]
    end
    subgraph AGENTS["Two Agents — engine/agents/"]
        DRIVER["Storyteller / Driver<br/>big model · drives world · Evaluator gate + retry"]
        ASSIST["Assistant<br/>small model · unreliable companion<br/>AssistantDirector: when / with-what / how-reliably"]
    end
    subgraph GOV["Governance — engine/governance/ + engine/mcp/"]
        PRE["PRE interceptors — shape the prompt<br/>LoreInject · DoomBeat · EvilPhaseTone · StorytellerMind · AwarenessGate"]
        POST["POST audit — SceneRulesEngine R001-R005<br/>RulesGovernor records LLM overreach"]
    end
    subgraph KNOW["OKFS Knowledge — knowledge/"]
        OKFS["one concept per .md + frontmatter + links<br/>lore · NPCs · items · arcs · runbooks · metrics<br/>content-hashed _index.json"]
    end
    subgraph MEDIA["Media — engine/media/ (graceful degradation)"]
        IMG["ComfyUI images / cutscenes"]
        VOICE["Voxtral TTS / STT"]
    end
    OBS["Oracle — engine/observability/ · /api/metrics"]

    SKILLS <--> STATE
    AGENTS -- "propose, never decide" --> SKILLS
    PRE --> AGENTS --> POST
    KNOW -. "RAG / progressive disclosure" .-> AGENTS
    AGENTS --> MEDIA
    AGENTS --> OBS
    POST --> OBS

The balance we chase: let the AIs run loose enough to surprise ; rein them with the engine + governance enough to stay coherent and fair.

The systems