Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 21 additions & 5 deletions .github/workflows/persona-mention.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,27 @@
# 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: {}

Expand All @@ -60,8 +76,8 @@
persona-mention:
permissions:
contents: read # the reusable checks out its tooling repo — required,
# or the call fails at startup (a reusable is granted

Check warning on line 79 in .github/workflows/persona-mention.yml

View workflow job for this annotation

GitHub Actions / Lint

79:29 [comments-indentation] comment not indented like content
# 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
Expand Down
27 changes: 17 additions & 10 deletions personas/qa-lead/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand Down
26 changes: 14 additions & 12 deletions personas/qa-lead/interaction.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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-<pr> (event path); persona-runner-qa-lead-<source_repo>-<item_number>-<comment_url> (mention path)"
concurrency_lane: "persona-runner-qa-lead-<source_repo>-<pr>- shared by the local and router-served event paths (local caller also serializes on qa-lead-pr-advisory-<pr>); persona-runner-qa-lead-<source_repo>-<item_number>-<comment_url> (mention path)"
stop_markers:
- qa-lead:hands-off
- needs-human-review
Expand Down
5 changes: 3 additions & 2 deletions personas/qa-lead/persona.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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]
Expand Down
14 changes: 11 additions & 3 deletions scripts/persona_reach_check.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
41 changes: 40 additions & 1 deletion scripts/validate-interaction-model.sh
Original file line number Diff line number Diff line change
Expand Up @@ -402,6 +402,33 @@ imv_persona_opt_out() {
' "$pf"
}

# imv_persona_serves_pr_surface <root> <role> — return 0 iff the persona's manifest
# (personas/<role>/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 <root> <md> — bidirectional §4 completeness (§10). Every
Expand Down Expand Up @@ -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")

Expand Down
13 changes: 13 additions & 0 deletions tests/persona_reach_check.bats
Original file line number Diff line number Diff line change
Expand Up @@ -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 ]
Expand Down
62 changes: 62 additions & 0 deletions tests/test_validate_interaction_model.bats
Original file line number Diff line number Diff line change
Expand Up @@ -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 <dir> <pr_surface_enabled:true|false|absent> <contract_events...>
_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"
Expand Down
Loading