Gitea-Tools/docs/bootstrap-review-path.md

Bootstrap Review Path for Self-Hosted MCP Workflow Fixes (#557)

Purpose

Gitea-Tools MCP workflow fixes can create a bootstrap deadlock: the live MCP daemons still run the broken code from master, so canonical reviewer / merger tools cannot complete the review that would land the fix.

This document defines a narrow, controller-authorized bootstrap path so such fixes can land without weakening normal review/merge gates.

It is not a general bypass. Normal PRs must still use the full reviewer → merger MCP workflow.

When this path applies

All of the following must be true:

1. The PR changes Gitea-Tools MCP workflow / preflight / lease / gate code that the live daemon must load to review itself (self-hosted control plane).
2. Canonical review or merge tools fail closed because of that defect (documented tool errors, not “inconvenience”).
3. A controller records an explicit bootstrap authorization on the PR or linked issue (see below).
4. The PR source is clean, testable, and free of unrelated scope.

Example (historical): PR #553 / Issue #546 (reviewer preflight capability/lease deadlock). Live daemons on unpatched master could not complete canonical review of the fix PR.

Durable authorization (required)

No manual remote merge, force-merge, or API merge of a bootstrap PR is allowed unless a controller has posted a durable authorization record on Gitea.

Authorization record (issue or PR comment)

The controller comment must include a machine-readable marker and the fields below:

## BOOTSTRAP REVIEW AUTHORIZATION (#557)

Status: APPROVED
PR: <number>
Issue: <number>
Controller: <gitea username>
Reason: live MCP runtime cannot canonically review this self-hosted workflow fix
Scope: narrow bootstrap only — does not weaken normal PR gates

Validation evidence:
- git diff --check: clean
- targeted pytest: <command> → pass
- full suite attribution (if non-zero): baseline compared to prgs/master

Duplicate-PR audit: <none | list and disposition>
Mutation ledger audit: <summary or path to proof>
Contamination audit: <clean | list contaminated comment/lease IDs and disposition>

Allowed verification actions used: <list>
Forbidden actions NOT used: root checkout edits; raw curl mutation; direct
module import of gitea_mcp_server for mutations; in-memory gate restoration

Post-land plan:
- restart MCP daemons for author/reviewer/merger/reconciler profiles
- re-verify with canonical tools (see Post-bootstrap steps)

Without this record, bootstrap merge is forbidden. Agents must stop with BLOCKED + DIAGNOSE rather than improvise a merge.

Review gates and proof (still required)

Bootstrap does not skip technical review. It only allows verification and landing when the live MCP mutation path cannot complete the review.

Before authorization, the controller (or a delegated read-only verifier in an isolated worktree) must have:

Gate	Requirement
Diff hygiene	git diff --check clean on the PR tip vs prgs/master
Tests	Targeted tests for the fix pass; full suite either green or failures attributed to baseline prgs/master
Duplicate PR	Open-PR inventory shows no competing open PR for the same issue (or supersession is documented)
Mutation ledger	Any claimed mutations are ledger-consistent; no silent root edits
Contamination audit	PR/issue comments and leases classified as clean vs workflow-contaminated
Scope	Diff limited to the bootstrap issue; no drive-by refactors

Contamination audit (comments / leases)

Comments or leases created via raw curl, direct Python import of MCP modules, or token extraction are workflow-contaminated. They must be listed and must not be treated as canonical review proof.

Only comments posted via sanctioned MCP reviewer tools (after the fix is landed and daemons restarted, or during a clean path that did not bypass gates) count as canonical review state.

Historical example on PR #553:

Comment	Disposition
#7247 test / raw API	contaminated
#7251 lease metadata / raw API	contaminated
#7252 lease metadata / direct import	contaminated
#7265 lease metadata / MCP reviewer tools	workflow-clean

Allowed verification actions

These may run outside the broken live mutation path to establish facts:

• Read-only MCP tools (gitea_view_pr, gitea_list_prs, gitea_whoami, gitea_get_profile, inventory, eligibility reads).
• Isolated branches/ worktree checkout of the PR head (never root).
• git fetch, git log, git diff, git merge-tree (read-only analysis).
• Targeted pytest / py_compile inside that worktree.
• Controller posting of the bootstrap authorization comment via a healthy MCP profile if available; if comment mutation is also deadlocked, a human operator posts the authorization in the Gitea UI (still durable on the thread).

Forbidden actions (always)

Even under bootstrap:

• Editing or committing in the project root / control checkout.
• Treating root as a worktree for implementation or review mutations.
• Raw curl / REST mutation with extracted tokens as a normal workflow.
• import gitea_mcp_server (or sibling modules) from a shell to call mutation helpers and bypass preflight.
• In-memory restoration of capability / lease / decision state to “finish” a blocked chain.
• Force-push, history rewrite, or deleting evidence comments.
• Weakening normal gates in code “temporarily” without a tracked issue/PR.
• Self-review or self-merge by the PR author identity.

Landing procedure (after APPROVED authorization)

1. Confirm the authorization record is present and complete on the PR or issue.
2. Merge only with an independent merger identity when possible.
   • Preferred: restart/replace the MCP merger daemon with a build that includes the fix (or a one-shot process started from the PR worktree binary) so gitea_merge_pr can run under normal gates.
   • If the live merger daemon still cannot load the fix, a human operator may merge via the Gitea UI only after the authorization record exists.
3. Never merge from contaminated proof alone.

Post-bootstrap steps

1. Restart MCP daemons

After the fix lands on prgs/master:

1. Stop author / reviewer / merger / reconciler MCP server processes for this repo (IDE MCP pool + any long-lived terminals).
2. Confirm no stale PID still serves the old code.
3. Restart each profile so it loads the updated master tree (or installed package path).
4. Call gitea_whoami / gitea_get_profile on each namespace and record profile name + identity.

2. Re-verify with canonical tools

Example pattern after PR #553-class fixes (lease release / #550-style follow-up):

1. From a reviewer MCP session: acquire/release or inspect the relevant lease with canonical tools only.
2. Confirm no direct-import or raw-API path is required.
3. Post a short controller or reconciler note: bootstrap complete; normal gates restored.

If verification still requires a bypass, open a new issue — do not extend this bootstrap authorization silently.

Explicit non-goals

• This path does not authorize skipping tests, duplicate audits, or contamination audits.
• This path does not authorize root checkout implementation work.
• This path does not replace BLOCKED + DIAGNOSE when a non-bootstrap failure occurs (#552).
• This path does not grant permanent “operator exception” culture.

Related

• Root checkout policy: docs/llm-workflow-runbooks.md (Global LLM Worktree Rule, #475)
• BLOCKED + DIAGNOSE: issue #552 / skill workflows
• Reviewer lease / preflight deadlock class: issues #546, #548, #550
• Durable session proofs across daemon pools: issue #559