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,566 @@
1
+ """The verbs whose subject is one line of the roadmap (RK494).
2
+
3
+ `add`, `status`, `amend`, `restate`, `renumber` and `next-id`, plus the two doors that are
4
+ not terminal — `defer` parks a line in the store with its id, its deps and its section, and
5
+ `resume` is the return direction the ledger has none of.
6
+
7
+ Each is a thin call into :mod:`roadkeep.authoring`, :mod:`roadkeep.renumbering` or
8
+ :mod:`roadkeep.deferring`. What lives here is the argument reading, the refusal and the
9
+ answer — never a rule, which would then be enforced on one surface and not on the other.
10
+
11
+ **And no longer the answer either** (RK1170): every write renders both registers off its own
12
+ record, so each door is the call, the save and a choice of reading. `next-id` renders three, the
13
+ id being stdout a shell captures and the promise a sentence that must not reach it.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import argparse
19
+ import json
20
+ import sys
21
+
22
+ from roadkeep.authoring import add, amend, restate, set_status
23
+ from roadkeep.capturing import stamp
24
+ from roadkeep.config import Config
25
+ from roadkeep.deferring import defer, resume
26
+ from roadkeep.ids import derivation
27
+ from roadkeep.renumbering import renumber
28
+ from roadkeep.verbs.reading import _body_reader, _one_body, _piped
29
+ from roadkeep.serving import Prose
30
+ from roadkeep.verbs.declaring import (
31
+ _BODY_FILE,
32
+ _JSON_HELP,
33
+ _PIPE,
34
+ _marker_flag,
35
+ _reason_flag,
36
+ withheld,
37
+ )
38
+ from roadkeep.verbs.refusing import EXIT_OK, EXIT_USAGE, REFUSALS, _refused
39
+
40
+
41
+
42
+ def _next_id(config: Config, args: argparse.Namespace) -> int:
43
+ try:
44
+ derived = derivation(config, args.family)
45
+ except ValueError as error:
46
+ return _refused(error)
47
+ family = args.family or config.schema.prefix
48
+ # Three streams and not two (RK1170): the id is stdout because this command exists to be
49
+ # captured in a shell, and the promise is stderr because a second line in that capture is
50
+ # a broken id — so the branch is which reading, never whether to add a sentence.
51
+ if args.json:
52
+ print(json.dumps(derived.payload(config, family), indent=2))
53
+ return EXIT_OK
54
+ print(derived.stated())
55
+ for note in derived.notice():
56
+ print(note, file=sys.stderr)
57
+ return EXIT_OK
58
+
59
+
60
+ def _add(config: Config, args: argparse.Namespace) -> int:
61
+ # The pipe clash is `dispatch`'s, asked over what this verb's parser declares (RK1176) —
62
+ # this had the only copy of it, which is how `ship` sent two arguments to one stream with
63
+ # the refusal sitting one module away. What is left here is the other question: a body given
64
+ # twice, as a string and as a path, which no declaration can answer.
65
+ clash = _one_body("--section-body", args.section_body, args.section_body_file)
66
+ if clash is not None:
67
+ print(f"roadkeep: {clash}", file=sys.stderr)
68
+ return EXIT_USAGE
69
+ try:
70
+ # The reader is handed over unread (RK381), so the paragraph is fetched below every
71
+ # refusal the *line* raises — an id already spent, a `why` three words over, a block
72
+ # nothing declares — and a pipe does not rewind. Inside the try for the reason
73
+ # `section add` reads there: prose that is not UTF-8 raises UnicodeDecodeError, which
74
+ # is a ValueError, and is refused with the code every other bad input gets. Gated on
75
+ # the title, because an `add` with no rationale must never block on a pipe.
76
+ section = None
77
+ if args.section is not None:
78
+ section = (
79
+ args.section,
80
+ _body_reader(args.section_body, args.section_body_file),
81
+ )
82
+ insertion = add(
83
+ config,
84
+ block=args.block,
85
+ symptom=args.symptom,
86
+ why=_piped(args.why),
87
+ status=args.status,
88
+ deps=args.deps,
89
+ requires=args.requires,
90
+ ref=args.ref,
91
+ task_id=args.task_id,
92
+ family=args.family,
93
+ section=section,
94
+ )
95
+ except REFUSALS as error:
96
+ return _refused(error) # a SchemaError arrives here as the ValueError it is
97
+
98
+ # After the line is placed and the files are saved, and never a condition of either
99
+ # (RK1141): the capture is evidence in an ignored directory, so a stamp that cannot be
100
+ # written costs the link and not the task — `claiming.follow`'s rule for the same reason.
101
+ # The third copy of the argument RK1396 was about, resolved the same way: this one is the
102
+ # path the *capture offer* printed, so a project-relative address read from the process's
103
+ # directory left the line filed and the row it was meant to clear still open — the one
104
+ # failure this stamp is not allowed to have, being the half that costs nothing to get right.
105
+ stamped = (
106
+ stamp(config.locate(args.capture), insertion.entry.task.id) if args.capture else False
107
+ )
108
+ if args.json:
109
+ print(json.dumps(insertion.addition(config, args.capture, stamped), indent=2))
110
+ else:
111
+ print(insertion.added(config, args.capture, stamped))
112
+ return EXIT_OK
113
+
114
+
115
+ def _status(config: Config, args: argparse.Namespace) -> int:
116
+ """Write one task's marker, and say what that did to the claim on its line (RK7, RK158).
117
+
118
+ Both registers come off the record (RK1170), the no-op reading included: a marker that did
119
+ not move still followed its claim, so the branch belongs with the answer and not in a door.
120
+ """
121
+ try:
122
+ change = set_status(config, args.id, args.marker)
123
+ except REFUSALS as error:
124
+ return _refused(error)
125
+
126
+ if args.json:
127
+ print(json.dumps(change.payload(config), indent=2))
128
+ else:
129
+ print(change.stated(config))
130
+ return EXIT_OK
131
+
132
+
133
+ def _amend(config: Config, args: argparse.Namespace) -> int:
134
+ """Correct one open line's why, deps or pointer, keeping its symptom and its id (RK65).
135
+
136
+ Both registers come off the record (RK1170), exactly as `restate`'s do: this door chooses
137
+ which reading to print and composes neither.
138
+ """
139
+ # `--requires` counts (RK1311). The flag is in the parser, documented in the help two lines
140
+ # above this message, and works — and the guard that decides whether anything was asked for
141
+ # did not know it. So the only way to attach a requirement to a line that already exists
142
+ # was to pass a field that is not changing: measured in pportal over five lines, where one
143
+ # of them meant re-sending a `why` that then failed the line limit, because the annotation
144
+ # had made the line longer. Two round trips for a field the verb has.
145
+ if args.why is None and args.deps is None and args.ref is None and not args.requires:
146
+ # Named only where the project declares a vocabulary (L6): a flag offered here and
147
+ # refused by `requires.unknown` one call later is the detour RK16 keeps out of a
148
+ # remedy, and a project that declared none has no requirement to attach.
149
+ fields = "--why, --dep or --ref"
150
+ if config.schema.requirements:
151
+ fields = "--why, --dep, --requires or --ref"
152
+ print(f"roadkeep: nothing to amend: pass {fields}", file=sys.stderr)
153
+ return EXIT_USAGE
154
+ try:
155
+ amended = amend(
156
+ config,
157
+ args.id,
158
+ why=_piped(args.why),
159
+ deps=args.deps,
160
+ requires=args.requires,
161
+ ref=args.ref,
162
+ lines=args.lines,
163
+ )
164
+ except REFUSALS as error:
165
+ return _refused(error)
166
+
167
+ if args.json:
168
+ print(json.dumps(amended.payload(config), indent=2))
169
+ else:
170
+ print(amended.stated(config))
171
+ return EXIT_OK
172
+
173
+
174
+ def _restate(config: Config, args: argparse.Namespace) -> int:
175
+ """Correct one open line's symptom, keeping its id, its deps and its section (RK178).
176
+
177
+ Both registers come off the record (RK1170): a write verb's answer is what the transaction
178
+ produced, and this door only chooses which reading to print.
179
+ """
180
+ try:
181
+ restated = restate(
182
+ config, args.id, args.symptom, lines=args.lines, typo=args.typo
183
+ )
184
+ except REFUSALS as error:
185
+ return _refused(error)
186
+
187
+ if args.json:
188
+ print(json.dumps(restated.payload(config), indent=2))
189
+ else:
190
+ print(restated.stated(config))
191
+ return EXIT_OK
192
+
193
+
194
+ def _renumber(config: Config, args: argparse.Namespace) -> int:
195
+ """Move one line to a free id, with its section, its subsections and its claim (RK74).
196
+
197
+ Both registers come off the record (RK1170); `wrote` is passed because saving is this
198
+ door's step, so the paths are a fact about the call and not about the transaction.
199
+ """
200
+ try:
201
+ moved = renumber(config, args.id, args.to)
202
+ wrote = moved.save()
203
+ except REFUSALS as error:
204
+ return _refused(error)
205
+
206
+ if args.json:
207
+ print(json.dumps(moved.payload(config, wrote), indent=2))
208
+ else:
209
+ print(moved.stated(config, wrote))
210
+ return EXIT_OK
211
+
212
+
213
+ def _defer(config: Config, args: argparse.Namespace) -> int:
214
+ """Set one open line aside in the store, keeping its design where it is (RK229, RK327).
215
+
216
+ Both registers come off the record (RK1170); `wrote` is passed because saving is this
217
+ door's step, so the paths are a fact about the call and not about the transaction.
218
+ """
219
+ try:
220
+ pause = defer(config, args.id, reason=_piped(args.reason))
221
+ wrote = pause.save()
222
+ except REFUSALS as error:
223
+ return _refused(error)
224
+
225
+ if args.json:
226
+ print(json.dumps(pause.payload(config, wrote), indent=2))
227
+ else:
228
+ print(pause.stated(config, wrote))
229
+ return EXIT_OK
230
+
231
+
232
+ def _resume(config: Config, args: argparse.Namespace) -> int:
233
+ try:
234
+ resumption = resume(config, args.id, marker=args.marker)
235
+ wrote = resumption.save()
236
+ except REFUSALS as error:
237
+ return _refused(error)
238
+
239
+ if args.json:
240
+ print(json.dumps(resumption.payload(config, wrote), indent=2))
241
+ else:
242
+ print(resumption.stated(config, wrote))
243
+ return EXIT_OK
244
+
245
+
246
+ def declare_lines(subcommands: argparse._SubParsersAction) -> None:
247
+ """This module's verbs, declared where their handlers are (RK1171).
248
+
249
+ `build_parser` called forty-nine blocks like these in a row; what it calls now is an index
250
+ over the modules that own them. The move is what RK1169 and RK1170 bought: the flags a verb
251
+ declares, the reasons it withholds and the record it answers with are one file's, so a
252
+ change to any of them is one file's too.
253
+
254
+ The order inside is `build_parser`'s own, which is where these blocks sat.
255
+ """
256
+ next_id_parser = subcommands.add_parser(
257
+ "next-id",
258
+ help="the next unused task id, one past the highest anywhere",
259
+ description=(
260
+ "Print the next id. Never the first unused number: a retired id is never "
261
+ "reused, so filling its hole would make two tasks share it in the history."
262
+ ),
263
+ )
264
+ next_id_parser.add_argument(
265
+ "--prefix",
266
+ dest="family",
267
+ help=(
268
+ "count in this track (default: the first declared) — two tracks sharing a "
269
+ "counter are two tracks that renumber each other"
270
+ ),
271
+ )
272
+ next_id_parser.add_argument(
273
+ "--json",
274
+ action="store_true",
275
+ help="include where the highest id was found, so the answer can be audited",
276
+ )
277
+ # `reads_only` is what keeps a command out of the write lock (RK117), declared here
278
+ # beside `tolerates_config_error` because both are claims about the command rather than
279
+ # about its arguments. Absent means locked, so a new command is serialised until someone
280
+ # says it only reads — and `next-id` only reads: the race is not in the scan, it is in
281
+ # the span between this answer and the `add` that spends it.
282
+ next_id_parser.set_defaults(handler=_next_id, reads_only=True)
283
+
284
+ add_parser = subcommands.add_parser(
285
+ "add",
286
+ help="insert a task line under its block, refusing the fields at input",
287
+ description=(
288
+ "Compose, validate and insert one task line. Nothing is written unless "
289
+ "every field passes: a limit reported after the prose exists is a limit "
290
+ "discovered too late to save the tokens it was meant to save. With "
291
+ "--section the rationale the line points at is written in the same "
292
+ "transaction; without it, the follow-up the pointer needs is named."
293
+ ),
294
+ )
295
+ add_parser.add_argument("--block", required=True, help="the block label, e.g. B")
296
+ add_parser.add_argument(
297
+ "--symptom", required=True, help="what does not work — a phrase, never a fix"
298
+ )
299
+ add_parser.add_argument(
300
+ "--why", required=True, help="one sentence, ending in a stop" + _PIPE
301
+ )
302
+ add_parser.add_argument(
303
+ "--dep",
304
+ action="append",
305
+ default=[],
306
+ dest="deps",
307
+ metavar="DEP",
308
+ help="a dep, repeatable: an id, 'Block X', a range, or work outside the backlog",
309
+ )
310
+ add_parser.add_argument(
311
+ "--requires",
312
+ action="append",
313
+ default=[],
314
+ dest="requires",
315
+ metavar="REQUIREMENT",
316
+ help=(
317
+ "what must be present to finish this, repeatable and declared in "
318
+ "`[requirements]`: not a dep — `pick` offers it only to a caller that has one"
319
+ ),
320
+ )
321
+ _marker_flag(
322
+ add_parser,
323
+ "the status marker (default: the first marker roadkeep.toml declares)",
324
+ )
325
+ add_parser.add_argument(
326
+ "--id",
327
+ dest="task_id",
328
+ help="the id (default: derived, one past the highest anywhere)",
329
+ )
330
+ add_parser.add_argument(
331
+ "--prefix",
332
+ dest="family",
333
+ help=(
334
+ "which track the derived id counts in (default: the first declared); only "
335
+ "a backlog that numbers by track has a second one to name"
336
+ ),
337
+ )
338
+ add_parser.add_argument(
339
+ "--ref",
340
+ help=(
341
+ "the rationale anchor, for ref_scheme = 'outline' only; otherwise derived — "
342
+ "<prefix>:<x.y> for a prose file [refs] gives a namespace"
343
+ ),
344
+ )
345
+ add_parser.add_argument(
346
+ "--section",
347
+ metavar="TITLE",
348
+ help=(
349
+ "write the rationale under this heading, in the same transaction: the "
350
+ "pointer every line carries resolves to nothing until a section exists"
351
+ ),
352
+ )
353
+ add_parser.add_argument(
354
+ "--section-body",
355
+ dest="section_body",
356
+ help="the rationale prose; omitted or '-' reads stdin. Read only with --section",
357
+ )
358
+ add_parser.add_argument(
359
+ "--section-body-file",
360
+ dest="section_body_file",
361
+ metavar="PATH",
362
+ help=_BODY_FILE.format(what="rationale"),
363
+ )
364
+ add_parser.add_argument(
365
+ "--capture",
366
+ metavar="PATH",
367
+ help=(
368
+ "the kept capture this line files, stamped with the id this call mints (RK1141) "
369
+ "— `report` prints this flag already filled in, so the row `stats` counts is "
370
+ "cleared by the act that closes it and never by a second step somebody remembers"
371
+ ),
372
+ )
373
+ add_parser.add_argument(
374
+ "--json", action="store_true", help="the line, with the file and line it landed on"
375
+ )
376
+ # `reads_stdin` is declared here for the reason `reads_only` is (RK171): it is a claim about
377
+ # this command that a surface serving it has to know, and the only statement of it used to be
378
+ # the comment two lines above the read. Gated, because an `add` naming no section must never
379
+ # block on a pipe — which is what that comment said and nothing enforced.
380
+ withheld(
381
+ add_parser,
382
+ family="the id's prefix is `[ids]`' and `next-id` derives it; a caller choosing one is a caller numbering into another project's range",
383
+ capture='a path to a local artefact this transport does not share, and the verb that writes one is not a tool here',
384
+ )
385
+ add_parser.set_defaults(
386
+ handler=_add,
387
+ # Two, and this is the command that has two (RK329): the body was the obvious
388
+ # affordance because it is long, and the `why` is the one that actually needed it
389
+ # because it is the field that reliably carries what a shell reads first. Ungated,
390
+ # unlike the body: a `--why -` is the caller asking for the pipe outright.
391
+ reads_stdin=(
392
+ Prose(dest="section_body", gated_by="section", unless="section_body_file"),
393
+ Prose(dest="why", omitted=False),
394
+ ),
395
+ )
396
+
397
+ status_parser = subcommands.add_parser(
398
+ "status",
399
+ help="set a task's marker in the roadmap, and nowhere else",
400
+ description=(
401
+ "Write one task's status marker. Refused if a sibling file already carries "
402
+ "one for that id: two files that both express status will eventually "
403
+ "express different status, and nothing says which is right."
404
+ ),
405
+ )
406
+ status_parser.add_argument("id", help="the task, e.g. RK7")
407
+ status_parser.add_argument(
408
+ "marker", help="the new marker, from the open set this project declares"
409
+ )
410
+ status_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
411
+ status_parser.set_defaults(
412
+ handler=_status,
413
+ twin=(
414
+ "status writes a marker onto one line and needs both: `status <id> <marker>`."
415
+ " The backlog's numbers are `stats`, which needs neither — one character "
416
+ "apart, and this is the one that writes"
417
+ ),
418
+ )
419
+
420
+ amend_parser = subcommands.add_parser(
421
+ "amend",
422
+ help="correct one open line's why, deps or pointer",
423
+ description=(
424
+ "Correct the three fields a project that adopted the tool has to be able to fix: "
425
+ "a pointer it never had, a dep naming an id in neither file, and the compression "
426
+ "of a `why` that was a paragraph before the limit existed. Validated at input "
427
+ "exactly as `add` validates it, or nothing is written. The `symptom` is not "
428
+ "amendable — it is the claim the line is, so a different one is a different task."
429
+ ),
430
+ )
431
+ amend_parser.add_argument("id", help="the task, e.g. RK7")
432
+ amend_parser.add_argument(
433
+ "--why", help="the sentence, re-validated against the limit" + _PIPE
434
+ )
435
+ amend_parser.add_argument(
436
+ "--dep",
437
+ action="append",
438
+ dest="deps",
439
+ metavar="DEP",
440
+ help="a dep, repeatable: given at all, it replaces the whole group",
441
+ )
442
+ amend_parser.add_argument(
443
+ "--requires",
444
+ action="append",
445
+ dest="requires",
446
+ metavar="REQUIREMENT",
447
+ help="a requirement, repeatable: given at all, it replaces the whole group",
448
+ )
449
+ amend_parser.add_argument(
450
+ "--ref", help="the rationale anchor, for ref_scheme = 'outline'"
451
+ )
452
+ amend_parser.add_argument(
453
+ "--lines",
454
+ type=int,
455
+ help=(
456
+ "how many lines this correction replaces; required where the line wraps, which "
457
+ "on a roadmap only an adopted backlog can be"
458
+ ),
459
+ )
460
+ amend_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
461
+ amend_parser.set_defaults(
462
+ handler=_amend, reads_stdin=(Prose(dest="why", omitted=False),)
463
+ )
464
+
465
+ restate_parser = subcommands.add_parser(
466
+ "restate",
467
+ help="correct one open line's symptom, keeping its id",
468
+ description=(
469
+ "The one field `amend` does not reach, at a door of its own. A different symptom "
470
+ "is normally a different task, which is why that verb excludes it — and a premise "
471
+ "that turns out false is not a different task, it is this file asserting "
472
+ "something untrue in the field a reader sees first. `retire` plus `add` is the "
473
+ "exit that was designed for it, and it spends an id, deletes a section that was "
474
+ "already right and records a departure that never happened. This keeps all three. "
475
+ "A verb rather than a flag, so the act has a name a reviewer can see."
476
+ ),
477
+ )
478
+ restate_parser.add_argument("id", help="the task, e.g. RK7")
479
+ restate_parser.add_argument(
480
+ "--symptom",
481
+ required=True,
482
+ help="what does not work — re-validated against the limit, exactly as `add` does"
483
+ + _PIPE,
484
+ )
485
+ restate_parser.add_argument(
486
+ "--lines",
487
+ type=int,
488
+ help="how many lines this restatement replaces; required where the line wraps",
489
+ )
490
+ restate_parser.add_argument(
491
+ "--typo",
492
+ action="store_true",
493
+ help=(
494
+ "a slip of the pen rather than a false premise: the claim is the one intended "
495
+ "and a word in it was wrong, so the answer and the payload say so"
496
+ ),
497
+ )
498
+ restate_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
499
+ restate_parser.set_defaults(
500
+ handler=_restate,
501
+ # The field the pipe convention skipped, and the verb whose only prose argument it is
502
+ # (RK1187). A symptom carries the backtick and the apostrophe exactly as a `why` does,
503
+ # and is the one a shell corrupts most quietly — a symptom that lost an apostrophe
504
+ # still reads like prose somebody wrote, so nothing downstream calls it wrong. Ungated
505
+ # and sentinel-only, like `amend --why`: `--symptom` is required, so the omitted read
506
+ # is a shape argparse already refuses.
507
+ reads_stdin=(Prose(dest="symptom", omitted=False),),
508
+ )
509
+
510
+ renumber_parser = subcommands.add_parser(
511
+ "renumber",
512
+ help="move one open line to a free id, with its section and its dependents",
513
+ description=(
514
+ "Change one line's address, without a departure. The line, the section its "
515
+ "pointer resolves to and every dep naming it move in one transaction; the "
516
+ "ledger is never opened, because an id it records is a decision and not an "
517
+ "address. This is the repair a merge that allocated one id twice needs, and "
518
+ "the door `ship`, `retire` and `amend` all deliberately refuse to be."
519
+ ),
520
+ )
521
+ renumber_parser.add_argument("id", help="the line to move, e.g. RK90")
522
+ renumber_parser.add_argument(
523
+ "--to",
524
+ help="the new id (default: derived, one past the highest in the line's family)",
525
+ )
526
+ renumber_parser.add_argument("--json", action="store_true", help="every edit, as data")
527
+ renumber_parser.set_defaults(handler=_renumber)
528
+
529
+ defer_parser = subcommands.add_parser(
530
+ "defer",
531
+ help="set a line aside without retiring it: the store, not the ledger",
532
+ description=(
533
+ "A pause spelled as a retirement is terminal — the id cannot come back, the "
534
+ "resolver reads the dep as never, and the rationale is deleted. This moves the "
535
+ "line to the deferred store instead, keeping every slot and the section."
536
+ ),
537
+ )
538
+ defer_parser.add_argument("id", help="the task being set aside, e.g. RK33")
539
+ _reason_flag(
540
+ defer_parser,
541
+ "one sentence, the author's own: it wraps the why and a resume unwraps it" + _PIPE,
542
+ )
543
+ defer_parser.add_argument("--json", action="store_true", help="every edit, as data")
544
+ defer_parser.set_defaults(
545
+ handler=_defer, reads_stdin=(Prose(dest="reason", omitted=False),)
546
+ )
547
+
548
+ resume_parser = subcommands.add_parser(
549
+ "resume",
550
+ help="return a set-aside line to its block — the direction the ledger has none of",
551
+ description=(
552
+ "The store is revivable, which is what separates it from the two terminal "
553
+ "doors: the same id, the same deps, the same section, back under the block "
554
+ "the line left. The open marker is the one thing the store could not keep."
555
+ ),
556
+ )
557
+ resume_parser.add_argument("id", help="the task coming back, e.g. RK33")
558
+ _marker_flag(
559
+ resume_parser,
560
+ "the open marker it returns with; omitted, the first this project declares — "
561
+ "the store holds one marker, so which one it was is not a fact any file kept",
562
+ dest="marker",
563
+ )
564
+ resume_parser.add_argument("--json", action="store_true", help="every edit, as data")
565
+ resume_parser.set_defaults(handler=_resume)
566
+