feat(miner): add a calibration-report CLI command

[real-venus]

Summary

• Adds gittensory-miner calibration [--json], a read-only report that finally joins the two data sources the miner already tracks independently — its own predicted gate verdicts (the prediction ledger) and the realized PR outcomes it later observed (pr_outcome events in the event ledger) — into a per-project accuracy report. Before this, an operator had no way to see their own prediction accuracy even though all the raw data existed (Build the missing calibration-report join #4849).
• buildCalibrationReport(predictions, outcomes) is a pure join over the existing record shapes: it matches by (project, targetId) only when an outcome resolves to a clear merge/close, builds a per-project confusion matrix (wouldMerge/mergeConfirmed/mergeFalse, same for close, plus hold), and computes merge/close precision (null below one sample).
• The CLI opens both local stores read-only, maps their rows to the record shapes, renders a text summary (or a JSON dump under --json), and closes. Outcome recordedAt comes from the event's own timestamp so an outcome is never dropped for lacking a closedAt, and only the latest outcome per (repo, PR) is counted.
• Per the issue's scope note, this does not touch the live scoring/calibration logic that feeds the actual gate — it is purely an operator-facing read of data that already exists.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves — Closes Build the missing calibration-report join #4849.

Validation

• git diff --check
• npm run typecheck
• npm run test:coverage — verified the changed files at 100% line + branch coverage locally via the v8 JSON report (calibration.js, calibration-cli.js); 16 dedicated unit tests across test/unit/miner-calibration.test.ts and test/unit/miner-calibration-cli.test.ts cover the join's confusion-matrix buckets, precision-null boundaries, the latest-outcome-per-PR dedup, malformed/non-outcome event skipping, the text and --json renderers, and the unknown-option path.
• New behavior has unit tests for the new branches and fallback paths (both sides of every precision-null ternary, the no-signal path, and the option parser).
• npm run command-reference:check (green — the added help line does not desync the generated command reference).

If any required check was skipped, explain why:

• actionlint, test:workers, build:mcp / test:mcp-pack, ui:openapi:check, ui:lint / ui:typecheck / ui:build, and npm audit were not run because this change touches only packages/gittensory-miner/** (miner CLI/lib) and test/** — it adds no workflow, worker, MCP, OpenAPI/API, UI, or dependency changes for those jobs to act on. The full npm run test:ci will run all of them on CI.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed. The report aggregates the operator's own local prediction/outcome tallies only.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Public docs/changelogs are updated where needed; no changelog is edited (this is not a release-prep PR).

Auth/CORS/session, API/OpenAPI/MCP, and UI safety boxes are not applicable — this PR changes none of those surfaces.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.49%. Comparing base (4e9ce1a) to head (e57d830).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5460   +/-   ##
=======================================
  Coverage   94.48%   94.49%           
=======================================
  Files         554      556    +2     
  Lines       44453    44520   +67     
  Branches    14662    14662           
=======================================
+ Hits        42002    42069   +67     
  Misses       1776     1776           
  Partials      675      675           

Flag	Coverage Δ
shard-1	43.90% <0.00%> (-0.19%)	⬇️
shard-2	34.94% <0.00%> (+<0.01%)	⬆️
shard-3	31.61% <55.22%> (-0.40%)	⬇️
shard-4	31.37% <0.00%> (-0.34%)	⬇️
shard-5	33.12% <0.00%> (+0.40%)	⬆️
shard-6	43.97% <91.04%> (+0.41%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/gittensory-miner/lib/calibration-cli.js	100.00% <100.00%> (ø)
packages/gittensory-miner/lib/calibration.js	100.00% <100.00%> (ø)
packages/gittensory-miner/lib/cli.js	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-12 21:51:03 UTC}

8 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a read-only `calibration` CLI command that joins the prediction ledger with realized PR outcomes into a per-project confusion matrix, closing #4849. The join logic in `buildCalibrationReport` is pure, correctly keys by (project, targetId), and the CLI layer maps store rows into the expected record shapes and reduces the event stream to latest-outcome-per-PR. The test suite is thorough and covers both branches of every precision ternary (n/a vs computed) plus malformed/unrecognized-decision edge cases; console usage flagged in the brief is intentional CLI output, not debug leftovers.

Nits — 5 non-blocking

• packages/gittensory-miner/lib/calibration-cli.js:19 — `toPredictionRecords` trusts `row.conclusion` is always a string; if the prediction-ledger schema ever allows null, `normalizeDecision` in calibration.js:16 would throw on `.trim()` since it assumes a validated non-empty string — worth a defensive check or a type-level guarantee comment at the DB layer.
• packages/gittensory-miner/lib/calibration.js:60 — `buildCalibrationReport` is doing a lot in one function (filtering, keying, tallying, deriving precision); consider extracting the confusion-matrix tally into a helper for readability, though it's well-tested as-is.
• packages/gittensory-miner/lib/calibration-cli.js — no CLI-level test asserts the exact usage-string content beyond 'Unknown option', minor gap for a help-text regression.
• Consider adding a one-line doc/example under README or CLI help output showing a sample `calibration` report for operators unfamiliar with the confusion-matrix terminology (wouldMerge/mergeConfirmed/etc.).
• packages/gittensory-miner/lib/calibration.js:44 — `recordKey` joins with a space separator; a delimiter less likely to appear in project names (e.g. `\u0000`) would be marginally safer, though the risk is already correctly called out as astronomically unlikely in the comment.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4849
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 106 registered-repo PR(s), 56 merged, 11 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	real-venus; Gittensor profile; 106 PR(s), 11 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence.

Review context

• Author: real-venus
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, JavaScript, CSS, MDX, Python, Rust, Svelte, Swift
• Official Gittensor activity: 106 PR(s), 11 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[real-venus]

@JSONbored
Please kindly review this.