roadkeep 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. roadkeep/__init__.py +79 -0
  2. roadkeep/adopting.py +2347 -0
  3. roadkeep/attesting.py +293 -0
  4. roadkeep/authoring.py +2117 -0
  5. roadkeep/backlog.py +767 -0
  6. roadkeep/blocking.py +1622 -0
  7. roadkeep/briefing.py +970 -0
  8. roadkeep/budgeting.py +2056 -0
  9. roadkeep/capturing.py +1699 -0
  10. roadkeep/claiming.py +1019 -0
  11. roadkeep/cli.py +638 -0
  12. roadkeep/commanding.py +487 -0
  13. roadkeep/config.py +1832 -0
  14. roadkeep/counting.py +376 -0
  15. roadkeep/criteria.py +933 -0
  16. roadkeep/deferring.py +708 -0
  17. roadkeep/describing.py +568 -0
  18. roadkeep/exporting.py +808 -0
  19. roadkeep/fixing.py +629 -0
  20. roadkeep/governing.py +934 -0
  21. roadkeep/graph.py +395 -0
  22. roadkeep/guarding.py +1028 -0
  23. roadkeep/history.py +2403 -0
  24. roadkeep/ids.py +301 -0
  25. roadkeep/installing.py +2145 -0
  26. roadkeep/kernel/__init__.py +24 -0
  27. roadkeep/kernel/document.py +1719 -0
  28. roadkeep/kernel/schema.py +2308 -0
  29. roadkeep/linting.py +4420 -0
  30. roadkeep/locking.py +209 -0
  31. roadkeep/markers.py +172 -0
  32. roadkeep/merging.py +1159 -0
  33. roadkeep/picking.py +772 -0
  34. roadkeep/provenance.py +789 -0
  35. roadkeep/queueing.py +752 -0
  36. roadkeep/ranking.py +139 -0
  37. roadkeep/referring.py +231 -0
  38. roadkeep/remaining.py +336 -0
  39. roadkeep/remedying.py +1989 -0
  40. roadkeep/rendering.py +1601 -0
  41. roadkeep/renumbering.py +503 -0
  42. roadkeep/repairing.py +295 -0
  43. roadkeep/reverting.py +144 -0
  44. roadkeep/scoping.py +708 -0
  45. roadkeep/screening.py +196 -0
  46. roadkeep/sections.py +4121 -0
  47. roadkeep/serving.py +2909 -0
  48. roadkeep/shipping.py +3993 -0
  49. roadkeep/showing.py +613 -0
  50. roadkeep/storing.py +224 -0
  51. roadkeep/verbs/__init__.py +26 -0
  52. roadkeep/verbs/adopting.py +974 -0
  53. roadkeep/verbs/authoring.py +566 -0
  54. roadkeep/verbs/declaring.py +335 -0
  55. roadkeep/verbs/linting.py +645 -0
  56. roadkeep/verbs/querying.py +2138 -0
  57. roadkeep/verbs/reading.py +307 -0
  58. roadkeep/verbs/refusing.py +146 -0
  59. roadkeep/verbs/sections.py +1433 -0
  60. roadkeep/verbs/shipping.py +819 -0
  61. roadkeep/weighing.py +380 -0
  62. roadkeep-0.2.0.dist-info/METADATA +453 -0
  63. roadkeep-0.2.0.dist-info/RECORD +67 -0
  64. roadkeep-0.2.0.dist-info/WHEEL +5 -0
  65. roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
  66. roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
  67. roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/claiming.py ADDED
@@ -0,0 +1,1019 @@
1
+ """What *taken* means, dated outside the repository (RK119).
2
+
3
+ `pick` (RK11) is a pure function of two files, so N callers reading an unchanged backlog get
4
+ N identical answers — and tier 1, which prefers a 🛠 line so one worker finishes what they
5
+ started, hands the second agent to ask exactly the line the first one is holding, with the
6
+ tier name saying so. The answer to that is that answering becomes a **write**: the marker
7
+ flips inside the same serialised transaction that chose the line
8
+ (:func:`roadkeep.picking.take`), so the next caller reads a file that has already moved.
9
+
10
+ That leaves the half a marker cannot carry. 🛠 says the work is under way; it does not say
11
+ whether the claim is still live, and a claim held by nobody is a task nobody can pick. So
12
+ **when** a claim was taken is recorded here — and here is deliberately the same place the
13
+ write lock lives (RK117), for the same three reasons:
14
+
15
+ * **Not a second store (L2).** It holds no fact about any task. What is durable is
16
+ *claimed* — the 🛠 the roadmap carries, which git moves between checkouts — and this file
17
+ only dates it. Delete it while nothing is running and every claim reads as expired, which
18
+ is precisely the behaviour before this existed: a 🛠 line nobody holds is offered again.
19
+ * **An expiry, not a lock.** Past `[claims] held` a claim is stepped over and the line is
20
+ offered as ordinary half-done work. There is no portable way to ask whether the worker is
21
+ still alive, and an agent that was killed must not take a task out of the backlog for
22
+ ever — a claim nobody can break is the failure, not the fix. How long that window is is
23
+ the one number here that is a judgement about how long work takes, so it is the project's
24
+ to declare (L6) and bounded at both ends where it is read (RK151).
25
+ * **No owner.** An owner field would be a schema change carrying a fact that lives outside
26
+ the repository; the identity behind a claim belongs in the commit. So a claim is
27
+ recognised and never attributed, which is why `pick` *names* the ids it stepped around
28
+ rather than only counting them: recognising one's own claim is the caller's to do, and it
29
+ cannot be done against a number.
30
+
31
+ What the registry holds is a **date**, and what that date *means* is three different things
32
+ depending on the line and the window — so :func:`survey` is the read that says which (RK161),
33
+ and where the file is. Every other question this tool answers is a command (L5); this was the
34
+ one that had to be answered by finding a temp file whose name is a digest.
35
+
36
+ What a claim *says its commit owns* is the one field here that is not about the line at all
37
+ (RK280), and :func:`departing` is what finally calls it (RK294): a scope declared and never
38
+ read back at the moment of committing is the advice `agents.md` already carried.
39
+
40
+ A claim is only ever read against a 🛠 line, so **the marker is what a claim follows** — which
41
+ :func:`follow` makes true in both directions (RK158) rather than leaving half of it to be
42
+ inferred by the read: a write that puts a line in progress dates a claim, and a write that
43
+ takes it out of progress drops one. Two doors change a claim without moving that marker at all
44
+ (RK156): `renumber` moves the *address* (:func:`rename`), and `defer` takes the line out of the
45
+ file the marker is read in, which the same rule then reads as a release. :func:`follow` is the
46
+ only thing that writes a *claim*, and every write it makes is a reconciliation against the lines
47
+ it was given (RK163) — one door, so the rule cannot come to have two behaviours. :func:`rename`
48
+ touches the same file and is not a second door to that rule: it moves an **address**, which is
49
+ the one thing about a claim the marker cannot express.
50
+ """
51
+
52
+ from __future__ import annotations
53
+
54
+ import time
55
+ from collections.abc import Iterable, Mapping
56
+ from dataclasses import dataclass
57
+ from enum import StrEnum
58
+ from pathlib import Path
59
+
60
+ from roadkeep.backlog import Backlog
61
+ from roadkeep.config import PROSE_ROLES, ROLES, Config
62
+ from roadkeep.ids import CARRIERS
63
+ from roadkeep.kernel.document import Entry
64
+ from roadkeep.locking import exclusive
65
+ from roadkeep.kernel.schema import IN_PROGRESS, Task
66
+ from roadkeep.storing import Claim, Store, read, write
67
+ from roadkeep.storing import path as store_path
68
+
69
+
70
+ def window(config: Config) -> float:
71
+ """This project's claim window, in seconds (RK151).
72
+
73
+ Orders of magnitude above the write lock's own :data:`~roadkeep.locking.STALE`, because
74
+ the two measure different spans: a lock covers one command and a claim covers the work.
75
+ Declared in minutes and used in seconds — the declaration is a judgement a person makes
76
+ about a backlog, and the arithmetic is nobody's to repeat at a call site.
77
+ """
78
+ return config.held * 60.0
79
+
80
+
81
+ class AlreadyHeld(ValueError):
82
+ """Taking a line a live claim already holds would be the two workers again (RK149).
83
+
84
+ Raised by the **marker write** and therefore by every door that names an id (RK160): a
85
+ pick was choosing anyway, so it steps around a live claim and answers with something else,
86
+ while a caller that said which id it wants has nothing to step to. What made this one
87
+ door's refusal rather than the rule's was that `status <id> 🛠` writes the same marker and
88
+ took the claim in the holder's name, silently — two workers on one line arriving through
89
+ the verb that exists to stop that.
90
+
91
+ So **nothing re-dates a live claim**, which is the invariant worth having: the window is
92
+ the expiry, not something a second call can postpone. Says what to do, because a claim
93
+ names nobody and this one may be the caller's own: the read is one call without the flag,
94
+ and the release is a marker.
95
+ """
96
+
97
+ def __init__(self, task_id: str, since: str, marker: str) -> None:
98
+ self.task_id = task_id
99
+ super().__init__(
100
+ f"{task_id} was claimed {since} ago and a claim names nobody, so it may be "
101
+ f"yours: read it without --claim, or move the marker off {marker} to release it"
102
+ )
103
+
104
+
105
+ def since(age: float) -> str:
106
+ """`14m`, `2h05m` — the figure a reader checks against how long the work should take.
107
+
108
+ One formatter, because two would eventually disagree about the same number in two answers.
109
+ """
110
+ minutes = int(age // 60)
111
+ return f"{minutes}m" if minutes < 60 else f"{minutes // 60}h{minutes % 60:02d}m"
112
+
113
+
114
+ #: One registry row as it is on disk. Defined in :mod:`roadkeep.storing` and named here,
115
+ #: because the row is the store's to spell (RK330) and the *meaning* of its date is this
116
+ #: module's alone — a claim is a date read against a 🛠 line and a window.
117
+ Dating = Claim
118
+
119
+
120
+ @dataclass(frozen=True, slots=True)
121
+ class Held:
122
+ """One claim a caller was not offered: which line, and how long it has been held."""
123
+
124
+ id: str
125
+ age: float
126
+ #: The paths this claim says are its commit's (RK280). Empty where none were declared,
127
+ #: which is every claim taken before the holder said — silence is not a claim to nothing.
128
+ paths: tuple[str, ...] = ()
129
+
130
+ @property
131
+ def since(self) -> str:
132
+ return since(self.age)
133
+
134
+
135
+ class State(StrEnum):
136
+ """What the registry's entry for one id actually is (RK161).
137
+
138
+ Three, because the registry holds one thing and means three: a claim is a *date* read
139
+ against a 🛠 line and a window, so an entry outliving either is not a claim and is what an
140
+ operator is hunting when a listing is what they wanted.
141
+ """
142
+
143
+ #: 🛠, inside the window: a line no answer will offer.
144
+ HELD = "held"
145
+ #: 🛠, past the window: stepped over, so the line is offered again as half-done work.
146
+ EXPIRED = "expired"
147
+ #: The marker moved on, or no line carries the id at all. Nothing reads it; the next
148
+ #: marker write reconciles it away.
149
+ STALE = "stale"
150
+
151
+
152
+ class Where(StrEnum):
153
+ """Where the id is now — the *cause* a stale row used to report as its consequence (RK164).
154
+
155
+ "No line carries this id" is true of four different situations and useful in one of them.
156
+ The other three left the roadmap by a door and are recorded: the reader scanning this
157
+ column is deciding whether to act, and only the last of these is anything to act on.
158
+ """
159
+
160
+ #: A line in the roadmap. Its own marker and block say the rest.
161
+ OPEN = "open"
162
+ SHIPPED = "shipped"
163
+ RETIRED = "retired"
164
+ PAUSED = "set aside"
165
+ #: In no governed file at all — the leftover, and the one row worth a second look. What
166
+ #: removed it is `gaps`' answer (RK31) and stays one command away: this resolves against
167
+ #: the files it already has open, and history is not one of them.
168
+ NOWHERE = "in no file at all"
169
+
170
+
171
+ @dataclass(frozen=True, slots=True)
172
+ class Dated:
173
+ """One entry in the registry, and what the files make of it (RK161)."""
174
+
175
+ id: str
176
+ age: float
177
+ state: State
178
+ #: Where the id is now (RK164) — a roadmap line, or which door it left by.
179
+ where: Where = Where.OPEN
180
+ #: The marker the line carries, or empty where no line carries the id.
181
+ marker: str = ""
182
+ block: str = ""
183
+ #: The paths this row says its commit owns (RK280), in the order they were declared.
184
+ paths: tuple[str, ...] = ()
185
+
186
+ @property
187
+ def since(self) -> str:
188
+ return since(self.age)
189
+
190
+ @property
191
+ def placed(self) -> str:
192
+ """Where this row is, in one column (RK164).
193
+
194
+ An open line says so with its own marker and block; anything else says which **door**
195
+ it left by, which is the cause and not the consequence — and the marker column is
196
+ dropped rather than left blank, a gap reading as something that failed.
197
+
198
+ On the record since RK1170: the listing and the row's payload are two readings of one
199
+ fact, and a function in the door was where only one of them could reach it.
200
+ """
201
+ if self.where is Where.OPEN:
202
+ return f"{self.marker} Block {self.block}"
203
+ return str(self.where)
204
+
205
+ def payload(self) -> dict[str, object]:
206
+ """The same row as data. `marker` and `block` are null rather than empty where no line
207
+ carries the id, so a consumer tells "absent" from "blank"."""
208
+ return {
209
+ "id": self.id,
210
+ "state": str(self.state),
211
+ "where": str(self.where),
212
+ "age": round(self.age),
213
+ "since": self.since,
214
+ "marker": self.marker or None,
215
+ "block": self.block or None,
216
+ "paths": list(self.paths),
217
+ }
218
+
219
+ def listed(self, pruned: bool = False) -> str:
220
+ """One line of the registry listing (RK161, RK280).
221
+
222
+ The scope is **counted** here and named by `claim <id>`: this listing ranks nothing and
223
+ offers nothing, and four paths per row would make it the other command.
224
+ """
225
+ scoped = f" {len(self.paths)} path(s)" if self.paths else ""
226
+ state = "pruned" if pruned else str(self.state)
227
+ return f" {state:<8} {self.id} claimed {self.since} ago {self.placed}{scoped}"
228
+
229
+
230
+ @dataclass(frozen=True, slots=True)
231
+ class Registry:
232
+ """The claim registry read against the roadmap, as one answer (RK161).
233
+
234
+ A record since RK1170: the door held four values — the rows, what a `--prune` dropped, the
235
+ window and the file — and composed a header, a listing and a payload from them. Nothing
236
+ ranks and nothing is offered: `pick` decides what to work on, and a listing that answered
237
+ that would be a fourth tier nobody declared.
238
+ """
239
+
240
+ rows: tuple[Dated, ...]
241
+ #: What `--prune` took out, and `()` where the flag was not passed. Named and not counted,
242
+ #: and present as an empty list when the flag was passed and dropped nothing (RK165): a
243
+ #: prune that hides its own effect is how "the registry is clean" gets read off a command
244
+ #: that emptied it.
245
+ dropped: tuple[Dated, ...] = ()
246
+ pruned: bool = False
247
+ #: The file itself. Named because the release is a marker and this is what an operator
248
+ #: deletes when a whole checkout's worth of claims outlived their workers (RK161).
249
+ registry: str = ""
250
+ #: This project's window, in minutes — the number the ages above are read against.
251
+ window: int = 0
252
+
253
+ @property
254
+ def held(self) -> int:
255
+ return sum(1 for one in self.rows if one.state is State.HELD)
256
+
257
+ def stated(self) -> str:
258
+ rows = [f"{len(self.rows)} dated, {self.held} held (window {self.window}m)"]
259
+ rows += [one.listed() for one in self.rows]
260
+ rows += [one.listed(pruned=True) for one in self.dropped]
261
+ if self.pruned and not self.dropped:
262
+ rows.append(" pruned nothing: every row is a claim")
263
+ rows.append(f" registry {self.registry}")
264
+ return chr(10).join(rows)
265
+
266
+ def payload(self) -> dict[str, object]:
267
+ return {
268
+ "window": self.window,
269
+ "registry": self.registry,
270
+ "held": self.held,
271
+ "claims": [one.payload() for one in self.rows],
272
+ "pruned": None if not self.pruned else [one.payload() for one in self.dropped],
273
+ }
274
+
275
+
276
+ def survey(backlog: Backlog) -> tuple[Dated, ...]:
277
+ """Every dated id, oldest first, with what the files make of it (RK161).
278
+
279
+ The one question about a claim that was not a command: `pick` names the ready lines it
280
+ stepped around and its stalled list annotates a started one, so seeing *all* of them meant
281
+ two questions and a union — and neither reaches an entry on a line that is neither, which
282
+ is exactly the one somebody is looking for.
283
+
284
+ Takes the whole backlog and not the roadmap alone (RK164), because "no line carries this id"
285
+ is true of four situations and worth acting on in one: the ledger and the store say which
286
+ door the other three left by, and the reader scanning the column is deciding exactly that.
287
+
288
+ Oldest first, because the axis a reader is scanning is age: the entry most likely to belong
289
+ to a worker who is gone is the one at the top. It **ranks nothing and offers nothing** —
290
+ `pick` decides what to work on, and a listing that answered that would be a fourth tier
291
+ nobody declared. Deliberately not an MCP tool for the same reason: `pick` and `brief`
292
+ already name the claims an agent's own answer stepped around, and this is the read a person
293
+ makes about a checkout.
294
+ """
295
+ config = backlog.config
296
+ dated = _read(config.root)
297
+ if not dated:
298
+ return ()
299
+ tasks = {entry.task.id: entry.task for entry in backlog.roadmap.entries}
300
+ elsewhere = (
301
+ (Where.SHIPPED, backlog.shipped()),
302
+ (Where.RETIRED, backlog.retired()),
303
+ (Where.PAUSED, backlog.deferred()),
304
+ )
305
+ now, held = time.time(), window(config)
306
+ rows = [
307
+ _row(task_id, now - row.when, tasks.get(task_id), elsewhere, held, row.paths)
308
+ for task_id, row in dated.items()
309
+ ]
310
+ return tuple(sorted(rows, key=lambda row: -row.age))
311
+
312
+
313
+ def _row(
314
+ task_id: str,
315
+ age: float,
316
+ task: Task | None,
317
+ elsewhere: tuple[tuple[Where, object], ...],
318
+ held: float,
319
+ paths: tuple[str, ...] = (),
320
+ ) -> Dated:
321
+ """One registry entry as the two questions a reader is asking: is it a claim, and where."""
322
+ if task is None:
323
+ return Dated(
324
+ id=task_id,
325
+ age=age,
326
+ state=State.STALE,
327
+ where=next((name for name, ids in elsewhere if task_id in ids), Where.NOWHERE), # type: ignore[operator]
328
+ paths=paths,
329
+ )
330
+ if task.status != IN_PROGRESS:
331
+ state = State.STALE
332
+ else:
333
+ state = State.HELD if age < held else State.EXPIRED
334
+ return Dated(
335
+ id=task_id,
336
+ age=age,
337
+ state=state,
338
+ where=Where.OPEN,
339
+ marker=task.status,
340
+ block=task.block,
341
+ paths=paths,
342
+ )
343
+
344
+
345
+ @dataclass(frozen=True, slots=True)
346
+ class Pruning:
347
+ """What a prune left and what it dropped (RK165). Both, because a filter that hides its
348
+ own effect is how "the registry is clean" gets read off a command that emptied it."""
349
+
350
+ kept: tuple[Dated, ...] = ()
351
+ dropped: tuple[Dated, ...] = ()
352
+
353
+
354
+ def prune(config: Config) -> Pruning:
355
+ """Drop every row that is not a claim, and leave every row that is (RK165).
356
+
357
+ Loads the backlog inside its own lock (RK167), the way :func:`roadkeep.picking.take` does:
358
+ the read decides what is dropped, so a read outside the lock would decide from a state the
359
+ write no longer applies to. Re-entrant, so the dispatcher declaring the same thing about the
360
+ argv costs nothing twice — and a library caller gets the guarantee either way.
361
+
362
+ The reconciliation :func:`follow` performs, reachable without a marker to write. It exists
363
+ because the other remedy is the whole file: a checkout between tasks has no marker to move,
364
+ so clearing one row nobody can act on meant deleting the claims of every worker beside it —
365
+ a blast radius the size of the checkout for a problem the size of an id.
366
+
367
+ So it decides nothing new. What it keeps is what `follow` keeps: every id the roadmap still
368
+ carries at 🛠, which is a **live claim and an expired one alike** — an expired row is still a
369
+ statement about a started line, and the caller that wants it gone moves the marker. A live
370
+ claim is never dropped here; taking a line from a worker is a marker, and the door that
371
+ refuses it is the one RK160 closed.
372
+ """
373
+ with exclusive(config.root):
374
+ rows = survey(Backlog.load(config))
375
+ dropped = tuple(row for row in rows if row.state is State.STALE)
376
+ if dropped:
377
+ gone = {row.id for row in dropped}
378
+ kept = {n: r for n, r in _read(config.root).items() if n not in gone}
379
+ _write(config.root, kept)
380
+ return Pruning(
381
+ kept=tuple(row for row in rows if row.state is not State.STALE), dropped=dropped
382
+ )
383
+
384
+
385
+ def path(root: Path | str) -> Path:
386
+ """Where this checkout's claims are dated — in the shared store, beside its lock (RK330)."""
387
+ return store_path(root)
388
+
389
+
390
+ def live(config: Config, entries: Iterable[Entry]) -> tuple[Held, ...]:
391
+ """The claims still held, over the lines given, in the order they were given.
392
+
393
+ Read *against the lines* and never alone: a claim is a statement about a 🛠 line, so an
394
+ id whose marker has moved on is not held — which is what makes every existing marker
395
+ door a release, with nothing to wire and nothing to forget to call.
396
+ """
397
+ dated = _read(config.root)
398
+ if not dated:
399
+ return ()
400
+ now, held = time.time(), window(config)
401
+ return tuple(
402
+ Held(entry.task.id, now - row.when, row.paths)
403
+ for entry in entries
404
+ if entry.task.status == IN_PROGRESS
405
+ and (row := dated.get(entry.task.id)) is not None
406
+ and now - row.when < held
407
+ )
408
+
409
+
410
+ class Followed(StrEnum):
411
+ """What a marker write did to the claim on its line (RK158). Printed, so it is not silent."""
412
+
413
+ CLAIMED = "claimed"
414
+ RELEASED = "released"
415
+ NEITHER = ""
416
+
417
+
418
+ def refuse_taken(
419
+ config: Config, task_id: str, marker: str, entries: Iterable[Entry]
420
+ ) -> None:
421
+ """Refuse a marker write that would take a claim this line already carries (RK160).
422
+
423
+ Called **before** the write and never from inside :func:`follow`, which runs after one: a
424
+ refusal that arrives once the file has moved is a refusal about a state that already
425
+ happened. Beside :func:`~roadkeep.authoring.refuse_reuse` in shape and for the same
426
+ reason — the check that a write is allowed belongs at the write, not at whichever caller
427
+ remembered it.
428
+
429
+ Only the in-progress marker. Writing any other one is how a claim is *released*, and a
430
+ release that could be refused is a line nobody can give back.
431
+ """
432
+ if marker != IN_PROGRESS:
433
+ return
434
+ for one in live(config, entries):
435
+ if one.id == task_id:
436
+ raise AlreadyHeld(task_id, one.since, IN_PROGRESS)
437
+
438
+
439
+ def follow(
440
+ root: Path | str, task_id: str, marker: str, entries: Iterable[Entry]
441
+ ) -> Followed:
442
+ """Make the claim follow the marker, on any door that writes one (RK158).
443
+
444
+ A claim is *read* against 🛠, so the marker is already the thing a claim is about — and
445
+ until this existed, the door that writes exactly that marker was the one door that did not
446
+ date it: `status <id> 🛠` is a legitimate way to say "I am on this", and the next `pick`
447
+ read the line as work somebody abandoned and offered it with tier 1's own reason.
448
+
449
+ Both directions, because half of this rule was already implicit: writing 🛠 dates a claim
450
+ (again, if one had expired — a re-assertion is a new claim), and writing anything else
451
+ drops it, which is the release the read used to infer. `add` is deliberately not one of
452
+ these doors: the three ways to *start* work are the two `--claim` flags and this one, and a
453
+ line being created is not one the backlog was handing out.
454
+
455
+ **Every direction reconciles** (RK163), and that is the whole of what a write here does:
456
+ the entries are the truth, so what is kept is what they still carry at 🛠 — and the id being
457
+ followed is dated on top of that, or left out by having stopped being one of them. Dropping
458
+ a single key instead left every row *no door reported* in place, which a `git checkout`
459
+ creates and only a later claim used to clear. Nothing else writes a claim, for the reason
460
+ two entry points to one rule is how it comes to have two behaviours (RK159) —
461
+ :func:`rename` is not one of them, moving an address rather than following a marker.
462
+
463
+ It writes only when the result differs, so a project that never claims never gets a file:
464
+ a `status` on a backlog with no registry is a read and a comparison.
465
+
466
+ A **re-assertion keeps the paths** it was holding (RK280): the row is dated again, and the
467
+ scope the holder declared is a statement about the same work, not one the clock revokes.
468
+ A release drops the row and the paths with it, which is what makes a marker the only thing
469
+ that has to be remembered.
470
+ """
471
+ dated = _read(root)
472
+ started = {entry.task.id for entry in entries if entry.task.status == IN_PROGRESS}
473
+ kept = {name: row for name, row in dated.items() if name in started}
474
+ if marker == IN_PROGRESS:
475
+ was = dated.get(task_id)
476
+ kept[task_id] = Dating(time.time(), was.paths if was is not None else ())
477
+ if kept != dated:
478
+ _write(root, kept)
479
+ if marker == IN_PROGRESS:
480
+ return Followed.CLAIMED
481
+ return Followed.RELEASED if task_id in dated else Followed.NEITHER
482
+
483
+
484
+ class NotHeld(ValueError):
485
+ """Declaring a scope for a line nobody is holding (RK280).
486
+
487
+ Refused rather than taken, because taking is a **marker** and this door writes no marker:
488
+ a command that dated a claim as a side effect of naming files would be a second way to
489
+ start work, which is the shape RK158 spent a task removing. Says the door that does open.
490
+ """
491
+
492
+ def __init__(self, task_id: str) -> None:
493
+ self.task_id = task_id
494
+ super().__init__(
495
+ f"no live claim on {task_id}: a scope is what a claim carries, so take the "
496
+ f"line first with `status {task_id} {IN_PROGRESS}` (or `pick --claim`)"
497
+ )
498
+
499
+
500
+ def scope(
501
+ config: Config, task_id: str, paths: Iterable[str], *, extend: bool = False
502
+ ) -> tuple[str, ...]:
503
+ """Record the paths a held line's commit owns, and answer them back (RK280).
504
+
505
+ The write that was missing. RK117 locks a scan-to-save span and RK119 says who holds a
506
+ line, and both did their job — no governed file corrupted, no id spent twice — while two
507
+ sessions each committed a tree holding the other's source, because the commit step is a
508
+ `git add -A` in a shell script and nothing in the contract could name what belonged to
509
+ whom. `agents.md` carried the remedy as advice ("a tree holding unrelated work wants the
510
+ task's paths staged"), which is where L1's argument says advice does not hold: it is an
511
+ analysis to make at the moment of committing, out of a `git status` that shows both
512
+ sessions' work and says nothing about which is which.
513
+
514
+ So the claim carries it, because the claim is the one thing that already knows a line is
515
+ being worked on and by one worker. What is stored is what the holder **said**, verbatim
516
+ and in order: this never asks the disk whether a path exists, and never derives a path
517
+ from the task's prose. A scope inferred from a sentence would be RK55's guessing put in
518
+ charge of what a commit contains.
519
+
520
+ The **third** writer of the registry, and the exception is the same one :func:`rename`
521
+ takes: it writes no date. Dating is `follow`'s, so nothing here can start work, postpone
522
+ an expiry or take a line from the worker holding it — the invariant RK160 closed stays
523
+ exactly where it was. Refused on a line no live claim holds, for the same reason.
524
+
525
+ Replaces rather than appends, and `extend` does not change that (RK307). A scope is the
526
+ answer to *what is this commit*, and a call that only ever grew one would make a corrected
527
+ answer unreachable without the file — which is RK165's argument, one row along. What
528
+ `extend` changes is where the answer is composed: the caller that found a tenth path after
529
+ declaring nine says *and this too* rather than retyping the nine, and the row is still
530
+ replaced, with the whole scope. Measured across one block here: three of five tasks needed
531
+ a second call, one of them ten paths long.
532
+
533
+ **One door and a parameter, not a second function** (RK159): the two are distinguishable
534
+ at the call site and identical at the write, so the invariants below — the refusal on a
535
+ line nobody holds, the untouched date, the collapse — are stated once and cannot come to
536
+ have two behaviours. The **existing paths come first**, because they were declared first
537
+ and the answer is read in the order it will be staged.
538
+
539
+ Duplicates collapse, order kept, because the answer is consumed by a `git add --` and a
540
+ path staged twice is noise in a contract meant to be read.
541
+ """
542
+ named = tuple(one for one in paths if one)
543
+ with exclusive(config.root):
544
+ backlog = Backlog.load(config)
545
+ if not any(one.id == task_id for one in live(config, backlog.roadmap.entries)):
546
+ raise NotHeld(task_id)
547
+ dated = _read(config.root)
548
+ row = dated[task_id]
549
+ # Read inside the lock, like everything else this decides from: a scope composed from
550
+ # a row read outside it would drop whatever another call added in between.
551
+ wanted = tuple(dict.fromkeys((*row.paths, *named) if extend else named))
552
+ dated[task_id] = Dating(row.when, wanted)
553
+ _write(config.root, dated)
554
+ return wanted
555
+
556
+
557
+ def elsewhere(config: Config, task_id: str, entries: Iterable[Entry]) -> tuple[Held, ...]:
558
+ """Every *other* live claim that has declared a scope, so a commit can leave it alone.
559
+
560
+ The half a claim could not answer before (RK280). A claim names nobody by design (RK119),
561
+ so no write can be refused on the grounds that it is somebody else's — the guard sees a
562
+ path and not a worker, and a session cannot be told it is not itself. What *is* decidable
563
+ is the reverse: given the id being committed, every path some other held line says is its
564
+ own. That is a list the caller subtracts, and it is why this closes at the commit rather
565
+ than at the write.
566
+
567
+ Claims with no scope are left out, and the omission is the honest one: silence is a
568
+ holder who has not said, not a holder claiming nothing, so a caller that treated it as
569
+ the second would be answering with a confidence the registry does not carry.
570
+ """
571
+ return tuple(
572
+ one for one in live(config, entries) if one.id != task_id and one.paths
573
+ )
574
+
575
+
576
+ @dataclass(frozen=True, slots=True)
577
+ class Scope:
578
+ """A dirty tree split by which claim speaks for each path (RK280, RK294).
579
+
580
+ Three lists and not one, because the caller does three different things with them:
581
+ stage :attr:`mine`, leave :attr:`theirs`, and *decide* about :attr:`loose`. The third is
582
+ the list the incident was made of — a path in neither scope is one `git add -A` takes
583
+ silently — so it is named rather than counted.
584
+ """
585
+
586
+ #: What the claim being committed says its commit owns, in the order it was declared.
587
+ mine: tuple[str, ...] = ()
588
+ #: `(path, holder)` for every changed path some *other* live claim covers. The **changed**
589
+ #: path and never the declaration it fell under (RK495): what a caller leaves alone is a
590
+ #: file, and a holder who scoped `src/` would otherwise be reported as holding nothing.
591
+ theirs: tuple[tuple[str, str], ...] = ()
592
+ #: Changed paths no live claim covers at all — by name or by the directory above them, and
593
+ #: whose change this id does not already explain (`accounted`, RK1117).
594
+ loose: tuple[str, ...] = ()
595
+ #: Declared paths that would stage nothing right now (RK295) — in neither the dirty set
596
+ #: nor the index. A subset of :attr:`mine`, in the order it was declared, because this is
597
+ #: a reading *of* the declaration and not a fourth list beside it.
598
+ idle: tuple[str, ...] = ()
599
+ #: `(path, ids)` for a governed file whose change this id explains **and** that another
600
+ #: session's line arrived in or left (RK1120). Not a fourth kind of ownership: the file is
601
+ #: staged either way, so what this carries is the ids inside it that are nobody's business
602
+ #: here — the half :attr:`loose` cannot reach, a roadmap always naming this id.
603
+ shared: tuple[tuple[str, tuple[str, ...]], ...] = ()
604
+ #: Which of :attr:`loose` the **index** already carries (RK1197). Not a sixth list: a
605
+ #: staged loose path is the same finding one degree louder, because a `git commit` takes
606
+ #: it whether or not the author reads a diff — and the diff they are reading is the other
607
+ #: side. Measured twice in one session as a version literal another process staged.
608
+ staged: tuple[str, ...] = ()
609
+
610
+ @property
611
+ def spoken(self) -> bool:
612
+ """Whether any live claim declared a path — the condition a volunteered read has.
613
+
614
+ `claim <id>` was *asked*, so it answers either way. A verb that reports this without
615
+ being asked has nothing to subtract the tree from when no claim spoke, and its whole
616
+ answer would be `git status` restated under a heading saying "loose".
617
+ """
618
+ return bool(self.mine or self.theirs)
619
+
620
+
621
+ @dataclass(frozen=True, slots=True)
622
+ class Claimed:
623
+ """One held line's scope as `claim <id>` answers it (RK280, RK294, RK342).
624
+
625
+ The result that read had none of (RK1170). `Scope` is the *subtraction* and is shared with
626
+ a departure; what this adds is the two things only this door has — the id it was asked
627
+ about, and what this task's own transactions already wrote — and the three registers that
628
+ were composed from all of it inside the handler.
629
+ """
630
+
631
+ task_id: str
632
+ scope: Scope
633
+ #: The governed files this task's own transactions wrote (RK342), by the reading `ship`
634
+ #: makes off its own `save`. Named rather than folded into `mine`, for the reason a
635
+ #: departure keeps them apart (RK309): the scope is what the holder *said*, verbatim, and
636
+ #: these are not a declaration to be corrected but a record to be used.
637
+ wrote: tuple[str, ...] = ()
638
+
639
+ def porcelain(self) -> str:
640
+ """Nothing but the paths, in `git add --` order.
641
+
642
+ This form is consumed by a shell, so a heading on it would be a filename — the
643
+ contract has to be safe to pipe. The written ones join it for the reason they join the
644
+ staging line: what the author does with both lists is the same `git add`.
645
+ """
646
+ return chr(10).join(dict.fromkeys((*self.scope.mine, *self.wrote)))
647
+
648
+ def stated(self) -> str:
649
+ from roadkeep.rendering import _scope_rows # noqa: PLC0415 - RK260
650
+
651
+ idle = set(self.scope.idle)
652
+ rows = [f"{self.task_id} claims {len(self.scope.mine)} path(s)"]
653
+ # Annotated where it stands, and not listed again below (RK295): the mistyped path and
654
+ # the real one are two lines apart, and the eye reads the second as somebody else's
655
+ # unless the first says what is wrong with it.
656
+ rows += [
657
+ f" mine {one}{' (stages nothing right now)' if one in idle else ''}"
658
+ for one in self.scope.mine
659
+ ]
660
+ rows += [
661
+ f" wrote {one} (this task's own transactions)" for one in self.wrote
662
+ ]
663
+ rows += _scope_rows(self.scope, self.wrote)
664
+ if not self.scope.mine:
665
+ rows.append(
666
+ f" none declared: `claim {self.task_id} --path <p>` says what this "
667
+ f"commit owns"
668
+ )
669
+ return chr(10).join(rows)
670
+
671
+ def payload(self) -> dict[str, object]:
672
+ return {
673
+ "id": self.task_id,
674
+ "paths": list(self.scope.mine),
675
+ # Its own key and never merged into `paths` (RK309, RK342): a client that read them
676
+ # as one would be handed a scope this tool never received, and the two answer
677
+ # different questions.
678
+ "wrote": list(self.wrote),
679
+ "theirs": [
680
+ {"path": one, "claimed_by": who} for one, who in self.scope.theirs
681
+ ],
682
+ "unclaimed": list(self.scope.loose),
683
+ # Which of them the index already carries (RK1197), the key a departure answers
684
+ # under the same name: a client acting on `unclaimed` decides, and one acting on
685
+ # this has already been committed to by a `git add`.
686
+ "unclaimed_staged": list(self.scope.staged),
687
+ # The same list a departure carries, and computed here since RK1122: the two
688
+ # readers of one contract answering differently was the defect.
689
+ "shared": [
690
+ {"path": one, "ids": list(named)} for one, named in self.scope.shared
691
+ ],
692
+ "staging_nothing": list(self.scope.idle),
693
+ }
694
+
695
+
696
+ def split(
697
+ config: Config,
698
+ task_id: str,
699
+ entries: Iterable[Entry],
700
+ changed: Iterable[str],
701
+ tracked: Iterable[str] = (),
702
+ accounted: Iterable[str] = (),
703
+ shared: Iterable[tuple[str, tuple[str, ...]]] = (),
704
+ staged: Iterable[str] = (),
705
+ ) -> Scope:
706
+ """Split the changed paths by whose claim names them (RK280, RK295).
707
+
708
+ Pure over `changed` and `tracked`: git is the caller's to ask, because the two callers ask
709
+ it under different conditions — one was told to, the other only where a claim spoke. What
710
+ is shared, and the reason this is a function rather than a second composition at each call
711
+ site, is the *subtraction* — lists that have to stay disjoint and stay in the same order
712
+ in both answers.
713
+
714
+ `accounted` is the third subtraction and the one RK1117 moved here: paths whose change
715
+ **this id already explains**, so they are not reported as belonging to nobody. It used to
716
+ be done by each printer, filtering `loose` against what the caller called written — and the
717
+ two callers mean different things by that word. `claim <id>` means "its diff carries this
718
+ id" (:func:`written`), which is the predicate; `ship` means "this transaction wrote it",
719
+ which is not. So a governed file that a departure wrote *and* that was already dirty with
720
+ another session's work was reported as written and never as loose, and the `git add --`
721
+ line took both. Measured here: a filing of RK1116 landed inside RK1112's commit.
722
+
723
+ `tracked` is the index, and it is what makes :attr:`Scope.idle` a fact rather than a
724
+ guess: a declared path that is dirty stages itself, and one the index carries is a real
725
+ file whose name was not mistyped. A caller that omits it gets no idle reading at all
726
+ rather than one made against half the evidence — the empty default is the honest failure,
727
+ since every path would otherwise read as staging nothing.
728
+
729
+ `shared` is :func:`sharing`'s answer, passed in for the same reason `changed` is: it asks
730
+ git, and this function's purity is what lets one caller be told to answer and the other
731
+ answer only where a claim spoke. Carried through rather than composed by each caller so
732
+ the whole :class:`Scope` is assembled in one place — five lists that have to stay
733
+ consistent with each other, and two assemblies of them is how they come to differ.
734
+
735
+ All three lists ask :func:`_covers`, which is the whole of RK495: they used to, between
736
+ them, read a declared directory two ways — `idle` as the `git add --` it becomes, and the
737
+ other two as a filename — so a claim on `src/` printed the staging line that takes
738
+ `src/a.py` and, three lines below it, reported `src/a.py` as named by nobody.
739
+ """
740
+ entries = tuple(entries)
741
+ rows = live(config, entries)
742
+ mine = next((one.paths for one in rows if one.id == task_id), ())
743
+ others = elsewhere(config, task_id, entries)
744
+ changed = frozenset(changed)
745
+ known = changed | frozenset(tracked)
746
+ theirs = tuple(
747
+ (one, other.id)
748
+ for one in sorted(changed)
749
+ for other in others
750
+ if any(_covers(declared, one) for declared in other.paths)
751
+ )
752
+ named = (*mine, *(one for other in others for one in other.paths))
753
+ explained = frozenset(accounted)
754
+ adrift = tuple(
755
+ one
756
+ for one in sorted(changed)
757
+ if one not in explained
758
+ and not any(_covers(declared, one) for declared in named)
759
+ )
760
+ return Scope(
761
+ mine=mine,
762
+ theirs=theirs,
763
+ loose=adrift,
764
+ # A subset of `loose` and in its order (RK1197), which is what keeps it from being a
765
+ # sixth list: the question is not *what else is staged* — `mine` is, and should be —
766
+ # but which of the paths nobody claims the next commit already carries.
767
+ staged=tuple(one for one in adrift if one in set(staged)),
768
+ idle=() if not known else tuple(one for one in mine if not _stages(one, known)),
769
+ shared=tuple(shared),
770
+ )
771
+
772
+
773
+ def _covers(declared: str, path: str) -> bool:
774
+ """Does a scope that declared ``declared`` speak for ``path`` (RK495)?
775
+
776
+ One reading, asked by every list :func:`split` returns, because a scope is a `git add --`
777
+ argument and that command answers this question the same way whichever list is about to
778
+ quote it. A **directory** is a legitimate scope — git lists neither `status` nor
779
+ `ls-files` by one, so a declared `docs/` compared as a filename matches nothing at all —
780
+ and the trailing slash is the author's spelling rather than a fact, so it comes off before
781
+ the prefix is built and `src` covers what `src/` does.
782
+
783
+ Prefix and not `startswith` alone: `src/` must not answer for `srcfoo/a.py`, which is a
784
+ different directory whose name begins the same way.
785
+
786
+ And **either side may be the directory** (RK1137), which is RK495's question from the other
787
+ end. Git collapses an untracked tree to its topmost new directory — `?? .claude/skills/` —
788
+ so a claim naming the file the write created was compared against a shorter string and
789
+ matched nothing: RK1136's own ship reported that file as `loose` *and* its declaration as
790
+ staging nothing, two wrong lines about one path.
791
+
792
+ The trailing slash is what makes the third case safe rather than a widening. Git spells a
793
+ collapsed tree with one and a dirty **file** never carries one, so `declared.startswith(path)`
794
+ fires exactly where the listed path is a directory standing for everything under it — and a
795
+ claim on `src/a.py` still does not answer for a tracked `src/` holding somebody else's edit,
796
+ because git lists that as `src/other.py`.
797
+ """
798
+ if path == declared or path.startswith(declared.rstrip("/") + "/"):
799
+ return True
800
+ return path.endswith("/") and declared.startswith(path)
801
+
802
+
803
+ def _stages(one: str, known: frozenset[str]) -> bool:
804
+ """Would `git add -- <one>` put anything in the next commit (RK295)?
805
+
806
+ The same question :func:`_covers` answers, asked over the whole tree instead of about one
807
+ path: a declaration stages something exactly where it covers a path git already knows —
808
+ dirty or in the index. Kept as its own name because what it reports is about the
809
+ *declaration* (a scope that would stage nothing is a typo) and not about the file.
810
+ """
811
+ return any(_covers(one, other) for other in known)
812
+
813
+
814
+ def writable(config: Config) -> tuple[str, ...]:
815
+ """Every path a verb of this tool can leave bytes in, as the project spells them (RK342).
816
+
817
+ The governed files plus the projections RK188 refreshes with them. Narrow on purpose: the
818
+ claim of :func:`written` is that *this tool wrote it*, and a source file whose diff cites
819
+ the id is the author's work and not this tool's — calling it written would put the tool's
820
+ signature on somebody's code. So the candidate set is what a verb could have produced, and
821
+ the diff then says which of those this task's own transaction did.
822
+ """
823
+ # Deferred: `exporting` reaches the write path, which reaches this module (RK260).
824
+ from roadkeep.exporting import DEFAULTS # noqa: PLC0415
825
+
826
+ out = [
827
+ config.relative(config.path(role)) for role in ROLES if config.has(role)
828
+ ]
829
+ # A literal name only: a role's own file is already in the loop above, and listing it twice
830
+ # would report one path as two scopes (RK1110).
831
+ out += [kind.name for kind in DEFAULTS.values() if kind.name]
832
+ return tuple(dict.fromkeys(out))
833
+
834
+
835
+ def written(config: Config, task_id: str, changed: Iterable[str]) -> tuple[str, ...]:
836
+ """The changed paths this task's own transactions wrote (RK342).
837
+
838
+ `ship` answers this off :meth:`~roadkeep.shipping.Departure.save`'s own return, which is
839
+ the better source and only exists inside a transaction. `claim <id>` is asked *between*
840
+ them, so the record it has is the files themselves: a claim moved a marker onto this line
841
+ and the projections were refreshed from it, and both diffs therefore name the id.
842
+
843
+ Two readings and not one, because the tool's signature is the whole point — a path is
844
+ written only where it is both something a verb could have produced (:func:`writable`) and
845
+ something whose diff carries this id (:func:`~roadkeep.history.carrying`). Either alone is
846
+ the repair RK342 names and refuses: every dirty governed file hands one session another's
847
+ `add`, and every dirty file carrying the id claims authorship of somebody's code.
848
+
849
+ A **third** since RK1126, and it is the same claim through the one carrier where the id is
850
+ not on the line: a rationale file edited inside this id's own section carries the id in no
851
+ changed line, because a heading is what carries one. So
852
+ :func:`~roadkeep.history.owned_edit` reads the span instead, and it is asked only of a prose
853
+ path that is dirty and that the first reading did not already name — two subprocesses on the
854
+ turn somebody edited a design, and none on any other.
855
+ """
856
+ # Deferred for RK260's reason, and because git belongs on no path that did not ask.
857
+ from roadkeep.history import carrying, owned_edit # noqa: PLC0415
858
+
859
+ changed = frozenset(changed)
860
+ candidates = [one for one in writable(config) if one in changed]
861
+ named = set(carrying(config, task_id, candidates))
862
+ named.update(
863
+ config.relative(config.path(role))
864
+ for role in PROSE_ROLES
865
+ if config.has(role)
866
+ and (where := config.relative(config.path(role))) in changed
867
+ and where not in named
868
+ and owned_edit(config, "HEAD", task_id, role)
869
+ )
870
+ # In `writable`'s order and never in the order the two readings answered: the list is read
871
+ # against a `git add --` line, and a path's place in it is not a fact about which reading
872
+ # found it.
873
+ return tuple(one for one in candidates if one in named)
874
+
875
+
876
+ def departing(config: Config, task_id: str, entries: Iterable[Entry]) -> Scope | None:
877
+ """The same split, asked at the moment a line leaves the roadmap (RK294).
878
+
879
+ RK280 gave a claim the paths its commit owns and gave `claim <id>` the read that names
880
+ what the tree holds for somebody else, and left it with no caller: the declaration was
881
+ asked for in `agents.md` and in the skill, which is advice about what to do at the moment
882
+ of committing — where the analysis is expensive and the author is already finishing. A
883
+ departure *is* that moment, and it holds the id.
884
+
885
+ `None` where **no live claim declared a path**, which is every project that has not
886
+ adopted this. Silence and not an empty answer: there is nothing to subtract the tree
887
+ from, so the honest report is no report — and the git process is not paid for either.
888
+
889
+ It derives nothing. A departure that filed the dirty paths under the id that is leaving
890
+ would answer the question the incident asked — which of these is mine — by assuming it,
891
+ and the two sessions this exists to separate would each get the other's files with the
892
+ tool's signature on it.
893
+
894
+ What this id **already explains** is asked here and not left to the printer (RK1117), and
895
+ asked of the tree *before* the transaction writes: a governed file dirty at this moment is
896
+ dirty from something else, and :func:`written` says whether that something names this id.
897
+
898
+ That reading is per **file**, and the roadmap is a file this task is always named in — the
899
+ marker that took the line is in the same diff — so RK1117 left the id inside it unreachable.
900
+ :attr:`Scope.shared` is that half (RK1120): for each carrier this id explains,
901
+ :func:`~roadkeep.history.ids_since` says which *other* ids gained or lost a line since HEAD,
902
+ which two parses answer and no textual reading can — an annotation refresh names every
903
+ dependent in an added line and moves none of them.
904
+ """
905
+ entries = tuple(entries)
906
+ if not any(one.paths for one in live(config, entries)):
907
+ return None
908
+ # Imported here for the reason :mod:`roadkeep.provenance` does it (RK260): this is the
909
+ # only function in the file that asks git anything, and every other reader of a claim —
910
+ # `pick`, `brief`, every marker write — would otherwise pay for the wrapper.
911
+ from roadkeep.history import indexed, status # noqa: PLC0415
912
+
913
+ seen = status(config)
914
+ accounted = written(config, task_id, seen.changed)
915
+ return split(
916
+ config,
917
+ task_id,
918
+ entries,
919
+ seen.changed,
920
+ indexed(config),
921
+ accounted=accounted,
922
+ shared=sharing(config, task_id, accounted),
923
+ staged=seen.staged,
924
+ )
925
+
926
+
927
+ def sharing(
928
+ config: Config, task_id: str, accounted: Iterable[str]
929
+ ) -> tuple[tuple[str, tuple[str, ...]], ...]:
930
+ """Per governed file this id explains, the other ids whose line moved in it (RK1120).
931
+
932
+ Its own function since RK1122, because **both** readers of the commit contract want it and
933
+ only one had it: `claim <id>` computed no `shared` at all — an empty list on every call —
934
+ while being the read a commit is actually composed from, `--porcelain` existing to be piped
935
+ into `git add --`. A departure *must* answer, the claim being released after it; this one is
936
+ asked, so it answers either way, which makes it the cheaper place for the warning and not
937
+ the one to leave it out of.
938
+
939
+ Only the files this id already explains (`accounted`): one it does not is reported whole by
940
+ :attr:`Scope.loose`, and naming the ids inside it as well would be one fact under two
941
+ headings.
942
+
943
+ Every governed file that can hold a record, in the unit that file keeps it in (RK1125): a
944
+ carrier holds **lines** and :func:`~roadkeep.history.ids_since` reads them, a rationale file
945
+ holds **sections** and :func:`~roadkeep.history.designs_since` reads those. Restricting this
946
+ to the carriers left the prose file a departure wrote unreadable for the same reason the
947
+ roadmap was — one `section amend` puts this id in its diff, and everything else inside it
948
+ then went unnamed.
949
+ """
950
+ # Deferred for RK260's reason, and because git belongs off every path that did not ask.
951
+ from roadkeep.history import designs_since, ids_since, resolves # noqa: PLC0415
952
+
953
+ readers = {
954
+ **dict.fromkeys(CARRIERS, ids_since),
955
+ **dict.fromkeys(PROSE_ROLES, designs_since),
956
+ }
957
+ explained = frozenset(accounted)
958
+ wanted = [
959
+ role
960
+ for role in readers
961
+ if config.has(role) and config.relative(config.path(role)) in explained
962
+ ]
963
+ if not wanted:
964
+ # Nothing to compare, so nothing is asked of git at all — the common case on a tree
965
+ # holding only this task's work, and the reason the loop is not entered to find out.
966
+ return ()
967
+ # Once, and passed down (RK1124): whether git knows `HEAD` is a fact about the repository,
968
+ # and a `rev-parse` per role was 40.6ms of an answer already in hand.
969
+ known = resolves(config, "HEAD")
970
+ out: list[tuple[str, tuple[str, ...]]] = []
971
+ for role in wanted:
972
+ moved = readers[role](config, "HEAD", role, resolved=known) - {task_id}
973
+ if moved:
974
+ out.append((config.relative(config.path(role)), tuple(sorted(moved))))
975
+ return tuple(out)
976
+
977
+
978
+ def rename(root: Path | str, old: str, new: str) -> bool:
979
+ """Carry a claim to the id its line was moved to (RK156). True where one moved.
980
+
981
+ The exception to "every marker door is a release": `renumber` does not move the marker,
982
+ it moves the **address**, so the registry keeps an id no line carries while the new one
983
+ reads as started work nobody holds — which is RK119's defect reopened by the one command
984
+ that exists because a merge spent an id twice. The date travels rather than restarting:
985
+ the work is the same age, and a claim that renewed itself on a rename would be an expiry
986
+ a rename could postpone for ever.
987
+
988
+ It re-addresses and does not reconcile, unlike :func:`follow` (RK163): the lines are not in
989
+ hand here, and a rename is rare while the next marker write is not — so a row this leaves
990
+ unpruned is cleared by the first `ship` or `status` after it.
991
+ """
992
+ dated = _read(root)
993
+ row = dated.pop(old, None)
994
+ if row is None:
995
+ return False
996
+ dated[new] = row
997
+ _write(root, dated)
998
+ return True
999
+
1000
+
1001
+ def _read(root: Path | str) -> dict[str, Dating]:
1002
+ """This checkout's claims, out of the shared store — empty where it cannot be read.
1003
+
1004
+ The grammar, the atomic replace and the "unreadable is empty" rule all belong to
1005
+ :mod:`roadkeep.storing` now (RK330); what stays here is the one table this module owns.
1006
+ """
1007
+ return dict(read(root).claims)
1008
+
1009
+
1010
+ def _write(root: Path | str, dated: Mapping[str, Dating]) -> None:
1011
+ """Replace the claims table, and leave every other table exactly as it was.
1012
+
1013
+ Read-modify-write, which is safe for the reason it is safe everywhere else here: every
1014
+ writer of the store runs under the checkout's exclusive lock (:func:`roadkeep.cli.dispatch`),
1015
+ so nothing can land between the read and the replace. A claim that dropped the write
1016
+ record on its way past would be the digest sidecar's data lost to the registry's write —
1017
+ the failure a shared file has and two files did not, closed at the one door that writes.
1018
+ """
1019
+ write(root, Store(claims=dict(dated), writes=read(root).writes))