Add hackathon readiness gates

README.md

@@ -111,6 +111,8 @@ The default preset is **Raven Quality Stack**. `black-forest-labs/FLUX.2-klein-4
 
 Tiny Titan is not the flagship story. It can be claimed only from a successful sidecar export packet where every active sidecar model is <=4B.
 
+See [docs/SUBMISSION_ASSETS.md](docs/SUBMISSION_ASSETS.md) for the demo script, social post draft, thumbnail direction, and final link checklist.
+
 ## Local Setup
 
 ```powershell

app.py

@@ -413,25 +413,36 @@ def export_packet(
     scan: dict[str, Any] | None,
     active_section: str,
     operator_state: dict[str, Any] | None,
+    override_reason: str = "",
 ) -> tuple[Any, ...]:
     state = operator_state or _default_operator_state()
     scan = _authoritative_generated_scan(state)
+    override_reason = (override_reason or "").strip()
     if run is None:
         next_state = {**state, "provider_state": "blocked", "export": "blocked", "message": "Export blocked: no active run packet exists."}
     elif state.get("checkpoint") != "approved":
         next_state = {**state, "provider_state": "blocked", "export": "blocked", "message": "Export blocked: human checkpoint has not been approved."}
     elif not _generated_output_path(state):
         next_state = {**state, "provider_state": "blocked", "export": "blocked", "message": "Export blocked: no generated artifact exists."}
-    elif scan.get("export_gate") != "clear":
-        next_state = {**state, "provider_state": "blocked", "export": scan.get("export_gate", "blocked"), "message": "Export blocked: ST3GG gate is not clear."}
+    elif scan.get("export_gate") != "clear" and not override_reason:
+        next_state = {**state, "provider_state": "blocked", "export": scan.get("export_gate", "blocked"), "message": "Export blocked: ST3GG gate is not clear. Add an explicit override reason to prepare a reviewed evidence packet."}
     else:
-        export = write_export_packet(run=run, scan=scan, operator_state=state, adult_mode=adult_mode)
-        next_state = {
+        export_state = "clear" if scan.get("export_gate") == "clear" else "override"
+        export_input_state = {
             **state,
+            **({"st3gg_override_reason": override_reason} if override_reason and scan.get("export_gate") != "clear" else {}),
+        }
+        export = write_export_packet(run=run, scan=scan, operator_state=export_input_state, adult_mode=adult_mode)
+        next_state = {
+            **export_input_state,
             "provider_state": "exported",
-            "export": "clear",
+            "export": export_state,
             "export_packet": {"path": export["path"]},
-            "message": f"Governed export packet prepared: {export['path']}",
+            "message": (
+                f"Governed export packet prepared with ST3GG override recorded: {export['path']}"
+                if export_state == "override"
+                else f"Governed export packet prepared: {export['path']}"
+            ),
         }
     return _render_stateful(run, adult_mode, scan, active_section, next_state)
 
@@ -525,6 +536,13 @@ with gr.Blocks(title="NEXUS Visual Weaver") as demo:
             )
             run_btn = gr.Button("Run Active Weave", variant="primary", scale=1)
             stop_btn = gr.Button("Stop Provider Job", variant="stop", interactive=False, scale=1)
+        override_reason = gr.Textbox(
+            value="",
+            label="ST3GG Override Reason",
+            placeholder="Required only to export a reviewed/blocked artifact. Explain why the evidence packet may be written.",
+            lines=2,
+            max_lines=3,
+        )
         with gr.Row(elem_id="nw-operator-actions", elem_classes=["nw-operator-actions"]):
             scan_btn = gr.Button("Scan Reference", scale=1)
             checkpoint_btn = gr.Button("Approve Checkpoint", scale=1)
@@ -627,7 +645,7 @@ with gr.Blocks(title="NEXUS Visual Weaver") as demo:
     )
     export_btn.click(
         fn=export_packet,
-        inputs=[active_run_state, adult_mode, scan_state, section_nav, operator_state],
+        inputs=[active_run_state, adult_mode, scan_state, section_nav, operator_state, override_reason],
         outputs=operator_outputs,
         api_name="prepare_export_packet",
     )

docs/HANDOFF_FINAL_HACKATHON.md

@@ -18,6 +18,7 @@
 
 Do not paste these into chat, commits, logs, or export packets.
 
+- Current Space secret inventory checked after the Raven sprint: `HF_TOKEN` is present; OpenBMB, Nemotron/NVIDIA, and Modal secrets are not present.
 - `HF_TOKEN`: required for gated FLUX.2 Klein 9B access after license acceptance; the app can honestly fall back to the 4B Tiny Titan sidecar if the 9B lane is unavailable.
 - `MINICPM_BASE_URL`: OpenBMB OpenAI-compatible endpoint base URL.
 - `MINICPM_API_KEY`: OpenBMB bearer token.
@@ -90,6 +91,7 @@ Current evidence from the SSE API:
 - OpenBMB and Nemotron endpoints are optional and must show `missing secret` rather than fake success when not configured.
 - Demo video and social post links must be added before final submission.
 - Dev mode served stale `dc6756e` until disabled through the HF API. Keep dev mode off for final judging unless you immediately verify `/config` after re-enabling.
+- The app now supports an explicit ST3GG override reason for evidence-packet export when a generated artifact is review/blocked. This does not mark ST3GG as clear; it records the blocked gate and the human reason.
 
 ## Last Verified Checks
 
@@ -101,6 +103,8 @@ Current evidence from the SSE API:
 - Public Space API: `/gradio_api/info` exposed `run_active_weave`, `scan_reference`, `approve_checkpoint`, `prepare_export_packet`, and `toggle_adult_catalog`.
 - Public Space config: `Raven Quality Stack` and `FLUX.2 9B PINNED` present; old `Dark Couture v2.4` and `FLUX.2 4B PINNED` absent.
 - Live weave: real FLUX image generated after switching to `Flux2KleinPipeline`; ST3GG marked the generated PNG `review` and blocked export due high entropy review, proving the export gate is active.
+- Readiness: the UI now shows explicit gates for Space/API, Raven Stack, ST3GG, FLUX artifact, checkpoint, export packet, sponsor evidence, and demo/social.
+- Submission assets: see `docs/SUBMISSION_ASSETS.md` for demo script, social draft, thumbnail direction, and final link checklist.
 
 ## Last-Step Checklist
 

docs/SUBMISSION_ASSETS.md

@@ -0,0 +1,42 @@
+# Submission Assets Plan
+
+## Demo Video
+
+Target length: 60-90 seconds.
+
+1. Open the Space and show the first viewport: Raven Quality Stack, 28.50B budget, ST3GG trust strip, and Hackathon Readiness.
+2. Run the default Raven Chronicle prompt.
+3. Show the real FLUX artifact in the Artifact Preview Lane.
+4. Show ST3GG verdict and explain that generation is not export.
+5. Approve the human checkpoint.
+6. If ST3GG marks the artifact review/blocked, type an explicit override reason and prepare the export packet.
+7. Open the evidence accordion: model stack, ST3GG scan, MiniCPM/Nemotron missing-secret or success states, and export packet path.
+8. Close with the prize map: Off Brand, Best Agent, OpenBMB/NVIDIA when provider evidence succeeds, Modal sidecar when documented.
+
+## Social Post Draft
+
+NEXUS Visual Weaver is our Build Small hackathon command center for governed visual creation: Raven Quality Stack image generation, gothic couture wardrobe control, LocateAnything grounding, ST3GG export gates, and human checkpoints before release.
+
+Built with Gradio on Hugging Face Spaces. Real FLUX artifacts are generated, scanned, checkpointed, and packaged as evidence instead of silently exported.
+
+Space: `SPACE_URL`
+Demo: `DEMO_VIDEO_URL`
+
+## Thumbnail Direction
+
+Create a dark couture command-center cover:
+
+- left: Raven Chronicle generated artifact
+- center: workflow graph with ST3GG trust gate
+- right: inspector cards for FLUX.2 9B, LocateAnything, MiniCPM, Nemotron, Modal VOID
+- color: black glass, crimson, cyan, subtle green trust signal
+- text: `NEXUS Visual Weaver`
+
+Avoid cluttered model logos, tiny unreadable UI screenshots, or a generic marketing hero.
+
+## Final Link Checklist
+
+- Replace `DEMO_VIDEO_URL` in README.
+- Replace `SOCIAL_POST_URL` in README.
+- Set `NEXUS_DEMO_VIDEO_URL` and `NEXUS_SOCIAL_POST_URL` as Space variables if we want the readiness meter to mark Demo/Social complete.
+- Re-run `/gradio_api/info` and one `run_active_weave` smoke after link update.

src/nexus_visual_weaver/exporter.py

@@ -102,6 +102,7 @@ def write_export_packet(
         "repo_id": "black-forest-labs/FLUX.2-klein-4B",
     }
     locate_grounding = operator_state.get("locateanything_grounding") or {}
+    st3gg_override_reason = str(operator_state.get("st3gg_override_reason", "")).strip()
     packet = {
         "schema": "nexus_visual_weaver.export_packet.v1",
         "run_id": run_id,
@@ -113,6 +114,7 @@ def write_export_packet(
         "artifact": artifact,
         "generation": generation,
         "st3gg_scan": scan,
+        "st3gg_override_reason": st3gg_override_reason or None,
         "locateanything_grounding": locate_grounding,
         "offellia_judge": offellia,
         "minicpm_judge": operator_state.get("minicpm_judge") or {},
@@ -147,6 +149,7 @@ def write_export_packet(
             "tiny_titan_sidecar": tiny_titan.get("status") in {"success", "available", "sidecar"},
             "raven_quality_stack": True,
             "locateanything_grounding": bool(locate_grounding.get("targets") or locate_grounding.get("repo_id")),
+            "st3gg_override_recorded": bool(st3gg_override_reason),
             "st3gg_export_gate": scan.get("export_gate"),
         },
     }

src/nexus_visual_weaver/render.py

@@ -154,6 +154,56 @@ def render_trust_strip(scan: dict | None = None, operator_state: dict | None = N
     """
 
 
+def _submission_link_ready() -> bool:
+    return bool(os.environ.get("NEXUS_DEMO_VIDEO_URL") and os.environ.get("NEXUS_SOCIAL_POST_URL"))
+
+
+def _submission_readiness(scan: dict | None = None, operator_state: dict | None = None) -> tuple[int, int, list[tuple[str, bool, str]]]:
+    scan = scan or {"status": "idle", "export_gate": "pending"}
+    operator_state = operator_state or {}
+    generation = operator_state.get("generation") or {}
+    minicpm = operator_state.get("minicpm_judge") or {}
+    nemotron = operator_state.get("nemotron_evidence") or {}
+    gates = [
+        ("Space/API", True, "Space is serving the command center and MCP/Gradio API."),
+        ("Raven Stack", True, "28.50B quality stack is configured under the 32B rule."),
+        ("ST3GG Visible", True, "Trust strip and export gate are above the fold."),
+        ("FLUX Artifact", generation.get("status") == "success", "Run Active Weave must generate a real artifact."),
+        ("Checkpoint", operator_state.get("checkpoint") == "approved", "Human checkpoint must approve the generated artifact."),
+        ("Export Packet", bool(operator_state.get("export_packet")), "Prepare Export Packet must write evidence JSON."),
+        (
+            "Sponsor Evidence",
+            minicpm.get("status") == "success" and nemotron.get("status") == "success",
+            "MiniCPM and Nemotron both need configured secrets and successful calls.",
+        ),
+        ("Demo/Social", _submission_link_ready(), "Final demo video and social post URLs are still required."),
+    ]
+    complete = sum(1 for _, ok, _ in gates if ok)
+    return complete, len(gates), gates
+
+
+def render_submission_readiness(scan: dict | None = None, operator_state: dict | None = None) -> str:
+    complete, total, gates = _submission_readiness(scan, operator_state)
+    pct = int((complete / total) * 100)
+    chips = "".join(
+        f'<span class="nw-ready-chip {"is-done" if ok else "is-waiting"}">{escape(label)}</span>'
+        for label, ok, _ in gates
+    )
+    blockers = [help_text for _, ok, help_text in gates if not ok][:3]
+    blockers_html = " ".join(f"<span>{escape(text)}</span>" for text in blockers)
+    return f"""
+    <section class="nw-readiness">
+      <div class="nw-ready-head">
+        <strong>Hackathon Readiness</strong>
+        <small>{complete}/{total} gates complete</small>
+      </div>
+      <div class="nw-ready-meter"><i style="width:{pct}%"></i></div>
+      <div class="nw-ready-chips">{chips}</div>
+      <div class="nw-ready-blockers">{blockers_html}</div>
+    </section>
+    """
+
+
 def render_topbar(
     adult_mode: bool = False,
     relay_status: dict | None = None,
@@ -197,6 +247,7 @@ def render_topbar(
       <div class="nw-locked"><b>18+</b><span>Locked. Enable in Security with explicit justification.</span></div>
     </div>
     {render_trust_strip(scan, operator_state)}
+    {render_submission_readiness(scan, operator_state)}
     """
 
 

src/nexus_visual_weaver/styles.py

@@ -165,6 +165,77 @@ footer { display: none !important; }
 .nw-trust-card .nw-badge {
   margin-bottom: 1px;
 }
+.nw-readiness {
+  display: grid;
+  grid-template-columns: 190px minmax(180px, 260px) minmax(420px, 1fr);
+  gap: 10px;
+  align-items: center;
+  padding: 8px;
+  border-bottom: 1px solid #171c22;
+  background:
+    linear-gradient(90deg, rgba(255,54,95,.08), transparent 42%),
+    rgba(5, 7, 10, .98);
+}
+.nw-ready-head {
+  min-width: 0;
+}
+.nw-ready-head strong {
+  display: block;
+  font-size: 13px;
+  line-height: 1.2;
+}
+.nw-ready-head small {
+  color: var(--nw-muted);
+  font-size: 11px;
+}
+.nw-ready-meter {
+  height: 10px;
+  border-radius: 999px;
+  overflow: hidden;
+  background: #1d242c;
+  box-shadow: inset 0 0 0 1px rgba(255,255,255,.06);
+}
+.nw-ready-meter i {
+  display: block;
+  height: 100%;
+  background: linear-gradient(90deg, var(--nw-green), var(--nw-cyan));
+  box-shadow: 0 0 16px rgba(32,217,232,.32);
+}
+.nw-ready-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 5px;
+}
+.nw-ready-chip {
+  border: 1px solid var(--nw-line);
+  border-radius: 999px;
+  padding: 4px 8px;
+  color: var(--nw-muted);
+  font-size: 10px;
+  font-weight: 750;
+  white-space: nowrap;
+}
+.nw-ready-chip.is-done {
+  color: #9ff4c6;
+  border-color: rgba(38,215,130,.42);
+  background: rgba(38,215,130,.08);
+}
+.nw-ready-chip.is-waiting {
+  color: #ffb7c4;
+  border-color: rgba(255,54,95,.34);
+  background: rgba(255,54,95,.06);
+}
+.nw-ready-blockers {
+  grid-column: 1 / -1;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+.nw-ready-blockers span {
+  color: var(--nw-muted);
+  font-size: 11px;
+  line-height: 1.35;
+}
 .nw-icon { width: 18px; height: 18px; stroke: currentColor; fill: none; stroke-width: 1.8; stroke-linecap: round; stroke-linejoin: round; }
 .nw-shell {
   display: grid;
@@ -938,6 +1009,8 @@ footer { display: none !important; }
 @media (max-width: 1100px) {
   .nw-topbar { grid-template-columns: 1fr; }
   .nw-trust-strip { grid-template-columns: 1fr; }
+  .nw-readiness { grid-template-columns: 1fr; }
+  .nw-ready-blockers { grid-column: 1; }
   .nw-shell { grid-template-columns: 1fr; grid-template-rows: auto; }
   .nw-rail, .nw-inspector, .nw-bottom { grid-column: 1; grid-row: auto; }
   .nw-rail { flex-direction: row; overflow-x: auto; }

tests/test_app_callbacks.py

@@ -146,6 +146,40 @@ def test_export_blocks_without_checkpoint() -> None:
     assert "checkpoint" in blocked[13]["message"].lower()
 
 
+def test_export_allows_st3gg_review_with_explicit_override() -> None:
+    from pathlib import Path
+
+    result = app.run_weave(
+        "gothic patent leather platform boots, crimson hardware",
+        "Strict",
+        "Wan2.2 I2V",
+        False,
+        None,
+        "Forge",
+    )
+    run = result[13]
+    artifact_path = Path("outputs/test-override-artifact.png")
+    artifact_path.parent.mkdir(parents=True, exist_ok=True)
+    artifact_path.write_bytes(b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIEND\xaeB`\x82NEXUS_REVIEW")
+    state = {
+        **result[15],
+        "generation": {**result[15]["generation"], "status": "success", "output_path": str(artifact_path)},
+        "checkpoint": "approved",
+        "provider_state": "checkpointed",
+    }
+    review_scan = {"status": "review", "export_gate": "blocked", "findings": ["high entropy sample"], "purification_actions": ["manual review"]}
+
+    blocked = app.export_packet(run, False, review_scan, "Forge", state, "")
+    assert blocked[13]["provider_state"] == "blocked"
+    assert "override reason" in blocked[13]["message"].lower()
+
+    exported = app.export_packet(run, False, review_scan, "Forge", state, "Judge-reviewed generated PNG; evidence packet only.")
+    assert exported[13]["provider_state"] == "exported"
+    assert exported[13]["export"] == "override"
+    assert exported[13]["st3gg_override_reason"] == "Judge-reviewed generated PNG; evidence packet only."
+    assert "export_packet" in exported[13]
+
+
 def test_reference_scan_cannot_clear_blocked_generated_artifact() -> None:
     base = app.ROOT / "outputs" / "test-app-callbacks"
     base.mkdir(parents=True, exist_ok=True)

tests/test_command_center.py

@@ -20,6 +20,7 @@ from nexus_visual_weaver.render import (
     render_inspector,
     render_operations_panel,
     render_provider_cards,
+    render_submission_readiness,
     render_topbar,
     render_trust_strip,
 )
@@ -315,6 +316,8 @@ def test_render_topbar_includes_trust_strip() -> None:
 
     assert "TRUST MODEL" in html
     assert "nw-trust-strip" in html
+    assert "Hackathon Readiness" in html
+    assert "3/8 gates complete" in html
 
 
 def test_render_topbar_with_scan_passes_to_trust_strip() -> None:
@@ -339,6 +342,24 @@ def test_render_topbar_default_scan_shows_fixture_evidence() -> None:
     assert "PNG trailing bytes -> blocked." in html
 
 
+def test_submission_readiness_tracks_run_and_submission_blockers() -> None:
+    html = render_submission_readiness(
+        scan={"status": "review", "export_gate": "blocked"},
+        operator_state={
+            "generation": {"status": "success"},
+            "checkpoint": "approved",
+            "export_packet": {"path": "outputs/exports/nw.json"},
+            "minicpm_judge": {"status": "missing_secret"},
+            "nemotron_evidence": {"status": "missing_secret"},
+        },
+    )
+
+    assert "Hackathon Readiness" in html
+    assert "6/8 gates complete" in html
+    assert "MiniCPM and Nemotron" in html
+    assert "Final demo video and social post URLs" in html
+
+
 # --- render_inspector sponsor evidence tests ---
 
 def test_render_inspector_shows_sponsor_evidence_section() -> None:

tests/test_exporter.py

@@ -131,6 +131,20 @@ def test_export_packet_hackathon_claims_st3gg_export_gate(monkeypatch) -> None:
     assert payload_blocked["hackathon_claims"]["st3gg_export_gate"] == "blocked"
 
 
+def test_export_packet_records_st3gg_override_reason(monkeypatch) -> None:
+    monkeypatch.setenv("NEXUS_EXPORT_DIR", "outputs/test-exports")
+    run = build_command_center_run("review override brief")
+    scan = {"status": "review", "export_gate": "blocked"}
+    state = _make_base_state(st3gg_override_reason="Human reviewed generated artifact for evidence-only export.")
+
+    result = write_export_packet(run=run, scan=scan, operator_state=state, adult_mode=False)
+    payload = json.loads(Path(result["path"]).read_text(encoding="utf-8"))
+
+    assert payload["st3gg_override_reason"] == "Human reviewed generated artifact for evidence-only export."
+    assert payload["hackathon_claims"]["st3gg_override_recorded"] is True
+    assert payload["hackathon_claims"]["st3gg_export_gate"] == "blocked"
+
+
 def test_export_packet_includes_model_stack_and_prompts(monkeypatch) -> None:
     monkeypatch.setenv("NEXUS_EXPORT_DIR", "outputs/test-exports")
     run = build_command_center_run("raven archivist couture brief")