Dashboard: real metrics, "needs your attention" panel, next-step actions

[carthworks]

Implements dashboard improvements 1–3 from the UX review.

1. Real numbers instead of placeholders

• OCR confidence: the card showed a hard-coded 99.4%. It now averages Tesseract's real mean word confidence, stored per document in ocr_text.mean_confidence. The value comes from the same image_to_data pass, so OCR does no extra work. Before any OCR it shows "—".
• Archives: the card said "PDF/A-1b". It now counts real archive packages and splits them into PDF/A-2b and standard PDF.
• Project list: GET /api/projects now includes title, has_archive, archive_format and mean_confidence, so the dashboard needs no extra requests.

2. Lead with "what needs me next"

• Header: the large hero banner is replaced by a one-line status ("3 documents waiting on you") and the main actions. Catalogue export moves into an Export menu (CSV / XML).
• Processing now: background OCR jobs with live page progress and a Stop button. The useActiveJobs hook polls every 1.5 s while jobs run and every 8 s when idle, and reloads documents when a job finishes.
• Up next: documents waiting on the user, oldest first, each with its next action.

3. One obvious next step per document

• Next-step buttons: every card and table row has an always-visible button: Run OCR → Review text → Add metadata → Create archive → View archive. A document with a running job shows its progress instead.
• Consistent stages: tabs, counts and labels all derive from one helper (src/utils/workflow.js). A document with metadata saved but no package built no longer shows as "Archived".
• Run OCR resumes the document: the Upload page accepts ?project=<id>. "Run OCR" from the dashboard continues that document (before, it opened an empty upload form). If its OCR is already running, the page reattaches to the live progress.
• Empty state: explains the three steps instead of showing zeroed metrics.

Testing

• Backend: 44 tests pass (ruff clean, veraPDF enabled). The workflow test now checks mean_confidence (80–100 for a clean scan) and has_archive/archive_format in the project list.
• ESLint: 0 errors. Build passes.
• In the browser, with documents seeded at every stage plus a running 6-page Advanced OCR job:
  • The panel showed live progress, and Stop cancelled the job and cleared the row.
  • "Run OCR" opened /upload?project=4 with that document loaded.
  • Clicking the running job's title reattached to "Analysing page 5 of 6".
  • Counts are consistent: 3 waiting = 1 OCR + 1 review + 1 to archive, with the running document excluded.
  • No page errors.

Known, not in scope

Below about 400 px wide the sidebar covers the whole page. This predates this PR. It only affects the web build, because the desktop window has a 1200 px minimum.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jze3nDgZGqUXGceiu5RCAf

---

Generated by Claude Code

[ecc-tools]

ECC Tools / Security Evidence

Commit: 3d91459b4261fd3eeeb256cdadd6d6da6373fd4f

Security scanner evidence required (action_required)

Detected 1 security-sensitive predictive risk signal(s) without scanner evidence.

Mode: enforce

Findings:

• Security-sensitive changes may ship without scanner evidence: The PR touches billing, secrets, auth, webhooks, agent, or CI-sensitive surfaces without adding obvious security scanner, code scanning, or security-focused validation evidence. (1 security-sensitive paths changed; 0 security scanner or security-focused validation artifacts changed)

Touched security-sensitive paths:

• src/hooks/useActiveJobs.js

Expected evidence:

• Security scanner, code scanning, secret scanning, dependency/security review, or focused security regression output.
• SARIF/code-scanning upload or equivalent pass/fail gate for the changed surface.

Check publication was denied or unavailable. An app owner must enable Checks: read and write, and the installation owner must approve the updated permission.

[ecc-tools]

ECC Tools / PR Risk Taxonomy

Commit: 3d91459b4261fd3eeeb256cdadd6d6da6373fd4f

PR taxonomy review recommended (neutral)

Detected 2 PR taxonomy bucket(s): Security Evidence, CI/CD Recommendation.

Scanned 12 changed file(s).

Roadmap taxonomy buckets:

Security Evidence

Security-sensitive changes should carry explicit scanner, code-scanning, or focused regression evidence.

Signals:

• Security-sensitive changes may ship without scanner evidence
• 0 security-sensitive path(s) changed

Paths:

• backend/app/db.py
• backend/app/routes/batch.py
• backend/app/routes/projects.py

CI/CD Recommendation

CI, dependency, coverage, and contract signals should be routed into follow-up checks or verification work.

Signals:

• Regression coverage may lag behind the diff
• API contract changes may ship without integration coverage
• API implementation changes may ship without contract artifact updates
• User-facing UI changes may ship without browser coverage
• 0 CI or workflow path(s) changed

Paths:

• backend/app/db.py
• backend/app/routes/batch.py
• backend/app/routes/projects.py
• backend/app/services/ocr.py
• backend/app/services/ocr_tasks.py
• backend/tests/test_workflow.py
• src/components/NeedsAttention.jsx
• src/hooks/useActiveJobs.js

Check publication was denied or unavailable. An app owner must enable Checks: read and write, and the installation owner must approve the updated permission.

[ecc-tools]

ECC Tools / Reference Set Readiness

Commit: 3d91459b4261fd3eeeb256cdadd6d6da6373fd4f

Reference set readiness gaps detected (neutral)

Reference evidence present for 0/7 areas (0%) across 12 changed file(s).

This check is based on files changed in this PR. Repository-level readiness is still reported by /ecc-tools analyze comments and generated manifests.

Area	Status	Evidence / Next Step
Deep analyzer corpus	Missing	Add analyzer fixture, golden, benchmark, or reference-set files that can catch analyzer regressions.
RAG/evaluator comparison	Missing	Add retrieval or evaluator reference-set comparison fixtures with expected ranking behavior.
PR salvage/review corpus	Missing	Add stale-PR, review-thread, reopen-flow, or salvage reference cases for queue cleanup automation.
Discussion triage corpus	Missing	Add public discussion triage fixtures, golden cases, or reference sets for informational, answered, and no-response classifications.
Harness compatibility	Missing	Add cross-harness, adapter-compliance, or harness-audit evidence for Claude, Codex, OpenCode, Zed, dmux, and agent surfaces.
Security evidence	Missing	Attach security evidence such as SBOMs, SARIF, audit reports, or AgentShield evidence packs.
CI failure-mode evidence	Missing	Add captured CI failure logs, dry-run fixtures, or troubleshooting docs for common workflow failure modes.

Check publication was denied or unavailable. An app owner must enable Checks: read and write, and the installation owner must approve the updated permission.

[ecc-tools]

ECC Tools / Hosted Promotion Readiness

Commit: 3d91459b4261fd3eeeb256cdadd6d6da6373fd4f

Hosted promotion readiness passed (success)

No hosted promotion evidence gaps detected across 12 changed file(s); 0 corpus scenarios had matching evidence.

This check compares PR file changes against the evaluator/RAG promotion corpus in src/analyzers/fixtures/evaluator-rag-corpus.ts.
Hosted output scoring inspected 0 completed cached hosted job results.

No evaluator corpus scenarios matched this PR.

Check publication was denied or unavailable. An app owner must enable Checks: read and write, and the installation owner must approve the updated permission.