4.3 KiB
name, description
| name | description |
|---|---|
| manage-atlas-pull-requests | 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:
/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:
/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:
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.