feat(notifications): add calibration section for maintainer recap

[claytonlin1110]

Summary

• Add buildCalibrationRecapSection(report) — a pure maintainer-recap digest section that surfaces reversals + reversalRate + a plain-English note (calibration drift / healthy / nothing auto-acted).
• reversalRate follows the AgentHealth contract (reversals / (merged + closed), 0 when nothing auto-acted); the drift note mirrors detectAnomalies calibration-drift phrasing without leaking score/reward internals.
• Unit tests cover drift-present, healthy, and zero-denominator arms (plus merged-only / closed-only denominator sides).

Closes #2243

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• 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 (e.g. Closes #123) — a linked open issue is required for every contributor PR.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; codecov/patch requires ≥99% coverage of the lines AND branches you changed (aim for 100% on your diff so CI variance does not fail near the threshold). Global coverage is a non-blocking trend with a loose 90% backstop, not the gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• Full npm run test:ci (workers / MCP / UI / actionlint / env-reference) was not re-run end-to-end on this machine — change is a pure additive src/services section builder + unit tests, imports nothing new beyond the existing redaction scrub, touches no worker/MCP/UI/OpenAPI/migrations/wrangler. Locally: git diff --check clean, npm run typecheck clean, focused coverage on the changed file is 100% statements/branches/functions/lines (13/13, 6/6), npm audit --audit-level=moderate reports 0 vulnerabilities. CI will cover the remaining path-filtered jobs.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. SVG screenshots are not used as review evidence. Review-only screenshots or recordings are not committed to the repository.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

UI Evidence

N/A — pure backend section builder; no visible UI, frontend, docs, or extension surface.

Notes

• Ships as src/services/maintainer-recap-calibration.ts so it does not conflict with the open foundation builder in feat(notifications): add the pure maintainer-recap builder (#2239) #4210 (maintainer-recap.ts / RecapReport). Accepts a structural CalibrationRecapSource projection (windowDays + totals.{merged,closed,reversals}) that is compatible with RecapReport once feat(notifications): pure maintainer-recap builder — aggregate review activity into a RecapReport #2239 lands; the formatter/delivery slices can import this section without waiting for a file merge.
• Auth / cookie / CORS / API / UI boxes above are N/A (no such surfaces changed) and checked as satisfied for scope.

[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 93.76%. Comparing base (e3b83c8) to head (c622b14).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4214   +/-   ##
=======================================
  Coverage   93.76%   93.76%           
=======================================
  Files         390      391    +1     
  Lines       36547    36560   +13     
  Branches    13389    13392    +3     
=======================================
+ Hits        34267    34280   +13     
  Misses       1623     1623           
  Partials      657      657           

Files with missing lines	Coverage Δ
src/services/maintainer-recap-calibration.ts	100.00% <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]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-08 18:46:20 UTC}

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

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): src/services/maintainer-recap-calibration.ts (matched src/services/**).

Review summary
Adds a small, pure, additive section builder (`buildCalibrationRecapSection`) for the maintainer recap digest, computing a reversal rate over merged+closed auto-actions and emitting a plain-English calibration note with three arms (nothing-auto-acted, drift, healthy). The zero-denominator guard correctly avoids NaN, the rate/percent derivation matches the `AgentHealth.reversalRate` contract cited from alerts.ts, and all four logical arms plus both sides of the `merged + closed` split are exercised by the accompanying tests. The module isn't wired into any live recap consumer yet (by design, per the description — it's a standalone slice awaiting the #2239 foundation builder), so there's no wiring risk to evaluate here, and the linked issue (#2243) is closed with matching scope.

Nits — 6 non-blocking

• `sanitizeRecapText`'s `.slice(0, 240)` in maintainer-recap-calibration.ts:38 and the `.toFixed(3)` in maintainer-recap-calibration.ts:51 are unexplained magic numbers — worth a named constant (e.g. `MAX_NOTE_LENGTH`) so future edits don't have to rediscover the intent.
• The 240-char truncation in `sanitizeRecapText` can cut a note mid-sentence/mid-word since it runs after the redaction replace; consider truncating on a word boundary or bumping the limit only if a real overlong case is expected.
• The 'stray reversals with zero denominator' behavior (maintainer-recap-calibration.ts note branch when `autoActed === 0` but `reversals > 0`) silently discards the reversal count from the note text — worth a one-line comment or log hook if this ledger-inconsistency case is expected to occur in practice rather than purely defensively.
• This module isn't imported/called from any other file yet — fine given the stated 'ships independently' intent, but worth confirming there's a tracked follow-up (e.g. feat(notifications): pure maintainer-recap builder — aggregate review activity into a RecapReport #2239) so it doesn't become permanently dead code.
• Extract the `240` and `3` literals into named constants near the top of maintainer-recap-calibration.ts for readability.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2243
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: 453 registered-repo PR(s), 312 merged, 102 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	claytonlin1110; Gittensor profile; 453 PR(s), 102 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Linked issue satisfaction

Addressed
The PR adds buildCalibrationRecapSection emitting reversals, reversalRate, and a plain-English note that mirrors the calibration-drift phrasing, and explicitly handles the zero-denominator 'nothing auto-acted' branch with reversalRate 0; unit tests cover drift-present, healthy, and zero-denominator arms as required. It defines its own structurally-compatible projection type rather than importing t

Review context

• Author: claytonlin1110
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, TypeScript, Rust
• Official Gittensor activity: 453 PR(s), 102 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.

_{🟩 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