@plainconceptsplatform/workflows 0.28.0 → 0.28.2

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

@@ -1657,6 +1657,10 @@ 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.
+# 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
 
@@ -1665,14 +1669,27 @@ if worker_installed merge-gate; then
   }
 
   # 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 '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'
-  vv 'continue-on-error: true' "$MERGE_GATE_WORKER_MD" 'visual-verify dispatch must not block the merge'
+
+  # 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
@@ -2114,6 +2131,49 @@ if worker_installed implement; then
   if [ "$ENDINGS_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+echo "── Refine size gate ──────────────────────────────────────────────────────"
+
+# The size gate added a job that skips in the happy path, and gh-aw adds every custom job to
+# the agent's needs. Three claims about that shape are asserted, because each one broke in
+# production in the same week (Pliny-Bot #320-322: sixteen runs, three parked issues, a
+# refusal loop on an issue the author was shrinking live):
+#
+#   1. the agent's gate carries !failure(), so a skipped refusal no longer poisons the
+#      implicit success() and kills the agent in 0s
+#   2. the incomplete job excludes the refusal, so a refused issue is terminal: no attempt
+#      counter, no x/5, no re-dispatch, no stalled
+#   3. the refusal itself releases bot-working, so a refused issue is not left reserved
+if worker_installed refine; then
+  SIZE_GATE_OK=1
+  REFINE_WORKER_MD="${WORKFLOWS_DIR}/agent-refine.md"
+
+  # The top-level if: starts at column 0 -- job-level ifs: are indented -- so anchor on that,
+  # not on the prose comment above it. It must end with !failure().
+  top_level_if="$(sed -n 's/^if: //p' "$REFINE_WORKER_MD" | head -1)"
+  if [[ "$top_level_if" != *'!failure()' ]]; then
+    SIZE_GATE_OK=0
+    echo "FAIL: refine gates the agent without !failure(); a skipped refuse_big_issue poisons the implicit success() and skips the agent on every under-limit issue" >&2
+  fi
+
+  # Extract the incomplete job's own block. A whole-file grep cannot make this claim: reserve,
+  # refuse_big_issue and the agent gate all read size_guard, so the exclusion clause could be
+  # deleted from incomplete while every grep still passes.
+  incomplete_block="$(awk '/^  incomplete:/{found=1; next} found && /^  [a-z_]+:/{exit} found{print}' "$REFINE_WORKER_MD")"
+  if ! printf '%s' "$incomplete_block" | grep -qE '^    needs: \[.*size_guard' \
+    || ! printf '%s' "$incomplete_block" | grep -qF "needs.size_guard.outputs.too_big != 'true'"; then
+    SIZE_GATE_OK=0
+    echo "FAIL: refine's incomplete does not exclude the refusal path; every refused issue also loops attempts" >&2
+  fi
+
+  refuse_block="$(awk '/^  refuse_big_issue:/{found=1; next} found && /^  [a-z_]+:/{exit} found{print}' "$REFINE_WORKER_MD")"
+  if ! printf '%s' "$refuse_block" | grep -qF 'WORKING_LABEL'; then
+    SIZE_GATE_OK=0
+    echo "FAIL: the refine refusal never releases bot-working; a refused issue stays reserved with no run behind it" >&2
+  fi
+
+  if [ "$SIZE_GATE_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
 echo "── Runner pools ──────────────────────────────────────────────────────────"
 
 # Where every job runs, stated once and asserted, because GitHub gives a wrong pool no error: a

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

@@ -378,6 +378,17 @@ 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
@@ -396,6 +407,8 @@ 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
@@ -457,13 +470,30 @@ 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
+      # 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'
-        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
+        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-refine.md

@@ -229,6 +229,17 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ inputs.issue-number }}
           labels: stalled
+      # A refusal must also release the reservation. authorize-bot-work adds bot-working
+      # before the router dispatches, and this job is the refused run's only terminal path:
+      # incomplete is gated off it (see there), so without this removal a refused issue
+      # stays reserved with no run behind it -- parked, invisible, not re-triggerable until
+      # the hourly reconcile sweep clears it hours later.
+      - name: Release the reservation
+        uses: ./.github/actions/remove-issue-labels
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          issue-number: ${{ inputs.issue-number }}
+          labels: ${{ env.WORKING_LABEL }}
   reserve:
     needs: [still_open, size_guard]
     if: needs.still_open.outputs.open == 'true' && needs.size_guard.outputs.too_big != 'true'
@@ -475,9 +486,15 @@ jobs:
   incomplete:
     # activation for the artifact prefix the usage read needs; validate_output for its
     # valid output, which decides whether the usage read should look for truncation at all.
-    needs: [activation, agent, safe_outputs, validate_output]
+    # size_guard because a refusal is terminal: when too_big is true, refuse_big_issue has
+    # already spoken on the issue and no attempt, retry or park may follow. Without this
+    # clause every refused issue also looped here -- one human-label visit produced eight
+    # refusal comments and eight "Attempt N of 5" comments, none of which could succeed
+    # (Pliny-Bot #322).
+    needs: [activation, agent, safe_outputs, validate_output, size_guard]
     if: >
       always() &&
+      needs.size_guard.outputs.too_big != 'true' &&
       (
         needs.agent.result != 'success' ||
         needs.safe_outputs.result != 'success' ||
@@ -598,7 +615,15 @@ jobs:
             ${{ steps.usage.outputs.truncated }}
             [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
 
-if: inputs.issue-number != '' && needs.still_open.outputs.open == 'true' && needs.size_guard.outputs.too_big != 'true'
+# `!failure()` is load-bearing, not decoration. gh-aw adds every custom job to the agent's
+# `needs`, including refuse_big_issue -- a job that skips precisely when refinement should
+# run. Without a status function in this `if:` GitHub prepends an implicit `success()`,
+# and a skipped need fails it, so every under-limit issue skipped the agent in 0s and the
+# incomplete loop parked the issue (Pliny-Bot #320-322, 16 runs). `!failure()` suppresses
+# the implicit success(): a refused skip no longer poisons the agent, while any real
+# failure -- size_guard erroring, the refusal job erroring mid-refuse, reserve failing --
+# still blocks it and lands in incomplete.
+if: inputs.issue-number != '' && needs.still_open.outputs.open == 'true' && needs.size_guard.outputs.too_big != 'true' && !failure()
 
 runs-on: agents-arc
 runs-on-slim: agents-arc
@@ -753,16 +778,16 @@ timeout-minutes: 90
    The visible line is for people and the marker is read by the workflow, which turns it into the
    `sp-N` label. A body without the marker gets no estimate label at all.
 
- 7. **One safe-output call per turn.** Never batch multiple safe-output calls into a single
-    message: `update_issue`, `create_issue` and `add_comment` each go in their own turn, with
-    nothing else in the message. The provider caps one response at a fixed size, and a batch of
-    large calls is truncated mid-JSON before any of them executes, ending the run green with
-    nothing written. On the split path, sequence `create_issue` → `create_issue` → … →
-    `update_issue` → `add_comment`, one per turn. If a single body is so large it approaches the
-    size of a very long message, tighten the body; a shorter call that lands beats a longer one
-    that is cut off.
+7. **One safe-output call per turn.** Never batch multiple safe-output calls into a single
+   message: `update_issue`, `create_issue` and `add_comment` each go in their own turn, with
+   nothing else in the message. The provider caps one response at a fixed size, and a batch of
+   large calls is truncated mid-JSON before any of them executes, ending the run green with
+   nothing written. On the split path, sequence `create_issue` → `create_issue` → … →
+   `update_issue` → `add_comment`, one per turn. If a single body is so large it approaches the
+   size of a very long message, tighten the body; a shorter call that lands beats a longer one
+   that is cut off.
 
- 8. Decide exactly one outcome:
+8. Decide exactly one outcome:
 
     Labels are workflow-owned state. Do not call `add_labels` or `remove_labels`.
 

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

@@ -43,6 +43,10 @@ on:
         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.
@@ -57,11 +61,28 @@ jobs:
       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:
@@ -80,7 +101,7 @@ jobs:
             issue="$(jq -r '.closingIssuesReferences[0].number // empty' <<<"$pr")"
           fi
           if [ -z "$issue" ]; then
-            issue="$(jq -r '.body // ""' <<<"$pr" |
+            issue="$(jq -r '.body // ""' <<<"$pr")"
               grep -oiE '(close[sd]?|fixe?[sd]?|resolve[sd]?) +#[0-9]+' |
               grep -oE '[0-9]+' | head -n 1 || true)"
           fi
@@ -198,6 +219,11 @@ post-steps:
     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:

package/package.json

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