Disclosure ask on external pull requests: a comment-only workflow under QEP-5

[mmcky]

Goal

One comment, posted once, on every pull request opened from outside the organisation, whose description carries no Assisted-by: line, linking to the Code of AI Use (QuantEcon/qeps#13) and asking the author for two things: add the line to their description, and confirm in a reply that a human has read the pull request and answers for it. Where the template did its job the comment never fires. It is the third visibility channel QEP-5's Adoption section names, beside the pull-request template and the AGENTS.md block.

Why a comment, and not the template or a gate

• The template reaches only the web UI. A pull request opened with gh pr create --body or through the API skips it. That is how the autonomous pipeline behind FIX: remove unused numerical locals QuantEcon.py#923 opened its pull request, and it is how most agent-driven pull requests arrive.
• The ask is the thing that worked. In QEP-5's one field test a neutral question on the thread produced full voluntary disclosure within the hour. The comment automates that question and removes the per-pull-request cost of a maintainer writing it.
• A gate was rejected. QEP-5 declines to hold a newcomer's first pull request behind a registration step. This comment holds nothing and decides nothing; the outcome is a human reading a reply.

Research: how to build it

Option	Finding	Verdict
actions/first-interaction	Fires only on a user's first pull request or issue in the repository. We want every external pull request, and a pipeline's second and third pull requests are exactly the ones that matter. It also comments on issues, which is out of scope for now.	Not a fit
A pull_request_target: opened job with actions/github-script	Filter on the event's author_association (skip OWNER, MEMBER, COLLABORATOR), skip [bot] accounts and any pull request carrying the automated label, search existing comments for a marker so it posts once, then post. Needs pull-requests: write only. About thirty lines.	Recommended
Reusable workflow in QuantEcon/.github, called from each repository	The body lives once; each repository carries a caller of roughly ten lines. Rolling the caller out is the same per-repository stamping problem as AGENTS.md, which QuantEcon/cli#50 proposes to solve.	Recommended delivery
A GitHub App installed org-wide	No per-repository file, but a hosted service to run and a private key to hold. Over-engineered for one comment; revisit only if the caller rollout proves painful.	Defer
Organisation rulesets with a required workflow	Designed for required status checks on pull_request, and would run for members too. Not evaluated further.	Not a fit

Constraints carried from QEP-5

• Comment only. No label, no status check, no hold. Enforcement stays with a maintainer reading the reply.
• Never check out the pull request's code. pull_request_target runs with base-repository permissions and secrets. The job must not run actions/checkout against the fork head; QEP-5 forbids any mechanism that checks out or executes pull-request code while holding write permissions.
• Skip the organisation's own automation. Bot accounts (dependabot[bot], github-actions[bot], quantecon-services) and anything labelled automated under QEP-2.
• Once per pull request, and only when needed. Post only if the description has no Assisted-by: line (any value, including none). A hidden marker in the comment body, checked before posting, so reopening or force-pushing never produces a second comment. An edited event on the description is not needed: the author's reply or edit is read by a human.
• Welcome tone. The comment is the first thing a newcomer sees. It thanks them, links the Code, and asks; it does not warn.

Details found while researching

• Nothing clickable lives in the bot's comment. GitHub lets only the comment's author or someone with write access tick a task list, so an external author cannot tick a box the bot posted. The comment asks for an edit to their own description (the Assisted-by: line) and a reply (the attestation), both of which they can do.
• author_association values are OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR, FIRST_TIMER, NONE, and MANNEQUIN. One thing to verify on a sandbox before relying on it: that MEMBER is reported for organisation members whose membership is private. If not, fall back to an explicit login list.
• Draft pull requests fire opened too, so they get the ask. That is fine.

Draft comment text

Thanks for the pull request! QuantEcon welcomes AI-assisted contributions under our Code of AI Use. Two quick things, please:

1. Add one line to the description above: Assisted-by: <tool> (<model>) if AI tools meaningfully contributed (for example Assisted-by: Claude Code (Claude Fable 5.1)), or Assisted-by: none if they did not.
2. Reply here to confirm that a human chose the task, read the result, and will answer review on it.

Revised 2026-09-11. QEP-5 replaced the checkbox pair with a single Assisted-by: line in three states (tool and model, none, or missing), so the comment now asks for the line and a reply rather than for pasted checkboxes. See the QEP's Adoption section at commit 8824139 on QuantEcon/qeps#13.

Phases

1. Decision: reusable workflow plus stamped caller, or a GitHub App. Recommendation above.
2. Build the reusable workflow in QuantEcon/.github and test it on a sandbox repository, including the private-membership check on author_association.
3. Pilot on QuantEcon.py, where the field test ran.
4. Roll the caller out with the CLI (QuantEcon/cli#50 covers the stamping mechanism).
5. Review after a month: how many external pull requests received the ask, how many answered, and whether the tone needed adjusting.

Blocked on QEP-5's acceptance (QuantEcon/qeps#13). The workflow and the comment text can be drafted and sandbox-tested now.

[mmcky]

@jstac I took your idea of the checkboxes on QEP-5 -- and it has turned into this idea. The issue with templates is that many PRs are now filed via gh cli or APIs so that misses them entirely. I think a QuantEcon bot is the answer here. It also will identify those PRs that are just opened and unwatched.

[mmcky]

The bot can then monitor and if the request is not responded to within 7 days (for example) we could auto-close

[jstac]

Thanks @mmcky , nice idea.