@plainconceptsplatform/workflows 1.0.14 → 1.1.1

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

@@ -1,350 +0,0 @@
----
-# 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
-  # The gate job the top-level `if:` reads. gh-aw folds that `if:` into the generated
-  # activation job but gives activation no dependency on the job, so the reference resolves
-  # to '' and the clause is false -- the agent would never run.
-  needs: [subject]
-
-# 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
-    timeout-minutes: 5
-    permissions:
-      contents: read
-      issues: read
-      pull-requests: read
-    outputs:
-      found: ${{ steps.subject.outputs.found }}
-      pr: ${{ steps.subject.outputs.pr }}
-      issue: ${{ steps.subject.outputs.issue }}
-      enabled: ${{ steps.config.outputs.enabled }}
-    steps:
-      - name: Checkout workflow actions
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      # Rung 4. A step can read the env: context; a job-level if: cannot. The enablement
-      # check therefore happens here and the agent gate reads the output -- a runnable
-      # snippet on an unconfigured repository burns the model otherwise.
-      - name: Read the visual-verify configuration
-        id: config
-        env:
-          ENABLED: ${{ env.VISUAL_VERIFY_ENABLED }}
-          START_COMMAND: ${{ env.VISUAL_VERIFY_START_COMMAND }}
-        run: |
-          set -euo pipefail
-          if [ "$ENABLED" = "true" ] && [ -n "$START_COMMAND" ]; then
-            echo "enabled=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "enabled=false" >> "$GITHUB_OUTPUT"
-            echo "::notice::visual verification is not configured (VISUAL_VERIFY_ENABLED=$ENABLED, start command ${START_COMMAND:-unset}); the agent will not run."
-          fi
-      - 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=$(gh pr view "$PR" --repo "$REPO" --json state,closingIssuesReferences,body)
-          [ "$(jq -r '.state' <<<"$pr")" = "OPEN" ] || { echo "found=false"; exit 0; }
-          echo "found=true" >> "$GITHUB_OUTPUT"
-          echo "pr=$PR" >> "$GITHUB_OUTPUT"
-          issue="$ISSUE"
-          if [ -z "$issue" ]; then
-            issue="$(jq -r '.closingIssuesReferences[0].number // empty' <<<"$pr")"
-          fi
-          if [ -z "$issue" ]; then
-            issue="$(jq -r '.body // ""' <<<"$pr" |
-              grep -oiE '(close[sd]?|fixe?[sd]?|resolve[sd]?) +#[0-9]+' |
-              grep -oE '[0-9]+' | head -n 1 || true)"
-          fi
-          echo "issue=$issue" >> "$GITHUB_OUTPUT"
-
-checkout:
-  fetch: ["*"]
-  fetch-depth: 0
-
-permissions: read-all
-
-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:
-  # Path A: the framework writes, so this worker does not stage and has no apply step in
-  # conclude. Staged here would mean the framework writes nothing and conclude would have to
-  # apply the comment, and conclude does not: the run would go green and the issue would
-  # never hear anything. That is staged-without-apply, the failure refine shipped once, not a
-  # property of staged itself. This worker stays on Path A and lets safe_outputs write.
-  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
-      # Unscoped: the package is Vercel Labs' agent-browser. The scoped
-      # @anthropic-ai/agent-browser does not exist on npm and 404s the install, which
-      # took down the agent job on the first run that ever reached this step.
-      npm install -g "agent-browser@${{ env.AGENT_BROWSER_VERSION }}"
-      # The npm package alone cannot drive a browser: the Chromium binary is a separate
-      # download, and a self-hosted Linux runner needs the system dependencies too.
-      # --with-deps is agent-browser's best effort but misses libraries on ubuntu-24.04.
-      chrome_dir=$(agent-browser path 2>/dev/null | grep -oE '/[^ ]+chrome[^ ]*' | head -1 || true)
-      if [ -n "$chrome_dir" ] && [ -d "$(dirname "$chrome_dir")/.." ]; then
-        ldd "$chrome_dir" 2>/dev/null | grep "not found" || true
-      fi
-      # Install the known missing Chromium dependencies on Debian/ubuntu runners.
-      # agent-browser install --with-deps may leave these out depending on the runner image.
-      sudo apt-get update -qq && sudo apt-get install -y --no-install-recommends \
-        libnss3 libatk1.0-0 libatk-bridge2.0-0 libdrm2 libgbm1 \
-        libasound2t64 libxkbcommon0 libcairo2 libpango-1.0-0 libxcomposite1 \
-        libxdamage1 libxfixes3 libxrandr2 2>/dev/null || true
-      agent-browser install --with-deps
-      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"
-      captured=0
-      i=0
-      # agent-browser uses Chromium which needs --no-sandbox on CI runners where
-      # there is no SYS_ADMIN capability. Set it once via the config file.
-      export AGENT_BROWSER_ARGS="${AGENT_BROWSER_ARGS:-} --no-sandbox"
-      while [ "$i" -lt "$waypoint_count" ]; do
-        i=$((i + 1))
-        url=$(jq -r ".waypoints[$((i - 1))].url" "$PLAN_FILE")
-        selector=$(jq -r ".waypoints[$((i - 1))].selector // empty" "$PLAN_FILE")
-        echo "Waypoint $i/$waypoint_count: $url (waiting for: ${selector:-nothing})"
-        # A failing waypoint must not lose the screenshots already taken: the count is
-        # reported and the run stays green, because evidence is what this worker produces.
-        if ! agent-browser open "http://localhost:$PORT$url"; then
-          echo "::warning::waypoint $i: could not open $url; skipping"
-          continue
-        fi
-        if [ -n "$selector" ]; then
-          agent-browser wait "$selector" || echo "::warning::waypoint $i: selector $selector did not appear; screenshotting anyway"
-        fi
-        agent-browser wait --load networkidle || true
-        if agent-browser screenshot "$OUTPUT_DIR/waypoint-$i.png" --full; then
-          captured=$((captured + 1))
-        else
-          echo "::warning::waypoint $i: screenshot failed"
-          # Diagnostic: show what's in the output dir and any browser errors
-          ls -la "$OUTPUT_DIR/" 2>/dev/null || true
-          echo "--- agent-browser debug ---"
-          agent-browser screenshot "$OUTPUT_DIR/debug-$i.png" --full 2>&1 || true
-        fi
-      done
-      echo "captured=$([ "$captured" -gt 0 ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
-      echo "screenshot_count=$captured" >> "$GITHUB_OUTPUT"
-
-  # The attach action reads the screenshots directory; on no capture it explains that
-  # instead (app never started, no plan, or every waypoint failed). `always()` because it
-  # must run even when the capture step above warned its way to the end.
-  - name: Attach screenshots to the issue
-    if: always() && env.VISUAL_VERIFY_ENABLED == 'true' && env.VISUAL_VERIFY_START_COMMAND != ''
-    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
-
-# `!failure()` because subject skips on an unconfigured repository and a closed pull
-# request: without a status function the implicit success() would let those skips look
-# like failures to every job that needs this one.
-if: needs.subject.outputs.found == 'true' && needs.subject.outputs.enabled == 'true' && !failure()
-
-timeout-minutes: 15
-
-engine:
-  id: opencode
-  version: "1.2.14"
-  env:
-    OPENAI_BASE_URL: https://forge.plainconcepts.com/v1
-
-model: openai/glm-5-2
-max-turns: 120
-max-turn-cache-misses: 3000
-max-ai-credits: 5000
----
-
-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.