roadkeep 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. roadkeep/__init__.py +79 -0
  2. roadkeep/adopting.py +2347 -0
  3. roadkeep/attesting.py +293 -0
  4. roadkeep/authoring.py +2117 -0
  5. roadkeep/backlog.py +767 -0
  6. roadkeep/blocking.py +1622 -0
  7. roadkeep/briefing.py +970 -0
  8. roadkeep/budgeting.py +2056 -0
  9. roadkeep/capturing.py +1699 -0
  10. roadkeep/claiming.py +1019 -0
  11. roadkeep/cli.py +638 -0
  12. roadkeep/commanding.py +487 -0
  13. roadkeep/config.py +1832 -0
  14. roadkeep/counting.py +376 -0
  15. roadkeep/criteria.py +933 -0
  16. roadkeep/deferring.py +708 -0
  17. roadkeep/describing.py +568 -0
  18. roadkeep/exporting.py +808 -0
  19. roadkeep/fixing.py +629 -0
  20. roadkeep/governing.py +934 -0
  21. roadkeep/graph.py +395 -0
  22. roadkeep/guarding.py +1028 -0
  23. roadkeep/history.py +2403 -0
  24. roadkeep/ids.py +301 -0
  25. roadkeep/installing.py +2145 -0
  26. roadkeep/kernel/__init__.py +24 -0
  27. roadkeep/kernel/document.py +1719 -0
  28. roadkeep/kernel/schema.py +2308 -0
  29. roadkeep/linting.py +4420 -0
  30. roadkeep/locking.py +209 -0
  31. roadkeep/markers.py +172 -0
  32. roadkeep/merging.py +1159 -0
  33. roadkeep/picking.py +772 -0
  34. roadkeep/provenance.py +789 -0
  35. roadkeep/queueing.py +752 -0
  36. roadkeep/ranking.py +139 -0
  37. roadkeep/referring.py +231 -0
  38. roadkeep/remaining.py +336 -0
  39. roadkeep/remedying.py +1989 -0
  40. roadkeep/rendering.py +1601 -0
  41. roadkeep/renumbering.py +503 -0
  42. roadkeep/repairing.py +295 -0
  43. roadkeep/reverting.py +144 -0
  44. roadkeep/scoping.py +708 -0
  45. roadkeep/screening.py +196 -0
  46. roadkeep/sections.py +4121 -0
  47. roadkeep/serving.py +2909 -0
  48. roadkeep/shipping.py +3993 -0
  49. roadkeep/showing.py +613 -0
  50. roadkeep/storing.py +224 -0
  51. roadkeep/verbs/__init__.py +26 -0
  52. roadkeep/verbs/adopting.py +974 -0
  53. roadkeep/verbs/authoring.py +566 -0
  54. roadkeep/verbs/declaring.py +335 -0
  55. roadkeep/verbs/linting.py +645 -0
  56. roadkeep/verbs/querying.py +2138 -0
  57. roadkeep/verbs/reading.py +307 -0
  58. roadkeep/verbs/refusing.py +146 -0
  59. roadkeep/verbs/sections.py +1433 -0
  60. roadkeep/verbs/shipping.py +819 -0
  61. roadkeep/weighing.py +380 -0
  62. roadkeep-0.2.0.dist-info/METADATA +453 -0
  63. roadkeep-0.2.0.dist-info/RECORD +67 -0
  64. roadkeep-0.2.0.dist-info/WHEEL +5 -0
  65. roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
  66. roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
  67. roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/picking.py ADDED
@@ -0,0 +1,772 @@
1
+ """What to work on next, and the reason it was chosen (RK11).
2
+
3
+ "What do I work on" is the question a roadmap is asked most often and answers worst: the
4
+ rule — *lowest-numbered task whose deps are all shipped* — is a join over two files that
5
+ costs reading both of them, every session, to learn one line. So it is a command, and the
6
+ answer carries **why**, because an unexplained pick cannot be checked and a pick nobody
7
+ checks is a pick nobody trusts (L5).
8
+
9
+ Three tiers, in this order, and each one is a fact rather than a taste:
10
+
11
+ 1. **Work already in progress.** A 🛠 line says someone started; picking something else
12
+ leaves it half-done, and half-done work is the one state the marker set can express
13
+ and no count can repair. This tier is why `pick` does not simply mean "lowest".
14
+ 2. **The declared priority.** A `## Priority` section of the roadmap, or `priority =
15
+ ["RK14", "Block D"]` in `roadkeep.toml` (L6), applied in the order written. The section
16
+ wins where both exist, and `roadkeep.queueing` is the reader — the objection this tier
17
+ used to state, that Shio's "## Priority queue" is a paragraph about why reachability
18
+ comes first, is about *interpreting prose* (L4) and does not reach a list this tool
19
+ renders (RK325). What the move buys is that the queue's tokens name work that **leaves**,
20
+ and the file the plan is in is the one every departure already rewrites.
21
+ 3. **The lowest ready id**, numerically. Blocks are ordered by dependency, so the id
22
+ order already follows the build order and needs no second opinion.
23
+
24
+ What never gets offered: anything :class:`Readiness.BLOCKED`, and — the distinction that
25
+ makes this useful — anything :class:`Readiness.OUTSIDE`. A task waiting on work this
26
+ backlog does not track never becomes ready by shipping tasks, so offering it as "next"
27
+ sends the caller at something that cannot be finished (RK28). :class:`Readiness.PAUSED`
28
+ is the third (RK92) and gets its own number for the same reason: a backlog stuck on
29
+ deferred deps is stuck on a decision nobody revisited, which no amount of shipping moves.
30
+
31
+ The stalled list is the other half of the same honesty: a 🛠 task that is *blocked* is
32
+ reported beside the answer, because that is the state a reader most needs to know about
33
+ and the one tier 1 cannot pick.
34
+
35
+ **Ready and implementable are two different states** (RK83). The tiers rank by id and
36
+ never by marker, so a block holding both designs and ideas answers a caller who asked to
37
+ execute it with a design session. Two things follow, and neither is a fourth tier: the
38
+ answer *says* when the line it chose still needs designing, because the complaint was
39
+ never that it chose wrongly but that it chose silently; and ``designed`` sets those lines
40
+ aside, because the bias belongs to the caller's intent and not to the ranking — a block
41
+ whose ideas are never offered is a block whose ideas are never designed.
42
+
43
+ **One backlog and two workers is one answer too few** (RK119). Every tier above is a pure
44
+ function of the file, so a second caller reading an unchanged roadmap is handed the line the
45
+ first one took — tier 1 most confidently of all, since a 🛠 line is *evidence* somebody
46
+ started. So a claim that is still live is stepped around before the tiers see it, and
47
+ :func:`take` is the door that makes one: it answers and flips the marker inside a single
48
+ serialised transaction, because a pick that answered and then wrote would be two steps with
49
+ the race in the middle. What a claim is, how it expires and why it names nobody is
50
+ :mod:`roadkeep.claiming`; what is here is that a held line is **named** in the answer rather
51
+ than silently absent, which is the same rule ``designed`` follows for the lines it sets
52
+ aside — and the only way a caller can recognise a claim as its own.
53
+ """
54
+
55
+ from __future__ import annotations
56
+
57
+ from collections.abc import Mapping, Sequence
58
+ from dataclasses import dataclass, replace
59
+ from enum import StrEnum
60
+
61
+ from roadkeep import claiming
62
+ from roadkeep.authoring import StatusChange, set_status
63
+ from roadkeep.backlog import Backlog, DepStatus, Readiness, Stage, Standing, id_order
64
+ from roadkeep.claiming import Held
65
+ from roadkeep.config import Config
66
+ from roadkeep.kernel.document import Entry, declares, shading
67
+ from roadkeep.locking import exclusive
68
+ from roadkeep.queueing import declared
69
+ from roadkeep.kernel.schema import IN_PROGRESS, Dep
70
+
71
+ #: How many runners-up an answer carries. Bounded on purpose: the value of `pick` is that
72
+ #: its output fits in a tool result, and a ranked list of everything is the file again.
73
+ ALTERNATIVES = 3
74
+
75
+
76
+ class Tier(StrEnum):
77
+ """Which rule produced the answer. Printed, so the pick can be argued with."""
78
+
79
+ STARTED = "in-progress"
80
+ PRIORITY = "declared-priority"
81
+ LOWEST = "lowest-ready-id"
82
+
83
+
84
+ @dataclass(frozen=True, slots=True)
85
+ class Stalled:
86
+ """A started task that cannot be continued, and what is holding it."""
87
+
88
+ id: str
89
+ blockers: tuple[str, ...]
90
+ #: The live claim on this line, where there is one (RK152). Its own field and not
91
+ #: :attr:`Choice.held`, which is the ready lines a claim kept out of the ranking: one word
92
+ #: for both facts is how this report came to be silent about the second. The two states it
93
+ #: separates are "somebody started this and hit a wall", which invites unblocking it, and
94
+ #: "somebody is on this now, and the dep is what they are waiting for", which does not.
95
+ claimed: Held | None = None
96
+
97
+
98
+ #: How many releasing ids a waiting row names (RK1304), bounded for RK1301's reason: a
99
+ #: priority waiting on eleven things is one whose next step is a decision and not a command,
100
+ #: and the count says that where the roster would only spend the answer saying it.
101
+ RELEASES = 4
102
+
103
+
104
+ @dataclass(frozen=True, slots=True)
105
+ class Waiting:
106
+ """A declared priority nothing ready answers, and what would release it (RK1304).
107
+
108
+ Observed over four consecutive sessions on a port whose roadmap declares Priority as
109
+ Block H then Block I. Every line in both was blocked, so the pick fell through to the
110
+ lowest ready id and said so: *the roadmap's queue names nothing ready*. True, and one step
111
+ short — Block H held one line, blocked on a single task in another block, and nothing in
112
+ the answer said which. The caller who wanted the priority had to open the roadmap, read
113
+ the queue, find the block's lines, read their deps and look each one up, which is the
114
+ reading this verb exists to replace, done by hand, at the moment it was least obvious.
115
+
116
+ Beside the pick and never instead of it: the pick may still be the right call when the
117
+ blocker is expensive. The case that makes this worth having is the other one, where it is
118
+ cheap and nobody looked.
119
+ """
120
+
121
+ #: The queue token, as the queue spells it — a `Block X` or an id.
122
+ token: str
123
+ #: Open lines the token names. Every one of them blocked, or this row would not exist.
124
+ lines: int
125
+ #: The ids whose shipping would release one of those lines: their unsatisfied deps,
126
+ #: deduplicated and in id order, bounded by :data:`RELEASES`.
127
+ releases: tuple[str, ...] = ()
128
+ #: How many there are in all, so a cut roster is never read as a short one.
129
+ of: int = 0
130
+
131
+
132
+ @dataclass(frozen=True, slots=True)
133
+ class Lacking:
134
+ """A ready line this caller cannot finish, and what it would take (RK1297).
135
+
136
+ Named and never merely counted, for the reason :attr:`Choice.held` is: a number the
137
+ caller cannot read is a line it asks about twice. Here the id is not even the actionable
138
+ half — :attr:`missing` is, because what closes this is somebody with a DualSense on the
139
+ desk rather than any command the caller could run.
140
+ """
141
+
142
+ id: str
143
+ #: The declared requirements this caller did not say it has, in the line's own order.
144
+ missing: tuple[str, ...]
145
+
146
+
147
+ @dataclass(frozen=True, slots=True)
148
+ class Choice:
149
+ """The answer, or the reasoned absence of one."""
150
+
151
+ entry: Entry | None
152
+ tier: Tier | None
153
+ reason: str
154
+ #: The block the question was scoped to, when it was (RK40). Every count and every
155
+ #: alternative below is then about that block and nothing else.
156
+ block: str | None = None
157
+ #: The next few ready tasks, in the same order the pick came from.
158
+ alternatives: tuple[str, ...] = ()
159
+ ready: int = 0
160
+ blocked: int = 0
161
+ outside: int = 0
162
+ #: Open lines waiting on work somebody set aside (RK92). Its own number for RK28's
163
+ #: reason: a backlog stuck on paused deps is stuck on a decision, not on a task.
164
+ paused: int = 0
165
+ stalled: tuple[Stalled, ...] = ()
166
+ #: Whether the chosen line still needs designing (RK83). Said, never acted on: it is
167
+ #: the sentence that stops the pick being silent about which of the two states it is.
168
+ needs_design: bool = False
169
+ #: How many ready lines ``designed`` set aside. 0 whenever the flag was not passed, so
170
+ #: a non-zero value is always the caller's own filter and never a fact about the file.
171
+ undesigned: int = 0
172
+ #: The ready lines a live claim kept out of the ranking (RK119). Named and not counted,
173
+ #: because a claim names nobody: a caller can only tell one of these is its own by
174
+ #: reading the id, and a number it cannot read is a line it will ask about twice.
175
+ held: tuple[Held, ...] = ()
176
+ #: The ready lines a requirement this caller does not have kept out of the ranking
177
+ #: (RK1297). Beside `held` and `undesigned` because it is the third thing that narrows an
178
+ #: offer without narrowing the truth — `ready` still counts these — and apart from both
179
+ #: because it is the only one nothing the caller does will change: a claim expires and a
180
+ #: design gets written, and a PS5 does not arrive because a command was run.
181
+ lacking: tuple[Lacking, ...] = ()
182
+ #: What the declared priority is waiting on, where nothing ready answers it (RK1304).
183
+ #: Empty on every other call — a queue the pick came *from* has nothing to be waiting for,
184
+ #: and a project that declares none has no queue to ask about.
185
+ waiting: tuple[Waiting, ...] = ()
186
+ #: What became of the block the question was scoped to (RK429). Absent on an unscoped
187
+ #: pick, where there is no label to have a state — and carried even when a line *was*
188
+ #: chosen, so a caller reading the payload never has to ask a second command what the
189
+ #: scope it just picked from is.
190
+ standing: Standing | None = None
191
+
192
+ @property
193
+ def found(self) -> bool:
194
+ return self.entry is not None
195
+
196
+ @property
197
+ def stage(self) -> Stage | None:
198
+ """The scope's state as the one word a caller branches on, or None if unscoped."""
199
+ return None if self.standing is None else self.standing.stage
200
+
201
+ @property
202
+ def counts(self) -> str:
203
+ """All four numbers, always: a zero is the fact a reader is checking for."""
204
+ return (
205
+ f"{self.ready} ready, {self.blocked} blocked, "
206
+ f"{self.outside} blocked outside the backlog, "
207
+ f"{self.paused} blocked on paused work"
208
+ )
209
+
210
+
211
+ def pick(
212
+ config: Config,
213
+ block: str | None = None,
214
+ designed: bool = False,
215
+ *,
216
+ backlog: Backlog | None = None,
217
+ claims: bool = True,
218
+ available: Sequence[str] = (),
219
+ ) -> Choice:
220
+ """Apply the three tiers to the roadmap, and say which one answered.
221
+
222
+ ``block`` scopes every part of the answer — the tiers, the counts, the alternatives —
223
+ so that "nothing to pick" is a statement about *that* block (RK40). Unscoped, the
224
+ lowest ready id can live in another block, and reading that as "this block is
225
+ finished" is a mistake the ids being non-sequential makes easy.
226
+
227
+ ``designed`` sets aside the ready lines whose marker says the design is unwritten
228
+ (RK83), for a caller who asked to *execute* rather than to plan. It narrows what may
229
+ be chosen and nothing else: ``ready`` still counts every ready line, because the
230
+ number of lines this backlog could start is not a fact the caller's intent changes.
231
+
232
+ ``available`` is what the caller says it has, and it is the axis the other two are not
233
+ (RK1297): a line whose `(needs: …)` names anything absent from it is set aside, counted
234
+ and **named**. Empty by default, and that default is the decision — the caller who
235
+ cannot press a button is the one who does not think to say so, and a `pick` that offered
236
+ hardware work to it was the five identical answers this exists to stop. A person at the
237
+ desk says `--have`, and gets the line the agent could not have.
238
+
239
+ ``backlog`` answers over files somebody else read — the state a transaction is about to
240
+ write, or a revision (RK104) — and ``claims = False`` asks the question the tiers were
241
+ before RK119: *what do the files alone say*. Both exist for the projection (RK39), which
242
+ is published, has to be idempotent, and is derived from the repository — so a next-ready
243
+ line that moved because a claim in one checkout expired would put a README permanently
244
+ one temp file away from stale, with nothing in any commit to explain it.
245
+ """
246
+ if backlog is None:
247
+ backlog = Backlog.load(config)
248
+ if block is not None and block not in backlog.declared_blocks():
249
+ declared = sorted(backlog.declared_blocks())
250
+ raise KeyError(
251
+ f"no heading declares {config.schema.block_named(block)}"
252
+ # And not every label that is declared (RK296): the caller typed a block, they are
253
+ # not choosing from a menu of the other eighty-nine.
254
+ f"{declares(declared)}"
255
+ # As at the write refusal (RK216): scoping a pick to `A` where `AJ` is declared
256
+ # would otherwise read as "that block is empty" dressed as "that block is absent".
257
+ f"{shading(block, declared)}"
258
+ )
259
+ scope = f" in {config.schema.block_named(block)}" if block else ""
260
+ # Read before the survey and kept whatever the answer is (RK429): the ledger is what
261
+ # tells a finished block from a heading opened before its lines, and the tiers below
262
+ # cannot see it — they rank open lines, and both of those states have none.
263
+ standing = None if block is None else backlog.standing(block)
264
+ considered = [
265
+ entry
266
+ for entry in backlog.roadmap.entries
267
+ if block is None or entry.task.block == block
268
+ ]
269
+ # Over every line in scope and not only the ready ones (RK152): a blocked 🛠 line was
270
+ # never a candidate and is still the line a reader most needs to know somebody is on.
271
+ claimed = (
272
+ {entry.id: entry for entry in claiming.live(config, considered)} if claims else {}
273
+ )
274
+ survey = _survey(backlog, considered, claimed)
275
+ ordered = sorted(survey.ready, key=lambda e: id_order(e.task.id, config.schema))
276
+ # Before the tiers and before `designed`, because a claim is a fact about the checkout
277
+ # while the flag is the caller's intent (RK119) — and because tier 1 would otherwise
278
+ # prefer exactly the held line, its premise being that a 🛠 line is work to continue.
279
+ held = tuple(claimed[e.task.id] for e in ordered if e.task.id in claimed)
280
+ if held:
281
+ ordered = [e for e in ordered if e.task.id not in claimed]
282
+ # Before the tiers, for the claim's own reason (RK1297): tier 1 prefers a 🛠 line, and a
283
+ # started line whose hardware is not on this desk is exactly the one that comes back
284
+ # every call — somebody began it where the controller was, and this caller cannot
285
+ # continue it. Stepped around here, so the tiers rank only what could actually be done.
286
+ has = frozenset(available)
287
+ lacking = tuple(
288
+ Lacking(entry.task.id, missing)
289
+ for entry in ordered
290
+ if (missing := tuple(one for one in entry.task.requires if one not in has))
291
+ )
292
+ if lacking:
293
+ short = {one.id for one in lacking}
294
+ ordered = [e for e in ordered if e.task.id not in short]
295
+ # Narrowed after the ordering and not before it, so `ready` keeps counting what the
296
+ # file holds: the caller's intent decides what may be offered, never what is true.
297
+ offered = [e for e in ordered if not config.schema.needs_design(e.task.status)]
298
+ set_aside = len(ordered) - len(offered) if designed else 0
299
+ if designed:
300
+ ordered = offered
301
+ counts = {
302
+ "block": block,
303
+ "blocked": survey.blocked,
304
+ "outside": survey.outside,
305
+ "paused": survey.paused,
306
+ "stalled": survey.stalled,
307
+ "undesigned": set_aside,
308
+ "held": held,
309
+ "lacking": lacking,
310
+ "standing": standing,
311
+ # Asked of the whole survey and not of `ordered` alone (RK1304): the question is what
312
+ # the queue's *blocked* lines are waiting on, and `ordered` is by construction the
313
+ # lines that are waiting on nothing.
314
+ "waiting": _waiting(backlog, config, ordered, considered),
315
+ }
316
+ if not ordered:
317
+ return Choice(
318
+ entry=None,
319
+ tier=None,
320
+ reason=_absence(
321
+ scope,
322
+ open_lines=bool(considered),
323
+ held=held,
324
+ set_aside=set_aside,
325
+ lacking=lacking,
326
+ standing=standing,
327
+ ),
328
+ ready=len(survey.ready),
329
+ **counts,
330
+ )
331
+
332
+ chosen, tier, why = _first(ordered, config)
333
+ rest = tuple(e.task.id for e in ordered if e is not chosen)[:ALTERNATIVES]
334
+ needs_design = config.schema.needs_design(chosen.task.status)
335
+ reason = f"{why}{scope}" if tier is Tier.LOWEST else why
336
+ if needs_design:
337
+ # Appended to the tier's own reason rather than replacing it: the tier still fired
338
+ # and is still a fact, and what was missing was never the choice but the caveat.
339
+ reason = f"{reason} — it still needs designing, which `--designed` skips"
340
+ return Choice(
341
+ entry=chosen,
342
+ tier=tier,
343
+ reason=reason,
344
+ alternatives=rest,
345
+ ready=len(survey.ready),
346
+ needs_design=needs_design,
347
+ **counts,
348
+ )
349
+
350
+
351
+ @dataclass(frozen=True, slots=True)
352
+ class Claim:
353
+ """A line taken, and the marker change that took it (RK119)."""
354
+
355
+ #: Absent where the caller named the id (RK149): there was no choice, so there is no tier
356
+ #: and no runner-up to report, and inventing an empty one would read as a pick that found
357
+ #: nothing rather than a pick that never happened.
358
+ choice: Choice | None
359
+ #: Absent when there was nothing to claim — an empty answer, not a refused write.
360
+ change: StatusChange | None = None
361
+
362
+ @property
363
+ def taken(self) -> bool:
364
+ return self.change is not None
365
+
366
+
367
+ def take(
368
+ config: Config,
369
+ block: str | None = None,
370
+ designed: bool = False,
371
+ *,
372
+ available: Sequence[str] = (),
373
+ ) -> Claim:
374
+ """Answer and claim in one indivisible step (RK119).
375
+
376
+ The lock is around **both**, and that is the whole mechanism: a pick that answered and
377
+ then flipped the marker would be two commands with the race between them, which is the
378
+ defect one layer along rather than the fix. What the claim consists of is the 🛠 the
379
+ roadmap now carries — durable, and git's to move — plus its date in
380
+ :mod:`roadkeep.claiming`, which is neither.
381
+
382
+ Nothing ready is not a failure: the empty answer comes back exactly as `pick` gave it,
383
+ because a caller asking for work and being told there is none got the fact it asked for.
384
+ The marker is written through `set_status`, so every refusal that guards a marker guards
385
+ this one too — a sibling file already stating status, a duplicated id — and a line
386
+ already at 🛠 whose claim expired is re-dated without a write it does not need.
387
+
388
+ **The claim is that marker write and nothing else** (RK159). Dating it here as well would
389
+ be a second writer of the one rule this design states out loud — a claim follows the
390
+ marker — and two writers of one rule is how the doors came to disagree to begin with.
391
+ """
392
+ with exclusive(config.root):
393
+ choice = pick(config, block, designed, available=available)
394
+ if choice.entry is None:
395
+ return Claim(choice=choice)
396
+ change = set_status(config, choice.entry.task.id, IN_PROGRESS)
397
+ # The entry is replaced by the line as written, so the answer shows the marker the
398
+ # caller now holds rather than the one it was chosen under.
399
+ return Claim(choice=replace(choice, entry=change.entry), change=change)
400
+
401
+
402
+ def hold(config: Config, task_id: str) -> Claim:
403
+ """Claim the line a caller named, refusing one another worker is already holding (RK149).
404
+
405
+ The second door, because a *named* claim is a different act from a chosen one, and the
406
+ difference is only visible on a collision: :func:`take` steps around a live claim because
407
+ it was choosing anyway, and here there is nowhere to step — so the answer is
408
+ :class:`~roadkeep.claiming.AlreadyHeld`, and never a second worker sent at one line.
409
+
410
+ What it does not do is judge the line. `pick` never offers blocked work, and a caller
411
+ that named an id may be about to unblock it; the marker door this goes through has always
412
+ allowed that, and a policy here would be this command re-deciding what `status` decides.
413
+
414
+ It neither writes the registry nor reads it (RK159, RK160): the claim *and* the refusal
415
+ both belong to the marker write, which is one name for one rule — and the refusal had to
416
+ move there anyway, `status <id> 🛠` being the same write with nothing guarding it.
417
+ """
418
+ with exclusive(config.root):
419
+ return Claim(choice=None, change=set_status(config, task_id, IN_PROGRESS))
420
+
421
+
422
+ def _absence(
423
+ scope: str,
424
+ *,
425
+ open_lines: bool,
426
+ held: tuple[Held, ...],
427
+ set_aside: int,
428
+ lacking: tuple[Lacking, ...] = (),
429
+ standing: Standing | None = None,
430
+ ) -> str:
431
+ """Why nothing was offered — five sentences, because they are five different states.
432
+
433
+ Telling them apart is the whole point of the scope (RK40): a block with nothing left is
434
+ finished, one whose lines are all blocked is not, one whose ready lines are all ideas is
435
+ waiting on a design session, and one whose ready lines are all claimed is waiting on the
436
+ workers holding them — which is the only one of the four that ends by itself.
437
+
438
+ The first of those four was itself two (RK429). "Nothing is open in Block C" is what a
439
+ finished block and a heading opened before its lines both produce, and the caller who
440
+ typed the wrong letter reads the same words — so where a label was named, the sentence
441
+ is :attr:`Standing.sentence` and states which. Unscoped there is no label to have a
442
+ state, and the old sentence is still the whole truth.
443
+
444
+ The fifth is the one whose remedy is a **person** and not a command (RK1297). Every
445
+ other sentence here ends by somebody shipping, resuming, designing or letting a claim
446
+ go; this one ends by whoever has the hardware asking for the same line, which is why it
447
+ names what is missing rather than what to run — and why it goes first, being the only
448
+ one that tells the caller reading it that the work is not theirs to do.
449
+ """
450
+ if lacking and not held and not set_aside:
451
+ return (
452
+ f"every ready task{scope} needs something this caller does not have: "
453
+ f"{_missing(lacking)} — `--have` is how a caller that has one says so"
454
+ )
455
+ if held and not set_aside:
456
+ return f"every ready task{scope} is claimed by a worker who has not finished it"
457
+ if set_aside:
458
+ return (
459
+ f"every ready task{scope} still needs designing, so there is nothing "
460
+ "to implement"
461
+ )
462
+ if not open_lines:
463
+ return f"nothing is open{scope}" if standing is None else standing.sentence
464
+ return f"every open task{scope} is blocked, so there is nothing to start"
465
+
466
+
467
+ def _missing(lacking: Sequence[Lacking]) -> str:
468
+ """Every requirement standing between this caller and the ranking, once each.
469
+
470
+ The union and not a line-by-line list: the sentence is about what the caller has to
471
+ acquire, and one word repeated across six lines is one thing to go and get. Which lines
472
+ those are is :attr:`Choice.lacking`, printed under it and named there.
473
+ """
474
+ return ", ".join(dict.fromkeys(one for entry in lacking for one in entry.missing))
475
+
476
+
477
+ @dataclass(frozen=True, slots=True)
478
+ class _Survey:
479
+ """One pass over the lines in scope: who is ready, and who is not and why not."""
480
+
481
+ ready: tuple[Entry, ...]
482
+ blocked: int
483
+ outside: int
484
+ stalled: tuple[Stalled, ...]
485
+ paused: int = 0
486
+
487
+
488
+ def _survey(
489
+ backlog: Backlog, considered: list[Entry], claimed: Mapping[str, Held]
490
+ ) -> _Survey:
491
+ ready: list[Entry] = []
492
+ blocked = outside = paused = 0
493
+ stalled: list[Stalled] = []
494
+ for entry in considered:
495
+ readiness = backlog.readiness(entry.task)
496
+ if readiness is Readiness.READY:
497
+ ready.append(entry)
498
+ continue
499
+ if readiness is Readiness.OUTSIDE:
500
+ outside += 1
501
+ elif readiness is Readiness.PAUSED:
502
+ paused += 1
503
+ else:
504
+ blocked += 1
505
+ if entry.task.status == IN_PROGRESS:
506
+ stalled.append(
507
+ Stalled(
508
+ id=entry.task.id,
509
+ blockers=tuple(
510
+ r.dep.id for r in backlog.resolve(entry.task) if not r.satisfied
511
+ ),
512
+ claimed=claimed.get(entry.task.id),
513
+ )
514
+ )
515
+ return _Survey(
516
+ ready=tuple(ready),
517
+ blocked=blocked,
518
+ outside=outside,
519
+ stalled=tuple(stalled),
520
+ paused=paused,
521
+ )
522
+
523
+
524
+ def _waiting(
525
+ backlog: Backlog, config: Config, ordered: list[Entry], considered: list[Entry]
526
+ ) -> tuple[Waiting, ...]:
527
+ """What the declared priority is waiting on, where nothing ready answers it (RK1304).
528
+
529
+ Empty the moment **any** token names a ready line, which is the state `_first`'s second
530
+ tier fires in: the queue was answered, the pick came from it, and a row about what some
531
+ other token is blocked on would be a cost quoted against a question nobody asked. So this
532
+ is the sentence for exactly one state — the one the fall-through already names in prose
533
+ and stopped short of making actionable.
534
+
535
+ The blockers are read through :meth:`Backlog.resolve`, which is where :class:`Stalled`
536
+ reads its own: an unsatisfied dep is one answer in this tool and a second walk here would
537
+ be a second answer about what is holding a line.
538
+
539
+ **Only the open ones**, unlike :class:`Stalled`, and the difference is what the two rows
540
+ claim: that one names what is holding a line and this one names what would *release* it.
541
+ Nothing now open satisfies an `UNRESOLVABLE` dep by construction (RK432), a `DEFERRED` one
542
+ needs a `resume` before any ship, and an `UNKNOWN` id is a finding rather than a target —
543
+ so naming any of them here would be an offer nothing answers, which is worse than the
544
+ count on its own (RK16). A token left with no id says exactly that.
545
+ """
546
+ queue = declared(config)
547
+ if not queue:
548
+ return ()
549
+ ready = {entry.task.id for entry in ordered}
550
+ named: list[tuple[str, list[Entry]]] = []
551
+ for token in queue.tokens:
552
+ label = config.schema.block_of_dep(Dep(token))
553
+ under = [
554
+ entry
555
+ for entry in considered
556
+ if (entry.task.block == label if label is not None else entry.task.id == token)
557
+ ]
558
+ if any(entry.task.id in ready for entry in under):
559
+ return ()
560
+ if under:
561
+ named.append((token, under))
562
+ out: list[Waiting] = []
563
+ for token, under in named:
564
+ blockers = sorted(
565
+ {
566
+ resolution.dep.id
567
+ for entry in under
568
+ for resolution in backlog.resolve(entry.task)
569
+ if resolution.status is DepStatus.OPEN
570
+ },
571
+ key=lambda one: id_order(one, config.schema),
572
+ )
573
+ out.append(
574
+ Waiting(
575
+ token=token,
576
+ lines=len(under),
577
+ releases=tuple(blockers[:RELEASES]),
578
+ of=len(blockers),
579
+ )
580
+ )
581
+ return tuple(out)
582
+
583
+
584
+ def _first(ordered: list[Entry], config: Config) -> tuple[Entry, Tier, str]:
585
+ """The three tiers, in order, each returning the reason it fired."""
586
+ started = [e for e in ordered if e.task.status == IN_PROGRESS]
587
+ if started:
588
+ return (
589
+ started[0],
590
+ Tier.STARTED,
591
+ f"{started[0].task.id} is already in progress and ready to continue",
592
+ )
593
+
594
+ # The roadmap's section where one is declared, and `roadkeep.toml` otherwise (RK325).
595
+ # Named in the reason rather than merely applied: a project that wrote a section and is
596
+ # still being ordered by its config has a fact to learn, and the tier is where it reads.
597
+ queue = declared(config)
598
+ named = "the roadmap's queue" if queue.declared_in == "roadmap" else "declared priority"
599
+ for token in queue.tokens:
600
+ # Typed by the code that types a dep, so `Block X` cannot come to mean two things.
601
+ label = config.schema.block_of_dep(Dep(token))
602
+ if label is not None:
603
+ inside = [e for e in ordered if e.task.block == label]
604
+ if inside:
605
+ return (
606
+ inside[0],
607
+ Tier.PRIORITY,
608
+ f"{named} names Block {label}, whose lowest ready id it is",
609
+ )
610
+ continue
611
+ match = next((e for e in ordered if e.task.id == token), None)
612
+ if match is not None:
613
+ return match, Tier.PRIORITY, f"{named} names {token} and it is ready"
614
+
615
+ if queue:
616
+ return (
617
+ ordered[0],
618
+ Tier.LOWEST,
619
+ f"lowest ready id; {named} names nothing ready",
620
+ )
621
+ return ordered[0], Tier.LOWEST, "lowest ready id"
622
+
623
+
624
+ @dataclass(frozen=True, slots=True)
625
+ class Picked:
626
+ """What `pick` answers: the choice, and the claim where the call took one (RK1170).
627
+
628
+ Three values reached the handler and were rendered there — the choice, the claim and the
629
+ event — so this verb's two registers were a printer in `verbs/querying.py` and a builder in
630
+ `rendering.py`, neither of them where the choice is made. One record carries both, and the
631
+ five sentences it shares with `brief` compose here because those produce rows now.
632
+
633
+ `config` is a field and not a parameter, unlike `View.stated`'s: every row this renders needs
634
+ it — the file a line sits on, the claim window, the offer to withdraw a heading — and this
635
+ record is built by the verb that already holds the project.
636
+ """
637
+
638
+ config: Config
639
+ choice: Choice
640
+ claim: Claim | None
641
+ event: Mapping[str, object] | None
642
+
643
+ def __str__(self) -> str: # noqa: PLR0912 - the rows are a list, not a branch tree
644
+ """The answer a reader scans, or the reasoned absence of one.
645
+
646
+ Nothing ready is an answer and not a failure: the exit stays 0 and the reason carries the
647
+ counts, so a caller can tell *backlog finished* from *everything is blocked*.
648
+ """
649
+ from roadkeep.rendering import ( # noqa: PLC0415 - RK260, the cycle's one direction
650
+ _claim_rows,
651
+ _event_rows,
652
+ _held_rows,
653
+ _lacking_rows,
654
+ _stalled_rows,
655
+ _undesigned_rows,
656
+ _waiting_rows,
657
+ )
658
+
659
+ choice, config = self.choice, self.config
660
+ if choice.entry is None:
661
+ return "\n".join(
662
+ [
663
+ f"nothing to pick: {choice.reason}",
664
+ f" backlog {choice.counts}",
665
+ *_undesigned_rows(choice),
666
+ *_lacking_rows(choice),
667
+ *_waiting_rows(choice),
668
+ *_held_rows(choice),
669
+ *_stalled_rows(choice),
670
+ ]
671
+ )
672
+ entry = choice.entry
673
+ where = f"{config.relative(config.path('roadmap'))}:{entry.lineno}"
674
+ rows = [
675
+ f"{entry.task.id} Block {entry.task.block} {entry.task.status} {where}",
676
+ f" because {choice.reason}",
677
+ f" backlog {choice.counts}",
678
+ f" symptom {entry.task.symptom}",
679
+ ]
680
+ if choice.alternatives:
681
+ rows.append(f" or {', '.join(choice.alternatives)}")
682
+ rows += _undesigned_rows(choice)
683
+ rows += _lacking_rows(choice)
684
+ # Beside the pick and never instead of it (RK1304): the fall-through is still the right
685
+ # call when the blocker is expensive, and the caller is the one who knows which it is.
686
+ rows += _waiting_rows(choice)
687
+ rows += _held_rows(choice)
688
+ rows += _stalled_rows(choice)
689
+ taken = _claim_rows(self.claim, config)
690
+ rows += taken
691
+ if taken and self.event is not None:
692
+ # Beside the claim and not at the end, which is where `brief` puts it too: an event
693
+ # line after a paragraph of prose is one a hook reader has to hunt for.
694
+ rows += _event_rows(dict(self.event), " ")
695
+ return "\n".join(rows)
696
+
697
+ def payload(self) -> dict[str, object]:
698
+ """The answer as one object, beside `Brief`'s and for the same reason it exists."""
699
+ choice, config = self.choice, self.config
700
+ entry = choice.entry
701
+ return {
702
+ "pick": None
703
+ if entry is None
704
+ else {
705
+ "id": entry.task.id,
706
+ "block": entry.task.block,
707
+ "status": entry.task.status,
708
+ "file": config.relative(config.path("roadmap")),
709
+ "line": entry.lineno,
710
+ "symptom": entry.task.symptom,
711
+ "ref": entry.task.ref,
712
+ },
713
+ "tier": None if choice.tier is None else str(choice.tier),
714
+ "reason": choice.reason,
715
+ "scope": choice.block,
716
+ # Beside `scope` and never instead of it (RK429): the label is what was asked and
717
+ # this is what became of it, so a loop scoped to a block reads one word rather than
718
+ # matching the sentence `reason` states it in.
719
+ "standing": None if choice.standing is None else choice.standing.payload(),
720
+ "alternatives": list(choice.alternatives),
721
+ "ready": choice.ready,
722
+ "blocked": choice.blocked,
723
+ "outside": choice.outside,
724
+ "paused": choice.paused,
725
+ "needs_design": choice.needs_design,
726
+ "undesigned": choice.undesigned,
727
+ # `claimed` on a stalled line and `held` beside it are two facts with two names
728
+ # (RK152): one is a line somebody is on that nothing could offer, the other is a
729
+ # candidate the ranking stepped around.
730
+ "stalled": [
731
+ {
732
+ "id": one.id,
733
+ "blockers": list(one.blockers),
734
+ "claimed": None
735
+ if one.claimed is None
736
+ else {"age": round(one.claimed.age), "since": one.claimed.since},
737
+ }
738
+ for one in choice.stalled
739
+ ],
740
+ "held": [
741
+ {"id": one.id, "age": round(one.age), "since": one.since}
742
+ for one in choice.held
743
+ ],
744
+ # The ready lines this caller cannot finish, and what each would take (RK1297).
745
+ # A list and not a count, for `held`'s reason and one more: a loop that hands
746
+ # work back to a person has to be able to say *which* work and *what for*.
747
+ "lacking": [
748
+ {"id": one.id, "missing": list(one.missing)} for one in choice.lacking
749
+ ],
750
+ # What the declared priority is waiting on (RK1304), where nothing ready answers
751
+ # it. `[]` on every other call and never omitted: a consumer reading a missing key
752
+ # cannot tell "the queue was answered" from "an older server".
753
+ "waiting": [
754
+ {
755
+ "token": one.token,
756
+ "lines": one.lines,
757
+ "releases": list(one.releases),
758
+ # The roster bounded and the count whole, which is RK1301's rule: a cut
759
+ # list is never read as a short one.
760
+ "of": one.of,
761
+ }
762
+ for one in choice.waiting
763
+ ],
764
+ "claimed": None
765
+ if self.claim is None
766
+ else {
767
+ "taken": self.claim.taken,
768
+ "from": None if self.claim.change is None else self.claim.change.before,
769
+ "to": None if self.claim.change is None else self.claim.change.after,
770
+ },
771
+ "event": None if self.event is None else dict(self.event),
772
+ }