Document IF artifact reviewer

docs/architecture/ink-branching-scenes.md

@@ -232,6 +232,91 @@ 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.
 
+## IF Artifact Review
+
+Branching fixtures need an independent review pass before acceptance. The
+coordinator should not be the only thing grading its own Ink, sidecar, and
+branch logic. That is how a scene ends up proudly tracking variables that do
+nothing except sit there in a tiny uniform.
+
+The reviewer may start as a prompted specialist sub-agent. Later it should
+become evaluator/classifier training data and eventually a trainable review
+organ. Its job is not prose polish. Its job is to catch false consequence.
+
+The reviewer receives:
+
+- the Ink file
+- the `.training.json` sidecar
+- the coordinator artifact
+- the intended branch plan, when available
+- the declared state variables, flags, bands, resources, risks, and visual
+  modifiers
+- any compiled Ink or validation output available for the fixture
+
+The reviewer emits:
+
+- `accepted`, `needs_revision`, or `rejected`
+- severity-ranked findings
+- a fake-variable audit
+- a choice-consequence audit
+- a fold/callback audit
+- a state-gated prose audit
+- a visual-continuity audit
+- major-route-split justification notes
+- specific required fixes
+
+Acceptance requires every material choice to change at least one later surface:
+
+- available options
+- scene route or justified route split
+- relationship, trust, appraisal, or social standing
+- resource cost, time pressure, legal exposure, authority pressure, heat burden,
+  exhaustion, or other risk
+- object custody, evidence quality, access, or technology state
+- later callback prose implemented as an actual conditional
+- ending texture or outcome band
+- visual state modifier tied to a real branch flag or state variable
+
+Every declared variable must either be read later or be marked as telemetry-only
+in the sidecar. Ominous variables need threshold behavior. If a variable named
+`authority_pressure` rises and nobody with authority ever reacts, the artifact
+fails review. If `heat_time` counts down and no route, ending, resource cost, or
+staff condition changes, the artifact fails review. The name is allowed to be
+dramatic only if the machinery has teeth.
+
+Any prose that says "if X happened" must be implemented as an actual conditional
+or moved into reviewer/coordinator notes. Writer-facing text should not name a
+branch possibility while dodging the state check that proves which version of
+history occurred.
+
+Common failure labels:
+
+- `potemkin_state`: a tracked variable never materially changes the artifact
+- `cosmetic_choice`: a choice changes wording but not affordance, cost, risk,
+  appraisal, callback, visual state, or outcome
+- `missing_state_read`: a set variable is never read by later Ink, sidecar, or
+  coordinator consequence logic
+- `fake_fold`: branches claim to fold, but the folded scene ignores their state
+- `unearned_convergence`: branches converge despite consequences that should
+  make convergence false
+- `unjustified_route_split`: a separate route exists without enough world or
+  story consequence to justify the writing debt
+- `state_named_instead_of_checked`: prose mentions alternate branch states
+  instead of checking variables
+- `visual_callback_missing`: image modifiers or visual prose ignore branch
+  consequences that should be visible
+- `authority_without_consequence`: institutional pressure rises but never bites
+- `resource_without_cost`: ledgers, heat, staff time, supplies, or access are
+  invoked without affecting later choices or outcomes
+- `ending_ignores_major_state`: the ending does not respond to major variables
+  established earlier
+
+The first Cold Wake branch-and-fold review exposed this exact class of failure:
+`heat_time`, `clinic_exhaustion`, `evidence_quality`, `provisional_category`,
+and `authority_pressure` initially looked important before review forced them
+to alter gates, callbacks, and outcomes. That review belongs in the evaluator
+training seed, not in a shame drawer. Shame drawers have terrible indexing.
+
 ## Scene Imagery
 
 Ghostlight scenes are also website content. A complete fixture should emit

notes/ghostlight-implementation-plan.md

@@ -40,6 +40,7 @@ sandboxed training-data pipeline for branching scenes and state consequences.
    - 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.
    - 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.
 
    - Still emit training artifacts at material turns: projected local context, responder packet, raw output/capture, leakage audit, reviewed mutation receipt, and aftermath state where relevant.

state/evidence.jsonl

@@ -32,3 +32,4 @@
 {"ts": "2026-05-02T17:12:51+00:00", "type": "implementation", "status": "ok", "note": "Created clean Cold Wake branch-and-fold IF scaffold: compiled Ink fixture, training sidecar with visual prompt anchors/modifiers, readable run document, and coordinator artifact. Accepted as coordinator/IF scaffold, not raw responder gold; schema validation passes."}
 {"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."}

state/map.yaml

@@ -40,6 +40,7 @@ hard_boundaries:
   - Elysium futures are branch-local canon indexed by lineage, not single-history Sol facts.
   - Technology exploration must emit game-usable item, component, assembly, supply-chain, compatibility, and provenance data mapped toward Aetheria-Economy.
   - Interactive-fiction fixtures should branch and fold: normalize most consequences into compact state variables and shared-scene conditionals, reserving isolated route splits for major world-changing divergence.
+  - Interactive-fiction fixtures require independent artifact review before acceptance; tracked variables must materially affect later affordances, risk, appraisal, callbacks, visual state, or outcomes, unless explicitly marked telemetry-only.
   - Complete interactive-fiction fixtures must emit visual art direction for website imagery, with one durable base image prompt per scene and additive modification prompts for branch-visible consequences and scene-state changes.
   - Archived local-model prototype runners are receipts and plumbing tests, not the gold-data path.
 
@@ -68,6 +69,7 @@ live_architecture:
     - Participant appraiser
     - State mutator
     - Relationship/perception updater
+    - 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
     - Aetheria-tuned responder