Skip to content

Clockwerk Dashboard

Clockwerk is the local project evolution dashboard for Luna and AncientOS. It is a telemetry surface for observing repository progress over time, not a control plane and not a source of authority.

The Governance Kernel defines optional Clockwerk Scheduling as a lifecycle boundary for explicitly approved future review or dispatch windows. The current Clockwerk dashboard remains telemetry only unless a separate governed scheduling implementation is approved.

Purpose

Clockwerk visualizes project scale, scope, architecture maturity, subsystem growth, tests/docs growth, and milestone progression from the local git repository and tracked files.

The first pass includes:

  • cumulative commits over time
  • commit velocity by day, week, and month in the generated JSON
  • recent commit timeline
  • milestone annotations inferred from commit message keywords
  • domain classification for Keeper, Lich, Naga, Roshan, Rubick, Meepo, Oracle, Runtime, Docs, Tests, Governance, Console/UI, and Scheduling
  • current repo summary including tracked files, Python files, tests, docs, services, app subsystems, SQL migrations, compose services, endpoint count, and text LOC
  • architecture/capability timeline inferred from commit subjects

Launch And Access

Clockwerk is defined as the clockwerk Docker Compose service.

docker compose up -d clockwerk

Local access:

http://127.0.0.1:8024/

Tailscale phone access uses the same private-local pattern as Keeper Console: open the host's Tailscale IP or MagicDNS name on port 8024.

http://<tailscale-hostname-or-ip>:8024/

The compose binding is 0.0.0.0:8024:8000, intended for local LAN/Tailscale reachability. Do not publish this service to the public internet.

Data Generation

Clockwerk reads local git history and tracked repository files. It writes a generated artifact to:

data/luna_dashboard/evolution.json

The artifact includes:

  • schema_version
  • generated_at
  • source_commit
  • summary metrics
  • commit series
  • repository surface metrics
  • architecture timeline

The dashboard serves cached data from the artifact and regenerates only when the artifact is missing or when a user manually presses Refresh, which calls POST /api/refresh.

API

  • GET /health
  • GET /api/evolution
  • POST /api/refresh
  • GET /

Policy

Clockwerk is observational only.

  • It does not mutate project history.
  • It does not use external SaaS.
  • It does not use the GitHub API.
  • It does not run an autonomous scheduler or hidden background refresh loop.
  • It does not import Keeper internals.
  • It writes only the generated JSON artifact under data/luna_dashboard.

Metric Limitations

Commit counts are activity indicators, not value indicators. A single commit can contain a major subsystem or a small fix.

LOC and file counts show surface area, not quality or maturity. Generated files, documentation structure, and refactors can change these numbers without changing capability.

Test count is a lightweight pytest-style AST count. It does not prove coverage, assertion quality, integration depth, or runtime health.

Endpoint count is a lightweight FastAPI decorator scan. It can miss routes created dynamically and can count inactive or test-only route declarations.

Domain and milestone classification are keyword-based. They are useful for trend visibility, but they should be treated as annotations rather than canonical architecture records.