Address review feedback on Vouch implementation

- Document @username syntax for targeted vouch commands in VOUCHED.td
- Restrict vouch management to admin, maintain, and write roles
- Scope the housekeeping app token to the required permissions
- Fail closed in the AGENTS.md vouch check if the login is empty
- Clarify that anyone not listed in VOUCHED.td must request a vouch
- Align the AGENTS.md vouch waiver with write access to the repo
- Don't skip vouch commands preceded by whitespace
- Use a sparse checkout to fetch only the unvouched PR message

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.github/VOUCHED.td

@@ -11,7 +11,9 @@
 #
 # Maintainers can vouch for new contributors by commenting "!vouch" on a
 # discussion by the author. Maintainers can also comment "!unvouch" to remove
-# a user, or "!denounce" (optionally "!denounce [username]") to denounce one.
+# the author, or "!denounce" to denounce them. To target a different user,
+# include their handle with an @ (e.g. "!denounce @username"); without the @,
+# the word is treated as a reason and the discussion author is targeted.
 #
 # See https://github.com/mitchellh/vouch for details.
 

.github/workflows/vouch-check-pr.yml

@@ -19,6 +19,8 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          sparse-checkout: .github/vouch-pr-unvouched-message
+          sparse-checkout-cone-mode: false
 
       - name: Check PR author
         uses: mitchellh/vouch/action/check-pr@d66fa29a64600490892131ad87597c30c91fcac4 # v1.5.0

.github/workflows/vouch-manage-by-discussion.yml

@@ -16,7 +16,7 @@ concurrency:
 jobs:
   manage:
     # Skip comments which can't contain a vouch command
-    if: github.repository == 'netbox-community/netbox' && startsWith(github.event.comment.body, '!')
+    if: github.repository == 'netbox-community/netbox' && contains(github.event.comment.body, '!')
     runs-on: ubuntu-latest
     steps:
       # An app token is required to merge the VOUCHED update into the protected default branch
@@ -26,6 +26,9 @@ jobs:
         with:
           app-id: 1076524
           private-key: ${{ secrets.HOUSEKEEPING_SECRET_KEY }}
+          permission-contents: write
+          permission-pull-requests: write
+          permission-discussions: read
 
       - name: Check out repo
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -40,6 +43,7 @@ jobs:
           vouch-keyword: "!vouch"
           denounce-keyword: "!denounce"
           unvouch-keyword: "!unvouch"
+          roles: "admin,maintain,write"
           pull-request: "true"
           merge-immediately: "true"
         env:

AGENTS.md

@@ -281,7 +281,7 @@ GitHub Actions workflows in `.github/workflows/`:
 2. **Issue must be open** — Before opening a PR, verify via `gh issue view <number>` that the referenced issue is currently open. Do not submit a PR against a closed issue.
 3. **Issue must be assigned to you** — Verify that the referenced issue is assigned to the submitting user. Do not open a PR for an issue that is unassigned or assigned to someone else.
 4. **Author must be vouched** — Pull requests are accepted only from contributors listed in `.github/VOUCHED.td` on the default branch; PRs from anyone else are closed automatically. If the submitting user is not listed, do not open the PR; instead, direct them to request a vouch by [starting a discussion](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) in the **Vouch Request** category, written in their own words.
-5. **No exceptions without maintainer status** — These requirements are waived only for project maintainers (members of the `netboxlabs` GitHub organization). All other contributors must satisfy all four checks before a PR is opened.
+5. **No exceptions without maintainer status** — Requirements 1–3 are waived only for project maintainers (members of the `netboxlabs` GitHub organization). Requirement 4 is waived only for users with write access to this repository, regardless of organization membership. All other contributors must satisfy all four checks before a PR is opened.
 
 **Pre-submission checklist for AI agents:**
 
@@ -289,9 +289,10 @@ GitHub Actions workflows in `.github/workflows/`:
 # Confirm the issue is open and assigned before opening a PR
 gh issue view <number> --json state,assignees
 
-# Confirm the submitting user is vouched (no output means not vouched)
-gh api repos/netbox-community/netbox/contents/.github/VOUCHED.td -H "Accept: application/vnd.github.raw" \
-  | grep -iE "^(github:)?$(gh api user -q .login)( |$)"
+# Confirm the submitting user is vouched (fails if the login can't be determined or isn't listed)
+login=$(gh api user -q .login) && [ -n "$login" ] \
+  && gh api repos/netbox-community/netbox/contents/.github/VOUCHED.td -H "Accept: application/vnd.github.raw" \
+  | grep -iE "^(github:)?${login}( |$)" && echo "vouched" || echo "NOT vouched"
 ```
 
 Reject the PR submission and report the problem if the issue is closed, unassigned, or assigned to a different user, or if the submitting user has not been vouched for.

CONTRIBUTING.md

@@ -85,13 +85,13 @@ intake policy](https://github.com/netbox-community/netbox/wiki/Issue-Intake-Poli
   * A maintainer triages the issue and may mark it as needing an owner
   * The issue's author can volunteer to own it, or someone else can
   * A maintainer assigns the issue to whomever volunteers
-  * If they haven't contributed before, the volunteer [requests a vouch](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) (see below)
+  * If they aren't already on the list of vouched contributors, the volunteer [requests a vouch](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) (see below)
   * The volunteer submits a pull request that will resolve the issue
   * A maintainer reviews and merges the pull request, closing the issue
 
 * It's very important that you not submit a pull request until a relevant issue has been opened **and** assigned to you. Otherwise, you risk wasting time on work that may ultimately not be needed.
 
-* Pull requests are accepted only from contributors who have been vouched for by a maintainer. (We use [Vouch](https://github.com/mitchellh/vouch) to manage this.) If you're contributing for the first time, please introduce yourself by [starting a discussion](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) in the **Vouch Request** category, telling us a bit about your background and why you'd like to contribute. Once a maintainer has approved your request, you'll be added to the list of [vouched contributors](https://github.com/netbox-community/netbox/blob/main/.github/VOUCHED.td) and can begin submitting pull requests. Pull requests from contributors who have not been vouched for are closed automatically.
+* Pull requests are accepted only from contributors who have been vouched for by a maintainer. (We use [Vouch](https://github.com/mitchellh/vouch) to manage this.) If you aren't yet listed as a [vouched contributor](https://github.com/netbox-community/netbox/blob/main/.github/VOUCHED.td) (for example, if you're contributing for the first time), please introduce yourself by [starting a discussion](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) in the **Vouch Request** category, telling us a bit about your background and why you'd like to contribute. Once a maintainer has approved your request, you'll be added to the list of vouched contributors and can begin submitting pull requests. Pull requests from contributors who have not been vouched for are closed automatically.
 
 > [!IMPORTANT]
 > Please write your vouch request yourself, in your own words. We want to get to know the person behind the contributions; requests that appear to be generated by AI will not be approved.

docs/development/getting-started.md

@@ -200,8 +200,8 @@ UPDATE_QUERY_COUNTS=1 python manage.py test --keepdb
 
 ## Submitting Pull Requests
 
-!!! note "First-time contributors"
-    Pull requests are accepted only from contributors who have been vouched for by a maintainer. If you haven't contributed to NetBox before, introduce yourself by [starting a discussion](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) in the **Vouch Request** category before submitting your first pull request. Pull requests from contributors who have not been vouched for are closed automatically. See the [contributing guide](https://github.com/netbox-community/netbox/blob/main/CONTRIBUTING.md) for details.
+!!! note "Vouched contributors"
+    Pull requests are accepted only from contributors who have been vouched for by a maintainer. If you aren't yet listed in [`.github/VOUCHED.td`](https://github.com/netbox-community/netbox/blob/main/.github/VOUCHED.td) (for example, if you're contributing for the first time), introduce yourself by [starting a discussion](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) in the **Vouch Request** category before submitting your first pull request. Pull requests from contributors who have not been vouched for are closed automatically. See the [contributing guide](https://github.com/netbox-community/netbox/blob/main/CONTRIBUTING.md) for details.
 
 Once you're happy with your work and have verified that all tests pass, commit your changes and push it upstream to your fork. Always provide descriptive (but not excessively verbose) commit messages. Be sure to prefix your commit message with the word "Fixes" or "Closes" and the relevant issue number (with a hash mark). This tells GitHub to automatically close the referenced issue once the commit has been merged.