Scorecards

A scorecard is a repeatable quality rubric scored against the connected repository: a score out of a maximum, a ladder of levels the repo climbs, and a list of checks. Each check is a durable work item with its own evidence, verification state, impact points, and — where IonWarp can open a fix PR — a quick action.

Retrieve a scorecard — GET /api/v1/scorecards/learning-tests-run-under-bun

curl "https://ionwarp.com/api/v1/scorecards/learning-tests-run-under-bun" \
  -H "Authorization: Bearer $DASH_API_KEY" \
  -H "Project-ID: pr_acme"

What is holding the {id} score back?

data_get {
  "collection": "scorecards",
  "object_id": "learning-tests-run-under-bun"
}

{
  "object": "scorecard",
  "id": "obj_123",
  "name": "Agentic Readiness",
  "status": "ready",
  "lifespan": "persistent",
  "trigger": "repo_connected",
  "summary": "IonWarp scanned acme/api and found 9 readiness actions.",
  "created_at": "2026-07-25T12:00:00.000Z",
  "updated_at": "2026-07-25T12:00:00.000Z"
}

Every field is in the scorecards reference. The detail hangs off two more resources: scorecard-levels is the ladder (level, name, score, ai_unlocked, joined on scorecard_id) and checks is the per-check verdict (status, severity, verification_state, evidence_label, impact_points, file_path, line, prompt, quick_action_id, related_pr). Review history rolled up into metric boards is dashboards.

Running a scan

Which scorecards exist is generated, not curated: any skill declaring a scorecard_contract in its frontmatter is one, and those are the scorecards rows of the Skills index. Start with ai-readiness — it is what the project checklist wires. (Scorecard skills run in your project via tasks_create; the downloadable skills on the index are the review-study and model-lab operator workloads.)

Two calls run one by hand. POST /api/v1/scorecards/{id}/start marks it running and returns 202; it accepts a session or a Bearer PAT, which is what lets an external loop drive scans. Then create the task and start its run — scan wall time is minutes. The model resolves per scan, highest wins: run input.model → project.md ionwarp.scorecard.model_pins[<skill id>] → the skill's SKILL.md execution.model pin. The resolved model is stamped into input.model at run start, so you can always see which model produced which score.

---
config:
  ionwarp.scorecard.model_pins:
    ai-security: moonshotai/kimi-k3
---

Promote a winner by writing that block into project.md's frontmatter — read it with skills_get (skill id project), patch, write the complete content back with skills_update.

Let the agent do it

The task half of a scan is one call — ai-readiness here, or any skill with a scorecard_contract.

tasks_create { "project_id": "pr_acme", "skill_id": "ai-readiness", "run": true }
tasks_status { "task_id": "ts_…" }     // → score, action_item_count, model

Reading the result

The document is written incrementally and the last write commits, so the durable per-run record is an event, not the document. Every scan that reaches a done terminal with a committed result appends exactly one project event carrying {task_id, run_id, score, action_item_count, model}, under a deterministic id:

ionwarp.scorecard.<scorecard_id>.started.<task_id>
ionwarp.scorecard.<scorecard_id>.completed.<task_id>    ← carries score + model
ionwarp.scorecard.<scorecard_id>.failed.<task_id>

So a score is trustworthy when the document reads status: ready with a last_scan_task_id and the matching completed.<task_id> event exists. A done run whose document holds no committed result writes no completion event and is a named gap on the server — never an inferred score. A scan that dies before committing resets to a named failed state and the previously committed score is preserved; a $0, no-output, or failed scan is a failure, never graded, and a tie keeps the incumbent.

A scan that cannot start says so by name on the run (Debugging a Run); the project-level brakes that stop one — pause, approval window, spend cap — are on Control Plane.

Next: Reviewers & Models for the same pin mechanism on per-PR reviews · Plans for turning findings into proposed work.