Ground TOTEM scoring in fingerprint evidence

app.py

@@ -244,67 +244,6 @@ footer { display: none !important; }
   display: none !important;
 }
 
-/* ── Private scoring controls — dark themed (Stage 10) ─────────────────── */
-#score-panel {
-  max-width: 1180px;
-  margin: 8px auto 24px auto;
-  padding: 0 18px;
-}
-
-#score-panel > .label-wrap,
-#score-panel > details > summary,
-#score-panel summary {
-  background: rgba(13, 19, 48, 0.95) !important;
-  color: rgba(246, 241, 232, 0.9) !important;
-  border: 1px solid rgba(242, 193, 78, 0.25) !important;
-  border-radius: 10px !important;
-  font-family: var(--font-ui) !important;
-  font-size: 13px !important;
-  padding: 10px 16px !important;
-}
-
-#score-panel .score-card {
-  border: 1px solid rgba(242, 193, 78, 0.18);
-  background: rgba(7, 18, 45, 0.97);
-  border-radius: 10px;
-  padding: 18px;
-}
-
-#score-panel h3 {
-  margin: 0 0 12px 0;
-  font-size: 16px;
-  color: var(--totem-gold);
-  font-family: var(--font-display);
-}
-
-#score-panel button {
-  border-radius: 8px !important;
-  font-weight: 700 !important;
-  background: rgba(138, 77, 255, 0.25) !important;
-  border: 1px solid rgba(138, 77, 255, 0.5) !important;
-  color: #f6f1e8 !important;
-}
-
-#score-panel .wrap {
-  gap: 12px;
-}
-
-#score-panel label,
-#score-panel .block {
-  background: rgba(7, 18, 45, 0.8) !important;
-  border-color: rgba(246, 241, 232, 0.12) !important;
-  color: rgba(246, 241, 232, 0.9) !important;
-  border-radius: 8px !important;
-}
-
-#score-panel input,
-#score-panel textarea {
-  background: rgba(4, 8, 26, 0.9) !important;
-  color: #f6f1e8 !important;
-  border-color: rgba(242, 193, 78, 0.2) !important;
-  border-radius: 6px !important;
-}
-
 /* ── Global Gradio component dark overrides (Stage 9) ──────────────────── */
 .gradio-container input,
 .gradio-container textarea,
@@ -3147,8 +3086,14 @@ def _bridge_verification_notes(debug: dict, llm_state: dict) -> dict:
         warnings.append("Fake audit provider returned these numbers; this should never be enabled on Hugging Face Spaces.")
     if not usage_reported:
         warnings.append("Provider did not report token usage, so API completion cannot be cost-audited from usage fields.")
+    if not debug.get("fingerprint_supplied"):
+        warnings.append("Manuscript fingerprint was not supplied to the API, so scores are not VM-grounded.")
+    elif int(debug.get("fingerprint_metric_count") or 0) < 10:
+        warnings.append("Manuscript fingerprint contains fewer VM metrics than expected; score grounding may be partial.")
     if not str(llm_state.get("evidence_summary") or "").strip():
         warnings.append("Model returned no evidence_summary; score grounding is weak.")
+    if not isinstance(llm_state.get("score_evidence"), dict):
+        warnings.append("Model returned no per-score evidence object; scores cannot be traced to workbook/fingerprint inputs.")
 
     scores = llm_state.get("scores") if isinstance(llm_state.get("scores"), dict) else {}
     rounded_scores = [score for score in scores.values() if isinstance(score, int) and score % 5 == 0]
@@ -3234,10 +3179,20 @@ def analyze_manuscript_for_dashboard(file_obj, active_path: str):
         works_sampled=works_sampled,
     )
     manuscript_ctx = extract_manuscript_context(file_path)
+    try:
+        fingerprint_payload = json.loads(json_out) if json_out else {}
+        if not isinstance(fingerprint_payload, dict):
+            fingerprint_payload = {}
+    except Exception:
+        fingerprint_payload = {}
+    manuscript_ctx.fingerprint = fingerprint_payload
+    manuscript_ctx.fingerprint_report = report
     manuscript_state = {
         "path": manuscript_ctx.path,
         "cleaned_text": manuscript_ctx.cleaned_text,
         "word_count": manuscript_ctx.word_count,
+        "fingerprint": fingerprint_payload,
+        "fingerprint_report": report,
     }
     dashboard_status = (
         f"{status} | Draft Mode active: extraction complete. "
@@ -3267,8 +3222,14 @@ def run_totem_analysis_from_context(active_path: str, manuscript_context_json: s
         if not cleaned_text:
             raise BridgeError("Manuscript cleaned text is empty.")
         ctx_path = str(ctx_payload.get("path") or "").strip()
+        fingerprint_payload = ctx_payload.get("fingerprint")
+        if not isinstance(fingerprint_payload, dict):
+            fingerprint_payload = {}
+        fingerprint_report = str(ctx_payload.get("fingerprint_report") or "")
         if ctx_path and Path(ctx_path).exists():
             ctx = extract_manuscript_context(ctx_path)
+            ctx.fingerprint = fingerprint_payload
+            ctx.fingerprint_report = fingerprint_report
         else:
             ctx = ManuscriptContext(
                 path=ctx_path or "(session)",
@@ -3276,6 +3237,8 @@ def run_totem_analysis_from_context(active_path: str, manuscript_context_json: s
                 cleaned_text=cleaned_text,
                 word_count=len(cleaned_text.split()),
                 page_trace=[],
+                fingerprint=fingerprint_payload,
+                fingerprint_report=fingerprint_report,
             )
 
         path = _validate_workbook_path(Path(active_path) if active_path else _preferred_workbook_path())
@@ -3295,6 +3258,8 @@ def run_totem_analysis_from_context(active_path: str, manuscript_context_json: s
             "api_key_env": debug.get("api_key_env"),
             "manuscript_words": debug.get("word_count"),
             "manuscript_path": ctx.path,
+            "fingerprint_supplied": debug.get("fingerprint_supplied"),
+            "fingerprint_metric_count": debug.get("fingerprint_metric_count"),
             "rubric_metrics": len(rubric.get("metrics", [])),
             "skill_loaded": debug.get("skill_loaded"),
             "skill_path": debug.get("skill_path"),
@@ -3483,26 +3448,6 @@ with gr.Blocks(title="TOTEM Studio") as demo:
                     path_input = gr.Textbox(label="Local workbook path", value=str(_preferred_workbook_path()))
                     path_button = gr.Button("Load Local Path", variant="primary")
 
-            with gr.Accordion("Private scoring controls", open=False, elem_id="score-panel"):
-                gr.HTML("<div class='score-card'><h3>Live Score A Block</h3></div>")
-                with gr.Row():
-                    sequence = gr.Textbox(label="Sequence", value="Live pass")
-                    stanza_id = gr.Textbox(label="Stanza ID", value="New block")
-                    draft_pass = gr.Textbox(label="Draft / Pass", value="First score")
-                with gr.Row():
-                    clarity = gr.Slider(1, 10, value=7, step=0.5, label="Clarity")
-                    rhythm = gr.Slider(1, 10, value=7, step=0.5, label="Rhythm")
-                    flow = gr.Slider(1, 10, value=7, step=0.5, label="Read-aloud Flow")
-                with gr.Row():
-                    emotional_truth = gr.Slider(1, 10, value=7, step=0.5, label="Emotional Truth")
-                    visual_strength = gr.Slider(1, 10, value=7, step=0.5, label="Visual Strength")
-                    commercial = gr.Slider(1, 10, value=7, step=0.5, label="Commercial Publishability")
-                notes = gr.Textbox(label="Notes", lines=2)
-                with gr.Row():
-                    single_button = gr.Button("Score Block", variant="primary")
-                    recalc_button = gr.Button("Recalculate Gates")
-                    export_button = gr.Button("Download Updated Workbook")
-                single_df = gr.Dataframe(label="Latest scorecard", interactive=False, visible=False)
                 score_status = gr.Markdown(elem_id="hidden-status")
                 exported_file = gr.File(label="Export appears here", elem_id="hidden-export")
 
@@ -3660,16 +3605,6 @@ with gr.Blocks(title="TOTEM Studio") as demo:
         outputs=[bridge_diag_log],
         js="""(v) => { if (v) { navigator.clipboard.writeText(v); } return v; }""",
     )
-    recalc_button.click(recalc_log, inputs=[log_state, active_path],
-                        outputs=[dashboard, log_state, score_status])
-    export_button.click(export_log, inputs=[log_state, active_path], outputs=[exported_file])
-    single_button.click(
-        single_score,
-        inputs=[active_path, sequence, stanza_id, draft_pass, clarity, rhythm,
-                flow, emotional_truth, visual_strength, commercial, notes],
-        outputs=[single_df, score_status],
-    )
-
     # Codex Extractor tab
     codex_extract_btn.click(
         run_codex_extraction,

src/totem_bridge.py

@@ -62,6 +62,8 @@ class ManuscriptContext:
     cleaned_text: str
     word_count: int
     page_trace: list[dict[str, Any]]
+    fingerprint: dict[str, Any] | None = None
+    fingerprint_report: str = ""
 
 
 @dataclass
@@ -132,6 +134,16 @@ def load_totem_skill(skill_path: str | Path | None = None) -> tuple[str, str]:
 def dashboard_output_contract() -> dict[str, Any]:
     return {
         "scores": {field: "integer 0..100" for field in SCORE_FIELDS},
+        "score_evidence": {
+            field: {
+                "score": "integer 0..100 matching scores.<field>",
+                "fingerprint_metrics_used": ["VM metric ids used, e.g. VM-001, VM-010, VM-025"],
+                "workbook_rule": "target/threshold/rubric rule used from workbook matrix",
+                "manuscript_evidence": "short paraphrased manuscript evidence; no long excerpts",
+                "reason": "why this score follows from the workbook rule and fingerprint metrics",
+            }
+            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",
@@ -168,7 +180,7 @@ def run_totem_skill(
 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.
+Use the workbook matrix as scoring authority, manuscript fingerprint VM metrics as measured evidence, and manuscript text only as supporting evidence.
 
 --- TOTEM SKILL INSTRUCTIONS ---
 {skill_text}
@@ -178,12 +190,17 @@ Use the workbook matrix as scoring authority and manuscript text as evidence.
     user_payload = {
         "task": "score_manuscript_against_workbook_matrix_for_dashboard",
         "rubric_matrix": rubric_matrix,
+        "manuscript_fingerprint": manuscript.fingerprint or {},
+        "manuscript_fingerprint_report": manuscript.fingerprint_report[:6000] if manuscript.fingerprint_report else "",
         "manuscript_cleaned_text": manuscript.cleaned_text,
         "scoring_dimensions": SCORE_LABELS,
         "required_output_contract": contract,
         "instruction": (
             "Return exactly one JSON object matching required_output_contract. "
             "Scores must be 0..100 dashboard values for the six dimensions. "
+            "Every score_evidence entry must cite at least one VM metric id from manuscript_fingerprint "
+            "and one workbook rule/target from rubric_matrix. If the fingerprint is missing or insufficient, "
+            "return gate REVISE and explain the missing evidence in dashboard_message. "
             "Do not write a report and do not include manuscript excerpts."
         ),
     }
@@ -221,6 +238,8 @@ Use the workbook matrix as scoring authority and manuscript text as evidence.
             "skill_path": skill_path,
             "skill_loaded": True,
             "schema_pass": True,
+            "fingerprint_supplied": bool(manuscript.fingerprint),
+            "fingerprint_metric_count": _fingerprint_metric_count(manuscript.fingerprint),
             "token_audit_path": audit_path,
             "token_audit_transaction_id": transaction_id,
             "raw_model_payload": raw_payload,
@@ -350,6 +369,8 @@ Use the workbook matrix as scoring authority and manuscript text as evidence.
         "skill_loaded": True,
         "schema_pass": True,
         "actual_tokens": actual_tokens,
+        "fingerprint_supplied": bool(manuscript.fingerprint),
+        "fingerprint_metric_count": _fingerprint_metric_count(manuscript.fingerprint),
         "token_audit_path": audit_path,
         "token_audit_transaction_id": transaction_id,
         "raw_model_payload": parsed,
@@ -435,6 +456,7 @@ def _write_token_audit(
     error: str | None,
 ) -> str:
     rubric_json = compact_json(rubric_matrix)
+    fingerprint_json = compact_json(manuscript.fingerprint or {})
     contract_json = compact_json(contract)
     user_wrapper_json = compact_json(
         {
@@ -447,7 +469,7 @@ def _write_token_audit(
 You are the hidden TOTEM Analysis skill inside TOTEM Studio.
 Use the skill instructions 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.
+Use the workbook matrix as scoring authority, manuscript fingerprint VM metrics as measured evidence, and manuscript text only as supporting evidence.
 """.strip()
 
     component_estimates = estimate_components(
@@ -455,6 +477,8 @@ Use the workbook matrix as scoring authority and manuscript text as evidence.
             "system_wrapper": system_wrapper,
             "skill_md": skill_text,
             "workbook_rubric_json": rubric_json,
+            "manuscript_fingerprint_json": fingerprint_json,
+            "manuscript_fingerprint_report": manuscript.fingerprint_report or "",
             "manuscript_cleaned_text": manuscript.cleaned_text,
             "output_contract_json": contract_json,
             "user_wrapper_json": user_wrapper_json,
@@ -487,6 +511,12 @@ Use the workbook matrix as scoring authority and manuscript text as evidence.
             "chars": len(manuscript.cleaned_text),
             "word_count": manuscript.word_count,
         },
+        "fingerprint": {
+            "supplied": bool(manuscript.fingerprint),
+            "sha256": stable_hash(manuscript.fingerprint or {}),
+            "metric_count": _fingerprint_metric_count(manuscript.fingerprint),
+            "report_chars": len(manuscript.fingerprint_report or ""),
+        },
         "estimated_tokens": {
             **component_estimates,
             "wire_prompt": {
@@ -562,6 +592,11 @@ def validate_dashboard_payload(payload: dict[str, Any]) -> dict[str, Any]:
     }
     out.update(out["scores"])
 
+    score_evidence = payload.get("score_evidence")
+    if not isinstance(score_evidence, dict):
+        raise BridgeValidationError("score_evidence must be a JSON object keyed by scoring dimension.")
+    out["score_evidence"] = _normalize_score_evidence(score_evidence, out["scores"])
+
     rpq = payload.get("revision_priority_queue")
     if not isinstance(rpq, list):
         raise BridgeValidationError("revision_priority_queue must be a list.")
@@ -574,6 +609,45 @@ def validate_dashboard_payload(payload: dict[str, Any]) -> dict[str, Any]:
     return out
 
 
+def _normalize_score_evidence(evidence: dict[str, Any], scores: dict[str, int]) -> dict[str, dict[str, Any]]:
+    normalized: dict[str, dict[str, Any]] = {}
+    missing: list[str] = []
+    weak: list[str] = []
+    for field in SCORE_FIELDS:
+        item = evidence.get(field)
+        if not isinstance(item, dict):
+            missing.append(field)
+            continue
+
+        metrics = item.get("fingerprint_metrics_used") or item.get("vm_metrics_used") or []
+        if isinstance(metrics, str):
+            metrics = [metrics]
+        metric_ids = [str(x).strip() for x in metrics if str(x).strip()]
+        if not metric_ids or not any(m.upper().startswith("VM-") for m in metric_ids):
+            weak.append(field)
+
+        workbook_rule = str(item.get("workbook_rule") or "").strip()[:260]
+        manuscript_evidence = str(item.get("manuscript_evidence") or "").strip()[:260]
+        reason = str(item.get("reason") or "").strip()[:320]
+        if not workbook_rule or not reason:
+            weak.append(field)
+
+        normalized[field] = {
+            "score": scores[field],
+            "fingerprint_metrics_used": metric_ids[:8],
+            "workbook_rule": workbook_rule,
+            "manuscript_evidence": manuscript_evidence,
+            "reason": reason,
+        }
+
+    if missing:
+        raise BridgeValidationError(f"Missing score_evidence fields: {', '.join(missing)}")
+    if weak:
+        deduped = ", ".join(dict.fromkeys(weak))
+        raise BridgeValidationError(f"score_evidence lacks VM metric/workbook grounding for: {deduped}")
+    return normalized
+
+
 def recompute_gate(metrics: dict[str, int], rubric_matrix: dict[str, Any]) -> str:
     weights = rubric_matrix.get("weights", {}) if isinstance(rubric_matrix, dict) else {}
     if not isinstance(weights, dict) or not weights:
@@ -656,14 +730,25 @@ 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
+    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)),
+    }
     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)),
+        "scores": scores,
+        "score_evidence": {
+            field: {
+                "score": score,
+                "fingerprint_metrics_used": ["VM-024"],
+                "workbook_rule": "Fake provider test rule; real runs must cite workbook targets.",
+                "manuscript_evidence": "Fake provider uses word-count-only smoke evidence.",
+                "reason": f"Fake audit score for {field} derived from {word_count} words.",
+            }
+            for field, score in scores.items()
         },
         "gate": "REVISE",
         "weakest_metric": "Rhythm",
@@ -711,3 +796,9 @@ def _clamp_score(value: Any) -> int:
     except Exception as exc:
         raise BridgeValidationError(f"Invalid numeric score value: {value!r}") from exc
     return max(0, min(100, x))
+
+
+def _fingerprint_metric_count(fingerprint: dict[str, Any] | None) -> int:
+    if not isinstance(fingerprint, dict):
+        return 0
+    return sum(1 for key in fingerprint if str(key).upper().startswith("VM-"))