feat(review): polish review handoff surface

Make Run Story entries status and timestamp aware, add clearer Review empty states, and provide a Markdown download path for handoff previews before external routing.

Verification: make lint; venv/bin/python -m pytest tests/test_review_ui.py -q; make test (281 passed); venv/bin/python tests/ui_smoke.py; make browser-e2e-fresh; python3 -m json.tool ops/roadmap/features.json; git diff --check.

Author: WalksWithASwagger

ROADMAP.md

@@ -35,7 +35,7 @@ WhisperForge is now a single-user voice-to-knowledge workbench:
 - Open GitHub issues: none (`#41`, `#42`, `#43`, `#45`, `#46`, `#47`, and
   `#48` are shipped).
 - Open GitHub PRs: none.
-- Current unit baseline: `279 passed`.
+- Current unit baseline: `281 passed`.
 - Audio repo consolidation audit:
   [`docs/AUDIO-REPO-CONSOLIDATION-AUDIT-2026-05-18.md`](docs/AUDIO-REPO-CONSOLIDATION-AUDIT-2026-05-18.md).
   Next round plan:
@@ -123,7 +123,7 @@ useful in real sessions.
 | `wf-export-readiness-refresh` | P0 | Refresh scorecard/handoff readiness signals after export events | Shipped in `#47` |
 | `wf-transcription-router` | P1 | Implement provider router from transcription matrix | Shipped in `#48` |
 | `wf-demo-fixture-pack` | P0 | Expand the presentation demo fixture pack | Shipped; browser smokes stay credential-free |
-| `wf-review-polish` | P0 | Polish the Review tab for presentation and daily use | Rendered UI smoke covers labels/behavior |
+| `wf-review-polish` | P0 | Polish the Review tab for presentation and daily use | Shipped; rendered UI smoke covers labels/behavior |
 | `wf-kb-governance` | P1 | Add KB governance and profile-pack review workflow | Human confirms private/stale policy |
 | `wf-router-media-normalization` | P1 | Add fixture-backed media normalization for the transcription router | Runtime defaults preserved |
 | `wf-digest-approved-routing` | P1 | Add human-approved routing for resurfacing digests | Explicit approval remains required |

STATUS.md

@@ -46,7 +46,7 @@ Last updated: 2026-05-21
   -> `0`.
 - `python3 -m json.tool ops/roadmap/features.json` passes.
 - `make lint` passes dependency-light Python syntax checks.
-- `make test` -> `279 passed`.
+- `make test` -> `281 passed`.
 - `make browser-e2e` -> `browser-e2e: OK`.
 - `make browser-e2e-fresh` -> `browser-e2e-fresh: OK`.
 - `make eval-fixture` passes editorial and SongForge fixtures.
@@ -107,15 +107,13 @@ Last updated: 2026-05-21
 
 ## Next Round
 
-Dogfood closeout, first router slice, Run Story/Review extraction, and the demo
-fixture pack are complete. The next roadmap slice should stay focused on
-presentation polish and local-first reliability:
+Dogfood closeout, first router slice, Run Story/Review extraction, the demo
+fixture pack, and Review polish are complete. The next roadmap slice should
+stay focused on local-first reliability:
 
-1. `wf-review-polish` - make the Review tab more legible, status-aware, and
-   copy-friendly.
-2. `wf-kb-governance` - define canonical, stale, private, and ignored KB
+1. `wf-kb-governance` - define canonical, stale, private, and ignored KB
    context so agents do not over-trust messy source material.
-3. `wf-router-media-normalization` - add fixture-backed FFmpeg/media
+2. `wf-router-media-normalization` - add fixture-backed FFmpeg/media
    normalization before changing transcription defaults.
-4. `wf-digest-approved-routing` - route resurfacing digests only after explicit
+3. `wf-digest-approved-routing` - route resurfacing digests only after explicit
    approval.

changelog.md

@@ -27,6 +27,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a completed article/handoff run, a SongForge creative-pack run, and a
   partial/failed run so cold-start demos have useful Runs-dialog material
   without live credentials.
+- **Review tab polish** — Run Story steps now show readable statuses and UTC
+  timestamps, Review sections surface clearer empty states, and handoff previews
+  can be downloaded as Markdown before any tracker routing.
 - **Import-folder capture helpers** — `whisperforge_core.captures` can now
   import text/markdown notes and audio pointers from files or folders, dedupe
   obvious repeats, and ignore generated chunk/temp files.

docs/NEXT-ROUND-PLAN-2026-05-19.md

@@ -16,10 +16,10 @@ name remains WhisperForge.
 - Remote branches: only `origin/main`.
 - Legacy audio repositories are archived as historical pointers.
 - Release target: local-first personal workbench.
-- Current verification baseline: `make test` -> `279 passed`, plus lint, JSON,
+- Current verification baseline: `make test` -> `281 passed`, plus lint, JSON,
   rendered UI, browser, fixture, and Streamlit health smokes in normal closeout.
-- Latest polish slice: credential-free demo fixture pack with article/handoff,
-  SongForge, and partial/failed runs.
+- Latest polish slice: Review tab status/empty-state polish plus handoff draft
+  download.
 
 ## Product Direction
 
@@ -37,7 +37,6 @@ the local loop feels boringly reliable.
 
 | ID | Priority | Title | Why Now |
 | --- | --- | --- | --- |
-| `wf-review-polish` | P0 | Polish the Review tab for presentation and daily use | Review is now the trust surface; make it legible, calm, and copy-friendly. |
 | `wf-kb-governance` | P1 | Add KB governance and profile-pack review workflow | The KB is powerful enough to need explicit stale/private/canonical controls. |
 | `wf-router-media-normalization` | P1 | Add fixture-backed media normalization for the transcription router | Large audio/video intake is the next practical extraction bottleneck. |
 | `wf-digest-approved-routing` | P1 | Add human-approved routing for resurfacing digests | Resurfacing should become actionable without becoming autonomous spam. |
@@ -49,25 +48,18 @@ criteria and verification gates.
 
 ## Today/Tomorrow Execution Order
 
-1. **Review tab polish**
-   - Add status-aware Run Story rendering, timestamps where available, and
-     compact empty/error states.
-   - Add a copy-friendly handoff preview export/download path that works
-     without GitHub or Linear credentials.
-   - Keep UI tests focused on labels and behavior, not brittle styling.
-
-2. **KB governance**
+1. **KB governance**
    - Turn audit warnings into reviewer actions: canonical, ignore, quarantine,
      needs-update.
    - Document the privacy/stale policy for humans and future agents.
    - Surface unresolved governance warnings before generation.
 
-3. **Router media normalization**
+2. **Router media normalization**
    - Convert the provider matrix into fixture-backed FFmpeg/media inspection
      and chunk normalization behavior.
    - Preserve current runtime defaults until privacy/cost receipts are visible.
 
-4. **Digest approved routing**
+3. **Digest approved routing**
    - Keep digest generation report-only by default.
    - Add explicit approval for local follow-up queue and Notion draft paths.
 

docs/PRESENTATION-RUNBOOK-2026-05-19.md

@@ -26,7 +26,7 @@ make smoke
 
 Expected now:
 
-- `make test` -> `279 passed`
+- `make test` -> `281 passed`
 - fixture and UI/smoke checks pass
 
 If Docker is running and you want services proof:
@@ -115,9 +115,9 @@ Use these to get actionable feedback:
 
 ## 5) Next Dev Slice (After Review)
 
-1. Polish the Review tab: status-aware Run Story rendering, clearer empty/error
-   states, and a copy-friendly handoff preview path.
-2. Add KB governance so stale/private/canonical profile context is visible
+1. Add KB governance so stale/private/canonical profile context is visible
    before generation.
-3. Add fixture-backed media normalization for large audio/video routing before
+2. Add fixture-backed media normalization for large audio/video routing before
    changing transcription defaults.
+3. Add approved digest routing only after the local follow-up/Notion destination
+   rules are clear.

ops/roadmap/features.json

@@ -784,7 +784,7 @@
       "phase": "Presentation Polish",
       "priority": "P0",
       "kind": "ux",
-      "status": "planned",
+      "status": "shipped",
       "acceptance": [
         "Run Story steps render with clear status, timestamps where available, and no layout jitter.",
         "Review, scorecard, receipt, and handoff sections have useful empty/error states.",
@@ -793,6 +793,7 @@
       ],
       "verification": [
         "make test",
+        "venv/bin/python -m pytest tests/test_review_ui.py -q",
         "venv/bin/python tests/ui_smoke.py",
         "make browser-e2e-fresh",
         "git diff --check"

readme.md

@@ -164,7 +164,7 @@ services/
 └── frontend/Dockerfile       builds root app.py with DEPLOY_MODE=services
 
 shared/                       cross-service config + X-API-Key auth
-tests/                        279 tests + health/rendered UI smokes
+tests/                        281 tests + health/rendered UI smokes
 prompts/<user>/               profile.yaml, prompt .md files, knowledge_base,
                                personas, custom_prompts
 ```

tests/test_review_ui.py

@@ -0,0 +1,31 @@
+"""Small helper tests for Review tab presentation polish."""
+
+from ui import review
+
+
+def test_run_story_step_markdown_uses_readable_status_and_timestamp():
+    rendered = review._run_story_step_markdown({
+        "label": "Capture",
+        "status": "complete",
+        "detail": "Wispr Flow input: Morning kickoff",
+        "timestamp": "2026-05-21T17:04:15Z",
+    })
+
+    assert rendered == (
+        "- **Capture** · `Complete` · 2026-05-21 17:04 UTC  \n"
+        "  Wispr Flow input: Morning kickoff"
+    )
+
+
+def test_handoff_preview_download_helpers_are_markdown_safe():
+    preview = {
+        "title": "Handoff: Tighten week-two demo cadence",
+        "body": "## Context\n\nShip the smallest useful thing.",
+    }
+
+    assert review._handoff_preview_filename(preview["title"]) == (
+        "handoff-tighten-week-two-demo-cadence.md"
+    )
+    assert review._handoff_preview_markdown(preview).startswith(
+        "# Handoff: Tighten week-two demo cadence\n\n## Context"
+    )

ui/review.py

@@ -4,6 +4,8 @@
 
 import hashlib
 import os
+import re
+from datetime import datetime, timezone
 from typing import Optional
 
 import streamlit as st
@@ -16,6 +18,14 @@
 from whisperforge_core import run_story as run_story_mod
 from whisperforge_core import scorecards as scorecards_mod
 
+_RUN_STORY_STATUS_LABELS = {
+    "active": "Active",
+    "complete": "Complete",
+    "error": "Error",
+    "skipped": "Skipped",
+    "waiting": "Waiting",
+}
+
 
 def render() -> None:
     s = st.session_state
@@ -58,6 +68,8 @@ def render() -> None:
             st.markdown("**Receipts**")
             for source in summary["sources"]:
                 st.markdown(f"- {source}")
+        else:
+            st.caption("Receipts appear after capture, transcript, or retrieval metadata is recorded.")
         if summary["quotes"]:
             st.markdown("**Quotes / excerpts**")
             for item in summary["quotes"]:
@@ -111,8 +123,12 @@ def _scorecard_panel(scorecard: dict) -> None:
     st.markdown("**Scorecard**")
     st.metric("Verdict", scorecards_mod.compact_verdict(scorecard))
     st.caption("Advisory only; saves are not blocked.")
+    dimensions = scorecard.get("dimensions", [])
+    if not dimensions:
+        st.caption("Detailed scorecard dimensions appear after a full review run.")
+        return
     with st.expander("Scorecard details", expanded=False):
-        for dimension in scorecard.get("dimensions", []):
+        for dimension in dimensions:
             score = int(dimension.get("score", 0))
             st.progress(
                 score / 100,
@@ -129,27 +145,60 @@ def _scorecard_panel(scorecard: dict) -> None:
 def _run_story_panel(s) -> None:
     run_id = s.get("run_id")
     if not run_id:
+        st.caption("Run story appears after this output is linked to a run artifact.")
         return
     try:
         manifest = run_artifacts.load_manifest(run_id)
     except Exception:
+        st.caption("Run story unavailable; the run manifest could not be read.")
         return
     if not manifest:
+        st.caption("Run story unavailable; no manifest was found for this run.")
         return
 
     story = run_story_mod.build_run_story(
         manifest,
         capture_metadata=captures_mod.run_metadata(s.get("capture_id")),
     )
     if not story:
+        st.caption("Run story has no recorded steps yet.")
         return
 
     st.markdown("**Run story**")
     st.caption(f"Run `{manifest.get('run_id') or run_id}`")
     for step in story:
-        status = str(step.get("status") or "unknown").replace("_", " ")
-        detail = step.get("detail") or ""
-        st.markdown(f"- **{step.get('label', 'Step')}** · `{status}`  \n  {detail}")
+        st.markdown(_run_story_step_markdown(step))
+
+
+def _run_story_step_markdown(step: dict[str, str]) -> str:
+    label = step.get("label") or "Step"
+    status = _run_story_status_label(step.get("status") or "")
+    timestamp = _format_run_story_timestamp(step.get("timestamp") or "")
+    detail = step.get("detail") or "No detail recorded."
+    meta = f"`{status}`"
+    if timestamp:
+        meta = f"{meta} · {timestamp}"
+    return f"- **{label}** · {meta}  \n  {detail}"
+
+
+def _run_story_status_label(status: str) -> str:
+    normalized = str(status or "").replace("_", " ").strip().lower()
+    return _RUN_STORY_STATUS_LABELS.get(normalized, normalized.title() or "Unknown")
+
+
+def _format_run_story_timestamp(value: str) -> str:
+    raw = str(value or "").strip()
+    if not raw:
+        return ""
+    candidate = raw[:-1] + "+00:00" if raw.endswith("Z") else raw
+    try:
+        parsed = datetime.fromisoformat(candidate)
+    except ValueError:
+        return raw
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    parsed = parsed.astimezone(timezone.utc)
+    return parsed.strftime("%Y-%m-%d %H:%M UTC")
 
 
 def _review_summary_from_state(s) -> dict:
@@ -226,6 +275,7 @@ def _handoff_panel() -> None:
     s = st.session_state
     sources = _handoff_sources(s)
     if not sources:
+        st.caption("Handoff draft appears after an output, transcript, or capture is available.")
         return
     with st.expander("Agent handoff draft", expanded=False):
         st.caption(
@@ -264,10 +314,29 @@ def _handoff_panel() -> None:
                 st.caption(f"Saved to `{preview['path']}`")
             else:
                 st.caption("Preview only; start a run to persist the draft under run artifacts.")
+            st.download_button(
+                "Download draft",
+                data=_handoff_preview_markdown(preview),
+                file_name=_handoff_preview_filename(preview.get("title") or ""),
+                mime="text/markdown",
+                key="download_handoff_draft",
+                use_container_width=True,
+            )
             st.text_area("Preview", preview.get("body") or "", height=420, key="handoff_preview_body")
             _approval_panel(preview)
 
 
+def _handoff_preview_markdown(preview: dict) -> str:
+    title = str(preview.get("title") or "WhisperForge handoff draft").strip()
+    body = str(preview.get("body") or "").strip()
+    return f"# {title}\n\n{body}\n"
+
+
+def _handoff_preview_filename(title: str) -> str:
+    slug = re.sub(r"[^A-Za-z0-9_.-]+", "-", str(title or "").lower()).strip(".-")
+    return f"{(slug[:80] or 'whisperforge-handoff-draft')}.md"
+
+
 def _approval_panel(preview: dict) -> None:
     s = st.session_state
     st.markdown("---")