fix(review): treat an unstable GitHub mergeable_state as a held verdict in the PR panel

[JSONbored]

Summary

• Root-caused the ambiguous PR panel reported on feat(registry): add Ridges evaluation-set problems data-artifact (SN62) metagraphed#5288: a PR shows "✅ approve/merge recommended" / "safe to merge" while a third-party App's non-required check (e.g. Superagent's "Contributor trust") leaves GitHub's mergeable_state as unstable, and the disposition planner's own audit trail shows agent.action.hold: merge withheld because mergeable_state is unstable for the same PR at the same time.
• deriveUnifiedStatus (src/review/unified-comment.ts) only downgraded an otherwise-ready status to held for dirty/behind merge states. agentHoldAuditDetail (src/queue/processors.ts) -- the function that actually decides whether to withhold a merge -- treats ANY mergeableState !== "clean" as a withhold reason. unstable fell through that gap: a real withhold, but the comment claimed "safe to merge" anyway.
• Added unstable to the downgrade condition. Left unknown and blocked alone -- those are already documented as deliberately non-downgrading (a not-yet-computed state, and a pending-bot-approval state the bot itself will clear).

Test plan

• npx tsc --noEmit
• npx vitest run test/unit/unified-comment.test.ts test/unit/unified-comment-bridge.test.ts (166 passing)
• npm run test:ci (full local gate; one unrelated pre-existing failure in test/unit/mcp-cli-doctor.test.ts that depends on local machine env/credential state, not touched by this change)
• New regression test cases for unstable (including case-insensitivity) alongside the existing dirty/behind feat(mcp): add gittensory_explain_gate_disposition tool (#2234) #4220 coverage

[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 95.06%. Comparing base (09a60f0) to head (5518f8e).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5734   +/-   ##
=======================================
  Coverage   95.06%   95.06%           
=======================================
  Files         581      581           
  Lines       46181    46181           
  Branches    14811    14811           
=======================================
  Hits        43904    43904           
  Misses       1516     1516           
  Partials      761      761           

Flag	Coverage Δ
shard-1	43.41% <100.00%> (-0.54%)	⬇️
shard-2	35.96% <0.00%> (+0.25%)	⬆️
shard-3	32.15% <0.00%> (-0.13%)	⬇️
shard-4	31.14% <100.00%> (-1.87%)	⬇️
shard-5	32.55% <0.00%> (+0.79%)	⬆️
shard-6	45.01% <0.00%> (+0.37%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/review/unified-comment.ts	99.58% <100.00%> (ø)

🚀 New features to boost your workflow:

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

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-14 09:55:42 UTC}

2 files · 1 AI reviewer · 2 blockers · readiness 93/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• AI review could not be completed: The dual-model AI review did not return a usable verdict for this change.

Review summary
This is a narrow, well-targeted one-line logic fix: adding `unstable` to the mergeState downgrade condition in `deriveUnifiedStatus` so it matches `agentHoldAuditDetail`'s existing withhold logic (`mergeableState !== "clean"`), closing the exact contradiction described in the linked issue #5288. The fix is at the correct layer (the comment-rendering function, not the disposition planner which already handles this correctly), is covered by new case-insensitive regression tests mirroring the existing #4220 pattern, and leaves `unknown`/`blocked` untouched per their documented non-downgrading rationale.

Nits — 5 non-blocking

• The comment block above the fix (unified-comment.ts:342-348) is now quite long for a single conditional; consider trimming to the essential rationale plus the issue reference.
• Consider asserting the inverse case explicitly, e.g. a non-'ready' status with mergeStateLabel 'unstable' should not be affected, to fully pin the guard's scope (test/unit/unified-comment.test.ts).
• Given the description mentions `unified-comment-bridge.test.ts` was run (166 passing) but no changes are shown there, confirm no bridge-side mapping of mergeStateLabel needs a matching update.
• If other mergeStateLabel consumers exist elsewhere in the codebase, grep for `mergeStateLabel ===` to ensure `unstable` is handled consistently everywhere, not just in this one function.
• AI review could not be completed — The gate is held for a human reviewer rather than passed automatically; it re-evaluates on the next update.

Concerns raised — review before merging

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

📋 Copy for AI agents — paste into your coding agent

Fix the following blocker(s) from this PR review:

1. No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.

2. Maintainer requires a linked issue — Link the relevant issue (for example `Closes #123`) before opening the PR.

Signal	Result	Evidence
Code review	❌ 2 blockers	1 reviewer
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
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 (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 45 registered-repo PR(s), 37 merged, 310 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 45 PR(s), 310 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — A single-line but correctness-critical fix that closes a real contradiction between the comment's stated verdict and the bot's own merge-withhold decision, backed by targeted regression tests.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, Ruby, Go, JavaScript, MDX, Shell, Solidity
• Official Gittensor activity: 45 PR(s), 310 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Explain no-issue PR.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

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.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 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