@plainconceptsplatform/workflows 0.6.1 → 0.16.0

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

@@ -3,23 +3,69 @@
 # Exercise the router's real classifier. This sources classify-route.sh rather than
 # restating it, so a change to the route table cannot pass here by being copied twice.
 #
+# The same file runs in every consumer, whatever subset of workers it installed: the router is
+# regenerated for that subset, so every assertion about a worker or about its router job is
+# conditional on the worker file being present. The classifier is the complete route table in
+# every repository (a route with no job is a no-op run), so its assertions are unconditional.
+#
 # This file greps workflow sources for literal `${{ ... }}` expressions on purpose.
 # shellcheck disable=SC2016
 
 set -euo pipefail
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ROUTER_YML="${HERE}/../../workflows/work-router.yml"
-IMPLEMENT_WORKER_MD="${HERE}/../../workflows/agent-implement.md"
-MERGE_GATE_WORKER_MD="${HERE}/../../workflows/agent-merge-gate.md"
+WORKFLOWS_DIR="${HERE}/../../workflows"
+ROUTER_YML="${WORKFLOWS_DIR}/work-router.yml"
+IMPLEMENT_WORKER_MD="${WORKFLOWS_DIR}/agent-implement.md"
+MERGE_GATE_WORKER_MD="${WORKFLOWS_DIR}/agent-merge-gate.md"
+
+# The audit slot is per repository and lives in the router's own env: block, which a real run
+# exports into the classify step. Export it here too, or this file would test the classifier's
+# fallback rather than the cron the router actually fires on.
+router_env() {
+  sed -n "s/^  $1: *//p" "$ROUTER_YML" | head -1 | sed -e 's/^"\(.*\)"$/\1/' -e "s/^'\(.*\)'$/\1/"
+}
+AUDIT_CRON="$(router_env AUDIT_CRON)"
+export AUDIT_CRON
 
 # shellcheck source-path=SCRIPTDIR
 # shellcheck source=../classify-route/classify-route.sh
 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)
+
+worker_installed() {
+  [ -f "${WORKFLOWS_DIR}/agent-$1.md" ]
+}
+
+INSTALLED_ROUTES=()
+EXCLUDED_ROUTES=()
+for route in "${ALL_WORKER_ROUTES[@]}"; do
+  if worker_installed "$route"; then
+    INSTALLED_ROUTES+=("$route")
+  else
+    EXCLUDED_ROUTES+=("$route")
+  fi
+done
+echo "Installed workers: ${INSTALLED_ROUTES[*]:-(none)}"
+[ "${#EXCLUDED_ROUTES[@]}" -eq 0 ] || echo "Not installed: ${EXCLUDED_ROUTES[*]}"
+
 PASS=0
 FAIL=0
 
+# `grep -c` exits 1 when it counts zero, and this file runs under `set -e`, so writing
+# `n=$(grep -c ...)` against a pattern that is absent ended the whole suite at whatever section
+# it had reached, with no error printed and no FAIL counted. That made an assertion of the form
+# "this pattern must be GONE" impossible to write here: the moment it held, the suite died. Every
+# count goes through this instead, where zero is an answer rather than a failure. Callers pass
+# their own grep flags.
+count() {
+  grep "$@" 2>/dev/null || true
+}
+
 # Classify one event and read a single field out of the result.
 route_field() {
   local field="$1"
@@ -106,9 +152,6 @@ assert_route "the bot's own comment never re-enters refine" none \
 assert_route "a comment on an issue without refine routes nowhere" none \
   EVENT=issue_comment COMMENT_ON_PR=false COMMENT_SENDER_TYPE=User \
   'ISSUE_LABELS=["bug"]' EVENT_ISSUE_NUMBER=42
-assert_route "the bot's own comment never re-enters direct" none \
-  EVENT=issue_comment COMMENT_ON_PR=false COMMENT_SENDER_TYPE=Bot \
-  'ISSUE_LABELS=["direct"]' EVENT_ISSUE_NUMBER=42
 assert_route "a comment on a triage issue re-triages" triage \
   EVENT=issue_comment COMMENT_ON_PR=false COMMENT_SENDER_TYPE=User \
   'ISSUE_LABELS=["triage"]' EVENT_ISSUE_NUMBER=42
@@ -120,12 +163,22 @@ assert_route "the bot's own comment never re-enters triage" none \
   'ISSUE_LABELS=["triage"]' EVENT_ISSUE_NUMBER=42
 
 echo "── Closed issues ─────────────────────────────────────────────────────────"
-assert_route "a closing comment on a refine issue does not re-refine" none   EVENT=issue_comment COMMENT_ON_PR=false COMMENT_SENDER_TYPE=User   ISSUE_STATE=closed 'ISSUE_LABELS=["refine"]' EVENT_ISSUE_NUMBER=42
-assert_route "a comment on a closed issue never re-triages" none   EVENT=issue_comment COMMENT_ON_PR=false COMMENT_SENDER_TYPE=User   ISSUE_STATE=closed 'ISSUE_LABELS=["triage"]' EVENT_ISSUE_NUMBER=42
-assert_route "a work label added to a closed issue routes nowhere" none   EVENT=issues ACTION=labeled LABEL=bot-working ISSUE_STATE=closed   'ISSUE_LABELS=["implement"]' EVENT_ISSUE_NUMBER=42
-assert_route "a closed issue reopened as opened still routes nowhere while closed" none   EVENT=issues ACTION=opened ISSUE_STATE=closed 'ISSUE_LABELS=[]' EVENT_ISSUE_NUMBER=42
-assert_route "a comment on a closed pull request still routes to apply-review" apply-review   EVENT=issue_comment COMMENT_ON_PR=true ISSUE_STATE=closed EVENT_ISSUE_NUMBER=7
-assert_route "an open refine issue is unaffected by the closed guard" refine   EVENT=issue_comment COMMENT_ON_PR=false COMMENT_SENDER_TYPE=User   ISSUE_STATE=open 'ISSUE_LABELS=["refine"]' EVENT_ISSUE_NUMBER=42
+assert_route "a closing comment on a refine issue does not re-refine" none \
+  EVENT=issue_comment COMMENT_ON_PR=false COMMENT_SENDER_TYPE=User \
+  ISSUE_STATE=closed 'ISSUE_LABELS=["refine"]' EVENT_ISSUE_NUMBER=42
+assert_route "a comment on a closed issue never re-triages" none \
+  EVENT=issue_comment COMMENT_ON_PR=false COMMENT_SENDER_TYPE=User \
+  ISSUE_STATE=closed 'ISSUE_LABELS=["triage"]' EVENT_ISSUE_NUMBER=42
+assert_route "a work label added to a closed issue routes nowhere" none \
+  EVENT=issues ACTION=labeled LABEL=bot-working ISSUE_STATE=closed \
+  'ISSUE_LABELS=["implement"]' EVENT_ISSUE_NUMBER=42
+assert_route "a closed issue reopened as opened still routes nowhere while closed" none \
+  EVENT=issues ACTION=opened ISSUE_STATE=closed 'ISSUE_LABELS=[]' EVENT_ISSUE_NUMBER=42
+assert_route "a comment on a closed pull request still routes to apply-review" apply-review \
+  EVENT=issue_comment COMMENT_ON_PR=true ISSUE_STATE=closed EVENT_ISSUE_NUMBER=7
+assert_route "an open refine issue is unaffected by the closed guard" refine \
+  EVENT=issue_comment COMMENT_ON_PR=false COMMENT_SENDER_TYPE=User \
+  ISSUE_STATE=open 'ISSUE_LABELS=["refine"]' EVENT_ISSUE_NUMBER=42
 
 echo "── Review events ─────────────────────────────────────────────────────────"
 assert_route "a review comment routes to apply-review" apply-review \
@@ -162,7 +215,7 @@ while read -r cron; do
     PASS=$((PASS + 1))
     echo "  ${cron} -> ${selected}"
   fi
-done < <(sed -n 's/^ *- cron: "\(.*\)"$/\1/p' "$ROUTER_YML")
+done < <(sed -n 's/^ *- cron: "\([^"]*\)".*/\1/p' "$ROUTER_YML")
 
 assert_route "an unknown cron routes nowhere" none EVENT=schedule "SCHEDULE=0 0 30 2 *"
 
@@ -173,16 +226,12 @@ assert_route "refine dispatch rejects a non-numeric issue" none \
   EVENT=workflow_dispatch OPERATION=refine INPUT_ISSUE_NUMBER=abc
 assert_route "refine dispatch accepts a positive issue" refine \
   EVENT=workflow_dispatch OPERATION=refine INPUT_ISSUE_NUMBER=42
-assert_route "direct dispatch needs an issue number" none \
-  EVENT=workflow_dispatch OPERATION=direct INPUT_ISSUE_NUMBER=
 assert_route "triage dispatch accepts a positive issue" triage \
   EVENT=workflow_dispatch OPERATION=triage INPUT_ISSUE_NUMBER=42
 assert_route "triage dispatch needs an issue number" none \
   EVENT=workflow_dispatch OPERATION=triage INPUT_ISSUE_NUMBER=
 assert "triage dispatch defaults to first pass" first \
   "$(route_field triage-mode EVENT=workflow_dispatch OPERATION=triage INPUT_ISSUE_NUMBER=42)"
-assert_route "batch dispatch needs an issue number" none \
-  EVENT=workflow_dispatch OPERATION=batch INPUT_ISSUE_NUMBER=
 assert_route "merge-gate dispatch needs a pull request number" none \
   EVENT=workflow_dispatch OPERATION=merge-gate INPUT_PR_NUMBER=0
 assert_route "merge-gate dispatch accepts a positive pull request" merge-gate \
@@ -199,6 +248,8 @@ assert "implement dispatch forwards the attempt count" 2 \
   "$(route_field implement-attempts EVENT=workflow_dispatch OPERATION=implement INPUT_ISSUE_NUMBER=42 INPUT_ATTEMPTS_SO_FAR=2)"
 assert "a refine dispatch carries no implement attempts" 0 \
   "$(route_field implement-attempts EVENT=workflow_dispatch OPERATION=refine INPUT_ISSUE_NUMBER=42 INPUT_ATTEMPTS_SO_FAR=2)"
+assert_route "release dispatch needs no numbers" release \
+  EVENT=workflow_dispatch OPERATION=release
 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 \
@@ -209,13 +260,199 @@ assert "a scheduled audit reports its trigger kind" scheduled \
 assert "a dispatched audit reports its trigger kind" manual \
   "$(route_field trigger-kind EVENT=workflow_dispatch OPERATION=audit INPUT_TRIGGER_KIND=manual)"
 
+echo "── Prompt hygiene ────────────────────────────────────────────────────────"
+
+# Everything below a worker's frontmatter is the prompt. Three things must not be in one.
+#
+# A `gh` call, because the shared CI agent config says the GitHub CLI is intentionally
+# unauthenticated and the agent must never use it for GitHub reads or writes. A prompt that
+# orders one burns turns and fails; implement carried a `gh pr list` for weeks, asking the agent
+# to redo a check the router had already done before dispatching it.
+#
+# A duplicate step number, because these are ordered instruction lists and a step that says
+# "go to step 6" cannot resolve when there are two. implement had two 6s with contradictory
+# rules ("exactly one" and "at least one" safe output), refine had two 5s, apply-review two 9s.
+#
+# A Mermaid diagram, because it is documentation that the model is charged for on every run and
+# then told to ignore. They live in docs/diagrams.md.
+PROMPT_OK=1
+for worker in "${WORKFLOWS_DIR}"/agent-*.md; do
+  [ -f "$worker" ] || continue
+  name=$(basename "$worker")
+  # The prompt starts after the closing --- of the frontmatter.
+  fm_end=$(awk 'NR>1 && /^---[[:space:]]*$/{print NR; exit}' "$worker")
+  [ -n "$fm_end" ] || { PROMPT_OK=0; echo "FAIL: ${name} has no frontmatter terminator" >&2; continue; }
+  prompt=$(tail -n "+$((fm_end + 1))" "$worker")
+
+  if grep -qE '(^|[^[:alnum:]_-])gh (pr|issue|api|run|release|workflow|auth) ' <<<"$prompt"; then
+    PROMPT_OK=0
+    echo "FAIL: ${name}'s prompt tells the agent to run gh; the CLI is unauthenticated in CI" >&2
+    grep -nE '(^|[^[:alnum:]_-])gh (pr|issue|api|run|release|workflow|auth) ' <<<"$prompt" >&2
+  fi
+
+  if grep -q '```mermaid' <<<"$prompt"; then
+    PROMPT_OK=0
+    echo "FAIL: ${name}'s prompt contains a Mermaid diagram; diagrams belong in docs/diagrams.md" >&2
+  fi
+
+  # Top-level steps only: an indented "1." is a sub-list and numbers restart legitimately.
+  dupes=$(grep -oE '^[0-9]+\. ' <<<"$prompt" | tr -d '. ' | sort -n | uniq -d | tr '\n' ' ')
+  if [ -n "${dupes// /}" ]; then
+    PROMPT_OK=0
+    echo "FAIL: ${name}'s prompt repeats step number(s): ${dupes}" >&2
+  fi
+
+  # A multi-line env value does not survive compilation: gh-aw joins it onto one line in the
+  # lock, so a Markdown table written across five lines in the source reaches the agent as a
+  # single unreadable row. Verified against a compiled lock. Block the YAML block scalars that
+  # produce one, so the flattening is a failed check rather than a silently useless value.
+  block_scalars=$(awk '
+    /^env:$/ { inenv = 1; next }
+    inenv && /^[^ ]/ { inenv = 0 }
+    inenv && /^  [A-Za-z_][A-Za-z0-9_]*: *[|>]-?[0-9]* *$/ { print $1 }
+  ' "$worker" | tr -d ':' | tr '\n' ' ')
+  if [ -n "${block_scalars// /}" ]; then
+    PROMPT_OK=0
+    echo "FAIL: ${name} declares env value(s) as a multi-line block, which the compiler flattens: ${block_scalars}" >&2
+  fi
+done
+if [ "$PROMPT_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
 echo "── Router wiring ─────────────────────────────────────────────────────────"
 
+# Two router values are needed where GitHub evaluates no expression, so the installer mirrors
+# them out of env: into a literal. A copy that drifts fails in the direction that hurts: the
+# gate silently reads a CI workflow nobody runs, or the audit fires on a cron the classifier
+# maps to no route. Neither produces a red run, so assert the copies here.
+MIRROR_OK=1
+ci_name="$(router_env CI_WORKFLOW_NAME)"
+trigger_name="$(sed -n 's/^ *workflows: \["\(.*\)"\] *$/\1/p' "$ROUTER_YML" | head -1)"
+if [ -z "$ci_name" ]; then
+  MIRROR_OK=0; echo "FAIL: work-router.yml defines no CI_WORKFLOW_NAME in its env: block" >&2
+elif [ "$ci_name" != "$trigger_name" ]; then
+  MIRROR_OK=0
+  echo "FAIL: the workflow_run trigger names '${trigger_name}' but env.CI_WORKFLOW_NAME is '${ci_name}'" >&2
+fi
+# The audit cron only exists in a router that installed the audit worker.
+if worker_installed audit; then
+  cron_line="$(sed -n 's/^ *- cron: "\([^"]*\)" # audit slot.*/\1/p' "$ROUTER_YML" | head -1)"
+  if [ -z "$AUDIT_CRON" ]; then
+    MIRROR_OK=0; echo "FAIL: work-router.yml defines no AUDIT_CRON in its env: block" >&2
+  elif [ "$AUDIT_CRON" != "$cron_line" ]; then
+    MIRROR_OK=0
+    echo "FAIL: the audit slot cron is '${cron_line}' but env.AUDIT_CRON is '${AUDIT_CRON}'" >&2
+  fi
+fi
+# And nothing may go back to naming the CI workflow directly: a second literal is a second
+# thing to keep in step, and the one that gets forgotten is the one inside a jq filter.
+if [ "$(count -c '"App: CI"' "$ROUTER_YML")" -gt 2 ]; then
+  MIRROR_OK=0
+  echo "FAIL: work-router.yml hardcodes the CI workflow name outside env: and the mirrored trigger" >&2
+  grep -n '"App: CI"' "$ROUTER_YML" >&2
+fi
+
+# Bot logins are the same shape of problem. Most sites read env.TRUSTED_BOTS, but a job-level
+# `if:` cannot: GitHub does not expose the env context there, so bot-approve keeps literals and
+# they have to agree. Assert every bot login written anywhere in the router is in the list.
+trusted="$(router_env TRUSTED_BOTS)"
+if [ -z "$trusted" ]; then
+  MIRROR_OK=0; echo "FAIL: work-router.yml defines no TRUSTED_BOTS in its env: block" >&2
+else
+  while IFS= read -r login; do
+    [ -n "$login" ] || continue
+    case " $trusted " in
+      *" $login "*) ;;
+      *)
+        MIRROR_OK=0
+        echo "FAIL: work-router.yml names bot '${login}' but env.TRUSTED_BOTS does not list it" >&2
+        ;;
+    esac
+  done < <(grep -oE "'(app/[a-z-]+|[a-z-]+\[bot\])'|\"(app/[a-z-]+|[a-z-]+\[bot\])\"" "$ROUTER_YML" |
+    tr -d "'\"" | sort -u)
+fi
+if [ "$MIRROR_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
+# Run the belt's own jq, rather than reading it. The filter that picks which open pull requests
+# the hourly reconcile job acts on was written as
+#   ((env.TRUSTED_BOTS | split(" ")) | index(.user.login) != null)
+# which dies at runtime with `Cannot index array with string "user"`, because inside index() the
+# input is the array, not the pull request. Every assertion here passed: one checked the bot
+# logins were listed in TRUSTED_BOTS, another that the router named no bot outside that list.
+# Nothing executed the program. It failed hourly in production for a day, on the one job whose
+# purpose is to keep stuck pull requests moving. Extract it and give it inputs.
+BELT_OK=1
+bot_pr_filter=$(awk '/jq -r --arg repo "\$REPO"/{found=1;next} found && /^ *'"'"' \|$/{exit} found' "$ROUTER_YML")
+if [ -z "$bot_pr_filter" ]; then
+  BELT_OK=0
+  echo "FAIL: could not extract the open-pull-request filter from work-router.yml" >&2
+else
+  # One of each: a trusted App under both spellings, a human, a draft, and a fork.
+  belt_fixture='[
+    {"number":11,"draft":false,"user":{"login":"app/github-actions"},"head":{"ref":"a","sha":"s1","repo":{"full_name":"o/r"}}},
+    {"number":12,"draft":false,"user":{"login":"platform-devbox[bot]"},"head":{"ref":"b","sha":"s2","repo":{"full_name":"o/r"}}},
+    {"number":13,"draft":false,"user":{"login":"a-person"},"head":{"ref":"c","sha":"s3","repo":{"full_name":"o/r"}}},
+    {"number":14,"draft":true,"user":{"login":"app/github-actions"},"head":{"ref":"d","sha":"s4","repo":{"full_name":"o/r"}}},
+    {"number":15,"draft":false,"user":{"login":"app/github-actions"},"head":{"ref":"e","sha":"s5","repo":{"full_name":"fork/r"}}}
+  ]'
+  if ! selected=$(printf '%s' "$belt_fixture" |
+    TRUSTED_BOTS="$trusted" jq -r --arg repo "o/r" "$bot_pr_filter" 2>&1 | cut -f1 | tr '\n' ' '); then
+    BELT_OK=0
+    echo "FAIL: the open-pull-request filter does not run: ${selected}" >&2
+  elif [ "$(echo "$selected" | tr -s ' ')" != "11 12 " ]; then
+    BELT_OK=0
+    echo "FAIL: the belt selected pull requests [${selected}]; expected the two bot-authored ones (11 12)" >&2
+  fi
+fi
+if [ "$BELT_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
+# `review` must not be a one-way door. It used to be: authorize-bot-work refused to fire on an
+# issue carrying it, and the classifier refuses to route while it is set, so a person adding
+# `refine` to a parked issue got nothing at all — no run, no comment, no error. Triage's own
+# needs-maintainer verdict tells the maintainer to do exactly that, so the bot was giving an
+# instruction the machine ignored. authorize-bot-work now clears `review` before handing over,
+# which is what makes the human's decision stick.
+AUTHORIZE_YML="${WORKFLOWS_DIR}/authorize-bot-work.yml"
+if [ -f "$AUTHORIZE_YML" ]; then
+  DOOR_OK=1
+  authorize_if=$(sed -n '/^    if: >/,/^    runs-on:/p' "$AUTHORIZE_YML")
+  if grep -q "labels\.\*\.name, 'review'" <<<"$authorize_if"; then
+    DOOR_OK=0
+    echo "FAIL: authorize-bot-work refuses issues carrying review; a human could not un-park one" >&2
+  fi
+  # It must still refuse the bot, and an issue another run already owns.
+  grep -q "endsWith(github.actor, '\[bot\]')" <<<"$authorize_if" || {
+    DOOR_OK=0
+    echo "FAIL: authorize-bot-work no longer excludes bot actors; it would re-trigger itself" >&2
+  }
+  grep -q "labels\.\*\.name, 'bot-working'" <<<"$authorize_if" || {
+    DOOR_OK=0
+    echo "FAIL: authorize-bot-work no longer excludes an issue a run already owns" >&2
+  }
+  # The hand-off has to clear review BEFORE adding bot-working, because bot-working is the event
+  # the classifier reads: the other order raises an event whose payload still carries review.
+  remove_line=$(grep -n -- '--remove-label "review"' "$AUTHORIZE_YML" | head -1 | cut -d: -f1)
+  add_line=$(grep -n -- '--add-label "bot-working"' "$AUTHORIZE_YML" | head -1 | cut -d: -f1)
+  if [ -z "$remove_line" ] || [ -z "$add_line" ] || [ "$remove_line" -ge "$add_line" ]; then
+    DOOR_OK=0
+    echo "FAIL: authorize-bot-work must remove review before adding bot-working (review=${remove_line:-none} bot-working=${add_line:-none})" >&2
+  fi
+  if [ "$DOOR_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
+# The classifier's own guard stays: it stops the bot re-triggering itself while a human is
+# needed. Both halves matter, so assert the pair rather than either alone.
+assert_route "a bot-working event on a review-labelled issue still routes nowhere" none \
+  EVENT=issues ACTION=labeled LABEL=bot-working ACTOR=platform-devbox[bot] \
+  'ISSUE_LABELS=["implement","review"]' EVENT_ISSUE_NUMBER=42
+assert_route "and routes normally once review has been cleared" implement \
+  EVENT=issues ACTION=labeled LABEL=bot-working ACTOR=platform-devbox[bot] \
+  'ISSUE_LABELS=["implement"]' EVENT_ISSUE_NUMBER=42
+
 # GitHub evaluates every Actions expression in a workflow file, including ones written inside
 # shell comments. An empty pair is not a valid expression and fails the whole file to parse,
 # with an error that points at a line number rather than saying what is wrong. Prose about
 # expressions must not contain one.
-empty_expr=$(grep -rl -e '${{[[:space:]]*}}' "${HERE}/../../workflows"/*.yml "${HERE}/../../workflows"/*.md 2>/dev/null || true)
+empty_expr=$(grep -rl -e '${{[[:space:]]*}}' "${WORKFLOWS_DIR}"/*.yml "${WORKFLOWS_DIR}"/*.md 2>/dev/null || true)
 if [ -z "$empty_expr" ]; then
   PASS=$((PASS + 1))
 else
@@ -224,15 +461,16 @@ else
   while IFS= read -r offending; do echo "  $offending" >&2; done <<<"$empty_expr"
 fi
 
-
 # A hyphen inside a ${{ }} property path is parsed as subtraction, so the reference silently
 # resolves to nothing and the rendered prompt keeps the raw expression. Underscores only.
-if ! grep -qE 'needs\.[a-z_]+\.outputs\.[a-zA-Z0-9_]*-' "$IMPLEMENT_WORKER_MD"; then
-  PASS=$((PASS + 1))
-else
-  FAIL=$((FAIL + 1))
-  echo "FAIL: implement worker reads a hyphenated job output inside an expression" >&2
-  grep -nE 'needs\.[a-z_]+\.outputs\.[a-zA-Z0-9_]*-' "$IMPLEMENT_WORKER_MD" >&2
+if worker_installed implement; then
+  if ! grep -qE 'needs\.[a-z_]+\.outputs\.[a-zA-Z0-9_]*-' "$IMPLEMENT_WORKER_MD"; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: implement worker reads a hyphenated job output inside an expression" >&2
+    grep -nE 'needs\.[a-z_]+\.outputs\.[a-zA-Z0-9_]*-' "$IMPLEMENT_WORKER_MD" >&2
+  fi
 fi
 
 # A worker that prints `${{ env.NAME }}` without defining NAME in its own env: block renders
@@ -241,7 +479,8 @@ fi
 # worker prints must be defined in that worker. The values are consumer-owned (a consumer may
 # split VERIFY_COMMANDS per area, or keep one); only the wiring is asserted here.
 VERIFY_OK=1
-for worker in "${HERE}/../../workflows"/agent-*.md; do
+for worker in "${WORKFLOWS_DIR}"/agent-*.md; do
+  [ -f "$worker" ] || continue
   while read -r name; do
     [ -n "$name" ] || continue
     if ! grep -q "^  ${name}:" "$worker"; then
@@ -252,13 +491,29 @@ for worker in "${HERE}/../../workflows"/agent-*.md; do
 done
 if [ "$VERIFY_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 
-if grep -Fq 'protected-files: allowed' "$IMPLEMENT_WORKER_MD" &&
-  grep -Fq 'protected-files: allowed' "$MERGE_GATE_WORKER_MD" &&
-  grep -Fq "needs.protected_changes.outputs.requires_review != 'true' || needs.subject.outputs.conclusion == 'failure'" "$MERGE_GATE_WORKER_MD"; then
-  PASS=$((PASS + 1))
-else
-  FAIL=$((FAIL + 1))
-  echo "FAIL: protected changes must allow failed-CI repair while remaining held from merge" >&2
+# A protected path holds the merge for a human but must never stop the agent repairing failed
+# CI on those same files, or the pull request strands with nobody able to fix it. That pair of
+# conditions is decided once, in protected_changes.outputs.holds_review, and read everywhere
+# else; it used to be restated at eight call sites. Auto-merge stays blocked separately, by
+# conclude's own guard on requires_review, which holds even when CI failed.
+if worker_installed implement && worker_installed merge-gate; then
+  PROTECTED_OK=1
+  grep -Fq 'protected-files: allowed' "$IMPLEMENT_WORKER_MD" || PROTECTED_OK=0
+  grep -Fq 'protected-files: allowed' "$MERGE_GATE_WORKER_MD" || PROTECTED_OK=0
+  grep -Fq "holds_review: \${{ steps.files.outputs.requires_review == 'true' && needs.subject.outputs.conclusion != 'failure' }}" "$MERGE_GATE_WORKER_MD" || PROTECTED_OK=0
+  # The decision must not be re-derived anywhere: one definition, everything else reads it.
+  if [ "$(count -c "requires_review == 'true' && needs.subject.outputs.conclusion != 'failure'" "$MERGE_GATE_WORKER_MD")" -ne 1 ]; then
+    PROTECTED_OK=0
+    echo "FAIL: the protected-files hold is derived in more than one place; read holds_review instead" >&2
+  fi
+  # And conclude must still refuse to merge a protected pull request whatever CI said.
+  grep -Fq "needs.protected_changes.outputs.requires_review != 'true' || needs.validate_output.outputs.outcome != 'merge'" "$MERGE_GATE_WORKER_MD" || PROTECTED_OK=0
+  if [ "$PROTECTED_OK" -eq 1 ]; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: protected changes must allow failed-CI repair while remaining held from merge" >&2
+  fi
 fi
 
 # gh-aw folds the worker's top-level `if:` into the generated activation job but computes
@@ -266,56 +521,59 @@ fi
 # `needs:` are hoisted. A guard with its own `needs:` (protected_changes needs subject) is read
 # before it has run, resolves to '' and gates nothing, unless it is listed in `on.needs`, the
 # documented way to add jobs to pre_activation and activation. Inline list form is expected.
-TOP_IF="$(tr -d '\r' <"$MERGE_GATE_WORKER_MD" | sed -n 's/^if: //p')"
-ON_NEEDS="$(tr -d '\r' <"$MERGE_GATE_WORKER_MD" | sed -n '/^on:$/,/^[a-z]/p' |
-  sed -n 's/^  needs: *\[\(.*\)\].*/\1/p' | tr -d ' ' | tr ',' '\n')"
-ACTIVATION_OK=1
-[ -n "$TOP_IF" ] || { ACTIVATION_OK=0; echo "FAIL: could not read the merge-gate worker's top-level if" >&2; }
-while read -r job; do
-  [ -n "$job" ] || continue
-  if tr -d '\r' <"$MERGE_GATE_WORKER_MD" | sed -n "/^  ${job}:$/,/^  [a-z_]*:$/p" | grep -q '^    needs:' &&
-    ! grep -qx "$job" <<<"$ON_NEEDS"; then
-    ACTIVATION_OK=0
-    echo "FAIL: merge-gate top-level if reads needs.${job}, which has its own needs and is not in on.needs; activation would read it before it runs" >&2
-  fi
-done < <(grep -oE 'needs\.[a-z_]+\.' <<<"$TOP_IF" | sed 's/^needs\.//; s/\.$//' | sort -u)
-if [ "$ACTIVATION_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
-
-# The merge belt is serial for the whole repository: several overnight pull requests
-# mean every merge moves the default branch under the rest, and gates running at once
-# rebase onto bases other gates are about to invalidate. A per-issue group here would
-# reintroduce that race, so assert the repo-wide lock is the one in use.
-if grep -A7 'call-merge-gate:' "$ROUTER_YML" | grep -q 'group: merge-belt'; then
-  PASS=$((PASS + 1))
-else
-  FAIL=$((FAIL + 1))
-  echo "FAIL: call-merge-gate must hold the repo-wide merge-belt lock" >&2
+if worker_installed merge-gate; then
+  TOP_IF="$(tr -d '\r' <"$MERGE_GATE_WORKER_MD" | sed -n 's/^if: //p')"
+  ON_NEEDS="$(tr -d '\r' <"$MERGE_GATE_WORKER_MD" | sed -n '/^on:$/,/^[a-z]/p' |
+    sed -n 's/^  needs: *\[\(.*\)\].*/\1/p' | tr -d ' ' | tr ',' '\n')"
+  ACTIVATION_OK=1
+  [ -n "$TOP_IF" ] || { ACTIVATION_OK=0; echo "FAIL: could not read the merge-gate worker's top-level if" >&2; }
+  while read -r job; do
+    [ -n "$job" ] || continue
+    if tr -d '\r' <"$MERGE_GATE_WORKER_MD" | sed -n "/^  ${job}:$/,/^  [a-z_]*:$/p" | grep -q '^    needs:' &&
+      ! grep -qx "$job" <<<"$ON_NEEDS"; then
+      ACTIVATION_OK=0
+      echo "FAIL: merge-gate top-level if reads needs.${job}, which has its own needs and is not in on.needs; activation would read it before it runs" >&2
+    fi
+  done < <(grep -oE 'needs\.[a-z_]+\.' <<<"$TOP_IF" | sed 's/^needs\.//; s/\.$//' | sort -u)
+  if [ "$ACTIVATION_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
+  # The merge belt is serial for the whole repository: several overnight pull requests
+  # mean every merge moves the default branch under the rest, and gates running at once
+  # rebase onto bases other gates are about to invalidate. A per-issue group here would
+  # reintroduce that race, so assert the repo-wide lock is the one in use.
+  if grep -A7 'call-merge-gate:' "$ROUTER_YML" | grep -q 'group: merge-belt'; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: call-merge-gate must hold the repo-wide merge-belt lock" >&2
+  fi
 fi
 
 # A verdict is the gate marker AND a `**Verdict:**` line together. Comments carrying the
 # marker alone were progress notes and failed attempts, and the reconcile belt read every
 # one of them as final: a crashed or OOM-killed gate parked its pull request for the rest
 # of the night. Attempts are counted separately, capped, and reset by any new CI run.
+# The belt lives in the router's plumbing jobs, so this holds in every repository.
 BELT_OK=1
 if ! grep -q 'agent-merge-gate-attempt' "$ROUTER_YML"; then
   BELT_OK=0; echo "FAIL: router never counts gate attempts" >&2
 fi
-if [ "$(grep -cF 'contains("<!-- agent-merge-gate -->")) and (.body | contains("**Verdict:**"))' "$ROUTER_YML")" -lt 4 ]; then
+if [ "$(count -cF 'contains("<!-- agent-merge-gate -->")) and (.body | contains("**Verdict:**"))' "$ROUTER_YML")" -lt 4 ]; then
   BELT_OK=0; echo "FAIL: verdict detection must pair the gate marker with a Verdict line in both dispatch paths" >&2
 fi
-if [ "$(grep -c 'attempts_so_far' "$ROUTER_YML")" -lt 2 ]; then
+if [ "$(count -c 'attempts_so_far' "$ROUTER_YML")" -lt 2 ]; then
   BELT_OK=0; echo "FAIL: dispatch sites must forward attempts_so_far" >&2
 fi
 # A second gate for a pull request whose gate is already queued or running reads the same CI
 # verdict and is cancelled by the single-slot merge-belt queue (two cancellations on 2026-09-06).
-if [ "$(grep -c 'a merge-gate run is already live' "$ROUTER_YML")" -lt 2 ]; then
+if [ "$(count -c 'a merge-gate run is already live' "$ROUTER_YML")" -lt 2 ]; then
   BELT_OK=0; echo "FAIL: both dispatch paths must skip a pull request whose gate is already live" >&2
 fi
 # A conflicting pull request has no refs/pull/N/merge for GitHub to build, so a `pull_request`
 # CI workflow can never run on that head. Requiring a fresh verdict before dispatching deadlocks
 # the belt: only the gate resolves the conflict, and the gate never runs. Both paths fall back to
 # the branch's last verdict when, and only when, the pull request is conflicting.
-if [ "$(grep -c 'conflicts, so CI cannot run on' "$ROUTER_YML")" -lt 2 ]; then
+if [ "$(count -c 'conflicts, so CI cannot run on' "$ROUTER_YML")" -lt 2 ]; then
   BELT_OK=0
   echo "FAIL: both dispatch paths must gate a conflicting pull request that can never get fresh CI" >&2
 fi
@@ -327,8 +585,8 @@ fi
 # reports "not conflicting" for exactly the stale pull requests the fallback is for. Observed
 # twice in production: the fallback logged "no completed CI run" for a pull request that
 # `gh pr view` reported as CONFLICTING from a warm cache seconds later.
-if [ "$(grep -c 'mergeable_state()' "$ROUTER_YML")" -lt 2 ] ||
-  [ "$(grep -c 'mergeable_now=$(mergeable_state' "$ROUTER_YML")" -lt 2 ]; then
+if [ "$(count -c 'mergeable_state()' "$ROUTER_YML")" -lt 2 ] ||
+  [ "$(count -c 'mergeable_now=$(mergeable_state' "$ROUTER_YML")" -lt 2 ]; then
   BELT_OK=0
   echo "FAIL: both dispatch paths must poll the mergeable state; a single read answers UNKNOWN" >&2
 fi
@@ -338,7 +596,7 @@ if [ "$BELT_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 # CI never reaches the router's CI-completion route. The package ships a dispatch-merge-gate job
 # in templates/ci that hands the verdict over from inside CI; a consumer CI workflow, where one
 # exists beside the router, must carry it or bot pull requests wait for the hourly belt.
-for ci in "${HERE}/../../workflows/ci.yml" "${HERE}/../../workflows/app-ci.yml"; do
+for ci in "${WORKFLOWS_DIR}/ci.yml" "${WORKFLOWS_DIR}/app-ci.yml"; do
   [ -f "$ci" ] || continue
   if grep -q 'operation=merge-gate' "$ci"; then
     PASS=$((PASS + 1))
@@ -368,27 +626,29 @@ while read -r name; do
 done < <(grep -oE 'needs\.classify\.outputs\.[a-zA-Z0-9_-]+' "$ROUTER_YML" | sed 's/.*\.//' | sort -u)
 if [ "$CLASSIFY_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 
-# fromJson('') is a hard failure ("Error reading JToken"), and a workflow_call input arrives as
-# '' whenever the caller passes an empty expression, declared default or not. The gate must never
-# hand a raw input to fromJson; `inputs.x || '0'` reads the empty case as zero.
-if ! grep -qE "fromJson\(inputs\.[a-zA-Z0-9_]+\)" "$MERGE_GATE_WORKER_MD"; then
-  PASS=$((PASS + 1))
-else
-  FAIL=$((FAIL + 1))
-  echo "FAIL: merge-gate worker calls fromJson on a raw input; an empty caller value kills the job" >&2
-  grep -nE "fromJson\(inputs\.[a-zA-Z0-9_]+\)" "$MERGE_GATE_WORKER_MD" >&2
-fi
+if worker_installed merge-gate; then
+  # fromJson('') is a hard failure ("Error reading JToken"), and a workflow_call input arrives as
+  # '' whenever the caller passes an empty expression, declared default or not. The gate must never
+  # hand a raw input to fromJson; `inputs.x || '0'` reads the empty case as zero.
+  if ! grep -qE "fromJson\(inputs\.[a-zA-Z0-9_]+\)" "$MERGE_GATE_WORKER_MD"; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: merge-gate worker calls fromJson on a raw input; an empty caller value kills the job" >&2
+    grep -nE "fromJson\(inputs\.[a-zA-Z0-9_]+\)" "$MERGE_GATE_WORKER_MD" >&2
+  fi
 
-# The worker's own comments must keep the distinction: progress notes carry no marker,
-# failed attempts carry the attempt marker, verdicts carry the marker AND the Verdict line.
-# Three verdict sites: the review hold on the issue, the agent's assessment on the issue,
-# and conclude's short verdict on the pull request itself.
-if grep -q 'ATTEMPT_MARKER: "<!-- agent-merge-gate-attempt -->"' "$MERGE_GATE_WORKER_MD" &&
-  [ "$(grep -c '\${{ env.GATE_MARKER }}' "$MERGE_GATE_WORKER_MD")" -eq 3 ]; then
-  PASS=$((PASS + 1))
-else
-  FAIL=$((FAIL + 1))
-  echo "FAIL: merge-gate worker must keep verdict and attempt markers distinct" >&2
+  # The worker's own comments must keep the distinction: progress notes carry no marker,
+  # failed attempts carry the attempt marker, verdicts carry the marker AND the Verdict line.
+  # Three verdict sites: the review hold on the issue, the agent's assessment on the issue,
+  # and conclude's short verdict on the pull request itself.
+  if grep -q 'ATTEMPT_MARKER: "<!-- agent-merge-gate-attempt -->"' "$MERGE_GATE_WORKER_MD" &&
+    [ "$(count -c '\${{ env.GATE_MARKER }}' "$MERGE_GATE_WORKER_MD")" -eq 3 ]; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: merge-gate worker must keep verdict and attempt markers distinct" >&2
+  fi
 fi
 
 # add-issue-labels and remove-issue-labels split `labels` on newlines. A caller that joined two
@@ -397,7 +657,7 @@ fi
 # and review together for a day. Callers use block scalars, one label per line; the actions also
 # accept commas so a consumer copy of an old caller keeps working.
 LABELS_OK=1
-if grep -nE '^[[:space:]]+labels: [^|>].*,' "${HERE}/../../workflows"/agent-*.md >&2; then
+if grep -nE '^[[:space:]]+labels: [^|>].*,' "${WORKFLOWS_DIR}"/agent-*.md >&2 2>/dev/null; then
   LABELS_OK=0
   echo "FAIL: a worker passes comma-joined labels to a label action; use a block scalar, one label per line" >&2
 fi
@@ -409,83 +669,105 @@ for action in add-issue-labels remove-issue-labels; do
 done
 if [ "$LABELS_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 
-# The agent's fix reaches the branch as a bundle applied fast-forward only (apply-agent-output).
-# gh-aw's push tool description tells the model to rebase, and a rebased branch cannot
-# fast-forward: the push is refused and the verdict is lost (Pliny-Bot run 33952565835). The
-# worker must start on the pull request branch and must never say `git rebase`. Its progress
-# comment is posted on the first attempt only; retries are recorded by the attempt comment.
-BRANCH_OK=1
-# Path B: staged safe outputs, applied by conclude with the App token. Without `staged: true`
-# gh-aw's safe_outputs job writes too, and it runs first: it pushed a flattened single-parent
-# commit with GITHUB_TOKEN, which lost the agent's merge, left the pull request conflicting,
-# and started no CI, because GITHUB_TOKEN writes raise no events.
-if ! grep -qE '^  staged: true' "$MERGE_GATE_WORKER_MD"; then
-  BRANCH_OK=0; echo "FAIL: merge-gate safe-outputs must be staged; conclude owns the write path" >&2
-fi
-if grep -q 'git rebase' "$MERGE_GATE_WORKER_MD"; then
-  BRANCH_OK=0; echo "FAIL: merge-gate worker tells the agent to rebase; the push is fast-forward only" >&2
-fi
-if ! grep -q 'name: Check out the pull request branch' "$MERGE_GATE_WORKER_MD"; then
-  BRANCH_OK=0; echo "FAIL: merge-gate worker must check out the pull request branch before the agent starts" >&2
-fi
-if ! grep -qF "conclusion == 'failure' && (inputs.attempts_so_far || '0') == '0'" "$MERGE_GATE_WORKER_MD"; then
-  BRANCH_OK=0; echo "FAIL: the reserve job's progress comment must be posted on the first attempt only" >&2
-fi
-# A conflicting pull request has no CI run to read logs from, so the gate is handed empty
-# failure artifacts. Read on its own that looks like "no evidence", and the agent asked for a
-# human instead of resolving the conflict that caused it.
-if ! grep -qF 'Empty failure evidence is not a reason to ask for review' "$MERGE_GATE_WORKER_MD"; then
-  BRANCH_OK=0
-  echo "FAIL: the gate must treat empty failure evidence on a conflicting PR as the conflict to fix" >&2
+if worker_installed merge-gate; then
+  # The agent's fix reaches the branch as a bundle applied fast-forward only (apply-agent-output).
+  # gh-aw's push tool description tells the model to rebase, and a rebased branch cannot
+  # fast-forward: the push is refused and the verdict is lost (Pliny-Bot run 33952565835). The
+  # worker must start on the pull request branch and must never say `git rebase`. Its progress
+  # comment is posted on the first attempt only; retries are recorded by the attempt comment.
+  BRANCH_OK=1
+  # Path B: staged safe outputs, applied by conclude with the App token. Without `staged: true`
+  # gh-aw's safe_outputs job writes too, and it runs first: it pushed a flattened single-parent
+  # commit with GITHUB_TOKEN, which lost the agent's merge, left the pull request conflicting,
+  # and started no CI, because GITHUB_TOKEN writes raise no events.
+  if ! grep -qE '^  staged: true' "$MERGE_GATE_WORKER_MD"; then
+    BRANCH_OK=0; echo "FAIL: merge-gate safe-outputs must be staged; conclude owns the write path" >&2
+  fi
+  if grep -q 'git rebase' "$MERGE_GATE_WORKER_MD"; then
+    BRANCH_OK=0; echo "FAIL: merge-gate worker tells the agent to rebase; the push is fast-forward only" >&2
+  fi
+  if ! grep -q 'name: Check out the pull request branch' "$MERGE_GATE_WORKER_MD"; then
+    BRANCH_OK=0; echo "FAIL: merge-gate worker must check out the pull request branch before the agent starts" >&2
+  fi
+  if ! grep -qF "conclusion == 'failure' && (inputs.attempts_so_far || '0') == '0'" "$MERGE_GATE_WORKER_MD"; then
+    BRANCH_OK=0; echo "FAIL: the reserve job's progress comment must be posted on the first attempt only" >&2
+  fi
+  # A conflicting pull request has no CI run to read logs from, so the gate is handed empty
+  # failure artifacts. Read on its own that looks like "no evidence", and the agent asked for a
+  # human instead of resolving the conflict that caused it.
+  if ! grep -qF 'Empty failure evidence is not a reason to ask for review' "$MERGE_GATE_WORKER_MD"; then
+    BRANCH_OK=0
+    echo "FAIL: the gate must treat empty failure evidence on a conflicting PR as the conflict to fix" >&2
+  fi
+  if [ "$BRANCH_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
+  # pr-pending means a pull request for this issue is open and waiting. Only merging retires it.
+  # Every other path (the protected-files hold, a review verdict, a failed attempt) leaves the
+  # pull request open, and stripping the label there produced a board where issues with open
+  # pull requests looked like they had none. It went unnoticed while the label actions silently
+  # removed nothing, so the two bugs hid each other.
+  PENDING_OK=1
+  grep -q '^  PR_PENDING_LABEL:' "$MERGE_GATE_WORKER_MD" ||
+    { PENDING_OK=0; echo "FAIL: merge gate lost its PR_PENDING_LABEL definition" >&2; }
+  if [ "$(count -c '\${{ env.PR_PENDING_LABEL }}' "$MERGE_GATE_WORKER_MD")" -ne 1 ]; then
+    PENDING_OK=0
+    echo "FAIL: pr-pending must be removed in exactly one place, the merge path" >&2
+    grep -n '\${{ env.PR_PENDING_LABEL }}' "$MERGE_GATE_WORKER_MD" >&2
+  fi
+  # And that one place has to be the merge outcome, not a hold or a failed attempt.
+  grep -B12 '\${{ env.PR_PENDING_LABEL }}' "$MERGE_GATE_WORKER_MD" | grep -q "outcome == 'merge'" ||
+    { PENDING_OK=0; echo "FAIL: the only pr-pending removal must sit under the merge outcome" >&2; }
+
+  # The invariant only ever looked at the merge gate, so apply-review quietly stripped the label
+  # on its already-satisfied and needs-human paths — both of which leave the pull request open.
+  # The one file the check ignored was the one breaking it. Look at every worker: implement adds
+  # the label, merge-gate removes it on merge, nobody else may touch it.
+  for worker in "${WORKFLOWS_DIR}"/agent-*.md; do
+    [ -f "$worker" ] || continue
+    case "$(basename "$worker")" in
+      agent-merge-gate.md | agent-implement.md) continue ;;
+    esac
+    if grep -q 'remove-issue-labels' "$worker" &&
+      grep -A8 'remove-issue-labels' "$worker" | grep -q 'env.PR_PENDING_LABEL'; then
+      PENDING_OK=0
+      echo "FAIL: $(basename "$worker") removes pr-pending; only the merge gate's merge path may" >&2
+    fi
+  done
+  if [ "$PENDING_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
-if [ "$BRANCH_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
-
-# pr-pending means a pull request for this issue is open and waiting. Only merging retires it.
-# Every other path (the protected-files hold, a review verdict, a failed attempt) leaves the
-# pull request open, and stripping the label there produced a board where issues with open
-# pull requests looked like they had none. It went unnoticed while the label actions silently
-# removed nothing, so the two bugs hid each other.
-PENDING_OK=1
-grep -q '^  PR_PENDING_LABEL:' "$MERGE_GATE_WORKER_MD" ||
-  { PENDING_OK=0; echo "FAIL: merge gate lost its PR_PENDING_LABEL definition" >&2; }
-if [ "$(grep -c '\${{ env.PR_PENDING_LABEL }}' "$MERGE_GATE_WORKER_MD")" -ne 1 ]; then
-  PENDING_OK=0
-  echo "FAIL: pr-pending must be removed in exactly one place, the merge path" >&2
-  grep -n '\${{ env.PR_PENDING_LABEL }}' "$MERGE_GATE_WORKER_MD" >&2
+
+if worker_installed implement; then
+  # A provider outage kills a run in a couple of minutes with no answer, and the same issue used
+  # to be handed to a human for it. The implement worker retries those and only those: a run that
+  # worked for half an hour and then failed produced an answer that was wrong, and repeating it
+  # costs the fleet the same half hour to be wrong again.
+  IMPLEMENT_RETRY_OK=1
+  for needle in 'RETRY_UNDER_MINUTES' 'ATTEMPT_MARKER' 'attempts_so_far' 'operation=implement'; do
+    grep -qF "$needle" "$IMPLEMENT_WORKER_MD" || {
+      IMPLEMENT_RETRY_OK=0
+      echo "FAIL: implement worker lost its retry belt: no '$needle'" >&2
+    }
+  done
+  # Park and retry are mutually exclusive: the retry path must never add the review label, and
+  # the park path must never re-dispatch.
+  grep -A3 'Flag for human review' "$IMPLEMENT_WORKER_MD" | grep -q "retry != 'true'" ||
+    grep -B3 'Flag for human review' "$IMPLEMENT_WORKER_MD" | grep -q "retry != 'true'" || {
+      IMPLEMENT_RETRY_OK=0
+      echo "FAIL: the implement worker must not flag review on a run it is about to retry" >&2
+    }
+  if [ "$IMPLEMENT_RETRY_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
-# And that one place has to be the merge outcome, not a hold or a failed attempt.
-grep -B12 '\${{ env.PR_PENDING_LABEL }}' "$MERGE_GATE_WORKER_MD" | grep -q "outcome == 'merge'" ||
-  { PENDING_OK=0; echo "FAIL: the only pr-pending removal must sit under the merge outcome" >&2; }
-if [ "$PENDING_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
-
-# A provider outage kills a run in a couple of minutes with no answer, and the same issue used
-# to be handed to a human for it. The implement worker retries those and only those: a run that
-# worked for half an hour and then failed produced an answer that was wrong, and repeating it
-# costs the fleet the same half hour to be wrong again.
-IMPLEMENT_RETRY_OK=1
-for needle in 'RETRY_UNDER_MINUTES' 'ATTEMPT_MARKER' 'attempts_so_far' 'operation=implement'; do
-  grep -qF "$needle" "$IMPLEMENT_WORKER_MD" || {
-    IMPLEMENT_RETRY_OK=0
-    echo "FAIL: implement worker lost its retry belt: no '$needle'" >&2
-  }
-done
-# Park and retry are mutually exclusive: the retry path must never add the review label, and
-# the park path must never re-dispatch.
-grep -A3 'Flag for human review' "$IMPLEMENT_WORKER_MD" | grep -q "retry != 'true'" ||
-  grep -B3 'Flag for human review' "$IMPLEMENT_WORKER_MD" | grep -q "retry != 'true'" || {
-    IMPLEMENT_RETRY_OK=0
-    echo "FAIL: the implement worker must not flag review on a run it is about to retry" >&2
-  }
-if [ "$IMPLEMENT_RETRY_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 
-# A failed attempt must not strip `implement`: identify-gate-subject refuses an issue
-# without it, so the first crash would starve every retry at the subject check.
-if grep -A6 'Park the issue' "$MERGE_GATE_WORKER_MD" | grep -q 'REVIEW_LABEL' &&
-  ! grep -qF 'labels: ${{ env.WORKING_LABEL }},${{ env.IMPLEMENT_LABEL }}' "$MERGE_GATE_WORKER_MD"; then
-  PASS=$((PASS + 1))
-else
-  FAIL=$((FAIL + 1))
-  echo "FAIL: the incomplete job must keep implement and only park on an exhausted budget" >&2
+if worker_installed merge-gate; then
+  # A failed attempt must not strip `implement`: identify-gate-subject refuses an issue
+  # without it, so the first crash would starve every retry at the subject check.
+  if grep -A9 'Park the issue' "$MERGE_GATE_WORKER_MD" | grep -q 'REVIEW_LABEL' &&
+    ! grep -qF 'labels: ${{ env.WORKING_LABEL }},${{ env.IMPLEMENT_LABEL }}' "$MERGE_GATE_WORKER_MD"; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: the incomplete job must keep implement and only park on an exhausted budget" >&2
+  fi
 fi
 
 # This repository is public. Every route a human can start from a comment, a review or a
@@ -493,6 +775,7 @@ fi
 # writes code. Asserted here because removing the gate would otherwise be a silent, one-line
 # change that nothing fails on.
 for route in refine implement apply-review; do
+  worker_installed "$route" || continue
   if grep -qE "route == '${route}'.*needs\.authorize\.outputs\.trusted == 'true'" "$ROUTER_YML"; then
     PASS=$((PASS + 1))
   else
@@ -503,17 +786,83 @@ done
 
 # Triage runs under a trusted App identity. Outside collaborators are admitted only to
 # the deterministic dispatcher; the worker call itself requires a trusted actor.
-if grep -qE "dispatch-triage:.*" "$ROUTER_YML" && \
-   grep -qE "route == 'triage'.*is_outside_collaborator == 'true'" "$ROUTER_YML" && \
-   grep -qE "route == 'triage'.*trusted == 'true'" "$ROUTER_YML"; then
-  PASS=$((PASS + 1))
-else
-  FAIL=$((FAIL + 1))
-  echo "FAIL: route 'triage' does not dispatch outside collaborators and require a trusted worker actor" >&2
+if worker_installed triage; then
+  if grep -qE "dispatch-triage:.*" "$ROUTER_YML" && \
+     grep -qE "route == 'triage'.*is_outside_collaborator == 'true'" "$ROUTER_YML" && \
+     grep -qE "route == 'triage'.*trusted == 'true'" "$ROUTER_YML"; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: route 'triage' does not dispatch outside collaborators and require a trusted worker actor" >&2
+  fi
 fi
 
-for route in refine implement triage apply-review merge-gate audit bot-approve \
-  audit-close cleanup-artifacts reconcile-bot-pr-runs validate release; do
+# Out of scope is the wrong door, not a rejection, and it must never close an issue. Numa#654
+# was a reproducible authorization defect that passed nine of ten checks and was closed as
+# not_planned with every label stripped, so nobody would ever have found it. The verdict for
+# that case is needs-maintainer: open, review label, a maintainer adds refine to take it on.
+# Only block closes, and only for work that cannot be done or is unsafe.
+if worker_installed triage; then
+  TRIAGE_WORKER_MD="${WORKFLOWS_DIR}/agent-triage.md"
+  VALIDATE_TRIAGE_SH="${HERE}/../validate-triage-output/validate-triage-output.sh"
+  TRIAGE_OK=1
+
+  # The validator is what turns the agent's prose into the outcome the jobs branch on. A
+  # verdict it does not know becomes "invalid", which skips conclude entirely and reports the
+  # run incomplete, so the prompt and this script have to agree on all four names.
+  # Comment lines stripped first: the file explains the verdicts in prose above the program,
+  # and a plain search finds the name there even after it has been dropped from the jq
+  # alternation, which is exactly the regression this is meant to catch.
+  validate_program=$(grep -v '^[[:space:]]*#' "$VALIDATE_TRIAGE_SH")
+  for verdict in pass needs-info needs-maintainer block; do
+    if [ "$(count -c -- "$verdict" <<<"$validate_program")" -lt 3 ]; then
+      TRIAGE_OK=0
+      echo "FAIL: validate-triage-output.sh does not accept the '${verdict}' verdict in test(), capture() and the guard" >&2
+    fi
+    if ! grep -qF "\`**Verdict:** ${verdict}\`" "$TRIAGE_WORKER_MD"; then
+      TRIAGE_OK=0
+      echo "FAIL: the triage prompt does not offer '**Verdict:** ${verdict}'" >&2
+    fi
+  done
+
+  # The assertion this whole route turns on: exactly one step closes an issue, and it is
+  # reached only by a block verdict.
+  closes=$(count -c "state: 'closed'" "$TRIAGE_WORKER_MD")
+  if [ "$closes" -ne 1 ]; then
+    TRIAGE_OK=0
+    echo "FAIL: agent-triage.md closes an issue in ${closes} places; expected exactly one" >&2
+  elif ! grep -B12 "state: 'closed'" "$TRIAGE_WORKER_MD" | grep -q "outcome == 'block'"; then
+    TRIAGE_OK=0
+    echo "FAIL: the triage close step is not guarded on a block verdict alone" >&2
+  fi
+  if grep -q "outcome == 'needs-maintainer'" "$TRIAGE_WORKER_MD"; then
+    if grep -A6 "outcome == 'needs-maintainer'" "$TRIAGE_WORKER_MD" | grep -q "state: 'closed'"; then
+      TRIAGE_OK=0
+      echo "FAIL: a needs-maintainer verdict closes the issue; it must stay open" >&2
+    fi
+  else
+    TRIAGE_OK=0
+    echo "FAIL: agent-triage.md has no needs-maintainer branch in conclude" >&2
+  fi
+
+  # Parked, not looping: review goes on so a human sees it, triage comes off so a later
+  # comment does not re-enter triage and put it out of scope again for ever.
+  maintainer_block=$(sed -n "/outcome == 'needs-maintainer'/,/outcome == 'block'/p" "$TRIAGE_WORKER_MD")
+  grep -q 'env.REVIEW_LABEL' <<<"$maintainer_block" || {
+    TRIAGE_OK=0
+    echo "FAIL: the needs-maintainer branch does not add the review label" >&2
+  }
+  grep -q 'env.TRIAGE_LABEL' <<<"$maintainer_block" || {
+    TRIAGE_OK=0
+    echo "FAIL: the needs-maintainer branch does not remove the triage label, so comments would re-trigger triage" >&2
+  }
+
+  if [ "$TRIAGE_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
+# Every installed worker and every plumbing route has a job; a worker that is not installed
+# has none, or the router would call a lock file that does not exist.
+for route in "${INSTALLED_ROUTES[@]}" "${PLUMBING_ROUTES[@]}"; do
   if grep -q "route == '${route}'" "$ROUTER_YML"; then
     PASS=$((PASS + 1))
   else
@@ -521,6 +870,14 @@ for route in refine implement triage apply-review merge-gate audit bot-approve \
     echo "FAIL: work-router.yml has no job for route '${route}'" >&2
   fi
 done
+for route in "${EXCLUDED_ROUTES[@]}"; do
+  if grep -q "route == '${route}'" "$ROUTER_YML"; then
+    FAIL=$((FAIL + 1))
+    echo "FAIL: work-router.yml has a job for route '${route}' but agent-${route}.md is not installed" >&2
+  else
+    PASS=$((PASS + 1))
+  fi
+done
 
 while read -r operation; do
   if grep -q "route == '${operation}'" "$ROUTER_YML"; then
@@ -536,7 +893,7 @@ done < <(sed -n '/^      operation:/,/^      issue-number:/p' "$ROUTER_YML" |
 # contents and issues and failed nightly on a 403 that named the endpoint and nothing else.
 # Paired job-to-scope rather than parsed out of each action: the jobs that touch pull
 # requests are few and known, and naming them here is what makes the omission visible.
-for pr_job in audit-close reconcile-bot-pr-runs detect-pr-conflicts; do
+for pr_job in audit-close reconcile-bot-pr-runs detect-pr-conflicts housekeeping; do
   if ! grep -q "^  ${pr_job}:$" "$ROUTER_YML"; then
     continue
   fi
@@ -552,10 +909,330 @@ done
 # No written-down passwords in anything this repository ships. A throwaway credential for
 # a test container is still a policy finding, and one sat in every consumer's CI for weeks
 # until a scan found it rather than us. Two shapes: a password-ish name assigned a quoted
+echo "── Housekeeping ──────────────────────────────────────────────────────────"
+
+# The janitor is the only thing in the fleet that deletes a branch and closes an issue nobody
+# asked it to close, and it runs unattended every six hours. Its guardrails are one-line
+# conditions that would be easy to lose in an edit and impossible to notice afterwards, so
+# they are asserted rather than trusted.
+HOUSEKEEPING_YML="${HERE}/../housekeeping/action.yml"
+if [ -f "$HOUSEKEEPING_YML" ]; then
+  HK_OK=1
+  hk() {
+    grep -qE "$1" "$HOUSEKEEPING_YML" || { HK_OK=0; echo "FAIL: housekeeping ${2}" >&2; }
+  }
+
+  # Every write goes through act(), which is the only place dry-run is honoured. A second
+  # write path would make --dry-run a lie exactly once, on the run that deletes something.
+  hk 'const act = async' 'has no act\(\) wrapper, so dry-run cannot be enforced in one place'
+  writes=$(count -cE 'github\.rest\.(issues\.(create|update|createComment|removeLabel|addLabels)|git\.deleteRef|actions\.createWorkflowDispatch)\(' "$HOUSEKEEPING_YML")
+  outside=$(awk '
+    /await act\(/ { inact = 1 }
+    inact && /github\.rest\.(issues\.(create|update|createComment|removeLabel|addLabels)|git\.deleteRef|actions\.createWorkflowDispatch)\(/ { seen++ }
+    inact && /^          \}\);$/ { inact = 0 }
+    END { print seen + 0 }
+  ' "$HOUSEKEEPING_YML")
+  if [ "$writes" -ne "$outside" ]; then
+    HK_OK=0
+    echo "FAIL: housekeeping performs ${writes} write(s) but only ${outside} are inside act(); dry-run would not cover the rest" >&2
+  fi
+
+  # A branch is someone's work until its pull request is finished. All three guards have to
+  # hold: never the default branch, never one with an open pull request, and never one whose
+  # pull requests were not all opened by a bot.
+  hk "branch\.name === defaultBranch. continue" 'can delete the default branch'
+  hk "p\.state === 'open'\)\) continue" 'can delete a branch whose pull request is still open'
+  hk 'isBot\(p\.user' 'can delete a branch from a human pull request'
+  hk 'forBranch\.length === 0. continue' 'can delete a branch that never had a pull request'
+
+  # Retrying a decision reproduces it. Only a park the machine caused carries `stalled`, and
+  # only those may be re-dispatched; everything else is reported.
+  hk "labels\.includes\('stalled'\)" 'retries parks that were decisions, not machine failures'
+  # Match the guard, not the phrase. `attempts >= maxRetries` also appears in the line that
+  # labels the digest entry, so grepping for the words alone still passed with the guard
+  # deleted from the `if` -- the same weak-assertion shape that let a deleted triage verdict
+  # through because the words survived in a comment.
+  hk 'if \(attempts >= maxRetries \|\| !work\) \{' 'has no retry budget guard on the retry path'
+
+  # The janitor closes issues, and the only issues it may close are a split parent whose
+  # children are all done and its own digest. Anything else is a person's to close.
+  closes=$(count -cE "state: 'closed'" "$HOUSEKEEPING_YML")
+  if [ "$closes" -eq 2 ]; then
+    PASS=$((PASS + 1))
+  else
+    HK_OK=0
+    echo "FAIL: housekeeping closes issues in ${closes} place(s); only the split parent and its own digest are allowed" >&2
+  fi
+
+  # A retry is a workflow_dispatch, and GitHub starts no workflow run from an event raised
+  # with GITHUB_TOKEN. Wiring the default token here would make every retry a silent no-op:
+  # green run, comment posted, labels removed, and nothing ever picks the issue up again.
+  hk_job=$(sed -n '/^  housekeeping:$/,/^  [a-z0-9_-]*:$/p' "$ROUTER_YML")
+  if printf '%s' "$hk_job" | grep -q 'app-token.outputs.token'; then
+    PASS=$((PASS + 1))
+  else
+    HK_OK=0
+    echo "FAIL: the housekeeping job passes a token that cannot start a workflow run; retries would silently do nothing" >&2
+  fi
+  # Deleting a ref needs contents: write. Without it every delete answers 403 and the sweep
+  # reports success having removed nothing.
+  if printf '%s' "$hk_job" | grep -qE '^      contents: write$'; then
+    PASS=$((PASS + 1))
+  else
+    HK_OK=0
+    echo "FAIL: the housekeeping job deletes branches but grants no contents: write scope" >&2
+  fi
+
+  # Every knob the action takes is a repository's to change, so each has to come from the
+  # router's env: block, which is the one part of the file `workflows update` preserves.
+  for knob in HOUSEKEEPING_RETRY_AFTER_HOURS HOUSEKEEPING_MAX_RETRIES HOUSEKEEPING_STALE_PR_DAYS HOUSEKEEPING_DIGEST_TITLE; do
+    if [ -n "$(router_env "$knob")" ] && printf '%s' "$hk_job" | grep -q "env.${knob}"; then
+      PASS=$((PASS + 1))
+    else
+      HK_OK=0
+      echo "FAIL: ${knob} is not both declared in the router env: block and read by the housekeeping job" >&2
+    fi
+  done
+
+  if [ "$HK_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
+# The audit chain closes its own reports, and every way it can be wrong is silent: a report
+# closed as completed with nothing implemented, or a report pinned open forever so the next
+# audit never runs. Both happened. Assert the three conditions that decide it.
+AUDIT_CLOSE_YML="${HERE}/../audit-close/action.yml"
+if [ -f "$AUDIT_CLOSE_YML" ] && worker_installed audit; then
+  AC_OK=1
+
+  # A report referencing no issues had no work done on it. Closing that as `completed` is how
+  # an audit used to end with every finding closed and nothing implemented.
+  if grep -qE 'resolved === 0\) \{' "$AUDIT_CLOSE_YML" &&
+     ! sed -n '/resolved === 0) {/,/^            }$/p' "$AUDIT_CLOSE_YML" | grep -q "state: 'closed'"; then
+    PASS=$((PASS + 1))
+  else
+    AC_OK=0
+    echo "FAIL: audit-close closes a report that references no issues; nothing was implemented from it" >&2
+  fi
+
+  # Only a real closing keyword may pin a report open. One pattern here required the literal
+  # `#closes #12` and matched nothing; the other matched a bare `#12` anywhere in any open
+  # pull request and pinned the report open for as long as that pull request lived.
+  if grep -q 'clos(?:e|es|ed)' "$AUDIT_CLOSE_YML" && ! grep -qF '#(?:closes?' "$AUDIT_CLOSE_YML"; then
+    PASS=$((PASS + 1))
+  else
+    AC_OK=0
+    echo "FAIL: audit-close still carries the dead '#closes #N' pattern or lost its closing-keyword match" >&2
+  fi
+
+  # The backpressure query has to exclude what the chain marks stale, or three abandoned
+  # reports disable the weekly audit permanently and the run skips green every week.
+  # Read the query line itself, not the file. The prose above it explains what
+  # `-label:stale-audit` is for, so a grep of the whole file passed with the exclusion deleted
+  # from the query -- matching the comment that describes it.
+  AUDIT_WORKER_MD="${WORKFLOWS_DIR}/agent-audit.md"
+  audit_query="$(sed -n 's/^ *query: *"\(.*\)" *$/\1/p' "$AUDIT_WORKER_MD" | head -1)"
+  if [[ "$audit_query" == *-label:stale-audit* ]] && grep -q "STALE_LABEL = 'stale-audit'" "$AUDIT_CLOSE_YML"; then
+    PASS=$((PASS + 1))
+  else
+    AC_OK=0
+    echo "FAIL: the audit backpressure query and audit-close disagree about stale-audit; abandoned reports would block every future audit" >&2
+  fi
+
+  if [ "$AC_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
+echo "── Merge gate park ───────────────────────────────────────────────────────"
+
+# A gate verdict parks the code it was given on. Both dispatch paths -- detect-pr-conflicts and
+# the reconcile belt -- used to compare the standing verdict against the CI finish time, which
+# made the park worthless: any later run on the same commits was newer than the verdict, so the
+# belt re-dispatched a pull request a human already owned and reset its attempt budget at the
+# same time. Lyceum PR #13 sat parked for six days while that happened. Asserted because both
+# comparisons are one line and neither failing produces a red run.
+if worker_installed merge-gate; then
+  GATE_OK=1
+
+  # Neither path may key the park to CI timing again.
+  stale_horizon=$(count -cE 'verdict" \\> "\$ci_finished"|latest_verdict" \\> "\$ci_finished"' "$ROUTER_YML")
+  if [ "$stale_horizon" -eq 0 ]; then
+    PASS=$((PASS + 1))
+  else
+    GATE_OK=0
+    echo "FAIL: the merge-gate park is keyed to the CI finish time in ${stale_horizon} place(s); a CI re-run would reopen a park a person owns" >&2
+  fi
+
+  # Both must fall back to the CI time only when the head commit cannot be read.
+  horizons=$(count -cE '\$\{head_committed:-\$ci_finished\}' "$ROUTER_YML")
+  if [ "$horizons" -eq 2 ]; then
+    PASS=$((PASS + 1))
+  else
+    GATE_OK=0
+    echo "FAIL: ${horizons} of the 2 gate dispatch paths key their park to the head commit" >&2
+  fi
+
+  # One cap, not four literals, and it has to match what the worker tells the reader.
+  router_cap="$(router_env MAX_GATE_ATTEMPTS)"
+  worker_cap="$(sed -n 's/^  MAX_ATTEMPTS: "\([0-9]*\)"$/\1/p' "${WORKFLOWS_DIR}/agent-merge-gate.md" | head -1)"
+  if [ -n "$router_cap" ] && [ "$router_cap" = "$worker_cap" ]; then
+    PASS=$((PASS + 1))
+  else
+    GATE_OK=0
+    echo "FAIL: the belt gives up after '${router_cap:-unset}' attempts but agent-merge-gate.md tells the reader '${worker_cap:-unset}'" >&2
+  fi
+  # And no path may go back to a literal. Counting the word `6` would match a hundred things,
+  # so this looks only at the attempt comparison and the message beside it.
+  if ! grep -qE '"\$attempts" -ge 6|attempts \+ 1\)\) of 6' "$ROUTER_YML"; then
+    PASS=$((PASS + 1))
+  else
+    GATE_OK=0
+    echo "FAIL: the gate attempt cap is hardcoded in work-router.yml instead of read from env.MAX_GATE_ATTEMPTS" >&2
+    grep -nE '"\$attempts" -ge 6|attempts \+ 1\)\) of 6' "$ROUTER_YML" >&2
+  fi
+
+  if [ "$GATE_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
+# `length()`, no `replace()`, and calling one is not a warning: the workflow fails to load with
+# "Unrecognized function", which shows up as a run that never starts. `split(env.REPO, '/')[0]`
+# was written into a template here and only caught by hand. actionlint would find it, but it
+# does not read composite manifests and is not installed in every consumer, so the same rule
+# lives here where the rest of the invariants are.
+readonly GH_EXPRESSION_FUNCTIONS='contains|startsWith|endsWith|format|join|toJSON|toJson|fromJSON|fromJson|hashFiles|success|always|cancelled|failure'
+EXPR_OK=1
+while IFS= read -r workflow; do
+  # Only inside an expression. The same word in a `run:` block is shell or JavaScript.
+  offenders="$(grep -oE '\$\{\{[^}]*\}\}' "$workflow" |
+    grep -oE '[a-zA-Z_][a-zA-Z0-9_]*\(' |
+    tr -d '(' |
+    grep -vE "^(${GH_EXPRESSION_FUNCTIONS})$" |
+    sort -u || true)"
+  if [ -n "$offenders" ]; then
+    EXPR_OK=0
+    echo "FAIL: $(basename "$workflow") calls $(echo "$offenders" | tr '\n' ' ')which GitHub expressions do not have; the workflow will not load" >&2
+  fi
+done < <(find "$WORKFLOWS_DIR" "${HERE}/../.." -maxdepth 3 -name '*.yml' -not -name '*.lock.yml' 2>/dev/null | sort -u)
+if [ "$EXPR_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
+echo "── Error report privacy ──────────────────────────────────────────────────"
+
+# Every repository that installs this package is private, and the error report is the only job
+# that sends anything out of one. Its whole safety argument is four properties, each of which
+# is one line that an edit could remove without any run going red, so all four are asserted.
+ERROR_REPORT_YML="${HERE}/../report-workflow-errors/action.yml"
+if [ -f "$ERROR_REPORT_YML" ]; then
+  ER_OK=1
+  er() {
+    grep -qE "$1" "$ERROR_REPORT_YML" || { ER_OK=0; echo "FAIL: report-workflow-errors ${2}" >&2; }
+  }
+
+  # 1. The scanner, and its teeth. A body that trips it must not be filed, and the run must go
+  # red so the field that carried private text gets fixed instead of leaking again tomorrow.
+  #
+  # Match the declaration and count the sites, never the bare symbol. A grep for `leakChecks`
+  # passed with the declaration renamed, because the name survives where scan() uses it, and a
+  # grep for `core.setFailed` passed with one of the two calls turned into core.info. Both of
+  # those were mutation-tested and both let a broken privacy guard through.
+  er 'const leakChecks = \[' 'declares no leak scanner'
+  teeth=$(count -cE 'core\.setFailed.*withheld by the leak scanner' "$ERROR_REPORT_YML")
+  if [ "$teeth" -ge 2 ]; then
+    PASS=$((PASS + 1))
+  else
+    ER_OK=0
+    echo "FAIL: report-workflow-errors fails the run on a leak in only ${teeth} of its 2 exit paths" >&2
+  fi
+  # Every write upstream has to be behind a scan. Counting is enough here because both are few
+  # and named, and a new write added without a guard moves the counts apart.
+  scans=$(count -cE 'if \(!scan\(' "$ERROR_REPORT_YML")
+  upstream_writes=$(count -cE 'upstream\.rest\.issues\.(create|update)\(' "$ERROR_REPORT_YML")
+  if [ "$scans" -ge "$upstream_writes" ] && [ "$upstream_writes" -gt 0 ]; then
+    PASS=$((PASS + 1))
+  else
+    ER_OK=0
+    echo "FAIL: report-workflow-errors makes ${upstream_writes} upstream write(s) behind only ${scans} leak scan(s)" >&2
+  fi
+  for guard in 'the repository name' 'the owner name' 'a github.com URL' 'an email address' 'an absolute path'; do
+    er "\{ what: '${guard}', test:" "no longer scans for ${guard}"
+  done
+
+  # 2. The allowlist. A consumer's own workflow name can describe a product, a customer or an
+  # environment; only the names this package gives its own files may be reported.
+  er 'const OWNED = /\^\(work-router' 'has no workflow allowlist, so a repository-specific workflow name could be reported'
+  er 'skippedForeign' 'does not account for the workflows it declined to inspect'
+
+  # 3. No raw log text. The catalogue matches the log tail and only the matched entry's id is
+  # kept; a change that put the matched text in the report would be the leak.
+  #
+  # The finding object is that boundary, because bodyFor() renders a finding, so the check is
+  # on its shape: the fields the object literals actually set must be exactly the declared
+  # reportable list. An earlier version of this tried to spot log text in the body with a
+  # regex over the whole file, and a mutation that added `${finding.logText.slice(0, 400)}`
+  # walked straight past it -- the pattern was case-sensitive and the inserted label said
+  # "Summary". Comparing two sets has no such gap.
+  er 'patternId = CATALOGUE\.find' 'no longer classifies the log through the catalogue'
+  declared=$(sed -n "s/^ *const FINDING_FIELDS = \[\(.*\)\];$/\1/p" "$ERROR_REPORT_YML" |
+    tr -d " '" | tr ',' '\n' | sort -u | tr '\n' ' ')
+  # Every key set in a finding object literal, plus every key assigned onto one afterwards.
+  assigned=$( { sed -n '/const seen = findings\.get/,/^              };$/p' "$ERROR_REPORT_YML" |
+      grep -oE '[a-zA-Z_][a-zA-Z0-9_]*:' | tr -d ':'
+    grep -oE 'seen\.[a-zA-Z_][a-zA-Z0-9_]*' "$ERROR_REPORT_YML" | cut -d. -f2
+  } | sort -u | tr '\n' ' ')
+  if [ -n "${declared// /}" ] && [ "$declared" = "$assigned" ]; then
+    PASS=$((PASS + 1))
+  else
+    ER_OK=0
+    echo "FAIL: report-workflow-errors builds findings with fields that are not the declared reportable set" >&2
+    echo "  declared: ${declared:-(none)}" >&2
+    echo "  assigned: ${assigned:-(none)}" >&2
+  fi
+  # And the run-time half of the same boundary, so a field that arrives by a path the check
+  # above cannot see stops the job instead of being rendered upstream.
+  er 'not in the reportable field list' 'does not check the finding shape at run time'
+
+  # 4. No model. A model asked to summarise a failure paraphrases whatever the log held, which
+  # is the one thing that must not cross the boundary. This job stays deterministic.
+  if grep -qiE '(engine:|opencode|safe-outputs|OPENAI_API_KEY)' "$ERROR_REPORT_YML"; then
+    ER_OK=0
+    echo "FAIL: report-workflow-errors reaches for a model; the report must stay deterministic" >&2
+  else
+    PASS=$((PASS + 1))
+  fi
+
+  # The workflow that drives it is an optional template: installed under .github/workflows in a
+  # consumer, and still in templates/ upstream. Check whichever is present, so the assertions
+  # run in the package's own CI rather than only after somebody installs it.
+  ERROR_REPORT_WORKFLOW="${WORKFLOWS_DIR}/agentics-error-report.yml"
+  [ -f "$ERROR_REPORT_WORKFLOW" ] ||
+    ERROR_REPORT_WORKFLOW="${HERE}/../../templates/agentics/agentics-error-report.yml"
+  if [ -f "$ERROR_REPORT_WORKFLOW" ]; then
+    # It reads this repository and writes nothing to it. A write scope here would mean the job
+    # that talks to another repository can also change this one.
+    if grep -qE '^      (contents|actions): read$' "$ERROR_REPORT_WORKFLOW" &&
+       ! grep -qE '^      [a-z-]+: write$' "$ERROR_REPORT_WORKFLOW"; then
+      PASS=$((PASS + 1))
+    else
+      ER_OK=0
+      echo "FAIL: agentics-error-report.yml grants a write scope; it must be read-only in the repository it reports on" >&2
+    fi
+    # The upstream token is scoped to the upstream repository alone, never the default token.
+    if grep -q 'upstream-token: ${{ steps.upstream-token.outputs.token }}' "$ERROR_REPORT_WORKFLOW" &&
+       grep -qE '^          repositories: \$\{\{ env\.UPSTREAM_NAME \}\}$' "$ERROR_REPORT_WORKFLOW"; then
+      PASS=$((PASS + 1))
+    else
+      ER_OK=0
+      echo "FAIL: agentics-error-report.yml does not scope its upstream token to the upstream repository" >&2
+    fi
+  fi
+
+  if [ "$ER_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
 # value, and a command-line flag given one; a line containing a dollar sign is taken to be
 # an expression or a shell variable and allowed. Paths resolve relative to this script, so
 # upstream this reads the templates and in a consumer it reads the real workflows.
-PASSWORD_SCAN_DIRS=("${HERE}/../../workflows")
+PASSWORD_SCAN_DIRS=("${WORKFLOWS_DIR}")
 [ -d "${HERE}/../../templates/ci" ] && PASSWORD_SCAN_DIRS+=("${HERE}/../../templates/ci")
 [ -d "${HERE}/../../templates/agentics" ] && PASSWORD_SCAN_DIRS+=("${HERE}/../../templates/agentics")
 password_hits=$(