feat(review): delivery escalation for generated E2E tests — commit / follow-up-PR modes

[JSONbored]

Part of #4189. Depends on #4195. See also #4201 (contributor-scoring exclusion — required before this ships, not optional).

Revised 2026-07-08: this is now the primary v1 delivery mode, not a v2 escalation over comment-only suggestion. Maintainers specifically want "generate full E2E test code at the click of a button, added as a new commit to the PR, before it merges" — that's this issue's commit mode, invoked only via #4195's maintainer-only command. The comment-only rendering path (#4193/#4194) still matters as a confirmation/summary layer (what was generated, a link to the commit), not as the primary content-delivery mechanism. pr mode (a separate follow-up PR) remains a genuine v2+ option but is no longer the focus of this issue.

Context

gittensory already has a working example of exactly the write path this needs: openRepoDocPullRequest (src/github/repo-doc-pr.ts:140) builds a tree/commit/branch using the raw Git Data API (POST git/trees at repo-doc-pr.ts:98,102, POST git/commits at repo-doc-pr.ts:220, POST git/refs at repo-doc-pr.ts:223). This issue needs the "commit onto the existing PR's own head branch" variant — a ref-update against the PR's head.ref, not a new branch/ref-create.

This is a deliberate, narrow exception to #1972's no-cloud-write boundary (see the epic's Context) — safe specifically because: (1) only a genuine maintainer/owner can trigger it (#4195's ["maintainer"]-only authorization, never collaborator/pr_author/confirmed_miner), (2) the commit is clearly attributed (a commit trailer + PR comment marker identifying it as maintainer-invoked/machine-generated), and (3) the contributor's Gittensor score must not be inflated by it (#4201).

Requirements

• commit mode (the primary target): push the generated test file(s) as a new commit onto the PR's own head branch/ref, reusing the git/trees → git/commits → git/refs pattern from repo-doc-pr.ts, adapted to PATCH git/refs/{ref} against the PR's existing head rather than creating a new ref.
• The commit must carry a clear, auditable marker of provenance — e.g. a trailer such as Generated-by: gittensory (invoked by @<maintainer-login>) — both so fix(scoring): exclude maintainer-generated test commits from contributor scoring #4201's scoring exclusion has a reliable signal to key off, and so anyone reading git log later understands where the commit came from.
• Must respect feat(commands): wire @gittensory generate-tests PR-comment command #4195's ["maintainer"]-only authorization tier — do not widen it for this heavier write; if anything this mode deserves the same or stricter scrutiny than plain comment delivery, not less.
• Public-safe content only — reuse feat(review): render + comment-assembly for generated E2E test blocks #4193's render/safety guarantees for the commit's content; do not bypass that layer just because the destination changed from a comment to a commit.
• After a successful commit, post a short confirmation comment (reusing feat(commands): wire @gittensory generate-tests PR-comment command #4195's confirmation-comment convention) linking to the new commit — this is the "summary layer" role feat(review): render + comment-assembly for generated E2E test blocks #4193/feat(review): dispatch wiring for e2eTests in queue/processors.ts #4194's rendering now plays, replacing "the full test source lives in the comment body."
• pr mode (separate follow-up PR, lower priority than commit mode for this issue): follow openRepoDocPullRequest's pattern directly (new branch off the PR's head, tree/commit/ref, then POST pulls) if/when a maintainer wants tests reviewed independently of the PR itself. Must account for gittensory's 2-open-PR contributor cap (src/settings/global-contributor-cap.ts) — document whether a generated-tests PR counts against the contributor's cap (it should not, since the contributor didn't open it) or is exempt entirely.
• A delivery setting on the e2eTests feature config (resolve the exact shape against feat(review): register e2eTests as the sixth converged-feature key #4190/feat(config): repo/path-scoped test-coverage instructions for e2eTests generation #4200's schema work) selects commit vs pr vs (still available) comment-only — default should be whatever a maintainer explicitly opts into per repo, not silently on.

Deliverables

• commit mode implemented and tested against a fixture PR branch, including the provenance trailer.
• Confirmation-comment posting after a successful commit.
• pr mode implemented as the secondary path, with a documented decision on the contributor-PR-cap interaction.
• delivery config resolved, defaulting to no silent behavior change for repos that haven't opted in.

Expected outcome

A maintainer can comment @gittensory generate-tests on any PR and get a real commit, pushed directly onto that PR's branch, containing AI-generated Playwright tests — clearly attributed, gated to maintainer-only, and excluded from the contributor's own scored contribution.

Resources / examples

• src/github/repo-doc-pr.ts (full file — openRepoDocPullRequest, the git/trees → git/commits → git/refs pattern)
• src/settings/global-contributor-cap.ts (the contributor open-PR-cap mechanism to reconcile with, for pr mode)
• CodeRabbit's own two delivery modes, for reference: same-PR commit vs. separate follow-up PR

Effort

L — real write access to a PR branch is a bigger surface than anything else in the epic short of #4198; budget for careful authorization, provenance, and scoring-interaction review.

[linear-code]

JSO-3229