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
@@ -0,0 +1,453 @@
1
+ Metadata-Version: 2.4
2
+ Name: roadkeep
3
+ Version: 0.2.0
4
+ Summary: Owns the writes to a project's ROADMAP, CHANGELOG, IMPROVEMENTS and STRATEGY files, so the format is a schema at the point of insertion.
5
+ Author: Alexandre Oliveira
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/alegauss/roadkeep
8
+ Project-URL: Repository, https://github.com/alegauss/roadkeep
9
+ Project-URL: Issues, https://github.com/alegauss/roadkeep/issues
10
+ Project-URL: Changelog, https://github.com/alegauss/roadkeep/blob/main/docs/CHANGELOG.md
11
+ Keywords: roadmap,changelog,markdown,backlog,linter,pre-commit,agents,claude-code
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Documentation
21
+ Classifier: Topic :: Software Development :: Quality Assurance
22
+ Classifier: Topic :: Text Processing :: Markup :: Markdown
23
+ Requires-Python: >=3.11
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=8; extra == "dev"
28
+ Requires-Dist: pytest-xdist>=3; extra == "dev"
29
+ Dynamic: license-file
30
+
31
+ <p align="center">
32
+ <img src="https://raw.githubusercontent.com/alegauss/roadkeep/main/docs/assets/roadkeep-banner.png" alt="roadkeep — a schema at the point of insertion" width="840">
33
+ </p>
34
+
35
+ <!--
36
+ Assets in docs/assets/ — the mark is task lines cut at a gate, with the refused
37
+ remainder faded beyond it. The SVGs follow the reader's light/dark theme; a PNG
38
+ cannot, so each carries a fixed dark palette.
39
+
40
+ roadkeep-mark.svg 160x160 icon
41
+ roadkeep-logo.svg 520x160 mark + wordmark
42
+ roadkeep-banner.svg 1200x300 source for the header above
43
+ roadkeep-banner.png 1200x300 the header above. Raster and absolute because this
44
+ file is also the PyPI project page (RK19): a
45
+ relative path resolves against pypi.org and an SVG
46
+ is served as text/plain, so both render as broken.
47
+ roadkeep-social.svg 1280x640 source for the link preview
48
+ roadkeep-social.png 1280x640 upload at Settings > General > Social preview.
49
+ This is what renders when the repo URL is pasted
50
+ into LinkedIn, Slack or a link card anywhere else.
51
+ Re-render either PNG after editing its SVG:
52
+ msedge --headless=new --window-size=1200,300 \
53
+ --screenshot=docs/assets/roadkeep-banner.png \
54
+ file:///.../docs/assets/roadkeep-banner.svg
55
+ -->
56
+
57
+
58
+ **A CLI that owns the writes to your `ROADMAP.md`, `CHANGELOG.md`, `IMPROVEMENTS.md`
59
+ and `STRATEGY.md`, so the format is a schema at the point of insertion instead of a
60
+ convention an author is asked to remember.**
61
+
62
+ Shipped as a Claude Code plugin, because the author to constrain is usually an agent.
63
+
64
+ ---
65
+
66
+ ## The problem, measured
67
+
68
+ This did not start as an idea. It started as three readings from a real production
69
+ repository, where all three files declared a format and none enforced it:
70
+
71
+ | Artefact | Declared rule | Actual reading |
72
+ |---|---|---|
73
+ | `docs/ROADMAP.md` | one sentence per task | 92 lines, **142 words** average, worst **1406 characters** |
74
+ | `agents.md` | index only, loaded every turn | grew to **186 KB (~46k tokens)** |
75
+ | `docs/IMPROVEMENTS.md` | rationale for *unshipped* work | a sibling project's reached **539 KB** |
76
+
77
+ The finding that decided the design: **six of the eight worst lines were written in the
78
+ session that then diagnosed the problem.** This is not inattention. An author — human or
79
+ model — who has the whole design in working memory will write it where the reader is,
80
+ and an instruction to be terse does not survive the moment its author knows more than
81
+ the line allows.
82
+
83
+ ## Why a linter was the wrong answer
84
+
85
+ A linter reports *after* the prose exists. By then the tokens are spent, and the author
86
+ is being asked to delete work they just did. A field with `maxLength: 200` refuses at
87
+ the point of insertion, before a sentence is composed to fill it.
88
+
89
+ Same rule, two orders of magnitude cheaper — and it converts an analytical act (*"is
90
+ this too long, and what would I cut?"*) into a procedural one (*"call `add`"*).
91
+
92
+ > **The saving is the analysis, not the characters.**
93
+
94
+ ## What makes it different
95
+
96
+ The space around this is not empty, and the honest comparison is narrow:
97
+
98
+ | | What it does well | Why roadkeep is not it |
99
+ |---|---|---|
100
+ | **markdownlint** | structure and style of Markdown | explicitly not prose — it will not tell you a sentence is too long |
101
+ | **Vale** | prose rules, style guides | a linter: it reports after the text exists, which is the cost being avoided |
102
+ | **Backlog.md**, taskmd, and the markdown-task-for-agents family | mature task management, kanban, MCP | one `.md` **file per task**, with acceptance criteria and DoD — more room, and more room invites more prose |
103
+ | **ADR / MADR** | rationale that survives, superseded never deleted | an ADR set grows monotonically; that curve *is* the 539 KB above |
104
+
105
+ Four properties are the actual differentiator:
106
+
107
+ 1. **Enforced at the write path, not the review.** The refusal happens before the prose
108
+ exists. Everything else in this space reports afterwards.
109
+ 2. **It governs the file you already have.** One line in your existing `ROADMAP.md` —
110
+ not a new store you migrate into. A repository with a hand-written backlog is the
111
+ target, not the obstacle.
112
+ 3. **Round-trip or refuse.** Parse → render → byte-identical, or the tool declines to
113
+ write the file at all. A tool that owns writes to a hand-edited file has to prove it
114
+ cannot corrupt one.
115
+ 4. **Query instead of read.** Every question a maintainer asks the file is a command,
116
+ so answering it costs no context. Reading a backlog end-to-end to find one ready
117
+ task cost ~5k tokens in this very repository.
118
+
119
+ ## The six laws
120
+
121
+ A change that breaks one is wrong even if requested.
122
+ [docs/IMPROVEMENTS.md §0.3](https://github.com/alegauss/roadkeep/blob/main/docs/IMPROVEMENTS.md)
123
+ is authoritative.
124
+
125
+ | # | Law |
126
+ |---|---|
127
+ | L1 | The format is a schema, **enforced where the text is created**; `lint` is the backstop. |
128
+ | L2 | **The store is the repository** — Markdown, greppable, diffable. No database, no service. |
129
+ | L3 | **Round-trip or don't write** — parse → render → byte-identical. |
130
+ | L4 | **The tool never writes prose** — it validates and renders. |
131
+ | L5 | **Query instead of read** — every question is a command. |
132
+ | L6 | **Configuration, not convention** — prefix, paths, markers and limits are per project. |
133
+
134
+ L4 is the one people try to relax first. A generator that writes the `symptom` for you
135
+ would reintroduce exactly the drift this exists to stop.
136
+
137
+ ## Status
138
+
139
+ The table below is **not written by hand** — `roadkeep export --readme` derives it from
140
+ `docs/`, which is the point of RK39: a README that restates a backlog it cannot re-read is
141
+ stale from the first ship, and this one claimed "8 of 36" while four of the commands it
142
+ called unbuilt were already in the ledger.
143
+
144
+ <!-- roadkeep:begin -->
145
+ <!-- generated by `roadkeep export --readme`; edit the governed files instead -->
146
+
147
+ | Block | Open | Shipped | Retired |
148
+ | --- | --- | --- | --- |
149
+ | A — The model (a task is data before it is a line) | 0 | 43 | 2 |
150
+ | B — Authoring (insert, never hand-edit) | 0 | 217 | 2 |
151
+ | C — Query (consult without reading the file) | 0 | 140 | 2 |
152
+ | D — The gate | 1 | 199 | 2 |
153
+ | E — Adoption | 1 | 112 | 1 |
154
+ | F — The Claude Code plugin (the guardrail at the agent boundary) | 0 | 125 | 2 |
155
+ | G — The editor surface (the backlog where the file is open) | 0 | 13 | 0 |
156
+ | H — The tool's own shape (what one verb costs to change) | 0 | 35 | 1 |
157
+ | I — The documentation area (what an adopter reads before there is a session to ask) | 3 | 13 | 0 |
158
+ | **Total** | 5 | 897 | 12 |
159
+
160
+ **Next ready:**
161
+
162
+ - 📋 **RK1412** (deps: —) **The area's build runs on changes to site and docs, and every page it generates is read out of src** — A renamed verb or flag changes the reference and can break the build, and no job runs until somebody happens to touch the area itself. → §RK1412
163
+ <!-- roadkeep:end -->
164
+
165
+ Every command takes `--json`, which carries provenance — which file and line the answer
166
+ came from — because an answer an agent cannot audit gets verified by reading the file,
167
+ which is the cost the command existed to remove.
168
+
169
+ Open work, and where to look:
170
+ [docs/ROADMAP.md](https://github.com/alegauss/roadkeep/blob/main/docs/ROADMAP.md) — the count
171
+ and the next ready line are in the derived block above, so this sentence states neither. The
172
+ same file carries the **non-goals**, which is the half of it that binds: `brief` prints them
173
+ with every task, and they are what a proposal is checked against before it becomes a line.
174
+
175
+ Four projects are adopted and governed — this one, Shio, Turing and Dumont — each with its own
176
+ `roadkeep.toml` and the measurement that produced it. A fifth candidate was measured and
177
+ **retired** rather than adopted: its tasks are wrapped paragraphs with their deps on a line of
178
+ their own, and reading those is a second grammar rather than a configuration key. That refusal
179
+ is the one worth reading, because a tool that stretched to fit it would have stopped being
180
+ able to promise the round-trip.
181
+
182
+ ## Adopt it in a project — two commands, and the repository carries the rest
183
+
184
+ Nothing is installed and nothing is added to `PATH`. The plugin ships this package, so the
185
+ only thing the machine needs is a Python ≥3.11 interpreter — which is what runs the tool
186
+ either way. Run these in the project you want governed:
187
+
188
+ ```sh
189
+ claude plugin marketplace add alegauss/roadkeep --scope project
190
+ claude plugin install roadkeep@alegauss --scope project
191
+ ```
192
+
193
+ `--scope project` writes both declarations into that repository's `.claude/settings.json`:
194
+
195
+ ```jsonc
196
+ "extraKnownMarketplaces": { "alegauss": { "source": { "source": "github", "repo": "alegauss/roadkeep" } } },
197
+ "enabledPlugins": { "roadkeep@alegauss": true }
198
+ ```
199
+
200
+ Commit that file and **every clone is wired** — no per-machine step, no OS-specific path. What
201
+ arrives with it: the hook that denies a hand-edit and names the tool, the twelve MCP tools
202
+ whose input schema is *your* project's schema, the four `/roadkeep:*` commands, and the skill
203
+ that loads only when a governed file is in play (~300 tokens per session, all in).
204
+
205
+ Then declare the format once. `init` and `adopt` run before the project is governed, so they
206
+ are the one thing that wants a shell — the plugin's own copy answers, with no install:
207
+
208
+ ```sh
209
+ # the plugin's launcher, wherever the marketplace was cloned
210
+ R=~/.claude/plugins/marketplaces/alegauss/scripts/roadkeep.py
211
+
212
+ python $R adopt docs/ROADMAP.md --prefix SH # measures first: what would change, and where
213
+ python $R adopt docs/IMPROVEMENTS.md --sections --with docs/STRATEGY.md # the other half
214
+ python $R init # writes roadkeep.toml and the files it declares
215
+ ```
216
+
217
+ Both halves, because both are limits you have to declare. The backlog run reports the longest
218
+ `symptom`, `why` and rendered line; the `--sections` run reports the longest section in words
219
+ and the width your prose is already wrapped to — the numbers `[limits]` gets set from, taken
220
+ from your corpus rather than copied from this one. `--with` names the other prose files, and
221
+ is the one measure that is about a set: two outlines written apart both start at `I`, so the
222
+ address they share is a finding no per-file read can make and the first one `lint` would.
223
+
224
+ Everything a *task* needs afterwards is already in the tools the plugin installed: `add`,
225
+ `status`, `ship`, `retire`, `record_add`, `record_drop`, `section_add`, `section_drop`,
226
+ `brief`, `pick`, `list`,
227
+ `deps`, `lint`. No shell, no `PATH`, and the schema each of them validates against is the one
228
+ `roadkeep.toml` just declared.
229
+
230
+ **[Viglet Shio](https://github.com/openviglet/shio) is the reference adoption**: 80 task
231
+ lines, a 618 KB ledger of 233 entries written years before this tool, and a `roadkeep.toml`
232
+ that declares exactly what that history is — `[ledger]` for the two slots its lines never
233
+ carried, `[limits.changelog]` for a file whose median line is 1038 characters, and
234
+ `[rules.changelog]` for the two prose rules history cannot obey.
235
+
236
+ ### Or from a checkout beside it
237
+
238
+ A project adopting an *unreleased* version runs a sibling checkout rather than the published
239
+ plugin — and then the hook, the tools and the skill arrive with nothing, because those ship
240
+ with the plugin. `install` writes them itself, translated from the files the plugin carries,
241
+ with the launcher's path as the only substituted fact:
242
+
243
+ ```sh
244
+ python ../roadkeep/scripts/roadkeep.py -C . install
245
+ python ../roadkeep/scripts/roadkeep.py -C . install --check # in CI: still in step?
246
+ ```
247
+
248
+ `.mcp.json`, the guard on its three hook events in `.claude/settings.json`, a verbatim
249
+ `.claude/skills/roadkeep/SKILL.md`, and — only where the repository already has workflows — a
250
+ job calling the action above. The skill is **refreshed on every run** and `--check` exits 1
251
+ once it drifts, which is what a vendored copy otherwise has nothing to keep it in step with.
252
+ Declarations are merged, so what another tool wrote in either file survives; the workflow is
253
+ written once and tuned by you thereafter. The fifth surface is named and not written: the line
254
+ in `CONTRIBUTING.md` is prose about your project, and this tool writes none (L4).
255
+
256
+ ### On Claude Code on the web, the plugin is not there
257
+
258
+ [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web) has no
259
+ `/plugin` command and never installs a marketplace plugin — a cloud session reads only what the
260
+ repository commits (`.claude/settings.json`, `.mcp.json`, `.claude/skills/`) and a setup script.
261
+ So the two commands at the top of this section wire **nothing** there: the hook, the server and
262
+ the skill all ride with a plugin the environment does not install, and an agent with no guard
263
+ falls back to hand-editing the governed files — the one drift this tool exists to refuse, now
264
+ in the one place it cannot see itself doing it (*"No roadkeep plugin/hooks → I'll track via git
265
+ log"* is the tell).
266
+
267
+ The fix is the checkout path made portable: commit a small launcher and point the hook and the
268
+ server at it instead of at `${CLAUDE_PLUGIN_ROOT}`. It resolves an engine at run time —
269
+ `$ROADKEEP_HOME`, an installed plugin, a sibling `../roadkeep`, a cached clone, or a fresh
270
+ `git clone` — and runs the same `guard` and `mcp` entry points the plugin would, so **one
271
+ wiring holds on a laptop and in the cloud**:
272
+
273
+ ```jsonc
274
+ // .claude/settings.json — the guard on its three events, launcher instead of the plugin root
275
+ "hooks": { "PreToolUse": [{ "matcher": "Edit|MultiEdit|NotebookEdit|Write|Bash",
276
+ "hooks": [{ "type": "command",
277
+ "command": "python \"${CLAUDE_PROJECT_DIR}/.claude/hooks/roadkeep-launch.py\" guard" }] }] }
278
+ // .mcp.json — the same launcher, `mcp` mode, gives `mcp__roadkeep__*` where the plugin cannot
279
+ "mcpServers": { "roadkeep": { "command": "python",
280
+ "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/roadkeep-launch.py", "mcp"] } }
281
+ ```
282
+
283
+ Two rules keep the committed launcher from ever making a machine worse than the plugin did, and
284
+ both are the **guard's**: it **defers to the plugin** when one is installed, so no deny message
285
+ doubles on the laptop that already has it, and it **no-ops on exit 0** when no engine is found,
286
+ so a repository without roadkeep is never blocked by a hook that cannot answer. The `mcp` mode
287
+ keeps neither — a stdio server cannot stand down, since the exit that would say so is what the
288
+ harness reads as a crash.
289
+ [Viglet Shio](https://github.com/openviglet/shio) carries the reference copy at
290
+ [`.claude/hooks/roadkeep-launch.py`](https://github.com/openviglet/shio/blob/main/.claude/hooks/roadkeep-launch.py).
291
+
292
+ ### Or just the CLI
293
+
294
+ ```sh
295
+ # Not on PyPI yet, so the name resolves by URL until the first release is cut
296
+ uvx --from git+https://github.com/alegauss/roadkeep roadkeep lint # no install, no checkout
297
+ pip install git+https://github.com/alegauss/roadkeep
298
+
299
+ # What those two become the moment `publish.yml` runs with target=pypi
300
+ uvx roadkeep lint
301
+ pip install roadkeep
302
+ ```
303
+
304
+ Python ≥3.11, **zero runtime dependencies** — `argparse` and `tomllib`, not `click` and
305
+ `pydantic`. A tool meant to run in someone else's CI pays for every dependency it takes,
306
+ and that is also what makes the `uvx` line above viable: there is nothing to resolve.
307
+
308
+ ## Run it as a gate
309
+
310
+ `roadkeep lint` exits **1** on a file that drifted and **0** on one that did not — that exit
311
+ code is the whole contract, so every surface calls the same command rather than a copy of it.
312
+ A gate that runs in only one place is a gate with a documented bypass.
313
+
314
+ ```yaml
315
+ # .github/workflows/gate.yml — the action this repository ships
316
+ steps:
317
+ - uses: actions/checkout@v4
318
+ - uses: alegauss/roadkeep@main # with: {directory: .}
319
+
320
+ # .pre-commit-config.yaml — the same command, one step earlier
321
+ repos:
322
+ - repo: https://github.com/alegauss/roadkeep
323
+ rev: main # no tag is cut yet; a version pin once one is
324
+ hooks:
325
+ - id: roadkeep-lint # or roadkeep-lint-fix, which normalizes first
326
+ ```
327
+
328
+ `--fix` repairs only what the format *derives* — the dep annotation, the pointer, dep order,
329
+ an invisible codepoint, whitespace around a field, a queue entry whose task has left, a
330
+ criteria heading addressed to nothing — and
331
+ leaves every editorial finding to a human, which is what keeps a first run on a real backlog
332
+ down to a report somebody reads.
333
+
334
+ Every finding **names the command that closes it**, and `roadkeep repair` runs the ones that
335
+ need no decision — the mechanical pass, then each complete argv, re-reading the report between
336
+ writes because a repair moves the line numbers after it. That matters most for the caller this
337
+ ships for: the guard denies an agent the hand edit, so a report whose remedy lived in English
338
+ cost a turn per finding to act on. What still needs a sentence you have to write, or a choice
339
+ between two doors, is printed with both and never guessed at — the tool does not write prose.
340
+ `repair --dry-run` prints the commands and runs none of them, and `roadkeep explain <code>`
341
+ answers what a code *means* — the class, what produces it, and its doors — which is the one
342
+ question the report could never answer, since a finding is about a line and a code is about a
343
+ kind. With no argument it lists them all, which is a vocabulary this tool had never published.
344
+
345
+ Two things it reports **without** failing, because refusing them would fail an honest file
346
+ and a gate that gets bypassed is worth nothing: what a `Block X` dep expands to (one token
347
+ named 41 open tasks in the backlog measured above), and — with `--since HEAD`, which the
348
+ pre-commit hook passes — a rationale section edited while the line carrying its status was
349
+ not. The line is the only thing `pick` reads and the section is deleted on ship, so a
350
+ requirement written only into the reasoning cannot be picked, shipped, or kept.
351
+
352
+ The gate also holds the files nobody edits on purpose. An instruction file loaded on every
353
+ turn spends the resource this tool exists to protect, and `agents.md` reached **186 KB** in
354
+ the project measured above while declaring a 150-line rule at the bottom of itself — so the
355
+ budget moves out of its prose and into the configuration, in both units a reader pays:
356
+
357
+ ```toml
358
+ [budgets]
359
+ "agents.md" = { lines = 125, bytes = 8400 } # this repository's own, held by `lint`
360
+ ```
361
+
362
+ ## Run it as a Claude Code plugin
363
+
364
+ The store is Markdown (L2), so an agent can bypass the entire format with one `Edit` — and
365
+ will, because `Edit` is cheaper than reading a `--help`. A gate at the commit catches that a
366
+ whole turn of prose too late: the tokens are already spent, and the report asks for a
367
+ deletion. So the plugin installs the one enforcement point an agent cannot route around.
368
+
369
+ ```jsonc
370
+ // hooks/hooks.json, shipped in this repository — `roadkeep guard` answers both events
371
+ "PreToolUse": [{ "matcher": "Edit|MultiEdit|NotebookEdit|Write", … }] // deny, and say what to call
372
+ "Stop": [{ … }] // `lint`, before the turn ends
373
+ ```
374
+
375
+ A write to a file some project's `roadkeep.toml` declares is **denied with the command that
376
+ does it properly**, flags included — a refusal that names no alternative is one an agent
377
+ routes around, and one that names the command makes the denial the cheapest path forward:
378
+
379
+ ```
380
+ Edit refused: docs/ROADMAP.md is this project's roadmap, and roadkeep owns its writes.
381
+ …
382
+ Call instead, from the project root:
383
+ roadkeep add --block <x> --symptom "…" --why "…" a new task line, fields refused at input
384
+ roadkeep status <id> <marker> a marker, and only in this file
385
+ roadkeep ship <id> shipped: ledger entry, line gone, section dropped
386
+ ```
387
+
388
+ Three properties are load-bearing, and each is a test rather than an intention. The config is
389
+ discovered **from the file** and not from the working directory, so one hook process answers
390
+ correctly for every repository a session touches. **Silence is the allow** — `deny` is the only
391
+ decision it ever returns, because `allow` in this protocol *grants* the write and would wave
392
+ through the permission rules you set for every file the tool has no opinion about. And **every
393
+ failure allows**: a broken `roadkeep.toml`, a payload that is not JSON, a tool input with no
394
+ path. A guard that denies on its own errors turns one typo into a repository nobody can edit,
395
+ and the gate is still there at the commit.
396
+
397
+ `Bash` is deliberately not matched: `sed -i` on the roadmap is a real bypass, and matching every
398
+ shell command to catch it taxes every command in the session. The `Stop` hook runs `lint`
399
+ instead — so the bypass is caught before the turn ends, by the agent that can still fix it.
400
+
401
+ The denial is one surface of four; the other three are what make calling the command cheaper
402
+ than typing it. The plugin ships an **MCP server** — `roadkeep mcp`, JSON-RPC on stdio, no
403
+ port and no state — exposing `add`, `ship`, `pick` and `lint` as tools whose input schema is
404
+ *derived*: `maxLength` is this project's `symptom` and `why` limits, `enum` is its declared
405
+ markers, `pattern` is its id shape, and the description is the subcommand's own help. So a
406
+ misspelt `--deps` is refused by the protocol with the arguments that exist, instead of costing
407
+ a round trip to a usage string, and every call is dispatched through the same parser a
408
+ terminal uses — one engine, one refusal.
409
+
410
+ The same four are **slash commands** — `/roadkeep:add`, `/roadkeep:ship`, `/roadkeep:pick`,
411
+ `/roadkeep:lint` — for the person driving the standard, who reads `/help` and not a JSON
412
+ Schema. `/roadkeep:add F | what does not work | one sentence.` passes those words *verbatim*:
413
+ the command files are written so that every instruction about the user's text is a
414
+ prohibition, because a prompt that said "write a concise symptom" would have moved the prose
415
+ generation one file to the left while keeping L4's letter. That is asserted, not intended —
416
+ `tests/test_commands.py` refuses the phrasing.
417
+
418
+ The fourth is a **skill**, `skills/roadkeep/SKILL.md`, holding which command to call, what it
419
+ derives, the two rules a schema cannot check, and how work is picked. It is a skill and not a
420
+ paragraph in the
421
+ project's instruction file because instructions are loaded on *every* turn, including the ones
422
+ that touch no roadmap — the budget above exists because that is how the 186 KB happened. The
423
+ skill is read when a governed file is in play and costs nothing otherwise, and it ships with
424
+ the plugin, so the standard is the same text in every project rather than a copy per repo.
425
+
426
+ All four install with the two commands at the top of this file, and both surfaces the harness
427
+ starts run `python "${CLAUDE_PLUGIN_ROOT}/scripts/roadkeep.py"` — the package the plugin
428
+ already copied. There is no console script to install and no `PATH` entry to add, because a
429
+ plugin that installs cleanly and then starts nothing is the failure that taught this (RK57).
430
+
431
+ One more property makes the gate usable on a repository that adopts the tool late: the `Stop`
432
+ hook judges **only the lines the working tree changed**. Shio joined with 278 findings in it,
433
+ and a gate that blocked the end of every turn over somebody else's history is a gate that gets
434
+ switched off — so `lint`, the pre-commit hook and the Action still judge every line, and the
435
+ hook answers the narrower question it was installed to answer (RK60).
436
+
437
+ ## Non-goals
438
+
439
+ These are binding, and half the point. Check before proposing work:
440
+
441
+ - **No web UI and no server.** Files and a CLI — the MCP server above is one stdio process
442
+ speaking JSON-RPC to the CLI, which binds nothing and stores nothing.
443
+ - **No issue-tracker sync.** A backlog that lives in a service is one an agent cannot `grep`.
444
+ - **No model and no prompts inside the tool.** It validates and renders; it never writes
445
+ the symptom or the rationale.
446
+ - **No dates, quarters or estimates.** A marker is maturity, not a schedule.
447
+
448
+ ## This repository is the conformance fixture
449
+
450
+ `roadkeep lint` must pass on `docs/` here. The format is proven by the artefact rather
451
+ than asserted in a README — including this one. A limit that cannot express these lines
452
+ is the wrong limit, not a set of wrong lines, and the test suite asserts it against
453
+ `docs/ROADMAP.md` under this repository's own `roadkeep.toml`.
@@ -0,0 +1,67 @@
1
+ roadkeep/__init__.py,sha256=3HjJn3SG8W01VdXGxstBPJVz7rvoGT6IgkJfCDChNnI,3603
2
+ roadkeep/adopting.py,sha256=49NuVsM5pnvsd5wqrt_t__DoiNOaF5GSuUxU2HCL4Jg,122934
3
+ roadkeep/attesting.py,sha256=KNmBt_zEeTgzU5hZZkr2LpxnZhNwZsAIZ3GKrrFqVqo,13950
4
+ roadkeep/authoring.py,sha256=652P_YwUferZZbpfXT3KVVfYFvtX2hoA5XKc7SV0xXo,110464
5
+ roadkeep/backlog.py,sha256=TLdIJ4ocy1l6O1Smt3CfNyT0cZJTICvKGnev3Nsshp8,37909
6
+ roadkeep/blocking.py,sha256=x6iwSUQmxS2s_MG1Qbe8beCJnMLgNryMgQ3xKBLl_Z4,77954
7
+ roadkeep/briefing.py,sha256=fShdjQrVThVkRcZC2b5uul6qckwZ7OVN20O2-iU8Jak,53892
8
+ roadkeep/budgeting.py,sha256=E08Dl0gWsGRz36D5t_5KC8XD4QPkXQ1oYzCDpRKy0c8,109994
9
+ roadkeep/capturing.py,sha256=yXExbL9RVCvnQQDgQAyS1siGvHUXogJrc4IDQng2gcw,83860
10
+ roadkeep/claiming.py,sha256=_ki361Y83ECeqP_qySCX0ciF5H1x8gE1w8FFXTTtZ8E,51327
11
+ roadkeep/cli.py,sha256=41KI0bQx_YJ6lQftJ3Ma7qES1MUttkHrH6dmkgYvba4,32226
12
+ roadkeep/commanding.py,sha256=3dGjVUpjLvrkxkRXO-66fDQ_EldUZwKYfvF8z5_nGeE,22919
13
+ roadkeep/config.py,sha256=LH5PllJ_aokSCP-ecGbyyOJZ7Y6am4a0yidpYv3WGdE,92865
14
+ roadkeep/counting.py,sha256=vThMf2iv4iTmwG3kB8IQetiTf6svrs2gJtGNRyEjESE,17176
15
+ roadkeep/criteria.py,sha256=389laLohCLOS6242PL5tcmkDM8BSt2qmu549Bh22gYs,41508
16
+ roadkeep/deferring.py,sha256=4AJWChyjBkkRIyIrfyNHwVDLRfSTJo5lzw_46dPmwQQ,33984
17
+ roadkeep/describing.py,sha256=JUhZz466ee0vrFu83bgrfDA0DEi0fPEEO8V3tUJK8XY,27376
18
+ roadkeep/exporting.py,sha256=6ALcX3iwnlrOvnm25u9ufwuG20jtMqOET6IdTZj3fYM,36320
19
+ roadkeep/fixing.py,sha256=ma6E0ohK4t8k3bWOk8PeoXjskQT46mtGovT2Isj1p-I,29970
20
+ roadkeep/governing.py,sha256=HrnBoAfry2hnykXhJvjD9_mWZuEnx1anuYr91qNahxA,44537
21
+ roadkeep/graph.py,sha256=IBasokDOWnhl2_mSP3ivnHWnciy6Er6M-xZJeLyF3uA,16502
22
+ roadkeep/guarding.py,sha256=WSxKpDFXsVjlg3ZCn2DgpDZ-8aGIl55NmboPpUhgxRY,58193
23
+ roadkeep/history.py,sha256=KaL2VA4OGBy4XCS-uYlDppCRl3UYrrmqC3EwVhlyL2M,115367
24
+ roadkeep/ids.py,sha256=rRHC0URyd0qLIjdtZ_kB1-qAL3PPiQNjxD09YgSzY5U,13148
25
+ roadkeep/installing.py,sha256=zn3CbVNm1kJW1ueXg0B_czB7vPfyg_BOVh82VeAzo80,106841
26
+ roadkeep/linting.py,sha256=j2R1MTm1t-oN0k3sNguaAgonLUrTvRbGzr46K4CS8xw,219722
27
+ roadkeep/locking.py,sha256=ersR5tYDIX90So9nQk7FholpqgBrnHgMGW2Wyf2o_xU,9380
28
+ roadkeep/markers.py,sha256=dXmD12_dNVTyf0dAYI02ZyuxYJU8WsNV_tOxiQI4KI0,10025
29
+ roadkeep/merging.py,sha256=mngENw1OYW3pMV8wne1SPxHlVhsZNJoB5RTK6E1dStY,55923
30
+ roadkeep/picking.py,sha256=A5Lg4v32Cqj5Enf7VG9XJV5BO-nwrt_bQS1RBqCrMGM,36788
31
+ roadkeep/provenance.py,sha256=vz0sN_hJt5EiQu1CQ3FQS8A7svIbBRl4IW_NqwtrZpo,41567
32
+ roadkeep/queueing.py,sha256=D_duEdt1uktGBBrfPYNISR6Eb2aiAw2cTaiBNyS8TJs,33529
33
+ roadkeep/ranking.py,sha256=FLIQGtEx26VrbWTp37KwLguA2aVkEFFoSOpJAKRKcMU,8092
34
+ roadkeep/referring.py,sha256=VYhPl1fc3BKsj22WqV6tw9YXzqYTcH43MXqqXbZTrek,12277
35
+ roadkeep/remaining.py,sha256=ctZyygCzEmzT_QPZ-8ALyQ_EJJHNTZJmRznd_ciSD78,15881
36
+ roadkeep/remedying.py,sha256=3KULd-njF811BIWDbN3aYBsi2NsTTfHHbjlvDf1PoQg,106903
37
+ roadkeep/rendering.py,sha256=jZkuS0YFGMjQc4gNVwJMP7TOfK4hRR70JwePGcUMVxs,85920
38
+ roadkeep/renumbering.py,sha256=7nwPad5E41iT3-a8uR16e8Bo6UQxsyogaqlvu-QM_Hc,24536
39
+ roadkeep/repairing.py,sha256=ViPs3U9oXi4pmsri0pfSgCxhBLc99ErAoOZWaDJ7jNU,12599
40
+ roadkeep/reverting.py,sha256=D3JbUIKyWePgDqIzwltJO7-IAauPrDSRkskqgL6Ihac,6057
41
+ roadkeep/scoping.py,sha256=sMNLdkwz0i9IzMqdNmTKRhiIGKWKbbc0VIhStRhiaNQ,30887
42
+ roadkeep/screening.py,sha256=9ZKq-ID0Zk3aA3S_ywLKrCBOouWH1-5XJwL8AQZ2qxs,9095
43
+ roadkeep/sections.py,sha256=PWB2X4qj449c_FXGwdq7YX6KVQm4oKVZkY-NxWTB-3E,210626
44
+ roadkeep/serving.py,sha256=QXtLPiIl9nepxNc9GoPwTQ1-vEdjBXsAcbNZGaC7TqI,167946
45
+ roadkeep/shipping.py,sha256=Z44HFAy4pj5xeI4KK1QqQ4qQUU1FVueIkLdNW77Dv0o,203553
46
+ roadkeep/showing.py,sha256=vJris0sMzQFt_03ZE-b2qJVHRiKzTb4dv6ydw5Qdoxk,32368
47
+ roadkeep/storing.py,sha256=cdBP7l5zp8gVsjQJY8rf7oXsvvUizh-zSa2CRkt07VA,10229
48
+ roadkeep/weighing.py,sha256=dKW7a6ZnX-_-sffCecQMJEtwKHzD9sM7zOx7bQOTHnQ,17523
49
+ roadkeep/kernel/__init__.py,sha256=YlmpZeuG6ToDmseiH_N2rwbFrJNF5tnn_OGTzigTQf0,1595
50
+ roadkeep/kernel/document.py,sha256=toEo6IaDM-er1DibCHC-uG9iwpm88Er_6K5njn4kz7g,86793
51
+ roadkeep/kernel/schema.py,sha256=mUDVklvW20-72SLk0slZEJF0CZ-sFISk3uW7daDU9P0,121502
52
+ roadkeep/verbs/__init__.py,sha256=xNGl9xtUNHL41nWKjuoK36hDgBGnjV35rPvvAtyZAOM,1712
53
+ roadkeep/verbs/adopting.py,sha256=QEWGYv6hSJBdb9ZzKPrd93QcIzmAKiCfaMkP09ZSzwA,46394
54
+ roadkeep/verbs/authoring.py,sha256=D1bJ4hBPc54V6EKRRSDks3c2l1OZtoQy3D3PznpPGCE,24268
55
+ roadkeep/verbs/declaring.py,sha256=_tc6Mtj3x-NVXWEgSF9U3BlsPgdGYQzRleZKoQmJjPA,18834
56
+ roadkeep/verbs/linting.py,sha256=U0s9wCutEtxhJo7Q4rE5K88SEz_j7xjLQWjHT7cfq9o,32237
57
+ roadkeep/verbs/querying.py,sha256=uu1TMZnEsOyDB0tJmKXXprFgt2mJSUXZva646DAilmo,101072
58
+ roadkeep/verbs/reading.py,sha256=HeVERLNCpDG_NRQkoCLOTecWqi7cem-4qYlCcRQhaP4,16344
59
+ roadkeep/verbs/refusing.py,sha256=aOUPehNWT8m59AwU2rTBtha4RQW2UVQBXhAOmKGo1_M,8106
60
+ roadkeep/verbs/sections.py,sha256=tdewHM1B7AV_bp83qj-b7EdopwShlsi3qMVo7-ngovg,63389
61
+ roadkeep/verbs/shipping.py,sha256=P_x95gOsoEAozbME-V4HV8DvlSyAnKx4gqCpUZOym1A,38385
62
+ roadkeep-0.2.0.dist-info/licenses/LICENSE,sha256=_T_vdD4jljVOPNNboOKq83RvZ4FwlsdD9unXfGcDHZU,11349
63
+ roadkeep-0.2.0.dist-info/METADATA,sha256=zLNEGq-V04fB8rQ5b3nHITNF8Gl7NwzZPzK-tyrmocU,25968
64
+ roadkeep-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
65
+ roadkeep-0.2.0.dist-info/entry_points.txt,sha256=f8RbWpDRu5Tu_4NoDnE2PA7D2qgi7plB1_3O2IvEQI4,47
66
+ roadkeep-0.2.0.dist-info/top_level.txt,sha256=s3CHayuQl5DQtEz8y_BE4WjpKD3c9OTIy6PPTQ3bMZ0,9
67
+ roadkeep-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ roadkeep = roadkeep.cli:main