Document branch compiler organ

docs/architecture/ink-branching-scenes.md

@@ -232,6 +232,55 @@ is created, the artifact should name the reason and the expected future writing
 debt. Trees are cheap to grow and expensive to prune. The machine should not
 act surprised by botany.
 
+## Branch Compiler
+
+The Branch Compiler is the organ that turns Ghostlight scene intent into a
+playable Ink artifact. It is not the character agent, the responder, the
+appraiser, or the final reviewer. It assembles branch structure from already
+available scene state, projected actor affordances, proposed actions, accepted
+consequence packets, and coordinator constraints.
+
+The Branch Compiler receives:
+
+- fixture brief and scene spine
+- source-grounded lore digest
+- current world, scene, resource, relationship, and branch state
+- actor-local branch candidates, including speech and non-speech actions
+- responder outputs or coordinator-authored placeholder reactions
+- consequence packets from reviewed turns
+- branch-and-fold plan
+- visual continuity requirements
+- schema and Ink formatting constraints
+
+The Branch Compiler emits:
+
+- readable `.ink` scene content
+- Ink variables, knots, stitches, choices, gathers, and conditionals
+- a `.training.json` sidecar tying each branch to state basis, action intent,
+  consequence surfaces, and later callbacks
+- compiler notes for fold decisions, route-split decisions, and known review
+  risks
+- image prompt anchors and branch/state modification handles when the fixture is
+  meant for illustrated output
+
+The Branch Compiler may propose structure. It must not invent hidden character
+truth, private motivations, or durable social mutations as if compilation made
+them real. Character behavior comes from projected local context and responder
+or coordinator-authored action proposals. Social interpretation and memory
+changes come from appraiser/mutator review. The compiler's job is to make the
+branching artifact playable, legible, and traceable.
+
+The compiler should prefer compact state variables, bands, and flags over
+runaway branch trees. It should create major route splits only when the
+coordinator or reviewed consequence packet says folding would falsify the
+world. When it folds branches, it must preserve the variables and callbacks that
+make the fold honest.
+
+The Branch Compiler output is draft until the IF Artifact Reviewer accepts it.
+That separation matters. A compiler can make a scene valid Ink while still
+producing cosmetic choices, fake folds, unused variables, or endings that ignore
+the whole moral machinery. Valid syntax is not wisdom. It is barely hygiene.
+
 ## IF Artifact Review
 
 Branching fixtures need an independent review pass before acceptance. The

notes/ghostlight-implementation-plan.md

@@ -39,6 +39,7 @@ sandboxed training-data pipeline for branching scenes and state consequences.
      not raw responder gold.
    - Interactive-fiction correction: a full-story pass is not just a linear chain of responder receipts. It needs a beginning-to-ending narrative spine, branch points, and cross-scene consequence carryover so decisions visibly matter later. Responder artifacts should be generated at branch/action moments, while coordinator artifacts track branch flags, relationship deltas, resource costs, unresolved hooks, and later scene consequences.
    - Branch-and-fold correction: do not let every choice create an isolated subtree. Normalize consequences into compact state bands and flags, fold most branches back into shared later scenes, and reserve major route splits for consequences that change the playable world enough that convergence would lie.
+   - Branch compiler correction: treat Ink materialization as its own organ. It receives fixture brief, lore digest, scene/world/relationship state, actor-local branch candidates, consequence packets, fold plan, and visual continuity requirements; it emits playable Ink plus a training sidecar and compiler notes. It does not own hidden character truth or social mutation.
    - Website-content correction: each complete scene should include an art-direction block with establishing shot, light/color, bodies/interfaces, material evidence, branch-visible marks, one durable base image prompt, and additive branch/state modification prompts. Visual continuity is part of consequence carryover, not decorative garnish applied after the story escapes containment.
    - IF review correction: run an independent artifact reviewer after branch/Ink generation and before acceptance. The reviewer audits fake variables, cosmetic choices, missing state reads, fake folds, unearned convergence, state-named-instead-of-checked prose, visual callback gaps, and endings that ignore major state. The first Cold Wake user review is a seed failure taxonomy for this evaluator path.
    - The older Cold Wake v0/v1 fragments remain diagnostic seam tests around the clinic climax, not the accepted clean fixture.

state/evidence.jsonl

@@ -33,3 +33,4 @@
 {"ts": "2026-05-02T22:14:22+00:00", "type": "review", "status": "ok", "note": "Revised Cold Wake IF scaffold after user review: heat_time, evidence_quality, provisional_category, clinic_exhaustion, and trust now change choice availability, clinic prose, visual modifiers, and final outcome texture instead of acting as set dressing."}
 {"ts": "2026-05-02T22:15:47+00:00", "type": "review", "status": "ok", "note": "Revised Cold Wake IF scaffold again after user review: authority_pressure now creates concrete PSC audit/sanction consequences, can make strong evidence unsafe without provisional_category, and appears in visual/climax modifiers."}
 {"ts": "2026-05-02T22:29:00+00:00", "type": "design", "status": "ok", "note": "IF artifact reviewer required before acceptance to catch Potemkin state variables, cosmetic choices, fake folds, missing state reads, state-named-instead-of-checked prose, visual callback gaps, and endings that ignore major state."}
+{"ts": "2026-05-02T22:30:27+00:00", "type": "design", "status": "ok", "note": "Branch Compiler documented as a separate organ: it materializes playable Ink, sidecars, fold/callback structure, and visual handles from fixture state and reviewed consequence packets, without owning hidden character truth or durable social mutation."}

state/map.yaml

@@ -61,6 +61,9 @@ live_architecture:
   coordinator:
     - The coordinator is a trainable soft organ: it stages scenes, chooses next beats and acting agents, invokes specialist machinery, carries unresolved hooks, emits glue prose, and proposes game-engine-shaped state changes.
     - Glue prose is training signal, not canonical truth.
+  branch_compiler:
+    - The branch compiler turns fixture briefs, lore digests, scene/world state, actor-local branch candidates, reviewed consequence packets, fold plans, and visual continuity requirements into playable Ink plus training sidecars and compiler notes.
+    - The branch compiler owns playable structure, conditionals, variables, callbacks, fold materialization, and image prompt handles; it does not own hidden character truth, participant appraisal, or durable social mutation.
   training_targets:
     - Coordinator/story runtime
     - Memory and lore retrieval
@@ -69,6 +72,7 @@ live_architecture:
     - Participant appraiser
     - State mutator
     - Relationship/perception updater
+    - Branch compiler for Ink materialization, fold/callback structure, sidecar generation, and visual prompt handles
     - Interactive-fiction artifact reviewer for fake variables, cosmetic choices, missing state reads, fake folds, and visual callback gaps
     - Human-facing appraisal and opinion model for VoidBot
     - Evaluator/review classifiers