feat(review): automatically label new PRs for accepted work

.agents/skills/create-github-issue/SKILL.md

@@ -137,6 +137,8 @@ GitHub built-in issue types (`Bug`, `Feature`, `Task`) should come from the matc
 
 Creating an issue does not accept it. Follow Label Discovery in `CONTRIBUTING.md` to retrieve every page of current `state:*` label definitions and resolve unclear meanings, then follow its triage → validation → human acceptance process. Agents may assess facts, but only humans decide whether to accept work or place it on the roadmap. A direct user request authorizes the requested planning or implementation phase without changing issue disposition.
 
+Follow [Labeling and Notifications](../../../CONTRIBUTING.md#labeling-and-notifications) for classification labels. Defer area/topic labels until the work is accepted; filing an issue or identifying its subject is not acceptance. Intake workflow labels may still record triage status. Classification can trigger subscribers' GitHub app in Slack and other integration notifications.
+
 ## Useful Options
 
 | Option              | Description                        |

.agents/skills/create-github-pr/SKILL.md

@@ -258,6 +258,11 @@ automatically on issue-label events.
 Created PR [#123](https://github.com/OWNER/REPO/pull/123)
 ```
 
+Follow the shared [accepted-work definition](../../../CONTRIBUTING.md#accepted-work)
+and [Labeling and Notifications](../../../CONTRIBUTING.md#labeling-and-notifications)
+when applying classification labels. Review-readiness applies the acceptance label
+to qualifying PRs when they open; this does not replace existing PR requirements.
+
 ### Monitor Workflow Run (Optional)
 
 If the user asks to wait for a green CI before posting the RFR, use this snippet to monitor the workflow run:

.agents/skills/triage-issue/SKILL.md

@@ -15,6 +15,8 @@ For a specific issue, assess it when requested. For batch triage, first show the
 
 Do not apply an acceptance state, place issues on the roadmap, or make a product investment decision. Do not introduce `agent:*` workflow labels. Follow `SECURITY.md` if the report may disclose a vulnerability; do not copy sensitive details into a public comment.
 
+Follow [Labeling and Notifications](../../../CONTRIBUTING.md#labeling-and-notifications): defer area/topic classification labels until the work is accepted. They drive subscriber notifications, so technical classification alone must not send unaccepted intake to those streams. Continue to record appropriate triage state.
+
 ## Assess one issue
 
 1. Run `gh issue view <id> --json number,title,body,state,labels,author,comments`. Follow Label Discovery in `CONTRIBUTING.md` to retrieve every page of current `state:*` label definitions and resolve unclear meanings. Check for previous triage, new human evidence, an existing owner, and duplicate issues.

.github/CODEOWNERS

@@ -40,5 +40,9 @@
 /tasks/scripts/check_issue_acceptance.cjs @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
 /tasks/scripts/check_issue_acceptance.test.cjs @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
 
+# Accepted-work classification
+/tasks/scripts/label_accepted_work.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
+/tasks/scripts/label_accepted_work_test.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
+
 # Auditable SBOM check
 /tasks/scripts/verify-image-sbom.sh @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr

.github/workflows/branch-checks.yml

@@ -608,6 +608,9 @@ jobs:
 
       - name: Test release qualification summary
         run: mise run test:qualification-summary
+
+      - name: Test accepted-work library and review-readiness
+        run: "mise run test:accepted-work ::: test:review-readiness"
   python-sdk-freeze:
     # The Python SDK moved to ai-openshell/sdk-python (#5287), which imported it
     # at v0.1.7. Its files stay only until core removes them, so PRs must not

.github/workflows/review-readiness.yml

@@ -9,6 +9,7 @@ on:
 
 permissions:
   contents: read
+  issues: read
   pull-requests: write
 
 concurrency:
@@ -19,30 +20,39 @@ jobs:
   reviewers:
     name: OpenShell / Review Readiness
     if: >-
-      !github.event.pull_request.draft &&
-      (github.event.action == 'opened' ||
-       github.event.action == 'ready_for_review' ||
-       startsWith(github.event.label.name, 'area:') ||
-       startsWith(github.event.label.name, 'topic:'))
+      github.event.action == 'opened' ||
+      (!github.event.pull_request.draft &&
+       (github.event.action == 'ready_for_review' ||
+        startsWith(github.event.label.name, 'area:') ||
+        startsWith(github.event.label.name, 'topic:')))
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
       # Use the merged roster and helper, never code from the PR head.
       - name: Check out the reviewer roster and helper
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.event.repository.default_branch }}
           sparse-checkout: |
             REVIEWERS.md
+            MAINTAINERS.md
             tasks/scripts/check_review_readiness.py
+            tasks/scripts/label_accepted_work.py
+            tasks/scripts/check_maintainer_approval.py
           sparse-checkout-cone-mode: false
           persist-credentials: false
 
-      - name: Reconcile reviewer requests
+      - name: Label newly opened accepted work and reconcile reviewers
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GH_REPO: ${{ github.repository }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_ACTION: ${{ github.event.action }}
+        shell: bash
         run: |
-          python3 tasks/scripts/check_review_readiness.py \
-            --repo "$GH_REPO" --pr "$PR_NUMBER" --apply
+          set -euo pipefail
+          args=(--repo "$GH_REPO" --pr "$PR_NUMBER" --apply)
+          if [ "$PR_ACTION" = opened ]; then
+            args+=(--label-accepted-work)
+          fi
+          python3 tasks/scripts/check_review_readiness.py "${args[@]}"

.github/zizmor.yml

@@ -12,4 +12,5 @@ rules:
       - pr-issue-acceptance.yml:6
       - release-canary.yml:3
       - required-ci-gates.yml:3
+      - review-readiness.yml:6
       - vouch-check.yml:3

CI.md

@@ -705,6 +705,7 @@ The bot's full administrator documentation is internal to NVIDIA. The only comma
 | `.github/actions/pr-merge-base/action.yml` | Composite action that resolves and fetches the merge-base commit for `pull-request/<N>` push workflows. |
 | `.github/workflows/required-ci-gates.yml` | Posts required PR-head and merge-group statuses for gated CI workflows. This is what branch protection and merge queue should require. |
 | `.github/workflows/e2e-label-help.yml` | When a `test:e2e*` label is applied, posts a PR comment telling the maintainer the next manual step (re-run an existing workflow run, or `/ok to test <SHA>` to refresh the mirror). |
+| `.github/workflows/review-readiness.yml` | Labels newly opened accepted-work PRs using the shared read-only acceptance library, including drafts; routes matching reviewers when a PR is ready and classified. |
 | `.github/workflows/workflow-security.yml` | Runs informational Actionlint and High-severity Zizmor reports on GitHub-hosted runners. |
 | `.github/workflows/dependency-review.yml` | Reports dependency changes when GitHub Dependency Graph is available; otherwise publishes a neutral warning. |
 | `.github/workflows/codeql.yml` | Runs nightly informational CodeQL analysis on `main` for Rust and the Python and TypeScript SDKs and retains SARIF artifacts. |

CONTRIBUTING.md

@@ -72,7 +72,7 @@ Every pull request must be approved by someone listed in [MAINTAINERS.md](MAINTA
 
 Pull requests that touch the enforcement machinery or reviewer routing — anything under `.github/workflows/`, `.github/actions/`, `MAINTAINERS.md`, `REVIEWERS.md`, `.github/CODEOWNERS`, or the enforcement and reviewer-routing scripts in `tasks/scripts/` — additionally require a code owner's approval, listed in [.github/CODEOWNERS](.github/CODEOWNERS). The status check reads its inputs from `main`, but a workflow triggered by a review runs the pull request's own copy of the workflow file, so GitHub's native code owner requirement is what keeps a change from disabling the gate that would have blocked it.
 
-Use exactly one `area:` label and any relevant `topic:` labels on your pull request. The [reviewer routing workflow](.github/workflows/review-readiness.yml) requests all matching members of [REVIEWERS.md](REVIEWERS.md), excluding the author, when a PR opens ready for review, leaves draft status, or gains or loses an area/topic label. Reviewers do not need repository write access to receive requests or review PRs. Manual reviewer choices and people who have commented or reviewed are preserved. Propose roster membership changes through a reviewed PR.
+Once your pull request represents [accepted work](#accepted-work), apply exactly one `area:` label and any relevant `topic:` labels. Follow [Labeling and Notifications](#labeling-and-notifications) before applying classification labels. The [reviewer routing workflow](.github/workflows/review-readiness.yml) requests all matching members of [REVIEWERS.md](REVIEWERS.md), excluding the author, when a PR opens ready for review, leaves draft status, or gains or loses an area/topic label. Reviewers do not need repository write access to receive requests or review PRs. Manual reviewer choices and people who have commented or reviewed are preserved. Propose roster membership changes through a reviewed PR.
 
 If your pull request has been idle, ask for a reviewer in the pull request or in the CNCF Slack channel rather than waiting.
 
@@ -131,6 +131,29 @@ A direct request to an agent authorizes the requested planning or implementation
 
 Do not file suspected vulnerabilities as public issues. Follow [SECURITY.md](SECURITY.md). Use the specialized security skills for authorized review or remediation.
 
+### Accepted Work
+
+Accepted work is work the project intends to pursue. Work submitted by a maintainer listed in the merged [MAINTAINERS.md](MAINTAINERS.md), or someone with repository `WRITE`, `MAINTAIN`, or `ADMIN` access, qualifies immediately. Other issues require a maintainer's acceptance, recorded with `state:accepted`.
+
+A PR represents accepted work when either:
+
+- Its author is a maintainer or has repository write access as described above.
+- It closes at least one issue in this repository that has `state:accepted`, and the PR author is that issue's submitter or a current assignee.
+
+Use GitHub closing references such as `Closes #123` or `Fixes #123`. Merely mentioning an accepted issue does not qualify. Acceptance and the author relationship must hold on the same issue. The PR author determines eligibility, not the person triggering a workflow. Other tools and contributor skills use this shared definition; the importable `tasks/scripts/accepted_work.py` library implements the PR check.
+
+Acceptance classifies work, not implementation quality or approval to merge. Existing issue-linking rules, the separate `PR Issue Acceptance` check (which requires every linked issue to be accepted for community authors), and maintainer/code-owner approvals still apply. Acceptance does not certify that the diff implements the issue, and the existing Dependabot gate exemption does not automatically qualify a PR as accepted work.
+
+### Labeling and Notifications
+
+Labels drive notification streams as well as classification. Contributors use the GitHub app in Slack, and other integrations, to follow issues and PRs filtered by area or topic. Applying those labels can notify subscribers immediately, before they have chosen to follow the individual item.
+
+Apply `area:` and `topic:` classification labels only after the issue or PR meets the shared [accepted-work definition](#accepted-work). Once accepted, apply the relevant classification labels so subscribers can find the work.
+
+Do not classify an issue merely because it was filed or its subject is clear. Waiting until acceptance keeps label-filtered streams focused on work the project intends to pursue and avoids sending unaccepted intake to subscribers. Workflow labels such as `state:triage-needed` still record intake status; they do not establish acceptance.
+
+Automatic classification at issue creation and filters that exclude unaccepted work are being discussed separately in [#5261](https://github.com/NVIDIA/OpenShell/issues/5261). Until that policy changes, defer classification labels until acceptance.
+
 ### Label Discovery
 
 Retrieve every page of repository labels and their descriptions:
@@ -458,6 +481,12 @@ Automated dependency update PRs, including Dependabot PRs, are exempt from the s
 
 Authors with `WRITE`, `MAINTAIN`, or `ADMIN` access may open a PR that only fixes a broken build or flaky tests without a separate issue. Describe the failure in the PR instead. Authors without write access follow the normal issue and acceptance requirements.
 
+### Automatic Acceptance Labeling
+
+The existing [review-readiness workflow](.github/workflows/review-readiness.yml) checks [accepted work](#accepted-work) when a PR is opened and adds `state:accepted` if it qualifies. This includes drafts and PRs awaiting area/topic classification. Reviewer requests still wait until a PR is ready and has an area label.
+
+This is an additive check at creation, not continuous reconciliation: later edits, permission changes, and issue-label or assignment changes do not refresh or remove the PR label. The shared library is read-only; review-readiness applies the label. The label does not replace the issue-acceptance gate or merge approvals.
+
 ### Branch Names
 
 Use `<type>/<issue-id>-<short-description>/<github-username>` for contributor branches. Choose the Conventional Commit type that describes the work, such as `feat`, `fix`, `refactor`, `chore`, `perf`, `docs`, `test`, or `ci`. The description is a short lowercase slug separated by hyphens; the final component is your GitHub login, not initials.

tasks/scripts/check_review_readiness.py

@@ -10,6 +10,7 @@
 """Reconcile PR reviewers from the merged REVIEWERS.md and current PR metadata.
 
 Preview with --repo OWNER/REPO --pr NUMBER; add --apply to update requests.
+For newly opened PRs, --label-accepted-work also adds state:accepted if qualified.
 Request all matching roster members, excluding the author. Preserve
 manual choices, unknown request provenance, and anyone who commented or reviewed.
 The parser and planning helpers are importable. No state is stored between runs.
@@ -22,9 +23,12 @@
 import re
 import subprocess
 import sys
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, replace
 from pathlib import Path
 
+from check_maintainer_approval import parse_maintainers
+from label_accepted_work import ACCEPTED_LABEL, check_pr_accepted_work
+
 HEADER = ["Name", "GitHub ID", "Company/Organization"]
 LABEL = re.compile(r"(?:area|topic):[a-z0-9]+(?:-[a-z0-9]+)*")
 PROFILE = re.compile(r"\[@([a-z0-9-]+)\]\(https://github\.com/([a-z0-9-]+)/?\)", re.I)
@@ -34,6 +38,8 @@
 class ReviewPlan:
     add: tuple[str, ...]
     remove: tuple[str, ...]
+    accepted_work: bool | None = None
+    add_labels: tuple[str, ...] = ()
 
 
 def parse_reviewers(markdown: str) -> dict[str, set[str]]:
@@ -212,15 +218,45 @@ def check_review_readiness(
     number: int,
     *,
     apply=False,
+    label_accepted_work=False,
+    maintainers: set[str] | None = None,
 ) -> ReviewPlan | None:
-    """Plan or apply routing. Callers must serialize runs for the same PR."""
+    """Plan labeling and routing; callers serialize runs for the same PR.
+
+    Enable label_accepted_work for newly opened PRs, including drafts. Acceptance
+    is independent of readiness and classification; only reviewer routing needs
+    a ready PR with an area label. Labeling never removes an existing label.
+    """
     pull = f"repos/{repository}/pulls/{number}"
     pr = _api(pull)
-    if pr["state"] != "open" or pr["draft"]:
+    if pr["state"] != "open":
         return None
-    selected = select_reviewers(categories, {label["name"] for label in pr["labels"]})
+    accepted = None
+    add_labels = ()
+    labels = {label["name"] for label in pr["labels"]}
+    if label_accepted_work:
+        accepted = check_pr_accepted_work(
+            repository, pr, maintainers or set(), api=_api
+        )
+        if accepted and ACCEPTED_LABEL not in labels:
+            add_labels = (ACCEPTED_LABEL,)
+            if apply:
+                _api(
+                    f"repos/{repository}/issues/{number}/labels",
+                    method="POST",
+                    data={"labels": list(add_labels)},
+                )
+    if pr["draft"] or not any(label.startswith("area:") for label in labels):
+        if pr["draft"] and not label_accepted_work:
+            return None
+        return ReviewPlan((), (), accepted, add_labels)
+    selected = select_reviewers(categories, labels)
     selected -= {pr["user"]["login"].lower()}
-    plan = plan_review_requests(selected, **_load_reviewers(repository, number, pr))
+    plan = replace(
+        plan_review_requests(selected, **_load_reviewers(repository, number, pr)),
+        accepted_work=accepted,
+        add_labels=add_labels,
+    )
     if apply:
         endpoint = f"{pull}/requested_reviewers"
         if plan.add:
@@ -233,7 +269,7 @@ def check_review_readiness(
             refreshed = plan_review_requests(
                 selected, **_load_reviewers(repository, number, latest)
             )
-            plan = ReviewPlan(plan.add, refreshed.remove)
+            plan = replace(plan, remove=refreshed.remove)
             if plan.remove:
                 _api(endpoint, method="DELETE", data={"reviewers": list(plan.remove)})
     return plan
@@ -242,6 +278,12 @@ def check_review_readiness(
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--reviewers", type=Path, default=Path("REVIEWERS.md"))
+    parser.add_argument("--maintainers", type=Path, default=Path("MAINTAINERS.md"))
+    parser.add_argument(
+        "--label-accepted-work",
+        action="store_true",
+        help="check and label accepted work on a newly opened PR",
+    )
     parser.add_argument("--repo", required=True, help="target OWNER/REPO")
     parser.add_argument("--pr", required=True, type=int, help="pull request number")
     parser.add_argument(
@@ -252,8 +294,27 @@ def main(argv: list[str] | None = None) -> int:
         parser.error("--repo must be OWNER/REPO and --pr must be positive")
     try:
         categories = parse_reviewers(args.reviewers.read_text(encoding="utf-8"))
-        plan = check_review_readiness(categories, args.repo, args.pr, apply=args.apply)
-    except (OSError, UnicodeError, ValueError, subprocess.CalledProcessError) as exc:
+        maintainers = (
+            parse_maintainers(args.maintainers.read_text(encoding="utf-8"))
+            if args.label_accepted_work
+            else None
+        )
+        plan = check_review_readiness(
+            categories,
+            args.repo,
+            args.pr,
+            apply=args.apply,
+            label_accepted_work=args.label_accepted_work,
+            maintainers=maintainers,
+        )
+    except (
+        OSError,
+        UnicodeError,
+        ValueError,
+        KeyError,
+        TypeError,
+        subprocess.CalledProcessError,
+    ) as exc:
         print(f"Review readiness: {exc}", file=sys.stderr)
         return 1
     print(