From 8c66d35affdb2ad9c4ac1d06cc1bcb202f3d40e2 Mon Sep 17 00:00:00 2001 From: Jim Meyer Date: Mon, 28 Sep 2026 19:05:26 -0700 Subject: [PATCH] docs(workflow): align contributor guidance and active workflows Signed-off-by: Jim Meyer --- .agents/skills/create-github-issue/SKILL.md | 2 +- .agents/skills/create-github-pr/SKILL.md | 2 + .agents/skills/create-rfc/SKILL.md | 8 +- .agents/skills/sync-agent-infra/SKILL.md | 4 +- .agents/skills/triage-issue/SKILL.md | 2 +- .agents/workflow-labels.json | 3 +- .github/workflows/stale.yml | 8 +- AGENTS.md | 8 +- CONTRIBUTING.md | 171 +++--------------- docs/contributing/issue-workflow.mdx | 2 + rfc/README.md | 4 +- .../agents/gator/skills/gator-gate/SKILL.md | 2 +- scripts/workflow_labels.py | 4 +- scripts/workflow_labels_test.py | 1 + 14 files changed, 57 insertions(+), 164 deletions(-) diff --git a/.agents/skills/create-github-issue/SKILL.md b/.agents/skills/create-github-issue/SKILL.md index 2510b79272..630899bc90 100644 --- a/.agents/skills/create-github-issue/SKILL.md +++ b/.agents/skills/create-github-issue/SKILL.md @@ -125,7 +125,7 @@ EOF GitHub built-in issue types (`Bug`, `Feature`, `Task`) should come from the matching issue template when possible, or be set manually afterward. Do not try to emulate them through labels. -Creating an issue does not accept it or queue agent work. Agents never apply `state:accepted`, the `roadmap` label, add issues to the roadmap project, or apply `agent:plan-requested` or `agent:implementation-requested`. Community issues proceed through `triage-issue`; a human accepts technically validated work with `state:accepted` or roadmap placement. The request labels queue work for unattended agents. A user may instead direct an agent to a specific issue; the agent warns about missing expected workflow labels and continues with the requested phase without changing them. +Creating an issue does not accept it or queue implementation. Agents never apply `state:accepted`, roadmap placement, `needs:plan`, or `needs:pr` to authorize themselves. The issue-opened workflow assigns `state:new` to non-maintainer submissions for screening only; maintainer-authored issues enter the accepted path under the current exception. A human invokes `triage-issue`, reviews its Slack handoff, and directs public action. A human accepts technically validated work with `state:accepted` or roadmap placement and queues a phase with its `needs:*` value in an active pickup state. A user may instead direct an agent to a specific phase; the agent warns about missing queue labels and continues without changing authorization labels. ## Useful Options diff --git a/.agents/skills/create-github-pr/SKILL.md b/.agents/skills/create-github-pr/SKILL.md index dd0463df8b..dcbbd06855 100644 --- a/.agents/skills/create-github-pr/SKILL.md +++ b/.agents/skills/create-github-pr/SKILL.md @@ -118,6 +118,8 @@ gh pr create --title "PR title" --body "PR description" Features, user-visible behavior changes, public API changes, architecture changes, and multi-PR efforts must link an accepted issue. Use `Closes #` in the body to auto-close the issue when merged: +Keep `type:*`, `state:*`, and `needs:*` on the linked issue; do not mirror those labels onto the PR. GitHub already shows PR review and merge state. A PR with no linked issue may carry useful labels, but its labels do not establish that the work was accepted. + ```bash gh pr create \ --title "Fix validation error for empty requests" \ diff --git a/.agents/skills/create-rfc/SKILL.md b/.agents/skills/create-rfc/SKILL.md index 6e8cffd428..b241b2cdee 100644 --- a/.agents/skills/create-rfc/SKILL.md +++ b/.agents/skills/create-rfc/SKILL.md @@ -16,8 +16,12 @@ Keep the template as the source of truth for section guidance. RFC number, and how the lifecycle works. 2. Read `rfc/0000-template/README.md` before drafting. Follow its section guidance, including scope, expected detail, and suggested section length. -3. Choose the next available `NNNN` from the existing `rfc/NNNN-*` directories - unless the user provided a specific number. +3. Confirm that an originating GitHub issue exists and a maintainer assigned its + RFC number. The maintainer also records `needs:rfc` on + the issue. Never choose a number locally or apply these human-only labels. + If the number is missing, prepare the draft in ignored `architecture/plans/` + for review, then ask the maintainer to assign a number before creating the + RFC folder. 4. Create `rfc/NNNN-short-title/README.md` by copying the template and replacing placeholders. Use a short hyphenated folder title. 5. Fill in front matter with the RFC author, `state: draft`, and any related diff --git a/.agents/skills/sync-agent-infra/SKILL.md b/.agents/skills/sync-agent-infra/SKILL.md index 68a623c392..e9668d7fe6 100644 --- a/.agents/skills/sync-agent-infra/SKILL.md +++ b/.agents/skills/sync-agent-infra/SKILL.md @@ -91,7 +91,7 @@ The canonical workflow chains are defined in `AGENTS.md` under "## Workflow Chai ### Labels -The canonical label set is used by skills and templates. The key labels are: `state:triage-needed`, `state:needs-info`, `state:validated`, `state:accepted`, `agent:plan-requested`, `agent:plan-ready`, `agent:implementation-requested`, `agent:in-progress`, `agent:pr-opened`, `roadmap`, `topic:security`, `good first issue`, `help wanted`, `spike`, and the relevant `area:*`, `topic:*`, `integration:*`, and `test:*` labels. Lifecycle and `agent:*` request labels gate unattended queue pickup. They do not prevent a direct user request: the agent warns about each missing or incomplete expected workflow label and continues with the requested phase without changing those labels. +The canonical three-axis label set lives in `.agents/workflow-labels.json` and is explained in `docs/contributing/issue-workflow.mdx`. The key values are `type:*`, `state:new`, `state:validated`, `state:accepted`, `state:in-progress`, `state:in-review`, `needs:info`, `needs:plan`, `needs:pr`, `needs:spike`, `needs:rfc`, plus the orthogonal `status:stale`, `roadmap`, `topic:security`, `good first issue`, `help wanted`, and relevant area/topic/integration/test labels. State, the human-set need, acceptance, and any required approved plan gate unattended queue pickup. A direct request authorizes its stated phase after a warning about missing or incomplete queue labels; it does not change them. ## Step 2: Check Each File for Drift @@ -116,7 +116,7 @@ For each file in the table above, check for the following inconsistencies: ### Issue Lifecycle Documentation 1. **`CONTRIBUTING.md` issue lifecycle section** — State, roadmap, acceptance-signal, and agent-workflow meanings must match `AGENTS.md`. -2. **Invocation modes** — Lifecycle and `agent:*` request labels must gate unattended queue pickup without blocking a direct user request to a specific agent. +2. **Invocation modes** — Acceptance, the active issue state, the human-set need, and any required approved plan must gate unattended queue pickup without blocking a direct user request to a specific agent. 3. **Direct-mode warnings** — Guidance must require the agent to warn about each missing or incomplete expected workflow label, continue with the requested phase, and leave labels unchanged. ### `README.md` diff --git a/.agents/skills/triage-issue/SKILL.md b/.agents/skills/triage-issue/SKILL.md index a9b4ba4b3c..a465b2372e 100644 --- a/.agents/skills/triage-issue/SKILL.md +++ b/.agents/skills/triage-issue/SKILL.md @@ -9,7 +9,7 @@ metadata: Assess a community issue so the duty engineer can quickly accept it, decline it with an explanation, ask for exact missing information, or invite collaborators into the decision. This skill is human-invoked during this rollout. `state:new` calls for screening only; it does not authorize planning or implementation. Maintainer-authored issues normally enter `state:accepted` through the issue-opened workflow and do not need this screening. -The [issue workflow](../../../docs/contributing/issue-workflow.mdx) defines the three label axes. The [proposal](https://github.com/NVIDIA/OpenShell/issues/3807) explains the rollout. This skill never decides acceptance or roadmap placement, and never adds or removes `state:accepted`, `roadmap`, `needs:spike`, `needs:plan`, `needs:pr`, or `needs:rfc` without human direction. A human can directly request a specific phase without changing queue labels. +The [issue workflow](https://docs.nvidia.com/openshell/latest/contributing/issue-workflow.md) defines the three label axes. The [proposal](https://github.com/NVIDIA/OpenShell/issues/3807) explains the rollout. This skill never decides acceptance or roadmap placement, and never adds or removes `state:accepted`, `roadmap`, `needs:spike`, `needs:plan`, `needs:pr`, or `needs:rfc` without human direction. A human can directly request a specific phase without changing queue labels. ## Prerequisites diff --git a/.agents/workflow-labels.json b/.agents/workflow-labels.json index fba11430ff..ffbfb7e727 100644 --- a/.agents/workflow-labels.json +++ b/.agents/workflow-labels.json @@ -14,6 +14,7 @@ {"name": "needs:plan", "color": "fbca04", "description": "Needs an implementation plan or review of that plan"}, {"name": "needs:pr", "color": "fbca04", "description": "Needs a pull request or review of that pull request"}, {"name": "needs:spike", "color": "fbca04", "description": "Needs a maintainer-approved bounded investigation"}, - {"name": "needs:rfc", "color": "fbca04", "description": "Needs a maintainer-directed RFC pull request"} + {"name": "needs:rfc", "color": "fbca04", "description": "Needs a maintainer-directed RFC pull request"}, + {"name": "status:stale", "color": "ededed", "description": "Inactive item awaiting renewed attention; separate from workflow state"} ] } diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index e45ccbf5eb..4eb13124d2 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -16,7 +16,7 @@ jobs: steps: - uses: actions/stale@4391f3da665fdf50b6810c1a66712fb9ba21aa93 # v11.0.0 with: - stale-issue-label: state:stale + stale-issue-label: status:stale days-before-issue-stale: 14 days-before-issue-close: -1 # -1 puts this into dry-run mode. Update to 7 to enable closing. @@ -26,13 +26,13 @@ jobs: operations-per-run: 300 sort-by: updated - exempt-issue-labels: state:triage-needed,state:validated,state:accepted,agent:plan-requested,agent:plan-ready,agent:implementation-requested,agent:in-progress,agent:pr-opened,roadmap + exempt-issue-labels: state:validated,state:accepted,state:in-progress,state:in-review,roadmap close-issue-reason: not_planned stale-issue-message: > This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. - Comment or remove the state:stale label to keep it open. + Comment or remove the status:stale label to keep it open. close-issue-message: > Closing this issue after 7 days with no activity since it was marked stale. Reopen it if the work is still relevant. @@ -44,7 +44,7 @@ jobs: steps: - uses: actions/stale@4391f3da665fdf50b6810c1a66712fb9ba21aa93 # v11.0.0 with: - stale-pr-label: state:stale + stale-pr-label: status:stale days-before-issue-stale: -1 days-before-issue-close: -1 diff --git a/AGENTS.md b/AGENTS.md index a590b117ce..9e0c858e18 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,11 +22,11 @@ Do not rely on this file for a full inventory. The detailed public and contribut These pipelines connect skills into end-to-end workflows. Individual skill files don't describe these relationships. - **Community inflow:** `triage-issue` → human disposition and roadmap placement → `create-spike` when needed → `build-from-issue` - - Triage establishes facts and marks technically valid issues `state:validated`. A human signals that the project should pursue the work by applying `state:accepted` or placing the issue on the roadmap. The `agent:*` labels support unattended agents that scan for queued work: a human queues a plan with `agent:plan-requested`, the agent returns `agent:plan-ready`, and a human queues implementation with `agent:implementation-requested`. A direct user request to an agent authorizes the requested phase even when the expected lifecycle or workflow labels are missing or incomplete; the agent warns about the discrepancies and continues without changing the labels. + - Non-maintainer issues enter `state:new` for screening. A human invokes triage, reviews its private Slack summary, and directs public action. Maintainer-authored issues enter the accepted path for now; automatic triage is a separate follow-on. Triage establishes facts and may mark technically valid issues `state:validated`; a human accepts or declines. For queued work, a human sets `needs:plan` or `needs:pr` after the relevant decision and keeps the issue in an active pickup state. A direct user request authorizes its stated phase despite missing workflow labels; the agent warns and continues without changing authorization labels. - **Internal development:** `create-spike` → human disposition and roadmap placement → `build-from-issue` - - Spike explores feasibility and marks its issue `state:validated` when sufficient evidence exists. A human accepts it with `state:accepted` or roadmap placement, or declines it, and optionally queues it through the `agent:*` workflow or directs an agent to it. A direct request proceeds after warning about missing or incomplete expected labels. + - Spike explores feasibility and marks its issue `state:validated` when sufficient evidence exists. A human accepts it with `state:accepted` or roadmap placement, or declines it, and optionally queues the next phase with `needs:*` in an active pickup state or directs an agent to it. A direct request proceeds after warning about missing or incomplete expected labels. - **Security:** `review-security-issue` → `fix-security-issue` - - General build agents must not process `topic:security` issues. For unattended processing, a human queues specialized review with `agent:plan-requested`; review produces a severity assessment and remediation plan; a human queues remediation with `agent:implementation-requested`. On direct requests to the specialized skills, missing workflow labels produce a warning rather than blocking the requested phase. + - General build agents must not process `topic:security` issues. For unattended processing, a human queues specialized review with `needs:plan` in an eligible state; review produces an assessment and remediation plan; a human queues remediation with `needs:pr` in an active pickup state after approval. Direct requests to specialized skills warn about missing queue labels without blocking the requested phase; remediation still requires a legitimate prior review. - **Policy iteration:** `openshell-cli` → `generate-sandbox-policy` - CLI manages the sandbox lifecycle; policy generation authors the YAML constraints. @@ -100,7 +100,7 @@ design, and schema evolution. - **Bug reports and feature requests** must include a User Story, Problem Statement, Impact / Why This Matters, and Acceptance Criteria. The impact should explain the consequences of the current behavior, the current workaround, and why that workaround is insufficient. Bug reports additionally require reproduction steps and environment details and may include concise, redacted logs. - **Feature requests** must also include a Proposed Design and Alternatives Considered. The design should define the user-facing workflow and externally observable behavior while leaving internal implementation choices open. Agent investigation is optional. - **New features** must start as GitHub issues using the feature request template. Open an RFC only after an issue exists; maintainers decide when one is needed and assign RFC numbers from the issue. -- **Issue triage** establishes technical validity and impact evidence. Agents never decide acceptance, apply `state:accepted`, place issues on the roadmap, or apply `agent:plan-requested` or `agent:implementation-requested`. Humans accept or decline validated work; `state:accepted` or roadmap placement records acceptance, and roadmap association additionally carries sequencing. Lifecycle and request labels gate unattended queue pickup. An explicit user instruction authorizes an agent to plan or implement the specified issue even when expected labels are missing or incomplete; the agent warns the user and continues without changing those labels. OpenShell has no `priority:*` labels. +- **Issue triage** establishes technical validity and impact evidence, then privately hands findings to the duty engineer. Agents never decide acceptance, apply `state:accepted`, place issues on the roadmap, or apply `needs:plan` or `needs:pr` to queue themselves. Humans accept or decline validated work; `state:accepted` or roadmap placement records acceptance, and roadmap association additionally carries sequencing. State, the human-set need, acceptance, and any required approved plan gate unattended pickup. An explicit user instruction authorizes an agent to plan or implement the specified issue even when expected labels are incomplete; the agent warns and continues without changing authorization labels. OpenShell has no `priority:*` labels. - **PRs** must follow the PR template structure: Summary, Related Issue, Changes, Testing, Checklist. Contributors should use their agent to investigate the current code and behavior for accepted issue-backed work, verify any diagnostics already on the issue, understand the change they submit, and report the resulting implementation and verification—not paste an earlier issue-filing diagnostic. - **PRs for features, user-visible behavior, public APIs, architecture, or multi-PR efforts** must link an accepted issue. Small docs fixes, mechanical maintenance, and obvious localized bug fixes may state why no issue is required. - **PRs from unvouched external contributors** are automatically closed. See the Vouch System section above. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 935328b2b4..900b220400 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,7 @@ We use a vouch system. This exists because AI makes it trivial to generate plaus Issues labeled [`good first issue`](https://github.com/NVIDIA/OpenShell/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are scoped, well-documented, and friendly to new contributors. Start there. If you need guidance, comment on the issue. -An open issue is not necessarily accepted or ready to be worked on. Human contributors should look for `state:accepted`, roadmap placement, `good first issue`, or `help wanted`, or ask a maintainer before starting. Unattended agents require the expected lifecycle state and the appropriate human-applied `agent:*` request label. An agent directly asked to work on a specific issue warns about missing or incomplete expected labels and continues with the requested phase without changing them. +An open issue is not necessarily accepted or ready to be worked on. Human contributors should look for `state:accepted`, roadmap placement, `good first issue`, or `help wanted`, or ask a maintainer before starting. Unattended agents require acceptance or roadmap placement, an active pickup state, the human-applied `needs:*` label for the requested phase, and any required approved plan. An agent directly asked to work on a specific issue warns about missing or incomplete queue labels and continues with the requested phase without changing them. ## Before You Open an Issue @@ -121,164 +121,47 @@ Skills connect into pipelines. Individual skill files don't describe these relat ### Issue Lifecycle, Roadmap, and Agent Work -OpenShell separates technical assessment, roadmap decisions, sequencing, and agent delegation. +OpenShell uses three label axes on issues. The [issue workflow guide](docs/contributing/issue-workflow.mdx) defines every value and example. GitHub's issue type, closure reason, assignee, and roadmap placement remain separate metadata. -An open issue is not automatically accepted or ready for implementation. Check its `state:*` label before starting work, and ask a maintainer when its status is unclear. +| Axis | Question | Cardinality on an open issue after intake | +| --- | --- | --- | +| `type:*` | What kind of issue is this? | At most one; it may be absent while intake gathers evidence. | +| `state:*` | Where does the issue stand? | Exactly one. | +| `needs:*` | What work or information is needed next? | At most one; it may be absent during a disposition decision. | -#### The Four Decisions +`state:new` means screening or information gathering is pending. `state:validated` means the factual assessment is complete and a human should make a disposition decision promptly. `state:accepted` records a maintainer decision to pursue the work. `state:in-progress` and `state:in-review` describe active work and review. Closed issues use GitHub's closure reason; this rollout leaves already closed items untouched. The separate `status:stale` marker records inactivity without creating a second `state:*` label. -Each issue can require four independent decisions: +#### Intake and Human Disposition -| Decision | Question | Recorded by | -|---|---|---| -| Assessment | Is the report technically valid, and is there enough evidence to act on it? | `state:*` | -| Disposition | Should OpenShell pursue the work? | `state:accepted`, roadmap placement, or closure as not planned | -| Sequencing | Where does accepted work sit relative to everything else? | Placement on the [OpenShell Roadmap](https://github.com/orgs/NVIDIA/projects/233) | -| Ownership | Will a human implement the issue, will a user directly instruct an agent, or will a maintainer queue it for an unattended agent? | Direct instruction or optional `agent:*` workflow | +New community issues receive `state:new`. For this rollout, a human invokes `triage-issue`; the agent checks completeness, duplicates, prior declines, releases, and technical validity, then posts a private summary to `#openshell-triage` mentioning `@openshell-duty-eng`. The duty engineer can invite others into the Slack discussion and directs every public reply, label change, acceptance, or decline. Triage is not automatically invoked on issue creation yet. -`state:validated` confirms that the factual assessment is complete, but it does not mean the project has accepted the work. A maintainer signals acceptance with `state:accepted` or roadmap placement. Roadmap placement also communicates sequencing, but it does not assign an owner or queue an unattended agent. +Maintainer-authored issues bypass screening and enter `state:accepted` for scheduling and assignment. The automatic-triage follow-on will reconsider this exception. Suspected vulnerabilities follow [SECURITY.md](SECURITY.md) and are never filed as public GitHub issues. -#### Who Controls Each Decision +An issue needing specific evidence uses `needs:info` until the reporter or another person responds. A valid issue awaiting disposition uses `state:validated` only for the time needed to make that decision. A maintainer accepts by applying `state:accepted` or placing the issue on the [OpenShell Roadmap](https://github.com/orgs/NVIDIA/projects/233); roadmap placement additionally records sequencing. A maintainer declines by closing with an explanation. Agents never make those investment decisions or add `state:accepted` or roadmap placement. -Agents investigate issues, collect evidence, and report technical findings. Humans retain the product and investment decisions. +#### Human and Agent Work -| Action | Who performs it | -|---|---| -| Assess technical validity and impact | Triage agent or human triager | -| Request missing evidence | Triage agent or human triager | -| Mark the assessment complete with `state:validated` | Triage agent or human triager | -| Accept or decline the work with `state:accepted`, roadmap placement, or closure | Maintainer | -| Place the issue on the roadmap or move it | Maintainer | -| Directly request an agent plan | User | -| Queue an agent plan with `agent:plan-requested` | Maintainer | -| Produce a plan, implement it, and open a pull request | Agent | -| Directly request agent implementation | User | -| Queue approved implementation with `agent:implementation-requested` | Maintainer | +Human contributors may work on accepted issues without agent queue labels. Check for an assignee, branch, linked PR, or discussion that shows someone else is already working on the issue. `good first issue` and `help wanted` describe contributor suitability. OpenShell does not use priority labels. -Agents do not apply `state:accepted`, place issues on the roadmap, or apply `agent:plan-requested` or `agent:implementation-requested`. A direct request may authorize work outside the recorded workflow, but it does not alter the issue's disposition or make the labels accurate. +An unattended agent checks the full label combination before a phase: -#### Issue State - -The `state:*` namespace records the issue's disposition for all contributors, regardless of who might implement it. - -| State | Meaning | Normal next action | -|---|---|---| -| `state:triage-needed` | The issue has not been assessed. New issues from users without repository write access receive this automatically. | Investigate the report and record the result. | -| `state:needs-info` | The assessment needs specific evidence or reproduction details. | The reporter or another contributor supplies the requested information. | -| `state:validated` | The factual assessment is complete. | A maintainer accepts the issue, declines it, or asks for more evidence. | -| `state:accepted` | A maintainer decided that OpenShell should pursue the issue. | A human may implement it, or a maintainer may delegate work to an agent. | - -Keep one of these states on an open issue. When new evidence resolves a `state:needs-info` request, reassess the issue and move it to `state:validated` if the evidence is sufficient. - -`state:stale` is an inactivity marker, not a lifecycle decision. Accepted issues and issues awaiting human disposition are exempt from stale handling. An issue in `state:needs-info` can become stale if no new evidence arrives. - -#### Assessing an Incoming Issue - -Triage checks the user story, reproduction or workflow, environment, related issues, current releases, and the relevant code paths. The assessment ends in one of these outcomes: - -| Outcome | State or resolution | -|---|---| -| A bug is confirmed. | Replace the intake state with `state:validated`. | -| A feature proposal is technically coherent and feasible. | Replace the intake state with `state:validated`. | -| The report is credible but needs a deeper investigation or spike. | Add the `spike` label when available and use `state:validated` so a human can decide whether to invest in the investigation. | -| Critical evidence is missing, or a faithful attempt cannot reproduce the problem. | Use `state:needs-info` and request the exact evidence needed. | -| A released change already fixes the behavior. | Explain the fix and version. Close the issue only when the causal link is clear; otherwise request a retest. | -| Another issue is the canonical report. | Link the canonical issue and close the duplicate. | -| The behavior is expected or caused by unsupported configuration. | Explain the finding and close the issue with the appropriate GitHub reason. | -| The report describes a security vulnerability. | Stop public triage and follow the private process in `SECURITY.md`. | - -Triage establishes facts and impact. It does not decide whether the project should spend time on the work. - -#### Human Disposition - -When an issue reaches `state:validated`, a maintainer chooses one of three paths: - -- **Accept:** apply `state:accepted`, place the issue on the roadmap, or do both. Either action signals that OpenShell should pursue the work; roadmap placement additionally records sequencing. -- **Decline:** close it as not planned and record the rationale. -- **Await more evidence:** replace `state:validated` with `state:needs-info` and leave it off the roadmap. - -Do not use `state:accepted` as shorthand for technical validity, roadmap sequencing, or agent authorization. It records the human decision that OpenShell should pursue the work. Roadmap placement records the same acceptance decision plus sequencing. - -#### Roadmap - -OpenShell does not use priority labels. Sequencing comes from the [OpenShell Roadmap](https://github.com/orgs/NVIDIA/projects/233): a maintainer associates an issue with a roadmap item, signaling acceptance and giving it timing. Issues tracked on the roadmap carry the `roadmap` label. - -An issue with `state:accepted` and no roadmap association is real work the project intends to do, but it is not scheduled. Ask a maintainer before starting on one. - -Roadmap placement does not assign an owner. A roadmap issue still needs a human contributor, a direct user instruction to an agent, or an unattended-agent queue label. - -`good first issue` and `help wanted` describe contributor suitability, not sequencing. - -#### Human or Agent Ownership - -A human contributor may implement an accepted issue without any `agent:*` label. Before starting, check for an assignee, linked pull request, active branch, or comment that shows someone else is already working on it. - -Maintainers use the `agent:*` workflow to queue work for always-on or unattended agents that scan issues. Keep exactly one agent-workflow label on the issue at a time. When a user directly asks an agent to plan or implement a specific issue, that instruction authorizes the requested phase even if the issue does not match the normal lifecycle or agent-workflow state. The agent warns about each missing or incomplete expected label and continues without changing the labels. - -| Agent workflow | Applied by | Meaning | -|---|---|---| -| `agent:plan-requested` | Maintainer | Ask an agent to produce an implementation plan. | -| `agent:plan-ready` | Agent | The plan is ready for human review. | -| `agent:implementation-requested` | Maintainer | The plan is approved and an agent may implement it. | -| `agent:in-progress` | Agent | Authorized implementation is underway. | -| `agent:pr-opened` | Agent | The implementation produced a pull request. | - -The normal delegated workflow is: - -```text -(state:accepted OR roadmap placement) - | - +-- agent:plan-requested - | - +-- agent:plan-ready - | - +-- agent:implementation-requested - | - +-- agent:in-progress - | - +-- agent:pr-opened -``` - -`agent:plan-requested` authorizes an unattended agent to pick up planning, not implementation. `agent:implementation-requested` confirms that a human reviewed the plan and authorizes an unattended agent to pick up implementation. Agents never apply either request label. Planning authority does not imply implementation authority. - -#### Spikes - -Use a spike when the report is credible but technical uncertainty prevents a buildable plan. The triage assessment should identify the unknowns and the evidence the spike needs to produce. - -A maintainer first decides whether OpenShell should invest in the investigation. If accepted, the maintainer places it on the roadmap and may request agent work. The spike records its findings in an issue and uses: - -- `state:validated` when the evidence supports a human accept or decline decision. -- `state:needs-info` when material evidence or an external decision is still missing. - -A completed spike does not automatically authorize implementation. The resulting issue follows the same human disposition process. - -#### Security Issues - -Do not file or discuss suspected vulnerabilities in a public GitHub issue. Follow the disclosure instructions in `SECURITY.md`. - -Maintainers use the specialized security review and remediation workflow for an authorized security issue. For unattended processing, it uses the same queue controls: - -1. A maintainer applies `agent:plan-requested` to request a security review and remediation plan. -2. The review agent replaces it with `agent:plan-ready`. -3. A maintainer reviews the plan and applies `agent:implementation-requested`. -4. The remediation agent implements the approved plan. - -A user may instead directly request review or remediation from the specialized skill. If the corresponding queue label is missing, the agent warns and continues without changing it, but a request for review still does not authorize remediation. General implementation agents do not process issues labeled `topic:security`. +| Phase | Required issue state | +| --- | --- | +| Intake screening | `state:new`; this never authorizes planning or implementation. | +| Planning | Acceptance or roadmap placement, `state:accepted` or `state:in-progress`, and human-applied `needs:plan`. | +| Plan review | `state:in-review`, `needs:plan`. | +| Implementation | Acceptance or roadmap placement, `state:accepted` or `state:in-progress`, an approved plan, and human-applied `needs:pr`. | +| PR review | `state:in-review`, `needs:pr`. | -#### When an Issue Is Ready for Work +A plan request authorizes planning only. After reviewing the plan, a human changes `needs:plan` to `needs:pr` and returns the issue to `state:accepted` or `state:in-progress` to queue implementation. Agents may move an authorized issue into `state:in-progress` and return it to `state:in-review` when the plan or PR is ready. Agents never apply `needs:plan` or `needs:pr` to queue themselves. `needs:spike` requires a human-approved bounded investigation; `needs:rfc` requires maintainer direction and an assigned RFC number. -| You are | Ready when | -|---|---| -| A human contributor | The issue has `state:accepted`, roadmap placement, an invitation to contribute, or maintainer confirmation, and has no conflicting owner or implementation. | -| An unattended agent scanning for planning work | The issue has `state:accepted` or roadmap placement, plus the human-applied `agent:plan-requested` label. | -| An unattended agent scanning for implementation work | The issue has `state:accepted` or roadmap placement, plus an approved plan and the human-applied `agent:implementation-requested` label. | -| An agent directly instructed by a user | The instruction explicitly requests the phase the agent will perform and the issue has no conflicting owner or implementation. Missing or incomplete workflow labels produce a warning, not a stop. | +An explicit user request for a particular issue authorizes the stated phase even when expected queue labels are missing or incomplete. The agent warns about the discrepancy and continues without changing authorization labels. A direct planning request does not authorize implementation. General build agents do not process `topic:security` issues; the specialized security review and fix skills retain their own human approval and prior-review gates. -For unattended agents, `state:needs-info` blocks work until the requested evidence arrives, and `state:triage-needed` or `state:validated` blocks work unless a maintainer has separately placed the issue on the roadmap or applied `state:accepted`. For a directly instructed agent, these labels require a warning but do not themselves block the requested work. If information actually needed to do the work is unavailable, the agent reports that concrete blocker rather than treating the label as the blocker. +#### Pull Requests and Staleness -#### Stale Issues +Issue workflow labels stay on the issue linked from a PR. PR review and merge status are already visible in GitHub; a PR need not duplicate the issue's four axes. A PR without a linked issue may use useful workflow labels but is not assumed to represent accepted work. Feature and multi-PR efforts link accepted issues. -Inactive issues and pull requests are automatically labeled `state:stale` after 14 days without activity. Automated closing is currently disabled. Comment on the item or remove `state:stale` to keep it active. Issues awaiting triage or human disposition, accepted issues, active agent workflows, and roadmap issues are exempt. `state:needs-info` may become stale when no new evidence arrives. +Inactive issues and pull requests receive `status:stale` after 14 days. Automatic closure remains disabled. Comment or remove the marker to keep an item active. Issues awaiting triage or human disposition, accepted issues, active agent work, and roadmap issues are exempt; `needs:info` issues may become stale when no answer arrives. ## Prerequisites diff --git a/docs/contributing/issue-workflow.mdx b/docs/contributing/issue-workflow.mdx index ba4cc57737..33fe16b62f 100644 --- a/docs/contributing/issue-workflow.mdx +++ b/docs/contributing/issue-workflow.mdx @@ -19,6 +19,8 @@ Use `state:new`, `state:validated`, `state:accepted`, `state:in-progress`, and ` GitHub's closed status and reason describe completed or declined work. Do not add terminal `state:done` or `state:canceled` labels. When closing a new issue, clear `needs:*` labels that no longer describe a next action. The migration leaves already closed items untouched. +`status:stale` is an inactivity marker outside the four workflow axes. It can appear on an issue or pull request without creating a conflicting `state:*` label. The stale workflow does not close items automatically. + GitHub's built-in issue type is separate metadata. Use `type:*` for the more specific workflow classification. Conventional Commit types describe commits and do not determine issue type. Usage questions may use `type:support`; suspected vulnerabilities belong in the private process in `SECURITY.md`, not a public `type:security` issue. ## Intake and Disposition diff --git a/rfc/README.md b/rfc/README.md index 2c4260141d..b0f324146d 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -13,7 +13,7 @@ Before writing an RFC, you must open a [GitHub issue](https://github.com/NVIDIA/ - Build consensus before investing in a detailed proposal - Identify the right reviewers and stakeholders -If the ticket shows sufficient interest and maintainers decide the idea needs broad design review, they will ask for an RFC from that issue. Maintainers assign the RFC number and add the `needs-rfc` label in the issue before the RFC is created, preventing number clashes across branches and making pending RFC work searchable. +If the ticket shows sufficient interest and maintainers decide the idea needs broad design review, they will ask for an RFC from that issue. Maintainers assign the RFC number and add `needs:rfc` before the RFC is created, preventing number clashes across branches and making pending RFC work searchable. ## RFCs vs other artifacts @@ -93,7 +93,7 @@ Start with a GitHub issue. New features must use the feature request template an ### 2. Get maintainer confirmation -Maintainers decide from the issue whether an RFC is necessary. If it is, they assign the RFC number in the issue before anyone creates the RFC branch or folder, and add the `needs-rfc` label to the originating issue so pending RFC work is searchable. Authors should use the assigned number instead of choosing one locally. +Maintainers decide from the issue whether an RFC is necessary. If it is, they assign the RFC number in the issue before anyone creates the RFC branch or folder, and add `needs:rfc` to the originating issue so pending RFC work is searchable. Authors should use the assigned number instead of choosing one locally. ### 3. Create your RFC diff --git a/scripts/agents/gator/skills/gator-gate/SKILL.md b/scripts/agents/gator/skills/gator-gate/SKILL.md index 494946286d..03171a19b5 100644 --- a/scripts/agents/gator/skills/gator-gate/SKILL.md +++ b/scripts/agents/gator/skills/gator-gate/SKILL.md @@ -246,7 +246,7 @@ Before discovering work, define the invocation target selector and keep every la - Explicit issue or PR numbers: process only those items, even if a PR is closed or merged. - "My PRs" or similar operator-owned requests: resolve the current GitHub user with `gh api user --jq '.login'` and process only PRs authored by that login. - "All active PRs", "all gator-labeled PRs", or repo-wide requests: process across authors only when the operator explicitly asks for repo-wide scope. For write actions across authors, verify maintainer authority first. -- No-number requests that mention untriaged issues: process only the issue set implied by the request, such as open issues with `state:triage-needed`. +- No-number requests that mention untriaged issues: process only the issue set implied by the request, such as open issues with `state:new`. That intake state permits screening only; it does not queue planning or implementation. Keep `gator:*` labels as the separate PR supervision state machine. For PR watch requests, normal discovery should include open non-draft PRs matching the target selector. Closed/merged reconciliation may also include closed or merged PRs matching the same selector when they still have an active `gator:*` label. This is a cleanup extension of the current invocation scope, not permission to scan or mutate all gator-labeled PRs in the repository. diff --git a/scripts/workflow_labels.py b/scripts/workflow_labels.py index af4c39348b..7e0765838b 100644 --- a/scripts/workflow_labels.py +++ b/scripts/workflow_labels.py @@ -26,8 +26,8 @@ def load_manifest(path: Path) -> list[dict[str, str]]: if name in seen: raise ValueError(f"duplicate label: {name}") seen.add(name) - if not name.startswith(AXES): - raise ValueError(f"not a workflow-axis label: {name}") + if not name.startswith(AXES) and name != "status:stale": + raise ValueError(f"not a managed workflow label: {name}") if not re.fullmatch(r"[0-9a-fA-F]{6}", label["color"]): raise ValueError(f"invalid color for {name}") if not label["description"] or len(label["description"]) > 100: diff --git a/scripts/workflow_labels_test.py b/scripts/workflow_labels_test.py index b46c4e1f54..e16eea8a79 100644 --- a/scripts/workflow_labels_test.py +++ b/scripts/workflow_labels_test.py @@ -23,6 +23,7 @@ def test_committed_manifest_is_valid(self): labels = workflow_labels.load_manifest(manifest) self.assertIn("state:new", {label["name"] for label in labels}) self.assertFalse(any(label["name"].startswith("ready-for:") for label in labels)) + self.assertIn("status:stale", {label["name"] for label in labels}) def test_manifest_rejects_duplicate_names(self): self.assertIsNotNone(workflow_labels, "workflow_labels.py is missing")