HVTracker Listing Lifecycle Specification
https://hvtracker.net/spec/listing/v0.1
1. Abstract
This document defines the lifecycle states for agent listings in the HVTracker registry. It specifies how agents transition between states, the evidence required at each stage, the evidence grade system, and the HVTrust composite score methodology.
The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119.
2. Motivation
As HVTracker evolves from a leaderboard into a trust registry, agents need a formal lifecycle beyond "tracked or not." A project may be discovered but unreviewed, listed but not yet verified, or previously listed but now delisted due to archival or license changes. The listing lifecycle provides a vocabulary for these states and defines the evidence thresholds for transitions.
3. Listing States
Every agent in the HVTracker registry MUST be in exactly one of the following states:
| State | Description | Visible on site |
|---|---|---|
discovered | Agent identified but not yet reviewed for eligibility. | No |
candidate | Submitted for listing (via issue template or discovery). Under review. | No |
listed | Meets eligibility criteria. Tracked with daily signal collection. | Yes — full leaderboard entry |
verified | Listed + additional manual verification of agent identity and capabilities. | Yes — with verified badge (future) |
warning | Listed but flagged for eligibility issues (archived, no license, stale). | Yes — with warning indicator |
legacy | Historically significant but no longer actively maintained (>365 days inactive). | Yes — in legacy section |
delisted | Removed from active tracking due to disqualification criteria. | No (historical data preserved) |
rejected | Reviewed and determined not to meet eligibility criteria. | No |
4. State Transitions
State transitions are triggered either automatically by the daily build or manually by the registry owner.
| From | To | Trigger | Type |
|---|---|---|---|
| — | discovered | Agent identified in universe scan or external source | Manual |
discovered | candidate | GitHub issue submitted or owner initiates review | Manual |
candidate | listed | Passes all MUST criteria in Eligibility Spec | Manual |
candidate | rejected | Fails eligibility review | Manual |
listed | verified | Owner manually confirms identity and capabilities | Manual |
listed | warning | Automated eligibility check fires (§4.1.1, §4.2.1, §5.1) | Automatic |
warning | listed | Warning condition resolved (e.g., license added, repo unarchived) | Automatic |
listed | legacy | No meaningful activity in 365+ days | Manual |
listed | delisted | Disqualification criterion met (§5.1–5.5 in Eligibility Spec) | Manual |
legacy | listed | Project resumes activity | Manual |
listed and legacy states are used in production. Other states are defined for future use. Transitions are manual; automated state changes will be added in a future version.5. Evidence Grade
Every listed agent receives an evidence grade (A–D) based on how many independent signal types contribute data for that agent. The grade reflects data coverage, not quality.
| Grade | Signal types required | Interpretation |
|---|---|---|
| A | ≥5 | Comprehensive coverage — GitHub + downloads + trust signals + fingerprints + HN |
| B | 4 | Strong coverage — multiple independent signal families |
| C | 3 | Moderate coverage — GitHub + two additional signal types |
| D | 1–2 | Limited coverage — GitHub only or GitHub + one other source |
Signal types counted:
- GitHub — always present (stars, commits, freshness, forks, license)
- Package downloads — npm and/or PyPI weekly downloads are non-null
- Trust infrastructure — OSSF Scorecard score is non-null OR package provenance is present
- Behavioral fingerprints — public action tracking returns data
- Community signals — Hacker News mention count is non-null
6. HVTrust Score
The HVTrust Score is a composite metric (0–100) that measures trust across five dimensions. It is computed alongside the existing health score but uses different inputs and weights.
| Dimension | Max | Inputs |
|---|---|---|
| Activity | 25 | Freshness (days since push, linear decay over 180d, max 15) + commit activity (log-scaled, max 10) |
| Adoption | 20 | Stars (log-scaled vs 100k, max 12) + weekly downloads (log-scaled vs 1M, max 8) |
| Transparency | 20 | License present (8 pts) + OSSF Scorecard contribution (scaled to 12 pts) |
| Safety | 20 | OSSF Scorecard (scaled to 10 pts) + package provenance (5 pts) + signed commits ratio (scaled to 5 pts) |
| Identity | 15 | Evidence grade (A=10, B=7, C=4, D=1) + listing status (listed=5, legacy=2) |
trust_score = activity + adoption + transparency + safety + identity
Relationship to health score: The health score (stars + freshness + activity + community = 100) measures momentum. The HVTrust score measures trustworthiness. Both are displayed; the leaderboard can be sorted by either. The health score formula is unchanged — HVTrust is purely additive.
7. Versioning and Changelog
| Version | Date | Summary |
|---|---|---|
| v0.1 | 2026-05-26 | Initial publication. Defines 8 listing states, transition triggers, evidence grade system (A–D), and HVTrust composite score (5 dimensions, 100 points). |
A. State Diagram
discovered → candidate → listed → verified
↓ ↓ ↑
rejected warning
↓
legacy ↔ listed
↓
delisted
Arrows indicate valid transitions. Bidirectional arrows (↔) indicate the transition can go either way. The delisted state is terminal in practice but historical data is preserved.