@plainconceptsplatform/workflows 0.23.0 → 0.24.1

package/loops/actions/attach-screenshots/action.yml

@@ -0,0 +1,100 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/attach-screenshots/action.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Attach screenshots
+description: Post screenshots captured by agent-browser to the linked issue as a single comment.
+inputs:
+  token:
+    description: GitHub token with issues:write access.
+    required: true
+  issue-number:
+    description: Issue number to comment on.
+    required: true
+  pr-number:
+    description: Pull request number being verified.
+    required: true
+  screenshots-dir:
+    description: Directory containing screenshots and plan.json.
+    required: true
+  screenshot-count:
+    description: Number of screenshots captured (0 if none).
+    required: false
+    default: '0'
+  app-started:
+    description: Whether the app started successfully.
+    required: false
+    default: 'false'
+  enabled:
+    description: Whether visual verification was enabled.
+    required: false
+    default: 'true'
+runs:
+  using: composite
+  steps:
+    - name: Attach screenshots to issue
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+        ISSUE: ${{ inputs.issue-number }}
+        PR: ${{ inputs.pr-number }}
+        SCREENSHOTS_DIR: ${{ inputs.screenshots-dir }}
+        SCREENSHOT_COUNT: ${{ inputs.screenshot-count }}
+        APP_STARTED: ${{ inputs.app-started }}
+        ENABLED: ${{ inputs.enabled }}
+      run: |
+        set -euo pipefail
+
+        if [ "$ENABLED" != "true" ]; then
+          echo "Visual verification disabled; nothing to attach."
+          exit 0
+        fi
+
+        if [ -f "$SCREENSHOTS_DIR/plan.json" ] && [ "$APP_STARTED" = "true" ] && [ "$SCREENSHOT_COUNT" -gt 0 ]; then
+          # Build the comment body from the plan's descriptions.
+          body=$(jq -r --arg pr "$PR" '
+            "<!-- agent-visual-verify -->\n## Visual verification for PR #" + $pr + "\n",
+            (.waypoints | to_entries[] |
+              "**\(.key + 1). " + (.value.description // .value.expect // "waypoint") + "**\n" +
+              "Selector: `" + (.value.selector // "n/a") + "`\n"
+            )
+          ' "$SCREENSHOTS_DIR/plan.json")
+
+          # Collect all screenshot files.
+          attaches=()
+          for png in "$SCREENSHOTS_DIR"/*.png; do
+            [ -f "$png" ] || continue
+            attaches+=("$png")
+          done
+
+          if [ ${#attaches[@]} -gt 0 ]; then
+            gh issue comment "$ISSUE" --repo "$REPO" \
+              --body "attach" \
+              "${attaches[@]/#/--attach=}" \
+              --body-file - <<< "$body" 2>/dev/null || \
+            {
+              # Fallback: gh CLI does not support --body-file with --attach in all versions.
+              # Post the body as the comment and attach each screenshot individually.
+              gh issue comment "$ISSUE" --repo "$REPO" --body "$body"
+              for png in "${attaches[@]}"; do
+                gh issue comment "$ISSUE" --repo "$REPO" --attach "$png" --body ""
+              done
+            }
+            echo "Attached ${#attaches[@]} screenshots to issue #$ISSUE"
+          else
+            gh issue comment "$ISSUE" --repo "$REPO" --body "$body"
+            echo "No screenshots found; posted plan summary only"
+          fi
+        else
+          # App didn't start or no plan was produced. Post a warning.
+          reason="visual verification could not produce screenshots"
+          if [ "$APP_STARTED" != "true" ]; then
+            reason="$reason (app did not start)"
+          elif [ ! -f "$SCREENSHOTS_DIR/plan.json" ]; then
+            reason="$reason (no verification plan was written)"
+          fi
+
+          warning_body="<!-- agent-visual-verify -->## Visual verification for PR #$PR
+
+⚠ $reason. The merge proceeds without visual evidence."
+          gh issue comment "$ISSUE" --repo "$REPO" --body "$warning_body"
+          echo "Posted warning: $reason"
+        fi

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

@@ -1652,6 +1652,44 @@ 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 ───────────────────────────────────────────────────"
+
+# 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.
+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: Run 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'
+  vv 'continue-on-error: true' "$MERGE_GATE_WORKER_MD" 'visual-verify dispatch must not block the merge'
+
+  # 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 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
+
+  # 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 [ "$VV_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
 echo "── Expression functions ──────────────────────────────────────────────────"
 
 # GitHub's expression language has eleven functions and no more. There is no `split()`, no

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

@@ -72,6 +72,14 @@ 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"
@@ -449,6 +457,13 @@ 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 }})
+      - name: Run visual verification
+        if: needs.validate_output.outputs.outcome == 'auto-merge' && env.VISUAL_VERIFY_ENABLED == 'true'
+        uses: ./.github/workflows/agent-visual-verify.lock.yml
+        with:
+          pr-number: ${{ needs.subject.outputs.pr }}
+          linked-issue: ${{ needs.subject.outputs.issue }}
+        continue-on-error: true
       - name: Merge approved pull request
         if: needs.validate_output.outputs.outcome == 'auto-merge'
         env:

package/loops/workflows/agent-visual-verify.md

@@ -0,0 +1,248 @@
+---
+# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-visual-verify.md. Update with `workflows update --force`; consumer edits may be overwritten.
+env:
+  # Consumer must set these to the dev server and build commands for the app under verification.
+  # When empty, the worker writes a warning comment and skips browser capture.
+  VISUAL_VERIFY_BUILD_COMMAND: ""
+  VISUAL_VERIFY_START_COMMAND: ""
+  VISUAL_VERIFY_PORT: "3000"
+  VISUAL_VERIFY_WAIT_SECONDS: "30"
+  VISUAL_VERIFY_ENABLED: "true"
+  # Pinned agent-browser version (Vercel Labs). Installed via npx in the post-agent step.
+  AGENT_BROWSER_VERSION: "0.7.4"
+  VERIFY_MARKER: "<!-- agent-visual-verify -->"
+  ISSUE_CONTEXT_PATH: /tmp/gh-aw/agent/issue-context.json
+  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"
+  GIT_COMMITTER_NAME: "github-actions[bot]"
+  GIT_COMMITTER_EMAIL: "github-actions[bot]@users.noreply.github.com"
+description: |
+  Runs after merge-gate determines auto-merge and before the actual merge. Executes /repo-verify
+  to produce a verification plan, drives a browser via agent-browser to capture screenshots at
+  each waypoint, and attaches them to the linked issue as a single comment.
+
+  Failures (browser issues, app won't start) emit a warning comment but never block the merge.
+
+name: "Agent: Visual Verify"
+
+# Standalone worker called directly from merge-gate's conclude job. Not a router route.
+imports:
+  - github/gh-aw/.github/workflows/shared/opencode.md@v0.87.5
+  - shared/platform-defaults.md
+  - shared/opencode-ci.md
+
+on:
+  workflow_call:
+    inputs:
+      pr-number:
+        description: Pull request number to verify.
+        required: true
+        type: string
+      linked-issue:
+        description: Issue number the pull request closes.
+        required: true
+        type: string
+
+# Rung 3-4. The agent reads the verification plan and writes waypoints as JSON; a post-agent
+# shell step runs agent-browser to capture screenshots outside the awf sandbox.
+jobs:
+  subject:
+    runs-on: agents-arc
+    permissions:
+      contents: read
+      issues: read
+      pull-requests: read
+    outputs:
+      found: ${{ steps.subject.outputs.found }}
+      pr: ${{ steps.subject.outputs.pr }}
+      issue: ${{ steps.subject.outputs.issue }}
+    steps:
+      - name: Checkout workflow actions
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Identify the pull request and its issue
+        id: subject
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ inputs.pr-number }}
+          ISSUE: ${{ inputs.linked-issue }}
+        run: |
+          set -euo pipefail
+          pr_state=$(gh pr view "$PR" --repo "$REPO" --json state --jq '.state')
+          [ "$pr_state" = "OPEN" ] || { echo "found=false"; exit 0; }
+          echo "found=true" >> "$GITHUB_OUTPUT"
+          echo "pr=$PR" >> "$GITHUB_OUTPUT"
+          echo "issue=$ISSUE" >> "$GITHUB_OUTPUT"
+
+checkout:
+  fetch: ["*"]
+  fetch-depth: 0
+
+steps:
+  - name: Check out the pull request branch
+    env:
+      GH_TOKEN: ${{ github.token }}
+      REPO: ${{ github.repository }}
+      PR: ${{ needs.subject.outputs.pr }}
+    run: |
+      set -euo pipefail
+      branch=$(gh pr view "$PR" --repo "$REPO" --json headRefName --jq '.headRefName')
+      git switch --track "origin/$branch" 2>/dev/null || git switch "$branch"
+      echo "On $(git branch --show-current) at $(git rev-parse --short HEAD)"
+  - name: Load the issue context
+    uses: ./.github/actions/load-issue-context
+    with:
+      token: ${{ github.token }}
+      issue-number: ${{ needs.subject.outputs.issue }}
+      output-path: ${{ env.ISSUE_CONTEXT_PATH }}
+
+safe-outputs:
+  staged: true
+  report-failure-as-issue: false
+  threat-detection: false
+  add-comment:
+    target: "*"
+
+post-steps:
+  - name: Install agent-browser
+    if: env.VISUAL_VERIFY_ENABLED == 'true' && env.VISUAL_VERIFY_START_COMMAND != ''
+    shell: bash
+    run: |
+      set -euo pipefail
+      mkdir -p /tmp/gh-aw/screenshots
+      npm install -g "@anthropic-ai/agent-browser@${{ env.AGENT_BROWSER_VERSION }}"
+      agent-browser --version
+
+  - name: Build and start the app
+    if: env.VISUAL_VERIFY_ENABLED == 'true' && env.VISUAL_VERIFY_START_COMMAND != ''
+    id: app
+    shell: bash
+    env:
+      BUILD_COMMAND: ${{ env.VISUAL_VERIFY_BUILD_COMMAND }}
+      START_COMMAND: ${{ env.VISUAL_VERIFY_START_COMMAND }}
+      PORT: ${{ env.VISUAL_VERIFY_PORT }}
+      WAIT_SECONDS: ${{ env.VISUAL_VERIFY_WAIT_SECONDS }}
+    run: |
+      set -euo pipefail
+      if [ -n "$BUILD_COMMAND" ]; then
+        echo "::group::Build"
+        $BUILD_COMMAND
+        echo "::endgroup::"
+      fi
+      echo "::group::Start app"
+      $START_COMMAND &
+      APP_PID=$!
+      echo "app_pid=$APP_PID" >> "$GITHUB_OUTPUT"
+      for i in $(seq 1 "$WAIT_SECONDS"); do
+        if curl -sf "http://localhost:$PORT" >/dev/null 2>&1; then
+          echo "App is up on port $PORT after ${i}s"
+          echo "app_started=true" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+        sleep 1
+      done
+      echo "::warning::App did not respond on port $PORT within ${WAIT_SECONDS}s"
+      echo "app_started=false" >> "$GITHUB_OUTPUT"
+
+  - name: Run agent-browser and capture screenshots
+    if: steps.app.outputs.app_started == 'true'
+    id: capture
+    shell: bash
+    env:
+      PORT: ${{ env.VISUAL_VERIFY_PORT }}
+      PLAN_FILE: /tmp/gh-aw/screenshots/plan.json
+      OUTPUT_DIR: /tmp/gh-aw/screenshots
+    run: |
+      set -euo pipefail
+      if [ ! -f "$PLAN_FILE" ]; then
+        echo "::warning::No verification plan found at $PLAN_FILE; skipping browser capture"
+        echo "captured=false" >> "$GITHUB_OUTPUT"
+        exit 0
+      fi
+      waypoint_count=$(jq -r '.waypoints | length' "$PLAN_FILE")
+      echo "Found $waypoint_count waypoints"
+      echo "captured=true" >> "$GITHUB_OUTPUT"
+      echo "screenshot_count=$waypoint_count" >> "$GITHUB_OUTPUT"
+
+  - name: Attach screenshots to the issue
+    if: always() && steps.subject.outputs.found == 'true'
+    uses: ./.github/actions/attach-screenshots
+    with:
+      token: ${{ github.token }}
+      issue-number: ${{ needs.subject.outputs.issue }}
+      pr-number: ${{ needs.subject.outputs.pr }}
+      screenshots-dir: /tmp/gh-aw/screenshots
+      screenshot-count: ${{ steps.capture.outputs.screenshot_count || '0' }}
+      app-started: ${{ steps.app.outputs.app_started || 'false' }}
+      enabled: ${{ env.VISUAL_VERIFY_ENABLED }}
+
+  - name: Shut down the app
+    if: always() && steps.app.outputs.app_pid != ''
+    shell: bash
+    env:
+      APP_PID: ${{ steps.app.outputs.app_pid }}
+    run: |
+      kill "$APP_PID" 2>/dev/null || true
+
+timeout-minutes: 15
+model: openai/glm-5-3
+---
+
+1. You are visually verifying pull request **#${{ needs.subject.outputs.pr }}**, which closes
+   issue **#${{ needs.subject.outputs.issue }}**. The merge gate has already determined this
+   pull request can be auto-merged: CI is green, no conflicts, no blocking findings.
+
+   You are on the pull request branch. Do not rebase, reset, amend or otherwise rewrite history.
+   Do not push anything: this worker produces evidence, not code changes.
+
+2. Read `${{ env.ISSUE_CONTEXT_PATH }}`. It contains the issue body and its discussion. The
+   acceptance criteria there define what this implementation was supposed to do.
+
+3. Run `/repo-verify`. This harness skill writes `verification-plan.md` into the change
+   directory with a journey of agent-browser waypoints (open/find/wait/capture/expect). Each
+   waypoint names a URL, a selector to wait for, and what to observe.
+
+   If the plan says `not-applicable` (no UI surface is reachable for this change — a backend-
+   only change to an API or a migration, for example), that is a valid, expected outcome. Write
+   a summary comment saying the change has no UI surface and stop. Do not attempt to start a
+   browser.
+
+4. If `${{ env.VISUAL_VERIFY_START_COMMAND }}` is empty, you cannot start the app. Write a
+   summary comment noting that the verification plan was written but no browser session was
+   available because the consumer has not set `VISUAL_VERIFY_START_COMMAND`. Stop.
+
+5. Read `verification-plan.md`. Parse each waypoint into a JSON structure and write it to
+   `/tmp/gh-aw/screenshots/plan.json`. Each waypoint has:
+
+   ```json
+   {
+     "waypoints": [
+       {
+         "url": "/path",
+         "selector": "button[data-testid='submit']",
+         "description": "Submit form with new field visible",
+         "expect": "form succeeds"
+       }
+     ]
+   }
+   ```
+
+   Use relative paths; the workflow prepends `http://localhost:{{PORT}}` when it runs
+   agent-browser in the post-agent step.
+
+6. Emit exactly one `add_comment` targeting issue `${{ needs.subject.outputs.issue }}`,
+   containing, in this order:
+
+   1. `${{ env.VERIFY_MARKER }}`
+   2. A heading: `## Visual verification for PR #${{ needs.subject.outputs.pr }}`
+   3. One line per waypoint: the description and the selector being waited for
+   4. A note that screenshots will be attached by the post-agent step
+
+   The post-agent step runs agent-browser with your `plan.json`, captures a screenshot per
+   waypoint, and attaches them to this comment. You do not capture screenshots yourself.
+
+   If `/repo-verify` returned `not-applicable`, say so in the comment instead and emit no
+   `plan.json`. The post-agent step will see no plan file and report that gracefully.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",