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/history.py ADDED
@@ -0,0 +1,2403 @@
1
+ """Reaching the reasoning behind a shipped decision (RK31).
2
+
3
+ Shipping deletes the rationale section, the ledger keeps one line, and the argument
4
+ survives only in a commit message. That is not a bad place to keep it — it is the one
5
+ place that cannot drift from the code — but it is unreachable in practice: answering
6
+ "why is this like this" costs a `git log -S` over the whole history, so the question
7
+ goes unasked and the design gets re-litigated instead.
8
+
9
+ **The pointer is derived, not stored.** The obvious design — write the shipping commit's
10
+ hash into the ledger entry — is wrong, and the objection is decisive: `squash`, `amend`
11
+ and `rebase` rewrite that hash, and a dead hash reads exactly like a live one. A stored
12
+ pointer would rot silently, which is worse than no pointer at all.
13
+
14
+ So resolve it from git on demand. The commit that shipped a task is, by construction,
15
+ the commit that **added its id to the ledger**, and the commit that proposed it is the
16
+ one that added the id to the roadmap. Both are found with `git log -S` scoped to one
17
+ file, both are correct after any history rewrite, and neither costs a byte in the
18
+ documents. It also works retroactively: every task shipped before this module existed
19
+ is already addressable.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import re
25
+ import shutil
26
+ import subprocess
27
+ from collections.abc import Sequence
28
+ from dataclasses import dataclass, replace
29
+ from pathlib import Path
30
+
31
+ from roadkeep.config import PROSE_ROLES, Config
32
+ from roadkeep.kernel.document import Document
33
+ from roadkeep.kernel.schema import ARROW, REF_SEPARATOR, Schema, split_ref
34
+ from roadkeep.sections import Section, anchored, find, owners
35
+
36
+ _UNIT = "\x1f" # between fields
37
+ _RECORD = "\x1e" # between commits — a body may hold newlines, so lines will not do
38
+ _FORMAT = _UNIT.join(["%H", "%h", "%aI", "%an", "%s", "%b"]) + _RECORD
39
+ _TIMEOUT = 20
40
+ #: What `-z` separates paths by, on both ends of `check-ignore` (RK213).
41
+ _NUL = chr(0)
42
+
43
+
44
+ class HistoryUnavailable(RuntimeError):
45
+ """No git, or no repository — the answer is absent rather than negative."""
46
+
47
+
48
+ @dataclass(frozen=True, slots=True)
49
+ class Commit:
50
+ sha: str
51
+ short: str
52
+ date: str
53
+ author: str
54
+ subject: str
55
+ body: str
56
+
57
+ @property
58
+ def reasoning(self) -> str:
59
+ """Subject plus body: the part a ledger line cannot hold."""
60
+ return f"{self.subject}\n\n{self.body}".strip()
61
+
62
+
63
+ @dataclass(frozen=True, slots=True)
64
+ class Origin:
65
+ """Where a task entered the backlog, and where it left it."""
66
+
67
+ task_id: str
68
+ proposed_in: Commit | None
69
+ shipped_in: Commit | None
70
+
71
+
72
+ def git_available() -> bool:
73
+ return shutil.which("git") is not None
74
+
75
+
76
+ def _run(root: Path, *args: str, fed: Sequence[str] = ()) -> str:
77
+ return _bytes(root, *args, fed=fed).decode("utf-8", errors="replace")
78
+
79
+
80
+ def _bytes(root: Path, *args: str, fed: Sequence[str] = ()) -> bytes:
81
+ """The raw output, because one caller reads a file and not a report (RK84).
82
+
83
+ Bytes and not ``text=True``: universal newlines would translate CRLF to LF, and a
84
+ baseline that read the file at a revision through that translation would report every
85
+ ending as changed — on the two things `lint` measures in bytes, the round-trip (L3)
86
+ and a budget (RK30). Text callers decode here instead, which is the same string
87
+ `text=True` gave them minus the rewriting.
88
+
89
+ ``fed`` is the revisions a `--stdin` call reads, and it is the one thing here that is
90
+ **not** argv (RK1315). A list handed as arguments is bounded by the operating system:
91
+ measured on this repository at the commit that crossed it — 802 ledger entries, 798
92
+ distinct commits, 32,718 characters of shas alone against Windows' 32,767 — where
93
+ `weigh` stopped answering with `HistoryUnavailable`, which its caller reports as an
94
+ absent answer. So the verb that says what a comparable task cost failed at exactly the
95
+ ledger size that makes the question worth asking, and POSIX reaches its own `ARG_MAX`
96
+ later rather than never. Fed on stdin the list has no ceiling and the call count does
97
+ not grow with the file, which is the property `costs_of` was written for.
98
+ """
99
+ if not git_available():
100
+ raise HistoryUnavailable("git is not on PATH")
101
+ try:
102
+ # Fixed argv and shell=False: nothing here interpolates into a shell.
103
+ result = subprocess.run(
104
+ ["git", "-C", str(root), *args],
105
+ capture_output=True,
106
+ timeout=_TIMEOUT,
107
+ check=False,
108
+ # `b"\n".join` and not a text `input`: this call is byte-oriented on purpose,
109
+ # and a rev is ASCII — encoding it here keeps the one decode at the boundary.
110
+ input=b"\n".join(one.encode("utf-8") for one in fed) if fed else None,
111
+ )
112
+ except (OSError, subprocess.TimeoutExpired) as error:
113
+ raise HistoryUnavailable(str(error)) from error
114
+ if result.returncode != 0:
115
+ raise HistoryUnavailable(
116
+ result.stderr.decode("utf-8", errors="replace").strip() or "git failed"
117
+ )
118
+ return result.stdout
119
+
120
+
121
+ def _parse(output: str) -> tuple[Commit, ...]:
122
+ commits: list[Commit] = []
123
+ for record in output.split(_RECORD):
124
+ record = record.strip("\n")
125
+ if not record:
126
+ continue
127
+ fields = record.split(_UNIT)
128
+ if len(fields) < 6:
129
+ continue
130
+ sha, short, date, author, subject, body = fields[:6]
131
+ commits.append(
132
+ Commit(
133
+ sha=sha,
134
+ short=short,
135
+ date=date,
136
+ author=author,
137
+ subject=subject,
138
+ body=body.strip(),
139
+ )
140
+ )
141
+ return tuple(commits)
142
+
143
+
144
+ def commits_touching(
145
+ root: Path, needle: str, path: Path | None = None, *, literal: bool = True
146
+ ) -> tuple[Commit, ...]:
147
+ """Commits whose diff mentions ``needle`` at all, oldest first.
148
+
149
+ Two deliberate choices:
150
+
151
+ * **Not `--grep`.** Putting the id in the commit subject is a convention an author
152
+ can forget; a commit that moved a task's line *must* contain the id in its diff.
153
+ * **`-G`, not `-S`.** `-S` counts occurrences and reports only a *net* change, so
154
+ rewording a line — the id present before and after — is invisible to it. `-G`
155
+ matches any diff that mentions the id, which is what "every commit that touched
156
+ this task" means.
157
+
158
+ One thing neither flag can recover: if a task is proposed and shipped inside one
159
+ commit, the roadmap ends the commit as it began and there is no diff to find. The
160
+ squash destroyed that fact; the shipping commit, which is the one carrying the
161
+ reasoning, still resolves.
162
+
163
+ ``literal`` off hands the needle to git as the pattern it already is, for the one
164
+ caller with a shape rather than a string to find (RK212): a heading is spelled two ways
165
+ across live outline projects — `### VIII.1` in Shio and Turing, `### §I.1` in
166
+ claude-tray — and an escaped literal would answer for one of them and silently miss the
167
+ other, which a reader would read as "nobody ever wrote it".
168
+ """
169
+ args = ["log", "--reverse", f"--format={_FORMAT}"]
170
+ if not literal:
171
+ # git reads `-G` as a *basic* regex, where `?` is a literal character rather than a
172
+ # quantifier — so the optional sigil below would be searched for as a `?`.
173
+ args.append("--extended-regexp")
174
+ args += ["-G", re.escape(needle) if literal else needle]
175
+ if path is not None:
176
+ args += ["--", str(path)]
177
+ return _parse(_run(root, *args))
178
+
179
+
180
+ def check_ignore(root: Path, paths: Sequence[str]) -> frozenset[str]:
181
+ """Which of these paths the repository has declared it will never track (RK213).
182
+
183
+ `check-ignore` and not a table of directory names, because the repository already
184
+ carries the declaration: the same `.gitignore`, `.git/info/exclude` and
185
+ `core.excludesFile` a developer's own `git status` reads, so the gate and the author
186
+ cannot disagree about what is tracked here (L6, answered by the project rather than by
187
+ this tool). Exit 1 means *none matched*, which is an answer and not a failure — the only
188
+ reason this cannot go through :func:`_run`.
189
+
190
+ `-z` on both ends: a path holding a quote or a non-ASCII byte arrives as itself rather
191
+ than as git's escaped rendering, which is :func:`tracked_at`'s reason one command along.
192
+ """
193
+ if not paths:
194
+ return frozenset()
195
+ if not git_available():
196
+ raise HistoryUnavailable("git is not on PATH")
197
+ try:
198
+ result = subprocess.run(
199
+ ["git", "-C", str(root), "check-ignore", "--stdin", "-z"],
200
+ input=_NUL.join(paths).encode("utf-8"),
201
+ capture_output=True,
202
+ timeout=_TIMEOUT,
203
+ check=False,
204
+ )
205
+ except (OSError, subprocess.TimeoutExpired) as error:
206
+ raise HistoryUnavailable(str(error)) from error
207
+ if result.returncode not in (0, 1):
208
+ raise HistoryUnavailable(
209
+ result.stderr.decode("utf-8", errors="replace").strip() or "git failed"
210
+ )
211
+ listed = result.stdout.decode("utf-8", errors="replace")
212
+ return frozenset(name for name in listed.split(_NUL) if name)
213
+
214
+
215
+ #: What `check-attr` answers where a path has no value for the attribute at all.
216
+ UNSPECIFIED = "unspecified"
217
+
218
+
219
+ def check_attr(root: Path, attribute: str, paths: Sequence[str]) -> dict[str, str]:
220
+ """What git resolves `attribute` to for each of these paths (RK273).
221
+
222
+ `check-attr` and not a read of `<root>/.gitattributes`, because that file is not where the
223
+ answer lives: git consults a `.gitattributes` in every directory from the path upward, then
224
+ `$GIT_DIR/info/attributes`, then `core.attributesFile`, with the deepest rule winning. A
225
+ read of the root file alone reports files unsent that git sends — measured, with
226
+ `.git/info/attributes` carrying the line. The repository already holds the declaration, so
227
+ it is asked rather than guessed at, the same choice :func:`check_ignore` makes (L6).
228
+
229
+ The value is git's own word: a driver's name where one is set, or :data:`UNSPECIFIED`,
230
+ `set`, `unset`. Richer than the boolean a string comparison yields — a path sent to a
231
+ *different* driver is a deliberate act, and invisible to a read looking only for one name.
232
+
233
+ `-z`, for the reason :func:`check_ignore` gives one command along: a path holding a quote
234
+ or a non-ASCII byte arrives as itself and not as git's escaped rendering. The paths go as
235
+ arguments rather than down `--stdin`, because a project declares a handful of governed
236
+ files and that keeps this on :func:`_bytes` — the package's one place with a timeout, an
237
+ encoding and a single failure type.
238
+ """
239
+ if not paths:
240
+ return {}
241
+ listed = _bytes(root, "check-attr", "-z", attribute, "--", *paths).decode(
242
+ "utf-8", errors="replace"
243
+ )
244
+ # Triples, `<path>\0<attribute>\0<value>\0`, so the walk is by threes and not by lines —
245
+ # a value is one field of a record here, never a line of output.
246
+ fields = [field for field in listed.split(_NUL) if field != ""]
247
+ return {
248
+ fields[index]: fields[index + 2]
249
+ for index in range(0, len(fields) - 2, 3)
250
+ if fields[index + 1] == attribute
251
+ }
252
+
253
+
254
+ @dataclass(frozen=True, slots=True)
255
+ class Change:
256
+ """One changed line, numbered **on the side it exists on**.
257
+
258
+ Which side matters, and getting it wrong is what makes a diff-based check cry wolf: a
259
+ deleted paragraph has no line number in the file as it is now, so attributing it to
260
+ the new-side position lands it in whichever section happens to precede the hole.
261
+ """
262
+
263
+ lineno: int
264
+ text: str
265
+ #: True for a line the diff added (new side), False for one it removed (old side).
266
+ added: bool
267
+
268
+
269
+ @dataclass(frozen=True, slots=True)
270
+ class Touched:
271
+ """Every line a diff changed in one file (RK36)."""
272
+
273
+ changes: tuple[Change, ...] = ()
274
+
275
+ @property
276
+ def lines(self) -> tuple[str, ...]:
277
+ """The changed text, either side — added, removed or reworded.
278
+
279
+ All three mean somebody had the line open, which is the only thing the check is
280
+ entitled to conclude: deciding whether the edit was *responsive* would be reading
281
+ prose (L4).
282
+ """
283
+ return tuple(change.text for change in self.changes)
284
+
285
+
286
+ _HUNK_RE = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
287
+
288
+
289
+ def resolves(config: Config, rev: str) -> bool:
290
+ """Does git know this revision? False for `HEAD` in a repository with no commits."""
291
+ try:
292
+ _run(config.root, "rev-parse", "--verify", "--quiet", f"{rev}^{{commit}}")
293
+ except HistoryUnavailable:
294
+ return False
295
+ return True
296
+
297
+
298
+ def revisions_of(
299
+ config: Config, path: Path, first: int, last: int
300
+ ) -> tuple[Commit, ...]:
301
+ """Every commit that touched these lines of this file, oldest first (RK1163).
302
+
303
+ `-L` and not `-G`, which is the difference between a *span* and a mention: a section's
304
+ heading appears in the diff of the commit that wrote it and of nothing else, so a body-only
305
+ `section amend` — the ordinary way a design is revised — is invisible to a needle. That is
306
+ RK1126's finding one module over, and it is the whole reason this reads a range.
307
+
308
+ The range is the section's own span, resolved through history by git rather than by this
309
+ reader: `-L` follows the lines as the file moves around them, which no line number stored
310
+ here could. `-s` suppresses the diffs, since what is wanted is the commits.
311
+ """
312
+ where = str(path if not path.is_absolute() else path.relative_to(config.root))
313
+ return _parse(
314
+ _run(
315
+ config.root,
316
+ "log",
317
+ "--reverse",
318
+ "-s",
319
+ f"--format={_FORMAT}",
320
+ f"-L{first},{last}:{where}",
321
+ )
322
+ )
323
+
324
+
325
+ def precedes(config: Config, earlier: str, later: str) -> bool:
326
+ """Whether one commit is an ancestor of another — the ordering dates cannot give (RK1163).
327
+
328
+ Two commits made in the same second carry the same ISO timestamp, so a date compare answers
329
+ *no* about a design that plainly predates a ship; and a rebase can order dates against the
330
+ history. What git already knows is the ancestry, which is the question actually being asked:
331
+ was this written before that landed.
332
+
333
+ A commit is its own ancestor, so an identical pair answers True and the caller excludes it —
334
+ a design revised *in* the shipping commit has read what changed, which is the one case this
335
+ must not report.
336
+ """
337
+ if not earlier or not later:
338
+ return False
339
+ try:
340
+ _run(config.root, "merge-base", "--is-ancestor", earlier, later)
341
+ except HistoryUnavailable:
342
+ return False
343
+ return True
344
+
345
+
346
+ def touched_since(config: Config, rev: str, role: str) -> Touched:
347
+ """The diff of one governed file from ``rev`` to the working tree.
348
+
349
+ `-U0`, because context lines would put a neighbouring section inside the span and the
350
+ whole value of this check is that it names the section somebody actually opened.
351
+ """
352
+ if not config.has(role) or not config.path(role).is_file():
353
+ return Touched()
354
+ try:
355
+ relative = config.path(role).relative_to(config.root)
356
+ except ValueError:
357
+ relative = config.path(role)
358
+ output = _run(config.root, "diff", "--no-color", "-U0", rev, "--", str(relative))
359
+ return _read_diff(output)
360
+
361
+
362
+ def changed_paths(config: Config, rev: str) -> frozenset[str]:
363
+ """Every path this working tree changed against ``rev``, repo-relative (RK1228).
364
+
365
+ The half `--since` already had for the governed files, asked of the **rest of the tree**:
366
+ `touched_since` diffs one governed file to attribute a change to a section, and this is
367
+ the mirror question — what source moved while the backlog stood still.
368
+
369
+ Names and not hunks, because the question is *did anything under this task change* and a
370
+ line count would invite a threshold nobody could defend. Repo-relative and forward-slashed,
371
+ which is the spelling a section's own prose uses and what `paths_in` resolves to.
372
+
373
+ Empty where git cannot answer, which keeps the note silent: this reports a coincidence
374
+ worth a sentence, and a repository with no history has no coincidence to report.
375
+ """
376
+ try:
377
+ found = _run(config.root, "diff", "--name-only", rev)
378
+ except HistoryUnavailable:
379
+ return frozenset()
380
+ return frozenset(one.strip().replace("\\", "/") for one in found.splitlines() if one.strip())
381
+
382
+
383
+ def changed_lines(config: Config, rev: str, path: Path) -> frozenset[int] | None:
384
+ """Line numbers this working tree changed in one file against ``rev`` (RK60).
385
+
386
+ ``None`` means git cannot narrow this file — no history, no `git`, or a file it does not
387
+ track yet — and the caller then judges all of it, because a file nothing can diff is a
388
+ file nobody can be excused from.
389
+
390
+ A path and not a role, because the `Stop` gate also holds the instruction files a
391
+ `[budgets]` entry names (RK30), and those are governed by nothing.
392
+ """
393
+ try:
394
+ relative = path.resolve().relative_to(config.root)
395
+ except ValueError:
396
+ relative = path
397
+ try:
398
+ if not _run(config.root, "ls-files", "--", str(relative)).strip():
399
+ return None # untracked: every line of it arrived without a commit
400
+ output = _run(config.root, "diff", "--no-color", "-U0", rev, "--", str(relative))
401
+ except HistoryUnavailable:
402
+ return None
403
+ return frozenset(
404
+ change.lineno for change in _read_diff(output).changes if change.added
405
+ )
406
+
407
+
408
+ def _read_diff(output: str) -> Touched:
409
+ """Walk a `-U0` diff, numbering each changed line on its own side."""
410
+ changes: list[Change] = []
411
+ old = new = 0
412
+ for raw in output.splitlines():
413
+ hunk = _HUNK_RE.match(raw)
414
+ if hunk:
415
+ old, new = int(hunk.group(1)), int(hunk.group(3))
416
+ continue
417
+ if raw.startswith(("+++", "---")):
418
+ continue
419
+ if raw.startswith("+"):
420
+ changes.append(Change(lineno=new, text=raw[1:], added=True))
421
+ new += 1
422
+ elif raw.startswith("-"):
423
+ changes.append(Change(lineno=old, text=raw[1:], added=False))
424
+ old += 1
425
+ return Touched(changes=tuple(changes))
426
+
427
+
428
+ def content_at(config: Config, rev: str, role: str) -> str:
429
+ """One governed file as of ``rev``, or empty when it was not there yet.
430
+
431
+ Needed because a removal has to be attributed to the section that *held* it, and that
432
+ section may no longer exist — which is exactly the case `ship` produces, and the one a
433
+ check must not report (RK36).
434
+ """
435
+ if not config.has(role):
436
+ return ""
437
+ raw = blob_at(config, rev, config.path(role))
438
+ return "" if raw is None else raw.decode("utf-8", errors="replace")
439
+
440
+
441
+ def blob_at(config: Config, rev: str, path: Path) -> bytes | None:
442
+ """One file's bytes as of ``rev``, or ``None`` when that tree did not carry it (RK84).
443
+
444
+ The two answers are kept apart because a baseline turns on the difference: an empty
445
+ file was there and said nothing, and an absent one is a file the change *added* — so
446
+ crediting it with the findings of a file it did not have would forgive every line of
447
+ it. Bytes, because the caller measuring a budget is counting them (RK30).
448
+ """
449
+ try:
450
+ relative = path.resolve().relative_to(config.root)
451
+ except ValueError:
452
+ relative = path
453
+ try:
454
+ return _bytes(config.root, "show", f"{rev}:{relative.as_posix()}")
455
+ except HistoryUnavailable:
456
+ return None
457
+
458
+
459
+ def tracked_at(config: Config, rev: str) -> frozenset[str]:
460
+ """Every path in the tree at ``rev``, as git spells them (RK84).
461
+
462
+ One `ls-tree` rather than a question per path: a ledger names 886 of them on the corpus
463
+ this was measured against, and a subprocess each is the difference between a check and
464
+ a thing nobody runs. `-z`, so a path holding a quote or a non-ASCII byte arrives as
465
+ itself instead of as git's escaped rendering of it.
466
+ """
467
+ try:
468
+ output = _run(config.root, "ls-tree", "-r", "--name-only", "-z", rev)
469
+ except HistoryUnavailable:
470
+ return frozenset()
471
+ return frozenset(name for name in output.split("\0") if name)
472
+
473
+
474
+ def indexed(config: Config) -> frozenset[str]:
475
+ """Every path the index carries, including one deleted from the working tree (RK217).
476
+
477
+ :func:`tracked_now` without its subtraction, because the two answer different questions.
478
+ *Does the repository still have this artefact* must not credit a file somebody deleted
479
+ and did not stage — that is the finding the path check exists for. *Is this a directory
480
+ the repository knows about* must: a ledger naming `lib/gone.py` after `lib/` was removed
481
+ is precisely the case worth reporting, and a listing that had already forgotten `lib/`
482
+ would make the token stop being a claim rather than become a finding.
483
+ """
484
+ try:
485
+ listed = _run(config.root, "ls-files", "-z")
486
+ except HistoryUnavailable:
487
+ return frozenset()
488
+ return frozenset(name for name in listed.split(chr(0)) if name)
489
+
490
+
491
+ def tracked_now(config: Config) -> frozenset[str]:
492
+ """Every tracked path the working tree still **has**, as git spells them (RK173).
493
+
494
+ :func:`tracked_at`'s answer for the run that has no revision, and asked for the same
495
+ reason: two processes rather than a walk of the repository or a stat per path, so a
496
+ check over a ledger naming hundreds of artefacts stays a check rather than a thing
497
+ nobody runs. Git's own list, so a build directory nobody committed cannot satisfy a
498
+ claim about the source.
499
+
500
+ Minus what git calls deleted, which is the whole reason this is not `ls-files` alone:
501
+ the index still carries a file removed from the tree and not yet staged, and crediting
502
+ one would forgive exactly the finding this check exists for — an artefact that was there
503
+ at the revision and is gone now. :func:`indexed` is the same listing without that
504
+ subtraction, for the caller asking the other question.
505
+ """
506
+ listed = indexed(config)
507
+ if not listed:
508
+ return frozenset()
509
+ try:
510
+ removed = _run(config.root, "ls-files", "--deleted", "-z")
511
+ except HistoryUnavailable:
512
+ return frozenset()
513
+ gone = {name for name in removed.split(chr(0)) if name}
514
+ return frozenset(name for name in listed if name not in gone)
515
+
516
+
517
+ def dirty(config: Config) -> frozenset[str]:
518
+ """Every path the working tree has changed, staged or not, untracked included (RK280).
519
+
520
+ What a `git add -A` would put in the next commit, which is the list a scope is subtracted
521
+ from — so it has to be exactly that list and not a tidier one: an untracked file is the
522
+ new test somebody's session just wrote, and leaving it out would answer *your commit is
523
+ clean* about the tree that carried the defect this exists for.
524
+
525
+ `status --porcelain -z` and not a diff: one process, git's own spelling on every platform,
526
+ and the rename case arrives as both its ends, which is the honest reading when the
527
+ question is what a commit would touch. Empty where git cannot answer, the rule every
528
+ reader here keeps — a checkout with no git is one this reports nothing about, never one
529
+ it refuses.
530
+ """
531
+ return status(config).changed
532
+
533
+
534
+ def status(config: Config) -> Status:
535
+ """The porcelain read once, split by which side of the index each path changed on (RK1197).
536
+
537
+ One process for both answers rather than two for one each: the columns are in the same
538
+ record git already sent, and asking twice would be this module doing what it tells its
539
+ callers not to.
540
+ """
541
+ try:
542
+ listed = _run(config.root, "status", "--porcelain", "-z")
543
+ except HistoryUnavailable:
544
+ return Status()
545
+ return Status(*_read_status(listed))
546
+
547
+
548
+ @dataclass(frozen=True, slots=True)
549
+ class Status:
550
+ """A working tree as `git status` describes it, both sides kept apart (RK1197)."""
551
+
552
+ #: Every path the tree has changed, staged or not, untracked included — what a `git add -A`
553
+ #: would put in the next commit, which is the list a scope is subtracted from.
554
+ changed: frozenset[str] = frozenset()
555
+ #: The subset whose **index** already differs from `HEAD`. The half that was thrown away:
556
+ #: a `git commit` takes these whether or not the author reads a diff, and the diff they are
557
+ #: reading is the other side. Measured twice in one session as a version literal another
558
+ #: process staged and this one would have committed.
559
+ staged: frozenset[str] = frozenset()
560
+
561
+
562
+ def carrying(config: Config, task_id: str, paths: Iterable[str]) -> tuple[str, ...]:
563
+ """Which of these paths have this id **in their working-tree diff** (RK342).
564
+
565
+ The fact `claim <id>` was missing. A claim's own transaction writes governed files — the
566
+ marker moves in the roadmap, and every governed write carries the README refresh RK188
567
+ added — and the read-back then listed both as `loose`, which reads as *a file somebody
568
+ else touched*. So the author declares the governed paths by hand to silence it, and the
569
+ scope comes to carry paths that were never the work: the analysis this command exists to
570
+ make, made wrong, on the first call of every task.
571
+
572
+ **Not every dirty governed file**, which is the repair that was available and wrong: a
573
+ roadmap the tree holds may hold another session's `add`, and handing it to whoever asks
574
+ would be the two sessions RK294 separates each getting the other's files with this tool's
575
+ signature on it. The distinction the files themselves carry is the id — a line whose
576
+ marker this transaction moved is a changed line naming it, and a projection refreshed
577
+ from that line reproduces it.
578
+
579
+ Read off `git diff HEAD`, both sides, so a **removed** line counts: a ship takes the line
580
+ out, and a diff read for additions alone would answer "no" about the departure that is
581
+ most of the work. Whole-word, because `RK34` must not answer for `RK342` — the same care
582
+ :func:`cited_origin` takes with an anchor, and the same reason.
583
+
584
+ Empty where git cannot answer, the rule every reader here keeps.
585
+ """
586
+ wanted = tuple(dict.fromkeys(paths))
587
+ if not wanted or not task_id:
588
+ return ()
589
+ try:
590
+ # `-U0`, so only the changed lines are read: a context line naming the id belongs to
591
+ # a neighbour this transaction did not touch, and counting it would claim the file
592
+ # for whichever task happens to sit next to the one that moved.
593
+ listed = _run(config.root, "diff", "HEAD", "-U0", "--", *wanted)
594
+ except HistoryUnavailable:
595
+ return ()
596
+ found: list[str] = []
597
+ current = ""
598
+ pattern = re.compile(rf"(?<![\w-]){re.escape(task_id)}(?![\w-])")
599
+ for line in listed.splitlines():
600
+ if line.startswith("+++ b/"):
601
+ current = line[6:]
602
+ elif line[:1] in "+-" and not line.startswith(("+++", "---")) and current:
603
+ if pattern.search(line):
604
+ found.append(current)
605
+ current = "" # one hit settles the file; the rest of its hunks are noise
606
+ # Answered in the caller's order and not git's, so two runs of the same tree read alike.
607
+ return tuple(one for one in wanted if one in set(found))
608
+
609
+
610
+ def _read_status(listed: str) -> tuple[frozenset[str], frozenset[str]]:
611
+ """The paths out of `status --porcelain -z`, whose records are not one per NUL.
612
+
613
+ A rename spends **two** NUL-separated fields — `R <to>\\0<from>` — so a naive split reads
614
+ the origin as a record and its first two characters as a status code. Both ends are
615
+ kept, because both are paths the commit touches.
616
+
617
+ Two sets since RK1197, from the same records: `XY` is one column per side, and the first
618
+ is the index. `?` is not one of them — an untracked file is in neither the index nor
619
+ `HEAD`, so it changes the commit and is not something the commit already carries.
620
+ """
621
+ changed: list[str] = []
622
+ staged: list[str] = []
623
+ fields = [field for field in listed.split(_NUL) if field]
624
+ index = 0
625
+ while index < len(fields):
626
+ record = fields[index]
627
+ index += 1
628
+ code, _, name = record[:2], record[2:3], record[3:]
629
+ if not name:
630
+ continue
631
+ changed.append(name)
632
+ # The **origin** of a rename is staged too, and by the same record: git states one
633
+ # code for the pair, so both ends take it.
634
+ renamed = code[0] in "RC" and index < len(fields)
635
+ origin = fields[index] if renamed else ""
636
+ if renamed:
637
+ changed.append(origin)
638
+ index += 1
639
+ if code[0] not in " ?":
640
+ staged.append(name)
641
+ if origin:
642
+ staged.append(origin)
643
+ return frozenset(changed), frozenset(staged)
644
+
645
+
646
+ @dataclass(frozen=True, slots=True)
647
+ class Cost:
648
+ """What one commit changed: lines either side, and how many files (RK71).
649
+
650
+ Both, because the two live corpora disagree about which one an author pays. Lines are
651
+ what varies and files are what an agent holds in context, which is the comparison the
652
+ "no size field" non-goal argues from — median to p90, 2.7× against 1.4×, a ratio
653
+ holding where the ranges it was first stated as have not (RK367). A derivation that
654
+ reported one would be picking the axis for the reader.
655
+ """
656
+
657
+ sha: str
658
+ short: str
659
+ lines: int
660
+ files: int
661
+
662
+
663
+ def added_ids(config: Config, role: str) -> dict[str, str]:
664
+ """Which commit first added each id to one governed file: id → sha, oldest wins.
665
+
666
+ One `git log -U0` over the file, not one pickaxe per id: 69 ids is 69 processes, which
667
+ is the difference between a query and a thing nobody runs twice. The trade is that this
668
+ reads *added lines* rather than asking about an id, so an id the file never carried is
669
+ absent here where :func:`origin_of` would say so — which is why both exist.
670
+ """
671
+ if not config.has(role):
672
+ return {}
673
+ try:
674
+ relative = config.path(role).relative_to(config.root)
675
+ except ValueError:
676
+ relative = config.path(role)
677
+ output = _run(
678
+ config.root,
679
+ "log",
680
+ "--reverse",
681
+ f"--format={_RECORD}%H",
682
+ "--no-color",
683
+ "-U0",
684
+ "--",
685
+ str(relative),
686
+ )
687
+ # The qualifier a **partial** entry carries inside the bold span (RK121, RK1175): a search
688
+ # for the bare id read `**RK1169 (the withheld reasons)**` as no id at all, so every partially
689
+ # shipped entry was reported as one no commit accounts for — permanently, since the qualifier
690
+ # stays until the completing ship. Optional here for the same reason the grammar has it.
691
+ bold = re.compile(rf"\*\*({config.schema.id_fragment})(?: \([^)]+\))?\*\*")
692
+ first: dict[str, str] = {}
693
+ for head, rows in _records(output):
694
+ added = "\n".join(
695
+ row for row in rows if row.startswith("+") and not row.startswith("+++")
696
+ )
697
+ for task_id in bold.findall(added):
698
+ first.setdefault(task_id, head.strip())
699
+ return first
700
+
701
+
702
+ def ids_since(
703
+ config: Config, rev: str, role: str, *, resolved: bool | None = None
704
+ ) -> frozenset[str]:
705
+ """Which ids this role's file **gained or lost a line for** since ``rev`` (RK1120).
706
+
707
+ Two parses and never a diff heuristic, which is the whole of why this is decidable. RK1117
708
+ subtracted whole *files* a departure could explain — the roadmap is always one, because
709
+ the marker write that took the line is in the same diff — so another session's added line
710
+ rode inside the staging the report printed. What tells them apart is not that a second id
711
+ *appears* in the change: an annotation refresh (RK8) rewrites every dependent's deps field
712
+ and names those ids in added lines, so a textual reading calls half the backlog somebody
713
+ else's. What it is, is a line **arriving or leaving**, which only two parses can answer.
714
+
715
+ The symmetric difference and not the additions, because both directions are a second
716
+ session's work: a line added here is theirs, and a line removed is a ship of theirs that
717
+ this commit would carry. The id being committed is the caller's to exclude — it is in this
718
+ set on every ordinary departure, that being the line leaving.
719
+
720
+ Empty where git cannot answer or the role is not declared, the rule every reader here
721
+ keeps: a report is worth less than a session, and this feeds a report. :func:`resolves` is
722
+ asked first and not left to the read below, because the two silences differ in the one way
723
+ that matters here: :func:`content_at` answers `""` both for a file a revision did not carry
724
+ and for a revision that does not exist, and comparing a *whole backlog* against nothing
725
+ reports every id in it as newly arrived — which on a directory that is not a repository is
726
+ every line the project has.
727
+
728
+ ``resolved`` is that answer where the caller already has it (RK1124). Whether git knows a
729
+ revision is a fact about the **repository**, and asking it per role made a caller looping
730
+ over the carriers pay a `rev-parse` for something in hand: measured at 20.6ms each, 85.6ms
731
+ for the pair this repository declares, against the 43ms floor RK176 set for a whole
732
+ session-start read. A parameter and not a cache, the shape `plan(gauging=…)` already uses
733
+ for the one expensive question a caller may decline — a cache keyed on a revision would be
734
+ a second reader of git state with its own staleness, in a module that stores nothing.
735
+ """
736
+ if not config.has(role):
737
+ return frozenset()
738
+ if not (resolves(config, rev) if resolved is None else resolved):
739
+ return frozenset()
740
+ schema = config.schema_for(role)
741
+ try:
742
+ before = Document.parse(content_at(config, rev, role), schema=schema)
743
+ now = config.document(role)
744
+ except (HistoryUnavailable, OSError, ValueError):
745
+ return frozenset()
746
+ return frozenset(before.by_id()) ^ frozenset(now.by_id())
747
+
748
+
749
+ def designs_since(
750
+ config: Config, rev: str, role: str, *, resolved: bool | None = None
751
+ ) -> frozenset[str]:
752
+ """Which designs this prose role's file **gained or lost a section for** since ``rev``.
753
+
754
+ :func:`ids_since`'s unit one file over (RK1125). A rationale file holds no task lines, so
755
+ that reading answers nothing about it — and the file a departure *wrote* is exactly where
756
+ the silence hurt: one `section amend` earlier in the session puts this id in the diff, the
757
+ file is then accounted for, and another session's new `### §RK-B` rides into the staging
758
+ with nothing said. That is RK1117's defect and RK1120's fix, in the other unit.
759
+
760
+ Labelled by the **id the heading names** where it names one, and by the anchor otherwise.
761
+ Under the id scheme those are the same string; under an outline the anchor is `XVI.12` and
762
+ the id lives in the title, so a label read off the anchor alone would report an address the
763
+ reader then has to resolve. :meth:`~roadkeep.sections.Section.names` is that reading and it
764
+ is the title's alone — a section quoting another id is discussing it, not being it.
765
+
766
+ Two consequences worth stating, and both are the roadmap's reading in this unit. A section
767
+ this project *moved* keeps its id, so it is not reported — the design did not arrive or
768
+ leave, its address changed, which is what `section move` is for. And a **subsection added
769
+ under a design that already existed** is that design changing rather than arriving, so it is
770
+ not reported either: exactly as an amended task line is not an id arriving on the roadmap
771
+ (RK1120), and for the same reason — this answers which work is in the file, not which
772
+ paragraph somebody edited.
773
+ """
774
+ if role not in PROSE_ROLES or not config.has(role):
775
+ return frozenset()
776
+ if not (resolves(config, rev) if resolved is None else resolved):
777
+ return frozenset()
778
+ schema = config.schema_for(role)
779
+ try:
780
+ before = anchored(Document.parse(content_at(config, rev, role), schema=schema))
781
+ now = anchored(config.document(role))
782
+ except (HistoryUnavailable, OSError, ValueError):
783
+ return frozenset()
784
+ ids = config.schema.id_pattern()
785
+ return _labels(before, ids) ^ _labels(now, ids)
786
+
787
+
788
+ def owned_edit(config: Config, rev: str, task_id: str, role: str) -> bool:
789
+ """Whether this tree's changes to a prose file are inside a section this id owns (RK1126).
790
+
791
+ The reading :func:`carrying` cannot make. It credits a path where an added or removed line
792
+ **names the id**, which on a rationale file means a heading — so `section amend <id>
793
+ --body` rewrites the paragraph under one, touches no line carrying the id, and the file the
794
+ author just edited came back as `loose (no claim names it)`. RK1117's sentence pointed at
795
+ the author's own work, and RK342's defect from the other side: withholding a path is as
796
+ wrong as handing it over, because the answer is then declared by hand and the scope carries
797
+ what was never the work.
798
+
799
+ Additions are read against the file **now** and removals against the file at ``rev``, which
800
+ is RK36's split and the reason this is not one span lookup: a deleted paragraph's line
801
+ numbers are the old file's, and judging them against the current parse attributes them to
802
+ whichever section now sits over the hole. :func:`~roadkeep.sections.owners` decides
803
+ ownership so the outline case answers too — there the id is in the heading's title and a
804
+ sub-anchor belongs to the id its first segment spells.
805
+
806
+ A blank line belongs to no section's prose, exactly as the gate reads it: counting one
807
+ would credit a file for the trailing newline of somebody else's paragraph.
808
+ """
809
+ if role not in PROSE_ROLES or not config.has(role):
810
+ return False
811
+ ids = config.schema.id_pattern()
812
+ try:
813
+ edited = touched_since(config, rev, role)
814
+ now = anchored(config.document(role))
815
+ before = anchored(
816
+ Document.parse(content_at(config, rev, role), schema=config.schema_for(role))
817
+ )
818
+ except (HistoryUnavailable, OSError, ValueError):
819
+ return False
820
+ for change in edited.changes:
821
+ if not change.text.strip():
822
+ continue
823
+ for section in now if change.added else before:
824
+ if section.first <= change.lineno <= section.last and task_id in owners(
825
+ section, ids
826
+ ):
827
+ return True
828
+ return False
829
+
830
+
831
+ def _labels(sections: Sequence[Section], ids: re.Pattern[str]) -> frozenset[str]:
832
+ """Each section as **the task it belongs to**, or as its anchor where it belongs to none.
833
+
834
+ :func:`~roadkeep.sections.owners` and not a second reading of a heading (RK1127). Labelling
835
+ by the ids a *title* names left a sub-anchor labelled by its own address: `§RK2.1` is `RK2`'s
836
+ subsection and the anchor says so segment by segment, so the exclusion `- {task_id}` did not
837
+ remove it and a departure reported the design being shipped as somebody else's. `owners`
838
+ already answers this for the gate and for the drop — under the id scheme the anchor is the
839
+ id and a sub-anchor is its root's, and under an outline the id is in the title — so the one
840
+ thing left here is the fallback: a section belonging to no task is labelled by the anchor,
841
+ which is the only handle a reader has on prose that is nobody's.
842
+ """
843
+ out: set[str] = set()
844
+ for section in sections:
845
+ out.update(owners(section, ids) or (section.anchor,))
846
+ return frozenset(out)
847
+
848
+
849
+ def costs_of(config: Config, shas: tuple[str, ...]) -> dict[str, Cost]:
850
+ """The size of each named commit, across every file it touched, in one call.
851
+
852
+ `--no-walk`, so the list is the commit list and not a range: the commits that wrote a
853
+ ledger entry are scattered through history and a range would count what sits between
854
+ them. A binary file's numstat is `-`, and it counts as a file and no lines.
855
+
856
+ And the list arrives on **stdin** (RK1315), which is the one thing about this call that
857
+ is not free to be argv: as arguments it is bounded by the operating system, and this
858
+ repository crossed Windows' ceiling at 798 commits — 32,718 characters of shas, against
859
+ 32,767 — so the read failed on size rather than on history. `--stdin` and not batching,
860
+ because batching trades the property stated above, *two git calls whatever the size of
861
+ the ledger*, for a number of calls that grows with the file.
862
+ """
863
+ if not shas:
864
+ return {}
865
+ output = _run(
866
+ config.root,
867
+ "log",
868
+ "--no-walk",
869
+ f"--format={_RECORD}{_UNIT.join(['%H', '%h'])}",
870
+ "--numstat",
871
+ "--stdin",
872
+ fed=shas,
873
+ )
874
+ out: dict[str, Cost] = {}
875
+ for head, rows in _records(output):
876
+ sha, _, short = head.partition(_UNIT)
877
+ counted = [
878
+ changed for changed in (_numstat(row) for row in rows) if changed is not None
879
+ ]
880
+ out[sha] = Cost(
881
+ sha=sha, short=short or sha[:7], lines=sum(counted), files=len(counted)
882
+ )
883
+ return out
884
+
885
+
886
+ def _numstat(row: str) -> int | None:
887
+ """One numstat row as the lines it changed, or None when the row is not one.
888
+
889
+ A binary file reports `-` for both sides: it is a file that changed and no lines that
890
+ did, which is what the caller counts it as rather than dropping it.
891
+ """
892
+ columns = row.split("\t")
893
+ if len(columns) != 3:
894
+ return None
895
+ added, removed = columns[0], columns[1]
896
+ return (int(added) if added.isdigit() else 0) + (
897
+ int(removed) if removed.isdigit() else 0
898
+ )
899
+
900
+
901
+ def _records(output: str) -> tuple[tuple[str, tuple[str, ...]], ...]:
902
+ """Split a `--format=<record>…` log into (head line, following rows) pairs.
903
+
904
+ The record separator and not newlines, for :data:`_FORMAT`'s reason: a subject or a diff
905
+ line can hold anything, so only a byte no message carries can end a record.
906
+ """
907
+ out: list[tuple[str, tuple[str, ...]]] = []
908
+ for record in output.split(_RECORD):
909
+ rows = record.strip("\n").splitlines()
910
+ if rows:
911
+ out.append((rows[0], tuple(rows[1:])))
912
+ return tuple(out)
913
+
914
+
915
+ def origin_of(config: Config, task_id: str) -> Origin:
916
+ """The commit that proposed the task and the one that shipped it, if each exists."""
917
+ needle = f"**{task_id}**" # the bold id, so RK1 does not match RK10
918
+ proposed = _first_touching(config, needle, "roadmap")
919
+ shipped = _first_touching(config, needle, "changelog")
920
+ return Origin(task_id=task_id, proposed_in=proposed, shipped_in=shipped)
921
+
922
+
923
+
924
+ @dataclass(frozen=True, slots=True)
925
+ class Pending:
926
+ """One open line, and the commits whose message already names it (RK1201).
927
+
928
+ Not "the work is done" — which of a task's commits completed it is a judgement, and this
929
+ tool has no model of one (L4). What this holds is the two facts a reader needs to decide:
930
+ the line is open, and something in the history says otherwise.
931
+ """
932
+
933
+ id: str
934
+ marker: str
935
+ block: str
936
+ #: The commits naming this id, newest first. Read from the **message** and not from a
937
+ #: file's history: `origin` asks which commit touched the roadmap at this id, which is
938
+ #: about the *line*, and the question here is about the work.
939
+ commits: tuple[Commit, ...] = ()
940
+ #: Whether the ledger already holds an entry for it — true on a partial (RK121), which is
941
+ #: the state this deliberately does not report: a half recorded and a line still open is
942
+ #: exactly what a partial is, and reporting it would be reporting the feature.
943
+ recorded: bool = False
944
+
945
+ @property
946
+ def stale(self) -> bool:
947
+ return bool(self.commits) and not self.recorded
948
+
949
+
950
+ def pending(config: Config) -> tuple[Pending, ...]:
951
+ """Every open line with commits naming it and no ledger entry (RK1201).
952
+
953
+ One `git log` for the whole backlog rather than one per id: the ids are matched against the
954
+ subjects that come back, so a backlog of forty costs the same read as a backlog of one.
955
+
956
+ Empty where git cannot answer, the rule every reader here keeps — a checkout with no git is
957
+ one this reports nothing about, never one it refuses.
958
+ """
959
+ from roadkeep.backlog import Backlog # noqa: PLC0415 - RK260
960
+
961
+ backlog = Backlog.load(config)
962
+ open_lines = list(backlog.roadmap.entries)
963
+ if not open_lines:
964
+ return ()
965
+ recorded = (
966
+ {entry.task.id for entry in backlog.ledger.entries}
967
+ if backlog.ledger is not None
968
+ else set()
969
+ )
970
+ try:
971
+ # The module's own format and its own parser (RK1201): a second spelling of a commit
972
+ # here would be a second thing to keep true, and the one already there carries every
973
+ # field this needs.
974
+ listed = _parse(_run(config.root, "log", "--no-merges", f"--format={_FORMAT}"))
975
+ except HistoryUnavailable:
976
+ return ()
977
+ from roadkeep.ids import id_scanner # noqa: PLC0415 - RK260
978
+
979
+ naming: dict[str, list[Commit]] = {}
980
+ # The **scanner** and not `id_pattern` (RK106): one matches an id as a whole string and the
981
+ # other finds one inside running text, which is what a commit subject is.
982
+ pattern = id_scanner(config.schema)
983
+ for commit in listed:
984
+ for token in {found.group(0) for found in pattern.finditer(commit.subject)}:
985
+ naming.setdefault(token, []).append(commit)
986
+
987
+ # **The oldest commit naming an id is the one that filed it**, and it is dropped: `add` is
988
+ # what mints an id, so nothing could name one before the line existed. Measured before this
989
+ # was written — without it the sweep reported seven lines and every one was its own filing,
990
+ # where `docs: file RK1196` names the id and means the opposite of what the report said.
991
+ #
992
+ # Read off the log already in hand rather than by asking `origin` per id, which is the same
993
+ # answer at one git call per open line. A **promise** (RK431) is the one shape this reads as
994
+ # work: an id a sentence named before the line existed leaves the filing as the newest of
995
+ # two, which errs toward reporting — the safe direction for a report.
996
+ for named in naming.values():
997
+ named.pop()
998
+
999
+ return tuple(
1000
+ Pending(
1001
+ id=entry.task.id,
1002
+ marker=entry.task.status,
1003
+ block=entry.task.block,
1004
+ commits=tuple(naming.get(entry.task.id, ())),
1005
+ recorded=entry.task.id in recorded,
1006
+ )
1007
+ for entry in open_lines
1008
+ )
1009
+
1010
+
1011
+ #: What one `git log` line carries, separated by a NUL. A NUL cannot appear in a subject,
1012
+ #: which is what makes splitting safe where a subject may hold anything else — and it is
1013
+ #: spelled `%x00` because an argv may not carry one: Windows refuses the process outright.
1014
+
1015
+
1016
+ @dataclass(frozen=True, slots=True)
1017
+ class Unclosed:
1018
+ """The sweep as one answer: which open lines the history already speaks for (RK1201).
1019
+
1020
+ **A report and never a refusal.** The honest reading of a line with commits is sometimes
1021
+ "the work is under way and these are partial", which is what a partial entry is for — so
1022
+ this states the fact and leaves the verdict where it belongs.
1023
+ """
1024
+
1025
+ rows: tuple[Pending, ...] = ()
1026
+ #: True where git answered at all. `()` means two different things otherwise, and a
1027
+ #: checkout with no history reading as a clean backlog is the silence RK10 is about.
1028
+ searched: bool = True
1029
+
1030
+ @property
1031
+ def stale(self) -> tuple[Pending, ...]:
1032
+ return tuple(one for one in self.rows if one.stale)
1033
+
1034
+ def stated(self) -> str:
1035
+ if not self.searched:
1036
+ return "no history to read, so nothing here says whether a line was left open"
1037
+ found = self.stale
1038
+ rows = [
1039
+ f"{len(found)} of {len(self.rows)} open line(s) already have commits naming them"
1040
+ ]
1041
+ for one in found:
1042
+ named = ", ".join(commit.short for commit in one.commits[:3])
1043
+ more = f" and {len(one.commits) - 3} more" if len(one.commits) > 3 else ""
1044
+ rows.append(
1045
+ f" {one.marker} {one.id:<8} Block {one.block:<3} {named}{more}"
1046
+ )
1047
+ if found:
1048
+ # The door, as every finding this tool prints carries one (RK420): what closes a
1049
+ # line is `ship`, and what closes it *honestly* where only half landed is `--part`.
1050
+ rows.append(
1051
+ " close `ship <id> --why …` records the outcome, or `--part` where only "
1052
+ "half of it landed"
1053
+ )
1054
+ return chr(10).join(rows)
1055
+
1056
+ def payload(self) -> dict[str, object]:
1057
+ return {
1058
+ "searched": self.searched,
1059
+ "open": len(self.rows),
1060
+ "unclosed": [
1061
+ {
1062
+ "id": one.id,
1063
+ "marker": one.marker,
1064
+ "block": one.block,
1065
+ "recorded": one.recorded,
1066
+ "commits": [
1067
+ {"sha": commit.sha, "short": commit.short, "subject": commit.subject}
1068
+ for commit in one.commits
1069
+ ],
1070
+ }
1071
+ for one in self.stale
1072
+ ],
1073
+ }
1074
+
1075
+
1076
+ @dataclass(frozen=True, slots=True)
1077
+ class Cited:
1078
+ """An anchor somebody's prose still names, resolved against history (RK212)."""
1079
+
1080
+ anchor: str
1081
+ #: The prose role the address was searched in, and the commits at each end.
1082
+ role: str
1083
+ written_in: Commit | None
1084
+ removed_in: Commit | None
1085
+ #: Whether the log that came back empty was a log worth trusting — :class:`Gap`'s split.
1086
+ searched: bool = False
1087
+
1088
+ @property
1089
+ def live(self) -> bool:
1090
+ """Written and never removed: the section is still there and this is a live cite."""
1091
+ return self.written_in is not None and self.removed_in is None
1092
+
1093
+ def stated(self, where: str, *, why: bool = False) -> str:
1094
+ """Where the design behind this citation went, as the reader is told it (RK212).
1095
+
1096
+ Beside :meth:`payload` since RK1170: these two were a printer inside the handler and a
1097
+ builder in the same function, so one answer had two spellings and the file that holds the
1098
+ fact held neither. `where` is passed rather than stored — the role is the fact and how a
1099
+ project spells that file is the caller's (RK75).
1100
+
1101
+ The absences are three different answers and never one (RK95): a history nobody could
1102
+ search, a history searched to the root that never saw the address — which is what a typo
1103
+ looks like — and an address still in the file, where the citation simply resolves.
1104
+ """
1105
+ if not self.searched:
1106
+ return f"§{self.anchor}: no history to resolve against"
1107
+ if self.written_in is None:
1108
+ return f"§{self.anchor}: searched {where} to the root and nothing ever wrote it"
1109
+ rows = [
1110
+ f"§{self.anchor} in {where}",
1111
+ f" written {self.written_in.short} {self.written_in.date[:10]} "
1112
+ f"{self.written_in.subject}",
1113
+ ]
1114
+ if self.removed_in is None:
1115
+ rows.append(" removed — the section is still there, so the citation resolves")
1116
+ else:
1117
+ rows.append(
1118
+ f" removed {self.removed_in.short} {self.removed_in.date[:10]} "
1119
+ f"{self.removed_in.subject}"
1120
+ )
1121
+ if why:
1122
+ # The commit's own reasoning, only where it was asked for: it is the one field
1123
+ # here that is a paragraph, and a read that always printed it would be a read
1124
+ # nobody puts in a loop.
1125
+ rows += ["", self.removed_in.reasoning]
1126
+ return "\n".join(rows)
1127
+
1128
+ def payload(self, *, whole: bool = True) -> dict[str, object]:
1129
+ """The same answer as data, with each end null where history answered nothing.
1130
+
1131
+ `whole` keeps the commit's message: a caller asking about an address is asking about
1132
+ those two commits, so the body is the answer here rather than a paragraph riding along.
1133
+ """
1134
+
1135
+ def commit(one: Commit | None) -> dict[str, str] | None:
1136
+ if one is None:
1137
+ return None
1138
+ said = {
1139
+ "sha": one.sha,
1140
+ "short": one.short,
1141
+ "date": one.date,
1142
+ "subject": one.subject,
1143
+ }
1144
+ return {**said, "body": one.body} if whole else said
1145
+
1146
+ return {
1147
+ "anchor": self.anchor,
1148
+ "role": self.role,
1149
+ "searched": self.searched,
1150
+ "written": commit(self.written_in),
1151
+ "removed": commit(self.removed_in),
1152
+ }
1153
+
1154
+
1155
+ def cited_origin(config: Config, anchor: str) -> Cited:
1156
+ """Where the design behind a dangling citation was written, and what took it away.
1157
+
1158
+ The half of RK206 a verb cannot reach. `ship` names the sections left citing what it
1159
+ deleted, at the moment it deletes it; a reader meeting `§XVIII.12` a year later has no
1160
+ such moment, and the files hold no answer — `as_ledger` keeps no pointer, so nothing
1161
+ records which anchor a shipped design had.
1162
+
1163
+ Measured before choosing this over a gate: 37 such references across this repository,
1164
+ claude-tray, Shio and Turing, and 36 of them are in `ref_scheme = "outline"` projects
1165
+ where the anchor carries no id at all. A finding would fail four files whose prose is
1166
+ correct; a *note* would be 28 of them in one Turing report, which is the output nobody
1167
+ reads that this project refuses elsewhere (RK16). So the answer is a question instead
1168
+ (L5) — it costs nothing until somebody meets the reference and asks.
1169
+
1170
+ Both ends, because they are different facts: the commit that *wrote* the section says
1171
+ what the design was, and the one that *removed* it says which task took it. `-G` finds
1172
+ both (:func:`commits_touching`), so a history that cannot be searched answers neither —
1173
+ reported as :attr:`searched` rather than as an anchor nobody ever wrote, which is
1174
+ :class:`Gap`'s split and made for the same reason.
1175
+ """
1176
+ # The **heading**, not the citation. `§RK15` alone matches every commit that touched
1177
+ # somebody's prose about it, so the last one was RK206's ship — which deleted a
1178
+ # sentence citing §RK15 and never went near the section. `anchor_text` is the one
1179
+ # place a heading's spelling is decided (RK44), so the two schemes agree here for
1180
+ # free, and the trailing space keeps `§RK1` from answering for `§RK15`.
1181
+ # Grouped, not `§?`: git matches bytes, so an unparenthesised `?` would make the
1182
+ # *second* byte of the two-byte sigil optional and the pattern would match neither
1183
+ # spelling. Two live outline projects disagree about the sigil in a heading — Shio and
1184
+ # Turing write `### VIII.1`, claude-tray writes `### §I.1` and `### XVIII.12` in the
1185
+ # same file — so both are admitted, and the trailing space keeps `§I.1` from answering
1186
+ # for `§I.12`.
1187
+ needle = "# (§)?" + re.escape(anchor) + " "
1188
+ for role in ("improvements", "strategy"):
1189
+ if not config.has(role):
1190
+ continue
1191
+ try:
1192
+ found = _touching_role(config, needle, role, literal=False)
1193
+ except HistoryUnavailable:
1194
+ return Cited(anchor=anchor, role=role, written_in=None, removed_in=None)
1195
+ if not found:
1196
+ continue
1197
+ # Oldest first (`--reverse`), so the first wrote it. The last removed it only if
1198
+ # the address is gone now: a section still in the file has a last commit that
1199
+ # edited it, and calling that a removal would invent a deletion nobody made.
1200
+ gone = find(config.document(role), anchor) is None if config.path(role).is_file() else True
1201
+ return Cited(
1202
+ anchor=anchor,
1203
+ role=role,
1204
+ written_in=found[0],
1205
+ removed_in=found[-1] if gone else None,
1206
+ searched=True,
1207
+ )
1208
+ return Cited(anchor=anchor, role=PROSE_ROLES[0], written_in=None, removed_in=None, searched=True)
1209
+
1210
+
1211
+ @dataclass(frozen=True, slots=True)
1212
+ class Anchor:
1213
+ """One outline address a prose file declares, or used to (RK247)."""
1214
+
1215
+ anchor: str
1216
+ role: str
1217
+ #: Whether a heading declares it *now*. False is retired: the section was deleted by a
1218
+ #: ship or a retirement, and every entry whose prose cited it still says `§<anchor>`.
1219
+ live: bool
1220
+ #: The first commit that wrote the heading, where history reaches it — a file older than
1221
+ #: the clone has live anchors nothing here can date, and that is not a state to hide.
1222
+ written_in: str = ""
1223
+ #: The task the **heading** names, or `""` where it names none (RK453). Under an outline
1224
+ #: that id is the ownership (RK262), and until this read it was visible only as `ship`'s
1225
+ #: `kept` field scrolling past. Empty on a retired anchor, which has no heading left.
1226
+ binds: str = ""
1227
+ #: Every **live line** pointing at this address, roadmap and deferred store, in the order
1228
+ #: those files hold them. Two facts and not one, because they come apart in both
1229
+ #: directions and each way is a different thing to do: a heading binding nobody that a
1230
+ #: line claims is RK452's write left undone on a corpus that predates it, and one binding
1231
+ #: a task no live line claims is prose whose task has shipped — what `ship` reports once
1232
+ #: and no reader has held since.
1233
+ claimed: tuple[str, ...] = ()
1234
+
1235
+ @property
1236
+ def memo(self) -> bool:
1237
+ """A live heading that names no task and that no open line claims (RK461).
1238
+
1239
+ The third state, and the one that is never a thing to do. RK236 settled that a
1240
+ heading naming no task is prose belonging to none, which a standing memo genuinely
1241
+ is — Turing's GEO memo is the case it was decided for, and this repository's own `§0`
1242
+ to `§0.4` are five more. Nothing closes it, because nothing is open.
1243
+
1244
+ Named so the two states that *are* actionable can be told from it: reported beside
1245
+ them, it was five of the five rows this project's audit printed, and a list whose
1246
+ majority is noise is what teaches somebody to stop reading a report.
1247
+ """
1248
+ return self.live and not self.binds and not self.claimed
1249
+
1250
+ @property
1251
+ def orphaned(self) -> bool:
1252
+ """A live heading bound to a task no open line claims — prose whose task has left.
1253
+
1254
+ `binds` and not only the absence of a claimant (RK461): without it this was true of a
1255
+ memo too, which was never anybody's and so cannot have been left. Still not a
1256
+ violation, for RK236's reason; it is a fact this read states and the gate stays out of.
1257
+ """
1258
+ return self.live and bool(self.binds) and not self.claimed
1259
+
1260
+
1261
+ def anchors(config: Config, role: str = "", family: str = "") -> tuple[Anchor, ...]:
1262
+ """Every anchor this **project** declares or ever declared, in outline order (RK247).
1263
+
1264
+ The read `section add` could not make. Its refusals list the anchors that **exist**, so
1265
+ after a fully-shipped family that is none of them and the next free number looks like
1266
+ `.1` — while the ledger entries whose prose cited `.1` are still in the file, addressing
1267
+ a section that will now say something else. Observed on a project where §XXXVII.1 to
1268
+ §XXXVII.16 were all retired and all still cited, and the safe number was found by
1269
+ grepping the ledger by hand.
1270
+
1271
+ So the source is the diff and not the file: an anchor is *used* once a heading declared
1272
+ it, and `ship` deleting that heading does not give the address back — the same rule
1273
+ `add` applies to ids, where retired-never-reused is the roadmap's own property. One
1274
+ `git log -U0` over the file, on :func:`added_ids`' reasoning: one process, not one
1275
+ pickaxe per anchor.
1276
+
1277
+ Both sides of the diff are read. An anchor added before the clone's history and removed
1278
+ inside it appears only as a **removed** line, and that is exactly the retired address
1279
+ this exists to name; a live one the log cannot reach is still reported, off the file,
1280
+ with no commit to point at.
1281
+
1282
+ ``family`` narrows to one subtree by segments — `XXXVII` gives `XXXVII.1` and
1283
+ `XXXVII.1.a` and never `XXXVIII.1`, the care :func:`~roadkeep.sections._extends` takes
1284
+ about where an anchor ends. Empty is the whole file.
1285
+
1286
+ **Every declared prose role, unless ``role`` names one** (RK297). An address is spent
1287
+ once a heading used it, and a project declaring two files has one outline across both:
1288
+ reading the first alone answered `IX.5` on a project whose sibling file had spent to
1289
+ `IX.12`, so the read made to avoid spending an address twice handed back one already
1290
+ taken — and writing it is the doubled anchor `ref.ambiguous` reports at both headings.
1291
+ The direction `_pointers` took at RK172, one read over. ``role`` stays as the narrower
1292
+ question, and it narrows the *listing*: :func:`next_child` and :func:`next_family` are
1293
+ taken over whatever they are handed, so a caller that means the free address hands them
1294
+ the project.
1295
+ """
1296
+ roles = (role,) if role else PROSE_ROLES
1297
+ found = [
1298
+ one
1299
+ for name in roles
1300
+ if config.has(name)
1301
+ for one in _role_anchors(config, name)
1302
+ ]
1303
+ found += _spent_by_departure(config, roles, found)
1304
+ # Whether this file numbers in Roman is a fact about the whole set (RK293), so it is
1305
+ # settled once here and handed to the key — a per-segment decision would read `C` as 100
1306
+ # in a file whose families are letters, and sort a listing by an arithmetic nobody meant.
1307
+ # The namespace is not part of the numbering (RK340): `S:IX` spells nine in Roman, and a
1308
+ # set read with the prefix on it would answer "no numerals here" and sort as text.
1309
+ numbered = bool(found) and all(numeral(_family_of(one.anchor)) for one in found)
1310
+ wanted = [_claimed(config, one) for one in found if _within(one.anchor, family)]
1311
+ # The role breaks the tie, so an address two files declare comes out as two adjacent
1312
+ # rows in `[files]` order — which is the doubling, reported rather than collapsed.
1313
+ return tuple(sorted(wanted, key=lambda one: (_ordinal(one, numbered), one.role)))
1314
+
1315
+
1316
+ def _claimed(config: Config, anchor: Anchor) -> Anchor:
1317
+ """Fill in who binds this address and who points at it (RK453).
1318
+
1319
+ RK452 stops the unbound heading being created and does not reach the corpora already
1320
+ holding one — and no command listed them, so the fixture's §I.1 was found by reading
1321
+ `ship`'s `kept` field as it scrolled past, and Shio's the same way. `anchors` was the
1322
+ only verb that lists sections and its `live` answers a different question: RK247 built it
1323
+ about address *reuse*, so `live` means a heading declares the address now, and one
1324
+ written for a task that has since shipped is counted among the working ones.
1325
+
1326
+ Both files a line can be open in, for :func:`families_of_block`'s reason: a design whose
1327
+ task is paused is claimed, and answering "nobody" about it would name prose to delete.
1328
+
1329
+ Retired anchors are left alone. There is no heading to read an id off, and a claimant
1330
+ would be a live line pointing at an address nothing declares, which `lint` already
1331
+ refuses as `ref.unresolved` — a second reading of it here would be a second gate.
1332
+ """
1333
+ if not anchor.live:
1334
+ return anchor
1335
+ section = None
1336
+ if config.has(anchor.role):
1337
+ section = find(config.document(anchor.role), anchor.anchor)
1338
+ binds = ""
1339
+ if section is not None:
1340
+ named = owners(section, config.schema.id_pattern())
1341
+ binds = named[0] if named else ""
1342
+ claimed = tuple(
1343
+ entry.task.id
1344
+ for role in ("roadmap", "deferred")
1345
+ if config.has(role)
1346
+ for entry in config.document(role).entries
1347
+ if entry.task.ref == anchor.anchor
1348
+ )
1349
+ return replace(anchor, binds=binds, claimed=claimed)
1350
+
1351
+
1352
+ def families_of_block(config: Config, block: str) -> tuple[str, ...]:
1353
+ """Which outline families a block's prose already lives under (RK312).
1354
+
1355
+ The read that was derivable from no command at all. Under an outline a prose file
1356
+ declares no block headings — the address *is* the placement — so which numeral a block's
1357
+ designs sit in is written down nowhere, and the way to it was globbing pointers per block
1358
+ by hand: `list --block Q | grep -oE "§[IVXL]+"`, repeated once per block. It is a
1359
+ question, so it is a command (L5).
1360
+
1361
+ Read off the **pointers** and never off the prose file, for the reason
1362
+ :func:`~roadkeep.sections.pointers` gives: a heading nested under another is that other's
1363
+ prose until a line names it, and a task line is the only place that says which block an
1364
+ address belongs to. Both files a line can be open in, because a block whose every live
1365
+ line is paused still has a family and answering "none" would send the caller to open a
1366
+ second one.
1367
+
1368
+ More than one is a real answer and not a failure. A block that reopened under a fresh
1369
+ top-level has two, and returning both is what lets the caller see that before choosing —
1370
+ a single answer would pick one, which is the guess this exists to stop making.
1371
+
1372
+ Spelled **with the namespace** where `[refs]` declares one (RK340), because that is how
1373
+ :func:`_within` and :func:`next_child` read a family: `S:IX` and `IX` are two subtrees on
1374
+ a project whose two files each number their own outline, and a family stripped of the
1375
+ prefix here would be handed back an address the sibling file already spent.
1376
+ """
1377
+ found: list[str] = []
1378
+ for role in ("roadmap", "deferred"):
1379
+ if not config.has(role) or not config.path(role).is_file():
1380
+ continue
1381
+ for entry in config.document(role).entries:
1382
+ if entry.task.block == block and entry.task.ref:
1383
+ family = entry.task.ref.split(".")[0]
1384
+ if family and family not in found:
1385
+ found.append(family)
1386
+ return tuple(found)
1387
+
1388
+
1389
+ def _spent_by_departure(
1390
+ config: Config, roles: Sequence[str], known: Sequence[Anchor]
1391
+ ) -> list[Anchor]:
1392
+ """Addresses no prose diff witnesses, read off the pointers that left with them (RK1178).
1393
+
1394
+ The blind spot :func:`_pointed_at` covers, joined here so one listing answers for both kinds
1395
+ of evidence: a heading any committed tree held, and an address whose heading no tree ever did
1396
+ because the `section add` that wrote it and the `ship` that dropped it were one commit.
1397
+
1398
+ **Outline only**, the rule :func:`~roadkeep.sections._refuse_reuse` keeps for the same reason:
1399
+ under `ref_scheme = "id"` the pointer *is* the id, retired-never-reused is the roadmap's own
1400
+ property (RK4), and every shipped task would arrive here as an address to refuse.
1401
+
1402
+ Attributed to the file the address belongs to, which its namespace answers where `[refs]`
1403
+ declares one (RK340). Where none does, both files number into one space and the row goes to
1404
+ the first declared role: the address is spent either way — that is the fact this reports — and
1405
+ which file would have held the heading is a question no history can settle.
1406
+ """
1407
+ declared = [name for name in roles if config.has(name)]
1408
+ if not declared or config.schema_for(declared[0]).ref_scheme == "id":
1409
+ return []
1410
+ seen = {one.anchor for one in known}
1411
+ out: list[Anchor] = []
1412
+ for anchor, sha in _pointed_at(config).items():
1413
+ if anchor in seen:
1414
+ continue
1415
+ namespace, _ = split_ref(anchor)
1416
+ role = next(
1417
+ (name for name in declared if config.schema_for(name).ref_prefix == namespace),
1418
+ declared[0],
1419
+ )
1420
+ out.append(Anchor(anchor=anchor, role=role, live=False, written_in=sha))
1421
+ seen.add(anchor)
1422
+ return out
1423
+
1424
+
1425
+ def _pointed_at(config: Config) -> dict[str, str]:
1426
+ """Every address a task line pointed at and **took with it**, by the commit that removed it.
1427
+
1428
+ The witness for an address declared and dropped inside one commit (RK1178). `_anchors_written`
1429
+ reads the prose file's own diffs, which is the whole history of an address in every case but
1430
+ one: a task whose `section add` and whose `ship` land in the same commit leaves a net-zero
1431
+ diff there — the heading was never in any committed tree, so no diff of that file mentions it.
1432
+ Nothing in the ledger does either, `as_ledger` keeping no pointer.
1433
+
1434
+ What does survive is the **roadmap**: that task's line was filed in an earlier commit carrying
1435
+ `→ §XIV.30`, and the ship removed the line. So the address is read off the pointer that left,
1436
+ which is a fact in the same history and about the same address.
1437
+
1438
+ Worth fixing rather than tolerating because of which workflow produces it: a task that files
1439
+ its own rationale and ships in one commit is what a one-task-one-commit rule *requires*, so
1440
+ this is the normal path and not unusual sequencing.
1441
+
1442
+ **Removed pointers only.** A pointer on a line still in the file is an address the two-command
1443
+ flow is halfway through spending — `add --ref I.3` then `section add I.3` — and counting it
1444
+ would make the second command refuse the address the first was told to take. A rewritten
1445
+ pointer (`amend --ref`) does register the one it abandoned: an address nothing wrote is still
1446
+ an address a reader saw cited, and they cost nothing.
1447
+ """
1448
+ out: dict[str, str] = {}
1449
+ for role in ("roadmap", "deferred"):
1450
+ if not config.has(role):
1451
+ continue
1452
+ try:
1453
+ output = _run(
1454
+ config.root,
1455
+ "log",
1456
+ "--reverse",
1457
+ f"--format={_RECORD}%H",
1458
+ "--no-color",
1459
+ "-U0",
1460
+ "--",
1461
+ str(config.relative(config.path(role))),
1462
+ )
1463
+ except HistoryUnavailable:
1464
+ continue
1465
+ # Read as `anchor_of` reads a heading's: whatever follows the sigil up to the space
1466
+ # that ends the pointer, which is the last thing a rendered line carries. The address is
1467
+ # then validated by the same reader the prose file's own scan uses, so a bullet that
1468
+ # merely contains an arrow contributes nothing.
1469
+ pointer = re.compile(rf"{ARROW} §(\S+)\s*$")
1470
+ for head, rows in _records(output):
1471
+ for row in rows:
1472
+ if not row.startswith("-") or row.startswith("---"):
1473
+ continue
1474
+ found = pointer.search(row)
1475
+ if found:
1476
+ out.setdefault(found[1], head.strip())
1477
+ return out
1478
+
1479
+
1480
+ def _role_anchors(config: Config, role: str) -> list[Anchor]:
1481
+ """One prose file's share of the answer, live rows first and retired ones behind them."""
1482
+ live = _declared(config, role) if config.path(role).is_file() else ()
1483
+ first = _anchors_written(config, role, config.schema_for(role))
1484
+ return [
1485
+ Anchor(anchor=anchor, role=role, live=True, written_in=first.get(anchor, ""))
1486
+ for anchor in live
1487
+ ] + [
1488
+ Anchor(anchor=anchor, role=role, live=False, written_in=sha)
1489
+ for anchor, sha in first.items()
1490
+ if anchor not in live
1491
+ ]
1492
+
1493
+
1494
+ def doubled(taken: Sequence[Anchor]) -> tuple[tuple[str, tuple[str, ...]], ...]:
1495
+ """Every address more than one prose file **declares now**, with the files (RK297).
1496
+
1497
+ Reported here because this is the read that would otherwise hand one back as free: an
1498
+ author asking which address to take is the one who needs to know that two already answer
1499
+ to it. `lint` says the same thing as `ref.ambiguous`, and a gate is not a question — by
1500
+ the time it speaks, both headings exist and four verbs refuse to resolve between them.
1501
+
1502
+ Live only. A retired address in two files is two histories of one outline and nothing to
1503
+ act on; two *headings* are the state a pointer cannot resolve against.
1504
+ """
1505
+ by_anchor: dict[str, list[str]] = {}
1506
+ for one in taken:
1507
+ if one.live:
1508
+ by_anchor.setdefault(one.anchor, []).append(one.role)
1509
+ return tuple(
1510
+ (anchor, tuple(roles)) for anchor, roles in by_anchor.items() if len(roles) > 1
1511
+ )
1512
+
1513
+
1514
+ def next_child(taken: Sequence[Anchor], family: str) -> str:
1515
+ """The lowest numbered child of ``family`` no anchor above has ever used (RK247).
1516
+
1517
+ Derived one past the highest **ever** used and not one past the highest surviving, which
1518
+ is the whole difference: the surviving one is often none. Numeric children only — a
1519
+ lettered or roman segment is somebody's numbering and not this tool's to continue (L4) —
1520
+ and the answer is a suggestion a reader takes, never an anchor any verb writes.
1521
+ """
1522
+ used = {
1523
+ int(child)
1524
+ for anchor in taken
1525
+ for child in (anchor.anchor[len(family) + 1 :].split(".")[:1] or [""])
1526
+ if anchor.anchor.startswith(f"{family}.") and child.isdigit()
1527
+ }
1528
+ return f"{family}.{max(used) + 1 if used else 1}"
1529
+
1530
+
1531
+ #: A well-formed Roman numeral, and only one: `IIII` and `IL` spell nothing here, because a
1532
+ #: reader that accepted them would order a file by a spelling nobody wrote.
1533
+ _ROMAN = re.compile(r"^M{0,3}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})$")
1534
+ _DIGITS = (("M", 1000), ("CM", 900), ("D", 500), ("CD", 400), ("C", 100), ("XC", 90),
1535
+ ("L", 50), ("XL", 40), ("X", 10), ("IX", 9), ("V", 5), ("IV", 4), ("I", 1))
1536
+
1537
+
1538
+ def numeral(text: str) -> tuple[str, int] | None:
1539
+ """The number a segment spells and the system it spells it in, or None for neither.
1540
+
1541
+ Arithmetic and not prose (L4): `IX` is a number written a way this tool has to *read*
1542
+ to sort by, because a listing ordered by a numeral's spelling puts `IX` between `IV` and
1543
+ `V` and cannot be scanned for a gap (RK293). Reading it is also what lets the next free
1544
+ address be derived rather than guessed off the tail of the listing.
1545
+
1546
+ Strict, because a permissive reader is worse than none: a segment that is not a numeral
1547
+ must come back as one, so the caller can put it beside its siblings as text instead of
1548
+ among them as a number nobody meant.
1549
+ """
1550
+ if text.isdigit():
1551
+ return "decimal", int(text)
1552
+ if text and _ROMAN.match(text):
1553
+ value, rest = 0, text
1554
+ for glyph, amount in _DIGITS:
1555
+ while rest.startswith(glyph):
1556
+ value, rest = value + amount, rest[len(glyph) :]
1557
+ return "roman", value
1558
+ return None
1559
+
1560
+
1561
+ def spell(value: int, system: str) -> str:
1562
+ """``value`` written the way ``system`` writes it — the inverse of :func:`numeral`."""
1563
+ if system != "roman":
1564
+ return str(value)
1565
+ out, left = [], value
1566
+ for glyph, amount in sorted(_DIGITS, key=lambda pair: -pair[1]):
1567
+ while left >= amount:
1568
+ out.append(glyph)
1569
+ left -= amount
1570
+ return "".join(out)
1571
+
1572
+
1573
+ def namespaces(taken: Sequence[Anchor]) -> tuple[str, ...]:
1574
+ """Every namespace these addresses live in, `""` for the unprefixed one (RK340).
1575
+
1576
+ Sorted with the unprefixed first, because it is the one a project has before it declares
1577
+ any and the one every listing had until this existed.
1578
+ """
1579
+ return tuple(sorted({split_ref(one.anchor)[0] for one in taken}))
1580
+
1581
+
1582
+ def next_family(taken: Sequence[Anchor], namespace: str = "") -> str | None:
1583
+ """The lowest top-level address no anchor has ever used, or None where none derives.
1584
+
1585
+ The question one line up from :func:`next_child`, and the normal case rather than an edge
1586
+ one (RK293): a block reused after its family shipped needs a *new* top-level, and until
1587
+ this the number was read off the tail of a listing sorted by spelling — where the last row
1588
+ is not the maximum. Derived from the same walk, so it costs nothing the command did not
1589
+ already pay.
1590
+
1591
+ None where the top-levels are not one numbering, which is the honest answer and not a
1592
+ fallback: a file whose families are `A`, `B` and `C` has a next nobody can derive, and a
1593
+ guess printed beside a total reads exactly like a fact. Spelled in the system of the
1594
+ family that holds the maximum, because that is the sequence being continued.
1595
+
1596
+ **Per namespace** (RK340), which is what a namespace is for: `[refs]` makes two files two
1597
+ outlines, each numbering itself from `I`, so a maximum taken across both would answer
1598
+ with the taller file's number for the shorter one — and reading the mixed set as one
1599
+ sequence answers None, which is the useful answer withheld from exactly the projects
1600
+ that declared their way out of the collision. The default is the unprefixed namespace,
1601
+ which is every project that declares no `[refs]` at all.
1602
+
1603
+ **One numbering means one system, and until RK1210 it meant one that reads as a number.**
1604
+ The guard below caught a segment that is no numeral at all and let `1` beside `I` through
1605
+ — they read as 1 and 1, so the key ties, and `max` returns whichever the iteration reached
1606
+ first. That order is a **set** comprehension's over strings, which is per-process hash
1607
+ randomisation: eight runs over one revision of one file answered `II`, `2`, `2`, `2`, `II`,
1608
+ `2`, `2`, `2`. The system the address is spelled in was the tie-break, so the address was
1609
+ too — and `ref.missing` carries it as `offered`, the string a retry substitutes, so a
1610
+ refusal and its own retry could name two different addresses. In one tree they did:
1611
+ `anchors` printed `next §2` where the refusal said `§II is its free top-level`.
1612
+
1613
+ The fix is this function's own rule applied and never a tie-break invented — sorting the
1614
+ set would make the answer stable and still make it a coin the file did not toss. Two
1615
+ systems is two numberings, so it is None, exactly as `A`, `B`, `C` is; every caller
1616
+ already has an answer for None, `_where_a_top_level_is` naming `anchors` in place of an
1617
+ address for the undecidables it already knew about.
1618
+ """
1619
+ own = [one for one in taken if split_ref(one.anchor)[0] == namespace]
1620
+ read = {top: numeral(top) for top in {_family_of(one.anchor) for one in own}}
1621
+ if not read or any(value is None for value in read.values()):
1622
+ return None
1623
+ counted = [value for value in read.values() if value]
1624
+ if len({system for system, _ in counted}) > 1:
1625
+ # Roman in one family and decimal in another. Not a sequence to continue, and the one
1626
+ # shape where continuing it silently picked which of two conventions the project has.
1627
+ return None
1628
+ system, highest = max(counted, key=lambda one: one[1])
1629
+ top = spell(highest + 1, system)
1630
+ return f"{namespace}{REF_SEPARATOR}{top}" if namespace else top
1631
+
1632
+
1633
+ def left_the_repository(root: Path, token: str) -> bool:
1634
+ """Whether this repository once held ``token`` and no longer does, as committed (RK1217).
1635
+
1636
+ The tree a shipped entry's paths are about is **not this afternoon's**. Turing's `T759`
1637
+ names `frontend/apps/site/scripts/emit-model-catalog.mjs`, a script that existed when the
1638
+ work shipped and was later extracted into its own repository with the model catalog it
1639
+ built. The entry is accurate, the file is gone, and the gate reported it every run and
1640
+ would have kept reporting it.
1641
+
1642
+ `Tree.anywhere` already forgives a path that moved **within** the repository, so what was
1643
+ left was the one that left it entirely — a correct statement about the past, read as drift.
1644
+ And the door made it worse than noise: the remedy rewrites the entry's sentence, which on
1645
+ that entry is about 1,500 characters of as-built record. The offered fix for a stale path
1646
+ was deleting the thing that made the entry worth keeping, so nobody took it and the finding
1647
+ sat forgiven by a baseline for ever.
1648
+
1649
+ **Two questions, and the first one is what keeps this narrow.** *Is it in `HEAD`* — because
1650
+ a file somebody deleted in their working tree and has not committed is still the
1651
+ repository's, and forgiving that would stop the gate reporting a deletion at exactly the
1652
+ moment it is worth reporting. Only then *did any commit ever hold it*, over all refs, which
1653
+ is the reading that answers `T759`.
1654
+
1655
+ Not `--follow`, which needs a single surviving path and answers about a rename chain rather
1656
+ than about existence.
1657
+
1658
+ **What this deliberately stops catching** is a rename the ledger did not follow, which was
1659
+ the one true finding this check produced on a live corpus: the old path was held once, so
1660
+ it is now forgiven. RK1217 takes that trade knowingly — the alternative is a correct
1661
+ statement about the past reported for ever, with a door whose only effect is to delete the
1662
+ as-built record that made the entry worth keeping. What is left is the reading the rule was
1663
+ always for: **a path this repository never had.**
1664
+
1665
+ Cheap because it is asked **last** (see :func:`~roadkeep.linting._paths`): the working tree
1666
+ answers first, so a healthy repository asks this nothing at all and a corpus with stale
1667
+ entries pays at most two calls per token that already failed every other reading.
1668
+
1669
+ False where git cannot be reached, which keeps the finding: this is a *forgiveness*, and an
1670
+ unavailable history is not evidence that a path was ever there.
1671
+ """
1672
+ try:
1673
+ if _run(root, "ls-tree", "HEAD", "--", token).strip():
1674
+ return False
1675
+ found = _run(root, "log", "--all", "--max-count=1", "--format=%H", "--", token)
1676
+ except HistoryUnavailable:
1677
+ return False
1678
+ return bool(found.strip())
1679
+
1680
+
1681
+ def _declared(config: Config, role: str) -> tuple[str, ...]:
1682
+ from roadkeep.sections import anchored # noqa: PLC0415 - RK260
1683
+
1684
+ return tuple(section.anchor for section in anchored(config.document(role)))
1685
+
1686
+
1687
+ def _anchors_written(config: Config, role: str, schema: Schema) -> dict[str, str]:
1688
+ """Anchor → the first sha whose diff on this file carries its heading, oldest first."""
1689
+ from roadkeep.sections import anchor_of, qualified # noqa: PLC0415 - RK260
1690
+
1691
+ try:
1692
+ relative = config.path(role).relative_to(config.root)
1693
+ except ValueError:
1694
+ relative = config.path(role)
1695
+ try:
1696
+ output = _run(
1697
+ config.root,
1698
+ "log",
1699
+ "--reverse",
1700
+ f"--format={_RECORD}%H",
1701
+ "--no-color",
1702
+ "-U0",
1703
+ "--",
1704
+ str(relative),
1705
+ )
1706
+ except HistoryUnavailable:
1707
+ return {}
1708
+ first: dict[str, str] = {}
1709
+ for head, rows in _records(output):
1710
+ for row in rows:
1711
+ if row[:1] not in ("+", "-") or row.startswith(("+++", "---")):
1712
+ continue
1713
+ # A heading and not any line that starts with the anchor's spelling: under an
1714
+ # outline the anchor is a bare number, so a table row or a bullet beginning
1715
+ # `XXXVII.4` would otherwise register an address nobody declared.
1716
+ text = row[1:].lstrip()
1717
+ if not text.startswith("#"):
1718
+ continue
1719
+ # Read the way a parsed heading is read — `Heading.text` is what follows the
1720
+ # hashes, and :func:`anchor_of` is written against that.
1721
+ anchor = anchor_of(text.lstrip("#").lstrip(), schema)
1722
+ if anchor is not None:
1723
+ # The project's address and not the heading's (RK340) — the same
1724
+ # qualification `anchored` makes of a live one, so the two halves of this
1725
+ # listing are addresses of one kind and a retired `S:I` is not a second `I`.
1726
+ first.setdefault(qualified(schema, anchor), head.strip())
1727
+ return first
1728
+
1729
+
1730
+ def _within(anchor: str, family: str) -> bool:
1731
+ """Is this anchor the family or under it, segment by segment rather than by string."""
1732
+ if not family:
1733
+ return True
1734
+ segments, wanted = anchor.split("."), family.split(".")
1735
+ return segments[: len(wanted)] == wanted
1736
+
1737
+
1738
+ def _ordinal(anchor: Anchor, numbered: bool = False) -> tuple[object, ...]:
1739
+ """File order is not sort order once retired addresses are back in the list, so the
1740
+ segments are compared as numbers where they are numbers and as text where they are not —
1741
+ `.2` before `.10`, and a lettered segment beside its siblings rather than among them.
1742
+
1743
+ ``numbered`` reads a Roman segment as the number it spells (RK293), and is decided over
1744
+ the whole set rather than per segment: `C` and `D` are numerals on a file numbered in
1745
+ Roman and are letters on one whose families are `A` to `F`, and only the set says which.
1746
+ """
1747
+ return tuple(
1748
+ (0, int(part), "")
1749
+ if part.isdigit()
1750
+ else ((0, read[1], "") if numbered and (read := numeral(part)) else (1, 0, part))
1751
+ # The first segment carries the namespace where a project declares one (RK340), and
1752
+ # it is read off for the same reason `numbered` is: the number is what orders a
1753
+ # listing, and a prefix in front of it is the file's name and not part of the number.
1754
+ for part in _unprefixed(anchor.anchor).split(".")
1755
+ )
1756
+
1757
+
1758
+ def _family_of(anchor: str) -> str:
1759
+ """The top-level segment, with any namespace taken off — `S:IX.2` → `IX` (RK340)."""
1760
+ return _unprefixed(anchor).split(".")[0]
1761
+
1762
+
1763
+ def _unprefixed(anchor: str) -> str:
1764
+ """The address without the namespace `[refs]` put in front of it (RK340)."""
1765
+ return split_ref(anchor)[1]
1766
+
1767
+
1768
+ @dataclass(frozen=True, slots=True)
1769
+ class Gap:
1770
+ """An id that is in neither file, and the commit that took it out (RK32).
1771
+
1772
+ ``removed_in`` is None for two unlike reasons, and RK95 is the record of them having
1773
+ read alike. A history that **cannot** be searched — no git, no repository, a shallow
1774
+ clone — answers nothing; a complete one that mentions the id nowhere answers that no
1775
+ line ever carried it, which is the shape of a number skipped when a batch was
1776
+ allocated. The first prints as *unresolvable* and the second as *never carried*, on
1777
+ RK28's reasoning: an absent answer and a negative one are different answers, and
1778
+ collapsing them here would invent a decision nobody recorded — or deny one that was.
1779
+ """
1780
+
1781
+ id: str
1782
+ number: int
1783
+ removed_in: Commit | None
1784
+ #: Whether the log that came back empty was a log worth trusting.
1785
+ searched: bool = False
1786
+
1787
+ @property
1788
+ def resolved(self) -> bool:
1789
+ return self.removed_in is not None
1790
+
1791
+ @property
1792
+ def never_carried(self) -> bool:
1793
+ """Searched to the root commit and found nowhere: skipped, not removed."""
1794
+ return self.removed_in is None and self.searched
1795
+
1796
+
1797
+
1798
+ def _ownership(one: Anchor) -> str:
1799
+ """Who binds this address and who points at it, where either is worth saying (RK453).
1800
+
1801
+ Silent on the ordinary row — a heading bound to the one line that claims it is the state
1802
+ every write produces, and repeating it on every address would bury the two that are not.
1803
+ What it names is exactly the two ways they come apart, and each is a different act: an
1804
+ unbound heading a line claims is `section amend --title` away from bound, and a bound
1805
+ heading nothing claims is prose whose task has left, which is the reader's to keep or
1806
+ delete.
1807
+
1808
+ Three silences and not one (RK461). A retired address has no heading to have an opinion
1809
+ about; the bound-and-claimed row is what every write produces; and a **memo** — naming no
1810
+ task and claimed by none — is the state RK236 protects and nothing ever closes. Reported
1811
+ beside the two that are actionable, that third one was five of the five rows this
1812
+ project's audit printed, and a list whose majority is noise is what teaches somebody to
1813
+ stop reading a report.
1814
+ """
1815
+ if not one.live or one.memo:
1816
+ return ""
1817
+ if one.binds and one.claimed == (one.binds,):
1818
+ return ""
1819
+ if not one.binds:
1820
+ return f" binds nobody, claimed by {', '.join(one.claimed)}"
1821
+ if not one.claimed:
1822
+ return f" binds {one.binds}, which no open line claims"
1823
+ return f" binds {one.binds}, claimed by {', '.join(one.claimed)}"
1824
+
1825
+
1826
+ def opens(family: str) -> str:
1827
+ """The sentence a free top-level owes, and the command that makes it a section (RK1140)."""
1828
+ from roadkeep.provenance import invocation # noqa: PLC0415 - RK260
1829
+
1830
+ return (
1831
+ f"§{family} is free and not yet a section, so `{invocation()} add --ref {family}.1` "
1832
+ f"refuses until one exists — `{invocation()} section add {family} --title \"…\"` "
1833
+ f"opens it"
1834
+ )
1835
+
1836
+
1837
+ @dataclass(frozen=True, slots=True)
1838
+ class Addresses:
1839
+ """Live and retired addresses across a project's prose, as one answer (RK247, RK297).
1840
+
1841
+ The result this read had none of (RK1170). The door narrowed the listing, derived the free
1842
+ address from a *wider* set than the one it listed, split the outline out of the ids, and
1843
+ then composed four readings from those four values — two payloads and two reports, each
1844
+ subtracting the same things again.
1845
+
1846
+ **The narrowing and the derivation are not the same set, and that is the whole of RK297.**
1847
+ `--role` narrows :attr:`found`; the free address is computed from :attr:`whole`, because
1848
+ where no `[refs]` declares a namespace both files number into one and a `next` taken from
1849
+ a single file is the answer this read exists to stop somebody acting on.
1850
+ """
1851
+
1852
+ #: The role a caller narrowed to, or `""` for every declared prose file.
1853
+ role: str
1854
+ #: The roles actually read, which is what a listing names its files from.
1855
+ read: tuple[str, ...]
1856
+ #: The family a caller narrowed to, or `""`. Under `--block` it is resolved from the
1857
+ #: pointers rather than given (RK312).
1858
+ family: str
1859
+ #: The block asked about, and every family its open lines point into. Both, because one of
1860
+ #: them narrowed the listing and two did not, and a caller cannot tell those apart.
1861
+ block: str = ""
1862
+ spans: tuple[str, ...] = ()
1863
+ found: tuple[Anchor, ...] = ()
1864
+ #: The same read over the project, whatever the listing was narrowed to.
1865
+ whole: tuple[Anchor, ...] = ()
1866
+ #: :attr:`found` and :attr:`whole` with the task ids taken out. An address that is an id is
1867
+ #: a question already answered — `add` refuses to reuse one (RK4) and every shipped task
1868
+ #: leaves its section retired, so on this project they are 287 of 307 rows and none of them
1869
+ #: is a choice anybody makes.
1870
+ outline: tuple[Anchor, ...] = ()
1871
+ spread: tuple[Anchor, ...] = ()
1872
+
1873
+ @classmethod
1874
+ def of(
1875
+ cls,
1876
+ config: Config,
1877
+ role: str,
1878
+ family: str,
1879
+ read: Sequence[str],
1880
+ block: str = "",
1881
+ spans: Sequence[str] = (),
1882
+ ) -> Addresses:
1883
+ found = anchors(config, role, family)
1884
+ whole = found if not role else anchors(config, "", family)
1885
+ ids = config.schema_for(role or read[0]).id_pattern()
1886
+ outside = lambda rows: tuple( # noqa: E731 - one predicate, read twice
1887
+ one for one in rows if not ids.match(one.anchor.split(".")[0])
1888
+ )
1889
+ return cls(
1890
+ role=role,
1891
+ read=tuple(read),
1892
+ family=family,
1893
+ block=block,
1894
+ spans=tuple(spans),
1895
+ found=tuple(found),
1896
+ whole=tuple(whole),
1897
+ outline=outside(found),
1898
+ spread=outside(whole),
1899
+ )
1900
+
1901
+ @property
1902
+ def retired(self) -> tuple[Anchor, ...]:
1903
+ return tuple(one for one in self.found if not one.live)
1904
+
1905
+ @property
1906
+ def spent(self) -> int:
1907
+ """How many of the listed addresses are task ids rather than outline numerals."""
1908
+ return len(self.found) - len(self.outline)
1909
+
1910
+ def files(self, config: Config) -> str:
1911
+ return ", ".join(config.relative(config.path(one)) for one in self.read)
1912
+
1913
+ def families(self) -> list[dict[str, object]]:
1914
+ """One row per top-level address, in numeral order (RK293), with the files it spans.
1915
+
1916
+ The counts are the project's and so is `next` (RK297): a family declared in two prose
1917
+ files is one family, and a per-file count would be the number this read exists to stop
1918
+ somebody taking. `files` is what a row says once it spans two — named rather than
1919
+ summed away, because which file spent an address is what a reader checks it against.
1920
+ """
1921
+ out: dict[str, dict[str, object]] = {}
1922
+ for one in self.outline:
1923
+ top = one.anchor.split(".")[0]
1924
+ row = out.setdefault(top, {"family": top, "live": 0, "retired": 0, "files": []})
1925
+ key = "live" if one.live else "retired"
1926
+ row[key] = int(row[key]) + 1
1927
+ if one.role not in row["files"]: # type: ignore[operator]
1928
+ row["files"].append(one.role) # type: ignore[attr-defined]
1929
+ for top, row in out.items():
1930
+ row["next"] = next_child(self.outline, top)
1931
+ return list(out.values())
1932
+
1933
+ def doubled_rows(self) -> list[str]:
1934
+ """The addresses two prose files both declare, named here and not only at the gate.
1935
+
1936
+ `lint` reports them as `ref.ambiguous`, and by then both headings exist and four verbs
1937
+ refuse to resolve between them (RK297). This is the read an author makes *before*
1938
+ choosing, so it is where the state is cheapest to hear about.
1939
+ """
1940
+ return [
1941
+ f" doubled §{anchor} is declared by {' and '.join(roles)}"
1942
+ for anchor, roles in doubled(self.whole)
1943
+ ]
1944
+
1945
+ def room_left(self, config: Config) -> str:
1946
+ """What the parent of an offered child address has left, where it has too little.
1947
+
1948
+ An address `add` will refuse is an address this listing should not hand over silently
1949
+ (RK1024). Measured: `anchors --block AJ` offered `§L.1`, `§L` was 299 words of its own
1950
+ 300, and every child of it — the empty one included — was over before a word was
1951
+ composed. Said and never refused, because `anchors` is a read (L5): the caller may be
1952
+ about to shorten the parent, which is a plan no count can see.
1953
+ """
1954
+ from roadkeep.kernel.schema import body_aim # noqa: PLC0415 - RK260
1955
+ from roadkeep.sections import binding # noqa: PLC0415 - RK260
1956
+
1957
+ for role in self.read:
1958
+ answer = binding(config, role, self.family)
1959
+ if answer is None:
1960
+ continue
1961
+ taken, limit = answer
1962
+ if taken >= body_aim(limit):
1963
+ return (
1964
+ f", but §{self.family} already spends {taken} of its {limit} words, "
1965
+ f"so a child of it is charged over the limit before it is written"
1966
+ )
1967
+ return ""
1968
+
1969
+ # -- the free address alone (RK410) ------------------------------------
1970
+
1971
+ def freely(self) -> tuple[list[str], list[str]]:
1972
+ """The next address and nothing else, as `(stdout, stderr)`.
1973
+
1974
+ `anchors` answers two questions at once: which addresses a family has spent, asked
1975
+ once before reopening a shipped subtree, and which one nothing ever used, asked by
1976
+ every `add --ref`. Under a 27-anchor family the second answer was the 28th row — and
1977
+ on a tool result the rows are what gets truncated first, which made the one line that
1978
+ mattered the one most likely to be cut.
1979
+
1980
+ Two streams, for `next-id`'s reason: stdout is the address, because this is captured
1981
+ in a shell. **No note where a family was named** and the difference is the whole of
1982
+ RK1140: a free *child* is placeable the moment it is answered, the family's heading
1983
+ already existing. It is the top-level below that is an address and not yet a section.
1984
+ """
1985
+ if self.family:
1986
+ return [f"§{next_child(self.whole, self.family)}"], []
1987
+ out: list[str] = []
1988
+ notes: list[str] = []
1989
+ for space in namespaces(self.spread):
1990
+ fresh = next_family(self.spread, space)
1991
+ named = f" {space}" if space else ""
1992
+ # The same refusal the wide read gives, in one line: a namespace whose top-levels
1993
+ # are not one numbering derives nothing, and a blank row would read as an address.
1994
+ out.append(
1995
+ f"§{fresh}{named}" if fresh else f"—{named} not one numbering, so none derives"
1996
+ )
1997
+ if fresh:
1998
+ notes.append(f"roadkeep: {opens(fresh)}")
1999
+ return out, notes
2000
+
2001
+ def free_payload(self) -> dict[str, object]:
2002
+ """The narrow read in the narrow shape (RK410).
2003
+
2004
+ `family` and `namespace` are kept because the answer is meaningless without saying
2005
+ which numbering it continues — everything else in the wide payload is the listing this
2006
+ flag exists to leave out.
2007
+ """
2008
+ return {
2009
+ "family": self.family or None,
2010
+ "next": next_child(self.whole, self.family) if self.family else None,
2011
+ "next_families": []
2012
+ if self.family
2013
+ else [
2014
+ {
2015
+ "namespace": space or None,
2016
+ "next": next_family(self.spread, space),
2017
+ # The same sentence the reader gets, as the command it names (RK1140): a
2018
+ # client composing `add --ref <next>.1` walks into the refusal a person
2019
+ # now reads about, and two answers to one question is what a payload
2020
+ # beside a report must not be.
2021
+ "opens": None
2022
+ if not (fresh := next_family(self.spread, space))
2023
+ else f"section add {fresh} --title …",
2024
+ }
2025
+ for space in namespaces(self.spread)
2026
+ ],
2027
+ }
2028
+
2029
+ # -- the wide read -----------------------------------------------------
2030
+
2031
+ def stated(self, config: Config, claims: bool) -> str:
2032
+ from roadkeep.provenance import invocation # noqa: PLC0415 - RK260
2033
+
2034
+ where = self.files(config)
2035
+ if claims:
2036
+ # Its own header and not a second one under the totals (RK459): this listing is
2037
+ # the exceptions, so the number a reader wants first is how many there are.
2038
+ rows = [one for one in self.found if _ownership(one)]
2039
+ # The memos are counted and not listed (RK461): "five of them and none needing
2040
+ # anything" is a different answer from silence, and it is the answer an adopting
2041
+ # corpus most often has.
2042
+ memos = sum(1 for one in self.found if one.memo)
2043
+ counted = f", {memos} standing memo(s)" if memos else ""
2044
+ said = [
2045
+ f"{len(rows)} of {len(self.found)} address(es) say something about "
2046
+ f"ownership{counted} ({where})"
2047
+ ]
2048
+ said += [
2049
+ f" {one.anchor}"
2050
+ + (f" in {one.role}" if len(self.read) > 1 else "")
2051
+ + _ownership(one)
2052
+ for one in rows
2053
+ ]
2054
+ return chr(10).join(said + self.doubled_rows())
2055
+
2056
+ said = [f"{len(self.found)} anchor(s), {len(self.retired)} retired ({where})"]
2057
+ if self.block:
2058
+ # Said whichever way it went (RK312): one family is the narrowing the rest of this
2059
+ # output is already about, and two is the answer itself — the caller picks, because
2060
+ # which subtree a new line belongs under is a judgement no file holds.
2061
+ named = ", ".join(f"§{one}" for one in self.spans)
2062
+ # The whole command and not the flag alone (RK1022): a caller arrives here from an
2063
+ # `add` refusal that named `--ref`, so a bare `--family` reads as a second flag of
2064
+ # the verb they were writing.
2065
+ picked = (
2066
+ ""
2067
+ if len(self.spans) == 1
2068
+ else f" — pick one, e.g. `{invocation()} anchors --family {self.spans[0]}`"
2069
+ )
2070
+ said.append(f" block Block {self.block}'s prose is under {named}{picked}")
2071
+ if self.family:
2072
+ for one in self.found:
2073
+ written = f" written in {one.written_in[:7]}" if one.written_in else ""
2074
+ # The file, wherever the project has more than one: two rows spelling the same
2075
+ # address are the doubling, and unlabelled they read as one row printed twice.
2076
+ named = f" in {one.role}" if len(self.read) > 1 else ""
2077
+ said.append(
2078
+ f" {'live' if one.live else 'retired':<8} {one.anchor}{named}"
2079
+ f"{written}{_ownership(one)}"
2080
+ )
2081
+ said.append(
2082
+ f" next §{next_child(self.whole, self.family)} — nothing ever used it"
2083
+ f"{self.room_left(config)}"
2084
+ )
2085
+ return chr(10).join(said + self.doubled_rows())
2086
+
2087
+ # Beside the totals and above the rows, because it is the question a reused block asks
2088
+ # first and the listing cannot be read for it (RK293): the rows are per family, and the
2089
+ # last one is only the maximum once they are ordered by the number a numeral spells.
2090
+ for space in namespaces(self.spread) if self.spread else ():
2091
+ # One line per namespace (RK340). Where a project declares no `[refs]` this is the
2092
+ # one line it always printed; where it does, the two files each continue their own
2093
+ # numbering, and a single answer would give one file the other's next address.
2094
+ fresh = next_family(self.spread, space)
2095
+ named = f" in {space}" if space else ""
2096
+ said.append(
2097
+ f" next §{fresh} — no family{named} ever used it"
2098
+ if fresh
2099
+ else f" next — these families{named} are not one numbering, so none derives"
2100
+ )
2101
+ for family in self.families():
2102
+ # The files only where there is more than one to name (RK297): on the single-file
2103
+ # project that is every project until it declares a second, it would be noise.
2104
+ across = family["files"]
2105
+ spans = f" ({', '.join(across)})" if len(across) > 1 else "" # type: ignore[arg-type]
2106
+ said.append(
2107
+ f" {family['family']:<8} {family['live']} live, {family['retired']} retired"
2108
+ f" next §{family['next']}{spans}"
2109
+ )
2110
+ if self.spent:
2111
+ said.append(
2112
+ f" {self.spent} address(es) are task ids, which `add` already refuses to reuse"
2113
+ )
2114
+ said += self.doubled_rows()
2115
+ if self.outline:
2116
+ # Named because the listing above is per family and the addresses are what the
2117
+ # caller came for: one flag away, and never printed by the hundred unasked.
2118
+ said.append(
2119
+ f" `{invocation()} anchors --family <anchor>` lists the addresses under one"
2120
+ )
2121
+ return chr(10).join(said)
2122
+
2123
+ def payload(self, config: Config, claims: bool) -> dict[str, object]:
2124
+ return {
2125
+ "role": self.role or None,
2126
+ # Every file the answer was read from, and not one (RK297): a client comparing two
2127
+ # runs needs to know which outline it was handed.
2128
+ "files": [config.relative(config.path(one)) for one in self.read],
2129
+ "family": self.family or None,
2130
+ "block": self.block or None,
2131
+ "block_families": list(self.spans),
2132
+ "live": len(self.found) - len(self.retired),
2133
+ "retired": len(self.retired),
2134
+ # The rows are the answer where a family was named, and the families are the answer
2135
+ # where none was (RK264's rule): 287 retired addresses is not a listing anybody
2136
+ # reads. Under `--claims` the rows *are* the answer whatever the family (RK459).
2137
+ "anchors": [
2138
+ _anchor_row(one)
2139
+ for one in self.found
2140
+ if self.family or (claims and _ownership(one))
2141
+ ],
2142
+ "families": [] if self.family else self.families(),
2143
+ "id_anchors": self.spent,
2144
+ # Both free addresses are the **project's** even where the listing was narrowed
2145
+ # (RK297): the field an author acts on may not be per file.
2146
+ "next": next_child(self.whole, self.family) if self.family else None,
2147
+ # The question one line up, asked **per namespace** and nowhere else (RK340,
2148
+ # RK346). One row where a project declares no `[refs]`, whose `namespace` is null,
2149
+ # and one per namespace where it does; `next` is null inside a row where those
2150
+ # top-levels are not one numbering, which is an answer and not an absence.
2151
+ #
2152
+ # Without `opens`, which the narrow payload carries and this one does not: there
2153
+ # the free address is the whole answer and the command that makes it a section is
2154
+ # what it owes (RK1140); here the listing already names every family, and a client
2155
+ # reading this one is not composing an `add --ref` off a single line.
2156
+ "next_families": []
2157
+ if self.family
2158
+ else [
2159
+ {"namespace": space or None, "next": next_family(self.spread, space)}
2160
+ for space in namespaces(self.spread)
2161
+ ],
2162
+ # What no question asked and only the gate said (RK297): an address two headings
2163
+ # answer to is one no pointer resolves against.
2164
+ "doubled": [
2165
+ {"anchor": anchor, "files": list(roles)}
2166
+ for anchor, roles in doubled(self.whole)
2167
+ ],
2168
+ }
2169
+
2170
+
2171
+ def _anchor_row(one: Anchor) -> dict[str, object]:
2172
+ return {
2173
+ "anchor": one.anchor,
2174
+ # Which file declared it, which is the whole of RK297 in one field: two rows with one
2175
+ # address are two headings, and unlabelled they read as a listing that repeated.
2176
+ "role": one.role,
2177
+ "live": one.live,
2178
+ "written_in": one.written_in or None,
2179
+ # The two facts RK453 adds, and they are two because they come apart in both
2180
+ # directions: a heading binding nobody that a line claims is RK452's write left undone
2181
+ # on an older corpus, and one binding a task no live line claims is prose whose task
2182
+ # has shipped. Null and `[]` on a retired address, which has no heading.
2183
+ "binds": one.binds or None,
2184
+ "claimed": list(one.claimed),
2185
+ "orphaned": one.orphaned,
2186
+ # The third state, told apart from the two that are (RK461): a memo is prose that was
2187
+ # never anybody's, so it is neither bound nor left behind, and a client filtering on
2188
+ # `orphaned` alone used to catch it.
2189
+ "memo": one.memo,
2190
+ }
2191
+
2192
+
2193
+ def gaps(config: Config) -> tuple[Gap, ...]:
2194
+ """Every id below the highest that no line carries, oldest number first.
2195
+
2196
+ The gaps are computed from the *entries* of both files rather than from a text scan:
2197
+ an id mentioned in prose — `agents.md` cites plenty — is still a gap, because what is
2198
+ missing is the record of a decision and not the string.
2199
+
2200
+ Per family, and in declared order (RK74): each track counts on its own, so a `C##`
2201
+ that reached 40 says nothing about which `V##` are missing, and one range walked over
2202
+ the highest id anywhere would report every unreached number of every other track.
2203
+ """
2204
+ searched = searchable(config)
2205
+ return tuple(
2206
+ gap
2207
+ for family in config.schema.prefixes
2208
+ for gap in _gaps_in(config, family, searched)
2209
+ )
2210
+
2211
+
2212
+ def searchable(config: Config) -> bool:
2213
+ """Whether an empty `git log` here means *never* rather than *cannot tell* (RK95).
2214
+
2215
+ A missing git, a directory that is not a repository and a shallow clone all return
2216
+ nothing for an id some commit does carry. Only a history that reaches its root commit
2217
+ makes the absence of a hit a fact about the id instead of one about the clone.
2218
+
2219
+ Asked once per call and not per gap: it is a property of the checkout, and the answer
2220
+ is what separates the two ways :class:`Gap` has of holding no commit.
2221
+ """
2222
+ try:
2223
+ answer = _run(config.root, "rev-parse", "--is-shallow-repository").strip()
2224
+ except HistoryUnavailable:
2225
+ return False
2226
+ return answer == "false"
2227
+
2228
+
2229
+ def _gaps_in(config: Config, family: str, searched: bool) -> tuple[Gap, ...]:
2230
+ from roadkeep.ids import highest # here, because ids.py reads this module's config
2231
+
2232
+ top = highest(config, family)
2233
+ if top is None:
2234
+ return ()
2235
+ recorded: set[int] = set()
2236
+ for role in ("roadmap", "changelog"):
2237
+ if not config.has(role) or not config.path(role).is_file():
2238
+ continue
2239
+ for task_id in config.document(role).by_id():
2240
+ number = _number(task_id, family)
2241
+ if number is not None:
2242
+ recorded.add(number)
2243
+ return tuple(
2244
+ Gap(
2245
+ id=f"{family}{number}",
2246
+ number=number,
2247
+ removed_in=_last_touching(config, f"**{family}{number}**"),
2248
+ searched=searched,
2249
+ )
2250
+ for number in range(1, top.number + 1)
2251
+ if number not in recorded
2252
+ )
2253
+
2254
+
2255
+ def _number(task_id: str, prefix: str) -> int | None:
2256
+ tail = task_id[len(prefix) :] if task_id.startswith(prefix) else ""
2257
+ return int(tail) if tail.isdigit() else None
2258
+
2259
+
2260
+ def _last_touching(config: Config, needle: str) -> Commit | None:
2261
+ """The last commit whose roadmap diff mentions the id — where the line left.
2262
+
2263
+ The last and not the first: the first added it. A removal is not distinguished from a
2264
+ rewording here, because a line that was reworded and is now absent still left in that
2265
+ commit, and the commit message is what the reader is being sent to read.
2266
+ """
2267
+ try:
2268
+ found = _touching_role(config, needle, "roadmap")
2269
+ except HistoryUnavailable:
2270
+ return None
2271
+ return found[-1] if found else None
2272
+
2273
+
2274
+ def _first_touching(config: Config, needle: str, role: str) -> Commit | None:
2275
+ found = _touching_role(config, needle, role)
2276
+ return found[0] if found else None
2277
+
2278
+
2279
+ def _touching_role(
2280
+ config: Config, needle: str, role: str, *, literal: bool = True
2281
+ ) -> tuple[Commit, ...]:
2282
+ if not config.has(role):
2283
+ return ()
2284
+ try:
2285
+ relative = config.path(role).relative_to(config.root)
2286
+ except ValueError:
2287
+ relative = config.path(role)
2288
+ return commits_touching(config.root, needle, relative, literal=literal)
2289
+
2290
+
2291
+ @dataclass(frozen=True, slots=True)
2292
+ class Gapped:
2293
+ """Every id below the highest that no file carries, as one result (RK1170).
2294
+
2295
+ The second verb moved to the shape RK1170 asks for, and `weight`'s reasons hold unchanged:
2296
+ both registers are derived here, beside the numbers, so the payload carries what the printed
2297
+ answer showed by construction. What the handler keeps is the door — run it, and say which
2298
+ register was asked for.
2299
+
2300
+ The two registers differ on purpose, and here that difference is the whole of RK1165: the
2301
+ printed one collapses a **contiguous run** of never-carried ids into a single row, because 499
2302
+ of this repository's own 503 lines were a numbering jump saying one sentence with a different
2303
+ number. The payload keeps every id, a key costing a client nothing to skip where a line costs
2304
+ every reader the same attention.
2305
+ """
2306
+
2307
+ gaps: tuple[Gap, ...]
2308
+
2309
+ def __str__(self) -> str:
2310
+ if not self.gaps:
2311
+ return "no gaps: every id below the highest is in one of the files"
2312
+ rows: list[tuple[str, str]] = []
2313
+ at = 0
2314
+ for gap, run in _runs(self.gaps):
2315
+ where = gap.id if run == 1 else f"{gap.id}–{self.gaps[at + run - 1].id}"
2316
+ at += run
2317
+ if gap.never_carried:
2318
+ # **Every** run and not a long one (RK1165): a threshold would be a number nobody
2319
+ # can re-read, and two consecutive ids in one row is the same information rather
2320
+ # than less. What decides the row is contiguity, which is a fact and not a
2321
+ # judgement about why the numbering skipped.
2322
+ counted = "" if run == 1 else f" ({run} ids)"
2323
+ rows.append(
2324
+ (where, f"never carried the whole history mentions it nowhere{counted}")
2325
+ )
2326
+ elif gap.removed_in is None:
2327
+ rows.append((where, "unresolvable no history here to search"))
2328
+ else:
2329
+ commit = gap.removed_in
2330
+ rows.append((where, f"{commit.short} {commit.date[:10]} {commit.subject}"))
2331
+ # Padded to the widest label, which a range is: a column sized for one id puts the
2332
+ # sentence of a collapsed row in a different place from every other one.
2333
+ width = max(len(label) for label, _ in rows)
2334
+ resolved = sum(1 for gap in self.gaps if gap.resolved)
2335
+ skipped = sum(1 for gap in self.gaps if gap.never_carried)
2336
+ tail = f", {skipped} never carried" if skipped else ""
2337
+ return "\n".join(
2338
+ [
2339
+ *(f" {label:<{width}} {said}" for label, said in rows),
2340
+ f"{len(self.gaps)} gap(s), {resolved} resolved against history{tail}",
2341
+ ]
2342
+ )
2343
+
2344
+ def payload(self) -> list[dict[str, object]]:
2345
+ """Every gap, one row each — the runs the printed answer collapses are the reader's cost.
2346
+
2347
+ The commit is the four fields a caller reaches an id's departure by, and `None` where
2348
+ history was searched and answered nothing: *unresolvable* and *never carried* are two
2349
+ different absences (RK95), which the two flags beside it tell apart.
2350
+ """
2351
+ return [
2352
+ {
2353
+ "id": gap.id,
2354
+ "resolved": gap.resolved,
2355
+ "never_carried": gap.never_carried,
2356
+ "removed_in": None
2357
+ if gap.removed_in is None
2358
+ else {
2359
+ "sha": gap.removed_in.sha,
2360
+ "short": gap.removed_in.short,
2361
+ "date": gap.removed_in.date,
2362
+ "subject": gap.removed_in.subject,
2363
+ },
2364
+ }
2365
+ for gap in self.gaps
2366
+ ]
2367
+
2368
+
2369
+ def _runs(found: Sequence[Gap]) -> list[tuple[Gap, int]]:
2370
+ """Each gap with how many **contiguous never-carried** ids start there (RK1165).
2371
+
2372
+ Only that kind runs together: a gap resolved against history carries a commit of its own and
2373
+ two of them are two answers, however adjacent their numbers. What a run of never-carried ids
2374
+ carries is one sentence repeated, and this is what lets the row say it once.
2375
+
2376
+ Contiguity is read off the numbers the ids spell, which `next_id` already treats as a
2377
+ sequence — a prefix change ends a run for free, two families being two sequences.
2378
+ """
2379
+ out: list[tuple[Gap, int]] = []
2380
+ index = 0
2381
+ while index < len(found):
2382
+ gap = found[index]
2383
+ run = 1
2384
+ if gap.never_carried:
2385
+ while index + run < len(found) and _follows(found[index + run - 1], found[index + run]):
2386
+ run += 1
2387
+ out.append((gap, run))
2388
+ index += run
2389
+ return out
2390
+
2391
+
2392
+ def _follows(earlier: Gap, later: Gap) -> bool:
2393
+ """Whether one never-carried id is the next number after another, in the same family."""
2394
+ if not later.never_carried:
2395
+ return False
2396
+ one, two = _numbered(earlier.id), _numbered(later.id)
2397
+ return one is not None and two is not None and one[0] == two[0] and two[1] == one[1] + 1
2398
+
2399
+
2400
+ def _numbered(task_id: str) -> tuple[str, int] | None:
2401
+ """An id as its family and its number, or None where it spells neither."""
2402
+ found = re.match(r"^([A-Za-z]+)(\d+)$", task_id)
2403
+ return (found[1], int(found[2])) if found else None