[qa-lead reach 3/3] Serve the pull_request surface from the persona mention router (architect decision (b), ADR-0007 consolidation)

[don-petry]

Story

As the org,
I want the persona mention router to also serve the pull_request event,
so that a persona's PR-advisory surface is delivered by the one published ingress path instead of a second, repo-local runtime.

Decided by solution-architect advisory on petry-projects/.github-private#1869 (2026-09-23), option (b).

Why this repo, and why the router

The qa-lead pull_request advisory (.github/workflows/qa-lead-pr-advisory.yml in .github-private) is self-contained: it sources a local script and calls a local persona-runner-reusable.yml, and has no standards/workflows/ template. It therefore cannot be deployed anywhere.

The architect ruled against publishing a second runtime, citing ADR-0007 (one agent-ingress stub per repo, not one stub per role): ADR-0007 fact 4 already names persona-mention → persona-runner as the fleet's hub-and-spoke model, and a second published runtime "repeats, at the ingress-path level, the exact per-role-stub proliferation ADR-0007 just collapsed."

The router is now the right home: #1134 merged, persona-mention is promoted through v1-stable (all tiers at fde249e0), and #1159 put persona-mention.yml into DEPLOYABLE_WORKFLOWS, so the stub reaches nine repos on the next sweep.

Acceptance Criteria

1. persona-mention-reusable.yml accepts a pull_request-sourced trigger and dispatches the addressed persona's advisory for that PR, alongside the existing comment-mention path. The caller-stub template standards/workflows/persona-mention.yml gains the event; consumers get it by re-sync, never by hand-editing a stub.
2. Stop markers bind on the new path — the hard requirement. A pull_request-sourced dispatch must honour each persona's stop_markers from personas/<id>/interaction.yml exactly as the mention path does (persona-mention router ignores stop_markers (needs-human-review, dev-lead:needs-human) — a human hold stops dev-lead but not a mentioned persona #1133/feat: implement issue #1133 — persona-mention router ignores stop_markers (needs-human-review, dev-lead:needs-human) — a human hold stops dev-lead but not a mentioned persona #1134): skip on a declared marker, fail closed on an unreadable contract or a non-200/404 fetch, refuse when a persona has a manifest but no contract. The architect named this "the real open risk, not the routing choice." Prove it with a test per branch, not by inspection.
3. Which personas fire on pull_request is derived, not hardcoded. Use each manifest's declared surfaces (persona.yml), so enabling another persona needs no edit here — the derive-don't-enumerate rule (Provision <id>:hands-off labels so persona opt-out actually works #756).
4. The existing write-mode gate, opt-out label check, trust floor and agent-marker exclusion apply unchanged on the new path. A PR event must not become an ungated write surface.
5. No behaviour change for the comment-mention path, evidenced by the existing tests still passing untouched.
6. Rollout follows channel discipline: land here, then a maintainer cuts persona-mention and advances v1-next. Do not repoint caller stubs. Note in the PR that .github-private's local qa-lead-pr-advisory.yml is retired only after this reaches the channel (tracked on [qa-lead reach 3/3] The pull_request advisory surface has no deployable form — decide and implement how it ships beyond .github-private .github-private#1869) — retiring it earlier would leave the surface dead.

Tests

In the existing persona-mention-tests.yml suite: PR event with no stop marker → dispatches; with a declared marker → skipped, naming the marker; contract fetch 5xx → job fails (closed); contract 404 for a manifested persona → refuses; persona not declaring the surface → not dispatched; comment-mention path unchanged.

Budget guard

1. Router ingress + derivation + stop-marker enforcement on the new path, with the tests above (AC Addressing PR comments #1–Add workflow, environment, and orchestration guidance #4). This is the commit that matters.
2. Template stub event + docs (AC Addressing PR comments #1 remainder, feat: add Structured Logging and CQRS standards #6 note).

If budget runs low, stop after step 1 with a green PR and list the rest. Do not land the template stub change without the enforcement — a deployed stub whose path ignores stop markers is a fail-open brake fleet-wide.

References

petry-projects/.github-private#1869 (decision + advisory), #1134/#1133 (stop markers in the router), #1159/#1156 (fleet deployment), #1745 (the brake semantics), ADR-0007, ADR-0006.

[don-petry]

Dev-Lead Implementation Plan

Issue: #1165 — [qa-lead reach 3/3] Serve the pull_request surface from the persona mention router (architect decision (b), ADR-0007 consolidation)

Scope

Teach the org persona-mention router (persona-mention-reusable.yml + its pure core scripts/lib/persona-mention.sh) to also serve pull_request events: derive which personas declare an enabled pull_request surface from their manifests, dispatch each PR-advisory, and bind every brake the mention path already binds — stop markers (fail-closed), opt-out, write-mode gate, trust floor, and the bot/agent-marker recursion guards — on the new path. Comment-mention path is left byte-for-byte unchanged.

Implementation Checklist

• scripts/lib/persona-mention.sh — allow pm_manifest_query to forward extra jq args (--arg); add pure, surface-parameterised helpers: pm_surface_decision, pm_surface_trust_floor, pm_surface_gate_label (explicit-surface, no default_mode fallback — derive-don't-enumerate Provision <id>:hands-off labels so persona opt-out actually works #756); add pm_pr_should_route (event pre-filter: bot/marker/trust) and pm_pr_route_verdict (the composed PR gauntlet: stop-marker → write-gate → floor → dispatch, fail-closed on a bad contract/schema). Reuse the existing stop-marker core (pm_stop_markers/pm_first_stop_marker/pm_fetch_disposition) unchanged.
• .github/workflows/persona-mention-reusable.yml — add pull_request to workflow_call triggers-of-record; add a second route-pull-request job (job-level if: mirrors pm_pr_should_route) that lists personas from .github-private, derives the firing set from declared surfaces, and dispatches via pm_pr_route_verdict. The existing route job is untouched. Widen concurrency to serialise per-PR without touching the comment key.
• standards/workflows/persona-mention.yml — caller-stub template gains the pull_request trigger + doc note (budget step 2; no with: forward, so no channel-skew).
• PR note — record the ADR-0007/channel-discipline rollout (land here → maintainer cuts persona-mention/advances v1-stable → sweep → only then retire .github-private's local qa-lead-pr-advisory.yml, tracked on [qa-lead reach 3/3] The pull_request advisory surface has no deployable form — decide and implement how it ships beyond .github-private .github-private#1869). Do not repoint caller stubs.

Tests to Write (in tests/persona_mention.bats)

• pm_surface_decision: enabled pull_request row → true <mode>; absent row → false off (persona not declaring the surface is not dispatched, Provision <id>:hands-off labels so persona opt-out actually works #756); explicit enabled: false → false; no default_mode fallback (unlike mention).
• pm_surface_trust_floor / pm_surface_gate_label for the pull_request surface (surface tightens persona-wide floor; write gate present/absent).
• pm_pr_should_route: blocks bot actor (axis 1), blocks agent-marker body (axis 2), blocks below-floor author, allows a trusted human.
• pm_pr_route_verdict (the AC Add multi-agent isolation strategy using git worktrees #2 proof, per branch not by inspection): no stop marker → dispatch; declared marker present → skip stop-marker <marker> (named); unparseable/false contract → fail closed (non-zero); write-mode not-armed → skip not-armed; write-mode armed → dispatch; write-mode w/ missing gate_label → fail closed; author below persona floor → skip below-floor.
• Contract fetch dispositions reused for the PR path (5xx → fail, 404 → absent/refuse) via existing pm_fetch_disposition.
• Comment-mention path unchanged — all existing tests still pass untouched (AC Add stacked PR strategy and Epic-level workflow guidance #5).

Test Command

bats tests/persona_mention.bats (plus bash .dev-lead/scripts/dev-lead-lint.sh for shellcheck)

[don-petry]

Dev-Lead: Progress (in progress — not yet durable)

Provisional. Nothing is pushed yet; the automation posts the authoritative
completion record (with PR number + head SHA) after the push. Treat the notes
below as intent, not delivered results.

Plan Execution (intended)

Both budget steps were worked in this workspace:

Step 1 — the enforcement (the commit that matters):

• scripts/lib/persona-mention.sh — new pure core for the event surface: pm_surface_decision / pm_surface_trust_floor / pm_surface_gate_label (explicit-surface, no default_mode fallback — derive-don't-enumerate, Provision <id>:hands-off labels so persona opt-out actually works #756), pm_pr_should_route (bot / agent-marker / trust pre-filter), and pm_pr_route_verdict (the composed gauntlet: stop-marker → write-gate → trust-floor → dispatch, fail-closed on a malformed contract or a write surface missing its gate_label). Stop-marker enforcement reuses the existing pm_stop_markers / pm_first_stop_marker / pm_fetch_disposition core unchanged. pm_manifest_query now forwards extra jq args (--arg surface …), backward-compatible.
• .github/workflows/persona-mention-reusable.yml — a second, independent route-pull-request job (the comment route job is untouched). It derives the firing set by listing personas in .github-private and consulting each manifest's declared pull_request surface, then runs the same brake gauntlet before dispatching. pull_request fetch of a contract mirrors the manifest fetch (200 read / 404 refuse / else fail-closed).

Step 2 — template + docs:

• standards/workflows/persona-mention.yml — caller-stub template gains the pull_request trigger (no with: forward, so no channel-skew), with a note that the path activates only once the pinned channel advances.

Local check output (provisional — not the pushed run)

bats tests/persona_mention.bats      → 89 checks, 0 failing (66 pre-existing untouched + 23 new)
shellcheck -x scripts/lib/persona-mention.sh   → clean
actionlint (pinned 1.7.7) .github/workflows/persona-mention-reusable.yml + stub  → clean
bash .dev-lead/scripts/dev-lead-lint.sh  → all checks passed

Also ran the embedded PR-routing glue against stubbed gh/curl: happy path dispatches with client_payload[surface]=pull_request; stop-marker / opt-out / no-PR-surface skip without dispatch; contract 5xx fails the job; contract 404 for a manifested persona refuses. (Pre-existing, unrelated tests/test_bootstrap_new_repo.bats DRY_RUN failures exist on a clean tree and are not touched by this change.)

Files touched (this workspace, not yet pushed)

• scripts/lib/persona-mention.sh
• .github/workflows/persona-mention-reusable.yml
• standards/workflows/persona-mention.yml
• tests/persona_mention.bats

Notes — rollout & channel discipline (AC #6), for the PR body

• Land here first. A maintainer then cuts persona-mention and advances the channel (v1-stable) to a commit that includes the route-pull-request job; only then does the sweep carry the updated stub (with the pull_request trigger) to consumers. Do not repoint caller stubs.
• .github-private's local qa-lead-pr-advisory.yml is retired only after this reaches the channel (tracked on [qa-lead reach 3/3] The pull_request advisory surface has no deployable form — decide and implement how it ships beyond .github-private .github-private#1869). Retiring it earlier would leave the PR-advisory surface dead.
• Until the channel advances, a synced stub's pull_request trigger is a harmless no-op (the pre-channel reusable's jobs don't match the event) — not fail-open, because no dispatch occurs. The enforcement lives in the reusable, so the brake can never ship ahead of the routing.
• Not in scope here (follow-ups): per-action-type filtering from surfaces[].events; fork-PR member advisories (blocked fail-closed by the trust floor / missing secrets, by design); the persona-runner consuming client_payload[surface]=pull_request (owned by .github-private#1869).

[don-petry]

Dev-Lead: Implementation Complete — PR #1167

The implementation for issue #1165 is durable: commits are pushed and a pull request is open. This record is backed by verifiable artifacts you can confirm in one click.

• Pull request: feat: implement issue #1165 — [qa-lead reach 3/3] Serve the pull_request surface from the persona mention router (architect decision (b), ADR-0007 consolidation) #1167
• Head commit: 01e877fb9f8d046f5acd2263e6d55d9b63636e9c
• Net change against main: 4 file(s), +556/-10 lines
• Run: https://github.com/petry-projects/.github/actions/runs/35804269087

Review happens on the PR. Acceptance criteria and test results are evidenced by the PR's diff and CI checks — not asserted here. If a later stage fails, this claim is retracted in place.