Repository Intelligence Dashboard

Decision

Publish one static, repository-scoped dashboard at the site’s /intelligence/ surface. Empathy currently serves that surface at https://egohygiene.github.io/empathy/intelligence/ until its custom domain is configured. The dashboard summarizes authoritative scanner outputs rather than replacing their native reports, SARIF uploads, or GitHub Security-tab integration.

The dashboard is a public, compact projection. Raw logs, SARIF payloads, workflow artifacts, and any private workflow context remain outside the site.

User-facing model

The landing page should answer four questions at a glance:

Area	Canonical source	Dashboard value
Dependency risk	OSV summary	Severity counts, scanned ecosystems, threshold, freshness, and report link.
Code and configuration quality	MegaLinter summary	Passing/failing tool counts, selected profile, freshness, and report link.
Supply-chain posture	OpenSSF Scorecard	Overall score, check-level status, freshness, and source link.
Repository vitality	Deterministic local collector	Default branch, latest commit, contribution/activity metrics, automation posture, and report links.

Every card must present execution state separately from finding state. For example, a successful OSV run can still report vulnerabilities, while a failed MegaLinter run may still publish a valuable curated snapshot.

Data contract

Each authoritative workflow publishes a small, versioned JSON summary under .reports/<producer>/summary.json. The dashboard builder reads only those committed summaries plus repository metadata available in the checkout.

Required common fields:

{
  "schema": "egohygiene.repository-report-summary/v1",
  "schema_version": 1,
  "producer": "osv",
  "repository": "egohygiene/empathy",
  "generated_at": "2026-08-14T12:41:52Z",
  "commit": "<40-character-sha>",
  "freshness": {
    "expires_at": "2026-08-22T12:41:52Z",
    "stale_after_days": 8
  },
  "execution": {
    "state": "success",
    "message": "Canonical OSV JSON and SARIF outputs were validated."
  },
  "findings": {
    "state": "attention",
    "total": 2,
    "blocking": 0,
    "advisory": 2,
    "by_severity": { "medium": 2 }
  },
  "provenance": {
    "event": "push",
    "workflow": "OSV Vulnerability Scan",
    "run_id": "123456789",
    "run_attempt": 1
  },
  "links": {
    "detail": "https://github.com/egohygiene/empathy/tree/<sha>/.reports/osv",
    "workflow": "https://github.com/egohygiene/empathy/actions/runs/123456789",
    "security": "https://github.com/egohygiene/empathy/security/code-scanning",
    "source": "https://github.com/egohygiene/empathy/commit/<sha>"
  },
  "osv": {}
}

Producer-specific fields remain namespaced below their own object. Missing, stale, or schema-incompatible reports render as unknown or stale; they must never become a misleading green result.

Delivery architecture

canonical scanners and collectors
  -> stable .reports/<producer>/summary.json snapshots
  -> pinned Relay repository-intelligence action
  -> .cache/mindgarden/site/intelligence/
  -> repository-owned GitHub Pages composition and deployment

Relay owns the reusable collectors, schemas, normalizers, renderer, assets, and guarded report publisher. Empathy owns its scanner configuration, normalized report snapshots, Mindgarden build, final site composition, Pages permissions, and immutable Relay version selection. The shared action writes only the intelligence/ subtree and cannot deploy or replace the rest of the site.

Delivery slices

1. Promote the universal dependency-review gate and record the staging migration decisions. Complete.
2. Define a shared, versioned producer contract; normalize OSV and MegaLinter; and publish a compact OpenSSF Scorecard summary through the existing trusted report-publication action. Complete.
3. Add a dashboard builder action with fixtures for OSV, MegaLinter, Scorecard, repository vitality, and unavailable/stale inputs. Emit summary.json, index.html, and a small accessible stylesheet with no client-side framework. Complete.
4. Extend the Mindgarden Pages build job to place the generated dashboard at intelligence/ beside the Quartz site and add a garden link to it. Complete.
5. Extract the stable builder and caller contract to Relay, replace Empathy’s incubated implementation with an immutable thin consumer, and prove the released contract in Akashic and Optiflow. In progress.

Dashboard expansion roadmap

1. Create commit-scoped, versioned repository-tree and public analytics contracts. Normalize historical paths, remove generated and vendored churn, and guarantee that public projections contain no contributor identities or commit messages. Complete.
2. Render accessible line, donut, and horizontal-bar statistical snapshots from the public analytics contract, with semantic table fallbacks. Complete.
3. Add a searchable, collapsible repository anatomy explorer sourced from the commit-scoped tree contract, with source-pinned links and consistent icons. Complete.
4. Add historical scanner deltas, sparklines, deterministic insight callouts, and final responsive and accessibility polish.

Grafana and Prometheus

GitHub Pages is the right first surface: zero persistent service, public by default, versioned in Git, and readable when no observability stack is running.

Prometheus and Grafana fit one level up in observatory, not inside each repository. A scheduled collector can read each repository’s compact public summary and expose metrics such as repository_scan_findings_total, repository_report_age_seconds, and repository_workflow_state, labelled by repository, producer, severity, and default branch. Grafana then provides cross-repository trends, alerting, and operational views. Realm can later host that optional stack for the organization without making it a prerequisite for repository publishing.

Guardrails

• Do not scrape or publish raw workflow logs, tokens, artifact download URLs, or unreviewed issue data.
• Do not duplicate scanners merely to feed the dashboard.
• Keep raw SARIF in GitHub Code Scanning and stable summaries in .reports/.
• Treat report freshness and schema validation as first-class states.
• Keep PRs read-only; only trusted default-branch, scheduled, or manual runs may publish stable report snapshots.
• Enable the dependency-review profile only after GitHub Dependency Graph is enabled, by setting the repository variable DEPENDENCY_REVIEW_ENABLED=true.