diff --git a/.github/workflows/persona-mention.yml b/.github/workflows/persona-mention.yml index f98fdedb7..e166a2bc0 100644 --- a/.github/workflows/persona-mention.yml +++ b/.github/workflows/persona-mention.yml @@ -48,11 +48,27 @@ on: # repository_dispatch, which is exactly the bridge the manifest declares. discussion_comment: types: [created] -# NOTE: reviewer assignment (pull_request/review_requested) is NOT subscribed -# here yet, even though §4 says "Reviewer-assignment counts here too". The -# router has no path for it, and a trigger that fires into a router which + # The router also serves the pull_request EVENT surface (#1165): it derives + # which personas fire from their manifests' declared `pull_request` surfaces + # and dispatches each PR-advisory, binding the same stop-marker / opt-out / + # write-gate / trust-floor brakes as the mention path. This path activates + # once the reusable at the pinned channel below advances to include it — + # rollout is central (bump the channel, then sweep), never a stub edit. + # + # Subscribe only the actions a persona can declare on its `pull_request` + # surface today: opened, ready_for_review, reopened. `synchronize` is NOT + # subscribed — no persona declares it (qa-lead excludes it deliberately) and + # the router would discard every synchronize event once the declared-events + # gate is in, so subscribing it only burns a runner in every repo on every + # push. It would be added here only if a persona declares it. (Reviewer + # assignment, review_requested, is still correctly omitted — see below.) + pull_request: + types: [opened, ready_for_review, reopened] +# NOTE: reviewer assignment (pull_request/review_requested) is still NOT +# subscribed here, even though §4 says "Reviewer-assignment counts here too". +# The router has no path for it — and a trigger that fires into a router which # ignores it is a dead trigger that only burns runs. Tracked as finding 10 in -# petry-projects/.github#755; the trigger lands with the routing, not before. +# petry-projects/.github#755; that trigger lands with its routing, not before. permissions: {} @@ -61,7 +77,7 @@ jobs: permissions: contents: read # the reusable checks out its tooling repo — required, # or the call fails at startup (a reusable is granted - # no more than the caller; §5) + # no more than the caller; persona-standards.md §5) issues: read pull-requests: read uses: petry-projects/.github/.github/workflows/persona-mention-reusable.yml@persona-mention/v1-next # NOSONAR(githubactions:S7637) first-party channel ref diff --git a/personas/qa-lead/README.md b/personas/qa-lead/README.md index 84934c1be..7bd53329a 100644 --- a/personas/qa-lead/README.md +++ b/personas/qa-lead/README.md @@ -47,18 +47,25 @@ is a Class 1 (event-driven) caller that fires on `pull_request: [opened, ready_for_review]` — `synchronize` is deliberately not wired, so a PR gets one advisory as it enters review, not one per push. -This surface is served **locally in `.github-private`** today — the workflow is -self-contained (it `source`s a repo-local gate script and calls the local -persona runtime), **not** a fleet-deployable thin caller stub, so it cannot ship -to another repo by the standards sweep. [ADR-0009](../../docs/architecture/adr/0009-qa-lead-pull-request-surface-routes-through-the-shared-router.md) +That local workflow is self-contained (it `source`s a repo-local gate script and +calls the local persona runtime), **not** a fleet-deployable thin caller stub, +so it cannot ship to another repo by the standards sweep. [ADR-0009](../../docs/architecture/adr/0009-qa-lead-pull-request-surface-routes-through-the-shared-router.md) records the decision (#1869) to route the `pull_request` event through the shared `persona-mention` router instead of publishing a second runtime, so the -surface reaches beyond this repo. The router change is cross-repo; this local -workflow is retired only **after** it lands on the `persona-mention/v1-next` -channel and the #1745 stop-marker semantics are verified on a -`pull_request`-sourced dispatch. - -It reuses the **one** persona runtime +surface reaches beyond this repo. That router path is live on the +`persona-mention/v1-next` channel, and this repo's +[`persona-mention.yml`](../../.github/workflows/persona-mention.yml) stub +subscribes `pull_request` (#2187). + +So the `pull_request` surface is currently served by **both** paths: the local +`qa-lead-pr-advisory.yml` and the router. Both call the shared runtime with +`surface: pull_request`, so they share **one** per-(persona, repo, PR) +concurrency group and the same already-advised marker check. A PR gets one +advisory, not two. The local workflow is retired in a separate issue, only +**after** the router path is verified on real PRs, including the #1745 +stop-marker semantics on a `pull_request`-sourced dispatch. + +The local workflow reuses the **one** persona runtime ([`persona-runner-reusable.yml`](../../.github/workflows/persona-runner-reusable.yml)) — there is no qa-lead-specific runner. Before invoking it, a pure gate ([`scripts/qa-lead-advisory-gate.sh`](../../scripts/qa-lead-advisory-gate.sh), diff --git a/personas/qa-lead/interaction.yml b/personas/qa-lead/interaction.yml index e2f567fb9..f9738df05 100644 --- a/personas/qa-lead/interaction.yml +++ b/personas/qa-lead/interaction.yml @@ -7,16 +7,17 @@ # 1. Mention-routed: a human @petry-projects/qa-lead mention is parsed by the # shared router .github/workflows/persona-mention.yml and bridged # (repository_dispatch:persona-mention) to persona-runner. -# 2. Event-driven PR advisory (#1646 — [qa-lead S3]): qa-lead-pr-advisory.yml -# fires on pull_request:[opened, ready_for_review], gates on real test -# surface (scripts/qa-lead-advisory-gate.sh), and reuses the SAME -# persona-runner-reusable.yml to post one advisory. `synchronize` is -# deliberately NOT wired. This surface is served LOCALLY in .github-private -# today (the workflow is self-contained, not a fleet-deployable thin stub); -# ADR-0009 routes the pull_request event through the shared persona-mention -# router so it reaches beyond this repo (#1869). The local workflow is -# retired only after that router change lands on persona-mention/v1-next and -# the #1745 stop markers are verified on a pull_request-sourced dispatch. +# 2. Event-driven PR advisory (#1646 — [qa-lead S3]): served by BOTH +# qa-lead-pr-advisory.yml (local, self-contained — gates on real test +# surface via scripts/qa-lead-advisory-gate.sh) AND, since #2187, the shared +# persona-mention.yml router, which subscribes pull_request and dispatches +# qa-lead per its declared [opened, ready_for_review] (ADR-0009, #1869). +# Both reuse the SAME persona-runner-reusable.yml with surface=pull_request, +# so they share one per-(persona, repo, PR) concurrency group and the same +# already-advised marker check — a PR gets ONE advisory. `synchronize` is +# deliberately NOT wired. The local workflow is retired (a separate issue) +# only after the router path is verified on real PRs, including the #1745 +# stop markers on a pull_request-sourced dispatch. # NOTE: Private source repositories other than .github-private are out of # scope for the router-served pull_request path: its pre-gate runs with # github.token scoped to .github-private and fails closed when it cannot @@ -27,7 +28,8 @@ # # triggers.events mirror the DEPLOYED on: blocks (AC #3/#8) — the union across # both workflows: persona-mention.yml's issue_comment / pull_request_review_comment -# / discussion_comment PLUS qa-lead-pr-advisory.yml's pull_request. As of #1647 +# / discussion_comment / pull_request PLUS qa-lead-pr-advisory.yml's pull_request +# (the same event, served by both until the local workflow is retired). As of #1647 # persona.yml now AGREES with this contract: the surfaces nothing here serves # (pull_request_review, issues, discussion, check_run) are `enabled: false` there, # kept with notes as intended-future surfaces. The contract records what is @@ -51,7 +53,7 @@ interaction: emits: - "comment:advisory-response" idempotency_key: "one advisory per PR (marker scan) for the event path; one run per mention (source_repo + item_number + comment_url) for the mention path" - concurrency_lane: "qa-lead-pr-advisory- (event path); persona-runner-qa-lead--- (mention path)" + concurrency_lane: "persona-runner-qa-lead--- shared by the local and router-served event paths (local caller also serializes on qa-lead-pr-advisory-); persona-runner-qa-lead--- (mention path)" stop_markers: - qa-lead:hands-off - needs-human-review diff --git a/personas/qa-lead/persona.yml b/personas/qa-lead/persona.yml index 9ca02de94..0abf3ef1d 100644 --- a/personas/qa-lead/persona.yml +++ b/personas/qa-lead/persona.yml @@ -101,7 +101,8 @@ skills: # index-of-record). The truth is recorded in personas/qa-lead/interaction.yml and # enforced by validate-personas.py's surface-liveness invariant (#1647). Only two # surfaces are wired today: `mention` (the shared persona-mention.yml router) and -# `pull_request` (qa-lead-pr-advisory.yml, #1646). The rest are KEPT as +# `pull_request` (both qa-lead-pr-advisory.yml, #1646, and the shared router, #2187, +# until the local workflow is retired). The rest are KEPT as # `enabled: false` with the design intent intact — deleting them would lose it, # leaving them `true` would be the lie the standard forbids. triggers: @@ -112,7 +113,7 @@ triggers: events: [opened, ready_for_review] enabled: true mode: advisory - notes: "Risk assessment + test-coverage review comments on PRs with test surface. Served LOCALLY in .github-private today by qa-lead-pr-advisory.yml (#1646) on [opened, ready_for_review]; this surface is NOT fleet-deployable via a caller stub because that workflow is self-contained, not a thin stub. ADR-0009 routes it through the shared persona-mention router so it reaches beyond .github-private (#1869); the local workflow is retired only after that router change lands on persona-mention/v1-next and the #1745 stop markers are verified on a pull_request-sourced dispatch. `synchronize` is deliberately EXCLUDED (one advisory as a PR enters review, not on every push) — so the declared events match what is deployed. NOTE: The router-served pull_request pre-gate runs with github.token scoped to .github-private; it cannot read private source repositories other than .github-private, so those dispatches fail with a retryable workflow error before advisory generation — such private source repositories are out of scope." + notes: "Risk assessment + test-coverage review comments on PRs with test surface. Served on [opened, ready_for_review] by BOTH the local, self-contained qa-lead-pr-advisory.yml (#1646) AND the shared persona-mention router, which this repo's stub subscribes to pull_request (ADR-0009, #1869, #2187). Both call persona-runner-reusable.yml with surface=pull_request, so they share one per-(persona, repo, PR) concurrency group and the same already-advised marker check — a PR gets ONE advisory. The local workflow is retired (a separate issue) only after the router path is verified on real PRs, including the #1745 stop markers on a pull_request-sourced dispatch. `synchronize` is deliberately EXCLUDED (one advisory as a PR enters review, not on every push) — so the declared events match what is deployed. NOTE: The router-served pull_request pre-gate runs with github.token scoped to .github-private; it cannot read private source repositories other than .github-private, so those dispatches fail with a retryable workflow error before advisory generation — such private source repositories are out of scope." - surface: pull_request_review events: [submitted, created] diff --git a/scripts/persona_reach_check.sh b/scripts/persona_reach_check.sh index 4400c94bc..df467adf3 100755 --- a/scripts/persona_reach_check.sh +++ b/scripts/persona_reach_check.sh @@ -46,9 +46,17 @@ set -euo pipefail # surface beyond the shared mention router. # 3 hard error — bad usage / missing inputs. -# The shared persona-mention router's DEPLOYED trigger events (persona-standards §4.1; -# .github/workflows/persona-mention.yml `on:` block). Anything a persona subscribes -# beyond this set is a NEW trigger surface introduced during promotion. +# The shared persona-mention router's MENTION events (persona-standards §4.1) — the +# set a mention-only persona may be served on. Anything a persona subscribes beyond +# this set is a NEW trigger surface introduced during promotion. +# +# This is deliberately NOT the router's whole `on:` block. Since #2187 the router +# (.github/workflows/persona-mention.yml) also subscribes `pull_request`, but that +# is an EVENT surface a persona must opt into by declaring a `pull_request` surface +# in its manifest — not a mention event. Deriving this set from `on:` would let a +# mention-only persona widen onto pull_request unnoticed, which is exactly the fan-out +# this guard exists to catch, so `pull_request` stays out of it. +# (prc_router_serves_events still reads the real `on:` block for wiring.) PRC_ROUTER_EVENTS="issue_comment pull_request_review_comment discussion_comment" PRC_RING_ORDER="draft canary next ring0 ring1 stable retired" diff --git a/scripts/validate-interaction-model.sh b/scripts/validate-interaction-model.sh index 00fb3a986..c81ea6e9d 100644 --- a/scripts/validate-interaction-model.sh +++ b/scripts/validate-interaction-model.sh @@ -402,6 +402,33 @@ imv_persona_opt_out() { ' "$pf" } +# imv_persona_serves_pr_surface — return 0 iff the persona's manifest +# (personas//persona.yml) declares a `pull_request` surface with +# `enabled: true` and at least one declared event the router subscribes (opened, +# ready_for_review, reopened). The shared persona-mention router derives which personas it +# dispatches on the pull_request EVENT from exactly these manifest surfaces (#1165, +# #2187), so only such a persona is served pull_request by the router. +imv_persona_serves_pr_surface() { + local root="${1:-}" role="${2:-}" pf + pf="$root/personas/$role/persona.yml" + [ -f "$pf" ] || return 1 + awk ' + function flush() { if (cur == "pull_request" && en && ov) found=1; cur=""; en=0; ov=0 } + /^[A-Za-z_]/ { flush() } # a top-level key ends the surfaces list + /^[[:space:]]*-[[:space:]]*surface:/ { + flush() + s=$0; sub(/.*surface:[[:space:]]*/,"",s); gsub(/[\047"]/,"",s); sub(/[[:space:]#].*/,"",s) + cur=s; next + } + cur == "pull_request" && /^[[:space:]]*events:/ { + # only the actions the router subscribes (opened, ready_for_review, reopened) count + if ($0 ~ /[^A-Za-z_](opened|ready_for_review|reopened)[^A-Za-z_]/) ov=1 + } + cur == "pull_request" && /^[[:space:]]*enabled:[[:space:]]*true([[:space:]#]|$)/ { en=1 } + END { flush(); exit found ? 0 : 1 } + ' "$pf" +} + # ── detectors (each prints tagged FAIL lines; none aborts on first finding) ─── # imv_v_completeness — bidirectional §4 completeness (§10). Every @@ -547,7 +574,19 @@ imv_v_contracts() { actual_events=""; actual_crons="" while IFS= read -r wf; do [ -n "$wf" ] || continue - actual_events+="$(imv_on_event_set "$root/$wf")"$'\n' + # The shared persona-mention router's on: block also carries the + # pull_request EVENT surface (#2187), but the router dispatches a persona on + # it only when that persona's manifest enables a pull_request surface. A + # mention-only persona is not served pull_request by the router, so its + # contract is not charged with it. + local role status=0 + role="$(imv_c_role "$c")" || status=$? + if [ "$status" -eq 0 ] && [ "$wf" = ".github/workflows/persona-mention.yml" ] \ + && ! imv_persona_serves_pr_surface "$root" "$role"; then + actual_events+="$(imv_on_event_set "$root/$wf" | grep -vx 'pull_request' || true)"$'\n' + else + actual_events+="$(imv_on_event_set "$root/$wf")"$'\n' + fi actual_crons+="$(imv_on_crons "$root/$wf")"$'\n' done < <(imv_c_workflows "$c") diff --git a/tests/persona_reach_check.bats b/tests/persona_reach_check.bats index 74f7a133e..5f101c08b 100644 --- a/tests/persona_reach_check.bats +++ b/tests/persona_reach_check.bats @@ -43,6 +43,19 @@ setup() { [[ "$output" == *"pull_request"* ]] } +@test "prc_surface_is_mention_only: pull_request stays rejected though the real router subscribes it (#2187)" { + # The router's on: block now carries the pull_request EVENT surface, but + # PRC_ROUTER_EVENTS is the router's MENTION events only: a mention-only + # persona may not widen onto pull_request just because the router serves it. + local router + router="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/.github/workflows/persona-mention.yml" + run prc_router_serves_events "$router" "pull_request" + [ "$status" -eq 0 ] + run prc_surface_is_mention_only "issue_comment,pull_request" + [ "$status" -ne 0 ] + [[ "$output" == *"pull_request"* ]] +} + @test "prc_surface_is_mention_only: rejects an added schedule/cron surface" { run prc_surface_is_mention_only "issue_comment,schedule" [ "$status" -ne 0 ] diff --git a/tests/test_validate_interaction_model.bats b/tests/test_validate_interaction_model.bats index 1f8b9d91c..1225f8fd8 100644 --- a/tests/test_validate_interaction_model.bats +++ b/tests/test_validate_interaction_model.bats @@ -325,6 +325,68 @@ setup() { [ "$output" = "alpha:hands-off" ] } +# --------------------------------------------------------------------------- +# #2187: the shared persona-mention router also subscribes the pull_request EVENT +# surface. It dispatches only personas whose manifest enables a pull_request +# surface, so only THOSE contracts are charged with the router's pull_request. +# --------------------------------------------------------------------------- + +# _router_tree +_router_tree() { + local d="$1" enabled="$2" ev; shift 2 + mkdir -p "$d/.github/workflows" "$d/personas/alpha" + printf 'on:\n issue_comment:\n types: [created]\n pull_request:\n types: [opened, ready_for_review, reopened]\njobs: {}\n' \ + > "$d/.github/workflows/persona-mention.yml" + { + printf 'id: alpha\ntriggers:\n surfaces:\n' + if [ "$enabled" != "absent" ]; then + printf ' - surface: pull_request\n events: [opened]\n enabled: %s\n' "$enabled" + fi + printf ' - surface: mention\n events: [created]\n enabled: true\n' + } > "$d/personas/alpha/persona.yml" + { + printf 'role: alpha\nkind: persona\nworkflows:\n - .github/workflows/persona-mention.yml\ninteraction:\n triggers:\n events:\n' + for ev in "$@"; do printf ' - %s\n' "$ev"; done + printf ' timers: []\n idempotency_key: "k"\n concurrency_lane: "l"\n' + } > "$d/personas/alpha/interaction.yml" +} + +@test "imv_persona_serves_pr_surface: true only for an ENABLED pull_request surface" { + _router_tree "$BATS_TEST_TMPDIR/on" true issue_comment pull_request + run imv_persona_serves_pr_surface "$BATS_TEST_TMPDIR/on" alpha + [ "$status" -eq 0 ] + _router_tree "$BATS_TEST_TMPDIR/off" false issue_comment + run imv_persona_serves_pr_surface "$BATS_TEST_TMPDIR/off" alpha + [ "$status" -ne 0 ] + _router_tree "$BATS_TEST_TMPDIR/none" absent issue_comment + run imv_persona_serves_pr_surface "$BATS_TEST_TMPDIR/none" alpha + [ "$status" -ne 0 ] + run imv_persona_serves_pr_surface "$BATS_TEST_TMPDIR/none" missing + [ "$status" -ne 0 ] +} + +@test "#2187: a mention-only persona is not charged with the router's pull_request" { + _router_tree "$BATS_TEST_TMPDIR/t" absent issue_comment + run imv_v_contracts "$BATS_TEST_TMPDIR/t" + [ -z "$output" ] +} + +@test "#2187: a mention-only persona declaring pull_request still diverges (FAIL[c])" { + _router_tree "$BATS_TEST_TMPDIR/t" false issue_comment pull_request + run imv_v_contracts "$BATS_TEST_TMPDIR/t" + [[ "$output" == *"FAIL[c]"* ]] +} + +@test "#2187: a persona enabling pull_request must declare the router's pull_request (FAIL[c])" { + _router_tree "$BATS_TEST_TMPDIR/t" true issue_comment + run imv_v_contracts "$BATS_TEST_TMPDIR/t" + [[ "$output" == *"FAIL[c]"* ]] + [[ "$output" == *"pull_request"* ]] + _router_tree "$BATS_TEST_TMPDIR/u" true issue_comment pull_request + run imv_v_contracts "$BATS_TEST_TMPDIR/u" + [ -z "$output" ] +} + @test "imv_escalation_label_from parses a := default assignment" { tmp="$(mktemp)" printf ': "${NEEDS_HUMAN_REVIEW_LABEL:=needs-human-review}"\n' > "$tmp"