Docs for #1165: in-progress marks only a live Run (grill, ADR 0029, glossary)

GLOSSARY.md

@@ -27,7 +27,7 @@ An issue scoping one session of work, standing alone or as a sub-issue of a **Sp
 _Avoid_: task, sub-task
 
 **Ready issue**:
-An open issue a **Pickup run** may take: labelled `ready-for-agent`, written by a **Trusted account**, with its most recent `ready-for-agent` labelling made by a Trusted account and no edit to its title or body since then by an account that is not one, with no label that makes an **Unready Ticket** and no **Claim**, not a sub-issue, not a **Base fix**'s or a **Security run**'s fix issue, with no open blocker, either never started (no **Issue branch** and no pull request) or handed back by the **Day shift** applying `ready-for-agent` at or after the last **Claim** ended, as recorded in its label history, not a **Spec** whose **Tickets** are all closed, left untouched long enough that whoever is shaping it has finished, and, if it is a Spec, with a **Startable Ticket**. A hand-back made in the same edit as the Claim's removal counts in either listed order at that timestamp; a Claim applied at the same timestamp leaves the issue Claimed. On a Spec, the label says its Tickets are published. A `ready-for-agent` Ticket inside a Spec is not one: it is reached through its Spec, when the Spec is itself a Ready issue.
+An open issue a **Pickup run** may take: labelled `ready-for-agent`, written by a **Trusted account**, with its most recent `ready-for-agent` labelling made by a Trusted account and no edit to its title or body since then by an account that is not one, with no label that makes an **Unready Ticket** and no **Claim**, not a sub-issue, not a **Base fix**'s or a **Security run**'s fix issue, with no open blocker, either never started (no **Issue branch** and no pull request) or handed back at or after the last **Claim** ended, as recorded in its label history: by the **Day shift** applying `ready-for-agent`, or by thirdshift putting it back on a Spec whose Spec run ended only waiting, which it does only when no account that is not a Trusted account has edited the Spec since its last `ready-for-agent` labelling, and otherwise labels the Spec `needs-triage`, not a **Spec** whose **Tickets** are all closed, left untouched long enough that whoever is shaping it has finished, and, if it is a Spec, with a **Startable Ticket**. A hand-back made in the same edit as the Claim's removal counts in either listed order at that timestamp; a Claim applied at the same timestamp leaves the issue Claimed. On a Spec, the label says its Tickets are published. A `ready-for-agent` Ticket inside a Spec is not one: it is reached through its Spec, when the Spec is itself a Ready issue.
 _Avoid_: queued issue, backlog item
 
 **Trusted account**:
@@ -40,19 +40,19 @@ An open **Ticket** labelled with a triage role that says it is not agent work: `
 An open **Ticket** in its **Spec**'s repository, with no sub-issues of its own, no open blocker, and not an **Unready Ticket**: one a **Spec run** could start if no Ticket were running. A Spec run starts only these, and a **Spec** with none is not a **Ready issue**.
 
 **Claim**:
-The mark that the factory has taken an issue: thirdshift labels the issue `in-progress`, in place of `ready-for-agent` if it has that, when a **Ticket run** or a **Spec run** starts on it, whether started on its **Issue URL** or by an **Architect run**, a **Pickup run** or a **Security run**, or in place of its triage role when a **Triage run** starts on an existing issue. A **Ticket run** in a Spec run and a **Base fix** make none. Ending a Claim finishes even after Command interruption. A failed Security fix keeps its Claim even with nothing on `origin`, so it stays with the Day shift. For other Ticket runs, a Claim is released, `ready-for-agent` put back, only when the Ticket run ends with nothing on `origin` to take over and was not ended by a **Stop**: no **Issue branch** and no pull request. Otherwise it stays while the issue is open, whether its pull request is ready for review or the Ticket run failed, until the **Day shift** relabels it, and thirdshift takes the label off once the issue is closed. A bug Ticket run that cannot reproduce the bug ends its Claim with `needs-info`, leaving `ready-for-agent` absent. A Triage run on an existing issue replaces its Claim with the resulting triage role when it finishes, with `needs-triage` on a Stop asked to requeue, with `ready-for-human` on any other Stop, and with `ready-for-human` and `agent-failed` when the Triage run fails.
+The mark that a Run is live on an issue: thirdshift labels the issue `in-progress`, in place of `ready-for-agent` if it has that, when a **Ticket run**, a **Spec run** or a **Custom process** starts on it, whether started on its **Issue URL** or by an **Architect run**, a **Pickup run** or a **Security run**, or in place of its triage role when a **Triage run** starts on an existing issue. A **Ticket run** in a Spec run and a **Base fix** make none. It lasts only while the Run is live, and ending it leaves the issue marked with how the Run ended. A Run whose pull request is ready for review, or whose **Self-merge** was held with its pull request ready, takes it off and puts nothing back: the open pull request stands for the work. A Self-merge that closed the issue takes it off; one that merged without closing the issue leaves it until the issue is closed. A Failed run with work on `origin` swaps it for `agent-failed` (see **Failure limit**), as does a failed Security fix even with nothing on `origin`, so it stays with the Day shift. A Ticket run that fails with nothing on `origin` to take over, no **Issue branch** and no pull request, releases it, putting `ready-for-agent` back. A Spec run whose undone **Tickets** are all only waiting, on a person or on other work, puts `ready-for-agent` back on its Spec without `agent-failed` (see **Ready issue**). A **Stop** leaves `needs-triage`, and a bug Ticket run that cannot reproduce the bug leaves `needs-info`. A Triage run on an existing issue replaces its Claim with the resulting triage role when it finishes, with `needs-triage` on a Stop asked to requeue, with `ready-for-human` on any other Stop, and with `ready-for-human` and `agent-failed` when the Triage run fails. Ending a Claim finishes even after Command interruption.
 _Avoid_: lock (a lock is per machine and ends with its process), assignment
 
 **Failure limit**:
-The number of open issues the factory failed on, labelled `agent-failed`, at which a **Pickup run** or a **Triage run** started as a **Pass** takes no more, set in the **User config**. thirdshift adds the label when a **Failed ticket run** or a **Failed spec run** keeps its **Claim**, or when a Triage run on an existing issue fails, whatever started it. A held **Self-merge** that leaves its pull request ready gets none, and neither does a **Stop**. The label comes off when the **Day shift** acts on the failure: by putting `ready-for-agent` back, by taking `in-progress` off, leaving no `needs-triage`, to take the issue over, by relabelling a failed triage issue, or by closing it, which the **Sweep** clears. It keeps a broken **Base branch** or **Harness** from failing every **Ready issue** or `needs-triage` issue in turn. A pull request that is ready for review or merged never counts, so the factory keeps working while reviews wait.
+The number of open issues the factory failed on, labelled `agent-failed`, at which a **Pickup run** or a **Triage run** started as a **Pass** takes no more, set in the **User config**. thirdshift puts the label on in place of the **Claim** when a **Failed ticket run**, a **Failed spec run** or a failed **Custom process** on an issue leaves work on `origin`, or when a Triage run on an existing issue fails, whatever started it. A held **Self-merge** that leaves its pull request ready gets none, and neither does a **Stop** or a Spec run that is only waiting. The label comes off when the **Day shift** acts on the failure: by putting `ready-for-agent` back, by taking `agent-failed` off to take the issue over, or by closing it, which the **Sweep** clears. The next Claim also takes it off. It keeps a broken **Base branch** or **Harness** from failing every **Ready issue** or `needs-triage` issue in turn. A pull request that is ready for review or merged never counts, so the factory keeps working while reviews wait.
 _Avoid_: Claim limit (former name), WIP limit, concurrency (it counts issues waiting on the **Day shift**, not Commands in flight)
 
 **Command limit**:
 The number of live **Commands** on one repository on one machine at which a **Pass** there is skipped, set in the **User config**, one by default. Every live Command counts, a Ticket run started by hand on an **Issue URL** included, together with the Spec run or Ticket run each Pass dispatched, but only a Pass is ever skipped for it: a Command a person types always runs. Passes of different kinds may run side by side up to the limit, but never two **Architect runs** or two **Security runs** on one repository at once. It counts no other repository; load across a machine is the **User config**'s memory and load waits.
 _Avoid_: Pass lock (former, one-wide form), concurrency limit, parallel
 
 **Sweep**:
-A **Pickup run**'s or a **Triage run** **Pass**'s removal of `in-progress` and `agent-failed` from every closed issue in the repository that still has them, and of `in-progress` from closed pull requests, with other labels kept. Each Pickup run or Triage run Pass that is not skipped for its **Command limit** makes one, before it holds the repository against its **Failure limit**. A Sweep that fails is a warning, never a failure.
+A **Pickup run**'s or a **Triage run** **Pass**'s removal of `in-progress` and `agent-failed` from every closed issue in the repository that still has them, of `in-progress` from every open issue that also has `agent-failed`, and of `in-progress` from closed pull requests, with other labels kept. Each Pickup run or Triage run Pass that is not skipped for its **Command limit** makes one, before it holds the repository against its **Failure limit**. A Sweep that fails is a warning, never a failure.
 _Avoid_: cleanup, garbage collection
 
 ### Repository and branches
@@ -264,7 +264,7 @@ A **Ticket run** that ends, including by interruption, without an open pull requ
 _Avoid_: Failed run (former name)
 
 **Recovery**:
-The lines a **Failed ticket run** ends with, saying where it stopped, what work was preserved and where, and the command that continues or retries it, except after a **Spec PR** changed under its **Spec run**, when no command would be safe; built only from factory-owned facts, never agent output.
+The lines a **Failed ticket run** ends with, saying where it stopped, what work was preserved and where, and the command that continues or retries it, except after a **Spec PR** changed under its **Spec run**, when no command would be safe; built only from factory-owned facts, never agent output. When the Failed run leaves its issue `agent-failed`, thirdshift also posts it there as a comment marked as generated, except for a failed Security fix, whose Recovery stays in its private advisory: the cause, where it stopped, what was preserved, the machine, and how to retry by putting `ready-for-agent` back, without local paths or the continue command. A **Spec run** that ends only waiting posts a comment on its **Spec** instead, naming each undone **Ticket** and what it waits on.
 
 **Continuation**:
 A **Ticket run** that picks up an existing **Issue branch**, one with no pull request or an open one, instead of starting fresh. When a pull request is open, its base is the **Base branch**.

docs/adr/0029-in-progress-marks-only-a-live-run.md

@@ -0,0 +1,26 @@
+# `in-progress` marks only a live Run
+
+This amends [ADR 0026](0026-pickup-counts-failures-and-passes-share-a-repository-up-to-a-command-limit.md)'s take-over rule and its last consequence. The rest of ADR 0026 stands.
+
+A **Claim** used to outlive its Run. A Ticket run or Spec run whose pull request was ready for review kept `in-progress`, and so did a Failed run with work on `origin`, which ADR 0026 also labelled `agent-failed`. Meanwhile a **Custom process**'s Delivery took `in-progress` off at ready for review (#1388). The issue list therefore couldn't answer "what is running?" (#1165). The Day shift relabelled stale issues by hand, and stopped trusting the label.
+
+So `in-progress` now means a live Run, on issues as it already did on pull requests. It goes on when a Run starts and comes off when it ends, and the issue is left marked with how the Run ended:
+
+- **Ready for review**, or a **Self-merge** held with its pull request ready: no label. The open pull request stands for the work, and Pickup still won't take the issue, because a started issue is a **Ready issue** only after a handback.
+- **Failed with work on `origin`**, or a failed Security fix: `agent-failed` in place of `in-progress`, whatever kind of Command failed. The Day shift takes over a failure in one of three ways: by putting `ready-for-agent` back, by taking `agent-failed` off, or by closing the issue.
+- **A Spec run that is only waiting** on gated, blocked or out-of-repository Tickets: `ready-for-agent` back on its Spec and no `agent-failed`, unless an account that is not a **Trusted account** has edited the Spec since its last Trusted labelling, in which case `needs-triage`.
+
+Decided in `docs/grill-with-docs/1165-claim-labels.md`: Q1.2, Q1.3, Q1.5, Q2.1, Q2.2 and Q2.4.
+
+## Considered Options
+
+- **A new `in-review` label** for a pull request waiting for review. It was recommended while the Claim limit counted those issues to stop reviews piling up. Rejected once ADR 0026 stopped counting them: with nothing counting it, the label would repeat what the open pull request and the Inbox's Ready for review already show.
+- **Keep `in-progress` beside `agent-failed`**, so "running" is `in-progress` without `agent-failed`. Rejected: a reader of GitHub, or another host, would need a two-label search to see what is live, and that was #1165's complaint.
+- **Follow Spec #1695 everywhere**: a failure leaves `ready-for-human` plus `agent-failed`, and removing `ready-for-human` is the take-over. Rejected: retrying a Ticket would take two label edits, because `ready-for-human` makes an issue Unready, and `ready-for-human` would mean "human work" on some issues and "the factory failed" on others.
+
+## Consequences
+
+- ADR 0026's take-over signal "taking `in-progress` off, leaving no `needs-triage`" goes. Without the change, the swap would let the next Pickup run clear every failure.
+- The **Sweep** also takes `in-progress` off any open issue that carries `agent-failed`. Under the new rules the two never sit together, so this both migrates old issues and stays safe forever. Issues whose pull request was ready for review under the old rules are cleared by hand once, because GitHub alone can't tell them from a live Continuation.
+- A failed Triage run (#1695) also gets `ready-for-human`, so the Triage Pass passes over it, but only `agent-failed` is the failure mark.
+- A failure with nothing on `origin` still releases its issue to `ready-for-agent`, and nothing brakes Pickup retaking it. That is left to its own issue.