Merge pull request #119 from codex-bot-andresmgsl/build/113-directed-hold-park

docs: define directed-hold parked claims

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

CHANGELOG.md

@@ -8,6 +8,7 @@ so entries say what changed, cite the issue, and stop.
 
 - `actions/changelog-assembled` — a release PR's stamped section must be byte-for-byte what the fragments it consumed assemble to, replayed from the merge base; inapplicable trees pass with a NOTICE (#116).
 - `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).
 - `LABELS.md` — drop the vendored scope-table enumeration; the per-repo set lives in `.github/labels.conf` and the repo's own CONTRIBUTING (#104).

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