Skip to content

Solo-maintainer explicit-approval token for 🔴 PRs (verified human token instead of a second account) #398

Description

@rucka

Story Statement

As a solo maintainer of a pair-managed repository
I want an explicit-approval token a single human account can apply to a 🔴 PR (a human-applied approved:human label with actor verification, or an /approve comment command)
So that a single-account repo can satisfy the 🔴 explicit-human-approval rule (D10) without a second reviewer account, instead of leaving the rule advisory

Where: code host (PR approval surface) + pair-explicit-approval required check

Epic Context

Parent Epic: Unified classification & assessments #208
Status: Draft

User Value

Today pair-explicit-approval (#234, ADR-018) demands a non-author human approving review on the current head. GitHub rejects an approving review from the PR author, so on a single-maintainer repository no 🔴 PR can reach ready-to-merge. The only options #234 leaves are: add a second human account, or drop the context from the required list and accept the 🔴 rule as advisory. Neither is acceptable for solo/small projects that are pair's most common adopters.

Rough Sizing

3–5 (design change: the approval token must be forgery-resistant — the actor who applied it must be verified server-side, and the reviewing agent must not be able to apply it).

Initial Scope

Likely In Scope

  • Decide the token mechanism (human-applied approved:human label with actor verification via the host's timeline/audit API, vs an /approve comment command with actor + head-SHA binding).
  • Actor verification: non-bot, non-agent identity, bound to the current head SHA (invalidated by a force-push, like the review-based approval).
  • pair-explicit-approval job accepts the token as an alternative to a non-author approving review; the reviewing agent can never satisfy it.
  • ADR (or ADR-018 amendment) + pr-states.md / github-implementation.md updates; remove the "no story" wording in favour of this one.

Likely Out of Scope

Open Questions

  • Can a label application's actor be verified reliably enough (issue timeline / audit log) for an authorization decision, given labels are writable by any collaborator?
  • Does allowing the author to self-approve at 🔴 preserve any real value of the D10 rule, or does it only preserve the audit trail? (If only the trail, say so explicitly in the ADR.)

Definition of Done Expectations

  • A 🔴 PR on a single-account repository can reach ready-to-merge through a verified human token, with an auditable trail.
  • Grep-verifiable: the reviewing agent has no path to apply the token itself.
  • Docs site + pr-states.md + ADR updated; PR state flow (gate≠review) + pair review as required check #234's "design change with its own story" wording cites this issue.

Dependencies

Prerequisite: #234 (PR state flow + pair-explicit-approval).
Related: #218 (approval/block identity).

Notes

Filed during the independent review of PR #390 (story #234): the PR defers this design change to "its own story" in pr-states.md, ADR-018, the docs-site page and way-of-working.md, but no story existed. This issue makes the deferral tracked and citable.

Metadata

Metadata

Assignees

Labels

user storyWork item representing a user story

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions