feat(mcp): gittensory_check_before_start (pre-start duplicate/solvability check)

[oktofeesh1]

Fixes #545

What

Adds gittensory_check_before_start, a pre-start MCP tool that answers — before any code is written — whether an issue is already claimed or solved, whether a duplicate cluster is forming, and whether it is a valid target. It returns a go / raise / avoid recommendation with public-safe reasons from cached metadata. Metadata only; no GitHub writes.

This moves collision/solvability detection earlier than the existing preflight_* tools (which only run after a branch exists), addressing a top source of wasted effort / slop.

How

• src/signals/engine.ts — new deterministic buildPreStartCheck builder that reuses the existing reports: buildCollisionReport, buildIssueQualityReport, and buildIssueDiscoveryLifecycleReport. It resolves the target by issueNumber, fuzzy title match (token Jaccard), or plannedPaths overlap with recently merged work, then derives claimStatus (unclaimed/claimed/solved/unknown), duplicateClusterRisk, and the recommendation.
• Public-safe by construction — every reason/blocker is routed through sanitizePublicComment (fail-closed); no reward/score/trust language, and other contributors' private context is never surfaced.
• src/mcp/server.ts — registers gittensory_check_before_start with an inputSchema and an outputSchema.
• src/api/routes.ts — POST /v1/repos/:owner/:repo/check-before-start backing the local CLI tool (mirrors the issue-quality route's auth).
• packages/gittensory-mcp/bin/gittensory-mcp.js — exposes the tool, proxying to the API route.

Output boundaries

Public-safe reasons only; metadata only, no writes. The tool never reveals reward/score/trust internals or other contributors' private context.

Tests

• test/unit/pre-start-check.test.ts — go/raise/avoid, claimed (open linked PR), solved (merged work), high duplicate-cluster risk, duplicate/invalid labels, needs-proof, not-found, fuzzy-title resolution, title no-match, direct-PR lane, planned-path overlap, and forbidden-term assertions on all output.
• test/unit/mcp-output-schemas.test.ts — output-schema discovery + structured-content call.
• test/integration/api.test.ts — route success, invalid body (400), and session-forbidden (403).

npm run validate (typecheck + coverage) is green at the 97%+ branch threshold; build:mcp, test:mcp-pack, test:workers, and ui:openapi:check also pass.

🤖 Generated with Claude Code

[ghost]

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

[ghost]

gittensory · advisory review

Reviewed 7 changed file(s) — two independent AI reviewers.

Suggested action: ✅ Safe to merge — both reviewers found no blocking issues.

What changed

• Added checkBeforeStartShape schema to CLI and server.
• Implemented new API route /v1/repos/:owner/:repo/check-before-start.
• Added MCP tool registration and handler checkBeforeStart.
• Implemented buildPreStartCheck with public‑safe sanitization.
• Updated output schema list and added related unit/integration tests.
• Added new test suite pre-start-check.test.ts covering many scenarios.

Reviewer A · gpt-oss-120b — recommends ✅ merge
This PR introduces a new pre‑start check tool (gittensory_check_before_start) with API route, MCP registration, implementation, and comprehensive tests. The implementation respects the public‑sanitizer and aligns with existing architecture.

Suggestions

• Consider adding the max title length constraint to the CLI input schema for consistency with the server validation.
• Add a unit test covering title length validation to ensure the tool rejects overly long titles before hitting the server.

Worth double-checking

• CLI schema allows titles longer than the server's max length, which will result in a 400 error at runtime.
• Ensure the imported sanitizePublicComment path is correct and that the function does not throw on empty strings.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
This PR adds a new MCP tool 'gittensory_check_before_start' for pre-start duplicate/solvability checks. The changes span MCP tool registration, API route, business logic in signals/engine, and comprehensive tests. The implementation follows project conventions: uses proper validation, authentication, sanitizes public output, and includes unit/integration tests. The code is clean, well-tested, and addresses a clear feature need.

Suggestions

• Consider adding a comment in src/signals/engine.ts explaining why plannedPaths are lowercased (for case-insensitive file system matching).
• In test/unit/pre-start-check.test.ts, the test 'returns go for planned paths with no overlapping merged work' could assert that duplicateClusterRisk is 'none' for clarity.
• The MCP tool description in src/mcp/server.ts could explicitly mention that no GitHub writes occur (already implied by 'No GitHub writes' but could be emphasized).

Worth double-checking

• Ensure the sanitizePublicComment function is indeed imported and available in src/signals/engine.ts (it is, via the added import).
• Verify that the new route doesn't inadvertently expose private data - the use of buildPreStartCheck with sanitization appears correct.
• Check that the MCP tool's output schema matches what's actually returned (it does, based on the handler).

[ghost]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#621 is no longer open.	No action.

---

💰 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.

[superagent-security]

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

[JSONbored]

fix failing CI, please.