# Methodology

This document is public on purpose. Builders and agents should be able to see exactly
how readiness scores are produced, how facts are cited, and what our conflict-of-interest
rules are. Transparency is the point — a reproducible score beats an authoritative one.

## Readiness scoring

- **Deterministic and build-time.** Scores are recomputed on every build by
  `scripts/lib/score.ts` (version `score.v2`). They are never hand-entered or stored in
  the canonical YAML. `git log protocols/<slug>.yaml` is the score history.
- **Range:** 0–100.

### Factors and weights (score.v2)

| Factor | Max points | What earns it |
|---|---|---|
| `docs_present` | 10 | A docs URL is present. |
| `sdk_present` | 8 | An SDK URL is present. |
| `template_present` | 6 | A template/quickstart URL is present. |
| `support_present` | 6 | A support channel URL is present. |
| `capability_depth` | 20 | Weighted capability types, capped at 20 points. |
| `production_capability` | 15 | At least one capability is `production-ready`. |
| `provenance_confidence` | 5 | High confidence = 5, medium = 3, low = 1. |
| `chain_coverage` | 10 | 2 points per supported chain, capped at 5. |
| `freshness` | 10 | Freshest `verified_at` ≤ 60 days = 10; ≤ 180 days = 5; older = 0. |
| `no_open_critical` | 10 | No open `critical` known issue. |

Capability depth is intentionally weighted instead of counted. A platform primitive is
not the same signal as a small feature flag.

| Capability type | Points |
|---|---:|
| `feature` | 3 |
| `agent_workflow` | 4 |
| `integration_workflow` | 5 |
| `production_surface` | 8 |
| `ecosystem_primitive` | 8 |

### Hard caps

Applied after summing factors:

- No public docs → score capped at **60**.
- An open `critical` known issue → score capped at **70**.
- Only `low`-confidence evidence among known issues → score capped at **80**.

### Known limitation

The scorer still depends on record quality. `score.v2` improves platform records by
weighting capability depth, but meaningful differentiation still needs richer evidence:
cited known-issues, SDK release recency, example freshness, and real integration-failure
reports. The fix is more evidence, not per-protocol nudging.

## Citations

- Every non-obvious claim should carry a citation: source URL, verbatim quote,
  `retrieved_at` date, and a `confidence` of low/medium/high.
- Protocol-level `sources` (attribution links) are distinct from per-claim `citations`.
- `verified_at` on a field means a human confirmed that specific fact as of that date.

## Source freshness

- `verified_at` is updated whenever a fact is re-checked, even if unchanged.
- Freshness contributes directly to the readiness score.
- A scraper service (planned) will open PRs proposing freshness refreshes; humans review
  and merge. No bot merges.

## Conflict of interest

- **No paid placement.** Position in a recommended stack is never for sale.
- **No scoring uplift for payment or protocol-team status.** A protocol team's own
  contributions go through the same review and the same deterministic scorer as anyone
  else's.
- If a paid contribution intake is ever introduced, it will buy **faster review only**,
  every paid-originated claim will be flagged `paid: true`, and it will have **zero**
  influence on scores or ranking. This rule exists so the registry never becomes
  ad-shaped to the models that ingest it.

## Corrections

Open an issue or a PR. Corrections to cited facts are prioritized. Disputed protocol-team
claims are resolved by a human reviewer, not automatically.

## Release integrity (Ethereum binding)

Releases are trustlessly verifiable, so you do not have to trust the maintainer to believe a
published record is the one that was reviewed:

1. Each build hashes every rendered `protocols/<slug>.json` (sha256) and computes a
   `merkle_root` over those hashes (sorted leaves, odd nodes promoted). Both go in
   `manifest.json`.
2. The deploy/anchor step pins `dist/` to IPFS, sets the `composewith.eth` ENS `contenthash`
   to the resulting CID, and records `{version, cid, merkleRoot}` in an onchain
   `ReleaseRegistry` (Arbitrum One). Releases are immutable — a version cannot be overwritten.
3. **To verify a release yourself:** fetch the content at `composewith.eth` (IPFS), recompute
   each protocol's sha256 and the merkle root, read the onchain `ReleaseRegistry` entry for that
   `version`, and assert the CID and root match. If they do, the data is exactly what was anchored.

Git remains the authoring layer (where edits and review happen); Ethereum is the publication and
verification layer. There is no gas cost to propose or review a change — only to publish a release.

## Protocol-owner claims

Ownership is recognized only with identity proof — e.g. a signed message or a statement
from a GitHub account verifiably tied to the protocol team (such as the org that owns the
SDK repository). Ownership grants review standing, not edit authority or score control.