docs(openapi): document contributor watches GET/POST/DELETE routes (#9306)

[RealDiligent]

Problem

Closes #9306.

/v1/contributors/:login/watches is live across GET=list / POST=watch / DELETE=unwatch as the REST mirror of the loopover_watch_issues MCP tool, but no verb appears in src/openapi/spec.ts.

Fix

Mirrors the neighboring /v1/contributors/{login}/notifications routes:

1. src/openapi/schemas.ts: ContributorWatchesResponseSchema (field-level parity with watchIssuesOutputSchema) + ContributorWatchRequestSchema (POST/DELETE body, mirroring watchSubscriptionBodySchema).
2. src/openapi/spec.ts: register both and registerPath all three verbs.
3. Regenerated + committed apps/loopover-ui/public/openapi.json; npm run ui:openapi:check enforces it.

test/unit/openapi.test.ts passes; 100% patch coverage on the new lines.

[superagent-security]

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

[loopover-orb]

Caution

🛑 LoopOver review result - reject/close recommended

_{Review updated: 2026-07-27 19:49:54 UTC}

3 files · 1 AI reviewer · 1 blocker · CI failing · dirty

🛑 Suggested Action - Reject/Close

Review summary
This PR mirrors the existing `/v1/contributors/{login}/notifications` documentation pattern to document the previously-undocumented `/v1/contributors/{login}/watches` GET/POST/DELETE routes, adding `ContributorWatchesResponseSchema` and `ContributorWatchRequestSchema` in schemas.ts and registering them plus three `registerPath` calls in spec.ts, with the regenerated openapi.json committed. The schema field-level parity claim (matching `watchIssuesOutputSchema`/`watchSubscriptionBodySchema`) cannot be independently verified since those source files aren't shown, but the structure and conventions closely follow the neighboring notifications routes visible in the same files, and the change is a pure additive doc/spec change with low correctness risk. The PR description states 100% patch coverage via `test/unit/openapi.test.ts`, which is plausible given this repo's existing pattern of a single generic openapi-shape test file rather than per-route tests, though no test diff is shown in this PR.

Nits — 6 non-blocking

• The PR asserts field-level parity with `watchIssuesOutputSchema` and `watchSubscriptionBodySchema` in comments (src/openapi/schemas.ts) — I can't verify this from the diff alone since those source files aren't included; worth double-checking the actual MCP tool schemas match before merging.
• src/openapi/schemas.ts: ContributorWatchesResponseSchema marks both `watching` and `changed` as `.optional()` even though GET responses should always include `watching` — consider whether GET's 200 response should require `watching` while POST/DELETE also require `changed`, similar to how NotificationsMarkedSchema keeps its fields required.
• The two undetailed FAILED checks (validate, validate-code) could not be attributed to this diff's content since this branch is 1 commit behind the default branch, which is a plausible cause — worth rebasing to confirm.
• Confirm ContributorWatchesResponseSchema and ContributorWatchRequestSchema field names/optionality genuinely match `watchIssuesOutputSchema`/`watchSubscriptionBodySchema` in src/mcp/server.ts and src/api/routes.ts respectively, since that parity is the core claim of this PR.
• Consider tightening `watching` to required on the GET response schema since the route always returns it (per the description's own wording), rather than leaving it optional for all three verbs.
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Why this is blocked

• No linked issue detected: The PR cites an issue number, but it could not be verified as a currently open issue. — If this PR is intended to solve an issue, link it explicitly in the PR body.

📋 Copy for AI agents — paste into your coding agent

Fix the following blocker(s) from this PR review:

1. No linked issue detected: The PR cites an issue number, but it could not be verified as a currently open issue. — If this PR is intended to solve an issue, link it explicitly in the PR body.

CI checks failing

• validate
• validate-code

Decision drivers

• ❌ Code review — 1 blocker (1 reviewer)
• ❌ Gate result — Blocking (Repo-configured hard blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#9306
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: 267 registered-repo PR(s), 113 merged, 36 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 267 PR(s), 36 issue(s).
Improvement	ℹ️ None detected	risk: low · value: none · LLM: minor

Linked issue satisfaction

Partially addressed
The PR adds ContributorWatchesResponseSchema and ContributorWatchRequestSchema, registers all three verbs in spec.ts, and regenerates openapi.json, closely mirroring the notifications pattern as required. However, the diff shows no addition of the explicitly required regression test asserting all three verbs and matching response schema keys against watchIssuesOutputSchema in a test file, which th

Review context

• Author: RealDiligent
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, Ruby, TypeScript, Svelte, Cuda, JavaScript, Markdown, MDX
• Official Gittensor activity: 267 PR(s), 36 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.

🧪 Chat with LoopOver

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

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

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/	desktop	before /	after /	—
/	mobile	before / (mobile)	after / (mobile)	—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

Scroll preview

Route	Before (production)	After (this PR's preview)
/	before / (scroll)	after / (scroll)

A short scroll-through clip (desktop) — click either thumbnail to open the full animation. Evidence for scroll-linked behavior a single screenshot can't show.

_{🟩 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 LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.69%. Comparing base (6269d27) to head (510e518).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9457      +/-   ##
==========================================
+ Coverage   75.51%   75.69%   +0.18%     
==========================================
  Files         275      277       +2     
  Lines       58032    58487     +455     
  Branches     6209     6216       +7     
==========================================
+ Hits        43820    44274     +454     
  Misses      13942    13942              
- Partials      270      271       +1     

Flag	Coverage Δ
backend	99.78% <100.00%> (?)

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

Files with missing lines	Coverage Δ
src/openapi/schemas.ts	100.00% <100.00%> (ø)
src/openapi/spec.ts	99.63% <100.00%> (ø)

[loopover-orb]

LoopOver is closing this pull request on the maintainer's behalf (CI is failing (validate, validate-code); conflicts with the base branch — resolve and open a fresh PR; No linked issue detected). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.