Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/standards/issue-tracker.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Issue fields are defined once for the organization by an organization owner in i
Prefer a native mechanism over a status label wherever GitHub offers one, because the native mechanism carries behavior the label can only imitate:

- **Blocking is a dependency edge, not a label.** Model "this cannot proceed until that is done" as a native blocked-by relationship between issues. The edge resolves itself when the blocker closes; a label has to be cleared by hand and silently goes stale.
- **Claiming is an assignee plus a lease, not a label, and the mechanism is active.** A worker taking an issue sets themselves as its assignee under a time-boxed lease, so ownership and its freshness live in the native field where a second worker can trust them, rather than in a label anyone can leave behind. The activation trigger this convention named, assignment contention becoming real, was met when autonomous multi-worker loop lanes began claiming from the same backlog; the mechanism is the work-items plugin's [tracker-seam lease protocol](https://github.com/melodic-software/claude-code-plugins/blob/main/plugins/work-items/tools/work-item-tracker/CONTRACT.md#lease-protocol), which defines the lease semantics (expiration, renewal, concurrent-claim arbitration). The former interim 🔒 marker is retired.
- **Claiming is an assignee plus a lease, not a label, and the mechanism is active.** A worker taking an issue sets themselves as its assignee under a time-boxed lease, so ownership and its freshness live in the native field where a second worker can trust them, rather than in a label anyone can leave behind. The activation trigger this convention named, assignment contention becoming real, was met when autonomous multi-worker loop lanes began claiming from the same backlog; the mechanism is the work-items plugin's [tracker-seam lease protocol](https://github.com/melodic-software/claude-code-plugins/blob/main/plugins/work-items/tools/work-item-tracker/CONTRACT.md#lease-protocol), which defines the lease semantics (expiration, renewal, concurrent-claim arbitration).
- **Work status is the one status.** The organization issue field Work status holds an issue's single current status, with no sub-statuses. The name keeps it apart from a project's own Status field.
- **Hold labels stack beside it.** A hold means *a human must act before work can continue*, such as waiting on the owner's decision or on the reporter's information. Holds can stack and a field holds one value, so each hold is also a flat label, spelled the same as its Work status option; the spellings are defined in infrastructure-as-code.
- **Work that waits on a decision is blocked by a decision issue.** File the decision as its own issue, Work status `needs-owner-decision`, assigned to the owner, and add a blocked-by edge from the waiting issue to it. When the owner decides and the decision issue closes, the edge clears and the waiting work becomes startable. A dependency written only in prose stops nothing.
Expand All @@ -98,7 +98,7 @@ Reconcile recurring items by a dedicated bare marker label (for example `recurri

## Closing pull requests

A pull request that resolves an issue uses one of GitHub's native closing keywords as the default house style. The keyword is what wires the automatic link and auto-close on merge; a plain-text reference like "see #123" does neither, and a disclaimer around a keyword does not stop it, because GitHub's parser ignores the surrounding words. The pull-request body contract is not restated here: the `body` fields of `components/pr-convention-policy/policy.json` record it (the accepted linkage lines, including how to link without closing and the no-issue opt-out, and the required sections), and the `ci-workflows` `check-contract` composite enforces it. The practice applies org- and account-wide, not only where a CI gate can check it. This began as `provisioning`'s stricter convention (decisions log #58/#59); the shared `check-contract` composite inside each requires-ci repository's `CI Status` check reports it, leaving an advisory comment and the `needs-issue-linkage` label rather than failing the check, and repositories without CI follow the same convention unreported.
A pull request that resolves an issue uses one of GitHub's native closing keywords as the default house style. The keyword is what wires the automatic link and auto-close on merge; a plain-text reference like "see #123" does neither, and a disclaimer around a keyword does not stop it, because GitHub's parser ignores the surrounding words. The pull-request body contract is not restated here: the `body` fields of `components/pr-convention-policy/policy.json` record it (the accepted linkage lines, including how to link without closing and the no-issue opt-out, and the required sections), and the `ci-workflows` `check-contract` composite enforces it. The practice applies org- and account-wide, not only where a CI gate can check it. The shared `check-contract` composite inside each requires-ci repository's `CI Status` check reports it, leaving an advisory comment and the `needs-issue-linkage` label rather than failing the check, and repositories without CI follow the same convention unreported.

## Optional conventions

Expand Down
Loading