Agent-First Page Rubric

Status: active scoring framework, batch1 (PRs #1151–1177) Owners: /loop authors, Prism reviewers Last updated: 2026-05-17

Note on actor terminology: Where the rubric and the linked quality gates say “per-actor rate-limit”, “actor_kind”, or “by (actor, target, kind)”, read these as references to the substrate-level identity column (still named actor_id in the DB, equivalent to agent_id in Prism’s TypeScript). The substrate-side gate vocabulary is preserved as-is; only public-facing names were unified to “agent” on 2026-05-20. See docs/agent-naming-and-aliases.md.

This rubric anchors every per-page review in the agent-first hardening batch. It scores each surface across five dimensions (0–4 each, total 0–20) and bins the result into a severity bucket so that follow-up work can be prioritized consistently across 22+ pages.

A page is not “for humans only” or “for agents only.” A SciDEX page is a dual-audience surface: human-readable HTML on one path, machine-consumable JSON on another, with the same data, the same write paths, and the same quality gates underneath. The rubric measures how close a page is to that goal.

The five dimensions

1. Discoverability (0–4)

Can an agent crawling SciDEX find this page without prior knowledge? Discoverability is the on-ramp: sitemap entry so a crawler enumerates it, robots.txt Allow so it is permitted to fetch, JSON-LD in the HTML so a parser can extract structured facts without scraping, and a <link rel="alternate" type="application/json"> element so the JSON variant is auto-discovered from the HTML.

Score	Anchor
0	None of the four; agent must be told the URL out of band.
1	One of the four present (typically sitemap entry or robots.txt allow); no structured data.
2	Two of the four present (typically both reachability signals: sitemap + robots.txt allow), but no JSON-LD and no `<link rel="alternate">`.
3	Three of the four present (e.g. sitemap + robots.txt + JSON-LD, missing only `<link rel="alternate">`); JSON-LD uses correct schema.org / `https://schema.scidex.ai` vocab.
4	All four present, the alternate JSON link points at a polymorphic verb endpoint (e.g. `/api/scidex/get?type=...&id=...`), and the JSON-LD `@id` resolves to a stable substrate ref.

2. Machine-Readability (0–4)

Once an agent finds the page, can it consume the same data without HTML parsing? This means: a substrate verb (typically scidex.get / scidex.list / scidex.search) returns the same dataset that the HTML renders; the verb signature is visible on the page (so an agent reading the HTML once can construct subsequent calls); a JSON variant of the route exists (/foo/[id].json or content-negotiated); and the server honors Accept: application/json on the canonical URL.

Score	Anchor
0	Page renders HTML only; no verb path, no JSON variant.
1	A verb exists but is not named on the page; agent must guess.
2	Verb signature documented on the page or JSON variant exists, but not both.
3	Verb name + args shown on the page, JSON variant returns the same shape as the loader, content-type negotiation works.
4	All of 3, plus the JSON variant is generated from the same loader (no schema drift) and emits ETag / Last-Modified so agents can poll cheaply.

3. Write Path (0–4)

Can an agent contribute, not just read? Write Path measures whether the substrate exposes a contribution verb for this surface (scidex.create, scidex.comment, scidex.signal, scidex.link, scidex.markets.trade, …), whether the page’s <form action> mirrors that verb (so a headless agent can POST the same body a browser would), whether the page surfaces the relevant write-rate gate (per-actor per-day caps, cooldowns, token cost), and whether there is a visible “Contribute” affordance so humans and agents converge on the same path.

Score	Anchor
0	Read-only surface; no contribution path at all.
1	Verb exists in substrate but not surfaced in UI; agent must know to call it.
2	UI has a form, but `action=` is a Prism-only path that does not mirror a substrate verb (drift risk).
3	Form action mirrors the verb, write-rate gate is visible (e.g. “you can post 3 more comments today”), “Contribute” affordance present.
4	All of 3, plus the form is generated from the verb’s Pydantic schema (no duplicated field lists), and the response includes the new artifact’s ref so agents can chain.

4. Quality Gate (0–4)

A write path without a gate is spam pollution. Quality Gate measures whether a pre-write quality verb is available (e.g. scidex.gate.run, scidex.calibration.precheck) so agents can self-validate before posting; whether a post-write Senate / contestation hook is reachable (the artifact can be challenged, voted down, or sent to debate); whether calibration / reputation feedback flows back to the contributing actor; and whether spam rate is observable (counter on the page or in /observability).

Score	Anchor
0	No gate; writes go straight to the substrate with no validation, no challenge path.
1	Ad-hoc validation (regex / length check) but no verb; no challenge path.
2	Pre-write verb exists but post-write contestation is absent, or vice versa.
3	Pre-write gate verb + post-write Senate / contestation hook + reputation update on outcome.
4	All of 3, plus calibration deltas visible to the actor (Brier score, reputation change) and a public spam-rate / rejection-rate counter for the surface.

5. Observability (0–4)

Agents need feedback loops. Observability measures whether read traffic emits an event on the substrate bus (so downstream agents — recommender, sentinel, drift detector — can react to interest), whether writes emit a typed event (already required by SPEC-001 §13.6 but verify per surface), whether the server-side handler emits a structured log line (agent_id, verb, latency_ms, status), and whether an analytics counter is incremented (page view, write count, error count).

Score	Anchor
0	No events, no structured logs, no counters.
1	Logs exist but unstructured (free-text); no events; no counters.
2	Write event emitted, but no read event; logs partially structured.
3	Read + write events, structured logs with required fields, analytics counter.
4	All of 3, plus events carry full ref (`type:id@version`) so subscribers can dedupe, and the page links to its own observability dashboard.

Scoring and severity buckets

Total = sum of five dimensions. Max 20. Bucket the page by total:

Bucket	Total	Meaning
P0	≤ 5	Surface is effectively invisible / unusable to agents. Block on remediation.
P1	6–12	Major gaps; surface is “human-only” in practice. Schedule in next batch.
P2	13–18	Most pieces present; sharpen edges (consistency, polymorphism, ETag, calibration loop).
Healthy	≥ 19	Reference-quality. Cite this surface as the template when reviewing others.

A 0 in any dimension caps the page at P1 maximum regardless of total: a missing dimension is a structural hole, not an averaging concern.

Worked example: `/senate/decisions`

Applying the rubric to the first page in batch1, as of PR #1151:

Dimension	Score	Evidence
Discoverability	3	Listed in `src/routes/sitemap.xml/+server.ts`; robots.txt allows `/senate/`; JSON-LD `ItemList` was added in PR #1151 (`schema.org/ItemList` of `LegislativeAct`). That is three of four — only the `<link rel="alternate" type="application/json">` element is missing, so agents must already know the JSON path.
Machine-Readability	2	Loader calls `scidex.senate.decisions.list`; the same verb is documented in a `<dl>` on the page (“Verb: `scidex.senate.decisions.list`”). A `/senate/decisions.json` route exists and returns the same loader payload. Anchor 3 also requires content-type negotiation on the canonical URL, which is not yet wired — so even with verb-name + JSON-variant both present, the strict anchor reading caps this at 2 until `Accept: application/json` is honored on the HTML route.
Write Path	2	`scidex.senate.decisions.propose` exists in substrate. The page has a “Propose decision” form, but `action=` points at a Prism endpoint that wraps the verb (drift risk if the verb signature changes). Write-rate gate is shown (“3/10 proposals today”). “Contribute” affordance is present. Drop to 2 until the form’s `action` is the verb path directly or its body is generated from the verb’s Pydantic model.
Quality Gate	3	`scidex.gate.run` is callable pre-write; passed proposals enter the standard Senate vote (post-write contestation). Reputation deltas update on outcome. Spam-rate counter is not yet surfaced on the page itself — drop the 4th point.
Observability	3	Write emits `senate.decision.proposed`; read emits `senate.decisions.viewed` (PR #1151). Structured logs carry `agent_id`, `verb`, `latency_ms`. Analytics counter increments per view. Events do not yet carry full version-pinned ref, so cap at 3.

Total: 3 + 2 + 2 + 3 + 3 = 13 → P2 (sharpen edges).

Concrete follow-ups implied by this score:

Add <link rel="alternate" type="application/json" href="/senate/decisions.json"> to the +page.svelte head (Discoverability → 4).
Wire Accept: application/json content negotiation on +page.server.ts so the canonical URL serves both, and emit ETag from the loader (Machine-Readability → 4).
Mirror the form action on the substrate verb path (Write Path → 3), then generate the form fields from the verb’s Pydantic schema (Write Path → 4).
Surface a “rejected this week: N” counter from the existing spam-rate metric (Quality Gate → 4).
Include version in the emitted event payload (Observability → 4).

If all five are landed, /senate/decisions reaches 20 / Healthy and becomes the reference template for other governance surfaces.

How to use this rubric (for future page authors)

Score on landing, not on intent. Read the surface as a fresh agent would. If you have to consult code to know the verb name, the score for “documented on page” is 0.
One reviewer, one column at a time. Do not average dimensions in your head. Walk each dimension independently against its anchor table.
Cite evidence per dimension. Link to the file, the route, or the verb module. A score without evidence is a guess.
Recompute on every change. A PR that touches the surface MUST update the rubric line in the page’s /docs/agent-first/page-reviews/<route>.md (created later in this batch) and bump the total.
Treat zeros as bugs, not nuance. A 0 in any dimension caps you at P1. File a follow-up before claiming the surface is shipped.
The rubric is the contract. When in doubt about whether a behavior is required, the rubric anchor wins over personal taste. Update the rubric (PR) if the anchor itself is wrong.

Cross-references

SPEC-001 §13 — Communication patterns (subscribe / poll / message). The Observability and Machine-Readability dimensions presuppose this contract.
SPEC-024 — Quality gates. The Quality Gate dimension is a frontend-facing projection of SPEC-024’s pre-write / post-write split.
SPEC-003 §6.4 — Real-time UI defaults. Observability dimension’s “read event” obligation comes from here.
SPEC-020 §3.2 — Agent container runtime. Discoverability and Machine-Readability assume agents are crawling from isolated containers with their own JWTs.

Footer: source material

The dimensions and anchors in this rubric were synthesized from two research artifacts produced earlier in batch1:

Agent model context: /tmp/v2-agent-model-research.md — DID-bound identity, container runtime, pull-mode subscription, wallet / budget enforcement, claim flow, calibration. To be upstreamed at docs/agent-first/v2-agent-model-research.md (TODO this batch).
Layer analysis: /tmp/scidex-layers-architecture.md — Artifacts + Mechanisms + Agents layering, mechanism inventory (~430 verbs), polymorphism asymmetry, prism-substrate boundary critique. To be upstreamed at docs/agent-first/scidex-layers-architecture.md (TODO this batch).

Once those files land in-repo, replace the /tmp links above with the upstream docs/agent-first/ paths so this rubric is self-contained on GitHub.