Harden PR queue reconciliation against stale or conflicting PR state reports #166

New Issue

2026-07-05T11:25:34-05:00

jcwalker3 commented

2026-07-05 11:25:34 -05:00

Problem

Recent reviewer sessions produced conflicting queue reports for the same PR.

Observed mismatch:

One reviewer session reported Gitea-Tools PR #163 was reviewed, merged, and Issue #154 was closed.
A later reviewer session reported PR #163 was still open with change requests and skipped it.
This indicates one of the sessions was operating on stale MCP data, stale local git state, wrong remote/repo context, cached PR list output, or insufficient post-merge verification.

This is a workflow reliability issue. LLM reviewers must not make review/merge decisions from stale or conflicting PR state.

Goal

Improve the Gitea MCP review workflow and/or tooling so PR queue reconciliation is live, explicit, and conflict-aware.

Requirements

Add or improve documentation/runbooks for reviewer queue reconciliation:
- list open PRs
- immediately view_pr the selected PR
- verify PR state, mergeability, head SHA, review status, and linked issue state
- fetch/prune remotes before local validation
- after merge, re-list open PRs and re-view the merged PR
- use git merge --ff-only or equivalent fast-forward-only master update
Add a warning rule:
If a reviewer sees a PR as open but a prior handoff says it was merged, the reviewer must:
- re-fetch/re-view the PR
- check linked issue state
- check master commit/merge commit
- report the inconsistency
- stop before reviewing or merging that PR unless live state is unambiguous
Improve MCP tool output if needed:
- gitea_list_prs and/or gitea_view_pr should expose enough safe metadata to detect stale/conflicting state:
  - state
  - mergeable
  - head SHA
  - base branch
  - updated timestamp
  - merged timestamp, if closed/merged
  - merge commit SHA, if available
  - linked issue state, if safely derivable
- Do not expose raw service URLs unless reveal-gated.
Add or update guide/runtime output:
- warn that queue state can move quickly across multiple LLMs
- tell reviewers to reconcile live state before acting
- tell reviewers not to rely only on prior chat handoffs
- tell reviewers to treat conflicting PR state as a blocker until resolved
Add tests if code changes are made:
- stale prior handoff says merged but live PR says open
- prior handoff says open but live PR says closed
- gitea_list_prs and gitea_view_pr disagree
- merge commit missing after claimed merge
- linked issue remains open after claimed merge
- safe metadata is present without leaking raw URLs/secrets

Acceptance criteria

Reviewer workflow clearly requires live-state reconciliation before review/merge.
Conflicting PR state reports are treated as a stop-and-report condition.
Post-merge verification includes PR state, issue state, updated master commit, and refreshed PR queue.
Tool output or docs make stale-state risk explicit.
No secrets, tokens, keychain IDs, raw private service URLs, or private config values are exposed.
No production changes.
No tags/releases.

Notes

This issue is about preventing future queue/reporting errors by LLM reviewers. It is not about blaming a specific LLM. The system should make stale state harder to miss.

Related: #164 (read-only PR queue inventory under author profiles — three-way "found / not attempted / blocked" report language), #139 (role-aware task routing umbrella), #142 (structured permission failure reports).

## Problem Recent reviewer sessions produced conflicting queue reports for the same PR. Observed mismatch: * One reviewer session reported Gitea-Tools PR #163 was reviewed, merged, and Issue #154 was closed. * A later reviewer session reported PR #163 was still open with change requests and skipped it. * This indicates one of the sessions was operating on stale MCP data, stale local git state, wrong remote/repo context, cached PR list output, or insufficient post-merge verification. This is a workflow reliability issue. LLM reviewers must not make review/merge decisions from stale or conflicting PR state. ## Goal Improve the Gitea MCP review workflow and/or tooling so PR queue reconciliation is live, explicit, and conflict-aware. ## Requirements 1. Add or improve documentation/runbooks for reviewer queue reconciliation: * list open PRs * immediately `view_pr` the selected PR * verify PR state, mergeability, head SHA, review status, and linked issue state * fetch/prune remotes before local validation * after merge, re-list open PRs and re-view the merged PR * use `git merge --ff-only` or equivalent fast-forward-only master update 2. Add a warning rule: If a reviewer sees a PR as open but a prior handoff says it was merged, the reviewer must: * re-fetch/re-view the PR * check linked issue state * check master commit/merge commit * report the inconsistency * stop before reviewing or merging that PR unless live state is unambiguous 3. Improve MCP tool output if needed: * `gitea_list_prs` and/or `gitea_view_pr` should expose enough safe metadata to detect stale/conflicting state: * state * mergeable * head SHA * base branch * updated timestamp * merged timestamp, if closed/merged * merge commit SHA, if available * linked issue state, if safely derivable * Do not expose raw service URLs unless reveal-gated. 4. Add or update guide/runtime output: * warn that queue state can move quickly across multiple LLMs * tell reviewers to reconcile live state before acting * tell reviewers not to rely only on prior chat handoffs * tell reviewers to treat conflicting PR state as a blocker until resolved 5. Add tests if code changes are made: * stale prior handoff says merged but live PR says open * prior handoff says open but live PR says closed * `gitea_list_prs` and `gitea_view_pr` disagree * merge commit missing after claimed merge * linked issue remains open after claimed merge * safe metadata is present without leaking raw URLs/secrets ## Acceptance criteria * Reviewer workflow clearly requires live-state reconciliation before review/merge. * Conflicting PR state reports are treated as a stop-and-report condition. * Post-merge verification includes PR state, issue state, updated master commit, and refreshed PR queue. * Tool output or docs make stale-state risk explicit. * No secrets, tokens, keychain IDs, raw private service URLs, or private config values are exposed. * No production changes. * No tags/releases. ## Notes This issue is about preventing future queue/reporting errors by LLM reviewers. It is not about blaming a specific LLM. The system should make stale state harder to miss. **Related:** #164 (read-only PR queue inventory under author profiles — three-way "found / not attempted / blocked" report language), #139 (role-aware task routing umbrella), #142 (structured permission failure reports).

jcwalker3 added the mcp gitea documentation testing reliability workflow labels 2026-07-05 11:25:43 -05:00

jcwalker3 referenced this issue

2026-07-05 11:33:05 -05:00

Harden LLM role/task alignment and PR review feedback discovery #167

jcwalker3 added the status:in-progress label 2026-07-05 11:40:12 -05:00

jcwalker3 commented

2026-07-05 11:44:11 -05:00

Coordination note (author session, jcwalker3 / prgs-author):

I claimed this issue via status:in-progress a few minutes ago after finding it unclaimed. Immediately afterward I detected live uncommitted work-in-progress for this issue by another operator session in the shared main clone (branch feat/issue-166-pr-queue-reconciliation-harden, uncommitted edits to mcp_server.py, tests/test_mcp_server.py, and docs/llm-workflow-runbooks.md — including updated_at/merged_at/merge_commit_sha staleness metadata and a live-state reconciliation runbook section, with tests tagged (#166)).

I am NOT implementing this issue. I am leaving the status:in-progress label in place so it protects the in-flight WIP session from a third operator grabbing the issue. That session should post here to confirm ownership when it opens its PR. Operator may reassign/release the label if that session has died.

I am moving to issue #167 instead (isolated worktree; no contact with this clone's working tree).

Coordination note (author session, `jcwalker3` / `prgs-author`): I claimed this issue via `status:in-progress` a few minutes ago after finding it unclaimed. Immediately afterward I detected **live uncommitted work-in-progress for this issue by another operator session** in the shared main clone (branch `feat/issue-166-pr-queue-reconciliation-harden`, uncommitted edits to `mcp_server.py`, `tests/test_mcp_server.py`, and `docs/llm-workflow-runbooks.md` — including `updated_at`/`merged_at`/`merge_commit_sha` staleness metadata and a live-state reconciliation runbook section, with tests tagged `(#166)`). I am NOT implementing this issue. I am leaving the `status:in-progress` label in place so it protects the in-flight WIP session from a third operator grabbing the issue. That session should post here to confirm ownership when it opens its PR. Operator may reassign/release the label if that session has died. I am moving to issue #167 instead (isolated worktree; no contact with this clone's working tree).

jcwalker3 referenced this issue from a commit

2026-07-05 11:45:11 -05:00

feat: harden PR queue reconciliation against stale/conflicting state (#166)

jcwalker3 referenced a pull request that will close this issue

2026-07-05 11:45:14 -05:00

Harden PR queue reconciliation against stale or conflicting PR state reports #168

sysadmin referenced this issue

2026-07-05 11:58:58 -05:00

Harden PR queue reconciliation against stale or conflicting PR state reports #168

sysadmin closed this issue

2026-07-05 11:59:06 -05:00

sysadmin removed the status:in-progress label 2026-07-05 11:59:07 -05:00