feat(openapi): document validate-linked-issue + check-before-start

[philluiz2323]

What

POST /v1/repos/:owner/:repo/validate-linked-issue and POST /v1/repos/:owner/:repo/check-before-start are live with MCP tools (loopover_validate_linked_issue / loopover_check_before_start) and Zod output shapes, but were missing from the OpenAPI contract — the same class of gap #6611 fixed for gate-config/effective.

Change

• Add request + response schemas in src/openapi/schemas.ts from the MCP tool shapes
• Register both schemas and registerPath entries in src/openapi/spec.ts
• Assert paths + schema keys in test/unit/openapi.test.ts
• Regenerate apps/loopover-ui/public/openapi.json

Closes #9304

Made with Cursor

[superagent-security]

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

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-27 16:44:12 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds OpenAPI documentation (schemas + registerPath entries) for the already-live validate-linked-issue and check-before-start endpoints, following the exact pattern established for gate-config/effective (#6611). The generated openapi.json diff matches the spec.ts/schemas.ts changes, request/response schema field names line up between schemas.ts and the JSON, and PREFLIGHT_LIMITS is imported for shared bounds (titleChars/changedFileChars/changedFiles) rather than hardcoding magic numbers. One notable divergence: openapi.json's ValidateLinkedIssueRequest.issueNumber uses `minimum: 0, exclusiveMinimum: true` (equivalent to positive-int) matching the Zod schema, so the generated artifact is consistent with source.

Nits — 5 non-blocking

• schemas.ts's CheckBeforeStartRequestSchema marks issueNumber as optional while ValidateLinkedIssueRequestSchema requires it — worth a one-line comment confirming this asymmetry matches the actual MCP tool shapes rather than being an oversight.
• The HTTP status codes flagged by the external brief (200/400/401/403) are standard REST conventions already used identically in every other registerPath block in this file (e.g. live-gate-thresholds, gate-config/effective) — not literals worth extracting to constants.
• test/unit/openapi.test.ts asserts schema keys exist and that specific field names appear via JSON.stringify string search, but doesn't verify the full property list or that optional-vs-required matches the Zod source, so a future accidental required/optional flip wouldn't be caught.
• Consider a comment in schemas.ts noting the reasoning for CheckBeforeStartRequestSchema.issueNumber being optional vs ValidateLinkedIssueRequestSchema.issueNumber being required, since both wrap similar 'issue' concepts.
• The regenerated openapi.json is large and mechanical — fine to keep in the same PR since it's a generated artifact, per repo convention.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#9304
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: 992 registered-repo PR(s), 564 merged, 125 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	philluiz2323; Gittensor profile; 992 PR(s), 125 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The PR adds ValidateLinkedIssueResponseSchema/CheckBeforeStartResponseSchema (plus request schemas) in schemas.ts, registers both as components and registerPath entries in spec.ts mirroring the gate-config pattern, regenerates the openapi.json, and adds regression tests asserting the paths and key schema fields matching the MCP tool shapes.

Review context

• Author: philluiz2323
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, MDX, TypeScript, CSS, Cuda, HTML, Kotlin
• Official Gittensor activity: 992 PR(s), 125 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Triage stale or unlinked PRs.

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

[loopover-orb]

This pull request changes UI/visual code but its screenshot evidence is incomplete. Every required viewport × theme combination needs its own before/after image pair in a labeled table row (e.g. "Desktop · Light | before | after"). Still missing: Desktop · Dark, Tablet · Dark, Mobile · Dark.

Please resubmit with the remaining rows filled in.

See https://github.com/JSONbored/loopover/blob/main/.claude/skills/contributing-to-loopover/SKILL.md for the exact format and examples. This is an automated maintenance action.

[JSONbored]

Re-opened to re-review, but merge conflicts so re-closing.

This branch has conflicts that must be resolved
Use the web editor or the command line to resolve conflicts before continuing.

apps/loopover-ui/public/openapi.json