Organization Harness usage dashboard

Traceability

• Spec ID: 2026-09-01-organization-harness-dashboard
• Status: Implemented
• Extended by: 2026-09-01-task-evidence-upload-end-to-end, which supplies the stored evidence AC-8 projects, replaces the process-lifetime data cache with a bounded refresh window, and widens the collected host set.

Intent

Create a private @qoder-ai/harness-ui Next.js dashboard whose visible metrics are projections of data that Better Harness scripts collect from the current workspace. The first screen is a calm, standalone shadcn-style analytics page, not a Harness Studio workbench and not a speculative organization-governance console. Production UI must not fall back to sample organization, session, usage, context, asset, or upload values.

The source contracts are:

• better-harness.session-usage-summary schema version 1 from scripts/session-analysis/usage-summary.mjs;
• usageActivity schema version 3 from scripts/session-analysis/daily-usage.mjs and the findings.json report;
• contextUsage from the task-loop report, including observed context-window occupancy, bounded category token estimates, item coverage, and native Cursor evidence status;
• agent-lint with the agent-assets-review profile from scripts/agent-lint/index.mjs, including its configured Skills, MCPs, Hooks, Commands, Rules, Agents, and Plugins summary;
• better-harness.task-evidence-packet schema version 1 from scripts/task-evidence-upload/contract.mjs.

Dashboard selectors may derive display rows, cross-host totals, and percentages from those shapes, but may not introduce a metric that has no source field or documented formula. Test fixtures remain test-only and are never the normal page data source.

Acceptance Scenarios

• AC-1 — Script-shaped input: the Dashboard adapter accepts the existing usage summary, daily activity, agent asset inventory, and task evidence packet shapes. Tests build inputs with the real script functions before passing them to the UI adapter.
• AC-2 — Honest overview: the usage headline metrics are analyzed sessions, estimated active minutes, model responses, and observed Skill invocations. Exact cost, first-pass success, intervention rate, autonomy readiness, and invented organization outcomes are absent.
• AC-2a — Organization asset inventory: a separate overview shows summed configured instances of Skills, MCPs, and Hooks across supplied project inventory reports. Commands, Rules, Agents, and Plugins use the same contract and can be expanded without introducing a new metric model. The UI does not call configured instances unique assets or quality scores.
• AC-3 — shadcn chart composition: the primary card follows the shadcn Area Chart composition: neutral card shell, restrained typography, chart tooltip, range control, and an area fill used only as data encoding. Users can switch between session starts and estimated active minutes without mixing units on one axis.
• AC-3a — Skill trend, not ranked decoration: Skill activity uses the existing date-aligned usageActivity.skills[].daily series in a chart with a bounded Skill selector. The ranked progress-bar list is removed.
• AC-4 — Evidence boundary: accounting mode, analyzed coverage, usage-field coverage, semantic-review state, warning codes, and exact-cost availability remain preserved in the source contract. The Dashboard does not convert them into outcome metrics or render them as a competing review panel.
• AC-4a — Usage and context quantities: token totals keep input, output, cache-read, and cache-creation lanes from the usage summary. Context-window occupancy and category estimates appear only when contextUsage.status is observed; unobserved inputs do not produce category claims.
• AC-4b — Token charts own token evidence: usageActivity.tokens adds date-aligned daily input, output, cache-read, and cache-creation totals from normalized response events. The Token section uses four compact daily charts, one each for input, output, cache-read, and cache-creation; it does not synthesize dates from the aggregate totals. A provider without non-zero token observations contributes neither zero-filled daily points nor false coverage.
• AC-5 — Existing detail only: the bounded Model chart switches between response count and usage-field-observed count from modelUsage; Skill series come from usageActivity.skills, and task rows come from prepared evidence packets and their existing acceptance, asset, observation, and privacy coverage fields.
• AC-5a — Remove internal review chrome: the Dashboard does not render the Data quality/Coverage card. Accounting and review-boundary fields remain in the source contract for other consumers, but they are not a primary organization Dashboard visualization.
• AC-6 — Independent responsive UI: the page has no Studio sidebar, pane chrome, or Inspector hierarchy. It remains usable at 1440x900, 1024x768, and 390x844 with bounded charts/tables, visible focus, and no page or console errors.
• AC-7 — Honest missing-data boundary: the normal page runs the local session-analysis and agent-lint collectors. A missing source hides its dependent section or produces one actionable empty state; sample values, sample organizations, and prepared test uploads never replace it.
• AC-8 — Current upload end to end: a fixture runs through the real better-harness upload plan CLI, writes and validates a plan artifact, preserves the no-network/no-remote-mutation boundary, redacts private input, and projects the resulting packet into the Dashboard and browser view.

Non-goals

• Implementing Protobuf/Buf ingestion, PostgreSQL, authentication, or remote live-data refresh.
• Restoring AG-UI or placing Agent execution inside the Next.js application.
• Aggregating unavailable task outcomes, quality, cost, review, or autonomy metrics.
• Reusing Harness Studio navigation or visual hierarchy.
• Publishing the package to npm.
• Rendering a product hero, organization switcher, or duplicated Dashboard title above the observed data.

Plan and Tasks

1. Recreate packages/harness-ui as a private Next.js application with a narrower shadcn-style Dashboard contract.
2. Add a server-only local collector and typed adapter over the existing script output shapes; aggregate host series only after aligning their UTC dates.
3. Build one responsive Overview page: observed asset inventory, source-backed session, Skill, Token, and optional context charts, plus model activity. Render prepared task evidence only when the input actually contains it; omit the internal evidence-boundary card from this surface.
4. Extend usageActivity at its existing daily-usage owner with date-aligned Token lanes, then update its validator and focused contract tests.
5. Test projections with inputs generated by the actual scripts, then run typecheck, production build, and Playwright visual checks.
6. Keep the rendered view dense: explanatory contract detail belongs in the spec, tooltips, or compact status labels rather than large Dashboard copy.

Later service boundary

Keep better-harness upload as the producer of task evidence semantics. A future Buf module should encode the existing packet rather than redesign it. The ingestion service validates organization identity, idempotency, digest, and schema version, then stores packet metadata in PostgreSQL and optional large evidence blobs in object storage.

2026-09-01-task-evidence-upload-end-to-end implements that validation shape locally: the bundled /api/upload route checks schema, digest, and organization before storing one record per packet digest. It is a local destination for the local Dashboard, not a deployed control plane, and Next.js remains outside Agent execution.

Test and Review Evidence

• AC-1, AC-2, AC-2a, AC-4, AC-4a, AC-4b, AC-5, AC-7, AC-8:npm test -w @qoder-ai/harness-ui passes 22 projection, local aggregation, upload-store, and upload-chain tests. The primary test builds its inputs with buildUsageSummary, buildDailyUsageActivity, runAgentLint, and createTaskEvidencePacket, then verifies the displayed totals, daily token accounting lanes, observed context-window occupancy, aligned cross-host daily series, and the absence of cost and autonomy fields in the overview model. The normal page calls the local collector rather than importing a preview fixture. The daily-usage owner and task-loop validator pass 140 focused tests, including schema version 3 token totals/date alignment. The upload-chain test invokes the real CLI, validates the written plan and digest, proves private path and token redaction, asserts network: none and remoteMutation: false, and projects the emitted packet as TASK-42.
• AC-3, AC-3a, AC-4b, AC-5a, and AC-6:npm run build -w @qoder-ai/harness-ui produces the dynamic Next.js route. npm run test:browser -w @qoder-ai/harness-ui passes one interaction at 1440x900, 1024x768, and 390x844. It checks the usage area chart, Skill bar chart, four Token area charts, Model metric chart, metric/range controls, visible chart focus, accepted evidence loaded through the real CLI, removed Data quality heading, bounded horizontal overflow, three screenshots, and no failed resources, console errors, or page errors.

The remaining product boundary is explicit: asset totals are configured instances summed across supplied inventory reports, active time is an estimate, and the page remains a script-aligned preview until remote upload exists.