@plainconceptsplatform/workflows 1.0.14 → 1.1.1

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -35,7 +35,7 @@ source "${HERE}/../classify-route/classify-route.sh"
 # Every worker route the package knows. The ones with a worker file here are installed; the
 # others must have no job in this router. Plumbing routes are in every router.
 ALL_WORKER_ROUTES=(refine implement triage apply-review merge-gate audit release)
-PLUMBING_ROUTES=(bot-approve audit-close cleanup-artifacts reconcile-bot-pr-runs housekeeping validate)
+PLUMBING_ROUTES=(bot-approve evidence audit-close cleanup-artifacts reconcile-bot-pr-runs housekeeping validate)
 
 worker_installed() {
   [ -f "${WORKFLOWS_DIR}/agent-$1.md" ]
@@ -78,7 +78,7 @@ route_field() {
     unset EVENT ACTION LABEL ISSUE_LABELS EVENT_ISSUE_NUMBER EVENT_PR_NUMBER \
       COMMENT_ON_PR COMMENT_SENDER_TYPE RUN_PR_NUMBER RUN_CONCLUSION RUN_ID \
       SCHEDULE OPERATION INPUT_ISSUE_NUMBER INPUT_PR_NUMBER INPUT_MODE \
-      INPUT_CI_CONCLUSION INPUT_CI_RUN_ID INPUT_TRIGGER_KIND
+      INPUT_CI_CONCLUSION INPUT_CI_RUN_ID INPUT_TRIGGER_KIND PR_MERGED EVIDENCE_ENABLED
 
     for assignment in "${assignments[@]}"; do
       key="${assignment%%=*}"
@@ -187,6 +187,14 @@ assert_route "a submitted review routes to apply-review" apply-review \
   EVENT=pull_request_review EVENT_PR_NUMBER=7
 assert_route "a pull_request_target routes to bot-approve" bot-approve \
   EVENT=pull_request_target ACTION=opened
+assert_route "a merged pull request routes to evidence" evidence \
+  EVENT=pull_request_target ACTION=closed PR_MERGED=true EVENT_PR_NUMBER=7
+assert "evidence carries the merged pull request" 7 \
+  "$(route_field pr-number EVENT=pull_request_target ACTION=closed PR_MERGED=true EVENT_PR_NUMBER=7)"
+assert_route "a pull request closed unmerged does not route to evidence" bot-approve \
+  EVENT=pull_request_target ACTION=closed PR_MERGED=false EVENT_PR_NUMBER=7
+assert_route "EVIDENCE_ENABLED=false turns the merge route off" none \
+  EVENT=pull_request_target ACTION=closed PR_MERGED=true EVENT_PR_NUMBER=7 EVIDENCE_ENABLED=false
 
 echo "── CI completion ─────────────────────────────────────────────────────────"
 assert_route "a failed App CI run on a pull request routes to merge-gate" merge-gate \
@@ -250,6 +258,14 @@ assert "implement dispatch forwards the attempt count" 2 \
   "$(route_field attempts EVENT=workflow_dispatch OPERATION=implement INPUT_ISSUE_NUMBER=42 INPUT_ATTEMPTS_SO_FAR=2)"
 assert_route "release dispatch needs no numbers" release \
   EVENT=workflow_dispatch OPERATION=release
+assert_route "evidence dispatch with a pull request routes to evidence" evidence \
+  EVENT=workflow_dispatch OPERATION=evidence INPUT_PR_NUMBER=7
+assert_route "evidence dispatch without a pull request routes nowhere" none \
+  EVENT=workflow_dispatch OPERATION=evidence INPUT_PR_NUMBER=
+assert_route "evidence dispatch runs even where the merge route is off" evidence \
+  EVENT=workflow_dispatch OPERATION=evidence INPUT_PR_NUMBER=7 EVIDENCE_ENABLED=false
+assert_route "the retired visual-verify operation routes nowhere" none \
+  EVENT=workflow_dispatch OPERATION=visual-verify INPUT_PR_NUMBER=7
 assert_route "reconcile-bot-pr-runs dispatch needs no numbers" reconcile-bot-pr-runs \
   EVENT=workflow_dispatch OPERATION=reconcile-bot-pr-runs
 assert_route "an unknown operation routes nowhere" none \
@@ -1667,60 +1683,59 @@ if worker_installed merge-gate; then
   if [ "$GATE_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
-echo "── Visual verify wiring ───────────────────────────────────────────────────"
+echo "── Evidence wiring ───────────────────────────────────────────────────────"
 
-# The merge-gate's conclude job dispatches agent-visual-verify before merging when the outcome
-# is auto-merge and VISUAL_VERIFY_ENABLED is true. Each of these is one line an edit could drop
-# with nothing going red: a missing dispatch step, a missing env var, or a missing worker file.
-# The guard against the original bug comes first: the call is a dispatch, never a step doing
-# `uses:` on a workflow file -- that resolves as a local action, dies with "Can't find
-# action.yml", and under continue-on-error every auto-merge shipped with zero screenshots
-# and nothing red.
-if worker_installed merge-gate; then
-  VV_OK=1
-
-  vv() {
-    grep -qE "$1" "$2" || { VV_OK=0; echo "FAIL: $3" >&2; }
-  }
-
-  # The dispatch step exists and runs only on auto-merge with the feature flag on.
-  vv 'name: Dispatch visual verification' "$MERGE_GATE_WORKER_MD" 'merge-gate has no visual-verify dispatch step'
-  vv "outcome == 'auto-merge'.*VISUAL_VERIFY_ENABLED == 'true'" "$MERGE_GATE_WORKER_MD" 'visual-verify dispatch has wrong guard'
-
-  # The shape that never worked: a step calling a reusable workflow file. Also reject the
-  # swallowed-failure form it shipped with.
-  vv 'operation=visual-verify' "$MERGE_GATE_WORKER_MD" 'the dispatch must target the router operation, not a nested file'
-  if grep -qE '^      - name:.*\n.*uses: \./\.github/workflows/agent-visual-verify' "$MERGE_GATE_WORKER_MD" 2>/dev/null \
-    || grep -A2 '^      - name:' "$MERGE_GATE_WORKER_MD" | grep -q 'uses: \./\.github/workflows/'; then
-    VV_OK=0
-    echo "FAIL: a step still uses: a workflow file; the runner resolves it as a local action and it cannot work" >&2
-  fi
-
-  # The env vars the worker needs.
-  vv 'VISUAL_VERIFY_ENABLED:' "$MERGE_GATE_WORKER_MD" 'merge-gate missing VISUAL_VERIFY_ENABLED env var'
-  vv 'VISUAL_VERIFY_START_COMMAND:' "$MERGE_GATE_WORKER_MD" 'merge-gate missing VISUAL_VERIFY_START_COMMAND env var'
-
-  # The worker gates its agent on its own configuration, so an unconfigured repository
-  # runs no model: the subject job exposes it, the top-level if: reads it.
-  vv 'enabled: ' "${WORKFLOWS_DIR}/agent-visual-verify.md" 'visual-verify subject does not expose the enabled output'
-  vv "outputs.enabled == 'true'" "${WORKFLOWS_DIR}/agent-visual-verify.md" 'visual-verify agent gate does not read the enabled output'
-
-  # The worker file exists.
-  VV_WORKER_MD="${WORKFLOWS_DIR}/agent-visual-verify.md"
-  if [ ! -f "$VV_WORKER_MD" ]; then
-    VV_OK=0
-    echo "FAIL: agent-visual-verify.md does not exist" >&2
-  fi
+# A merged pull request's verification plan is replayed by evidence.yml, a plain workflow with no
+# model. The shape it replaced (agent-visual-verify) never produced one screenshot, and each check
+# below is one way it failed: dispatched from the merge gate it raced the merge, published with a
+# token `gh --attach` refuses, and would have run pull request code beside a write token.
+EVIDENCE_YML="${WORKFLOWS_DIR}/evidence.yml"
+EV_OK=1
+ev() {
+  grep -qE "$1" "$2" || { EV_OK=0; echo "FAIL: $3" >&2; }
+}
+ev_absent() {
+  if grep -qE "$1" "$2"; then EV_OK=0; echo "FAIL: $3" >&2; fi
+}
 
-  # The attach-screenshots action exists.
-  VV_ATTACH="${HERE}/../attach-screenshots/action.yml"
-  if [ ! -f "$VV_ATTACH" ]; then
-    VV_OK=0
-    echo "FAIL: attach-screenshots/action.yml does not exist" >&2
-  fi
+if [ ! -f "$EVIDENCE_YML" ]; then
+  EV_OK=0
+  echo "FAIL: evidence.yml does not exist" >&2
+else
+  ev 'uses: \./\.github/workflows/evidence\.yml' "$ROUTER_YML" 'the router does not call evidence.yml'
+  ev '^  EVIDENCE_ENABLED: ' "$ROUTER_YML" 'the router env does not declare EVIDENCE_ENABLED'
+  ev 'uses: \./\.github/actions/capture-evidence' "$EVIDENCE_YML" 'evidence.yml does not use the capture-evidence action'
+  if [ ! -f "${HERE}/../capture-evidence/action.yml" ] || [ ! -f "${HERE}/../capture-evidence/capture.mjs" ]; then
+    EV_OK=0
+    echo "FAIL: the capture-evidence action is incomplete" >&2
+  fi
+
+  # The capture job runs the pull request's code, so it holds no secret and no write.
+  capture_job="$(sed -n '/^  capture:/,/^  publish:/p' "$EVIDENCE_YML")"
+  if grep -qE 'secrets\.|contents: write|pull-requests: write|issues: write' <<<"$capture_job"; then
+    EV_OK=0
+    echo "FAIL: evidence.yml's capture job runs pull request code and must hold no secret and no write" >&2
+  fi
+  # The publish job writes, so it runs no repository code: no checkout and no local action.
+  publish_job="$(sed -n '/^  publish:/,$p' "$EVIDENCE_YML")"
+  if grep -qE 'actions/checkout|uses: \./' <<<"$publish_job"; then
+    EV_OK=0
+    echo "FAIL: evidence.yml's publish job holds a write token and must not check out or run repository code" >&2
+  fi
+  ev_absent 'secrets\.' "$EVIDENCE_YML" 'evidence.yml must need no secret; GITHUB_TOKEN is enough'
+  ev_absent 'gh (issue|pr) comment.*--attach' "$EVIDENCE_YML" 'gh --attach refuses installation tokens; publish through the evidence branch'
+fi
 
-  if [ "$VV_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+# The retired worker stays retired: nothing dispatches it and nothing waits for it.
+if worker_installed merge-gate; then
+  ev_absent 'operation=visual-verify|VISUAL_VERIFY_' "$MERGE_GATE_WORKER_MD" 'merge-gate still carries the retired visual-verify wiring'
 fi
+if [ -f "${WORKFLOWS_DIR}/agent-visual-verify.md" ]; then
+  EV_OK=0
+  echo "FAIL: agent-visual-verify.md was retired by evidence.yml and must not come back" >&2
+fi
+
+if [ "$EV_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 
 echo "── Expression functions ──────────────────────────────────────────────────"
 
@@ -2275,13 +2290,7 @@ for worker_md in "${WORKFLOWS_DIR}"/agent-*.md; do
     case " $allowed_pools " in *" $p "*) ;; *) ok=0 ;; esac
   done
   if ! echo "$got" | grep -qw "$AGENT_POOL"; then
-    # visual-verify gets its agent runs-on from a shared import, not from the .md file,
-    # so the pool check only sees the subject gate job on RunnerLandingZone.
-    if [ "$worker_name" = "agent-visual-verify" ] && echo "$got" | grep -qw "$PLUMBING_POOL"; then
-      :
-    else
-      ok=0
-    fi
+    ok=0
   fi
   if [ "$ok" -ne 1 ]; then
     POOL_OK=0
@@ -2289,10 +2298,18 @@ for worker_md in "${WORKFLOWS_DIR}"/agent-*.md; do
   fi
 done
 
+# The router's own jobs run on the agent fleet's per-run lease: `[agents-aw, "affinity-..."]`,
+# which pools_named reads as its first token. That is the shape the compile step rewrites every
+# worker lock to as well, so it is the router's pool, not a drift from agents-arc.
+AFFINITY_POOL="[agents-aw,"
 router_pools="$(pools_named "$ROUTER_YML" | tr '\n' ' ' | sed 's/ $//')"
-if ! echo "$router_pools" | grep -qw "$AGENT_POOL"; then
+router_ok=1
+for p in $router_pools; do
+  case " ${AGENT_POOL} ${PLUMBING_POOL} ${AFFINITY_POOL} " in *" $p "*) ;; *) router_ok=0 ;; esac
+done
+if [ -z "$router_pools" ] || [ "$router_ok" -ne 1 ]; then
   POOL_OK=0
-  echo "FAIL: the router names runner pool(s) '${router_pools}' but must name only '${AGENT_POOL}' and/or '${PLUMBING_POOL}' (with at least ${AGENT_POOL})" >&2
+  echo "FAIL: the router names runner pool(s) '${router_pools}' but must name only '${AFFINITY_POOL} affinity]', '${AGENT_POOL}' and/or '${PLUMBING_POOL}'" >&2
 fi
 
 # And the pool must not be reintroduced as a per-consumer value: that is the mechanism that let

package/loops/docs/diagrams.md

@@ -412,7 +412,8 @@ reads them next time.
 
 ## agent-release.md
 
-Manual dispatch only. The agent writes prose; a deterministic job does everything irreversible.
+Manual dispatch only. The agent writes prose; deterministic jobs do everything irreversible, and
+nothing reaches `main` except through a pull request.
 
 ```mermaid
 flowchart TD
@@ -420,26 +421,34 @@ flowchart TD
     relFacts("Facts (rung 3)<br/>Commit log since the last tag<br/>and the current version, to disk") --> relAgent
     relAgent("Agent (rung 5)<br/>Categorise by conventional-commit<br/>prefix, write release-notes.md.<br/>The only judgement in this route") --> relNoop
     relNoop("noop<br/>the agent writes a file,<br/>not a GitHub object") --> relConclude
-    relConclude["conclude (rung 6)<br/>Bump: BREAKING is major,<br/>feat is minor, else patch"] --> relPush
-    relPush("Commit, tag, push,<br/>create the GitHub Release") --> relDone
+    relConclude["conclude (rung 6)<br/>Bump: BREAKING is major,<br/>feat is minor, else patch"] --> relPr
+    relPr("App token: push release/vX.Y.Z,<br/>open chore(release) PR,<br/>enable squash auto-merge") --> relMerge
+    relMerge{"CI green and<br/>auto-merge allowed?"}
+    relMerge -->|yes| relTag
+    relMerge -.->|auto-merge disabled| relOpen
+    relTag("release-tag.yml on push to main<br/>GITHUB_TOKEN: tag vX.Y.Z,<br/>Release with the PR body as notes") --> relDone
     relConclude -.->|fails| relFail
-    relDone(("Released<br/>tag and Release published"))
-    relFail(("Failed<br/>no tag created, nothing partial"))
+    relOpen(("PR left open<br/>warning names the fix"))
+    relDone(("Released<br/>tag and Release published,<br/>no tag-triggered workflow fired"))
+    relFail(("Failed<br/>no branch, nothing partial"))
 
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
     classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
     classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
     classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class relStart start
-    class relFacts,relAgent,relNoop,relPush action
-    class relConclude decision
+    class relFacts,relAgent,relNoop,relPr,relTag action
+    class relConclude,relMerge decision
     class relFail failure
+    class relOpen idle
     class relDone success
 ```
 
 The version bump, the tag and the Release are deterministic on purpose. The agent's only output is
-a file on disk, so a confused model cannot publish a release.
+a file on disk, so a confused model cannot publish a release. The tag and the Release use
+`GITHUB_TOKEN` so that a consumer deploying on `v*` tags does not deploy because a release was cut.
 
 
 ---
@@ -613,49 +622,41 @@ earlier versions of them passed against a deliberately broken guard and were rew
 
 ---
 
-## agent-visual-verify.md
+## evidence.yml
 
-Runs after merge-gate decides to auto-merge, before the actual merge, and produces **evidence, not
-code changes**: it writes a verification plan, drives a real browser through the app, and attaches
-screenshots to the linked issue. It is called directly by merge-gate's `conclude` job, so it is not
-a router route. Failures never block the merge a browser that will not start or an app that never
-comes up emits a warning comment and the merge proceeds.
+Archives what a merged pull request looks like. Not an agent: the plan was written by the agent that
+implemented the change (`pc-repo-verify`), and this replays it. The router calls it when a pull
+request merges, and `operation=evidence` runs it by hand. Nothing waits on it and nothing reads it.
+The capture job runs the pull request's code with a read-only token; only the publish job writes,
+and it runs no repository code.
 
 ```mermaid
 flowchart TD
-    vvStart("merge-gate conclude<br/>calls agent-visual-verify") --> vvSubject
-    vvSubject["subject (rung 4)<br/>PR open? linked issue found?"] --> vvConfig
-    vvConfig{"config (rung 4)<br/>VISUAL_VERIFY_ENABLED and<br/>START_COMMAND set?"}
-    vvConfig -.->|"no"| vvIdle
-    vvConfig -->|"yes"| vvFacts
-    vvFacts["Facts (rung 3)<br/>PR branch checked out,<br/>issue context loaded"] --> vvPlan
-    vvPlan{"/repo-verify (rung 5)<br/>reachable UI surface?"}
-    vvPlan -.->|"not-applicable"| vvNoUi
-    vvPlan -->|"yes"| vvStartCmd
-    vvStartCmd{"start command set?<br/>VISUAL_VERIFY_START_COMMAND"}
-    vvStartCmd -.->|"empty"| vvNoStart
-    vvStartCmd -->|"yes"| vvAgent
-    vvAgent["Agent (rung 5)<br/>parse waypoints into plan.json,<br/>one add_comment on the issue"] --> vvCapture
-    vvCapture["post-agent (rung 6)<br/>build + start the app,<br/>agent-browser captures per waypoint"] --> vvAttach
-    vvAttach["attach-screenshots (rung 6)<br/>always(), subject found + enabled"] --> vvShutdown
-    vvShutdown["shut down the app"] --> vvDone
-    vvCapture -.->|"app never started,<br/>no plan, or all waypoints failed"| vvPartial
-    vvDone(("Verified<br/>screenshots attached,<br/>merge proceeds"))
-    vvPartial(("Attach what exists<br/>no-capture explanation,<br/>run stays green"))
-    vvNoUi(("No UI surface<br/>summary comment, stop"))
-    vvNoStart(("Not configured<br/>warning comment, stop"))
-    vvIdle(("Idle<br/>unconfigured or PR not open"))
+    evStart("router: pull request merged<br/>or operation=evidence") --> evPlans
+    evPlans{"verification-plan.md<br/>in the pull request?"}
+    evPlans -.->|"no"| evIdle
+    evPlans -->|"yes"| evInspect
+    evInspect{"capture-evidence inspect<br/>a replayable journey?"}
+    evInspect -.->|"not-applicable or prose"| evIdle
+    evInspect -->|"yes"| evApp
+    evApp["capture (read-only)<br/>check out the head,<br/>install, start the app"] --> evUp
+    evUp{"app answers at<br/>the plan's url?"}
+    evUp -->|"yes"| evReplay
+    evUp -.->|"no, after the timeout"| evUnreached
+    evReplay["replay each waypoint<br/>in headless Chromium,<br/>one JPEG per waypoint"] --> evPublish
+    evUnreached["record why nothing<br/>was captured"] --> evPublish
+    evPublish["publish (GITHUB_TOKEN)<br/>commit to the orphan evidence branch,<br/>upsert one comment"] --> evDone
+    evDone(("Archived<br/>on the pull request"))
+    evIdle(("Nothing to capture"))
 
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
     classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
     classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
-    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
-    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef idle fill:#f4f4f6,stroke:#5b5b66,stroke-width:2px,color:#2b2b33
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
-    class vvStart start
-    class vvSubject,vvFacts,vvCapture,vvAttach,vvShutdown action
-    class vvConfig,vvPlan,vvStartCmd decision
-    class vvIdle idle
-    class vvNoUi,vvNoStart,vvPartial failure
-    class vvDone success
+    class evStart start
+    class evApp,evReplay,evUnreached,evPublish action
+    class evPlans,evInspect,evUp decision
+    class evIdle idle
+    class evDone success
 ```

package/loops/workflows/agent-merge-gate.md

@@ -72,14 +72,6 @@ env:
   # one unusable report can keep every other bot pull request in the repository waiting.
   PARK_AT_UNUSABLE_OUTPUT: "2"
   ISSUE_CONTEXT_PATH: /tmp/gh-aw/agent/issue-context.json
-  # Visual verification runs after auto-merge is decided and before the merge itself. The worker
-  # runs /repo-verify, drives a browser via agent-browser, and attaches screenshots to the linked
-  # issue. Failures never block the merge. Consumers opt out by setting this to "false".
-  VISUAL_VERIFY_ENABLED: "true"
-  VISUAL_VERIFY_BUILD_COMMAND: ""
-  VISUAL_VERIFY_START_COMMAND: ""
-  VISUAL_VERIFY_PORT: "3000"
-  VISUAL_VERIFY_WAIT_SECONDS: "30"
   GH_AW_ALLOWED_BOTS: "platform-devbox[bot],github-actions[bot]"
   GIT_AUTHOR_NAME: "github-actions[bot]"
   GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
@@ -382,17 +374,6 @@ jobs:
           protected-hit: ${{ needs.protected_changes.outputs.requires_review }}
           owner-hit: ${{ needs.protected_changes.outputs.owner_hit }}
           confidence-threshold: ${{ env.CONFIDENCE_THRESHOLD }}
-  # The pre-merge screenshot pass is dispatched rather than nested. A nested
-  # workflow_call job cannot live downstream of this worker's agent: the compiler hoists
-  # prompt-referenced jobs into the agent's needs, and any call job depending on
-  # validate_output closes a cycle through agent (measured: the graph refuses to compile).
-  # The first version of this wiring was a step doing `uses:` on the worker's lock file,
-  # which is not a call at all -- the runner resolved it as a local action and died with
-  # "Can't find action.yml" under continue-on-error, so every auto-merge since the feature
-  # shipped merged with zero screenshots and nothing red. This dispatches the router's
-  # existing visual-verify operation (the dispatch-triage pattern) before the merge below.
-  # The merge pins the head SHA with --match-head-commit, and visual-verify re-reads the
-  # pull request itself, so the called worker owns its own subject validation.
   conclude:
     needs: [activation, subject, protected_changes, agent, safe_outputs, validate_output]
     # `protected_changes.result == 'success'` is stated rather than relied on. GitHub skips a job
@@ -411,8 +392,6 @@ jobs:
       contents: write
       issues: write
       pull-requests: write
-      # dispatching the visual-verify pass through the router's workflow_dispatch
-      actions: write
     steps:
       - name: Create bot token
         id: app-token
@@ -474,30 +453,6 @@ jobs:
             ```
 
             Findings and verification on the linked issue: #${{ needs.subject.outputs.issue }}. [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
-      # Screenshots before the merge. The visual-verify pass is dispatched through the
-      # router (see the visual_verify note above conclude) and cannot be awaited from here;
-      # the merge below pins the head SHA with --match-head-commit, so a screenshot run on
-      # the same head describes exactly what is being merged. GITHUB_TOKEN: a dispatch
-      # raises one workflow_run-free event, and the called worker re-owns its subject.
-      - name: Dispatch visual verification
-        if: needs.validate_output.outputs.outcome == 'auto-merge' && env.VISUAL_VERIFY_ENABLED == 'true'
-        env:
-          GH_TOKEN: ${{ github.token }}
-          REPO: ${{ github.repository }}
-          REF: ${{ github.event.repository.default_branch }}
-          PR: ${{ needs.subject.outputs.pr }}
-          ISSUE: ${{ needs.subject.outputs.issue }}
-        run: |
-          set -euo pipefail
-          if gh workflow run work-router.yml --repo "$REPO" --ref "$REF" \
-            -f operation=visual-verify -f pr-number="$PR" -f issue-number="$ISSUE"; then
-            echo "Visual verification dispatched for PR #$PR."
-          else
-            echo "::warning::could not dispatch visual verification for PR #$PR; merging without screenshots."
-          fi
-      # The visual verification pass is the visual_verify dispatch above. It runs as its own
-      # worker because a step cannot call a reusable workflow, and the merge below may land
-      # while the capture is still running -- the head SHA pin keeps the two honest.
       - name: Merge approved pull request
         if: needs.validate_output.outputs.outcome == 'auto-merge'
         env:

package/loops/workflows/agent-release.md

@@ -6,9 +6,10 @@ env:
   GIT_COMMITTER_NAME: "github-actions[bot]"
   GIT_COMMITTER_EMAIL: "github-actions[bot]@users.noreply.github.com"
 description: |
-  Generates release notes from the commit log and creates a tagged GitHub Release.
+  Generates release notes from the commit log and opens a release pull request.
   The agent writes human-readable release notes; every other step (version bump,
-  commit, tag, push, release creation) is deterministic.
+  release branch, pull request, auto-merge) is deterministic. release-tag.yml tags
+  the merged commit and publishes the GitHub Release.
 
   Router-only worker: triggered exclusively via workflow_call from work-router.yml.
   Contract input: version-bump(patch|minor|major|auto).
@@ -92,6 +93,15 @@ safe-outputs:
 timeout-minutes: 30
 
 jobs:
+  # The release is a pull request, not a push. A repository whose `main` requires pull
+  # requests and status checks cannot accept a direct push, and a push with GITHUB_TOKEN would
+  # not start CI on the branch either, so the required checks would never report. The App token
+  # does both: its push and its pull request fire workflows, so CI runs and auto-merge can land
+  # the bump once it is green.
+  #
+  # No tag and no GitHub Release here. `release-tag.yml` creates both after the merge, with
+  # GITHUB_TOKEN on purpose: a consumer deploying to production on `v*` tags must not start
+  # that deploy from a release (see the comment at the top of release-tag.yml).
   conclude:
     needs: [activation, agent, safe_outputs]
     if: >
@@ -100,7 +110,7 @@ jobs:
       needs.safe_outputs.result == 'success'
     runs-on: agents-arc
     permissions:
-      contents: write
+      contents: read
     steps:
       - name: Download agent output artifact
         id: download-agent-output
@@ -110,10 +120,16 @@ jobs:
           pattern: "{${{ needs.activation.outputs.artifact_prefix }}agent,${{ needs.activation.outputs.artifact_prefix }}agent-output-fallback}"
           merge-multiple: true
           path: /tmp/gh-aw/
+      - name: Create bot token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          token: ${{ github.token }}
+          token: ${{ steps.app-token.outputs.token }}
           fetch-depth: 0
       - name: Read release notes and determine version
         id: release
@@ -173,32 +189,72 @@ jobs:
               }
             }
           "
-      - name: Commit, tag, and push
+      - name: Commit and push the release branch
+        id: branch
         env:
           NEW_VERSION: ${{ steps.release.outputs.new_version }}
-          GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
+          base=$(git rev-parse --abbrev-ref HEAD)
+          branch="release/v${NEW_VERSION}"
+          # A second dispatch before the first release PR merged computes the same version from
+          # the same package.json. Two PRs bumping to one version would tag it twice.
+          if git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
+            echo "::error::Branch $branch already exists: a release PR for v${NEW_VERSION} is open or was abandoned. Merge or close it, delete the branch, then dispatch again."
+            exit 1
+          fi
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
+          git switch -c "$branch"
           git add package.json
           [ -f cli/package.json ] && git add cli/package.json
           git commit -m "chore(release): v${NEW_VERSION}"
-          git tag "v${NEW_VERSION}"
-          git push
-          git push --tags
-          echo "Tagged v${NEW_VERSION} and pushed."
-      - name: Create GitHub Release
+          git push origin "$branch"
+          echo "base=$base" >> "$GITHUB_OUTPUT"
+          echo "branch=$branch" >> "$GITHUB_OUTPUT"
+          echo "Pushed $branch (base $base)."
+      # The body is what release-tag.yml publishes as the GitHub Release notes. The marker is how
+      # it tells this PR from any other PR associated with the merge commit.
+      - name: Open the release pull request
+        id: pr
         env:
           NEW_VERSION: ${{ steps.release.outputs.new_version }}
-          GH_TOKEN: ${{ github.token }}
+          BASE: ${{ steps.branch.outputs.base }}
+          BRANCH: ${{ steps.branch.outputs.branch }}
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
         run: |
           set -euo pipefail
-          gh release create "v${NEW_VERSION}" \
+          {
+            echo "<!-- release:v${NEW_VERSION} -->"
+            cat /tmp/release-notes.md
+          } > /tmp/release-pr-body.md
+          url=$(gh pr create \
             --repo "$GITHUB_REPOSITORY" \
-            --title "v${NEW_VERSION}" \
-            --notes-file /tmp/release-notes.md
-          echo "GitHub Release v${NEW_VERSION} created."
+            --base "$BASE" \
+            --head "$BRANCH" \
+            --title "chore(release): v${NEW_VERSION}" \
+            --body-file /tmp/release-pr-body.md)
+          echo "url=$url" >> "$GITHUB_OUTPUT"
+          echo "Opened $url"
+      # Squash keeps the PR title as the commit subject, which is what release-tag.yml matches.
+      - name: Enable auto-merge
+        env:
+          NEW_VERSION: ${{ steps.release.outputs.new_version }}
+          PR_URL: ${{ steps.pr.outputs.url }}
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          set -euo pipefail
+          if gh pr merge "$PR_URL" --auto --squash --subject "chore(release): v${NEW_VERSION}" 2>/tmp/auto-merge.err; then
+            echo "Auto-merge enabled on $PR_URL; v${NEW_VERSION} is tagged once it merges."
+            exit 0
+          fi
+          cat /tmp/auto-merge.err >&2
+          allowed=$(gh api "repos/$GITHUB_REPOSITORY" --jq '.allow_auto_merge' 2>/dev/null || echo "unknown")
+          if [ "$allowed" = "false" ]; then
+            echo "::warning::Auto-merge is disabled on $GITHUB_REPOSITORY, so the release PR $PR_URL stays open. Merge it by hand (squash), or enable it once: gh api -X PATCH repos/$GITHUB_REPOSITORY -F allow_auto_merge=true"
+          else
+            echo "::warning::Could not enable auto-merge on $PR_URL; it stays open. Merge it by hand (squash) to tag v${NEW_VERSION}."
+          fi
 
   incomplete:
     needs: [agent, safe_outputs]
@@ -241,4 +297,4 @@ jobs:
    - Keep it concise and factual. Do not invent changes that are not in the log.
 
 5. Call `noop` and stop. The deterministic `conclude` job reads the notes you wrote
-   and handles version bumping, tagging, and release creation.
+   and handles the version bump and the release pull request.