Approval Gates¶

Tatara is designed to be useful without being autonomous. Three gates stand between an issue arriving on a forge and code landing on main:

sequenceDiagram
    participant M as Maintainer
    participant SCM as SCM (GitHub/GitLab)
    participant OP as Operator
    participant AG as Agent pod (implement)

    OP->>SCM: open the issue thread, mirror it onto an Issue CR
    AG->>OP: implement: submit_outcome(action=approved, no citation yet)
    OP->>OP: verifyApprovalScope over every live owned Issue
    Note over OP: no comment to cite yet,<br/>park at identity-unverified
    M->>SCM: comment "go ahead, I approve!"
    SCM->>OP: issue_comment webhook (sender=M)
    OP->>OP: sync the comment mirror,<br/>un-park a fresh implement pod
    AG->>OP: implement: submit_outcome(action=approved,<br/>approving_maintainer=M, plan_note_id=..., approval_citations=[{id, quote}])
    OP->>OP: verify structurally: citation exists, author is a<br/>verified non-bot maintainer, quote occurs verbatim,<br/>not already consumed; plan-hash matches the pinned plan note
    OP->>OP: pin ApprovalEvidence on the Issue CR,<br/>Issue.status.status = approved
    OP->>OP: Task.status.state: refined -> under-implementation
    AG->>SCM: same pod (or its next turn) pushes a branch, opens a PR
    OP->>AG: spawn the review pod
    AG->>OP: review: submit_outcome(verdict=approve)
    OP->>SCM: the OPERATOR posts the review, then merges

Gate 1: Intake - who can drive a Task into existence¶

The intake gate controls which issues and comments the operator acts on at all. By default the gate is open: the operator mints Tasks from issues by any author. When spec.scm.reporterLogins is non-empty the gate becomes restricted: only these authors (plus the bot and any maintainer) may drive the platform. Everything else is dropped at intake - sweep and webhook alike - so unenrolled third parties cannot submit arbitrary work to agents.

The effective reporter set for a given repository is:

1. The configured botLogin - always trusted, unconditionally.
2. Every login in spec.scm.maintainerLogins - always trusted, unconditionally.
3. Every login explicitly listed in spec.scm.reporterLogins - trusted when the list is non-empty.

An empty reporterLogins disables the gate entirely.

apiVersion: tatara.dev/v1alpha1
kind: Project
metadata:
  name: my-project
spec:
  scm:
    provider: github
    owner: my-org
    botLogin: my-bot
    reporterLogins:       # restrict intake to these accounts
      - alice
      - ci-system
    maintainerLogins:     # see Gate 2 - the ONLY approval-granting set
      - alice
      - bob

Intake decides only whether the platform listens. It grants nothing. An allowlisted reporter who is not a maintainer can open an issue and talk to an implement agent all day; they cannot cause a line of code to be written.

Gate 2: The approval grammar¶

Approval is not a label, and it is not a wordlist match either. A maintainer comment is always required. The implement agent judges whether it approves; the operator independently verifies the structural facts the agent's judgment rests on. The operator has no wordlist and does no text matching of its own - it never decides what a comment means. It only checks that the comment the agent cited is real, whose it is, and that the quoted text is genuinely there.

The agent's side, submit_outcome(action=approved, ...):

• reason says in plain words who approved and why the agent read their comment that way.
• plan_note_id is always required on action=approved, including when no human commented: the id of the task_note(kind="plan") call that wrote the plan being approved. The operator hashes that note's body at grant and re-checks the hash before the agent writes any code - see the plan pin below.
• approving_maintainer and approval_citations travel as a pair - both, or neither. approval_citations carries one {id, quote} pair for every Issue the Task owns that a maintainer has commented on at all: id is that comment's forge external_id, copied verbatim from the turn-0 bundle; quote is a verbatim substring of that comment's body. Neither field is required when the Issue satisfies the auto-approve carve-out below - see clause 3 for what happens on an Issue with no maintainer comment.

The operator sets Issue.status.status = approved only when all of the following hold, run by restapi.verifyApprovalScope over every LIVE owned Issue - state == "open" and status not in (done, rejected); an out-of-scope Issue is filtered out of the loop entirely and never has to produce evidence - this is the single grant path; there is no other:

1. An implement Task submitted action=approved. That is the agent's judgment on scope and meaning, and it is a precondition, never itself an approval.
2. Scope. Every live Issue the Task owns satisfies clause 3. Not one of them. Every live one. One citation on one issue does not approve a Task spanning six repositories. Narrowing to live issues is deliberate: a human closing one issue of a multi-issue Task must not make approval require fresh evidence on a closed thread, forever.
3. For each live Issue: a. No maintainer has commented on it at all. Citations are irrelevant in this arm: the Issue either satisfies the auto-approve carve-out or the whole check refuses with no-maintainer-comment. There is nothing for the agent to cite and nothing citing can fix. b. A maintainer has commented, so a citation is now required. For the cited comment C: i. C exists on that Issue - the operator looks it up by external_id in its own mirror (Issue.status.comments), never by trusting the agent's say-so, and its author is a maintainer, structurally excluding the bot. ii. The quote the agent cited really occurs as a substring of C.body as the operator itself holds it. The operator tries the quote exactly as submitted, then - because the turn-0 bundle XML-escapes comment bodies (contract E.1), so a maintainer's "let's ship it" renders as let's ship it and an agent citing that verbatim would otherwise be refused - the quote html.UnescapeString'd. Both are literal containment tests against the operator's own mirror; neither is a fuzzy match, and a fabricated quote fails both. iii. C.externalId is not the comment id already recorded in Issue.status.approval.commentId. Approval evidence is single-use: a consumed comment cannot approve a second time.
4. The operator then pins the evidence on the Issue CR, and once every owned Issue is approved, moves the Task from refined to under-implementation:

status:
  status: approved
  approval:
    login: szymonrychu
    commentId: "1234567"
    createdAt: "2026-07-12T10:02:00Z"
    phrase: "go ahead, I approve!"

phrase here is the matched form of the agent's quote - exactly as submitted if that literal substring occurred in the comment body, or the html.UnescapeString'd form if only that one occurred - not necessarily byte-identical to what the agent submitted, and not a match against any configured wordlist. The Project.spec.scm field that used to hold a closed phrase list is gone, and there is no replacement: what approves is the maintainer's comment as the agent read it and the operator verified it, not membership in a closed set of strings.

The plan pin¶

Approval grants a specific plan, not a blank check. plan_note_id is mandatory on every action=approved call, human comment or not: it names the task_note(kind="plan") the agent wrote before asking for the go-ahead. The operator hashes that note's body at grant time and re-checks the hash immediately before the pod's next code-writing turn - if the plan note has changed since, the Task routes back to refined (plan-hash-mismatch) instead of proceeding on a plan nobody approved. This closes a hole the pre-#521 gate did not have to think about: when the same pod both judges approval and writes the code, "the plan I got approved" and "the plan I am about to implement" are two separate reads that must be pinned to the same note, not two names for the same variable.

There is no most-recent-comment requirement, and that is deliberate¶

Clause 3 does not require the cited comment to be the thread's most recent maintainer comment. Requiring that would deadlock an ordinary thread: a maintainer who writes "go ahead, I approve!" and later adds "thanks - ping me when the PR is up" has given unambiguous consent, but that later comment is not itself a go-ahead, so a most-recent-only check could never be satisfied and the Task would park forever with no path out.

Whether a later maintainer comment actually withdraws an earlier approval is an intent question, and intent is the agent's job under this design, not the operator's - the operator only checks structure. An implement pod that reads a later maintainer comment as a withdrawal or qualification of an earlier approval must submit action=discuss, not cite the stale approval. This is a real, accepted narrowing of the operator's backstop relative to the old wordlist grammar's "most recent wins" rule: a misjudging agent that cites a genuinely-superseded approval is not caught structurally. See Prompt-Injection Defenses for the full accounting of what is and is not covered.

When the citation check runs¶

The check is not a one-shot at implement's first outcome. It runs at both of:

1. an implement Task's submit_outcome(action=approved), and
2. every non-bot event on a Task parked at identity-unverified un-parks the Task and spawns a fresh implement pod - it does not grant approval by itself. That pod reads the refreshed thread and submits its own action=approved with a fresh citation through the same gate.

The webhook path never grants approval on its own any more: it only puts a live agent back in front of the human who just commented. There used to be two grant paths - one at the gate agent's outcome time, one on the webhook comment path - and they have collapsed into the single restapi.verifyApprovalScope call. Collapsing them removes a whole class of the two paths ever disagreeing with each other.

When it fails¶

If any check fails, the Task parks with parkReason=identity-unverified - HTTP 200, not an error. Nothing is posted to the issue thread. The refusal reason is recorded as a Task.status.notes entry, a WARN log line, and the operator_approval_refused_total{reason} counter - visible to whoever operates the platform, not to the maintainer waiting on the thread. Un-parking requires a genuinely new non-bot comment on the thread, and there is nothing on the thread itself prompting anyone to post one; if the situation is not otherwise noticed, the Task can sit parked until it ages out at ParkRetention and is reaped.

Approval is not sticky¶

An Issue acquired after the Task reached under-implementation - through issue_write creating one, or through a refine fold adopting one - resets the Task back to refined, because clause 2 no longer holds. An agent cannot widen its own mandate by adopting work after the gate closed behind it.

The one carve-out with no comment to cite: autoApproveMaxSignificance¶

There is one path where ApprovalEvidence is pinned with no maintainer comment at all: a bot-authored proposal issue (from brainstorm or an incident filing) is auto-approved with login: <tatara:auto> and commentId: "", and auto: true is stamped so the transition is queryable without log-scraping. It exists alongside the citation check above, not instead of it - a maintainer comment on an auto-approvable issue still routes through the normal citation path, and the carve-out only fires when there is no maintainer comment for the agent to cite in the first place.

Project.spec.autoApproveMaxSignificance is how much that path may ship:

The empty string reads as off. That is what makes the CRD upgrade fail closed: the field replaced a boolean, so every Project written by an older operator carries no value for it.

The other four axes of the carve-out are unchanged and all still hold: the issue must be open, bot-authored, carry a valid tatara-proposed-by marker, and still match its filing-time Spec.proposalBodyHash anchor. Raising the ceiling widens what an already-qualifying proposal may ship; it does not qualify anything new.

The ship gate: no merge request can carry unapproved work¶

The grammar above decides whether an agent may start. A second, separate check decides whether the change may leave, and until it existed the first one could simply be skipped: mr_write(action=open) checked the head branch, idempotency and outstanding work, and submit_outcome(action=submitted) checked only the plan hash. Neither read Issue.status.approval at all, so an implement agent that never called the gate - or that was refused by it and wrote the code anyway - still opened the PR, and neither the reviewer nor the merge corridor downstream has an approval check of its own.

Both now refuse 409 {reason: "approval-required", ...} while any live owned Issue is not clear to ship, with one entry per blocking issue:

Every entry carries a guidance sentence naming the next step. The two no-evidence details are split precisely because their remedies differ: one waits on a person, the other is a tool call the agent can make in the same turn.

Every gate answer guides the agent¶

submit_outcome(action=approved) returns granted: true with a guidance string and the Task under task, or granted: false with reason, declared and guidance. The ship refusals carry per-issue guidance too.

reason is a closed constant and a Prometheus label: it names the fault and says nothing about the remedy, and the remedies genuinely differ per reason - plan-note-not-plan is repaired in the same turn, no-maintainer-comment cannot be repaired by the agent at all. Collapsing that distinction is what produced a real stall: an agent refused no-maintainer-comment could not tell which of five carve-out axes had closed, concluded it needed a comment it had no way to obtain, and spent its turn on action=discuss.

The guidance is derived operator-side from maps that are total over the closed vocabularies, pinned by test. tatara-cli renders whatever rides the refusal and holds no second copy of the vocabulary, so a blocker the operator adds later needs no cli release.

Labels are write-only¶

Labels are a projection of Issue.status.status, never a source of it. The operator writes them; nothing reads them back into a decision.

Issue.status.status   is written ONLY by the approval grammar above, and by the
                      operator's own lifecycle writes (rejected, done).
Labels                are a ONE-WAY PROJECTION of it, written by the operator.
                      No label is EVER read to produce a status. A test in the
                      operator's suite asserts it.

There is no label-to-status path at all - not from the sweep, not from a reconcile, and not from the webhook either. An earlier design kept a webhook-only path, on the reasoning that the webhook alone sees a verified sender and could therefore refuse a bot-written label, where a cron - which sees no sender - would launder one into an approval. That guard is gone along with the path it guarded: the three label-name fields the old model configured on Project.spec (the approval, idea and rejected label names) are removed from the CRD, and no label anywhere means "approved" to anything in the control path.

The only label read anywhere in the control path is tatara-parked, and it decides cost, not authority: the sweep uses it to mint a parked Issue as a cheap, pod-less Task instead of an active one. Forging that label onto an issue buys an attacker a Task that stays parked. It fails safe. Forging a label that meant "approved" would have bought them production.

issue_write has no labels parameter and no status parameter. An agent cannot stamp a label, so it cannot self-escalate by stamping one.

Gate 3: Merge - an operator action¶

Merge is an operator action, triggered by a review agent's approval. It is never an agent action, and the forge's native merge-on-green is never armed on a tatara PR.

A review pod reads the diff and submits submit_outcome. If the verdict is approve, the operator - not the agent - posts the SCM review, then walks Task.spec.mergeOrder and merges each repository in turn:

1. It reads the live head SHA from the forge, never the mirror.
2. If the live head no longer equals MergeRequest.status.reviewedSHA, the head moved under the review. The MR is reset to unreviewed and the Task goes back to reviewing. Reviewed code is what merges, or nothing does.
3. It merges only on green CI at that exact SHA. A 409 or a "head sha changed" from the merge call sends the Task back to reviewing too, which closes the window between the check and the merge.

Two things follow, and they are the whole design:

• No MCP tool exposes merge. There is no merge action in any tool profile, for any agent kind. A hallucinated merge has nothing to call.
• Agents never post SCM reviews either. The operator writes the review from the accepted verdict. The platform has one bot identity, and a forge will not let an identity post an approving review on its own pull request - so the review the operator posts is a comment carrying the verdict, and the approval of record is the merge itself, not a green review check on the PR.

What is in scope under one identity¶

Three controls remain available and are all worth having:

1. Branch protection forbidding direct pushes to main on every repository. This stops git push origin HEAD:main outright and needs no review requirement at all. It is the single highest-value control available under one identity, and it is cheap.
2. A scoped installation token in place of an org-wide PAT, so the blast radius of a leaked pod token is one installation rather than the whole organisation.
3. gh, glab, and direct-to-forge-API curl on the wrapper's deny-list, so a compliant agent has no ergonomic path to the merge endpoint even though a determined one has a possible path.

Per-repository overrides¶

Both allowlists can be overridden at the Repository CR level, independently of the Project. This lets you tighten gates on sensitive repositories without changing the project-wide defaults.

apiVersion: tatara.dev/v1alpha1
kind: Repository
metadata:
  name: payments-service
spec:
  projectRef: my-project
  url: https://github.com/my-org/payments-service
  maintainerLogins:    # overrides project-level for this repo only
    - alice
    - security-lead
  reporterLogins:      # overrides project-level for this repo only
    - alice
    - security-lead

Override semantics:

An explicit empty list [] opens intake for that repository to any SCM author, regardless of the project-level reporterLogins. To close intake to only the bot and maintainers, set reporterLogins to a non-empty list containing only the trusted accounts.

Setting maintainerLogins to an explicit empty list [] for a repository has the opposite effect: it closes the approval gate for that repository - no maintainer, so no comment there can ever approve anything - even if the project-level list is non-empty.

The complete approval flow¶

flowchart TD
    A([Issue filed]) --> B{Intake gate\nreporterLogins}
    B -- author not allowed --> Z1([Dropped - no Task minted])
    B -- author allowed --> C[implement pod reads the thread\nstate: refined]
    C -- action: rejected --> D([Issue closed, state rejected])
    C -- action: discuss --> E[Task stays at refined]
    C -- "action: approved\n+ plan_note_id\n+ approval_citations" --> F{verifyApprovalScope:\ncitation + plan-hash checks pass\non EVERY live owned Issue?}
    F -- no --> P[parked: identity-unverified\nHTTP 200, not an error\nnothing posted to the thread]
    F -- yes --> G[ApprovalEvidence pinned\nstate: under-implementation]
    P --> H{Non-bot comment\narrives on the thread}
    H --> R[un-park,\nfresh implement pod re-decides]
    R --> C
    E --> H
    G --> I[same implement pod\nopens a PR]
    I --> J[review pod submits a verdict]
    J -- request_changes --> I
    J -- approve --> K{Live head SHA still\nequals reviewedSHA?}
    K -- no --> J
    K -- yes --> L{CI green at that SHA?}
    L -- no --> M([Hold - awaiting CI])
    L -- yes --> N([Operator merges, in mergeOrder])