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/briefing.py ADDED
@@ -0,0 +1,970 @@
1
+ """Everything it costs to start one task, in one call (RK29).
2
+
3
+ Starting RK1 in this repository cost reading `ROADMAP.md` and `IMPROVEMENTS.md` end to end
4
+ — some 5k tokens to learn one task, of which one line and one paragraph mattered. `pick`
5
+ (RK11) and `show` (RK12) each answer half; this composes them with the resolved deps
6
+ (RK28), the blocker chain (RK13) and the non-goals, so the answer to "start work" is a
7
+ single tool result.
8
+
9
+ **Bounded output is the point**, not a side effect: an answer that fits in a tool result
10
+ is an answer that costs nothing to consult twice, and one that does not fit gets replaced
11
+ by re-reading the file — which is the cost this removes. So the section is capped by its
12
+ own word budget (RK9), the chains by the graph's own limit, and the non-goals are carried
13
+ as *leads only*: enough to keep a proposal inside scope, not the paragraph that argues it.
14
+
15
+ Nothing here is stored and nothing is composed of new prose (L4): every field is another
16
+ module's answer, gathered in one place. Call it with no id and it briefs whatever `pick`
17
+ would choose, which makes the first call of a session the only one.
18
+
19
+ What it carries of the pick is the pick's own :class:`~roadkeep.picking.Choice` and not a
20
+ sentence copied out of it (RK154): a held line has to be *named* here for the reason it is
21
+ named there — a claim carries no owner, so an id is the only thing a caller recognises its own
22
+ by — and a field lifted out one at a time is a second place to keep in step.
23
+
24
+ **Which is why the claim has to be reachable from here** (RK149). RK119 made answering "what
25
+ next" a write so two agents get two lines, and put the flag on `pick` — the command a session
26
+ following the skill does not call, this one being the door that starts a task in one call. So
27
+ ``claim`` takes the line as well as describing it, and the module's promise narrows from
28
+ *writes none* to *writes one marker, and only when asked*. The two callers it serves are not
29
+ the same act: with no id the claim is `pick`'s, which steps around what somebody else holds,
30
+ and with an id it is the caller's own assertion, which is refused where a live claim already
31
+ answers for that line (:func:`roadkeep.picking.hold`).
32
+ """
33
+
34
+ from __future__ import annotations
35
+
36
+ import textwrap
37
+ from collections.abc import Sequence
38
+ from dataclasses import dataclass, field
39
+
40
+ from roadkeep.backlog import Backlog, DepStatus, Readiness, Resolution, Standing
41
+ from roadkeep.budgeting import Budget, budget_of
42
+ from roadkeep.config import Config, Scope
43
+ from roadkeep.kernel.document import Document
44
+ from roadkeep.graph import Chain, Graph, Leverage
45
+ from roadkeep.history import Commit
46
+ from roadkeep import criteria, scoping
47
+ from roadkeep.claiming import Held
48
+ from roadkeep.locking import exclusive
49
+ from roadkeep.picking import Choice, Claim, Lacking, Waiting, hold, pick, take
50
+ from roadkeep.kernel.schema import Task
51
+ from roadkeep.remaining import Clause
52
+ from roadkeep.shipping import as_recorded, recording_cost, supersession_cost
53
+ from roadkeep.showing import View, show
54
+
55
+ #: How many blocker chains a brief carries. Lower than the graph's own limit on purpose:
56
+ #: a brief is read to start work, and the second chain is already context, not an answer.
57
+ CHAINS = 2
58
+
59
+ #: How many non-goals a brief carries, for the same reason (RK68): the list binds what may be
60
+ #: proposed, and a section long enough to need scrolling is the file back. Two live corpora
61
+ #: write seven and eight, so this is headroom over both rather than a cut anyone will meet.
62
+ NON_GOALS = 12
63
+
64
+ #: How many of the ids a task unblocks a brief carries (RK1301). The **count** is the answer —
65
+ #: it ranks this line against every other one and a caller reads it once — and the roster is
66
+ #: the file back: measured on quickshell, a fresh eighty-one-line backlog, where the first task
67
+ #: answered with seventy-nine ids spelled out, in a read RK29 bounded to a tool result and
68
+ #: RK1286 gave a ceiling. The case where the list is longest is exactly the case where it says
69
+ #: least, a task early in the graph unblocking essentially everything.
70
+ #:
71
+ #: `deps <id>` answers the roster whole and is where a caller who wants it goes. This number
72
+ #: bounds the printed row too, so the two registers cannot come to disagree about how much of
73
+ #: it a brief shows — it was the printer's own constant before it was a bound on the payload.
74
+ UNBLOCKS = 4
75
+
76
+ #: What a cut lead ends with. A space before it, so the mark reads as the tool's and not as
77
+ #: an author's ellipsis — the cut has to be visible where it happens, never silent.
78
+ ELLIPSIS = " …"
79
+
80
+
81
+ class NothingToBrief(KeyError):
82
+ """`pick` found no ready task, so there is nothing to start. Not a failure.
83
+
84
+ Carries the held ids where a claim is what emptied the answer (RK154): "every ready task
85
+ is claimed by a worker who has not finished it" is the one absence in this design a
86
+ caller cannot act on without them, a claim naming no owner and its own being the one it
87
+ would otherwise ask about again next turn.
88
+ """
89
+
90
+ def __init__(
91
+ self,
92
+ reason: str,
93
+ held: tuple[Held, ...] = (),
94
+ standing: Standing | None = None,
95
+ lacking: tuple[Lacking, ...] = (),
96
+ ) -> None:
97
+ self.held = held
98
+ #: The ready lines this caller has no way to finish, and what each would take
99
+ #: (RK1297). Carried for `held`'s reason and one further: a claim ends by itself,
100
+ #: and this absence ends only when the ids reach somebody who has the thing — so a
101
+ #: caller that cannot name them cannot even hand the work over.
102
+ self.lacking = lacking
103
+ #: What became of the block this was scoped to (RK429), where one was named. The
104
+ #: sentence above already states it; this is the same fact as a word, so a loop
105
+ #: driving a block to completion branches on `finished` rather than on English.
106
+ self.standing = standing
107
+ #: The bare sentence, before this class wraps it (RK409). Kept as a field because
108
+ #: `brief --json` answers this branch too now, and recovering it from `str(self)`
109
+ #: means stripping a prefix and `KeyError`'s own quoting — two spellings of the
110
+ #: reason, one of which goes wrong the first time either half is reworded.
111
+ self.reason = reason
112
+ named = ", ".join(f"{one.id} ({one.since} ago)" for one in held)
113
+ # Beside the held ids and on the same line, because this register is one string
114
+ # (RK1297): the sentence already says a requirement is missing, and these are the
115
+ # lines it is missing *for* — the half a caller needs to hand the work to somebody.
116
+ short = ", ".join(f"{one.id} ({', '.join(one.missing)})" for one in lacking)
117
+ super().__init__(
118
+ f"nothing to brief: {reason}"
119
+ + (f" — held: {named}" if named else "")
120
+ + (f" — absent: {short}" if short else "")
121
+ )
122
+
123
+
124
+ @dataclass(frozen=True, slots=True)
125
+ class DoneWhen:
126
+ """What would finish this task and what would finish its block (RK1265, RK1268).
127
+
128
+ :class:`NonGoals`' two fields for its reason, and a third thing this one has to state
129
+ without a field — **an empty list is not an empty answer here**. A block nobody wrote a
130
+ criterion for and a block whose criteria were all dropped are different facts, and `brief`
131
+ prints neither row rather than inventing a sentence about which: the difference is
132
+ `criterion list`'s to report, where a caller went to ask.
133
+
134
+ Two lists and not one, because they are two altitudes and the answer would otherwise
135
+ conflate them: the block's says when the body of work is finished and the task's own says
136
+ when this line is, and an agent starting the line is asking the second.
137
+ """
138
+
139
+ leads: tuple[str, ...] = ()
140
+ #: How many the block's list held beyond the ones carried. 0 means these are all.
141
+ elided: int = 0
142
+ #: The task's own list, addressed by its id (RK1268), bounded the same way.
143
+ own: tuple[str, ...] = ()
144
+ #: How many the task's own list held beyond the ones carried. 0 means these are all.
145
+ own_elided: int = 0
146
+
147
+
148
+ @dataclass(frozen=True, slots=True)
149
+ class NonGoals:
150
+ """The scope a proposal has to stay inside: the leads carried, and what was left.
151
+
152
+ Two fields because a bounded list that does not say it is bounded reads as the whole
153
+ list — the failure this is the fix for, one level up (RK68).
154
+ """
155
+
156
+ leads: tuple[str, ...] = ()
157
+ #: How many bullets the section held beyond the ones carried. 0 means these are all.
158
+ elided: int = 0
159
+
160
+ def stated(self, config: Config) -> str:
161
+ """The list at the moment a task is proposed (RK69), as a reader is told it.
162
+
163
+ Beside :meth:`payload` since RK1170. The rows take the shape `brief` prints, so the
164
+ list is recognisable as the same list and not as a second one that happens to agree
165
+ today — which is what a second projection of a scope would be.
166
+ """
167
+ where = config.relative(config.path("roadmap"))
168
+ if not self.leads:
169
+ return f"{where}: no non-goals — nothing here says what may not be proposed"
170
+ # A project that has not opted in can still be read (RK70), and the report says which
171
+ # it is: `add` is what `[non_goals]` gates, and a listing that hid the difference would
172
+ # let a reader take an ungoverned list for an enforced one.
173
+ ungoverned = "" if config.non_goals is not None else " read-only: no [non_goals]"
174
+ rows = [f"{where} {len(self.leads)} non-goal(s){ungoverned}"]
175
+ rows += [f" not {lead}" for lead in self.leads]
176
+ if self.elided:
177
+ rows.append(f" not … and {self.elided} more under Non-goals")
178
+ return "\n".join(rows)
179
+
180
+ def payload(self, config: Config) -> dict[str, object]:
181
+ return {
182
+ "file": config.relative(config.path("roadmap")),
183
+ # A project that has not opted in can still be read — `add` is what `[non_goals]`
184
+ # gates (RK70), and refusing the read too would leave the scope of two live corpora
185
+ # unaskable.
186
+ "governed": config.non_goals is not None,
187
+ "non_goals": list(self.leads),
188
+ "non_goals_elided": self.elided,
189
+ }
190
+
191
+
192
+ @dataclass(frozen=True, slots=True)
193
+ class Settled:
194
+ """A dep that shipped **after** this design was last revised (RK1163).
195
+
196
+ Measured on a real run. A task asked whether a check should widen, and its rationale argued
197
+ both sides — widening risks a report full of findings about work somebody is still writing,
198
+ which is the noise that gets a check switched off. Its dep then shipped a unique index, and
199
+ that deleted one side of the trade-off: what was left to report could no longer be anybody's
200
+ unfinished draft. The section still read as an open question, and `brief` handed it over
201
+ verbatim beside `deps_resolved: shipped`. Both facts were on screen and nothing joined them.
202
+
203
+ **A date and not a judgement.** What changed is in the dep's own commit, and saying which
204
+ part of a design it settles would be this tool writing prose about a trade-off (L4). So the
205
+ fact is the ordering — the section predates the ship — and the reader decides.
206
+
207
+ Empty wherever git cannot answer, which is a checkout with no history and a project whose
208
+ prose file is untracked: a note that cannot be dated is a guess, and this is a query.
209
+ """
210
+
211
+ dep: str
212
+ #: The commit that shipped it, so the reader can go straight to what changed.
213
+ shipped: Commit
214
+ #: The last commit that touched this design, which is what "predates" is measured against.
215
+ revised: Commit
216
+
217
+
218
+ @dataclass(frozen=True, slots=True)
219
+ class Brief:
220
+ """One task, and every derived fact needed to start it."""
221
+
222
+ view: View
223
+ readiness: Readiness
224
+ deps: tuple[Resolution, ...]
225
+ chains: tuple[Chain, ...]
226
+ leverage: Leverage
227
+ non_goals: NonGoals
228
+ #: What would finish **this task's block** (RK1265), as leads in file order and bounded
229
+ #: the way the non-goals are. Beside them because they are the same kind of statement
230
+ #: pointed opposite ways — one binds what may be proposed, the other says when the body
231
+ #: of work is done — and a task starts against both or against neither.
232
+ done_when: DoneWhen = field(default_factory=lambda: DoneWhen())
233
+ #: The pick that chose this id, absent where the caller named one (RK154). The whole
234
+ #: answer and not the sentence it used to be: `held` is the ids a live claim was stepped
235
+ #: around, and with no owner field a caller recognises its own only by reading them. One
236
+ #: field rather than five, so the next question `pick` already answers is a field here and
237
+ #: not a change — while what this *prints* stays bounded, which is why the counts are left
238
+ #: to the command that is about them.
239
+ choice: Choice | None = None
240
+ #: The line taken, where the caller asked for it (RK149). Absent otherwise, so a brief
241
+ #: that claimed nothing cannot be read as one that did.
242
+ claim: Claim | None = None
243
+ #: Deps that shipped after this design was last revised (RK1163) — the question a
244
+ #: dependency may have answered, said as an ordering and never as a claim about the prose.
245
+ settled: tuple[Settled, ...] = ()
246
+ #: What the **ship** this brief is starting will have for prose (RK1174). The same field of
247
+ #: the same task, measured under the ledger's grammar: `[limits.changelog]` and a line with
248
+ #: no deps and no pointer in it. Two numbers for what an author thinks of as one thing, and
249
+ #: only the one that does not apply was shown before the write — measured across four ships
250
+ #: in one session, three of them refused for `why.too-long` on the first attempt.
251
+ #:
252
+ #: None where the project declares no changelog, and on a shipped line, which has no ship
253
+ #: left to compose for.
254
+ shipping: Budget | None = None
255
+ #: What the **decision** that same ship may file will have for prose (RK1275). Its own
256
+ #: field and not a clause of the row above, because it is not that sentence at all: a
257
+ #: `--decides` writes a line in the decisions role, under that role's own limits, and the
258
+ #: one sentence this format asked an author to compose blind was the one recording what
259
+ #: outlives the code. None where the project declares no such role.
260
+ deciding: Budget | None = None
261
+ #: What this line has left for prose (RK190). Here because a brief is the call that
262
+ #: starts a task, and the next write on the line it handed over is an `amend` — so the
263
+ #: number that would otherwise arrive as a refusal is already on the desk. None for a
264
+ #: shipped task: the ledger is a different grammar and holds no line to amend.
265
+ budget: Budget | None = None
266
+ #: What this task's design says would prove it done, and how many sites each clause
267
+ #: matches **now** (RK1184, RK1185). A count and a quotation, never the files behind
268
+ #: them: this answer is bounded to a tool result, and the addresses are what `evidence`
269
+ #: is for once the work is under way.
270
+ #:
271
+ #: Empty where the design declares no criterion, and that is answered with silence: most
272
+ #: tasks state one in prose and always have, so printing an absence every turn is a nag
273
+ #: this tool has no standing to make.
274
+ criterion: tuple[tuple[Clause, int], ...] = ()
275
+ #: What has already **landed** of this task, as the ledger records it (RK1226). One string
276
+ #: per `ship --part`, in the order the ledger holds them, and empty for the ordinary line
277
+ #: that has shipped nothing.
278
+ #:
279
+ #: `ship --part` records the half that landed and leaves the line open, which is the right
280
+ #: shape: the ledger gains an entry qualified by what shipped and the roadmap keeps a task
281
+ #: whose sentence is still partly true. What nothing held was the **other** half. Reading
282
+ #: the ⏳ line said the problem was not solved and reading the ledger said what was done, so
283
+ #: the remainder was reconstructed by subtracting one from the other — across two files,
284
+ #: from prose written for different purposes, by whoever picked the line up. That
285
+ #: reconstruction happened here several sessions later and needed the whole design read to
286
+ #: recover a remainder the person shipping had known precisely.
287
+ #:
288
+ #: The subtraction is still the reader's; what changes is that both sides of it are on one
289
+ #: answer. Naming the remainder as *data* is the stronger version and a change to the
290
+ #: model — a second field on the entry — which RK1226 leaves open rather than guessing at.
291
+ landed: tuple[str, ...] = ()
292
+
293
+ @property
294
+ def task(self) -> Task:
295
+ return self.view.task
296
+
297
+ @property
298
+ def picked(self) -> str:
299
+ """Why this id was chosen, or empty where the caller named it."""
300
+ return "" if self.choice is None else self.choice.reason
301
+
302
+ @property
303
+ def held(self) -> tuple[Held, ...]:
304
+ """The ready lines a live claim kept out of the pick this brief came from."""
305
+ return () if self.choice is None else self.choice.held
306
+
307
+ def _clauses(self) -> list[dict[str, object]]:
308
+ """What `ship`'s two optional flags spend out of the ledger sentence (RK1306).
309
+
310
+ Derived from the anchor and nothing else, which is the whole reason a number exists to
311
+ publish: `--superseded-design` parenthesises a note beside the pointer the line already
312
+ carries and `--recorded-in` wraps a path beside it, so the brackets and the address are
313
+ knowable before either is written and only the caller's own prose is not.
314
+
315
+ `[]` where there is no ship to compose for, or where the line points at nothing — both
316
+ figures are measured off an anchor, and inventing one would price a clause the write
317
+ cannot append. A record per flag rather than two keys, so `yours` can say **what the
318
+ number leaves out**: a consumer that added neither its note nor its path would
319
+ under-count by exactly the prose it is holding while it reads this.
320
+ """
321
+ if self.shipping is None or self.task.ref is None:
322
+ return []
323
+ return [
324
+ {
325
+ "flag": "--superseded-design",
326
+ "wrapper": supersession_cost(self.task.ref, self.task.id),
327
+ "yours": "the note",
328
+ },
329
+ {
330
+ "flag": "--recorded-in",
331
+ "wrapper": recording_cost(self.task.ref, self.task.id),
332
+ "yours": "the path",
333
+ },
334
+ ]
335
+
336
+ @property
337
+ def waiting(self) -> tuple[Waiting, ...]:
338
+ """What the declared priority is waiting on, where nothing ready answered it (RK1304).
339
+
340
+ Off the choice for :attr:`held`'s reason: it is a fact about the pick this brief came
341
+ from, so a brief called with an id has none — nothing was ranked and no queue was
342
+ consulted, and inventing the reading here would answer a question nobody asked.
343
+ """
344
+ return () if self.choice is None else self.choice.waiting
345
+
346
+ def stated(self, config: Config) -> str:
347
+ """Everything needed to start this task, as a reader is told it (RK29).
348
+
349
+ Beside :meth:`payload` since RK1170, and the last of the verbs that task measured: 20
350
+ prints in the handler against a builder in `rendering.py`, one answer in two files with
351
+ neither of them where the brief is composed. The five sentences shared with `pick` compose
352
+ here because those produce rows, which is what the two prerequisite slices bought.
353
+
354
+ **Bounded, and that is the claim this file exists to keep.** An answer that fits in a tool
355
+ result costs nothing to consult twice; one that does not gets replaced by re-reading the
356
+ file, which is the 5k tokens this verb exists to stop spending — so the non-goals are
357
+ elided with a count and the budget is one line rather than the whole table.
358
+ """
359
+ from roadkeep.rendering import ( # noqa: PLC0415 - RK260, the cycle's one direction
360
+ _claim_event,
361
+ _claim_rows,
362
+ _event_rows,
363
+ _held_rows,
364
+ _leverage_rows,
365
+ _waiting_rows,
366
+ )
367
+ from roadkeep.sections import heading_of # noqa: PLC0415 - RK260
368
+
369
+ view, task = self.view, self.task
370
+ rows = [
371
+ f"{task.id} Block {task.block} {task.status} {self.readiness} "
372
+ f"{view.file}:{view.entry.lineno}"
373
+ ]
374
+ if self.picked:
375
+ rows.append(f" picked {self.picked}")
376
+ if self.choice is not None:
377
+ # What the declared priority is waiting on, where nothing ready answered it
378
+ # (RK1304). Beside `picked` because that is the sentence it completes: *the queue
379
+ # names nothing ready* is true and does not say which task would change it.
380
+ rows += _waiting_rows(self.choice)
381
+ # The ids a live claim was stepped around (RK154), on the door a session starts a task
382
+ # with: without them the caller cannot tell one of them is its own.
383
+ rows += _held_rows(self.choice)
384
+ taken = _claim_rows(self.claim, config)
385
+ rows += taken
386
+ event = _claim_event(self.claim, config)
387
+ if taken and event is not None:
388
+ # Beside the claim and not at the end: the rationale section closes this output, and
389
+ # an event line after a paragraph of prose is one a hook reader has to hunt for.
390
+ rows += _event_rows(event, " ")
391
+ rows.append(f" symptom {task.symptom}")
392
+ rows.append(f" why {task.why}")
393
+ if self.budget is not None:
394
+ # One line, and only the field an amend rewrites (RK190): the whole table is
395
+ # `budget`'s answer, and a brief that grew one would stop being a bounded one.
396
+ why = self.budget.share("why")
397
+ # The same figure `budget` states, off the same `Share` (RK245): a brief that named
398
+ # the whole field's aim beside this line's remainder would be the second answer.
399
+ #
400
+ # `allowed`, and `on <the line>` in the words the two rows under it use (RK1375).
401
+ # These three exist to be **compared** — RK1174 prints the second only where it
402
+ # differs, because two numbers for one field is the fact worth seeing — and a
403
+ # reader made to translate `left` into `for the ledger line` before subtracting
404
+ # pays that cost through the phrasing instead of through the repetition. Since
405
+ # RK1366 neither figure is what is left beside anything, so `left` was the word
406
+ # that had stopped describing either, and the branch spelling it for a draft was
407
+ # unreachable from here: this budget is always the line as it stands.
408
+ rows.append(
409
+ f" budget why {why.allowed} on this line, {why.aimed}, "
410
+ f"{self.budget.prose} for prose"
411
+ )
412
+ if self.shipping is not None:
413
+ # The allowance for the write this brief is starting, which is not the one above
414
+ # (RK1174): a `ship` writes a ledger line, whose limit is `[limits.changelog]` and
415
+ # whose structure carries no deps and no pointer. Measured across four ships in one
416
+ # session, three refused for `why.too-long` on the first attempt — a refusal that
417
+ # names the arithmetic and cannot arrive early, which is what this line is for.
418
+ #
419
+ # Printed only where it **differs**: two numbers for one field is the fact worth
420
+ # seeing, and repeating the same one under another name teaches nobody anything.
421
+ ship = self.shipping.share("why")
422
+ if self.budget is None or ship.allowed != self.budget.share("why").allowed:
423
+ # And what a supersession takes out of the same sentence (RK1261). The other
424
+ # hedge stays a hedge because a qualifier is prose this cannot know; this one
425
+ # is *derived*, the anchor being the pointer the line already carries — and a
426
+ # task about to lose its design is exactly when this allowance is read, so an
427
+ # answer that omitted it was wrong precisely when it was asked for.
428
+ rows.append(
429
+ f" shipping why {ship.allowed} on the ledger line a `ship` writes, which "
430
+ f"is the limit that refuses it — the whole of it, that sentence replacing "
431
+ f"this line's rather than extending it (RK1365) — less a `--part` "
432
+ f"qualifier, which is structure this cannot know you will pass"
433
+ )
434
+ # Both clauses and no longer one (RK1275): two flags landed in that sentence
435
+ # after this row learned to name the first, so the figure was wrong by an
436
+ # amount this tool knows. A row of their own rather than a third subordinate
437
+ # clause — the line above is already the longest a brief prints.
438
+ if task.ref is not None:
439
+ rows.append(
440
+ f" shipping less {supersession_cost(task.ref, task.id)} for a "
441
+ f"`--superseded-design` clause and {recording_cost(task.ref, task.id)} for a "
442
+ f"`--recorded-in` wrapper, both into that same sentence — the note "
443
+ f"and the path are yours and are not in either number"
444
+ )
445
+ if self.deciding is not None:
446
+ # The third write, and the one that is not that sentence at all (RK1275): a
447
+ # `--decides` files a line in the decisions role under that role's own limits, so
448
+ # a reader given only the ledger's number was composing the durable half blind.
449
+ decided = self.deciding.share("why")
450
+ rows.append(
451
+ f" deciding why {decided.allowed} on the line `--decides` files, which is "
452
+ f"the decisions role's own limit and not the ledger's — the constraint that "
453
+ f"outlives the code, refused by that number"
454
+ )
455
+ # The **claim** that line inherits, where the decisions file is narrower than the
456
+ # roadmap (RK1281): `--decides` writes no symptom, so a ship refused over one is
457
+ # refused for a field no flag on the call reaches — and the read that could have
458
+ # said so beforehand priced the `why` and stopped. Printed only where it binds,
459
+ # which is two numbers for one field being the fact worth seeing (RK1174).
460
+ claim = self.deciding.share("symptom")
461
+ if self.budget is not None and claim.allowed < self.budget.share("symptom").allowed:
462
+ rows.append(
463
+ f" deciding symptom {claim.taken} of {claim.allowed} there, inherited "
464
+ f"from this line's own claim — `--decides` does not write one, so "
465
+ f"`restate` or a wider limit are the two doors if it does not fit"
466
+ )
467
+ settled = {one.dep: one for one in self.settled}
468
+ for resolution in self.deps:
469
+ rows.append(
470
+ f" dep {resolution.dep.id} {resolution.status} {resolution.detail}"
471
+ )
472
+ landed = settled.get(resolution.dep.id)
473
+ if landed is not None:
474
+ # The ordering and never a claim about the prose (RK1163): the design below was
475
+ # last written before this dep shipped, so a trade-off it argues may already be
476
+ # decided — and what decided it is in that commit, which is what this names.
477
+ rows.append(
478
+ f" shipped {landed.shipped.date[:10]} in "
479
+ f"{landed.shipped.short}, after this design was last written "
480
+ f"({landed.revised.date[:10]})"
481
+ )
482
+ rows += [f" chain {chain.render(task.id)} — {chain.detail}" for chain in self.chains]
483
+ if not view.shipped:
484
+ # What shipping this would unblock, which a shipped line has already done (RK324):
485
+ # `unblocks 0 of 14 open` beside a checkmark is a cost quoted for work that happened,
486
+ # and the readiness word above is the whole answer a caller needs about it.
487
+ rows += _leverage_rows(self.leverage)
488
+ rows += [
489
+ f" path {one.path}{'' if one.exists else ' (missing)'}" for one in view.paths
490
+ ]
491
+ # Before the criterion and after the deps, which is where a fact about *this* line's
492
+ # own history belongs (RK1226): what already landed is the other side of the
493
+ # subtraction whoever picks a partial up has to make, and the design is what they
494
+ # would otherwise read in full to make it.
495
+ rows += [f" landed {one}" for one in self.landed]
496
+ for clause, found in self.criterion:
497
+ # Before the design and after the deps, which is where the claim belongs: the
498
+ # order is the whole point (RK1185) — what the work will be measured against
499
+ # arrives before the first edit rather than at the `ship`. Never a verdict: `0`
500
+ # is the ordinary state of a task about to start.
501
+ rows.append(f" proves {clause} ({found} site(s) now)")
502
+ # The task's own first and the block's under it, each carrying its address (RK1268):
503
+ # two altitudes printed as one list is a reader taking the block's finish line for
504
+ # this line's, which is the conflation the second address exists to end.
505
+ rows += [f" done {self.view.task.id}: {lead}" for lead in self.done_when.own]
506
+ if self.done_when.own_elided:
507
+ rows.append(
508
+ f" done {self.view.task.id}: ... and {self.done_when.own_elided} more "
509
+ f"under Done when"
510
+ )
511
+ named = config.schema.block_named(self.view.task.block)
512
+ rows += [f" done {named}: {lead}" for lead in self.done_when.leads]
513
+ if self.done_when.elided:
514
+ rows.append(
515
+ f" done {named}: ... and {self.done_when.elided} more under Done when"
516
+ )
517
+ rows += [f" not {lead}" for lead in self.non_goals.leads]
518
+ if self.non_goals.elided:
519
+ # Where the list was cut, and not silently: a bounded list that reads as the whole
520
+ # one is a proposal made against a scope it never saw (RK68).
521
+ rows.append(f" not … and {self.non_goals.elided} more under Non-goals")
522
+ if view.section is not None:
523
+ rows += ["", heading_of(config.schema, view.section), "", view.section.body]
524
+ else:
525
+ rows.append(f" section none — {view.section_absence}")
526
+ return "\n".join(rows)
527
+
528
+ def payload(self, config: Config) -> dict[str, object]:
529
+ """The same answer as data, with the whole budget table and every count (RK29).
530
+
531
+ Beside :meth:`stated` and deliberately wider: a tool result is read by something that
532
+ can hold it, so what the printed register elides with a count this carries in full —
533
+ the non-goals, both allowances, and the commits behind a settled dep.
534
+ """
535
+ from roadkeep.rendering import ( # noqa: PLC0415 - RK260
536
+ _claim_event,
537
+ _dated_json,
538
+ )
539
+
540
+ return {
541
+ **self.view.payload(),
542
+ "readiness": str(self.readiness),
543
+ "picked": self.picked or None,
544
+ "deps_resolved": [
545
+ {
546
+ "dep": r.dep.id,
547
+ "kind": str(r.kind),
548
+ "status": str(r.status),
549
+ "detail": r.detail,
550
+ # Where this dep shipped after the design was last written (RK1163), the two
551
+ # commits that say so — beside the resolution rather than in a list of their
552
+ # own, because it is a fact *about* this dep and a consumer reading the row
553
+ # would otherwise join two arrays to find it.
554
+ **{
555
+ "settled_since": {
556
+ "shipped": _dated_json(one.shipped),
557
+ "revised": _dated_json(one.revised),
558
+ }
559
+ for one in self.settled
560
+ if one.dep == r.dep.id
561
+ },
562
+ }
563
+ for r in self.deps
564
+ ],
565
+ "chains": [
566
+ {
567
+ "path": [self.task.id, *(hop.target for hop in c.hops)],
568
+ "end": str(c.end),
569
+ "detail": c.detail,
570
+ }
571
+ for c in self.chains
572
+ ],
573
+ # The count whole and the roster bounded (RK1301), which is what the non-goals list
574
+ # in this same payload already does: a handful of ids, and how many were left, so a
575
+ # caller can tell a short list from a cut one without a second call. `deps <id>` is
576
+ # where the whole roster lives, and it is the read that answers that question.
577
+ "unblocks": {
578
+ "count": self.leverage.count,
579
+ "of": self.leverage.of,
580
+ "transitive": list(self.leverage.transitive[:UNBLOCKS]),
581
+ "transitive_elided": max(0, self.leverage.count - UNBLOCKS),
582
+ },
583
+ "non_goals": list(self.non_goals.leads),
584
+ "non_goals_elided": self.non_goals.elided,
585
+ "done_when": list(self.done_when.leads),
586
+ "done_when_elided": self.done_when.elided,
587
+ # The task's own, as its own key (RK1268): a caller merging the two would be
588
+ # asserting the block's finish line about this line.
589
+ "done_when_own": list(self.done_when.own),
590
+ "done_when_own_elided": self.done_when.own_elided,
591
+ # What the design says would prove this done, with what each clause matches now
592
+ # (RK1185). The clauses and the counts and never the sites: this answer is bounded
593
+ # to a tool result, and the addresses are `evidence`'s once the work is under way.
594
+ # `[]` where the design declares none, which is an answer and not an absence.
595
+ # What the ledger already records as landed, per `ship --part` (RK1226). `[]` on
596
+ # the ordinary line, which is an answer rather than an absence.
597
+ "landed": list(self.landed),
598
+ "criterion": [
599
+ {"pathspec": one.pathspec, "pattern": one.pattern, "sites": found}
600
+ for one, found in self.criterion
601
+ ],
602
+ # The whole table here and one line on stdout (RK190): a tool result is read by
603
+ # something that can hold it, and this is the number the next write is measured on.
604
+ "budget": None if self.budget is None else self.budget.payload(),
605
+ # The write about to be made (RK1174), as its **difference** from the table above
606
+ # rather than as a second copy of it (RK1298). Always published where it exists —
607
+ # unlike the printed line, which is silent when the two agree: a consumer comparing
608
+ # them wants the numbers present, and what it never wanted is five rows repeated to
609
+ # say nothing. `against` names the base, so the overlay needs no convention.
610
+ "shipping": None
611
+ if self.shipping is None
612
+ else self.shipping.delta(self.budget, "budget" if self.budget else None),
613
+ # The third write (RK1275), diffed against the second where there is one: a project
614
+ # declaring both roles usually declares them the same limits, so `changed: {}` is the
615
+ # answer — and it is a fact, where a third identical table was the same fact spelled
616
+ # in every row it has.
617
+ "deciding": None
618
+ if self.deciding is None
619
+ else self.deciding.delta(
620
+ self.shipping or self.budget,
621
+ "shipping" if self.shipping else ("budget" if self.budget else None),
622
+ ),
623
+ # And what the two optional clauses spend **out of** that allowance (RK1306). The
624
+ # row above stdout has carried them since RK1261 and RK1275 and the payload never
625
+ # did, so the caller this project is built for — the one on the other end of the
626
+ # served tool — composed a `why` against the published number and was refused by
627
+ # arithmetic it had no way to do. Measured on quickshell at five ships out of five:
628
+ # QS8, QS9, QS10, QS87 and QS88 each took a `why.too-long` first, and every one
629
+ # passed `--recorded-in` or `--superseded-design` or both.
630
+ #
631
+ # The **wrappers** and never the whole clause, which is what makes them knowable:
632
+ # the anchor is the pointer the line already carries, so only the note and the path
633
+ # are the caller's — and those the caller is holding while it reads this. `[]`
634
+ # where the line points at nothing, both figures being derived from the anchor.
635
+ #
636
+ # **Not `doors`, and the name now says so** (RK1324). These are *costs* and not
637
+ # calls: RK1324's falsification asked whether the four names were four facts,
638
+ # and this is the one that was — so it keeps its own key and stops reading as
639
+ # the class a consumer looks for a runnable command in.
640
+ "clause_costs": self._clauses(),
641
+ # Same key and same shape as `pick`'s (RK154): one fact spelled two ways is two facts.
642
+ "held": [{"id": h.id, "age": round(h.age), "since": h.since} for h in self.held],
643
+ # And the same for what the priority is waiting on (RK1304), by the same rule: this
644
+ # verb answers the pick's question too, so it answers it in the pick's words.
645
+ "waiting": [
646
+ {
647
+ "token": one.token,
648
+ "lines": one.lines,
649
+ "releases": list(one.releases),
650
+ "of": one.of,
651
+ }
652
+ for one in self.waiting
653
+ ],
654
+ "claimed": None
655
+ if self.claim is None or self.claim.change is None
656
+ else {
657
+ "taken": True,
658
+ "from": self.claim.change.before,
659
+ "to": self.claim.change.after,
660
+ },
661
+ "event": _claim_event(self.claim, config),
662
+ }
663
+
664
+
665
+ def brief(
666
+ config: Config,
667
+ task_id: str | None = None,
668
+ block: str | None = None,
669
+ designed: bool = False,
670
+ claim: bool = False,
671
+ available: Sequence[str] = (),
672
+ ) -> Brief:
673
+ """Join every answer about one task, and take it where the caller asked to.
674
+
675
+ ``block`` scopes the pick when no id is given (RK40), so "start the next thing in
676
+ Block C" is one call whose absence of an answer is about Block C. ``designed`` narrows
677
+ it to work whose design is written (RK83) — the two flags together are what "execute
678
+ Block C" means, and neither reaches a brief the caller addressed by id.
679
+
680
+ ``available`` is what this caller has (RK1297), and it reaches the pick for the reason
681
+ the two above do: a brief is the call that *starts* work, so the one filter whose answer
682
+ is "not by you" belongs where the line is chosen and not where it is described.
683
+
684
+ ``claim`` moves the marker to in-progress (RK149). One lock covers the write **and** the
685
+ reading that follows it, so the brief describes the line as it was taken rather than as
686
+ some later state found it — the four reads being milliseconds, which is what makes
687
+ holding the write lock across them free.
688
+ """
689
+ if claim:
690
+ with exclusive(config.root):
691
+ return _gather(config, *_claimed(config, task_id, block, designed, available))
692
+ if task_id is None:
693
+ chosen = pick(config, block, designed, available=available)
694
+ if chosen.entry is None:
695
+ raise NothingToBrief(
696
+ chosen.reason, chosen.held, chosen.standing, chosen.lacking
697
+ )
698
+ return _gather(config, chosen.entry.task.id, chosen, None)
699
+ return _gather(config, task_id, None, None)
700
+
701
+
702
+ def _claimed(
703
+ config: Config,
704
+ task_id: str | None,
705
+ block: str | None,
706
+ designed: bool,
707
+ available: Sequence[str] = (),
708
+ ) -> tuple[str, Choice | None, Claim]:
709
+ """Take a line, by the tiers or by the id the caller gave, and say which happened."""
710
+ if task_id is not None:
711
+ return task_id, None, hold(config, task_id)
712
+ taken = take(config, block, designed, available=available)
713
+ if taken.choice is None or taken.choice.entry is None:
714
+ # The same absence `pick` reports and not a refusal: a caller asking for work and
715
+ # being told there is none got the fact it asked for, and nothing was written.
716
+ held = () if taken.choice is None else taken.choice.held
717
+ raise NothingToBrief(
718
+ "" if taken.choice is None else taken.choice.reason,
719
+ held,
720
+ None if taken.choice is None else taken.choice.standing,
721
+ () if taken.choice is None else taken.choice.lacking,
722
+ )
723
+ return taken.choice.entry.task.id, taken.choice, taken
724
+
725
+
726
+ def _gather(
727
+ config: Config, task_id: str, chosen: Choice | None, claim: Claim | None
728
+ ) -> Brief:
729
+ """Every derived fact about one task, joined. This half reads and never writes."""
730
+ view = show(config, task_id)
731
+ backlog = Backlog.load(config)
732
+ graph = Graph.of(backlog)
733
+ entry = backlog.entry(task_id)
734
+ # A shipped task has no deps left to resolve: the ledger carries none, which is the
735
+ # schema saying a shipped line has no dependency to state. Its readiness is the ledger's
736
+ # own answer and not `ready` (RK324) — this is the command a session starts work with, so
737
+ # the one word it leads with is the one a caller acts on, and `show` already says shipped.
738
+ task = entry.task if entry is not None else view.task
739
+ readiness = backlog.readiness(task) if entry is not None else Readiness.SHIPPED
740
+ return Brief(
741
+ view=view,
742
+ readiness=readiness,
743
+ deps=backlog.resolve(task) if entry is not None else (),
744
+ chains=graph.chains(task_id)[:CHAINS] if entry is not None else (),
745
+ leverage=graph.leverage(task_id),
746
+ non_goals=non_goals(config, backlog.roadmap),
747
+ done_when=done_when(config, backlog.roadmap, task.block, task.id),
748
+ choice=chosen,
749
+ claim=claim,
750
+ settled=_settled(config, view, backlog.resolve(task) if entry is not None else ()),
751
+ budget=None if view.shipped else budget_of(config, task, open_line=True),
752
+ criterion=_criterion(config, view),
753
+ # A lookup this verb already performs (RK1226): the ledger is open because `shipping`
754
+ # is measured against it, so surfacing what has already landed costs nothing.
755
+ landed=_landed(backlog, task.id) if not view.shipped else (),
756
+ shipping=None
757
+ if view.shipped or not config.has("changelog")
758
+ else budget_of(
759
+ config,
760
+ # The task **as the ledger will hold it** and not as the roadmap holds it
761
+ # (RK1199): `ship` drops the deps and the pointer before it renders, so pricing
762
+ # the roadmap's task under the ledger's schema measured a structure ten
763
+ # characters wider than the line — an allowance with ten it could not spend, and
764
+ # a reader who trusted it and then watched `ship` accept more was told two things.
765
+ # Through `ship`'s own function, so the figure and the write cannot come apart.
766
+ #
767
+ # With the `why` **emptied** and not inherited (RK1365). `Share.left` subtracts what
768
+ # a field already holds, which is an `amend`'s question — and `ship --why` is
769
+ # required and *replaces* the roadmap's sentence, so the room for it is the whole
770
+ # allowance. Priced with that sentence still in the field, this read reported `37 of
771
+ # 200` against a ship that then accepted 145: a number four times under the real one
772
+ # fails in the direction that looks safe, and an advisory limit nobody believes still
773
+ # costs a line of every brief.
774
+ as_recorded(task, config.schema.shipped_marker, ""),
775
+ open_line=False,
776
+ schema=config.schema_for("changelog"),
777
+ ),
778
+ # The third write the same ship may make (RK1275), priced the same way and under the
779
+ # role's own schema: `--decides` renders a decision the way `ship` renders an entry,
780
+ # so the figure comes through `as_recorded` for the reason the one above does — and with
781
+ # the `why` emptied for the reason that one is (RK1365), a `--decides` sentence being
782
+ # written from nothing exactly as the entry's is.
783
+ deciding=None
784
+ if view.shipped or not config.has("decisions")
785
+ else budget_of(
786
+ config,
787
+ as_recorded(task, config.schema_for("decisions").shipped_marker, ""),
788
+ open_line=False,
789
+ schema=config.schema_for("decisions"),
790
+ ),
791
+ )
792
+
793
+
794
+ def non_goals(config: Config, document: Document) -> NonGoals:
795
+ """The lead of each bullet under the non-goals heading, in file order and bounded.
796
+
797
+ The lead and not the bullet: what keeps a proposal inside scope is *that* the line
798
+ exists, and the sentence arguing it is already in the file the caller can open. *Which*
799
+ characters are the lead is `scoping`'s answer and not one guessed here (RK68) — the
800
+ module that writes a non-goal is the one that says what its address is.
801
+
802
+ Bounded twice, for the reason the chains stop at two and a section has a word budget:
803
+ each lead is cut to the project's own `[non_goals]` limit (L6) with the cut *shown*, and
804
+ a list past :data:`NON_GOALS` reports how many it left. A field with no limit at all is
805
+ a forty-bullet section arriving in place of the file this call exists to replace.
806
+ """
807
+ limit = (config.non_goals or Scope()).lead
808
+ every = scoping.leads(document)
809
+ return NonGoals(
810
+ leads=tuple(
811
+ textwrap.shorten(lead, width=limit, placeholder=ELLIPSIS)
812
+ for lead in every[:NON_GOALS]
813
+ ),
814
+ elided=max(0, len(every) - NON_GOALS),
815
+ )
816
+
817
+
818
+
819
+ def done_when(
820
+ config: Config, document: Document, block: str, task_id: str = ""
821
+ ) -> DoneWhen:
822
+ """What finishes this task and what finishes its block, in file order and bounded (RK1265).
823
+
824
+ :func:`non_goals`' shape one list over, and bounded for its reasons: each lead is cut to
825
+ the project's own `[criteria]` limit with the cut shown, and a list past :data:`NON_GOALS`
826
+ reports how many it left. *Which* characters are the lead is `criteria`'s answer and not
827
+ one guessed here — the module that writes a criterion says what its address is.
828
+
829
+ Scoped to the task's own block and never to the backlog: a criterion is about a body of
830
+ work, so printing another block's would be answering a question the caller did not ask
831
+ with a claim about somebody else's finish line. And to the task's own list beside it
832
+ (RK1268), which is the narrower version of exactly that argument: the line is the unit
833
+ being executed, so what would finish *it* is the answer a brief was opened for.
834
+ """
835
+ limit = (config.criteria or Scope()).lead
836
+
837
+ def bounded(every: tuple[str, ...]) -> tuple[tuple[str, ...], int]:
838
+ return (
839
+ tuple(
840
+ textwrap.shorten(lead, width=limit, placeholder=ELLIPSIS)
841
+ for lead in every[:NON_GOALS]
842
+ ),
843
+ max(0, len(every) - NON_GOALS),
844
+ )
845
+
846
+ leads, elided = bounded(criteria.leads(document, block))
847
+ own, own_elided = bounded(criteria.leads(document, task_id) if task_id else ())
848
+ return DoneWhen(leads=leads, elided=elided, own=own, own_elided=own_elided)
849
+
850
+
851
+ def _criterion(config: Config, view: View) -> tuple[tuple[Clause, int], ...]:
852
+ """What this design says would prove the task done, counted now (RK1184, RK1185).
853
+
854
+ The clause and its count, never the sites: a brief is bounded to a tool result, and the
855
+ addresses are what `evidence` answers once the work is under way. **A criterion is read
856
+ at the start and not at the ship** — the order is the whole point, since a claim the work
857
+ will be measured against has to arrive before the first edit.
858
+
859
+ Silent on three shapes, all of which are answers rather than failures: a task with no
860
+ design, a design declaring no criterion, and a block this grammar cannot read. The last is
861
+ `lint`'s to report (RK1184) and refusing a brief over it would take away the call that
862
+ starts the work, on a fence the work has not touched yet.
863
+ """
864
+ from roadkeep.remaining import EVIDENCE, QueryError, count, declared # noqa: PLC0415 - RK260
865
+
866
+ if view.section is None:
867
+ return ()
868
+ try:
869
+ clauses = declared(view.section.body, EVIDENCE)
870
+ except QueryError:
871
+ return ()
872
+ if not clauses:
873
+ return ()
874
+ # Per clause and not one total: two clauses at 3 and 0 are a criterion half met, and a
875
+ # single `3` says the same thing as both met — which is the shape RK10 is about, one
876
+ # module over. One `count` each rather than attributing a joined answer afterwards: a
877
+ # `Site` carries no clause, and giving it one to serve this reader would be a field on
878
+ # the record that only a caller's arithmetic wanted.
879
+ return tuple(
880
+ (clause, count(config.root, view.task.id, (clause,), EVIDENCE).total)
881
+ for clause in clauses
882
+ )
883
+
884
+
885
+ def _landed(backlog: Backlog, task_id: str) -> tuple[str, ...]:
886
+ """Every qualifier the ledger records for this open id, in file order (RK1226).
887
+
888
+ **All of them and not the first.** Through this tool's own door there is at most one:
889
+ `SecondPartial` refuses a second `ship --part` on one id, because one id carries one
890
+ partial and then the completion. An **adopted** ledger is the other case, and it is the
891
+ one that decides the reader — Turing's holds 755 entries written before the tool existed,
892
+ and a history spelling two deliveries of one id is exactly what `adopt` takes in. `by_id`
893
+ answers the first entry per id by design (a duplicate is a lint error, not a merge), which
894
+ would name one of them and hide the other.
895
+
896
+ Silent where nothing landed, which is every ordinary line: a row saying *nothing has
897
+ shipped* on every brief is a nag this tool has no standing to make.
898
+ """
899
+ if backlog.ledger is None:
900
+ return ()
901
+ return tuple(
902
+ entry.task.part
903
+ for entry in backlog.ledger.entries
904
+ if entry.task.id == task_id and entry.task.part
905
+ )
906
+
907
+
908
+ def _settled(config: Config, view: View, deps: tuple[Resolution, ...]) -> tuple[Settled, ...]:
909
+ """Which shipped deps landed after this design was last written (RK1163).
910
+
911
+ Only the **shipped** ones, because an open dep has settled nothing and its date would be a
912
+ question about work in progress. Only where the task has a section: there is no design to
913
+ predate otherwise, and `brief` on a line whose prose is unwritten already says so.
914
+
915
+ Two git reads per shipped dep at most, on a command a session runs once to start a task —
916
+ and none at all for the common case of a task whose deps are open or absent. A failure to
917
+ read history is silence, never an error: `git_available` is the guard the rest of this
918
+ package uses and a note nobody can date is the guess L4 keeps out.
919
+ """
920
+ if view.section is None or not deps:
921
+ return ()
922
+ # Deferred for RK260's reason: `history` runs git, and no successful write path reaches it.
923
+ from roadkeep.history import ( # noqa: PLC0415
924
+ HistoryUnavailable,
925
+ git_available,
926
+ origin_of,
927
+ precedes,
928
+ revisions_of,
929
+ )
930
+
931
+ if not git_available():
932
+ return ()
933
+ if view.section_role is None or not config.has(view.section_role):
934
+ return ()
935
+ prose = config.path(view.section_role)
936
+ if not prose.is_file():
937
+ return ()
938
+ # The section's **span** and never a needle for its heading: a heading appears in the diff of
939
+ # the commit that wrote it and of nothing else, so a body-only `section amend` — the ordinary
940
+ # way a design is revised — would be invisible and every design would read as unrevised since
941
+ # the day it was filed. RK1126 measured that asymmetry one verb over.
942
+ try:
943
+ written = revisions_of(config, prose, view.section.first, view.section.last)
944
+ except (HistoryUnavailable, OSError):
945
+ # A project git cannot answer for — no repository, a checkout too shallow — says
946
+ # nothing rather than raising: this is a note on a query, and `brief` is the command a
947
+ # session starts a task with.
948
+ return ()
949
+ if not written:
950
+ return ()
951
+ revised = written[-1]
952
+ out: list[Settled] = []
953
+ for one in deps:
954
+ if one.status is not DepStatus.SHIPPED:
955
+ continue
956
+ try:
957
+ shipped = origin_of(config, one.dep.id).shipped_in
958
+ except (HistoryUnavailable, OSError):
959
+ continue
960
+ # Ancestry and not dates (RK1163): two commits in one second carry the same timestamp,
961
+ # and a rebase can order dates against the history. `precedes` answers the question the
962
+ # note is about — was this design written before that ship landed — and a design revised
963
+ # *in* the shipping commit is excluded, having read what changed.
964
+ if (
965
+ shipped is not None
966
+ and revised.sha != shipped.sha
967
+ and precedes(config, revised.sha, shipped.sha)
968
+ ):
969
+ out.append(Settled(dep=one.dep.id, shipped=shipped, revised=revised))
970
+ return tuple(out)