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/linting.py ADDED
@@ -0,0 +1,4420 @@
1
+ """The gate: every governed line, validated where nothing else was watching (RK14).
2
+
3
+ `add` refuses a field at the moment it is typed (L1), which is where the saving is — but
4
+ a file also drifts by the paths `add` does not own: a hand edit, a merge that resolved
5
+ into a half-line, a `roadkeep.toml` limit lowered after the lines were written. So this
6
+ is the backstop, and the one thing that makes it a gate rather than advice is the exit
7
+ code: **exit 1 when anything drifted**, so a pre-commit hook and an Action (RK17) can
8
+ both call the same command and neither has to parse a report.
9
+
10
+ It re-validates rather than re-implements. Every rule read here comes from
11
+ :meth:`Schema.validate`, every line from :class:`Document`, every dep resolution from
12
+ :mod:`roadkeep.backlog` — a linter with its own regexes over prose would be a second
13
+ statement of the format, and the two would disagree in the direction nobody tests.
14
+
15
+ What it reports, and why each one is a defect the other commands cannot see:
16
+
17
+ * **A schema violation** on a line that exists — the limit that was raised after the
18
+ line was written, or the line that never went through `add`.
19
+ * **A line that does not round-trip** (L3). Reported and never repaired: normalizing a
20
+ line the parser may have misread is the corruption the whole invariant exists to
21
+ prevent, so what this prints is the canonical rendering and the fix stays a human's.
22
+ * **A marker-bearing bullet the grammar rejected** — the silent miss `audit` (RK10)
23
+ prints at exit 0. `audit` reports; this fails.
24
+ * **One id in two places** — twice in one file, or in both the roadmap and the ledger.
25
+ Two lines carrying one id is two answers to "is this done?", and nothing says which.
26
+ * **A dep nothing can satisfy** — an id in neither file (a typo, or a line deleted by
27
+ hand), a dep on a task that was retired (RK32: the record says the work will not
28
+ happen, so the dependent line is the author's next edit), or `Block X` where no
29
+ heading declares X (RK37). An *external* dep is not a finding: real work waits on
30
+ things this backlog does not track, and Turing writes them on purpose.
31
+ * **A stale `(deps: … ✅)` annotation** — derived on every write (RK8), so a divergence
32
+ here means the file was edited by something that is not this tool.
33
+ * **A cycle** — three tasks waiting on each other are three tasks nothing can start
34
+ (RK13), which is a defect and not a shape.
35
+ * **A queue entry naming work that has left** (RK326) — the same resolution, applied to
36
+ the one list that outranks the id order: shipped, retired, set aside, naming nothing,
37
+ or naming a block whose every line has left or been set aside. Written as deps, most already
38
+ failed here; written as a priority they passed at exit 0 while `pick` said only that
39
+ the queue "names nothing ready".
40
+
41
+ And the same question asked of the prose file, which is RK15's half: **a pointer that
42
+ resolves to nothing reads exactly like a design that exists**, which is worse than no
43
+ pointer because it makes a reader stop looking. So the `→ §RK<n>` is resolved against
44
+ the improvements file, in both directions — a pointer with no section, and a section no
45
+ line points at — plus the section's word budget and the paths a line claims. The
46
+ pointer is read from the parsed ``ref`` field and never from the line's text: §RK15's
47
+ own `why` quotes a pointer as an example, and a scan over the line would report that
48
+ quotation as the broken pointer it is not. And once from the prose end alone (RK239): two
49
+ files declaring one anchor is a defect at both headings whether or not a line reached it.
50
+
51
+ And the one block the tool writes **outside** a governed file: a projection of the backlog
52
+ is derived rather than restated (RK39), and nothing held the derivation to the files it came
53
+ from — so a commit that ships a task and forgets `export` left a README contradicting the
54
+ ledger, caught here by a pytest fixture an adopting project does not install (RK104). The
55
+ markers are the author's declaration, so a file carrying none is silent; a file carrying them
56
+ is spliced in memory and compared, and a difference is one finding naming the command.
57
+
58
+ And one file the tool never writes: **an always-loaded instruction file has a budget, and
59
+ a budget stated in its own prose is what let Shio's `agents.md` reach 186 KB** while
60
+ declaring 150 lines at the bottom of itself (RK30). So `roadkeep.toml` declares it and the
61
+ exit code holds it, in lines and in bytes — the two units the reader actually pays.
62
+
63
+ **Two tiers, because the exit code is the contract.** A :class:`Finding` fails the build;
64
+ a :class:`Note` is something the gate says at exit 0. Both exist because two real defects
65
+ cannot be refused without failing an honest file: `Block P` is a legitimate dep that
66
+ happens to name forty-eight open tasks (RK35), and a rationale section edited without its
67
+ task line is the shape of a smuggled requirement *and* of a typo fix (RK36). Refusing
68
+ either would produce a gate that gets bypassed, which is worth less than a sentence read
69
+ at the moment of the commit — the same split `audit` (RK10) makes.
70
+
71
+ Everything above is decidable from the files as they are. The checks that are about a
72
+ *change* are opt-in through ``since``, because `lint` has to keep working in a checkout with
73
+ no history: `--since HEAD` in a commit hook, the base branch in CI. The second of them is a
74
+ block this commit **emptied or reopened** (RK269) — the transition `ship` computes, states
75
+ once to a console and records nowhere, which is what left a project's derived per-block index
76
+ claiming a finished block was active while `lint` called the tree clean four times running.
77
+
78
+ **And one question the absolute count cannot answer: did this change make it worse (RK84).**
79
+ An adopting project arrives with history — one live corpus lints at 317 problems, none of
80
+ them the current change's — so the gate cannot be wired to its CI, and the number moving by
81
+ one or two per task carries no signal. ``baseline`` reads the governed files *at a revision*,
82
+ runs everything above over those, and reports only the excess: what this working tree added,
83
+ with the standing debt named and forgiven. It exits non-zero on the difference alone, which
84
+ is the shape that lets a repository adopt the gate before it has paid the debt off. Two
85
+ things it deliberately does **not** vary: the configuration, because a limit is the ruler and
86
+ not the thing measured, and the repository, because what a baseline run stashes is the three
87
+ files — which is what the hand procedure it replaces did, four commands at a time.
88
+
89
+ What is deliberately *not* here: normalizing what is mechanical, which is a write and lives
90
+ in :mod:`roadkeep.fixing` (RK16). This module answers one question completely and never
91
+ writes: *is every line in the governed files a line this format accepts, does everything it
92
+ points at exist, and did anything loaded every turn outgrow what it was allowed?*
93
+ """
94
+
95
+ from __future__ import annotations
96
+
97
+ import os
98
+ import re
99
+ import unicodedata
100
+ import functools
101
+ from collections.abc import Callable, Sequence
102
+ from typing import Any
103
+ from dataclasses import dataclass, field, replace
104
+ from pathlib import Path
105
+
106
+ from roadkeep import criteria, queueing, scoping
107
+ from roadkeep.backlog import Backlog, DepStatus, Stage, id_order
108
+ from roadkeep.blocking import removable
109
+ from roadkeep.config import LINE_ROLES as _LINE_ROLES
110
+ from roadkeep.config import PROSE_ROLES, ROLES, Config, spent, translated
111
+ from roadkeep.kernel.document import Document, Entry, Heading, ending
112
+ from roadkeep.exporting import (
113
+ BEGIN,
114
+ DEFAULTS,
115
+ NoMarkers,
116
+ enclosing,
117
+ project,
118
+ splice,
119
+ target_of,
120
+ )
121
+ from roadkeep.graph import Graph
122
+ from roadkeep.history import (
123
+ HistoryUnavailable,
124
+ check_ignore,
125
+ blob_at,
126
+ content_at,
127
+ resolves,
128
+ touched_since,
129
+ tracked_at,
130
+ tracked_now,
131
+ )
132
+ from roadkeep.markers import derive
133
+ from roadkeep.referring import PAIRS
134
+ from roadkeep.kernel.schema import (
135
+ CODEPOINT_KINDS,
136
+ TAB,
137
+ Dep,
138
+ DepKind,
139
+ Task,
140
+ codepoint_kind,
141
+ indentation,
142
+ over_by,
143
+ suspect,
144
+ )
145
+ from roadkeep.sections import Section, anchored, find, references
146
+ from roadkeep.sections import owners as section_owners
147
+ from roadkeep.showing import known_directories, on_disk, paths_in
148
+ from roadkeep.provenance import invocation
149
+
150
+ #: The governed files whose unit is a task line. The prose files are paragraphs, so
151
+ #: their gate is a pointer and a budget — RK15 and RK30, not this. The deferred store is
152
+ #: one of them (RK96): a line set aside is still a line, and a store nothing gated would
153
+ #: be the one place the format is a convention again.
154
+ #: "Nobody has asked yet", which None cannot say here: None is the answer meaning "git
155
+ #: could not tell us", and the two have to be different things (RK217).
156
+ _UNASKED = object()
157
+
158
+ #: `decisions` is the fourth (RK1269), and for the store's own argument: a decision record is
159
+ #: a line, so a file this gate did not read would be the one place the format is a convention
160
+ #: again — which is precisely what an ADR kept by hand already was.
161
+ #:
162
+ #: Declared in `config` since RK1361 and re-exported here, where every reader of it already
163
+ #: looks: that role is now a prose file too, so "not a prose role" stopped deriving this set
164
+ #: and `govern` needed the same four. One authority, two importers.
165
+ LINE_ROLES = _LINE_ROLES
166
+
167
+ #: The two whose lines are still alive, so their rationale section is still there: open
168
+ #: work, and work set aside (RK96). The ledger is not among them — `ship` and `retire`
169
+ #: delete the section in the transaction that writes the entry.
170
+ LIVE_ROLES = ("roadmap", "deferred")
171
+
172
+ #: The codes both surfaces raise, where this file's own scan is the better half (RK499). The
173
+ #: schema refuses these at the door, naming a position inside the argument the caller retypes;
174
+ #: `_characters` finds them anywhere in the file, naming the line and the column. One defect,
175
+ #: two readings, and the gate prints the one addressed to a reader of the file.
176
+ _SCANNED = frozenset({"char.tab", "char.space", "char.invisible"})
177
+
178
+ _ENDING_NAMES = {"\r\n": "CRLF", "\n": "LF", "\r": "CR"}
179
+
180
+
181
+ @dataclass(frozen=True, slots=True)
182
+ class Finding:
183
+ """One defect, at one place. ``code`` is stable; ``message`` names the fix.
184
+
185
+ The code is the same string :class:`~roadkeep.kernel.schema.Violation` uses where the
186
+ finding came from the schema, so a caller filtering on `why.sentences` filters the
187
+ same rule whether it was refused at `add` or found here.
188
+ """
189
+
190
+ code: str
191
+ file: str
192
+ message: str
193
+ #: 1-based, as an editor counts. ``None`` when the finding is about the file itself.
194
+ lineno: int | None = None
195
+ id: str = ""
196
+ #: 1-based column, for a finding about one character (RK34). An invisible codepoint
197
+ #: cannot be found by eye, so the offset is half of what makes the report usable.
198
+ column: int | None = None
199
+ #: What the remedy is *about*, where that is not the id and not printable as a prefix
200
+ #: (RK420). `id` already doubles as the subject on most codes — a block label, a section
201
+ #: anchor — because it is printed in front of the message and reads correctly there. A
202
+ #: queue token does not: the message opens `queues RK12, …`, so putting it in `id` would
203
+ #: render `RK12: queues RK12`. Last field, so every positional call site still means what
204
+ #: it did.
205
+ subject: str = ""
206
+ #: What this finding has in common with its siblings, where a whole group of them is one
207
+ #: fact and one edit (RK469). Empty on every code but the one that needed it: a report
208
+ #: whose bulk is one sentence repeated is one a reader learns to skip (RK146), and it
209
+ #: buries the findings that are each about a different line.
210
+ #:
211
+ #: Declared by the **emitter**, which is the only place that knows what is shared —
212
+ #: string surgery on the message would be a second reading of a sentence this file
213
+ #: composes. Read only by the terminal report: `--json` keeps one entry per address,
214
+ #: because a consumer acting per address needs the line, and the count that follows the
215
+ #: findings is about addresses either way.
216
+ shared: str = ""
217
+ #: The file this finding is *about*, where that is not the file it is filed against
218
+ #: (RK1070). One code needs it: `grammar.unreadable` lands on `roadkeep.toml`, because
219
+ #: the declaration that broke the file is there and so is the edit (RK1067), and it
220
+ #: explains every per-line failure in the file it names. Two addresses and not one —
221
+ #: `file` is where a reader clicks, `about` is what the finding covers — because
222
+ #: conflating them is how a suppression silences the wrong file.
223
+ about: str = ""
224
+
225
+ @property
226
+ def token(self) -> str:
227
+ """What a remedy substitutes: the explicit subject, or the id it usually is."""
228
+ return self.subject or self.id
229
+
230
+ @property
231
+ def where(self) -> str:
232
+ if self.lineno is None:
233
+ return self.file
234
+ if self.column is None:
235
+ return f"{self.file}:{self.lineno}"
236
+ return f"{self.file}:{self.lineno}:{self.column}"
237
+
238
+ def __str__(self) -> str:
239
+ subject = f"{self.id}: " if self.id else ""
240
+ return f"{self.where} {self.code} {subject}{self.message}"
241
+
242
+
243
+ @dataclass(frozen=True, slots=True)
244
+ class Note:
245
+ """Something the gate says and does not fail on (RK35).
246
+
247
+ A separate list from :class:`Finding` because the exit code is the contract: `Block P`
248
+ is a legitimate dep (RK28) and failing a build over one would fail the honest backlog
249
+ this tool was measured against. But it is one token naming forty-eight open tasks, and
250
+ a reader counting deps to judge how blocked a line is has no way to see that from the
251
+ line — so the expansion is stated, at exit 0, which is the same split `audit` (RK10)
252
+ makes between reporting a miss and being the gate.
253
+ """
254
+
255
+ code: str
256
+ file: str
257
+ message: str
258
+ lineno: int | None = None
259
+ id: str = ""
260
+ #: The same field :class:`Finding` grew for the same reason (RK420): a note carries a
261
+ #: remedy too, and the thing it is about is not always printable in front of a message.
262
+ subject: str = ""
263
+
264
+ @property
265
+ def token(self) -> str:
266
+ return self.subject or self.id
267
+
268
+ def __str__(self) -> str:
269
+ where = self.file if self.lineno is None else f"{self.file}:{self.lineno}"
270
+ subject = f"{self.id}: " if self.id else ""
271
+ return f"{where} {self.code} {subject}{self.message}"
272
+
273
+
274
+ @dataclass(slots=True)
275
+ class Tree:
276
+ """Where one run reads the governed files from: this working tree, or a revision (RK84).
277
+
278
+ Every disk touch a run makes on a file it *governs* goes through here, which is the whole
279
+ of how a baseline is taken — the documents, the budgeted files, and whether a declared
280
+ file is there at all. What does not go through here is the rest of the repository: a
281
+ baseline varies the three files and holds the code constant, because that is the question
282
+ being asked, and because resolving a whole tree would make the comparison a checkout.
283
+
284
+ Bytes, and not text: a governed file is compared to its own rendering byte for byte (L3)
285
+ and a budget is spent in them (RK30), so a revision read through newline translation
286
+ would answer both wrongly.
287
+ """
288
+
289
+ config: Config
290
+ #: ``None`` for the working tree — the run every other command makes.
291
+ rev: str | None = None
292
+ #: The revision's paths, read once and only if something asks (`ls-tree` is not free).
293
+ _names: frozenset[str] | None = field(default=None, repr=False)
294
+ #: One read per file: `_absent` asks whether it is there and everything else asks what
295
+ #: is in it, which at a revision is two subprocesses for one answer.
296
+ _blobs: dict[Path, bytes | None] = field(default_factory=dict, repr=False)
297
+ #: Every tail of every tracked path, built once (RK173). Unbuilt until something asks,
298
+ #: because only one check needs it and a `ls-files` per run of `show` would be a cost
299
+ #: paid by the callers that never ask about an artefact at all.
300
+ _tails: frozenset[str] | None = field(default=None, repr=False)
301
+ #: What the repository declared untracked, per token (RK213, keyed by RK219). A dict
302
+ #: and not a set-of-the-first-answer: the key is the question, so a second caller — or
303
+ #: a second pass — is answered about what it asked rather than about what came first.
304
+ _ignored: dict[str, bool] = field(default_factory=dict, repr=False)
305
+ #: The directories a path claim is decided against (RK217), or None where git could not
306
+ #: say — a sentinel rather than None-means-unasked, because None is itself the answer.
307
+ _directories: frozenset[str] | None | object = field(default=_UNASKED, repr=False)
308
+ #: The root as a normalised string, so the constant half of a spelling is built once.
309
+ _root: str | None = field(default=None, repr=False)
310
+
311
+ def document(self, role: str) -> Document | None:
312
+ """One governed file under its role's schema, or ``None`` when this tree lacks it."""
313
+ if not self.config.has(role):
314
+ return None
315
+ if self.rev is None:
316
+ path = self.config.path(role)
317
+ return self.config.document(role) if path.is_file() else None
318
+ raw = self.blob(self.config.path(role))
319
+ if raw is None:
320
+ return None
321
+ # Deliberately parsed without its path: a document of how a file *was* must not be
322
+ # one call away from being saved over the file as it is.
323
+ return Document.parse(
324
+ raw.decode("utf-8", errors="replace"), schema=self.config.schema_for(role)
325
+ )
326
+
327
+ def blob(self, path: Path) -> bytes | None:
328
+ if path in self._blobs:
329
+ return self._blobs[path]
330
+ if self.rev is not None:
331
+ found = blob_at(self.config, self.rev, path)
332
+ else:
333
+ found = path.read_bytes() if path.is_file() else None
334
+ self._blobs[path] = found
335
+ return found
336
+
337
+ def present(self, path: Path) -> bool:
338
+ """Whether this tree carried the file at all, without reading one to find out."""
339
+ return path.is_file() if self.rev is None else self.blob(path) is not None
340
+
341
+ def carries(self, token: str, near: Path) -> bool:
342
+ """Did this tree have the artefact a line names, under either convention (RK51)?
343
+
344
+ Asked only of a revision, and only to *withhold* a `path.missing` the baseline should
345
+ never have credited: a file that was there at the ref and is not here now was deleted
346
+ by this change, and forgiving that would forgive the one true finding this check has
347
+ produced on a live corpus — a class the ledger still names under the directory it was
348
+ renamed inside.
349
+ """
350
+ if self.rev is None:
351
+ return False
352
+ return any(spelling in self.listing() for spelling in self.spellings(token, near))
353
+
354
+ def declared_untracked(self, tokens: Sequence[tuple[str, Path]]) -> frozenset[str]:
355
+ """Which tokens name a path the repository has declared it will never track (RK213).
356
+
357
+ The next shape along from RK173's widening, and the one an adopter hit first. Claude
358
+ Code Tray's ledger names `bin/Release/net10.0-windows/win-x64/ClaudeTray.exe` while
359
+ explaining why its CI builds rather than publishes — a correct sentence about where
360
+ the build output lands. `bin/` is the first line of its `.gitignore`, and its
361
+ roadkeep job is `checkout` then the action, so `lint` exited 1 on every push and 0
362
+ on the machine of anyone who had just compiled. Invisible locally, and in CI the
363
+ only finding, so the job was simply red.
364
+
365
+ **Asked of git, not of a list.** A table of `bin/`, `dist/`, `target/`, `build/`
366
+ here would be convention where the repository already has a declaration (L6), and
367
+ it would be wrong for the project that tracks its `dist/` on purpose.
368
+ `check-ignore` reads the same `.gitignore`, `.git/info/exclude` and core.excludesFile
369
+ the developer's own `git status` reads, so the tool and the author cannot disagree
370
+ about what this repository tracks.
371
+
372
+ One call for every candidate, because the candidates are what survived `exists`,
373
+ `carries` and `anywhere` — one or two on a live corpus — and a subprocess each would
374
+ price a check by how broken the file is. Both spellings are asked (RK51): a token is
375
+ relative to the ledger's directory or to the root, and either may be the ignored one.
376
+
377
+ No git, no answer, and the finding stands: withholding where the question could not
378
+ be asked would turn "this repository says so" into "nobody could say otherwise".
379
+
380
+ Every token asked is recorded, ignored or not, so a repeat costs nothing and a new
381
+ one costs the batch it arrives in (RK219). What is *not* recorded is the difference
382
+ between "git said no" and "git could not be asked", because within one tree that
383
+ cannot change: a run has one repository, and it either has git or it does not.
384
+ """
385
+ unknown = [(token, near) for token, near in tokens if token not in self._ignored]
386
+ if unknown:
387
+ declared = _declared_untracked(self.config, unknown)
388
+ for token, _ in unknown:
389
+ self._ignored[token] = token in declared
390
+ return frozenset(token for token, _ in tokens if self._ignored[token])
391
+
392
+ def spellings(self, token: str, near: Path) -> tuple[str, ...]:
393
+ """How git could spell this token, from each base it may be relative to (RK51).
394
+
395
+ Computed once and passed down (RK228): `holds` used to ask `carries`, which spelled
396
+ the token, and then spell it again for the directory set — two answers to one
397
+ question, and the profile's largest remaining row was the second one.
398
+
399
+ The root prefix is the constant half, so it is normalised once for the whole run
400
+ rather than 34133 times through `os.path.relpath`, which normcases both ends of
401
+ every call. Nothing about the answer changes; only how often the part that cannot
402
+ differ is recomputed.
403
+ """
404
+ return tuple(
405
+ spelling
406
+ for base in (near, self.config.root)
407
+ if (spelling := _spelled(self._prefix(), str(base), token)) is not None
408
+ )
409
+
410
+ def _prefix(self) -> str:
411
+ """The repository root as a normalised prefix, with its separator, built once."""
412
+ if self._root is None:
413
+ self._root = os.path.normpath(str(self.config.root))
414
+ return self._root
415
+
416
+ def listing(self) -> frozenset[str]:
417
+ """Every path this tree still **has**, read once (RK173, RK217).
418
+
419
+ Two checks want it — the tail index and the revision's membership test — so it is
420
+ the tree's rather than each one's, and a run costs one listing however many ask.
421
+ """
422
+ if self._names is None:
423
+ self._names = (
424
+ tracked_now(self.config)
425
+ if self.rev is None
426
+ else tracked_at(self.config, self.rev)
427
+ )
428
+ return self._names
429
+
430
+ def holds(self, token: str, near: Path) -> bool:
431
+ """Does the tree this run is judging have what this token names? (RK84, RK218)
432
+
433
+ The working tree answers from the disk, which is its subject. A revision answers
434
+ from git, and from **both** shapes a token can name: a file is a tracked path, and
435
+ a directory is a prefix of one — `docs`, `create-shio-app` and thirty-three more
436
+ across the two pins are named as directories and were only ever admitted because
437
+ they happened to be on somebody's disk.
438
+
439
+ `exists` is a fact about *now*, so a run naming a revision may not consult it: an
440
+ untracked file created since the ref, which git has never seen, used to silence a
441
+ finding that revision genuinely had.
442
+ """
443
+ if self.rev is None:
444
+ return on_disk(token, self.config.root, near)
445
+ spellings = self.spellings(token, near)
446
+ if any(spelling in self.listing() for spelling in spellings):
447
+ return True
448
+ directories = self.directories() or frozenset()
449
+ return any(spelling in directories for spelling in spellings)
450
+
451
+ def directories(self) -> frozenset[str] | None:
452
+ """Which directories this repository knows, for deciding a claim (RK217).
453
+
454
+ Not :meth:`listing`, and the difference is the defect: that one drops a file
455
+ deleted from the working tree, which is right for "does the tree still have it" and
456
+ exactly wrong here — a ledger naming `lib/gone.py` after `lib/` was removed would
457
+ stop being a claim instead of becoming a finding. At a revision the two coincide,
458
+ there being no working tree to have deleted anything from.
459
+ """
460
+ if self._directories is _UNASKED:
461
+ # At HEAD the function's own default is the index, which is the listing this
462
+ # question wants (RK221); at a revision the tree's listing already is that.
463
+ self._directories = known_directories(
464
+ self.config, None if self.rev is None else self.listing()
465
+ )
466
+ return self._directories
467
+
468
+ def anywhere(self, token: str) -> bool:
469
+ """Does this tree hold the artefact this token names, under **any** prefix? (RK173)
470
+
471
+ A monorepo entry writes the path its reader is standing in — the frontend app, the
472
+ showcase skill — because that is what a developer pastes from a terminal already
473
+ inside it. Resolving from the repository root alone reported the difference as a
474
+ missing file: of Turing's eight `path.missing` findings, six named artefacts the
475
+ repository has, which is a signal ratio at which the class stops being read. Worse,
476
+ it points at history — these are shipped entries, so the remedy the wording implies
477
+ is editing what already happened.
478
+
479
+ The question this check asks is whether the **repository has the artefact** (RK51),
480
+ so the tail is what answers it, and a rename inside a directory — the one true
481
+ finding this check has produced on a live corpus — still matches nothing.
482
+
483
+ **Measured coming out, too** (RK189), because a widening whose cost is an argument
484
+ is a widening nobody can price. Over both pins: Shio exercises the rule zero times
485
+ in 1278 files, and Turing's ledger leaves six tokens unresolved, of which this
486
+ silences five and reports the moved file. Four of the five are two-segment tokens
487
+ matching exactly one tracked file — the match identifies the artefact rather than
488
+ finding a name — and the fifth is the `./package.json` that motivated the rule,
489
+ matching thirteen. So a one-segment token is admitted deliberately: requiring a
490
+ slash would re-report that one and change none of the others. The exposure it
491
+ accepts is real and unrealised — 17% of the files in each tree share a basename —
492
+ and `tests/test_linting.py` is where all four numbers are held.
493
+ """
494
+ if self._tails is None:
495
+ names = self.listing()
496
+ self._tails = frozenset(
497
+ "/".join(segments[start:])
498
+ for name in names
499
+ for segments in (name.split("/"),)
500
+ for start in range(len(segments))
501
+ )
502
+ wanted = token.replace("\\", "/")
503
+ while wanted.startswith("./"):
504
+ wanted = wanted[2:]
505
+ return wanted in self._tails
506
+
507
+
508
+ @dataclass(frozen=True, slots=True)
509
+ class Baseline:
510
+ """What the same gate said at a revision, so this run can report only what it added.
511
+
512
+ ``forgiven`` is the standing debt *as it still stands* — findings this working tree has
513
+ and the revision had too. ``resolved`` is the other direction, and it is here for the
514
+ reading that nearly hid a real defect: a run that deleted 160 lines of rationale it
515
+ should not have took the count down by eight, and the drop read as an improvement until
516
+ the two findings it *added* were looked at individually. One number cannot say both.
517
+ """
518
+
519
+ rev: str
520
+ forgiven: tuple[Finding, ...] = ()
521
+ resolved: tuple[Finding, ...] = ()
522
+
523
+ @property
524
+ def standing(self) -> int:
525
+ return len(self.forgiven)
526
+
527
+
528
+ @dataclass(frozen=True, slots=True)
529
+ class Report:
530
+ """What was checked, and everything wrong with it. Emptiness is the pass."""
531
+
532
+ findings: tuple[Finding, ...]
533
+ #: The files this run **judged**, as the project spells them — printed even when clean,
534
+ #: because a gate that passed by reading nothing is the failure mode of every gate. Judged
535
+ #: and not merely read, so every finding's file is in here (RK354): `roadkeep.toml` is one
536
+ #: where it carries a queue and is not one where it only said which files to open.
537
+ checked: tuple[str, ...]
538
+ lines: int
539
+ #: Anchored sections read in the prose file — the other half of what was checked.
540
+ sections: int = 0
541
+ #: Always-loaded files whose budget was measured (RK30).
542
+ budgets: int = 0
543
+ #: What the gate observed without failing on it (RK35). Never affects the exit code.
544
+ notes: tuple[Note, ...] = ()
545
+ #: The revision this run was measured against, when it was (RK84). Present means
546
+ #: ``findings`` holds the difference and nothing else.
547
+ baseline: Baseline | None = None
548
+
549
+ @property
550
+ def clean(self) -> bool:
551
+ return not self.findings
552
+
553
+ @property
554
+ def problems(self) -> int:
555
+ return len(self.findings)
556
+
557
+ def stated(self, config: Config, applied: Fix, root: str, quiet: bool) -> None:
558
+ """The gate's report, written as it is composed (RK14, RK35, RK420).
559
+
560
+ Beside :meth:`payload` since RK1170 — one answer, on the record both readings are
561
+ about. It **writes** rather than returning rows, which is the one exception this task
562
+ leaves standing: a finding's remedy is fetched per finding and the mechanical class is
563
+ counted while the rest are printed, so building the whole report as a list would hold
564
+ a corpus-sized report in memory to hand it straight to `print`.
565
+
566
+ `quiet` is the caller's: what it silences is the *body*, never the summary and never
567
+ the refusals, because a pass that could not prove its own output wrote nothing.
568
+ """
569
+ _report_rows(config, self, applied, root, quiet)
570
+
571
+ def payload(self, config: Config, applied: Fix, root: str) -> dict[str, object]:
572
+ """The same answer as data, rooted first (RK299).
573
+
574
+ Every path in it is relative to `root`, and a payload a second tool files against the
575
+ wrong project is worse than one it cannot file at all — so the key comes first, spelled
576
+ the way `install --json` already spells it.
577
+ """
578
+ return _lint_json(config, self, applied, root)
579
+
580
+ def codes(self) -> dict[str, int]:
581
+ """Findings per code, most first — the summary a report of ninety is read by."""
582
+ found: dict[str, int] = {}
583
+ for finding in self.findings:
584
+ found[finding.code] = found.get(finding.code, 0) + 1
585
+ return dict(sorted(found.items(), key=lambda pair: (-pair[1], pair[0])))
586
+
587
+
588
+ def lint(
589
+ config: Config,
590
+ since: str | None = None,
591
+ baseline: str | None = None,
592
+ at: str | None = None,
593
+ ) -> Report:
594
+ """Read every governed file and return every defect. Writes nothing, ever.
595
+
596
+ ``at`` runs the whole gate over a **revision** instead of the working tree (RK210) —
597
+ the read ``baseline`` already makes, given a name so a caller can make it alone. Both
598
+ ends move together, which is the point: the governed files come from the revision *and*
599
+ so does the repository the path check asks about, so nothing in the answer is half about
600
+ this afternoon. Library-only, with no flag beside it: `--baseline` is the question a
601
+ person asks at a terminal, and "what did the gate say at a revision" has one caller —
602
+ the pinned-corpus fixture, whose whole difficulty was that a config can carry one root
603
+ and a pinned run needs the governed files copied and the tree left where git can read it.
604
+
605
+ ``since`` adds the checks that are about a *change* rather than a state — a section edited
606
+ without its line (RK36), and a block this change emptied or reopened (RK269) — against a
607
+ revision, `HEAD` in a pre-commit hook and the base branch in CI. Both are notes, and both
608
+ are only askable of a diff: as states they are "somebody edited prose once" and "this
609
+ block is empty", which are true forever and read by nobody.
610
+
611
+ ``baseline`` answers the other question about a change (RK84): the same gate is run over
612
+ the governed files as they were at that revision, and what comes back is the excess —
613
+ so a repository with standing debt gets an exit code about *its own* commit. The two
614
+ compose, and the baseline run makes no ``since`` comparison of its own: a note about a
615
+ section edited since a ref is about this working tree either way.
616
+ """
617
+ if at is not None and not resolves(config, at):
618
+ raise HistoryUnavailable(f"{at} is not a revision this repository knows")
619
+ report = _examine(config, since=since, tree=Tree(config, at))
620
+ if baseline is None:
621
+ return report
622
+ if not resolves(config, baseline):
623
+ # Unlike `since`, this one cannot degrade to silence: the exit code is the answer,
624
+ # and a run that could not read its baseline would report the whole debt as new.
625
+ raise HistoryUnavailable(f"{baseline} is not a revision this repository knows")
626
+ return _subtract(
627
+ report, _examine(config, since=None, tree=Tree(config, baseline)), baseline
628
+ )
629
+
630
+
631
+ def _examine(config: Config, since: str | None, tree: Tree) -> Report:
632
+ """Every check, over whichever tree is being judged.
633
+
634
+ A **loop over a declared domain** since RK1172, where it was 21 hand-wired calls whose scan
635
+ kind lived in their parameter lists. What each rule reads is now a field on it, so the five
636
+ inputs are built once here and each kind's iteration — the whole tree, every line-bearing
637
+ role, one role, the prose with its anchor index — is written once below rather than at every
638
+ call site. Adding a rule that scans something new says so; adding one that scans something
639
+ already known costs a row.
640
+ """
641
+ documents: dict[str, Document] = {}
642
+ for role in LINE_ROLES:
643
+ document = tree.document(role)
644
+ if document is not None:
645
+ documents[role] = document
646
+ prose: dict[str, Document] = {}
647
+ for role in PROSE_ROLES:
648
+ document = tree.document(role)
649
+ if document is not None:
650
+ prose[role] = document
651
+ anchors = {role: anchored(document) for role, document in prose.items()}
652
+ sections = tuple(section for found in anchors.values() for section in found)
653
+ scanned = _Scan(
654
+ config=config,
655
+ tree=tree,
656
+ documents=documents,
657
+ prose=prose,
658
+ anchors=anchors,
659
+ since=since,
660
+ # Read before the rules that want it, and not a check: a projection target is a fact
661
+ # about the tree that two rules and the file list all ask for (RK1110).
662
+ targets=_targets(config, tree),
663
+ )
664
+
665
+ findings: list[Finding] = []
666
+ notes: list[Note] = []
667
+ for rule in _rules():
668
+ for one in rule.run(scanned):
669
+ (notes if isinstance(one, Note) else findings).append(one)
670
+
671
+ targets = scanned.targets
672
+ checked = _checked(config, documents, prose, targets)
673
+ # The second phase, run as the list it is (RK1172). Every rule above reads the *project*;
674
+ # these three read what those produced — a whole file's worth of findings is evidence about
675
+ # the rule rather than about a line (RK1068), what another finding already explains is not a
676
+ # second finding, and the printed order is a fact about the report. Nested calls said the
677
+ # same thing and said it inside out: `_ordered(_untainted(findings), checked)` puts the last
678
+ # step first, and where a fourth fold goes was a question about parentheses.
679
+ for fold in _FOLDS:
680
+ findings = list(fold(findings, config=config, documents=documents, checked=checked))
681
+ return Report(
682
+ findings=tuple(findings),
683
+ checked=checked,
684
+ lines=sum(len(d.entries) for d in documents.values()),
685
+ sections=len(sections),
686
+ budgets=len(config.budgets),
687
+ notes=tuple(notes),
688
+ )
689
+
690
+
691
+ @dataclass(frozen=True, slots=True)
692
+ class _Scan:
693
+ """Every input a rule can read, built once (RK1172).
694
+
695
+ The five kinds the measurement found — the governed **tree**, the **documents** carrying task
696
+ lines, the **prose** files, the **anchor** index derived from them, and a git **revision** —
697
+ plus the projection targets, which are a reading of the tree that three rules share.
698
+
699
+ One record and not a parameter list, so a rule that starts reading a second input changes its
700
+ own row and nothing else: the signature `(config, documents, prose, targets)` was the fourth
701
+ shape invented at a call site, and each new one made `_examine` the only place that knew.
702
+ """
703
+
704
+ config: Config
705
+ tree: Tree
706
+ documents: dict[str, Document]
707
+ prose: dict[str, Document]
708
+ anchors: dict[str, tuple[Section, ...]]
709
+ since: str | None
710
+ targets: tuple[Target, ...]
711
+
712
+ @property
713
+ def governed(self) -> dict[str, Document]:
714
+ """Both halves, for the rules decided against the whole set and not one file (RK417)."""
715
+ return {**self.documents, **self.prose}
716
+
717
+
718
+ @dataclass(frozen=True, slots=True)
719
+ class _Rule:
720
+ """One gate rule: what it reads, and what it reports (RK1172).
721
+
722
+ `remedying.py` has been a table keyed by code since RK420, and its argument — that a central
723
+ domain is what a test can be total over — was only half applied: the *remedy* was a table and
724
+ the *check* was sixty functions with signatures invented where they were called.
725
+
726
+ :attr:`reads` is the field that removes the hand-wiring. It names one of the kinds
727
+ :class:`_Scan` holds, and the loop below turns that name into the iteration: `role` runs the
728
+ rule once per line-bearing document, `prose_role` once per prose file, `whole` once. A rule
729
+ that fits none of them is the evidence the set is wrong, which is what this task asked for.
730
+ """
731
+
732
+ reads: str
733
+ run: Callable[[_Scan], Sequence[Finding | Note]]
734
+
735
+
736
+ # Cached rather than built at import: `within` and half the rules below are defined further down
737
+ # this file, and a domain whose construction depended on definition order would break when a rule
738
+ # moves. One call, and the tuple is a value a test can be total over.
739
+ @functools.lru_cache(maxsize=1)
740
+ def _rules() -> tuple[_Rule, ...]:
741
+ """The domain, in the order it runs (RK1172).
742
+
743
+ Order is the reader's convenience and not a rule's requirement: `_ordered` sorts the report by
744
+ file and line, and the two folds before it read the whole population — so nothing here depends
745
+ on running before anything else, which is what makes a declared list safe.
746
+ """
747
+
748
+ def per_role(one: Callable[[Config, str, Document], Sequence[Finding]]) -> Callable[[_Scan], list[Finding]]:
749
+ return lambda scan: [
750
+ found
751
+ for role, document in scan.documents.items()
752
+ for found in one(scan.config, role, document)
753
+ ]
754
+
755
+ def characters(scan: _Scan) -> list[Finding]:
756
+ # The character pass is a second walk over the same file, so the rule `within` holds has
757
+ # to be read here too or the 3,301 findings it exists to replace come back from the other
758
+ # side (RK451). The same predicate and not a second statement of it: `within` owns what
759
+ # "not text" means and this asks it.
760
+ return [
761
+ found
762
+ for role, document in scan.documents.items()
763
+ if not _voided(document)
764
+ for found in _characters(scan.config, role, document)
765
+ ]
766
+
767
+ def resolved(scan: _Scan) -> list[Finding]:
768
+ if not scan.prose:
769
+ return []
770
+ found = list(_pointers(scan.config, scan.documents, scan.anchors))
771
+ found += _citations(scan.config, scan.prose, scan.anchors)
772
+ found += _crossing(scan.config, scan.prose, scan.anchors)
773
+ # The fourth kind of citation (RK1380), asked of every governed file and not of the
774
+ # prose ones alone: a law is cited from a ledger sentence and a roadmap `why` as
775
+ # readily as from a design.
776
+ found += _laws(scan.config, scan.documents, scan.prose)
777
+ for role, document in scan.prose.items():
778
+ found += _orphans(
779
+ scan.config, scan.documents, document, scan.anchors, role=role
780
+ )
781
+ return found
782
+
783
+ def against_baseline(scan: _Scan) -> list[Note]:
784
+ if scan.since is None:
785
+ return []
786
+ found = list(_turned(scan.config, scan.documents, scan.since))
787
+ if scan.prose:
788
+ found += _unpaired(
789
+ scan.config, scan.anchors.get("improvements", ()), scan.since
790
+ )
791
+ # And the mirror of it (RK1228): prose that moved without its line, then source
792
+ # that moved under a line nobody closed.
793
+ found += _worked(
794
+ scan.config,
795
+ scan.documents,
796
+ scan.anchors.get("improvements", ()),
797
+ scan.since,
798
+ )
799
+ return found
800
+
801
+ def budgeted(scan: _Scan) -> list[Finding | Note]:
802
+ found, said = _budgets(scan.config, scan.tree)
803
+ return [*found, *said]
804
+
805
+ def queued(scan: _Scan) -> list[Finding | Note]:
806
+ found, said = _queue(scan.config, scan.documents)
807
+ return [*found, *said]
808
+
809
+ return (
810
+ _Rule("tree", lambda scan: _absent(scan.config, scan.tree)),
811
+ _Rule("role", per_role(within)),
812
+ _Rule("role", characters),
813
+ _Rule("documents", lambda scan: _across(scan.config, scan.documents)),
814
+ _Rule("documents", lambda scan: _scope(scan.config, scan.documents.get("roadmap"))),
815
+ # The positive twin of the rule above (RK1265), read from the same document and
816
+ # opt-in on its own declaration: a project may govern one list and not the other.
817
+ _Rule(
818
+ "documents",
819
+ lambda scan: _criteria(
820
+ scan.config, scan.documents.get("roadmap"), scan.documents
821
+ ),
822
+ ),
823
+ _Rule("documents", queued),
824
+ _Rule("documents", lambda scan: _collective(scan.config, scan.documents)),
825
+ _Rule("tree", lambda scan: _disagreeing(scan.config, scan.tree)),
826
+ _Rule("revision", against_baseline),
827
+ _Rule("prose_role", lambda scan: [
828
+ found
829
+ for role, document in scan.prose.items()
830
+ for found in _marks(scan.config, role, document)
831
+ ]),
832
+ _Rule("anchors", resolved),
833
+ _Rule("governed", lambda scan: _repeated(scan.config, scan.governed)),
834
+ _Rule("tree", lambda scan: _paths(scan.config, scan.documents, scan.tree)),
835
+ _Rule("governed", lambda scan: _projections(scan.config, scan.governed, scan.targets)),
836
+ _Rule("tree", budgeted),
837
+ # Its own rule and not a tail of `budgeted` (RK1192): what a surface costs and whether
838
+ # it is the one this engine ships are two questions, and a check folded into another's
839
+ # return is one nobody finds by reading the list of what this gate asks.
840
+ _Rule("config", lambda scan: _wired(scan.config)),
841
+ # And the other half of the same pin (RK1238): `_wired` asks whether the surfaces are
842
+ # behind the engine, and this asks whether the engine judging them is behind the one
843
+ # the project chose.
844
+ _Rule("config", lambda scan: _judged(scan.config)),
845
+ )
846
+
847
+
848
+
849
+ def _folding(name: str) -> Callable[..., Any]:
850
+ """One rule of the reporting phase, adapted to the one shape a fold has (RK1172).
851
+
852
+ The three read different things — a document set, the findings alone, the file order — so
853
+ an adapter is what lets the phase be a list. Written here rather than by changing each
854
+ rule's own signature: what a rule wants is a fact about that rule, and a uniform parameter
855
+ list that every caller then ignores half of is the hand-wiring one layer up.
856
+ """
857
+ def fold(findings: list[Finding], **inputs: Any) -> Sequence[Finding]:
858
+ if name == "grammatical":
859
+ return _grammatical(inputs["config"], inputs["documents"], findings)
860
+ if name == "untainted":
861
+ return _untainted(findings)
862
+ return _ordered(findings, inputs["checked"])
863
+
864
+ fold.__name__ = f"fold_{name}"
865
+ return fold
866
+
867
+
868
+ #: The reporting phase, in the order it runs (RK1172). The fold before the drop before the sort,
869
+ #: because each reads what the one before it left: the inference needs the whole population, the
870
+ #: drop needs the fold's own finding to exist before it can suppress what that explains, and the
871
+ #: order is over whatever survived. Three names in a list, where the order used to be the shape
872
+ #: of an expression.
873
+ _FOLDS: tuple[Callable[..., Sequence[Finding]], ...] = (
874
+ _folding("grammatical"),
875
+ _folding("untainted"),
876
+ _folding("ordered"),
877
+ )
878
+
879
+
880
+ def _checked(
881
+ config: Config,
882
+ documents: dict[str, Document],
883
+ prose: dict[str, Document],
884
+ targets: tuple[Target, ...],
885
+ ) -> tuple[str, ...]:
886
+ """Every file this run judged, in the order its findings print in (RK365).
887
+
888
+ One place, because the list is two things at once: what the report *says* was read, and
889
+ the sort key :func:`_ordered` applies to every finding. It was appended to at five points
890
+ down `_examine`'s body, three of them conditional, so the order findings print in was
891
+ decided by where a check happened to be added rather than by anything anybody wrote down.
892
+
893
+ The order is the reader's. The line-bearing files first, because they are what this format
894
+ is about; the prose they point into next; then the files this tool does not own — a
895
+ projection target, an instruction file with a budget — and `roadkeep.toml` last, judged
896
+ only where it carries a queue (RK354) and not a governed file at all.
897
+
898
+ Conditional membership is the rule and not the exception: a budgeted file is here because
899
+ `[budgets]` names it, a target because a marked block asked to be projected into it, and
900
+ the config because it declared an order. What decides each is one expression, all four in
901
+ view of each other.
902
+ """
903
+ checked = [config.relative(config.path(role)) for role in documents]
904
+ checked.extend(config.relative(config.path(role)) for role in prose)
905
+ checked.extend(target.where for target in targets)
906
+ checked.extend(config.relative(budget.path) for budget in config.budgets)
907
+ # By path and not by role (RK1361): `decisions` is read twice — once for its lines and
908
+ # once for its sections — and the report is a list of *files*, so naming it twice said
909
+ # this run judged five where it judged four. The order is still the first mention's,
910
+ # which is the reader's order above: a file sorts where it was first read.
911
+ checked = list(dict.fromkeys(checked))
912
+ # The config is judged where it declares a queue (RK354) and where it declares what a
913
+ # served tool may cost (RK1059) — the second being the one budget whose subject is not
914
+ # a file, so `roadkeep.toml` is both what declared it and the only place to name.
915
+ if config.priority or config.tool_characters is not None:
916
+ checked.append(_configured(config))
917
+ return tuple(checked)
918
+
919
+
920
+ #: How many lines a file must hold before *all* of them failing the round-trip reads as the
921
+ #: rule rather than the lines (RK1068). Two, because one line disagreeing with the schema is
922
+ #: an edited line and is exactly what `line.non-canonical` is for — the inference is about a
923
+ #: population, and a population of one is a line.
924
+ _A_POPULATION = 2
925
+
926
+
927
+ def _grammatical(
928
+ config: Config, documents: Mapping[str, Document], findings: list[Finding]
929
+ ) -> list[Finding]:
930
+ """Fold a whole file's worth of non-canonical lines into one defect at the rule (RK1068).
931
+
932
+ The cost a declared grammar does not remove, caught at the end it is actually about. A
933
+ grammar given as data (RK1064) can be one that cannot read back what it writes, and the
934
+ round-trip guard then refuses the whole file — correctly and by law — so a separator
935
+ declared one character too loose presents as **every line in the corpus** being
936
+ non-canonical, and the report blames a hundred lines for the one line of config that
937
+ broke them.
938
+
939
+ **Both ways a line can fail it**, which measuring made the point of: a declaration too
940
+ *loose* renders what it read differently and the file comes back `line.non-canonical`,
941
+ and one too *narrow* — a slot dropped that the file has — stops matching at all and the
942
+ same file comes back `line.unparsed`. The second is what a wrong `drop` actually
943
+ produces, so a fold that watched only the first would miss the failure it was written
944
+ for. A bullet counts either way, which is why the population is entries **and** rejects.
945
+
946
+ The inference is deliberately narrow: *every* line-shaped bullet in a role's file, and
947
+ at least :data:`_A_POPULATION` of them. One line differing from its rendering is an
948
+ edited line and is what `line.non-canonical` already says; a file where not one bullet
949
+ survives is not a file somebody hand-edited into that state.
950
+
951
+ Paired with RK1067, which is what makes the answer actionable rather than merely
952
+ correct: the finding lands on the declaration's own line, so the report reads as one
953
+ defect at one config line instead of a corpus that stopped conforming.
954
+ """
955
+ explained = next(rule for rule in EXPLAINS if rule.by == "grammar.")
956
+ out = list(findings)
957
+ for role, document in documents.items():
958
+ population = len(document.entries) + len(document.rejects)
959
+ if population < _A_POPULATION:
960
+ continue
961
+ where = config.relative(config.path(role))
962
+ # Counted against the same rule that will suppress them (RK1070), so "which failures
963
+ # is this an explanation of" is one declaration and not a literal here and a
964
+ # predicate there. Nothing is removed by this function: it *reports*, and
965
+ # :func:`_untainted` drops what the report explains — which is what keeps the
966
+ # removal from being identity over a dataclass, where two findings that compare
967
+ # equal on one line went together or not at all.
968
+ broken = sum(
969
+ 1 for finding in out if finding.file == where and explained.explains(finding)
970
+ )
971
+ if broken < population:
972
+ continue
973
+ declared = config.grammars.get(role)
974
+ out.append(
975
+ Finding(
976
+ "grammar.unreadable",
977
+ _configured(config) if declared else where,
978
+ f"the grammar for {role} fails on {population} of {population} bullets: "
979
+ f"this is the rule and not the lines, and a file where none survives is "
980
+ f"not one somebody hand-edited"
981
+ + (
982
+ f" — `[grammar.{role}]` is what to look at"
983
+ if declared
984
+ else " — no [grammar] is declared, so the file was written under "
985
+ "another format"
986
+ ),
987
+ subject=role,
988
+ # What it covers, which is not where it is filed (RK1070): the declaration
989
+ # is in the config and the lines it explains are in the governed file.
990
+ about=where,
991
+ )
992
+ )
993
+ return out
994
+
995
+
996
+ @dataclass(frozen=True, slots=True)
997
+ class Explains:
998
+ """One finding that makes another one noise, declared (RK1070).
999
+
1000
+ Two checks in this module do this and neither said so: a codepoint nobody typed makes
1001
+ every other diagnosis of that line a consequence (RK34), and a grammar that fails on a
1002
+ whole file makes every per-line failure in it an effect (RK1068). Both were a predicate
1003
+ and a set comprehension written out at the call site — so a third arriving is folded
1004
+ only if somebody remembers, and *at what scope* was a tuple that happened to be built
1005
+ the same way twice.
1006
+
1007
+ :attr:`scope` is the whole of what differs between the two. A codepoint explains the
1008
+ other findings **on its line**, because the byte is in that line and the next one is
1009
+ judged normally; a grammar explains them **in its file**, because the rule is what
1010
+ every line in it was read under. Naming that is what makes the two one mechanism rather
1011
+ than two loops that resemble each other.
1012
+ """
1013
+
1014
+ #: The code that explains, or its prefix where the family is what explains — `char.`
1015
+ #: is nine codes and every one of them makes the same point about the line it is on.
1016
+ by: str
1017
+ #: What it explains, matched the same way.
1018
+ over: tuple[str, ...]
1019
+ #: `line` or `file` — how far the explanation reaches.
1020
+ scope: str
1021
+
1022
+ def explains(self, finding: Finding) -> bool:
1023
+ return any(finding.code.startswith(code) for code in self.over)
1024
+
1025
+ def spoken_by(self, finding: Finding) -> bool:
1026
+ return finding.code.startswith(self.by)
1027
+
1028
+ def where(self, finding: Finding, *, speaking: bool = False) -> tuple[str, int | None]:
1029
+ """The key two findings share when one explains the other.
1030
+
1031
+ ``speaking`` lets an explanation be filed somewhere other than what it is about,
1032
+ which the grammar one has to be: it lands on `roadkeep.toml`, where the declaration
1033
+ that broke the file is and where the edit goes (RK1067), and it explains findings in
1034
+ the file it names. `about` carries that second address, so the two are not confused
1035
+ — the finding's own `file` is where a reader clicks and never what it covers.
1036
+ """
1037
+ under = finding.about if speaking and finding.about else finding.file
1038
+ return (under, finding.lineno if self.scope == "line" else None)
1039
+
1040
+
1041
+ #: Every explanation this gate makes, which is the index RK1070 asked for: a reader asking
1042
+ #: "does a finding suppress another" reads four lines rather than two functions.
1043
+ EXPLAINS: tuple[Explains, ...] = (
1044
+ # A line carrying a byte nobody typed is not a line this format can judge (RK34): the
1045
+ # parser read a string the author cannot see, so every other diagnosis of it names a
1046
+ # consequence. Report the codepoint; the rest is decidable on the next run.
1047
+ Explains(by="char.", over=("",), scope="line"),
1048
+ # A rule that fails on every bullet in a file is what broke them (RK1068), so the
1049
+ # per-line failures are the effect and the report is one defect at one declaration.
1050
+ Explains(
1051
+ by="grammar.",
1052
+ over=("line.non-canonical", "line.unparsed"),
1053
+ scope="file",
1054
+ ),
1055
+ )
1056
+
1057
+
1058
+ def _untainted(findings: list[Finding]) -> list[Finding]:
1059
+ """Every finding except the ones another already explains (RK34, RK1068, RK1070).
1060
+
1061
+ One pass over :data:`EXPLAINS` rather than a function per relation: what each row says
1062
+ is which code speaks, which it speaks over and how far, and the loop under that is the
1063
+ same four lines it always was. An explanation never suppresses another explanation —
1064
+ a codepoint on a line whose file has a bad grammar is still worth reporting, both being
1065
+ causes rather than effects.
1066
+ """
1067
+ kept = list(findings)
1068
+ for rule in EXPLAINS:
1069
+ # A line-scoped rule needs a line to be about: a finding filed against the file
1070
+ # itself explains nothing on any particular one, and taking it as evidence would
1071
+ # silence every other file-level finding there.
1072
+ spoken = {
1073
+ rule.where(f, speaking=True)
1074
+ for f in kept
1075
+ if rule.spoken_by(f) and (rule.scope == "file" or f.lineno)
1076
+ }
1077
+ kept = [
1078
+ f
1079
+ for f in kept
1080
+ # Never an explanation: a codepoint on a line whose file has a bad grammar is
1081
+ # still worth reporting, both being causes rather than effects of each other.
1082
+ if any(one.spoken_by(f) for one in EXPLAINS)
1083
+ or not rule.explains(f)
1084
+ or rule.where(f) not in spoken
1085
+ ]
1086
+ return kept
1087
+
1088
+
1089
+ def _ordered(findings: list[Finding], checked: tuple[str, ...]) -> tuple[Finding, ...]:
1090
+ """Every finding, in the order the report prints them (RK365).
1091
+
1092
+ `checked` **is** the order, so a file sorts where the reader was told it was read, and the
1093
+ two halves of the report cannot disagree about which file came first.
1094
+
1095
+ A finding whose file the list does not name sorts **last**, by falling off the end of the
1096
+ index. That was right by accident until RK354 put the config in `checked`, and it is stated
1097
+ here rather than left in a `dict.get` default: the report is read against the list, so
1098
+ anything the list does not name belongs after everything it does.
1099
+ """
1100
+ order = {name: index for index, name in enumerate(checked)}
1101
+ return tuple(
1102
+ sorted(findings, key=lambda f: (order.get(f.file, len(order)), f.lineno or 0, f.code))
1103
+ )
1104
+
1105
+
1106
+ def _subtract(now: Report, before: Report, rev: str) -> Report:
1107
+ """The findings this working tree added, and the ones it inherited (RK84).
1108
+
1109
+ **Counted per (file, code, task), and never per line number.** A line moves when
1110
+ anything above it is inserted, so an identity that included the position would report
1111
+ the whole file as new the first time a task was added at the top — which is the failure
1112
+ mode that makes a delta gate worth less than no gate. What is compared is therefore how
1113
+ many findings of one kind one line has, and the excess is what this change wrote.
1114
+
1115
+ Within a kind the ones that did not move are forgiven first. It changes no count; it
1116
+ means the finding *reported* is the one at a position the revision did not have, which
1117
+ is the one a reader is being sent to look at.
1118
+ """
1119
+ standing: dict[tuple[str, str, str], list[Finding]] = {}
1120
+ for finding in before.findings:
1121
+ standing.setdefault(_debt(finding), []).append(finding)
1122
+
1123
+ here: dict[tuple[str, str, str], list[int]] = {}
1124
+ for index, finding in enumerate(now.findings):
1125
+ here.setdefault(_debt(finding), []).append(index)
1126
+
1127
+ forgiven: set[int] = set()
1128
+ resolved: list[Finding] = []
1129
+ for key, indices in here.items():
1130
+ there = standing.pop(key, [])
1131
+ places = {finding.lineno for finding in there}
1132
+ stayed = [i for i in indices if now.findings[i].lineno in places]
1133
+ moved = [i for i in indices if now.findings[i].lineno not in places]
1134
+ forgiven.update((stayed + moved)[: len(there)])
1135
+ resolved.extend(there[len(indices) :])
1136
+ for left in standing.values():
1137
+ resolved.extend(left)
1138
+
1139
+ return replace(
1140
+ now,
1141
+ findings=tuple(f for i, f in enumerate(now.findings) if i not in forgiven),
1142
+ baseline=Baseline(
1143
+ rev=rev,
1144
+ forgiven=tuple(now.findings[i] for i in sorted(forgiven)),
1145
+ resolved=tuple(resolved),
1146
+ ),
1147
+ )
1148
+
1149
+
1150
+ def _debt(finding: Finding) -> tuple[str, str, str]:
1151
+ """What makes two findings the same standing problem: one kind, one line's worth."""
1152
+ return (finding.file, finding.code, finding.id)
1153
+
1154
+
1155
+ def _characters(config: Config, role: str, document: Document) -> list[Finding]:
1156
+ """Name the byte, not its consequence (RK34).
1157
+
1158
+ The format is structural Unicode — `—`, `→`, `§` and four emoji markers — so every
1159
+ lookalike a human editor produces is invisible exactly where it fails. Measured
1160
+ against this parser: `📋` plus U+FE0F is reported as `status.unknown`, which prints as
1161
+ "'📋️' is not one of 📋"; a no-break space before the pointer is reported as
1162
+ `why.no-terminator`, naming the one thing the line does not lack. Both are correct and
1163
+ unusable, because the character that caused them cannot be seen.
1164
+
1165
+ Only the line-bearing files. A paragraph has no parse for an invisible byte to corrupt,
1166
+ and §RK34 had to *quote* a variation selector to explain the defect — which a scan over
1167
+ prose would have reported as the defect itself.
1168
+
1169
+ **Which codepoints occur is asked before where they are** (RK227). The rule stays
1170
+ :func:`suspect`'s — a Unicode category and not a hand-kept list, so a format character
1171
+ nobody has met yet is still caught — but it is asked once per *distinct* codepoint
1172
+ instead of once per character: 800215 calls over Turing's ledger, every answer no, for
1173
+ 148 ms of a 660 ms gate. A clean file leaves the walk below unentered, and every file
1174
+ this gate passes is a clean file.
1175
+
1176
+ The bodies and not the raw lines, because a line ending is `Cc` and therefore the one
1177
+ thing every file would have flagged — :func:`_endings` is what judges those, and a
1178
+ sweep that always said "dirty" would have been the loop with a longer preamble.
1179
+ """
1180
+ file = config.relative(config.path(role))
1181
+ ids = {entry.lineno: entry.task.id for entry in document.entries}
1182
+ out = _endings(document, file)
1183
+ bodies = [raw.rstrip("\r\n") for raw in document.lines]
1184
+ # `indent=False`, so a tab counts as a candidate wherever it sits; the walk is what
1185
+ # knows whether one is indentation, which is the only place it reads as text (RK146).
1186
+ candidates = {char for char in set("".join(bodies)) if suspect(char)}
1187
+ if not candidates:
1188
+ return out
1189
+ found = re.compile(f"[{''.join(re.escape(char) for char in sorted(candidates))}]")
1190
+ for number, body in enumerate(bodies, start=1):
1191
+ head = indentation(body)
1192
+ for match in found.finditer(body):
1193
+ column = match.start() + 1
1194
+ if not suspect(match.group(), indent=column <= head):
1195
+ continue
1196
+ out.append(_named(file, number, column, match.group(), ids.get(number, "")))
1197
+ return out
1198
+
1199
+
1200
+ #: The one codepoint a prose file is swept for (RK1028). Not the rest of :func:`suspect`'s
1201
+ #: domain, and §RK34 is why: a design explaining a lookalike has to **quote** it, so a scan
1202
+ #: over prose would report the paragraph that documents the defect as the defect. A mark is
1203
+ #: the exception that proves the rule — no design pastes one, they name it `U+FEFF`, and no
1204
+ #: keyboard produces it. What does produce it is every mainstream Windows editor, ahead of a
1205
+ #: file `--body-file` then reads whole.
1206
+ MARK = ""
1207
+
1208
+
1209
+ def _marks(config: Config, role: str, document: Document) -> list[Finding]:
1210
+ """A byte-order mark anywhere in a prose file, which is never something anybody wrote.
1211
+
1212
+ The gate half of RK1028. The writer now strips one at position 1 of a stream or a file,
1213
+ where it is the encoder's; this is the file that already carries one — from an editor,
1214
+ from a paste, from the route that was open before the strip — and it is invisible by
1215
+ definition, so the first reader to notice is whoever greps a heading and finds nothing.
1216
+
1217
+ Anywhere and not only at the start, because that is where the hole was: a body read from
1218
+ a path lands **mid-file**, under whatever heading the section was placed at, and a rule
1219
+ about position 1 would have reported nothing. The code is `char.bom` either way — one
1220
+ byte, one meaning, one door.
1221
+ """
1222
+ file = config.relative(config.path(role))
1223
+ out: list[Finding] = []
1224
+ for number, raw in enumerate(document.lines, start=1):
1225
+ column = raw.find(MARK)
1226
+ while column >= 0:
1227
+ out.append(
1228
+ Finding(
1229
+ "char.bom",
1230
+ file,
1231
+ "U+FEFF byte-order mark inside the prose: not text, invisible in an "
1232
+ "editor, and a byte the round-trip compares",
1233
+ number,
1234
+ "",
1235
+ column + 1,
1236
+ )
1237
+ )
1238
+ column = raw.find(MARK, column + 1)
1239
+ return out
1240
+
1241
+
1242
+ def _named(file: str, lineno: int, column: int, char: str, task_id: str) -> Finding:
1243
+ point = f"U+{ord(char):04X}"
1244
+ name = unicodedata.name(char, "unnamed control character").lower()
1245
+ if lineno == 1 and column == 1 and char == "":
1246
+ # Its own answer: a byte-order mark is not text at all, and it lands on whatever
1247
+ # the first line happens to be — which is a heading, so nothing else reports it.
1248
+ return Finding(
1249
+ "char.bom",
1250
+ file,
1251
+ f"{point} byte-order mark at the start of the file: not text, and a byte the "
1252
+ f"round-trip compares",
1253
+ lineno,
1254
+ task_id,
1255
+ column,
1256
+ )
1257
+ # The code and the clause are the schema's (RK499), which is where the door raises the
1258
+ # same three about a *field*: a tab past the indentation is a separator this format does
1259
+ # not write, a `Zs` renders as a space and is not one, and everything else cannot be seen.
1260
+ # What is this function's own is the place — a line and a column, which is what a report
1261
+ # is read for and what an argument has none of.
1262
+ code, because = CODEPOINT_KINDS[codepoint_kind(char)]
1263
+ named = "tab" if char == TAB else name
1264
+ return Finding(code, file, f"{point} {named} at column {column}: {because}", lineno, task_id, column)
1265
+
1266
+
1267
+ def _endings(document: Document, file: str) -> list[Finding]:
1268
+ """Two kinds of line ending in one file — one line edited by something else.
1269
+
1270
+ A file that is *uniformly* CRLF is not a defect and is not reported: `Document` keeps
1271
+ every ending verbatim, so it round-trips, and a repository that checks out CRLF is a
1272
+ configuration rather than a mistake (L6). Mixed is the byte nobody typed.
1273
+ """
1274
+ found: dict[str, int] = {}
1275
+ for line in document.lines:
1276
+ terminator = ending(line)
1277
+ if terminator:
1278
+ found[terminator] = found.get(terminator, 0) + 1
1279
+ if len(found) < 2:
1280
+ return []
1281
+ spelled = ", ".join(
1282
+ f"{count}× {_ENDING_NAMES[terminator]}" for terminator, count in sorted(found.items())
1283
+ )
1284
+ return [
1285
+ Finding(
1286
+ "char.mixed-endings",
1287
+ file,
1288
+ f"two kinds of line ending in one file ({spelled}): one of them was written "
1289
+ f"by something that is not this tool, and the round-trip compares bytes",
1290
+ )
1291
+ ]
1292
+
1293
+
1294
+ def _budgets(config: Config, tree: Tree) -> tuple[list[Finding], list[Note]]:
1295
+ """Every always-loaded file, against what it declared it may cost (RK30).
1296
+
1297
+ Measured in bytes off the tree and lines by counting terminators, so nothing here has
1298
+ to decode a file the tool does not govern: a budget is about what a loader pays, and
1299
+ an instruction file is not a format this tool has any business parsing (L4). Off the
1300
+ tree and not off disk for RK84's reason — an `agents.md` pushed over its budget by this
1301
+ change is the finding a baseline exists to keep, and both runs reading the same bytes
1302
+ would forgive it.
1303
+
1304
+ Which is exactly why the count is normalised (RK1105): with no baseline the tree *is*
1305
+ disk, so this read is a working tree's bytes, and with one it is a git blob's — the same
1306
+ gate answering two numbers for one commit, 311 bytes apart on the corpus that found it.
1307
+ `spent` drops the terminator's second byte and the second half of that is here, as a
1308
+ note: the checkout's real cost is stated and never charged.
1309
+ """
1310
+ out: list[Finding] = []
1311
+ notes: list[Note] = []
1312
+ for budget in config.budgets:
1313
+ where = config.relative(budget.path)
1314
+ raw = tree.blob(budget.path)
1315
+ if raw is None:
1316
+ out.append(
1317
+ Finding(
1318
+ "budget.absent",
1319
+ where,
1320
+ "declares a budget and is not on disk: the entry holds nothing",
1321
+ )
1322
+ )
1323
+ continue
1324
+ # One measurement, called and not repeated (RK345): `budget --file` reports the room
1325
+ # this refuses, and a second count here is a gate disagreeing with the read that
1326
+ # composed the edit.
1327
+ measured_in = spent(raw)
1328
+ for unit, measured, allowed in (
1329
+ ("lines", measured_in["lines"], budget.lines),
1330
+ ("bytes", measured_in["bytes"], budget.bytes),
1331
+ ):
1332
+ if allowed is not None and measured > allowed:
1333
+ out.append(
1334
+ Finding(
1335
+ f"budget.{unit}",
1336
+ where,
1337
+ f"{measured} {unit}, budget is {allowed}: this is loaded every "
1338
+ f"turn, so the overrun is paid on every turn",
1339
+ )
1340
+ )
1341
+ extra = translated(raw)
1342
+ if extra and budget.bytes is not None:
1343
+ notes.append(
1344
+ Note(
1345
+ "budget.translated",
1346
+ where,
1347
+ f"{measured_in['bytes']} bytes counted and {extra} more on this "
1348
+ f"checkout, whose lines end CRLF: the ceiling is the commit's, so a "
1349
+ f"number declared against a working tree has that much room it never "
1350
+ f"voted for",
1351
+ subject=where,
1352
+ )
1353
+ )
1354
+ over, said = _reads(config)
1355
+ return out + _served(config) + over, notes + said
1356
+
1357
+
1358
+ def _reads(config: Config) -> tuple[list[Finding], list[Note]]:
1359
+ """The briefs a session is about to ask for, against what one may cost (RK1286, RK1287).
1360
+
1361
+ `_served`' argument about a **read** rather than about the schema. RK30 held the resident
1362
+ prose, RK1059 the served surface, and the one answer this project recommends *over*
1363
+ reading the file had no figure at all — while growing four arithmetic rows in one session,
1364
+ each argued and none counted.
1365
+
1366
+ **Bounded, and it says by how much.** A brief costs tens of milliseconds, so pricing every
1367
+ open line put a project that declared a ceiling at O(open) of them on every commit. What
1368
+ this prices is `pick`'s own answer and the alternatives it already names — the reads a
1369
+ session is about to make — and the note says how many lines that left out and which
1370
+ command prices them all. Never a silent cap: a report that omits without saying so reads
1371
+ as one that covered everything.
1372
+
1373
+ Filed against `roadkeep.toml`, which declared it and is the only file involved — a brief
1374
+ is composed per call and there is no path a reader could open to see it, which is
1375
+ `_served`'s own reason. Silent where nothing is declared, and **composed only there**.
1376
+ """
1377
+ if config.brief_read is None:
1378
+ return [], []
1379
+ from roadkeep.budgeting import brief_budget # noqa: PLC0415 - RK260
1380
+
1381
+ where = config.relative(config.source or config.root)
1382
+ found = brief_budget(config, offered=True)
1383
+ out = [
1384
+ Finding(
1385
+ "read.over",
1386
+ where,
1387
+ f"{one.id}'s brief is {one.characters} characters against a budget of "
1388
+ f"{config.brief_read}: this is the read that replaces reading the file, so one "
1389
+ f"that does not fit a tool result is a task a session opens the roadmap for — "
1390
+ f"`{invocation()} cost --brief` ranks every one and names what each costs",
1391
+ subject=one.id,
1392
+ )
1393
+ for one in found.over
1394
+ ]
1395
+ # A line the ranking could not measure is the one most likely to have been the widest
1396
+ # (RK1288), so its absence is a finding and not a note: `read.over` is derived from this
1397
+ # ranking, and a project can be over its ceiling on a line nothing reported.
1398
+ out += [
1399
+ Finding(
1400
+ "read.unpriced",
1401
+ where,
1402
+ f"{one.id}'s brief would not compose, so it is not in the ranking `[reads] "
1403
+ f"brief` is held against: {one.because} — the widest is the bound, and a line "
1404
+ f"this read could not measure is the shape most likely to be it",
1405
+ subject=one.id,
1406
+ )
1407
+ for one in found.unpriced
1408
+ ]
1409
+ notes = (
1410
+ [
1411
+ Note(
1412
+ "read.priced",
1413
+ where,
1414
+ f"{len(found.briefs)} of {found.open_lines} open line(s) priced against "
1415
+ f"`[reads] brief`"
1416
+ + (f", {len(found.unpriced)} refused" if found.unpriced else "")
1417
+ + f", {found.elided} not asked for — the ones `pick` offers next, so what is "
1418
+ f"left out is what nobody is about to brief, and the next run prices "
1419
+ f"whatever the answer has become; `{invocation()} cost --brief` ranks "
1420
+ f"every one now",
1421
+ )
1422
+ ]
1423
+ # **More left out than priced** (RK1290), which is `_collective`'s shape and not a
1424
+ # tuned ratio: below it this gate saw the majority of the backlog and there is no
1425
+ # surprise to report, and above it the ceiling is held against a minority — which is
1426
+ # the fact worth a line. Without a threshold it fired on every clean run of any real
1427
+ # backlog, and a reader who meets the same sentence every time stops reading the
1428
+ # notes, so the next one that matters arrives under a heading they learnt to skip.
1429
+ #
1430
+ # Never about the **refused**: those are `read.unpriced` findings, and a threshold
1431
+ # here silences nothing this report would otherwise have said.
1432
+ if found.elided > len(found.briefs)
1433
+ else []
1434
+ )
1435
+ return out, notes
1436
+
1437
+
1438
+ def _wired(config: Config) -> list[Note]:
1439
+ """The vendored surfaces behind the engine answering here (RK1192).
1440
+
1441
+ `install --check` already answers this exactly, and that is the whole problem: it is a
1442
+ command nobody thinks to run. Nothing prompts it, no failure names it, and a project
1443
+ reaches it only by already suspecting what it reports.
1444
+
1445
+ Measured on another project. Its committed launcher predated RK1116, so it forwarded
1446
+ `guard` and `mcp` and nothing else; the MCP server had not connected; and the skill that
1447
+ session read named that launcher as the entry point. Every door was shut at once, and the
1448
+ way out was guessing a version directory under the plugin cache — the one route no
1449
+ document mentions, because it is not meant to be one.
1450
+
1451
+ So the gate asks it, being what runs anyway: `lint` fires every turn through the `Stop`
1452
+ hook, it already reports drift between what a file says and what this tool would write,
1453
+ and a wired surface behind the version answering is drift of exactly that kind. The
1454
+ remedy is `install`, which is the complete command, so `repair` closes it too.
1455
+
1456
+ **Against the engine answering here and never the newest one.** :func:`~roadkeep.installing.stale`
1457
+ plans from `_source()`, the checkout this process is, so what is compared is the copy that
1458
+ would do the writing. Three copies are allowed to differ and `engines` is what adjudicates
1459
+ that (RK415); a second opinion here about which version is *right* would be this gate
1460
+ taking a side in a question another verb exists to report.
1461
+
1462
+ **Filed at the surface**, unlike `budget.tool` one function down: there is a path a reader
1463
+ can open, and it is the file that drifted.
1464
+
1465
+ Silent where nothing is vendored, which is every plugin-served project — there is no copy
1466
+ to be behind. Silent too where `[install] pinned` says the version is the project's choice
1467
+ (L6): a finding on every turn about a decision already taken is noise, and a gate carrying
1468
+ noise is one that stops being read.
1469
+
1470
+ Cheap, and measured before it was put on a per-turn path: :func:`~roadkeep.installing.stale`
1471
+ is **0.07 ms** unwired — one `is_file` — and **0.86 ms** wired, against RK176's 43 ms
1472
+ floor. It declines the workflow gauge, which is the 40 ms of that, by the same field that
1473
+ makes the workflow the adopter's after the first write.
1474
+
1475
+ **A note, so the exit code does not move** (RK1308), which is `engine.disagreement`'s rule
1476
+ one function over and for the same reason: what this gate is *for* is whether the governed
1477
+ lines drifted, and whether this checkout's installed surface matches the engine is
1478
+ maintenance — true of the machine rather than of the branch. Observed in pportal,
1479
+ 2026-08-22: `lint` exited 1 on a backlog `ship` had just written and that had drifted in no
1480
+ way at all, reporting `311 line(s), 32 section(s) … clean` in the same breath. That exit
1481
+ code is the whole contract of the CI job this project publishes, so a repository whose only
1482
+ gate is `roadkeep lint` went red on every push, for every contributor.
1483
+
1484
+ The consequence to keep: `repair` walks findings, so it no longer reaches this — and that
1485
+ is the argument rather than a loss. `install` writes into `.claude/` and not into the
1486
+ backlog, so in a project holding one task to one commit it has to become a commit of its
1487
+ own; a repair loop that ran it inside whatever was being shipped is the state this task
1488
+ describes, arrived at from the other side.
1489
+ """
1490
+ if config.install_pinned:
1491
+ return []
1492
+ from roadkeep.installing import stale # noqa: PLC0415 - RK260
1493
+
1494
+ # Every failure inside is silence, as it is for the session-start notice this shares a
1495
+ # reader with (RK82, RK234): a gate that fails because a checkout moved is worse than one
1496
+ # that says nothing, and `install --check` still answers on demand.
1497
+ return [
1498
+ Note(
1499
+ "install.stale",
1500
+ where,
1501
+ f"this surface is behind the roadkeep answering here, so a session reads a "
1502
+ f"skill, hook or launcher older than the engine it names — "
1503
+ f"`{invocation()} install` rewrites the ones this checkout ships",
1504
+ subject=where,
1505
+ )
1506
+ for where in stale(config.root)
1507
+ ]
1508
+
1509
+
1510
+ def _judged(config: Config) -> list[Note]:
1511
+ """Whose rules this verdict is, where the project said which copy's it should be (RK1238).
1512
+
1513
+ RK1235 guards the **pen**: a governed write from a copy behind the pinned one is refused
1514
+ before the lock. The gate was left alone, and it is the same copy — so on a pinned project
1515
+ running a stale engine the writes stop and this keeps answering from rules that have
1516
+ moved. It reports clean, and the action CI runs at its own ref disagrees.
1517
+
1518
+ That is RK1235's failure with the halves swapped, and worse in one way. A refused write is
1519
+ a message, read at the moment somebody asked for something. A gate that passes is
1520
+ **silence** — which is exactly what the shipped `Stop` hook produces on every turn that
1521
+ changed nothing, so there is no moment at which a reader is looking.
1522
+
1523
+ A **note**, and the shape is the whole task. A refusal is wrong: `lint` exiting 2 because a
1524
+ copy is old turns one stale plugin into a repository nobody can commit in, which is the
1525
+ state `guard` is written to survive (RK22). A finding is wrong for RK1192's stated reason:
1526
+ it fires every turn until somebody updates, and a gate carrying noise stops being read.
1527
+ What a note does is qualify the verdict beside it — printed before the findings and before
1528
+ a clean summary alike (RK35) — so a clean report says *whose* clean it is.
1529
+
1530
+ Both of RK1235's conditions and for its reasons: `behind` and never `unpinnable`, because
1531
+ a modified checkout is where a developer lives; and only where `[install] enforced` is
1532
+ declared, that key being the project saying the registered plugin is the copy that should
1533
+ write here (L6, RK1240) rather than this tool guessing at a setup it cannot see. Filed at
1534
+ `roadkeep.toml`, which is where that decision is written and what a reader would open.
1535
+
1536
+ **2 ms**, and that is why it can be on the gate at all: :func:`~roadkeep.installing.behind`
1537
+ compares versions before it asks git anything (RK1237), so the case this fires on — two
1538
+ copies at two versions — is answered without a subprocess.
1539
+ """
1540
+ if not config.install_enforced:
1541
+ return []
1542
+ from roadkeep.installing import behind, engines # noqa: PLC0415 - RK260
1543
+
1544
+ # Silence on every failure inside, as `_wired` is and for its reason (RK82, RK234): a gate
1545
+ # that fails because a registry moved is worse than one that says nothing, and `engines`
1546
+ # still answers on demand.
1547
+ try:
1548
+ if not behind(config.root):
1549
+ return []
1550
+ read = engines(config.root)
1551
+ except OSError:
1552
+ return []
1553
+ return [
1554
+ Note(
1555
+ "gate.behind",
1556
+ _configured(config),
1557
+ f"this gate is {read.running.version} and the project pinned "
1558
+ f"{read.plugin.version if read.plugin else '—'}, so a clean report here is that "
1559
+ f"copy's clean — `{invocation()} engines` names all three",
1560
+ subject="pinned",
1561
+ )
1562
+ ]
1563
+
1564
+
1565
+ def _served(config: Config) -> list[Finding]:
1566
+ """Every served tool against what one may cost a session (RK1059).
1567
+
1568
+ `_budgets`' argument, about the surface instead of about a file. RK30 held the resident
1569
+ prose and RK464 measured the schema and stopped there, deliberately: what a ceiling
1570
+ would be *per* was a decision it declined to make without a number in front of it. Here
1571
+ it is per tool, because a total names nothing — it fails on whichever tool is added
1572
+ last — and a per-tool one is refused by the tool whose description somebody just edited.
1573
+
1574
+ Filed against `roadkeep.toml`, which is the file that declared it and the only file
1575
+ involved: the cost is composed per session from the parser, the config and the `TOOLS`
1576
+ table, so there is no path a reader could open to see it. `cost --tools` is what
1577
+ prints it, and the message says so.
1578
+
1579
+ Silent where nothing is declared, which is every adopting project until it looks at the
1580
+ number — a gate that arrived with a ceiling this tool chose would be the guess RK464
1581
+ refused to make.
1582
+
1583
+ **And it is cheap, which RK1061 was filed believing it was not.** That task measured 201
1584
+ ms against 80 and read it as this check building 52 descriptors on a command CI, the
1585
+ pre-commit hook and the Stop hook each run. Measured again, warm: `descriptors` is 1 ms
1586
+ and this whole function is **1.4 ms**. The 121 ms was one-time import cost — `serving`
1587
+ and the CLI it reaches — attributed to the check by an in-process comparison whose first
1588
+ call paid it. The import is still real and is 13 ms on a path where `cli` is already
1589
+ loaded, which every path this runs on is. Left as it is, and the measurement kept here
1590
+ because the next reader will make the same inference from the same shape.
1591
+ """
1592
+ if config.tool_characters is None:
1593
+ return []
1594
+ from roadkeep.serving import surface
1595
+
1596
+ allowed = config.tool_characters
1597
+ where = _configured(config)
1598
+ sent = surface(config)
1599
+ # The same payload `cost --tools` measures, through the same function (RK345): a
1600
+ # second estimate here is a gate disagreeing with the read that composed the edit. In
1601
+ # its order too — largest first — because the message sends the reader to that ranking,
1602
+ # and a report listing the offenders in a different one is two answers to one question.
1603
+ out = [
1604
+ Finding(
1605
+ "budget.tool",
1606
+ where,
1607
+ f"the {name} tool is {size} characters, budget is {allowed}: this is sent to "
1608
+ f"every session that connects the server, so the overrun is paid before the "
1609
+ f"first call — `{invocation()} cost --tools` ranks them",
1610
+ subject=name,
1611
+ )
1612
+ for name, size in sent.tools
1613
+ if size > allowed
1614
+ ]
1615
+ # And the sum, where the project declared one (RK1097). Second and not instead: this one
1616
+ # names no author, so a report carrying only it would refuse the verb added last for a
1617
+ # size the other 51 built.
1618
+ #
1619
+ # Appended after the per-tool findings and printed before them, which is not a
1620
+ # contradiction left standing: every finding here is filed at `roadkeep.toml` with no
1621
+ # line, so `_ordered` breaks the tie on the code and `budget.session` sorts under
1622
+ # `budget.tool`. Left that way rather than special-cased — one address, one documented
1623
+ # order, and the message says no single tool is at fault, which is what a reader arriving
1624
+ # at it first needs to know.
1625
+ # `held` and not `characters` (RK1334): the handshake names which tree answered, and the
1626
+ # commit, the `modified` flag and the absolute path are the checkout's rather than the
1627
+ # surface's. Refusing the total made the verdict move with the environment, and the two
1628
+ # environments a gate actually runs in are the two that differ most — a pre-commit hook
1629
+ # always sees a dirty tree, and a CI checkout is never at the author's path.
1630
+ if config.tool_session is not None and sent.held > config.tool_session:
1631
+ out.append(
1632
+ Finding(
1633
+ "budget.session",
1634
+ where,
1635
+ f"the served surface is {sent.held} characters — {len(sent.tools)} "
1636
+ f"tool(s) and the handshake, less what names the checkout — against a budget "
1637
+ f"of {config.tool_session}: "
1638
+ # The ranking and not the total (RK1336): naming `--session` here restated the
1639
+ # figure this sentence had just given, and the reader's next act is to pick a
1640
+ # description. The doors beneath carry both, in the order the work goes.
1641
+ f"every session pays this at connect before it calls anything, and no one "
1642
+ f"tool is at fault — `{invocation()} cost --tools` ranks every description "
1643
+ f"against this ceiling and prints the room each has",
1644
+ subject="session",
1645
+ )
1646
+ )
1647
+ return out
1648
+
1649
+
1650
+ def _collective(config: Config, documents: dict[str, Document]) -> list[Note]:
1651
+ """What a `Block X` or a range actually names, said out loud (RK35).
1652
+
1653
+ Only when it expands to **two or more** open tasks, which is precisely the case the
1654
+ line hides: at one there is no surprise to report, and at zero there is nothing to
1655
+ name — whether waiting is over there is the standing's answer and not this note's, a
1656
+ label with no open member being finished, paused or a heading opened before its lines,
1657
+ and only the first of those annotating ✅ (RK8, RK432). A note per token below that
1658
+ threshold would be output nobody reads, which is the failure mode RK16 exists to avoid.
1659
+
1660
+ **One row per token and not per line** (RK1299), which is RK1165's shape at the gate: a
1661
+ run of rows saying one thing is one row with its count. Measured on winwright the moment
1662
+ its first block finished — a clean `lint --json` was 25,823 characters, 42 notes, all of
1663
+ them this code, and between them they stated six facts; eleven lines depending on Block G
1664
+ contributed the same sentence eleven times, each with a `remedy` whose prose was the same
1665
+ 78 characters. That is five times the text form of the same run, for a verdict of `clean`,
1666
+ on the read that runs at the end of every turn.
1667
+
1668
+ So the expansion is stated once and the lines waiting on it are named beside it. Filed at
1669
+ the **first** of them, which is what keeps the address real and the remedy runnable: `deps`
1670
+ resolves a task and not a label, so a row anchored on the token would carry a command
1671
+ nothing answers. The other lines are named only where there are other lines — a list of
1672
+ one is the id this note already carries, and printing it twice is the repetition this is.
1673
+ """
1674
+ roadmap = documents.get("roadmap")
1675
+ if roadmap is None:
1676
+ return []
1677
+ backlog = Backlog.during(
1678
+ config,
1679
+ roadmap=roadmap,
1680
+ ledger=documents.get("changelog"),
1681
+ store=documents.get("deferred"),
1682
+ )
1683
+ file = config.relative(config.path("roadmap"))
1684
+ # Keyed by the token and in first-appearance order, which is file order: the rows a reader
1685
+ # scans stay in the order the lines that raised them do. The dep travels with the group
1686
+ # because `expand` resolves the parsed token and not the string it renders as.
1687
+ waiting: dict[str, tuple[object, list[str]]] = {}
1688
+ where: dict[str, int | None] = {}
1689
+ for entry in roadmap.entries:
1690
+ for dep in entry.task.deps:
1691
+ if not config.schema.classify_dep(dep).collective:
1692
+ continue
1693
+ found = waiting.setdefault(dep.id, (dep, []))
1694
+ found[1].append(entry.task.id)
1695
+ where.setdefault(dep.id, entry.lineno)
1696
+ out: list[Note] = []
1697
+ for token, (dep, ids) in waiting.items():
1698
+ members = backlog.expand(dep) # type: ignore[arg-type]
1699
+ if len(members) < 2:
1700
+ continue
1701
+ shown = ", ".join(members[:6]) + (" …" if len(members) > 6 else "")
1702
+ message = f"{token} is one token naming {len(members)} open tasks: {shown}"
1703
+ if len(ids) > 1:
1704
+ listed = ", ".join(ids[:6]) + (" …" if len(ids) > 6 else "")
1705
+ message += f" — and {len(ids)} lines wait on it: {listed}"
1706
+ out.append(Note("deps.collective", file, message, where[token], ids[0]))
1707
+ return out
1708
+
1709
+
1710
+ def _turned(config: Config, documents: dict[str, Document], since: str) -> list[Note]:
1711
+ """A block that emptied or reopened in this change (RK269).
1712
+
1713
+ `ship` is the only verb that computes it — `event T282 Block AI finished` — and says it once,
1714
+ to a console. Nothing records it, no later verb can ask, and `lint` reports a clean tree
1715
+ either way, which is the gate an author actually trusts. Measured in a repository keeping a
1716
+ per-block index beside its ledger, one `(active — see ROADMAP)` per row: two ships emptied a
1717
+ block and two adds reopened it across four commits, every row was flipped by hand, and every
1718
+ time `lint` passed on the wrong one. The discrepancy was caught by that project's own test
1719
+ suite, which asserts the index against the roadmap because this tool does not.
1720
+
1721
+ Three shapes were open and this is the cheapest of them, which is also the one that would
1722
+ have caught all four. Not a query verb: `stats --json` already answers which blocks hold
1723
+ nothing, so a project's check can be written against roadkeep today. Not ownership of the
1724
+ index row either — that is a projection, and a projection roadkeep writes is `export`'s
1725
+ contract (RK39), which wants a declared shape rather than a guess at somebody's table.
1726
+
1727
+ Reported with ``since`` and never as a state, which is the whole reason it is quiet enough
1728
+ to keep: the shipped pre-commit hook runs `lint --since HEAD`, so this lands at the moment of
1729
+ the commit that moved it — while "Block A is empty" is true of this repository forever and a
1730
+ line printed forever is a line nobody reads (RK16).
1731
+
1732
+ A **note**, because emptying a block is what finishing one looks like. Only blocks *both*
1733
+ trees declare: one that arrived is `block add`'s own event and one that left is `block drop`,
1734
+ and neither is a transition of state.
1735
+
1736
+ Emptiness is `Document.holds` and nothing wider — the same *call* the event line makes and
1737
+ not a second spelling of it (RK300), because two answers to "is that block empty" is this
1738
+ defect with the arrow reversed (RK92: a deferred line is set aside, not open). The counts
1739
+ below are presentation and not the decision: how many lines a block held is a fact about
1740
+ the baseline that the event line never computes, so it is read where it is printed.
1741
+ """
1742
+ roadmap = documents.get("roadmap")
1743
+ if roadmap is None:
1744
+ return []
1745
+ if not resolves(config, since):
1746
+ # A repository with no commits has no HEAD, which is the shipped hook's default.
1747
+ if since == "HEAD":
1748
+ return []
1749
+ raise HistoryUnavailable(f"{since} is not a revision this repository knows")
1750
+ before = Tree(config, since).document("roadmap")
1751
+ if before is None:
1752
+ return []
1753
+ file = config.relative(config.path("roadmap"))
1754
+ declared = {h.label for h in before.headings if h.label}
1755
+ held = {label for label in declared if before.holds(label)}
1756
+ out: list[Note] = []
1757
+ for heading in roadmap.headings:
1758
+ label = heading.label
1759
+ if label is None or label not in declared:
1760
+ continue
1761
+ now = roadmap.holds(label)
1762
+ if label in held and not now:
1763
+ out.append(
1764
+ Note(
1765
+ "block.emptied",
1766
+ file,
1767
+ f"held {len(before.block(label))} open line(s) at {since} and holds none "
1768
+ f"now: a projection that states which blocks are active is a row this "
1769
+ f"commit moves, and nothing else here will say so",
1770
+ heading.lineno,
1771
+ label,
1772
+ )
1773
+ )
1774
+ elif now and label not in held:
1775
+ out.append(
1776
+ Note(
1777
+ "block.reopened",
1778
+ file,
1779
+ f"held no open line at {since} and holds {len(roadmap.block(label))} now: "
1780
+ f"the same row, in the other direction",
1781
+ heading.lineno,
1782
+ label,
1783
+ )
1784
+ )
1785
+ return out
1786
+
1787
+
1788
+ def _worked(
1789
+ config: Config, documents: dict[str, Document], sections: tuple[Section, ...], since: str
1790
+ ) -> list[Note]:
1791
+ """Source moved under an open task while its line stood still (RK1228).
1792
+
1793
+ :func:`_unpaired` checks the shape where the *prose* moved and the line did not. This is
1794
+ the mirror, and it was unchecked: source can change under everything a task's section
1795
+ names, the tests for it can pass, and the line stays open with nobody told.
1796
+
1797
+ Observed here across a working session. A task's section named the component and the
1798
+ library module it needed; both were rewritten, a dozen assertions were added and passed,
1799
+ the outcome was reported as delivered — and `ship` was never called. `lint` said clean,
1800
+ because the files it governs were internally consistent, and they were: the entry simply
1801
+ did not exist. It surfaced two blocks later, when a block that should have been finished
1802
+ still counted one open line.
1803
+
1804
+ **A note and never a finding**, which is the whole judgement and the same one RK36 made: a
1805
+ path named in a section changes for plenty of reasons that are not the task — a rename, a
1806
+ neighbouring fix, a refactor that crossed it — so refusing would produce a gate that gets
1807
+ bypassed within a week. Saying it once, at the moment of the commit, is the whole value.
1808
+
1809
+ Nothing here is semantic. The signal is a coincidence of two facts this run already holds:
1810
+ the paths a section names, which `show` resolves, and the diff, which `--since` has.
1811
+
1812
+ **The block reading replaces its members** (RK1234). Per line this fires once and reads as
1813
+ a coincidence, which is what it is; per block it reads as a diagnosis, and saying the weak
1814
+ thing five times and then the strong one about the same five lines is noise. So a block
1815
+ that qualifies emits `block.worked` and its members emit nothing.
1816
+
1817
+ Qualifying is deliberately narrow, because the aggregate should be worth reading every
1818
+ time it appears. **Every** open line in the block names at least one path and every one of
1819
+ those lines moved: one line whose section names no path makes the block unreachable, which
1820
+ is the honest cost of not letting a prose-only line report on an unrelated edit. And two
1821
+ lines at minimum — on a block holding one, "every line moved" is the per-line note with a
1822
+ heading's lineno, so the members' own reading is the truer one.
1823
+ """
1824
+ if not sections or not documents.get("roadmap"):
1825
+ return []
1826
+ from roadkeep.history import changed_paths # noqa: PLC0415 - RK260
1827
+
1828
+ moved = changed_paths(config, since)
1829
+ if not moved:
1830
+ return []
1831
+ roadmap = documents["roadmap"]
1832
+ where = config.relative(config.path("roadmap"))
1833
+ by_anchor = {one.anchor: one for one in sections}
1834
+ named_by_id: dict[str, set[str]] = {}
1835
+ touched_by_id: dict[str, list[str]] = {}
1836
+ for entry in roadmap.entries:
1837
+ section = by_anchor.get(entry.task.ref or entry.task.id)
1838
+ if section is None:
1839
+ continue
1840
+ named_by_id[entry.task.id] = {
1841
+ one.path
1842
+ for one in paths_in(
1843
+ section.body,
1844
+ config.root,
1845
+ near=config.path("improvements").parent
1846
+ if config.has("improvements")
1847
+ else None,
1848
+ known=lambda: known_directories(config),
1849
+ )
1850
+ }
1851
+ touched_by_id[entry.task.id] = sorted(named_by_id[entry.task.id] & moved)
1852
+ out: list[Note] = []
1853
+ aggregated: set[str] = set()
1854
+ for heading in roadmap.headings:
1855
+ label = heading.label
1856
+ if label is None:
1857
+ continue
1858
+ held = roadmap.block(label)
1859
+ if len(held) < 2:
1860
+ continue
1861
+ if not all(named_by_id.get(one.task.id) for one in held):
1862
+ continue
1863
+ if not all(touched_by_id.get(one.task.id) for one in held):
1864
+ continue
1865
+ aggregated.update(one.task.id for one in held)
1866
+ out.append(
1867
+ Note(
1868
+ "block.worked",
1869
+ where,
1870
+ f"this change touches a path every one of the {len(held)} open line(s) filed "
1871
+ f"here names, and none of them shipped — a block finished and not closed "
1872
+ f"looks exactly like this",
1873
+ heading.lineno,
1874
+ label,
1875
+ )
1876
+ )
1877
+ for entry in roadmap.entries:
1878
+ if entry.task.id in aggregated or not touched_by_id.get(entry.task.id):
1879
+ continue
1880
+ section = by_anchor[entry.task.ref or entry.task.id]
1881
+ out.append(
1882
+ Note(
1883
+ "task.worked",
1884
+ where,
1885
+ f"this change touches {', '.join(touched_by_id[entry.task.id])}, which "
1886
+ f"§{section.anchor} names, and the line is still open — `ship` if that is "
1887
+ f"what landed",
1888
+ entry.lineno,
1889
+ entry.task.id,
1890
+ )
1891
+ )
1892
+ # Both readings address one file, so they are reported in its order and not in the order
1893
+ # the two passes happened to compute them.
1894
+ return sorted(out, key=lambda one: one.lineno)
1895
+
1896
+
1897
+ def _unpaired(config: Config, sections: tuple[Section, ...], since: str) -> list[Note]:
1898
+ """A rationale section edited without touching the line that carries its status (RK36).
1899
+
1900
+ RK15 refuses a pointer at a section that does not exist; this is the mirror, and the
1901
+ more expensive direction: the line is the only thing `pick` reads and the section is
1902
+ deleted on ship, so a requirement written only into the rationale cannot be picked,
1903
+ cannot be shipped, and leaves with the section that held it. It happened three times in
1904
+ one session here, every time by an author who had just learned something and wrote it
1905
+ where the reasoning was rather than where the status is.
1906
+
1907
+ A **note**, not a finding, and this is the whole judgement: the check cannot tell a
1908
+ typo in a paragraph from a smuggled requirement, and a gate that failed every honest
1909
+ rationale edit would be bypassed within a week — which is worth less than a sentence
1910
+ read at the moment of the commit. It is deliberately not semantic (§RK36 says so): the
1911
+ signal is that the section was open and the line was not.
1912
+ """
1913
+ if not resolves(config, since):
1914
+ # A repository with no commits has no HEAD, which is the shipped hook's default —
1915
+ # so the initial commit is not the thing this fails on.
1916
+ if since == "HEAD":
1917
+ return []
1918
+ raise HistoryUnavailable(f"{since} is not a revision this repository knows")
1919
+
1920
+ edited = touched_since(config, since, "improvements")
1921
+ if not edited.changes:
1922
+ return []
1923
+ ids = config.schema.id_pattern()
1924
+ mentioned = re.compile(rf"\*\*({config.schema.id_fragment})\*\*")
1925
+ touched_ids = {
1926
+ found
1927
+ for role in LINE_ROLES
1928
+ for line in touched_since(config, since, role).lines
1929
+ for found in mentioned.findall(line)
1930
+ }
1931
+ # The file as it was, so a *removal* is attributed to the section that held it. Without
1932
+ # this a deleted section lands in whichever one now precedes the hole — and the section
1933
+ # `ship` just deleted would be reported against its innocent neighbour every time.
1934
+ before = anchored(
1935
+ Document.parse(content_at(config, since, "improvements"), schema=config.schema)
1936
+ )
1937
+
1938
+ opened: set[str] = set()
1939
+ for change in edited.changes:
1940
+ if not change.text.strip():
1941
+ # A blank belongs to no section's prose, and counting it would attribute an
1942
+ # appended section to the one whose trailing blank line it starts on.
1943
+ continue
1944
+ anchor = _section_at(sections if change.added else before, change.lineno)
1945
+ if anchor is not None:
1946
+ opened.add(anchor)
1947
+
1948
+ here = {section.anchor: section for section in sections}
1949
+ out: list[Note] = []
1950
+ for anchor in sorted(opened):
1951
+ section = here.get(anchor)
1952
+ if section is None or not ids.match(anchor) or anchor in touched_ids:
1953
+ continue
1954
+ out.append(
1955
+ Note(
1956
+ "section.unpaired",
1957
+ config.relative(config.path("improvements")),
1958
+ f"§{anchor} was edited and {anchor}'s line was not: the line is the only "
1959
+ f"thing `pick` reads, and this section is deleted on ship — so a "
1960
+ f"requirement written only here goes with it",
1961
+ section.first,
1962
+ anchor,
1963
+ )
1964
+ )
1965
+ return out
1966
+
1967
+
1968
+ def _section_at(sections: tuple[Section, ...], lineno: int) -> str | None:
1969
+ """The anchor whose span holds this line, or None for prose under no anchor."""
1970
+ return next(
1971
+ (s.anchor for s in sections if s.first <= lineno <= s.last),
1972
+ None,
1973
+ )
1974
+
1975
+
1976
+ def characters_in(config: Config, role: str, document: Document) -> list[Finding]:
1977
+ """The byte-level walk over one file, for a caller that holds only that file (RK1351).
1978
+
1979
+ `within` is not the place, which one run of the corpora settled: the merge driver gates
1980
+ its **own output** with it, and folding this in made a merge of Shio's rationale file with
1981
+ itself refuse over a variation selector that was already there. A defect the driver
1982
+ inherited is not one it introduced, and a project that cannot merge until it cleans a
1983
+ codepoint is a worse answer than the blindness.
1984
+
1985
+ So the estimate asks for it by name. `adopt` prices what adoption costs, and a BOM the
1986
+ fixer closes with no decision is a cost — `lint` on the same bytes reported `char.bom` and
1987
+ named `--fix` while the estimate named it nothing at all.
1988
+ """
1989
+ return _characters(config, role, document)
1990
+
1991
+
1992
+ def resolving(config: Config, role: str, roadmap: Document) -> list[Finding]:
1993
+ """The dep questions one file cannot answer, asked of a candidate roadmap (RK1353).
1994
+
1995
+ `within` is *everything decidable from one file alone*, and whether a dep names a line
1996
+ the backlog carries is not: it needs the roadmap, the ledger and the store together. So
1997
+ the merge driver — which holds three versions of one path and gates what it composed —
1998
+ could not see the one class a merge is uniquely able to create. Measured: one branch adds
1999
+ `RK3 (deps: RK2)` while the other removes `RK2`, and the merged file, held by neither
2000
+ side, lands clean and fails `lint` afterwards.
2001
+
2002
+ The candidate stands in for the roadmap and the other roles are read from disk, which is
2003
+ where a merge runs: git calls a driver in a worktree, so the ledger and the store are the
2004
+ committed ones. `_present` answers `None` for a role that is undeclared or not yet
2005
+ written, so a project holding only a roadmap asks a narrower question rather than failing
2006
+ — the same tolerance `Backlog.load` gives every other reader.
2007
+
2008
+ Roadmap only, deliberately: a ledger entry carries no deps, so asking would be composing
2009
+ a question the grammar has no field for.
2010
+ """
2011
+ from roadkeep.backlog import Backlog, _present # noqa: PLC0415 - RK260's edge back
2012
+
2013
+ if role != "roadmap":
2014
+ return []
2015
+ backlog = Backlog(
2016
+ config=config,
2017
+ roadmap=roadmap,
2018
+ ledger=_present(config, "changelog"),
2019
+ store=_present(config, "deferred"),
2020
+ )
2021
+ file = config.relative(config.path(role))
2022
+ # All four kinds and not the three `_deps` holds (RK1354). A cycle is the purer case of
2023
+ # what only a merge writes: a dangling dep is visible on the branch that wrote it, as a
2024
+ # dep on an id that branch does not carry, while a cycle is well-formed on both sides and
2025
+ # exists in the merged file alone — a state neither author can review, neither having had
2026
+ # it. Measured: one branch adding `RK2 (deps: RK3)` and the other `RK3 (deps: RK2)` merged
2027
+ # clean and linted `deps.cycle`. The group's id is stable — the same cycle answers `RK2`
2028
+ # with or without a line above it — so an inherited one is still told from a composed one.
2029
+ return [
2030
+ *(
2031
+ found
2032
+ for entry in roadmap.entries
2033
+ for found in _deps(backlog, entry.task, file, entry.lineno)
2034
+ ),
2035
+ *_cycles(backlog, file),
2036
+ ]
2037
+
2038
+
2039
+ def _voided(document: Document) -> bool:
2040
+ """Whether this file's every byte is NUL — the shape a lost write leaves (RK451).
2041
+
2042
+ Not a heuristic about looking binary, which would be a judgement about files this tool
2043
+ did not write. The decidable question is narrower and is the one the failure produces:
2044
+ RK118 wrote every byte of a governed file, and none of them was ever a NUL, so a file
2045
+ that is nothing but NUL is one whose content did not reach the disk. An empty file is a
2046
+ different state — a scaffold before its first line — and stays the gate's other business.
2047
+ """
2048
+ if not document.lines:
2049
+ return False
2050
+ return all(character == "\x00" for line in document.lines for character in line)
2051
+
2052
+
2053
+ def _absent(config: Config, tree: Tree) -> list[Finding]:
2054
+ """A declared file that is not on disk (`init` creates it: RK18).
2055
+
2056
+ Asked of the tree and not of disk, so a baseline says *was it there then*: a governed
2057
+ file deleted since the ref is a finding this change made, and one added since is a file
2058
+ the ref cannot be asked to account for.
2059
+ """
2060
+ return [
2061
+ Finding(
2062
+ "file.missing",
2063
+ config.relative(config.path(role)),
2064
+ f"declared as the {role} file and not on disk",
2065
+ )
2066
+ for role in ROLES
2067
+ if config.has(role) and not tree.present(config.path(role))
2068
+ ]
2069
+
2070
+
2071
+ def within(config: Config, role: str, document: Document) -> list[Finding]:
2072
+ """Everything decidable from one file alone.
2073
+
2074
+ Public because the merge driver gates its own output with it (RK120): a driver holds
2075
+ three versions of one file and none of the others, so this is exactly the half of the
2076
+ gate it can run — and a second statement of these rules would be a second gate to keep
2077
+ in step with this one.
2078
+ """
2079
+ file = config.relative(config.path(role))
2080
+ out: list[Finding] = []
2081
+
2082
+ # Before the line reader (RK451, RK454). A NUL in a governed file is a **lost write**
2083
+ # and not a character somebody typed: RK118 wrote every byte of this file and none of
2084
+ # them was ever one, so the diagnosis `char.invisible` gives is wrong in kind and the
2085
+ # `--fix` it names is worse — on a file a crash left entirely NUL that pass would strip
2086
+ # every byte and report the tree clean, and on a partly-lost one it claims all 400
2087
+ # findings, writes nothing, and returns the identical report on the next run.
2088
+ #
2089
+ # So the file states it once. Whole-file rather than per-byte because the loss is,
2090
+ # and because a column is a fact about a line that no longer says anything.
2091
+ lost = sum(line.count("\x00") for line in document.lines)
2092
+ if lost:
2093
+ held = sum(len(line) for line in document.lines)
2094
+ out.append(
2095
+ Finding(
2096
+ "file.not-text",
2097
+ file,
2098
+ (
2099
+ f"holds {held} character(s) and not one of them is text: every byte is "
2100
+ f"NUL"
2101
+ if lost == held
2102
+ else f"holds {lost} NUL byte(s) among its {held} character(s)"
2103
+ )
2104
+ + ", which is what a crash between a write and its rename leaves — the "
2105
+ "content is gone rather than malformed",
2106
+ )
2107
+ )
2108
+ # Nothing below can read a file with no text in it, and every rule here asks what a
2109
+ # *line* says. A file that kept some of its lines is a different answer (RK454): its
2110
+ # surviving lines have defects of their own, and hiding them would answer a question
2111
+ # nobody asked.
2112
+ if lost == held:
2113
+ return out
2114
+
2115
+ for reject in document.rejects:
2116
+ # The line the parser could not read at all. It is reported here and counted
2117
+ # nowhere else, which is the difference between `audit` and a gate.
2118
+ out.append(Finding("line.unparsed", file, reject.reason, reject.lineno))
2119
+
2120
+ seen: dict[str, int] = {}
2121
+ for entry in document.entries:
2122
+ task = entry.task
2123
+ for violation in document.schema.validate(task):
2124
+ if violation.code in _SCANNED:
2125
+ # RK499 put the codepoint rule at the door too, and `_characters` already
2126
+ # walks every line of this file for it — so surfacing both would report one
2127
+ # tab twice under one code, at two different numbers: a position inside a
2128
+ # field, and the column of the line. The scan's is what a report is read
2129
+ # for, and the schema's is what a *refusal* is read for.
2130
+ continue
2131
+ out.append(
2132
+ Finding(violation.code, file, violation.message, entry.lineno, task.id)
2133
+ )
2134
+ canonical = document.schema.render(task)
2135
+ if canonical != entry.raw:
2136
+ # Named, not fixed (L3): the tool may not rewrite a line it might have
2137
+ # misread, so the report carries the rendering and the edit stays a human's.
2138
+ out.append(
2139
+ Finding(
2140
+ "line.non-canonical",
2141
+ file,
2142
+ f"written differently from what the schema renders: {canonical!r}",
2143
+ entry.lineno,
2144
+ task.id,
2145
+ )
2146
+ )
2147
+ if task.id in config.reserved:
2148
+ # The check that RK1031 is a fix and not a suppression. A reservation says the
2149
+ # address is spoken for and never written as a line; a line that carries one is
2150
+ # the two statements disagreeing, and the deriver has been handing out numbers
2151
+ # past it on the strength of the declaration.
2152
+ out.append(
2153
+ Finding(
2154
+ "id.reserved",
2155
+ file,
2156
+ "declared in `reserved_ids` and written here as a line: a reservation "
2157
+ "is an address nothing carries, so one of the two has to go",
2158
+ entry.lineno,
2159
+ task.id,
2160
+ )
2161
+ )
2162
+ first = seen.get(task.id)
2163
+ if first is not None:
2164
+ out.append(
2165
+ Finding(
2166
+ "id.duplicate",
2167
+ file,
2168
+ f"already carried by line {first}: two lines with one id are two "
2169
+ f"answers to whether it is done",
2170
+ entry.lineno,
2171
+ task.id,
2172
+ )
2173
+ )
2174
+ seen.setdefault(task.id, entry.lineno)
2175
+ return out
2176
+
2177
+
2178
+ def _scope(config: Config, roadmap: Document | None) -> list[Finding]:
2179
+ """The non-goals, for a project that declared them governed (RK70).
2180
+
2181
+ Silent otherwise, and that is the whole of the opt-in: two live corpora wrote their lists
2182
+ as free prose years before this grammar existed, and a gate that reported fifteen findings
2183
+ on the first run is a gate that gets bypassed rather than adopted (RK66).
2184
+
2185
+ What is judged is what the schema can judge — the shape, the two lengths, and a lead
2186
+ claimed twice. Not the wrap: a filled bullet is written at insertion (L1) and a
2187
+ hand-wrapped one is whitespace inside prose, which `--fix` is the door for (RK16).
2188
+ """
2189
+ if roadmap is None or config.non_goals is None:
2190
+ return []
2191
+ file = config.relative(config.path("roadmap"))
2192
+ out: list[Finding] = []
2193
+ for lineno, raw in scoping.rejects(roadmap):
2194
+ out.append(
2195
+ Finding(
2196
+ scoping.SHAPE,
2197
+ file,
2198
+ f"a governed non-goal is `- **<lead>** <why>`, so this bullet has no lead "
2199
+ f"to be addressed by: {raw.strip()[:60]!r}",
2200
+ lineno,
2201
+ # The **lead as this file reads it** (RK1266), which is the address every
2202
+ # door here takes: `scoping` gives an unshaped bullet one on purpose, so the
2203
+ # remedy is a complete command rather than a blank.
2204
+ subject=_led(roadmap, lineno),
2205
+ )
2206
+ )
2207
+ seen: dict[str, int] = {}
2208
+ for non_goal in scoping.read(roadmap):
2209
+ # The two lengths, only where the shape held (RK233). A bullet the reader now returns
2210
+ # unshaped already carries the finding above, whose remedy is the rewrite — charging
2211
+ # its sentence-lead against `lead` on top of that is a second finding the first one
2212
+ # subsumes, and Turing's `is **not** a path` would add a third for the `*` a bold run
2213
+ # this module never wrote is made of.
2214
+ if non_goal.shaped:
2215
+ for violation in scoping.validate(config, non_goal.lead, non_goal.why):
2216
+ out.append(
2217
+ Finding(
2218
+ violation.code,
2219
+ file,
2220
+ violation.message,
2221
+ non_goal.first,
2222
+ subject=non_goal.lead,
2223
+ )
2224
+ )
2225
+ # The address is checked for every bullet, because every bullet now has one: two
2226
+ # constraints a reader looks up by the same words are two answers about one scope
2227
+ # whichever shape they are written in, and `drop` would take the later one either way.
2228
+ lead = scoping.address(non_goal.lead)
2229
+ first = seen.get(lead)
2230
+ if first is not None:
2231
+ out.append(
2232
+ Finding(
2233
+ "non-goal.duplicate",
2234
+ file,
2235
+ f"already led on line {first}: the lead is the address, so two bullets "
2236
+ f"carrying it are two answers about one scope",
2237
+ non_goal.first,
2238
+ subject=non_goal.lead,
2239
+ )
2240
+ )
2241
+ seen.setdefault(lead, non_goal.first)
2242
+ return out
2243
+
2244
+
2245
+ def _criteria(
2246
+ config: Config, roadmap: Document | None, documents: dict[str, Document]
2247
+ ) -> list[Finding]:
2248
+ """The criteria, for a project that declared them governed (RK1265).
2249
+
2250
+ :func:`_scope`'s three checks one list over, and silent otherwise for its reason: an
2251
+ adopting project's `Done when` prose was written before this grammar, and a gate that
2252
+ reported on it before anybody opted in is a gate that gets bypassed.
2253
+
2254
+ The address is the **pair** here, so a lead is judged against the leads of its own list: a
2255
+ criterion reading "Every write has a door" under two blocks is two claims about two bodies
2256
+ of work and not one written twice, which is the one place this differs from the non-goals
2257
+ and the reason the seen-set is keyed by both. A task's list is the same pair with an id in
2258
+ it (RK1268), and keys the same way for the same reason.
2259
+ """
2260
+ if roadmap is None or config.criteria is None:
2261
+ return []
2262
+ file = config.relative(config.path("roadmap"))
2263
+ out: list[Finding] = []
2264
+ for lineno, raw in criteria.rejects(roadmap):
2265
+ out.append(
2266
+ Finding(
2267
+ criteria.SHAPE,
2268
+ file,
2269
+ f"a governed criterion is `- **<lead>** <why>`, so this bullet has no lead "
2270
+ f"to be addressed by: {raw.strip()[:60]!r}",
2271
+ lineno,
2272
+ # The **lead as this file reads it**, which is the address every door here
2273
+ # takes (RK420): where the shape did not hold, `criteria` still gives the
2274
+ # bullet one, so the remedy is a complete command rather than a blank.
2275
+ subject=_leading(roadmap, lineno),
2276
+ )
2277
+ )
2278
+ seen: dict[tuple[str, str], int] = {}
2279
+ for one in criteria.read(roadmap):
2280
+ # The two lengths, only where the shape held — `_scope`'s rule and its whole argument:
2281
+ # the unshaped bullet already carries the finding above, whose remedy is the rewrite.
2282
+ if one.shaped:
2283
+ for violation in criteria.validate(config, one.lead, one.why):
2284
+ out.append(
2285
+ Finding(
2286
+ violation.code,
2287
+ file,
2288
+ violation.message,
2289
+ one.first,
2290
+ subject=one.lead,
2291
+ )
2292
+ )
2293
+ address = (one.about, criteria.address(one.lead))
2294
+ first = seen.get(address)
2295
+ if first is not None:
2296
+ out.append(
2297
+ Finding(
2298
+ "criterion.duplicate",
2299
+ file,
2300
+ f"already led on line {first} under "
2301
+ f"{criteria.named(config.schema, one.about)}: the lead is the "
2302
+ f"address, so two bullets carrying it are two answers about one claim",
2303
+ one.first,
2304
+ subject=one.lead,
2305
+ )
2306
+ )
2307
+ seen.setdefault(address, one.first)
2308
+ return out + _orphaned(config, roadmap, documents, file)
2309
+
2310
+
2311
+ def _orphaned(
2312
+ config: Config, roadmap: Document, documents: dict[str, Document], file: str
2313
+ ) -> list[Finding]:
2314
+ """A `Done when` list whose address stopped existing (RK1318).
2315
+
2316
+ The gate reads what a schema can read — shape, the two lengths, a lead stated twice inside
2317
+ one list — and never whether the block or the id it is addressed to is still there.
2318
+ `criteria._addressed` validates that at the write, which is L1 and right; nothing re-asks
2319
+ once the address has gone, and the write path cannot, the block having been there when the
2320
+ bullet was written.
2321
+
2322
+ Two states reached it, and both are closed at their own door now: `block drop` withdrawing
2323
+ a label whose list stayed (RK1316), and `renumber` spending the id a list is addressed to
2324
+ (RK1317). So this is the **backstop** those two make rare and never impossible — a hand
2325
+ edit, a textual merge, a tree governed before either of them shipped.
2326
+
2327
+ One finding per **region** and not per bullet, filed at the heading: what is orphaned is
2328
+ the list, and a bullet under it is not wrong about anything. The subject is the first
2329
+ lead, because the door is `criterion drop <lead>` *bare* — the addressed form is refused,
2330
+ the address being exactly what stopped existing, so a remedy spelling `--block` would name
2331
+ a command that cannot run (RK16). A region the last drop leaves empty carries no lead and
2332
+ therefore no door: the heading survives its bullets by design (RK1265), and `--fix` is what
2333
+ takes that one.
2334
+ """
2335
+ backlog = Backlog.during(
2336
+ config,
2337
+ roadmap=roadmap,
2338
+ ledger=documents.get("changelog"),
2339
+ store=documents.get("deferred"),
2340
+ )
2341
+ labels = backlog.declared_blocks()
2342
+ open_ids = {entry.task.id for entry in roadmap.entries}
2343
+ if documents.get("deferred") is not None:
2344
+ # A paused line still exists and a `resume` brings it back, so its list is not an
2345
+ # orphan — the address is spent by a departure and never by setting work aside (RK92).
2346
+ open_ids |= {entry.task.id for entry in documents["deferred"].entries}
2347
+ out: list[Finding] = []
2348
+ for at, about in criteria._regions(roadmap): # noqa: SLF001 - the region reader is its own
2349
+ addresses_task = criteria.addresses_task(config.schema, about)
2350
+ if about in (open_ids if addresses_task else labels):
2351
+ continue
2352
+ named = criteria.named(config.schema, about)
2353
+ held = criteria.read(roadmap, about)
2354
+ out.append(
2355
+ Finding(
2356
+ "criterion.orphan",
2357
+ file,
2358
+ f"nothing answers {named} any more, so this list asks what would finish work "
2359
+ f"that has "
2360
+ + ("left the backlog" if addresses_task else "no heading in any file")
2361
+ + ": a criterion is addressed by the pair, and half of it is gone",
2362
+ at + 1,
2363
+ # The lead of the first bullet, which is what the bare `criterion drop` takes.
2364
+ # Empty where the region has none, and the remedy table answers no door for a
2365
+ # blank subject — which is the state `--fix` is for.
2366
+ subject=held[0].lead if held else "",
2367
+ )
2368
+ )
2369
+ return out
2370
+
2371
+
2372
+ def _led(roadmap: Document, lineno: int) -> str:
2373
+ """The lead of the non-goal at this line, for the door a shape finding names (RK1266).
2374
+
2375
+ :func:`_leading`'s twin one list over, and read back for its reason: `scoping.rejects`
2376
+ answers the gate's question — which bullets are unshaped — and the address is a second
2377
+ question the same records already hold.
2378
+ """
2379
+ return next((one.lead for one in scoping.read(roadmap) if one.first == lineno), "")
2380
+
2381
+
2382
+ def _leading(roadmap: Document, lineno: int) -> str:
2383
+ """The lead of the criterion at this line, for the door a shape finding names (RK1265).
2384
+
2385
+ Read back rather than threaded through :func:`criteria.rejects`: that reader answers the
2386
+ gate's question — which bullets are unshaped — and the address is a second question the
2387
+ same records already hold.
2388
+ """
2389
+ return next((one.lead for one in criteria.read(roadmap) if one.first == lineno), "")
2390
+
2391
+
2392
+ def _configured(config: Config) -> str:
2393
+ """Where a finding about `roadkeep.toml`'s own keys goes, as the project spells it.
2394
+
2395
+ One expression, because :attr:`Report.checked` names this file and `_queue` files against
2396
+ it: two spellings of the same path is a count and a finding disagreeing (RK354).
2397
+ """
2398
+ return config.relative(config.source) if config.source else "roadkeep.toml"
2399
+
2400
+
2401
+ def _queue(
2402
+ config: Config, documents: dict[str, Document]
2403
+ ) -> tuple[list[Finding], list[Note]]:
2404
+ """Every entry in the queue that outranks the id order, resolved (RK326).
2405
+
2406
+ `Config._check_priority` types a token and stops there, a config parser having no
2407
+ roadmap to resolve it against — so `priority = ["QQ1", "Block Z", "QQ9"]` with QQ1
2408
+ shipped, no heading declaring Z and QQ9 in no file lints clean, while `pick` answers
2409
+ "the declared priority names nothing ready": one sentence covering three deaths and
2410
+ naming none. Written as deps, two of those tokens are already findings here.
2411
+
2412
+ Since RK325 the list is in the roadmap, so the resolution is the one
2413
+ :class:`~roadkeep.backlog.Backlog` already does and the codes are the states a token
2414
+ can be **dead** in: shipped, retired, set aside, naming nothing, and naming a block
2415
+ whose every line has left or is set aside — plus one named twice, which is two answers
2416
+ about where the same work sits. At `file:line:column` like everything else (RK34).
2417
+
2418
+ Two states are deliberately **not** findings. An entry naming a merely blocked task is
2419
+ a queue doing its job — that is what a queue is *for* — and a declared block holding
2420
+ nothing **yet** is legitimate, `block add` writing the heading before the lines. Which
2421
+ of those a label is in is :class:`~roadkeep.backlog.Stage`'s answer and not this
2422
+ module's (RK434); what stays here is which code and which tier each state costs a queue.
2423
+
2424
+ And a `priority` still in `roadkeep.toml` beside a section that now holds the order is
2425
+ the third note: it is read (:func:`~roadkeep.queueing.declared` says the section wins),
2426
+ and a queue quietly coming from the other file is the failure RK325 is about.
2427
+
2428
+ A queue the **config** declares is resolved too, against `roadkeep.toml` and without a
2429
+ line: that is where the defect was measured, and a project that has not written the
2430
+ section is exactly the one whose queue nothing else reads.
2431
+ """
2432
+ roadmap = documents.get("roadmap")
2433
+ if roadmap is None:
2434
+ return [], []
2435
+ backlog = Backlog.during(
2436
+ config,
2437
+ roadmap=roadmap,
2438
+ ledger=documents.get("changelog"),
2439
+ store=documents.get("deferred"),
2440
+ )
2441
+ file = config.relative(config.path("roadmap"))
2442
+ found = queueing.read(roadmap, config)
2443
+
2444
+ out: list[Finding] = []
2445
+ notes: list[Note] = []
2446
+ # A line the task grammar already read is that reader's (RK1357), which is the decision
2447
+ # RK1355 recorded and the queue's own verbs already keep: `priority list` prints such a
2448
+ # line as `unread` rather than as an entry, and `priority drop` pointed at it refuses.
2449
+ # Only the finding claimed it — *a malformed entry of mine* — beside the `block.missing`
2450
+ # that says what actually happened, so the gate and the read disagreed about one line.
2451
+ #
2452
+ # Filtered here and never in `queueing.read`: the reject is what makes the `unread` row,
2453
+ # and a queue holding a line it cannot read is worth saying. What is dropped is the claim
2454
+ # that the line is a defective entry, not the report that it is sitting there.
2455
+ claimed = {entry.lineno for entry in roadmap.entries}
2456
+ for lineno, raw in found.rejects:
2457
+ if lineno in claimed:
2458
+ continue
2459
+ out.append(
2460
+ Finding(
2461
+ "priority.shape",
2462
+ file,
2463
+ f"a queue entry is `- <id>` or `- Block X` and nothing else, so this "
2464
+ f"bullet addresses no work: {raw.strip()[:60]!r}",
2465
+ lineno,
2466
+ )
2467
+ )
2468
+
2469
+ if found.declared_in:
2470
+ if config.priority:
2471
+ notes.append(
2472
+ Note(
2473
+ "priority.config",
2474
+ _configured(config),
2475
+ f"declares priority = {list(config.priority)} while "
2476
+ f"{file} holds the queue: the section wins, so the config's order is "
2477
+ f"read by nothing and `priority drop` cannot reach it",
2478
+ )
2479
+ )
2480
+ places = [
2481
+ (entry.token, entry.lineno, entry.raw.index(entry.token) + 1)
2482
+ for entry in queueing.entries(roadmap, config)
2483
+ ]
2484
+ else:
2485
+ file = _configured(config)
2486
+ places = [(token, None, None) for token in config.priority]
2487
+
2488
+ seen: dict[str, int | None] = {}
2489
+ for token, lineno, column in places:
2490
+ if token in seen:
2491
+ first = f" on line {seen[token]}" if seen[token] else ""
2492
+ out.append(
2493
+ Finding(
2494
+ "priority.duplicate",
2495
+ file,
2496
+ f"{token} is already queued{first}: an entry is an address, so a "
2497
+ f"second one is two answers about where the same work sits",
2498
+ lineno,
2499
+ subject=token,
2500
+ column=column,
2501
+ )
2502
+ )
2503
+ continue
2504
+ seen[token] = lineno
2505
+ finding = _dead(config, backlog, token, file, lineno, column)
2506
+ if isinstance(finding, Note):
2507
+ notes.append(finding)
2508
+ elif finding is not None:
2509
+ out.append(finding)
2510
+ return out, notes
2511
+
2512
+
2513
+ def _dead(
2514
+ config: Config,
2515
+ backlog: Backlog,
2516
+ token: str,
2517
+ file: str,
2518
+ lineno: int | None,
2519
+ column: int | None,
2520
+ ) -> Finding | Note | None:
2521
+ """How this one entry is dead, or nothing where the tier can still fire.
2522
+
2523
+ One resolution, from the code that resolves a dep, so a token cannot mean one thing in
2524
+ an annotation and another in the order (RK11's rule, and :func:`~roadkeep.queueing.typed`
2525
+ at the other end).
2526
+
2527
+ The block half opens no file of its own since RK434: the states it used to read out of
2528
+ the ledger are :class:`~roadkeep.backlog.Stage`'s, read off the same backlog this
2529
+ resolution came from — which was already built from those documents.
2530
+ """
2531
+ resolution = backlog.resolve_dep(Dep(token))
2532
+ if resolution.kind is DepKind.BLOCK:
2533
+ return _dead_block(config, backlog, token, file, lineno, column, resolution.detail)
2534
+ if resolution.status is DepStatus.SHIPPED:
2535
+ return Finding(
2536
+ "priority.shipped",
2537
+ file,
2538
+ f"queues {token}, which is {resolution.detail}: work that left the roadmap "
2539
+ f"cannot be first, and the queue is the one list its departure did not reach",
2540
+ lineno,
2541
+ column=column,
2542
+ subject=token,
2543
+ )
2544
+ if resolution.status is DepStatus.DEFERRED:
2545
+ return Finding(
2546
+ "priority.deferred",
2547
+ file,
2548
+ f"queues {token}, which is {resolution.detail}: `pick` never offers a paused "
2549
+ f"line, so the order is over work nothing can start",
2550
+ lineno,
2551
+ column=column,
2552
+ subject=token,
2553
+ )
2554
+ if resolution.status is DepStatus.UNKNOWN:
2555
+ return Finding(
2556
+ "priority.unknown",
2557
+ file,
2558
+ f"queues {token}, which is {resolution.detail}: nothing can be first because "
2559
+ f"of an id no file carries",
2560
+ lineno,
2561
+ column=column,
2562
+ subject=token,
2563
+ )
2564
+ if resolution.status is DepStatus.UNRESOLVABLE:
2565
+ return Finding(
2566
+ "priority.retired",
2567
+ file,
2568
+ f"queues {token}, which is {resolution.detail}",
2569
+ lineno,
2570
+ column=column,
2571
+ subject=token,
2572
+ )
2573
+ # OPEN, which includes blocked: a queue naming work that is waiting is a queue doing
2574
+ # its job, and the tier fires the moment the blocker ships.
2575
+ return None
2576
+
2577
+
2578
+ def _dead_block(
2579
+ config: Config,
2580
+ backlog: Backlog,
2581
+ token: str,
2582
+ file: str,
2583
+ lineno: int | None,
2584
+ column: int | None,
2585
+ detail: str,
2586
+ ) -> Finding | Note | None:
2587
+ """The half of :func:`_dead` about a `Block X` entry, and what each state costs a queue.
2588
+
2589
+ The states are :class:`~roadkeep.backlog.Stage`'s and not this function's (RK434). They
2590
+ were worked out here first — a heading the ledger files entries under is a block that
2591
+ emptied, one with neither is a heading written before its lines — and RK429 wrote the
2592
+ same walk as :meth:`~roadkeep.backlog.Backlog.standing`, because `brief`, `pick` and
2593
+ `list` needed it too. The copy that goes is this one, and not for being second: it read
2594
+ the roadmap and the ledger and never the store, though `lint` already loads all three,
2595
+ so a block whose lines were set aside was reported as one nothing had been filed under
2596
+ yet — a finding arguing from the opposite of what the file says.
2597
+
2598
+ What stays is the **codes and the tier**, which are the gate's and not a property of a
2599
+ block. `empty` is a note because `block add` writes the heading before the lines, which
2600
+ is the order this tool prescribes and so is a plan rather than a defect; the other
2601
+ three fail a build, `paused` for the reason a queued id in the store does
2602
+ (`priority.deferred`) — the same fact must not change tier by whether it was written as
2603
+ an id or as the label above it. `live` is the one state with nothing to say, so it is
2604
+ the fall-through: a stage this does not name yet is a silence, and a code naming a
2605
+ state the file is not in is worse than no code.
2606
+
2607
+ ``detail`` is the resolver's sentence for the same label, which since RK432 *is*
2608
+ :attr:`Standing.sentence` — one oracle reached two ways, and it is taken as an argument
2609
+ rather than re-read so that a message and the dep report quoting it cannot drift.
2610
+ """
2611
+ label = config.schema.block_of_dep(Dep(token))
2612
+ # Never None here: `_dead` calls this only where `classify_dep` answered `BLOCK`, which
2613
+ # is the same pattern `block_of_dep` matches.
2614
+ standing = backlog.standing(label)
2615
+ if standing.stage is Stage.UNKNOWN:
2616
+ return Finding(
2617
+ "priority.block",
2618
+ file,
2619
+ f"queues {token} and {detail}",
2620
+ lineno,
2621
+ column=column,
2622
+ subject=token,
2623
+ )
2624
+ if standing.stage is Stage.PAUSED:
2625
+ return Finding(
2626
+ "priority.block-paused",
2627
+ file,
2628
+ f"queues {token}, which has nothing open and {standing.paused} set aside: "
2629
+ f"`pick` never offers a paused line, so the order is over work nothing can "
2630
+ f"start",
2631
+ lineno,
2632
+ column=column,
2633
+ subject=token,
2634
+ )
2635
+ if standing.stage is Stage.CURRENT:
2636
+ # Silent (RK1180): a tier over a standing category is an order waiting for the next
2637
+ # finding, which is what that kind of block is for — the finding below is about a tier
2638
+ # that fires on nothing *from now on*, and this one will fire again.
2639
+ return None
2640
+ if standing.stage is Stage.FINISHED:
2641
+ return Finding(
2642
+ "priority.block-empty",
2643
+ file,
2644
+ f"queues {token}, whose every line has shipped or left: a tier that fires on "
2645
+ f"nothing is an order the author believes is in force",
2646
+ lineno,
2647
+ column=column,
2648
+ subject=token,
2649
+ )
2650
+ if standing.stage is Stage.EMPTY:
2651
+ return Note(
2652
+ "priority.block-unstarted",
2653
+ file,
2654
+ f"queues {token}, which no line is filed under yet: the tier fires on nothing "
2655
+ f"until one is",
2656
+ lineno,
2657
+ subject=token,
2658
+ )
2659
+ return None
2660
+
2661
+
2662
+ def _across(config: Config, documents: dict[str, Document]) -> list[Finding]:
2663
+ """What needs both files: one id in two of them, a block only one declares, and every
2664
+ dep resolved."""
2665
+ roadmap = documents.get("roadmap")
2666
+ if roadmap is None:
2667
+ return []
2668
+ ledger = documents.get("changelog")
2669
+ backlog = Backlog.during(
2670
+ config, roadmap=roadmap, ledger=ledger, store=documents.get("deferred")
2671
+ )
2672
+ file = config.relative(config.path("roadmap"))
2673
+ out: list[Finding] = []
2674
+
2675
+ if ledger is not None:
2676
+ out.extend(_undeclared_blocks(config, roadmap, ledger, file))
2677
+ out.extend(_carried(config, backlog))
2678
+
2679
+ for entry in roadmap.entries:
2680
+ out.extend(_deps(backlog, entry.task, file, entry.lineno))
2681
+ derived = derive(backlog, entry.task)
2682
+ if derived.deps != entry.task.deps:
2683
+ out.append(
2684
+ Finding(
2685
+ "deps.stale",
2686
+ file,
2687
+ f"the annotation caches another line's status and this one is out "
2688
+ f"of date: derived, it reads "
2689
+ f"({', '.join(d.render() for d in derived.deps)})",
2690
+ entry.lineno,
2691
+ entry.task.id,
2692
+ )
2693
+ )
2694
+
2695
+ out.extend(_cycles(backlog, file))
2696
+ return out
2697
+
2698
+
2699
+ def _disagreeing(config: Config, tree: Tree) -> list[Note]:
2700
+ """The pen and the judge, where they are two versions of this tool (RK415).
2701
+
2702
+ An adopting project runs three copies — the plugin its hook and skill run, the action its
2703
+ workflow gates on, and whatever `roadkeep` the caller invokes. Measured live: a checkout
2704
+ at 0.1.418 doing every write while the plugin at 0.1.285 denied the hand edits, 133
2705
+ versions apart, in a project whose backlog reasoned about *the plugin this repository
2706
+ runs* while a newer copy held the pen. Nothing said so, and the facts were local the
2707
+ whole time.
2708
+
2709
+ Here because this is the gate, and once per commit is the right frequency: the same
2710
+ sentence on every `add` is noise the author learns to skip, and `engines` is the verb for
2711
+ asking on purpose. A **note**, so the exit code does not move — a cache lagging a
2712
+ checkout is allowed, and what is not survivable is not being told (RK79).
2713
+
2714
+ Never over a **revision** (`--baseline`, `--at`): those runs judge the files as they were
2715
+ and the engines are a fact about right now, so the same note subtracted from itself would
2716
+ be reported as resolved debt the moment the versions agreed again.
2717
+ """
2718
+ if tree.rev is not None:
2719
+ return []
2720
+ from roadkeep.installing import engines # noqa: PLC0415
2721
+
2722
+ found = engines(config.root)
2723
+ if found.agree or found.plugin is None:
2724
+ return []
2725
+ return [
2726
+ Note(
2727
+ "engine.disagreement",
2728
+ config.relative(config.root),
2729
+ f"this gate is {found.running.version} and the plugin wired to this project is "
2730
+ f"{found.plugin.version}: a hook's refusal is that copy's rule — `engines` "
2731
+ f"reads all three, and `/plugin update` moves the judge",
2732
+ )
2733
+ ]
2734
+
2735
+
2736
+ def _repeated(config: Config, files: dict[str, Document]) -> list[Finding]:
2737
+ """One label declared by two headings in one file — the gate's half of RK391.
2738
+
2739
+ RK390 made `init` refuse it, which closed one of four doors: a hand edit, an `adopt`, and
2740
+ a merge of two branches all reach the same file, and there `lint` said *clean* while
2741
+ `add --block A` filed under the last of the two. That is L1 read the wrong way round —
2742
+ the law is that the schema is enforced where the text is created *and* the gate is the
2743
+ backstop, not that the write path is the only way in. Every other rule here has both
2744
+ ends; this one had the first alone.
2745
+
2746
+ A **finding**, not a note, and the exit code is the argument: a file no verb can address
2747
+ is not a stylistic drift, and `add`, `ship` and `record add` now all refuse over it
2748
+ (:class:`~roadkeep.kernel.document.RepeatedHeading`) — a gate that stayed quiet would be the
2749
+ only thing in this tool that saw the state and let it stand. A project mid-adoption that
2750
+ has not reached its duplicate yet is what `--baseline` answers (RK84), which is the
2751
+ general answer to standing debt and not a reason to weaken one rule.
2752
+
2753
+ Every governed file with headings, prose included: the rationale file is filed under the
2754
+ same block headings, and `section add` resolves a block there the same way.
2755
+
2756
+ Reported once per label, at the **second** heading and naming the first. The second is
2757
+ the one that was added, and the message needs both addresses because the fix is an
2758
+ editorial merge of two regions that nothing but their line numbers locates.
2759
+
2760
+ **And it names the verb where the verb works** (RK417). One of two headings often stands
2761
+ over nothing — measured on a real corpus — and `block drop <label>` takes exactly that
2762
+ one out, in one command and with no editorial judgement at all; a report that stopped at
2763
+ the diagnosis left the author to research it. The clause is conditional, because that
2764
+ removal is all-or-nothing across the governed set: a file where nothing is removable
2765
+ refuses the whole run, so the condition is asked of every file that declares the label
2766
+ and :func:`~roadkeep.blocking.removable` is the one expression both sides read. If the
2767
+ repair is `block merge` (RK403), the message references the first heading because the
2768
+ merge keeps that first heading and folds the later region into it. Where both regions
2769
+ hold work there is no command to name, and saying so is still the useful half — it
2770
+ tells the reader which of the two cases they are in.
2771
+
2772
+ """
2773
+ word = config.schema.heading_word
2774
+ out: list[Finding] = []
2775
+ for role, document in files.items():
2776
+ where = config.relative(config.path(role))
2777
+ for label in dict.fromkeys(h.label for h in document.headings if h.label):
2778
+ declared = document.declaring(label)
2779
+ if len(declared) < 2:
2780
+ continue
2781
+ first, *rest = declared
2782
+ remedy = (
2783
+ f"`block drop {label}` takes the empty one out"
2784
+ if closes_by_drop(document, rest[0], files, label)
2785
+ # `block merge` is that command, and this clause read "a merge by hand"
2786
+ # until RK425 — prose left behind when RK403 shipped the verb. It named an
2787
+ # edit the guard denies, and the obvious reading of it is a *rename*, which
2788
+ # detaches every entry beneath the second heading: measured, renaming five
2789
+ # produced 83 findings and had to be reverted. So the sentence says what the
2790
+ # command does, because the caller's next question is whether their lines
2791
+ # survive it.
2792
+ else f"`block merge {label}` folds the later region into the first"
2793
+ )
2794
+ for later in rest:
2795
+ out.append(
2796
+ Finding(
2797
+ "block.repeated",
2798
+ where,
2799
+ f"{word} {label} is already declared on line {first.lineno}: one "
2800
+ f"label is one region, neither of these is inside the other, and a "
2801
+ f"write files under the first by position alone — {remedy}"
2802
+ + _moving(document, later, files, label),
2803
+ later.lineno,
2804
+ # The label rather than a task id: this finding is about a heading,
2805
+ # and it is what `block merge` takes (RK420).
2806
+ subject=label,
2807
+ )
2808
+ )
2809
+ return out
2810
+
2811
+
2812
+ def _moving(
2813
+ document: Document, later: Heading, files: dict[str, Document], label: str
2814
+ ) -> str:
2815
+ """What the merge would move, where there is a merge to make (RK425).
2816
+
2817
+ Said only on the branch that names `block merge`: the drop branch removes a region that
2818
+ holds nothing, so a count of zero beside it is a sentence about the absence of a fact.
2819
+ """
2820
+ if closes_by_drop(document, later, files, label):
2821
+ return ""
2822
+ held = _under(document, later)
2823
+ return f", moving the {held} line(s) under it and keeping the file's order"
2824
+
2825
+
2826
+ def _under(document: Document, heading: Heading) -> int:
2827
+ """How many entries sit in **this heading's region** — the lines a merge would move.
2828
+
2829
+ Printed because it is the caller's next question, and the one the report could answer
2830
+ all along: `block merge` moves exactly these, and a number beside the verb is the
2831
+ difference between running it and reading the source first.
2832
+
2833
+ The region ends at the next heading of **any level**, which is the second fact RK425 is
2834
+ about: a `###` cannot group entries inside a block, so a subheading between two regions
2835
+ ends the first one — and a count that ignored the level would promise to move lines the
2836
+ merge leaves where they are.
2837
+ """
2838
+ after = [one.lineno for one in document.headings if one.lineno > heading.lineno]
2839
+ end = min(after) if after else len(document.lines) + 1
2840
+ return sum(1 for e in document.entries if heading.lineno < e.lineno < end)
2841
+
2842
+
2843
+ def closes_by_drop(
2844
+ document: Document, later: Heading, files: dict[str, Document], label: str
2845
+ ) -> bool:
2846
+ """Whether `block drop` would **close this finding** rather than merely run (RK468).
2847
+
2848
+ Two questions and the conjunction, where `_droppable` alone was read as both. That one
2849
+ asks whether the verb will refuse — it is all-or-nothing across files, so a label with
2850
+ work under it anywhere stops the run — and it says nothing about *which* heading comes
2851
+ out. Measured: a repeat in the ledger beside an empty `## Block A` in the roadmap
2852
+ answered droppable, and `block drop` then withdrew the roadmap's heading and left the
2853
+ finding standing, correctly reporting `block merge` on the next run.
2854
+
2855
+ So the region this finding is about has to be the empty one too. `_under` is that
2856
+ question, per heading and per file, and it is the same count `_moving` prints — which is
2857
+ what keeps the sentence, the remedy and the number one answer instead of three.
2858
+
2859
+ Public because `remedying` asks it (RK468): the finding's message branched here and its
2860
+ remedy came from a table that could not, so on a droppable one the two named different
2861
+ commands and `repair` ran the one the sentence did not.
2862
+ """
2863
+ return _under(document, later) == 0 and _droppable(files, label)
2864
+
2865
+
2866
+ def _droppable(files: dict[str, Document], label: str) -> bool:
2867
+ """Whether `block drop <label>` would remove a heading rather than refuse (RK417).
2868
+
2869
+ Asked of every file that declares the label, because that verb is all-or-nothing: one
2870
+ file where nothing is removable refuses the run, including the files whose heading *was*
2871
+ removable. The ledger is the exception it is at the door — its headings hold history and
2872
+ are skipped rather than refused over — so a ledger with nothing removable is not what
2873
+ stops the rest.
2874
+ """
2875
+ declaring = {
2876
+ role: document for role, document in files.items() if document.declaring(label)
2877
+ }
2878
+ if not declaring:
2879
+ return False
2880
+ return any(
2881
+ removable(document, label) is not None for document in declaring.values()
2882
+ ) and all(
2883
+ role == "changelog" or removable(document, label) is not None
2884
+ for role, document in declaring.items()
2885
+ )
2886
+
2887
+
2888
+ def _undeclared_blocks(
2889
+ config: Config, roadmap: Document, ledger: Document, file: str
2890
+ ) -> list[Finding]:
2891
+ """A block planning work the ledger cannot receive it into (RK380).
2892
+
2893
+ Measured in Turing: `## Block BV` carried eight open lines for months and `CHANGELOG.md`
2894
+ declared no such heading. Nothing said so — every one of those lines is valid, its deps
2895
+ resolve, its pointer resolves — and the fact surfaced at the first `ship`, which is the
2896
+ end of a task rather than the start. :func:`~roadkeep.authoring.declaring` closes the
2897
+ door for lines written from here on; this is the state a project already in it is in, and
2898
+ reporting it costs one pass rather than one ship.
2899
+
2900
+ **Only where the block has open lines**, which is what makes it a defect rather than an
2901
+ observation. A roadmap heading over nothing is a block being drafted, and one whose lines
2902
+ have all shipped or left keeps a ledger heading anyway — so the finding fires exactly
2903
+ when there is work that cannot be delivered.
2904
+
2905
+ Reported at the roadmap's heading and not at each line under it: one heading is missing,
2906
+ one command adds it, and a finding per open line would report an eight-line block eight
2907
+ times for a single omission.
2908
+
2909
+ A ledger organised by **nothing** is one finding and not one per block (RK403, RK411).
2910
+ It was silent for a week, because `block add` did not start organising such a file and
2911
+ the sentence would have named a verb that refuses; `--organise <role>` is that remedy now
2912
+ (RK405), and what is restored is deliberately not the per-block shape. There is one thing
2913
+ wrong with that project — its ledger has no headings — and saying it once per roadmap
2914
+ heading is the same omission reported as many defects. So the finding is about the
2915
+ **file**, reported against the ledger and at no line, which is where `file.missing`
2916
+ already reports a whole-file fact. It names one label, because `--organise` is needed for
2917
+ the first heading and never for the second.
2918
+ """
2919
+ out: list[Finding] = []
2920
+ word = config.schema.heading_word
2921
+ if not any(heading.label for heading in ledger.headings):
2922
+ return _unorganised(config, roadmap, word)
2923
+ for heading in roadmap.headings:
2924
+ if heading.label is None or ledger.heading(heading.label) is not None:
2925
+ continue
2926
+ open_lines = roadmap.block(heading.label)
2927
+ if not open_lines:
2928
+ continue
2929
+ out.append(
2930
+ Finding(
2931
+ "block.unrecorded",
2932
+ file,
2933
+ f"{word} {heading.label} plans {len(open_lines)} open line(s) and "
2934
+ f"{config.relative(config.path('changelog'))} declares no heading for it: "
2935
+ f"the first ship in this block refuses — "
2936
+ f'`block add {heading.label} --title "<its title>"`',
2937
+ heading.lineno,
2938
+ subject=heading.label,
2939
+ )
2940
+ )
2941
+ return out
2942
+
2943
+
2944
+ def _unorganised(config: Config, roadmap: Document, word: str) -> list[Finding]:
2945
+ """The whole-file half of :func:`_undeclared_blocks`: a ledger with no heading at all.
2946
+
2947
+ Every `ship` in this project refuses, and one command ends it — so the count that matters
2948
+ is how much work is waiting rather than which block is first, and the label named is only
2949
+ there to make the remedy copyable. Silent where nothing is open: a ledger organised by
2950
+ nothing is how every project starts, and it is a defect only once there is work it cannot
2951
+ receive.
2952
+ """
2953
+ planned = [
2954
+ (heading.label, roadmap.block(heading.label))
2955
+ for heading in roadmap.headings
2956
+ if heading.label
2957
+ ]
2958
+ waiting = [(label, lines) for label, lines in planned if lines]
2959
+ if not waiting:
2960
+ return []
2961
+ label = waiting[0][0]
2962
+ lines = sum(len(entries) for _, entries in waiting)
2963
+ return [
2964
+ Finding(
2965
+ "block.unorganised",
2966
+ config.relative(config.path("changelog")),
2967
+ f"declares no {word.lower()} heading at all, and "
2968
+ f"{config.relative(config.path('roadmap'))} plans {lines} open line(s) under "
2969
+ f"{len(waiting)} of them: every ship here refuses until one exists — "
2970
+ f'`block add {label} --title "<its title>" --organise changelog`',
2971
+ None,
2972
+ subject=label,
2973
+ )
2974
+ ]
2975
+
2976
+
2977
+ def _carried(config: Config, backlog: Backlog) -> list[Finding]:
2978
+ """Every pair of governed files holding a line for one id (RK1082).
2979
+
2980
+ One loop over `referring.PAIRS` rather than a rule per pair. Three files can hold a line
2981
+ — RK96 added the third — and the gate read two of the three pairs, each by its own copy
2982
+ of this loop: RK1081 wrote the second by copying the first, which is the arrangement
2983
+ RK1077 was filed about one layer up. The pairs are a cross product over
2984
+ :data:`~roadkeep.ids.CARRIERS`, so a fourth role that can hold a line is covered by
2985
+ arithmetic instead of by somebody remembering.
2986
+
2987
+ The **wording** stays per pair, which is the line RK1081 drew: open-and-gone is not the
2988
+ sentence open-and-paused is, and the doors differ too. What is shared is which pairs
2989
+ exist and the walk over them; a pair the declaration carries with no code is one nobody
2990
+ has walked into, and it is skipped here and named there.
2991
+
2992
+ `in_halves` is the one tolerated shape (RK121, RK1080) and belongs to the **ledger's own
2993
+ entry**: an entry naming a half is the file saying work arrived in halves, and whatever
2994
+ sits beside it agrees rather than disagrees. No other file can say so, which is why the
2995
+ roadmap–store pair has no tolerance at all.
2996
+
2997
+ Read off whichever side *is* the changelog and no longer off `second` (RK1215). Two of
2998
+ the three pairs put the ledger second and the third puts it first, so the qualifier was
2999
+ being looked for on the store's line — where it never appears — and `id.paused-and-gone`
3000
+ fired on a half-shipped line the store legitimately holds. A tolerance applied to a
3001
+ position rather than to the file that carries the fact is one that works by coincidence.
3002
+ """
3003
+ # Off the `Backlog` the run already holds (RK1085), which is the reader that opens all
3004
+ # three carriers once — the shape `_deps` and `_queued` are handed. Reaching for
3005
+ # `config.document` per pair was one extra parse today and one per pair as carriers are
3006
+ # added, on a check whose caller had the documents in scope the whole time.
3007
+ carriers = {
3008
+ "roadmap": backlog.roadmap,
3009
+ "changelog": backlog.ledger,
3010
+ "deferred": backlog.store,
3011
+ }
3012
+ out: list[Finding] = []
3013
+ for pair in PAIRS:
3014
+ first, second = carriers.get(pair.first), carriers.get(pair.second)
3015
+ if not pair.code or first is None or second is None:
3016
+ continue
3017
+ elsewhere = second.by_id()
3018
+ where = config.relative(config.path(pair.second))
3019
+ filed = config.relative(config.path(pair.first))
3020
+ for task_id, entry in first.by_id().items():
3021
+ held = elsewhere.get(task_id)
3022
+ if held is None:
3023
+ continue
3024
+ recorded = (
3025
+ entry if pair.first == "changelog"
3026
+ else held if pair.second == "changelog"
3027
+ else None
3028
+ )
3029
+ if recorded is not None and recorded.task.in_halves:
3030
+ continue
3031
+ out.append(
3032
+ Finding(
3033
+ pair.code,
3034
+ # The pair's own first file and not the roadmap's (RK1084): the third
3035
+ # pair is filed against the changelog, which is where its line is.
3036
+ filed,
3037
+ f"also on line {held.lineno} of {where}: {pair.says}",
3038
+ entry.lineno,
3039
+ task_id,
3040
+ )
3041
+ )
3042
+ return out
3043
+
3044
+
3045
+ def _deps(backlog: Backlog, task: Task, file: str, lineno: int) -> list[Finding]:
3046
+ """Deps nothing will ever satisfy — three of the four kinds, for three reasons."""
3047
+ out: list[Finding] = []
3048
+ for resolution in backlog.resolve(task):
3049
+ kind, dep = resolution.kind, resolution.dep
3050
+ if resolution.status is DepStatus.UNKNOWN:
3051
+ out.append(
3052
+ Finding(
3053
+ "deps.unknown",
3054
+ file,
3055
+ f"waits on {dep.id}, which is in neither the roadmap nor the "
3056
+ f"changelog: nothing can say whether it is done",
3057
+ lineno,
3058
+ task.id,
3059
+ )
3060
+ )
3061
+ elif resolution.status is not DepStatus.UNRESOLVABLE:
3062
+ continue
3063
+ elif kind is DepKind.TASK:
3064
+ out.append(
3065
+ Finding(
3066
+ "deps.retired",
3067
+ file,
3068
+ f"waits on {dep.id}, which left without shipping: "
3069
+ f"{resolution.detail}",
3070
+ lineno,
3071
+ task.id,
3072
+ )
3073
+ )
3074
+ elif kind is DepKind.BLOCK:
3075
+ out.append(
3076
+ Finding(
3077
+ "deps.block",
3078
+ file,
3079
+ f"waits on {dep.id} and {resolution.detail}",
3080
+ lineno,
3081
+ task.id,
3082
+ )
3083
+ )
3084
+ # An external dep falls through on purpose: waiting on work this backlog does
3085
+ # not track is a fact about the work, and reporting it would fail every file
3086
+ # that states one honestly. A deferred one falls through for the same reason
3087
+ # (RK92) — it is recorded, findable and revivable, and the gate reported it as a
3088
+ # missing id for as long as the resolver had no fifth answer to give.
3089
+ return out
3090
+
3091
+
3092
+ def _pointers(
3093
+ config: Config,
3094
+ documents: dict[str, Document],
3095
+ anchors: dict[str, tuple[Section, ...]],
3096
+ ) -> list[Finding]:
3097
+ """Every `→ §<anchor>` on a line that still has a design, resolved against **every**
3098
+ governed prose file (RK15, widened by RK172) — open, or set aside and still pointing at
3099
+ the rationale a resume needs (RK96).
3100
+
3101
+ Read from the parsed ``ref`` and never from the line's text, which is the whole
3102
+ subtlety: §RK15's own sentence quotes a pointer as an example of one, and a scan
3103
+ over the raw line reports that quotation as a design that does not exist.
3104
+
3105
+ Measured adopting Turing: six open GEO lines carry `→ §X.3` and `→ §X.4`, which
3106
+ `docs/STRATEGY.md` declares and this resolved against the improvements file alone — so
3107
+ the gate called six correct pointers unresolved, and the only ways to satisfy it were to
3108
+ repoint a line at an unrelated section or to move positioning prose out of the file the
3109
+ config declares for it. Where **two** roles declare one anchor the answer is neither
3110
+ file: `ref.ambiguous` names both, because reading the first is what billed T354's `§X.1`
3111
+ 365 words of somebody else's subtree without saying so.
3112
+ """
3113
+ declared = _declared(anchors)
3114
+ where = " or ".join(config.relative(config.path(role)) for role in anchors)
3115
+ out: list[Finding] = []
3116
+ for role in LIVE_ROLES:
3117
+ if role not in documents:
3118
+ continue
3119
+ file = config.relative(config.path(role))
3120
+ for entry in documents[role].entries:
3121
+ ref = entry.task.ref
3122
+ if not ref:
3123
+ continue
3124
+ found = declared.get(ref, ())
3125
+ if not found:
3126
+ out.append(
3127
+ Finding(
3128
+ "ref.unresolved",
3129
+ file,
3130
+ f"points at §{ref}, which is not in {where}: a pointer to a "
3131
+ f"section that does not exist reads as a design that does",
3132
+ entry.lineno,
3133
+ entry.task.id,
3134
+ # The remedy is about the **anchor** and the report is about the line
3135
+ # (RK1206). Under `ref_scheme = "id"` the two are the same string, so
3136
+ # composing the door from the id was right here and wrong everywhere
3137
+ # else: on an outline, `TT1` points at `§I.1`, and `section add TT1`
3138
+ # writes a section the line does not point at — leaving the finding
3139
+ # standing with a second orphan beside it. `subject` is the field
3140
+ # RK420 added for exactly this split, so the prefix stays the id a
3141
+ # reader clicks and the substitution becomes the address that failed.
3142
+ subject=ref,
3143
+ )
3144
+ )
3145
+ elif len(found) > 1:
3146
+ named = " and ".join(
3147
+ config.relative(config.path(other)) for other in found
3148
+ )
3149
+ out.append(
3150
+ Finding(
3151
+ "ref.ambiguous",
3152
+ file,
3153
+ f"points at §{ref}, which {named} both declare: one anchor names "
3154
+ f"one section, and a pointer resolving to two resolves to neither"
3155
+ f"{_namespace_remedy(config)}",
3156
+ entry.lineno,
3157
+ entry.task.id,
3158
+ )
3159
+ )
3160
+ return out
3161
+
3162
+
3163
+ def _citations(
3164
+ config: Config,
3165
+ prose: dict[str, Document],
3166
+ anchors: dict[str, tuple[Section, ...]],
3167
+ ) -> list[Finding]:
3168
+ """Every `§<anchor>` a section's **prose** makes, resolved like a pointer (RK1106).
3169
+
3170
+ The fourth relation, and the gap the other three left between them. `_pointers` reads the
3171
+ ref a task line carries and `_orphans` reads what points at a section; a citation inside a
3172
+ paragraph is neither, so `ship` deletes a design another design argues from and the gate
3173
+ reports clean. Measured on Shio: four citations of retired addresses — `§II.1`, `§II.7`,
3174
+ `§III.1`, `§III.10` — over 641 lines the gate called clean.
3175
+
3176
+ Not a duplicate of what the writers already say. `ship` and `section drop` name the
3177
+ sections citing what *they* are deleting, in the transaction that creates the dangling
3178
+ reference, which is the L1 door and the cheaper moment. This is the backstop for the
3179
+ caller who was told and did not act, and for the hand edit and the merge — and it reads
3180
+ :func:`~roadkeep.sections.references`, the same scan those two select from, so a project
3181
+ never gets two counts of its own dead citations.
3182
+
3183
+ **Resolved against every prose file, exactly as a pointer is**, which is why `declared` is
3184
+ the index and not one document's anchors: a citation of `§S:I.2` from the improvements
3185
+ file is a reference into the strategy file, and asking one document would report the
3186
+ correct half of a project's prose as dangling.
3187
+ """
3188
+ if not prose:
3189
+ return []
3190
+ declared = _declared(anchors)
3191
+ where = " or ".join(config.relative(config.path(role)) for role in anchors)
3192
+ out: list[Finding] = []
3193
+ for role, document in prose.items():
3194
+ file = config.relative(config.path(role))
3195
+ for cited in references(document):
3196
+ if cited.anchor in declared:
3197
+ continue
3198
+ out.append(
3199
+ Finding(
3200
+ "ref.dangling",
3201
+ file,
3202
+ f"§{cited.by} cites §{cited.anchor}, which is not in {where}: prose "
3203
+ f"arguing from a section that is gone reads exactly like a typo, and "
3204
+ f"from the next command on nothing can tell the two apart",
3205
+ cited.lineno,
3206
+ # The **citing** section and not the cited one, which is the subject every
3207
+ # other reference code carries: `ref.unresolved` names the task holding the
3208
+ # pointer, not the heading nothing answers. The edit is here too.
3209
+ subject=cited.by,
3210
+ )
3211
+ )
3212
+ return out
3213
+
3214
+
3215
+ #: A law as a sentence cites one, and the two shapes that are not citations. `#L35` is a line
3216
+ #: anchor inside a URL fragment — the ledger carries one — and `L` followed by a letter is a
3217
+ #: word. A check opening with a false finding on a corpus that has none is how a gate comes to
3218
+ #: be switched off (RK1380), so the exclusions are in the pattern rather than in a filter after.
3219
+ _CITED_LAW = re.compile(r"(?<![#\w])(L[1-9][0-9]*)(?![\w])")
3220
+
3221
+ #: How the authoritative table states one: a leading cell holding the law's own name. Read
3222
+ #: rather than declared, because the table *is* the declaration — `agents.md` carries a
3223
+ #: compressed copy and says this one governs, and a second list in `roadkeep.toml` would be the
3224
+ #: thing the table exists not to be. A project with no such table declares no laws, and then
3225
+ #: this reports **nothing**: an empty declaration means there is nothing to resolve against,
3226
+ #: never that every citation is unknown — which is the direction a gate may not fail in.
3227
+ _DECLARES_LAW = re.compile(r"^\|\s*(L[1-9][0-9]*)\s*\|", flags=re.MULTILINE)
3228
+
3229
+
3230
+ def _laws(
3231
+ config: Config, documents: dict[str, Document], prose: dict[str, Document]
3232
+ ) -> list[Finding]:
3233
+ """A law a governed sentence cites that no prose file declares (RK1380).
3234
+
3235
+ The fourth kind of citation this prose carries and the only one nothing resolved. An anchor
3236
+ is `ref.dangling`, a path is `path.missing`, an id is a dep the parser types — and a law
3237
+ read back as true whatever it said, so an `L7` was a law this project appeared to hold and
3238
+ was a number somebody typed.
3239
+
3240
+ Silent on a project that declares none, which is every adopter: the laws are one project's
3241
+ and the table stating them is what makes the set closed, so where there is no table there is
3242
+ no population and no finding. That is the whole safety of doing this by reading rather than
3243
+ by configuration — an absent declaration reports nothing rather than everything.
3244
+ """
3245
+ declared = {
3246
+ law
3247
+ for document in prose.values()
3248
+ for law in _DECLARES_LAW.findall(document.render())
3249
+ }
3250
+ if not declared:
3251
+ return []
3252
+ where = " or ".join(config.relative(config.path(role)) for role in prose)
3253
+ out: list[Finding] = []
3254
+ # Both sets, because `_Scan` keeps them apart: `documents` is the files organised by lines
3255
+ # and `prose` the ones organised by sections, and a law is cited from a design as readily
3256
+ # as from a ledger sentence — which is the whole population this is about.
3257
+ for role, document in {**documents, **prose}.items():
3258
+ file = config.relative(config.path(role))
3259
+ owner = _owners(document)
3260
+ for lineno, line in enumerate(document.lines, start=1):
3261
+ for found in _CITED_LAW.finditer(line):
3262
+ if found.group(1) in declared:
3263
+ continue
3264
+ out.append(
3265
+ Finding(
3266
+ "law.unknown",
3267
+ file,
3268
+ f"cites {found.group(1)}, which {where} does not declare: the laws "
3269
+ f"are a closed table and a citation of one outside it reads as a rule "
3270
+ f"this project holds, which is the one thing prose may not invent",
3271
+ lineno,
3272
+ # The id or anchor whose prose carries the sentence, so the door is one
3273
+ # command and not a shape to fill (RK420) — every other finding here
3274
+ # names the thing its remedy addresses, and a citation's is whatever
3275
+ # owns the line it sits on.
3276
+ owner.get(lineno, ""),
3277
+ # And the offset by name, which is what makes one `L` among a
3278
+ # paragraph's words findable by eye (RK34).
3279
+ column=found.start(1) + 1,
3280
+ )
3281
+ )
3282
+ return out
3283
+
3284
+
3285
+ def _owners(document: Document) -> dict[int, str]:
3286
+ """Which id or anchor owns each line of one governed file (RK1380).
3287
+
3288
+ A citation is corrected through the verb that owns the prose it sits in, and every one of
3289
+ those takes an address: `amend` a line's id, `section amend` an anchor, `record amend` an
3290
+ entry's id. So a finding about a *line* has to resolve it, or its door is a shape rather
3291
+ than a command.
3292
+
3293
+ Both organisations, read through the two readers that already answer this: an entry knows
3294
+ the span it owns because a ledger bullet may wrap (RK157), and a section knows its own from
3295
+ `first` to `last`. A line owned by neither — a heading, a blank, prose above the first
3296
+ section — answers `""`, which is the honest state and the one the remedy's blank is for.
3297
+ """
3298
+ from roadkeep.sections import anchored # noqa: PLC0415 - RK260
3299
+
3300
+ out: dict[int, str] = {}
3301
+ for entry in document.entries:
3302
+ for lineno in range(entry.lineno, max(entry.stop, entry.lineno) + 1):
3303
+ out[lineno] = entry.task.id
3304
+ for section in anchored(document):
3305
+ for lineno in range(section.first, section.last + 1):
3306
+ out.setdefault(lineno, section.anchor)
3307
+ return out
3308
+
3309
+
3310
+ def _namespace_remedy(config: Config) -> str:
3311
+ """The configuration that makes two colliding addresses two addresses (RK340).
3312
+
3313
+ Named at the finding and not only in the docs, because the state it reports is one a
3314
+ project cannot edit its way out of: both files number their own outline from `I`, so
3315
+ "rename one of them" is a renumbering of somebody's whole document. Silent where the
3316
+ project already declares a namespace for both — there the collision is inside one of
3317
+ them, and `[refs]` has nothing left to say about it.
3318
+ """
3319
+ if all(role in config.refs for role in PROSE_ROLES if config.has(role)):
3320
+ return ""
3321
+ return (
3322
+ " — `[refs] <role> = \"<prefix>\"` in roadkeep.toml gives one of the two files its "
3323
+ "own namespace, so its addresses are written §<prefix>:<x.y>"
3324
+ )
3325
+
3326
+
3327
+ def _crossing(
3328
+ config: Config,
3329
+ prose: dict[str, Document],
3330
+ anchors: dict[str, tuple[Section, ...]],
3331
+ ) -> list[Finding]:
3332
+ """A citation that resolves into the **other** prose file while a local one exists (RK1168).
3333
+
3334
+ Declaring `[refs]` re-addresses every heading in a file at once — 48 of them in the run this
3335
+ was measured on — and carries none of that file's own citations. Seven became `ref.dangling`,
3336
+ which the gate reports; **twenty-one kept resolving**, into the other file's section of the
3337
+ same address, because both files declared it — which is why they collided at all and why the
3338
+ key was declared in the first place. Nothing said a word about those.
3339
+
3340
+ That is worse than a dead reference: a dangling citation stops a reader, and this one hands
3341
+ them somebody else's design under the address they meant. So the shape reported is exactly
3342
+ that state — the citing file gives its own headings a namespace, the citation is written bare,
3343
+ and the namespaced address it would have meant is a section that exists here.
3344
+
3345
+ Not every bare citation into another file. A project's prose argues from the other file all
3346
+ the time and `§S:I.2` is how it says so; what makes this a finding is that the same address
3347
+ resolves **both** ways and the local one is the file the sentence is in.
3348
+ """
3349
+ declared = _declared(anchors)
3350
+ out: list[Finding] = []
3351
+ for role, document in prose.items():
3352
+ namespace = document.schema.ref_prefix
3353
+ if not namespace:
3354
+ continue
3355
+ file = config.relative(config.path(role))
3356
+ for cited in references(document):
3357
+ local = f"{namespace}:{cited.anchor}"
3358
+ if local not in declared or role in declared.get(cited.anchor, ()):
3359
+ continue
3360
+ elsewhere = declared.get(cited.anchor, ())
3361
+ if not elsewhere:
3362
+ continue # `ref.dangling` is that finding, and one state is one code
3363
+ named = " and ".join(config.relative(config.path(one)) for one in elsewhere)
3364
+ out.append(
3365
+ Finding(
3366
+ "ref.crossed",
3367
+ file,
3368
+ f"§{cited.by} cites §{cited.anchor}, which resolves into {named} while "
3369
+ f"§{local} is this file's own: a namespace re-addressed the headings and "
3370
+ f"not the prose citing them, so the reference reads as correct and answers "
3371
+ f"with somebody else's design",
3372
+ cited.lineno,
3373
+ subject=cited.by,
3374
+ )
3375
+ )
3376
+ return out
3377
+
3378
+
3379
+ def _declared(anchors: dict[str, tuple[Section, ...]]) -> dict[str, tuple[str, ...]]:
3380
+ """Which prose roles declare which anchor — one index, read by resolution and by budget.
3381
+
3382
+ A role that declares an anchor twice says so once here: `section.duplicate` is that
3383
+ file's own finding, and counting it again would make one file's mistake read as two
3384
+ files disagreeing.
3385
+ """
3386
+ out: dict[str, list[str]] = {}
3387
+ for role, found in anchors.items():
3388
+ for anchor in dict.fromkeys(section.anchor for section in found):
3389
+ out.setdefault(anchor, []).append(role)
3390
+ return {anchor: tuple(roles) for anchor, roles in out.items()}
3391
+
3392
+
3393
+ def _orphans(
3394
+ config: Config,
3395
+ documents: dict[str, Document],
3396
+ prose: Document,
3397
+ anchors: dict[str, tuple[Section, ...]],
3398
+ *,
3399
+ role: str,
3400
+ ) -> list[Finding]:
3401
+ """One prose file read from its own side: a section, and what points at it.
3402
+
3403
+ A pointer resolves one way only, so nothing in `_pointers` can see a section that
3404
+ survived its task. Three ways that happens and one budget, all at the anchor's line.
3405
+
3406
+ Called **per governed prose role** (RK172), because a strategy file is a prose file: its
3407
+ sections are pointed at, budgeted and orphaned by the same rules, and a gate that read
3408
+ one of the two would leave the other ungoverned in exactly the way the roadmap is not.
3409
+
3410
+ The budget is charged against **what a pointer hands a reader**, which is the one
3411
+ reading that keeps RK9's rule and this repository's own file both true: a section a
3412
+ line points at is measured with its subsections (`show` prints them, so a rationale
3413
+ that doubled by growing a `§RK34.1` is caught), and one nothing points at is measured
3414
+ on its own prose (`§0` is a container whose three anchored children are each inside
3415
+ the budget, and charging it 461 words would fail a file with no long paragraph in it).
3416
+ An anchor **two** files declare is charged as pointed at by nobody: which of the two a
3417
+ line meant is what `ref.ambiguous` asks the author, and billing one of them 365 words of
3418
+ the other's subtree in the meantime is the silent half of that defect.
3419
+
3420
+ Which is also reported **here**, at the heading, and that is RK239: `ref.ambiguous`
3421
+ fires from the pointer end, so the state is named only where a task line happens to
3422
+ reach it. Turing at `f08304fcb1` declares thirteen anchors in both prose files, one is
3423
+ pointed at, and the other twelve were reported by nothing — while `show`, `brief`,
3424
+ `ship` and `defer` all already refuse to resolve them (RK186/RK196/RK229) and
3425
+ `_budget` above charges them as unreachable. `section.ambiguous` is the same word from
3426
+ the file that made the claim, once per heading, because the remedy is an edit at each
3427
+ of the two and `id.duplicate` is the shape an editor can act on twice. Not `--fix`'s:
3428
+ which of the two is the design is editorial (RK16).
3429
+ """
3430
+ file = config.relative(config.path(role))
3431
+ sections = anchors[role]
3432
+ declared = _declared(anchors)
3433
+ # A deferred task's section is carried, not deleted (RK96), so the line that owns it is
3434
+ # in the store rather than the roadmap — and reporting it orphaned would make the gate
3435
+ # demand the deletion of exactly what a resume restores.
3436
+ # And the decisions file owns its own prose (RK1361): a body there belongs to the record
3437
+ # one bullet up, not to a roadmap line — so the ledger is not what decides it left. Read
3438
+ # off the file being judged, because that is the whole difference between the two kinds of
3439
+ # body: a design is deleted by the ship that files the decision, and the decision's body
3440
+ # is what survives it. Superseded entries included, both halves of a `supersede` keeping
3441
+ # theirs — the record of what a replacement was needed against is the body it replaced.
3442
+ owning = ("decisions",) if role == "decisions" else LIVE_ROLES
3443
+ lines = {
3444
+ task_id: entry
3445
+ for one in owning
3446
+ if one in documents
3447
+ for task_id, entry in documents[one].by_id().items()
3448
+ }
3449
+ kept = set(lines)
3450
+ gone = (
3451
+ {}
3452
+ if role == "decisions"
3453
+ else (documents["changelog"].by_id() if "changelog" in documents else {})
3454
+ )
3455
+ pointed = {
3456
+ entry.task.ref
3457
+ for document in documents.values()
3458
+ for entry in document.entries
3459
+ if entry.task.ref and len(declared.get(entry.task.ref, ())) == 1
3460
+ }
3461
+ claimed = _claimed(documents)
3462
+ ids = config.schema.id_pattern()
3463
+ seen: dict[str, int] = {}
3464
+ out: list[Finding] = []
3465
+
3466
+ for section in sections:
3467
+ anchor = section.anchor
3468
+ first = seen.get(anchor)
3469
+ if first is not None:
3470
+ out.append(
3471
+ Finding(
3472
+ "section.duplicate",
3473
+ file,
3474
+ f"§{anchor} is already at line {first}: an anchor names one "
3475
+ f"section, and a pointer that resolves to two resolves to neither",
3476
+ section.first,
3477
+ anchor,
3478
+ )
3479
+ )
3480
+ elif len(declared.get(anchor, ())) > 1:
3481
+ # Once per file and never per copy, for the reason `_declared` dedupes a role:
3482
+ # a file that declares the anchor twice already carries the finding above, and
3483
+ # counting it again here would read as three files disagreeing.
3484
+ elsewhere = " and ".join(
3485
+ config.relative(config.path(other))
3486
+ for other in declared[anchor]
3487
+ if other != role
3488
+ )
3489
+ out.append(
3490
+ Finding(
3491
+ "section.ambiguous",
3492
+ file,
3493
+ f"§{anchor} is declared in {elsewhere} as well: one anchor names one "
3494
+ f"section, so no pointer here resolves and every verb that reads one "
3495
+ f"refuses{_namespace_remedy(config)}",
3496
+ section.first,
3497
+ anchor,
3498
+ # The fact these findings **share** (RK469): the pair of files, not the
3499
+ # address. Measured on Turing, 27 of them filled 80% of the report with
3500
+ # one sentence and one remedy repeated, and a single `[refs]` line closes
3501
+ # every one — so the reader is told the pair once and the addresses under
3502
+ # it. The findings stay one per address, because the addresses are the
3503
+ # evidence an author picking which file takes the namespace reads.
3504
+ shared=f"declared in {elsewhere} as well",
3505
+ )
3506
+ )
3507
+ seen.setdefault(anchor, section.first)
3508
+ out.extend(_budget(prose, section, pointed=anchor in pointed, file=file))
3509
+ out.extend(_query(config, section, file))
3510
+ out.extend(_hollow(prose, section, file, pointed=anchor in pointed))
3511
+ out.extend(_promise(config, section, file))
3512
+ owners = section_owners(section, ids)
3513
+ # Prose that belongs to no task is nobody's orphan — `§0.1` under the id scheme, and
3514
+ # any outline heading that names no id — the same rule `section add` applies (RK9).
3515
+ if not owners:
3516
+ continue
3517
+ if any(owner in kept for owner in owners):
3518
+ finding = _unreachable(section, file, owners=owners, lines=lines, claimed=claimed)
3519
+ else:
3520
+ finding = _unowned(
3521
+ section,
3522
+ file,
3523
+ shipped=any(owner in gone for owner in owners),
3524
+ owners=owners,
3525
+ claimants=tuple(claimed.get(anchor, ())),
3526
+ )
3527
+ if finding is not None:
3528
+ out.append(finding)
3529
+ return out
3530
+
3531
+
3532
+ def _claimed(documents: dict[str, Document]) -> dict[str, list[str]]:
3533
+ """Which open lines point at which anchor — :func:`~roadkeep.sections.pointers`' index.
3534
+
3535
+ Rebuilt from the documents this run already read rather than from disk, because a
3536
+ baseline run judges a revision and the gate has to ask its questions of that tree.
3537
+
3538
+ And the decisions file's own records, which claim by pointer under an outline (RK1363).
3539
+ The same index `sections.pointers` builds, so the gate and the writer cannot disagree —
3540
+ which is the disagreement `_pointed_at` exists to prevent, found here as a
3541
+ `section.unreachable` on a body the ship had just addressed correctly. Not in
3542
+ :data:`LIVE_ROLES`: those are the roles whose *lines* are still open work, and a decision
3543
+ is not open work — it is a record that never leaves, which is why its claim never lapses.
3544
+ """
3545
+ out: dict[str, list[str]] = {}
3546
+ for role in (*LIVE_ROLES, "decisions"):
3547
+ for entry in documents[role].entries if role in documents else ():
3548
+ if entry.task.ref:
3549
+ out.setdefault(entry.task.ref, []).append(entry.task.id)
3550
+ return out
3551
+
3552
+
3553
+ def _unreachable(
3554
+ section: Section,
3555
+ file: str,
3556
+ *,
3557
+ owners: tuple[str, ...],
3558
+ lines: dict[str, Entry],
3559
+ claimed: dict[str, list[str]],
3560
+ ) -> Finding | None:
3561
+ """A section whose task is alive and points somewhere else (RK135).
3562
+
3563
+ The gap the three neighbouring checks leave between them, measured on Shio: `XV.21` and
3564
+ `XV.22` carried the same title — one an earlier draft of the other — and SH265 points at
3565
+ `XV.22`. `section.orphan` did not fire, the id in the title being an open line;
3566
+ `section.duplicate` did not fire, the anchors differing; `ref.unresolved` did not fire,
3567
+ the pointer resolving somewhere. Twenty-three lines of superseded design lint clean, and
3568
+ the only reason it was found is that a reader compared two adjacent headings.
3569
+
3570
+ Reachability is the pointer index and never the title, so the two readers RK134 split
3571
+ apart stay one: a section **any** open line points at is reached, and so is one under an
3572
+ anchor a pointer names — `§RK34.1` is handed to a reader by the `§RK34` its parent's
3573
+ pointer resolves to, which is the same subtree `show` prints and `_budget` measures.
3574
+
3575
+ Not an orphan, and the remedy is not a drop: the task is alive, one of the two sections
3576
+ is its design and the other is history, and which is which is a reading.
3577
+ """
3578
+ if _reached(section.anchor, claimed):
3579
+ return None
3580
+ elsewhere = [
3581
+ (owner, lines[owner].task.ref)
3582
+ for owner in owners
3583
+ if owner in lines and lines[owner].task.ref
3584
+ ]
3585
+ if not elsewhere:
3586
+ return None
3587
+ named = ", ".join(f"{owner} points at §{ref}" for owner, ref in elsewhere)
3588
+ return Finding(
3589
+ "section.unreachable",
3590
+ file,
3591
+ f"{named}, so no pointer resolves here: the task is alive and its design is "
3592
+ f"somewhere else, which makes one of the two history rather than a deletion",
3593
+ section.first,
3594
+ section.anchor,
3595
+ )
3596
+
3597
+
3598
+ def _reached(anchor: str, claimed: dict[str, list[str]]) -> bool:
3599
+ """Does an open line's pointer hand a reader this section — directly or by its parent?
3600
+
3601
+ Segment by segment and never by string, the care :func:`~roadkeep.sections._extends`
3602
+ takes at the other end: `§0.1` is not under `§0.10`, and reading it as one would silence
3603
+ a check on a section nobody can reach.
3604
+ """
3605
+ segments = anchor.split(".")
3606
+ return any(
3607
+ ".".join(segments[:depth]) in claimed for depth in range(1, len(segments) + 1)
3608
+ )
3609
+
3610
+
3611
+ def _query(config: Config, section: Section, file: str) -> list[Finding]:
3612
+ """The `roadkeep-remaining` block a design may declare, held to its grammar (RK492).
3613
+
3614
+ The backstop half of L1 for a fence: `remaining` refuses one it cannot read, but that verb
3615
+ is asked by whoever is continuing the migration, and a query nobody has run since it was
3616
+ typed is exactly the one that is wrong. So the gate reads it on every run, which costs one
3617
+ string scan per section and answers the only question the fence can be wrong about.
3618
+
3619
+ A section declaring none is silent, which is every section here: this reports a block that
3620
+ exists and does not parse, never the absence of one. The count itself is `remaining`'s and
3621
+ never a finding — sites left are work, and work is not a defect in a file.
3622
+ """
3623
+ from roadkeep.remaining import ( # noqa: PLC0415 - RK260
3624
+ EVIDENCE,
3625
+ FENCE,
3626
+ QueryError,
3627
+ declared,
3628
+ )
3629
+
3630
+ # Both fences, and one rule (RK1184): the criterion is the same grammar with the sign
3631
+ # flipped, so a block it cannot read is the same finding — and reporting one kind and
3632
+ # not the other would be the gate holding half of what the parser accepts.
3633
+ found: list[Finding] = []
3634
+ for tag in (FENCE, EVIDENCE):
3635
+ if tag not in section.body:
3636
+ continue
3637
+ try:
3638
+ declared(section.body, tag)
3639
+ except QueryError as error:
3640
+ found.append(
3641
+ Finding(
3642
+ "remaining.format",
3643
+ file,
3644
+ f"§{section.anchor} declares a `{tag}` block this grammar cannot "
3645
+ f"read: {error}",
3646
+ section.first,
3647
+ section.anchor,
3648
+ )
3649
+ )
3650
+ continue
3651
+ found += _directoried(config, section, file, tag)
3652
+ return found
3653
+
3654
+
3655
+ #: What makes a pathspec a **pattern** rather than a name (RK1222). `Path.glob`'s own three,
3656
+ #: and the whole of the narrowing below: a spec carrying one of these is a query the author
3657
+ #: wrote as a query, and a migration whose sites were deleted rather than rewritten ends with
3658
+ #: exactly such a spec matching nothing — which is the query working.
3659
+ _GLOBBED = ("*", "?", "[")
3660
+
3661
+
3662
+ def _directoried(
3663
+ config: Config, section: Section, file: str, tag: str
3664
+ ) -> list[Finding]:
3665
+ """A pathspec that is a directory where a pattern was meant (RK1222).
3666
+
3667
+ RK1216 gave the *read* the words — `remaining` names a pathspec that reached no file, on
3668
+ the headline and beside its own clause — and left the gate to this task, because the typo
3669
+ is in a governed file and a claim nothing can answer is what `lint` refuses for a pointer,
3670
+ a dead queue entry and an unreadable fence.
3671
+
3672
+ **The false positive is real and this is the narrowing that avoids it.** A migration whose
3673
+ sites are *deleted* rather than rewritten ends with its pathspec matching nothing, and that
3674
+ is the query working — the same zero, arrived at honestly. A finding on that would fire on
3675
+ the finished migration it was meant to tell apart from the typo, which is RK1216's own
3676
+ confusion with the sign flipped.
3677
+
3678
+ So this fires on one shape only, and it is the shape both measured cases had: a spec with
3679
+ **no glob metacharacter** that names an **extant directory**. `lib/src :: <regex>` reads as
3680
+ a directory, which `Path.glob` matches as one entry that is not a file, so the whole query
3681
+ answered `0 site(s) left in 0 file(s)` over trees holding 14 and 420. Corrected to
3682
+ `lib/src/**/*.c` the tool agrees exactly; nothing was wrong but the glob.
3683
+
3684
+ A spec that carries a metacharacter is the author's query and is left alone, whatever it
3685
+ matches. A spec naming a directory that is *gone* is left alone too — that is the deleted
3686
+ migration, and the read already says so in words.
3687
+ """
3688
+ from roadkeep.remaining import declared # noqa: PLC0415 - RK260
3689
+
3690
+ out: list[Finding] = []
3691
+ for clause in declared(section.body, tag):
3692
+ spec = clause.pathspec
3693
+ if any(one in spec for one in _GLOBBED):
3694
+ continue
3695
+ if not (config.root / spec).is_dir():
3696
+ continue
3697
+ out.append(
3698
+ Finding(
3699
+ "remaining.unmatched",
3700
+ file,
3701
+ f"§{section.anchor} queries `{spec}`, which is a directory: `Path.glob` "
3702
+ f"matches it as one entry that is not a file, so this clause reads every "
3703
+ f"file in it and finds none — `{spec}/**/*` is the pattern it was meant as",
3704
+ section.first,
3705
+ section.anchor,
3706
+ )
3707
+ )
3708
+ return out
3709
+
3710
+
3711
+ def _promise(config: Config, section: Section, file: str) -> list[Finding]:
3712
+ """A design naming an id no line carries, once a file already holds one (RK1003).
3713
+
3714
+ The backstop half of L1 for the rule RK1002 put at the door, and :func:`_query`'s shape
3715
+ exactly: `section add` refuses the body, and this reads what is already on disk. The
3716
+ three ways one gets there without passing a door are the three the backstop exists for —
3717
+ an adopted backlog, a hand edit and a textual merge.
3718
+
3719
+ Reproduced the hour RK1002 shipped: a design edited to name an unclaimed id left `lint`
3720
+ clean while `next-id` warned about it inside another command's output, hedged, with
3721
+ nothing that had to act on the warning.
3722
+
3723
+ **Not repairable, and it says so through its remedy rather than through `--fix`**: which
3724
+ of two ids an author meant is a judgement about a sentence, and the tool has no model of
3725
+ one (L4). The finding names the same two ways out the refusal does.
3726
+
3727
+ Under the same code the door raises, which is what :class:`Finding` promises about every
3728
+ rule the two surfaces share: a caller filtering on `body.promise` filters one rule.
3729
+ """
3730
+ # Deferred beside `_query`'s, and one-way for the same reason (RK260).
3731
+ from roadkeep.sections import known, promised # noqa: PLC0415 - RK1003
3732
+
3733
+ return [
3734
+ Finding("body.promise", file, f"§{section.anchor} {one.message}", section.first, section.anchor)
3735
+ for one in promised(config.schema_for("roadmap"), section.body, known(config, section.anchor, None))
3736
+ ]
3737
+
3738
+
3739
+ def _hollow(prose: Document, section: Section, file: str, *, pointed: bool) -> list[Finding]:
3740
+ """A section a pointer resolves to that gives the reader nothing (RK1012).
3741
+
3742
+ The two states RK1004's register measured as reachable and reported by nothing: a heading
3743
+ with no prose under it, and one addressed with no title. `section add` refuses both — the
3744
+ door's own words are *a section with no prose is a heading* and *a section is named by its
3745
+ heading* — and a file carrying either lints clean.
3746
+
3747
+ Neither is cosmetic, and the pointer is why. A line renders `→ §<id>` and the gate holds
3748
+ that the address resolves, so a heading with nothing under it satisfies that check while
3749
+ giving the reader none of what the pointer promised: `show` prints it and `brief` hands it
3750
+ to whoever starts the task, both answering with a title and a blank.
3751
+
3752
+ The five rows beside them in that register stay silent and are a different answer: a
3753
+ heading is one line, so a newline in a title is about an argument, and an address this
3754
+ scheme cannot read is not parsed as a section at all — the heading is prose, and prose in
3755
+ a prose file is allowed.
3756
+
3757
+ Not repairable, which is why both are `compose`: what the paragraph should say and what
3758
+ the heading should be called are the author's, and the tool writes neither (L4).
3759
+
3760
+ **Only a section a line points at**, which is the symptom's own wording and the thing that
3761
+ makes it decidable. A heading nothing addresses is prose under a heading — this file's own
3762
+ `§0` is one, a container whose children are the rationale — and `section.orphan` is what
3763
+ names one of those. The subtree is read for the same reason `_budget` reads it: the walk
3764
+ hands over a section's own paragraph, and a parent's argument is its children.
3765
+ """
3766
+ if not pointed:
3767
+ return []
3768
+ whole = find(prose, section.anchor) or section
3769
+ out: list[Finding] = []
3770
+ if not section.title.strip():
3771
+ out.append(
3772
+ Finding(
3773
+ "title.empty",
3774
+ file,
3775
+ f"§{section.anchor} is addressed and unnamed: a section is named by its "
3776
+ f"heading, and a pointer resolving here reaches an address and no subject",
3777
+ section.first,
3778
+ section.anchor,
3779
+ )
3780
+ )
3781
+ if not whole.body.strip():
3782
+ out.append(
3783
+ Finding(
3784
+ "body.empty",
3785
+ file,
3786
+ f"§{section.anchor} has a heading and no prose: the line pointing here "
3787
+ f"promised a rationale, and `show` answers with a title and a blank",
3788
+ section.first,
3789
+ section.anchor,
3790
+ )
3791
+ )
3792
+ return out
3793
+
3794
+
3795
+ def _budget(
3796
+ prose: Document, section: Section, *, pointed: bool, file: str
3797
+ ) -> list[Finding]:
3798
+ handed = (find(prose, section.anchor) if pointed else None) or section
3799
+ # The prose file's own budget where it declares one (RK50): `[limits.improvements]` is
3800
+ # the same declaration `[limits.changelog]` is, and this is the file it governs.
3801
+ limit = prose.schema.section_max
3802
+ if handed.words <= limit:
3803
+ return []
3804
+ return [
3805
+ Finding(
3806
+ "section.too-long",
3807
+ file,
3808
+ f"{over_by(handed.words, limit, unit='word')}; a section this long is "
3809
+ f"two sections, or a paragraph that belongs in the commit",
3810
+ section.first,
3811
+ section.anchor,
3812
+ )
3813
+ ]
3814
+
3815
+
3816
+ def _unowned(
3817
+ section: Section,
3818
+ file: str,
3819
+ *,
3820
+ shipped: bool,
3821
+ owners: tuple[str, ...],
3822
+ claimants: tuple[str, ...] = (),
3823
+ ) -> Finding | None:
3824
+ """A section whose task no open line carries — gone, or never there.
3825
+
3826
+ `owners` is what the section says it belongs to, which is the anchor under the id scheme
3827
+ and the ids in the heading under an outline (RK61). Named in the message, because
3828
+ `§XVI.12` alone tells a reader nothing about which task left.
3829
+
3830
+ `claimants` is the other reader of the same fact, and until RK134 the two disagreed:
3831
+ this check decided from the ids in the heading while `section drop` decides from the
3832
+ pointers that resolve, so a section **still pointed at by** four open lines was reported
3833
+ stale and the only remedy the finding named was the one the tool refuses. RK64 already
3834
+ settled it for `ship` — a section another open line points at is kept, and the reason is
3835
+ reported — so the state this reports is the one `ship` itself writes. Shio's `VI.1` is
3836
+ the live case: SH22 shipped, SH44-SH47 are open against the same design, and the only
3837
+ way out was to retitle the heading by hand. A finding whose remedy the tool refuses is
3838
+ worse than no finding, which is the split RK16 exists to keep.
3839
+ """
3840
+ if claimants:
3841
+ return None
3842
+ named = ", ".join(owners)
3843
+ if shipped:
3844
+ return Finding(
3845
+ "section.stale",
3846
+ file,
3847
+ f"{named} is in the changelog and this rationale is still here: "
3848
+ f"`ship` deletes the section, so this survived a hand edit",
3849
+ section.first,
3850
+ section.anchor,
3851
+ )
3852
+ return Finding(
3853
+ "section.orphan",
3854
+ file,
3855
+ f"no line in any governed file carries {named}, so nothing can ever point "
3856
+ f"at this section",
3857
+ section.first,
3858
+ section.anchor,
3859
+ )
3860
+
3861
+
3862
+ def _paths(config: Config, documents: dict[str, Document], tree: Tree) -> list[Finding]:
3863
+ """Paths a *shipped* line claims, resolved against disk (RK15, narrowed by RK46).
3864
+
3865
+ Two exemptions, and both turn on which file is being read rather than on the token.
3866
+
3867
+ Lines only: an unshipped design's whole job is to describe a file that does not exist
3868
+ yet — §RK26 names `.claude-plugin/marketplace.json` and is right to — so resolving a
3869
+ section's prose would fail every honest forward reference.
3870
+
3871
+ And the ledger only, which is the same reasoning applied one file up. A roadmap
3872
+ describes work that has **not happened**, so the paths in it are disproportionately
3873
+ the artefacts its tasks exist to write; naming one is what a task line is for. Shio
3874
+ had eight such findings and all eight were false. A shipped line is the opposite
3875
+ claim — the work is done, so a path it names and the repository lacks is a real
3876
+ defect, and the only one here worth exit 1.
3877
+
3878
+ The one place a baseline run resolves against the *revision* rather than the working
3879
+ tree (RK84). It has to: this finding is the only one whose subject is outside the
3880
+ governed files, so an artefact deleted since the ref would otherwise be missing in both
3881
+ runs and forgiven — and a rename the ledger did not follow is precisely the true finding
3882
+ this check produced on the corpus that motivated it.
3883
+
3884
+ **And the working tree is then not a reader at all** (RK218). Half of that resolution
3885
+ moved and half did not: `carries` and `anywhere` asked git at the ref while
3886
+ `referenced.exists` still asked this disk, so a file created since the ref — untracked,
3887
+ never committed, invisible to git — silenced a finding the revision genuinely had. The
3888
+ same commit answered two ways depending on somebody's scratch file. So at a revision the
3889
+ filesystem is skipped outright rather than corrected: `exists` is a fact about now, and
3890
+ a run that names a revision is not asking about now.
3891
+ """
3892
+ document = documents.get("changelog")
3893
+ if document is None:
3894
+ return []
3895
+ file = config.relative(config.path("changelog"))
3896
+ near = config.path("changelog").parent
3897
+ # One pass, keeping what it found (RK223). The candidates have to be gathered before
3898
+ # `.gitignore` is asked, because one call for all of them is what keeps that question
3899
+ # cheap (RK213) — and gathering them with a comprehension of its own made the findings
3900
+ # comprehension repeat the whole scan: 1602 entries into `paths_in` for 801 entries,
3901
+ # and 2.9 s of a `lint` that a pre-commit hook waits for (RK17).
3902
+ unresolved = [
3903
+ (entry, token)
3904
+ for entry in document.entries
3905
+ for token in _candidates(tree, entry.raw, near)
3906
+ ]
3907
+ untracked = tree.declared_untracked([(token, near) for _, token in unresolved])
3908
+ left = _left_the_repository(config, tree, [token for _, token in unresolved])
3909
+ return [
3910
+ Finding(
3911
+ "path.missing",
3912
+ file,
3913
+ f"names {token}, which is not in the repository",
3914
+ entry.lineno,
3915
+ entry.task.id,
3916
+ )
3917
+ for entry, token in unresolved
3918
+ # Not a path this repository has declared it will never track (RK213): a build
3919
+ # output is absent from a bare checkout and present for whoever just compiled, so
3920
+ # a gate that read the filesystem alone answered by machine.
3921
+ if token not in untracked
3922
+ # And not one it *had* when the entry was written (RK1217): a shipped sentence is a
3923
+ # claim about the tree that shipped it, and a file later extracted into its own
3924
+ # repository makes history a finding on every run for ever.
3925
+ and token not in left
3926
+ ]
3927
+
3928
+
3929
+ def _left_the_repository(
3930
+ config: Config, tree: Tree, tokens: Sequence[str]
3931
+ ) -> frozenset[str]:
3932
+ """Which of these paths this repository once held and no longer does (RK1217).
3933
+
3934
+ Asked **last and only of what already failed**, which is the whole of its cost: `exists`,
3935
+ `anywhere` and `check-ignore` have each answered before a token reaches here, so a healthy
3936
+ repository asks git nothing and a corpus with stale entries pays one call per token — six
3937
+ on the ledger that motivated this, against 801 entries.
3938
+
3939
+ Skipped at a revision, where the question is already being asked of history: a run naming a
3940
+ `--baseline` resolves the tree at that ref (RK218), and reaching past it to *every* ref
3941
+ would forgive a path the baseline's own tree never had.
3942
+ """
3943
+ if tree.rev is not None or not tokens:
3944
+ return frozenset()
3945
+ from roadkeep.history import left_the_repository # noqa: PLC0415 - RK260
3946
+
3947
+ return frozenset(
3948
+ token
3949
+ for token in dict.fromkeys(tokens)
3950
+ if left_the_repository(config.root, token)
3951
+ )
3952
+
3953
+
3954
+ def _candidates(tree: Tree, text: str, near: Path) -> tuple[str, ...]:
3955
+ """Every path one sentence names that this tree does not have, before `.gitignore`.
3956
+
3957
+ The half :func:`_paths` and :func:`unresolved` share, so the gate and the write path
3958
+ cannot come to disagree about what counts as missing — which they would, being written
3959
+ weeks apart against the same six rules (RK55, RK173, RK213, RK217, RK218).
3960
+
3961
+ ``known`` is the bound method and not its answer (RK222): it caches, so passing it makes
3962
+ the listing lazy for free, and a sentence whose every path resolves asks git nothing.
3963
+ """
3964
+ return tuple(
3965
+ referenced.path
3966
+ for referenced in paths_in(
3967
+ text,
3968
+ tree.config.root,
3969
+ near=near,
3970
+ known=tree.directories,
3971
+ has=lambda token: tree.holds(token, near),
3972
+ )
3973
+ if not referenced.exists and not tree.anywhere(referenced.path)
3974
+ )
3975
+
3976
+
3977
+ def unresolved(config: Config, text: str) -> tuple[str, ...]:
3978
+ """The paths a sentence about *shipped* work names that this repository lacks (RK497).
3979
+
3980
+ The gate's own `path.missing` rule, asked before the prose exists rather than after it
3981
+ lands — which is L1, and the reason this is here rather than a second reading in
3982
+ :mod:`roadkeep.shipping`: one definition of missing, called from both ends.
3983
+
3984
+ Measured cost, and why a write can afford it: `paths_in` asks the filesystem per token
3985
+ and asks git only for a token that fails (RK222), and `check-ignore` runs only for what
3986
+ survives that (RK213). A sentence whose paths resolve — every sentence anybody means to
3987
+ write — costs one `stat` each and no subprocess at all.
3988
+
3989
+ Resolved against the **working tree**, never a revision: the caller is writing the entry
3990
+ now, so "now" is the only tree the question can be about.
3991
+ """
3992
+ near = config.path("changelog").parent
3993
+ tree = Tree(config)
3994
+ found = _candidates(tree, text, near)
3995
+ untracked = tree.declared_untracked([(token, near) for token in found])
3996
+ return tuple(token for token in found if token not in untracked)
3997
+
3998
+
3999
+ def _declared_untracked(
4000
+ config: Config, tokens: Sequence[tuple[str, Path]]
4001
+ ) -> frozenset[str]:
4002
+ """The tokens `check-ignore` says this repository will never track (RK213).
4003
+
4004
+ Both spellings per token — under the ledger's own directory and under the root (RK51) —
4005
+ so a `bin/…` written from `docs/` is asked about as the repository spells it. The answer
4006
+ is mapped back to the token, because that is what the finding names.
4007
+ """
4008
+ if not tokens:
4009
+ return frozenset()
4010
+ asked: dict[str, str] = {}
4011
+ for token, near in tokens:
4012
+ for base in (near, config.root):
4013
+ spelling = _spelled(os.path.normpath(str(config.root)), str(base), token)
4014
+ # None is a path above the root, which is nothing this repository's
4015
+ # `.gitignore` could have declared — and git refuses the **whole**
4016
+ # invocation over one of them (RK220), through the same door as "there is
4017
+ # no git here", where nothing is withheld. The *spelling* is dropped and
4018
+ # not the token, because the other base may still be inside.
4019
+ if spelling is not None:
4020
+ asked.setdefault(spelling, token)
4021
+ if not asked:
4022
+ return frozenset()
4023
+ try:
4024
+ answered = check_ignore(config.root, tuple(asked))
4025
+ except HistoryUnavailable:
4026
+ # The question could not be asked, so nothing is withheld: silence here would read
4027
+ # as "this repository declared it untracked", which is the one thing it did not.
4028
+ return frozenset()
4029
+ return frozenset(asked[name] for name in answered if name in asked)
4030
+
4031
+
4032
+ def _spelled(root: str, base: str, token: str) -> str | None:
4033
+ """How git would spell this token from this base — decided **lexically** (RK225).
4034
+
4035
+ `Config.relative` resolves the path, which is right where a junction has to be followed
4036
+ and ruinous where a check asks it per token: 34326 `realpath` calls at Turing's pin,
4037
+ 7.4 s of an 11.5 s run. Every path compared against git's listing here is built from the
4038
+ config's own root, so the prefix already agrees and normalising the `..` segments
4039
+ textually gives the answer that listing holds — without touching the filesystem, which
4040
+ is the whole point of judging a revision.
4041
+
4042
+ None where the spelling climbs out of the repository: git has nothing to say about a
4043
+ path above the root, and one of them refuses a whole `check-ignore` batch (RK220).
4044
+ """
4045
+ joined = os.path.normpath(os.path.join(base, token))
4046
+ if joined == root:
4047
+ return "."
4048
+ if not joined.startswith(root + os.sep):
4049
+ # Above the root, or on another mount: either way not a path git can be asked
4050
+ # about. A prefix test rather than `os.path.relpath`, which normcases and splits
4051
+ # both ends per call — 342330 `normcase` calls under 34133 of them (RK228) — and
4052
+ # cannot say more here, because both sides are built from the same config root.
4053
+ return None
4054
+ return joined[len(root) + 1 :].replace(os.sep, "/")
4055
+
4056
+
4057
+ @dataclass(frozen=True, slots=True)
4058
+ class Target:
4059
+ """A file carrying a projection of the backlog, as this tree holds it (RK104)."""
4060
+
4061
+ #: The `export` flag that writes it, which is what the repair is named by.
4062
+ flag: str
4063
+ #: The path as the project spells it.
4064
+ where: str
4065
+ #: Which of the two shapes belongs between its markers.
4066
+ shape: str
4067
+ text: str
4068
+
4069
+
4070
+ def _targets(config: Config, tree: Tree) -> tuple[Target, ...]:
4071
+ """Every file `export` writes that has been given somewhere to write (RK104).
4072
+
4073
+ **The markers are the declaration**, so a file carrying none is not a target and is not
4074
+ read again (RK37): a README restating nothing cannot restate it wrongly, and demanding the
4075
+ container would be a gate inventing what only the author may put there — which is why
4076
+ `docs/index.html` here, a pitch with no strip in it, is not one.
4077
+ """
4078
+ out: list[Target] = []
4079
+ for flag, kind in DEFAULTS.items():
4080
+ # Through the resolver the write uses (RK1110), never a path spelled again here: a
4081
+ # target is a literal name or a governed role, and a gate that decided that for itself
4082
+ # would be a gate over a file nothing writes — which passes for the same reason the
4083
+ # drift got in.
4084
+ path = target_of(config, flag)
4085
+ raw = None if path is None else tree.blob(path)
4086
+ if raw is None:
4087
+ continue
4088
+ text = raw.decode("utf-8", errors="replace")
4089
+ if BEGIN in text:
4090
+ out.append(Target(flag, config.relative(path), kind.shape, text))
4091
+ return tuple(out)
4092
+
4093
+
4094
+ def _projections(
4095
+ config: Config, documents: dict[str, Document], targets: tuple[Target, ...]
4096
+ ) -> list[Finding]:
4097
+ """The derived block in a file this tool does not own, checked where it was written (RK104).
4098
+
4099
+ RK39 made the README's status table derived rather than restated, on the argument that a
4100
+ file repeating a backlog it cannot re-read is stale from the first ship. The derivation
4101
+ shipped and the gate over it did not, so a commit that ships a task and forgets `export`
4102
+ leaves a table contradicting the ledger — and what caught that here was a pytest fixture,
4103
+ which an adopting project does not install with the plugin.
4104
+
4105
+ Two decisions, and each is the same one made elsewhere in this module:
4106
+
4107
+ * **The block is compared, never repaired.** Every character of it is derived, so the
4108
+ repair is one command and the finding names it; writing it from here would make the
4109
+ linter a writer (L4), and `--fix` is where a derived field is normalised (RK16).
4110
+ * **The finding lands on the begin marker.** It is a defect about that block and the block
4111
+ has a place, the same reading RK34 makes of a column — so the report is usable, and the
4112
+ `Stop` hook's own narrowing (RK60) leaves a turn that merely moved a marker alone. What
4113
+ a projection goes stale against is a commit, and the commit is where this bites.
4114
+
4115
+ The block is derived from the tree's own documents, so a baseline run compares a revision's
4116
+ README against the counts *that* revision's files render: a stale block is standing debt to
4117
+ be named and forgiven (RK84), not something every commit after it is charged for.
4118
+ """
4119
+ if not targets or "roadmap" not in documents:
4120
+ return []
4121
+ projection = project(config, documents)
4122
+ out: list[Finding] = []
4123
+ for target in targets:
4124
+ try:
4125
+ rendered = projection.body(target.shape, omit=enclosing(target.text))
4126
+ if splice(target.text, rendered, target.where) == target.text:
4127
+ continue
4128
+ except NoMarkers as error:
4129
+ # A begin with no end, or the two in the wrong order: the block has no extent, so
4130
+ # there is nothing to compare and `export` refuses the same file for the same
4131
+ # reason. Reported with the message that names the two lines to paste.
4132
+ out.append(
4133
+ Finding(
4134
+ "export.unmarked",
4135
+ target.where,
4136
+ str(error),
4137
+ _marked(target.text),
4138
+ # The flag, so the door under the message names the same projection the
4139
+ # message does (RK1110) — with a third target a literal `--readme` in the
4140
+ # remedy contradicted it, which is the half a reader trusts.
4141
+ subject=target.flag,
4142
+ )
4143
+ )
4144
+ continue
4145
+ out.append(
4146
+ Finding(
4147
+ "export.stale",
4148
+ target.where,
4149
+ f"the block between the roadkeep markers is not what the governed files "
4150
+ f"render: `{invocation()} export --{target.flag}` rewrites it, and every "
4151
+ f"character of it is derived",
4152
+ _marked(target.text),
4153
+ subject=target.flag,
4154
+ )
4155
+ )
4156
+ return out
4157
+
4158
+
4159
+ def _marked(text: str) -> int | None:
4160
+ """Where the block starts, as an editor counts — the line the report sends a reader to."""
4161
+ for number, line in enumerate(text.split("\n"), start=1):
4162
+ if line.strip() == BEGIN:
4163
+ return number
4164
+ return None
4165
+
4166
+
4167
+ def _cycles(backlog: Backlog, file: str) -> list[Finding]:
4168
+ """A group of tasks that wait on each other, anchored on its lowest id."""
4169
+ out: list[Finding] = []
4170
+ schema = backlog.config.schema
4171
+ for group in Graph.of(backlog).cycles():
4172
+ anchor = min(group, key=lambda i: id_order(i, schema))
4173
+ entry = backlog.entry(anchor)
4174
+ # A group of one is the same defect through a `Block X` dep the task is itself a
4175
+ # member of: the block cannot empty until this line ships, so the line waits on
4176
+ # itself. Worth its own sentence — "wait on each other" reads as a tool bug.
4177
+ message = (
4178
+ f"{' ↔ '.join(group)} wait on each other, so nothing in the group can be "
4179
+ f"started"
4180
+ if len(group) > 1
4181
+ else f"{anchor} is in its own blocker set, so no amount of shipping "
4182
+ f"anything else makes it ready"
4183
+ )
4184
+ out.append(
4185
+ Finding(
4186
+ "deps.cycle",
4187
+ file,
4188
+ message,
4189
+ None if entry is None else entry.lineno,
4190
+ anchor,
4191
+ )
4192
+ )
4193
+ return out
4194
+
4195
+
4196
+ # -- the gate's own two readings (RK1170) -------------------------------------
4197
+ #
4198
+ # Here and no longer in `rendering`, which is where they were cut to when that module was made
4199
+ # out of an 8,489-line `cli.py`: theirs was the cut with no import cycle, which is a fix for a
4200
+ # file's size and not for where a verb's answer lives. `Report` is what both are about, so both
4201
+ # are on it — and the finding-level helpers below are private to them.
4202
+
4203
+
4204
+ def _report_rows(config: Config, report: Report, applied: Fix, root: str, quiet: bool) -> None:
4205
+ from roadkeep.rendering import _print, _tree # noqa: PLC0415 - RK260
4206
+
4207
+ if not quiet:
4208
+ _print(applied.stated())
4209
+ # Notes before the findings and the summary: a note is what the gate says about a
4210
+ # file it is passing, and after an exit-1 report nobody would read it (RK35).
4211
+ for note in report.notes:
4212
+ print(str(note))
4213
+ for line in applied.refusals():
4214
+ print(line, file=sys.stderr)
4215
+ if report.clean:
4216
+ # The files are named on the way out even when there is nothing to say: a gate
4217
+ # that passed by reading nothing looks exactly like a gate that passed.
4218
+ print(
4219
+ f"{', '.join(report.checked) or 'nothing'}: {_measured(report)}, clean"
4220
+ f"{_standing_line(report)}{_tree(root)}"
4221
+ )
4222
+ return
4223
+ mechanical = 0
4224
+ if not quiet:
4225
+ mechanical = _print_findings(config, report)
4226
+ added = "new " if report.baseline is not None else ""
4227
+ print(
4228
+ f"{report.problems} {added}problem(s) in {_measured(report)} across "
4229
+ f"{len(report.checked)} file(s): {_codes_line(report)}{_standing_line(report)}{_tree(root)}"
4230
+ )
4231
+ if mechanical:
4232
+ # Said once and never per line (RK420): the mechanical class is the one remedy that
4233
+ # is identical on every finding it answers, so repeating it under each of them would
4234
+ # spend the report's length on the findings that cost the reader nothing.
4235
+ print(f"{mechanical} of them need no decision: {invocation()} lint --fix")
4236
+
4237
+
4238
+ def _print_findings(config: Config, report: Report) -> int:
4239
+ """Every finding, with a group that is one fact said once (RK469).
4240
+
4241
+ A finding is per line and stays per line — the addresses are the evidence. What is said
4242
+ once is the *sentence and the remedy* where a whole run of them shares both: measured on
4243
+ Turing, 27 `section.ambiguous` findings and their 26 remedies were 80% of a 15,894-char
4244
+ report, two distinct messages once the anchor was taken off, and one `[refs]` line in
4245
+ `roadkeep.toml` closes every one.
4246
+
4247
+ The same argument RK420 already makes one line down, where the mechanical remedy is
4248
+ counted rather than repeated under each finding, and the same one RK451 made about a file
4249
+ a crash left NUL: one finding because the loss is one. A report whose bulk is one sentence
4250
+ repeated is one a reader learns to skip (RK146), and it buries the four findings here that
4251
+ are each about a different line.
4252
+
4253
+ Grouped by what the **emitter** declared they share, and only for runs of two or more: a
4254
+ single member is its own sentence, and a group of one printed as a group would be a
4255
+ heading over nothing.
4256
+ """
4257
+ mechanical = 0
4258
+ # By the key and not by adjacency: a report interleaves files, so the members of one
4259
+ # group are rarely consecutive — and a grouping that only folded runs would fold Turing's
4260
+ # and leave a fixture's alone, which is the shape that passes a test and misses the case.
4261
+ # Printed at the first member's place, so the report's order is otherwise the one it had.
4262
+ groups: dict[tuple[str, str, str], list[Finding]] = {}
4263
+ for finding in report.findings:
4264
+ if finding.shared:
4265
+ groups.setdefault((finding.code, finding.file, finding.shared), []).append(finding)
4266
+ printed: set[tuple[str, str, str]] = set()
4267
+ for finding in report.findings:
4268
+ key = (finding.code, finding.file, finding.shared)
4269
+ run = groups.get(key, []) if finding.shared else []
4270
+ if len(run) < 2:
4271
+ print(str(finding))
4272
+ mechanical += _print_remedy(finding, config)
4273
+ continue
4274
+ if key in printed:
4275
+ continue
4276
+ printed.add(key)
4277
+ first = finding
4278
+ # The pair once, the addresses under it: `file:line` each, which is what an editor
4279
+ # opens and what an author choosing which file takes the namespace counts.
4280
+ print(f"{first.file} {first.code} {len(run)} addresses {first.shared}")
4281
+ print(f" {' '.join(f'{one.token}:{one.lineno}' for one in run)}")
4282
+ mechanical += _print_remedy(first, config)
4283
+ return mechanical
4284
+
4285
+
4286
+ def _print_remedy(finding: Finding, config: Config) -> int:
4287
+ """Print what closes this finding, and return 1 where that was `--fix`'s (RK420).
4288
+
4289
+ Printed by default rather than behind a flag. The defect being answered is a caller
4290
+ spending a *turn* to learn the command, so a report that carries it only on request has
4291
+ the cost exactly where it was: the second call is the thing being removed.
4292
+
4293
+ The mechanical class is counted instead of printed, and every other kind gets its line —
4294
+ including `decide`, whose whole content is the two doors and what separates them, since
4295
+ a decision printed as one word is a decision made by running one and reading its refusal.
4296
+ """
4297
+ from roadkeep.remedying import remedy # noqa: PLC0415 - RK260
4298
+
4299
+ found = remedy(finding, config)
4300
+ if found is None or found.kind == "fix":
4301
+ return 1 if found is not None else 0
4302
+ for line in str(found).splitlines():
4303
+ print(f" {line}" if not line.startswith(" ") else line)
4304
+ return 0
4305
+
4306
+
4307
+ def _lint_json(config: Config, report: Report, applied: Fix, root: str) -> dict[str, object]:
4308
+ baseline = report.baseline
4309
+ return {
4310
+ # First, because every path below is relative to it and a payload a second tool files
4311
+ # against the wrong project is worse than one it cannot file at all (RK299). The same
4312
+ # key `install --json` already uses, spelled the same way.
4313
+ "root": root,
4314
+ "clean": report.clean and not applied.refused,
4315
+ # Absent without `--baseline`, so a caller reading `problems` cannot mistake a
4316
+ # difference for a total: with it, `findings` holds only what this tree added.
4317
+ **(
4318
+ {}
4319
+ if baseline is None
4320
+ else {
4321
+ "baseline": {
4322
+ "rev": baseline.rev,
4323
+ "standing": baseline.standing,
4324
+ "forgiven": [_finding_json(f, config) for f in baseline.forgiven],
4325
+ "resolved": [_finding_json(f, config) for f in baseline.resolved],
4326
+ }
4327
+ }
4328
+ ),
4329
+ "fixed": [
4330
+ {
4331
+ "file": repair.file,
4332
+ "line": repair.lineno,
4333
+ "id": repair.id,
4334
+ "reasons": list(repair.reasons),
4335
+ "before": repair.before,
4336
+ "after": repair.after,
4337
+ # A key on the same list rather than a `removed` list beside `fixed` (RK357):
4338
+ # `line` means the pre-pass position here, and a consumer resolving addresses
4339
+ # has to know that from the payload rather than from an empty `after`.
4340
+ "removed": repair.removed,
4341
+ }
4342
+ for repair in applied.repairs
4343
+ ],
4344
+ "kept": [
4345
+ {"file": s.file, "line": s.lineno, "id": s.id, "reason": s.reason}
4346
+ for s in applied.skipped
4347
+ ],
4348
+ "refused": list(applied.refused),
4349
+ "checked": list(report.checked),
4350
+ "lines": report.lines,
4351
+ "sections": report.sections,
4352
+ "budgets": report.budgets,
4353
+ "problems": report.problems,
4354
+ "codes": report.codes(),
4355
+ "findings": [_finding_json(f, config) for f in report.findings],
4356
+ "notes": [
4357
+ {
4358
+ "code": note.code,
4359
+ "file": note.file,
4360
+ "line": note.lineno,
4361
+ "id": note.id or None,
4362
+ "message": note.message,
4363
+ **_remedy_json(note, config),
4364
+ }
4365
+ for note in report.notes
4366
+ ],
4367
+ }
4368
+
4369
+
4370
+ def _standing_line(report: Report) -> str:
4371
+ """What the baseline forgave, and what left — said out loud, both of them (RK84).
4372
+
4373
+ Both, because either number alone is the misreading §RK84 was written about: the run
4374
+ that deleted 160 lines of rationale took the count *down* by eight, and the drop read as
4375
+ an improvement right up until the two findings it added were looked at individually.
4376
+ """
4377
+ baseline = report.baseline
4378
+ if baseline is None:
4379
+ return ""
4380
+ counts = f"{baseline.standing} standing"
4381
+ if baseline.resolved:
4382
+ counts += f", {len(baseline.resolved)} resolved"
4383
+ return f" against {baseline.rev} ({counts})"
4384
+
4385
+
4386
+ def _measured(report: Report) -> str:
4387
+ """What was read, in its own units: task lines, sections, and budgeted files."""
4388
+ scope = f"{report.lines} line(s), {report.sections} section(s)"
4389
+ return scope if not report.budgets else f"{scope}, {report.budgets} budget(s)"
4390
+
4391
+
4392
+ def _codes_line(report: Report) -> str:
4393
+ return " ".join(f"{code} {count}" for code, count in report.codes().items())
4394
+
4395
+
4396
+ def _finding_json(finding: Finding, config: Config) -> dict[str, object]:
4397
+ return {
4398
+ "code": finding.code,
4399
+ "file": finding.file,
4400
+ "line": finding.lineno,
4401
+ # Only a character finding has one (RK34), and it is what makes an invisible
4402
+ # codepoint findable: `file:line:column` is what an editor jumps to.
4403
+ "column": finding.column,
4404
+ "id": finding.id or None,
4405
+ "message": finding.message,
4406
+ **_remedy_json(finding, config),
4407
+ }
4408
+
4409
+
4410
+ def _remedy_json(finding: object, config: Config) -> dict[str, object]:
4411
+ """The remedy, as a key that is absent rather than null when the table has none (RK420).
4412
+
4413
+ Absent and not `"remedy": null`, because a consumer that reads the key at all is one
4414
+ about to run what is in it, and a null is a shape it has to branch on before it can
4415
+ tell "no command exists" from "this build predates the field".
4416
+ """
4417
+ from roadkeep.remedying import remedy # noqa: PLC0415 - RK260
4418
+
4419
+ found = remedy(finding, config)
4420
+ return {} if found is None else {"remedy": found.payload(_served(config))}