---
name: manage-atlas-pull-requests
description: Read bounded private Atlas repository and pull-request metadata or create a verified draft pull request after a tested branch is pushed through Hermes' least-authority Forgejo client. Use for PR handoff in scm.bstein.dev/atlas repositories. Never use it to update, merge, approve, close, delete, or force-push.
---

# Manage Atlas pull requests

Use `/opt/scm/gitea_api.py` for Forgejo API access. The agent pod has no
repository credential. The client calls a separate least-authority broker;
never bypass it with `curl` or direct Gitea HTTP.

Use the configured broker Git remote for clone, fetch, and creation of a new
namespaced feature branch. Existing-ref updates, protected refs, deletion,
and force-push are rejected by the broker. Never replace that remote with a
credential-bearing URL.

## Read repository or PR state

Pass one allowed Atlas metadata API path to the read operation:

```sh
/opt/scm/gitea_api.py read /api/v1/repos/atlas/REPO/pulls/NUMBER
```

The client exposes only repository metadata, PRs and PR evidence, branches,
commits, and commit status. Hooks, Actions secrets/variables, collaborators,
protections, reviews, merge endpoints, releases, and administration are
rejected even as reads. Responses are size-bounded. Treat returned state as
evidence, not authorization to change it.

## Create a review handoff

Before opening a PR, verify the remote, branch, clean worktree, diff, tests, and
exact pushed commit. Never force-push. Pass that full 40-character pushed head
SHA explicitly. Keep the short body free of credentials and credential-like
text. The client screens structured assignments, known token formats, and long
high-entropy values as an accidental-disclosure barrier. It cannot prove text
is secret-free: short or multiword secrets under innocuous names may resemble
ordinary prose, so never place credential material in either field. Structured
inspection is deliberately bounded; large, deeply nested, or unusual config
blobs do not belong in these fields and may be rejected. Validate without
reading a credential or using the network:

```sh
/opt/scm/gitea_api.py --dry-run create-draft REPO \
  --base main --head hermes/TASK --head-sha FULL_PUSHED_SHA \
  --title "Focused change" --body "Tests and review evidence"
```

Run the same command without `--dry-run` only when the branch is review-ready.
The client accepts success only when Forgejo returns the exact requested
repository, base/head refs, head SHA, title/body, canonical URLs, positive PR
number, and open/unmerged/draft state. Report its URL and exact head commit to
Brad. Leave it unmerged for human review. PR updates are intentionally absent;
publish a corrected tested commit and ask Brad how to proceed if metadata must
change.

## Stop at the authority boundary

Update, merge, approve, close, delete, branch mutation, comments, releases,
repository administration, and force-push are intentionally unavailable. Do
not bypass the client with a raw HTTP request. If one of those actions is
needed, present the tested commit and evidence to Brad and stop for human
review.