Wire TOTEM skill scoring to dashboard metrics

app.py

@@ -5,6 +5,7 @@ import html
 import json
 import os
 import re
+import datetime
 from shutil import copy2
 from html import escape
 from pathlib import Path
@@ -36,6 +37,7 @@ from src.totem_bridge import (
     extract_workbook_matrix,
     recompute_gate,
     run_totem_skill,
+    SCORE_FIELDS,
 )
 from smoke_signal_tab import smoke_signal_tab, SS_CSS
 
@@ -1217,13 +1219,13 @@ TOTEM_CSS = """
 
 .totem-shell .totem-row {
   display: grid;
-  grid-template-columns: repeat(5, minmax(0, 1fr));
-  gap: var(--space-3);
+  grid-template-columns: repeat(6, minmax(0, 1fr));
+  gap: 10px;
 }
 
 .totem-metric-card {
-  min-height: 178px;
-  padding: 18px;
+  min-height: 168px;
+  padding: 14px;
   border-radius: 14px;
   background: linear-gradient(180deg, rgba(16, 26, 58, 0.96), rgba(8, 18, 45, 0.98));
   border: 1px solid rgba(174, 183, 204, 0.3);
@@ -1232,60 +1234,60 @@ TOTEM_CSS = """
 
 .totem-metric-head {
   display: grid;
-  grid-template-columns: 56px 1fr;
-  gap: 12px;
+  grid-template-columns: 48px 1fr;
+  gap: 10px;
   align-items: center;
 }
 
 .totem-metric-icon {
-  width: 56px;
-  height: 56px;
+  width: 48px;
+  height: 48px;
   border-radius: 999px;
   display: grid;
   place-items: center;
   color: #fff;
-  font-size: 24px;
+  font-size: 21px;
   background: rgba(7, 18, 45, 0.45);
   border: 1px solid var(--metric-color);
   box-shadow: 0 0 22px color-mix(in srgb, var(--metric-color), transparent 55%);
 }
 
 .totem-metric-label {
-  font-size: 14px;
+  font-size: 13px;
   color: rgba(246, 241, 232, 0.95);
 }
 
 .totem-metric-score {
   margin-top: 12px;
-  font-size: 42px;
+  font-size: 38px;
   line-height: 1;
   color: var(--metric-color);
   font-variant-numeric: tabular-nums;
 }
 
 .totem-metric-score small {
-  font-size: 17px;
+  font-size: 15px;
   color: rgba(174, 183, 204, 0.95);
 }
 
 .totem-metric-bars {
   display: flex;
   align-items: end;
-  gap: 6px;
-  height: 32px;
-  margin-top: 14px;
+  gap: 4px;
+  height: 30px;
+  margin-top: 12px;
 }
 
 .totem-metric-bars span {
-  width: 4px;
+  width: 3px;
   border-radius: 3px 3px 0 0;
   background: var(--metric-color);
   opacity: .95;
 }
 
 .totem-metric-hint {
-  margin-top: 12px;
-  font-size: 12px;
+  margin-top: 10px;
+  font-size: 11px;
   color: rgba(174, 183, 204, 0.98);
 }
 
@@ -1497,6 +1499,7 @@ DASHBOARD_STATE_KEYS = (
     "project_name",
     "workbook_loaded",
     "analysis_status",
+    "dashboard_message",
     "last_analysis_at",
     "totem_signal",
     "metrics",
@@ -1547,11 +1550,12 @@ def compute_totem_signal(
         return 35
 
     weights = {
-        "overall_publishability": 0.30,
-        "read_aloud_flow": 0.15,
-        "emotional_truth": 0.20,
-        "visual_strength": 0.20,
-        "commercial_viability": 0.15,
+        "clarity": 0.16,
+        "rhythm": 0.14,
+        "read_aloud_flow": 0.18,
+        "emotional_truth": 0.18,
+        "visual_strength": 0.16,
+        "commercial_viability": 0.18,
     }
 
     total = 0.0
@@ -1566,27 +1570,16 @@ def get_initial_dashboard_state() -> dict:
     Stage 2 state contract.
     Placeholder values are deliberate before first analysis run.
     """
-    metrics = {
-        "overall_publishability": 0,
-        "read_aloud_flow": 0,
-        "emotional_truth": 0,
-        "visual_strength": 0,
-        "commercial_viability": 0,
-    }
+    metrics = {key: 0 for key in SCORE_FIELDS}
     return {
         "project_name": "Editorial Workspace",
         "workbook_loaded": False,
         "analysis_status": "idle",  # idle | ready | running | complete | error
+        "dashboard_message": "",
         "last_analysis_at": None,
         "totem_signal": compute_totem_signal(metrics, workbook_loaded=False, analysis_timestamp=None),
         "metrics": metrics,
-        "metric_history": {
-            "overall_publishability": [],
-            "read_aloud_flow": [],
-            "emotional_truth": [],
-            "visual_strength": [],
-            "commercial_viability": [],
-        },
+        "metric_history": {key: [] for key in SCORE_FIELDS},
         "revision_queue": [],
         "risk_clusters": [],
     }
@@ -1610,6 +1603,7 @@ def normalize_dashboard_state(raw_existing_outputs) -> dict:
     if status not in {"idle", "ready", "running", "complete", "error"}:
         status = state["analysis_status"]
     state["analysis_status"] = status
+    state["dashboard_message"] = str(raw_existing_outputs.get("dashboard_message") or state["dashboard_message"]).strip()
 
     ts_value = raw_existing_outputs.get("last_analysis_at")
     state["last_analysis_at"] = str(ts_value).strip() if ts_value else None
@@ -1853,7 +1847,7 @@ def render_status_row(state: dict) -> str:
         "error": "TOTEM analysis error. Review logs and retry.",
     }
     css_state = status if status in {"ready", "running", "complete", "error"} else "ready"
-    message = esc(text_by_status.get(status, text_by_status["ready"]))
+    message = esc(state.get("dashboard_message") or text_by_status.get(status, text_by_status["ready"]))
     return f"""
     <section class="totem-status-row state-{css_state}">
       <div>{message}</div>
@@ -1882,8 +1876,9 @@ def render_metric_cards(state: dict) -> str:
     metrics = state.get("metrics", {}) if isinstance(state, dict) else {}
     history = state.get("metric_history", {}) if isinstance(state, dict) else {}
     card_defs = [
-        ("overall_publishability", "Overall Publishability", "✦", "var(--totem-gold)", "Source: viability lens"),
-        ("read_aloud_flow", "Read-Aloud Flow", "≋", "var(--totem-pink)", "Weakest live pressure"),
+        ("clarity", "Clarity", "✦", "var(--totem-gold)", "Clean story signal"),
+        ("rhythm", "Rhythm", "▰", "var(--totem-warning)", "Beat and cadence"),
+        ("read_aloud_flow", "Read-Aloud Flow", "≋", "var(--totem-pink)", "Mouth-feel pressure"),
         ("emotional_truth", "Emotional Truth", "❤", "var(--totem-emerald)", "Strongest story signal"),
         ("visual_strength", "Visual Strength", "◉", "var(--totem-cyan)", "Drawable page value"),
         ("commercial_viability", "Commercial Viability", "↗", "var(--totem-violet)", "Publisher-facing lens"),
@@ -2940,6 +2935,7 @@ def _build_dashboard_state_from_workbook(path: Path, status: str, notice: str =
     state["analysis_status"] = status
     state["workbook_loaded"] = path.exists()
     state["project_name"] = "Editorial Workspace"
+    state["dashboard_message"] = notice or ""
     state["last_analysis_at"] = datetime.datetime.now().isoformat(timespec="seconds") if status == "complete" else None
 
     if path.exists():
@@ -2947,7 +2943,8 @@ def _build_dashboard_state_from_workbook(path: Path, status: str, notice: str =
             log_df = score_log(path)
             if log_df is not None and not log_df.empty:
                 for key, col in [
-                    ("overall_publishability", "Commercial Publishability"),
+                    ("clarity", "Clarity"),
+                    ("rhythm", "Rhythm"),
                     ("read_aloud_flow", "Read-aloud Flow"),
                     ("emotional_truth", "Emotional Truth"),
                     ("visual_strength", "Visual Strength"),
@@ -3063,6 +3060,21 @@ def run_analysis(active_path: str):
     return render_dashboard(state), log_df, _score_summary(log_df)
 
 
+def _dashboard_error_response(active_path: str, message: str, error_detail: str):
+    try:
+        path = _validate_workbook_path(Path(active_path) if active_path else _preferred_workbook_path())
+        log_df = score_log(path)
+        state = _build_dashboard_state_from_workbook(path, "error", message)
+        summary = _score_summary(log_df)
+    except Exception:
+        state = get_initial_dashboard_state()
+        state["analysis_status"] = "error"
+        state["dashboard_message"] = message
+        log_df = pd.DataFrame(columns=LOG_COLUMNS)
+        summary = "Dashboard analysis blocked."
+    return render_dashboard(state), log_df, summary, json.dumps({"status": "error", "error": error_detail}, indent=2)
+
+
 def _apply_llm_dashboard_state(
     *,
     active_path: str,
@@ -3071,25 +3083,21 @@ def _apply_llm_dashboard_state(
 ) -> tuple[str, pd.DataFrame, str, str]:
     path = _validate_workbook_path(Path(active_path) if active_path else _preferred_workbook_path())
     log_df = score_log(path)
-    state = _build_dashboard_state_from_workbook(path, "complete", notice)
-    state["metrics"]["overall_publishability"] = int(llm_state["overall_publishability"])
-    state["metrics"]["read_aloud_flow"] = int(llm_state["read_aloud_flow"])
-    state["metrics"]["emotional_truth"] = int(llm_state["emotional_truth"])
-    state["metrics"]["visual_strength"] = int(llm_state["visual_strength"])
-    state["metrics"]["commercial_viability"] = int(llm_state["commercial_visibility"])
+    state = _build_dashboard_state_from_workbook(path, "complete", llm_state.get("dashboard_message") or notice)
+    scores = llm_state.get("scores") if isinstance(llm_state.get("scores"), dict) else llm_state
+    for key in SCORE_FIELDS:
+        state["metrics"][key] = int(scores[key])
     state["revision_queue"] = list(llm_state.get("revision_priority_queue") or [])
     state["risk_clusters"] = list(llm_state.get("risk_clusters") or [])
     state["analysis_status"] = "complete"
+    state["last_analysis_at"] = datetime.datetime.now().isoformat(timespec="seconds")
+    state["totem_signal"] = compute_totem_signal(
+        state["metrics"],
+        workbook_loaded=state["workbook_loaded"],
+        analysis_timestamp=state["last_analysis_at"],
+    )
     if os.getenv("TOTEM_RECOMPUTE_GATES", "1").strip() not in {"0", "false", "False"}:
-        recomputed = recompute_gate(
-            {
-                "read_aloud_flow": state["metrics"]["read_aloud_flow"],
-                "emotional_truth": state["metrics"]["emotional_truth"],
-                "visual_strength": state["metrics"]["visual_strength"],
-                "commercial_visibility": state["metrics"]["commercial_viability"],
-            },
-            extract_workbook_matrix(path),
-        )
+        recomputed = recompute_gate(state["metrics"], extract_workbook_matrix(path))
         gate_summary = f"Gate={llm_state.get('gate','REVISE')} | Recomputed={recomputed}"
     else:
         gate_summary = f"Gate={llm_state.get('gate','REVISE')}"
@@ -3161,8 +3169,11 @@ def run_totem_analysis_from_context(active_path: str, manuscript_context_json: s
     - validated JSON updates dashboard
     """
     if not manuscript_context_json:
-        dashboard_html, log_df, summary = run_analysis(active_path)
-        return dashboard_html, log_df, summary, "No manuscript context found. Ran workbook-only refresh."
+        return _dashboard_error_response(
+            active_path,
+            "Upload a manuscript first, then run TOTEM Analysis.",
+            "No manuscript context found.",
+        )
 
     try:
         ctx_payload = json.loads(manuscript_context_json)
@@ -3196,12 +3207,18 @@ def run_totem_analysis_from_context(active_path: str, manuscript_context_json: s
             "manuscript_words": debug.get("word_count"),
             "manuscript_path": ctx.path,
             "rubric_metrics": len(rubric.get("metrics", [])),
+            "skill_loaded": debug.get("skill_loaded"),
+            "skill_path": debug.get("skill_path"),
+            "schema_pass": debug.get("schema_pass"),
+            "score_fields": list(SCORE_FIELDS),
         }
         return dashboard_html, log_df, summary, json.dumps(debug_log, indent=2)
     except Exception as exc:
-        dashboard_html, log_df, summary = run_analysis(active_path)
-        debug_log = {"status": "error", "error": f"{type(exc).__name__}: {exc}"}
-        return dashboard_html, log_df, summary, json.dumps(debug_log, indent=2)
+        return _dashboard_error_response(
+            active_path,
+            "TOTEM analysis error. Review Bridge Diagnostics and retry.",
+            f"{type(exc).__name__}: {exc}",
+        )
 
 
 def recalc_log(log_df, active_path: str):
@@ -3258,7 +3275,7 @@ with gr.Blocks(title="TOTEM Studio") as demo:
                 "border:1px solid rgba(242,193,78,.35);border-radius:10px;"
                 "background:rgba(10,22,45,.85);color:#f6f1e8;font-size:13px;'>"
                 "<b>Mode:</b> Draft Mode (ORDER_91) keeps manuscript extraction separate from scoring. "
-                "Only <b>Run TOTEM Analysis</b> updates the 5 scoring metrics. "
+                "Only <b>Run TOTEM Analysis</b> updates the 6 scoring metrics. "
                 "<span style='opacity:.95;color:#8df0b5;font-weight:700'>BRIDGE ACTIVE</span> · "
                 "<span style='opacity:.8'>Build: 668ed10</span>"
                 "</div>"

data/skills/TOTEM_Manuscript_Scoring_Skill.md

@@ -0,0 +1,70 @@
+# TOTEM Manuscript Scoring Skill
+
+## Purpose
+Turn any uploaded children's picture-book manuscript into a polished, branded TOTEM Studio assessment document without the user needing to retype the full context each time.
+
+## User trigger phrases
+Run this workflow when the user says any of the following:
+- “TOTEM score this”
+- “Score my manuscript”
+- “Run a TOTEM snapshot”
+- “Turn this into a professional report”
+- “Assess this with the Henry / TOTEM metrics”
+
+## Required inputs
+1. The manuscript file or manuscript text.
+2. Optional: title, author name, target age band, intended page count, and publishing route.
+3. Optional: brand image/assets. If absent, use the saved TOTEM Studio brand system below.
+
+## Brand system
+- Brand: TOTEM Studio — Story Intelligence OS.
+- Brand essence: magical, intelligent, imaginative, premium.
+- Voice: wonder-driven, insightful, trustworthy, inventive.
+- Colours:
+  - Midnight Navy #07122D
+  - Story Gold #F2C14E
+  - Enchanted Violet #8A4DFF
+  - Pixie Pink #FF5FD2
+  - Emerald Tale #22B573
+  - Celestial Cyan #39C9FF
+  - Moonlight Ivory #F6F1E8
+- Visual rule: dark premium background, gold section rules, restrained sparkle/stardust accents, clean typography.
+- Logo rule: use full logo on cover, icon mark for headers/dividers, horizontal lockup for back page or footer where useful.
+
+## TOTEM scoring dimensions
+Score each dimension from 1–10, with clear acceptance risk and rewrite priority:
+1. Clarity
+2. Rhythm
+3. Read-aloud flow
+4. Emotional truth
+5. Visual strength
+6. Commercial viability
+
+## Assessment method
+1. Read the manuscript fully before scoring.
+2. Identify the core emotional promise and the likely market/category.
+3. Score each TOTEM dimension using evidence from the manuscript.
+4. Identify the strongest commercial asset.
+5. Identify the largest acceptance blocker.
+6. Produce targeted rewrite directives, not generic feedback.
+7. Include a block-level pressure map where useful.
+8. End with a practical rewrite roadmap.
+
+## Output rule
+Do not dump the full report into chat. Create a professionally formatted DOCX using the TOTEM branded template. The chat response should only include a short confirmation and the download link.
+
+## Required report structure
+1. Cover / brand title page
+2. Executive verdict
+3. TOTEM metric score table
+4. Dimension-by-dimension analysis
+5. Acceptance blocker summary
+6. Block-level pressure map
+7. Rewrite roadmap
+8. Optional appendix for manuscript notes
+
+## Quality standard
+Clarity, rhythm, read-aloud flow, emotional truth, visual strength, and commercial publishability are non-negotiable. Prioritise publishability over cleverness. Be direct, commercial, and useful.
+
+## Safety / rights rule
+Do not include long copyrighted excerpts from outside sources. Do not mix controlled samples, public-domain samples, or user manuscript text unless the user has clearly supplied the manuscript for assessment.

src/totem_bridge.py

@@ -12,6 +12,31 @@ from src.codex_extractor import clean_text, extract_text_from_file
 from src.totem_workbook import METRICS, protocol_table, protocol_weights
 
 
+APP_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_SKILL_PATH = APP_ROOT / "data" / "skills" / "TOTEM_Manuscript_Scoring_Skill.md"
+
+SCORE_FIELDS = (
+    "clarity",
+    "rhythm",
+    "read_aloud_flow",
+    "emotional_truth",
+    "visual_strength",
+    "commercial_viability",
+)
+
+SCORE_LABELS = {
+    "clarity": "Clarity",
+    "rhythm": "Rhythm",
+    "read_aloud_flow": "Read-aloud Flow",
+    "emotional_truth": "Emotional Truth",
+    "visual_strength": "Visual Strength",
+    "commercial_viability": "Commercial Viability",
+}
+
+VALID_GATES = {"HARD FAIL", "SOFT FAIL", "READ-ALOUD BLOCK", "COMMERCIAL CHECK", "GREENLIGHT", "REVISE"}
+VALID_RISKS = {"High Risk", "Medium Risk", "Low Risk"}
+
+
 class BridgeError(RuntimeError):
     pass
 
@@ -58,7 +83,7 @@ def extract_workbook_matrix(path: Path) -> dict[str, Any]:
     return {
         "weights": {k: float(v) for k, v in weights.items()},
         "metrics": metric_rows,
-        "gate_labels": ["HARD FAIL", "SOFT FAIL", "READ-ALOUD BLOCK", "COMMERCIAL CHECK", "GREENLIGHT", "REVISE"],
+        "gate_labels": sorted(VALID_GATES),
     }
 
 
@@ -75,11 +100,61 @@ def extract_manuscript_context(file_path: str | Path) -> ManuscriptContext:
     )
 
 
+def load_totem_skill(skill_path: str | Path | None = None) -> tuple[str, str]:
+    path = Path(skill_path or os.getenv("TOTEM_SKILL_PATH") or DEFAULT_SKILL_PATH)
+    if not path.exists():
+        raise BridgeError(f"TOTEM scoring skill not found: {path}")
+    text = path.read_text(encoding="utf-8").strip()
+    if not text:
+        raise BridgeError(f"TOTEM scoring skill is empty: {path}")
+    return text, str(path)
+
+
+def dashboard_output_contract() -> dict[str, Any]:
+    return {
+        "scores": {field: "integer 0..100" for field in SCORE_FIELDS},
+        "gate": "HARD FAIL | SOFT FAIL | READ-ALOUD BLOCK | COMMERCIAL CHECK | GREENLIGHT | REVISE",
+        "weakest_metric": "one of: Clarity, Rhythm, Read-aloud Flow, Emotional Truth, Visual Strength, Commercial Viability",
+        "dashboard_message": "short dashboard status message, max 220 characters",
+        "revision_priority_queue": [
+            {
+                "block": "short block/page/section identifier",
+                "weakest_dimension": "scoring dimension name",
+                "gate": "gate label",
+                "priority": "High | Medium | Low",
+                "recommended_action": "specific rewrite action, max 240 characters",
+            }
+        ],
+        "risk_clusters": [
+            {
+                "name": "risk cluster name",
+                "risk": "High Risk | Medium Risk | Low Risk",
+                "summary": "short evidence-based risk summary",
+            }
+        ],
+        "evidence_summary": "brief evidence summary, max 500 characters",
+    }
+
+
 def run_totem_skill(
     *,
     rubric_matrix: dict[str, Any],
     manuscript: ManuscriptContext,
 ) -> tuple[dict[str, Any], dict[str, Any]]:
+    skill_text, skill_path = load_totem_skill()
+
+    if _env_truthy("TOTEM_FAKE_API"):
+        raw_payload = _fake_dashboard_payload(manuscript)
+        validated = validate_dashboard_payload(raw_payload)
+        return validated, {
+            "model": "fake-audit",
+            "word_count": manuscript.word_count,
+            "raw_response_chars": len(json.dumps(raw_payload)),
+            "skill_path": skill_path,
+            "skill_loaded": True,
+            "schema_pass": True,
+        }
+
     api_key = os.getenv("OPENAI_API_KEY")
     if not api_key:
         raise BridgeError("OPENAI_API_KEY is not configured.")
@@ -89,41 +164,28 @@ def run_totem_skill(
     model = os.getenv("TOTEM_OPENAI_MODEL", "gpt-4.1-mini")
     client = OpenAI(api_key=api_key)
 
-    system_prompt = (
-        "You are the hidden TOTEM Analysis skill. "
-        "Return strict JSON only with no markdown. "
-        "Use workbook matrix as scoring authority and manuscript text as evidence."
-    )
+    system_prompt = f"""
+You are the hidden TOTEM Analysis skill inside TOTEM Studio.
+Use the skill instructions below as the scoring method, but do not create a DOCX report for this dashboard run.
+Return strict JSON only. No prose. No markdown. No code fences.
+Use the workbook matrix as scoring authority and manuscript text as evidence.
+
+--- TOTEM SKILL INSTRUCTIONS ---
+{skill_text}
+--- END TOTEM SKILL INSTRUCTIONS ---
+""".strip()
+
     user_payload = {
-        "task": "score_manuscript_against_workbook_matrix",
+        "task": "score_manuscript_against_workbook_matrix_for_dashboard",
         "rubric_matrix": rubric_matrix,
         "manuscript_cleaned_text": manuscript.cleaned_text,
-        "required_output_contract": {
-            "overall_publishability": "int 0..100",
-            "read_aloud_flow": "int 0..100",
-            "emotional_truth": "int 0..100",
-            "visual_strength": "int 0..100",
-            "commercial_visibility": "int 0..100",
-            "gate": "string",
-            "weakest_metric": "string",
-            "dashboard_message": "string",
-            "revision_priority_queue": [
-                {
-                    "block": "string",
-                    "weakest_dimension": "string",
-                    "gate": "string",
-                    "priority": "string",
-                    "recommended_action": "string",
-                }
-            ],
-            "risk_clusters": [
-                {
-                    "name": "string",
-                    "risk": "High Risk | Medium Risk | Low Risk",
-                    "summary": "string",
-                }
-            ],
-        },
+        "scoring_dimensions": SCORE_LABELS,
+        "required_output_contract": dashboard_output_contract(),
+        "instruction": (
+            "Return exactly one JSON object matching required_output_contract. "
+            "Scores must be 0..100 dashboard values for the six dimensions. "
+            "Do not write a report and do not include manuscript excerpts."
+        ),
     }
 
     resp = client.chat.completions.create(
@@ -146,17 +208,30 @@ def run_totem_skill(
         "model": model,
         "word_count": manuscript.word_count,
         "raw_response_chars": len(raw),
+        "skill_path": skill_path,
+        "skill_loaded": True,
+        "schema_pass": True,
     }
     return validated, debug
 
 
 def validate_dashboard_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise BridgeValidationError("Dashboard payload must be a JSON object.")
+
+    scores = payload.get("scores")
+    if not isinstance(scores, dict):
+        # Backward-compatible normalization for older flat model responses.
+        scores = {
+            "clarity": payload.get("clarity"),
+            "rhythm": payload.get("rhythm"),
+            "read_aloud_flow": payload.get("read_aloud_flow"),
+            "emotional_truth": payload.get("emotional_truth"),
+            "visual_strength": payload.get("visual_strength"),
+            "commercial_viability": payload.get("commercial_viability", payload.get("commercial_visibility")),
+        }
+
     required = [
-        "overall_publishability",
-        "read_aloud_flow",
-        "emotional_truth",
-        "visual_strength",
-        "commercial_visibility",
         "gate",
         "weakest_metric",
         "dashboard_message",
@@ -167,16 +242,22 @@ def validate_dashboard_payload(payload: dict[str, Any]) -> dict[str, Any]:
     if missing:
         raise BridgeValidationError(f"Missing required output fields: {', '.join(missing)}")
 
+    missing_scores = [field for field in SCORE_FIELDS if field not in scores or scores.get(field) in (None, "")]
+    if missing_scores:
+        raise BridgeValidationError(f"Missing required score fields: {', '.join(missing_scores)}")
+
+    gate = str(payload.get("gate") or "REVISE").strip().upper()
+    if gate not in VALID_GATES:
+        gate = "REVISE"
+
     out = {
-        "overall_publishability": _clamp_score(payload["overall_publishability"]),
-        "read_aloud_flow": _clamp_score(payload["read_aloud_flow"]),
-        "emotional_truth": _clamp_score(payload["emotional_truth"]),
-        "visual_strength": _clamp_score(payload["visual_strength"]),
-        "commercial_visibility": _clamp_score(payload["commercial_visibility"]),
-        "gate": str(payload.get("gate") or "REVISE").strip()[:48],
+        "scores": {field: _clamp_score(scores[field]) for field in SCORE_FIELDS},
+        "gate": gate,
         "weakest_metric": str(payload.get("weakest_metric") or "Read-aloud Flow").strip()[:80],
         "dashboard_message": str(payload.get("dashboard_message") or "").strip()[:280],
+        "evidence_summary": str(payload.get("evidence_summary") or "").strip()[:500],
     }
+    out.update(out["scores"])
 
     rpq = payload.get("revision_priority_queue")
     if not isinstance(rpq, list):
@@ -196,17 +277,15 @@ def recompute_gate(metrics: dict[str, int], rubric_matrix: dict[str, Any]) -> st
         return "REVISE"
 
     metric_key_map = {
-        "Clarity": None,
-        "Rhythm": None,
+        "Clarity": "clarity",
+        "Rhythm": "rhythm",
         "Read-aloud Flow": "read_aloud_flow",
         "Emotional Truth": "emotional_truth",
         "Visual Strength": "visual_strength",
-        "Commercial Publishability": "commercial_visibility",
+        "Commercial Publishability": "commercial_viability",
     }
     scores = []
     for label, key in metric_key_map.items():
-        if key is None:
-            continue
         score = float(metrics.get(key, 0))
         w = float(weights.get(label, 0.0))
         scores.append((label, score, w))
@@ -216,11 +295,18 @@ def recompute_gate(metrics: dict[str, int], rubric_matrix: dict[str, Any]) -> st
     weighted = sum(s * w for _, s, w in scores)
     low = min(s for _, s, _ in scores)
     low_count = sum(1 for _, s, _ in scores if s <= 60)
+    rhythm = float(metrics.get("rhythm", 0))
+    flow = float(metrics.get("read_aloud_flow", 0))
+    commercial = float(metrics.get("commercial_viability", 0))
 
     if low <= 40:
         return "HARD FAIL"
     if low_count >= 2:
         return "SOFT FAIL"
+    if rhythm < 70 or flow < 70:
+        return "READ-ALOUD BLOCK"
+    if commercial < 70:
+        return "COMMERCIAL CHECK"
     if weighted >= 80 and low >= 70:
         return "GREENLIGHT"
     return "REVISE"
@@ -229,16 +315,16 @@ def recompute_gate(metrics: dict[str, int], rubric_matrix: dict[str, Any]) -> st
 def _normalize_queue_item(item: Any) -> dict[str, str]:
     if not isinstance(item, dict):
         return {
-            "block": "—",
+            "block": "-",
             "weakest_dimension": "Read-aloud Flow",
-            "gate": "Soft Fail",
+            "gate": "REVISE",
             "priority": "Medium",
             "recommended_action": "Review and revise.",
         }
     return {
-        "block": str(item.get("block") or "—").strip()[:48],
+        "block": str(item.get("block") or "-").strip()[:48],
         "weakest_dimension": str(item.get("weakest_dimension") or "Read-aloud Flow").strip()[:80],
-        "gate": str(item.get("gate") or "Soft Fail").strip()[:48],
+        "gate": str(item.get("gate") or "REVISE").strip()[:48],
         "priority": str(item.get("priority") or "Medium").strip()[:24],
         "recommended_action": str(item.get("recommended_action") or "Review and revise.").strip()[:280],
     }
@@ -253,7 +339,7 @@ def _normalize_cluster_item(item: Any) -> dict[str, Any]:
             "sparkline": [8, 10, 9, 11, 12, 10, 9, 11],
         }
     risk = str(item.get("risk") or "Medium Risk").strip()
-    if risk not in {"High Risk", "Medium Risk", "Low Risk"}:
+    if risk not in VALID_RISKS:
         risk = "Medium Risk"
     return {
         "name": str(item.get("name") or "Risk").strip()[:60],
@@ -263,6 +349,50 @@ def _normalize_cluster_item(item: Any) -> dict[str, Any]:
     }
 
 
+def _fake_dashboard_payload(manuscript: ManuscriptContext) -> dict[str, Any]:
+    word_count = max(1, manuscript.word_count)
+    base = max(45, min(88, 62 + (word_count // 160)))
+    long_sentence_penalty = 8 if word_count > 850 else 3
+    return {
+        "scores": {
+            "clarity": max(0, min(100, base - long_sentence_penalty)),
+            "rhythm": max(0, min(100, base - 11)),
+            "read_aloud_flow": max(0, min(100, base - 7)),
+            "emotional_truth": max(0, min(100, base + 5)),
+            "visual_strength": max(0, min(100, base + 8)),
+            "commercial_viability": max(0, min(100, base + 1)),
+        },
+        "gate": "REVISE",
+        "weakest_metric": "Rhythm",
+        "dashboard_message": "TOTEM analysis complete using fake audit response.",
+        "revision_priority_queue": [
+            {
+                "block": "Opening third",
+                "weakest_dimension": "Rhythm",
+                "gate": "REVISE",
+                "priority": "High",
+                "recommended_action": "Run a read-aloud pass and cut any line that stalls the beat.",
+            },
+            {
+                "block": "Middle turn",
+                "weakest_dimension": "Clarity",
+                "gate": "REVISE",
+                "priority": "Medium",
+                "recommended_action": "Clarify the character action before adding extra comic business.",
+            },
+        ],
+        "risk_clusters": [
+            {"name": "Rhythm", "risk": "High Risk", "summary": "Read-aloud pressure likely clusters around longer lines."},
+            {"name": "Clarity", "risk": "Medium Risk", "summary": "Some manuscript beats may need cleaner cause and effect."},
+        ],
+        "evidence_summary": f"Fake audit used {word_count} manuscript words.",
+    }
+
+
+def _env_truthy(name: str) -> bool:
+    return str(os.getenv(name, "")).strip().lower() in {"1", "true", "yes", "on"}
+
+
 def _safe_float(value: Any) -> float | None:
     try:
         if value is None or value == "":