feat(miner-plan): wire the feasibility gate into a new MCP tool + miner CLI command

[joaovictor91123]

Summary

• Closes feat(miner-plan): wire the feasibility gate into a new MCP tool + miner CLI command #4270 by wiring the already-implemented buildFeasibilityVerdict composer (packages/gittensory-engine/src/feasibility.ts) into both halves the issue asks for: a new local MCP tool and a new miner CLI command. Neither half adds new business logic — both are thin parse/validate -> call the pure composer -> render wrappers, mirroring this repo's existing conventions exactly.
• MCP tool (packages/gittensory-mcp/bin/gittensory-mcp.js): registers gittensory_feasibility_gate, following the issue's own explicit reasoning for choosing this package over src/mcp/server.ts — it already depends on @jsonbored/gittensory-engine and already imports local helper modules in the same file, so no new cross-package dependency is introduced. Unlike every other tool in this file (all of which round-trip to the hosted API via apiGet/apiPost), this is a genuinely local, synchronous, no-network computation — exactly what the composer's own header comment describes.
• Miner CLI command (packages/gittensory-miner/lib/feasibility-cli.js): gittensory-miner feasibility <claimStatus> <duplicateClusterRisk> <issueStatus> [--not-found] [--json], following the same parse -> execute -> render(json|table) -> exit-code convention as runQueueCli/runClaimCli. Dispatched in bin/gittensory-miner.js alongside the other purely-local commands (queue/claim/ledger/plan/governor), before the npm-registry update check starts, since it makes no network calls either.
• printHelp in lib/cli.js documents the new command's usage line.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused: one new CLI command file + its declaration, the MCP tool registration + its input shape + descriptor entry, two new test files, and three small wiring edits. No unrelated backend/UI/docs/dependency changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint — not run; no workflow files touched.
• npm run typecheck (clean on this diff; the repo's one pre-existing failure — a missing aws4fetch type declaration in src/selfhost/s3-blob-store.ts — reproduces identically on a clean main checkout and is unrelated).
• npm run test:coverage locally — packages/gittensory-miner/** and packages/gittensory-mcp/** are plain JS and are not in vitest's coverage include globs (only src/** and packages/gittensory-engine/src/** are instrumented, per vitest.config.ts), so this diff carries no codecov/patch obligation (buildFeasibilityVerdict itself is untouched, pre-existing, already-tested engine code). In lieu of the full unsharded run (this dev machine is shared with several other concurrent contributor sessions and a full run does not complete in reasonable time), I ran the two new suites — test/unit/miner-feasibility-cli.test.ts (14 tests: arg parsing/validation, all three verdict arms, --not-found, dependency injection, and real subprocess CLI-entrypoint calls through the compiled engine) and test/unit/mcp-feasibility-gate.test.ts (6 tests: a real node bin/gittensory-mcp.js --stdio process connected over StdioClientTransport, exercising tool listing, all three verdict arms, zod input validation, and a private-terminology leak check) — plus every directly-adjacent sibling suite (miner-cli, miner-discover-cli, mcp-cli-tools, mcp-cli-upstream-drift, mcp-cli-basics, mcp-output-schemas): 120/120 pass.
• npm run test:workers — not run; no Cloudflare Worker code touched.
• npm run build:mcp / npm run test:mcp-pack / miner-pack equivalents — not run directly, but npm --workspace @jsonbored/gittensory-mcp run build (node --check on the touched bin file) and npm --workspace @jsonbored/gittensory-engine run build were both run locally as part of getting the subprocess tests green, and both succeed. test:mcp-pack/test:miner-pack themselves currently fail on this Windows machine for an unrelated, pre-existing reason (spawnSync("npm", ...) requires shell:true on Windows; reproduces identically on a clean main checkout).
• npm run ui:openapi:check / ui:lint / ui:typecheck / ui:build — not run; no apps/gittensory-ui files touched. (npm run command-reference:check was checked too: it tracks an unrelated GitHub @gittensory mention-command catalog in src/github/commands.ts, not this MCP/CLI tool system; confirmed a no-op for this diff.)
• npm audit --audit-level=moderate — not run; no dependency changes.
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries: all three feasibility verdict arms (go/raise/avoid) through both the CLI and the MCP tool, --not-found, malformed-enum rejection (CLI arg validation + MCP zod schema validation), and a private-terminology leak check on the MCP response.

If any required check was skipped, explain why:

• Everything skipped above is either inapplicable to a plain-JS, non-src/, non-UI, non-workflow change, or blocked by pre-existing, reproducible-on-clean-main Windows-local environment issues (npm pack's spawnSync Windows incompatibility) that do not reflect real CI behavior (GitHub Actions runs on Linux, and a dedicated CI step already builds @jsonbored/gittensory-engine before test:coverage runs specifically so subprocess tests like these resolve the compiled package).

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.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session behavior is not changed.
• API/OpenAPI/MCP behavior: adds a new, purely local, no-network MCP tool; every existing tool is untouched (mcp-output-schemas.test.ts's full tool-inventory and output-schema tests still pass unmodified).
• No visible UI changes; UI evidence is not applicable.
• Public docs/changelogs are not changed.

UI Evidence

Not applicable; this is a local CLI + MCP tool change.

Notes

• The MCP tool never calls apiGet/apiPost and never touches the network — its handler is a direct, synchronous call into buildFeasibilityVerdict, the only tool in packages/gittensory-mcp/bin/gittensory-mcp.js with that property today.

[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.97%. Comparing base (8cebd14) to head (f8aad56).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4432   +/-   ##
=======================================
  Coverage   93.97%   93.97%           
=======================================
  Files         411      411           
  Lines       37202    37202           
  Branches    13587    13587           
=======================================
  Hits        34962    34962           
  Misses       1585     1585           
  Partials      655      655           

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-09 18:21:24 UTC}

7 files · 1 AI reviewer · no blockers · readiness 82/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This wires the already-built `buildFeasibilityVerdict` composer into a new `gittensory-miner feasibility` CLI subcommand and a new `gittensory_feasibility_gate` MCP tool, both as thin parse/validate → call → render wrappers with no new business logic, matching the repo's existing conventions (queue/claim CLI pattern, apiGet/apiPost-free local MCP tools). The CLI's --not-found/--json handling, exit codes (0/2), and the MCP tool's zod enum schema all line up correctly with the composer's actual output shape, and the tests exercise the real compiled engine dependency end-to-end rather than a fabricated payload. The one real design smell is that the three enum value sets (claimStatus/duplicateClusterRisk/issueStatus) are hardcoded independently in both the CLI (JS arrays) and the MCP tool (z.enum literals) instead of being derived from the engine package's exported types, risking silent drift if the composer's discriminants change.

Nits — 5 non-blocking

• packages/gittensory-miner/lib/feasibility-cli.js and packages/gittensory-mcp/bin/gittensory-mcp.js each hardcode their own copy of the claimStatus/duplicateClusterRisk/issueStatus enum values instead of importing a shared list from @​jsonbored/gittensory-engine — if the composer adds/renames a status, these two call sites won't get a compile-time signal to update.
• packages/gittensory-miner/lib/feasibility-cli.js:35's sequential if-chain validating three enums back-to-back could be collapsed into a small `[value, allowed, label][]` loop to cut the nesting depth and the repeated `must be one of` string-join pattern.
• The bare `3` in `if (positional.length !== 3)` (feasibility-cli.js:35) could be named (e.g. `REQUIRED_POSITIONAL_ARGS`) for a touch more self-documentation, though it's low-risk given the immediately-following destructure makes the count obvious.
• Worth a one-line comment or test explicitly confirming that an omitted `found` in the MCP tool's optional zod field and the CLI's implicit `found: true` default both resolve identically inside the composer, since that equivalence is only implied by the passing tests, not stated.
• Export the three status arrays (or a zod schema) from @​jsonbored/gittensory-engine and import them in both feasibility-cli.js and gittensory-mcp.js so the CLI usage string, the zod enum, and the composer's discriminants can never drift independently.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4270
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 (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 101 registered-repo PR(s), 50 merged, 11 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	joaovictor91123; Gittensor profile; 101 PR(s), 11 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The diff registers `gittensory_feasibility_gate` in packages/gittensory-mcp/bin/gittensory-mcp.js (with documented rationale for choosing that package over src/mcp/server.ts), adds packages/gittensory-miner/lib/feasibility-cli.js exporting runFeasibilityCli following the parse->execute->render convention, wires a new `feasibility` dispatch branch into gittensory-miner.js, updates printHelp's usage

Review context

• Author: joaovictor91123
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, MDX, C++, CSS, Rust, TypeScript
• Official Gittensor activity: 101 PR(s), 11 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (issue #4293, issue #4307)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• 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

[loopover-orb]

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