# issue-state-labels — delta spec

## ADDED Requirements

### Requirement: Canonical label taxonomy
The backlog label set on every routed tracker SHALL be: priority `P0` `P1` `P2` `P3`;
autonomy `hitl` `semi` `afk-ready`; state `next` `waiting` `review`. `/os-backlog:route`
SHALL ensure these labels exist (idempotently) on forgejo/github trackers when onboarding.
No `doing` or `done` label exists: in-progress is expressed by assignment/branch activity,
completion by closing the issue.

#### Scenario: Route onboards a Forgejo repo
- **WHEN** `/os-backlog:route` configures `tracker=forgejo:<owner>/<repo>`
- **THEN** all ten canonical labels exist on the repo afterwards, and re-running route
  creates nothing new

### Requirement: The next label is human-only
The `next` label marks human-curated priority. The AI SHALL never apply or remove `next`
on any issue, in any project, under any instruction short of an explicit direct user
request naming the specific issue.

#### Scenario: AI triages a backlog
- **WHEN** an AI session labels or files issues during triage or capture
- **THEN** `next` is neither added to nor removed from any issue

### Requirement: Autonomy label semantics
`hitl` issues are human-owned and SHALL never be picked up autonomously. `semi` issues MAY
be worked autonomously through their mechanical parts, SHALL stop at named decision gates,
and on shipping SHALL receive the `review` label instead of being closed. `afk-ready`
issues, once shipped AND verified, SHALL be closed directly. Assigning autonomy labels is
the responsible project's job; ambiguity resolves to `hitl`.

#### Scenario: Semi-autonomy work ships
- **WHEN** an AI session completes the mechanical work of a `semi` issue
- **THEN** the issue receives the `review` label, a comment summarizing what shipped, and
  remains open for human sign-off

#### Scenario: Afk-ready work ships and verifies
- **WHEN** an AI session completes and verifies work on an `afk-ready` issue
- **THEN** the issue is closed with a closing comment linking the verification evidence

### Requirement: Working an issue means recording state on it
An AI session working an issue SHALL record state transitions on the issue itself: a
comment when work starts, the `waiting` label plus a blocker comment when blocked, and the
shipping transition per its autonomy label. Blocked issues SHALL have `waiting` removed
when work resumes.

#### Scenario: Work blocks on an external dependency
- **WHEN** in-progress issue work hits a blocker the session cannot resolve
- **THEN** the issue gains the `waiting` label and a comment naming the blocker, and the
  session moves on

### Requirement: Recurring process issues are never closed
An issue representing a recurring process (e.g. the biweekly orchestration audit in the
ops repo) SHALL be worked by commenting each occurrence's outcome on it and leaving it
open; closing it is a human-only action.

#### Scenario: Recurring audit completes an occurrence
- **WHEN** an AI session completes one occurrence of a recurring-convention issue
- **THEN** the outcome is added as a comment and the issue stays open with its labels
  unchanged