From 17e888a6b12c24336bdcc37a621b52211136ad8a Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl <304681515+codex-bot-andresmgsl@users.noreply.github.com> Date: Fri, 24 Jul 2026 08:22:02 +0000 Subject: [PATCH 1/2] docs: define directed-hold parked claims --- BUILDER.md | 15 +++++++++++++-- TRIAGE.md | 6 +++--- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/BUILDER.md b/BUILDER.md index 426241e..47aa8bf 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -15,7 +15,7 @@ triage bug, and the move is to say so on the issue, not to guess. writing or revising a deliverable — finish or release that work before starting new work. The rule counts build work in flight, not claims: a claim does not consume the slot while it is **parked**, meaning the next - move belongs to someone else. Exactly four shapes qualify: + move belongs to someone else. Exactly five shapes qualify: 1. the issue carries `needs-ruling`, its escalation names a decider, and its `Blocked:` line stops the remaining work; 2. the deliverable is in a review round where every outstanding verdict @@ -28,6 +28,10 @@ triage bug, and the move is to say so on the issue, not to guess. 4. the deliverable is **handed off** — the round passed, no `blocker:*` stands, and you set `state:needs-human` per Handoff (below). The remaining move is the human's merge. + 5. the claim is **held by directive** — triage or the operator has told + you to stop, the direction names what the hold waits on, and that thing + is not yours to move. This is not "waiting for a good moment": somebody + else has decided the work must not proceed, and only they end it. Not parked — these are what the rule defends against: waiting on yourself, waiting on CI, or waiting for a good moment. An issue you have simply stopped working on is not parked either — that is abandonment, @@ -63,7 +67,14 @@ triage bug, and the move is to say so on the issue, not to guess. - **Pick up `attention` before anything else.** On your claim, first post a short pickup comment and remove `attention`; the removal is the ack. A demand on a parked claim is usually its unpark, so take the slot back under - the existing rule below rather than leaving the demand parked. + the existing rule below rather than leaving the demand parked. A demand + that *is* the park is different: the pickup comment is the declaration, + so one comment does both jobs, and the demand does not take the slot back. +- **A directed hold keeps its bookkeeping visible.** The PR carries `blocked` + with a comment naming what it waits on; the issue stays `claimed` and + carries `attention` until the builder acknowledges it. Nobody unassigns + the issue, and the 48-hour reclaim does not fire because the claim has an + open PR. Unparking follows the existing rule below. - **Unparking is a claim like any other.** When the wait ends, the parked issue is work again and takes the slot. If you are already active elsewhere, finish or release that work first, and say which you did on diff --git a/TRIAGE.md b/TRIAGE.md index 6a05966..84e0626 100644 --- a/TRIAGE.md +++ b/TRIAGE.md @@ -44,9 +44,9 @@ is the failure this whole flow exists to prevent. blocks something already on the board — an existing issue, or minted work a discussion's ruling gates — set `needs-ruling` on it too, so the board shows where the human's turn is; the issue keeps its queue label. - When you direct a builder to hold a claim that has no build work left, - say the claim is **parked** and name what it waits on — the directive - and the builder's doctrine + When you direct a builder to hold a claim, say the claim is **parked**, + name what it waits on, and set `attention` so the assignee's ack is visible + on the board — the directive and the builder's doctrine ([BUILDER.md](BUILDER.md#claiming)) must use one word. Past 24 hours from the current episode's `labeled` event, if the ruling still stands and doubt remains, it is triage's duty to pick the option the From f95692091f1e906a14e97ae158d54a857e21d303 Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl <304681515+codex-bot-andresmgsl@users.noreply.github.com> Date: Fri, 24 Jul 2026 09:17:04 +0000 Subject: [PATCH 2/2] docs: record directed-hold doctrine --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e33fc8e..06079f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ so entries say what changed, cite the issue, and stop. ## Unreleased - `lib/changelog.sh` + `bin/changelog-assemble` — read the `changelog.d/` fragments, assemble one release section (canonical group order, one shape per repo), and consume exactly what was published (#114). +- BUILDER.md — the directed hold is the parked claim's fifth shape, its attention demand is acknowledged in the declaration comment, and its board bookkeeping covers in-flight work; TRIAGE.md no longer excludes it (#113). - BUILDER.md — the handed-off PR is the parked claim's fourth shape, its handoff is its declaration, and shape 2 covers the round awaiting its first verdicts (#109). - `labels-reconcile` — a degraded mergeability/checks read now logs gh's actual stderr (collapsed, bounded) beside the byte-identical counted line, and the blind-sweep warning leads with the observed reason instead of asserting the permissions cause (#101). - Changelog publication — count entries instead of bytes, refuse dangling grouped headings, and seed grouped re-arms with Added/Changed/Fixed (#98).