docs(openapi): document validate-linked-issue + check-before-start routes (#9304)

[RealDiligent]

Problem

Closes #9304.

Two live POST /v1/repos/:owner/:repo/* pre-work-check routes each already have an MCP tool with its own Zod shapes, but neither appears in src/openapi/spec.ts:

• POST …/validate-linked-issue → loopover_validate_linked_issue
• POST …/check-before-start → loopover_check_before_start

Fix

Mirrors the #6611 gate-config/effective pattern (and the evaluate-escalation POST mirror):

1. src/openapi/schemas.ts: added ValidateLinkedIssue/CheckBeforeStart request+response schemas — field-level parity with the MCP tools' inputSchema/outputSchema.
2. src/openapi/spec.ts: registry.register all four as components and registerPath both routes (params + body + response, 400/401/403).
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 schemas.ts/spec.ts lines.

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

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

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds OpenAPI schemas and path registrations for two existing live routes (validate-linked-issue, check-before-start), mirroring the established pattern from the gate-config/effective and evaluate-escalation routes. The schemas in src/openapi/schemas.ts are consistent field-for-field with the MCP tool shapes cited in comments, and spec.ts wiring (registry.register + registerPath, with 400/401/403 responses) matches the existing convention exactly. The one real gap is that this is a pure docs/spec change with zero test additions, and the description's claim of 'test/unit/openapi.test.ts passes; 100% patch coverage' cannot be verified from the diff alone — I'd want to see that test file actually assert the two new paths exist in the generated spec.

Nits — 6 non-blocking

• No test-path changes are visible in this diff (src/openapi/schemas.ts and spec.ts have zero test-path evidence per the engine classifier) — since these files are typically covered by a snapshot-style test like `test/unit/openapi.test.ts` asserting registered paths/schemas, confirm that file was actually updated to assert on the two new routes rather than just passing incidentally.
• CheckBeforeStartRequestSchema's issueNumber, title, and plannedPaths are all optional with only owner/repo required (src/openapi/schemas.ts) — worth double-checking this matches `checkBeforeStartShape`'s actual required fields in src/mcp/server.ts, since a check-before-start with no issueNumber and no title seems like it would carry little useful signal.
• The `reasons`/`report`/`blockers` fields are typed as bare `z.unknown().optional()` mapping to `{"nullable": true}` in the generated JSON (apps/loopover-ui/public/openapi.json) with no `type`, which is technically valid but unhelpfully vague for API consumers — consider at least `type: "array"`/`type: "object"` where the shape is known, as done for other opaque fields elsewhere in the file.
• Add or confirm assertions in test/unit/openapi.test.ts for the two new registered paths and schemas, matching the pattern used for the OpenAPI spec is missing GET /v1/repos/{owner}/{repo}/gate-config/effective (documented sibling: live-gate-thresholds) #6611 gate-config/effective and evaluate-escalation mirrors.
• Double check `issueNumber`/`title` optionality in CheckBeforeStartRequestSchema against the live MCP tool's `checkBeforeStartShape` in src/mcp/server.ts for field-level parity, per the PR's own stated goal.
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

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: 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

Addressed
The PR adds ValidateLinkedIssueResponseSchema and CheckBeforeStartResponseSchema (plus request schemas) to schemas.ts, registers them and registerPath entries for both routes in spec.ts mirroring the gate-config pattern, and regenerates/commits the updated openapi.json.

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 (2e4388d) to head (a8fc537).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9449      +/-   ##
==========================================
+ Coverage   75.51%   75.69%   +0.18%     
==========================================
  Files         275      277       +2     
  Lines       58032    58472     +440     
  Branches     6209     6216       +7     
==========================================
+ Hits        43820    44259     +439     
  Misses      13942    13942              
- Partials      270      271       +1     

Flag	Coverage Δ
backend	99.77% <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.62% <100.00%> (ø)

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.