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/sections.py ADDED
@@ -0,0 +1,4121 @@
1
+ """Prose files have a different unit, so they get a different schema (RK9).
2
+
3
+ Three of the four governed files are lines; two are paragraphs. A rationale or a strategy
4
+ is prose under a heading, and applying the line schema to it would be the wrong law
5
+ twice over: there is no `symptom` to bound and no 320-character cap that means anything
6
+ about a paragraph. What a section *does* have is:
7
+
8
+ * **an anchor**, which is the whole reason the pointer on a task line resolves (RK27) —
9
+ so `§RK9` must name an open task, and a typo names nothing at all. Read **per scheme**
10
+ (RK44): `id` requires the § that tells an id from a word, while an outline numbers its
11
+ own headings and puts the sigil on the pointer alone, so reading one spelling into the
12
+ other turned Shio's 151 headings into 0 sections and 74 pointers into 74 dangling ones;
13
+ * **a word budget**, because the failure mode measured here was a rationale file reaching
14
+ 539 KB one honest paragraph at a time — a limit in words is the one an author can act
15
+ on before writing, which is the same argument as `add`'s (L1);
16
+ * **a place**, which is derived twice over: a section for a task belongs under that task's
17
+ block, and a section for no task belongs under the section its anchor extends (RK45) —
18
+ §0.4 after §0.3, §RK34.1 inside §RK34. So the file's shape is a consequence of the
19
+ backlog's and of the outline's, and nobody chooses where to type.
20
+
21
+ `amend` is the door that was missing (RK123). Three correct refusals — `drop` while a live
22
+ pointer names the anchor, `add` on the duplicate, and the guard on the hand edit — added up
23
+ to a rationale that could not be corrected at all while its task was open, which is exactly
24
+ when a design changes. It rewrites the heading text and the section's **own** prose, never
25
+ the subtree and never the anchor: a subsection has an anchor of its own to be named by, and
26
+ an address under the id scheme is `renumber`'s.
27
+
28
+ `move` is the same sentence's other half (RK377). Under an outline the anchor is *not* an id,
29
+ so `renumber` never reaches it — line 172 there keeps the pointer as typed — and a doubled
30
+ address had no verb at all: `lint` reports `section.ambiguous`, `add` refuses the second one,
31
+ and Turing adopted the tool with 13 addresses its two prose files both declared. So the
32
+ re-address is a door, taking every refusal `add` computes about a destination
33
+ (:func:`unspent`) and moving the whole address in one transaction — the heading, every nested
34
+ anchor that extends it, and the `→ §<anchor>` on every line that points at one of them. Which
35
+ line meant which of two doubled sections is the thing the files do not say, so the pointers
36
+ move with the heading and are **named** in the answer, for the reason
37
+ :mod:`~roadkeep.renumbering` names the deps it moved. Only within the address's own parent:
38
+ the section stays where it is in the file, and a heading re-addressed across parents would
39
+ sit inside a subtree its address no longer names — where the next `drop` takes it.
40
+
41
+ `drop` is the operation `ship` (RK6) calls for rule one of its three edits — it lives here
42
+ rather than there because deleting a section is a fact about this file's grammar, not
43
+ about shipping, and the two would otherwise disagree about where a section ends. It takes
44
+ the **whole subtree**, and is refused before it writes when that subtree holds a section
45
+ some other open line points at (RK78): a heading nested under another is that other's
46
+ prose, right up until a second pointer names it, and then deleting it is a deletion the
47
+ transaction never named — measured on Shio, 160 lines removed by a command that reported
48
+ dropping one section, leaving two live pointers resolving to nothing.
49
+
50
+ Reflow is deliberately narrow. A plain paragraph is filled to the configured width, and
51
+ anything carrying a Markdown structure — a table, a list, a quote, a fence — is inserted
52
+ exactly as written: the tool re-flows prose, and never reformats a shape it did not
53
+ author. That is the same line L4 draws, one file down.
54
+ """
55
+
56
+ from __future__ import annotations
57
+
58
+ import re
59
+ import textwrap
60
+ from collections.abc import Iterator, Mapping, Sequence
61
+ from dataclasses import dataclass, field, replace
62
+ from typing import TYPE_CHECKING
63
+
64
+ from roadkeep.backlog import Whereabouts
65
+ from roadkeep.config import PROSE_ROLES, Config
66
+ from roadkeep.kernel.document import Document, Heading, UnknownBlock, blank, save_all
67
+ from roadkeep.kernel.schema import (
68
+ OUTLINE_ANCHOR_RE,
69
+ REF_SEPARATOR,
70
+ Schema,
71
+ SchemaError,
72
+ Task,
73
+ Violation,
74
+ over_by,
75
+ split_ref,
76
+ )
77
+
78
+ if TYPE_CHECKING: # imported for the annotation alone: `history` reads this module back
79
+ from roadkeep.history import Anchor
80
+
81
+ #: Openers that are a shape whatever follows them: a table row, a blockquote, a fence. No
82
+ #: space is required after any of these, `|a|b|` and `>quoted` both being legal Markdown.
83
+ _VERBATIM = ("|", ">", "```", "~~~")
84
+ #: A list marker or a heading, which is the character **and the space after it** (RK397). The
85
+ #: space is the whole rule: `*` was read as a bullet, so a prose line breaking before a
86
+ #: `**bold**` span made the paragraph a structure and the tool stopped filling it — silently,
87
+ #: `lint` charging a body in words and never in width. `1.5 seconds` fell the same way.
88
+ _MARKER = re.compile(r"(?:[-*+]|#{1,6}|\d+[.)])(?:\s|$)")
89
+ #: The same characters with no space, which is a thematic break and is still a shape. Kept
90
+ #: apart from :data:`_MARKER` rather than folded in, because the two are opposite readings of
91
+ #: one prefix and a rule that guessed between them is the defect above with a longer alphabet.
92
+ _BREAK = re.compile(r"(?:-{3,}|\*{3,}|_{3,})\s*$")
93
+ #: What opens a block whose contents are quoted or generated rather than written (RK136).
94
+ _FENCES = ("```", "~~~")
95
+ #: A line that is data rather than argument, so the budget does not charge for it. A list
96
+ #: marker is deliberately absent: a bullet is how an argument is written in these files.
97
+ _DATA = ("|", ">")
98
+
99
+
100
+ class SectionError(SchemaError):
101
+ """A section the schema refuses, carrying every violation, not the first.
102
+
103
+ A :class:`~roadkeep.kernel.schema.SchemaError` because it is the same law one file down —
104
+ which also means every caller that already reports violations reports these.
105
+ """
106
+
107
+
108
+ class NoSuchSection(ValueError):
109
+ """An anchor nothing in this file declares."""
110
+
111
+ def __init__(self, anchor: str, where: str = "", *, titled_too: bool = False) -> None:
112
+ self.anchor = anchor
113
+ # `titled_too` where the caller also tried the address as a **heading text** (RK1107):
114
+ # `show` and `amend` look an anchor up first and fall through to the title, so a
115
+ # refusal naming only the anchor would describe half the lookup that failed.
116
+ said = f"no §{anchor} section in {where or 'the document'}"
117
+ if titled_too:
118
+ said += f", and no heading reading {anchor!r} either"
119
+ super().__init__(said)
120
+
121
+
122
+ class NotOneOccurrence(ValueError):
123
+ """`--replace` naming a string this prose does not hold exactly once (RK1263).
124
+
125
+ The refusal that makes the narrow edit safe. A substitution applied to whatever it happens
126
+ to match is a write whose blast radius the caller cannot see, which is the property the
127
+ whole-body form at least had — so the count is the contract: none means the string was
128
+ mistyped or already corrected, and several mean the call is ambiguous about which.
129
+
130
+ Neither is answered by picking one. The first occurrence is a guess, and `str.replace`'s own
131
+ default — all of them — is the edit a caller reaching for a one-clause fix least expects.
132
+ """
133
+
134
+ def __init__(self, old: str, found: int, where: str) -> None:
135
+ self.old = old
136
+ self.found = found
137
+ said = (
138
+ f"{where} does not carry {old!r}"
139
+ if found == 0
140
+ else f"{where} carries {old!r} {found} times"
141
+ )
142
+ advice = (
143
+ "check the spelling against `section show`, which prints the prose as it is"
144
+ if found == 0
145
+ else "pass a longer string that occurs once, or --body for the whole prose"
146
+ )
147
+ super().__init__(f"--replace names one occurrence and {said}: {advice}")
148
+
149
+
150
+ @dataclass(frozen=True, slots=True)
151
+ class Substitution:
152
+ """One string out and one string in, for an edit whose blast radius is the call (RK1263).
153
+
154
+ `amend` takes the whole body, so correcting one stale citation meant copying the section's
155
+ table, fence and block quote out of the file, retyping the clause and passing all of it
156
+ back — eight times over, on a corpus of eight sections whose prose was right except for one
157
+ reference each. Every round trip can drop a pipe from a row or a backtick from a fence, and
158
+ nothing checks: a body is prose to this tool, so a mangled fence validates exactly like a
159
+ clean one.
160
+
161
+ A pair and not two arguments threaded separately, because :meth:`applied` is the rule — one
162
+ occurrence or a refusal — and a caller holding the halves apart is a caller who could apply
163
+ it without asking. The whole-body form stays for a real rewrite.
164
+ """
165
+
166
+ old: str
167
+ new: str
168
+
169
+ def applied(self, prose: str, where: str) -> str:
170
+ """The prose with its one occurrence replaced, or :class:`NotOneOccurrence`.
171
+
172
+ **Matched with the wrapping collapsed** (RK1312). A section is written to a prose
173
+ width, so any sentence longer than that width is stored with a newline and some
174
+ indentation inside it — and a caller quoting the sentence, which is how the prose reads
175
+ to anybody looking at it, was refused for text the section plainly carries. Observed in
176
+ pportal, 2026-08-22, twice in one task: both fragments were full sentences copied from
177
+ `section show`, which prints the prose as it is, so the command the refusal recommends
178
+ is the command that produces the text the refusal rejected.
179
+
180
+ It also made this flag weaker than it looks. A short fragment is what fits inside one
181
+ stored line, and a short fragment is what *occurs exactly once* refuses — the two rules
182
+ pushed in opposite directions and the caller landed between them.
183
+
184
+ The stored form does not change: what is found is a **span** of the prose as it sits,
185
+ and the replacement is spliced into it, so a table or a fence the needle happens to
186
+ neighbour is untouched. A run of whitespace holding two newlines is a paragraph break
187
+ and stays a barrier — a needle is a sentence, and one that matched across a blank line
188
+ would be reaching into prose the caller was not looking at.
189
+ """
190
+ spans = _spans(prose, self.old)
191
+ if len(spans) != 1:
192
+ raise NotOneOccurrence(self.old, len(spans), where)
193
+ first, last = spans[0]
194
+ return prose[:first] + self.new + prose[last:]
195
+
196
+
197
+ #: What a paragraph break becomes while a needle is looked for (RK1312) — a character no
198
+ #: needle can carry, so a fragment holding a single space cannot match across a blank line.
199
+ _PARAGRAPH = "\x00"
200
+
201
+ #: A run of whitespace, which is what wrapping is made of. Matched whole so the run's own
202
+ #: newline count decides whether it is a space or a barrier.
203
+ _WHITESPACE = re.compile(r"\s+")
204
+
205
+
206
+ def _flattened(prose: str) -> tuple[str, tuple[int, ...]]:
207
+ """The prose with its wrapping collapsed, and where each character came from (RK1312).
208
+
209
+ The index list is the whole point: a needle is found in the flat text and replaced in the
210
+ stored one, so nothing about how the file holds its paragraphs has to change. Every flat
211
+ character maps to the offset it started at, and the list carries one entry past the end so
212
+ a match ending on the last character has a stop to name.
213
+ """
214
+ out: list[str] = []
215
+ at: list[int] = []
216
+ index = 0
217
+ for part in _WHITESPACE.split(prose):
218
+ run = _WHITESPACE.match(prose, index + len(part))
219
+ out.append(part)
220
+ at.extend(range(index, index + len(part)))
221
+ index += len(part)
222
+ if run is None:
223
+ continue
224
+ # Two newlines is a paragraph break and one is a wrap: the first stays a barrier and
225
+ # the second becomes the space the reader sees.
226
+ out.append(_PARAGRAPH if run.group().count("\n") > 1 else " ")
227
+ at.append(index)
228
+ index = run.end()
229
+ at.append(len(prose))
230
+ return "".join(out), tuple(at)
231
+
232
+
233
+ def _spans(prose: str, needle: str) -> list[tuple[int, int]]:
234
+ """Every span of ``prose`` whose collapsed text reads as ``needle`` (RK1312).
235
+
236
+ Empty for a needle that is only whitespace, which is not a fragment of anything: the
237
+ caller passed nothing to look for, and reporting the prose's every gap as a match would
238
+ turn a mistyped argument into an ambiguity refusal about the wrong thing.
239
+ """
240
+ wanted = " ".join(needle.split())
241
+ if not wanted:
242
+ return []
243
+ flat, at = _flattened(prose)
244
+ out: list[tuple[int, int]] = []
245
+ start = flat.find(wanted)
246
+ while start != -1:
247
+ out.append((at[start], at[start + len(wanted) - 1] + 1))
248
+ start = flat.find(wanted, start + 1)
249
+ return out
250
+
251
+
252
+ class SectionExists(ValueError):
253
+ """One anchor, one section: two would make the pointer ambiguous.
254
+
255
+ Asked of **the project's declarations and not the file's** (RK302). This checked the
256
+ document it was writing into and nobody else, so on a project declaring two prose roles
257
+ the same four `section add` calls into each file all succeeded and printed their line
258
+ counts — and `lint` then reported four `section.ambiguous` findings whose own message is
259
+ the argument for refusing here: one anchor names one section, so no pointer resolves and
260
+ every verb that reads one refuses. The write path was building a state its own gate calls
261
+ unresolvable, out of which `drop` was the only exit — and that deletes prose somebody
262
+ wrote.
263
+
264
+ No `--force`, deliberately. RK297's measurement is that the doubled anchors in both live
265
+ corpora were made by hand rather than by this verb, so a door that never opens is the
266
+ cheaper answer than one whose only correct use is a hand edit the guard already denies.
267
+ """
268
+
269
+ def __init__(
270
+ self, anchor: str, where: str, lineno: int, *, elsewhere: bool = False
271
+ ) -> None:
272
+ self.anchor = anchor
273
+ self.lineno = lineno
274
+ self.elsewhere = elsewhere
275
+ span = (
276
+ "an anchor names one section across every prose file this project declares"
277
+ if elsewhere
278
+ else "an anchor names one section"
279
+ )
280
+ super().__init__(
281
+ f"§{anchor} is already at {where}:{lineno}: {span}, "
282
+ f"and a pointer that resolves to two resolves to neither"
283
+ )
284
+
285
+
286
+ class SectionOccupied(ValueError):
287
+ """A drop whose subtree holds prose another open line owns (RK78).
288
+
289
+ The counterpart, one level down, of the multi-owner check `ship` already makes about the
290
+ anchor it was given: that one asks who else points *here*, and this one asks who else
291
+ points at anything **nested** here. Both refuse rather than repair, because a drop is
292
+ contiguous — a subtree with a stranger in the middle has no partial deletion that is not
293
+ a decision about someone else's prose — and the author's remedy is to lift the section
294
+ out or to ship the line that claims it.
295
+
296
+ Refused *before* the write and not reported after, which is the whole difference this
297
+ closes: `lint` named the damage as two `ref.unresolved` immediately afterwards, by which
298
+ point the only remedy was `git checkout` on the file, discarding the part of the ship
299
+ that was correct along with the part that was not (L1, one verb along from `add`).
300
+ """
301
+
302
+ def __init__(
303
+ self, anchor: str, occupied: Sequence[tuple[str, Sequence[str]]], where: str = ""
304
+ ) -> None:
305
+ self.anchor = anchor
306
+ self.occupied = tuple((child, tuple(owners)) for child, owners in occupied)
307
+ named = ", ".join(
308
+ f"§{child} ({', '.join(owners)})" for child, owners in self.occupied
309
+ )
310
+ file = f" in {where}" if where else ""
311
+ super().__init__(
312
+ f"§{anchor}{file} nests {len(self.occupied)} section(s) another open line "
313
+ f"points at: {named} — dropping it deletes prose this transaction never "
314
+ f"named, and leaves those pointers resolving to nothing"
315
+ )
316
+
317
+
318
+ class SectionClaimed(ValueError):
319
+ """A drop of the section an open line points at, refused before the write (RK112).
320
+
321
+ :class:`SectionOccupied` one level up, and the level that was missing: that one asks who
322
+ points at anything *nested* under the anchor, `ship` asks who else points *at* it — and
323
+ `section drop`, the verb whose whole job is removing one section, asked neither. Found by
324
+ using the tool: `section drop VIII.11` succeeded on a section stale by every other
325
+ measure, and the next `lint` reported `ref.unresolved` for an open line that owned it.
326
+
327
+ A refusal and not a report, because the drop was one of seven in a triage pass: `lint`
328
+ names the damage afterwards, and by then `git checkout` discards the six that were right
329
+ along with the one that was not. `ship` still drops its own task's section — that caller
330
+ passes ``leaving``, so the claim that is the reason for the drop is not one of these.
331
+ """
332
+
333
+ def __init__(
334
+ self, anchor: str, owners: Sequence[str], where: str = "", *, recorded: bool = False
335
+ ) -> None:
336
+ self.anchor = anchor
337
+ self.owners = tuple(owners)
338
+ file = f" in {where}" if where else ""
339
+ # The decisions file claims by id and has no door out (RK1361), so the two remedies
340
+ # below are both wrong there: there is no pointer to repoint and no line to ship. What
341
+ # a body written badly takes is `section amend`, which is the same escape the entry
342
+ # one line above it has.
343
+ if recorded:
344
+ super().__init__(
345
+ f"§{anchor}{file} is the body of {', '.join(self.owners)}, a decision this "
346
+ f"file still records — nothing here is ever deleted, a superseded entry "
347
+ f"included: `section amend {anchor} --role decisions --body -` is how prose "
348
+ f"that came out wrong is corrected"
349
+ )
350
+ return
351
+ super().__init__(
352
+ f"§{anchor}{file} is pointed at by {', '.join(self.owners)} — dropping it "
353
+ f"leaves {'that pointer' if len(self.owners) == 1 else 'those pointers'} "
354
+ f"resolving to nothing: repoint the line, or ship the one that claims it"
355
+ )
356
+
357
+
358
+ class AnchorClaimed(ValueError):
359
+ """A drop whose anchor an open line's pointer descends from, by name (RK169).
360
+
361
+ :class:`SectionOccupied` decides ownership by walking the *sections* inside the span, and
362
+ a section is a **heading**. Measured adopting Turing: `section drop XIV` was accepted and
363
+ took `§XIV.8` with it, and under that heading sat
364
+ `- **XIV.8.7 — ship Cloud default config as a GLOBAL seed ZIP (T373).**` — the design of
365
+ an open task, deleted without a word, because a bullet is not a section and the subtree
366
+ looked unowned.
367
+
368
+ Two things were true there and only one of them was a defect. That T373's pointer did not
369
+ resolve is Turing's, and `lint` says so. That the verb whose whole job is *the orphan*
370
+ deleted a live design **because** the pointer was already broken is this tool's: the
371
+ finding made the content invisible to the guard that would have protected it, so two
372
+ reports compounded into data loss.
373
+
374
+ So the guard reads the **name** and not the shape. An address under the anchor is claimed
375
+ prose whether the corpus writes it as a heading, as a bullet or as a table row — which
376
+ needs no parsing of the prose at all, and is exactly the check the adoption script had to
377
+ write by hand before it could proceed safely.
378
+ """
379
+
380
+ def __init__(
381
+ self, anchor: str, claimed: Sequence[tuple[str, Sequence[str]]], where: str = ""
382
+ ) -> None:
383
+ self.anchor = anchor
384
+ self.claimed = tuple((ref, tuple(owners)) for ref, owners in claimed)
385
+ named = ", ".join(f"§{ref} ({', '.join(owners)})" for ref, owners in self.claimed)
386
+ file = f" in {where}" if where else ""
387
+ super().__init__(
388
+ f"§{anchor}{file} is above {named}, which an open line points at: a drop takes "
389
+ f"everything under the anchor, and an address under it is claimed prose whether "
390
+ f"this file writes it as a heading or as a bullet — repoint the line, or ship "
391
+ f"the one that claims it"
392
+ )
393
+
394
+
395
+ class AnchorRetired(ValueError):
396
+ """An outline address a heading already used, and a ship deleted (RK247).
397
+
398
+ :class:`SectionExists` for the anchors that are no longer there. Under an outline the
399
+ caller names the anchor, and the only list they are ever shown is of the sections that
400
+ **exist** — so after a fully-shipped family "the next one" looks like `.1`, and writing
401
+ it silently re-points every ledger entry whose prose cites that address at prose about
402
+ something else. `as_ledger` keeps no pointer, so nothing in the files says the address
403
+ was ever spent; the diff does, which is where this reads it.
404
+
405
+ The same rule ids have had since RK4, one file over: retired-never-reused. The remedy is
406
+ an address nobody used, so the refusal carries the derived one rather than sending the
407
+ author to grep a ledger — which is how the safe number was found before this existed.
408
+ """
409
+
410
+ def __init__(self, anchor: str, written_in: str, free: str = "", where: str = "") -> None:
411
+ self.anchor = anchor
412
+ self.written_in = written_in
413
+ #: The derived free child, or empty for a **top-level** address: what follows
414
+ #: `XXXVII` is somebody's numbering — roman, lettered, a phase — and inventing the
415
+ #: next one would be this tool choosing an author's outline (L4).
416
+ self.free = free
417
+ file = f" in {where}" if where else ""
418
+ commit = f" ({written_in[:7]})" if written_in else ""
419
+ remedy = (
420
+ f"§{free} is the next one nothing ever used"
421
+ if free
422
+ else "name an address this file has never declared"
423
+ )
424
+ super().__init__(
425
+ f"§{anchor}{file} was declared before{commit} and its section is gone: the "
426
+ f"entries whose prose cites it are still there, and reusing the address makes "
427
+ f"them cite this — {remedy}"
428
+ )
429
+
430
+
431
+ class UnknownParent(ValueError):
432
+ """An anchor states its place, and this file declares nothing it extends (RK45).
433
+
434
+ The counterpart of :class:`~roadkeep.kernel.document.UnknownBlock`, for prose that belongs to
435
+ no task: a §0.4 appended after the last block reads as that block's rationale, which is
436
+ the mistake this module already refuses one case over. So everything under the top level
437
+ is derived, and a **nested** anchor whose parent is missing stays a refusal — that is a
438
+ typo in an address, and appending it would file somebody's paragraph under a design it
439
+ does not extend.
440
+
441
+ What is no longer refused is the **top level itself** (RK166). "A heading that is merely
442
+ missing is a heading they can add" was this class's own argument, and the guard denies
443
+ exactly that edit — RK141's deadlock, one file over: `block add` skips a prose file
444
+ organised by an outline rather than by blocks, so a newly declared block's first section
445
+ was reachable by nothing at all. A top-level anchor under an outline is now placed after
446
+ the last top-level section, which is the same derivation this file already makes one
447
+ level down.
448
+
449
+ ``opens`` is every ancestor of this anchor the file does not declare, outermost first
450
+ (RK1207). Until it existed every clause of this sentence was true and none of them was a
451
+ verb: the listing of what the file declares came closest, and on a file whose outline has
452
+ not started that listing is the word `none`. The write that makes room is the **same
453
+ command one address up**, which is why it reads as a wall rather than a step — a caller
454
+ told `section add` refuses naturally looks for a different verb, and there is none.
455
+
456
+ Derived rather than described, so what is left for the author is the title, which is
457
+ editorial and L4's to leave alone. A chain, because `§I.1.2` on an empty outline is two
458
+ calls before this one: reporting the first alone is the staircase RK1198 took out of the
459
+ door one file over, and this is the same staircase met by a caller who arrived directly —
460
+ writing a design before the line, which is the order an outline invites.
461
+
462
+ ``role`` rides with it for RK197's reason: a project whose only prose file is the strategy
463
+ one would be handed `section add`'s default, which is a remedy that cannot run.
464
+ """
465
+
466
+ def __init__(
467
+ self,
468
+ anchor: str,
469
+ declared: Sequence[str],
470
+ where: str = "",
471
+ *,
472
+ opens: Sequence[str] = (),
473
+ role: str = "",
474
+ ) -> None:
475
+ from roadkeep.provenance import invocation # noqa: PLC0415 - RK260
476
+
477
+ self.anchor = anchor
478
+ self.declared = tuple(declared)
479
+ self.opens = tuple(opens)
480
+ known = ", ".join(f"§{a}" for a in self.declared) or "none"
481
+ file = f"{where} " if where else ""
482
+ named = "" if role in ("", "improvements") else f" --role {role}"
483
+ steps = ", then ".join(
484
+ f"`{invocation()} section add {one} --title …{named}`" for one in self.opens
485
+ )
486
+ # Silent where nothing derives one, which is a one-segment anchor under the id scheme:
487
+ # there this refusal means the id names no open line, and a `section add` above it
488
+ # would be an address invented out of a task number.
489
+ opening = f" — {steps} opens what it extends" if self.opens else ""
490
+ super().__init__(
491
+ f"no section §{anchor} extends ({file}declares: {known}): an anchor states "
492
+ f"its own place, and appending files the prose under the last block{opening}"
493
+ )
494
+
495
+
496
+ class SameAnchor(ValueError):
497
+ """A move to the address the section already carries (RK377)."""
498
+
499
+ def __init__(self, anchor: str) -> None:
500
+ self.anchor = anchor
501
+ super().__init__(
502
+ f"§{anchor} already is that address: a move that changes nothing would still "
503
+ f"rewrite the file, and an untouched file with a moved mtime reads as an edit"
504
+ )
505
+
506
+
507
+ class AnchorIsId(ValueError):
508
+ """A re-address under `ref_scheme = "id"`, where the address is the task's (RK377).
509
+
510
+ The one scheme this verb has nothing to do. There the anchor *is* the id, so a section
511
+ whose address moved and whose line did not is a section its own task no longer points at
512
+ — and moving both is :func:`~roadkeep.renumbering.renumber`, which does it in one
513
+ transaction with every dep. The other reason to be here is a doubled anchor, and under
514
+ this scheme that is two files holding one task's design rather than two addresses
515
+ colliding: one of them is the design and the other is a copy, which is `section drop`.
516
+ """
517
+
518
+ def __init__(self, anchor: str, where: str = "") -> None:
519
+ self.anchor = anchor
520
+ file = f" in {where}" if where else ""
521
+ super().__init__(
522
+ f"§{anchor}{file} is addressed by its task's id, so the address is not this "
523
+ f"verb's to move: `renumber {anchor} --to <id>` moves the line, the heading, the "
524
+ f"subtree and every dep together, and a second file holding the same design is "
525
+ f"`section drop`"
526
+ )
527
+
528
+
529
+ class NotASibling(ValueError):
530
+ """A destination under a different parent, which is a relocation and not a move (RK377).
531
+
532
+ The bound that keeps this verb honest about what it does. A section's **place** is derived
533
+ from its address (RK45), and this write changes the address without moving a line of prose
534
+ — which is right while the parent is the same, and wrong the moment it is not: a `§XIV.5`
535
+ re-addressed in place still sits inside `§I`'s subtree, where :func:`_span` ends it, `drop`
536
+ takes it and `_extends` reads the file's shape past it. So the two would disagree, and the
537
+ disagreement is invisible until a deletion acts on it.
538
+
539
+ Refused rather than relocated, because relocating carries prose the caller never named:
540
+ a subtree holds sections other lines point at (:class:`SectionOccupied`'s whole argument),
541
+ and re-levelling one to fit a new depth is a rewrite of headings nobody asked about.
542
+ """
543
+
544
+ def __init__(self, anchor: str, to: str, parent: str, free: str = "") -> None:
545
+ self.anchor = anchor
546
+ self.to = to
547
+ self.parent = parent
548
+ #: The free address under that parent, where history could be read for it (RK1378).
549
+ #: This refusal named the family and stopped, and a caller has no way to the address
550
+ #: but a guess — which is the last step every other complete door here already takes:
551
+ #: `add --ref` on a block whose prose has not started carries the whole path with the
552
+ #: arguments filled in. Empty where `anchors` could not be read, and then the sentence
553
+ #: names *that* read rather than claiming an address it does not have.
554
+ self.free = free
555
+ under = f"under §{parent}" if parent else "at the top level"
556
+ from roadkeep.provenance import invocation # noqa: PLC0415 - RK260
557
+
558
+ # The address, or the read that gives it. Never a composed `section move`: the address
559
+ # is derivable and which sibling a heading should become is the caller's, so what is
560
+ # offered is the free anchor and not a call somebody would run without reading.
561
+ says = (
562
+ f", where §{free} is free"
563
+ if free
564
+ else f" (`{invocation()} anchors --family {parent}` says which is free)"
565
+ if parent
566
+ else ""
567
+ )
568
+ super().__init__(
569
+ f"§{anchor} cannot move to §{to}: this write changes the address and not the "
570
+ f"place, so a destination under another parent leaves the heading inside the "
571
+ f"subtree it no longer names — name an address {under}{says}"
572
+ )
573
+
574
+
575
+ def _free_under(config: Config, family: str) -> str:
576
+ """The next address nothing under ``family`` ever used, or `""` (RK1378).
577
+
578
+ :func:`~roadkeep.history.next_child` and never a count of the headings on file, for that
579
+ function's own reason: an address a ship retired is spent, and a family reopened over one
580
+ is the collision `section add` refuses by name. So this reads history, and where history
581
+ cannot be read — a checkout with no git, a repository this process cannot run — it answers
582
+ nothing and the refusal names the command instead of stating an address it did not get.
583
+ """
584
+ if not family:
585
+ return ""
586
+ from roadkeep.history import HistoryUnavailable, anchors, next_child # noqa: PLC0415 - RK260
587
+
588
+ try:
589
+ return next_child(anchors(config), family)
590
+ except (HistoryUnavailable, OSError):
591
+ return ""
592
+
593
+
594
+ @dataclass(frozen=True, slots=True)
595
+ class Section:
596
+ """A heading, its prose, and the lines it occupies. ``last`` includes the blank."""
597
+
598
+ anchor: str
599
+ title: str
600
+ level: int
601
+ first: int # 1-based, as an editor counts
602
+ last: int
603
+ body: str = ""
604
+ #: This section's **own** prose, where :attr:`body` is a subtree (RK287). None where the
605
+ #: two are the same string — :func:`anchored`'s reading — and set by :func:`find`, which
606
+ #: is the constructor that returns the children with the parent. The **text** and not a
607
+ #: count of it since RK1112: `amend` replaces exactly this, so a reader that could state
608
+ #: its size but not print it left `show` unable to offer what the write takes.
609
+ own: str | None = None
610
+
611
+ @property
612
+ def words(self) -> int:
613
+ """What the budget charges this section: its argument, not its whole text (RK136)."""
614
+ return words(self.body)
615
+
616
+ @property
617
+ def prose(self) -> str:
618
+ """This section's own text, subsections excluded — what `amend --body` replaces."""
619
+ return self.body if self.own is None else self.own
620
+
621
+ @property
622
+ def own_words(self) -> int:
623
+ """The same count over this section's own prose, with no subsection in it (RK287).
624
+
625
+ Equal to :attr:`words` for a leaf, and the whole point for a parent: a container
626
+ like this repository's `§0` has no paragraph of its own, so :attr:`words` measures
627
+ the file's shape rather than anyone's argument.
628
+ """
629
+ return words(self.prose)
630
+
631
+ @property
632
+ def nests(self) -> bool:
633
+ """Whether the two counts differ, which is when printing only one of them misleads.
634
+
635
+ The rule RK245 and RK265 each found at another door: a verb printing a number beside
636
+ a limit is claiming the two are the same number. Here they are two numbers, and which
637
+ one the gate charges depends on whether a line points at this anchor (RK215) — so
638
+ both are said, and neither is presented as the verdict.
639
+ """
640
+ return self.own_words != self.words
641
+
642
+ def names(self, pattern: re.Pattern[str]) -> tuple[str, ...]:
643
+ """The task ids this heading names, in order (RK61).
644
+
645
+ Whose section this is, for a project that numbers by hand: under
646
+ `ref_scheme = "outline"` the anchor is `XVI.12` and the id lives in the title —
647
+ `§XVI.12 A design (SH123)` — so ownership is unreadable from the anchor alone, and
648
+ both `section.orphan` and `section.stale` fired for nobody in the two live corpora.
649
+
650
+ The **title** and never the body: a section quoting another id is discussing it, not
651
+ owning it, and reading the prose would report every cross-reference in the file.
652
+ """
653
+ return tuple(dict.fromkeys(pattern.findall(self.title)))
654
+
655
+ def __str__(self) -> str:
656
+ return f"§{self.anchor} ({self.first}-{self.last})"
657
+
658
+ def counted(self, limit: int) -> str:
659
+ """This section's size as every verb that prints it says it (RK287).
660
+
661
+ Both figures where they differ, and the limit beside them either way. A bare `310 words`
662
+ on a section whose own prose is 48 invites cutting prose that was never over — and the
663
+ limit is what makes the number act on something, which is the whole of RK283 one door
664
+ over. Which of the two the gate charges depends on whether a line points at the anchor
665
+ (RK215), so neither is spelled as the verdict and the refusal states its own.
666
+
667
+ Here since RK1170: three verb files and a view all print this, and a helper in
668
+ `rendering.py` was the fifth place a fact about a section was spelled.
669
+ """
670
+ if not self.nests:
671
+ return f"{self.words} words (limit {limit})"
672
+ return f"{self.own_words} words, {self.words} with subsections (limit {limit})"
673
+
674
+ def payload(self, where: str) -> dict[str, object]:
675
+ """This section as data, at every door that publishes one (RK1170).
676
+
677
+ `where` is passed and not stored, for `counted`'s reason: the file a section was read
678
+ from is a fact about the project, and an `add` publishes the same record about a file it
679
+ is writing into.
680
+ """
681
+ return {
682
+ "anchor": self.anchor,
683
+ "title": self.title,
684
+ "level": self.level,
685
+ "file": where,
686
+ "first": self.first,
687
+ "last": self.last,
688
+ "words": self.words,
689
+ # The figure the limit is measured on, beside the one a reader pays (RK287). `words`
690
+ # keeps its meaning — the subtree, which is what a drop takes — and this is the
691
+ # section's own argument, which for a container is none of it.
692
+ "own_words": self.own_words,
693
+ }
694
+
695
+
696
+ def local(schema: Schema, anchor: str) -> str | None:
697
+ """This address as the *file* writes it, or None where it is another role's (RK340).
698
+
699
+ The one seam between the project's namespace and a document's own. A role that declares
700
+ `[refs] <role> = "S"` answers `S:I` and never a bare `I`; a role that declares none
701
+ answers the bare address and never a prefixed one — which is what makes the two
702
+ addresses rather than one anchor read twice, and it is symmetric on purpose: a project
703
+ that prefixed only one of its files would otherwise have `S:I` and `I` both resolving in
704
+ strategy, and the collision back one file over.
705
+
706
+ None and not a raise, because every caller already has an answer for an anchor this file
707
+ does not hold: `find` returns nothing, `declaring` leaves the role out, and the gate says
708
+ `ref.unresolved` naming the files it looked in.
709
+ """
710
+ prefix, bare = split_ref(anchor)
711
+ return bare if prefix == schema.ref_prefix else None
712
+
713
+
714
+ def qualified(schema: Schema, anchor: str) -> str:
715
+ """This file's address as a *pointer* writes it — `I.2` → `S:I.2` (RK340).
716
+
717
+ The inverse of :func:`local`, and the one writer of the prefixed spelling for the reason
718
+ :func:`anchor_text` is the one writer of the heading's: an address rendered by hand at a
719
+ call site is how the two ends of a pointer come to disagree.
720
+ """
721
+ return f"{schema.ref_prefix}{REF_SEPARATOR}{anchor}" if schema.ref_prefix else anchor
722
+
723
+
724
+ def find(document: Document, anchor: str) -> Section | None:
725
+ """The section this anchor names, or None. Subsections belong to it, not after it."""
726
+ span = _span(document, anchor)
727
+ if span is None:
728
+ return None
729
+ _, end, heading = span
730
+ body = "".join(document.lines[heading.lineno : end]).strip("\r\n")
731
+ # Both spans off the one heading (RK287). The subtree is what a drop deletes and what a
732
+ # reader pays; the prose is what the argument costs — and a Section that carried only the
733
+ # first left every printer stating a figure no limit is measured against.
734
+ own = "".join(document.lines[heading.lineno : document.prose_end(heading)]).strip("\r\n")
735
+ return Section(
736
+ anchor=anchor,
737
+ title=_title_of(heading.text, document.schema),
738
+ level=heading.level,
739
+ first=heading.lineno,
740
+ last=end,
741
+ body=body,
742
+ own=own,
743
+ )
744
+
745
+
746
+ def declaring(config: Config, anchor: str) -> tuple[str, ...]:
747
+ """Which declared prose roles actually hold this anchor, in `[files]` order (RK196).
748
+
749
+ The resolution no verb may assume: `ship` deletes the design and `defer` reports where it
750
+ stayed, and both were written naming `improvements` outright — the reason a project
751
+ declaring `strategy` alone was told its own section is missing while the section sat
752
+ there. `show` asks the same question with one distinction more, a declared file that is
753
+ not on disk yet being an answer of its own, so it keeps its own reading and this stays
754
+ the shape a writer needs.
755
+
756
+ A **tuple**, because the answers to none and to two are not this function's: an absence
757
+ is where the design would go for one caller and a refusal for another, and two roles
758
+ declaring one anchor is the `ref.ambiguous` the gate reports and no verb resolves by
759
+ picking. Only which files say so is the same question everywhere.
760
+ """
761
+ return tuple(
762
+ role
763
+ for role in PROSE_ROLES
764
+ if config.has(role)
765
+ and config.path(role).is_file()
766
+ and find(config.document(role), anchor) is not None
767
+ )
768
+
769
+
770
+ def bind(document: Document, section: Section, task_id: str) -> Document:
771
+ """Append a task's id to a heading that names none, changing nothing else (RK452).
772
+
773
+ The binding written from the **pointer's** end. :func:`_bound` renders it into a title a
774
+ caller passed; this one is for the write where nobody passed a title at all — `add --ref`
775
+ on an outline anchor whose design was written first — so what it may touch is the id and
776
+ not one byte more.
777
+
778
+ Which is why it appends to the heading's own line rather than re-rendering it. RK388
779
+ settled that a `--title` amend restyles on purpose: the caller asked for the heading to
780
+ change, so the canonical spelling is right there. Nobody asked here, and re-rendering
781
+ would take the `§` an author wrote and whatever spacing that heading had (RK44) as the
782
+ silent price of a binding — the exact restyle RK388 removed from the body-only path.
783
+
784
+ The caller has already established that the heading names no task: this appends, and
785
+ deciding whether it should is :func:`owners`'.
786
+ """
787
+ heading = next(
788
+ (one for one in document.headings if anchor_of(one.text, document.schema) == section.anchor),
789
+ None,
790
+ )
791
+ if heading is None: # pragma: no cover - the caller found this section a moment ago
792
+ return document
793
+ line = document.lines[heading.lineno - 1]
794
+ body = line.rstrip("\r\n")
795
+ return document.replace_line(heading.lineno - 1, f"{body.rstrip()} ({task_id})")
796
+
797
+
798
+ def owners(section: Section, ids: re.Pattern[str]) -> tuple[str, ...]:
799
+ """The tasks this section belongs to, whichever scheme addresses it (RK61).
800
+
801
+ Under `ref_scheme = "id"` the anchor *is* the id. Under an outline the anchor is
802
+ `XVI.12` and the id is in the heading — `§XVI.12 A design (SH123)` — which is why both
803
+ checks below fired for nobody in the two live corpora until this read it.
804
+
805
+ So **naming a task in a heading is the claim to be its rationale**, with no exemption for
806
+ where the section sits. The first attempt made one — "a task's section is under a `Block X`
807
+ heading", read off this repository's own file — and it disabled the check on the corpus it
808
+ was written for: Shio files its rationale under `## VIII. The Agent Gateway (Block H)`,
809
+ which is an outline heading, so all 146 of its sections looked unowned. A section that
810
+ means to cite a task rather than belong to it says so in its prose, which this never reads.
811
+
812
+ A **sub-anchor under the id scheme is derived from an id** and belongs to it (RK114):
813
+ `§RK34.1` is `RK34`'s subsection and the anchor says so, segment by segment — the same
814
+ reading :func:`~roadkeep.sections._extends` gives it one module over. Matching the whole
815
+ anchor cannot see that, which exempted every sub-anchor from both checks and let a
816
+ `renumber RK1 --to RK9` leave `§RK1.1` behind on a file `lint` then called clean. Only
817
+ the first segment is asked, so `§0.1` and `§XVI.12` still reach the heading below: prose
818
+ belonging to no task stays nobody's orphan.
819
+
820
+ Here rather than inside `lint` because the **writer needs the same answer** (RK236): a
821
+ departure deletes the section it owns, and ownership read one way by the gate and another
822
+ by the drop is how Turing's standing GEO memo lost two subsections to a retirement.
823
+ """
824
+ if ids.match(section.anchor):
825
+ return (section.anchor,)
826
+ root = section.anchor.split(".")[0]
827
+ if root != section.anchor and ids.match(root):
828
+ return (root,)
829
+ return section.names(re.compile(rf"\b{ids.pattern.strip('^$')}\b"))
830
+
831
+
832
+ def citing(
833
+ document: Document, anchors: Sequence[str], *, ignore: Sequence[str] = ()
834
+ ) -> tuple[tuple[str, str], ...]:
835
+ """Which sections' prose cites which of ``anchors`` — the other end of a pointer (RK206).
836
+
837
+ `_pointers` resolves the ref a *task line* carries, and nothing resolves the references
838
+ a section's prose makes, so `ship` deletes a design that another design cites and every
839
+ check answers clean: `ref.unresolved` reads task lines, `section.orphan` reads what
840
+ points at a section, and citing prose is neither. Measured on claude-tray: `§XVIII.9`
841
+ cited `§XVIII.12`, `ship` took §XVIII.12 with the line that owned it, and `lint`
842
+ reported `clean` for a day.
843
+
844
+ **Membership and not shape.** The caller names the anchors that are going away, so an
845
+ anchor-shaped token is interesting only when it is one of them — which removes RK15's
846
+ quotation problem from the pattern entirely: `§RK15` in a sentence about pointers is
847
+ text nobody is deleting. What is left of that problem is prose that quotes a reference
848
+ to a section this very transaction removes, and three exclusions answer it, each
849
+ measured across four trees rather than guessed:
850
+
851
+ * a **fenced block** is quoted or generated (the reading :data:`_FENCES` already makes);
852
+ * an **inline code span**, which is how this repository writes a pointer it is talking
853
+ about — 3 of them in `docs/IMPROVEMENTS.md`;
854
+ * a **blockquote**, which is 18 of Shio's anchor-shaped tokens and 19 of Turing's, all
855
+ of them quoted material;
856
+ * a token directly after a **`→`**, which is a task line reproduced as an example — 3 in
857
+ claude-tray, and the shape `Schema.render` writes.
858
+
859
+ ``ignore`` is what the transaction is deleting: a section citing its own subtree, or a
860
+ sibling going in the same drop, is prose that leaves with the reference.
861
+
862
+ Membership is the **filter** and no longer the scan (RK1106): :func:`references` reads the
863
+ prose once and this selects from it, because the gate asks the same file the opposite
864
+ question — which citations resolve to nothing — and two scanners would give a project two
865
+ counts of its own dead citations.
866
+ """
867
+ wanted = {anchor for anchor in anchors if anchor}
868
+ if not wanted:
869
+ return ()
870
+ skipped = set(ignore)
871
+ return tuple(
872
+ (cited.anchor, cited.by)
873
+ for cited in references(document)
874
+ if cited.anchor in wanted and cited.by not in skipped
875
+ )
876
+
877
+
878
+ @dataclass(frozen=True, slots=True)
879
+ class Cite:
880
+ """One `§<anchor>` a section's prose makes, and where it is written (RK1106).
881
+
882
+ The record the fourth relation resolves — a citation, beside the dep, the pointer and the
883
+ queue entry :mod:`roadkeep.referring` already declares. It carries the place because the
884
+ gate reports `file:line`, and the citing section because that is who has to make the edit:
885
+ a dangling reference is a defect in the prose that makes it, not in the section it names.
886
+ """
887
+
888
+ #: What is cited, as the prose spells it — namespaced (`S:I.2`) where the pointer is.
889
+ anchor: str
890
+ #: The anchor of the section whose prose cites it.
891
+ by: str
892
+ #: 1-based, as an editor counts.
893
+ lineno: int
894
+
895
+
896
+ #: An anchor-shaped token after a `§`, in either scheme (RK1106). Deliberately looser than
897
+ #: :data:`~roadkeep.kernel.schema.OUTLINE_ANCHOR_RE` and than any id shape, because the two
898
+ #: questions are different: a *reference* is anything an author wrote as one, and whether the
899
+ #: token is a well-formed address of this project is what resolving it answers. A pattern that
900
+ #: only matched valid anchors would read a typo as prose and report nothing about it, which is
901
+ #: the citation this exists to find.
902
+ #:
903
+ #: **Atomic**, which is the whole of RK1111: the address is taken whole or not at all. The
904
+ #: earlier boundary `(?![\w.])` refused a sentence-final `.` — punctuation the address does not
905
+ #: own — and the engine answered by *shortening the match* until the lookahead passed, so the
906
+ #: prose `§S:V.` was read as a citation of `§S` and `§I.2.` as no citation at all. Both silent:
907
+ #: one reported a live anchor as dangling in every project that namespaces a second file, the
908
+ #: other reported nothing over a dead one. What follows a whole address may be anything that is
909
+ #: not a word character — a period, a comma, a paren, a fence — and a token that runs on into
910
+ #: `\w` after the scheme's own separators is not an address in either scheme.
911
+ _CITED_RE = re.compile(r"§((?>[A-Za-z0-9]+(?::[A-Za-z0-9]+)?(?:\.[A-Za-z0-9]+)*))(?!\w)")
912
+
913
+
914
+ def cited_in(body: str) -> tuple[str, ...]:
915
+ """Every anchor a body cites, in order and without repeats (RK1227).
916
+
917
+ :func:`references` asks this of a **document**, for the gate; this asks it of a paragraph
918
+ somebody is about to write, for the door. Both go through :func:`_argument` and
919
+ :data:`_CITED_RE`, so what counts as a citation — the four exclusions, each measured
920
+ across four trees — is decided once and the two cannot come to disagree about a quotation.
921
+
922
+ Distinct here and every occurrence there, which is the same split :func:`citing` makes:
923
+ the gate reports a place per dead citation because each is an edit, and a refusal is about
924
+ *which addresses do not resolve*, where naming one twice is noise.
925
+ """
926
+ return tuple(dict.fromkeys(_CITED_RE.findall(_argument(body))))
927
+
928
+
929
+ def references(document: Document) -> tuple[Cite, ...]:
930
+ """Every citation this file's prose makes, unresolved (RK1106).
931
+
932
+ One scan, two questions. :func:`citing` asks which of *these* anchors are cited, at the
933
+ moment a transaction deletes them; the gate asks which citations name nothing at all. The
934
+ reading of what counts as a citation — :func:`_argument`'s four exclusions, each measured
935
+ across four trees — belongs to neither of them and is made once, here.
936
+
937
+ Every occurrence and not the distinct set: two dead citations on two lines are two edits,
938
+ and a reader handed one of them fixes the file halfway. `citing` de-duplicates on its own
939
+ side, where the answer is *which* section to warn about and saying it twice is noise.
940
+ """
941
+ out: list[Cite] = []
942
+ for section in anchored(document):
943
+ # Off the document's own lines and **not** off `Section.body`, which is stripped of the
944
+ # blank after the heading — measured: that shift reported claude-tray's §I.7 two lines
945
+ # early, onto prose carrying no citation at all. `_argument` blanks a quotation in
946
+ # place rather than dropping it, so this slice and its output stay index-for-index.
947
+ raw = "".join(document.lines[section.first : section.last])
948
+ for offset, line in enumerate(_argument(raw).splitlines()):
949
+ for found in _CITED_RE.findall(line):
950
+ out.append(
951
+ Cite(anchor=found, by=section.anchor, lineno=section.first + 1 + offset)
952
+ )
953
+ return tuple(out)
954
+
955
+
956
+ #: A mark that **carries its file**: the outward citation (RK1181). Prose in a governed file
957
+ #: legitimately argues from another document's numbered sections — a spec, an RFC, a standard —
958
+ #: and those documents number themselves with the same mark, so `§3.1` written plainly is read as
959
+ #: a pointer into this file and refused as dangling. Met twice in one session in a project whose
960
+ #: specs live beside the governed files; both times the repair was to strike the mark and spell
961
+ #: the reference in words, which is a worse sentence, and both times the turn was already spent.
962
+ #:
963
+ #: Not a suppression flag, which is what this must never become: an author who can silence the
964
+ #: check silences it for the typo too, and a bare mark naming nothing is usually exactly that —
965
+ #: the case the rule was built for, which it goes on catching. What earns the silence is the
966
+ #: **file**, named the way a Markdown link already names one. This repository's own `agents.md`
967
+ #: writes `[§0.3](docs/IMPROVEMENTS.md)`, so the form is the corpus's and not an invention.
968
+ #:
969
+ #: A fragment (`[§I.2](#i-2)`) is *this* document and buys nothing: a target that names no path
970
+ #: would be the suppression flag with an extra two characters.
971
+ _OUTWARD_RE = re.compile(r"\[(§[^\]]*)\]\(\s*(?!#)([^)\s]+)[^)]*\)")
972
+
973
+
974
+ def _argument(body: str) -> str:
975
+ """A section's prose with every quotation blanked out, so a reference in one is not one.
976
+
977
+ Blanked rather than dropped: the lines keep their positions, which is what lets a caller
978
+ report a place without the two readings of the file disagreeing about which line it is.
979
+
980
+ The **outward citation** is blanked the same way (RK1181): a mark inside a Markdown link
981
+ whose target is a path is a reference into that document, which this file's outline cannot
982
+ answer for and the gate has nothing to resolve it against.
983
+ """
984
+ out: list[str] = []
985
+ fence: str | None = None
986
+ #: Whether an **indented** code block is open, and what the last line was — the two the
987
+ #: fourth exclusion needs (RK1151). A block and not a line, because four spaces mean two
988
+ #: different things: sample output where a blank line came before, and a list item's own
989
+ #: continuation where a bullet did. A rule reading indentation alone would blank the
990
+ #: second, and a citation nobody scans is worse than one falsely reported — this is the
991
+ #: backstop that is supposed to notice.
992
+ indented = False
993
+ previous = ""
994
+ for raw in body.splitlines():
995
+ # The link text first and in place, so an address inside one is gone before any other
996
+ # rule reads the line and every column after it still lines up.
997
+ line = _OUTWARD_RE.sub(lambda m: " " * len(m[0]), raw)
998
+ stripped = line.strip()
999
+ if fence is not None:
1000
+ if stripped.startswith(fence):
1001
+ fence = None
1002
+ out.append("")
1003
+ previous = stripped
1004
+ continue
1005
+ if stripped.startswith(_FENCES):
1006
+ fence = stripped[:3]
1007
+ out.append("")
1008
+ previous = stripped
1009
+ continue
1010
+ if stripped.startswith(">"):
1011
+ out.append("")
1012
+ previous = stripped
1013
+ continue
1014
+ if indented and stripped and not line.startswith(_INDENT):
1015
+ # Closed by the first line indented less, which is Markdown's own rule — a blank
1016
+ # line inside an indented block does not end it.
1017
+ indented = False
1018
+ elif not indented and stripped and line.startswith(_INDENT) and not previous:
1019
+ # Opened only after a blank line: indented code cannot interrupt a paragraph, and
1020
+ # under a bullet the blank is the item's, so `_BULLET` is what tells them apart.
1021
+ indented = not _BULLET.match(_before(out))
1022
+ if indented:
1023
+ out.append("")
1024
+ previous = stripped
1025
+ continue
1026
+ out.append(_QUOTED.sub(lambda m: " " * len(m.group()), line))
1027
+ previous = stripped
1028
+ return "\n".join(out)
1029
+
1030
+
1031
+ #: Four spaces: Markdown's other code block, and the width a list item's continuation shares
1032
+ #: with it. A tab is deliberately not read as one — no line in any of the four trees measured
1033
+ #: for RK1151 opens a block that way, and treating one as code would blank a Markdown table.
1034
+ _INDENT = " "
1035
+ #: What opens a list item, whose continuation is prose (RK1151). Ordered and unordered both:
1036
+ #: a numbered argument's second paragraph is indented exactly like sample output.
1037
+ _BULLET = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s")
1038
+
1039
+
1040
+ def _before(rendered: list[str]) -> str:
1041
+ """The last line that said anything, for deciding what an indent belongs to.
1042
+
1043
+ Read off what is already rendered rather than off the source, so a blockquote or a fence —
1044
+ both blanked above — cannot be mistaken for the bullet an indent hangs from.
1045
+ """
1046
+ for line in reversed(rendered):
1047
+ if line.strip():
1048
+ return line
1049
+ return ""
1050
+
1051
+
1052
+ #: What is being talked about rather than said: a code span, and a pointer reproduced whole.
1053
+ _QUOTED = re.compile(r"`[^`]*`|→\s*§[\w.]+")
1054
+
1055
+
1056
+ def unanchored(document: Document) -> tuple[Heading, ...]:
1057
+ """Headings that are where a section would be, and carry no anchor (RK281).
1058
+
1059
+ :func:`anchored` finds `§<anchor>` headings, and the sigil is **this tool's convention**
1060
+ rather than Markdown's — so `adopt --sections` read a rationale file correctly exactly
1061
+ when that file had already adopted the format, which is the one case nobody needs an
1062
+ estimate for. A real `DESIGN.md` answered 0 sections and 0 would change: RK98's zero,
1063
+ one command over from where RK279 closed it.
1064
+
1065
+ A second reader over the same headings and never a second grammar, the line RK98 drew
1066
+ when it counted table rows without parsing cells. Nothing here composes an anchor — an
1067
+ address the file does not have is not this tool's to invent (L4) — so what comes back is
1068
+ the heading, and the estimate takes a count and a word measure off its span.
1069
+
1070
+ Two exclusions, both because they are frame rather than work: a level-1 heading is the
1071
+ document's title and not a section in it, and a heading with no prose of its own is a
1072
+ container — `## Block B` above a list of subsections describes them, and counting it
1073
+ would measure the file's shape rather than anyone's paragraph, which is the distinction
1074
+ :func:`anchored` already makes for `§0`.
1075
+ """
1076
+ out: list[Heading] = []
1077
+ for heading in document.headings:
1078
+ if heading.level < 2 or anchor_of(heading.text, document.schema) is not None:
1079
+ continue
1080
+ end = document.prose_end(heading)
1081
+ if any(not blank(line) for line in document.lines[heading.lineno : end]):
1082
+ out.append(heading)
1083
+ return tuple(out)
1084
+
1085
+
1086
+ def anchored(document: Document) -> tuple[Section, ...]:
1087
+ """Every `§<anchor>` section in file order, each carrying only its **own** prose.
1088
+
1089
+ The gate (RK15) needs the set and not one lookup: a pointer resolves in one
1090
+ direction, and an orphan — a section nothing points at — is only visible from the
1091
+ other. **Own** prose, because :func:`find` deliberately returns the subtree (`drop`
1092
+ has to delete it whole, and a task's rationale is charged for the subsection it
1093
+ grew), and a container like this repository's `§0` has no prose of its own at all —
1094
+ counting its children against it would measure the file's shape rather than anyone's
1095
+ paragraph. Which of the two the budget uses is the gate's decision, not this one's.
1096
+
1097
+ Each anchor is the **project's** address and not the heading's (RK340): a heading writes
1098
+ `I` and a pointer writes `S:I` where `[refs]` gives this role a namespace, and the gate
1099
+ reads these sections into one index across both prose files — which is the index the
1100
+ collision was in. So the qualification happens here, once, and every reader downstream
1101
+ compares addresses that are comparable. :func:`anchor_text` is the way back.
1102
+ """
1103
+ out: list[Section] = []
1104
+ for heading in document.headings:
1105
+ anchor = anchor_of(heading.text, document.schema)
1106
+ if anchor is None:
1107
+ continue
1108
+ end = document.prose_end(heading)
1109
+ out.append(
1110
+ Section(
1111
+ anchor=qualified(document.schema, anchor),
1112
+ title=_title_of(heading.text, document.schema),
1113
+ level=heading.level,
1114
+ first=heading.lineno,
1115
+ last=end,
1116
+ body="".join(document.lines[heading.lineno : end]).strip("\r\n"),
1117
+ )
1118
+ )
1119
+ return tuple(out)
1120
+
1121
+
1122
+ def nested(document: Document, anchor: str) -> tuple[Section, ...]:
1123
+ """The anchored sections a drop of this one would take with it, in file order (RK78).
1124
+
1125
+ What :func:`find` returns as one body, enumerated as the headings it actually is — the
1126
+ honest report of a deletion whose size is not the size of the section that was named.
1127
+ Empty for an anchor this file does not declare, because "nothing is nested under a
1128
+ section that is not there" is the same answer as the refusal :func:`drop` raises, and
1129
+ a reader asking this question is not the one to tell about the missing heading.
1130
+ """
1131
+ span = _span(document, anchor)
1132
+ if span is None:
1133
+ return ()
1134
+ _, end, heading = span
1135
+ return tuple(
1136
+ section for section in anchored(document) if heading.lineno < section.first <= end
1137
+ )
1138
+
1139
+
1140
+ def descending(document: Document, anchor: str) -> tuple[Section, ...]:
1141
+ """The nested sections that are this address's own numbering — `I.2.1`, never `XIV.8`.
1142
+
1143
+ :func:`nested` bounded by the **name** rather than by the span, which is the difference
1144
+ that matters to anything re-addressing a subtree: a `§I.2.1` travels with `§I.2` because
1145
+ the address says it is part of it, and a `§XIV.8` somebody filed inside that subtree keeps
1146
+ the address of the thing that owns it. Segment by segment and never as a string prefix,
1147
+ the care :func:`_extends` takes at the other end of the same question — `§0.1` is not
1148
+ above `§0.10`.
1149
+
1150
+ Public and here rather than beside either caller (RK377): `renumber` asks it of an id's
1151
+ subtree and `move` of an outline address's, and two readings of "which anchors are this
1152
+ one's own" is how one door renames half a subtree the other would have renamed whole.
1153
+ """
1154
+ segments = anchor.split(".")
1155
+ return tuple(
1156
+ child
1157
+ for child in nested(document, anchor)
1158
+ if child.anchor.split(".")[: len(segments)] == segments
1159
+ )
1160
+
1161
+
1162
+ def pointers(config: Config, *, leaving: str = "") -> dict[str, tuple[str, ...]]:
1163
+ """Which open lines point at which anchor — the claims a drop may not orphan (RK78).
1164
+
1165
+ Read from the roadmap and never from the prose file, because a claim is a pointer and a
1166
+ pointer only exists on a task line: a heading nested under another is that other's prose
1167
+ until a line names it, and this is the one place that says which ones do. `leaving` is
1168
+ the line being shipped, whose own claim is the reason the drop is happening.
1169
+
1170
+ And from the decisions file, whose records claim by **id** rather than by pointer
1171
+ (RK1361). Nothing in that file is ever deleted — the one departure is `supersede`, which
1172
+ keeps both entries — so the body of a decision that stands is a body no verb removes, and
1173
+ `section drop` was the one door that did not know it. Read here rather than refused at
1174
+ that door, because `drop`, `ship` and the gate all ask this one function and a check in
1175
+ one of them would be a rule the other two disagreed with. A superseded entry claims its
1176
+ own too: what a replacement was needed against is the body it replaced.
1177
+ """
1178
+ out: dict[str, list[str]] = {}
1179
+ for entry in config.document("roadmap").entries:
1180
+ if entry.task.ref and entry.task.id != leaving:
1181
+ out.setdefault(entry.task.ref, []).append(entry.task.id)
1182
+ if config.has("decisions") and config.path("decisions").is_file():
1183
+ for entry in config.document("decisions").entries:
1184
+ anchor = entry.task.ref or entry.task.id
1185
+ if entry.task.id not in out.setdefault(anchor, []):
1186
+ out[anchor].append(entry.task.id)
1187
+ return {anchor: tuple(ids) for anchor, ids in out.items() if ids}
1188
+
1189
+
1190
+ @dataclass(frozen=True, slots=True)
1191
+ class Shown:
1192
+ """One section as `show` answers it: the extent asked for, and what carries the rest.
1193
+
1194
+ The result that read had none of (RK1170). The door looked the address up two ways, chose
1195
+ an extent off a flag, gathered the nested anchors and composed both registers from the
1196
+ four — so neither reading had a result to derive from, which is that task's whole subject.
1197
+ """
1198
+
1199
+ section: Section
1200
+ #: The extent the caller asked for (RK1112): the subtree is what a reader of the design
1201
+ #: wants and the own prose is what `amend` replaces, so the flag says which question this
1202
+ #: call is. `body` stays the key either way — it is the body of what was asked for, and
1203
+ #: `own_words` beside it already states that the two extents differ.
1204
+ body: str
1205
+ #: The anchors nested under it, named rather than left as a blank line (RK1118): a
1206
+ #: container has no prose of its own, so `--own` on this repository's `§0` answered with a
1207
+ #: heading and nothing — correct, and indistinguishable from a command that printed nothing.
1208
+ nested: tuple[str, ...]
1209
+ #: The file, as this project spells it.
1210
+ where: str
1211
+
1212
+ @classmethod
1213
+ def of(cls, config: Config, role: str, address: str, own: bool) -> Shown:
1214
+ """Look the address up the way every reader here does, or raise `NoSuchSection`.
1215
+
1216
+ **An anchor first and a heading text second** (RK1107): an anchor is the project's
1217
+ chosen name and wins, and the fall-through is what makes `section show 'Table of
1218
+ contents'` an answer instead of a refusal.
1219
+ """
1220
+ document = config.document(role)
1221
+ where = config.relative(config.path(role))
1222
+ section = find(document, address)
1223
+ if section is None:
1224
+ heading = titled(document, address)
1225
+ section = (
1226
+ None
1227
+ if heading is None
1228
+ else next(
1229
+ (one for one in untitled(document) if one.first == heading.lineno),
1230
+ None,
1231
+ )
1232
+ )
1233
+ if section is None:
1234
+ raise NoSuchSection(address, where, titled_too=True)
1235
+ return cls(
1236
+ section=section,
1237
+ body=section.prose if own else section.body,
1238
+ nested=tuple(one.anchor for one in nested(document, section.anchor)),
1239
+ where=where,
1240
+ )
1241
+
1242
+ def stated(self, schema: Schema) -> str:
1243
+ """The heading, a blank line, and the prose — which is what an `amend --body-file` is
1244
+ composed from, so nothing else may reach stdout."""
1245
+ return chr(10).join([heading_of(schema, self.section), "", self.body])
1246
+
1247
+ def silence(self) -> list[str]:
1248
+ """Which of the two empty answers this is, for **stderr** (RK1118).
1249
+
1250
+ Two, because a section with no text has two shapes and one of them is a defect: a
1251
+ **container** is the ordinary structure of a rationale file — this repository's `§0`,
1252
+ and every `## <Block>` heading over subsections — while a leaf with nothing in it is
1253
+ what the gate calls `body.empty`. Saying "no prose" to both would send half the readers
1254
+ to `lint` and the other half looking for a bug in the reader.
1255
+
1256
+ On stderr and not beside the prose, for the reason above: this output is piped into a
1257
+ file, and a sentence on stdout would end up in it.
1258
+ """
1259
+ if self.body.strip():
1260
+ return []
1261
+ if self.nested:
1262
+ named = ", ".join("§" + one for one in self.nested)
1263
+ return [
1264
+ f"roadkeep: §{self.section.anchor} carries no prose of its own — its "
1265
+ f"{self.section.words} words are {named}, each amended by its own anchor"
1266
+ ]
1267
+ return [
1268
+ f"roadkeep: §{self.section.anchor} is empty in {self.where}: a heading with no "
1269
+ f"paragraph under it, which `lint` reports as `body.empty`"
1270
+ ]
1271
+
1272
+ def payload(self) -> dict[str, object]:
1273
+ """The same answer as data, with the nested anchors under their own key — so the
1274
+ payload and the report cannot disagree about why a body came back empty."""
1275
+ return {
1276
+ **self.section.payload(self.where),
1277
+ "body": self.body,
1278
+ "nested": list(self.nested),
1279
+ }
1280
+
1281
+
1282
+ @dataclass(frozen=True, slots=True)
1283
+ class Carrier:
1284
+ """One section whose own prose holds a sought string, and how often (RK1310)."""
1285
+
1286
+ anchor: str
1287
+ role: str
1288
+ where: str
1289
+ line: int
1290
+ title: str
1291
+ count: int
1292
+
1293
+ def payload(self) -> dict[str, object]:
1294
+ return {
1295
+ "anchor": self.anchor,
1296
+ "role": self.role,
1297
+ "file": self.where,
1298
+ "line": self.line,
1299
+ "title": self.title,
1300
+ "count": self.count,
1301
+ }
1302
+
1303
+
1304
+ @dataclass(frozen=True, slots=True)
1305
+ class Found:
1306
+ """Which anchors carry a sentence — the lookup that had no verb (RK1310).
1307
+
1308
+ Observed in pportal, 2026-08-22. A line count stated in the prose had gone stale, and the
1309
+ correction is `section amend <anchor> --replace <old> --with <new>`. The anchor was wrong:
1310
+ the claim sized one C file, the task about that file was one id, and the sentence sizing it
1311
+ lived in the section of a *different* id — the one covering three such files together.
1312
+
1313
+ The refusal was a good one. It said the text does not occur in the section named and
1314
+ pointed at `section show`, which is the right next command. What it could not say is the
1315
+ thing the caller wanted: that the text occurs once, and where. Every fact needed to say so
1316
+ had just been read.
1317
+
1318
+ The general shape is that `amend` and `section amend` are addressed **by anchor** and the
1319
+ caller often knows only the text. A pointer resolves an id to a section; nothing resolved a
1320
+ sentence to one, so the loop was show, read, guess again — and for an agent caller each
1321
+ turn of it is a file printed into a context window.
1322
+
1323
+ Reads and writes nothing, which is why it can be cheap: the count per anchor is the whole
1324
+ answer, because it is what decides whether `--replace` will be accepted and by which one.
1325
+ Never the prose — that is `section show`'s, and printing it here would be the file back.
1326
+ """
1327
+
1328
+ text: str
1329
+ carriers: tuple[Carrier, ...]
1330
+ #: Every prose role looked in, so an empty answer is about the files and not about a filter
1331
+ #: the caller forgot they passed.
1332
+ roles: tuple[str, ...]
1333
+
1334
+ @property
1335
+ def total(self) -> int:
1336
+ return sum(one.count for one in self.carriers)
1337
+
1338
+ @property
1339
+ def replaceable(self) -> tuple[Carrier, ...]:
1340
+ """The anchors a `--replace` would be accepted by: exactly one occurrence (RK1263)."""
1341
+ return tuple(one for one in self.carriers if one.count == 1)
1342
+
1343
+ def stated(self) -> str:
1344
+ if not self.carriers:
1345
+ return (
1346
+ f"no section in {', '.join(self.roles)} carries {self.text!r} — "
1347
+ f"`section show <anchor>` prints the prose as it is"
1348
+ )
1349
+ rows = [
1350
+ f"{self.total} occurrence(s) of {self.text!r} in "
1351
+ f"{len(self.carriers)} section(s), in file order"
1352
+ ]
1353
+ for one in self.carriers:
1354
+ # The count beside the address, because it is the half that decides the next call:
1355
+ # one is what `--replace` accepts, and more is the ambiguity it refuses.
1356
+ takes = " (`--replace` takes it)" if one.count == 1 else ""
1357
+ rows.append(
1358
+ f" §{one.anchor} {one.count}x {one.where}:{one.line} "
1359
+ f"{one.title}{takes}"
1360
+ )
1361
+ return "\n".join(rows)
1362
+
1363
+ def payload(self, served: str = "") -> dict[str, object]:
1364
+ from roadkeep.remedying import BLANK, Door # noqa: PLC0415 - RK260
1365
+
1366
+ return {
1367
+ "text": self.text,
1368
+ "roles": list(self.roles),
1369
+ "total": self.total,
1370
+ "carriers": [one.payload() for one in self.carriers],
1371
+ # The subset a narrow edit can address, named rather than left to be derived: the
1372
+ # rule is `Substitution`'s and a consumer recomputing it would be its second reader.
1373
+ "replaceable": [one.anchor for one in self.replaceable],
1374
+ # And the door the empty sentence names (RK1307's rule, which caught this verb the
1375
+ # day it was written): nothing carries the string, so the next read is the prose as
1376
+ # the file spells it — and the caller reaching this through the served answer is
1377
+ # the one the whole verb is for. Absent where something was found, there being
1378
+ # nothing to look up.
1379
+ **(
1380
+ {}
1381
+ if self.carriers
1382
+ else {
1383
+ # `doors` and always a list (RK1324), which is the one shape a consumer
1384
+ # reads wherever a payload offers a runnable command.
1385
+ "doors": [
1386
+ Door(
1387
+ ("section", "show", BLANK),
1388
+ "nothing carries it, so the prose as the file spells it is the read",
1389
+ ).payload(served)
1390
+ ]
1391
+ }
1392
+ ),
1393
+ }
1394
+
1395
+
1396
+ def carrying(config: Config, text: str, role: str | None = None) -> Found:
1397
+ """Every section whose **own** prose holds ``text``, in file order (RK1310).
1398
+
1399
+ Own prose and not the subtree, because that is the extent `amend --replace` writes into: a
1400
+ container counted for its children would name an anchor the substitution then refuses, which
1401
+ is the wrong answer arriving through the read that exists to stop it.
1402
+
1403
+ Every declared prose role unless one is named — the sentence a caller is hunting may be in
1404
+ either file, and a default that looked in one would answer *not found* about the other.
1405
+ """
1406
+ asked = [role] if role else [one for one in PROSE_ROLES if config.has(one)]
1407
+ out: list[Carrier] = []
1408
+ for name in asked:
1409
+ document = config.document(name)
1410
+ where = config.relative(config.path(name))
1411
+ for section in anchored(document):
1412
+ count = section.prose.count(text)
1413
+ if count:
1414
+ out.append(
1415
+ Carrier(
1416
+ anchor=section.anchor,
1417
+ role=name,
1418
+ where=where,
1419
+ line=section.first,
1420
+ title=section.title,
1421
+ count=count,
1422
+ )
1423
+ )
1424
+ return Found(text=text, carriers=tuple(out), roles=tuple(asked))
1425
+
1426
+
1427
+ @dataclass(frozen=True, slots=True)
1428
+ class Deleted:
1429
+ """One section removed whole, and who is left citing it (RK78, RK206).
1430
+
1431
+ A record and no longer a three-tuple (RK1170): the design that task rests on is that both
1432
+ registers come off **one result**, and a tuple has no place to put a method. What the change
1433
+ bought beyond that is :attr:`nested` — the door recomputed the subtree with a second reader
1434
+ to say what went with the heading, and :func:`drop` had the same list in hand to delete it.
1435
+ """
1436
+
1437
+ #: The file without the section, unsaved: the caller mid-transaction decides when.
1438
+ document: Document
1439
+ section: Section
1440
+ #: Sections whose **prose** still names what this deleted (RK206). Reported and never
1441
+ #: refused: a citation is a sentence, and re-wording one is an edit rather than a
1442
+ #: transaction to abandon.
1443
+ cited: tuple[str, ...] = ()
1444
+ #: The anchors that went with it, nested under the one named (RK78). On the record because
1445
+ #: after the write no file holds them, and this answer is their only record.
1446
+ nested: tuple[str, ...] = ()
1447
+ #: The file this was dropped from, as the caller spells it — the same string the refusals
1448
+ #: above take, so a report and a refusal can never name two different files.
1449
+ where: str = ""
1450
+
1451
+ def stated(self, config: Config, wrote: Sequence[Path]) -> str:
1452
+ """What went, and who is left pointing at it."""
1453
+ from roadkeep.rendering import _cited_rows, _staging_rows # noqa: PLC0415 - RK260
1454
+
1455
+ rows = [f"dropped {self.section} from {self.where}"]
1456
+ if self.nested:
1457
+ rows.append(f" nested {', '.join(f'§{a}' for a in self.nested)} went with it")
1458
+ rows += _cited_rows(self.cited)
1459
+ rows += _staging_rows(config.relative(one) for one in wrote)
1460
+ return "\n".join(rows)
1461
+
1462
+ def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
1463
+ """The same answer as data, with the subtree the anchor does not state (RK78)."""
1464
+ from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
1465
+
1466
+ return {
1467
+ **self.section.payload(self.where),
1468
+ "nested": list(self.nested),
1469
+ "cited": list(self.cited),
1470
+ **_wrote_json(config, wrote),
1471
+ }
1472
+
1473
+
1474
+ @dataclass(frozen=True, slots=True)
1475
+ class Written:
1476
+ """One section placed under its block or its anchor (RK93).
1477
+
1478
+ A record and no longer a two-tuple, for :class:`Deleted`'s reason (RK1170). It carries the
1479
+ role because both registers need it — the path to name, and the word limit to count the
1480
+ prose against, which is per role and not per project.
1481
+ """
1482
+
1483
+ document: Document
1484
+ section: Section
1485
+ role: str = "improvements"
1486
+
1487
+ def stated(self, config: Config, wrote: Sequence[Path]) -> str:
1488
+ from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
1489
+
1490
+ where = config.relative(config.path(self.role))
1491
+ rows = [
1492
+ f"§{self.section.anchor} → {where}:{self.section.first} "
1493
+ f"{self.section.counted(config.schema_for(self.role).section_max)}"
1494
+ ]
1495
+ rows += _staging_rows(config.relative(one) for one in wrote)
1496
+ return "\n".join(rows)
1497
+
1498
+ def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
1499
+ from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
1500
+
1501
+ return {
1502
+ **self.section.payload(config.relative(config.path(self.role))),
1503
+ **_wrote_json(config, wrote),
1504
+ }
1505
+
1506
+
1507
+ @dataclass(frozen=True, slots=True)
1508
+ class Rewritten:
1509
+ """One section's heading text or prose corrected in place (RK123, RK1107).
1510
+
1511
+ One record for both doors — anchored and unanchored — because what differs between them is
1512
+ what the write *may* do and not what it answers with: an unanchored section is named by its
1513
+ heading and carries no word count, and :attr:`Section.anchor` being empty is what says so.
1514
+ """
1515
+
1516
+ document: Document
1517
+ section: Section
1518
+ #: Which fields moved. Empty when the file already read that way, and then nothing was
1519
+ #: written — the one answer here with nothing in it to read (RK1109).
1520
+ changed: tuple[str, ...] = ()
1521
+ role: str = "improvements"
1522
+
1523
+ def stated(self, config: Config, wrote: Sequence[Path], read_body: bool) -> str:
1524
+ """What moved, or why nothing did (RK1109).
1525
+
1526
+ `read_body` is the caller's: whether this call looked at the prose at all is a fact
1527
+ about the argv — a piped body and a `--title` land in the unchanged answer together,
1528
+ and one of them means the paragraph was never read.
1529
+ """
1530
+ from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
1531
+ from roadkeep.verbs.reading import unread_prose # noqa: PLC0415 - RK260
1532
+
1533
+ where = config.relative(config.path(self.role))
1534
+ # An unanchored section is named by its heading and never by a bare sigil (RK1107), and
1535
+ # it carries no word count: `section = <n>` is what a *rationale* may spend, and printing
1536
+ # a figure beside a limit is claiming the two are the same number — which the file's
1537
+ # opening paragraph and its contents table are not measured by. `[budgets]` counts bytes.
1538
+ named = f"§{self.section.anchor}" if self.section.anchor else f"'{self.section.title}'"
1539
+ if not self.changed:
1540
+ # RK1109. `unchanged` at exit 0 is the one answer here with nothing in it to read:
1541
+ # the changed path lists its fields, so a caller sees `(title)` and knows the prose
1542
+ # was left alone, and this path listed nothing at all.
1543
+ aside = "" if read_body else f" — {unread_prose()}"
1544
+ return f"{named} unchanged: it already reads that way{aside}"
1545
+ counted = (
1546
+ f" {self.section.counted(config.schema_for(self.role).section_max)}"
1547
+ if self.section.anchor
1548
+ else ""
1549
+ )
1550
+ rows = [
1551
+ f"{named} amended {where}:{self.section.first} "
1552
+ f"({', '.join(self.changed)}){counted}"
1553
+ ]
1554
+ rows += _staging_rows(config.relative(one) for one in wrote)
1555
+ return "\n".join(rows)
1556
+
1557
+ def payload(
1558
+ self, config: Config, wrote: Sequence[Path], read_body: bool
1559
+ ) -> dict[str, object]:
1560
+ from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
1561
+
1562
+ return {
1563
+ **self.section.payload(config.relative(config.path(self.role))),
1564
+ "changed": list(self.changed),
1565
+ # The same fact as a field (RK1109): whether this call looked at the prose at all.
1566
+ # `changed: []` says nothing moved and cannot say why, which is the ambiguity a
1567
+ # piped body and a `--title` land in together.
1568
+ "read_body": read_body,
1569
+ **_wrote_json(config, wrote),
1570
+ }
1571
+
1572
+
1573
+ def drop(
1574
+ document: Document,
1575
+ anchor: str,
1576
+ *,
1577
+ claimed: Mapping[str, Sequence[str]] | None = None,
1578
+ where: str = "",
1579
+ recorded: bool = False,
1580
+ ) -> Deleted:
1581
+ """Delete the section whole — subsections included — and report what went, and who is
1582
+ left citing it.
1583
+
1584
+ A subsection left behind is orphaned prose under the *next* task's heading, which
1585
+ reads as that task's design and is the one outcome worse than deleting too much.
1586
+
1587
+ Unless one of them is not this section's at all. `claimed` is :func:`pointers`' answer,
1588
+ and a nested anchor in it stops the whole write with :class:`SectionOccupied` (RK78) —
1589
+ the deletion is bounded by ownership rather than by depth, so a level-2 grouping four
1590
+ level-3 designs is refused while a task's own `§RK34.1` still goes with `§RK34`. Omitted,
1591
+ nothing is claimed: a caller with no roadmap to read cannot be told about a pointer, and
1592
+ both callers that have one pass it.
1593
+
1594
+ The anchor that was **named** is asked first and answered the same way (RK112). It is the
1595
+ obvious half and it was the missing one: `ship` made that check on its own path and the
1596
+ standalone verb inherited nothing, so the one command that exists to delete a section was
1597
+ the one that could strand a live pointer.
1598
+
1599
+ ``where`` is the file as the report spells it, rendered by the caller and passed in the
1600
+ way ``claimed`` is (RK181): this function takes a :class:`Document` and not a
1601
+ :class:`Config`, so `config.relative` — the one function that renders an address — is out
1602
+ of its reach, and building the string here from ``document.path`` is what printed an
1603
+ absolute path beside a `lint` naming the same file as `IMPROVEMENTS.md:5`.
1604
+
1605
+ The **third** answer is who cited what just went (RK206, RK209), and it is returned
1606
+ rather than left to the callers for this module's own reason: what a deletion breaks is
1607
+ a fact about this file's grammar, the same argument that puts `drop` here instead of in
1608
+ `shipping`. It arrived through the departure path first, so `ship` and `retire` named it
1609
+ and the one verb whose whole job is deleting a section stayed silent — and every refusal
1610
+ above reads a *pointer*, which is the end of the reference that was already read.
1611
+
1612
+ ``recorded`` says this file's records claim their own bodies by id (RK1361), which is the
1613
+ decisions role and nothing else. It changes no outcome and one sentence: the refusal there
1614
+ may not offer a pointer to repoint or a line to ship, neither of which that file has.
1615
+
1616
+ Reported and never refused, unlike everything above it. Those refuse because a pointer is
1617
+ a promise the format makes: a line says `→ §<anchor>` and the anchor has to be there. A
1618
+ citation in prose is a sentence, and a sentence that has to be re-worded is an edit and
1619
+ not a transaction to abandon. Computed **before** the removal, because afterwards the
1620
+ prose is the only end of the reference still in the file.
1621
+ """
1622
+ span = _span(document, anchor)
1623
+ section = find(document, anchor)
1624
+ if span is None or section is None:
1625
+ raise NoSuchSection(anchor, where)
1626
+ if claimed:
1627
+ owners = claimed.get(anchor)
1628
+ if owners:
1629
+ raise SectionClaimed(anchor, owners, where, recorded=recorded)
1630
+ occupied = [
1631
+ (child.anchor, claimed[child.anchor])
1632
+ for child in nested(document, anchor)
1633
+ if child.anchor in claimed
1634
+ ]
1635
+ if occupied:
1636
+ raise SectionOccupied(anchor, occupied, where)
1637
+ # And the same question asked of the **name** rather than of the headings (RK169),
1638
+ # which is the half a corpus addressing its prose as bullets fell through: the check
1639
+ # above proves containment and misses everything that is not a heading, and this one
1640
+ # proves nothing about the file and misses nothing an open line has claimed.
1641
+ descended = _descended(anchor, claimed)
1642
+ if descended:
1643
+ raise AnchorClaimed(anchor, descended, where)
1644
+ leaving = (anchor, *(child.anchor for child in nested(document, anchor)))
1645
+ cited = tuple(dict.fromkeys(by for _, by in citing(document, leaving, ignore=leaving)))
1646
+ start, end, _ = span
1647
+ # One edit, not one per line (RK54): a loop validates every half-deleted state, and a
1648
+ # section quoting a fenced example is briefly a file whose fence has no opening line.
1649
+ return Deleted(
1650
+ document.remove_lines(start, end),
1651
+ section,
1652
+ cited=cited,
1653
+ # The subtree, from the list the deletion itself was computed from — the door
1654
+ # used to read it again with a second reader (RK1170).
1655
+ nested=leaving[1:],
1656
+ where=where,
1657
+ )
1658
+
1659
+
1660
+ def add(
1661
+ config: Config,
1662
+ role: str,
1663
+ anchor: str,
1664
+ title: str,
1665
+ body: str,
1666
+ *,
1667
+ level: int | None = None,
1668
+ task: Task | None = None,
1669
+ opens: tuple[str, str] | None = None,
1670
+ ) -> Written:
1671
+ """Place one section under its block or its anchor, reflowed. Validates first.
1672
+
1673
+ Returns the document unsaved, so a caller mid-transaction (`ship`, `init`) decides
1674
+ when the file is touched.
1675
+
1676
+ ``level`` is **derived** where the caller names none (RK166), and it has to be: a
1677
+ top-level section written at the depth a subsection uses is not a top-level section at
1678
+ all — it lands inside the previous one's subtree, where every reader that asks a heading
1679
+ where it ends would find it. So the depth of a new top level is read off the file's own
1680
+ existing top level, the way `block add` reads a heading's level off the first block
1681
+ heading, and a subsection keeps the depth every caller already got.
1682
+
1683
+ `task` is the line this anchor names, for the one caller holding a line the roadmap
1684
+ does not carry yet: `add --section` (RK93) validates both files before writing either,
1685
+ so its owner cannot be read back off disk — and read off disk it would be absent,
1686
+ which is `anchor.unknown`, a refusal about a line that is one save away. Omitted, the
1687
+ owner is read from the roadmap, which is every other caller.
1688
+
1689
+ ``opens`` is the family this same write declares first, as ``(anchor, title)`` (RK1258) —
1690
+ the one caller being a block's **first** task, whose child address extends a top level no
1691
+ prose file has opened. Without it that call is refused (:class:`UnknownParent`) and the
1692
+ only address available is the family itself, so a block's first design was filed *as* the
1693
+ family heading and every later one as a child of it: two shapes for one thing, and the
1694
+ difference was never a choice anybody made. What is opened is a **container** — a heading
1695
+ and no prose — which is the ordinary structure of a rationale file and the one shape
1696
+ ``body.empty`` does not name, that finding being about a leaf a pointer resolves to.
1697
+ """
1698
+ document = config.document(role)
1699
+ where = config.relative(config.path(role))
1700
+ if task is None:
1701
+ task = _task_for(config, anchor, role)
1702
+ # Bound before it is checked and before it is rendered, so the title this function
1703
+ # validates is the one it writes (RK262) — a heading checked in one spelling and filed
1704
+ # in another is the disagreement L3 refuses a file over.
1705
+ title = _bound(document.schema, anchor, title, task)
1706
+ # The files are read only where nothing live answered *and* the anchor is an id (RK238,
1707
+ # narrowed by RK240): a section written for an open line, or under an outline anchor,
1708
+ # costs no second parse for a door it will never be handed.
1709
+ try:
1710
+ _check(
1711
+ document.schema,
1712
+ anchor,
1713
+ title,
1714
+ body,
1715
+ task,
1716
+ elsewhere=_elsewhere(config, document.schema, anchor, task),
1717
+ known=known(config, anchor, task),
1718
+ # The same question `amend` now asks (RK1227), so the two writers into one file
1719
+ # cannot come to disagree about which addresses a paragraph may cite.
1720
+ resolves=resolvable(config, anchor),
1721
+ )
1722
+ except SectionError as error:
1723
+ # The third door onto the same gap (RK349). `anchor.format` fires on the caller who
1724
+ # typed an id where this scheme numbers its own headings, and the address they now
1725
+ # need is the free child of this block's family — which is what the line writes have
1726
+ # been told since RK312. An anchor naming no task is answered too (RK360), with the
1727
+ # free top-level: that caller has no address at all, which is more and not less.
1728
+ raise naming_the_anchor(
1729
+ config,
1730
+ task.block if task is not None else None,
1731
+ error,
1732
+ namespace=document.schema.ref_prefix or "",
1733
+ anchor=anchor,
1734
+ ) from None
1735
+ unspent(config, role, anchor, document=document, where=where)
1736
+
1737
+ # The file as it was read, for the delta :func:`_refuse_overflow` charges (RK1033).
1738
+ was = document
1739
+ # After every refusal the child can raise and before its placement is computed (RK1258):
1740
+ # the family has to exist for :func:`_extended` to find it, and a transaction that opened
1741
+ # one and then refused the design would leave a heading nobody asked for.
1742
+ if opens is not None:
1743
+ document = _opening(config, role, document, opens, where)
1744
+ lines = _render(document.schema, anchor, title, body, _depth(document, anchor, level))
1745
+ index = _placement(document, anchor, task, where, role)
1746
+ document = _inserted(document, index, lines)
1747
+
1748
+ placed = find(document, anchor)
1749
+ assert placed is not None # rendered by this function a moment ago
1750
+ _refuse_overflow(config, document, anchor, was)
1751
+ return Written(document, placed, role)
1752
+
1753
+
1754
+ #: The second half of the overage refusal, by the door that raised it (RK1034). The
1755
+ #: arithmetic above it is one number and is shared; what changes is the list of ways out,
1756
+ #: which is what a refusal is *for* — and RK1033 shipped `add`'s list at both doors.
1757
+ #:
1758
+ #: At an `add` the address has not been chosen, so "put it somewhere else" is one flag away.
1759
+ #: At an `amend` the section is already there and the prose being handed over replaces prose
1760
+ #: that exists: `anchors --next` opens nothing, and taking the subtree elsewhere is `section
1761
+ #: move`, a different act with consequences for every pointer at it. What is left is shorten
1762
+ #: this, or shorten the parent — and the second is invisible from here, the overage being the
1763
+ #: parent's while the paragraph in front of the caller is the child's.
1764
+ _WAYS_OUT = {
1765
+ "add": (
1766
+ "a subsection is charged to the address that owns it, so this prose belongs at a "
1767
+ "free top-level anchor (`anchors --next`) rather than under §{parent}"
1768
+ ),
1769
+ "amend": (
1770
+ "the overage is §{parent}'s and this paragraph is §{anchor}'s, so the ways out are "
1771
+ "shortening this body or amending §{parent}'s own prose — `section move {anchor} "
1772
+ "--to <free anchor>` is what takes the subtree out from under it"
1773
+ ),
1774
+ }
1775
+
1776
+
1777
+ def _refuse_overflow(
1778
+ config: Config,
1779
+ document: Document,
1780
+ anchor: str,
1781
+ before: Document | None = None,
1782
+ door: str = "add",
1783
+ ) -> None:
1784
+ """Refuse a write that leaves an ancestor over its own limit and worse than it was.
1785
+
1786
+ RK1024 for an `add`, and RK1033 for the `amend` that door left open — which is the one an
1787
+ author reaches more often, a design being amended more than once and written once.
1788
+
1789
+ `add` opens its help with the promise that nothing is written unless every field passes,
1790
+ because *a limit reported after the prose exists is a limit discovered too late to save
1791
+ the tokens it was meant to save*. Charged on the child alone, that promise was false for
1792
+ every nested address: measured in one sitting, `anchors --block AJ` offered `§L.1`,
1793
+ `budget` reported 51 words left, `add` **accepted** a 278-word section, and `lint` then
1794
+ failed the parent by 277. `§L` was 299 words of its own 300 — so every child of it,
1795
+ including an empty one, was over before a word of it was composed, and no writer said so.
1796
+
1797
+ Measured against the file this call has already built rather than against a sum, so the
1798
+ number is the one the gate will read: the walk is the same :func:`find`, the limit is the
1799
+ same `section_max`, and the pointer decides the charge exactly as `_pointed_at` says
1800
+ (RK215). An ancestor nothing points at is a container, and counting its children against
1801
+ it here would refuse prose the gate calls clean — which is the disagreement that made
1802
+ this a defect rather than a limit.
1803
+
1804
+ Every ancestor and not only the immediate one: `L.1.2` is inside `L.1` and inside `L`,
1805
+ and a parent with room under a grandparent with none is still a write `lint` fails.
1806
+
1807
+ ``before`` is the file as it was read, and it makes the rule a **delta** rather than a
1808
+ state: a shorter body that leaves an already-over parent over is a correction in the
1809
+ right direction, and refusing it is RK215's deadlock exactly — every door closed and the
1810
+ file left saying something untrue. So what is refused is a write that makes the total
1811
+ worse, never one that arrives at a file somebody else left over. An `add` passes it too:
1812
+ a section body cannot be empty, so an insert is always worse by its own words, and
1813
+ stating the rule once is what keeps the two doors from disagreeing about it.
1814
+ """
1815
+ limit = document.schema.section_max
1816
+ parent = _parent(anchor)
1817
+ while parent:
1818
+ whole = find(document, parent)
1819
+ if whole is None or whole.words <= limit or not _pointed_at(config, parent):
1820
+ parent = _parent(parent)
1821
+ continue
1822
+ was = find(before, parent) if before is not None else None
1823
+ if was is not None and whole.words <= was.words:
1824
+ parent = _parent(parent)
1825
+ continue
1826
+ raise SectionError(
1827
+ (
1828
+ Violation(
1829
+ "body.too-long",
1830
+ "body",
1831
+ f"§{parent} would be "
1832
+ f"{over_by(whole.words, limit, unit='word', because=' with this section under it')}"
1833
+ f" — {_WAYS_OUT[door].format(parent=parent, anchor=anchor)}",
1834
+ ),
1835
+ )
1836
+ )
1837
+
1838
+
1839
+ def unspent(config: Config, role: str, anchor: str, *, document: Document, where: str) -> None:
1840
+ """Refuse an address anything has already taken — this file, a sibling, or history.
1841
+
1842
+ The three questions `add` asks about a destination, asked once (RK377). `move` asks the
1843
+ same three about the address it is re-writing to, and a second call site spelling them out
1844
+ is how one door comes to refuse what the other writes: the whole reason RK302 exists is
1845
+ that the doubling check was made against the file being written and not against the
1846
+ project, and a repair verb that inherited two of the three would recreate the state it was
1847
+ added to fix.
1848
+
1849
+ ``document`` is the caller's own parse rather than a fourth read of the same file: both
1850
+ callers already hold it, and reading it again is what makes two readings possible.
1851
+ """
1852
+ existing = find(document, anchor)
1853
+ if existing is not None:
1854
+ raise SectionExists(anchor, where, existing.first)
1855
+ _refuse_doubling(config, role, anchor)
1856
+ _refuse_reuse(config, role, anchor, where)
1857
+
1858
+
1859
+ def _refuse_doubling(config: Config, role: str, anchor: str) -> None:
1860
+ """Refuse an anchor a **sibling** prose file already declares (RK302).
1861
+
1862
+ :func:`_refuse_reuse` catches the address a heading in history spent, which is the case
1863
+ where history is the only witness. A live one is visible in the file next to it, and until
1864
+ this ran nothing looked: RK297 taught the *read* that an outline spans every declared prose
1865
+ file, and the write kept asking the document it was writing into.
1866
+
1867
+ :func:`declaring` and not a fourth reading of the same question (RK229) — the one resolver
1868
+ three verbs already ask which file holds an anchor. The target role is skipped because the
1869
+ caller checked it a line earlier, against the document it has open, and that refusal names
1870
+ the file the author is writing to rather than one they did not mention.
1871
+
1872
+ Both schemes, unlike :func:`_refuse_reuse`: under `id` the anchor is the id and
1873
+ :func:`~roadkeep.authoring.refuse_reuse` covers the roadmap, but two prose files can still
1874
+ hold `§RK2` between them, which is the same `section.ambiguous` by the same reading.
1875
+ """
1876
+ for other in declaring(config, anchor):
1877
+ if other == role:
1878
+ continue
1879
+ held = find(config.document(other), anchor)
1880
+ if held is not None:
1881
+ raise SectionExists(
1882
+ anchor,
1883
+ config.relative(config.path(other)),
1884
+ held.first,
1885
+ elsewhere=True,
1886
+ )
1887
+
1888
+
1889
+ def _refuse_reuse(config: Config, role: str, anchor: str, where: str) -> None:
1890
+ """Refuse an outline address a heading in this file's history already spent (RK247).
1891
+
1892
+ **Outline only.** Under the id scheme the anchor is the id, so reuse is refused one file
1893
+ over by `refuse_reuse` (RK4) and an anchor whose task shipped fails `anchor.unknown`
1894
+ before ever reaching here — a second check would be a second opinion about a closed
1895
+ question, on every `add --section` this project makes.
1896
+
1897
+ Silence where history cannot answer, the rule every reader of it keeps: a shallow clone
1898
+ and a directory that is not a repository must not stop a write, and what is lost is a
1899
+ refusal and never a file. Imported here rather than at the top because `history` reads
1900
+ this module (RK260), and the cycle is only avoided at the direction the caller is in.
1901
+ """
1902
+ if config.schema_for(role).ref_scheme == "id":
1903
+ return
1904
+ from roadkeep.history import anchors, next_child # noqa: PLC0415 - RK260
1905
+
1906
+ # The project's addresses and not this file's (RK297): an outline spans every prose file
1907
+ # a project declares, so a write refused against one of them is a write that takes an
1908
+ # address the sibling spent — which is the doubled anchor, made by the check against it.
1909
+ taken = anchors(config)
1910
+ spent = next((one for one in taken if one.anchor == anchor and not one.live), None)
1911
+ if spent is None:
1912
+ return
1913
+ free = next_child(taken, anchor.rsplit(".", 1)[0]) if "." in anchor else ""
1914
+ raise AnchorRetired(anchor, spent.written_in, free, where)
1915
+
1916
+
1917
+ def _refuse_subtree(document: Document, anchor: str, body: str) -> None:
1918
+ """Refuse a body that carries a subsection's own heading (RK1112).
1919
+
1920
+ `show` prints the subtree and this verb replaces the own prose, so the obvious round-trip
1921
+ — show a section, correct one sentence, amend it back — arrived at the word limit instead:
1922
+ measured in claude-tray, 1692 words against 300 on a `§XXIII` with six subsections. That
1923
+ refusal is right about the number and says nothing about the cause, and an author reads
1924
+ *"a section this long is two sections"* as a verdict on prose they only meant to pass
1925
+ through. Asked **before** the limit, because a mistake about extent is not a mistake about
1926
+ length and the two have no remedy in common.
1927
+
1928
+ Read off the file's own heading lines and never by parsing the pasted text: what a child's
1929
+ heading is, this document already decided, so the check is whether the body carries one of
1930
+ those strings — no second grammar for headings, and a body carrying none of them is prose
1931
+ however long. The remedy is the extent, so the message names both halves of it: the
1932
+ reader that prints what this verb takes, and the anchor a subsection is amended by.
1933
+ """
1934
+ lines = {line.strip() for line in body.splitlines() if line.strip()}
1935
+ for child in nested(document, anchor):
1936
+ heading = document.lines[child.first - 1].strip()
1937
+ if heading in lines:
1938
+ raise SectionError(
1939
+ (
1940
+ Violation(
1941
+ "body.subtree",
1942
+ "body",
1943
+ f"the body carries §{child.anchor}'s own heading, so this is "
1944
+ f"§{anchor}'s subtree and not its prose: `section show {anchor} "
1945
+ f"--own` prints the extent this replaces, and §{child.anchor} is "
1946
+ f"amended by its own anchor",
1947
+ ),
1948
+ )
1949
+ )
1950
+
1951
+
1952
+ def amend(
1953
+ config: Config,
1954
+ role: str,
1955
+ anchor: str,
1956
+ *,
1957
+ title: str | None = None,
1958
+ body: str | None = None,
1959
+ substitute: Substitution | None = None,
1960
+ ) -> Rewritten:
1961
+ """Rewrite one live section's heading text or its prose, in place (RK123).
1962
+
1963
+ The gap this closes is a union of three correct refusals: `drop` refuses while an open
1964
+ line points at the anchor, `add` refuses the duplicate, and the guard denies the hand
1965
+ edit — so the rationale of an **open** task could not be changed at all, by anybody,
1966
+ until it shipped and the section was deleted. That is the ordinary case and not an edge
1967
+ one: a design under a marker that is not ✅ is expected to change.
1968
+
1969
+ Its **own** prose and never the subtree. A `§<id>.1` is a section with an anchor of its
1970
+ own, amended by naming it — replacing the subtree here would delete somebody's
1971
+ subsection as a side effect of correcting a paragraph, which is `drop`'s job and
1972
+ `drop`'s refusals.
1973
+
1974
+ The anchor is not a field. An address is `renumber`'s (RK97) under the id scheme and
1975
+ :func:`move`'s under an outline (RK377), and either way a section that changed anchor is a
1976
+ section every pointer at it has to change with — which is a transaction and not a field.
1977
+
1978
+ A rewrite that leaves nothing of the original is **not** refused, and the question the
1979
+ design left open is answered here: the falsifiable claim is the `symptom` on the task
1980
+ line, which `amend` already refuses to touch (RK7). A rationale rewritten under an
1981
+ unchanged symptom is still that symptom's rationale; one rewritten because the symptom
1982
+ changed is a line the other verb will not let you rewrite. A second guard here would be
1983
+ a second opinion about a question already answered one file over.
1984
+
1985
+ ``substitute`` is the **narrow** form of the same write (RK1263): one string out, one in,
1986
+ derived from the prose already on disk so a table or a fence is never retyped. What it
1987
+ changes about the rules is one thing, and it is the reason this parameter is not just sugar
1988
+ at the verb layer — a section already over the word limit for reasons the edit has nothing
1989
+ to do with was refused for a four-character correction, and the way out was shortening
1990
+ prose the caller never came to touch. So an edit that does not *grow* the prose inherits
1991
+ the overrun instead of being charged it, which is `lint --baseline`'s argument arriving at
1992
+ a door: the standing debt stays a finding, and this call is not what it is about. Only
1993
+ here, because only here is the growth bounded by the replacement's own delta — a
1994
+ whole-body rewrite that happens to come back no longer is still a body somebody composed.
1995
+ """
1996
+ document = config.document(role)
1997
+ span = _span(document, anchor)
1998
+ section = find(document, anchor)
1999
+ if span is None or section is None:
2000
+ raise NoSuchSection(anchor, config.relative(config.path(role)))
2001
+ _, _, heading = span
2002
+ # The one reading of "this section's own prose", off the record `find` already built
2003
+ # (RK1112): a second slice here is the second answer that let `show` print one extent and
2004
+ # this verb take another.
2005
+ own = section.prose
2006
+ if body is not None:
2007
+ _refuse_subtree(document, anchor, body)
2008
+
2009
+ # Read before the no-op check rather than after it, because a `--title` has to be bound
2010
+ # before it can be compared (RK262): the title that differs from the file only by the id
2011
+ # it omits is a no-op, and comparing the unbound spelling would report a change and
2012
+ # rewrite the heading to the bytes it already holds. The cost is one roadmap parse on the
2013
+ # path that returns without writing, which is the rarest one here.
2014
+ owner = _task_for(config, anchor, role)
2015
+ # Only a title that was **passed** is bound. A body-only amend leaves the heading alone,
2016
+ # id or no id: correcting a paragraph is not the call in which a heading silently changes.
2017
+ wanted_title = (
2018
+ section.title if title is None else _bound(document.schema, anchor, title, owner)
2019
+ )
2020
+ # The prose on disk is what a substitution is applied to, which is the whole point: the
2021
+ # bytes the caller never named are the bytes that cannot be lost (RK1263).
2022
+ wanted_body = own if body is None else body
2023
+ if substitute is not None:
2024
+ wanted_body = substitute.applied(own, f"§{anchor}")
2025
+ changed = tuple(
2026
+ name
2027
+ for name, before, after in (
2028
+ ("title", section.title, wanted_title.strip()),
2029
+ ("body", own, _normalize(wanted_body)),
2030
+ )
2031
+ if before != after
2032
+ )
2033
+ if not changed:
2034
+ return Rewritten(document, section, (), role)
2035
+
2036
+ _check(
2037
+ document.schema,
2038
+ anchor,
2039
+ wanted_title,
2040
+ wanted_body,
2041
+ owner,
2042
+ elsewhere=_elsewhere(config, document.schema, anchor, owner),
2043
+ known=known(config, anchor, owner),
2044
+ # The addresses this body may cite (RK1227), read from the project because `_check`
2045
+ # takes a schema and cannot.
2046
+ resolves=resolvable(config, anchor),
2047
+ # What the prose already spent, where this edit did not compose it (RK1263).
2048
+ standing=None if substitute is None else words(own),
2049
+ )
2050
+ updated = _rewrite(
2051
+ document,
2052
+ heading,
2053
+ replace(section, title=wanted_title.strip()),
2054
+ wanted_body,
2055
+ retitle="title" in changed,
2056
+ )
2057
+ amended = find(updated, anchor)
2058
+ assert amended is not None # the heading this function just wrote
2059
+ # Charged against the subtree **only where a line points at this anchor**, which is
2060
+ # exactly what the gate charges (RK215). The subtree unconditionally was a writer holding
2061
+ # a file to a limit `lint` does not: measured in Claude Code Tray, a nine-word correction
2062
+ # to a two-sentence intro was refused for 934 words — 900 of them three live
2063
+ # subsections' — on a file that passes the gate. With `drop` refused by those same live
2064
+ # pointers and the guard denying the hand edit, every door was closed and the file left
2065
+ # saying something untrue, which is RK141's deadlock one level over.
2066
+ #
2067
+ # So an intro **is** a section like any other, which is the question the design left open:
2068
+ # `add` already writes a top-level anchor's own prose (RK166), `_rewrite` above already
2069
+ # replaces only that prose, and where nothing points at the anchor `_check` has already
2070
+ # charged it — so there is nothing further to ask.
2071
+ # And the same inheritance one measurement over (RK1263): the subtree is what a pointed-at
2072
+ # section is billed, so a narrow edit inside an already-over subtree is refused here for
2073
+ # words in somebody's subsections — which is the deadlock above with one more layer of
2074
+ # prose the caller never came to touch.
2075
+ if (
2076
+ _pointed_at(config, anchor)
2077
+ and amended.words > document.schema.section_max
2078
+ and not (substitute is not None and amended.words <= section.words)
2079
+ ):
2080
+ counted = over_by(
2081
+ amended.words,
2082
+ document.schema.section_max,
2083
+ unit="word",
2084
+ because=" with its subsections",
2085
+ )
2086
+ raise SectionError(
2087
+ (
2088
+ Violation(
2089
+ "body.too-long",
2090
+ "body",
2091
+ f"{counted}; a section this long is two sections, or a paragraph "
2092
+ f"that belongs in the commit",
2093
+ ),
2094
+ )
2095
+ )
2096
+ # The door RK1024 and RK1029 left open (RK1033): a rewrite of `§L.3` that puts `§L`
2097
+ # eighty words over was accepted and reported by `lint` afterwards, which is the
2098
+ # sequence both of those closed at `add`. The delta is what makes it safe here — an
2099
+ # amend is where the prose already exists, and refusing a *shortening* is RK215's
2100
+ # deadlock in the one direction an author can act in.
2101
+ _refuse_overflow(config, updated, anchor, document, door="amend")
2102
+ return Rewritten(updated, amended, changed, role)
2103
+
2104
+
2105
+ def amend_untitled(
2106
+ config: Config,
2107
+ role: str,
2108
+ title: str,
2109
+ *,
2110
+ body: str | None = None,
2111
+ retitle: str | None = None,
2112
+ substitute: Substitution | None = None,
2113
+ ) -> Rewritten:
2114
+ """Rewrite an unanchored section's prose or its heading, in place (RK1107).
2115
+
2116
+ :func:`amend`'s twin for the two regions a prose file has that carry no address — its
2117
+ opening, and a `## Table of contents`. The same three properties and one fewer: own prose
2118
+ and never the subtree, nothing written unless something changed, and **no `owner`** —
2119
+ an unanchored section belongs to no task, so there is no id to bind into the heading and no
2120
+ pointer that a re-titling has to move with it. That last is the whole reason this is a
2121
+ second function rather than a branch in the first: `amend`'s body is about the anchor, the
2122
+ task that owns it, and the budget the two decide between them, and an unanchored section
2123
+ has none of the three.
2124
+
2125
+ Not budgeted, deliberately. `section = <n>` is what a *rationale* may spend, measured
2126
+ against a corpus of rationale sections; a file's opening paragraph and a contents table are
2127
+ neither, and charging them a limit nobody measured them against is how a ceiling comes to
2128
+ refuse the prose it was derived from. What holds them is `[budgets]` on the whole file,
2129
+ which already counts every byte of both.
2130
+ """
2131
+ document = config.document(role)
2132
+ heading = titled(document, title)
2133
+ if heading is None:
2134
+ raise NoSuchSection(title, config.relative(config.path(role)))
2135
+ end = document.prose_end(heading)
2136
+ own = "".join(document.lines[heading.lineno : end]).strip("\r\n")
2137
+ section = Section(
2138
+ anchor="",
2139
+ title=heading.text.strip(),
2140
+ level=heading.level,
2141
+ first=heading.lineno,
2142
+ last=end,
2143
+ body=own,
2144
+ )
2145
+ wanted_title = section.title if retitle is None else retitle.strip()
2146
+ # The narrow form reaches here too (RK1263), and this is the region it is most obviously
2147
+ # for: a `## Table of contents` is a table whose every row is a heading somebody's ship
2148
+ # moved, and retyping the whole of it to correct one row is the risk that task is about.
2149
+ wanted_body = own if body is None else body
2150
+ if substitute is not None:
2151
+ wanted_body = substitute.applied(own, repr(section.title))
2152
+ changed = tuple(
2153
+ name
2154
+ for name, before, after in (
2155
+ ("title", section.title, wanted_title),
2156
+ ("body", own, _normalize(wanted_body)),
2157
+ )
2158
+ if before != after
2159
+ )
2160
+ if not changed:
2161
+ return Rewritten(document, section, (), role)
2162
+ if not wanted_title:
2163
+ raise SectionError(
2164
+ (
2165
+ Violation(
2166
+ "title.empty",
2167
+ "title",
2168
+ "an unanchored section is addressed by its heading, so a blank one "
2169
+ "leaves it with no address at all",
2170
+ ),
2171
+ )
2172
+ )
2173
+ updated = _rewrite(
2174
+ document,
2175
+ heading,
2176
+ replace(section, title=wanted_title),
2177
+ wanted_body,
2178
+ retitle="title" in changed,
2179
+ )
2180
+ return Rewritten(
2181
+ updated,
2182
+ replace(section, title=wanted_title, body=_normalize(wanted_body)),
2183
+ changed,
2184
+ role,
2185
+ )
2186
+
2187
+
2188
+ #: The governed files whose lines carry a `→ §<anchor>`, which is the end of a pointer a
2189
+ #: re-address has to move with the heading. The deferred store is one (RK96): pausing a line
2190
+ #: keeps its section, so its pointer is as live as the roadmap's and the gate reads both.
2191
+ POINTING_ROLES = ("roadmap", "deferred")
2192
+
2193
+
2194
+ @dataclass(frozen=True, slots=True)
2195
+ class Moved:
2196
+ """Every edit one section's change of address makes, as data, before it is written."""
2197
+
2198
+ anchor: str
2199
+ to: str
2200
+ role: str
2201
+ #: The section as it now reads, at its new address.
2202
+ section: Section
2203
+ #: The nested addresses re-written with it, `(before, after)` in file order.
2204
+ subsections: tuple[tuple[str, str], ...] = ()
2205
+ #: The governed files this write leaves changed, by role. A mapping and not named fields
2206
+ #: for :class:`~roadkeep.renumbering.Renumbering`'s reason: which files are in it is a
2207
+ #: property of the project, a deferred store being optional and a pointer being a line
2208
+ #: some backlogs carry none of.
2209
+ documents: Mapping[str, Document] = field(default_factory=dict)
2210
+ #: Every line whose pointer followed, as `(id, address)`. Its own address and not the
2211
+ #: named one: a line pointing at a subsection follows to `§I.11.1` while the section this
2212
+ #: was called about lands at `§I.11`, and one destination for both would be a report
2213
+ #: nobody can check against the file. Named and never silent — a pointer is the other end
2214
+ #: of the address that moved, and the author is who can say whether it should have.
2215
+ repointed: tuple[tuple[str, str], ...] = ()
2216
+ #: Lines left pointing at the old address because a sibling prose file still declares it,
2217
+ #: as `(id, address)` — the doubling this verb is usually called for, resolving to the
2218
+ #: section that stayed rather than following the one that moved.
2219
+ kept: tuple[tuple[str, str], ...] = ()
2220
+ #: Sections whose **prose** still cites an address that moved, as `(address, by)`.
2221
+ #: Reported and never rewritten, for the reason `drop` reports the same thing: a pointer
2222
+ #: is a promise the format makes and a citation is a sentence (L4).
2223
+ cited: tuple[tuple[str, str], ...] = ()
2224
+
2225
+ def save(self) -> tuple[Path, ...]:
2226
+ """Write every file this move touched, and answer them all (RK1130)."""
2227
+ return save_all(*self.documents.values())
2228
+
2229
+ def stated(self, config: Config, wrote: Sequence[Path]) -> str:
2230
+ """Where the address went, and every line that followed it (RK377).
2231
+
2232
+ Beside :meth:`payload` since RK1170. Four lists and never a count: a pointer is the
2233
+ other end of an address that moved, and the line that changed is the one whose author
2234
+ has to agree it should have (RK97).
2235
+ """
2236
+ from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
2237
+
2238
+ where = config.relative(config.path(self.role))
2239
+ rows = [
2240
+ f"§{self.anchor} → §{self.to} {where}:{self.section.first}",
2241
+ *(f" nested §{before} → §{after}" for before, after in self.subsections),
2242
+ *(f" pointer {one} follows it to §{a}" for one, a in self.repointed),
2243
+ # The doubling this verb is usually called for: the address still resolves, to the
2244
+ # section that stayed, and that is the answer rather than a thing left half done.
2245
+ *(
2246
+ f" kept {one} still points at §{a}, which the other file declares"
2247
+ for one, a in self.kept
2248
+ ),
2249
+ *(
2250
+ f" cited §{by} names §{a} in its prose — that address has moved"
2251
+ for a, by in self.cited
2252
+ ),
2253
+ ]
2254
+ rows += _staging_rows(config.relative(one) for one in wrote)
2255
+ return "\n".join(rows)
2256
+
2257
+ def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
2258
+ """The same answer as data, with each list as pairs a caller can act on."""
2259
+ from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
2260
+
2261
+ where = config.relative(config.path(self.role))
2262
+ return {
2263
+ **self.section.payload(where),
2264
+ "from": self.anchor,
2265
+ "subsections": [
2266
+ {"from": before, "to": after} for before, after in self.subsections
2267
+ ],
2268
+ "repointed": [{"id": one, "to": a} for one, a in self.repointed],
2269
+ "kept": [{"id": one, "address": a} for one, a in self.kept],
2270
+ "cited": [{"address": a, "by": by} for a, by in self.cited],
2271
+ **_wrote_json(config, wrote),
2272
+ }
2273
+
2274
+
2275
+ def move(config: Config, role: str, anchor: str, to: str) -> Moved:
2276
+ """Re-address one live section, its own subtree and every pointer at it (RK377).
2277
+
2278
+ The verb an outline had none of. `renumber` moves an **id**, and keeps the pointer as
2279
+ typed wherever the scheme is not `id` — which is precisely the scheme a project with a
2280
+ hand-kept outline is on — so a doubled address, the thing `lint` reports as
2281
+ `section.ambiguous` and the write path refuses to create, was repairable only by the hand
2282
+ edit the guard denies. Turing adopted the tool with 13 of them.
2283
+
2284
+ Everything the address owns, or nothing. The heading, every nested anchor that
2285
+ :func:`descending` says is this one's own numbering, and the `→ §<anchor>` on every line
2286
+ in :data:`POINTING_ROLES` naming one of them, validated before a file is touched — a
2287
+ re-address that moved the heading and not the pointer is the dangling reference this
2288
+ module exists to prevent, one verb over.
2289
+
2290
+ The destination takes :func:`unspent`, which is every refusal `add` computes about an
2291
+ address: taken here, declared by a sibling prose file, or spent by a heading in this
2292
+ file's history. Each **new** address is asked, not only the named one, because a
2293
+ subsection's is derived from its parent's and a collision on `§I.14.1` is the same
2294
+ collision one segment down.
2295
+
2296
+ **A pointer follows the section when nothing else answers its address, or when this
2297
+ heading names its task.** Both halves are readings this module already makes, and neither
2298
+ is a guess. The ordinary re-address is the first: nothing else declares the old address,
2299
+ so a pointer left behind is the dangling reference, and it moves. The doubling this verb
2300
+ exists for is the second, and moving every pointer there would be exactly wrong — the
2301
+ address resolved to two sections, one of them names the task in its heading
2302
+ (:func:`owners`), and repairing the *other* file must leave that line pointing where its
2303
+ design still is. What stays is reported as :attr:`Moved.kept`, because a line the caller
2304
+ expected to move and that did not is the half of the answer the files no longer state.
2305
+
2306
+ What it does not do is move prose. The section stays exactly where it is in the file and
2307
+ only its address changes, which is why :class:`NotASibling` bounds the destination to the
2308
+ parent the source already had — see that class for why the two cannot be separated.
2309
+ """
2310
+ document = config.document(role)
2311
+ where = config.relative(config.path(role))
2312
+ schema = document.schema
2313
+ if schema.ref_scheme == "id":
2314
+ raise AnchorIsId(anchor, where)
2315
+ section = find(document, anchor)
2316
+ if section is None:
2317
+ raise NoSuchSection(anchor, where)
2318
+ # The project's spelling of the address and not the caller's: `find` resolves a bare `I.2`
2319
+ # in a namespaced file, and every comparison below is against anchors :func:`anchored`
2320
+ # already qualified (RK340).
2321
+ anchor = section.anchor
2322
+ if (bad := _address_violation(schema, to)) is not None:
2323
+ raise SectionError((bad,))
2324
+ if to == anchor:
2325
+ raise SameAnchor(anchor)
2326
+ if _parent(to) != _parent(anchor):
2327
+ raise NotASibling(anchor, to, _parent(anchor), _free_under(config, _parent(anchor)))
2328
+
2329
+ children = descending(document, anchor)
2330
+ subsections = tuple(
2331
+ (child.anchor, f"{to}{child.anchor[len(anchor) :]}") for child in children
2332
+ )
2333
+ for address in (to, *(after for _, after in subsections)):
2334
+ unspent(config, role, address, document=document, where=where)
2335
+
2336
+ ids = schema.id_pattern()
2337
+ carried = {
2338
+ moving.anchor: Carried(
2339
+ to=after,
2340
+ owns=owners(moving, ids),
2341
+ # Whichever files answer the old address once this one stops: empty is the plain
2342
+ # re-address, where a pointer left behind resolves to nothing.
2343
+ answered_by=tuple(r for r in declaring(config, moving.anchor) if r != role),
2344
+ )
2345
+ for moving, after in ((section, to), *zip(children, (a for _, a in subsections), strict=True))
2346
+ }
2347
+ # Read before the rewrite, while the prose and the addresses it names still agree. Nothing
2348
+ # is ignored: a citation inside the moving subtree is as stale afterwards as one outside it.
2349
+ cited = citing(document, tuple(carried))
2350
+ # By line number and applied to a document that reparses, which is why the headings are
2351
+ # collected first: one `replace_line` is one line for one line, so no heading below an edit
2352
+ # has moved under the edits above it (the care :func:`_rewrite` takes for the same reason).
2353
+ updated = document.replace_line(
2354
+ section.first - 1, heading_of(schema, replace(section, anchor=to))
2355
+ )
2356
+ for child, after in zip(children, (after for _, after in subsections), strict=True):
2357
+ updated = updated.replace_line(
2358
+ child.first - 1, heading_of(schema, replace(child, anchor=after))
2359
+ )
2360
+ documents: dict[str, Document] = {role: updated}
2361
+ repointed, kept = _repoint(config, carried, documents)
2362
+
2363
+ landed = find(updated, to)
2364
+ assert landed is not None # the heading this function wrote a moment ago
2365
+ return Moved(
2366
+ anchor=anchor,
2367
+ to=to,
2368
+ role=role,
2369
+ section=landed,
2370
+ subsections=subsections,
2371
+ documents=documents,
2372
+ repointed=repointed,
2373
+ kept=kept,
2374
+ cited=cited,
2375
+ )
2376
+
2377
+
2378
+ @dataclass(frozen=True, slots=True)
2379
+ class Carried:
2380
+ """One address on the move, and what decides whether a pointer at it goes too (RK377)."""
2381
+
2382
+ to: str
2383
+ #: The task ids this heading names, which is the claim to be their design (:func:`owners`).
2384
+ owns: tuple[str, ...]
2385
+ #: The other prose roles still declaring the address after this write — the doubling.
2386
+ answered_by: tuple[str, ...]
2387
+
2388
+ def follows(self, task_id: str) -> bool:
2389
+ """Whether this line's pointer moves with the heading — see :func:`move`."""
2390
+ return not self.answered_by or task_id in self.owns
2391
+
2392
+
2393
+ def _repoint(
2394
+ config: Config, carried: Mapping[str, Carried], documents: dict[str, Document]
2395
+ ) -> tuple[tuple[tuple[str, str], ...], tuple[tuple[str, str], ...]]:
2396
+ """Rewrite every `→ §<old>` that follows its heading, by line file (RK377).
2397
+
2398
+ Which lines those are is read once, before any of them is rewritten, and re-fetched by id
2399
+ inside the loop: `replace_task` reparses, so an entry held across an edit is one whose line
2400
+ number may already have moved — the care every mutator in :mod:`roadkeep.kernel.document` takes.
2401
+
2402
+ Through `schema.check`, which is what refuses a longer address that pushes the rendered
2403
+ line past its limit. That refusal belongs here rather than after the write: a pointer left
2404
+ behind because the line would not fit is the dangling reference, and this transaction has
2405
+ touched nothing yet.
2406
+ """
2407
+ moved: list[tuple[str, str]] = []
2408
+ stayed: list[tuple[str, str]] = []
2409
+ for name in POINTING_ROLES:
2410
+ if not config.has(name) or not config.path(name).is_file():
2411
+ continue
2412
+ lines = config.document(name)
2413
+ pointing = _following(lines, carried, stayed)
2414
+ for task_id in pointing:
2415
+ current = next(e for e in lines.entries if e.task.id == task_id)
2416
+ lines = lines.replace_task(
2417
+ current,
2418
+ lines.schema.check(
2419
+ replace(current.task, ref=carried[current.task.ref].to)
2420
+ ),
2421
+ )
2422
+ if pointing:
2423
+ documents[name] = lines
2424
+ moved.extend((one, carried[ref].to) for one, ref in pointing.items())
2425
+ return tuple(moved), tuple(stayed)
2426
+
2427
+
2428
+ def _following(
2429
+ lines: Document, carried: Mapping[str, Carried], stayed: list[tuple[str, str]]
2430
+ ) -> dict[str, str]:
2431
+ """Which of this file's lines follow their heading, by id, and which are left behind."""
2432
+ out: dict[str, str] = {}
2433
+ for entry in lines.entries:
2434
+ one = carried.get(entry.task.ref)
2435
+ if one is None:
2436
+ continue
2437
+ if one.follows(entry.task.id):
2438
+ out[entry.task.id] = entry.task.ref
2439
+ else:
2440
+ stayed.append((entry.task.id, entry.task.ref))
2441
+ return out
2442
+
2443
+
2444
+ def _parent(anchor: str) -> str:
2445
+ """The address one segment up — `S:I.2` → `S:I`, and `''` for a top level.
2446
+
2447
+ The namespace is not a segment (RK340): `S:I` is one address whose separator is a colon,
2448
+ so a top level keeps its prefix and answers `''` here like any other.
2449
+ """
2450
+ return anchor.rsplit(".", 1)[0] if "." in anchor else ""
2451
+
2452
+
2453
+ def _rewrite(
2454
+ document: Document,
2455
+ heading: Heading,
2456
+ section: Section,
2457
+ body: str,
2458
+ *,
2459
+ retitle: bool = True,
2460
+ ) -> Document:
2461
+ """Swap a heading's line and the prose under it for the reflowed replacement.
2462
+
2463
+ One removal and one insertion per line rather than a patch, because every mutator in
2464
+ :mod:`roadkeep.kernel.document` reparses — so the region is taken out first and the new lines
2465
+ go in at the heading's own index, where nothing below has moved yet.
2466
+
2467
+ ``retitle`` is false where only the prose changed, and then the heading line is not
2468
+ touched at all (RK388). It used to be re-rendered unconditionally, and under an outline
2469
+ that is a **silent rewrite of something nobody named**: the reader accepts `## §I A
2470
+ design` because a sigil an author wrote is not a spelling to punish (RK44), and
2471
+ :func:`anchor_text` then writes the canonical `## I A design` — so a `section amend
2472
+ --body` on any section in the file took the `§` off the one it was passed, along with
2473
+ whatever spacing that heading had. `lint` called the result clean, because L3 is held
2474
+ over task lines and a prose file has none.
2475
+
2476
+ Of the three repairs the design weighed — refuse the file, make the sigil canonical, or
2477
+ narrow the reader — this is a fourth, and it is the one that costs nothing: the writer
2478
+ stops reproducing a line it was not asked about. An amend that *does* pass `--title` is
2479
+ the caller asking for the heading to change, and there the canonical spelling is right.
2480
+ """
2481
+ end = document.prose_end(heading)
2482
+ payload = ["", *_body_lines(document.schema, body)]
2483
+ if end < len(document.lines):
2484
+ # The blank that separates this section's prose from the next heading. Kept when
2485
+ # there is a next heading and omitted at the end of the file, which is where a
2486
+ # trailing blank is one nobody put there.
2487
+ payload.append("")
2488
+ updated = document.remove_lines(heading.lineno, end)
2489
+ for offset, raw in enumerate(payload):
2490
+ updated = updated.insert_line(heading.lineno + offset, raw)
2491
+ if not retitle:
2492
+ return updated
2493
+ # The heading last and through :func:`heading_of`, so the one writer of that spelling
2494
+ # stays one (RK44) — an amend that composed it here would be the second.
2495
+ return updated.replace_line(heading.lineno - 1, heading_of(document.schema, section))
2496
+
2497
+
2498
+ def paragraphs(body: str) -> tuple[int, ...]:
2499
+ """What each paragraph of a body costs, in the same unit :func:`words` charges (RK311).
2500
+
2501
+ The half a refusal was missing. `budget` prices the ceiling before a word exists, which
2502
+ is the right half and the one L1 is about; what had no answer was a draft that already
2503
+ exists — measured over one session of thirteen filings, **fifteen** `body.too-long`
2504
+ refusals, three of them over one or two words, each discarding about 250 words to remove
2505
+ a handful. The overage alone does not shorten the second attempt: it says a cut is needed
2506
+ and leaves the author counting by hand for somewhere to make it, against a number this
2507
+ module has already computed exactly.
2508
+
2509
+ So the refusal says **where**. Paragraphs are blank-line separated, a fenced block is one
2510
+ paragraph however many blanks are inside it, and each is charged by the same reading the
2511
+ limit uses — so the three shapes :func:`words` exempts show as `0` rather than as
2512
+ something a cut could reach. That zero is the answer to the other half of the question: a
2513
+ section over the limit whose longest paragraph is a table is not one to split.
2514
+ """
2515
+ out: list[int] = []
2516
+ current: list[str] = []
2517
+ fence: str | None = None
2518
+ for raw in body.splitlines():
2519
+ line = raw.lstrip()
2520
+ if fence is not None:
2521
+ current.append(raw)
2522
+ if line.startswith(fence):
2523
+ fence = None
2524
+ continue
2525
+ if line.startswith(_FENCES):
2526
+ # A fence opens *inside* whatever paragraph is being read, so an intro line and
2527
+ # the block under it stay one unit — which is how the author sees them.
2528
+ fence = line[:3]
2529
+ current.append(raw)
2530
+ continue
2531
+ if not line:
2532
+ if current:
2533
+ out.append(words("\n".join(current)))
2534
+ current = []
2535
+ continue
2536
+ current.append(raw)
2537
+ if current:
2538
+ out.append(words("\n".join(current)))
2539
+ return tuple(out)
2540
+
2541
+
2542
+ def _where_the_words_are(body: str) -> str:
2543
+ """The per-paragraph counts, as the clause a refusal ends with (RK311).
2544
+
2545
+ Named for what it answers rather than for what it formats: the author has been told a cut
2546
+ is needed and this is the sentence that says where one is available. Silent on a
2547
+ single-paragraph body — "¶1 335" restates the total the same message already gave, and a
2548
+ refusal that repeats itself is one an author stops reading.
2549
+ """
2550
+ counted = paragraphs(body)
2551
+ if len(counted) < 2:
2552
+ return ""
2553
+ listed = ", ".join(f"¶{n} {count}" for n, count in enumerate(counted, 1))
2554
+ # The longest is named because it is the one the author is looking for, and a tie names
2555
+ # the first — the cut has to start somewhere and the file reads top down.
2556
+ fattest = counted.index(max(counted)) + 1
2557
+ return f"; by paragraph {listed} — ¶{fattest} is the longest"
2558
+
2559
+
2560
+ def words(body: str) -> int:
2561
+ """The words of **argument** in a body — the budget's unit, and never its whole text.
2562
+
2563
+ `len(body.split())` charged every cell of a Markdown table what a word of argument
2564
+ costs. Measured while adopting Claude Tray: its `III` is 269 words of which 230 are the
2565
+ measured-baseline table the file keeps *because it is data, not design*, and its `XVI.3`
2566
+ is 293 of which 72 are a timing table — both under 250 counting prose alone. The remedy
2567
+ the finding offered, "this is two sections, or a paragraph that belongs in the commit",
2568
+ is advice about prose and applied to neither: splitting a six-row measurement in half
2569
+ helps nobody, and the rows are the evidence the design rests on. That adoption ended by
2570
+ declaring `section = 300`, a number describing two tables rather than budgeting anybody's
2571
+ prose, which is the outcome L6 exists to prevent (RK136).
2572
+
2573
+ So three shapes are data and cost nothing: a **table** row, a **fenced** block with
2574
+ everything in it, and a **blockquote**, which is somebody else's words being cited. A
2575
+ list is not among them — a bullet is how an argument is written here, and exempting one
2576
+ would reopen the budget by reformatting. What the limit is for is an agent's attention
2577
+ on an argument, and a row of numbers is not asking for any.
2578
+ """
2579
+ total = 0
2580
+ fence: str | None = None
2581
+ for raw in body.splitlines():
2582
+ line = raw.lstrip()
2583
+ if fence is not None:
2584
+ fence = None if line.startswith(fence) else fence
2585
+ elif line.startswith(_FENCES):
2586
+ fence = line[:3]
2587
+ elif not (line.startswith(_DATA) or raw.startswith(" ")):
2588
+ total += len(raw.split())
2589
+ return total
2590
+
2591
+
2592
+ # -- validation --------------------------------------------------------------
2593
+
2594
+
2595
+ #: The violations that are an author holding no address, and that `anchors` answers (RK349).
2596
+ #: `ref.missing` is a line with no pointer and `anchor.format` a section written at one that
2597
+ #: is not an address at all; both leave the caller looking for the same free number, and both
2598
+ #: used to state a rule and name nothing that satisfies it.
2599
+ _UNANCHORED = ("ref.missing", "anchor.format")
2600
+
2601
+
2602
+ @dataclass(frozen=True, slots=True)
2603
+ class Namespaced:
2604
+ """A prose file's addresses moved into a namespace, with its own citations carried (RK1168).
2605
+
2606
+ Declaring `[refs]` re-addresses every heading in a file at once — 48 of them in the run this
2607
+ was measured on — and carried none of that file's own citations: seven dangled and twenty-one
2608
+ kept resolving, into the other file's section of the same address. The first half of this task
2609
+ made the second population a finding (`ref.crossed`); this is the transaction that stops
2610
+ creating it.
2611
+
2612
+ **Why it has to be one act.** At the moment the key is declared, every bare citation in that
2613
+ file *was* local by construction — they resolved to it before the namespace existed, which is
2614
+ what a namespace changes. A minute later the same citation is ambiguous, which is why the
2615
+ finding's remedy is `compose` and this one can be a rewrite: the transaction is what makes the
2616
+ answer knowable, and outside it nobody can say which section was meant.
2617
+
2618
+ An address and never a word of prose (L4): what changes is `§I.2` to `§S:I.2` inside a
2619
+ sentence nobody else touches — the same act `move` performs on the pointers at a section.
2620
+ """
2621
+
2622
+ role: str
2623
+ namespace: str
2624
+ #: The file, with the citations rewritten. Saved by the caller, so the config write and this
2625
+ #: one land together or not at all.
2626
+ document: Document
2627
+ #: What was re-addressed, as `(anchor, line)`, so the report names every one.
2628
+ carried: tuple[tuple[str, int], ...]
2629
+ #: The configuration as it will read, rendered from the file that is there — a targeted
2630
+ #: insertion and never a serialiser, for `bump_version`'s reason: the rest of somebody's
2631
+ #: `roadkeep.toml` has to come back byte-identical.
2632
+ config_text: str
2633
+
2634
+ def stated(self, config: Config, wrote: Sequence[Path]) -> str:
2635
+ """The key declared, and every citation carried into it (RK1168).
2636
+
2637
+ Beside :meth:`payload` since RK1170. The config's own path joins the staging line here
2638
+ and not in :attr:`config_text`'s write: it is the file this transaction's *other* half
2639
+ touched, and a commit that staged the prose and left the key is the half-declared state.
2640
+ """
2641
+ from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
2642
+
2643
+ where = config.relative(config.path(self.role))
2644
+ source = config.relative(config.source)
2645
+ rows = [f'{source} [refs] {self.role} = "{self.namespace}"']
2646
+ # Named and not counted: this is a rewrite inside somebody's prose, and a number alone
2647
+ # is the diff a reviewer has to reconstruct to see what moved.
2648
+ rows += [
2649
+ f" carried §{anchor} → §{self.namespace}:{anchor} ({where}:{line})"
2650
+ for anchor, line in self.carried
2651
+ ]
2652
+ if not self.carried:
2653
+ rows.append(f" carried nothing: {where} cites none of its own sections")
2654
+ rows += _staging_rows([where, source])
2655
+ return "\n".join(rows)
2656
+
2657
+ def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
2658
+ """The same answer as data, naming both files the transaction wrote."""
2659
+ from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
2660
+
2661
+ return {
2662
+ "role": self.role,
2663
+ "namespace": self.namespace,
2664
+ "file": config.relative(config.path(self.role)),
2665
+ "config": config.relative(config.source),
2666
+ "carried": [
2667
+ {"anchor": anchor, "line": line} for anchor, line in self.carried
2668
+ ],
2669
+ **_wrote_json(config, (*wrote, config.source)),
2670
+ }
2671
+
2672
+
2673
+ def namespaced(config: Config, role: str, prefix: str) -> Namespaced:
2674
+ """Declare `[refs] <role>` and carry that file's own citations into it (RK1168).
2675
+
2676
+ Refuses rather than guesses in the three states it cannot answer for: a role this project
2677
+ does not declare as prose, a namespace this project already gives that role — where every
2678
+ citation is already qualified and there is nothing to carry — and a *different* namespace,
2679
+ which is a re-addressing whose citations carry the old prefix and whose answer is a different
2680
+ transaction from this one.
2681
+ """
2682
+ if role not in PROSE_ROLES or not config.has(role):
2683
+ raise ValueError(
2684
+ f"{role} is not a prose file this project declares: `[refs]` names the namespace a "
2685
+ f"prose file's outline lives in, and the roles are {', '.join(sorted(PROSE_ROLES))}"
2686
+ )
2687
+ if not _NAMESPACE_RE.match(prefix):
2688
+ raise ValueError(
2689
+ f"'{prefix}' is not a namespace: one is the letters and digits before the colon of "
2690
+ f"an address like `S:I.2`, and a separator inside it would be a second address"
2691
+ )
2692
+ already = config.refs.get(role)
2693
+ if already == prefix:
2694
+ raise ValueError(
2695
+ f"{role} already lives in `{prefix}:`, so its citations are already qualified and "
2696
+ f"there is nothing to carry"
2697
+ )
2698
+ if already:
2699
+ raise ValueError(
2700
+ f"{role} already lives in `{already}:`, and moving it to `{prefix}:` re-addresses "
2701
+ f"citations that carry the old namespace — a different transaction from declaring one"
2702
+ )
2703
+ document = config.document(role)
2704
+ own = {section.anchor for section in anchored(document)}
2705
+ carried: list[tuple[str, int]] = []
2706
+ for cited in references(document):
2707
+ # The file's **own** addresses and no others, read as they stand *before* the key is
2708
+ # declared — which is the whole reason this is one transaction: right now a bare anchor
2709
+ # this file declares is unambiguously its own, and a citation of the other file's section
2710
+ # is already right and must not be moved into a namespace it has no section in.
2711
+ if cited.anchor not in own:
2712
+ continue
2713
+ at = cited.lineno - 1
2714
+ replaced = document.lines[at].replace(f"§{cited.anchor}", f"§{prefix}:{cited.anchor}")
2715
+ if replaced == document.lines[at]:
2716
+ continue
2717
+ carried.append((cited.anchor, cited.lineno))
2718
+ document = document.replace_line(at, replaced)
2719
+ return Namespaced(
2720
+ role=role,
2721
+ namespace=prefix,
2722
+ document=document,
2723
+ carried=tuple(carried),
2724
+ config_text=_with_namespace(config, role, prefix),
2725
+ )
2726
+
2727
+
2728
+ #: What a namespace may be: the letters and digits before the colon of an address (RK340). A
2729
+ #: separator inside one would make `S:I` two addresses rather than one.
2730
+ _NAMESPACE_RE = re.compile(r"^[A-Za-z0-9]+$")
2731
+
2732
+
2733
+ def _with_namespace(config: Config, role: str, prefix: str) -> str:
2734
+ """This project's `roadkeep.toml` with one key added, and every other byte as it was.
2735
+
2736
+ A targeted insertion and never a serialiser, which is `bump_version`'s rule about the two
2737
+ files that state a version: a `tomllib` round-trip is not one — it drops the comments a
2738
+ scaffolded config is mostly made of, and rewriting somebody's file to add a line is the
2739
+ destructive formatting L3 refuses one layer down.
2740
+ """
2741
+ if config.source is None:
2742
+ raise ValueError("this project declares no roadkeep.toml to add a namespace to")
2743
+ text = config.source.read_text(encoding="utf-8")
2744
+ row = f'{role} = "{prefix}"\n'
2745
+ if "\n[refs]\n" in text or text.startswith("[refs]\n"):
2746
+ at = text.index("[refs]\n") + len("[refs]\n")
2747
+ return text[:at] + row + text[at:]
2748
+ # A table of its own, at the end: a key appended under whatever table happens to be last
2749
+ # would belong to that table, which is the one way this write can be silently wrong.
2750
+ joined = "" if text.endswith("\n") else "\n"
2751
+ return f"{text}{joined}\n[refs]\n{row}"
2752
+
2753
+
2754
+ def naming_the_anchor(
2755
+ config: Config,
2756
+ block: str | None,
2757
+ error: SchemaError,
2758
+ *,
2759
+ namespace: str = "",
2760
+ anchor: str = "",
2761
+ ) -> SchemaError:
2762
+ """The same refusal, told which command answers it (RK312, widened by RK349).
2763
+
2764
+ This project's own standard applied to itself. `ref: every task points at its rationale
2765
+ section` states the rule and names nothing that satisfies it — and `--ref` is the one
2766
+ required field of the write path that is neither derived nor guessable, wrong *silently*
2767
+ if the number picked is one some heading already spent. `anchors` answers it exactly, and
2768
+ there was no way to learn that from the refusal; the two reads it replaced were a glob of
2769
+ the pointers per block and a grep of the prose file's headings, done four times by hand.
2770
+
2771
+ Here rather than in `authoring`, which is where RK312 wrote it, because the doors that
2772
+ reach it are on both sides of that import: `place` validates the line `add`, `defer` and
2773
+ `resume` each write, and :func:`add` below validates the anchor `section add` passes.
2774
+ One function, so a fifth door is a call and not a fifth copy of the sentence.
2775
+
2776
+ Every other violation rides through untouched, the error keeps its own class, and the
2777
+ sentence is **appended** rather than replaced: what the rule is has to survive, because
2778
+ a refusal that only says what to type teaches nobody why the field exists.
2779
+
2780
+ ``block`` is `None` where the anchor names no live task, and that is not the caller to
2781
+ stay silent for (RK360) — it is the one holding no address at all, since typing a task id
2782
+ is what produces a block to read. What changes is which address is offered, and that is
2783
+ :func:`_where_a_top_level_is`'s to decide from the anchor itself: a family the caller
2784
+ already typed gets its next child, and everything else gets the free top-level. Never a
2785
+ family derived from whichever one happened to be last, which is the guess the two-family
2786
+ branch below also refuses to make.
2787
+
2788
+ Silent where history cannot be searched, which is where the free address cannot be
2789
+ derived: naming a number this could not verify is the failure the whole read exists to
2790
+ prevent, and the command that can say so is still named.
2791
+ """
2792
+ named = tuple(one for one in error.violations if one.code in _UNANCHORED)
2793
+ if not named:
2794
+ return error
2795
+ clause, free = (
2796
+ _where_a_top_level_is(config, namespace, anchor)
2797
+ if block is None
2798
+ else _where_the_anchor_is(config, block)
2799
+ )
2800
+ refusal = type(error)(
2801
+ tuple(
2802
+ replace(one, message=f"{one.message}{clause}") if one in named else one
2803
+ for one in error.violations
2804
+ )
2805
+ )
2806
+ # The address as **data** on the refusal, for the surface that can turn it into a retry
2807
+ # (RK1149). On the exception and not in a slot somewhere: it is one refusal's fact, it
2808
+ # travels with the object that carries the refusal, and a reader that finds no attribute
2809
+ # gets today's behaviour rather than a stale answer about an earlier call.
2810
+ if free:
2811
+ refusal.offered = free
2812
+ return refusal
2813
+
2814
+
2815
+ def checked(config: Config, task: Task, *, schema: Schema | None = None) -> Task:
2816
+ """`schema.check`, with the anchor named — the seam a **rewrite** passes (RK379).
2817
+
2818
+ RK312 enriched the refusal an `add` raises and RK349 widened it to the other doors that
2819
+ *insert* a line, by putting the call in :func:`~roadkeep.authoring.place`. Every door that
2820
+ rewrites a line already on the file misses that seam entirely: `amend`, `restate`, `status`
2821
+ and `renumber` each validate the task they composed and none of them goes through `place`.
2822
+
2823
+ So the bare rule survived exactly where an adopting project meets it. `ref.missing` on an
2824
+ insertion is a field the author forgot; on a rewrite it is a line that was **imported
2825
+ without a pointer**, which is the whole population `amend` exists for — the author is
2826
+ correcting that line's `why`, is told a pointer is required, and is told nothing about
2827
+ which address is free. That is the same measured cost RK312 removed, on the door the
2828
+ correction path actually uses.
2829
+
2830
+ Not folded into `place`, which takes a :class:`~roadkeep.kernel.document.Document` and an optional
2831
+ config: these callers hold a :class:`Config` unconditionally, and a rewrite has no
2832
+ insertion to make. The enrichment stays :func:`naming_the_anchor`, so this is a call and
2833
+ still not a copy of the sentence.
2834
+
2835
+ ``schema`` is which grammar validates, and it is a parameter because `renumber` moves an
2836
+ id that may be the **ledger's**: a shipped entry is `as_ledger()`, which requires no
2837
+ pointer at all, and validating one against the roadmap's schema would refuse an entry for
2838
+ lacking a field its own file has no column for. The default is this project's roadmap
2839
+ schema, which is every other caller.
2840
+ """
2841
+ try:
2842
+ return (schema or config.schema).check(task)
2843
+ except SchemaError as error:
2844
+ raise naming_the_anchor(config, task.block, error) from None
2845
+
2846
+
2847
+ def _where_the_anchor_is(config: Config, block: str) -> tuple[str, str]:
2848
+ """The clause an unanchored refusal ends with, and the address it offers (RK1149).
2849
+
2850
+ A pair, because the sentence and the anchor are read by different surfaces: the clause is
2851
+ what a human reads and the anchor is what a **retry** needs, and until this the second only
2852
+ existed inside the first. `""` where none could be derived — the two cases this already
2853
+ refused to guess in — so a caller has nothing to substitute and says so by having nothing.
2854
+ """
2855
+ # Deferred for RK260's reason, and because git belongs on no successful write path.
2856
+ from roadkeep.history import ( # noqa: PLC0415
2857
+ HistoryUnavailable,
2858
+ anchors,
2859
+ families_of_block,
2860
+ next_child,
2861
+ )
2862
+ from roadkeep.provenance import invocation # noqa: PLC0415
2863
+
2864
+ spans = families_of_block(config, block)
2865
+ if len(spans) > 1:
2866
+ # A block that reopened under a fresh top-level. Two families is a real answer and the
2867
+ # tool must not pick between them (RK312), so the command that lists both is still the
2868
+ # whole of it — the one case here where the path forks on a judgement, and so the one
2869
+ # RK1198 leaves exactly as it was.
2870
+ return (
2871
+ f" — `{invocation()} anchors --block {block}` says which family this block's "
2872
+ f"prose lives under, and `anchors` alone names the free top-level"
2873
+ ), ""
2874
+ if not spans:
2875
+ # And none is a block whose prose has not started, which is not the same question
2876
+ # (RK1198): the two shared a sentence, and the sentence sent an author who was six
2877
+ # calls from a first write to a command that answers one of them.
2878
+ return _the_path_into(config, block)
2879
+ family = spans[0]
2880
+ try:
2881
+ free = next_child(anchors(config), family)
2882
+ except (HistoryUnavailable, OSError):
2883
+ return (
2884
+ f" — Block {block}'s prose is under §{family}, and "
2885
+ f"`{invocation()} anchors --family {family}` says which address is free"
2886
+ ), ""
2887
+ return (
2888
+ f" — Block {block}'s prose is under §{family}, where §{free} is free "
2889
+ f"(`{invocation()} anchors --block {block}` lists it)"
2890
+ ), free
2891
+
2892
+
2893
+ def _the_path_into(config: Config, block: str) -> tuple[str, str]:
2894
+ """Every verb between this refusal and the line that lands, with its arguments (RK1198).
2895
+
2896
+ Observed filing three tasks into a project whose `ref_scheme` is `outline`, into blocks
2897
+ whose every line had shipped. Each refusal was individually correct and named the next
2898
+ verb; together they were a staircase, and six calls stood between prose that was ready at
2899
+ call one and the first write. The information was there at the first refusal — it knew the
2900
+ block, whether a heading declared it, that its families were spent and what the next free
2901
+ top-level was, which is everything the remaining five calls established.
2902
+
2903
+ So reporting one step is right when a caller is one step from done and wrong when they are
2904
+ six, because a staircase discovered a stair at a time reads as a tool changing its mind.
2905
+ The refusal carries the path rather than a `--plan` flag doing it, for the reason the
2906
+ whole clause exists: this is the moment the author is actually in, and a flag is one more
2907
+ thing to have learnt first.
2908
+
2909
+ Filled in and not described: the block, the address and the ledger's own spelling are all
2910
+ derived here, so what is left in angle brackets is the title, which is editorial and L4's
2911
+ to leave alone. `""` for the address wherever the outline's numbering does not derive one
2912
+ — the same silence :func:`_where_a_top_level_is` keeps, since a path opening on a number
2913
+ this could not verify is worse than the command that reads it.
2914
+ """
2915
+ # Deferred for RK260's reason, and because git belongs on no successful write path.
2916
+ from roadkeep.authoring import prose_role # noqa: PLC0415
2917
+ from roadkeep.blocking import BLOCK_ROLES # noqa: PLC0415
2918
+ from roadkeep.history import ( # noqa: PLC0415
2919
+ HistoryUnavailable,
2920
+ anchors,
2921
+ next_child,
2922
+ next_family,
2923
+ )
2924
+ from roadkeep.provenance import invocation # noqa: PLC0415
2925
+
2926
+ role = prose_role(config, on_disk=True)
2927
+ started = f" — Block {block}'s prose has not started"
2928
+ try:
2929
+ taken = () if role is None else anchors(config)
2930
+ except (HistoryUnavailable, OSError):
2931
+ taken = ()
2932
+ family = None if role is None else next_family(taken, config.schema_for(role).ref_prefix)
2933
+ if family is None:
2934
+ # An outline with no family at all, one whose top-levels are not one numbering, or a
2935
+ # history that cannot be read: all three are numbers this could not verify, and a path
2936
+ # opening on a guessed address is worse than the command that reads the real one
2937
+ # (RK340, RK293).
2938
+ return (
2939
+ f"{started}, and `{invocation()} anchors` names the free top-level it opens at"
2940
+ ), ""
2941
+ # The task's design is a **child** of that family, through
2942
+ # :func:`~roadkeep.history.next_child` rather than spelled here, so the one writer of a
2943
+ # child address stays the one writer of it.
2944
+ free = next_child(taken, family)
2945
+ steps = [
2946
+ # The family first, and it is the stair nobody sees coming: `section add <free>`
2947
+ # refuses with nothing to extend, and so does an `add --section` naming the same
2948
+ # address, because an anchor states its own place and a fresh top-level has no prose
2949
+ # yet. A free family exists nowhere by construction, so this step is unconditional.
2950
+ f'section add {family} --title "<its title>"',
2951
+ f"add --block {block} --ref {free} …",
2952
+ # Named although the `add` above prints it on success: the whole point is that the
2953
+ # path is legible at call one, and a last step that only appears once the fourth call
2954
+ # lands is the staircase again with one stair left on it.
2955
+ f"section add {free} --title …",
2956
+ ]
2957
+ if any(
2958
+ not config.document(one).declaring(block)
2959
+ for one in BLOCK_ROLES
2960
+ if config.has(one) and config.path(one).is_file()
2961
+ ):
2962
+ # Ahead of them all, because it is the refusal the retry walks into next: a label no
2963
+ # heading declares is `add`'s own second door, one call further down the stairs.
2964
+ steps.insert(0, f'block add {block} --title "<its title>"')
2965
+ return (
2966
+ f"{started} and §{family} is its free top-level, so filing here is "
2967
+ + ", then ".join(f"`{invocation()} {one}`" for one in steps)
2968
+ ), free
2969
+
2970
+
2971
+ def _where_a_top_level_is(config: Config, namespace: str, anchor: str = "") -> tuple[str, str]:
2972
+ """The same clause for an anchor belonging to nobody: a free address, or the command.
2973
+
2974
+ A pair for :func:`_where_the_anchor_is`' reason (RK1149): the second half is the address a
2975
+ retry substitutes, and `""` wherever this declines to name one.
2976
+
2977
+ **Which** free address is decided by what the caller typed (RK363). A malformed anchor
2978
+ whose leading segment is a family that exists is a typo inside that family — `XVII-1`
2979
+ is a hyphen where a dot belongs — and answering it with a new top-level says *start a
2980
+ new subtree*, which is the one thing that author was not doing. So the segment is read
2981
+ and, where it names a live family, that family's next child is the answer.
2982
+
2983
+ That is not the guess RK360 refused to make. Deriving a family from whichever one
2984
+ happened to be last is context this cannot verify; reading the front of the address the
2985
+ caller wrote down is the same read :func:`split_ref` already makes, and it answers
2986
+ nothing where the segment names no family.
2987
+
2988
+ The top-level is what remains, per namespace, for :func:`~roadkeep.history.next_family`'s
2989
+ reason (RK340): two prose files each numbering themselves from `I` have two free
2990
+ top-levels, and the taller file's number is not an answer about the shorter one.
2991
+ """
2992
+ # Deferred for RK260's reason, and because git belongs on no successful write path.
2993
+ from roadkeep.history import ( # noqa: PLC0415
2994
+ HistoryUnavailable,
2995
+ anchors,
2996
+ next_child,
2997
+ next_family,
2998
+ )
2999
+ from roadkeep.provenance import invocation # noqa: PLC0415
3000
+
3001
+ try:
3002
+ taken = anchors(config)
3003
+ except (HistoryUnavailable, OSError):
3004
+ return f" — `{invocation()} anchors` names the addresses this outline has taken", ""
3005
+ family = _family_typed(taken, namespace, anchor)
3006
+ if family is not None:
3007
+ child = next_child(taken, family)
3008
+ return (
3009
+ f" — §{family} is a family that exists, where §{child} is "
3010
+ f"free (`{invocation()} anchors --family {family}` lists it)"
3011
+ ), child
3012
+ free = next_family(taken, namespace)
3013
+ if free is None:
3014
+ # None is the honest answer where the top-levels are not one numbering, and a guess
3015
+ # printed beside a rule reads exactly like a fact.
3016
+ return f" — `{invocation()} anchors` names the addresses this outline has taken", ""
3017
+ return (
3018
+ f" — a section belonging to no task takes a top-level, and §{free} is free "
3019
+ f"(`{invocation()} anchors` lists what is taken)"
3020
+ ), free
3021
+
3022
+
3023
+ #: What counts as the segment a malformed address opens with: the letters and digits before
3024
+ #: whatever separator was typed wrong. `XVII-1` and `XVII 1` are one mistake (RK363).
3025
+ _LEADING = re.compile(r"[A-Za-z0-9]+")
3026
+
3027
+
3028
+ def _family_typed(taken: Sequence[Anchor], namespace: str, anchor: str) -> str | None:
3029
+ """The live family this malformed address opens with, spelled as its anchors spell it."""
3030
+ if not anchor:
3031
+ return None
3032
+ head = _LEADING.match(split_ref(anchor)[1])
3033
+ if head is None:
3034
+ return None
3035
+ for one in taken:
3036
+ space, bare = split_ref(one.anchor)
3037
+ if space == namespace and bare.split(".")[0] == head.group():
3038
+ return one.anchor.split(".")[0]
3039
+ return None
3040
+
3041
+
3042
+ def _outline_violation(schema: Schema, anchor: str) -> Violation | None:
3043
+ """What is wrong with this address under an outline — its namespace, or its shape.
3044
+
3045
+ Namespace first, because it is the question the other one cannot answer: `S:I` fails
3046
+ every reading of `<x.y>` and saying so would send an author to fix a spelling that is
3047
+ correct for the file they meant (RK340).
3048
+ """
3049
+ here = local(schema, anchor)
3050
+ if here is None:
3051
+ # An address in another role's namespace, written into this file: refused rather
3052
+ # than resolved, because the write was told which role it is for and the anchor
3053
+ # names a different one — and the heading drops the prefix, so the disagreement
3054
+ # would not survive in the file to be seen.
3055
+ return Violation(
3056
+ "anchor.namespace",
3057
+ "anchor",
3058
+ f"{anchor!r} is not an address in this file's namespace ("
3059
+ f"{schema.ref_prefix or 'none'}, per [refs]): a section written here is one "
3060
+ f"every pointer to that address resolves somewhere else",
3061
+ )
3062
+ if not OUTLINE_ANCHOR_RE.match(here):
3063
+ # Refused rather than written, because the heading would be read back by nothing:
3064
+ # under this scheme the number is what announces a section (RK44), so an anchor
3065
+ # that is not one is a section invisible from the moment it reaches the file.
3066
+ return Violation(
3067
+ "anchor.format",
3068
+ "anchor",
3069
+ f"not an <x.y> outline anchor: {anchor!r} — under ref_scheme = outline "
3070
+ f"the heading numbers itself, and a heading with no number is prose",
3071
+ )
3072
+ return None
3073
+
3074
+
3075
+ def addressable(schema: Schema, anchor: str) -> bool:
3076
+ """Whether this scheme could read the token as a section address at all (RK1025).
3077
+
3078
+ The public half of :func:`_address_violation`, for a reader that has an argument and no
3079
+ section: `show` refuses a token that is not a task id, and whether the token is one this
3080
+ file's outline *numbers* is what decides between "never written" and "you want the other
3081
+ verb". A predicate rather than the violation, because nothing here is being refused —
3082
+ the caller is deciding which sentence to print.
3083
+
3084
+ **Only decidable under an outline**, and it says so by answering `False` everywhere
3085
+ else: under the `id` scheme an anchor is an id, so every token this could be asked about
3086
+ is either already a task or nothing at all, and answering `True` would name a section
3087
+ verb for an argument that is simply a typo.
3088
+ """
3089
+ if schema.ref_scheme != "outline":
3090
+ return False
3091
+ return _address_violation(schema, anchor) is None
3092
+
3093
+
3094
+ def _address_violation(schema: Schema, anchor: str) -> Violation | None:
3095
+ """What is wrong with this address as an address, whichever scheme reads it (RK377).
3096
+
3097
+ The half of :func:`_check` a verb that writes no prose still has to make: `move` validates
3098
+ a destination and has no title and no body to be told about, and re-spelling two branches
3099
+ at that call site is the second reader of a rule this module keeps one of.
3100
+ """
3101
+ if not anchor or anchor.startswith("§"):
3102
+ return Violation("anchor.sigil", "anchor", f"store the anchor without §: {anchor!r}")
3103
+ if schema.ref_scheme == "outline":
3104
+ return _outline_violation(schema, anchor)
3105
+ return None
3106
+
3107
+
3108
+ def _inherited(body: str, standing: int | None) -> bool:
3109
+ """Whether this overrun was already in the file before the call (RK1263).
3110
+
3111
+ ``standing`` is what the prose spent before the edit, and `None` is every caller that
3112
+ composed the whole body — there the overrun is theirs by construction. Where it is a
3113
+ number, an edit that leaves the count where it was or below it is one the file's standing
3114
+ debt refuses, not the caller: `lint` still reports the section, and the finding is about
3115
+ the paragraph rather than about the four characters somebody corrected inside it.
3116
+
3117
+ Not *equal* and not a tolerance: the comparison is `<=`, so shortening an over-long section
3118
+ towards the limit is always allowed and growing it never is.
3119
+ """
3120
+ return standing is not None and words(body) <= standing
3121
+
3122
+
3123
+ def _check(
3124
+ schema: Schema,
3125
+ anchor: str,
3126
+ title: str,
3127
+ body: str,
3128
+ task: Task | None,
3129
+ *,
3130
+ elsewhere: Whereabouts | None = None,
3131
+ known: frozenset[str] | None = None,
3132
+ resolves: frozenset[str] | None = None,
3133
+ standing: int | None = None,
3134
+ ) -> None:
3135
+ """Every rule a section is refused by, under **this file's** schema (RK147).
3136
+
3137
+ ``elsewhere`` is where an id no live role holds actually is, threaded in rather than read
3138
+ here (RK238): this function takes a schema and not a project, which is what keeps it the
3139
+ one place the *rules* live — and the door an unknown anchor should be handed is a fact
3140
+ about the caller's files. `None` is the caller saying there is nothing to say, which
3141
+ `_elsewhere` decides.
3142
+
3143
+ The schema is the one the caller loaded the document under — `config.schema_for(role)`,
3144
+ which is what `[limits.improvements]` declares (RK50) — and never `config.schema`, which
3145
+ is the project's top-level numbers. L1 is the first law: the format is enforced where
3146
+ the text is created, and reading a different limit here than the gate charges is exactly
3147
+ the failure it names. A project declaring a *tighter* rationale budget got it only after
3148
+ the paragraph existed; one declaring a *looser* one had this door refusing prose the gate
3149
+ would accept, which is worse — a refusal on legal text is a refusal an author routes
3150
+ around. Threaded rather than looked up again, so the two readings cannot disagree.
3151
+
3152
+ The **binding** is not refused here and is not checked here at all: :func:`_bound` has
3153
+ already rendered it (RK262), so by the time a title reaches this function it names the
3154
+ task the anchor names, and a violation for the state that cannot arrive is a rule nobody
3155
+ can trip.
3156
+ """
3157
+ out: list[Violation] = []
3158
+ if (bad := _address_violation(schema, anchor)) is not None:
3159
+ out.append(bad)
3160
+ elif schema.id_pattern().match(anchor) and task is None:
3161
+ # The pointer is the id (RK27), so an id-shaped anchor that names no live task is
3162
+ # a section nothing can ever point at — an orphan the moment it is written. *Live*
3163
+ # and not open (RK231): a paused line keeps its id and its pointer, so its design is
3164
+ # amendable, and the word here is the one `_task_for` reads.
3165
+ out.append(Violation("anchor.unknown", "anchor", _unknown(anchor, elsewhere)))
3166
+ if not title.strip():
3167
+ out.append(Violation("title.empty", "title", "a section is named by its heading"))
3168
+ elif "\n" in title or "\r" in title:
3169
+ out.append(Violation("title.newline", "title", "a heading is one line"))
3170
+ elif title.lstrip().startswith("#"):
3171
+ out.append(
3172
+ Violation("title.markup", "title", "the level is a field, not part of the text")
3173
+ )
3174
+ elif title.strip() == anchor or title.strip() == f"§{anchor}":
3175
+ # The address stated twice with no words in it (RK1329). Measured across one session:
3176
+ # nine sections filed and nine titled with their own anchor, every one by a caller who
3177
+ # had just been thinking in ids and read a bare positional beside `--block` as one.
3178
+ # Nothing refused it, any string being a legal heading, and `show` and `brief` then
3179
+ # print `§RK1320 RK1320` where the title is the line saying what the design argues.
3180
+ #
3181
+ # Knowable at the door, which is where this format puts a limit: the write mints the
3182
+ # id and is handed the title in the same call, so the comparison is free. Not a rule
3183
+ # about the id scheme — under an outline the anchor is passed explicitly and a title
3184
+ # equal to it is the same degenerate heading, so this is checked against whichever
3185
+ # address the caller is writing under.
3186
+ out.append(
3187
+ Violation(
3188
+ "title.is-anchor",
3189
+ "title",
3190
+ f"the heading would read `§{anchor} {title.strip()}`: the anchor is already "
3191
+ f"the address, so this argument is the sentence the design argues",
3192
+ )
3193
+ )
3194
+ out += promised(schema, body, known)
3195
+ # The one thing prose can be wrong about mechanically, asked where the text is created
3196
+ # (RK1227, L1). Found in Shio filing SH763: its rationale cited `§XVII.100`, an anchor a
3197
+ # task had removed when it shipped, and this write took it without complaint — surfacing
3198
+ # two commits later as a **red gate in that project**, on a docs-only commit that had
3199
+ # touched nothing else. Length was checked and paragraph shape was checked; whether the
3200
+ # address resolves was not asked, though the file was open and the answer is a lookup.
3201
+ #
3202
+ # Threaded like `known` and never resolved here (RK238): this function takes a schema and
3203
+ # not a project, which is what keeps it the one place the *rules* live — and which
3204
+ # addresses exist is a fact about the caller's files. `None` is a caller with nothing to
3205
+ # say, which is every call that cannot open them.
3206
+ if resolves is not None:
3207
+ dangling = [one for one in cited_in(body) if one not in resolves]
3208
+ if dangling:
3209
+ out.append(
3210
+ Violation(
3211
+ "ref.dangling",
3212
+ "body",
3213
+ f"cites {', '.join('§' + one for one in dangling)}, which no prose file "
3214
+ f"declares: a citation of an address a ship removed reads as an argument "
3215
+ f"the reader can follow, and the gate finds it in somebody else's commit",
3216
+ )
3217
+ )
3218
+ if not body.strip():
3219
+ out.append(Violation("body.empty", "body", "a section with no prose is a heading"))
3220
+ elif words(body) > schema.section_max and not _inherited(body, standing):
3221
+ out.append(
3222
+ Violation(
3223
+ "body.too-long",
3224
+ "body",
3225
+ f"{over_by(words(body), schema.section_max, unit='word')}; a section "
3226
+ f"this long is two sections, or a paragraph that belongs in the commit"
3227
+ # Where the words are, on the refusal that discards them (RK311): the
3228
+ # overage says a cut is needed, and this says where one is available, so
3229
+ # the second draft is composed once instead of counted by hand.
3230
+ f"{_where_the_words_are(body)}",
3231
+ )
3232
+ )
3233
+ if out:
3234
+ raise SectionError(tuple(out))
3235
+
3236
+
3237
+ def binding(config: Config, role: str, anchor: str) -> tuple[int, int] | None:
3238
+ """What this address charges anything written **under** it, and against what limit.
3239
+
3240
+ `(words, limit)`, or `None` where nothing written under this anchor is charged to it —
3241
+ which is two states and not one: the address names no section, or it names a container
3242
+ nothing points at. A pointer hands a reader the whole subtree, so a *pointed-at* section
3243
+ is billed with its children and therefore binds them; a container is billed its own
3244
+ prose, and charging its children to it would price a body against a heading the gate does
3245
+ not bill (RK215). Both readers of this — `anchors` offering a child address (RK1024), and
3246
+ `budget` pricing one (RK1029) — want exactly the second question, and asking it here is
3247
+ what keeps them from deriving two answers to it.
3248
+
3249
+ A read, so it decides nothing: `anchors` states the number and still prints the address,
3250
+ because an author about to shorten the parent is holding a plan no count can see.
3251
+ """
3252
+ if not config.has(role) or not _pointed_at(config, anchor):
3253
+ return None
3254
+ section = find(config.document(role), anchor)
3255
+ if section is None:
3256
+ return None
3257
+ return section.words, config.schema_for(role).section_max
3258
+
3259
+
3260
+ def known(config: Config, anchor: str, task: Task | None) -> frozenset[str]:
3261
+ """The ids a design may name: every one some file carries, plus this task's own.
3262
+
3263
+ The task's own is added because `add --section` writes the line and the prose in one
3264
+ transaction and the prose is checked first — so at this moment the id it explains is not
3265
+ yet carried by anything, and refusing a design for naming the task it is the design of
3266
+ would be the refusal reading the transaction backwards.
3267
+ """
3268
+ # Deferred: `ids` reads the documents this module writes into (RK260).
3269
+ from roadkeep.ids import carried # noqa: PLC0415 - RK1002
3270
+
3271
+ own = {anchor} if task is None else {task.id, anchor}
3272
+ return carried(config) | frozenset(own)
3273
+
3274
+
3275
+ def resolvable(config: Config, anchor: str) -> frozenset[str]:
3276
+ """Every anchor a body may cite: those the prose files declare, plus the one being written.
3277
+
3278
+ Across **every** prose role and never one document's (RK1227, following RK1106's reading):
3279
+ a citation of `§S:I.2` from the improvements file is a reference into the strategy file,
3280
+ and asking one document would refuse the correct half of a project's prose.
3281
+
3282
+ The anchor being written is included for :func:`known`'s reason one field over: `section
3283
+ add` is checked before it writes, so a design citing the address it *is* would be refused
3284
+ by the transaction reading itself backwards.
3285
+ """
3286
+ out = {anchor}
3287
+ for role in PROSE_ROLES:
3288
+ if not config.has(role) or not config.path(role).is_file():
3289
+ continue
3290
+ out.update(one.anchor for one in anchored(config.document(role)))
3291
+ return frozenset(out)
3292
+
3293
+
3294
+ def promised(schema: Schema, body: str, known: frozenset[str] | None) -> list[Violation]:
3295
+ """An id-shaped token in a design that no line carries (RK1002).
3296
+
3297
+ RK431 made deriving an id read prose, and that is right: a ledger entry promising *filed
3298
+ as RK499* before the line exists has to reserve the number, or two things carry one id.
3299
+ What deriving cannot do is tell a promise from an illustration — deciding would take the
3300
+ model L4 forbids — so it warns, hedged, in another command's output, two sessions later.
3301
+
3302
+ This is where the same rule is enforceable without judgement. **A design does not promise
3303
+ an id**: it explains a task that already has one, so an id-shaped token in a rationale
3304
+ body either names a line this backlog carries or it is an example, and an example that is
3305
+ spelled in this project's own prefix spends an address. §RK498 was composed with `add
3306
+ --dep RK999` in it, `section add` said nothing, and the next task filed was RK1000.
3307
+
3308
+ The ledger is deliberately not held to this — that is where RK431's promise is legitimate,
3309
+ and refusing it there would refuse the one sentence the mechanism exists for.
3310
+
3311
+ ``known`` is the ids some file carries as a line, plus the one this transaction is about
3312
+ to write. ``None`` means the caller had no project to ask, and the check is skipped rather
3313
+ than guessed at.
3314
+ """
3315
+ if known is None:
3316
+ return []
3317
+ # Deferred beside :func:`known`, and the same one-way edge (RK260).
3318
+ from roadkeep.ids import id_scanner # noqa: PLC0415 - RK1002
3319
+
3320
+ scanner = id_scanner(schema)
3321
+ loose = [
3322
+ match for match in scanner.finditer(body) if match.group(0) not in known
3323
+ ]
3324
+ if not loose:
3325
+ return []
3326
+ named = ", ".join(dict.fromkeys(match.group(0) for match in loose))
3327
+ ceiling = _highest_carried(scanner, known)
3328
+ ahead = [
3329
+ match
3330
+ for match in loose
3331
+ if 0
3332
+ < int(match.group("number")) - ceiling.get(match.group("family"), 0)
3333
+ <= _IN_FLIGHT
3334
+ ]
3335
+ return [
3336
+ Violation(
3337
+ "body.promise",
3338
+ "body",
3339
+ f"names {named}, which no line carries: an id in this project's own prefix is "
3340
+ f"read as spent, so the next `add` derives past it (RK431) — "
3341
+ + (
3342
+ # The case both old remedies missed (RK1027). An id past everything a line
3343
+ # carries is not a typo and not a retirement: it is work in flight, and the
3344
+ # caller is authoring two tasks that cite each other in the only order a
3345
+ # shell allows. Told first, because the other two ask them to rename or
3346
+ # delete a cross-reference the backlog wanted.
3347
+ f"{named} is past every id a line carries, so file that task first and "
3348
+ f"write this section after — or spell the example outside "
3349
+ f"{'/'.join(schema.prefixes)}"
3350
+ if len(ahead) == len(loose)
3351
+ else f"spell the example outside {'/'.join(schema.prefixes)}, name the id "
3352
+ f"actually meant, or read `gaps` for where it went"
3353
+ ),
3354
+ )
3355
+ ]
3356
+
3357
+
3358
+ #: How far past the highest id a line carries a token may sit and still read as work in
3359
+ #: flight (RK1027). Three zones, not two: below the maximum a missing id is a hole `gaps`
3360
+ #: answers; **just** past it is the sibling being authored alongside this one; far past it
3361
+ #: is an illustration, which is the case RK1002 was filed for — §RK498 named `RK999` against
3362
+ #: a backlog whose next id was RK1000, and calling that a forward reference would take the
3363
+ #: refusal RK1002 bought and blunt it.
3364
+ #:
3365
+ #: Not configuration (L6), and the same argument `ranking.NEAREST` makes: a project declares
3366
+ #: how long its lines may be, and this is a property of how a sitting authors — measured on
3367
+ #: this repository's own two batches of cross-citing tasks, which spanned three ids each.
3368
+ _IN_FLIGHT = 8
3369
+
3370
+
3371
+ def _highest_carried(
3372
+ scanner: re.Pattern[str], known: frozenset[str]
3373
+ ) -> dict[str, int]:
3374
+ """The largest number each family holds as a line, read off ``known`` (RK1027).
3375
+
3376
+ The discriminator between a forward reference and a mistake, and it needs no second view
3377
+ of the surface: `known` is already every id some file carries, and the same scanner that
3378
+ found the loose token names the family and the number of each one. A maximum and not
3379
+ `next_id`: this function takes no project, which is what keeps `promised` the one place
3380
+ the *rule* lives — and `next_id` derives past everything a line carries, so the two
3381
+ disagree only about ids that are ahead either way.
3382
+ """
3383
+ ceiling: dict[str, int] = {}
3384
+ for one in known:
3385
+ match = scanner.fullmatch(one)
3386
+ if match is None:
3387
+ continue
3388
+ family = match.group("family")
3389
+ ceiling[family] = max(ceiling.get(family, 0), int(match.group("number")))
3390
+ return ceiling
3391
+
3392
+
3393
+ def violations(
3394
+ schema: Schema,
3395
+ anchor: str,
3396
+ title: str,
3397
+ body: str,
3398
+ task: Task | None = None,
3399
+ *,
3400
+ elsewhere: Whereabouts | None = None,
3401
+ known: frozenset[str] | None = None,
3402
+ ) -> tuple[Violation, ...]:
3403
+ """The same rules, collected rather than raised (RK426).
3404
+
3405
+ `add --section` refuses the line and the section in two passes, so a call whose `why` is
3406
+ fifteen characters over and whose body is fifty words over costs **two** full
3407
+ resubmissions — the second for a limit the first refusal already knew was breached. That
3408
+ is the cost `--section-body-file` exists to avoid, charged for a field the tool had not
3409
+ looked at, and re-passing the prose is the expensive half.
3410
+
3411
+ So the caller that holds both sets asks for them and raises once. This is the collector
3412
+ and :func:`_check` is the raiser above it, rather than the reverse, because every other
3413
+ caller wants the refusal at the point of the check — a function that returned violations
3414
+ to twelve call sites would put the raise in twelve places, which is the shape L1 exists
3415
+ to avoid one layer up.
3416
+ """
3417
+ try:
3418
+ _check(schema, anchor, title, body, task, elsewhere=elsewhere, known=known)
3419
+ except SectionError as error:
3420
+ return tuple(error.violations)
3421
+ return ()
3422
+
3423
+
3424
+ def _bound(schema: Schema, anchor: str, title: str, task: Task | None) -> str:
3425
+ """The heading text with the task named in it, which is what makes it that task's (RK262).
3426
+
3427
+ Under an outline the anchor is an address and the **id in the heading is the binding** —
3428
+ `§XVI.12 A design (SH123)` — so `add --section "A design"` wrote a section belonging to
3429
+ nobody, and every reader afterwards was correct and useless: `ship` reported it *kept*,
3430
+ as prose belonging to none; `lint` declined to call it orphaned on exactly that reading;
3431
+ and the rationale for shipped work stayed in the prose file, which is what RK6 exists to
3432
+ prevent. The recovery was a `section amend --title "<title> (<id>)"` the author had to
3433
+ derive from a field named `kept`.
3434
+
3435
+ **Rendered and not refused**, which is the door the design listed first and the only one
3436
+ `add --section` can take: that command *derives* the id, so an author composing the title
3437
+ does not yet know what to type, and refusing would be the tool telling them the answer and
3438
+ asking them to send it back. Nor is it prose (L4) — the id is the pointer's other end, and
3439
+ rendering a binding into the text that carries it is what `Schema.render` does one file
3440
+ over with `→ §<anchor>`.
3441
+
3442
+ Whose it is, is :func:`owners` and never a second reading of it: that function already
3443
+ answers the question for the gate and for the drop, and a writer that agreed with neither
3444
+ is how a heading passes the door and fails the departure. A throwaway :class:`Section`
3445
+ because that is what it takes — every field but the two it reads is a placeholder. Under
3446
+ `ref_scheme = "id"` the anchor satisfies it, so nothing is ever appended there: no branch
3447
+ on the scheme, because the exemption *is* the reading.
3448
+ """
3449
+ if task is None or not title.strip():
3450
+ # An empty title stays empty: appending the id would render `§X.1 (CT1)`, a heading
3451
+ # that names its task and nothing else, and would take `title.empty` — the refusal
3452
+ # that is the whole reason nothing composes a heading out of a blank field — with it.
3453
+ return title.strip()
3454
+ probe = Section(anchor=anchor, title=title.strip(), level=0, first=0, last=0)
3455
+ if task.id in owners(probe, schema.id_pattern()):
3456
+ return title.strip()
3457
+ return f"{title.strip()} ({task.id})"
3458
+
3459
+
3460
+ def _unknown(anchor: str, elsewhere: Whereabouts | None) -> str:
3461
+ """The refusal for an id no live line names, carrying a door the author can take (RK238).
3462
+
3463
+ `add the line first` is the remedy for the one state it fits — an id that never existed.
3464
+ For an id the ledger holds it is the single door RK4 closes: `refuse_reuse` reads every
3465
+ governed file, so the `add` this advises is `IdInUse`, and retired-never-reused is the rule
3466
+ saying so. A finding whose named remedy the tool refuses is worse than one with no remedy,
3467
+ because the author spends the attempt before learning that (RK16).
3468
+
3469
+ So the state is named the way :class:`~roadkeep.deferring.NotSetAside` names it — where the
3470
+ id *is* — and the two doors that do open are the ones offered: `record amend` for the entry
3471
+ sentence, which is what actually needs correcting when a shipped design reads wrong, and an
3472
+ outline anchor for prose belonging to no task, which this message already offered.
3473
+
3474
+ The door is chosen from :class:`~roadkeep.backlog.Where` and not from whether a sentence
3475
+ is empty (RK240): `record amend` is the remedy for an id the **ledger** holds, and a
3476
+ branch that infers that from the truthiness of prose is a branch reading prose.
3477
+ """
3478
+ if elsewhere is not None and elsewhere.recorded:
3479
+ return (
3480
+ f"no live task {anchor} points at this section: {elsewhere.sentence}, so its "
3481
+ f"design ended at the departure — correct that entry with `record amend`, or use "
3482
+ f"an outline anchor for prose that belongs to no task"
3483
+ )
3484
+ return (
3485
+ f"no live task {anchor} points at this section: add the line first, or "
3486
+ f"use an outline anchor for prose that belongs to no task"
3487
+ )
3488
+
3489
+
3490
+ def _elsewhere(config: Config, schema: Schema, anchor: str, task: Task | None) -> Whereabouts | None:
3491
+ """Where the id is, read only where the refusal can use the answer (RK240).
3492
+
3493
+ `None` is "nothing to say", and it covers two cases rather than one: a live line already
3494
+ owns this anchor, or the anchor is not an id at all. An outline anchor named a section
3495
+ and never a task, so reading a ledger for it is a parse spent on a question `_unknown`
3496
+ will not ask — the one this used to make before the shape was checked.
3497
+ """
3498
+ if task is not None or not schema.id_pattern().match(anchor):
3499
+ return None
3500
+ return Whereabouts.of(config, anchor)
3501
+
3502
+
3503
+ def _pointed_at(config: Config, anchor: str) -> bool:
3504
+ """Does a live task line point at this anchor — the gate's own question (RK215).
3505
+
3506
+ What decides which of the two numbers a section is charged. A pointer hands a reader the
3507
+ whole subtree, so a *pointed-at* section is measured with it; a container nothing points
3508
+ at is measured on its own prose, because counting its children against it would measure
3509
+ the file's shape rather than anybody's paragraph. That is `lint`'s rule, and this asks it
3510
+ the same way so the writer and the gate cannot disagree — the disagreement being the
3511
+ defect, not the limit.
3512
+
3513
+ Both live roles, as the gate reads them: a deferred line keeps its pointer and its
3514
+ section (RK96), so work set aside still claims its rationale. The ledger is not among
3515
+ them — a departure deletes the section in the transaction that writes the entry.
3516
+
3517
+ And **only where one prose role declares the anchor** (RK232), which is the last condition
3518
+ RK215's agreement was missing. An anchor two files declare is charged as pointed at by
3519
+ nobody, because which of the two a line meant is what `ref.ambiguous` asks the author and
3520
+ billing one of them the other's subtree is the silent half of that defect. Counted before
3521
+ it was written: Turing at `f08304fcb1` declares 13 such anchors, one of them — `X.1`,
3522
+ pointed at by T354 — where the gate charges 73 words and this charged 365, so a correction
3523
+ to the intro was refused for 292 words of somebody else's subsections while the gate
3524
+ called that check clean. RK215's finding exactly, in the state RK215 did not reach.
3525
+ """
3526
+ if len(declaring(config, anchor)) != 1:
3527
+ return False
3528
+ return any(
3529
+ entry.task.ref == anchor
3530
+ for document in _live(config)
3531
+ for entry in document.entries
3532
+ )
3533
+
3534
+
3535
+ def _task_for(config: Config, anchor: str, role: str = "") -> Task | None:
3536
+ """The live task this anchor names, if it names one at all.
3537
+
3538
+ ``role`` is the prose file the section is being written into, and it decides **which**
3539
+ file the owner is looked for in (RK1361). The decisions role is the one that carries both
3540
+ records and prose, so a record there owns a section *in that file* and nowhere else: were
3541
+ the search unconditional, a shipped task with a decision filed under its id would become
3542
+ an id `section add --role improvements` accepts, which is the design a ship deleted coming
3543
+ back under the number that deleted it. Empty is every other caller, and unchanged.
3544
+
3545
+ Both live roles, for the reason `_pointed_at` reads both (RK231) — and this is the half
3546
+ that *refuses*. Reading the roadmap alone, `section amend RK1` on a paused line answered
3547
+ `anchor.unknown`: "no open task RK1 points at this section: add the line first", about a
3548
+ line that exists, in the file `resume` restores from. That closed the last door on a
3549
+ state the tool creates on purpose, RK123's deadlock displaced — `drop` refused while the
3550
+ store's pointer claimed the anchor, `amend` refused because it read a different file than
3551
+ the pointer lived in, and the guard denied the `Edit`.
3552
+
3553
+ Which leaves `anchor.unknown` with nothing to distinguish: a paused task is found here,
3554
+ so the refusal only ever fires for an anchor no live line names. An id the *ledger* holds
3555
+ is one of those, and rightly — a departure deletes the design, so there is no section to
3556
+ amend and no line to add back (RK4).
3557
+
3558
+ **Under an outline the pointer is the answer** (RK262), and until this read it there was
3559
+ none: the anchor is an address, so the id test above matched nothing and every outline
3560
+ section looked ownerless to every caller here — which is why `section add` and `amend`
3561
+ could compose a heading naming no task while `add --section`, the one caller that passes
3562
+ its own, could not. The scan is `_pointed_at`'s and the rule is RK64's: **exactly one**
3563
+ live line, because four of Shio's point at one epic design, and picking one of four would
3564
+ be this function answering a question the format leaves open. Nothing refuses on the None
3565
+ that returns — an outline anchor never reaches `anchor.unknown` — so the cost of the
3566
+ ambiguous case is a heading the author binds by hand, which is where it started.
3567
+ """
3568
+ owning = _owning(config, role)
3569
+ if config.schema.id_pattern().match(anchor):
3570
+ for document in owning:
3571
+ entry = document.by_id().get(anchor)
3572
+ if entry is not None:
3573
+ return entry.task
3574
+ return None
3575
+ owners_here = [
3576
+ entry.task
3577
+ for document in owning
3578
+ for entry in document.entries
3579
+ if entry.task.ref == anchor
3580
+ ]
3581
+ return owners_here[0] if len(owners_here) == 1 else None
3582
+
3583
+
3584
+ def _owning(config: Config, role: str = "") -> list[Document]:
3585
+ """The files a record owning a section in ``role`` is live in (RK1361).
3586
+
3587
+ Every entry the decisions file holds owns its body, superseded ones included: that is the
3588
+ one departure this role has, and it keeps both entries because the record of what a
3589
+ replacement was needed against is the body of the decision it replaced. So the whole
3590
+ document answers, and there is no marker to filter on.
3591
+
3592
+ Asked *of the destination*, which is what keeps the two doors apart: a decision's body
3593
+ lives in the decisions file, and the design a `ship` deleted stays deleted.
3594
+ """
3595
+ if role == "decisions":
3596
+ if config.has(role) and config.path(role).is_file():
3597
+ return [config.document(role)]
3598
+ return []
3599
+ return list(_live(config))
3600
+
3601
+
3602
+ def _live(config: Config) -> Iterator[Document]:
3603
+ """The files a task line is live in, in the order a reader should trust them.
3604
+
3605
+ One place, because the two questions above are the same question about one set of files:
3606
+ a pointer that claims a section and a task that owns one are both facts a ⏸ line still
3607
+ carries (RK96). The changelog is deliberately absent from both.
3608
+ """
3609
+ for role in ("roadmap", "deferred"):
3610
+ if config.has(role) and config.path(role).is_file():
3611
+ yield config.document(role)
3612
+
3613
+
3614
+ # -- rendering and placement -------------------------------------------------
3615
+
3616
+
3617
+ def _render(
3618
+ schema: Schema, anchor: str, title: str, body: str, level: int
3619
+ ) -> tuple[str, ...]:
3620
+ heading = f"{'#' * level} {anchor_text(schema, anchor)} {title.strip()}"
3621
+ return (heading, "", *_body_lines(schema, body))
3622
+
3623
+
3624
+ def _inserted(document: Document, index: int, lines: Sequence[str]) -> Document:
3625
+ """Put these lines at ``index``, separated from what is already there.
3626
+
3627
+ Factored out for the second writer (RK1258): a family opened in the same transaction is
3628
+ placed exactly as the design under it is, and two copies of the blank-line rule is how one
3629
+ of them comes to write a heading flush against the paragraph above it.
3630
+ """
3631
+ payload = list(lines)
3632
+ if index > 0 and not blank(document.lines[index - 1]):
3633
+ payload.insert(0, "")
3634
+ if index < len(document.lines):
3635
+ payload.append("")
3636
+ for offset, raw in enumerate(payload):
3637
+ document = document.insert_line(index + offset, raw)
3638
+ return document
3639
+
3640
+
3641
+ def _opening(
3642
+ config: Config, role: str, document: Document, opens: tuple[str, str], where: str
3643
+ ) -> Document:
3644
+ """Declare the family this write's design extends, as a heading and nothing else (RK1258).
3645
+
3646
+ A container and not a section with prose, and the difference is the whole shape: what a
3647
+ reader wants under `## XXXI` is the tasks, and what the tool may not do is compose the
3648
+ paragraph that would otherwise have to sit there (L4). The title is the **block's own**,
3649
+ which is a string the author already wrote — read at the door and passed in, so this
3650
+ function derives no words either.
3651
+
3652
+ The address is asked the three questions every destination is asked, against the document
3653
+ this transaction holds: a family the file, a sibling or history already spent is a refusal
3654
+ here, before the child is placed inside it.
3655
+ """
3656
+ family, title = opens
3657
+ unspent(config, role, family, document=document, where=where)
3658
+ heading = (
3659
+ f"{'#' * _depth(document, family, None)} "
3660
+ f"{anchor_text(document.schema, family)} {title.strip()}"
3661
+ )
3662
+ return _inserted(document, _placement(document, family, None, where, role), (heading,))
3663
+
3664
+
3665
+ def _body_lines(schema: Schema, body: str) -> tuple[str, ...]:
3666
+ """The prose as the file carries it: paragraphs filled, structures verbatim.
3667
+
3668
+ Apart from :func:`_render` because `amend` (RK123) writes exactly this and not the
3669
+ heading above it — and a second copy of the reflow rules is the one that would fill a
3670
+ table the day this one learned not to.
3671
+ """
3672
+ paragraphs = [p for p in _normalize(body).split("\n\n") if p.strip()]
3673
+ out: list[str] = []
3674
+ for position, paragraph in enumerate(paragraphs):
3675
+ if position:
3676
+ out.append("")
3677
+ out.extend(_reflow(paragraph, schema.prose_width).split("\n"))
3678
+ return tuple(out)
3679
+
3680
+
3681
+ def _normalize(body: str) -> str:
3682
+ """The body arrives from an argument or a pipe, so its endings are not the file's."""
3683
+ return body.replace("\r\n", "\n").replace("\r", "\n").strip("\n")
3684
+
3685
+
3686
+ def structural(lines: Sequence[str]) -> bool:
3687
+ """Is this paragraph a shape inserted verbatim, rather than prose the tool fills?
3688
+
3689
+ Public because `adopt --sections` measures the width a file's prose is *already*
3690
+ wrapped to (RK99), and that number only means anything over the paragraphs
3691
+ :func:`_reflow` would touch: the widest line in a rationale file is otherwise a table
3692
+ row, a heading or a long link — none of which the tool ever wraps, and all of which an
3693
+ adopter would read `prose` off by mistake. One predicate, so the width that is measured
3694
+ is the width that would be written.
3695
+ """
3696
+ return any(_shape(line) for line in lines)
3697
+
3698
+
3699
+ def _shape(line: str) -> bool:
3700
+ """Is this one line a Markdown structure rather than a sentence in a paragraph? (RK397)
3701
+
3702
+ Read as three questions because the prefixes answer to three rules. A pipe, a quote and a
3703
+ fence are shapes on sight. A bullet, a number and a heading are a character **followed by
3704
+ a space** — that is what CommonMark says a marker is, and the space is what tells `* item`
3705
+ from `*emphasis*` and `1. one` from `1.5 seconds`. A run of three or more is a thematic
3706
+ break, which has no space and is a shape anyway.
3707
+
3708
+ Four indented spaces stay a code block. Asked of the raw line and not the stripped one,
3709
+ which is the only place in here where the leading whitespace is the meaning.
3710
+ """
3711
+ if line.startswith(" "):
3712
+ return True
3713
+ head = line.lstrip()
3714
+ return bool(
3715
+ head.startswith(_VERBATIM) or _BREAK.match(head) or _MARKER.match(head)
3716
+ )
3717
+
3718
+
3719
+ def _reflow(paragraph: str, width: int) -> str:
3720
+ lines = paragraph.split("\n")
3721
+ if structural(lines):
3722
+ return paragraph.rstrip()
3723
+ return textwrap.fill(
3724
+ " ".join(line.strip() for line in lines),
3725
+ width=width,
3726
+ break_long_words=False,
3727
+ break_on_hyphens=False,
3728
+ )
3729
+
3730
+
3731
+ def _placement(
3732
+ document: Document, anchor: str, task: Task | None, where: str = "", role: str = ""
3733
+ ) -> int:
3734
+ """Where the section goes: after the last one under its block, or after what it extends.
3735
+
3736
+ A section for a task belongs under that task's block, so the prose file's order is a
3737
+ consequence of the backlog's rather than a decision made per insertion. Prose that
3738
+ belongs to no task — this project's `§0` preface — has no block to derive it from, and
3739
+ derives it from the anchor instead (RK45): `§0.4` follows `§0.3` and `§RK34.1` belongs
3740
+ inside `§RK34`, so the place is the end of the subtree of the longest anchor this file
3741
+ declares that the new one extends.
3742
+
3743
+ **Under an outline the anchor decides even for a task** (RK166), because there the
3744
+ author chose that anchor and it states a place, while the prose file is organised by the
3745
+ outline and not by blocks — measured on all three outline projects on this machine, whose
3746
+ prose files declare no block heading at all, so the block branch could only ever refuse.
3747
+ Under the id scheme the anchor is the id and carries no place, which is why that scheme
3748
+ is the one that reads the block.
3749
+
3750
+ Neither is ever appended at the end as a fallback. A block the prose file does not
3751
+ declare is refused (RK37) and so is a *nested* anchor extending nothing: a Block A section
3752
+ landing after Block F's reads as Block F's, which is the same mistake `add` refuses one
3753
+ file over, and appending is the one answer that is always plausible and frequently
3754
+ wrong. A task whose line sits under no heading at all is the one case with nothing to
3755
+ derive from either side, and only that one goes last.
3756
+ """
3757
+ if task is None or document.schema.ref_scheme != "id":
3758
+ return _extended(document, anchor, where, role)
3759
+ if not task.block:
3760
+ return len(document.lines)
3761
+ heading = document.heading(task.block)
3762
+ if heading is None:
3763
+ raise UnknownBlock(
3764
+ task.block,
3765
+ sorted({h.label for h in document.headings if h.label}),
3766
+ where,
3767
+ word=document.schema.heading_word,
3768
+ )
3769
+ return document.subtree_end(heading)
3770
+
3771
+
3772
+ def _extended(
3773
+ document: Document, anchor: str, where: str = "", role: str = ""
3774
+ ) -> int:
3775
+ """The end of the subtree of the section this anchor extends, or a refusal (RK45).
3776
+
3777
+ Or, for a top-level anchor under an outline, the end of the last top-level section
3778
+ (RK166): that is the one place a section extending nothing can go without reading as
3779
+ somebody else's, and until this existed a new block's first design was reachable by no
3780
+ verb at all. The file's *own* order decides it — after the last one, never sorted, since
3781
+ whether `XXII` follows `XXI` is a question about somebody's numbering (L4, L6) and the
3782
+ author is the one who wrote the anchor.
3783
+
3784
+ ``role`` reaches the refusal alone, for RK197's reason: the remedy it names is a
3785
+ `section add`, and on a project declaring only a strategy file the default role is one
3786
+ that cannot run. Read here and not resolved from a config this function does not hold.
3787
+
3788
+ **A prefix found is not an address that is well-formed** (RK1208). :func:`_extends`
3789
+ answers the *longest declared* prefix, and reading that as a parent wrote `§I.9.1` into a
3790
+ file holding only `§I` — a `###` at a child's depth, so `I.9.1` reads as a sibling of
3791
+ `I.1`, while `anchors --family I` derives its next child from the `9` inside it and spends
3792
+ a `§I.9` nothing ever claimed. `section add I.1` on that same file is refused, which is
3793
+ the same mistake with the same author and the other answer.
3794
+ """
3795
+ parent = _extends(document, anchor)
3796
+ if parent is None:
3797
+ if _top_level(document, anchor):
3798
+ tops = [s for s in anchored(document) if _is_top(s.anchor)]
3799
+ if not tops:
3800
+ return len(document.lines)
3801
+ span = _span(document, tops[-1].anchor)
3802
+ assert span is not None # read out of this document a line ago
3803
+ return span[1]
3804
+ raise UnknownParent(
3805
+ anchor,
3806
+ [section.anchor for section in anchored(document)],
3807
+ where,
3808
+ opens=_ancestry(anchor),
3809
+ role=role,
3810
+ )
3811
+ # Every generation between the prefix found and the anchor typed. None of them is declared
3812
+ # by construction — `_extends` returned the longest that is — so this asks *how far* the
3813
+ # prefix falls short and never re-asks what the file holds.
3814
+ missing = _ancestry(anchor)[len(parent.split(".")) :]
3815
+ if missing:
3816
+ raise UnknownParent(
3817
+ anchor,
3818
+ [section.anchor for section in anchored(document)],
3819
+ where,
3820
+ opens=missing,
3821
+ role=role,
3822
+ )
3823
+ span = _span(document, parent)
3824
+ assert span is not None # `_extends` read the anchor out of this document
3825
+ return span[1]
3826
+
3827
+
3828
+ def _ancestry(anchor: str) -> tuple[str, ...]:
3829
+ """Every ancestor of this anchor, outermost first — the address alone (RK1207, RK1208).
3830
+
3831
+ Not filtered against what the file declares, and the two callers are why that is an
3832
+ invariant rather than an omission: :func:`_extends` answers the **longest declared
3833
+ prefix**, so where it answered None every ancestor is missing, and where it answered one
3834
+ the callers take the tail past it. Either way the set handed to the refusal is undeclared
3835
+ by construction, and a filter here would re-ask what that function already decided.
3836
+
3837
+ Outermost first, because that is the order the calls have to run in: `section add I.1` on
3838
+ a file with no §I is this same refusal, one address down. Empty for a one-segment anchor,
3839
+ which has no ancestor to be missing.
3840
+ """
3841
+ segments = anchor.split(".")
3842
+ return tuple(".".join(segments[:depth]) for depth in range(1, len(segments)))
3843
+
3844
+
3845
+ #: The depth a section with nothing to derive one from is written at: a one-segment anchor
3846
+ #: under the id scheme, which is a task's own design, and the last resort for anything else.
3847
+ NESTED_LEVEL = 3
3848
+
3849
+
3850
+ def _depth(document: Document, anchor: str, level: int | None) -> int:
3851
+ """The heading level this section is written at — the caller's, or the file's own (RK166).
3852
+
3853
+ Named, it is used: a project whose outline nests four deep has a depth no rule here
3854
+ knows. Omitted, a **new top level** gets the depth this file already writes one at —
3855
+ falling back to one under its shallowest heading, which is the file's title in every
3856
+ corpus read here — and a **subsection** gets one under the section it extends (RK180).
3857
+
3858
+ That last one was :data:`NESTED_LEVEL` flat, which is the same defect one level down:
3859
+ in a file whose designs are `####` under `###` parts, `section add XXI.6` wrote `###
3860
+ XXI.6`, a *sibling* of `### XXI` that ends the subtree it was meant to be inside — and
3861
+ depth is what says where a section ends (RK115), so `drop XXI` then takes the parent and
3862
+ orphans this one.
3863
+
3864
+ The parent's level and not the depth of the file's other sections at the same number of
3865
+ segments: those are the same answer in a consistently nested file and different in one
3866
+ that mixes schemes, and there the sibling count is wrong in exactly this task's
3867
+ direction — this repository declares `§0.3` at level 3, so a `§RK34.1` read off it would
3868
+ be written level with the `§RK34` it belongs inside.
3869
+ """
3870
+ if level is not None:
3871
+ return level
3872
+ if _top_level(document, anchor):
3873
+ tops = [s.level for s in anchored(document) if _is_top(s.anchor)]
3874
+ if tops:
3875
+ return tops[0]
3876
+ levels = [h.level for h in document.headings]
3877
+ return min(levels) + 1 if levels else NESTED_LEVEL - 1
3878
+ parent = _extends(document, anchor)
3879
+ if parent is None:
3880
+ # Either a one-segment anchor under the id scheme — a task's design, which has no
3881
+ # parent by construction — or a nested one whose parent this file does not declare,
3882
+ # and that one never reaches a write: `_extended` refuses it by name.
3883
+ return NESTED_LEVEL
3884
+ return next(s.level for s in anchored(document) if s.anchor == parent) + 1
3885
+
3886
+
3887
+ def _descended(
3888
+ anchor: str, claimed: Mapping[str, Sequence[str]]
3889
+ ) -> list[tuple[str, tuple[str, ...]]]:
3890
+ """Every claimed pointer that descends from this anchor, segment by segment (RK169).
3891
+
3892
+ Segment-wise and never as a string, the care :func:`_extends` already takes: `§0.1` is
3893
+ not above `§0.10`, and a guard that read it as one would refuse a drop nobody claimed.
3894
+ The anchor itself is not a descendant of itself — that is :class:`SectionClaimed`, asked
3895
+ first and answered with the message about the pointer that names it exactly.
3896
+ """
3897
+ segments = anchor.split(".")
3898
+ out: list[tuple[str, tuple[str, ...]]] = []
3899
+ for ref, owners in claimed.items():
3900
+ parts = ref.split(".")
3901
+ if len(parts) > len(segments) and parts[: len(segments)] == segments:
3902
+ out.append((ref, tuple(owners)))
3903
+ return out
3904
+
3905
+
3906
+ def _is_top(anchor: str) -> bool:
3907
+ """One segment, so there is nothing above it in the outline: `XXII`, `0`, `IX`."""
3908
+ return "." not in anchor
3909
+
3910
+
3911
+ def _top_level(document: Document, anchor: str) -> bool:
3912
+ """May this anchor open a new top level of the file? (RK166)
3913
+
3914
+ Only under an outline, and only for a one-segment anchor. Under the id scheme the anchor
3915
+ *is* the id, so it carries no place and no level: a `§RK9` that extends nothing is a
3916
+ section for a task, placed under that task's block, and reaching here with one means the
3917
+ id names no open line — which stays the refusal it was.
3918
+ """
3919
+ return document.schema.ref_scheme != "id" and _is_top(anchor)
3920
+
3921
+
3922
+ def _extends(document: Document, anchor: str) -> str | None:
3923
+ """The longest anchor this file declares that `anchor` continues: `0.4.2` → `0.4`, `0`.
3924
+
3925
+ Segment by segment rather than by string, which is what keeps `§0.1` from being read as
3926
+ the parent of `§0.10` — the same care :func:`_names` takes about where an anchor ends.
3927
+ """
3928
+ segments = anchor.split(".")
3929
+ best: list[str] = []
3930
+ for section in anchored(document):
3931
+ candidate = section.anchor.split(".")
3932
+ if len(best) < len(candidate) < len(segments):
3933
+ if candidate == segments[: len(candidate)]:
3934
+ best = candidate
3935
+ return ".".join(best) or None
3936
+
3937
+
3938
+ def untitled(document: Document) -> tuple[Section, ...]:
3939
+ """Every heading this file carries that declares no anchor, in file order (RK1107).
3940
+
3941
+ The other half of :func:`anchored`, and until this the half no verb could reach. A prose
3942
+ file's opening — the `#` that names it, and the prose under it saying what the file is —
3943
+ declares no address, and neither does a `## Table of contents`; both go stale the instant
3944
+ a `ship` drops a section, and the only door onto either was the hand edit the guard denies.
3945
+ Measured: `section show 'Table of contents'` answered *no §Table of contents section*, which
3946
+ was true and left the caller nowhere to go.
3947
+
3948
+ **The heading's text is the address, and that is not a second addressing scheme.** An
3949
+ anchor is a name the project chose and never reuses; this is the heading a reader already
3950
+ sees, matched as it is written. §RK1107 assumed a positional name (`preamble`, `contents`)
3951
+ would be needed and would have to be declared per project (L6) — measuring the two live
3952
+ files says otherwise: the opening prose is the `#`'s **own** body, which
3953
+ :meth:`~roadkeep.kernel.document.Document.prose_end` already delimits, so the file's title
3954
+ is its address and no new word is invented anywhere.
3955
+
3956
+ Own prose and never the subtree, for :func:`anchored`'s reason: the `#` heading's body is
3957
+ the preamble and stops at the first `##`, so amending it can never reach a section that has
3958
+ an address of its own.
3959
+ """
3960
+ out: list[Section] = []
3961
+ for heading in document.headings:
3962
+ if anchor_of(heading.text, document.schema) is not None:
3963
+ continue
3964
+ end = document.prose_end(heading)
3965
+ out.append(
3966
+ Section(
3967
+ anchor="",
3968
+ title=heading.text.strip(),
3969
+ level=heading.level,
3970
+ first=heading.lineno,
3971
+ last=end,
3972
+ body="".join(document.lines[heading.lineno : end]).strip("\r\n"),
3973
+ )
3974
+ )
3975
+ return tuple(out)
3976
+
3977
+
3978
+ def titled(document: Document, title: str) -> Heading | None:
3979
+ """The one unanchored heading whose text is *title*, or None (RK1107).
3980
+
3981
+ Compared on the stripped text and nothing cleverer: the caller has the file open, and a
3982
+ fuzzy match would make *which section did I just edit* a question. Refused rather than
3983
+ guessed where two headings carry one text — :class:`AmbiguousTitle` — because a file whose
3984
+ contents heading is written twice has two regions and no address distinguishes them.
3985
+
3986
+ Asked **only of the unanchored**, so this can never become a second way to reach a section
3987
+ that has an anchor: one address per addressable thing, which is the property every reader
3988
+ downstream of `_span` already depends on.
3989
+ """
3990
+ wanted = title.strip()
3991
+ found = [
3992
+ heading
3993
+ for heading in document.headings
3994
+ if anchor_of(heading.text, document.schema) is None and heading.text.strip() == wanted
3995
+ ]
3996
+ if len(found) > 1:
3997
+ raise AmbiguousTitle(wanted, tuple(heading.lineno for heading in found))
3998
+ return found[0] if found else None
3999
+
4000
+
4001
+ class AmbiguousTitle(ValueError):
4002
+ """One heading text, two headings — so the text is not an address (RK1107)."""
4003
+
4004
+ def __init__(self, title: str, linenos: tuple[int, ...]) -> None:
4005
+ self.title = title
4006
+ self.linenos = linenos
4007
+ spelled = ", ".join(str(one) for one in linenos)
4008
+ super().__init__(
4009
+ f"{len(linenos)} headings read '{title}' (lines {spelled}): an unanchored section "
4010
+ f"is addressed by its heading, so two with one text have no address between them — "
4011
+ f"give one of them a different heading, or an anchor"
4012
+ )
4013
+
4014
+
4015
+ def _span(document: Document, anchor: str) -> tuple[int, int, Heading] | None:
4016
+ """The `[start, end)` lines to delete, and the heading that names them.
4017
+
4018
+ A section ends where the next heading of the same or higher level begins — the
4019
+ document's own answer (RK115), because a drop takes the subtree. When it is the last
4020
+ thing in the file, the deletion reaches back over the blank line above it, which
4021
+ otherwise survives as a trailing blank nobody put there.
4022
+ """
4023
+ for heading in document.headings:
4024
+ if not _names(heading.text, anchor, document.schema):
4025
+ continue
4026
+ start = heading.lineno - 1
4027
+ end = document.subtree_end(heading)
4028
+ if end == len(document.lines):
4029
+ while start > 0 and blank(document.lines[start - 1]):
4030
+ start -= 1
4031
+ return start, end, heading
4032
+ return None
4033
+
4034
+
4035
+ def anchor_text(schema: Schema, anchor: str) -> str:
4036
+ """The anchor as a *heading* spells it: `§RK9` under `id`, `VIII.1` under `outline`.
4037
+
4038
+ The one place that spelling is decided, so a reader that echoes a heading (`section
4039
+ show`, `brief`) cannot print a file back differently from how it is written. On the
4040
+ pointer the § is unconditional — that is the end of the reference where a sigil is
4041
+ what tells an anchor from a word, in either scheme.
4042
+
4043
+ The **namespace stays on the pointer** (RK340): `[refs]` says which file an address is
4044
+ in, and a heading is already in one, so writing `S:I` above the prose in `STRATEGY.md`
4045
+ would put the answer to "which file" inside the file that is the answer.
4046
+ """
4047
+ if schema.ref_scheme == "id":
4048
+ return f"§{anchor}"
4049
+ return local(schema, anchor) or anchor
4050
+
4051
+
4052
+ def heading_of(schema: Schema, section: Section) -> str:
4053
+ """The heading line this section is written as — one spelling, one writer (RK44).
4054
+
4055
+ An empty anchor is the unanchored section (RK1107) and writes its title alone: under the
4056
+ id scheme :func:`anchor_text` would otherwise render the sigil with nothing after it, so a
4057
+ re-titled `## Table of contents` came back as `## § Table of contents`. Answered here
4058
+ because this is the one writer, and a caller composing the exception would be the second.
4059
+ """
4060
+ if not section.anchor:
4061
+ return f"{'#' * section.level} {section.title}"
4062
+ return f"{'#' * section.level} {anchor_text(schema, section.anchor)} {section.title}"
4063
+
4064
+
4065
+ def anchor_of(text: str, schema: Schema) -> str | None:
4066
+ """The anchor this heading declares, or None when it declares none (RK27, RK44).
4067
+
4068
+ Public because a heading is read outside a parsed document too (RK247): the anchors a
4069
+ file *used to* declare are in its diffs, and a second reader of this spelling one module
4070
+ over is the drift :func:`anchor_text` refuses at the writing end.
4071
+
4072
+ Read **per scheme**, because the two write it differently and requiring one spelling
4073
+ read the other as prose: measured on Shio, 151 headings yielded 0 sections and
4074
+ therefore 74 pointers reported as resolving to nothing against a file that answers
4075
+ every one of them — RK15's argument inverted, which is how a gate teaches its reader
4076
+ to skip a category.
4077
+
4078
+ * ``id`` — `§RK9 A design` → `RK9`. The anchor is a task id, so the § is what marks
4079
+ it as an anchor rather than a word, and it is required.
4080
+ * ``outline`` — `VIII.1 MCP server host` → `VIII.1`, Shio's `0. Strategy` → `0`, and
4081
+ Turing's lettered fourth level `IX.4.d The pivot` → `IX.4.d` (RK47) and commitclerk's
4082
+ block letters `B.2 Ticket trailers` → `B.2` (RK101), where the bare `B — Context`
4083
+ above it is still a block: the number *is*
4084
+ the announcement, so the sigil belongs on the pointer alone. It is accepted where an
4085
+ author wrote one anyway, because a heading nothing can see is the defect this closes
4086
+ and not a spelling to punish. What a segment may be is
4087
+ :data:`~roadkeep.kernel.schema.OUTLINE_ANCHOR_RE`'s to say, at both ends of the pointer.
4088
+ """
4089
+ head = text.lstrip()
4090
+ if schema.ref_scheme == "id":
4091
+ if not head.startswith("§"):
4092
+ return None
4093
+ return head[1:].split(" ", 1)[0].strip() or None
4094
+ # The trailing period is Shio's numbering ("## VIII. The Agent Gateway"), not part of
4095
+ # the anchor a pointer writes — the pointer says `§VIII.7`.
4096
+ token = head.split(" ", 1)[0].lstrip("§").rstrip(".")
4097
+ return token if OUTLINE_ANCHOR_RE.match(token) else None
4098
+
4099
+
4100
+ def _title_of(text: str, schema: Schema) -> str:
4101
+ """`§RK9 A design` → `A design`. The anchor is one token; the rest is the title."""
4102
+ if anchor_of(text, schema) is None:
4103
+ return text
4104
+ return text.lstrip().partition(" ")[2].strip()
4105
+
4106
+
4107
+ def _names(text: str, anchor: str, schema: Schema) -> bool:
4108
+ """Does this heading declare exactly this anchor?
4109
+
4110
+ Asked of the parsed anchor rather than of the text, which is what keeps `§0` from
4111
+ claiming `§0.1` and `VIII.1` from claiming `VIII.10` without a second opinion about
4112
+ where an anchor ends.
4113
+
4114
+ And asked in **this file's namespace** (RK340): the heading writes the bare address, so
4115
+ an anchor naming another role's is one no heading here declares. One comparison rather
4116
+ than a check at every reader, because this is the comparison every reader already makes.
4117
+ """
4118
+ here = local(schema, anchor)
4119
+ # Both sides answer None — a heading that declares no anchor, and an address that is
4120
+ # another role's — and the two Nones are not a match.
4121
+ return here is not None and anchor_of(text, schema) == here