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,974 @@
1
+ """The verbs run once per project, and those whose subject is this tool (RK494).
2
+
3
+ `init` scaffolds, `declare` retrofits a role, `adopt` estimates what an existing backlog
4
+ would cost to bring under the schema, `install` wires the skill, the tools and the guard
5
+ into a checkout, `uninstall` is the way back out, and `engines` says whether the copies
6
+ that can be in play agree. `mcp` serves the same surface over stdio (RK24).
7
+
8
+ `report`, `replay` and the `capture` group belong by the same rule and not by exception:
9
+ their subject is a defect in this tool, captured as facts a replay re-runs (RK85-89) —
10
+ something done to an installation rather than to a backlog.
11
+
12
+ **Neither list is counted here** (RK1397). This opened with *the two whose subject is this
13
+ tool* and named `report` and `replay`, while the module declared four: `capture filed`
14
+ arrived with RK1142 and `capture sweep` with RK1394, both by that same rule, and the first
15
+ paragraph had lost `declare` (RK1264) the same way. Each drift was one line an author did
16
+ not think to touch — the only count in this package that was prose confronted with nothing,
17
+ where every other census here is a table held against the population it is a set of. So the
18
+ two lists are :data:`ABOUT_THIS_TOOL` and :data:`ABOUT_THE_WIRING`, and `test_surfaces`
19
+ holds them against what :func:`declare_wiring` actually declares.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import argparse
25
+ import json
26
+ import sys
27
+ import tempfile
28
+
29
+ from roadkeep.adopting import (
30
+ OPT_IN,
31
+ NoSuchTable,
32
+ declare_table,
33
+ DEFERRED_ROLE,
34
+ SCAFFOLD_ROLES,
35
+ STRATEGY_ROLE,
36
+ adopt,
37
+ declare,
38
+ init,
39
+ )
40
+ from roadkeep.capturing import (
41
+ Filed,
42
+ REPORTS,
43
+ STOPPED_NOTICE,
44
+ body,
45
+ capture,
46
+ captures,
47
+ check,
48
+ delivered,
49
+ handoff,
50
+ keep,
51
+ replay,
52
+ stamp,
53
+ sweep,
54
+ )
55
+ from roadkeep.backlog import Backlog
56
+ from roadkeep.config import ROLES, Config
57
+ from roadkeep.installing import (
58
+ engines,
59
+ install,
60
+ plan,
61
+ removal,
62
+ uninstall,
63
+ vendor,
64
+ )
65
+ from roadkeep.rendering import _estimate_json, _print_estimate
66
+ from roadkeep.serving import serve
67
+ from roadkeep.capturing import PARTS
68
+ from roadkeep.verbs.declaring import _JSON_HELP
69
+ from roadkeep.verbs.refusing import EXIT_GATE, EXIT_OK, EXIT_USAGE, _refused
70
+
71
+ #: The subcommands here whose subject is a defect in **this tool** rather than a backlog
72
+ #: (RK85-89, RK1142, RK1394). Spelled by the full path a caller types, because `capture` is a
73
+ #: group and the two verbs under it are what have the subject — a list of top-level words could
74
+ #: not say that, and saying it wrongly is what RK1397 was.
75
+ ABOUT_THIS_TOOL = ("report", "replay", "capture filed", "capture sweep")
76
+
77
+ #: And those whose subject is the project's own wiring: which files exist, which copies write,
78
+ #: and how the surface is reached. The other half of a partition, so a verb added to this module
79
+ #: belongs to one of them and the test says which is missing rather than that a number moved.
80
+ ABOUT_THE_WIRING = (
81
+ "init",
82
+ "declare",
83
+ "adopt",
84
+ "install",
85
+ "uninstall",
86
+ "engines",
87
+ "mcp",
88
+ )
89
+
90
+
91
+ def _init(config: Config, args: argparse.Namespace) -> int:
92
+ # `config` is deliberately unused: `init` is the one command that runs *before* a
93
+ # project is configured, so it takes the directory it was pointed at. A discovered
94
+ # config would be an ancestor's, and scaffolding under someone else's paths is how a
95
+ # subproject ends up writing into its parent's roadmap.
96
+ del config
97
+ families = tuple(args.prefix or ("RK",))
98
+ try:
99
+ created = init(
100
+ args.directory,
101
+ prefix=families,
102
+ blocks=args.blocks or ("A",),
103
+ # Named at the door and never derived (RK1186): which prose files a project wants
104
+ # is the author's decision, and a scaffold that guessed would create a file
105
+ # somebody has to notice is empty before they can delete it.
106
+ roles=(
107
+ *SCAFFOLD_ROLES,
108
+ *((STRATEGY_ROLE,) if args.strategy else ()),
109
+ *((DEFERRED_ROLE,) if args.deferred else ()),
110
+ ),
111
+ )
112
+ except (ValueError, OSError) as error:
113
+ return _refused(error)
114
+
115
+ if args.json:
116
+ print(json.dumps(created.payload(args.directory, families), indent=2))
117
+ else:
118
+ print(created.stated(families))
119
+ return EXIT_OK
120
+
121
+
122
+ def _declare(config: Config, args: argparse.Namespace) -> int:
123
+ """`init`'s door for a project that is already configured (RK1264).
124
+
125
+ Unlike `_init` this one **wants** the discovered config: the role is added to the project
126
+ the caller is standing in, and the headings it mirrors are that project's own.
127
+ """
128
+ try:
129
+ # One argument, two vocabularies (RK1328): a **role** retrofits a file and its
130
+ # `[files]` key, and an opt-in **table** opens a list this project may then govern.
131
+ # Both are *this file, one key, refused where it is already declared*, which is why
132
+ # the argument widens rather than the verb list — a third served tool costs about 800
133
+ # characters against 87 of headroom, and the ceiling is not what should give.
134
+ if args.role in OPT_IN:
135
+ written = declare_table(config, args.role)
136
+ elif args.role in ROLES:
137
+ written = declare(config, args.role, args.path)
138
+ else:
139
+ # The word is in neither, and the refusal names both: one argument now carries two
140
+ # vocabularies, and a caller who typed into the wrong one learns nothing from a
141
+ # message about the other. `declare` keeps `NoSuchRole` for its own contract.
142
+ raise NoSuchTable(args.role, OPT_IN)
143
+ except (ValueError, OSError) as error:
144
+ return _refused(error)
145
+
146
+ if args.json:
147
+ print(json.dumps(written.payload(config), indent=2))
148
+ else:
149
+ print(written.stated(config))
150
+ return EXIT_OK
151
+
152
+
153
+ def _better_read(config: Config, args: argparse.Namespace, estimate):
154
+ """The reading that fits, where the caller named no role (RK1346).
155
+
156
+ Measured on an ungoverned `CHANGELOG.md`: the backlog grammar reported 0 parsed and *361
157
+ would change*, and `--ledger` reported 361 conform and none changing. The file was already
158
+ conforming, the report said it was 361 lines of work, and the word `ledger` appeared
159
+ nowhere in it. The diagnosis was accurate under the grammar it applied — *no marker where
160
+ the status goes* is exactly true of a ledger entry read as a task line — which is what made
161
+ it convincing.
162
+
163
+ Not a guess: the two grammars separate by an order of magnitude on real files. Measured on
164
+ this repository, `docs/CHANGELOG.md` reads 843 conform as a ledger and 0 as a backlog,
165
+ while `docs/ROADMAP.md` reads 1 and 0 the other way. So the better reading is the one with
166
+ more conforming lines, and a tie keeps what was asked for.
167
+
168
+ Only where nothing was asked. `--ledger` is honoured as typed, for the reason `--prefix`
169
+ is: an override the tool second-guesses is not an override — and the header now names the
170
+ role either way, so a reader can see which grammar answered and pass the other.
171
+ """
172
+ if args.ledger or args.sections or estimate.conforming:
173
+ return estimate
174
+ best = estimate
175
+ # Both other roles and not one (RK1347): a rationale file read as a backlog reported
176
+ # *nothing in 837 line(s) was read in any shape*, where `--sections` read 51 conforming
177
+ # sections and 19 paragraphs over a limit. Tried separately because the two flags are
178
+ # refused together, and the estimator is what declines the pair.
179
+ for role in ({"ledger": True}, {"sections": True}):
180
+ try:
181
+ other = adopt(
182
+ config,
183
+ args.path,
184
+ prefix=args.prefix,
185
+ ref_scheme=args.ref_scheme,
186
+ alongside=args.alongside,
187
+ **role,
188
+ )
189
+ except (ValueError, OSError):
190
+ # A role this file's arguments refuse is not a finding here: what was asked for
191
+ # still answers, and a retry that cannot be taken says nothing about the file.
192
+ continue
193
+ if other.conforming > best.conforming:
194
+ best = other
195
+ return best
196
+
197
+
198
+ def _adopt(config: Config, args: argparse.Namespace) -> int:
199
+ try:
200
+ estimate = adopt(
201
+ config,
202
+ args.path,
203
+ prefix=args.prefix,
204
+ ref_scheme=args.ref_scheme,
205
+ ledger=args.ledger,
206
+ sections=args.sections,
207
+ alongside=args.alongside,
208
+ )
209
+ except (ValueError, OSError) as error:
210
+ return _refused(error)
211
+
212
+ estimate = _better_read(config, args, estimate)
213
+ if args.json:
214
+ print(json.dumps(_estimate_json(estimate), indent=2))
215
+ return EXIT_OK
216
+ _print_estimate(estimate)
217
+ # Always 0: this reports on a file the project has not adopted, so there is no
218
+ # contract for it to have broken. `lint` is the command with an exit code.
219
+ return EXIT_OK
220
+
221
+
222
+ def _engines(config: Config, args: argparse.Namespace) -> int:
223
+ """The three copies this project runs, and whether the two versions agree (RK415).
224
+
225
+ `config` is read for its root alone — the registry is keyed by project path, so the
226
+ question is about the tree and not about the governed files in it.
227
+
228
+ The exit code is the answer, the way `install --check`'s is: a session that has to grep a
229
+ sentence to learn the pen and the judge are 133 versions apart is one that will not ask.
230
+ """
231
+ found = engines(config.root)
232
+ if args.invoke:
233
+ # One line and no verdict (RK1230): this answers *which copy to call*, which is a
234
+ # question a caller has before they know whether the copies agree — and an exit code
235
+ # about agreement would make a shell substitution fail on a project that is merely
236
+ # behind. `engines` bare is where the disagreement is read.
237
+ # `--json` is honoured rather than refused, because the served surface appends it to
238
+ # every call (RK319): a flag that only worked on a terminal would be one this project's
239
+ # own agent could not use, which is the caller the whole task is about.
240
+ print(json.dumps({"invoke": found.invoke()}, indent=2) if args.json else found.invoke())
241
+ return EXIT_OK
242
+ # Both registers off the record (RK1170), the exit code included: whether the pen and the
243
+ # judge are the same copy is a property of the reading and not a second decision here.
244
+ if args.json:
245
+ print(json.dumps(found.payload(), indent=2))
246
+ else:
247
+ print(found.stated())
248
+ return EXIT_OK if found.agree else EXIT_GATE
249
+
250
+
251
+ def _install(config: Config, args: argparse.Namespace) -> int:
252
+ """Wire the harness for a project the plugin did not install (RK100).
253
+
254
+ `config` is unused for `init`'s reason one step further along: this writes the surfaces
255
+ that decide *which* engine a session reaches, and none of it is read out of the governed
256
+ files. The exit code carries `--check`'s answer — 1 for a surface that would change,
257
+ because a copy held in step by a gate is the whole point of there being a check.
258
+ """
259
+ del config
260
+ try:
261
+ intent = (
262
+ # `--check` writes nothing, so it reports the driver as unwritten either way: a
263
+ # check that registered one would be a check that changed the repository (RK148).
264
+ plan(args.directory, source=args.source, committed=args.committed)
265
+ if args.check
266
+ else install(
267
+ args.directory,
268
+ source=args.source,
269
+ register_merge=args.register_merge,
270
+ committed=args.committed,
271
+ )
272
+ )
273
+ # After the surfaces and never instead of them (RK1193): the engine is what those
274
+ # declarations *point at*, so a run that vendored one and failed to wire it would
275
+ # leave a copy nothing reaches. Inside the same try, so a machine with no engine to
276
+ # copy refuses in the words every other bad input gets.
277
+ pinned = vendor(args.directory, checked=args.check) if args.vendor else None
278
+ except (ValueError, OSError) as error:
279
+ return _refused(error)
280
+
281
+ if args.json:
282
+ payload = intent.payload(args.check)
283
+ if pinned is not None:
284
+ payload["vendored"] = pinned.payload()
285
+ print(json.dumps(payload, indent=2))
286
+ else:
287
+ print(intent.stated(args.check))
288
+ if pinned is not None:
289
+ print(pinned.stated(args.check))
290
+ if args.check:
291
+ for line in intent.verdict():
292
+ print(line, file=sys.stderr)
293
+ if args.check and intent.changing:
294
+ return EXIT_GATE
295
+ return EXIT_OK
296
+
297
+
298
+ def _capture_filed(config: Config, args: argparse.Namespace) -> int:
299
+ """Record which task a capture already on disk was filed as (RK1142).
300
+
301
+ `add --capture` closes the row by the act that closes it, and covered every capture filed
302
+ from then on and none of the ones already held: clearing this repository's own row took a
303
+ `python -c`, which is the shape L5 exists against — every question this tool answers is a
304
+ command, and the maintainer reached past the tool.
305
+
306
+ Two refusals, both at the door (L1). An **id no governed file holds** is a link to nothing,
307
+ which is the reading `stats` already makes and the reason it does not clear a row. A **path
308
+ that is not a capture** is somebody's file, and a verb that stamped it would be writing a
309
+ key into an artefact this tool did not produce.
310
+ """
311
+ # Against the project `-C` named and not the process's directory (RK1396): the paths this
312
+ # verb is given are the ones `stats` and `capture sweep` print, and those are spelled
313
+ # project-relative — so reading them from wherever the process happens to be refused the
314
+ # tool's own doors, with a message naming the directory the file was in.
315
+ path = config.locate(args.path)
316
+ held = {one.path.resolve(): one for one in captures(config.root)}
317
+ known = held.get(path.resolve())
318
+ if known is None:
319
+ print(
320
+ f"roadkeep: {args.path} is not a capture this project holds: `stats` names the "
321
+ f"ones it does, under {config.relative(config.root / REPORTS)}",
322
+ file=sys.stderr,
323
+ )
324
+ return EXIT_USAGE
325
+ # A stamp naming another repository is not this backlog's to verify (RK1160): a capture of a
326
+ # defect in *this tool* is filed in this tool's backlog — which is what `report --to
327
+ # OWNER/REPO` says — so the id is one no governed file here holds, and the lookup below would
328
+ # refuse the one delivery a capture taken here can have. What is checked is the shape.
329
+ elsewhere = delivered(args.task_id)
330
+ backlog = Backlog.load(config)
331
+ # And a **bare** id the capture's own destination explains (RK1161): `--to` or `[report]
332
+ # upstream` is where a defect in roadkeep was aimed, the capture records it, so asking the
333
+ # author to spell it again is the asymmetry RK1149 took out of the refusals. Only where this
334
+ # backlog does not hold the id — a local id that resolves is a local filing, whatever the
335
+ # capture was aimed at, and a typo stays the refusal below.
336
+ ids = {
337
+ entry.task.id
338
+ for document in (backlog.roadmap, backlog.ledger, backlog.store)
339
+ if document is not None
340
+ for entry in document.entries
341
+ }
342
+ written = args.task_id
343
+ if not elsewhere and args.task_id not in ids and known.upstream:
344
+ written = f"{known.upstream}#{args.task_id}"
345
+ elsewhere = delivered(written)
346
+ if not elsewhere and args.task_id not in ids:
347
+ print(
348
+ f"roadkeep: no governed file holds {args.task_id}, so stamping it would be a "
349
+ f"link to nothing — file the capture first, and `add --capture {args.path}` "
350
+ f"stamps it as it mints the id; a defect in roadkeep itself belongs in roadkeep's "
351
+ f"backlog, and `--as owner/repo#{args.task_id}` records that delivery",
352
+ file=sys.stderr,
353
+ )
354
+ return EXIT_USAGE
355
+ if not stamp(known.path, written):
356
+ print(f"roadkeep: {args.path} could not be written", file=sys.stderr)
357
+ return EXIT_USAGE
358
+ # No staging line: the report directory is git-ignored, so there is nothing to stage —
359
+ # which is the exemption `test_every_write_command_is_either_wired_or_exempted` carries.
360
+ answer = Filed(
361
+ where=config.relative(known.path),
362
+ filed=written,
363
+ elsewhere=elsewhere,
364
+ asked=args.task_id,
365
+ )
366
+
367
+ if args.json:
368
+ print(json.dumps(answer.payload(), indent=2))
369
+ else:
370
+ print(answer.stated())
371
+ return EXIT_OK
372
+
373
+
374
+ def _capture_sweep(config: Config, args: argparse.Namespace) -> int:
375
+ """Delete the captures the ledger proves are answered, and name the ones it cannot (RK1394).
376
+
377
+ The retention `keep` parks, and the reading is the whole verb: `--check` and the delete print
378
+ the same table, because what a reader needs from a sweep is why four files survived and not
379
+ which three went. Nothing is refused at the door — an empty directory and a directory where
380
+ every capture is still open are both legitimate answers, and a non-zero exit would make a
381
+ project with nothing to sweep fail a hook that ran this.
382
+ """
383
+ found = sweep(config, delete=not args.check)
384
+ if args.json:
385
+ print(json.dumps(found.payload(config), indent=2))
386
+ else:
387
+ print(found.stated(config))
388
+ # A file the reading proved spent and the filesystem would not remove: the directory did not
389
+ # reach the state this reported, which is the one outcome a caller has to be able to branch
390
+ # on. `EXIT_USAGE` because that is where an `OSError` lands in `_refused`, and this is the
391
+ # same class of failure caught one layer earlier so the verdict about the others survives it.
392
+ return EXIT_USAGE if found.refused else EXIT_OK
393
+
394
+
395
+ def _uninstall(config: Config, args: argparse.Namespace) -> int:
396
+ """Take the harness back out of a project that was wired to a checkout (RK138).
397
+
398
+ `config` is unused for `_install`'s reason, and no `--source` is taken for the reason the
399
+ module states: the wiring is recognised by this project's own entries, so un-wiring works
400
+ after the checkout it named is gone — which is when it is usually wanted.
401
+ """
402
+ del config
403
+ try:
404
+ intent = removal(args.directory) if args.check else uninstall(args.directory)
405
+ except (ValueError, OSError) as error:
406
+ return _refused(error)
407
+
408
+ if args.json:
409
+ print(json.dumps(intent.payload(args.check), indent=2))
410
+ else:
411
+ print(intent.stated(args.check))
412
+ if args.check:
413
+ for line in intent.verdict():
414
+ print(line, file=sys.stderr)
415
+ if args.check and intent.changing:
416
+ return EXIT_GATE
417
+ return EXIT_OK
418
+
419
+
420
+ def _report(config: Config, args: argparse.Namespace) -> int:
421
+ """Capture one defect in this tool (RK85). Exit 2 refuses the claim, never the capture.
422
+
423
+ The refusal is the point: a report is a task line for a backlog that holds a limit, so
424
+ the sentence is judged in the session that made the claim rather than in the review of
425
+ an issue. What the observed command exits with is a *fact of the capture* and never this
426
+ command's own code — the whole reason to run it is that it failed.
427
+ """
428
+ argv = list(args.command_argv)
429
+ if argv and argv[0] == "--":
430
+ argv = argv[1:]
431
+ if not argv:
432
+ print("roadkeep: name the command that failed, after a bare --", file=sys.stderr)
433
+ return EXIT_USAGE
434
+ violations = check(args.symptom, args.why, args.block)
435
+ if violations:
436
+ print("roadkeep: refused, nothing captured:", file=sys.stderr)
437
+ for violation in violations:
438
+ print(f" {violation}", file=sys.stderr)
439
+ return EXIT_USAGE
440
+ # Resolved before the capture is composed and not in the `--issue` branch where it used to
441
+ # be read (RK1161): where this went is a fact of the capture, so the artefact records it and
442
+ # `capture filed` can qualify a bare id from the file instead of asking for it again.
443
+ aimed = args.to or config.upstream
444
+ found = capture(
445
+ args.symptom, args.why, args.block, argv, config.root, embed=args.embed, upstream=aimed
446
+ ).without(*args.without)
447
+ # Written before it is printed (RK89): what only exists on a stdout depends on the
448
+ # caller taking a second step, and this block's own RK86 is the record of second steps
449
+ # not being taken. On stderr, so `--json` and `--issue` stay pipeable.
450
+ kept = keep(found, config.root)
451
+ # The clause on the line that was misread (RK1139): a session ran this twice, read `kept
452
+ # …json` as "filed" and reported the work done — and `stats` answered `total 2` and was
453
+ # right, so nothing disagreed. "File it:" was already printed, at the end of the dump
454
+ # below; what was missing is the **negative**, said where the path is.
455
+ print(f"kept {kept.path} (a capture, not a backlog line)", file=sys.stderr)
456
+ # With the flag that closes the row filled in (RK1141): the path is decided here, by
457
+ # `keep`, so the capture cannot name itself — and a command a caller has to complete is a
458
+ # second step, which is what RK86 is this block's own record of.
459
+ print(f"file {found.filing} --capture {kept.path}", file=sys.stderr)
460
+ if kept.complaint:
461
+ print(f"roadkeep: {kept.complaint}", file=sys.stderr)
462
+ # Which of the two forms this is, said here because this is the only moment anybody can
463
+ # choose (RK481). `replay` refuses a capture that carries no governed files, and by the
464
+ # time it does the reporting session is over — so the flag is named to the one caller who
465
+ # could still pass it. Not the default, and that stays: `--embed` is this project's text
466
+ # leaving it, and a tool that published a private repository's roadmap by being helpful
467
+ # is the worse failure. The silence is what was wrong.
468
+ print(
469
+ "replay runs it anywhere: the governed files ride along"
470
+ if args.embed
471
+ else "replay refuses it: no governed files ride along — `--embed` writes the "
472
+ "capture that runs, and sends this project's text with it",
473
+ file=sys.stderr,
474
+ )
475
+ # RK440: the capture carries the annotation for whoever triages it, and this is the same
476
+ # fact said to the session that can still act on it. On stderr with the rest of the
477
+ # narration, so `--json` and `--issue` stay pipeable.
478
+ if found.failure.stopped:
479
+ print(f"roadkeep: {STOPPED_NOTICE}", file=sys.stderr)
480
+ if args.json:
481
+ print(json.dumps(found.as_dict(), indent=2, ensure_ascii=False))
482
+ return EXIT_OK
483
+ if not args.issue:
484
+ print(found)
485
+ return EXIT_OK
486
+ if aimed is None:
487
+ # Guessed, this publishes a private repository's contents in a stranger's tracker.
488
+ print(
489
+ "roadkeep: no upstream to file against: declare [report] upstream = "
490
+ "'owner/repo' in roadkeep.toml, or pass --to",
491
+ file=sys.stderr,
492
+ )
493
+ return EXIT_USAGE
494
+ print(body(found))
495
+ sys.stdout.flush()
496
+ print(handoff(found, aimed), file=sys.stderr)
497
+ return EXIT_OK
498
+
499
+
500
+ def _replay(config: Config, args: argparse.Namespace) -> int:
501
+ """Re-run one stored capture (RK88). Exit 1 when the verdict is not the recorded one.
502
+
503
+ A scratch directory and never the working tree: the capture carries a `roadkeep.toml`
504
+ and a governed file, and staging those over somebody's project would be the one write
505
+ this tool makes that nobody asked for.
506
+ """
507
+ try:
508
+ # `locate` for `_capture_filed`'s reason (RK1396): a capture is a file of the project,
509
+ # and the address a reader has is the one `stats` printed. `tolerates_config_error` does
510
+ # not weaken it — a default config still knows the root `-C` named, which is the whole
511
+ # of what this needs.
512
+ recorded = json.loads(config.locate(args.path).read_text(encoding="utf-8"))
513
+ except (OSError, ValueError) as error:
514
+ print(f"roadkeep: {error}", file=sys.stderr)
515
+ return EXIT_USAGE
516
+ with tempfile.TemporaryDirectory(prefix="roadkeep-replay-") as scratch:
517
+ outcome = replay(recorded, scratch)
518
+ expected = bool(recorded.get("reproduces", True))
519
+
520
+ if args.json:
521
+ print(json.dumps(outcome.payload(args.path, expected), indent=2))
522
+ else:
523
+ print(outcome.stated(args.path, expected))
524
+ return EXIT_OK if outcome.agrees(expected) else EXIT_GATE
525
+
526
+
527
+ def _mcp(config: Config, args: argparse.Namespace) -> int:
528
+ """Hand stdin and stdout to the protocol loop (RK24).
529
+
530
+ The directory and not the `Config`: the server re-discovers it per message, so a
531
+ `roadkeep.toml` edited during the session is the one the next `tools/list` describes.
532
+ """
533
+ return serve(sys.stdin, sys.stdout, args.directory)
534
+
535
+
536
+ def declare_wiring(subcommands: argparse._SubParsersAction) -> None:
537
+ """This module's verbs, declared where their handlers are (RK1171).
538
+
539
+ `build_parser` called forty-nine blocks like these in a row; what it calls now is an index
540
+ over the modules that own them. The move is what RK1169 and RK1170 bought: the flags a verb
541
+ declares, the reasons it withholds and the record it answers with are one file's, so a
542
+ change to any of them is one file's too.
543
+
544
+ The order inside is `build_parser`'s own, which is where these blocks sat.
545
+ """
546
+ report_parser = subcommands.add_parser(
547
+ "report",
548
+ help="capture a defect in this tool, with what the failing session knew",
549
+ description=(
550
+ "Re-run the command that failed, in this process, and emit what identifies the "
551
+ "defect: the argv, the exit code, the engine that answered, this project's "
552
+ "roadkeep.toml, the line the engine objected to and any traceback. The two "
553
+ "facts a machine cannot supply are arguments and are refused here against this "
554
+ "tool's own schema, so a report arrives inside the limits the backlog it is "
555
+ "destined for enforces. Nothing is sent: the capture is printed, and delivery "
556
+ "is a separate decision."
557
+ ),
558
+ )
559
+ report_parser.add_argument(
560
+ "--symptom", required=True, help="what does not work — a phrase, never a fix"
561
+ )
562
+ report_parser.add_argument(
563
+ "--why", required=True, help="one sentence, ending in a stop: why it matters"
564
+ )
565
+ report_parser.add_argument(
566
+ "--block",
567
+ default="F",
568
+ help="the block of roadkeep's own backlog this belongs under (default: F)",
569
+ )
570
+ report_parser.add_argument(
571
+ "--without",
572
+ dest="without",
573
+ action="append",
574
+ default=[],
575
+ metavar="PART",
576
+ choices=PARTS,
577
+ help=(
578
+ "drop one part of the capture, repeatable: what a private repository must not "
579
+ "publish is deleted by name, never scrubbed by a filter"
580
+ ),
581
+ )
582
+ report_parser.add_argument(
583
+ "--issue",
584
+ action="store_true",
585
+ help=(
586
+ "print the tracker body on stdout and the command that files it on stderr; "
587
+ "nothing is sent, and the destination is [report] upstream"
588
+ ),
589
+ )
590
+ report_parser.add_argument(
591
+ "--to",
592
+ metavar="OWNER/REPO",
593
+ help="file against this repository instead of the configured upstream",
594
+ )
595
+ report_parser.add_argument(
596
+ "--embed",
597
+ action="store_true",
598
+ help=(
599
+ "carry the governed files this project declares, so the capture can be replayed "
600
+ "without this repository — a test somewhere else, and files leaving here"
601
+ ),
602
+ )
603
+ report_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
604
+ report_parser.add_argument(
605
+ "command_argv",
606
+ nargs=argparse.REMAINDER,
607
+ metavar="-- COMMAND",
608
+ help="the roadkeep command that failed, after a bare --, without the program name",
609
+ )
610
+ report_parser.set_defaults(handler=_report, tolerates_config_error=True, reads_only=True)
611
+
612
+ replay_parser = subcommands.add_parser(
613
+ "replay",
614
+ help="re-run a stored capture against the tree that is here now",
615
+ description=(
616
+ "Stage the capture's own configuration and file in a scratch directory, run "
617
+ "the argv it recorded, and answer whether the defect still reproduces. Nothing "
618
+ "from the reporting project is needed: a capture that was never made replayable "
619
+ "says which part it lacks instead of being staged from a guess. Exits 1 when "
620
+ "the answer differs from the `reproduces` the file records — which is what "
621
+ "makes a corpus of field reports a gate rather than a folder."
622
+ ),
623
+ )
624
+ replay_parser.add_argument("path", help="a capture written by `report --json`")
625
+ replay_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
626
+ replay_parser.set_defaults(handler=_replay, tolerates_config_error=True, reads_only=True)
627
+
628
+ capture_parser = subcommands.add_parser(
629
+ "capture",
630
+ help="what became of a capture already on disk",
631
+ description=(
632
+ "The third of the capture pair's family (RK1142). `report` writes one and "
633
+ "`replay` re-runs it; this says what happened to one that is already there — "
634
+ "which task it was filed as, and whether that answer makes it spent. The "
635
+ "retention `keep` parked arrives here as `sweep` (RK1394), in its exact half "
636
+ "only: rotation, an age limit and a dedup by argv are still open, and they are "
637
+ "what a capture that never gets a stamp waits for."
638
+ ),
639
+ )
640
+ capture_actions = capture_parser.add_subparsers(dest="action", required=True)
641
+ capture_filed = capture_actions.add_parser(
642
+ "filed",
643
+ help="record which task a kept capture was filed as",
644
+ description=(
645
+ "Write into the capture the id it was filed as, so the row `stats` counts is "
646
+ "cleared by a fact in the artefact rather than by a symptom that matches "
647
+ "(RK1141). `add --capture` does this for a capture being filed now; this is the "
648
+ "door for one already on disk, and it is the whole of what RK1142 was: clearing "
649
+ "this repository's own row took a `python -c`, which is what L5 exists against. "
650
+ "Refused where no governed file holds the id — a stamp naming nothing is a link "
651
+ "to nothing — and where the path is not a capture this tool wrote. An id "
652
+ "**qualified by a repository** is the exception (RK1160): a defect in roadkeep is "
653
+ "filed in roadkeep's backlog, so no local file will ever hold that id, and both "
654
+ "readers left a row nothing could clear."
655
+ ),
656
+ )
657
+ capture_filed.add_argument("path", help="a capture under .roadkeep/reports/")
658
+ capture_filed.add_argument(
659
+ "--as",
660
+ dest="task_id",
661
+ required=True,
662
+ metavar="ID",
663
+ help=(
664
+ "the task it was filed as, e.g. RK1138 — refused unless a governed file holds it, "
665
+ "or `owner/repo#ID` for one filed in another backlog this project cannot read"
666
+ ),
667
+ )
668
+ capture_filed.add_argument("--json", action="store_true", help=_JSON_HELP)
669
+ capture_filed.set_defaults(handler=_capture_filed, wiring=True)
670
+
671
+ capture_sweep = capture_actions.add_parser(
672
+ "sweep",
673
+ help="delete the captures the ledger records as shipped",
674
+ description=(
675
+ "The retention `keep` parks, keyed on the fact the artefact already carries "
676
+ "(RK1394). A capture whose `filed` id the ledger records as shipped is answered "
677
+ "by this repository's own record, so it is deleted; every other state is named "
678
+ "and left. An age limit would be the weaker key — it says time passed where a "
679
+ "stamp says the work landed — and it deletes exactly the captures an exact "
680
+ "reading protects: one never filed, one open, and one delivered to a backlog "
681
+ "this project cannot read. `--check` prints the same table and removes nothing."
682
+ ),
683
+ )
684
+ capture_sweep.add_argument(
685
+ "--check",
686
+ action="store_true",
687
+ help="say what would go and leave the directory alone",
688
+ )
689
+ capture_sweep.add_argument("--json", action="store_true", help=_JSON_HELP)
690
+ # `reads_only` for `report`'s and `replay`'s reason and not as a claim about the filesystem
691
+ # (RK167): what it declares is that no **governed** file is written, which is what decides
692
+ # whether the lock is taken — the ledger is read here and nothing else is, and the files that
693
+ # go are in a directory git was taught to ignore.
694
+ #
695
+ # And deliberately no `wiring=True`, unlike its sibling. That exemption exists so a pin has a
696
+ # way to be satisfied and a defect a way to be filed (see `cli._enforced`); neither is what
697
+ # this does — it *deletes* evidence, which is the one write a copy the project has pinned
698
+ # away from should be refused, and a sweep postponed until the right copy runs costs
699
+ # kilobytes.
700
+ capture_sweep.set_defaults(handler=_capture_sweep, reads_only=True)
701
+
702
+ init_parser = subcommands.add_parser(
703
+ "init",
704
+ help="scaffold roadkeep.toml and the files it declares",
705
+ description=(
706
+ "Write the configuration and the three governed files, or write nothing. The "
707
+ "config is rendered from the schema's own defaults, so a scaffold cannot "
708
+ "declare a format the tool does not implement. No starter task and no prose: "
709
+ "a title, the blocks you name, and where the non-goals go."
710
+ ),
711
+ )
712
+ init_parser.add_argument(
713
+ "--prefix",
714
+ action="append",
715
+ help=(
716
+ "the id prefix, uppercase alphanumeric (default: RK). Repeatable for a "
717
+ "backlog numbered by track; the first is what `add` mints under"
718
+ ),
719
+ )
720
+ init_parser.add_argument(
721
+ "--block",
722
+ action="append",
723
+ dest="blocks",
724
+ metavar="LABEL",
725
+ help=(
726
+ "a block heading, repeatable: 'A' or 'A — The model'. A task is filed "
727
+ "under a heading and a write never invents one (default: A)"
728
+ ),
729
+ )
730
+ init_parser.add_argument(
731
+ "--strategy",
732
+ action="store_true",
733
+ help=(
734
+ "scaffold the strategy file too: a prose role for a document that outlives "
735
+ "every task filed under it, where an improvements section is one task's "
736
+ "rationale and goes when the line ships"
737
+ ),
738
+ )
739
+ init_parser.add_argument(
740
+ "--deferred",
741
+ action="store_true",
742
+ help=(
743
+ "scaffold the deferred store too: the file `defer` moves a line to, which "
744
+ "keeps the id, the deps and the section a retirement deletes. Without it that "
745
+ "verb refuses, and the remedy is a toml key and a skeleton written by hand"
746
+ ),
747
+ )
748
+ init_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
749
+ init_parser.set_defaults(handler=_init, wiring=True)
750
+
751
+ declare_parser = subcommands.add_parser(
752
+ "declare",
753
+ help="add one governed role or open one opt-in table, past `init`",
754
+ description=(
755
+ "Write one role's file and the `[files]` key governing it, or open an opt-in "
756
+ "table, on a project past `init`. Reach for it when a verb refuses over an "
757
+ "undeclared role or table: `init` writes both once and refuses to run twice, so "
758
+ "either declined at scaffold time was otherwise a hand edit. A role's file "
759
+ "arrives with the block headings the roadmap carries, spelled as that file spells "
760
+ "one; a table arrives empty, which is what opting in means, and `govern` tunes "
761
+ "what is in it. The config keeps every other byte. Refused where it is already "
762
+ "declared."
763
+ ),
764
+ )
765
+ # Not argparse `choices`, for `--role`'s own reason (RK304) read one step further: what is
766
+ # answerable here is the roles this *project* has not declared, which a parser built once
767
+ # per process cannot say — so the closed set is published per project in the tool schema and
768
+ # refused by name in the command.
769
+ declare_parser.add_argument(
770
+ "role",
771
+ help=(
772
+ f"which governed file to declare, one of {', '.join(ROLES)} — or an opt-in "
773
+ f"table to open, one of {', '.join(OPT_IN)}"
774
+ ),
775
+ )
776
+ declare_parser.add_argument(
777
+ "--path",
778
+ help="where it goes, project-relative (default: this role's own docs/ path)",
779
+ )
780
+ declare_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
781
+ declare_parser.set_defaults(handler=_declare)
782
+
783
+ adopt_parser = subcommands.add_parser(
784
+ "adopt",
785
+ help="what an existing backlog would have to change to pass",
786
+ description=(
787
+ "Run the schema over a backlog this tool does not own yet and report the "
788
+ "delta: what parses, what conforms, the longest field against its limit, the "
789
+ "markers to declare. Writes nothing and never fails — an estimate that "
790
+ "exits 1 is a gate, and the point is to take it before the commitment."
791
+ ),
792
+ )
793
+ adopt_parser.add_argument("path", help="the file to measure, e.g. docs/ROADMAP.md")
794
+ adopt_parser.add_argument(
795
+ "--prefix",
796
+ action="append",
797
+ help=(
798
+ "read the ids under this prefix, repeatable for a backlog numbered by "
799
+ "track; without it the project's own is used, or the one the file's ids "
800
+ "already spell — never all of them, which is a judgement and not a count"
801
+ ),
802
+ )
803
+ adopt_parser.add_argument(
804
+ "--ref-scheme",
805
+ dest="ref_scheme",
806
+ choices=("id", "outline"),
807
+ help=(
808
+ "measure the pointers under this scheme: 'outline' asks what adopting the "
809
+ "tool costs, 'id' what adopting it and renumbering the outline costs"
810
+ ),
811
+ )
812
+ adopt_parser.add_argument(
813
+ "--ledger",
814
+ action="store_true",
815
+ help="measure it as a changelog: shipped marker, no deps field, no pointer",
816
+ )
817
+ adopt_parser.add_argument(
818
+ "--sections",
819
+ action="store_true",
820
+ help=(
821
+ "measure it as a rationale file: sections against `section`, and the width "
822
+ "its prose is already wrapped to — the two limits an adopter has to declare"
823
+ ),
824
+ )
825
+ adopt_parser.add_argument(
826
+ "--with",
827
+ dest="alongside",
828
+ metavar="PATH",
829
+ action="append",
830
+ default=[],
831
+ help=(
832
+ "another prose file an address could be doubled across, repeatable — the one "
833
+ "measure here that is about a set of files rather than this one; requires "
834
+ "--sections, and never inferred from the directory"
835
+ ),
836
+ )
837
+ adopt_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
838
+ # Read-only, which RK18 has been true of since this verb existed and nothing declared:
839
+ # `adopt` measures a file and exits 0, writing nothing anywhere. Undeclared it took the
840
+ # write lock for a run that cannot conflict with one, and — since RK1147 published a door
841
+ # that reruns it — said `writes: true` in a payload about a command that writes nothing.
842
+ adopt_parser.set_defaults(handler=_adopt, reads_only=True)
843
+
844
+ install_parser = subcommands.add_parser(
845
+ "install",
846
+ help="wire this project to the checkout answering, the way the plugin would",
847
+ description=(
848
+ "Write the surfaces the plugin ships, for a project that runs roadkeep from a "
849
+ "checkout instead: the server, the guard on its three hook events, and the "
850
+ "skill that says which command to call — plus the CI workflow when the "
851
+ "repository already has one. Every byte is translated from what the plugin "
852
+ "carries, the launcher's path being the only substituted fact, so the skill "
853
+ "cannot drift from the file it was copied from. The skill is refreshed on "
854
+ "every run; the declarations keep everything they hold that is not this "
855
+ "project's entry; the workflow is written once and then yours."
856
+ ),
857
+ )
858
+ install_parser.add_argument(
859
+ "--check",
860
+ action="store_true",
861
+ help=(
862
+ "write nothing and exit 1 on anything that would change: the gate that keeps "
863
+ "the copied skill in step, for a CI job or a pre-commit hook"
864
+ ),
865
+ )
866
+ install_parser.add_argument(
867
+ "--source",
868
+ metavar="PATH",
869
+ help=(
870
+ "the roadkeep checkout to wire in (default: the one this command is running "
871
+ "from, which is the one whose hook and tools the project would get)"
872
+ ),
873
+ )
874
+ install_parser.add_argument(
875
+ "--register-merge",
876
+ action="store_true",
877
+ help=(
878
+ "wire the merge driver too — the `.gitattributes` half of `merge --register`, "
879
+ "with the `git config` line printed for you to run: a flag and not a default, "
880
+ "because it is configuration and the other half is outside these files"
881
+ ),
882
+ )
883
+ install_parser.add_argument(
884
+ "--committed",
885
+ action="store_true",
886
+ help=(
887
+ "wire a launcher committed to this repository instead of a path to the checkout, "
888
+ "so the guard reaches an environment that installs no plugin and clones no "
889
+ "checkout — Claude Code on the web. It defers where the harness has the plugin "
890
+ "wired for this project, and never blocks a turn"
891
+ ),
892
+ )
893
+ install_parser.add_argument(
894
+ "--vendor",
895
+ action="store_true",
896
+ help=(
897
+ "copy the highest-versioned roadkeep this machine can reach into .roadkeep/, so "
898
+ "the project runs a pinned engine instead of whichever copy a search order "
899
+ "reaches first; ROADKEEP_SRC names a working checkout, which is otherwise skipped"
900
+ ),
901
+ )
902
+ install_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
903
+ install_parser.set_defaults(handler=_install, wiring=True)
904
+
905
+ engines_parser = subcommands.add_parser(
906
+ "engines",
907
+ help="which copies of roadkeep write, judge and gate this project",
908
+ description=(
909
+ "An adopting project wires three: the plugin its hook and skill run, the action "
910
+ "its workflow gates on, and whatever `roadkeep` the caller invokes. They are "
911
+ "allowed to differ — a cache may lag a checkout — and what is not survivable is "
912
+ "not being able to say which one answered. A fourth is read and never judged: "
913
+ "the merge driver git would run, a command rather than a version. Exits 1 where "
914
+ "the two that state a version state different ones."
915
+ ),
916
+ )
917
+ # The one line a caller pastes (RK1230). Its own flag rather than a row in the table:
918
+ # what a shell needs is a value it can read into a variable, and the table is exactly the
919
+ # thing a session was reduced to grepping — or, worse, to finding by listing a cache.
920
+ engines_parser.add_argument(
921
+ "--invoke",
922
+ action="store_true",
923
+ help=(
924
+ "print only the command that reaches the copy wired to this project, so a shell "
925
+ "invocation needs no directory listing to find it"
926
+ ),
927
+ )
928
+ engines_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
929
+ # A read, and the exit code is its verdict rather than a fault (RK271): the three lines
930
+ # above it have already said everything, and `/plugin update` is the move.
931
+ engines_parser.set_defaults(handler=_engines, reads_only=True)
932
+
933
+ uninstall_parser = subcommands.add_parser(
934
+ "uninstall",
935
+ help="take this project's entries back out of the four surfaces install wrote",
936
+ description=(
937
+ "Un-wire a project that ran roadkeep from a checkout — moving to the plugin, or "
938
+ "off the tool entirely (RK138). The inverse of `install` under the same two "
939
+ "rules: the declarations keep every entry that is not this project's, and a "
940
+ "file that is not a JSON object is refused rather than rewritten. A file left "
941
+ "holding nothing but what `install` wrote is deleted, because that is the state "
942
+ "it was created from. It reads no checkout — the wiring is recognised by the "
943
+ "server's name and the launcher a hook runs — so a project can be un-wired "
944
+ "after the tree it pointed at is gone. The CI workflow stays: that gate calls "
945
+ "the published action and not the checkout."
946
+ ),
947
+ )
948
+ uninstall_parser.add_argument(
949
+ "--check",
950
+ action="store_true",
951
+ help=(
952
+ "take nothing out and exit 1 while anything is still wired: the same tense "
953
+ "`install --check` reports in, on the other direction"
954
+ ),
955
+ )
956
+ uninstall_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
957
+ uninstall_parser.set_defaults(handler=_uninstall, wiring=True)
958
+
959
+ mcp_parser = subcommands.add_parser(
960
+ "mcp",
961
+ help="serve add, ship, pick and lint as MCP tools over stdio",
962
+ description=(
963
+ "Speak JSON-RPC on stdin and stdout so the fields arrive as a schema the "
964
+ "client validates instead of flag names an agent types from memory (RK24). "
965
+ "Every tool is dispatched through this same parser, so the refusal is the one "
966
+ "a terminal prints. Not for a human to call: a session's client starts it."
967
+ ),
968
+ )
969
+ # Same reason as `guard`: the process is started once for a whole session, so refusing
970
+ # to start on a broken `roadkeep.toml` would take the tools away exactly when the gate
971
+ # is what the project needs. `tools/list` describes the defaults and the first call
972
+ # reports the error.
973
+ mcp_parser.set_defaults(handler=_mcp, tolerates_config_error=True, reads_only=True)
974
+