[tsapeta]

Stacked on #89.

Why

The docs agent in expo/expo can tell when docs or doc comments change in a way that needs a human review, but it has no way to bring in the docs owner. The agent already runs only on its paths, so it should be able to ask for a person when it decides one is needed.

Change

• A new agent front-matter key mention takes a list of GitHub logins or org/team slugs (an optional leading @ is dropped). It's the only source of whom a review notifies, and CI loads agent files from the base commit, so a PR can't change it.
• An invalid value (not a list, empty, or an entry that isn't a login or team, checked with MENTION_TARGET_RE) is a setup warning and the agent mentions no one, the same policy as paths.
• Reviewer passes can return humanReview: one sentence on why a person should review the change, parsed like summary. The engine keeps the first reason per agent.
• buildMentions turns a reason into a mention only for an agent that ran and has a mention list. attachMentions attaches an engine-owned mentions field and strips any coordinator-written value.
• The comment shows a visible line under the overall summary, like 📣 <logins>: the docs reviewer asks for your review. <reason>. The reason goes through plainModelLine, and the renderer re-checks every login because a re-render reads the state back from the comment body.
• The bot edits its comment in place on re-reviews. GitHub's docs say that an edit which adds a mention also notifies that person, so a mention still notifies when it first appears on a later re-review.
• The shared.md template documents humanReview. README, templates/config.jsonc, LLP 0002, LLP 0005 and LLP 0006 document mention.
• After a release, expo/expo can add mention to its docs agent.

Test Plan

bun test (810 pass), typecheck, lint, fmt:check, llp:check and ecr ref-check all pass.

The new tests fail before the change and pass after. They cover:

• config loading of mention logins and teams
• warnings for invalid values
• humanReview fail-soft parsing
• buildMentions and the coordinator boundary
• the visible line and filtering of an invalid login
• the state round trip and the aggregate comment

I also ran ecr review locally with a scratch docs agent (mention set to octocat, and a prompt asking for humanReview on substantive docs changes) on this branch's README changes. It returned a mention for octocat with the model's reason. I haven't run it against a live PR, so the GitHub notification itself is untested.

[github-actions]

🤖 AI code review

Decision: Ready for human review

Overall PR risk: Medium. The change modifies comment rendering and adds a mentioned state field for agents with mention declarations. Model text with @ or HTML references may render differently, invalid or missing state could cause repeat notifications, and prompt-injected humanReview might trigger unexpected mentions. Blast radius is limited to comment rendering with straightforward rollback.

🔎 Reviewer summaries (3)

• consistency: Checked the new mention front-matter key, the humanReview output field, and the mention rendering against sibling patterns. They follow the paths, agentSummaries, and template conventions. No consistency findings.
• correctness: I checked the new mention/humanReview flow: config parse, engine attach, state round-trip, and every render path. Model text cannot choose whom to notify. Every re-render passes the prior mention state. I found no defects.
• security: I reviewed the new mention feature for security. Only the base-commit agent config supplies logins. The renderer checks each login again and breaks every @​ in model text. I found no exploit path.

🔗 Review setup:

• This PR changes code the reviewer prompts cite (src, src/tests, src/config/load.ts, src/config/schema.ts, src/core/render.ts, and 2 more). Check that the guidance quoting it is still correct.

No findings.

---

This review is advisory — it never blocks a merge and never auto-approves.

[brentvatne]

Review notes from a multi-model review (Codex, Grok and Claude, each finding then re-checked against the code). Fixes are in 7b2eab6, pushed to this branch, and merge 514dada, which also merges #89's fixes so the mention filter stays one function.

1. Model text could still mention anyone (holds). The summary, and each finding's title, rationale, suggestion, source titles and requalification reason, went through stripStateMarkers only, in the single, aggregate and inline bodies. So "only the trusted config names people" didn't hold: a title citing @param or @types/node pings a user or a team.

• Fix: all of them go through modelText (stripStateMarkers + breakMentions), with feat: add per-agent reviewer summaries to the review comment #89's rules: escape @ character references, and break each @ that doesn't follow a letter or digit. Lines and formatting are kept.
• Trade-off: @ inside code in model text gets an invisible zero-width space too (@MainActor, @expo/...), so copying it from the comment carries the character. A backtick doesn't prove a code span (an HTML attribute can hold one), so a code-aware skip would reopen the bypass.

2. In the aggregate comment, a request was hidden when its scope had no findings (holds). The fold only opened for findings, requalified findings or replies. Fix: a mention line opens it.

3. Repeat notifications (holds). GitHub notifies when an edit adds a mention, and humanReview is recomputed every run (and steerable by the PR content), so a request that dropped out and came back notified again.

• Fix: the comment state's new mentioned: { live, notified }. A handle stays live while it stays; one that was notified, left and came back renders as @​login; a new handle still notifies.
• Design call for you: this means a genuinely new request for the same person later on the PR won't ping them. The alternative is to let every return notify. clear() re-creating a comment starts over, which notifies again. That's rare.

4. MENTION_TARGET_RE didn't match GitHub's rules (holds). It rejected EMU logins like name_shortcode, accepted -lead, trail- and dou--ble, and one bad entry made the loader drop the agent's whole mention list.

• Fix: logins are letters, digits and single inner hyphens, at most 39 characters, with an optional _shortcode, and team slugs follow GitHub's rules. A bad entry is left out with a warning naming it, and the rest still load.

5. Team mentions posted with GITHUB_TOKEN (unverified). GitHub notifies only people with read access, and for an org repo, org members. github-actions[bot] isn't one, so @expo/docs may not notify. Now documented as untested; it needs a live check before expo/expo relies on it.

Also: humanReviewReasons and buildMentions take a Map, the same constructor exposure #89 fixed for summaries. The /dismiss and reply credits (by @login) still mention the person who acted; that predates this PR, and the LLP no longer says "only".

Checks: typecheck, bun test (825 pass), lint, format and llp:check pass. Each new test fails with its fix reverted.

[brentvatne]

Follow-up: 6a476c4 merges #89's @@login fix (ce95adc) into breakMentions, so the multi-line model text gets it too. The multi-line test now covers @@run-user.