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
@@ -0,0 +1,819 @@
1
+ """The verbs a task leaves by, and the two reads only the ledger can answer (RK494).
2
+
3
+ `ship`, `retire` and the `record` family write the terminal entry; `delivered` and
4
+ `reversals` read it back — what a block already shipped, and which of those deliveries was
5
+ later undone. Filed by their subject, an entry in the ledger, and not by whether they write
6
+ one: a proposal is checked against both, and the two reads come before it, not after.
7
+
8
+ **Every write here renders both registers off its own record** (RK1170), so each door is the
9
+ call, the save and a choice of reading — and this module no longer imports `rendering` at all.
10
+ The two reads still compose their answers here, which is the rest of that task.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import json
17
+ import sys
18
+ from collections.abc import Sequence
19
+
20
+ from roadkeep.backlog import Backlog, Stage
21
+ from roadkeep.config import Config
22
+ from roadkeep.kernel.document import declares, shading
23
+ from roadkeep.ranking import NEAREST, nearest
24
+ from roadkeep.reverting import Reversed, reversals
25
+ from roadkeep.shipping import (
26
+ Delivered,
27
+ Closure,
28
+ Partial,
29
+ amend as amend_record,
30
+ drop as drop_record,
31
+ move as move_record,
32
+ readdress as readdress_record,
33
+ record,
34
+ retire,
35
+ ship,
36
+ )
37
+ from roadkeep.serving import Prose
38
+ from roadkeep.verbs.declaring import (
39
+ _JSON_HELP,
40
+ _PIPE,
41
+ _reason_flag,
42
+ withheld,
43
+ )
44
+ from roadkeep.verbs.reading import _piped
45
+ from roadkeep.verbs.refusing import EXIT_GATE, EXIT_OK, EXIT_USAGE, REFUSALS, _refused
46
+
47
+
48
+
49
+ def _ship(config: Config, args: argparse.Namespace) -> int:
50
+ if args.remainder is not None and args.part is None:
51
+ # Refused rather than ignored (RK465, RK1233): a remainder on a whole shipment is a
52
+ # sentence about a line that is being removed, and honouring it silently would write
53
+ # the caller's words into a `why` the same transaction then deletes.
54
+ print(
55
+ "roadkeep: --remainder is what is left after --part, and this ship removes the "
56
+ "line: pass --part <what landed> too, or leave it off",
57
+ file=sys.stderr,
58
+ )
59
+ return EXIT_USAGE
60
+ try:
61
+ shipment = ship(
62
+ config,
63
+ args.id,
64
+ # Resolved by `dispatch` from what this verb's parser declares (RK1176), and no
65
+ # longer here: a call site that reads the pipe for one argument is a call site that
66
+ # can be written without it, which is how `--superseded-design` published a dash.
67
+ why=args.why,
68
+ part=args.part,
69
+ remainder=args.remainder,
70
+ lines=args.lines,
71
+ superseded=args.superseded_design,
72
+ recorded_in=args.recorded_in,
73
+ decides=args.decides,
74
+ decides_ref=args.decides_ref,
75
+ )
76
+ # The files this transaction wrote, answered by the write itself (RK309) — the half
77
+ # of the commit's contents no author declares, and never a second list rebuilt here.
78
+ wrote = shipment.save()
79
+ except REFUSALS as error:
80
+ return _refused(error)
81
+
82
+ if isinstance(shipment, Partial):
83
+ # Nothing was removed and nothing was dropped, so the departure's report would be
84
+ # three lines of None (RK121): what happened is an entry and a marker.
85
+ return _partly(config, shipment, args)
86
+ if isinstance(shipment, Closure):
87
+ # The ledger already holds the entry, so there is none to report (RK62): what this
88
+ # call did is remove the line that was left behind, and the evidence is where the
89
+ # entry already was.
90
+ return _closed(config, shipment, args, wrote)
91
+
92
+ if args.json:
93
+ print(json.dumps(shipment.payload(config, wrote), indent=2))
94
+ else:
95
+ print(shipment.stated(config, wrote))
96
+ return EXIT_OK
97
+
98
+
99
+ def _partly(config: Config, partial: Partial, args: argparse.Namespace) -> int:
100
+ """Half of a task recorded, with its roadmap line still open (RK121)."""
101
+ if args.json:
102
+ print(json.dumps(partial.payload(config), indent=2))
103
+ else:
104
+ print(partial.stated(config))
105
+ return EXIT_OK
106
+
107
+
108
+ def _closed(
109
+ config: Config, closure: Closure, args: argparse.Namespace, wrote: Sequence[str] = ()
110
+ ) -> int:
111
+ """A roadmap line closed against an entry the ledger already had (RK62)."""
112
+ if args.json:
113
+ print(json.dumps(closure.payload(config, wrote), indent=2))
114
+ else:
115
+ print(closure.stated(config, wrote))
116
+ return EXIT_OK
117
+
118
+
119
+ def _record(config: Config, args: argparse.Namespace) -> int:
120
+ try:
121
+ entry = record(
122
+ config,
123
+ block=args.block,
124
+ symptom=args.symptom,
125
+ why=_piped(args.why),
126
+ task_id=args.task_id,
127
+ supersedes=args.supersedes,
128
+ lines=args.lines,
129
+ )
130
+ wrote = entry.save()
131
+ except REFUSALS as error:
132
+ return _refused(error)
133
+
134
+ if args.json:
135
+ print(json.dumps(entry.payload(config, wrote), indent=2))
136
+ else:
137
+ print(entry.stated(config, wrote))
138
+ return EXIT_OK
139
+
140
+
141
+ def _record_amend(config: Config, args: argparse.Namespace) -> int:
142
+ if args.why is None and args.part is None:
143
+ print("roadkeep: nothing to amend: pass --why or --part", file=sys.stderr)
144
+ return EXIT_USAGE
145
+ try:
146
+ # One read joined to the listing, not a second parse: `reversals` walks the same
147
+ # entries for the same clause, so asking it here is what keeps the two answers one
148
+ # fact (RK1042). Asked **before** the write and not after (RK1052): the mark lives
149
+ # inside the `why` this command is about to replace, so the post-write state cannot
150
+ # answer whether the entry being corrected had been undone. The parse is the one
151
+ # `amend` is about to make of the same bytes, so this costs a cache hit.
152
+ undone_by = {one.undone: one.by for one in reversals(config)}.get(args.id)
153
+ corrected = amend_record(
154
+ config, args.id, why=_piped(args.why), part=args.part, lines=args.lines
155
+ )
156
+ wrote = corrected.save()
157
+ except REFUSALS as error:
158
+ return _refused(error)
159
+
160
+ if args.json:
161
+ print(json.dumps(corrected.payload(config, wrote, undone_by), indent=2))
162
+ else:
163
+ print(corrected.stated(config, wrote, undone_by))
164
+ return EXIT_OK
165
+
166
+
167
+ def _record_move(config: Config, args: argparse.Namespace) -> int:
168
+ try:
169
+ refiled = move_record(config, args.id, to_block=args.to_block)
170
+ # Nothing is written where the entry already sits under that heading, so nothing is
171
+ # staged either: an empty list is the honest answer and `_print_staging` says nothing.
172
+ wrote = refiled.save() if refiled.moved else ()
173
+ except REFUSALS as error:
174
+ return _refused(error)
175
+
176
+ if args.json:
177
+ print(json.dumps(refiled.payload(config, wrote), indent=2))
178
+ else:
179
+ print(refiled.stated(config, wrote))
180
+ return EXIT_OK
181
+
182
+
183
+ def _record_renumber(config: Config, args: argparse.Namespace) -> int:
184
+ try:
185
+ moved = readdress_record(config, args.id, lineno=args.line, to=args.to)
186
+ wrote = moved.save()
187
+ except REFUSALS as error:
188
+ return _refused(error)
189
+
190
+ if args.json:
191
+ print(json.dumps(moved.payload(config, wrote), indent=2))
192
+ else:
193
+ print(moved.stated(config, wrote))
194
+ return EXIT_OK
195
+
196
+
197
+ def _record_drop(config: Config, args: argparse.Namespace) -> int:
198
+ try:
199
+ dropped = drop_record(config, args.id, lineno=args.line)
200
+ wrote = dropped.save()
201
+ except REFUSALS as error:
202
+ return _refused(error)
203
+
204
+ if args.json:
205
+ print(json.dumps(dropped.payload(config, wrote), indent=2))
206
+ else:
207
+ print(dropped.stated(config, wrote))
208
+ return EXIT_OK
209
+
210
+
211
+ def _delivered(config: Config, args: argparse.Namespace) -> int:
212
+ """Every claim this block has already made good on (RK385).
213
+
214
+ **Symptoms and not entries.** A shipped line states two things — the problem it claimed
215
+ and the outcome it delivered — and a duplicate collides with the first. Printing both
216
+ doubles a read the author makes before every proposal, and the second half is the one
217
+ that never matches: an outcome is written in the vocabulary of the fix.
218
+
219
+ Unbounded, unlike `brief`'s carry of the non-goals (RK68). The bound there is what keeps
220
+ a *brief* an answer rather than the file; here the list **is** the answer, and a
221
+ truncated one is the failure mode this exists for — the entry that got elided is exactly
222
+ the one nobody read.
223
+
224
+ `--near` is the one bound, and it is not a truncation of this listing (RK442): it is the
225
+ same read asked a **narrower question**, so what bounds it is the sentence the caller
226
+ passed rather than a number this verb chose. That is the whole difference — an elision
227
+ picks entries to drop and this picks the entries that answer — and it is why the header
228
+ says how many of how many, why the plain listing is named beside it, and why the order
229
+ is published with no score under it (RK441).
230
+
231
+ Retired lines are in it. A claim that was abandoned is still a claim somebody made and
232
+ argued about, and a proposal restating one wants the argument more than the outcome —
233
+ the marker says which, so nothing is hidden and nothing is conflated.
234
+
235
+ **The label is resolved before the ledger is filtered (RK433).** This answer is consumed
236
+ as *evidence* — it is the read that decides whether an `add` is a duplicate — so the one
237
+ thing it may not do is come back empty for a question it never asked. Filtering the
238
+ entries by a literal made `Block Z has delivered nothing yet` the answer to four
239
+ different states: a block still being worked, whose lines are open and none of them
240
+ shipped; one whose work is all set aside; a heading opened before its lines; and a letter
241
+ the project has never used. Only the fourth is a mistake, and it is the one that files
242
+ the duplicate this verb exists to prevent. So :meth:`~roadkeep.backlog.Backlog.standing`
243
+ runs first and its sentence rides with every answer, empty or not: the count is a fact
244
+ about the ledger, the state is the fact about the label, and they say the same thing in
245
+ one of the four states only.
246
+
247
+ That sentence goes to **stdout** and on every state, which is where this parts company
248
+ with `_print_standing` (RK429) and for two reasons that are this verb's own. Stdout,
249
+ because there is no raw-file pipe to keep clean here — the header and the rows are
250
+ already derived, reformatted text rather than the file's own lines. Unconditionally,
251
+ because `Standing.settled` answers *which states an empty answer needs explaining by*,
252
+ and nothing filtered this one: the state of the label is the whole reason the count is
253
+ what it is, and three entries under a finished block is a different read from three under
254
+ a live one. `standing.recorded` and the length of the listing are the same number by
255
+ construction — both are `Document.block(label)` — so the figure printed twice is one
256
+ fact stated twice on purpose.
257
+
258
+ `unknown` exits **2**, never 0 or 1. Two, because `pick --block <x>`, `brief --block <x>`
259
+ and `list --block <x>` already answer a label nothing declares that way, and one meaning
260
+ per code is what a loop can branch on. Not one: in this tool 1 is a verdict about the
261
+ repository's own contents, and `_may_offer` reads a read-only 1 as exactly that (RK86) —
262
+ it would drop the capture offer a mistyped argv should keep. `--json` gets the refusal
263
+ and no payload, which is the line RK409 drew: a finished block is an answer and deserves
264
+ a shape, a name nothing declares is a refusal on every surface.
265
+
266
+ The header and the state row take `Standing.named` rather than an f-string (RK75):
267
+ `heading_word` is per project, and a report saying `Block G` to a project whose headings
268
+ all say `Track` names nothing its author wrote. That is fixed for this verb and not for
269
+ the file — the other reports here still spell it from a literal.
270
+ """
271
+ try:
272
+ backlog = Backlog.load(config)
273
+ except (KeyError, OSError) as error:
274
+ return _refused(error)
275
+
276
+ ledger = backlog.ledger
277
+ if ledger is None:
278
+ print(
279
+ "roadkeep: this project declares no changelog, so nothing records what was "
280
+ "delivered — `non-goal list` is the other read before an `add`",
281
+ file=sys.stderr,
282
+ )
283
+ return EXIT_USAGE
284
+ label = args.block.strip()
285
+ standing = backlog.standing(label)
286
+ if standing.stage is Stage.UNKNOWN:
287
+ declared = sorted(backlog.declared_blocks())
288
+ # Printed here rather than raised through `_refused`: this refusal is composed and
289
+ # never raised, and `provenance.witness` on an exception carrying no traceback
290
+ # records `()` — which is not `None`, so `_answered` would take it as evidence and
291
+ # suppress the inventory RK267 reserves for exactly this case. The sibling refusal
292
+ # above, for a project that declares no changelog, already exits this way.
293
+ print(
294
+ f"roadkeep: {standing.sentence}{declares(declared)}: the ledger was not read, "
295
+ f"so this is not a block that delivered nothing{shading(label, declared)}",
296
+ file=sys.stderr,
297
+ )
298
+ return EXIT_USAGE
299
+ # `Document.block` and not a filter written here: it is the same call `Standing.of`
300
+ # makes, which is what makes this count and `standing.recorded` one number rather than
301
+ # two that agree.
302
+ entries = ledger.block(label)
303
+ # RK442: the whole block is what this verb answered with, and the question is whether one
304
+ # sentence collides with it. Ranked here rather than inside the reader, because the
305
+ # ordering is a property of the *query* and the block is the fact — and the unranked
306
+ # tuple stays exactly what it was, so `--near` narrows one answer and does not make a
307
+ # second one. `recorded` below is still the block's count, never the shown count.
308
+ recorded = len(entries)
309
+ if args.near is not None and not args.near.strip():
310
+ # An empty `--near` used to fall through to the unbounded listing, which answers a
311
+ # *different question* than the one asked and looks like the narrow answer until the
312
+ # caller counts the rows: 103 lines where five were asked for. Every prose argument
313
+ # in this tool refuses the empty slot, and a read is where it costs the most —
314
+ # nothing exits non-zero, so a wrong answer is the only signal there is.
315
+ print(
316
+ "roadkeep: --near is the symptom you are about to propose, and it arrived "
317
+ "empty: pass the sentence, or drop the flag for the whole block",
318
+ file=sys.stderr,
319
+ )
320
+ return EXIT_USAGE
321
+ if args.near:
322
+ entries = tuple(
323
+ entries[index]
324
+ for index in nearest(args.near, [e.task.symptom for e in entries], NEAREST)
325
+ )
326
+ where = config.relative(config.path("changelog"))
327
+ # One read joined to the listing, not a second parse: `reversals` walks the same entries
328
+ # for the same clause, so asking it here is what keeps the two answers one fact (RK1042).
329
+ answer = Delivered(
330
+ where=where,
331
+ standing=standing,
332
+ entries=entries,
333
+ recorded=recorded,
334
+ near=args.near or "",
335
+ reversed_by={one.undone: one.by for one in reversals(config)},
336
+ )
337
+ # Both registers off one result (RK1170). This is the read that decides whether an `add` is
338
+ # a duplicate, so the two had better say the same thing — and they were a printer and a
339
+ # payload builder in this handler, agreeing by hand over a header, a bound and a per-entry
340
+ # mark. The payload now carries what the listing shows by construction.
341
+ print(json.dumps(answer.payload(), indent=2) if args.json else answer)
342
+ return EXIT_OK
343
+
344
+
345
+ def _reversals(config: Config, args: argparse.Namespace) -> int:
346
+ """What the ledger already undid (RK416), and with `--id` whether one thing is among it.
347
+
348
+ `--id` exits 1 rather than 0 for a reason the plain listing does not need: the caller is
349
+ a script or an agent about to spend an id, and an exit code is what it can branch on
350
+ without reading either stream. Exit 1 is "this was tried and undone" and never "you may
351
+ not" — the read states a fact, and whether the revert was about a broken implementation
352
+ or a wrong idea is the one thing nobody here can tell.
353
+ """
354
+ try:
355
+ found = reversals(config)
356
+ except (KeyError, OSError) as error:
357
+ return _refused(error)
358
+
359
+ if args.task_id:
360
+ found = tuple(one for one in found if one.undone == args.task_id)
361
+ answer = Reversed(
362
+ found=found,
363
+ where=config.relative(config.path("changelog")),
364
+ root=config.root.as_posix(),
365
+ asked=args.task_id or "",
366
+ )
367
+
368
+ if args.json:
369
+ print(json.dumps(answer.payload(), indent=2))
370
+ else:
371
+ print(answer.stated())
372
+ return EXIT_GATE if answer.gated else EXIT_OK
373
+
374
+
375
+ def _supersede(config: Config, args: argparse.Namespace) -> int:
376
+ """The one door a decision leaves by (RK1274), which is not a departure from a backlog.
377
+
378
+ Nothing is deleted and nothing is composed: both entries stay, the marker says which is
379
+ live, and the clause naming the replacement is derived — so this handler passes two ids
380
+ and reads the answer off the record like every other write here.
381
+ """
382
+ from roadkeep.shipping import supersede # noqa: PLC0415 - RK260
383
+
384
+ try:
385
+ found = supersede(config, args.id, by=args.by)
386
+ wrote = found.save()
387
+ except REFUSALS as error:
388
+ return _refused(error)
389
+
390
+ if args.json:
391
+ print(json.dumps(found.payload(config, wrote), indent=2))
392
+ else:
393
+ print(found.stated(config, wrote))
394
+ return EXIT_OK
395
+
396
+
397
+ def _retire(config: Config, args: argparse.Namespace) -> int:
398
+ """Record a line leaving without shipping, and say where its replacement is (RK32, RK244).
399
+
400
+ Both registers come off the record (RK1170) — the *retirement* pair, one shape carrying two
401
+ doors' answers. The replacement's id moved onto it with them: reading it back off argv was
402
+ the verb answering about the call it received rather than the transaction it made.
403
+ """
404
+ try:
405
+ departure = retire(
406
+ config,
407
+ args.id,
408
+ reason=_piped(args.reason),
409
+ superseded_by=args.superseded_by,
410
+ )
411
+ wrote = departure.save()
412
+ except REFUSALS as error:
413
+ return _refused(error)
414
+
415
+ if args.json:
416
+ print(json.dumps(departure.retirement(config, wrote), indent=2))
417
+ else:
418
+ print(departure.retired(config, wrote))
419
+ return EXIT_OK
420
+
421
+
422
+ def declare_departures(subcommands: argparse._SubParsersAction) -> None:
423
+ """This module's verbs, declared where their handlers are (RK1171).
424
+
425
+ `build_parser` called forty-nine blocks like these in a row; what it calls now is an index
426
+ over the modules that own them. The move is what RK1169 and RK1170 bought: the flags a verb
427
+ declares, the reasons it withholds and the record it answers with are one file's, so a
428
+ change to any of them is one file's too.
429
+
430
+ The order inside is `build_parser`'s own, which is where these blocks sat.
431
+ """
432
+ ship_parser = subcommands.add_parser(
433
+ "ship",
434
+ help="move a task to the ledger, drop its rationale, clear the roadmap line",
435
+ description=(
436
+ "Ship one task in three edits across three files. Everything is validated "
437
+ "before anything is written, because whichever of the three is done by hand "
438
+ "last is the one that gets forgotten. `--why` is the outcome and is required: "
439
+ "the roadmap's sentence states the problem, and inheriting it files a defect "
440
+ "report under a heading that means done."
441
+ ),
442
+ )
443
+ ship_parser.add_argument("id", help="the task to ship, e.g. RK5")
444
+ ship_parser.add_argument(
445
+ "--why",
446
+ help=(
447
+ "the outcome this shipped — required where an entry is written, because the "
448
+ "roadmap's sentence states a problem and is not inherited; refused where the "
449
+ "ledger already holds the id and this call only closes the line. Completing a "
450
+ "wrapped partial with --lines above one, it is the whole span: the first line "
451
+ "is the outcome and the rest is written back as the tail" + _PIPE
452
+ ),
453
+ )
454
+ ship_parser.add_argument(
455
+ "--part",
456
+ help=(
457
+ "record only the half that landed and leave the line open, e.g. 'local "
458
+ "half'; a later ship with no --part completes it"
459
+ ),
460
+ )
461
+ # The open half, as data (RK1233). Beside `--part` and narrowed to it, because a
462
+ # remainder on a whole shipment is a sentence about a line that is being removed.
463
+ ship_parser.add_argument(
464
+ "--remainder",
465
+ help="what is still left, with --part: it becomes the open line's why",
466
+ )
467
+ ship_parser.add_argument(
468
+ "--lines",
469
+ type=int,
470
+ help=(
471
+ "how many lines the completion replaces; required where the partial entry it "
472
+ "completes wraps, and refused where this call replaces no entry — above one it "
473
+ "is also what lets --why carry that span back instead of collapsing it"
474
+ ),
475
+ )
476
+ ship_parser.add_argument(
477
+ "--superseded-design",
478
+ help=(
479
+ "what the design this deletes turned out to be wrong about, e.g. 'the resize "
480
+ "endpoint it called a new subsystem had shipped two blocks earlier'; appended "
481
+ "to the ledger's sentence with the section's address, since the entry is the "
482
+ "one place both survive the deletion" + _PIPE
483
+ ),
484
+ )
485
+ # RK1267. No pipe: a path carries nothing a shell reads first, and the clause around it
486
+ # is derived, so there is no prose here for stdin to be the door to.
487
+ ship_parser.add_argument(
488
+ "--recorded-in",
489
+ dest="recorded_in",
490
+ help="the file the deleted design's durable half moved to; must resolve",
491
+ )
492
+ # RK1269. It reads the pipe for `--why`'s reason: a constraint names types, files and
493
+ # prior ids, so it carries the backtick and the apostrophe a shell reads first.
494
+ ship_parser.add_argument(
495
+ "--decides",
496
+ help=(
497
+ "the constraint the deleted design leaves behind, filed as one line in the "
498
+ "decisions role" + _PIPE
499
+ ),
500
+ )
501
+ # RK1363. The address of the body that record keeps, on a project whose anchors are its
502
+ # own numbering. No pipe: it is an address and not prose, so nothing a shell eats is in it.
503
+ ship_parser.add_argument(
504
+ "--decides-ref",
505
+ dest="decides_ref",
506
+ metavar="ANCHOR",
507
+ help=(
508
+ "where the decision's body goes, as an outline anchor — required beside "
509
+ "--decides where `ref_scheme = \"outline\"` and refused where the anchor is the "
510
+ "id; `anchors --role decisions --next` names a free one"
511
+ ),
512
+ )
513
+ ship_parser.add_argument("--json", action="store_true", help="every edit, as data")
514
+ ship_parser.set_defaults(
515
+ handler=_ship,
516
+ reads_stdin=(
517
+ Prose(dest="why", omitted=False),
518
+ # The argument RK1176 was filed about: the pipe is documented on every prose
519
+ # argument, and this one reached the ledger as a literal `-` because the handler
520
+ # resolved `--why` by hand and this was added after that line was written.
521
+ Prose(dest="superseded_design", omitted=False),
522
+ # RK1269, and declared here rather than remembered: a prose argument that is not
523
+ # on this tuple is one the pipe silently does not reach.
524
+ Prose(dest="decides", omitted=False),
525
+ ),
526
+ )
527
+
528
+ record_parser = subcommands.add_parser(
529
+ "record",
530
+ help="write, correct, re-file, renumber or drop a ledger entry directly",
531
+ description=(
532
+ "The ledger's own doors, the ones the roadmap's are not: every other command "
533
+ "starts from a task line, and these start from the entry."
534
+ ),
535
+ )
536
+ entries = record_parser.add_subparsers(dest="action", required=True)
537
+
538
+ record_add = entries.add_parser(
539
+ "add",
540
+ help="write a ledger entry directly, for shipped work no open line can carry",
541
+ description=(
542
+ "The fourth door, and the only one that starts nowhere: `ship` and both "
543
+ "retirements begin from an open roadmap line, so this is how the ledger records "
544
+ "work that has none. Never planned is one case and not the definition — a task "
545
+ "that was planned and shipped inside another's sentence needs its own entry too, "
546
+ "and so does a revert (--supersedes). What it does is write the entry and touch "
547
+ "nothing else; without it the only route in was a fictitious line shipped in the "
548
+ "same breath, which teaches that the format can be gamed."
549
+ ),
550
+ )
551
+ record_add.add_argument("--block", required=True, help="the block label, e.g. B")
552
+ record_add.add_argument(
553
+ "--symptom",
554
+ required=True,
555
+ help="what did not work — a phrase, never the name of the patch that closed it",
556
+ )
557
+ record_add.add_argument(
558
+ "--why",
559
+ required=True,
560
+ help="one sentence, ending in a stop: the outcome" + _PIPE,
561
+ )
562
+ record_add.add_argument(
563
+ "--id",
564
+ dest="task_id",
565
+ help=(
566
+ "the id (default: derived, one past the highest anywhere); refused where a "
567
+ "line already holds it, allowed where only a sentence names it — which is how "
568
+ "an id cited but never recorded gets the entry it is missing"
569
+ ),
570
+ )
571
+ record_add.add_argument(
572
+ "--supersedes",
573
+ metavar="ID",
574
+ help=(
575
+ "the entry this one reverts: its sentence gains `(superseded by <id>)` in the "
576
+ "same write, so the ledger's two records of one decision know about each other"
577
+ ),
578
+ )
579
+ record_add.add_argument(
580
+ "--lines",
581
+ type=int,
582
+ # Declared only so a script that spells it gets `NoSpan` rather than argparse's
583
+ # `declares no --lines` (RK1056): the count authorised a span rewrite the pointer
584
+ # stopped making, and the refusal is the one answer that says which of the two
585
+ # changed. Withdrawn from the served tool, which has no script to keep working.
586
+ help=(
587
+ "refused, and kept only to say so: the --supersedes pointer is appended to the "
588
+ "sentence on the entry's first line and replaces no span, so a wrapped bullet "
589
+ "needs no count and keeps the lines under it"
590
+ ),
591
+ )
592
+ record_add.add_argument(
593
+ "--json", action="store_true", help="the entry, with the file and line it landed on"
594
+ )
595
+ withheld(
596
+ record_add,
597
+ task_id="the ledger's id is the roadmap line's, and `ship` is what carries it across; typing one here is inventing an id the backlog never issued",
598
+ lines="the entry's shape is derived from what it records, and a count set by hand is the arrangement the schema replaced",
599
+ )
600
+ record_add.set_defaults(
601
+ handler=_record, reads_stdin=(Prose(dest="why", omitted=False),)
602
+ )
603
+
604
+ record_amend = entries.add_parser(
605
+ "amend",
606
+ help="correct a ledger entry's sentence where it stands",
607
+ description=(
608
+ "Rewrite one entry's `why`, or a partial's qualifier, without moving the line. "
609
+ "`drop` and `add` are not equivalent to this: they would remove the entry and "
610
+ "append a new one under its block, so a ledger read in the order work landed "
611
+ "stops being one and a reviewer sees a deletion where a word changed. The "
612
+ "`symptom` is the claim and is not a field, the id is `renumber`'s, and the "
613
+ "block is not offered because filing an entry elsewhere is a move."
614
+ ),
615
+ )
616
+ record_amend.add_argument("id", help="the recorded id, e.g. RK41")
617
+ record_amend.add_argument(
618
+ "--why",
619
+ help=(
620
+ "the corrected sentence, one stop — or, with --lines above one, the whole span: "
621
+ "the first line is the sentence and the rest is written back as the tail" + _PIPE
622
+ ),
623
+ )
624
+ record_amend.add_argument(
625
+ "--part",
626
+ help="correct a partial's qualifier; refused where the entry carries none",
627
+ )
628
+ record_amend.add_argument(
629
+ "--lines",
630
+ type=int,
631
+ help=(
632
+ "how many lines this correction replaces; required where the entry wraps, "
633
+ "because there the sentence runs past the line the parse holds — and above "
634
+ "one it is also what lets --why carry that span back"
635
+ ),
636
+ )
637
+ record_amend.add_argument("--json", action="store_true", help=_JSON_HELP)
638
+ record_amend.set_defaults(
639
+ handler=_record_amend, reads_stdin=(Prose(dest="why", omitted=False),)
640
+ )
641
+
642
+ record_move = entries.add_parser(
643
+ "move",
644
+ help="re-file a ledger entry under another block heading",
645
+ description=(
646
+ "The move `amend` deliberately does not pretend is a correction. `ship` files an "
647
+ "entry under the block its roadmap line sat in, so a line filed under the wrong "
648
+ "one ships to the wrong one — and no other verb reaches it: `record add` refuses "
649
+ "an id that exists, `drop` wants the id stated twice, `renumber` changes the "
650
+ "address and not the heading. This removes the line and re-places it under the "
651
+ "named heading, reporting both positions, and refuses a heading the ledger does "
652
+ "not declare — `block add` is what writes one."
653
+ ),
654
+ )
655
+ record_move.add_argument("id", help="the recorded id, e.g. RK41")
656
+ record_move.add_argument(
657
+ "--to-block",
658
+ required=True,
659
+ dest="to_block",
660
+ help="the block label to file it under, e.g. B; refused unless a heading declares it",
661
+ )
662
+ record_move.add_argument(
663
+ "--json", action="store_true", help="both positions, and the blocks they are under"
664
+ )
665
+ record_move.set_defaults(handler=_record_move)
666
+
667
+ record_drop = entries.add_parser(
668
+ "drop",
669
+ help="remove the later of two ledger entries for one id",
670
+ description=(
671
+ "Delete a duplicate entry, and only a duplicate: refused unless the ledger states "
672
+ "the id twice, because removing the only record of a decision is deleting history "
673
+ "rather than de-duplicating it. The first entry stays, since that is where a "
674
+ "reader already found the decision, and no other file is opened."
675
+ ),
676
+ )
677
+ record_drop.add_argument("id", help="the id the ledger carries twice, e.g. RK41")
678
+ record_drop.add_argument(
679
+ "--line",
680
+ type=int,
681
+ help=(
682
+ "which of the two entries goes; required when they do not say the same thing, "
683
+ "because then they are two deliveries and not one recorded twice"
684
+ ),
685
+ )
686
+ record_drop.add_argument(
687
+ "--json", action="store_true", help="which line went, and which one answers now"
688
+ )
689
+ record_drop.set_defaults(handler=_record_drop)
690
+
691
+ record_renumber = entries.add_parser(
692
+ "renumber",
693
+ help="give one of two entries for an id an address of its own",
694
+ description=(
695
+ "The counterpart of `renumber` for the file that verb never opens. Renumbering "
696
+ "a record is normally how a `git log -S` starts returning two unrelated "
697
+ "designs — and that argument inverts on a collision, where the shared id is "
698
+ "already what makes the history unreadable. Refused on anything but an id the "
699
+ "ledger states twice, and which of the entries moves is yours to name: the one "
700
+ "that earned the id from a roadmap line is the one to leave alone."
701
+ ),
702
+ )
703
+ record_renumber.add_argument("id", help="the id the ledger carries twice, e.g. RK41")
704
+ record_renumber.add_argument(
705
+ "--line", type=int, help="the entry that moves; named, never defaulted"
706
+ )
707
+ record_renumber.add_argument(
708
+ "--to", help="the new id (default: derived, one past the highest in its family)"
709
+ )
710
+ record_renumber.add_argument("--json", action="store_true", help=_JSON_HELP)
711
+ record_renumber.set_defaults(handler=_record_renumber)
712
+
713
+ delivered_parser = subcommands.add_parser(
714
+ "delivered",
715
+ help="what a block has already shipped, as claims — the read before an `add`",
716
+ description=(
717
+ "The other list to consult before proposing work, beside `non-goal list` "
718
+ "(RK69). A duplicate is not refused and could not be: RK378 restated RK340 the "
719
+ "day after it shipped and RK382 restated RK178 a day later, and a lexical match "
720
+ "cannot be gated: measured over this ledger it ranks the true pair in the top "
721
+ "three and still scores below what an entry with no duplicate scores against "
722
+ "its own nearest neighbour, so no threshold separates them. Two people "
723
+ "describing one problem use disjoint words, and recognising that takes meaning "
724
+ "this tool has none of (L4). So it states what "
725
+ "the block delivered and you read it. Symptoms alone: the claim is what a "
726
+ "duplicate collides with, and the outcome sentence doubles the length. A letter "
727
+ "no heading declares is refused rather than answered as empty — that answer is "
728
+ "read as evidence — and where the label is declared the reply says which of "
729
+ "live, paused, finished or empty the block is. `--near` is the same read "
730
+ f"bounded by the question (RK442): the {NEAREST} entries nearest the sentence "
731
+ "you are about to propose, in order, instead of the whole block. The order is "
732
+ "the answer and there is no score — RK441 measured that the absolute one "
733
+ "separates nothing, so publishing it would invite a threshold that cannot exist."
734
+ ),
735
+ )
736
+ delivered_parser.add_argument("block", help="the block label, e.g. B")
737
+ delivered_parser.add_argument(
738
+ "--near",
739
+ metavar="SYMPTOM",
740
+ help=(
741
+ f"the symptom about to be proposed: print the {NEAREST} entries nearest it "
742
+ "rather than the block, ranked by word overlap and never refused or warned about"
743
+ ),
744
+ )
745
+ delivered_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
746
+ delivered_parser.set_defaults(handler=_delivered, reads_only=True)
747
+
748
+ reversals_parser = subcommands.add_parser(
749
+ "reversals",
750
+ help="the decisions this ledger already made and undid, with the argument",
751
+ description=(
752
+ "A revert is filed as a delivery, so a duplicate check answers `yes, shipped` "
753
+ "about the entry that says the work did not hold. This reads the forward "
754
+ "pointer back: every id the ledger marks superseded, the entry that superseded "
755
+ "it, and that entry's sentence — which is the argument a fresh proposal is "
756
+ "against. Read it before an `add`, not after. It refuses nothing: re-proposing "
757
+ "reverted work is sometimes right, and which is a judgement the tool never makes."
758
+ ),
759
+ )
760
+ reversals_parser.add_argument(
761
+ "--id",
762
+ dest="task_id",
763
+ help="ask about one id: exits 1 where that id's decision was reversed",
764
+ )
765
+ reversals_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
766
+ reversals_parser.set_defaults(handler=_reversals, reads_only=True)
767
+
768
+
769
+ supersede_parser = subcommands.add_parser(
770
+ "supersede",
771
+ help="mark one decision replaced by another, in the file that holds both",
772
+ description=(
773
+ "The decisions role's one departure. A roadmap line leaves by three doors and a "
774
+ "decision leaves by being replaced, so nothing in that file is ever deleted: this "
775
+ "appends the forward pointer to the entry that is now stale and moves its marker, "
776
+ "in one write. Both ids have to be decisions this file already records — the "
777
+ "replacement is written by `ship --decides` before it can replace anything — and "
778
+ "there is no reason field, because why one decision replaced another is the "
779
+ "argument in the entry that replaced it, one line away."
780
+ ),
781
+ )
782
+ supersede_parser.add_argument("id", help="the decision being replaced, e.g. RK5")
783
+ supersede_parser.add_argument(
784
+ "--by",
785
+ required=True,
786
+ metavar="ID",
787
+ help="the decision that replaces it, already filed in the same file",
788
+ )
789
+ supersede_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
790
+ supersede_parser.set_defaults(handler=_supersede)
791
+
792
+ retire_parser = subcommands.add_parser(
793
+ "retire",
794
+ help="record a line leaving without shipping: replaced by another, or abandoned",
795
+ description=(
796
+ "The two departures that are not a ship: the work moved to another id "
797
+ "(--superseded-by), or it is not being done. Both write one ledger line under "
798
+ "the block it belonged to, with the forward pointer where there is one, and no "
799
+ "design — which is what a gap here otherwise reads as, a botched hand-edit."
800
+ ),
801
+ )
802
+ retire_parser.add_argument("id", help="the task leaving, e.g. RK33")
803
+ retire_parser.add_argument(
804
+ "--superseded-by",
805
+ dest="superseded_by",
806
+ metavar="ID",
807
+ help=(
808
+ "the id that takes the work over, which is a replacement and not an "
809
+ "abandonment; omitted, the line is recorded as abandoned"
810
+ ),
811
+ )
812
+ _reason_flag(
813
+ retire_parser, "one sentence, the author's own: the tool never writes it" + _PIPE
814
+ )
815
+ retire_parser.add_argument("--json", action="store_true", help="every edit, as data")
816
+ retire_parser.set_defaults(
817
+ handler=_retire, reads_stdin=(Prose(dest="reason", omitted=False),)
818
+ )
819
+