89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
---
|
|
name: manage-atlas-pull-requests
|
|
description: Read bounded Atlas repository and pull-request metadata, create a verified draft, or queue a trusted repair of an existing Hermes-owned PR. Use for PR handoff in scm.bstein.dev/titan repositories. Never 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. Protected refs, deletion, and force-push are
|
|
rejected by the broker. Never replace that remote with a credential-bearing
|
|
URL. A pre-existing review branch may only be updated by a coordinator-issued
|
|
continuation task with a signed worker grant; an ordinary task cannot choose
|
|
or update it.
|
|
|
|
## 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/titan/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.
|
|
|
|
## Continue an existing Hermes PR
|
|
|
|
When the user asks to fix or continue an existing Hermes PR, including after a
|
|
review rejection or CI failure, queue a repair from its canonical root task.
|
|
Do not invent lineage in task text, pass a branch or PR URL, or open another
|
|
PR. The continuation command reads the board-local coordinator integrity record,
|
|
proves that the recorded PR is still open on its exact
|
|
repository/base/branch, and creates an idempotent root-parent child card:
|
|
|
|
```sh
|
|
python3 /opt/coordinator/kanban_continue_pr.py \
|
|
--board BOARD --root-task ROOT_TASK_ID \
|
|
--objective "Describe the approved repair and required verification"
|
|
```
|
|
|
|
The returned task ID is the continuation. Its worker receives a private clone
|
|
of the latest verified remote branch and may update only that recorded PR
|
|
through the signed mediator path. Re-running the command with the same root,
|
|
objective, and current head returns the same child. A changed head creates a
|
|
new child and clears any prior human-ready indication. Inspect the current diff
|
|
and tests before deciding whether to repair; reconcile delegated findings
|
|
before final triage. A PR being behind its base is not a reason to abandon it.
|
|
The signed broker request refreshes that existing PR's title and body for the
|
|
new verified head; never treat an old handoff description as current evidence.
|
|
|
|
## Stop at the authority boundary
|
|
|
|
Merge, approve, close, delete, force-push, releases, and repository
|
|
administration are unavailable. Do not bypass the client with raw HTTP. A
|
|
continuation only updates an existing PR through its trusted worker grant; it
|
|
does not change the human review authority.
|