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/deferring.py ADDED
@@ -0,0 +1,708 @@
1
+ """The two doors the store needs, one of them the way back (RK91).
2
+
3
+ RK96 built the state and stopped there: a fifth marker in a fifth governed file, read by
4
+ the parser and the gate, and nothing that could put a line in it. So a pause was still
5
+ spelled as a retirement, which is terminal by construction โ€” the resolver reads a retired
6
+ dep as never (RK28), and a re-add cannot reclaim the id, because retired-never-reused is
7
+ enforced (RK4). Recording "not now" that way destroys exactly what makes it not-now: the
8
+ id every dependent names, the `ยงid` rationale, and the thread `origin` and `deps` key on.
9
+
10
+ :func:`defer` is the transaction `ship` and `retire` are, with two differences that are the
11
+ whole point:
12
+
13
+ * **The section is carried, not deleted.** A departure removes the design because a shipped
14
+ line has none left to state; a pause keeps it, and the gate already knows to leave a
15
+ section the store points at alone rather than reporting it as an orphan.
16
+ * **The destination is revivable.** :func:`resume` is the return direction the ledger's
17
+ doors lack, and it is the same all-or-nothing shape read backwards. That is not a reused
18
+ id: a deferred id was never retired, so the same work coming back under its own number is
19
+ the pause working, not the non-goal being crossed.
20
+
21
+ Two things this deliberately does not preserve, both because the file *is* the state (RK96):
22
+
23
+ * **The open marker.** The store holds โธ and nothing else, so ๐Ÿ“‹ and โณ are indistinguishable
24
+ the moment a line lands there. `resume --marker` is where the author says which it was โ€”
25
+ the default is the project's first, exactly as `add`'s is, and a marker invented from the
26
+ word "resume" would be this tool holding an opinion about someone else's maturity.
27
+ * **The indent.** A nested line said which roadmap line it belonged under (RK49), and that
28
+ line is not in the store โ€” the same reason `ship` files its entry at column zero.
29
+
30
+ The reason is a **derived prefix on the `why`**, which is `retire`'s shape one door over: the
31
+ author's sentence is never rewritten (L4), it is wrapped, and :func:`resume` unwraps exactly
32
+ what this module wrote. The prefix ends at the first ``): ``, so a reason that spells that
33
+ sequence is refused rather than stored โ€” a pause the return trip cannot undo is a pause that
34
+ silently became a rewrite of the design sentence.
35
+ """
36
+
37
+ from __future__ import annotations
38
+
39
+ from collections.abc import Sequence
40
+ from dataclasses import dataclass, replace
41
+ from pathlib import Path
42
+
43
+ from roadkeep import claiming, queueing
44
+ from roadkeep.authoring import Insertion, place, remove_entry
45
+ from roadkeep.backlog import Backlog, NotOpen, Whereabouts
46
+ from roadkeep.config import DESIGN_ROLES, Config
47
+ from roadkeep.kernel.document import Document, Entry, save_all
48
+ from roadkeep.markers import refresh
49
+ from roadkeep.provenance import invocation
50
+ from roadkeep.kernel.schema import PAUSED_CLOSE, PAUSED_OPEN, Task, authored_why, pause_reason
51
+ from roadkeep.sections import declaring
52
+
53
+ __all__ = [
54
+ "Carried",
55
+ "NoStore",
56
+ "NotSetAside",
57
+ "Pause",
58
+ "Resumption",
59
+ "SetAside",
60
+ "UnrecoverableReason",
61
+ "defer",
62
+ "resume",
63
+ ]
64
+
65
+ #: What the derived prefix opens and closes. One spelling, and since RK1115 it lives in the
66
+ #: kernel: this module composes it, and the rule that measures a `why` has to know what part
67
+ #: of one it wrote โ€” two spellings of that would be a limit disagreeing with the door about
68
+ #: which characters an author is charged for.
69
+ _OPEN = PAUSED_OPEN
70
+ _CLOSE = PAUSED_CLOSE
71
+
72
+
73
+ class NoStore(ValueError):
74
+ """A pause with nowhere to go: this project declares no deferred file (RK96).
75
+
76
+ Refused and not scaffolded on the way past. A governed file is a path in
77
+ `roadkeep.toml` (L6) and `init` is what writes one โ€” a store a `defer` invented at the
78
+ moment it needed one would be a format decided by a verb, which is the thing Block A
79
+ exists to prevent.
80
+ """
81
+
82
+ def __init__(self, task_id: str) -> None:
83
+ self.task_id = task_id
84
+ super().__init__(
85
+ f"{task_id} cannot be set aside: no deferred store is declared โ€” add "
86
+ f'`deferred = "<path>"` under [files] and create the file with its block '
87
+ f"headings, or retire the line if the pause is really an abandonment"
88
+ )
89
+
90
+
91
+ class NoPlacement(ValueError):
92
+ """`--marker` on a resume that places no line (RK1083).
93
+
94
+ The reconciling path removes the store's stale copy and leaves the roadmap alone, so the
95
+ open marker a returned line would come back at has nothing to be about. Refused rather
96
+ than ignored, which is `NoCompletion`'s and `NoSpan`'s rule: a flag accepted where it
97
+ can take no effect is a flag the caller believes took one.
98
+
99
+ The remedy is the ordinary one โ€” `status <id> <marker>` writes the marker of a line that
100
+ is already there โ€” and it is named, because a refusal that only says no costs the reader
101
+ the turn this one saves.
102
+ """
103
+
104
+ def __init__(self, task_id: str, where: str, lineno: int) -> None:
105
+ self.task_id = task_id
106
+ super().__init__(
107
+ f"--marker names the marker a returned line comes back at, and this call places "
108
+ f"none: {task_id} is already open at {where}:{lineno} and only the store's copy "
109
+ f"is removed โ€” `{invocation()} status {task_id} <marker>` writes the marker of a "
110
+ f"line that is already there"
111
+ )
112
+
113
+
114
+ class SetAside(ValueError):
115
+ """The store already holds this id, so there is no line here to pause."""
116
+
117
+ def __init__(self, task_id: str, where: str, lineno: int) -> None:
118
+ self.task_id = task_id
119
+ self.lineno = lineno
120
+ super().__init__(
121
+ f"{task_id} is already set aside in {where}:{lineno}: a second line would be "
122
+ f"two answers to when this work comes back, and nothing says which is right"
123
+ )
124
+
125
+
126
+ class NotSetAside(KeyError):
127
+ """`resume` against an id the store does not hold.
128
+
129
+ Names where it *is*, because "not in the store" is the same sentence for a task that is
130
+ open, one that shipped and one that never existed โ€” and only the last is a typo.
131
+ """
132
+
133
+ def __init__(self, task_id: str, where: str, *, elsewhere: str = "") -> None:
134
+ self.task_id = task_id
135
+ found = f" ({elsewhere})" if elsewhere else ""
136
+ super().__init__(
137
+ f"{task_id} is not in {where}{found}: resume returns a line the store holds, "
138
+ f"and a task that never paused has nothing to come back from"
139
+ )
140
+
141
+
142
+ class UnrecoverableReason(ValueError):
143
+ """A reason spelling the sequence that ends the derived prefix.
144
+
145
+ Refused at input rather than stored, because the damage is invisible until the return
146
+ trip: the unwrap stops at the first ``): ``, so the author's own sentence would come
147
+ back with the tail of the reason glued to its front, and `lint` cannot see a `why` that
148
+ is merely wrong.
149
+ """
150
+
151
+ def __init__(self, reason: str) -> None:
152
+ super().__init__(
153
+ f"the reason may not contain {_CLOSE!r}: it is what closes the derived prefix, "
154
+ f"and resume would restore a sentence the pause rewrote โ€” {reason!r}"
155
+ )
156
+
157
+
158
+ @dataclass(frozen=True, slots=True)
159
+ class Carried:
160
+ """The design a pause kept, and the file that actually declares it (RK229).
161
+
162
+ RK196 taught `ship` to resolve an anchor across the declared prose roles and to report
163
+ the file it wrote; this is the same sentence one verb over, and the reason it is a type
164
+ rather than a string is that the anchor alone is what let the CLI supply the rest โ€” a
165
+ project declaring `strategy` was told its design was kept in an `improvements` file it
166
+ does not have, and the KeyError that named it arrived *after* both writes.
167
+
168
+ `role` is None where no declared prose file holds the anchor, or where two do, and
169
+ `absence` is the sentence saying which โ€” never resolved by picking, for the reason a ship
170
+ does not pick either: which of two a line meant is `ref.ambiguous`, and a pointer
171
+ resolving to nothing is a `lint` finding this door has no business answering.
172
+ """
173
+
174
+ #: As the line spells it, `ยง` included โ€” the pointer, not the id it usually equals.
175
+ anchor: str
176
+ #: The prose role holding it, where exactly one does. `Config.path` takes it from here.
177
+ role: str | None = None
178
+ #: Why no role answered, ready to print. Empty exactly when `role` is not None.
179
+ absence: str = ""
180
+
181
+ def line(self, config: Config) -> str:
182
+ """The one line saying where a paused design stayed (RK229).
183
+
184
+ `kept in <file>` only where a file holds it. An absence spells itself instead of being
185
+ dressed as a location: "kept in IMPROVEMENTS.md" about a section that is not there
186
+ sends a reader to look, and the pause is right either way.
187
+
188
+ On the record since RK1170, where `_defer` was composing it: which file this resolved
189
+ to is what this type exists to carry, and a phrasing about it belongs with it.
190
+ """
191
+ if self.role is None:
192
+ return f"{self.anchor} โ€” {self.absence}"
193
+ return f"{self.anchor} kept in {config.relative(config.path(self.role))}"
194
+
195
+
196
+ @dataclass(frozen=True, slots=True)
197
+ class Pause:
198
+ """Every edit setting one line aside makes, as data, before it is written."""
199
+
200
+ task_id: str
201
+ #: The line as the store now holds it: โธ, and every other slot kept.
202
+ store: Insertion
203
+ #: The roadmap without it, with every annotation re-derived (RK8).
204
+ roadmap: Document
205
+ removed_from: int
206
+ refreshed: tuple[str, ...] = ()
207
+ marker: str = ""
208
+ #: The priority entry this pause took out (RK327), or `None` where the queue never
209
+ #: named it. Taken and not kept, because a paused line is one `pick` can never offer;
210
+ #: put back by the author at the `resume`, which is where the order is known again.
211
+ dequeued: str | None = None
212
+ #: The section this did **not** delete, named โ€” silence about a carried design reads
213
+ #: exactly like the deletion a departure makes. Resolved here and not by the caller
214
+ #: (RK229): the role is a fact about the files this transaction read.
215
+ carried: Carried | None = None
216
+ #: Open lines that still name this id. Reported and not refused: waiting on paused work
217
+ #: is a legitimate state, and it is what `deps` and RK92 are for.
218
+ dependents: tuple[str, ...] = ()
219
+
220
+ #: The checkout, so a claim on the paused line can be dropped (RK156). Every other door
221
+ #: releases one by moving the marker; this one takes the line out of the file the marker
222
+ #: is read in, which no later read can tell from a claim still held.
223
+ root: Path | None = None
224
+ #: Whether this call **reconciled** a contradiction rather than returning a line (RK1081):
225
+ #: the roadmap already carried the id, so the store entry was the stale half and only it
226
+ #: was removed. Reported rather than inferred โ€” the caller printing "returned to Block A"
227
+ #: over a line that never moved would be describing a write nobody made.
228
+ reconciled: bool = False
229
+
230
+ def save(self) -> tuple[Path, ...]:
231
+ """Write both files, and answer every path that took (RK1130).
232
+
233
+ The store first, for the reason the ledger goes first in a departure (RK118): the
234
+ arrival is written before the removal, so a crash between them leaves the line in
235
+ both files โ€” visible, and a `resume` away โ€” rather than in neither.
236
+ """
237
+ wrote = save_all(self.store.document, self.roadmap)
238
+ if self.root is not None:
239
+ # Last, and never a condition of the write: the worker who set this aside is not
240
+ # holding it, and a claim left behind would greet the `resume` (RK156). The same
241
+ # rule every marker write obeys (RK158), the marker here being โธ.
242
+ claiming.follow(self.root, self.task_id, self.marker, self.roadmap.entries)
243
+ return wrote
244
+
245
+ @property
246
+ def block(self) -> str:
247
+ return self.store.entry.task.block
248
+
249
+ def event(self, config: Config) -> dict[str, object]:
250
+ """What this pause did to the block it left (RK38), off the roadmap it wrote."""
251
+ from roadkeep.rendering import _event # noqa: PLC0415 - RK260
252
+
253
+ return _event(self.task_id, self.block, self.roadmap, config)
254
+
255
+ def stated(self, config: Config, wrote: Sequence[Path]) -> str:
256
+ """Where the line went, and what the pause kept (RK229, RK327).
257
+
258
+ Beside :meth:`payload` since RK1170. `wrote` is a parameter and not a field, because
259
+ :meth:`save` is the caller's step: a record that named paths before they were written
260
+ would be answering about a write that may not have happened.
261
+ """
262
+ from roadkeep.rendering import ( # noqa: PLC0415 - RK260
263
+ _dequeued_rows,
264
+ _event_rows,
265
+ _staging_rows,
266
+ )
267
+
268
+ roadmap = config.relative(config.path("roadmap"))
269
+ store = config.relative(config.path("deferred"))
270
+ rows = [
271
+ f"{self.task_id} {self.marker} {store}:{self.store.lineno} under Block {self.block}",
272
+ f" removed {roadmap}:{self.removed_from}",
273
+ ]
274
+ if self.carried is not None:
275
+ # Named, because every other door that moves a line deletes this section: silence
276
+ # about a design that was kept reads exactly like the deletion (RK6). The *file* is
277
+ # the pause's answer and never this line's (RK229) โ€” composing it here from the
278
+ # improvements default is what named a path a strategy-only project does not declare.
279
+ rows.append(f" carried {self.carried.line(config)}")
280
+ if self.dependents:
281
+ rows.append(f" still {', '.join(self.dependents)} name {self.task_id}")
282
+ if self.refreshed:
283
+ rows.append(f" derived {', '.join(self.refreshed)} (dep annotations re-derived)")
284
+ rows += _dequeued_rows(self.dequeued)
285
+ rows += _staging_rows(config.relative(one) for one in wrote)
286
+ rows += _event_rows(self.event(config), " ")
287
+ return "\n".join(rows)
288
+
289
+ def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
290
+ """The same answer as data, with the design this did not delete (RK229)."""
291
+ from roadkeep.rendering import ( # noqa: PLC0415 - RK260
292
+ _carried_json,
293
+ _wrote_json,
294
+ )
295
+
296
+ return {
297
+ "id": self.task_id,
298
+ "marker": self.marker,
299
+ "deferred": {
300
+ "file": config.relative(config.path("deferred")),
301
+ "line": self.store.lineno,
302
+ "rendered": self.store.rendered,
303
+ },
304
+ "roadmap": {
305
+ "file": config.relative(config.path("roadmap")),
306
+ "removed": self.removed_from,
307
+ },
308
+ "carried": _carried_json(config, self.carried),
309
+ "dequeued": self.dequeued,
310
+ "dependents": list(self.dependents),
311
+ "refreshed": list(self.refreshed),
312
+ **_wrote_json(config, wrote),
313
+ "event": self.event(config),
314
+ }
315
+
316
+
317
+ @dataclass(frozen=True, slots=True)
318
+ class Resumption:
319
+ """The same transaction read backwards: the line returns, the store lets it go."""
320
+
321
+ task_id: str
322
+ #: The roadmap as this write leaves it. A **document** and not an `Insertion` since
323
+ #: RK1086: that type is a line and the file that now holds it, which is right for the
324
+ #: act this verb was built for and wrong for the one RK1081 added. A reconciling call
325
+ #: places nothing, so it had to point the field at the entry it left alone โ€” and the
326
+ #: third act, where the *ledger* is what already states the outcome, has no entry
327
+ #: anywhere to point at. `Insertion(entry=None)` parses and the printer reads
328
+ #: `.entry.task.block` two lines later, which is how RK1084 found this rather than
329
+ #: shipping a verb.
330
+ roadmap: Document
331
+ #: The line this call put back, or `None` where it placed none. The two are different
332
+ #: answers and the shape now says which: a caller printing "returned to Block A" over a
333
+ #: line that never moved is describing a write nobody made (RK1083).
334
+ placed: Entry | None
335
+ store: Document
336
+ removed_from: int
337
+ refreshed: tuple[str, ...] = ()
338
+ marker: str = ""
339
+ #: The reason the pause recorded, removed from the `why` and reported once โ€” the last
340
+ #: place it is visible, because the line that comes back is a design and not a history.
341
+ was: str | None = None
342
+ #: The checkout, so the claim can follow the marker this returns the line at (RK158): a
343
+ #: `resume --marker ๐Ÿ› ` is an assertion that somebody is on it, like every other ๐Ÿ›  write.
344
+ #: What it did is not a field here โ€” the command prints the marker, which is the fact, and
345
+ #: a second copy of it would be a second thing to keep true.
346
+ root: Path | None = None
347
+ #: Whether this call **reconciled** a contradiction rather than returning a line (RK1081):
348
+ #: the roadmap already carried the id, so the store entry was the stale half and only it
349
+ #: was removed. Reported rather than inferred โ€” the caller printing "returned to Block A"
350
+ #: over a line that never moved would be describing a write nobody made.
351
+ reconciled: bool = False
352
+
353
+ def save(self) -> tuple[Path, ...]:
354
+ # The same rule read backwards: the roadmap is the arrival now, so it goes first
355
+ # and the store's removal second (RK118). A line in both files is a state a reader
356
+ # can see and a second `resume` can finish; a line in neither is one nobody can.
357
+ wrote = save_all(self.roadmap, self.store)
358
+ if self.root is not None:
359
+ claiming.follow(
360
+ self.root, self.task_id, self.marker, self.roadmap.entries
361
+ )
362
+ return wrote
363
+
364
+ def standing(self, config: Config) -> Entry | None:
365
+ """The line this call placed, or the one already there on a reconciling call (RK1086).
366
+
367
+ Asked rather than faked: the shape says a reconciliation places nothing, so the entry
368
+ being described has to be looked up where it already was.
369
+ """
370
+ return self.placed or config.document("roadmap").by_id().get(self.task_id)
371
+
372
+ def event(self, config: Config) -> dict[str, object]:
373
+ """What this return did to the block it landed in (RK38), off the roadmap it wrote."""
374
+ from roadkeep.rendering import _event # noqa: PLC0415 - RK260
375
+
376
+ standing = self.standing(config)
377
+ block = standing.task.block if standing else ""
378
+ return _event(self.task_id, block, self.roadmap, config)
379
+
380
+ def requeue(self, config: Config) -> str | None:
381
+ """The `priority add` a resumed line may want, where this project has a queue (RK327).
382
+
383
+ Offered and never done. `defer` took the entry out because a paused line is one `pick`
384
+ can never offer; what it could not keep is **where in the order it sat**, the store
385
+ holding a line and not a rank โ€” so a resume that re-queued would be choosing a position
386
+ nobody stated. Silent where no heading declares a section, which is most projects: a
387
+ follow-up naming a list that does not exist is a command that cannot run.
388
+
389
+ On the record since RK1170, with both registers that print it: this is the half of the
390
+ pause the verb does not undo, which makes it part of what the transaction answers.
391
+ """
392
+ try:
393
+ queue = queueing.declared(config)
394
+ except (KeyError, OSError): # a roadmap this command already reported on
395
+ return None
396
+ if queue.declared_in != "roadmap" or self.task_id in queue.tokens:
397
+ return None
398
+ return (
399
+ f"`{invocation()} priority add {self.task_id}` if it goes back in the order โ€” the "
400
+ f"pause took it out, and where it sat is not something the store kept"
401
+ )
402
+
403
+ def stated(self, config: Config, wrote: Sequence[Path]) -> str:
404
+ """Which of the two acts this was, and what came back with the line (RK1083).
405
+
406
+ Beside :meth:`payload` since RK1170. `ship` answers the same shape the same way โ€” `RK1
407
+ closed` against `RK1 โ†’` โ€” because a caller holding an id should not have to know which
408
+ of two states the files are in, and the *output* is where they find out.
409
+ """
410
+ from roadkeep.rendering import ( # noqa: PLC0415 - RK260
411
+ _event_rows,
412
+ _staging_rows,
413
+ )
414
+
415
+ roadmap = config.relative(config.path("roadmap"))
416
+ store = config.relative(config.path("deferred"))
417
+ standing = self.standing(config)
418
+ if self.reconciled:
419
+ rows = [
420
+ f"{self.task_id} reconciled {store}:{self.removed_from} removed, "
421
+ f"already {self.marker} in {roadmap}:{standing.lineno}",
422
+ " roadmap untouched: the open line is what the files should say",
423
+ ]
424
+ else:
425
+ block = standing.task.block if standing else ""
426
+ rows = [
427
+ f"{self.task_id} {self.marker} {roadmap}:{self.placed.lineno} "
428
+ f"under Block {block}",
429
+ f" removed {store}:{self.removed_from}",
430
+ ]
431
+ if self.was is not None:
432
+ # The last time the reason is visible: what comes back is a design, and the pause
433
+ # it went through is history the commit states rather than the line.
434
+ rows.append(f" was set aside: {self.was}")
435
+ if self.refreshed:
436
+ rows.append(f" derived {', '.join(self.refreshed)} (dep annotations re-derived)")
437
+ follow = self.requeue(config)
438
+ if follow is not None:
439
+ rows.append(f" requeue {follow}")
440
+ rows += _staging_rows(config.relative(one) for one in wrote)
441
+ rows += _event_rows(self.event(config), " ")
442
+ return "\n".join(rows)
443
+
444
+ def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
445
+ """The same answer as data, saying which of the two acts it was (RK1083)."""
446
+ from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
447
+
448
+ return {
449
+ "id": self.task_id,
450
+ "marker": self.marker,
451
+ # Null on a reconciling call, which places no line โ€” a `line` there would be an
452
+ # address for a write nobody made (RK1086).
453
+ "roadmap": None
454
+ if self.placed is None
455
+ else {
456
+ "file": config.relative(config.path("roadmap")),
457
+ "line": self.placed.lineno,
458
+ "rendered": self.placed.raw,
459
+ },
460
+ "deferred": {
461
+ "file": config.relative(config.path("deferred")),
462
+ "removed": self.removed_from,
463
+ },
464
+ "was": self.was,
465
+ # Which of the two acts this was (RK1083): a reconciliation removes the store's
466
+ # stale copy and places nothing, so `roadmap.line` is where the line already was
467
+ # rather than where one landed.
468
+ "reconciled": self.reconciled,
469
+ "refreshed": list(self.refreshed),
470
+ # The half of the pause this does not undo (RK327): the entry the pause removed is
471
+ # the author's to put back, because where in the order it belonged is not a fact
472
+ # the store kept.
473
+ "requeue": self.requeue(config),
474
+ **_wrote_json(config, wrote),
475
+ "event": self.event(config),
476
+ }
477
+
478
+
479
+ def defer(config: Config, task_id: str, *, reason: str) -> Pause:
480
+ """Move one open line to the store. Validates both edits before writing either.
481
+
482
+ Refused when the id is already terminal: an entry in the ledger says the work shipped or
483
+ was abandoned, and pausing it afterwards would make two files disagree about a decision
484
+ that is already recorded. That check is the ledger's own, so it holds whether the entry
485
+ is a โœ… or a ๐Ÿ—‘.
486
+ """
487
+ if not config.has("deferred"):
488
+ raise NoStore(task_id)
489
+ if _CLOSE in reason:
490
+ raise UnrecoverableReason(reason)
491
+
492
+ backlog = Backlog.load(config)
493
+ roadmap = backlog.roadmap
494
+ entry = roadmap.by_id().get(task_id)
495
+ if entry is None:
496
+ raise NotOpen(
497
+ task_id,
498
+ config.relative(config.path("roadmap")),
499
+ Whereabouts.of(config, task_id),
500
+ )
501
+ _refuse_recorded(config, task_id)
502
+ store = config.document("deferred")
503
+ held = store.by_id().get(task_id)
504
+ if held is not None:
505
+ raise SetAside(task_id, config.relative(config.path("deferred")), held.lineno)
506
+
507
+ marker = config.schema.deferred_marker
508
+ insertion = place(
509
+ store,
510
+ _as_paused(entry.task, marker, reason),
511
+ role="deferred",
512
+ config=config,
513
+ )
514
+ remaining = remove_entry(roadmap, entry)
515
+ # And the queue entry, in the same rewrite (RK327). Worth naming apart from the two
516
+ # terminal doors: the line is still work, so an entry naming it reads as live โ€” and yet
517
+ # `pick` can never offer a line the store holds, so the tier could only fire on nothing.
518
+ remaining, dequeued = queueing.without(remaining, config, task_id)
519
+ # Derived against the state this write *creates* โ€” the line is out of the roadmap โ€” for
520
+ # the same reason a departure does it (RK8): an annotation left un-derived by one door
521
+ # is one nothing else revisits.
522
+ # Both halves of the new state, not just the roadmap: the dependents' annotations are
523
+ # derived from where this id now *is* (RK92), and a refresh reading the store from disk
524
+ # would annotate against a file this transaction has not written yet.
525
+ derived = refresh(replace(backlog, roadmap=remaining, store=insertion.document))
526
+ return Pause(
527
+ task_id=task_id,
528
+ store=insertion,
529
+ roadmap=derived.document,
530
+ removed_from=entry.lineno,
531
+ refreshed=derived.changed,
532
+ marker=marker,
533
+ dequeued=dequeued,
534
+ carried=_carried(config, entry.task.ref),
535
+ dependents=tuple(
536
+ e.task.id for e in derived.document.entries if task_id in e.task.dep_ids
537
+ ),
538
+ root=config.root,
539
+ )
540
+
541
+
542
+ def resume(config: Config, task_id: str, *, marker: str | None = None) -> Resumption:
543
+ """Return one line from the store to its block. The same transaction, backwards.
544
+
545
+ `marker` is the open one the line comes back with, and it defaults to the project's
546
+ first exactly as `add`'s does: the store holds โธ and nothing else (RK96), so which open
547
+ marker the pause set aside is not a fact any file still has, and inventing one would be
548
+ this tool stating a maturity it cannot read.
549
+ """
550
+ if not config.has("deferred"):
551
+ raise NoStore(task_id)
552
+
553
+ where = config.relative(config.path("deferred"))
554
+ store = config.document("deferred")
555
+ held = store.by_id().get(task_id)
556
+ if held is None:
557
+ raise NotSetAside(task_id, where, elsewhere=Whereabouts.of(config, task_id).sentence)
558
+ _refuse_recorded(config, task_id)
559
+
560
+ backlog = Backlog.load(config)
561
+ open_line = backlog.roadmap.by_id().get(task_id)
562
+ if open_line is not None:
563
+ if marker is not None:
564
+ raise NoPlacement(
565
+ task_id, config.relative(config.path("roadmap")), open_line.lineno
566
+ )
567
+ # The roadmap already says what a resume would write, so the store entry is the
568
+ # stale half and this call removes it (RK1081). The mirror of RK1075 one file over:
569
+ # two governed files disagreeing about one id, resolved towards the one that
570
+ # already states the outcome โ€” here the open line, there the ledger entry.
571
+ #
572
+ # Refusing was the earlier answer and it left the state with no verb at all: `defer`
573
+ # refuses because the store holds it, `ship` and `retire` *succeed* and leave the id
574
+ # recorded and still paused, and the gate said nothing. What a second line would be
575
+ # โ€” two answers to when the work comes back โ€” is what this prevents rather than
576
+ # what it creates, because no line is placed.
577
+ remaining = remove_entry(store, held)
578
+ derived = refresh(replace(backlog, store=remaining))
579
+ return Resumption(
580
+ task_id=task_id,
581
+ roadmap=derived.document,
582
+ placed=None,
583
+ store=remaining,
584
+ removed_from=held.lineno,
585
+ refreshed=tuple(name for name in derived.changed if name != task_id),
586
+ # The line's own, because no marker was chosen here: what this call did is
587
+ # remove a copy, and reporting a marker it did not write would be the
588
+ # placement the sentence above refuses to claim.
589
+ marker=open_line.task.status,
590
+ reconciled=True,
591
+ )
592
+
593
+ status = marker or config.schema.markers[0]
594
+ insertion = place(
595
+ backlog.roadmap,
596
+ _as_open(held.task, status),
597
+ role="roadmap",
598
+ config=config,
599
+ )
600
+ remaining = remove_entry(store, held)
601
+ # The store this write leaves behind, for `defer`'s reason read backwards: a dependent
602
+ # still annotated โธ after the pause ended is the stale cache RK8 exists to prevent.
603
+ derived = refresh(replace(backlog, roadmap=insertion.document, store=remaining))
604
+ returned = next(e for e in derived.document.entries if e.task.id == task_id)
605
+ return Resumption(
606
+ task_id=task_id,
607
+ roadmap=derived.document,
608
+ placed=returned,
609
+ store=remaining,
610
+ removed_from=held.lineno,
611
+ refreshed=tuple(name for name in derived.changed if name != task_id),
612
+ marker=status,
613
+ was=_reason(held.task.why),
614
+ root=config.root,
615
+ )
616
+
617
+
618
+ def _carried(config: Config, ref: str | None) -> Carried | None:
619
+ """Where the design this pause kept actually is (RK229).
620
+
621
+ Answered on the way past rather than reported as an anchor for the CLI to place, because
622
+ the line naming a file is the one line in the answer whose job is to say where a reader
623
+ goes looking โ€” and RK96's whole argument for keeping the section is that they can.
624
+
625
+ Every outcome is a sentence and none is a refusal: nothing is being deleted here, so a
626
+ pointer that resolves to nothing or to two files is a pause that worked and a `lint`
627
+ finding the author already owes. Saying so beats a path composed out of the default.
628
+ """
629
+ if ref is None:
630
+ return None
631
+ anchor = f"ยง{ref}"
632
+ roles = declaring(config, ref)
633
+ if len(roles) == 1:
634
+ return Carried(anchor=anchor, role=roles[0])
635
+ if roles:
636
+ both = " and ".join(config.relative(config.path(role)) for role in roles)
637
+ return Carried(
638
+ anchor=anchor,
639
+ absence=f"declared by {both}, so the pointer names neither",
640
+ )
641
+ # The design's two, not every prose role (RK1361): this pointer is a *task line's*, so a
642
+ # decisions file the project happens to declare is not somewhere its section could be โ€”
643
+ # naming it would report an absence closed by a `declare` that changes nothing here.
644
+ declared = tuple(role for role in DESIGN_ROLES if config.has(role))
645
+ if not declared:
646
+ return Carried(
647
+ anchor=anchor,
648
+ absence=f"this project declares no {' or '.join(DESIGN_ROLES)} file",
649
+ )
650
+ named = " or ".join(config.relative(config.path(role)) for role in declared)
651
+ return Carried(anchor=anchor, absence=f"not in {named}, so nothing was carried")
652
+
653
+
654
+ def _as_paused(task: Task, marker: str, reason: str) -> Task:
655
+ """The same task as the store states it: โธ, the reason wrapped around the design."""
656
+ return replace(
657
+ task,
658
+ status=marker,
659
+ why=f"{_OPEN}{reason}{_CLOSE}{task.why}",
660
+ # At column zero, for `ship`'s reason (RK49): the indent named a roadmap line this
661
+ # one was nested under, and that line is not in the store.
662
+ indent="",
663
+ )
664
+
665
+
666
+ def _as_open(task: Task, marker: str) -> Task:
667
+ """The same task as the roadmap states it again, with this module's prefix removed."""
668
+ return replace(task, status=marker, why=_unwrapped(task.why))
669
+
670
+
671
+ #: The reason a pause recorded, and the author's sentence without it. Both moved to the kernel
672
+ #: by RK1115, where the rule that measures a paused `why` reads them too โ€” named here because
673
+ #: this module is where the wrapping is composed, and a reader of `defer` looks for them here.
674
+ _reason = pause_reason
675
+ _unwrapped = authored_why
676
+
677
+
678
+ def _refuse_recorded(config: Config, task_id: str) -> None:
679
+ """A pause is between open and terminal, so an id the ledger holds has neither door.
680
+
681
+ **Except the one pair this tool writes on purpose** (RK1215). `ship --part` records a
682
+ qualified half and leaves the line open at โณ, and this asked only *does the ledger hold
683
+ the id* โ€” so a line whose remainder waits on a decision, which is the case the store
684
+ exists for, was refused with :class:`~roadkeep.shipping.AlreadyRecorded`: the ledger's own
685
+ sentence, about a second entry neither of these two verbs would write.
686
+
687
+ :attr:`~roadkeep.kernel.schema.Task.in_halves` and never a second test of the qualifier,
688
+ which is the field :func:`~roadkeep.authoring._refuse_sibling_status` and
689
+ :func:`~roadkeep.linting._carried` already read for this pair โ€” so the door, the gate and
690
+ the pause cannot disagree about a state one of them creates (RK1080, RK1114).
691
+ """
692
+ if not config.has("changelog") or not config.path("changelog").is_file():
693
+ return
694
+ recorded = config.document("changelog").by_id().get(task_id)
695
+ if recorded is None or recorded.task.in_halves:
696
+ return
697
+ # Imported here rather than at module scope: the two write paths are peers, and this is
698
+ # the one fact one of them owns about the other โ€” the ledger's refusal, in its words.
699
+ from roadkeep.shipping import AlreadyRecorded
700
+
701
+ raise AlreadyRecorded(
702
+ task_id,
703
+ config.relative(config.path("changelog")),
704
+ recorded.lineno,
705
+ recorded.task.status,
706
+ )
707
+
708
+