feat(scoring): model branch eligibility for issue PRs

[grnlemon]

Summary

• Closes feat(scoring): model branch eligibility for issue-solving PRs #90.
• Adds private branch eligibility modeling to scoring previews and local branch analysis so issue-solving PR assumptions can be marked eligible, ineligible, unknown, or missing.
• Threads branch eligibility through REST, MCP, the MCP CLI, generated OpenAPI, and local metadata collection without uploading source contents.
• Keeps public PR packets limited to linked-issue hygiene wording while private MCP/API output carries eligibility and scoreability details.

Scope

• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy 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
• npm run typecheck
• npm run test:coverage
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• Coverage remains at or above 97% for statements, branches, functions, and lines.

If any required check was skipped, explain why:

• None. npm run test:ci passed locally. Coverage: statements 98.94%, branches 97.02%, functions 97.83%, lines 99.49%.

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 changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include screenshots or a short recording.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

• No visible UI behavior changed; the UI artifact change is the regenerated OpenAPI schema only.
• API/OpenAPI/MCP contract changes add optional branchEligibility input and private branchEligibility result metadata.
• Public PR packet text intentionally says "Linked Issue Hygiene" and avoids private eligibility, multiplier, scoreability, reward, wallet, or trust-score language.
• MCP/local tooling tests prove branch eligibility metadata is sent without local source contents.

[JSONbored]

@MkDev11 This needs a rebase before review can move forward. The branch conflicts with current main in the MCP CLI/package files, src/api/routes.ts, and src/signals/local-branch.ts.

The feature direction still makes sense, but the post-MCP-release code has moved enough that I cannot evaluate the branch eligibility behavior that would actually land. Please rebase and rerun the full gate.

[grnlemon]

@MkDev11 This needs a rebase before review can move forward. The branch conflicts with current main in the MCP CLI/package files, src/api/routes.ts, and src/signals/local-branch.ts.

The feature direction still makes sense, but the post-MCP-release code has moved enough that I cannot evaluate the branch eligibility behavior that would actually land. Please rebase and rerun the full gate.

@JSONbored please check the update again

[JSONbored]

@MkDev11 thanks for rebasing this. The earlier conflict blocker looks resolved now.

A few notes:

• The branch eligibility signal is carried through scoring preview, local branch analysis, API/OpenAPI, MCP server, and CLI output.
• The public packet tests still protect against leaking scoreability/reward/trust-style language into public-safe copy.
• CI is green and the merge-tree is clean against current main.

No code changes requested from this pass.

[dosubot]

Documentation Updates

1 document(s) were updated by changes in this PR:

MCP & Agent Integration

View Changes

@@ -261,6 +261,16 @@
 ```sh
 gittensory-mcp analyze-branch --login yourlogin --json
 ```
+
+You can optionally pass branch eligibility metadata to model linked-issue assumptions:
+
+```sh
+gittensory-mcp analyze-branch --login yourlogin \
+  --branch-eligibility eligible \
+  --json
+```
+
+The `--branch-eligibility` flag accepts `eligible`, `ineligible`, or `unknown`. Related optional flags include `--branch-eligibility-source`, `--branch-eligibility-reason`, `--branch-eligibility-checked-at`, and `--branch-eligibility-stale`. These flags model branch eligibility for issue-solving PR assumptions in scoring previews.
 
 Or from an MCP client, call `gittensory_preflight_current_branch` with your login:
 
@@ -531,7 +541,7 @@
 
 | Command | Key Flags | Purpose |
 |---------|-----------|---------|
-| `gittensory-mcp analyze-branch` | `--login`, `--repo`, `--base`, `--pending-merged-prs`, `--expected-open-prs`, `--projected-credibility`, `--scenario-note`, `--validation` | Full branch analysis: summary, top action, workspace intelligence, score blockers, preflight status |
+| `gittensory-mcp analyze-branch` | `--login`, `--repo`, `--base`, `--branch-eligibility eligible\|ineligible\|unknown`, `--pending-merged-prs`, `--expected-open-prs`, `--projected-credibility`, `--scenario-note`, `--validation` | Full branch analysis: summary, top action, workspace intelligence, score blockers, preflight status |
 | `gittensory-mcp preflight` | Same as above | PR readiness focus: preflight status, PR packet, workspace intelligence |
 
 #### Agent Commands (copilot-only)
@@ -591,7 +601,7 @@
 **`gittensory_preview_local_pr_score`**
 
 - **Purpose:** Request a private scoring preview for local diff metadata
-- **Input:** All fields from `localDiffShape` plus optional `sourceTokenScore`, `totalTokenScore`, `sourceLines`, `credibility`, `projectedCredibility`, PR state fields, and `scenarioNotes`
+- **Input:** All fields from `localDiffShape` plus optional `sourceTokenScore`, `totalTokenScore`, `sourceLines`, `credibility`, `projectedCredibility`, PR state fields, `scenarioNotes`, and `branchEligibility` (object with `status`, `source`, `reason`, `checkedAt`, `stale`)
 - **Output:** Score estimate with scenario breakdowns, setup guidance if scorer is missing
 - **Use case:** Get a private score estimate before opening a PR [[23]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L212-L219)
 
@@ -626,6 +636,7 @@
 - Optional: `cwd`, `repoFullName`, `baseRef`, `headRef`, `branchName`, `title`, `body`, `labels`, `linkedIssues`
 - Scenario fields: `pendingMergedPrCount`, `expectedOpenPrCountAfterMerge`, `projectedCredibility`, `scenarioNotes`
 - Validation: array of `{ command, status, summary?, durationMs?, exitCode? }` objects
+- Branch eligibility: optional `branchEligibility` object with `status` ("eligible" | "ineligible" | "unknown"), `source`, `reason`, `checkedAt`, and `stale` fields — models branch eligibility for issue-solving PR assumptions when the standard issue mode is used
 
 **`gittensory_preflight_current_branch`** — PR readiness: preflight status, workspace intelligence, PR packet [[29]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/packages/gittensory-mcp/bin/gittensory-mcp.js#L290-L305)
 

^{How did I do? Any feedback?}