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/config.py ADDED
@@ -0,0 +1,1832 @@
1
+ """`roadkeep.toml` — the format's variability, declared per project (RK3, L6).
2
+
3
+ Three real projects, one format: Shio numbers `SH` and has no strategy file, Turing
4
+ numbers `T` and has one, Cursarei keeps its roadmap under `docs/roadmap/`. The moment
5
+ any of that is hardcoded the tool serves exactly one repository, so everything that
6
+ differs is a key here and everything that does not is in :mod:`roadkeep.kernel.schema`.
7
+
8
+ Two decisions that matter more than the file format:
9
+
10
+ * **An unknown key is refused, never ignored.** A mistyped `symptom_max` that silently
11
+ falls back to the default is a limit the author believes is in force and is not —
12
+ the same failure the whole tool exists to remove, one layer down. Refusals are
13
+ batched and name the allowed keys.
14
+ * **Config is found by walking up**, like git. A command run from a subdirectory has to
15
+ reach the same backlog as one run from the root, or the answer depends on the shell's
16
+ working directory.
17
+
18
+ Reading order: `roadkeep.toml` first, then `[tool.roadkeep]` in `pyproject.toml`. A
19
+ project that already has one config file does not need a second.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import re
25
+ import tomllib
26
+ from collections.abc import Mapping, Sequence
27
+ from dataclasses import dataclass, field, replace
28
+ from pathlib import Path
29
+ from typing import TYPE_CHECKING
30
+
31
+ if TYPE_CHECKING: # a string annotation under `from __future__ import annotations` (RK261)
32
+ from roadkeep.kernel.document import Document
33
+ from roadkeep.kernel.schema import (
34
+ DEFAULT_GRAMMARS,
35
+ DEFAULT_HEADING_WORD,
36
+ DEFERRED,
37
+ DROPPABLE,
38
+ MARKER_NAMES,
39
+ OPEN_MARKERS,
40
+ REF_PREFIX_RE,
41
+ REF_SEPARATOR,
42
+ RETIRED,
43
+ SHIPPED,
44
+ UNDESIGNED,
45
+ Dep,
46
+ DepKind,
47
+ Grammar,
48
+ Schema,
49
+ )
50
+
51
+ CONFIG_NAME = "roadkeep.toml"
52
+ PYPROJECT = "pyproject.toml"
53
+
54
+ #: The governed files. A project declares the ones it has; the rest are absent,
55
+ #: not empty — `strategy` missing means Shio, not a Shio with an empty strategy. The
56
+ #: same is true of `deferred` (RK96), which is why it is not in :data:`DEFAULT_PATHS`:
57
+ #: a project that never pauses anything has no store, rather than an empty one.
58
+ #:
59
+ #: `decisions` is the sixth and the one adopters ask for by name (RK1269): read as this format
60
+ #: an ADR is the pair already written here — an id, a marker, one falsifiable claim and a
61
+ #: reason — and the only difference is the departure. A roadmap line leaves by three doors and
62
+ #: a decision leaves by one, being superseded, so nothing in that file is ever deleted and it
63
+ #: grows only by decisions somebody actually made. **A named role and not an open tuple**: a
64
+ #: role no machinery knows is a file with no schema, which is the convention this tool replaces.
65
+ ROLES = ("roadmap", "changelog", "improvements", "strategy", "deferred", "decisions")
66
+
67
+ #: The governed files a `→ §<anchor>` pointer may address (RK172). Both, because `[files]`
68
+ #: declares strategy as a governed role and a line pointing at it is already in the model.
69
+ #: Here rather than beside either reader, because the gate and `show` resolving against
70
+ #: different sets is exactly what RK186 was: one of them called a section the other found.
71
+ #: Order is where a design goes when there is none yet — improvements first.
72
+ #:
73
+ #: `decisions` is the third (RK1361), and it is the one file here that carries **both** —
74
+ #: the records and the prose about them. That is the difference between the two kinds of
75
+ #: body and not an exception to the shape: a design section says how the work was built and
76
+ #: is correctly deleted by the ship that finishes it, while a decision's body says what was
77
+ #: weighed and what it costs, which is the half no store keeps and the half no `ship`
78
+ #: deletes. Last in the order, because a design with nowhere to go still goes to
79
+ #: `improvements`: nothing derives this role, and every body in it is one a caller named.
80
+ PROSE_ROLES = ("improvements", "strategy", "decisions")
81
+
82
+ #: Where a **task's** design section may go — the subset of :data:`PROSE_ROLES` that answers
83
+ #: "this line has a rationale and it lives somewhere" (RK1361). Not the same question: a
84
+ #: pointer may address any prose file, and a design has two candidates. `decisions` is
85
+ #: deliberately absent, and that absence is the whole distinction the third prose role
86
+ #: introduced — a decision's body is written *about a decision*, so a `defer` that cannot
87
+ #: find a design file must not report a decisions file as somewhere the design could live.
88
+ DESIGN_ROLES = ("improvements", "strategy")
89
+
90
+ #: The roles whose records are **lines**, which the gate reads and `govern` measures a field
91
+ #: over (RK1279, RK1361). Stated, not derived: it was "a declared role that is not a prose
92
+ #: one" until `decisions` became both, and that derivation then failed the way it was written
93
+ #: to fail loudly and did not — reporting a widest over three files where four hold lines,
94
+ #: and accepting a limit the fourth already breaks. Two overlapping sets are what the format
95
+ #: has, so each is named.
96
+ LINE_ROLES = ("roadmap", "changelog", "deferred", "decisions")
97
+
98
+ DEFAULT_PATHS: Mapping[str, str] = {
99
+ "roadmap": "docs/ROADMAP.md",
100
+ "changelog": "docs/CHANGELOG.md",
101
+ "improvements": "docs/IMPROVEMENTS.md",
102
+ }
103
+
104
+ #: Where the strategy file goes when a scaffold is asked for one (RK1186). **Beside the table
105
+ #: and not in it**, and the difference is what that table is: it declares the layout a project
106
+ #: *has* when it declares none, so a `strategy` row made `Config.missing()` report an absent
107
+ #: strategy file on every unconfigured project — measured immediately, by the test that asserts
108
+ #: that layout. This says where `init --strategy` would put one, which is a scaffold's decision.
109
+ #:
110
+ #: Here rather than in `adopting`, because L6's own invariant says so: two modules may spell a
111
+ #: governed file's default name, and the one that scaffolds is not one of them.
112
+ STRATEGY_PATH = "docs/STRATEGY.md"
113
+
114
+ #: Where the deferred store goes when a scaffold is asked for one (RK1259). Beside the table
115
+ #: for :data:`STRATEGY_PATH`'s reason and for the one this file already gives above it: a
116
+ #: project that never pauses anything has no store rather than an empty one, so the layout it
117
+ #: *has* does not include this and the layout `init --deferred` writes does.
118
+ #:
119
+ #: The verb exists because the alternative is where the refusal lands. `defer` will not
120
+ #: scaffold on the way past — a store invented at the moment one is needed is a format decided
121
+ #: by a verb — so until this the remedy was a toml key and a skeleton no command offered to
122
+ #: write, read out at the moment a pause reason had just been composed.
123
+ DEFERRED_PATH = "docs/DEFERRED.md"
124
+
125
+ #: Where the decision record goes when one is asked for (RK1269). Beside the two above and for
126
+ #: their reason: a project that has recorded no decision has no file, and `declare decisions`
127
+ #: is what writes one — never a `ship --decides` on the way past, a store invented at the moment
128
+ #: one is needed being a format decided by a verb.
129
+ DECISIONS_PATH = "docs/DECISIONS.md"
130
+
131
+ _TOP_KEYS = frozenset(
132
+ {
133
+ "prefix",
134
+ "ids",
135
+ "ref_scheme",
136
+ "files",
137
+ "limits",
138
+ "markers",
139
+ "id_sources",
140
+ "reserved_ids",
141
+ "priority",
142
+ "budgets",
143
+ "ledger",
144
+ "rules",
145
+ "non_goals",
146
+ # RK1265. The positive twin of the list above, governed on its own declaration.
147
+ "criteria",
148
+ "headings",
149
+ "report",
150
+ "claims",
151
+ "refs",
152
+ "tools",
153
+ # RK1286. What the read that replaces reading the file may cost.
154
+ "reads",
155
+ "grammar",
156
+ # RK1180. Which labels are standing categories rather than projects.
157
+ "blocks",
158
+ # RK1192. Whether the wired surfaces are held where they are, deliberately.
159
+ "install",
160
+ # RK1297. What a line may say has to be *present* before it can be finished.
161
+ "requirements",
162
+ }
163
+ )
164
+ #: `[grammar.<role>]` — the shape of a role's records, which L6 declared everything about
165
+ #: except (RK1064). Three keys and no fourth: what a record starts from, which markers it
166
+ #: may carry, and which slots it does without. `states` is not among them — whether a file
167
+ #: *is* a status is a fact about the tool's own roles, so a project may reshape a line and
168
+ #: never invent a state for which no verb exists.
169
+ _GRAMMAR_KEYS = frozenset({"extends", "markers", "drop"})
170
+ #: `[tools]` — what one served tool may cost a session (RK1059). Its own table and not a
171
+ #: `[budgets]` entry, because every key there is a **path** and this cost is not a file: it
172
+ #: is composed per session from the parser, the config and the `TOOLS` table, so an entry
173
+ #: under a name no file has would break the one thing that table's refusals can say.
174
+ #:
175
+ #: Per tool and not per list, which is the decision RK464 deliberately left open. A ceiling
176
+ #: on the total fails on whichever tool is added last and names nothing; a per-tool one is
177
+ #: refused by the tool that grew, which is the tool whose description somebody just edited —
178
+ #: and `cost --tools` already ranks them, so the read that composes the fix exists.
179
+ _TOOLS_KEYS = frozenset({"characters", "session"})
180
+ #: `[reads] brief` — what the one read that replaces reading the file may cost (RK1286). Its
181
+ #: own table and not a `[budgets]` entry, for `[tools]`' reason exactly: every key there is a
182
+ #: **path**, and a brief is composed per call from the line, its design, the deps, the
183
+ #: non-goals and four allowances. Not `[limits]` either — that table is the widths of the
184
+ #: fields a line carries, and this is the size of an answer about one.
185
+ _READS_KEYS = frozenset({"brief"})
186
+ #: `[install]` — whether this project holds its wired launcher, hook and skill at the version
187
+ #: they are (RK1192). Its own table and not a `[rules]` entry, because every key there is a
188
+ #: prose rule one governed *file* is not held to, and this is about the harness around them.
189
+ _INSTALL_KEYS = frozenset({"pinned", "enforced"})
190
+ #: `[claims]` — how long a claim on a line reads as held (RK151). Its own table for the reason
191
+ #: `[headings]` has one: a bare `held` beside `prefix` would read as one of the limits, and it
192
+ #: is not a limit on any field — it is the one number in the claim mechanism that is a
193
+ #: judgement about how long work takes.
194
+ _CLAIMS_KEYS = frozenset({"held"})
195
+ #: `[requirements]` — the words a `(needs: …)` group may draw on (RK1297). Its own table for
196
+ #: `[markers]`' reason: the vocabulary is one part of a shape whose other parts are a caller's
197
+ #: (`pick --have`) and a line's, and a bare `requirements` beside `priority` would read as a
198
+ #: list this backlog is subject to rather than one its lines quote from.
199
+ _REQUIREMENTS_KEYS = frozenset({"declared"})
200
+ #: `[headings]` — the word a project files work under (RK75). Its own table and not a top
201
+ #: key, because the heading is a shape with more than one part and the next question about
202
+ #: it (a sub-block that carries no word at all) belongs under the same heading.
203
+ _HEADING_KEYS = frozenset({"word", "permanent"})
204
+ #: `[ids]` — the shape of an id, where a project already spells one the format refused
205
+ #: (RK106). Its own table for the reason `[headings]` is: the spelling has more than one
206
+ #: part, and a bare `pad` beside `prefix` would read as one of the limits.
207
+ _IDS_KEYS = frozenset({"pad", "suffix"})
208
+ #: `[non_goals]` — the two fields the roadmap's other bullet has (RK70). Opt-in for RK66's
209
+ #: reason: two live corpora wrote theirs as free prose, and a default that reported findings
210
+ #: on the first run is a gate that gets bypassed instead of adopted.
211
+ _SCOPE_KEYS = frozenset({"lead", "why"})
212
+ _BUDGET_KEYS = frozenset({"lines", "bytes"})
213
+ #: Which slots the ledger's lines carry (RK43, RK48). Its own table because the shape of a
214
+ #: file is one decision with two parts, and `markers.ledger` put half of it under a heading
215
+ #: that cannot name the other half: a symptom is not a marker.
216
+ _LEDGER_KEYS = frozenset({"marker", "symptom"})
217
+ #: The rules a role may switch off (`[rules.<role>]`, RK52). Not limits, because they
218
+ #: are not numbers, and not `[ledger]`, because that table says which *slots* a line has.
219
+ #: `ref` joins them for RK66's reason: whether a line must point at a rationale section is
220
+ #: a convention, not a fact about the format, and a project that documents the opposite one
221
+ #: gets a finding for obeying itself.
222
+ _RULE_KEYS = {
223
+ "one_sentence": "one_sentence",
224
+ "terminator": "terminator",
225
+ "ref": "ref_required",
226
+ }
227
+ _LIMIT_KEYS = {
228
+ "symptom": "symptom_max",
229
+ "why": "why_max",
230
+ # What a partial entry's qualifier may cost (RK121). Per project like every other
231
+ # limit (L6): `local half` and `the SH22 half` are one corpus's answer to "which part",
232
+ # and a project whose halves have longer names has not made the qualifier a summary.
233
+ "part": "part_max",
234
+ "line": "line_max",
235
+ # A section is prose, so its budget is words and its shape is a width (RK9).
236
+ "section": "section_max",
237
+ "prose": "prose_width",
238
+ }
239
+ _MARKER_KEYS = frozenset({"open", "shipped", "retired", "deferred", "undesigned"})
240
+ # The invisible ones. A marker carrying U+FE0F renders identically and compares
241
+ # unequal, so a config that declares one puts every line in the file permanently
242
+ # out of round-trip. Refuse it where it is typed.
243
+ _INVISIBLE = {"️": "U+FE0F", "‍": "U+200D", "​": "U+200B"}
244
+
245
+
246
+ @dataclass(frozen=True, slots=True)
247
+ class Budget:
248
+ """A file that is loaded every turn, and what it is allowed to cost (RK30).
249
+
250
+ Declared here rather than in the file's own prose, which is the arrangement that let
251
+ Shio's `agents.md` reach 186 KB while stating a 150-line rule at the bottom of itself:
252
+ a budget nothing reads is a budget nothing enforces. Both numbers are optional and at
253
+ least one is required — an entry that declares neither is refused, because it would
254
+ read as a budget and hold nobody to anything.
255
+ """
256
+
257
+ path: Path
258
+ lines: int | None = None
259
+ #: Size on disk. Bytes and not tokens: the tool guesses at nothing, and 186 KB was the
260
+ #: measurement that started this — roughly 46k tokens, spent on every single turn.
261
+ bytes: int | None = None
262
+
263
+
264
+ def spent(raw: bytes) -> dict[str, int]:
265
+ """What an always-loaded file costs, in the two units `[budgets]` declares (RK30).
266
+
267
+ Bytes and not text, for the reason the gate reads them that way: a budget is about what
268
+ a loader pays, and an instruction file is not a format this tool has any business
269
+ decoding (L4). Here rather than in either reader, because the gate that refuses the
270
+ overrun (RK30) and the read that reports the room before an edit (RK345) are two callers
271
+ of one measurement — and two spellings of it would be the disagreement RK50 removed.
272
+
273
+ **The terminator is normalised out and nothing else is** (RK1105). Counted raw, the byte
274
+ number is a fact about the *checkout*: one commit of claude-tray's `AGENTS.md` is 24310
275
+ bytes with CRLF and 23999 with LF under `core.autocrlf=input`, so a ceiling moves 311
276
+ bytes per machine while `git diff` shows nothing, and a commit one byte inside its budget
277
+ passes on the runner and is refused on the desk. A budget is a fact about the commit —
278
+ that is what a reviewer reads and what CI gates — so `\\r\\n` is counted as the `\\n` the
279
+ repository stores. What this checkout pays over that is real and is not dropped in
280
+ silence: :func:`translated` is the difference, which `lint` states as a note and
281
+ `budget` prints beside the number.
282
+ """
283
+ counted = raw.replace(b"\r\n", b"\n")
284
+ return {"lines": counted.count(b"\n") + (0 if counted.endswith(b"\n") or not counted else 1),
285
+ "bytes": len(counted)}
286
+
287
+
288
+ def translated(raw: bytes) -> int:
289
+ """How many bytes this checkout carries that :func:`spent` did not count (RK1105).
290
+
291
+ One per `\\r\\n`, which is the whole difference between the two measurements — a lone `\\r`
292
+ is a byte in its own right in both, and `char.mixed-endings` is what has something to say
293
+ about a file carrying two conventions.
294
+ """
295
+ return raw.count(b"\r\n")
296
+
297
+
298
+ @dataclass(frozen=True, slots=True)
299
+ class Scope:
300
+ """What a governed non-goal may say, when a project declares its list governed (RK70).
301
+
302
+ Two numbers and no marker, no id and no pointer: a non-goal has no lifecycle to state.
303
+ The list is eight lines that change once a year, and an id would buy them a retirement,
304
+ a rename and a second file to disagree with — so the lead *is* the address.
305
+ """
306
+
307
+ #: The bolded head, which is what a `brief` prints and what a duplicate is judged on.
308
+ lead: int = 80
309
+ #: The rest of the bullet. Longer than a task's `why` and not one sentence: the corpus
310
+ #: argues these in two, and the file has no rationale section to send the second to.
311
+ why: int = 320
312
+
313
+
314
+ #: `[claims] held`, in **minutes** — how long a claim reads as held before a later caller
315
+ #: steps over it (RK119, RK151). An hour by default: long enough that a worker mid-task still
316
+ #: holds the line, short enough that a claim nobody released clears inside one session.
317
+ CLAIM_HELD = 60
318
+ #: The longest window this will accept. The reason there is an expiry rather than a lock is
319
+ #: that a killed worker must not take a line out of the backlog for ever, so a window nobody
320
+ #: would wait out is the defect coming back under a config key (RK151) — one working day is
321
+ #: where that starts, an abandoned claim past it surviving a night. It is also what turns the
322
+ #: unit into a refusal: `held = 3600`, meant as seconds, is refused rather than obeyed.
323
+ CLAIM_HELD_MAX = 480
324
+
325
+
326
+ class ConfigError(ValueError):
327
+ """Every problem with the file, not the first one found.
328
+
329
+ An **unknown key adds a clause** (RK1150), and it is about this process rather than about the
330
+ file: `unknown key 'headings.permanent' (allowed: headings.word)` is every word true, and the
331
+ conclusion it invites — delete it, or fix a config that is already right — is wrong whenever
332
+ the key belongs to a *later* roadkeep than the one reading. Reached from Shio, where the
333
+ server resolves this package from the plugin cache and the project from a checkout.
334
+
335
+ A key nothing ever declared is a typo and a key this build predates is an upgrade; the file
336
+ cannot tell them apart, so both are named and the command that decides it is carried the way
337
+ every `lint` finding carries one (RK14/15). Once per refusal and not once per key: three
338
+ unknown keys are one skew, and the same sentence three times reads as three problems.
339
+ """
340
+
341
+ def __init__(self, problems: tuple[str, ...], path: Path | None = None) -> None:
342
+ self.problems = tuple(problems)
343
+ self.path = path
344
+ where = f"{path}: " if path else ""
345
+ super().__init__(where + "; ".join(self.problems) + _skew(self.problems))
346
+
347
+
348
+ #: The three bytes a Windows editor writes ahead of a UTF-8 file, which `tomllib` refuses by
349
+ #: specification — and refuses at line 1, column 1, where the statement is correct.
350
+ _BOM = b"\xef\xbb\xbf"
351
+
352
+
353
+ def _marked(path: Path, broken: tomllib.TOMLDecodeError) -> Exception:
354
+ """A TOML refusal, re-read as the byte that caused it where that is what it is (RK1030).
355
+
356
+ `Invalid statement (at line 1, column 1)` is `tomllib` answering about the first thing it
357
+ could parse, which is `prefix = "RK"` — correct, and pointing at a line with nothing wrong
358
+ with it. What is wrong is three bytes no editor shows, in the file a project writes before
359
+ it has run anything, and on Windows the default route writes them: PowerShell 5.1's
360
+ `Set-Content -Encoding utf8` and `Out-File` both add the mark.
361
+
362
+ **Named and not stripped**, which is the difference from :func:`roadkeep.verbs.reading`'s
363
+ answer to the same byte one file over. A prose field is a sentence somebody typed and the
364
+ mark is the encoder's; this file is the project's own declaration, and a tool that quietly
365
+ accepted one encoding variant of it would teach nothing — the author would meet the mark
366
+ again in `git diff`, in their editor's next save, and in whatever reads the file next.
367
+
368
+ Every other TOML error is handed back exactly as `tomllib` wrote it: this reads the bytes
369
+ only after a refusal, and only to answer the one question the refusal could not.
370
+ """
371
+ try:
372
+ if not path.read_bytes().startswith(_BOM):
373
+ return broken
374
+ except OSError:
375
+ return broken
376
+ return ConfigError(
377
+ (
378
+ f"the file opens with a byte-order mark (U+FEFF), which TOML has no reading "
379
+ f"for — so the refusal below is about the first line it could parse and not "
380
+ f"about anything wrong with it ({broken}). Re-save it as UTF-8 without a BOM; "
381
+ f"in PowerShell, `Set-Content -Encoding utf8` and `Out-File` both write one",
382
+ ),
383
+ path,
384
+ )
385
+
386
+
387
+ #: Every argument this CLI takes that carries a path, and which directory it is read from
388
+ #: (RK1103). RK1101 stated the rule for one verb and this is the reading that says where else
389
+ #: it applies — and the answer it produced is that there are **three** classes and not two.
390
+ #:
391
+ #: * ``project`` — names a file of the project, so a relative one is resolved against the root
392
+ #: by :meth:`Config.locate`. `-C` selects the project and never the working directory, and
393
+ #: over MCP the two are never the same tree.
394
+ #: * ``caller`` — names a file to *read from*, the way `cat` does. The caller's own, relative
395
+ #: to the caller. Resolving one against the root would be a rule about somebody else's shell.
396
+ #: * ``repo`` — repo-relative **text**, and never resolved at all. A claim's scope becomes a
397
+ #: `git add --` argument matched against what git reports, which is repo-relative already;
398
+ #: resolving it would make `src/` absolute and stop it covering `src/a.py` (RK495). git's
399
+ #: merge driver passes `%O`, `%A`, `%B` and `%P` under its own contract, which is this class
400
+ #: arrived at from the other side.
401
+ #:
402
+ #: Held by `tests/test_config.py` against the parser, so a key naming no argument is a failure
403
+ #: rather than a classification that quietly stopped applying — the rule `_DIVERGENT` has.
404
+ #: What that test **cannot** say is that the table is complete: no property of an argparse
405
+ #: argument marks it as carrying a path (`--with` is `alongside`, `install --source` reads as
406
+ #: neither), so the guard is a scan for the obvious spellings and the rest is this list. That
407
+ #: limit is stated rather than papered over: a new path argument spelled `--out-dir` is caught,
408
+ #: one spelled `--target` is not.
409
+ PATH_ARGUMENTS: Mapping[str, Mapping[str, str]] = {
410
+ # `-C` is the caller's, and it is the one row worth saying out loud: the flag that selects
411
+ # the project is itself read from the process's directory, because there is no project to
412
+ # be relative to until it has been answered. Every `project` row below is relative to what
413
+ # this one found.
414
+ "": {"directory": "caller"},
415
+ # Both capture paths are the caller's, exactly as `replay`'s is (RK1141, RK1142): the file
416
+ # lives under the project, and what is handed to the process is a path the process resolves
417
+ # — a `-C` elsewhere does not make somebody's argument project-relative.
418
+ "add": {"section_body_file": "caller", "capture": "caller"},
419
+ "capture filed": {"path": "caller"},
420
+ # A file *of the project* and resolved against its root (RK1264): this names where a
421
+ # governed file is to be created, which is the same class every `[files]` value is — and
422
+ # over MCP the caller's directory is not the tree `-C` selected, so the caller class would
423
+ # put a role's file wherever the harness happened to launch this process.
424
+ "declare": {"path": "project"},
425
+ "section add": {"body_file": "caller"},
426
+ "section amend": {"body_file": "caller"},
427
+ "merge": {
428
+ "base": "repo",
429
+ "ours": "repo",
430
+ "theirs": "repo",
431
+ "path": "repo",
432
+ },
433
+ "claim": {"path": "repo", "add_path": "repo"},
434
+ # Two classes on one verb, and the pair is what makes the distinction concrete (RK1190):
435
+ # `--file` names an every-turn file *of the project* and is resolved against the root,
436
+ # while `--body-file` is a draft the caller is holding and is read the way `cat` reads one.
437
+ "budget": {"file": "project", "body_file": "caller"},
438
+ # The same `--file` one verb over (RK1272), and the same class: a `[budgets]` entry is
439
+ # addressed by the path the config declares, which is project-relative by construction.
440
+ "govern": {"file": "project"},
441
+ "replay": {"path": "caller"},
442
+ "adopt": {"path": "project", "alongside": "project"},
443
+ "install": {"source": "caller"},
444
+ }
445
+
446
+ #: The dest spellings a scan can recognise as a path, which is the partial guard above.
447
+ PATH_SPELLINGS = ("path", "paths", "file", "files", "directory")
448
+
449
+
450
+ @dataclass(frozen=True, slots=True)
451
+ class Config:
452
+ """Where the governed files are, and which format they are written in."""
453
+
454
+ root: Path
455
+ schema: Schema = field(default_factory=Schema)
456
+ paths: Mapping[str, Path] = field(default_factory=dict)
457
+ #: Files to scan for ids beyond the governed four (RK4). This repository keeps
458
+ #: task ids in `agents.md`, and an id the scan misses is an id that gets reused.
459
+ extra_id_sources: tuple[Path, ...] = ()
460
+ #: Ids this project has spoken for without writing them as a line (RK1031). Shio reserves
461
+ #: one per **epic** — `SH25`, `SH62` — each owning a sub-range whose sub-tasks ship under
462
+ #: their own numbers, so the epic id is never a task and never an entry; it exists so a
463
+ #: reader can name a body of work in one token.
464
+ #:
465
+ #: Declared and not inferred, because a reservation and a typo are the same string: the
466
+ #: deriver skips these because they **are** taken, the gate stops reporting them as spent,
467
+ #: and an id that is not on the list still fails exactly as it did.
468
+ reserved: tuple[str, ...] = ()
469
+ #: What jumps the queue, in order: an id or a `Block X`, and nothing else (RK11).
470
+ #: *Declared*, because the alternative is a "## Priority queue" section written in
471
+ #: prose — which Shio has, and which a tool that reads it would be interpreting
472
+ #: rather than validating (L4).
473
+ priority: tuple[str, ...] = ()
474
+ #: Always-loaded files and what each may cost (RK30). Not a governed role: the tool
475
+ #: writes none of these, it only refuses to let one grow unwatched.
476
+ budgets: tuple[Budget, ...] = ()
477
+ #: `[grammar.<role>]` — the shape of one role's records, where a project declares one
478
+ #: (RK1064), keyed by role and applied by :meth:`schema_for`. Empty is every project
479
+ #: that has not spoken about a shape, and then the grammars the tool ships are what
480
+ #: apply: a role nobody declared is not a role without one.
481
+ grammars: Mapping[str, Grammar] = field(default_factory=dict)
482
+ #: `[tools] characters` — what one served tool may cost the session that connects the
483
+ #: server (RK1059), or **None** where the project declares none, which is every project
484
+ #: that does not serve the surface and every one that has not looked at the number yet.
485
+ #: The same argument `budgets` makes about a resident file, about the schema: a cost
486
+ #: nobody counts is a cost that moves, and every flag added to a served verb spends it
487
+ #: in an edit whose diff shows one argument.
488
+ #: What one brief may cost a tool result, in UTF-16 code units (RK1286). `None` where the
489
+ #: project declared none, which is every project until it looks: the read exists to fit in
490
+ #: one tool result, and until this nothing said what that was — the same absence RK30 named
491
+ #: about a resident file and RK1059 about the served schema.
492
+ brief_read: int | None = None
493
+ tool_characters: int | None = None
494
+ #: `[tools] session` — what the whole served surface may cost at the handshake: every
495
+ #: tool plus the instructions, which is the figure `cost --session` prints (RK1097).
496
+ #: **None** where the project declares none, and separate from `characters` because they
497
+ #: refuse different edits — one description growing, against the list growing by one more
498
+ #: verb that is individually unremarkable. Measured across three projects before it was
499
+ #: offered: the count is 52 in all of them and the totals differ by 1.4%, so this is a
500
+ #: number about the package a project installs and not about the project.
501
+ tool_session: int | None = None
502
+ #: `[limits.<role>]` — the numbers one file is held to instead of the shared ones
503
+ #: (RK50), keyed by role and applied by :meth:`schema_for`. Empty is the common case:
504
+ #: a project declares one only where a file's economics differ, which in practice is a
505
+ #: ledger of history against a roadmap refused at insertion.
506
+ limits: Mapping[str, Mapping[str, int]] = field(default_factory=dict)
507
+ #: `[rules.<role>]` — a prose rule one file is not held to (RK52), applied by
508
+ #: :meth:`schema_for` alongside that file's limits.
509
+ rules: Mapping[str, Mapping[str, bool]] = field(default_factory=dict)
510
+ #: `[refs]` — the namespace a prose role's outline addresses live in (RK340), keyed by
511
+ #: role and applied by :meth:`schema_for`. Empty is every project that has not declared
512
+ #: one, and the behaviour is exactly what it was: one flat set of addresses across both
513
+ #: prose files, which is right for a project whose two files never collide and is the
514
+ #: `section.ambiguous` nothing could configure away for the one where they do.
515
+ refs: Mapping[str, str] = field(default_factory=dict)
516
+ #: `[non_goals]` — declared when this project's non-goals are governed too (RK70), and
517
+ #: **None** when they are prose, which is what every project's were before it opted in.
518
+ non_goals: Scope | None = None
519
+ #: `[criteria]` — the same two numbers about the **positive twin** (RK1265): what must be
520
+ #: true for a block to be finished, where a non-goal says what is not built. Opt-in for the
521
+ #: reason that one is, and separately: a project may govern one list and not the other, and
522
+ #: a criterion that inherited the non-goals' limits would be judged by numbers measured on
523
+ #: a different corpus.
524
+ criteria: Scope | None = None
525
+ #: `[report] upstream` — where a capture of a defect *in this tool* would be filed
526
+ #: (RK87), as `owner/repo`. Configuration and not a constant, so a fork reports to
527
+ #: itself (L6); **None** means `report --issue` refuses rather than guessing a
528
+ #: destination, since a wrong one is a private repository's contents in a stranger's
529
+ #: tracker. Nothing is ever sent from here — this only addresses the command a person
530
+ #: runs.
531
+ upstream: str | None = None
532
+ #: `[claims] held` — how many **minutes** a claim on a line reads as held (RK151). Per
533
+ #: project, because how long a task takes is the one thing about a claim that differs
534
+ #: between backlogs (L6), and bounded by :data:`CLAIM_HELD_MAX`, because a window nobody
535
+ #: would wait out is the lock this was designed not to be.
536
+ held: int = CLAIM_HELD
537
+ #: `[blocks] standing` — the labels that receive work forever and are empty only in the
538
+ #: sense that nobody has filed the next one yet (RK1180). A project block empties once and is
539
+ #: done; a standing category — *realignment of what already shipped*, a triage lane — empties
540
+ #: whenever it is caught up. Measured in one session on such a block: declared, emptied and
541
+ #: dropped **three times**, each drop followed within the hour by a finding that re-declared
542
+ #: it. Per label and not `[headings] permanent`, which is the same fact about a whole project:
543
+ #: a backlog can hold nine blocks that finish and one that never does.
544
+ standing: frozenset[str] = frozenset()
545
+ #: `[install] pinned` — whether this project holds its wired surfaces at the version they
546
+ #: are, deliberately (RK1192). Off by default, so nothing changes for a project that has
547
+ #: not said, and the gate reports a launcher, hook or skill behind the engine answering
548
+ #: here — which is the state that leaves a session with no door in, and which until now
549
+ #: only `install --check` reported, a command nobody thinks to run.
550
+ #:
551
+ #: Declared by a project that has chosen its version and is not the tool's to overrule.
552
+ #: The alternative to this key is a finding a reader learns to skip, which is how a gate
553
+ #: stops being read — the same argument `[headings] permanent` makes one table over.
554
+ #: It silences the *finding* and not the state: `install --check` and `engines` both
555
+ #: still answer, because what is pinned is a decision and not a fact about the files.
556
+ install_pinned: bool = False
557
+ #: `[install] enforced` — whether the engine writing here is held to the plugin the
558
+ #: harness registered (RK1240). A **different pair** from the one above: `pinned` is about
559
+ #: the surfaces vendored into this project against the engine answering, and this is about
560
+ #: that engine against the registered plugin. RK1235's write refusal and RK1238's gate
561
+ #: note read this one; borrowing `pinned` read a project that had quieted a finding as
562
+ #: having asked for a refusal on every write.
563
+ install_enforced: bool = False
564
+ #: `[headings] permanent` — whether this project's block headings outlive the work filed
565
+ #: under them (RK1121). Here and not on the schema: it shapes no line, it decides whether a
566
+ #: door is offered, which is `held`'s kind of fact rather than the grammar's.
567
+ permanent_headings: bool = False
568
+ source: Path | None = None
569
+
570
+ # -- construction ------------------------------------------------------
571
+
572
+ @classmethod
573
+ def default(cls, root: str | Path = ".") -> Config:
574
+ """The layout of a project that has not declared one."""
575
+ base = Path(root).resolve()
576
+ return cls(
577
+ root=base,
578
+ paths={role: base / rel for role, rel in DEFAULT_PATHS.items()},
579
+ )
580
+
581
+ @classmethod
582
+ def discover(cls, start: str | Path = ".") -> Config:
583
+ """Walk up for a config; fall back to the defaults at ``start``."""
584
+ found = find_config(start)
585
+ return cls.load(found) if found else cls.default(start)
586
+
587
+ @classmethod
588
+ def load(cls, path: str | Path) -> Config:
589
+ path = Path(path).resolve()
590
+ with path.open("rb") as handle:
591
+ try:
592
+ document = tomllib.load(handle)
593
+ except tomllib.TOMLDecodeError as broken:
594
+ raise _marked(path, broken) from None
595
+ if path.name == PYPROJECT:
596
+ document = document.get("tool", {}).get("roadkeep", {})
597
+ return cls.parse(document, root=path.parent, source=path)
598
+
599
+ @classmethod
600
+ def parse(
601
+ cls, data: Mapping[str, object], root: str | Path, source: Path | None = None
602
+ ) -> Config:
603
+ base = Path(root).resolve()
604
+ problems: list[str] = []
605
+ _reject_unknown(data, _TOP_KEYS, "", problems)
606
+
607
+ prefixes = _prefixes(data.get("prefix"), problems)
608
+ ids = _ids(data.get("ids"), problems)
609
+ heading_word = _heading_word(data.get("headings"), problems)
610
+ ref_scheme = _string(data, "ref_scheme", "id", problems)
611
+ markers = _markers(data.get("markers"), problems)
612
+ ledger = _ledger(data.get("ledger"), problems)
613
+ limits = _limits(data.get("limits"), problems)
614
+ per_role = _by_role(data.get("limits"), problems)
615
+ rules = _rules(data.get("rules"), problems)
616
+ paths = _paths(data.get("files"), base, problems)
617
+ refs = _refs(data.get("refs"), ref_scheme, paths, problems)
618
+ extras = tuple(
619
+ base / name for name in _string_list(data.get("id_sources"), "id_sources", problems)
620
+ )
621
+ reserved = tuple(
622
+ dict.fromkeys(_string_list(data.get("reserved_ids"), "reserved_ids", problems))
623
+ )
624
+ priority = tuple(_string_list(data.get("priority"), "priority", problems))
625
+ budgets = _budgets(data.get("budgets"), base, problems)
626
+ tool_characters, tool_session = _tool_budget(data.get("tools"), problems)
627
+ brief_read = _read_budget(data.get("reads"), problems)
628
+ grammars = _grammars(data.get("grammar"), problems)
629
+ non_goals = _scope(data.get("non_goals"), problems)
630
+ criteria = _scope(data.get("criteria"), problems, "criteria")
631
+ upstream = _upstream(data.get("report"), problems)
632
+ held = _held(data.get("claims"), problems)
633
+ permanent = _permanent_headings(data.get("headings"), problems)
634
+ standing = _standing_blocks(data.get("blocks"), problems)
635
+ requirements = _requirements(data.get("requirements"), problems)
636
+ pinned = _pinned_surfaces(data.get("install"), problems)
637
+ enforced = _enforced_engine(data.get("install"), problems)
638
+
639
+ schema = None
640
+ if not problems:
641
+ try:
642
+ schema = Schema(
643
+ prefixes=prefixes,
644
+ **ids,
645
+ heading_word=heading_word,
646
+ ref_scheme=ref_scheme,
647
+ **markers,
648
+ **ledger,
649
+ **limits,
650
+ requirements=requirements,
651
+ # Where each of those numbers was written, so a refusal over one names
652
+ # the line somebody reviews rather than only the number (RK1067).
653
+ origins=_origins(source, _scalars(data.get("limits"))), # RK1067
654
+ )
655
+ except ValueError as error: # a valid TOML file can still be a wrong format
656
+ problems.append(str(error))
657
+ if schema is not None:
658
+ _check_priority(schema, priority, problems)
659
+ _check_reserved(schema, reserved, problems)
660
+ if problems:
661
+ raise ConfigError(tuple(problems), source)
662
+
663
+ assert schema is not None
664
+ return cls(
665
+ root=base,
666
+ schema=schema,
667
+ paths=paths,
668
+ extra_id_sources=extras,
669
+ reserved=reserved,
670
+ priority=priority,
671
+ budgets=budgets,
672
+ brief_read=brief_read,
673
+ tool_characters=tool_characters,
674
+ tool_session=tool_session,
675
+ grammars=grammars,
676
+ limits=per_role,
677
+ rules=rules,
678
+ refs=refs,
679
+ non_goals=non_goals,
680
+ criteria=criteria,
681
+ upstream=upstream,
682
+ held=held,
683
+ permanent_headings=permanent,
684
+ standing=standing,
685
+ install_pinned=pinned,
686
+ install_enforced=enforced,
687
+ source=source,
688
+ )
689
+
690
+ # -- using it ----------------------------------------------------------
691
+
692
+ def has(self, role: str) -> bool:
693
+ return role in self.paths
694
+
695
+ def path(self, role: str) -> Path:
696
+ try:
697
+ return self.paths[role]
698
+ except KeyError:
699
+ raise KeyError(
700
+ f"this project declares no {role!r} file (has: "
701
+ f"{', '.join(sorted(self.paths)) or 'none'})"
702
+ ) from None
703
+
704
+ def schema_for(self, role: str) -> Schema:
705
+ """The changelog is the same format in its ledger configuration, not another.
706
+
707
+ The deferred store (RK96) is the third such configuration and the same claim: one
708
+ format, one marker set per file, and the file a line sits in is what states its
709
+ status — never a second grammar.
710
+
711
+ Plus whatever `[limits.<role>]` says (RK50) — the same format again, held to this
712
+ file's own numbers, because a ledger of history and a roadmap line are refused at
713
+ opposite ends of the work.
714
+
715
+ The shape comes from a **declaration** since RK1064: the grammar this project wrote
716
+ for the role, or the one the tool ships for it, applied by `Schema.under` either
717
+ way. `as_ledger` and `as_deferred` are still the names those two grammars go by and
718
+ are what every other caller reaches for; what changed is that neither is where the
719
+ shape is stated, so a project overriding one is not overriding a method.
720
+ """
721
+ declared = self.grammars.get(role) or DEFAULT_GRAMMARS.get(role)
722
+ schema = self.schema.under(declared) if declared else self.schema
723
+ own: dict[str, object] = {**self.limits.get(role, {}), **self.rules.get(role, {})}
724
+ if role in self.limits:
725
+ # The role's own citations layered over the shared ones (RK1067), so a `why`
726
+ # refused in the changelog names `[limits.changelog].why` and not the number
727
+ # the roadmap is held to — which is the whole reason RK50 exists, reaching the
728
+ # author at the moment they are standing over one of the two.
729
+ own["origins"] = tuple(
730
+ {**dict(schema.origins), **dict(_origins(self.source, self.limits[role], role))}
731
+ .items()
732
+ )
733
+ # The namespace this role's addresses live in (RK340), carried on the schema for the
734
+ # reason every other per-role difference is: the file travels with the rules it is
735
+ # read under, so nothing downstream has to be handed a role beside a document.
736
+ if role in self.refs:
737
+ own["ref_prefix"] = self.refs[role]
738
+ return replace(schema, **own) if own else schema
739
+
740
+ def document(self, role: str) -> Document:
741
+ """Load a governed file under the right schema — the one seam every command uses.
742
+
743
+ The project travels with the file, which is what lets a save re-derive the blocks
744
+ projected from it (RK188): a document that arrived any other way has no project and
745
+ writes exactly itself.
746
+
747
+ `Document` is reached here and not at module level (RK261). This module is imported by
748
+ every command in the package, and the guard imports it to answer *where* a write was
749
+ going — it never opens the file, and paid 9 ms for the model that would. Measured, it is
750
+ not a cost moved: 22 of the 37 modules import `document` directly, `cli.py` among them,
751
+ so the commands that load a document already had it before this line runs.
752
+ """
753
+ from roadkeep.kernel.document import Document # noqa: PLC0415 - RK261
754
+
755
+ return replace(
756
+ Document.load(self.path(role), self.schema_for(role)), config=self
757
+ )
758
+
759
+ def locate(self, path: str | Path) -> Path:
760
+ """A path naming a file **of this project**, resolved against its root (RK1101).
761
+
762
+ `-C` selects the project and never the working directory, so a relative path had two
763
+ possible bases and the answer differed by argument: `budget --file agents.md` resolved
764
+ against the root and `adopt ROADMAP.md` against whatever directory the process happened
765
+ to be in. Two rules is worse than either, and this is the one the tool already kept for
766
+ the file arguments that name governed files.
767
+
768
+ The half that decided it is the served surface. Over MCP the process's directory is the
769
+ session's and the project is `-C`'s, so a relative path was read from a tree the caller
770
+ never named — loudly where the file is absent there, and **silently where it is not**:
771
+ a real measurement of somebody else's backlog, reported under this project's prefix,
772
+ markers and limits, with nothing in the output naming the tree it read.
773
+
774
+ Only for a path that names a file of the project. A body file (`add --section-body-file`,
775
+ `section amend --body-file`) is the caller's own and stays relative to the caller, the way
776
+ `cat` is: it names a file to *read from* and can be anywhere, and nothing in this tool
777
+ ever composes one.
778
+
779
+ **A capture is not one of those, and RK1101 put it there** (RK1396). It lives under this
780
+ project's own `.roadkeep/reports/`, `stats` counts it as this project's debt and `capture
781
+ filed` refuses a path that is not "a capture this project holds" — so it was a file of
782
+ the project by every reading except the one that resolved it. What made the cost visible
783
+ is RK1395: both readers now *print* a project-relative path for one, so the tool composed
784
+ a door and then refused it, with a message naming the very directory the file is in.
785
+ """
786
+ given = Path(path)
787
+ return given if given.is_absolute() else self.root / given
788
+
789
+ def relative(self, path: Path) -> str:
790
+ """A path as the project spells it — output has to be machine-independent."""
791
+ try:
792
+ return Path(path).resolve().relative_to(self.root).as_posix()
793
+ except ValueError:
794
+ return Path(path).as_posix()
795
+
796
+ def missing(self) -> tuple[str, ...]:
797
+ """Declared roles with no file on disk — what `init` creates and `lint` reports."""
798
+ return tuple(role for role, path in self.paths.items() if not path.exists())
799
+
800
+ def id_sources(self) -> tuple[Path, ...]:
801
+ """Every file that may carry an id, governed or not, in declaration order."""
802
+ seen: dict[Path, None] = {}
803
+ for role in ROLES:
804
+ if role in self.paths:
805
+ seen.setdefault(self.paths[role])
806
+ for extra in self.extra_id_sources:
807
+ seen.setdefault(extra)
808
+ return tuple(seen)
809
+
810
+
811
+ def find_config(start: str | Path = ".") -> Path | None:
812
+ """The nearest `roadkeep.toml`, or a `pyproject.toml` that configures roadkeep."""
813
+ here = Path(start).resolve()
814
+ for directory in (here, *here.parents):
815
+ candidate = directory / CONFIG_NAME
816
+ if candidate.is_file():
817
+ return candidate
818
+ pyproject = directory / PYPROJECT
819
+ if pyproject.is_file() and _declares_roadkeep(pyproject):
820
+ return pyproject
821
+ return None
822
+
823
+
824
+ def _declares_roadkeep(path: Path) -> bool:
825
+ """Whether this `pyproject.toml` configures roadkeep — a probe, and it may not refuse.
826
+
827
+ The mark is taken off **here and only here** (RK1030), because this decides whether a
828
+ file is the project's config at all: a marked `pyproject.toml` parsed as-is is a
829
+ `TOMLDecodeError`, which this swallows, so discovery walked past a file that declares
830
+ `[tool.roadkeep]` and every verb then ran on defaults — the encoding defect turning into
831
+ silence rather than a refusal, which is the one outcome worse than the refusal.
832
+
833
+ Found here, refused in :meth:`Config.load`, which reads the bytes as they are and says
834
+ what the mark is. The strip is a question about *which file* and never about its content.
835
+ """
836
+ try:
837
+ raw = path.read_bytes()
838
+ except OSError:
839
+ return False
840
+ try:
841
+ data = tomllib.loads(raw.removeprefix(_BOM).decode("utf-8"))
842
+ except (UnicodeDecodeError, tomllib.TOMLDecodeError):
843
+ return False
844
+ return "roadkeep" in data.get("tool", {})
845
+
846
+
847
+ def _skew(problems: tuple[str, ...]) -> str:
848
+ """The reading an unknown key cannot rule out, or `""` where none was reported (RK1150).
849
+
850
+ Keyed off the problem text this module writes, one function over — a code would be a second
851
+ vocabulary for the same set, and this file's problems are prose by construction (`lint` is
852
+ where findings carry codes). `engines` is the door because it is the one command that answers
853
+ *which copies answer here*: the build that writes, the plugin's own, and the gate's.
854
+ """
855
+ if not any(one.startswith("unknown key") for one in problems):
856
+ return ""
857
+ from roadkeep.provenance import invocation # noqa: PLC0415 - RK260, the refusal path only
858
+
859
+ return (
860
+ " — unknown to this build: a typo if nothing declares it, an upgrade if a newer "
861
+ f"roadkeep does, and `{invocation()} engines` names the copies answering here"
862
+ )
863
+
864
+
865
+ # -- reading one key at a time, collecting what is wrong -------------------
866
+
867
+
868
+ def _reject_unknown(
869
+ data: Mapping[str, object], allowed: frozenset[str], where: str, problems: list[str]
870
+ ) -> None:
871
+ """Every key this schema does not declare, said as **two** readings and not one (RK1150).
872
+
873
+ The message used to name the key and the allowed set, which is the older schema presented as
874
+ though it were the schema: `unknown key 'headings.permanent' (allowed: headings.word)` was a
875
+ key a *later* roadkeep added, read by a build that predates it, and the cheapest action the
876
+ sentence suggested was deleting a key the project needs. Reached from Shio, where the server
877
+ resolves this package from the plugin cache and the project from a checkout.
878
+
879
+ A key no version ever declared is a typo and a key *this* build does not have is an upgrade,
880
+ and nothing in the file separates them — so both are named, and the clause carries the one
881
+ command that decides it (RK14/15's rule, on the refusal that reads a config rather than a
882
+ line). `engines` is that command: it prints the copy that writes beside the plugin's own.
883
+ """
884
+ for key in data:
885
+ if key not in allowed:
886
+ problems.append(
887
+ f"unknown key '{where}{key}' (allowed: "
888
+ f"{', '.join(where + name for name in sorted(allowed))})"
889
+ )
890
+
891
+
892
+ def _string(
893
+ data: Mapping[str, object], key: str, default: str, problems: list[str]
894
+ ) -> str:
895
+ value = data.get(key, default)
896
+ if not isinstance(value, str):
897
+ problems.append(f"{key} must be a string, got {type(value).__name__}")
898
+ return default
899
+ return value
900
+
901
+
902
+ def _prefixes(raw: object, problems: list[str]) -> tuple[str, ...]:
903
+ """`prefix` — one family, or the list a backlog numbered by track needs (RK74).
904
+
905
+ A string stays a string in the file, because three of the four live corpora number one
906
+ family and `prefix = ["RK"]` would be a list nobody asked for. A list is read in
907
+ declaration order: the first is what `add` mints under when no family is named, and
908
+ the order is the author's, so a message that reprints it prints their list back.
909
+ """
910
+ if raw is None:
911
+ return ("RK",)
912
+ if isinstance(raw, str):
913
+ return (raw,)
914
+ if isinstance(raw, list) and all(isinstance(item, str) for item in raw):
915
+ if not raw:
916
+ problems.append("prefix must name at least one family")
917
+ return ("RK",)
918
+ return tuple(raw)
919
+ problems.append(
920
+ "prefix must be a string, or a list of strings for a backlog that numbers "
921
+ "by track"
922
+ )
923
+ return ("RK",)
924
+
925
+
926
+ def _ids(raw: object, problems: list[str]) -> dict[str, object]:
927
+ """`[ids]` — the width the number is padded to, and whether a sub-letter is legal (RK106).
928
+
929
+ Both default to the shape every project had before this table existed, so a config that
930
+ declares nothing reads exactly as it did. Two live corpora declare one: Dumont pads `D01`
931
+ through `D09` on every line, and Turing carries `T24b`, `T221a` and `T227a` from tasks
932
+ split after their numbers were cited in commits and issues.
933
+
934
+ What is being declared is a *spelling*, never a scheme — the non-goal is contiguity,
935
+ reuse and ordering, which are properties of real backlogs, and a project stating the
936
+ width it already writes is the opposite of a scheme imposed on it (L6).
937
+ """
938
+ default: dict[str, object] = {"id_pad": 1, "id_suffix": False}
939
+ if raw is None:
940
+ return default
941
+ if not isinstance(raw, Mapping):
942
+ problems.append("ids must be a table with 'pad' and 'suffix'")
943
+ return default
944
+ _reject_unknown(raw, _IDS_KEYS, "ids.", problems)
945
+ pad = raw.get("pad", 1)
946
+ if not isinstance(pad, int) or isinstance(pad, bool) or pad < 1:
947
+ problems.append(
948
+ "ids.pad must be a positive integer: it is the width the number is "
949
+ "zero-filled to, and 1 is an unpadded id"
950
+ )
951
+ pad = 1
952
+ suffix = raw.get("suffix", False)
953
+ if not isinstance(suffix, bool):
954
+ problems.append("ids.suffix must be true or false")
955
+ suffix = False
956
+ return {"id_pad": pad, "id_suffix": suffix}
957
+
958
+
959
+ def _heading_word(raw: object, problems: list[str]) -> str:
960
+ """`[headings] word` — what this project files work under (RK75).
961
+
962
+ Defaults to `Block`, so a project that never declares it is unchanged. Declared by the
963
+ three of four adopting corpora that chose otherwise: Dumont files under `## Track A`,
964
+ cursarei under `## Fase 0`, and each was getting a finding per line for its own word.
965
+ """
966
+ if raw is None:
967
+ return DEFAULT_HEADING_WORD
968
+ if not isinstance(raw, Mapping):
969
+ problems.append("headings must be a table with 'word'")
970
+ return DEFAULT_HEADING_WORD
971
+ _reject_unknown(raw, _HEADING_KEYS, "headings.", problems)
972
+ word = raw.get("word", DEFAULT_HEADING_WORD)
973
+ if not isinstance(word, str):
974
+ problems.append("headings.word must be a string")
975
+ return DEFAULT_HEADING_WORD
976
+ return word
977
+
978
+
979
+ def _standing_blocks(raw: object, problems: list[str]) -> frozenset[str]:
980
+ """`[blocks] standing` — the labels whose emptiness means *caught up* (RK1180).
981
+
982
+ Empty by default, so nothing changes for a project that has not said. A label listed here
983
+ empties the way a queue does rather than the way a project does, and three answers change
984
+ with it: `ship` says caught up instead of finished, the offer to drop the heading is not
985
+ made, and a queue token over it is no longer an order over nothing.
986
+
987
+ Labels and never a per-block table of properties: what a block *is* is one bit, and a table
988
+ would invite the second, which is a plan this tool would then be keeping.
989
+ """
990
+ if not isinstance(raw, Mapping):
991
+ if raw is not None:
992
+ problems.append("blocks must be a table, e.g. [blocks] standing = [\"N\"]")
993
+ return frozenset()
994
+ value = raw.get("standing", ())
995
+ if isinstance(value, str) or not isinstance(value, Sequence):
996
+ problems.append('blocks.standing must be a list of labels, e.g. standing = ["N"]')
997
+ return frozenset()
998
+ labels = [one for one in value if isinstance(one, str) and one.strip()]
999
+ if len(labels) != len(list(value)):
1000
+ problems.append("blocks.standing takes block labels as strings")
1001
+ return frozenset(one.strip() for one in labels)
1002
+
1003
+
1004
+ def _permanent_headings(raw: object, problems: list[str]) -> bool:
1005
+ """`[headings] permanent` — whether an emptied heading is one this project ever drops.
1006
+
1007
+ Off by default, so nothing changes for a project that has not said (RK1121). Declared by
1008
+ one whose headings are the structure of the backlog rather than a grouping of live work:
1009
+ measured here across a session, **nine ships, six offers to withdraw a heading — D, B, F,
1010
+ B, C, E — and no block ever dropped.** The offer's own clause said `where this project
1011
+ drops one`, which is the sentence knowing the answer it cannot read: whether a finished
1012
+ block is a heading to take out is a fact about the plan, and this is where the plan speaks.
1013
+
1014
+ It silences the *offer* and not the state: the ship still prints `finished`, and the gate's
1015
+ `block.emptied` note (RK269) still records the transition. What emptied is history and what
1016
+ to do about it is the project's — the split every configurable rule here keeps.
1017
+ """
1018
+ if not isinstance(raw, Mapping):
1019
+ # Not a second refusal: `_heading_word` reads the same table and reports the shape.
1020
+ return False
1021
+ value = raw.get("permanent", False)
1022
+ if not isinstance(value, bool):
1023
+ problems.append("headings.permanent must be true or false")
1024
+ return False
1025
+ return value
1026
+
1027
+
1028
+ def _pinned_surfaces(raw: object, problems: list[str]) -> bool:
1029
+ """`[install] pinned` — whether this project holds its wired surfaces where they are.
1030
+
1031
+ The half RK1192 could not ship without. The gate now reports a launcher, hook or skill
1032
+ behind the engine answering here, and it fires every turn through the `Stop` hook — so a
1033
+ project that has *decided* to sit on an older surface would be told about that decision
1034
+ on every turn for as long as it holds. A finding a reader learns to skip is how a gate
1035
+ stops being read, which costs more than the check is worth.
1036
+
1037
+ Off by default, exactly as `[headings] permanent` is and for its reason: nothing changes
1038
+ for a project that has not spoken, and the key exists so the project can. And it silences
1039
+ the *finding* and never the state — `install --check` still reports the drift on demand
1040
+ and `engines` still adjudicates the three copies, because what is declared here is a
1041
+ decision about which version to run and not a claim that the files agree.
1042
+ """
1043
+ if not isinstance(raw, Mapping):
1044
+ return False
1045
+ _reject_unknown(raw, _INSTALL_KEYS, "install.", problems)
1046
+ return _install_flag(raw, "pinned", problems)
1047
+
1048
+
1049
+ def _enforced_engine(raw: object, problems: list[str]) -> bool:
1050
+ """`[install] enforced` — whether the engine writing here is held to the registered one.
1051
+
1052
+ Split from `pinned` (RK1240), and the reason is that the two are about **different pairs
1053
+ of copies**. `pinned` is a decision about the surfaces vendored into this project against
1054
+ the engine answering here — RK1192's subject, and what its docstring declares. RK1235's
1055
+ write refusal and RK1238's gate note are about the engine answering here against the
1056
+ plugin the harness registered, which is a comparison that key never mentioned.
1057
+
1058
+ Borrowing it read a project that had quieted one finding as having asked for a refusal on
1059
+ every write, and in the direction that costs most: :attr:`~roadkeep.installing.Engines.
1060
+ verdict` calls **any** version difference `behind`, so a project deliberately sitting on
1061
+ an older vendored copy whose plugin cache moved forward was refused and sent to the copy
1062
+ it had chosen against.
1063
+
1064
+ Its own key removes both. Declaring this is a project saying *the registered plugin is the
1065
+ copy that should write here*, which is exactly the standing a refusal that names
1066
+ `engines --invoke` needs — and off by default, so nothing fires for a project that has
1067
+ not said so.
1068
+ """
1069
+ if not isinstance(raw, Mapping):
1070
+ return False
1071
+ return _install_flag(raw, "enforced", problems)
1072
+
1073
+
1074
+ def _install_flag(raw: Mapping[str, object], key: str, problems: list[str]) -> bool:
1075
+ """One boolean under `[install]`, refused the same way for both (RK1240)."""
1076
+ value = raw.get(key, False)
1077
+ if not isinstance(value, bool):
1078
+ problems.append(f"install.{key} must be true or false")
1079
+ return False
1080
+ return value
1081
+
1082
+
1083
+ def _markers(raw: object, problems: list[str]) -> dict[str, object]:
1084
+ """The `[markers]` table as :class:`Schema` keywords — the four the format varies by."""
1085
+ default: dict[str, object] = {
1086
+ "markers": OPEN_MARKERS,
1087
+ "shipped_marker": SHIPPED,
1088
+ "retired_marker": RETIRED,
1089
+ "deferred_marker": DEFERRED,
1090
+ "undesigned": UNDESIGNED,
1091
+ }
1092
+ if raw is None:
1093
+ return default
1094
+ if not isinstance(raw, Mapping):
1095
+ problems.append(
1096
+ "markers must be a table with 'open', 'shipped', 'retired' and 'deferred'"
1097
+ )
1098
+ return default
1099
+ _reject_unknown(raw, _MARKER_KEYS, "markers.", problems)
1100
+ open_markers = tuple(_string_list(raw.get("open"), "markers.open", problems))
1101
+ shipped = _one_marker(raw, "shipped", SHIPPED, problems)
1102
+ retired = _one_marker(raw, "retired", RETIRED, problems)
1103
+ deferred = _one_marker(raw, "deferred", DEFERRED, problems)
1104
+ if shipped == retired:
1105
+ problems.append(
1106
+ "markers.shipped and markers.retired must differ: a ledger where both "
1107
+ "read the same cannot say whether the work was done"
1108
+ )
1109
+ if deferred in (shipped, retired):
1110
+ # Checked here rather than in the schema, where the open-set clash is: this pair
1111
+ # only meets inside `as_ledger`, so a project that spelled them the same would get
1112
+ # its refusal from a method call instead of from the file it typed them in.
1113
+ problems.append(
1114
+ "markers.deferred must differ from shipped and retired: a paused task that "
1115
+ "reads as a departure is the one distinction the state exists to make"
1116
+ )
1117
+ undesigned = _undesigned(raw, open_markers or OPEN_MARKERS, problems)
1118
+ for marker in (*open_markers, shipped, retired, deferred):
1119
+ _reject_invisible(marker, problems)
1120
+ if "ledger" in raw:
1121
+ # Moved to its own table by RK48, and refused rather than aliased: two spellings of
1122
+ # one flag are two spellings that can disagree, and a config error that names its
1123
+ # replacement costs one edit against a setting that silently stops being read.
1124
+ problems.append(
1125
+ "markers.ledger moved to [ledger] marker (RK48): the ledger's shape is one "
1126
+ "table, since [ledger] symptom cannot live under markers"
1127
+ )
1128
+ return {
1129
+ "markers": open_markers or OPEN_MARKERS,
1130
+ "shipped_marker": shipped,
1131
+ "retired_marker": retired,
1132
+ "deferred_marker": deferred,
1133
+ "undesigned": undesigned,
1134
+ }
1135
+
1136
+
1137
+ def _ledger(raw: object, problems: list[str]) -> dict[str, object]:
1138
+ """Which slots the ledger's own lines carry — the marker (RK43) and the symptom (RK48).
1139
+
1140
+ Both default to *present*, so a project that declares nothing keeps the format this
1141
+ repository's own ledger is written in, and a ledger written before the tool declares
1142
+ the two absences it already has.
1143
+ """
1144
+ default = {"ledger_marker": True, "ledger_symptom": True}
1145
+ if raw is None:
1146
+ return default
1147
+ if not isinstance(raw, Mapping):
1148
+ problems.append("ledger must be a table with 'marker' and 'symptom'")
1149
+ return default
1150
+ _reject_unknown(raw, _LEDGER_KEYS, "ledger.", problems)
1151
+ return {
1152
+ "ledger_marker": _flag(raw, "marker", True, problems),
1153
+ "ledger_symptom": _flag(raw, "symptom", True, problems),
1154
+ }
1155
+
1156
+
1157
+ def _flag(
1158
+ raw: Mapping[str, object], key: str, default: bool, problems: list[str]
1159
+ ) -> bool:
1160
+ value = raw.get(key, default)
1161
+ if not isinstance(value, bool):
1162
+ problems.append(f"ledger.{key} must be true or false")
1163
+ return default
1164
+ return value
1165
+
1166
+
1167
+ def _undesigned(
1168
+ raw: Mapping[str, object], open_markers: tuple[str, ...], problems: list[str]
1169
+ ) -> tuple[str, ...]:
1170
+ """Which open markers mean the design is still to be written (RK83).
1171
+
1172
+ Undeclared, it is the built-in list narrowed to what this project actually opens with,
1173
+ so a backlog whose marker set never spells 💭 gets an empty one instead of a default
1174
+ naming a codepoint it does not use. Declared, every entry has to be an open marker:
1175
+ a marker `pick` sets aside and no line can carry is a `--designed` that silently does
1176
+ nothing, and this is the file it was typed in.
1177
+ """
1178
+ if "undesigned" not in raw:
1179
+ return tuple(m for m in UNDESIGNED if m in open_markers)
1180
+ declared = tuple(_string_list(raw.get("undesigned"), "markers.undesigned", problems))
1181
+ stray = [m for m in declared if m not in open_markers]
1182
+ if stray:
1183
+ problems.append(
1184
+ f"markers.undesigned names {' '.join(stray)}, which markers.open does not: "
1185
+ "a marker no line may carry is a distinction `pick` can never act on"
1186
+ )
1187
+ return tuple(m for m in declared if m in open_markers)
1188
+
1189
+
1190
+ def _one_marker(
1191
+ raw: Mapping[str, object], key: str, default: str, problems: list[str]
1192
+ ) -> str:
1193
+ value = raw.get(key, default)
1194
+ if not isinstance(value, str):
1195
+ problems.append(f"markers.{key} must be a string")
1196
+ return default
1197
+ return value
1198
+
1199
+
1200
+ def _reject_invisible(marker: str, problems: list[str]) -> None:
1201
+ for char, name in _INVISIBLE.items():
1202
+ if char in marker:
1203
+ problems.append(
1204
+ f"marker {marker.replace(char, '')!r} carries {name}, which is "
1205
+ f"invisible in an editor and unequal to the bare character: every "
1206
+ f"line would be permanently out of round-trip"
1207
+ )
1208
+
1209
+
1210
+ def _check_priority(
1211
+ schema: Schema, priority: tuple[str, ...], problems: list[str]
1212
+ ) -> None:
1213
+ """A priority entry names a task or a block, and is typed by the same code deps are.
1214
+
1215
+ Refused rather than ignored, like every other key here: an entry `pick` cannot
1216
+ resolve is a queue the author believes is in force and is not, and a *silent* one is
1217
+ worse than none — the tool would then answer "lowest ready id" while looking like it
1218
+ had applied a declaration.
1219
+ """
1220
+ for token in priority:
1221
+ kind = schema.classify_dep(Dep(token))
1222
+ if kind is DepKind.TASK and not schema.id_pattern().match(token):
1223
+ problems.append(f"priority: not an id of this project: {token!r}")
1224
+ elif kind in (DepKind.RANGE, DepKind.EXTERNAL):
1225
+ problems.append(
1226
+ f"priority: {token!r} is neither an id nor 'Block X': a queue is an "
1227
+ f"order over work this backlog holds, so nothing else can be first"
1228
+ )
1229
+
1230
+
1231
+ def _check_reserved(
1232
+ schema: Schema, reserved: tuple[str, ...], problems: list[str]
1233
+ ) -> None:
1234
+ """A reserved id is an id of this project, and refused where it is not (RK1031).
1235
+
1236
+ The whole value of the list is that a token on it is *taken* and a token off it is a
1237
+ hazard, and both readings are worthless if the list can hold something the deriver
1238
+ cannot compare against a number. A word that is not an id would sit there looking like a
1239
+ reservation and reserve nothing — which is the silent state this declaration exists to
1240
+ replace, wearing the declaration's own name.
1241
+ """
1242
+ for token in reserved:
1243
+ if not schema.id_pattern().match(token):
1244
+ problems.append(
1245
+ f"reserved_ids: not an id of this project: {token!r} — a reservation is an "
1246
+ f"address the deriver skips, so it has to be one the deriver can read"
1247
+ )
1248
+
1249
+
1250
+ def _scalars(raw: object) -> dict[str, object]:
1251
+ """The keys a table sets directly, less its sub-tables — `[limits]` without a role's."""
1252
+ if not isinstance(raw, Mapping):
1253
+ return {}
1254
+ return {key: value for key, value in raw.items() if not isinstance(value, Mapping)}
1255
+
1256
+
1257
+ def _limits(raw: object, problems: list[str]) -> dict[str, int]:
1258
+ """`[limits]` — the numbers every governed file is held to, before any role says less.
1259
+
1260
+ A sub-table is a role's own (`[limits.changelog]`, RK50) and is read by :func:`_by_role`;
1261
+ it is skipped here rather than rejected, so one table can carry both.
1262
+ """
1263
+ if raw is None:
1264
+ return {}
1265
+ if not isinstance(raw, Mapping):
1266
+ problems.append("limits must be a table")
1267
+ return {}
1268
+ scalars = {key: value for key, value in raw.items() if not isinstance(value, Mapping)}
1269
+ _reject_unknown(scalars, frozenset(_LIMIT_KEYS), "limits.", problems)
1270
+ return _read_limits(scalars, "limits", problems)
1271
+
1272
+
1273
+ def _by_role(raw: object, problems: list[str]) -> dict[str, dict[str, int]]:
1274
+ """`[limits.<role>]` — where one file is held to a different number (RK50).
1275
+
1276
+ A roadmap line is refused at insertion, where the refusal costs a retry; a ledger line
1277
+ is history, and Turing's reads 938 characters at the median against a `line` of 320.
1278
+ Judging the second by the first is a report about work nobody will redo, so the number
1279
+ is per role — and per *role*, not per path, because the role is what the format knows.
1280
+ """
1281
+ if not isinstance(raw, Mapping):
1282
+ return {}
1283
+ out: dict[str, dict[str, int]] = {}
1284
+ for role, value in raw.items():
1285
+ if not isinstance(value, Mapping):
1286
+ continue
1287
+ where = f"limits.{role}"
1288
+ if role not in ROLES:
1289
+ problems.append(
1290
+ f"{where}: not a governed role ({', '.join(sorted(ROLES))}): a limit "
1291
+ f"for a file the format does not know is a limit nothing reads"
1292
+ )
1293
+ continue
1294
+ _reject_unknown(value, frozenset(_LIMIT_KEYS), f"{where}.", problems)
1295
+ found = _read_limits(value, where, problems)
1296
+ if found:
1297
+ out[role] = found
1298
+ return out
1299
+
1300
+
1301
+ def _rules(raw: object, problems: list[str]) -> dict[str, dict[str, bool]]:
1302
+ """`[rules.<role>]` — a rule one file is not held to (RK52, RK66).
1303
+
1304
+ Only per role: `why` is one sentence ending in a stop *because* the remainder belongs in
1305
+ the section the line points at. That reasoning is a roadmap's. A ledger adopted with
1306
+ history in it holds 233 paragraphs that were written before the rule existed, and no edit
1307
+ available to their author makes them one sentence — so the project declares the file
1308
+ exempt, rather than the tool deciding the rule never mattered there. The write path reads
1309
+ the same declaration, so what a project exempts it may also record.
1310
+
1311
+ `ref = false` is the third, and it is the same shape of decision: Shio's process guide
1312
+ says a task with no rationale section carries no pointer, and three of its lines are a
1313
+ finding for obeying it. Both positions are defensible, which is what makes this
1314
+ configuration rather than a default to argue about (L6). It defaults to *required*, so
1315
+ nothing changes for a project that never declares it — and only the demand is
1316
+ negotiable, never the resolution: a pointer that is written must still point at
1317
+ something, which :mod:`roadkeep.linting` checks whatever this says.
1318
+ """
1319
+ if not isinstance(raw, Mapping):
1320
+ if raw is not None:
1321
+ problems.append("rules must be a table of per-role tables")
1322
+ return {}
1323
+ out: dict[str, dict[str, bool]] = {}
1324
+ for role, value in raw.items():
1325
+ where = f"rules.{role}"
1326
+ if role not in ROLES:
1327
+ problems.append(
1328
+ f"{where}: not a governed role ({', '.join(sorted(ROLES))}): a rule for a "
1329
+ f"file the format does not know is a rule nothing reads"
1330
+ )
1331
+ continue
1332
+ if not isinstance(value, Mapping):
1333
+ problems.append(f"{where} must be a table of rule = true|false")
1334
+ continue
1335
+ _reject_unknown(value, frozenset(_RULE_KEYS), f"{where}.", problems)
1336
+ if role == "changelog" and "ref" in value:
1337
+ # The ledger has no pointer to demand or to waive: `ship` deletes §<id> in the
1338
+ # same transaction that writes the entry, so `ref = true` here would put every
1339
+ # line that ever ships permanently in violation, and `ref = false` states what
1340
+ # `as_ledger` already guarantees. Refused rather than ignored, like every other
1341
+ # key in this file.
1342
+ problems.append(
1343
+ f"{where}.ref: the ledger carries no pointer at all — the rationale "
1344
+ f"section is deleted when the task ships, so there is none to require"
1345
+ )
1346
+ continue
1347
+ found = {
1348
+ field: _flag(value, key, True, problems)
1349
+ for key, field in _RULE_KEYS.items()
1350
+ if key in value
1351
+ }
1352
+ if found:
1353
+ out[role] = found
1354
+ return out
1355
+
1356
+
1357
+ def _refs(
1358
+ raw: object, ref_scheme: str, declared: Mapping[str, Path], problems: list[str]
1359
+ ) -> dict[str, str]:
1360
+ """`[refs]` — which namespace a prose role's outline addresses live in (RK340).
1361
+
1362
+ Its own table and not a fourth key under `[rules.<role>]`, which says which rules a file
1363
+ is *not held to* and whose every value is a flag: a namespace is a name, and a string
1364
+ among booleans is the shape that made `markers.ledger` carry half of two decisions.
1365
+
1366
+ Three refusals, each of them a way for a namespace to fail to be one:
1367
+
1368
+ * **A prose role only.** The roadmap and the ledger hold lines and not headings, so a
1369
+ prefix on one addresses nothing — and the deferred store carries the section a pause
1370
+ kept, which is the prose role it came from and not a fourth namespace.
1371
+ * **Under an outline only.** The id scheme's anchor *is* the id, and ids are already one
1372
+ namespace this format refuses to spend twice; prefixing them would put a second address
1373
+ on a section whose first one the roadmap derives.
1374
+ * **Unique.** Two roles sharing a prefix is the collision this exists to end, one level
1375
+ up, and it would be the harder one to see: the addresses would agree and the files
1376
+ would not.
1377
+
1378
+ A role a project does not declare is refused too. It reads as configuration nothing
1379
+ applies, and the one thing worse than an unresolvable address is a declaration the author
1380
+ believes resolved it.
1381
+ """
1382
+ if raw is None:
1383
+ return {}
1384
+ if not isinstance(raw, Mapping):
1385
+ problems.append("refs must be a table of role = \"<prefix>\"")
1386
+ return {}
1387
+ out: dict[str, str] = {}
1388
+ for role, value in raw.items():
1389
+ where = f"refs.{role}"
1390
+ if role not in PROSE_ROLES:
1391
+ problems.append(
1392
+ f"{where}: not a prose role ({', '.join(PROSE_ROLES)}): only a file that "
1393
+ f"declares headings has addresses to put in a namespace"
1394
+ )
1395
+ continue
1396
+ if not isinstance(value, str) or not REF_PREFIX_RE.match(value):
1397
+ problems.append(
1398
+ f"{where} must be one word of letters and digits starting with a letter: "
1399
+ f"it is written in front of an address as <prefix>{REF_SEPARATOR}<x.y>"
1400
+ )
1401
+ continue
1402
+ if ref_scheme != "outline":
1403
+ problems.append(
1404
+ f"{where}: a namespace is for ref_scheme = \"outline\" — under \"id\" the "
1405
+ f"anchor is the task's own id, which is already unique across the project"
1406
+ )
1407
+ continue
1408
+ if role not in declared:
1409
+ problems.append(
1410
+ f"{where}: this project declares no {role!r} file, so the namespace "
1411
+ f"addresses nothing — declare it under [files], or drop this line"
1412
+ )
1413
+ continue
1414
+ taken = next((other for other, one in out.items() if one == value), None)
1415
+ if taken is not None:
1416
+ problems.append(
1417
+ f"{where}: {value!r} is already {taken}'s namespace, and two roles sharing "
1418
+ f"one is the collision a namespace exists to end"
1419
+ )
1420
+ continue
1421
+ out[role] = value
1422
+ return out
1423
+
1424
+
1425
+ def _read_limits(raw: Mapping[str, object], where: str, problems: list[str]) -> dict[str, int]:
1426
+ out: dict[str, int] = {}
1427
+ for key, field_name in _LIMIT_KEYS.items():
1428
+ if key not in raw:
1429
+ continue
1430
+ value = raw[key]
1431
+ if not isinstance(value, int) or isinstance(value, bool):
1432
+ problems.append(f"{where}.{key} must be an integer")
1433
+ continue
1434
+ out[field_name] = value
1435
+ return out
1436
+
1437
+
1438
+ def _scope(raw: object, problems: list[str], table: str = "non_goals") -> Scope | None:
1439
+ """`[non_goals]` — declared at all means governed, and each number may be left default.
1440
+
1441
+ An empty table is legal and is the shortest way to opt in: what a project is declaring
1442
+ is *that* the list is a schema, and the two limits are what it may then also tune (L6).
1443
+
1444
+ ``table`` is which of the two lists is being read (RK1265). `[criteria]` is the same two
1445
+ numbers about the positive twin, so the reader is one function and only the problems it
1446
+ reports name the key — two copies would be two opt-ins that came to accept different shapes.
1447
+ """
1448
+ if raw is None:
1449
+ return None
1450
+ if not isinstance(raw, Mapping):
1451
+ problems.append(f"{table} must be a table of lead = …, why = …")
1452
+ return None
1453
+ _reject_unknown(raw, _SCOPE_KEYS, f"{table}.", problems)
1454
+ numbers: dict[str, int] = {}
1455
+ for key in sorted(_SCOPE_KEYS):
1456
+ if key not in raw:
1457
+ continue
1458
+ value = raw[key]
1459
+ if not isinstance(value, int) or isinstance(value, bool) or value < 1:
1460
+ problems.append(f"{table}.{key} must be a positive integer")
1461
+ continue
1462
+ numbers[key] = value
1463
+ return Scope(**numbers)
1464
+
1465
+
1466
+ #: `[report]` — one key, and refused like every other. A table with room for a token or a
1467
+ #: URL is a table somebody puts a token in; the only thing declarable here is *where* a
1468
+ #: defect in this tool would be filed, and filing it is still a command a person types.
1469
+ _REPORT_KEYS = frozenset({"upstream"})
1470
+
1471
+ #: `owner/repo`, which is what `gh --repo` takes. Checked because the alternative to a
1472
+ #: shape here is a shape guessed by whatever the operator pipes the capture into.
1473
+ _UPSTREAM = re.compile(r"^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$")
1474
+
1475
+
1476
+ def _requirements(raw: object, problems: list[str]) -> tuple[str, ...]:
1477
+ """`[requirements] declared` — the vocabulary a `(needs: …)` group quotes from (RK1297).
1478
+
1479
+ Empty undeclared, which is what makes the axis opt-in and refusable at once: a project
1480
+ that never wrote this table refuses the first requirement an author types, and the
1481
+ refusal names the table instead of listing nothing. Nothing here is defaulted for the
1482
+ reason `[non_goals]` is not — a built-in vocabulary would be this tool deciding what a
1483
+ backlog's world contains, and `hardware` means nothing to a project that ships prose.
1484
+
1485
+ Every token is held to the shape the line can carry, and it is checked *here* rather
1486
+ than only at the write: a word with a comma in it splits into two on the way back out,
1487
+ so a vocabulary nothing could quote would be declared once and refuse every `add` after
1488
+ it, in a file the author is not looking at.
1489
+ """
1490
+ if raw is None:
1491
+ return ()
1492
+ if not isinstance(raw, Mapping):
1493
+ problems.append("requirements must be a table")
1494
+ return ()
1495
+ _reject_unknown(raw, _REQUIREMENTS_KEYS, "requirements.", problems)
1496
+ declared = tuple(
1497
+ dict.fromkeys(_string_list(raw.get("declared"), "requirements.declared", problems))
1498
+ )
1499
+ bad = [one for one in declared if not one or one.strip() != one or _UNQUOTABLE.search(one)]
1500
+ if bad:
1501
+ problems.append(
1502
+ f"requirements.declared names {', '.join(repr(one) for one in bad)}, which a "
1503
+ f"line cannot carry: the group closes at the first ')' and separates on ',', so "
1504
+ f"a requirement is one word with neither"
1505
+ )
1506
+ return tuple(one for one in declared if one not in bad)
1507
+
1508
+
1509
+ #: What a requirement may not contain, for the reason the deps group has the same rule: the
1510
+ #: `(needs: …)` slot closes at the first `)` and splits on `, `, so either inside a token is a
1511
+ #: line that stops parsing and no verb reaches again.
1512
+ _UNQUOTABLE = re.compile(r"[(),]")
1513
+
1514
+
1515
+ def _held(raw: object, problems: list[str]) -> int:
1516
+ """`[claims] held` — minutes, bounded at both ends (RK151).
1517
+
1518
+ The bound is the design and not a guard rail. Below a minute a claim expires before the
1519
+ worker has read the brief it came with; above :data:`CLAIM_HELD_MAX` an abandoned claim
1520
+ outlives the session that abandoned it, which is the lock this mechanism exists not to be.
1521
+ Between them the number is a judgement about this backlog, which is why it is declarable
1522
+ at all — and the refusal names the unit, because the one way to be badly wrong here is to
1523
+ write seconds in a key that reads minutes.
1524
+ """
1525
+ if raw is None:
1526
+ return CLAIM_HELD
1527
+ if not isinstance(raw, Mapping):
1528
+ problems.append("claims must be a table of held = <minutes>")
1529
+ return CLAIM_HELD
1530
+ _reject_unknown(raw, _CLAIMS_KEYS, "claims.", problems)
1531
+ value = raw.get("held")
1532
+ if value is None:
1533
+ return CLAIM_HELD
1534
+ if not isinstance(value, int) or isinstance(value, bool) or not 1 <= value <= CLAIM_HELD_MAX:
1535
+ problems.append(
1536
+ f"claims.held must be minutes, from 1 to {CLAIM_HELD_MAX}: a claim shorter than "
1537
+ f"that expires before the brief is read, and a longer one is the lock an expiry "
1538
+ f"exists not to be"
1539
+ )
1540
+ return CLAIM_HELD
1541
+ return value
1542
+
1543
+
1544
+ def _upstream(raw: object, problems: list[str]) -> str | None:
1545
+ if raw is None:
1546
+ return None
1547
+ if not isinstance(raw, Mapping):
1548
+ problems.append("report must be a table of upstream = 'owner/repo'")
1549
+ return None
1550
+ _reject_unknown(raw, _REPORT_KEYS, "report.", problems)
1551
+ value = raw.get("upstream")
1552
+ if value is None:
1553
+ return None
1554
+ if not isinstance(value, str) or not _UPSTREAM.match(value):
1555
+ problems.append("report.upstream must be 'owner/repo'")
1556
+ return None
1557
+ return value
1558
+
1559
+
1560
+ def _budgets(raw: object, base: Path, problems: list[str]) -> tuple[Budget, ...]:
1561
+ """`[budgets]` — a path to what it may cost. Refused, like every other key here."""
1562
+ if raw is None:
1563
+ return ()
1564
+ if not isinstance(raw, Mapping):
1565
+ problems.append("budgets must be a table of path = { lines = …, bytes = … }")
1566
+ return ()
1567
+ out: list[Budget] = []
1568
+ for name, value in raw.items():
1569
+ where = f"budgets.'{name}'"
1570
+ if not isinstance(value, Mapping):
1571
+ problems.append(f"{where} must be a table with 'lines' and/or 'bytes'")
1572
+ continue
1573
+ _reject_unknown(value, _BUDGET_KEYS, f"{where}.", problems)
1574
+ if Path(name).is_absolute():
1575
+ problems.append(
1576
+ f"{where} must be relative to the project root: an absolute path is "
1577
+ f"checked in and then wrong on every other machine"
1578
+ )
1579
+ continue
1580
+ if not _BUDGET_KEYS & set(value):
1581
+ # Declared *nothing*, which is a different mistake from declaring a number
1582
+ # this rejected: reporting both would send the reader to fix the wrong line.
1583
+ problems.append(
1584
+ f"{where} declares neither lines nor bytes: an entry that holds nobody "
1585
+ f"to anything reads as a budget and is the arrangement being replaced"
1586
+ )
1587
+ continue
1588
+ numbers = _positive(value, where, problems)
1589
+ if numbers:
1590
+ out.append(Budget(path=(base / name).resolve(), **numbers))
1591
+ return tuple(out)
1592
+
1593
+
1594
+ def _positions(source: Path | None) -> dict[tuple[str, str], int]:
1595
+ """Which line of the config each `table.key` is written on (RK1067).
1596
+
1597
+ Read off the text and never through the parse, for :func:`_declared_at`'s reason:
1598
+ `tomllib` keeps no positions, and a refusal that cited `roadkeep.toml:0` would be the
1599
+ one address in this tool that opens nothing. Coarse on purpose — the first assignment
1600
+ of a key under a header — because what a reader needs is the line to go and look at,
1601
+ and a second parser written to be exact about it is a second parser to keep right.
1602
+ """
1603
+ if source is None:
1604
+ return {}
1605
+ try:
1606
+ text = source.read_text(encoding="utf-8")
1607
+ except OSError:
1608
+ return {}
1609
+ found: dict[tuple[str, str], int] = {}
1610
+ table = ""
1611
+ for lineno, line in enumerate(text.splitlines(), start=1):
1612
+ stripped = line.strip()
1613
+ header = re.match(r"^\[([^\]]+)\]$", stripped)
1614
+ if header:
1615
+ table = header.group(1)
1616
+ continue
1617
+ key = re.match(r'^([A-Za-z_][A-Za-z0-9_]*|"[^"]+")\s*=', stripped)
1618
+ if key and (table, key.group(1)) not in found:
1619
+ found[(table, key.group(1))] = lineno
1620
+ return found
1621
+
1622
+
1623
+ def _origins(
1624
+ source: Path | None, declared: Mapping[str, object], role: str = ""
1625
+ ) -> tuple[tuple[str, str], ...]:
1626
+ """Where each limit this project set was declared, as the clause a refusal prints.
1627
+
1628
+ Only the keys the project actually wrote: a limit it never declared has no line, and
1629
+ :meth:`Schema.source_of` says *this tool's default* rather than inventing a citation —
1630
+ which of the two numbers a refusal is about being exactly the fact the author needs.
1631
+ """
1632
+ if source is None:
1633
+ return ()
1634
+ where = source.name
1635
+ table = f"limits.{role}" if role else "limits"
1636
+ at = _positions(source)
1637
+ out: list[tuple[str, str]] = []
1638
+ for key, attribute in _LIMIT_KEYS.items():
1639
+ # Either spelling, because the two callers hold different ones: the top-level table
1640
+ # arrives as it was written (`why`) and a role's arrives already translated to the
1641
+ # field it sets (`why_max`), and a citation that only knew one would silently drop
1642
+ # every per-role number — the ones RK50 exists for and the ones most worth citing.
1643
+ if key not in declared and attribute not in declared:
1644
+ continue
1645
+ lineno = at.get((table, key))
1646
+ address = f"{where}:{lineno}" if lineno else where
1647
+ out.append((attribute, f"{address} [{table}].{key}"))
1648
+ return tuple(out)
1649
+
1650
+
1651
+ def _grammars(raw: object, problems: list[str]) -> dict[str, Grammar]:
1652
+ """`[grammar.<role>]` — one role's shape, refused key by key like every other table.
1653
+
1654
+ Every name is checked against a closed set and never taken (RK1064): a `drop` naming a
1655
+ field this format does not have is a slot the author believes is gone, which is the
1656
+ same failure an unignored `symptom_max` typo is one layer down. The role itself is
1657
+ checked too — a grammar for a file `[files]` does not declare is a shape nothing reads.
1658
+ """
1659
+ if raw is None:
1660
+ return {}
1661
+ if not isinstance(raw, Mapping):
1662
+ problems.append("grammar must be a table of role = { extends = …, drop = […] }")
1663
+ return {}
1664
+ out: dict[str, Grammar] = {}
1665
+ for role, value in raw.items():
1666
+ where = f"grammar.{role}"
1667
+ if role not in ROLES:
1668
+ problems.append(f"{where} is not a role ({', '.join(ROLES)})")
1669
+ continue
1670
+ if not isinstance(value, Mapping):
1671
+ problems.append(f"{where} must be a table with {', '.join(sorted(_GRAMMAR_KEYS))}")
1672
+ continue
1673
+ _reject_unknown(value, _GRAMMAR_KEYS, f"{where}.", problems)
1674
+ extends = value.get("extends", "roadmap")
1675
+ if not isinstance(extends, str) or extends not in ROLES:
1676
+ problems.append(f"{where}.extends is not a role ({', '.join(ROLES)})")
1677
+ continue
1678
+ markers = _named(value.get("markers"), MARKER_NAMES, f"{where}.markers", problems)
1679
+ drop = _named(value.get("drop"), DROPPABLE, f"{where}.drop", problems)
1680
+ # The states a role carries are the tool's own and not a project's to declare, so
1681
+ # what a shipped grammar said stays said: a project reshapes the line under it.
1682
+ states = DEFAULT_GRAMMARS.get(role, Grammar()).states
1683
+ out[role] = Grammar(extends=extends, markers=markers, drop=drop, states=states)
1684
+ return out
1685
+
1686
+
1687
+ def _named(
1688
+ raw: object, allowed: Mapping[str, str], where: str, problems: list[str]
1689
+ ) -> tuple[str, ...]:
1690
+ """A list of names from a closed set, or a problem naming what the set holds."""
1691
+ if raw is None:
1692
+ return ()
1693
+ names = _string_list(raw, where, problems)
1694
+ unknown = [name for name in names if name not in allowed]
1695
+ if unknown:
1696
+ problems.append(
1697
+ f"{where} names {', '.join(unknown)}, which is not one of "
1698
+ f"{', '.join(sorted(allowed))}"
1699
+ )
1700
+ return ()
1701
+ return tuple(dict.fromkeys(names))
1702
+
1703
+
1704
+ def _read_budget(raw: object, problems: list[str]) -> int | None:
1705
+ """`[reads] brief` — what the one read that replaces reading the file may cost (RK1286).
1706
+
1707
+ Opt-in and refused like every other key here rather than defaulted, which is `[tools]`'
1708
+ rule and `[criteria]`'s: a ceiling this tool chose for somebody's answer would be a number
1709
+ nobody looked at, and a gate that reported on the first run is one that gets bypassed.
1710
+ """
1711
+ if raw is None:
1712
+ return None
1713
+ if not isinstance(raw, Mapping):
1714
+ problems.append("reads must be a table of brief = <characters>")
1715
+ return None
1716
+ _reject_unknown(raw, _READS_KEYS, "reads.", problems)
1717
+ value = raw.get("brief")
1718
+ if value is None:
1719
+ # `[tools]`' own refusal: a table that holds nobody to anything reads as a budget and
1720
+ # is exactly the arrangement being replaced.
1721
+ problems.append(
1722
+ "reads declares no brief: a table that holds nobody to anything reads as a "
1723
+ "budget and is the arrangement being replaced"
1724
+ )
1725
+ return None
1726
+ if not isinstance(value, int) or isinstance(value, bool) or value < 1:
1727
+ problems.append("reads.brief must be a positive integer")
1728
+ return None
1729
+ return value
1730
+
1731
+
1732
+ def _tool_budget(raw: object, problems: list[str]) -> tuple[int | None, int | None]:
1733
+ """`[tools]` — what one served tool may cost, and what the whole surface may (RK1059/1097).
1734
+
1735
+ Refused like every other key here rather than defaulted: a ceiling this tool chose for
1736
+ somebody's surface would be a number nobody looked at, which is the state RK464 named
1737
+ and declined to fix by guessing.
1738
+
1739
+ `session` is optional beside a declared `characters` and never instead of it. Per tool is
1740
+ the one that names an author — it is refused by whoever just edited that description —
1741
+ and it was right about *which* tool to blame and silent about the sum, which is how this
1742
+ repo reached 52 tools and 50,673 characters against a ceiling of 135,200 nobody chose.
1743
+ A total is the only rule that catches a list growing by verbs each of which is
1744
+ unremarkable, and it is offered rather than imposed for exactly RK1059's reason.
1745
+ """
1746
+ if raw is None:
1747
+ return None, None
1748
+ if not isinstance(raw, Mapping):
1749
+ problems.append("tools must be a table of { characters = … }")
1750
+ return None, None
1751
+ _reject_unknown(raw, _TOOLS_KEYS, "tools.", problems)
1752
+ if "characters" not in raw:
1753
+ # The same mistake `[budgets]` names: an entry that holds nobody to anything reads
1754
+ # as a budget and is exactly the arrangement being replaced. `session` alone does not
1755
+ # answer it: a surface under its total with one 30,000-character tool in it is the
1756
+ # state per-tool exists to refuse.
1757
+ problems.append(
1758
+ "tools declares no characters: a table that holds nobody to anything reads "
1759
+ "as a budget and is the arrangement being replaced"
1760
+ )
1761
+ return None, None
1762
+ numbers: dict[str, int | None] = {"characters": None, "session": None}
1763
+ for key in ("characters", "session"):
1764
+ if key not in raw:
1765
+ continue
1766
+ number = raw[key]
1767
+ if not isinstance(number, int) or isinstance(number, bool) or number < 1:
1768
+ problems.append(f"tools.{key} must be a positive integer")
1769
+ continue
1770
+ numbers[key] = number
1771
+ if numbers["characters"] is None:
1772
+ return None, None
1773
+ if numbers["session"] is not None and numbers["session"] < numbers["characters"]:
1774
+ # Not arithmetic pedantry: a total below what one tool may cost makes the per-tool
1775
+ # number unreachable, so one of the two was typed without reading the other.
1776
+ problems.append(
1777
+ f"tools.session is {numbers['session']} and tools.characters is "
1778
+ f"{numbers['characters']}: a surface may not cost less than one tool in it"
1779
+ )
1780
+ return numbers["characters"], None
1781
+ return numbers["characters"], numbers["session"]
1782
+
1783
+
1784
+ def _positive(
1785
+ value: Mapping[str, object], where: str, problems: list[str]
1786
+ ) -> dict[str, int]:
1787
+ """The budget's two numbers, each one a positive integer or a problem."""
1788
+ out: dict[str, int] = {}
1789
+ for key in sorted(_BUDGET_KEYS):
1790
+ if key not in value:
1791
+ continue
1792
+ number = value[key]
1793
+ if not isinstance(number, int) or isinstance(number, bool) or number < 1:
1794
+ problems.append(f"{where}.{key} must be a positive integer")
1795
+ continue
1796
+ out[key] = number
1797
+ return out
1798
+
1799
+
1800
+ def _paths(raw: object, base: Path, problems: list[str]) -> dict[str, Path]:
1801
+ if raw is None:
1802
+ return {role: base / rel for role, rel in DEFAULT_PATHS.items()}
1803
+ if not isinstance(raw, Mapping):
1804
+ problems.append("files must be a table of role = path")
1805
+ return {}
1806
+ _reject_unknown(raw, frozenset(ROLES), "files.", problems)
1807
+ out: dict[str, Path] = {}
1808
+ for role in ROLES:
1809
+ if role not in raw:
1810
+ continue
1811
+ value = raw[role]
1812
+ if not isinstance(value, str):
1813
+ problems.append(f"files.{role} must be a string path")
1814
+ continue
1815
+ candidate = Path(value)
1816
+ if candidate.is_absolute():
1817
+ problems.append(
1818
+ f"files.{role} must be relative to the project root: an absolute "
1819
+ f"path is checked in and then wrong on every other machine"
1820
+ )
1821
+ continue
1822
+ out[role] = (base / candidate).resolve()
1823
+ return out
1824
+
1825
+
1826
+ def _string_list(raw: object, where: str, problems: list[str]) -> list[str]:
1827
+ if raw is None:
1828
+ return []
1829
+ if not isinstance(raw, list) or not all(isinstance(item, str) for item in raw):
1830
+ problems.append(f"{where} must be a list of strings")
1831
+ return []
1832
+ return list(raw)