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,2138 @@
1
+ """Every verb that answers a question, which is why it is the largest of them (RK494).
2
+
3
+ `list`, `stats`, `audit`, `show`, `brief`, `pick`, `budget`, `deps`, `anchors`, `gaps`,
4
+ `origin`, `weight`, `remaining`, `claims`, `claim`, `writes` and `export` — L5's whole
5
+ surface, where a question costs a command instead of a file in the context.
6
+
7
+ The three that can write are here anyway and say so: `brief --claim`, `pick --claim` and
8
+ `claims --prune` move a marker or a registry, which is what :func:`roadkeep.cli.dispatch`
9
+ reads to take the lock (RK167). Their subject is still the question, and filing a verb by
10
+ what one flag makes it would put one verb in two places.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import json
17
+ import sys
18
+
19
+ from roadkeep import attesting, claiming
20
+
21
+ from roadkeep.backlog import Backlog, NotOpen, Stage, Standing, Whereabouts
22
+ from roadkeep.capturing import debt
23
+ from roadkeep.briefing import NothingToBrief, brief
24
+ from roadkeep.budgeting import (
25
+ Load,
26
+ Session,
27
+ body_budget,
28
+ budget,
29
+ file_budget,
30
+ notice_budget,
31
+ non_goal_budget,
32
+ )
33
+ from roadkeep.config import Config, PROSE_ROLES
34
+ from roadkeep.counting import Census
35
+ from roadkeep.kernel.document import StaleFile, write_all
36
+ from roadkeep.exporting import DEFAULTS, project, spec, splice_into
37
+ from roadkeep.graph import Dependencies
38
+ from roadkeep.history import (
39
+ Unclosed,
40
+ pending,
41
+ Addresses,
42
+ HistoryUnavailable,
43
+ cited_origin,
44
+ families_of_block,
45
+ Gapped,
46
+ gaps,
47
+ indexed,
48
+ origin_of,
49
+ status,
50
+ )
51
+ from roadkeep.picking import Claim, Picked, pick, take
52
+ from roadkeep.provenance import invocation
53
+ from roadkeep.remaining import EVIDENCE, QueryError, count, declared
54
+ from roadkeep.rendering import (
55
+ CHARACTER_UNIT,
56
+ _claim_event,
57
+ _commits_json,
58
+ _load_json,
59
+ _nothing_json,
60
+ )
61
+ from roadkeep.serving import Prose, Withheld, detail, surface
62
+ from roadkeep.showing import show
63
+ from roadkeep.verbs.declaring import (
64
+ _DESIGNED_HELP,
65
+ _HAVE_HELP,
66
+ _JSON_HELP,
67
+ _PIPE,
68
+ _counting_flags,
69
+ _marker_flag,
70
+ answers,
71
+ narrows,
72
+ withheld,
73
+ )
74
+ from roadkeep.verbs.reading import _body_reader, _one_body, _piped
75
+ from roadkeep.verbs.refusing import EXIT_GATE, EXIT_OK, EXIT_USAGE, REFUSALS, _refused
76
+ from roadkeep.weighing import Weighed, weigh
77
+
78
+
79
+ def _census(config: Config, args: argparse.Namespace) -> tuple[Census, Standing | None]:
80
+ """The census a `--block` narrows, and what became of the label it named (RK429).
81
+
82
+ A count reads one file, and keeping it that way is why `stats` cannot go stale against
83
+ a changelog it never read. So the second file is opened only where a label was named,
84
+ and what it answers is never counted — only said, on stderr, beside a listing that is
85
+ still exactly what the file holds.
86
+
87
+ Exactly one state changes what this returns, and it is the narrow one: a label this
88
+ file declares no heading for **and** that has nothing left anywhere — the block whose
89
+ last line shipped and whose roadmap heading `block drop` then took. A **live** block
90
+ missing from the file being counted keeps its refusal, because there the file really
91
+ does not declare a label that work is filed under, and `unknown` keeps its own for the
92
+ reason it exists: it is the only one that is a typo.
93
+ """
94
+ marker = getattr(args, "marker", None)
95
+ census = Census.read(config, args.role)
96
+ if args.block is None:
97
+ return census.select(marker=marker), None
98
+ if not config.has("roadmap") or not config.path("roadmap").is_file():
99
+ # Nothing to join against: the reader below needs the roadmap, and a project
100
+ # counting a ledger before `init` wrote one still gets the count it asked for.
101
+ return census.select(block=args.block, marker=marker), None
102
+ standing = Backlog.load(config).standing(args.block)
103
+ if standing.settled and args.block not in census.blocks:
104
+ # Narrowed by the marker first and *then* emptied, so an undeclared marker is
105
+ # refused here exactly as it is on every other path: a filter nobody validated is
106
+ # a filter that silently matches nothing, which is the answer a clean file gives.
107
+ return census.select(marker=marker).elsewhere(args.block), standing
108
+ if standing.stage is Stage.UNKNOWN and args.block in census.blocks:
109
+ # The file being counted declares a label the roadmap and the ledger do not — a
110
+ # deferred store is the one that can. Saying `unknown` beside the lines it just
111
+ # listed would be the payload contradicting the listing.
112
+ return census.select(block=args.block, marker=marker), None
113
+ return census.select(block=args.block, marker=marker), standing
114
+
115
+
116
+ def _list(config: Config, args: argparse.Namespace) -> int:
117
+ try:
118
+ census, standing = _census(config, args)
119
+ except (KeyError, OSError) as error:
120
+ return _refused(error)
121
+
122
+ if args.json:
123
+ print(json.dumps(census.listing(standing), indent=2))
124
+ else:
125
+ listed = census.listed(args.ids)
126
+ if listed:
127
+ print(listed)
128
+ for note in census.notes(standing):
129
+ print(note, file=sys.stderr)
130
+ return EXIT_OK
131
+
132
+
133
+ def _stats(config: Config, args: argparse.Namespace) -> int:
134
+ try:
135
+ census, standing = _census(config, args)
136
+ except (KeyError, OSError) as error:
137
+ return _refused(error)
138
+ # The capture debt is a second subject and joined here (RK1139): a capture is not a line
139
+ # of the file this counts, so reading one inside the census would make a count of the
140
+ # roadmap depend on a directory git ignores.
141
+ owed = debt(config)
142
+ if args.json:
143
+ print(json.dumps(census.counts(config, standing, owed), indent=2))
144
+ else:
145
+ print(census.counted_out(config, owed))
146
+ for note in census.silence(standing):
147
+ print(note, file=sys.stderr)
148
+ return EXIT_OK
149
+
150
+
151
+ def _audit(config: Config, args: argparse.Namespace) -> int:
152
+ try:
153
+ census, standing = _census(config, args)
154
+ except (KeyError, OSError) as error:
155
+ return _refused(error)
156
+
157
+ if args.json:
158
+ print(json.dumps(census.audit(standing), indent=2))
159
+ else:
160
+ print(census.audited())
161
+ for note in census.silence(standing):
162
+ print(note, file=sys.stderr)
163
+ return EXIT_OK
164
+
165
+
166
+ def _claims(config: Config, args: argparse.Namespace) -> int:
167
+ """The registry read against the roadmap (RK161). Nothing here is a failure, so exit 0."""
168
+ try:
169
+ # The whole backlog and not the roadmap alone (RK164): three of the four ways an id can
170
+ # be absent from it are recorded in the other two files.
171
+ if args.prune:
172
+ pruning = claiming.prune(config)
173
+ rows, dropped = pruning.kept, pruning.dropped
174
+ else:
175
+ rows, dropped = claiming.survey(Backlog.load(config)), ()
176
+ except (KeyError, OSError) as error:
177
+ return _refused(error)
178
+
179
+ answer = claiming.Registry(
180
+ rows=tuple(rows),
181
+ dropped=tuple(dropped),
182
+ pruned=bool(args.prune),
183
+ registry=str(claiming.path(config.root)),
184
+ window=config.held,
185
+ )
186
+
187
+ if args.json:
188
+ print(json.dumps(answer.payload(), indent=2))
189
+ else:
190
+ print(answer.stated())
191
+ return EXIT_OK
192
+
193
+
194
+ def _claim(config: Config, args: argparse.Namespace) -> int:
195
+ """One held line's scope: declared, or read back at the commit (RK280).
196
+
197
+ The read is the half that earns the command. `git status` shows a tree two sessions wrote
198
+ and says nothing about which half is whose, so the author committing was left an analysis
199
+ to make with no facts to make it from — and `agents.md` carried the answer as advice,
200
+ which RK1 says does not hold. Here the three lists are separate because the caller does
201
+ three different things with them: stage `mine`, leave `theirs`, and decide about `loose`.
202
+
203
+ `--add-path` is the same write from the other end (RK307), and passing both is refused
204
+ rather than merged: `--path` says *this is the scope* and `--add-path` says *and this
205
+ too*, so a call making both statements is one whose author has not decided which — and
206
+ reading it as either would be the tool picking.
207
+ """
208
+ backlog = Backlog.load(config)
209
+ entries = backlog.roadmap.entries
210
+ if args.path and args.add_path:
211
+ return _refused(
212
+ ValueError(
213
+ "--path replaces the scope and --add-path keeps it, so a call passing both "
214
+ "says two things about one commit: name the whole scope with --path, or add "
215
+ "to what is already there with --add-path alone"
216
+ )
217
+ )
218
+ try:
219
+ if args.path or args.add_path:
220
+ mine = claiming.scope(
221
+ config,
222
+ args.id,
223
+ args.path or args.add_path,
224
+ extend=bool(args.add_path),
225
+ )
226
+ else:
227
+ held = next((one for one in claiming.live(config, entries) if one.id == args.id), None)
228
+ if held is None:
229
+ raise claiming.NotHeld(args.id)
230
+ mine = held.paths
231
+ except (claiming.NotHeld, KeyError, OSError) as error:
232
+ return _refused(error)
233
+
234
+ # What this task's own transactions already wrote (RK342), by the reading `ship` makes
235
+ # off its own `save` — which only exists inside a transaction, so here it is read off
236
+ # the files: a claim moved a marker onto this line and the projections were refreshed
237
+ # from it, and both diffs name the id. Without it the report called them `loose`, which
238
+ # reads as *somebody else touched this*, and the author declared them by hand to
239
+ # silence it — the scope then carrying paths that were never the work.
240
+ seen = status(config)
241
+ wrote = claiming.written(config, args.id, seen.changed)
242
+ # The subtraction is `claiming`'s (RK294), because `ship` asks for the same lists at the
243
+ # moment of committing and two compositions of one answer is how they come to disagree.
244
+ # Git is asked here and not there: this command was told to answer.
245
+ # `accounted=wrote` (RK1117): here the word means what it always meant on this path — the
246
+ # dirty governed files whose diff carries this id — and the subtraction it feeds is the
247
+ # same one a departure makes, now made in one place rather than by each printer.
248
+ #
249
+ # And `shared` with it (RK1122): this is the read a commit is composed from, so the ids
250
+ # inside a file it is about to stage are exactly what it exists to say. Asked here rather
251
+ # than deep in the split for the same reason git is — this command was told to answer.
252
+ answer = claiming.Claimed(
253
+ task_id=args.id,
254
+ scope=claiming.split(
255
+ config,
256
+ args.id,
257
+ entries,
258
+ seen.changed,
259
+ indexed(config),
260
+ accounted=wrote,
261
+ shared=claiming.sharing(config, args.id, wrote),
262
+ staged=seen.staged,
263
+ ),
264
+ wrote=tuple(wrote),
265
+ )
266
+
267
+ # Three registers and not two (RK1170): `--porcelain` is a third reading of one result and
268
+ # not a narrowing of either — a shell consumes it, so it carries paths and nothing else.
269
+ if args.porcelain:
270
+ print(answer.porcelain())
271
+ elif args.json:
272
+ print(json.dumps(answer.payload(), indent=2))
273
+ else:
274
+ print(answer.stated())
275
+ return EXIT_OK
276
+
277
+
278
+ def _writes(config: Config, args: argparse.Namespace) -> int:
279
+ """The write record read against the files (RK200). Nothing here is a failure, so exit 0."""
280
+ survey = attesting.Survey(
281
+ attesting.survey(config), str(attesting.record_path(config.root))
282
+ )
283
+ if args.json:
284
+ print(json.dumps(survey.payload(), indent=2))
285
+ else:
286
+ print(survey.stated())
287
+ return EXIT_OK
288
+
289
+
290
+ def _brief(config: Config, args: argparse.Namespace) -> int:
291
+ if args.id is not None and (args.block is not None or args.designed or args.have):
292
+ # Two answers to one question: the id names a task and the others name a search.
293
+ # `--have` joins them for the same reason and not a weaker one (RK1297): it narrows
294
+ # what may be *chosen*, and a caller that named the line has already chosen — the
295
+ # refusal it would otherwise want is `brief <id>`'s own, which this verb does not make.
296
+ narrowed = (
297
+ "--block"
298
+ if args.block is not None
299
+ else ("--designed" if args.designed else "--have")
300
+ )
301
+ print(
302
+ f"roadkeep: give an id or {narrowed}, not both: an id is already the answer "
303
+ f"{narrowed} would look for",
304
+ file=sys.stderr,
305
+ )
306
+ return EXIT_USAGE
307
+ try:
308
+ gathered = brief(
309
+ config, args.id, args.block, args.designed, args.claim, args.have
310
+ )
311
+ except NothingToBrief as nothing:
312
+ # The one branch a loop actually reads, and the one `--json` did not cover (RK409).
313
+ # `brief --block <x>` is how a worker asks what to do next, and "nothing is open in
314
+ # Block <x>" is the only answer that means the block is finished — so a loop driving
315
+ # one to completion polls exactly this, and asked for JSON got an empty stdout and
316
+ # the sentence on stderr, where a real failure also lands.
317
+ #
318
+ # Still **not** exit 0, and still not a fourth exit code. An empty answer is nothing
319
+ # to brief, so succeeding would make a typo'd block name look like a finished one;
320
+ # and what the caller could not do at exit 2 was tell those two apart, which the
321
+ # payload now answers directly — `standing.state` is the word, `empty` stays the
322
+ # boolean it always was, and the refusal for a name nothing declares never reaches
323
+ # here at all (RK429 made the sentence say which; this comment predates it).
324
+ if args.json:
325
+ print(json.dumps(_nothing_json(nothing, args), indent=2))
326
+ return EXIT_USAGE
327
+ return _refused(nothing)
328
+ except REFUSALS as error:
329
+ # The whole tuple, because `--claim` makes this a write (RK149): every refusal that
330
+ # guards a marker reaches here, plus the one this door has of its own — a named line
331
+ # somebody else is already holding.
332
+ return _refused(error)
333
+
334
+ # Both registers off the record (RK1170), and the last of the verbs that task measured:
335
+ # `Brief` is the answer, and its two readings were 20 prints here and a builder in
336
+ # `rendering.py` — one answer in two files, with neither of them where a brief is composed.
337
+ print(json.dumps(gathered.payload(config), indent=2) if args.json else gathered.stated(config))
338
+ return EXIT_OK
339
+
340
+
341
+ def _show(config: Config, args: argparse.Namespace) -> int:
342
+ """One task, whole, from every file that holds a piece of it (RK9).
343
+
344
+ Both registers come off the record (RK1170): `View` is the answer, and its two readings were a
345
+ printer here and a builder in `rendering.py` — one verb spelled in two files, with neither
346
+ holding both. What is left here is the door.
347
+ """
348
+ try:
349
+ view = show(config, args.id)
350
+ except (KeyError, OSError) as error:
351
+ return _refused(error)
352
+
353
+ if args.json:
354
+ print(json.dumps(view.payload(body=not args.no_body), indent=2))
355
+ else:
356
+ print(view.stated(config, body=not args.no_body))
357
+ return EXIT_OK
358
+
359
+
360
+ def _cost(config: Config, args: argparse.Namespace) -> int:
361
+ """What this project's surface already spends (RK1321).
362
+
363
+ `_budget`'s dispatch for the other tense. The three subjects moved here whole — the same
364
+ readers, the same registers — because what split was the *verb* and not any answer: eight
365
+ subjects under one name made `budget` the largest served tool at 2,741, against a per-tool
366
+ ceiling calibrated on `ship` at 2,466, so whichever arrived last was refused by a limit
367
+ none of them was about.
368
+
369
+ Which subject was asked for, and that exactly one was, is `answers` at this verb's own
370
+ `add_parser` and `dispatch`'s to refuse (RK489) — so what is left here is the dispatch.
371
+ """
372
+ # `is not None` and not truth (RK1236): bare `--tools` is the empty string, the flag
373
+ # taking a value, which is `--brief`'s reading one subject over.
374
+ if args.tools is not None:
375
+ return _tools_budget(config, args)
376
+ if args.brief is not None:
377
+ return _brief_budget(config, args)
378
+ if args.session:
379
+ return _session_budget(config, args)
380
+ # No subject is the default here, unlike `budget`, whose bare form is about the line `add`
381
+ # would write next. These three are three cadences — once at connect, once per turn, once
382
+ # per read — and privileging one would make the other two look like narrowings of it.
383
+ print(
384
+ "roadkeep: cost takes a subject: --tools for the served surface, --brief for what "
385
+ "that read costs a tool result, --session for both against their cadences",
386
+ file=sys.stderr,
387
+ )
388
+ return EXIT_USAGE
389
+
390
+
391
+ def _budget(config: Config, args: argparse.Namespace) -> int:
392
+ # Which of the three subjects was asked for, and whether `--role` or `--lead` came with
393
+ # the one it narrows, are `answers` and `narrows` at this verb's own `add_parser` and
394
+ # `dispatch`'s to refuse (RK489). What is left here is the dispatch itself.
395
+ if args.anchor:
396
+ return _body_budget(config, args)
397
+ if args.non_goal:
398
+ return _non_goal_budget(config, args)
399
+ if args.file is not None:
400
+ return _file_budget(config, args)
401
+ clash = _one_body("--body", args.body, args.body_file)
402
+ if clash is not None:
403
+ print(f"roadkeep: {clash}", file=sys.stderr)
404
+ return EXIT_USAGE
405
+ try:
406
+ answer = budget(
407
+ config,
408
+ args.id,
409
+ block=args.block,
410
+ deps=args.deps,
411
+ status=args.status,
412
+ symptom=args.symptom,
413
+ family=args.family,
414
+ ref=args.ref,
415
+ # Read here and not in `budgeting`, which touches no stream: the pipe is this
416
+ # surface's affordance and the module measures whatever it is handed (RK1190).
417
+ why=_piped(args.why),
418
+ # And the other half of the same transaction (RK1224): `add --section` writes a
419
+ # line and a body together, so pricing them in two calls made the retry for a
420
+ # three-character overflow carry the whole paragraph again.
421
+ body=(
422
+ None
423
+ if args.body is None and args.body_file is None
424
+ else _body_reader(args.body, args.body_file)()
425
+ ),
426
+ # The third write off the same line (RK1305). `is not None` and not truth, which is
427
+ # `--tools`' reading: bare `--retire` is the empty string and means abandoned.
428
+ retire=args.retire,
429
+ )
430
+ except REFUSALS as error:
431
+ return _refused(error)
432
+
433
+ # Both registers off the record (RK1170): `Budget` already was the result this verb computed,
434
+ # and its two readings were a printer here and a builder in `rendering.py` — one answer in two
435
+ # files, with neither holding both.
436
+ print(json.dumps(answer.payload(), indent=2) if args.json else answer)
437
+ # Both halves of the transaction decide it (RK1224): a body three words over is a call the
438
+ # `add` refuses whole, so an exit that spoke only for the line would answer a question
439
+ # narrower than the one the caller asked.
440
+ return _verdict(
441
+ any(share.over for share in answer.shares if share.drafted)
442
+ or bool(answer.section is not None and answer.section.over)
443
+ )
444
+
445
+
446
+ def _verdict(over: bool) -> int:
447
+ """Exit 1 where a draft this call was handed does not fit (RK1190).
448
+
449
+ `EXIT_GATE`, and it is that code's own meaning: the write this read stands in for would have
450
+ refused, and a caller asking *will this fit* should not have to parse prose for the one bit
451
+ it asked for. Over MCP the same code becomes `isError`, which is what makes the answer usable
452
+ by the agent this whole read exists for.
453
+
454
+ **Only about a draft**, which is the narrowing that keeps this a read. A line the roadmap
455
+ already holds over its allowance is a `lint` finding and the gate's business; reporting it
456
+ here as a failure would make `budget <id>` exit non-zero over a file it was only asked to
457
+ describe, and make one verb answer for two different questions with one code.
458
+ """
459
+ return EXIT_GATE if over else EXIT_OK
460
+
461
+
462
+ def _body_budget(config: Config, args: argparse.Namespace) -> int:
463
+ """What a section body may say, before it is written — and what a draft of it costs.
464
+
465
+ The draft is read the way every writing verb reads one (RK381, RK329): a literal, a path,
466
+ or the pipe that `-` names. Unlike those verbs it is **optional here**, so an omitted
467
+ `--body` reads nothing at all rather than blocking on a stream nobody opened — the whole
468
+ subject of this call is a limit, which is answerable with no prose in hand (RK1190).
469
+ """
470
+ clash = _one_body("--body", args.body, args.body_file)
471
+ if clash is not None:
472
+ print(f"roadkeep: {clash}", file=sys.stderr)
473
+ return EXIT_USAGE
474
+ try:
475
+ # Inside the try for `section add`'s reason: prose that is not UTF-8 raises
476
+ # UnicodeDecodeError, which is a ValueError and is refused with the same code.
477
+ draft = (
478
+ None
479
+ if args.body is None and args.body_file is None
480
+ else _body_reader(args.body, args.body_file)()
481
+ )
482
+ answer = body_budget(config, args.anchor, args.role, draft)
483
+ except REFUSALS as error:
484
+ return _refused(error)
485
+ if args.json:
486
+ print(json.dumps({"subject": "section", **answer.payload()}, indent=2))
487
+ return _verdict(bool(answer.over))
488
+ state = "written" if answer.written else "the section add would write"
489
+ print(f"§{answer.anchor} {answer.role} ({state})")
490
+ print(f" body {answer.stated(named=False)}")
491
+ return _verdict(bool(answer.over))
492
+
493
+
494
+ def _file_budget(config: Config, args: argparse.Namespace) -> int:
495
+ """What an always-loaded file has left, before the edit is composed (RK345)."""
496
+ try:
497
+ loads = file_budget(config, args.file or None)
498
+ except REFUSALS as error:
499
+ return _refused(error)
500
+ if args.json:
501
+ print(json.dumps({"subject": "file", "files": [_load_json(one) for one in loads]},
502
+ indent=2))
503
+ return EXIT_OK
504
+ for load in loads:
505
+ # The state `lint` calls `budget.absent`, said here too: a declared file that is not
506
+ # there has its whole budget free, which is the one reading that looks like room.
507
+ state = "on disk" if load.present else "not on disk — the entry holds nothing"
508
+ print(f"{load.path} budgeted ({state})")
509
+ for cost in load.costs:
510
+ # No aim and no second unit (RK258): `[budgets]` is declared in what the loader
511
+ # pays, so a word figure beside it would be a number this project never stated.
512
+ over = f", {cost.over} over" if cost.over else f", {cost.left} left"
513
+ print(f" {cost.unit:<11}{cost.taken} of {cost.limit}{over}")
514
+ if load.translated:
515
+ # The remainder the ceiling does not charge (RK1105). Printed under the units and
516
+ # not beside one, because it is a fact about the checkout and not about the budget:
517
+ # the number above decides, and this one is what a loader here actually reads.
518
+ print(
519
+ f" {'checkout':<11}{load.translated} more, this tree's lines ending CRLF — "
520
+ f"counted as the commit stores them"
521
+ )
522
+ _print_parts(load)
523
+ if load.characters is not None:
524
+ # The figure the author is actually deciding against (RK1250), on the read RK345
525
+ # built for the moment before an edit — `--session` has had it since RK1245 and
526
+ # this one, the more likely to be open, threw it away.
527
+ #
528
+ # A **row** and not a clause on a cost, which is RK258's line kept rather than
529
+ # crossed: that task refused a word figure *beside a declared unit*, because
530
+ # `[budgets]` is stated in what the loader pays and an aim next to it would be a
531
+ # number this project never wrote. This is not next to one and is not an aim — it
532
+ # is a reading, and its clause says outright that nothing limits it.
533
+ #
534
+ # **Last, and under the breakdown** (RK1252). Printed between the limits and the
535
+ # sections, it was the total a reader met immediately before a list ranked in
536
+ # another unit — so the adjacency said *this is what those are of*, which it is
537
+ # not. The breakdown belongs to the ceiling above it; this belongs to neither.
538
+ print(
539
+ f" {'reader':<11}{load.characters} utf-16-code-units, what a model is "
540
+ f"charged — a reading, and nothing here limits it"
541
+ )
542
+ return EXIT_OK
543
+
544
+
545
+ #: How many sections the terminal names, for `_LARGEST_TOOLS`' reason: the largest few are
546
+ #: where the size went, and a caller reading a report to decide what to cut wants those.
547
+ _LARGEST_PARTS = 4
548
+
549
+
550
+ def _print_parts(load: Load) -> None:
551
+ """Where the size is, so the next compression is aimed (RK1092).
552
+
553
+ The read `cost --tools` makes about the served surface, one file over: a total says an
554
+ edit will be refused and says nothing about what to take out, and `agents.md` reaching
555
+ eight bytes of room turned *compress the prose* into a preference nothing had re-measured.
556
+
557
+ Only where the file is on disk and holds more than one section, because a single-section
558
+ file's breakdown is the total printed twice.
559
+
560
+ **Ranked by the limit about to refuse** (RK1252), which is :attr:`Load.ranked`'s decision
561
+ and not this renderer's: a file at 104 of 125 lines and 6906 of 8400 bytes is a line
562
+ problem, and a list ordered by bytes names a section that is not the one to cut. The
563
+ ranking unit leads the row, so the column a reader sorts on is the column they scan.
564
+ """
565
+ if len(load.parts) < 2:
566
+ return
567
+ unit = "bytes" if load.tightest is None else load.tightest.unit
568
+ other = "bytes" if unit == "lines" else "lines"
569
+ ranked = load.ranked
570
+ # Three figures need a header, where two did not (RK1253): the leading column varies with
571
+ # the ceiling and the third is a reading rather than a limit, so a row of bare numbers no
572
+ # longer says which is which. Named in the order they are printed, ranking unit first.
573
+ reading = " reader" if ranked[0].characters is not None else ""
574
+ print(f" {unit:>6} {other:>6}{reading}")
575
+ for part in ranked[:_LARGEST_PARTS]:
576
+ first, second = (part.lines, part.bytes) if unit == "lines" else (part.bytes, part.lines)
577
+ # Both declared columns at one width, because which of them leads now varies: a `>3`
578
+ # sized for lines misaligns the byte figure it may now hold.
579
+ said = f" {first:>6} {second:>6}"
580
+ if part.characters is not None:
581
+ said += f" {part.characters:>6}"
582
+ print(f"{said} {part.heading or '(before the first ##)'}")
583
+ if len(ranked) > _LARGEST_PARTS:
584
+ print(f" … and {len(ranked) - _LARGEST_PARTS} more — `--json` lists every one")
585
+
586
+
587
+ def _non_goal_budget(config: Config, args: argparse.Namespace) -> int:
588
+ """The two limits the roadmap's other bullet has (RK283)."""
589
+ try:
590
+ shares = non_goal_budget(config, args.lead)
591
+ except REFUSALS as error:
592
+ return _refused(error)
593
+ if args.json:
594
+ print(json.dumps({"subject": "non-goal", "lead": args.lead,
595
+ "fields": [one.payload() for one in shares]}, indent=2))
596
+ return EXIT_OK
597
+ where = config.relative(config.path("roadmap"))
598
+ state = f"the bullet leading {args.lead!r}" if args.lead else "the bullet add would write"
599
+ print(f"non-goals {where} ({state})")
600
+ # The line `Budget.__str__` prints for the same reason (RK1366): `non-goal amend --why`
601
+ # replaces that argument, so each remainder below is the whole limit and a reader given
602
+ # `37 written, 200 left` against 200 otherwise reads the two as adding up.
603
+ if any(share.replaced and share.taken for share in shares):
604
+ print(
605
+ " replacing what is written below, so each remainder is the whole limit and "
606
+ "not what is left beside it — an amend rewrites the field"
607
+ )
608
+ for share in shares:
609
+ # No `bound_by_line`: a non-goal is two fields on two lines and there is no third
610
+ # limit measured across them, which is the whole difference from a task line.
611
+ taken = f", {share.taken} written, {share.left} left" if share.taken else ""
612
+ print(f" {share.field:<11}{share.limit}{taken} {share.aimed}")
613
+ return EXIT_OK
614
+
615
+
616
+ #: How many tools the listing names before it stops naming them one by one. The largest few
617
+ #: are where the size went, and a caller reading a report to decide what to cut wants those;
618
+ #: the rest is the total, which is the number this read exists to state (RK464).
619
+ _LARGEST_TOOLS = 5
620
+
621
+
622
+ def _session_budget(config: Config, args: argparse.Namespace) -> int:
623
+ """Both halves of what a session pays, against the cadence each is paid at (RK1095).
624
+
625
+ `--tools` totals the served schema and `--file` totals a resident file, and neither knew
626
+ the other existed — so an author deciding whether to cut a tool description or a
627
+ paragraph ran two commands and subtracted by hand. That is the arithmetic RK183 removed
628
+ from the line budget and RK345 from the file one, still standing one level above both.
629
+
630
+ **Two figures and never a sum.** The schema is sent once at the handshake and a resident
631
+ file is read on every turn, so adding them produces a number that is wrong for every
632
+ session whose turn count is not one — which is all of them. What is honest is naming each
633
+ against what it is paid for, and letting the reader multiply the half that repeats.
634
+
635
+ The skill is not here, deliberately (RK23): it is trigger-loaded, so it costs the turns
636
+ that write and nothing on the turns that do not, and pricing it as resident would be the
637
+ third figure this read exists to avoid inventing.
638
+ """
639
+ # One measurement, two readers (RK1096) — the rule RK345 already states about the file
640
+ # half, applied to the surface: `--tools` ranks what this returns and `--session` totals
641
+ # it, so a change to what the handshake carries moves both or neither.
642
+ sent = surface(config)
643
+ resident, limit = notice_budget(config)
644
+ answer = Session(
645
+ once=sent.characters,
646
+ tools=len(sent.tools),
647
+ # The records themselves (RK1248): both readings of one file (RK1245) plus the room
648
+ # its own `[budgets]` line declares, all of which `Load` already holds.
649
+ resident=file_budget(config) if config.budgets else (),
650
+ # The third thing a session pays for (RK1243), and the one that had a ceiling nobody
651
+ # could ask about — measured off `announce`, so it is the line this project's sessions
652
+ # actually get rather than a second estimate of it.
653
+ # What the checkout contributes, named apart from what the surface does (RK1334): a
654
+ # session really is sent it, so it stays inside `once`, and no author can edit it, so
655
+ # the ceiling is not about it.
656
+ provenance=sent.provenance,
657
+ notice=resident,
658
+ notice_limit=limit,
659
+ # The ceiling `budget.session` refuses this total against, which is the single one
660
+ # there is (RK1333): read off the config here rather than recomputed, so the row and
661
+ # the gate cannot come apart the way the row and the notice's ceiling already had.
662
+ once_limit=config.tool_session,
663
+ )
664
+
665
+ if args.json:
666
+ print(json.dumps(answer.payload(CHARACTER_UNIT), indent=2))
667
+ else:
668
+ print(answer.stated(CHARACTER_UNIT))
669
+ return EXIT_OK
670
+
671
+
672
+ def _brief_budget(config: Config, args: argparse.Namespace) -> int:
673
+ """What a brief costs a tool result, per open line or for the one named (RK1286).
674
+
675
+ The sixth subject, and the one about a **read** rather than about prose or a file. Every
676
+ resident file has a budget and the served surface has two, on RK30's argument that a limit
677
+ nobody counts is a limit that moves — and the read this project recommends over reading
678
+ the file had none, while growing four arithmetic rows in one session.
679
+ """
680
+ from roadkeep.budgeting import brief_budget # noqa: PLC0415 - RK260
681
+
682
+ try:
683
+ found = brief_budget(config, args.brief or None)
684
+ except (KeyError, OSError) as error:
685
+ return _refused(error)
686
+
687
+ if args.json:
688
+ print(
689
+ json.dumps(
690
+ {
691
+ "unit": CHARACTER_UNIT,
692
+ "limit": found.limit,
693
+ "briefs": [
694
+ {"id": one.id, "characters": one.characters, "over": one.over(found.limit)}
695
+ for one in found.briefs
696
+ ],
697
+ # What the ranking could not measure (RK1288), which is the fact the
698
+ # widest is wrong without: `[]` is an answer and never an absence.
699
+ "unpriced": [
700
+ {"id": one.id, "because": one.because} for one in found.unpriced
701
+ ],
702
+ # Carried and never reconstructed (RK1289): priced, refused and not asked
703
+ # for are three numbers that add up to this one.
704
+ "elided": found.elided,
705
+ "open_lines": found.open_lines,
706
+ },
707
+ indent=2,
708
+ )
709
+ )
710
+ return EXIT_OK
711
+ # Both, because a ranking that is empty and a ranking whose every line refused are two
712
+ # answers (RK1288): the second has everything to report and nothing in the first column.
713
+ if not (found.briefs or found.unpriced):
714
+ print(
715
+ f"roadkeep: no open line to brief, so there is nothing to price — "
716
+ f"`{invocation()} list` says what the backlog holds"
717
+ )
718
+ return EXIT_OK
719
+ # The verdict says what it was taken over (RK1292). `0 over` beside a listing that names
720
+ # a line nobody could measure is a claim the ranking is not entitled to: the widest is
721
+ # the bound, and an unmeasured line is the shape most likely to be it. The gate has no
722
+ # such problem — there the absence is its own finding and the exit code is 1 either way —
723
+ # and here one string carried both the count and the confidence. Silent where nothing
724
+ # went unmeasured, which keeps the ordinary answer exactly as short as it was.
725
+ qualified = f", {len(found.unpriced)} unpriced" if found.unpriced else ""
726
+ ceiling = (
727
+ "no [reads] brief — this project declares no ceiling for the read that replaces "
728
+ "reading the file"
729
+ if found.limit is None
730
+ else f"{found.limit} allowed, {len(found.over)} over{qualified}"
731
+ )
732
+ rows = [f"{len(found.briefs)} brief(s), widest first, in {CHARACTER_UNIT}: {ceiling}"]
733
+ for one in found.briefs:
734
+ room = "" if found.limit is None else f" {found.limit - one.characters:+d}"
735
+ rows.append(f" {one.id:<10} {one.characters}{room}")
736
+ # Named under the ranking (RK1288): a line the read could not compose is the one most
737
+ # likely to have been the widest, so the top of the rest is not the answer while it is
738
+ # unaccounted for — and what refused it is the tool's own sentence, not one composed here.
739
+ rows += [f" {one.id:<10} unpriced — {one.because}" for one in found.unpriced]
740
+ print("\n".join(rows))
741
+ return EXIT_OK
742
+
743
+
744
+ def _tools_budget(config: Config, args: argparse.Namespace) -> int:
745
+ """What this project's tool list costs a session, stated because nothing stated it (RK464).
746
+
747
+ RK30 put `[budgets]` on the files a session loads every turn, because resident prose has
748
+ no natural ceiling — the 186 KB `agents.md` in §0.1 is the measurement this project starts
749
+ from — and `lint` refuses one over. The schema this server publishes was counted nowhere:
750
+ measured on a three-file project, 51 tools and 52,892 characters, six times the budget the
751
+ resident file is held to, paid once per session that connects the server.
752
+
753
+ That is not a claim the list is too long. It is that the number was not stated, and RK30's
754
+ own argument is that a limit nobody counts is a limit that moves: every task adding a tool
755
+ or a sentence to a description spends this, and each spend looks free where it is written.
756
+
757
+ **And the ceiling §RK464 left open** (RK1059), once the number had been looked at: it is
758
+ per tool, declared as `[tools] characters`, and `lint` refuses one over. A total names
759
+ nothing — it fails on whichever tool is added last — where a per-tool figure is refused
760
+ by the tool whose description somebody just edited, which is the ranking this read
761
+ already prints. Reported here as the room a caller has before the gate says no, which is
762
+ the pairing RK345 makes everywhere else: a limit that reaches an author only as a refusal
763
+ is the verdict-after-the-prose this project exists to replace.
764
+
765
+ **Both halves of what a session is handed** (RK1062), because one of them was a place to
766
+ hide in. The handshake is the other message sent before the first call, and RK1060 moved
767
+ a paragraph from the tool list into it — a real saving, reported gross, by a read that
768
+ could not see where it went. An edit that saved nothing would have measured the same.
769
+ Not folded into the ranking: no per-tool ceiling is about it, so it is named under them.
770
+
771
+ Derived from :func:`~roadkeep.serving.descriptors`, so it is the payload a client is
772
+ actually sent rather than a second estimate of it: a description reworded in `cli.py`
773
+ moves this figure, which is the whole reason the number is worth reading.
774
+ """
775
+ if args.tools:
776
+ # Named, so the question is which of *this* tool's fields spent the bytes (RK1236) —
777
+ # the one the ranking below cannot answer, and the one a caller has the moment `lint`
778
+ # names a tool that is over.
779
+ try:
780
+ one = detail(config, args.tools)
781
+ except Withheld as withheld:
782
+ # The one refusal here with a remedy (RK1360): the tool exists and this project is
783
+ # not sent it, so the answer is the `declare` that changes that and never the
784
+ # ranking, which is a list this verb is correctly absent from.
785
+ print(f"roadkeep: refused: {withheld}", file=sys.stderr)
786
+ return EXIT_USAGE
787
+ except KeyError:
788
+ print(
789
+ f"roadkeep: refused: {args.tools!r} is not a tool this project serves — "
790
+ f"`{invocation()} cost --tools` ranks every one, and `--json` lists them",
791
+ file=sys.stderr,
792
+ )
793
+ return EXIT_USAGE
794
+ if args.json:
795
+ print(json.dumps(one.payload(CHARACTER_UNIT, config.tool_characters), indent=2))
796
+ else:
797
+ print(one.stated(CHARACTER_UNIT, config.tool_characters))
798
+ return EXIT_OK
799
+
800
+ # The same measurement `--session` totals (RK1096), so the ranking and the total cannot
801
+ # come to disagree about what a client is sent.
802
+ sent = surface(config)
803
+
804
+ if args.json:
805
+ print(json.dumps(sent.payload(CHARACTER_UNIT, config.tool_characters, config.tool_session), indent=2))
806
+ else:
807
+ print(sent.stated(
808
+ CHARACTER_UNIT, config.tool_characters, _LARGEST_TOOLS, config.tool_session
809
+ ))
810
+ return EXIT_OK
811
+
812
+
813
+ def _pick(config: Config, args: argparse.Namespace) -> int:
814
+ """The next task this backlog offers, and why that one (RK11).
815
+
816
+ Both registers come off one record (RK1170): the choice, the claim and the event reached this
817
+ handler as three values and were rendered here and in `rendering.py`, so the verb's two
818
+ readings sat in two files and neither was where the choice is made.
819
+ """
820
+ claim: Claim | None = None
821
+ try:
822
+ if args.claim:
823
+ claim = take(config, args.block, args.designed, available=args.have)
824
+ choice = claim.choice
825
+ else:
826
+ choice = pick(config, args.block, args.designed, available=args.have)
827
+ except REFUSALS as error:
828
+ # The whole tuple and not `(KeyError, OSError)`: with `--claim` this command writes a
829
+ # marker, so every refusal that guards a marker — a stale file, a sibling stating
830
+ # status — reaches here, and a traceback is what the caller would otherwise read.
831
+ return _refused(error)
832
+
833
+ answer = Picked(
834
+ config=config, choice=choice, claim=claim, event=_claim_event(claim, config)
835
+ )
836
+ print(json.dumps(answer.payload(), indent=2) if args.json else answer)
837
+ return EXIT_OK
838
+
839
+
840
+ def _export(config: Config, args: argparse.Namespace) -> int:
841
+ # One task as a document, which is a different subject and not a fourth destination
842
+ # (RK1362): the backlog projection answers about every line and this answers about one,
843
+ # so composing them would be two documents spliced into one file.
844
+ if args.spec is not None:
845
+ try:
846
+ print(spec(config, args.spec).markdown(), end="")
847
+ except (KeyError, ValueError) as error:
848
+ return _refused(error)
849
+ return EXIT_OK
850
+ # Both destinations in one run: a README and a page that restate the same backlog have
851
+ # to be refreshed by the same call, or the one nobody remembered is the stale one —
852
+ # which is the whole symptom RK39 names, and it named the site too.
853
+ chosen: list[tuple[str, str | None]] = [
854
+ (flag, name)
855
+ for flag, name in (("readme", args.readme), ("site", args.site))
856
+ if name is not None
857
+ ]
858
+ if args.contents:
859
+ # No path of its own (RK1110): the target is the project's `[files]` rationale file, so
860
+ # a path here would be a second answer to a question the config already answers —
861
+ # `None` is what sends `splice_into` through the resolver the gate reads too.
862
+ chosen.append(("contents", None))
863
+ try:
864
+ projection = project(config)
865
+ if not chosen:
866
+ print(projection.json() if args.json else projection.markdown())
867
+ return EXIT_OK
868
+ planned = [splice_into(config, projection, flag, name) for flag, name in chosen]
869
+ # Both targets or neither (RK187, RK6): the splice is planned per file and the
870
+ # writes are made together, so a README refreshed beside a site refused is a state
871
+ # the command cannot leave — and the re-run it advises meets a whole tree.
872
+ write_all(*[write for write, _ in planned if write is not None])
873
+ except (KeyError, ValueError, OSError, StaleFile) as error:
874
+ return _refused(error)
875
+
876
+ for _, line in planned:
877
+ print(line)
878
+ return EXIT_OK
879
+
880
+
881
+ def _gaps(config: Config, args: argparse.Namespace) -> int:
882
+ """Which ids below the highest no file carries, and what became of each (RK39, RK95).
883
+
884
+ Both registers come off one result (RK1170): `Gapped` renders them beside the reading that
885
+ found the gaps, so the collapsed rows the printed answer shows and the per-id list the payload
886
+ carries are two readings of one thing rather than two functions two files apart.
887
+ """
888
+ answer = Gapped(gaps=gaps(config))
889
+ print(json.dumps(answer.payload(), indent=2) if args.json else answer)
890
+ return EXIT_OK
891
+
892
+
893
+ def _govern(config: Config, args: argparse.Namespace) -> int:
894
+ """A governed number, read and then declared in the same call (RK1272).
895
+
896
+ The read alone where no value is passed, which is the half that already existed under four
897
+ other verbs and nowhere near the declaration. Writes and so is not `reads_only`.
898
+ """
899
+ from roadkeep.governing import govern, reading # noqa: PLC0415 - RK260
900
+
901
+ try:
902
+ if args.at is None:
903
+ found = reading(config, args.key, file=args.file or "", role=args.role or "")
904
+ print(json.dumps(_reading_json(found), indent=2) if args.json else found.stated())
905
+ return EXIT_OK
906
+ written = govern(
907
+ config,
908
+ args.key,
909
+ args.at,
910
+ file=args.file or "",
911
+ role=args.role or "",
912
+ because=args.because or "",
913
+ instead=args.instead or "",
914
+ )
915
+ except REFUSALS as error:
916
+ return _refused(error)
917
+
918
+ if args.json:
919
+ print(json.dumps(written.payload(config), indent=2))
920
+ else:
921
+ print(written.stated(config))
922
+ return EXIT_OK
923
+
924
+
925
+ def _reading_json(found) -> dict:
926
+ """The measurement alone, shaped as the write's own `reading` block is (RK1272)."""
927
+ return {
928
+ "address": found.address,
929
+ "unit": found.unit,
930
+ "sites": found.sites,
931
+ "worst": found.worst,
932
+ "where": found.where,
933
+ "declared": found.declared,
934
+ # Beside it in both registers (RK1343): a consumer reading `declared: null` cannot
935
+ # tell a key this build falls back on from one nothing holds, and the two are the
936
+ # difference between a lenient gate and no gate.
937
+ "default": found.default,
938
+ "unmeasured": found.unmeasured or None,
939
+ "because": list(found.because),
940
+ }
941
+
942
+
943
+ def _config_shape(config: Config, args: argparse.Namespace) -> int:
944
+ """What `roadkeep.toml` may declare, and what this project did (RK1270).
945
+
946
+ Never refused over the project's *state* — a tree with no config at all is answered, that
947
+ being the caller who most needs the list — and refused over the **argument**, a table name
948
+ this build does not have being a typo rather than a table somebody has yet to declare.
949
+ """
950
+ from roadkeep.describing import payload, shape, stated # noqa: PLC0415 - RK260
951
+
952
+ try:
953
+ # Straight through, and the default is `None` rather than `""` for exactly one
954
+ # reason: the top level's own name *is* the empty string, so a default of `""` would
955
+ # make `--table ""` unaskable — the one table a reader starts from.
956
+ found = shape(config, args.table)
957
+ except KeyError as error:
958
+ return _refused(error)
959
+
960
+ if args.json:
961
+ print(json.dumps(payload(found), indent=2))
962
+ else:
963
+ print(stated(found))
964
+ return EXIT_OK
965
+
966
+
967
+ def _commands(config: Config, args: argparse.Namespace) -> int:
968
+ """What this build's command line takes, as data rather than as terminal text (RK1401).
969
+
970
+ `_config_shape`'s twin, and refused the same way: never over the project's *state* — a
971
+ tree with no config at all is answered, that being the reader deciding whether to adopt —
972
+ and refused over the **argument**, a verb this build does not have being a typo rather
973
+ than one somebody has yet to install.
974
+ """
975
+ from roadkeep.commanding import commands, payload, stated # noqa: PLC0415 - RK260
976
+
977
+ try:
978
+ found = commands(config, args.command)
979
+ except KeyError as error:
980
+ return _refused(error)
981
+
982
+ if args.json:
983
+ print(json.dumps(payload(found), indent=2))
984
+ else:
985
+ print(stated(found))
986
+ return EXIT_OK
987
+
988
+
989
+ def _anchors(config: Config, args: argparse.Namespace) -> int:
990
+ """Live and retired addresses across this project's prose (RK247, RK297).
991
+
992
+ Four readings off one record (RK1170) — the wide report and its payload, and the free
993
+ address alone in each register. What stays here is the three **argv** refusals: which
994
+ prose file, which of two narrowings, and a block whose lines point nowhere. Those are
995
+ about the call and not about the answer, which is why they never reached the record.
996
+ """
997
+ # Every declared role unless one is named. `--role` narrows the *listing* and never the
998
+ # free address, which is computed per namespace (RK340, RK346): where no `[refs]` declares
999
+ # one, both files number into the same namespace and a `next` taken from one of them is
1000
+ # the answer this read exists to stop somebody acting on (RK297); where one is declared,
1001
+ # the row for that namespace is that file's own and the sibling's is not an answer about
1002
+ # it. Reading every role either way is what makes `doubled` visible before a pick (RK383).
1003
+ asked = [one for one in PROSE_ROLES if config.has(one)]
1004
+ role = args.role or ""
1005
+ if (role and not config.has(role)) or not asked:
1006
+ print(
1007
+ f"roadkeep: this project declares no {role or 'prose'} file "
1008
+ f"({', '.join(PROSE_ROLES)} is what an anchor lives in)",
1009
+ file=sys.stderr,
1010
+ )
1011
+ return EXIT_USAGE
1012
+ # The block a caller knows, resolved to the family they do not (RK312): under an outline
1013
+ # the prose file declares no block heading, so which numeral a block's designs sit under
1014
+ # is written nowhere and used to be globbed out of the pointers by hand.
1015
+ block = args.block or ""
1016
+ if block and args.family:
1017
+ print(
1018
+ "roadkeep: --block resolves to a family, so passing both asks two questions: "
1019
+ f"`{invocation()} anchors --block {block}` names the families, and "
1020
+ f"`{invocation()} anchors --family <one of them>` narrows to it",
1021
+ file=sys.stderr,
1022
+ )
1023
+ return EXIT_USAGE
1024
+ spans: tuple[str, ...] = ()
1025
+ if block:
1026
+ spans = families_of_block(config, block)
1027
+ if not spans:
1028
+ print(
1029
+ f"roadkeep: no open line in Block {block} carries a pointer, so nothing "
1030
+ f"says which family its prose lives under — `anchors` alone lists every "
1031
+ f"top-level, and its next free one is where a new block starts",
1032
+ file=sys.stderr,
1033
+ )
1034
+ return EXIT_USAGE
1035
+ if len(spans) == 1:
1036
+ args.family = spans[0]
1037
+
1038
+ found = Addresses.of(
1039
+ config, role, args.family or "", [role] if role else asked, block, spans
1040
+ )
1041
+ if args.only_next:
1042
+ if args.json:
1043
+ print(json.dumps(found.free_payload(), indent=2))
1044
+ return EXIT_OK
1045
+ out, notes = found.freely()
1046
+ if not out:
1047
+ # The one refusal the narrow read has of its own: an empty stdout here reads as a
1048
+ # command that failed quietly, and this form exists to be captured.
1049
+ #
1050
+ # **Both spellings, because the first address chooses the system** (RK1211). This
1051
+ # named `I.1` by hand, on the one file with no family to read a system off — which
1052
+ # is exactly why `next_family` answers None here at all. So one half of the command
1053
+ # declined to guess and the other half guessed, and following the guess made the
1054
+ # file this tool then cannot read: measured on a project holding `1` and `1.1`,
1055
+ # offered `I.1`, which took its top levels to `1` and `I` — two systems tying at 1,
1056
+ # RK1210's nondeterminism, entered through a message that never mentions it.
1057
+ #
1058
+ # Naming both is what shows the choice exists. Naming one keeps a decision that is
1059
+ # the author's (L4, L6): a project outlining `1`, `2`, `3` is as ordinary as one
1060
+ # outlining `I`, `II`, `III`, and every address after the first is spelled the way
1061
+ # the first one was.
1062
+ print(
1063
+ "roadkeep: no outline family exists yet, so none is spent — the first "
1064
+ "address decides the system every address after it is spelled in, and that "
1065
+ "is yours: `add --ref I.1` or `add --ref 1.1`, whichever this project "
1066
+ "numbers in",
1067
+ file=sys.stderr,
1068
+ )
1069
+ return EXIT_USAGE
1070
+ print(chr(10).join(out))
1071
+ for note in notes:
1072
+ print(note, file=sys.stderr)
1073
+ return EXIT_OK
1074
+
1075
+ if args.json:
1076
+ print(json.dumps(found.payload(config, args.claims), indent=2))
1077
+ else:
1078
+ print(found.stated(config, args.claims))
1079
+ return EXIT_OK
1080
+
1081
+
1082
+ def _deps(config: Config, args: argparse.Namespace) -> int:
1083
+ try:
1084
+ backlog = Backlog.load(config)
1085
+ except (KeyError, OSError) as error:
1086
+ return _refused(error) # a declared file that is not there yet: `init` (RK18)
1087
+ try:
1088
+ found = Dependencies.of(backlog, args.id)
1089
+ except KeyError:
1090
+ # The shared refusal and no longer a second spelling of it (RK1342). `NotOpen` says
1091
+ # of itself that *the sentence has one spelling for every caller that asks*, and
1092
+ # answers three ways — in the changelog, paused with the store's own sentence and the
1093
+ # `resume` that undoes it, or nothing carries the id. This site hand-rolled two of
1094
+ # them, so the pause RK1213 taught that class to name was the one case it could not:
1095
+ # a sentence with two writers agrees until one of them grows a case.
1096
+ return _refused(
1097
+ NotOpen(
1098
+ args.id,
1099
+ config.relative(config.path("roadmap")),
1100
+ Whereabouts.of(config, args.id),
1101
+ )
1102
+ )
1103
+
1104
+ if args.json:
1105
+ print(json.dumps(found.payload(), indent=2))
1106
+ else:
1107
+ print(found.stated())
1108
+ return EXIT_OK
1109
+
1110
+
1111
+ def _origin(config: Config, args: argparse.Namespace) -> int:
1112
+ if args.id.startswith("§"):
1113
+ return _cited(config, args)
1114
+ try:
1115
+ origin = origin_of(config, args.id)
1116
+ except HistoryUnavailable as error:
1117
+ print(f"roadkeep: no history to resolve against ({error})", file=sys.stderr)
1118
+ return EXIT_USAGE
1119
+
1120
+ if args.json:
1121
+ print(json.dumps({"id": origin.task_id, **_commits_json(origin)}, indent=2))
1122
+ return EXIT_OK
1123
+
1124
+ if origin.proposed_in is None and origin.shipped_in is None:
1125
+ print(f"{args.id}: nothing in history mentions it yet")
1126
+ return EXIT_OK
1127
+ for label, commit in (("proposed", origin.proposed_in), ("shipped", origin.shipped_in)):
1128
+ if commit is None:
1129
+ print(f" {label:<9} —")
1130
+ continue
1131
+ print(f" {label:<9} {commit.short} {commit.date[:10]} {commit.subject}")
1132
+ if args.why and origin.shipped_in is not None:
1133
+ print()
1134
+ print(origin.shipped_in.reasoning)
1135
+ return EXIT_OK
1136
+
1137
+
1138
+ def _cited(config: Config, args: argparse.Namespace) -> int:
1139
+ """Where the design behind a dangling citation went (RK212).
1140
+
1141
+ `ship` names the sections left citing what it deleted (RK206), which serves the author
1142
+ at the moment of the write. This serves the reader who meets `§XVIII.12` a year later:
1143
+ the files hold no answer, because `as_ledger` keeps no pointer, so a citation of a
1144
+ shipped design and a typo read exactly alike.
1145
+
1146
+ A question and not a check, decided by counting: 37 such references across this
1147
+ repository, claude-tray, Shio and Turing, of which 36 are in outline projects whose
1148
+ anchor carries no id at all. A finding would fail four files whose prose is correct;
1149
+ 28 notes in one Turing report would be output nobody reads. So it costs nothing until
1150
+ somebody meets the reference and asks (L5).
1151
+ """
1152
+ anchor = args.id.lstrip("§")
1153
+ found = cited_origin(config, anchor)
1154
+ # Both registers off the record (RK1170), and the role spelled by this project (RK75): the
1155
+ # answer is `Cited`'s, and what the printed one needs beyond the fact is the file's name.
1156
+ where = config.relative(config.path(found.role)) if config.has(found.role) else found.role
1157
+ if args.json:
1158
+ print(json.dumps(found.payload(), indent=2))
1159
+ else:
1160
+ print(found.stated(where, why=args.why))
1161
+ return EXIT_OK
1162
+
1163
+
1164
+ def _weight(config: Config, args: argparse.Namespace) -> int:
1165
+ """Print what comparable tasks cost (RK71). Numbers only — the judgement is the author's.
1166
+
1167
+ No advice line: what a spread means for the line being written is an editorial call, and
1168
+ a tool that phrased it would be writing the reasoning it exists not to write (L4).
1169
+
1170
+ Both registers come off one result (RK1170): this verb was the shape the task measured — the
1171
+ plain answer spelled here and its payload in `rendering.py`, one verb's two readings two files
1172
+ apart, with neither file holding both. `Weighed` is that result, beside the numbers it is
1173
+ derived from, and what is left here is the door: run it, and say which register was asked for.
1174
+ """
1175
+ try:
1176
+ weights = weigh(config, args.block)
1177
+ except HistoryUnavailable as error:
1178
+ print(f"roadkeep: no history to weigh against ({error})", file=sys.stderr)
1179
+ return EXIT_USAGE
1180
+ except (KeyError, OSError) as error:
1181
+ return _refused(error)
1182
+
1183
+ answer = Weighed(
1184
+ where=config.relative(config.path("changelog")),
1185
+ weights=weights,
1186
+ records=args.records,
1187
+ )
1188
+ print(json.dumps(answer.payload(), indent=2) if args.json else answer)
1189
+ return EXIT_OK
1190
+
1191
+
1192
+ def _remaining(config: Config, args: argparse.Namespace) -> int:
1193
+ """Run the query a task's own design declares, against this tree, now (RK492).
1194
+
1195
+ A read in the strict sense: nothing is written, nothing is cached, and the exit code says
1196
+ the call was answered rather than what the answer was. A migration with sites left is not
1197
+ a failing gate — `lint` is what refuses — and a `remaining` that exited 1 while work was
1198
+ outstanding would be a verb nobody could put in a loop.
1199
+ """
1200
+ try:
1201
+ view = show(config, args.id)
1202
+ except (KeyError, OSError) as error:
1203
+ return _refused(error)
1204
+ if view.section is None:
1205
+ # The pointer's own failure, in the words `show` already composed for it: a task with
1206
+ # no design has no query, and which of the four absences it is matters to the repair.
1207
+ print(f"roadkeep: {args.id} has no section: {view.section_absence}", file=sys.stderr)
1208
+ return EXIT_USAGE
1209
+ try:
1210
+ clauses = declared(view.section.body)
1211
+ except QueryError as error:
1212
+ return _refused(error)
1213
+ if not clauses:
1214
+ # An answer and not a refusal: *this design declares no query* is a fact about the
1215
+ # task, and a read that refused it would be read as evidence the id was wrong. The
1216
+ # grammar is named, because the next thing a caller wants is to write one.
1217
+ if args.json:
1218
+ print(json.dumps({"id": args.id, "query": [], "total": None}, indent=2))
1219
+ else:
1220
+ print(
1221
+ f"{args.id} declares no query: a `roadkeep-remaining` fenced block in "
1222
+ f"§{view.entry.task.ref or args.id}, one `<pathspec> :: <regex>` per line"
1223
+ )
1224
+ return EXIT_OK
1225
+ found = count(config.root, args.id, clauses)
1226
+ print(json.dumps(found.payload(), indent=2) if args.json else str(found))
1227
+ return EXIT_OK
1228
+
1229
+
1230
+
1231
+ def _unclosed(config: Config, args: argparse.Namespace) -> int:
1232
+ """Open lines the history already speaks for (RK1201). Nothing here fails, so exit 0.
1233
+
1234
+ Both registers come off one record (RK1170), and the exit code is not one of them: a
1235
+ commit naming an id is not evidence the work is done, so a non-zero here would fail every
1236
+ session that is mid-task — which is the shape a report must not take.
1237
+ """
1238
+ try:
1239
+ answer = Unclosed(rows=pending(config))
1240
+ except (KeyError, OSError) as error:
1241
+ return _refused(error)
1242
+
1243
+ if args.json:
1244
+ print(json.dumps(answer.payload(), indent=2))
1245
+ else:
1246
+ print(answer.stated())
1247
+ return EXIT_OK
1248
+
1249
+
1250
+
1251
+ def _evidence(config: Config, args: argparse.Namespace) -> int:
1252
+ """What a task's own design says would prove it done, counted now (RK1184).
1253
+
1254
+ `remaining` with the sign flipped, and the same read: sites that must **exist** rather
1255
+ than sites still there. Never a verdict — the pattern is the author's claim and the count
1256
+ is the answer, so `0` says the evidence is not there yet and whether that is the work
1257
+ being done is the caller's judgement (L4).
1258
+
1259
+ The exit code says the call was answered and never what the answer was, for `remaining`'s
1260
+ reason: a criterion unmet is work outstanding, which is not a failing gate.
1261
+ """
1262
+ try:
1263
+ view = show(config, args.id)
1264
+ except (KeyError, OSError) as error:
1265
+ return _refused(error)
1266
+ if view.section is None:
1267
+ print(f"roadkeep: {args.id} has no section: {view.section_absence}", file=sys.stderr)
1268
+ return EXIT_USAGE
1269
+ try:
1270
+ clauses = declared(view.section.body, EVIDENCE)
1271
+ except QueryError as error:
1272
+ return _refused(error)
1273
+ if not clauses:
1274
+ # An answer and not a refusal, exactly as `remaining` reads an absent query: *this
1275
+ # design declares no criterion* is a fact about the task, and the grammar is named
1276
+ # because writing one is the next thing a caller wants.
1277
+ if args.json:
1278
+ print(json.dumps({"id": args.id, "kind": EVIDENCE, "query": [], "total": None}, indent=2))
1279
+ else:
1280
+ print(
1281
+ f"{args.id} declares no criterion: a `{EVIDENCE}` fenced block in "
1282
+ f"§{view.entry.task.ref or args.id}, one `<pathspec> :: <regex>` per line"
1283
+ )
1284
+ return EXIT_OK
1285
+ found = count(config.root, args.id, clauses, EVIDENCE)
1286
+ print(json.dumps(found.payload(), indent=2) if args.json else str(found))
1287
+ return EXIT_OK
1288
+
1289
+
1290
+ def declare_reads(subcommands: argparse._SubParsersAction) -> None:
1291
+ """This module's verbs, declared where their handlers are (RK1171).
1292
+
1293
+ `build_parser` called forty-nine blocks like these in a row; what it calls now is an index
1294
+ over the modules that own them. The move is what RK1169 and RK1170 bought: the flags a verb
1295
+ declares, the reasons it withholds and the record it answers with are one file's, so a
1296
+ change to any of them is one file's too.
1297
+
1298
+ The order inside is `build_parser`'s own, which is where these blocks sat.
1299
+ """
1300
+ list_parser = subcommands.add_parser(
1301
+ "list",
1302
+ help="the task lines, filtered, printed verbatim",
1303
+ description=(
1304
+ "Print the lines a filter selects, exactly as the file spells them. A "
1305
+ "marker-bearing line the grammar did not accept is reported on stderr with "
1306
+ "the count, so a filtered listing can never look complete when it is not."
1307
+ ),
1308
+ )
1309
+ _counting_flags(list_parser)
1310
+ _marker_flag(list_parser, "only this status marker", dest="marker")
1311
+ list_parser.add_argument(
1312
+ "--ids", action="store_true", help="print ids alone, one per line"
1313
+ )
1314
+ withheld(
1315
+ list_parser,
1316
+ ids='how a terminal prints: the payload carries every id in `tasks`, so a caller over this transport already has what the flag composes',
1317
+ )
1318
+ list_parser.set_defaults(handler=_list, reads_only=True)
1319
+ # Two output *forms* of one read are two answers, exactly as `budget`'s subjects are
1320
+ # (RK465's rule, RK467's find): the payload came back whole with nothing said about the
1321
+ # flag that shaped nothing.
1322
+ answers(list_parser, ("ids", "the listing as bare ids"), ("json", "the payload"))
1323
+
1324
+ stats_parser = subcommands.add_parser(
1325
+ "stats",
1326
+ help="counts per block and per marker, with what was not counted",
1327
+ description=(
1328
+ "Count the file. Every count carries the number of marker-bearing lines it "
1329
+ "could *not* read, printed even when it is zero: a grep reports the "
1330
+ "remainder with no indication that anything is missing."
1331
+ ),
1332
+ )
1333
+ _counting_flags(stats_parser)
1334
+ stats_parser.set_defaults(handler=_stats, reads_only=True)
1335
+
1336
+ audit_parser = subcommands.add_parser(
1337
+ "audit",
1338
+ help="every marker-bearing line the count did not count, and why",
1339
+ description=(
1340
+ "Print the misses. This is what makes a count trustable rather than an "
1341
+ "extra: exit stays 0, because reporting is not the gate (`lint`, RK14) — "
1342
+ "an audit that failed a build would be a gate nobody could adopt first."
1343
+ ),
1344
+ )
1345
+ _counting_flags(audit_parser)
1346
+ audit_parser.set_defaults(handler=_audit, reads_only=True)
1347
+
1348
+ claims_parser = subcommands.add_parser(
1349
+ "claims",
1350
+ help="which lines a worker is holding, oldest first, and where that is recorded",
1351
+ description=(
1352
+ "List the claim registry against the roadmap: held, expired — stepped over, so "
1353
+ "the line is offered again — or stale, meaning the marker moved and nothing "
1354
+ "reads the entry. Ranks nothing and offers nothing: `pick` decides what to work "
1355
+ "on, and the release is a marker."
1356
+ ),
1357
+ )
1358
+ claims_parser.add_argument(
1359
+ "--prune",
1360
+ action="store_true",
1361
+ help=(
1362
+ "drop the rows that are not claims and keep the ones that are, which is the "
1363
+ "reconciliation a marker write performs and the only other remedy is the file"
1364
+ ),
1365
+ )
1366
+ claims_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1367
+ # A read that can write, so it declares which flag makes it one (RK167): `dispatch` keeps
1368
+ # deciding the lock, and reading the registry never waits on one.
1369
+ withheld(
1370
+ claims_parser,
1371
+ prune='it writes the registry, exactly as `lint --fix` writes the files (RK16)',
1372
+ )
1373
+ claims_parser.set_defaults(handler=_claims, reads_only=True, writes_when="prune")
1374
+
1375
+ claim_parser = subcommands.add_parser(
1376
+ "claim",
1377
+ help="the paths one held line's commit owns, declared once and answered on demand",
1378
+ description=(
1379
+ "Say which paths this task will touch, and read them back at the moment of "
1380
+ "committing. Without --path it answers what was declared, plus what the tree "
1381
+ "holds that another live claim says is its own — the analysis `git add -A` "
1382
+ "cannot make. Declared verbatim: nothing here reads the disk or the task's "
1383
+ "prose to guess a path, and nothing here dates a claim."
1384
+ ),
1385
+ )
1386
+ claim_parser.add_argument("id", help="the task id, which a live claim must already hold")
1387
+ claim_parser.add_argument(
1388
+ "--path",
1389
+ action="append",
1390
+ default=[],
1391
+ metavar="PATH",
1392
+ help=(
1393
+ "a path this task's commit owns, repeatable; replaces the whole scope, so a "
1394
+ "correction is one call and not a file to edit"
1395
+ ),
1396
+ )
1397
+ claim_parser.add_argument(
1398
+ "--add-path",
1399
+ action="append",
1400
+ default=[],
1401
+ metavar="PATH",
1402
+ dest="add_path",
1403
+ help=(
1404
+ "a path this task's commit *also* owns, repeatable; keeps what was declared, so "
1405
+ "a file the work turned up is one argument and not the whole scope again"
1406
+ ),
1407
+ )
1408
+ claim_parser.add_argument(
1409
+ "--porcelain",
1410
+ action="store_true",
1411
+ help="the paths alone, one per line — what a commit script feeds to `git add --`",
1412
+ )
1413
+ claim_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1414
+ # A read that can write, declared the way `claims --prune` declares it (RK167) — and by
1415
+ # two arguments (RK307), because either of them is the write.
1416
+ withheld(
1417
+ claim_parser,
1418
+ porcelain='how a terminal prints, for a caller that is already reading JSON',
1419
+ )
1420
+ claim_parser.set_defaults(
1421
+ handler=_claim,
1422
+ reads_only=True,
1423
+ writes_when=("path", "add_path"),
1424
+ # The second pair, found by the read RK339 asked for: same one-edit distance, same
1425
+ # asymmetry, and the same verb typed wanting the listing.
1426
+ twin=(
1427
+ "claim reads one line's scope back and needs it: `claim <id>`, or "
1428
+ "`claim <id> --path …` to declare what this commit owns. The registry "
1429
+ "listing is `claims`, which needs no id"
1430
+ ),
1431
+ )
1432
+ # The sixth pair, and the first one the *declaration* found rather than a sweep (RK489):
1433
+ # `--porcelain` returned before `--json` was read, so a caller asking for the payload got
1434
+ # the paths, byte for byte. RK467's sweep could never see it — it runs against a fixture
1435
+ # with no live claim, where every `claim` pair exits 2 for want of one — which is the
1436
+ # limit of finding a class by probing, one probe away from the class being declarable.
1437
+ answers(
1438
+ claim_parser,
1439
+ ("porcelain", "the paths alone, for `git add --`"),
1440
+ ("json", "the payload"),
1441
+ )
1442
+
1443
+ writes_parser = subcommands.add_parser(
1444
+ "writes",
1445
+ help="which governed files a verb wrote, which nothing did, and where that is recorded",
1446
+ description=(
1447
+ "Read the write record against the files: attested — the bytes a verb left — "
1448
+ "unattested, meaning something else produced them, or unrecorded, meaning no "
1449
+ "verb has run here yet. Moves no baseline, so asking twice answers twice; the "
1450
+ "`Stop` hook states it once and consumes it (RK175)."
1451
+ ),
1452
+ )
1453
+ writes_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1454
+ # Never a write, not even behind a flag: re-baselining is what the `Stop` block does, and a
1455
+ # query offering it would be the laundering `dispatch` refuses queries in the first place.
1456
+ writes_parser.set_defaults(handler=_writes, reads_only=True)
1457
+
1458
+ unclosed_parser = subcommands.add_parser(
1459
+ "unclosed",
1460
+ help="open lines whose work the history already names, and what closes each",
1461
+ description=(
1462
+ "Which open lines already have commits naming them, and no ledger entry. A "
1463
+ "session that shipped the code and forgot the line leaves a state `gaps` "
1464
+ "cannot see — that verb explains an id in neither file, and this one is in "
1465
+ "the roadmap — and `origin` answers one id at a time, so it is a confirmation "
1466
+ "and never a discovery. The commit that *filed* each id is dropped: `add` "
1467
+ "mints the id, so nothing could name one before the line existed. A report "
1468
+ "and never a gate: work under way is exactly this shape, and what a partial "
1469
+ "landing wants is `ship --part`."
1470
+ ),
1471
+ )
1472
+ unclosed_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1473
+ unclosed_parser.set_defaults(handler=_unclosed, reads_only=True)
1474
+
1475
+ brief_parser = subcommands.add_parser(
1476
+ "brief",
1477
+ help="everything it costs to start one task, in one call",
1478
+ description=(
1479
+ "Compose the line, its rationale, its resolved deps, the blocker chain, what "
1480
+ "shipping it unblocks and the non-goals that bind it. With no id, briefs "
1481
+ "whatever `pick` would choose, which makes the first call the only one."
1482
+ ),
1483
+ )
1484
+ brief_parser.add_argument(
1485
+ "id", nargs="?", help="the task; omitted, `pick` chooses it"
1486
+ )
1487
+ brief_parser.add_argument(
1488
+ "--block", help="scope the pick to one block, e.g. C (only without an id)"
1489
+ )
1490
+ brief_parser.add_argument(
1491
+ "--designed",
1492
+ action="store_true",
1493
+ help=_DESIGNED_HELP,
1494
+ )
1495
+ brief_parser.add_argument(
1496
+ "--have",
1497
+ action="append",
1498
+ default=[],
1499
+ metavar="REQUIREMENT",
1500
+ help=_HAVE_HELP,
1501
+ )
1502
+ brief_parser.add_argument(
1503
+ "--claim",
1504
+ action="store_true",
1505
+ help=(
1506
+ "take the line as well as describing it: the marker moves to in-progress in the "
1507
+ "same transaction, and a named id another worker holds is refused"
1508
+ ),
1509
+ )
1510
+ brief_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1511
+ withheld(
1512
+ brief_parser,
1513
+ claim='it writes, and a read that writes is a read a caller stops making freely (L5) — so the writing door is a tool of its own with its own hint',
1514
+ )
1515
+ brief_parser.set_defaults(handler=_brief, reads_only=True, writes_when="claim")
1516
+
1517
+ budget_parser = subcommands.add_parser(
1518
+ "budget",
1519
+ help="how many characters a line has left for prose, before one is written",
1520
+ description=(
1521
+ "Report what a line leaves its prose fields, derived from the id, the marker, "
1522
+ "the deps and the pointer — all known before the first word. The drafts "
1523
+ "(--symptom, --why, --body) are measured, never composed, and exit 1 when "
1524
+ "over: the refusal, without the write."
1525
+ ),
1526
+ )
1527
+ budget_parser.add_argument(
1528
+ "id",
1529
+ nargs="?",
1530
+ help="an existing line, e.g. RK12 — omitted, the line `add` would write next",
1531
+ )
1532
+ budget_parser.add_argument(
1533
+ "--block", default="", help="the block the line would be filed under, e.g. B"
1534
+ )
1535
+ budget_parser.add_argument(
1536
+ "--dep",
1537
+ action="append",
1538
+ default=[],
1539
+ dest="deps",
1540
+ metavar="DEP",
1541
+ help="a dep the line would carry, repeatable: the group is what moves the number",
1542
+ )
1543
+ _marker_flag(
1544
+ budget_parser, "the marker the line would carry (default: the first declared)"
1545
+ )
1546
+ budget_parser.add_argument(
1547
+ "--symptom",
1548
+ default="",
1549
+ help="the symptom, drafted or written: what it takes is what the why loses",
1550
+ )
1551
+ # The draft, at the door that already states the allowance (RK1190). Measured and never
1552
+ # composed: a `why` twice its limit is a number here and a refusal on `add`, and that
1553
+ # difference is the whole reason this argument exists rather than a `--dry-run`.
1554
+ budget_parser.add_argument(
1555
+ "--why",
1556
+ help=(
1557
+ "a draft of the why, measured against its allowance instead of refused by it"
1558
+ + _PIPE
1559
+ ),
1560
+ )
1561
+ budget_parser.add_argument(
1562
+ "--prefix",
1563
+ dest="family",
1564
+ help="count the derived id in this track (default: the first declared)",
1565
+ )
1566
+ budget_parser.add_argument(
1567
+ "--ref",
1568
+ help=(
1569
+ "the anchor the line would point at, for ref_scheme = 'outline' only: the "
1570
+ "pointer is structure, so unnamed the budget assumes the widest on file"
1571
+ ),
1572
+ )
1573
+ # The other two prose limits, at the same door and never as a `--dry-run` (RK283): both
1574
+ # are facts about the file and the role, so both are answerable with no prose in hand.
1575
+ budget_parser.add_argument(
1576
+ "--anchor",
1577
+ metavar="ANCHOR",
1578
+ help="a section, e.g. RK12: what its body may say in words, and what it spends",
1579
+ )
1580
+ budget_parser.add_argument(
1581
+ "--role",
1582
+ choices=PROSE_ROLES,
1583
+ help="which prose file --anchor is priced against (default: the one holding it)",
1584
+ )
1585
+ # The section's own draft, beside the field's (RK1190). Two flags rather than one, for
1586
+ # `section add`'s reason (RK381): a body is the longest thing an author composes, and a
1587
+ # path is what a caller reaches for when the prose will not fit in a shell argument.
1588
+ budget_parser.add_argument(
1589
+ "--body",
1590
+ help="a draft body: what it costs the section this call is about" + _PIPE,
1591
+ )
1592
+ budget_parser.add_argument(
1593
+ "--body-file",
1594
+ dest="body_file",
1595
+ metavar="PATH",
1596
+ help="read the draft body from a file instead, with --anchor",
1597
+ )
1598
+ # The third write off the same line (RK1305), and the one this read did not answer for: a
1599
+ # retirement's reason shares the ledger's limit with a derived prefix, so the usable
1600
+ # maximum is neither the published one nor the one a ship is quoted. A value and not a
1601
+ # flag, for `--tools`' reason: bare is the abandonment and named is the supersession, which
1602
+ # spends more of the field before the author starts.
1603
+ budget_parser.add_argument(
1604
+ "--retire",
1605
+ nargs="?",
1606
+ const="",
1607
+ metavar="SUPERSEDED_BY",
1608
+ help=(
1609
+ "what a retirement's reason has — bare, abandoned; named, superseded by that "
1610
+ "id, which costs more of the field"
1611
+ ),
1612
+ )
1613
+ budget_parser.add_argument(
1614
+ "--non-goal",
1615
+ dest="non_goal",
1616
+ action="store_true",
1617
+ help="the two limits `non-goal add` enforces, which are the list's own",
1618
+ )
1619
+ budget_parser.add_argument(
1620
+ "--lead",
1621
+ help="a non-goal that exists, with --non-goal: what its reason has left",
1622
+ )
1623
+ # The fourth subject, and the one limit this format holds that had no pre-write read
1624
+ # (RK345): every other budget is derived from a line, and this one from the file on disk.
1625
+ budget_parser.add_argument(
1626
+ "--file",
1627
+ nargs="?",
1628
+ const="",
1629
+ metavar="PATH",
1630
+ help=(
1631
+ "an every-turn file `[budgets]` declares, e.g. agents.md: what it costs and "
1632
+ "what is left — bare, every declared budget"
1633
+ ),
1634
+ )
1635
+ budget_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1636
+ withheld(
1637
+ budget_parser,
1638
+ family="`add`'s reason read back: the answer is about the id this project would issue next, and a prefix typed here asks about one it would not",
1639
+ body_file="this read exists because a refusal over the transport costs the whole payload again, and the three verbs that write a body now take a path (RK1260), which is refused for the corrected field alone — so the draft still worth pricing here is the one that arrived in the call",
1640
+ )
1641
+ # Declared although this verb writes nothing (RK1260). `reads_stdin` is not about the
1642
+ # write lock: it is what a surface with no pipe reads to refuse `-` by name instead of
1643
+ # measuring a one-character draft and answering about it. Two of the three drafts reach the
1644
+ # pipe — `--symptom` never did, though the description above claimed all three, which is
1645
+ # what the declaration makes checkable.
1646
+ budget_parser.set_defaults(
1647
+ handler=_budget,
1648
+ reads_only=True,
1649
+ reads_stdin=(
1650
+ Prose(dest="why", omitted=False),
1651
+ Prose(dest="body", omitted=False, unless="body_file"),
1652
+ ),
1653
+ )
1654
+ # The subjects this verb keeps (RK283/RK345), declared rather than checked by hand (RK489).
1655
+ # Named rather than inferred from the positional: under the id scheme `RK12` is both a
1656
+ # line and an anchor, and a command that guessed which one was meant would be a budget
1657
+ # the caller has to check before trusting.
1658
+ answers(
1659
+ budget_parser,
1660
+ ("anchor", "one section's prose"),
1661
+ ("non_goal", "the roadmap's other bullet"),
1662
+ ("file", "an every-turn file"),
1663
+ )
1664
+
1665
+ # The other half of what `budget` was (RK1321). Eight subjects under one name made it the
1666
+ # largest served tool — 2,741 against a per-tool ceiling calibrated on `ship` at 2,466 —
1667
+ # so whichever subject arrived last was refused by a limit none of them was about. The
1668
+ # seam is the tense: `budget` says what a write **may** spend before a word exists, and
1669
+ # this says what a surface **does** spend, already, every session.
1670
+ cost_parser = subcommands.add_parser(
1671
+ "cost",
1672
+ help="what this project's surface costs a session, and where",
1673
+ description=(
1674
+ "Report what a caller already pays: the tool list once at connect, the files "
1675
+ "loaded on every turn, and what the read that replaces opening a file costs a "
1676
+ "tool result. `budget` is the other tense — what a write may spend before a "
1677
+ "word of it exists. Reads; never writes."
1678
+ ),
1679
+ )
1680
+ # A value and not a flag (RK1236): bare is the ranking over every tool, and named is the
1681
+ # ranking inside one — the question a caller has the moment the gate names a tool.
1682
+ cost_parser.add_argument(
1683
+ "--tools",
1684
+ nargs="?",
1685
+ const="",
1686
+ metavar="TOOL",
1687
+ help=(
1688
+ "what the tool list costs a session — bare, every tool ranked; named, e.g. "
1689
+ "ship, what each of that one's fields spent"
1690
+ ),
1691
+ )
1692
+ cost_parser.add_argument(
1693
+ "--brief",
1694
+ nargs="?",
1695
+ const="",
1696
+ metavar="ID",
1697
+ help="what a brief costs a tool result — bare, every open line, widest first",
1698
+ )
1699
+ cost_parser.add_argument(
1700
+ "--session",
1701
+ action="store_true",
1702
+ help=(
1703
+ "what one session pays: the served schema once at connect and every "
1704
+ "`[budgets]` file each turn, against the cadence of each"
1705
+ ),
1706
+ )
1707
+ cost_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1708
+ cost_parser.set_defaults(handler=_cost, reads_only=True)
1709
+ answers(
1710
+ cost_parser,
1711
+ ("tools", "what this tool surface costs a session"),
1712
+ ("brief", "what the read that replaces the file costs a tool result"),
1713
+ ("session", "both halves of what a session pays, against their cadences"),
1714
+ )
1715
+ narrows(budget_parser, "role", "anchor")
1716
+ # `--body` is **not** narrowed to `--anchor` (RK1224). It was, and that was the last thing
1717
+ # standing between this verb and one call for a whole `add --section`: the line subject
1718
+ # already reports the section its pointer names (RK301), so a draft body handed to it has
1719
+ # somewhere to be measured — and without that, the transaction `add` validates as one unit
1720
+ # took two reads to price. Measured filing one Shio task: four calls, three of them `why`
1721
+ # overflows of 176, 171 and 170 against 167, each throwing away the 250-word body that
1722
+ # travelled beside it. The field that failed was three characters too long and the payload
1723
+ # re-sent to fix it was two orders of magnitude larger.
1724
+ #
1725
+ # Still refused beside a subject with no section at all — `--file`, `--tools`, `--session`
1726
+ # — which is what `_one_answer` decides from `answers` above, and which is RK465's rule
1727
+ # kept where it applies: a draft measured against nothing is a number the caller misreads.
1728
+ narrows(budget_parser, "lead", "non_goal")
1729
+
1730
+ show_parser = subcommands.add_parser(
1731
+ "show",
1732
+ help="one task: its line, its rationale section and the paths it names",
1733
+ description=(
1734
+ "Join what a task is out of the files that hold a piece of it. Nothing is "
1735
+ "stored to make this possible: the section is found by the pointer, and a "
1736
+ "pointer that resolves to nothing is reported as the absence it is."
1737
+ ),
1738
+ )
1739
+ show_parser.add_argument("id", help="the task, e.g. RK12")
1740
+ show_parser.add_argument(
1741
+ "--no-body",
1742
+ dest="no_body",
1743
+ action="store_true",
1744
+ help="omit the section's prose, keeping the line and where the prose is",
1745
+ )
1746
+ show_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1747
+ show_parser.set_defaults(handler=_show, reads_only=True)
1748
+
1749
+ pick_parser = subcommands.add_parser(
1750
+ "pick",
1751
+ help="the next task to work on, and the reason it was chosen",
1752
+ description=(
1753
+ "Apply three tiers — work already in progress, the declared priority, then "
1754
+ "the lowest ready id — and print which one answered. A task blocked outside "
1755
+ "the backlog is never offered: shipping cannot unblock it."
1756
+ ),
1757
+ )
1758
+ pick_parser.add_argument(
1759
+ "--block",
1760
+ help=(
1761
+ "scope every part of the answer to one block, so 'nothing to pick' is a "
1762
+ "statement about that block and not about a lower id somewhere else"
1763
+ ),
1764
+ )
1765
+ pick_parser.add_argument(
1766
+ "--designed",
1767
+ action="store_true",
1768
+ help=_DESIGNED_HELP,
1769
+ )
1770
+ pick_parser.add_argument(
1771
+ "--have",
1772
+ action="append",
1773
+ default=[],
1774
+ metavar="REQUIREMENT",
1775
+ help=_HAVE_HELP,
1776
+ )
1777
+ pick_parser.add_argument(
1778
+ "--claim",
1779
+ action="store_true",
1780
+ help=(
1781
+ "take the line as well as read it: the marker moves to in-progress in the same "
1782
+ "transaction, so the next caller is answered with something else"
1783
+ ),
1784
+ )
1785
+ pick_parser.add_argument(
1786
+ "--json", action="store_true", help="the pick, the tier and the counts"
1787
+ )
1788
+ # The query it is without `--claim`, and the write it is with one (RK167). `take` still
1789
+ # holds a lock of its own over the answer *and* the marker, that pair being what has to be
1790
+ # indivisible for every caller — re-entrant, so declaring it here costs nothing twice.
1791
+ withheld(
1792
+ pick_parser,
1793
+ claim="`brief`'s reason, and its answer too: the writing door is already served as the `claim` tool, so a second flag here would be a second spelling of it",
1794
+ )
1795
+ pick_parser.set_defaults(handler=_pick, reads_only=True, writes_when="claim")
1796
+
1797
+ export_parser = subcommands.add_parser(
1798
+ "export",
1799
+ help="project the backlog onto a README block, a page, or a JSON payload",
1800
+ description=(
1801
+ "Derive what another file would restate: counts per block and the next ready "
1802
+ "line. Idempotent and stamped with nothing, so a refresh with nothing to say "
1803
+ "makes no diff — and every character of content already passed `add`."
1804
+ ),
1805
+ )
1806
+ export_parser.add_argument(
1807
+ "--readme",
1808
+ nargs="?",
1809
+ const=DEFAULTS["readme"].name,
1810
+ metavar="PATH",
1811
+ help=(
1812
+ f"write the block between the roadkeep markers in this file "
1813
+ f"(default {DEFAULTS['readme'].name})"
1814
+ ),
1815
+ )
1816
+ export_parser.add_argument(
1817
+ "--site",
1818
+ nargs="?",
1819
+ const=DEFAULTS["site"].name,
1820
+ metavar="PATH",
1821
+ help=(
1822
+ f"the same projection as HTML, between the same two markers "
1823
+ f"(default {DEFAULTS['site'].name})"
1824
+ ),
1825
+ )
1826
+ export_parser.add_argument(
1827
+ "--contents",
1828
+ action="store_true",
1829
+ help=(
1830
+ "refresh the table of contents inside this project's rationale file, between the "
1831
+ "same two markers: every row is a heading that file already carries, so a `ship` "
1832
+ "that drops a section leaves the list wrong until this runs. Takes no path — the "
1833
+ "target is `[files]`' own"
1834
+ ),
1835
+ )
1836
+ export_parser.add_argument(
1837
+ "--spec",
1838
+ metavar="ID",
1839
+ help=(
1840
+ "one task as a document: its claim, what it depends on, what would finish it, "
1841
+ "the non-goals that bind it and its design section whole. `brief` is the same "
1842
+ "join bounded to a tool result; this one is bounded by a file, for a reviewer, "
1843
+ "a second agent or a CI job that cannot run the read"
1844
+ ),
1845
+ )
1846
+ export_parser.add_argument(
1847
+ "--json", action="store_true", help="the payload a site build reads"
1848
+ )
1849
+ export_parser.set_defaults(handler=_export)
1850
+ # `--json` is a subject and a destination is a write, so asking for both asks two
1851
+ # questions (RK466). `--readme` and `--site` are not that shape — they are two
1852
+ # destinations of one projection and compose, which RK39 asked for, so they are one
1853
+ # group: the whole reason :class:`Answer` holds a group rather than a flag.
1854
+ answers(
1855
+ export_parser,
1856
+ ("json", "the projection printed"),
1857
+ (("readme", "site"), "the projection written into a file"),
1858
+ # A third subject and not a third destination (RK1362): this one is about one task,
1859
+ # so it answers a different question rather than putting the same answer somewhere
1860
+ # else. `brief <id> --json` is the payload read; this verb's `--json` is the site
1861
+ # build's, and the two are about different documents.
1862
+ ("spec", "one task as a document"),
1863
+ )
1864
+
1865
+ gaps_parser = subcommands.add_parser(
1866
+ "gaps",
1867
+ help="ids in neither file, resolved against the commit that removed them",
1868
+ description=(
1869
+ "Every id below the highest that no line carries. Each resolves to the commit "
1870
+ "whose message holds the decision, to 'never carried' when a complete history "
1871
+ "mentions it nowhere, or to 'unresolvable' when there is no history to search "
1872
+ "— three different answers from 'retired', none of them a weaker one."
1873
+ ),
1874
+ )
1875
+ gaps_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1876
+ gaps_parser.set_defaults(handler=_gaps, reads_only=True)
1877
+
1878
+ govern_parser = subcommands.add_parser(
1879
+ "govern",
1880
+ help="declare one number roadkeep.toml governs, against the reading that decides it",
1881
+ description=(
1882
+ "Take the reading and write the number in one call. `[limits]`, `[budgets]`, "
1883
+ "`[tools]` and `[claims]` hold the values that are a judgement about a figure, "
1884
+ "and each already had the read that decides it somewhere else. With no value it "
1885
+ "prints the reading alone. A limit this project already breaks is refused rather "
1886
+ "than written. Why this number and not the next is yours to write and this "
1887
+ "verb's to place: `--because` stacks your sentence above the key, and `--instead` "
1888
+ "replaces the argument standing there, for a reading that has moved."
1889
+ ),
1890
+ )
1891
+ govern_parser.add_argument(
1892
+ "key",
1893
+ help="the address, as `config` prints one — e.g. limits.symptom, tools.session",
1894
+ )
1895
+ govern_parser.add_argument(
1896
+ "at",
1897
+ nargs="?",
1898
+ type=int,
1899
+ help="the number to declare; omitted, the reading is printed and nothing is written",
1900
+ )
1901
+ govern_parser.add_argument(
1902
+ "--role",
1903
+ help="which role's limits, for a `[limits.<role>]` table (default: the shared one)",
1904
+ )
1905
+ govern_parser.add_argument(
1906
+ "--file",
1907
+ help="which every-turn file, for a `[budgets]` entry — the path the config spells",
1908
+ )
1909
+ govern_parser.add_argument(
1910
+ "--because",
1911
+ default="",
1912
+ help="your argument for this number, wrapped into comments above the key",
1913
+ )
1914
+ govern_parser.add_argument(
1915
+ "--instead",
1916
+ default="",
1917
+ help=(
1918
+ "the same sentence, replacing the run above the key instead of stacking on it; "
1919
+ "the answer names every line it took out"
1920
+ ),
1921
+ )
1922
+ govern_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1923
+ govern_parser.set_defaults(handler=_govern)
1924
+
1925
+ config_parser = subcommands.add_parser(
1926
+ "config",
1927
+ help="what roadkeep.toml may declare: every table, key, type and default",
1928
+ description=(
1929
+ "Print the shape of this project's own configuration, answered by the package "
1930
+ "that refuses everything else (RK1270). One row per key — its table, its type, "
1931
+ "what this build uses when nobody declares it, and whether this project did — "
1932
+ "with the sentence the source already carries above each table. What is listed "
1933
+ "is what *this* copy accepts, which is how a key it predates is told from a typo, "
1934
+ "so the build that answered is named. Last, what this build *fixes* from its own "
1935
+ "corpus and no project declares, with the reading behind it. It reads and never "
1936
+ "writes."
1937
+ ),
1938
+ )
1939
+ config_parser.add_argument(
1940
+ "--table",
1941
+ default=None,
1942
+ help=(
1943
+ "one table, spelled as the answer spells it — omitted, every one; the top level "
1944
+ "is the empty string, and a table declared per role or per path carries the "
1945
+ "placeholder, e.g. rules.<role>"
1946
+ ),
1947
+ )
1948
+ config_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1949
+ config_parser.set_defaults(handler=_config_shape, reads_only=True)
1950
+
1951
+ commands_parser = subcommands.add_parser(
1952
+ "commands",
1953
+ help="what may be typed: every verb, its arguments, defaults and served exposure",
1954
+ description=(
1955
+ "Print this build's own command surface as data (RK1401). One block per verb — "
1956
+ "whether it reads or writes, the flag that turns a read into a write, and one "
1957
+ "row per argument with its spellings, what it takes, its default and the "
1958
+ "sentence the parser already carries — plus which tool an agent is served it as, "
1959
+ "and which of its arguments that surface exposes on *this* project. `config` "
1960
+ "answers what roadkeep.toml may declare; this answers what may be typed. What is "
1961
+ "listed is what *this* copy takes, so the build that answered is named. It reads "
1962
+ "and never writes."
1963
+ ),
1964
+ )
1965
+ commands_parser.add_argument(
1966
+ "--command",
1967
+ default=None,
1968
+ metavar="VERB",
1969
+ help=(
1970
+ "one verb, spelled as the answer spells it — omitted, every one; a nested one "
1971
+ "carries its path, e.g. 'section add'"
1972
+ ),
1973
+ )
1974
+ commands_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
1975
+ commands_parser.set_defaults(handler=_commands, reads_only=True)
1976
+
1977
+ anchors_parser = subcommands.add_parser(
1978
+ "anchors",
1979
+ help="which outline addresses this project has ever declared, live or retired",
1980
+ description=(
1981
+ "Read the anchors out of every declared prose file and out of its diffs: live "
1982
+ "ones a heading declares now, and retired ones a ship deleted while every entry "
1983
+ "citing them stayed. An address is spent once a heading used it (RK4's rule for "
1984
+ "ids), so this is the read that says which number a reopened family may take — "
1985
+ "and which top-level is free, which is what a reused block needs."
1986
+ ),
1987
+ )
1988
+ anchors_parser.add_argument(
1989
+ "--family",
1990
+ default="",
1991
+ metavar="ANCHOR",
1992
+ help="only this subtree, e.g. XXXVII — omitted, one row per top-level family",
1993
+ )
1994
+ anchors_parser.add_argument(
1995
+ "--block",
1996
+ default="",
1997
+ metavar="LABEL",
1998
+ help=(
1999
+ "the subtree this block's prose already lives under, e.g. Q — the address a "
2000
+ "caller knows, since a prose file under an outline declares no block heading; "
2001
+ "refused with --family, and names both where a block spans two families"
2002
+ ),
2003
+ )
2004
+ anchors_parser.add_argument(
2005
+ "--role",
2006
+ default="",
2007
+ help=(
2008
+ "list only this prose file's addresses (default: every declared one) — the "
2009
+ "free top-level is per namespace, so it stays the project's where no [refs] "
2010
+ "declares one and is that file's own where one does"
2011
+ ),
2012
+ )
2013
+ anchors_parser.add_argument(
2014
+ "--next",
2015
+ dest="only_next",
2016
+ action="store_true",
2017
+ help=(
2018
+ "the free address alone, without the listing of spent ones — the `next-id` of "
2019
+ "anchors, and the read an `add --ref` makes every time"
2020
+ ),
2021
+ )
2022
+ anchors_parser.add_argument(
2023
+ "--claims",
2024
+ action="store_true",
2025
+ help=(
2026
+ "only the addresses whose ownership is not the ordinary one: a heading binding "
2027
+ "nobody, and one binding a task no open line claims — the audit, over every "
2028
+ "family at once, since the rows it leaves out are the ones nobody reads"
2029
+ ),
2030
+ )
2031
+ anchors_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
2032
+ anchors_parser.set_defaults(handler=_anchors, reads_only=True)
2033
+ # Two subjects, as `budget`'s four are (RK466): `--next` returned before the `--claims`
2034
+ # branch was reached, so a caller asking for the audit and the free address read the
2035
+ # address alone with nothing said about the other.
2036
+ answers(
2037
+ anchors_parser, ("only_next", "the free address"), ("claims", "the ownership audit")
2038
+ )
2039
+
2040
+ deps_parser = subcommands.add_parser(
2041
+ "deps",
2042
+ help="resolve one task's deps, naming the ones nothing can resolve",
2043
+ description=(
2044
+ "Resolve each dep against the roadmap and the changelog. A dep nothing now "
2045
+ "open will satisfy is reported as unresolvable rather than open — work "
2046
+ "outside the backlog, a task that retired, and a block label with nothing "
2047
+ "filed under it."
2048
+ ),
2049
+ )
2050
+ deps_parser.add_argument("id", help="the task to resolve, e.g. RK5")
2051
+ deps_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
2052
+ deps_parser.set_defaults(handler=_deps, reads_only=True)
2053
+
2054
+ origin_parser = subcommands.add_parser(
2055
+ "origin",
2056
+ help="the commits that proposed and shipped a task, with the reasoning",
2057
+ description=(
2058
+ "Resolve a task's history from git. The pointer is derived, never stored: "
2059
+ "a hash written into the ledger would be rewritten by the first squash or "
2060
+ "amend, and a dead hash reads exactly like a live one. A leading § asks the "
2061
+ "same question of a rationale anchor instead — the dangling cross-reference a "
2062
+ "ship leaves in somebody else's prose, which no file records the answer to."
2063
+ ),
2064
+ )
2065
+ origin_parser.add_argument(
2066
+ "id", help="the task to look up, e.g. RK1 — or §<anchor>, as the prose spells it"
2067
+ )
2068
+ origin_parser.add_argument(
2069
+ "--why",
2070
+ action="store_true",
2071
+ help="print the shipping commit's full message — the rationale the ledger drops",
2072
+ )
2073
+ origin_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
2074
+ origin_parser.set_defaults(handler=_origin, reads_only=True)
2075
+
2076
+ weight_parser = subcommands.add_parser(
2077
+ "weight",
2078
+ help="what comparable tasks cost, derived from the commits that shipped them",
2079
+ description=(
2080
+ "What a comparable task cost, so granularity is a query instead of a feel: a "
2081
+ "block whose last comparables shipped at 800+ lines is a block where the next "
2082
+ "line is probably two lines. Derived from the commit that wrote each ledger "
2083
+ "entry, so nothing stores it and `git show` refutes it. Two axes and no score — "
2084
+ "median to p90 lines vary 2.7× here and files, which is what an agent holds in "
2085
+ "context, 1.4×. An entry whose commit wrote several is named and left out "
2086
+ "rather than given a share of it, a divided cost being one no commit contains. "
2087
+ "This ranks nothing: every tier of `pick` is a fact, and a cheapness tier would "
2088
+ "defer the architectural tasks, which is where the leverage is."
2089
+ ),
2090
+ )
2091
+ weight_parser.add_argument("--block", help="only this block's comparables, e.g. C")
2092
+ weight_parser.add_argument(
2093
+ "--records",
2094
+ action="store_true",
2095
+ help=(
2096
+ "every weighed entry, which the percentiles summarise: the evidence for the "
2097
+ "figure, wanted when you dispute it and not when you are sizing a line (RK264)"
2098
+ ),
2099
+ )
2100
+ weight_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
2101
+ weight_parser.set_defaults(handler=_weight, reads_only=True)
2102
+
2103
+ remaining_parser = subcommands.add_parser(
2104
+ "remaining",
2105
+ help="how many sites a task's own declared query still matches",
2106
+ description=(
2107
+ "The mirror of `weight`, and derived the same way (RK492): that one says what a "
2108
+ "comparable task cost, from the commits that shipped it, and this says what one "
2109
+ "has left, from the repository as it is now. A migration declares the query in "
2110
+ "its rationale section — a fenced `roadkeep-remaining` block, one `<pathspec> :: "
2111
+ "<regex>` per line — and this runs it. Nothing is stored, so nothing goes stale: "
2112
+ "the first commit that closes a site changes the answer, which a number written "
2113
+ "onto a line could not. It is a count and never a verdict — the pattern is the "
2114
+ "author's, so a query answering 0 says the pattern stopped matching, and whether "
2115
+ "that is the work being done is a judgement this tool does not make."
2116
+ ),
2117
+ )
2118
+ remaining_parser.add_argument("id", help="the task whose design declares the query, e.g. RK12")
2119
+ remaining_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
2120
+ remaining_parser.set_defaults(handler=_remaining, reads_only=True)
2121
+
2122
+ evidence_parser = subcommands.add_parser(
2123
+ "evidence",
2124
+ help="what this task's design says would prove it done, counted now",
2125
+ description=(
2126
+ "Run the criterion a design declares, against this tree, now. `remaining` "
2127
+ "with the sign flipped: a `roadkeep-evidence` fenced block names sites that "
2128
+ "must **exist** where the other names sites still to change, and both are one "
2129
+ "`<pathspec> :: <regex>` per line read by one grammar. Never a verdict — the "
2130
+ "pattern is the author's claim and the count is the answer, so 0 says the "
2131
+ "evidence is not there yet and whether that is the work being done is yours "
2132
+ "to judge. Nothing is stored, so nothing goes stale."
2133
+ ),
2134
+ )
2135
+ evidence_parser.add_argument("id", help="the task whose design declares the criterion")
2136
+ evidence_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
2137
+ evidence_parser.set_defaults(handler=_evidence, reads_only=True)
2138
+