Agent Queue → Reviewed PR

The agent proposes, a human validates. Every link in the loop must have a consumer — an unconsumed state is a ticket stuck forever.

Access, data and network — read before wiring anything

Default is inert: no variable set → no outbound call. Every network destination is opt-in and listed here — there are no others.

Data minimization is a default, not your problem to solve. A brief cites code, never people: never copy a requester's name, email address, or any other personal identifier into a brief, a payload, a PR description, or a screenshot. Honor your forge's and hosting provider's ToS, and the law that applies to you (GDPR where applicable). Never point the QA link at a production tenant.

When to Use

The closed loop

  human triage (prioritize)          ← the cheapest guardrail there is
        │
        ▼
  [GROUND] raw request ──read-only code──▶ anchored brief ──▶ grounding-ack
        │
        ▼
  [RUN] queue ──▶ head of queue only ──▶ worktree ──▶ implement ──▶ blocking QA ──▶ draft PR ──▶ ack
        │                                                                                        │
        ▼                                                                                        ▼
  [STEWARD] merge integration branch in, map inter-PR conflicts        [QA] browser-test the preview → verdict + label
        │                                                                                        │
        ▼                                                                                        ▼
  [DRIFT] audit briefs still in queue ──STALE──▶ back to GROUND        [REMEDIATE] consume needs-work → fix on PR branch → back to QA

Read the arrows as consumers: stale-ack → grounding, needs-work → remediation. Ship a link whose output nobody reads and you have built the graveyard.

Contract — queue and ack

Design the HTTP surface first; the agent is the easy part. Full spec + typed errors: references/queue-contract.md.

curl -fsS --max-time 30 "${QUEUE_URL}" -H "Authorization: Bearer ${AGENT_API_TOKEN}"
# Output: {"ok":true,"count":2,"arrangementUpdatedAt":"2026-07-16T09:00:00.000Z","tickets":[
#   {"id":"tkt-401","title":"…","prompt":"…","status":"ready","column":"P0","globalOrder":0}, … ]}

"Ready" = status AND prioritized column. Both, or the ticket is invisible: a card sitting in INBOX is invisible to the agent whatever its status, and a human dragging it to P0..P3 is the explicit authorization to spend agent time. That drag is the human triage gate — the cheapest guardrail in the system. Empty or missing arrangement → empty queue → the agent does nothing. Fail-safe, not fail-open.

The executable grounding gate

Never implement a raw request. Ground it: read the real code read-only, verify every anchor (path, line, helper, convention) before writing it down, and emit a brief so self-contained that another agent can implement it without ever reading the original request. Method + payload template: references/grounding-brief.md. Checks run in one canonical order — the same in the script, in the server, and in the table below; any other order and the two sides are not mirrors.

Duplicate the gate on purpose. Locally you fail before the network call; server-side because your endpoint must never depend on the politeness of its client — a retry script or a hand-written curl will send garbage eventually. Configure the prefix first. ${TARGET_REPO} is a placeholder: export BRIEF_GATE_PREFIX with your repo name substituted, byte-identical to the string your server checks. The script refuses to run on a placeholder — or on an empty value, since startswith("") matches every prompt and would report a disabled gate as a passed one.

export BRIEF_GATE_PREFIX="Read CLAUDE.md AND AGENTS.md at the root of app-example first"
python3 scripts/brief-gate.py tkt-401 payload.json prompt.txt > body.json
# Output (rejected, exit 1): brief-gate: prompt too short (1180 < 3000 chars). Flesh out the brief: target 10000-16000 -- NOTHING was sent.
# Output (accepted, exit 0): stdout → body.json = {"card_id":…,"payload":{…},"prompt":"…"}
#   plus, on stderr, if the brief is under the 10k target: "brief-gate: note - prompt is 4061 chars,
#   outside the 10000-16000 target (gate still green)". Judge the exit code, never the silence.
curl -fsS -X POST "${GROUNDING_ACK_URL}" -H "Authorization: Bearer ${AGENT_API_TOKEN}" \
  -H "Content-Type: application/json" -d @body.json
# Output: {"ok":true,"status":"ready"}
# Output (server mirror rejects): 400 {"ok":false,"error":"grounding_too_thin"}
#   Same predicate, both sides, or it is not a gate.

The run, step by step

1. Fetch. count == 0 → answer QUEUE_EMPTY, stop. HTTP/auth error → STOP + alert, touch nothing.
2. Select globalOrder == 0 only. One ticket per run. No batch, no parallel, no skipping.
3. Anti-duplicate before any work (§below).
4. Deterministic branch = pure function of the ticket: agent/<id>-<slug>. Same ticket ⇒ same branch, forever. This is what makes step 3 possible.
5. Clean worktree from the up-to-date integration branch (git fetch origin then branch off origin/<integration-branch>) — never from a stale local state. Gotcha: if node_modules is a symlink in the worktree, bundlers fail with an unrelated error → rm node_modules && <install command> inside the worktree.
6. Read the target repo's conventions BEFORE implementing: CLAUDE.md + AGENTS.md at its root. They outrank your habits.
7. Implement strictly per the brief. No opportunistic refactor. Ambiguity or a red line in play → STOP + ask. Do not guess.
8. Blocking QA before any commit: <lint> → <type-check> → <test> → <build>. One red = no PR, no ack.
9. One draft PR per run.
10. Ack, then bookkeeping: memory/pr-index.json, journal line, remove the worktree.

git config user.email          # Output: agent@example.com  ← must match the authenticated forge account
gh pr create --repo acme-corp/app-example --base <integration-branch> \
  --head "agent/${id}-${slug}" --draft --fill --label agent
# Output: https://github.com/acme-corp/app-example/pull/42
curl -fsS -X POST "${ACK_URL}" -H "Authorization: Bearer ${AGENT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "$(python3 -c 'import json,sys;print(json.dumps({"card_id":sys.argv[1],"pr_url":sys.argv[2]}))' "$id" "$pr_url")"
# Output: {"ok":true,"status":"pr-opened","pr_url":"https://github.com/acme-corp/app-example/pull/42"}
# Build the body with python3, never by string-concatenating a title into JSON.

Git identity gotcha, root cause: a commit authored with a local email (*@Mac-*.local) is not linked to any forge account, so preview hosts refuse to build the PR ("No account was found matching the commit author email address"). The build never fails — it simply never happens, and the browser-QA link starves with no error to read. Check git config user.email before the first commit of every run.

Anti-duplicate — 4 locks, in order of strength

Negative proof, at the permission layer: provision the PAT with contents:write + pull_requests:write and nothing else. Then gh pr merge fails with a permission error and git push origin <release-branch> is refused by branch protection. The agent doesn't merge because it cannot merge — not because it was asked nicely. Verify this before going autonomous: run gh pr merge once and confirm it fails.

The decision tree

GOLDEN RULE — red = no PR AND no ack, the ticket stays in the queue. This one line is what makes the queue self-healing: a failed run leaves the world exactly as it found it, the ticket is still head-of-queue, and the next healthy run retries it. No retry logic, no dead-letter queue, no state machine. The design does not depend on the scheduler's retry — it depends on never acknowledging work that didn't happen.

The queue you do not control

The golden rule is purchased by the conditional ack (§Anti-duplicate, lock 1). Take that away and it inverts. Sooner or later the work source is a spreadsheet, a shared board, or someone else's API: no compare-and-swap, no conditional write, no transaction. Everything above still applies except the one line you most rely on.

So the rule flips: failure must be terminal, and explicitly written. "No ack" stops being self-healing the instant claiming stops being conditional — the row is already marked. Three consequences, none optional:

1. Confirm the claim by reading it back. Write your claim (status=in_progress plus a runId that is yours), then re-read the row and compare both fields. A mismatch means another writer won — abandon, do not proceed. This read-back is the only race detection you get; there is no 409 coming.
2. Write the failure. Wrap the run so every exit path — crash included — writes a terminal status with a short reason. An unwritten failure is an item claimed by nobody, and it is invisible: the row looks busy, not broken.
3. Reclaim orphans by TTL, never by trust. The claim carries the instant it was taken. An in_progress older than your longest possible run is an orphan; reclaim it. Without this, one kill -9 removes an item from the world permanently and raises no error, ever.

A local lock does not fix this. A mkdir lock on your own disk serializes your runs and says nothing about a second machine, a re-provisioned host, or a human editing the row by hand. The read-back is what protects you; the lock only makes the race rarer — which is worse, because rare enough to pass testing is not the same as absent.

If you can put a conditional write behind the queue, do it. Everything in this section is the tax you pay for not having one.

Integration steward

gh pr list --repo acme-corp/app-example --label agent --state open \
  --json number,headRefName,headRefOid,files,updatedAt
# Output: [{"number":42,"headRefName":"agent/tkt-401-invoice-filter","headRefOid":"9f2c1ab…","files":[…]}]

Idempotence by headSha

One verdict per commit. One remediation attempt per commit. Key every index <number>@<headSha>:

A new commit changes headSha, so the QA label goes stale automatically — no cleanup job, no TTL. Labels are human signals, NOT the source of idempotence: qa-needs-work present but the current headSha absent from qa-index.json = stale → QA re-tests, remediation skips. Without this key, QA and remediation fight over the same PR forever, each undoing the other's premise. Whoever laid down the verdict removes it: remediation pushes and stays silent on labels; QA re-verdicts the new commit and replaces the label. Every run that examines a PR writes an entry — pushed on success, or one of five named escalations, the agent's explicit right not to improvise (without it, an agent facing a hard bug ships a plausible-looking wide fix). Both: references/browser-qa.md.

Brief staleness is a first-class state

A brief anchored in code that has since moved is a loaded gun pointed at the implementation link. Audit briefs still in the queue against the integration branch, read-only. Full method: references/brief-staleness.md.

The technique worth stealing — the skeptical refutation pass. Before any destructive verdict, hand the candidate STALE to a second agent whose only mission is to prove the first wrong (basename, mapped variants, rename, barrel re-export, git log --diff-filter=D, --follow, -S). Refuted → MINOR_DRIFT. Doubt = never STALE. A single agent asked to check itself confirms itself; it has already committed to the reasoning.

The drift watcher's only write is a conditional stale-ack (ready → needs-grounding). Never raw SQL. Never hand-patch a brief — flip the status, let grounding regenerate it. A pr-opened ticket is never re-grounded (action: "check_pr").

Retention — declared is not enforced

QA screenshots are authenticated-session data; indexes name PRs forever. A retention nobody runs is a claim, not a control — so run it weekly, from the repo root, on the loop's cron:

gh pr list --repo acme-corp/app-example --label agent --state all --json number,state > pr-states.json
python3 scripts/retention.py pr-states.json           # dry run: prints the plan, changes nothing
# Output: retention: DRY RUN (3 PRs known) / memory/qa-index.json: 3 -> 1 entries
#         work/qa-runs/PR-42: removing (PR MERGED) / work/qa-runs/PR-99: removing (older than 7 days)
# On stderr, if an entry cannot be expired: retention: WARN memory/pr-index.json: key tkt-401
#   carries no PR number, cannot expire -- add a "number" field to this entry.
python3 scripts/retention.py pr-states.json --apply    # same plan, executed

No network call — it consumes the states fetched above. It removes only PR-<digits> directories directly under work/qa-runs/. The two scopes do not have the same rule. Indexes: an entry whose PR is absent from the listing, or whose key resolves to no PR number, is kept (absence ≠ closure) and WARNed. Screenshots: a PR-<n> directory goes as soon as its PR is no longer OPEN, and in every case at 7 days — open, closed or unknown alike. Screenshots carry authenticated-session data: 7 days is a hard ceiling, not a fallback, so a PR still in review on day 8 loses its evidence by design. It refuses to run from a root holding neither memory/ nor work/qa-runs/ (--root=<path> for cron), because a purge that silently did nothing is the failure this section exists to prevent. The journal memory/YYYY-MM-DD.md is out of scope on purpose — it is the audit trail, holds ids and PR URLs and never personal data, and no code touches it: the enforcement claim is scoped to the three indexes and the screenshots.

An entry is expirable only if a PR number resolves from it — hence number on every pr-index entry (§Anti-duplicate lock 3): that index is keyed by ticket id, so tkt-401 alone resolves to nothing and the entry would live forever. qa-index/remediation-index resolve from their <number>@<sha> key. An unresolvable entry is kept and WARNed on stderr, never kept silently — a retention that quietly skips an index it claims to purge is the "declared, not enforced" failure this section exists to prevent. Grep your cron log for WARN.

Output format

Every run answers with the same block — short, factual, no dump, no secret, no PII:

<link> - <Done | Nothing to process | Started | Blocked | Human action required | Error to fix>
Result: …
Item: …
Next action: …
Details: …

# Filled:
autopr - Done
Result: Draft PR opened and ticket acknowledged.
Item: tkt-401 - Filter invoices by status
Next action: Human review of the PR.
Details: branch=agent/tkt-401-invoice-filter, PR=…/pull/42, checks=green, action=created

Troubleshooting

First-run checklist

• Labels agent, qa-passed, qa-needs-work exist in the repo (gh label create agent) — gh pr create --label fails on a missing label.
• BRIEF_GATE_PREFIX exported with your repo name substituted, byte-identical to the server's string.
• GET ${QUEUE_URL} → 401 without Bearer, 200 with. Both asserted.
• Ack tested twice on one id → second returns idempotent:true.
• Local gate rejects a 1k-char brief without any network call; server returns 400 grounding_too_thin for the same input.
• BRIEF_GATE_PREFIX="" → the gate refuses to run (exit 1). An empty gate must never look like a passed one.
• python3 scripts/retention.py pr-states.json (dry run) prints a plan and changes nothing; --apply on a cron, weekly. Zero WARN on stderr — a WARN means something it claims to purge was not purged.
• Run retention from /tmp → exit 1, not a green no-op. Your cron's WorkingDirectory (or --root=) is the difference between a retention and a claim.
• gh pr merge fails (negative proof). Release branch protected, force-push and deletion off.
• Dry run on an empty queue → QUEUE_EMPTY, nothing created.
• Dry run on one ticket, then immediate re-run → no duplicate.
• Every state your loop can emit has exactly one consumer. List them. Any orphan = future graveyard.

Scope

This skill ONLY: reads a prioritized queue over an authenticated read-only endpoint; grounds briefs by reading code read-only; opens draft PRs on one repo from a deterministic branch; runs lint/type/test/build before proposing; browser-tests preview deploys non-destructively, on a dedicated test account, against test data; proposes verdicts and fixes, always disclosed as agent-written; acknowledges work that actually happened; talks to the four endpoints you configured, and to nothing else.

This skill NEVER: merges, marks a PR ready, pushes to an integration or release branch, force-pushes, rewrites history; acks a run whose checks were red; touches a ticket a human hasn't prioritized; invents an anchor it could not verify; clicks a destructive or irreversible action during QA (scan, delete, invite, payment) or points QA at a production tenant or a personal profile; works around a CAPTCHA, bot check or rate limit — if a challenge appears, it stops and hands over to a human; passes its output off as a human review, or denies being automated if asked; copies a requester's name, email or any personal identifier into a brief, a payload, a PR or a screenshot; keeps QA screenshots past the PR's close, or 7 days; hides a failure behind a fake success.