fix(observability): clarify manual/commented/ignored panel semantics

[JSONbored]

Summary

• The maintainer Reviews & PRs Grafana dashboard's Manual review, Commented (advisory), and Ignored stat panels (id 5/6/7) query review_targets filtered by unixepoch(updated_at) falling inside the dashboard's selected time window. This makes them "latest-update-in-window" counts, not lifetime/cumulative counts: a PR that entered manual and was later merged/closed within the same window shows only under Merged/Closed, never under Manual — it disappears rather than accumulating. This under-reports real activity for anyone who actively resolves their manual-review queue, matching the reported symptom in fix(observability): clarify manual/commented/ignored panel semantics on the Reviews & PRs dashboard #3717.
• This PR ships the cheap, safe half of fix(observability): clarify manual/commented/ignored panel semantics on the Reviews & PRs dashboard #3717: add a plain-language description field to panels 5/6/7 explaining this latest-update-in-window semantics, and bump the dashboard version.
• Deliberately out of scope, tracked as a follow-up (part 2 of fix(observability): clarify manual/commented/ignored panel semantics on the Reviews & PRs dashboard #3717): a true additive event-count panel backed by audit_events (or a newly-added emission point), which needs a real investigation of where review_targets.status/.verdict actually gets set to commented/manual/ignored for gittensory-native PRs — not yet located as of the issue filing, and too large to bundle here. Not forgotten.

Advances #3717

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.
• Owner PR — linked issue eligibility gate does not apply; issue referenced below for traceability (Advances #3717, not Closes, since only part 1 of 2 is shipped here).

Validation

• git diff --check
• npm run actionlint — not run locally (no workflow files touched); left to CI.
• npm run typecheck (npx tsc --noEmit -p .)
• npx vitest run test/unit/selfhost-grafana-dashboard.test.ts (targeted; 12/12 passing including the new assertion) — full unsharded test:coverage not run locally per this session's noted contention (spurious .tmp merge races under concurrent load); no src/** lines changed so codecov/patch has nothing to measure.
• npm run test:workers — not run; no worker code touched.
• npm run build:mcp / npm run test:mcp-pack — not run; no MCP code touched.
• npm run ui:openapi:check — N/A, no API/schema changes; not run.
• npm run ui:lint / npm run ui:typecheck / npm run ui:build — not run; no apps/gittensory-ui/** changes.
• npm audit --audit-level=moderate — not run this session (dependency review unaffected; no package.json/lockfile changes).
• node scripts/validate-observability-configs.mjs (the selfhost:validate-observability check) — passes against the edited dashboard.
• New test coverage: test/unit/selfhost-grafana-dashboard.test.ts asserts panels 5/6/7 carry a non-empty description mentioning the windowed semantics.

If any required check was skipped, explain why:

• This is a pure grafana/dashboards/** + test/** change (no src/**, no workflow, no UI, no MCP, no dependency changes), so the skipped checks above are inapplicable to the diff; CI runs the full authoritative gate regardless.

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.
• N/A — no auth, cookie, CORS, GitHub App, Cloudflare, or session changes.
• N/A — no API/OpenAPI/MCP behavior changed.
• N/A — no apps/gittensory-ui/** changes; this is a Grafana dashboard JSON config, not app UI, so no screenshot evidence applies.
• N/A — no changelog edit (not a release-prep PR).

UI Evidence

N/A — this changes a self-hosted Grafana dashboard's panel metadata (JSON config consumed by an operator's own Grafana instance), not apps/gittensory-ui/** or any in-repo rendered UI, so there is no screenshot surface to capture.

Notes

• Part 2 of fix(observability): clarify manual/commented/ignored panel semantics on the Reviews & PRs dashboard #3717 (the additive audit_events-backed event-count panel) is a deliberate, separate follow-up — it requires locating the actual call site(s) that set review_targets.status/.verdict to manual/commented/ignored for gittensory-native PRs, which is not yet confirmed, and is a larger change than this narrow clarity fix.

[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.71%. Comparing base (06689bc) to head (830fcc0).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4134   +/-   ##
=======================================
  Coverage   93.71%   93.71%           
=======================================
  Files         385      385           
  Lines       36197    36197           
  Branches    13264    13264           
=======================================
  Hits        33921    33921           
  Misses       1618     1618           
  Partials      658      658           

🚀 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 07:19:39 UTC}

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

⏸️ Suggested Action - Manual Review

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Review summary
This is a documentation-only change: it adds a `description` field to Grafana panels 5/6/7 explaining that they report latest-update-in-window state (not lifetime/cumulative counts), bumps the dashboard `version` from 4 to 5, and adds a unit test asserting the descriptions exist and mention "window". The SQL queries and semantics are unchanged, so this is low-risk and the new text is accurate to the actual query behavior (status/verdict filtered by `updated_at` in the selected range). The one thing worth a straight answer from the contributor: the PR title bar says "Closes: #1819" but every substantive discussion in the body is about #3717 ("matching the reported symptom in #3717", "Advances #3717, not Closes") and #1819 is never mentioned again — that's either a copy-paste leftover or the wrong issue number.

Nits — 5 non-blocking

• The PR header says `Closes: roadmap(selfhost): production hardening and first release readiness #1819` but the Scope section explicitly states this only *advances* fix(observability): clarify manual/commented/ignored panel semantics on the Reviews & PRs dashboard #3717 and roadmap(selfhost): production hardening and first release readiness #1819 is never referenced again in the body — confirm which issue this actually targets before merge, since a stale `Closes:` line will auto-close the wrong issue.
• grafana/dashboards/maintainer-reviews.json:59,68,79 — the descriptions use a bare `--` for the aside instead of the em dash (`—`) used elsewhere in this repo's dashboard descriptions (e.g. grafana/dashboards/codex-usage.json uses `—`); minor style inconsistency, not functional.
• test/unit/selfhost-grafana-dashboard.test.ts:258-271 — the new test only checks `description` is non-empty and contains the word "window"; it doesn't pin the specific wording, so it won't catch future edits that state the semantics incorrectly (a stronger assertion, e.g. checking for "Merged" or "Closed" cross-reference text, would give more protection for a description whose entire purpose is correctness).
• Reconcile the `Closes:`/`Advances:` issue references in the PR description before merge.
• Consider tightening the new test to assert on a stable substring of the actual semantic claim (e.g. "most recent status update") rather than just the word "window", so a future edit that drifts from correct semantics still fails CI.

Concerns raised — review before merging

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Signal	Result	Evidence
Code review	❌ 2 blockers	1 reviewer
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
Related work	⚠️ 1 scoped overlap	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 52 registered-repo PR(s), 43 merged, 496 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 52 PR(s), 496 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 52 PR(s), 496 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (issue #3716, issue #3717)

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Explain no-issue PR.
• Review top overlaps.
• Add a concise scope and risk note.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.
• Check active issues and PRs before submitting.

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