TaskZilla Merge Bot

I am TaskZilla's deterministic pull-request policy controller. I assemble exact-head evidence, apply protected merge policy, publish a readable scorecard, and merge only when that policy explicitly allows it.

No LLM makes my decision. The same trusted policy and the same evidence must produce the same result.

My job

I do	I do not
Bind every decision to one pull-request head SHA	Infer product intent, code meaning, or acceptable business risk
Evaluate protected, versioned repository policy	Treat an AI comment, label, reaction, or timeout as authority
Maintain deterministic path/risk labels, reviewer routing, and marker-backed control-plane receipts	Use model credentials or let untrusted PR text choose a privileged action
Publish one durable scorecard and update it as evidence changes	Merge a stale, out-of-date, held, rejected, or red commit
Submit a clearly identified policy approval only for low-risk work that I will immediately revalidate and merge	Impersonate a human approval or satisfy a required CODEOWNER decision
Revalidate immediately before merging eligible low-risk work	Bypass branch protection, force-push, administer repositories, or expose secrets

Evidence and decision contract

My inputs are machine-checkable facts:

• pull-request number, author, base branch, and exact head_sha;
• protected policy revision and digest from the default branch;
• required CI contexts and conclusions attached to that same head;
• current formal reviews, holds, rejections, and staleness state;
• the advisory review receipt and the head it covers;
• declared and path-derived risk class; and
• mergeability, base freshness, and repository protection state.

Labels make state easy to scan, but no label grants merge authority. Comments and SVGs explain the decision; structured Forgejo state and protected policy make it.

Deterministic state machine

1. Collect the evidence snapshot for the exact head.
2. Classify it with protected policy. Missing, stale, conflicting, or unavailable authority-bearing evidence resolves to WAIT or HUMAN, never MERGE. Missing or unavailable model output is neutral: it grants nothing and does not replace deterministic policy or human requirements.
3. Publish one marker-backed scorecard containing every gate, source, and reason.
4. Policy-approve only for an eligible low-risk head that I will immediately revalidate and merge. The review must say that it is policy evidence—not human judgment. I never submit APPROVED on a human-required path.
5. Revalidate head SHA, base freshness, required checks, reviews, holds, risk, and permissions immediately before the merge API call.
6. Merge only eligible low-risk work; otherwise wait or escalate.

Any new commit invalidates the earlier decision and starts the evaluation again.

What the scorecard proves

A useful scorecard names:

• repository, pull request, base, and exact head SHA;
• merge-policy revision and digest;
• required status contexts with their exact-head conclusions;
• advisory-review receipt SHA and disposition;
• human approvals, rejections, holds, and CODEOWNER requirement;
• risk class and the rule that produced it;
• current action: WAIT, POLICY APPROVED, HUMAN REQUIRED, or MERGE ELIGIBLE;
• evaluation time and the bot identity that performed it.

The scorecard is a durable receipt, not a stream of repetitive comments. A transition edits the existing receipt and rotates any automerge:* state label.

Safety boundaries

I must not merge when any of these are true:

• the head changed, the base is outdated, a required check is not green, or mergeability is unknown;
• a blocking review, unresolved hold, or protected approval requirement remains;
• an exact-head advisory receipt reports unresolved supported findings or malformed evidence that needs human triage;
• a sensitive path, high-risk class, deployment boundary, security control, or shared contract requires a human owner;
• the pull request changes my own policy, workflow, credentials, permission model, or merge implementation; or
• Forgejo, the evidence source, or revalidation call fails.

Self-modifying control-plane changes are never silently self-authorized. I may explain their deterministic state, but I withhold APPROVED; the final approval and merge belong to an independent human.

Who does what

• CI proves deterministic tests, builds, lint, security, and contract checks for the exact head.
• code-review-bot provides advisory semantic analysis with visible model and policy provenance. It cannot approve or merge.
• Human reviewers and CODEOWNERS own intent, domain judgment, security decisions, exceptions, and risk acceptance.
• I enforce the mechanical merge contract and serialize the final transition for eligible low-risk work.

An exception is not a hidden toggle. It needs a named human owner, written reason, bounded scope, expiry or follow-up, and an auditable Forgejo record.

Least-privilege contract

My identity is dedicated, restricted, and non-admin. Its token is separate from the AI reviewer and scoped only to the repositories and operations needed to read evidence, request the advisory reviewer, maintain deterministic labels and control receipts, update the scorecard, submit a policy review, and merge an eligible branch. It has no branch-protection administration, workflow-secret administration, release, deployment, or force-push authority.

The canonical design and rollout are tracked in TaskZilla/taskzilla#1424.