Add evaluation result insights

docs/project-worklog.md

@@ -479,24 +479,67 @@ Deferred:
 - Full interactive Docker demo remains pending until Docker is available.
 - Real model weights remain deferred until a GPU server is prepared.
 
-## Next Recommended Work
+### 2026-07-09: Evaluation Result Insights
 
-Continue Phase B from `docs/project-improvement-roadmap.md` with a narrower
-verification and insight branch:
+Branch:
 
 ```text
 feature/evaluation-result-insights
 ```
 
+Commit:
+
+```text
+See the PR commit history after merge.
+```
+
+What changed:
+
+- Added tested frontend insight calculation for evaluation samples.
+- Added a confusion matrix, label distribution, and sample-outcome summary to
+  `/admin/evaluations`.
+- Improved the wrong-sample empty state for completed matching predictions.
+
+Why:
+
+- The evaluation page needed to explain model behavior, not only list runs and
+  aggregate metrics.
+- The change keeps insight logic in a pure utility so future backend aggregation
+  can be compared against frontend expectations.
+
+Verification:
+
+- `npm run test`
+- `npm run lint`
+- `npm run build`
+- `mvn -B test`
+
+Deferred:
+
+- No backend aggregation API was added in this branch.
+- Real model weights remain deferred until a GPU server is prepared.
+- Local headless screenshot verification was attempted with a mocked API, but
+  the temporary Vite process exited before Chrome could capture the page.
+
+## Next Recommended Work
+
+Continue Phase B from `docs/project-improvement-roadmap.md` with a backend
+observability branch:
+
+```text
+feature/evaluation-observability
+```
+
 Scope:
 
-- Add a small confusion matrix or label breakdown to `/admin/evaluations`.
-- Add clearer empty states for runs with no wrong samples.
+- Add structured logs around evaluation execution start, retry, completion, and
+  failure.
+- Add lightweight timing fields or counters that make run latency explainable.
+- Document how to inspect evaluation execution behavior locally and in CI.
 - Keep the deterministic model boundary until GPU weights are available.
-- Preserve the current frontend visual style.
 
 Reason:
 
-The project now has evaluation execution and a usable admin workbench. The next
-interview-visible step is to make model quality easier to explain without
+The project now has evaluation execution and frontend result explainability. The
+next interview-visible step is to show production-minded observability without
 expanding scope into training, video detection, or heavy model operations.

docs/superpowers/plans/2026-07-09-evaluation-result-insights.md

@@ -0,0 +1,117 @@
+# Evaluation Result Insights Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add lightweight evaluation explainability to `/admin/evaluations` without adding backend APIs or model weights.
+
+**Architecture:** Compute insight summaries in a tested pure TypeScript utility, then render the result in the existing React evaluation page. Keep the UI within the current dark admin style and avoid chart dependencies.
+
+**Tech Stack:** React 18, TypeScript, Vite, CSS Modules, Node built-in test runner.
+
+## Global Constraints
+
+- Preserve the current frontend visual style.
+- Do not download model weights.
+- Do not add a chart library.
+- Do not add backend aggregation APIs in this branch.
+- Keep counting logic outside JSX.
+- Verify with `npm run test`, `npm run lint`, `npm run build`, `mvn -B test`, and `git diff --check`.
+
+---
+
+### Task 1: Insight Utility Tests
+
+**Files:**
+- Modify: `package.json`
+- Create: `src/pages/AdminEvaluations/evaluationInsights.test.ts`
+
+**Interfaces:**
+- Consumes future `buildEvaluationInsights(samples: EvaluationSampleResponse[]): EvaluationInsights`.
+- Produces expected behavior for matrix counts, summary counts, and label distribution.
+
+- [ ] Update `package.json` test script to include frontend test files:
+
+```json
+"test": "node --test --experimental-strip-types src/api/errorMessage.test.ts src/pages/AdminEvaluations/evaluationInsights.test.ts"
+```
+
+- [ ] Add a failing test for a mixed sample set:
+
+```typescript
+const insights = buildEvaluationInsights([
+  sample('a.jpg', 'AUTHENTIC', 'AUTHENTIC', true),
+  sample('b.jpg', 'AUTHENTIC', 'SYNTHETIC', false),
+  sample('c.jpg', 'SYNTHETIC', 'SYNTHETIC', true),
+  sample('d.jpg', 'UNCERTAIN', null, null, 'model unavailable'),
+  sample('e.jpg', 'SYNTHETIC', null, null),
+]);
+```
+
+Expected summary:
+
+```text
+total=5, correct=2, wrong=1, failed=1, pending=1
+```
+
+- [ ] Run `npm run test`.
+
+Expected: FAIL because `evaluationInsights.ts` does not exist yet.
+
+### Task 2: Insight Utility Implementation
+
+**Files:**
+- Create: `src/pages/AdminEvaluations/evaluationInsights.ts`
+
+**Interfaces:**
+- Produces `LABELS`, `EvaluationInsightSummary`, `ConfusionMatrixRow`, `LabelDistributionRow`, `EvaluationInsights`, and `buildEvaluationInsights`.
+
+- [ ] Implement fixed labels `AUTHENTIC`, `SYNTHETIC`, `UNCERTAIN`.
+- [ ] Count only samples with a `predictedLabel` in the confusion matrix.
+- [ ] Count `failureReason` samples as failed.
+- [ ] Count samples without `predictedLabel` and without `failureReason` as pending.
+- [ ] Calculate label-distribution percentages as `count / total`, using `0` when total is `0`.
+- [ ] Run `npm run test`.
+
+Expected: PASS.
+
+### Task 3: Evaluation Page Rendering
+
+**Files:**
+- Modify: `src/pages/AdminEvaluations/index.tsx`
+- Modify: `src/pages/AdminEvaluations/AdminEvaluations.module.css`
+
+**Interfaces:**
+- Consumes `buildEvaluationInsights(detail?.samples ?? [])`.
+- Renders summary cards, confusion matrix, and label distribution.
+
+- [ ] Import and memoize `buildEvaluationInsights`.
+- [ ] Add a summary strip below metric cards.
+- [ ] Add a confusion matrix with truth rows and prediction columns.
+- [ ] Add a label distribution panel.
+- [ ] Improve wrong-sample empty copy:
+
+```text
+All completed predictions match the manifest labels.
+```
+
+- [ ] Keep responsive behavior for narrow screens.
+- [ ] Run `npm run build`.
+
+Expected: PASS.
+
+### Task 4: Worklog And Verification
+
+**Files:**
+- Modify: `docs/project-worklog.md`
+
+**Interfaces:**
+- Records the branch, scope, verification, and deferred work.
+
+- [ ] Add a dated worklog entry for `feature/evaluation-result-insights`.
+- [ ] Run `npm run test`.
+- [ ] Run `npm run lint`.
+- [ ] Run `npm run build`.
+- [ ] Run `mvn -B test` in `backend-java`.
+- [ ] Run `git diff --check`.
+- [ ] Commit as `feat: add evaluation result insights`.
+- [ ] Push and open a PR against `main`.

docs/superpowers/specs/2026-07-09-evaluation-result-insights-design.md

@@ -0,0 +1,92 @@
+# Evaluation Result Insights Design
+
+## Purpose
+
+Improve `/admin/evaluations` so an interviewer can understand model behavior
+from one run without reading raw sample rows. The page should explain where the
+model is correct, where it confuses labels, and whether failures are prediction
+errors or execution errors.
+
+## Scope
+
+This branch adds frontend-only insight rendering based on the existing
+`EvaluationDetailResponse.samples` payload.
+
+In scope:
+
+- Confusion matrix for `AUTHENTIC`, `SYNTHETIC`, and `UNCERTAIN`.
+- Ground-truth label distribution.
+- Summary counts for total, correct, wrong, pending, and failed samples.
+- Clearer empty state when a selected run has no wrong or failed samples.
+- Documentation of the work in `docs/project-worklog.md`.
+
+Out of scope:
+
+- New backend aggregation APIs.
+- Model weight download or GPU runtime integration.
+- Charts from a new visualization dependency.
+- Video, training, or dataset management workflows.
+
+## Architecture
+
+Add a focused pure utility module under `src/pages/AdminEvaluations`:
+
+```text
+EvaluationDetailResponse.samples
+  -> buildEvaluationInsights(samples)
+  -> AdminEvaluations insight panels
+```
+
+The utility owns all counting logic and is tested with Node's built-in test
+runner. The React page only renders the computed view model. This keeps business
+math out of JSX and makes later backend/API changes easier to compare against
+frontend expectations.
+
+## UI Behavior
+
+The existing visual style stays intact:
+
+- Use the current dark surface, border, mono labels, and compact panel rhythm.
+- Render the insight section inside the selected-run detail area.
+- Use text tables and small numeric cards rather than a chart library.
+- Keep labels English to match the current admin page copy.
+
+The insight section contains:
+
+- A compact summary strip.
+- A confusion matrix with rows as ground truth and columns as prediction.
+- A label-distribution list showing sample counts and percentages.
+- A wrong-sample empty state that distinguishes "no selected run" from "all
+  completed predictions matched".
+
+## Error Handling
+
+Samples with `failureReason` count as failed samples. Samples with no
+`predictedLabel` and no `failureReason` count as pending samples. Failed and
+pending samples are excluded from the confusion matrix because no final
+prediction exists.
+
+## Testing
+
+Use the existing frontend `npm run test` command and add coverage for:
+
+- Correct confusion-matrix counting.
+- Failed and pending sample classification.
+- Label distribution percentages.
+- Empty sample handling.
+
+Run the full project checks before PR:
+
+```powershell
+npm run test
+npm run lint
+npm run build
+cd backend-java
+mvn -B test
+```
+
+## Approval
+
+The user requested continuing with the next planned branch. This design follows
+the previously recommended `feature/evaluation-result-insights` scope and keeps
+the project focused on interview-visible evaluation explainability.

package.json

@@ -7,7 +7,7 @@
     "dev": "vite",
     "build": "tsc -b && vite build",
     "lint": "eslint .",
-    "test": "node --test --experimental-strip-types src/api/errorMessage.test.ts",
+    "test": "node --test --experimental-strip-types src/api/errorMessage.test.ts src/pages/AdminEvaluations/evaluationInsights.test.ts",
     "preview": "vite preview"
   },
   "dependencies": {