roadkeep 0.2.0__tar.gz → 0.2.535__tar.gz
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.
- roadkeep-0.2.535/PKG-INFO +296 -0
- roadkeep-0.2.535/README.md +266 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/__init__.py +1 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/adopting.py +719 -59
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/authoring.py +535 -85
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/backlog.py +105 -10
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/blocking.py +165 -21
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/briefing.py +407 -43
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/budgeting.py +1137 -19
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/capturing.py +67 -20
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/claiming.py +55 -18
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/cli.py +349 -38
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/config.py +953 -50
- roadkeep-0.2.535/plugin/src/roadkeep/counting.py +839 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/criteria.py +22 -12
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/deferring.py +179 -17
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/describing.py +142 -9
- roadkeep-0.2.535/plugin/src/roadkeep/dismissing.py +593 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/exporting.py +1 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/fixing.py +50 -7
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/governing.py +356 -19
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/guarding.py +270 -32
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/history.py +756 -71
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/ids.py +7 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/installing.py +1395 -65
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/kernel/document.py +36 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/kernel/schema.py +332 -8
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/linting.py +948 -32
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/picking.py +190 -15
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/provenance.py +325 -4
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/queueing.py +14 -7
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/ranking.py +91 -12
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/referring.py +22 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/remaining.py +161 -7
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/remedying.py +518 -28
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/rendering.py +516 -3
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/renumbering.py +3 -3
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/reverting.py +9 -9
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/scoping.py +167 -12
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/sections.py +273 -49
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/serving.py +622 -43
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/shipping.py +971 -111
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/showing.py +386 -19
- roadkeep-0.2.535/plugin/src/roadkeep/validating.py +680 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/verbs/adopting.py +307 -64
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/verbs/authoring.py +271 -66
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/verbs/declaring.py +126 -9
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/verbs/linting.py +64 -38
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/verbs/querying.py +888 -254
- roadkeep-0.2.535/plugin/src/roadkeep/verbs/refusing.py +429 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/verbs/sections.py +217 -238
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/verbs/shipping.py +342 -90
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/weighing.py +150 -2
- roadkeep-0.2.535/plugin/src/roadkeep.egg-info/PKG-INFO +296 -0
- roadkeep-0.2.535/plugin/src/roadkeep.egg-info/SOURCES.txt +177 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/pyproject.toml +2 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_adopting.py +447 -19
- roadkeep-0.2.535/tests/test_advisories.py +457 -0
- roadkeep-0.2.535/tests/test_answers.py +855 -0
- roadkeep-0.2.535/tests/test_area.py +297 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_asking.py +19 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_authoring.py +304 -4
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_backlog.py +36 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_backstop.py +77 -3
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_blocking.py +276 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_briefing.py +267 -6
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_budgeted.py +1 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_budgeting.py +1573 -4
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_caches.py +1 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_capturing.py +195 -18
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_carrying.py +25 -5
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_checkout.py +2 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_claiming.py +118 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_commanding.py +63 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_commands.py +30 -2
- roadkeep-0.2.535/tests/test_composed.py +151 -0
- roadkeep-0.2.535/tests/test_composing.py +2317 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_config.py +397 -1
- roadkeep-0.2.535/tests/test_configured.py +565 -0
- roadkeep-0.2.535/tests/test_contents.py +123 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_corpora.py +168 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_counting.py +397 -3
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_criteria.py +330 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_cycles.py +19 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_deferring.py +288 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_describing.py +54 -1
- roadkeep-0.2.535/tests/test_dismissing.py +456 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_document.py +80 -10
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_doors.py +9 -4
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_doors_in_both_registers.py +5 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_editor.py +119 -22
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_encoding.py +119 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_events.py +51 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_exporting.py +13 -6
- roadkeep-0.2.535/tests/test_figures.py +191 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_findings.py +19 -14
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_fixing.py +31 -3
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_governing.py +451 -8
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_guarding.py +135 -8
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_history.py +660 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_importing.py +258 -0
- roadkeep-0.2.535/tests/test_installing.py +3637 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_invariants.py +281 -12
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_kernel.py +8 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_launching.py +311 -13
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_linting.py +547 -9
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_merging.py +7 -3
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_model_page.py +2 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_namespaces.py +12 -4
- roadkeep-0.2.535/tests/test_naming.py +185 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_owned.py +2 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_packaging.py +148 -23
- roadkeep-0.2.535/tests/test_pairs.py +907 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_payloads.py +357 -26
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_picking.py +329 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_plugin.py +46 -26
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_prevention.py +81 -3
- roadkeep-0.2.535/tests/test_priced.py +77 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_provenance.py +75 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_queueing.py +59 -0
- roadkeep-0.2.535/tests/test_quoting.py +84 -0
- roadkeep-0.2.535/tests/test_ranking.py +915 -0
- roadkeep-0.2.535/tests/test_reading.py +195 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_recording.py +119 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_reference.py +30 -12
- roadkeep-0.2.535/tests/test_registers.py +292 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_remaining.py +107 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_remedying.py +348 -8
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_renumbering.py +3 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_repairing.py +59 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_replaying.py +7 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_retiring.py +158 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_reverting.py +4 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_schema.py +130 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_scoping.py +628 -1
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_screening.py +2 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_sections.py +164 -9
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_serving.py +591 -22
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_session_page.py +2 -2
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_shipping.py +629 -3
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_showing.py +335 -6
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_skill.py +188 -17
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_spelling.py +9 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_status.py +33 -4
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_surfaces.py +236 -17
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_turning.py +7 -6
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_twins.py +8 -8
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_unpaired.py +4 -4
- roadkeep-0.2.535/tests/test_validating.py +496 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_walkthrough.py +15 -4
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_weighing.py +240 -2
- roadkeep-0.2.0/PKG-INFO +0 -453
- roadkeep-0.2.0/README.md +0 -423
- roadkeep-0.2.0/src/roadkeep/counting.py +0 -376
- roadkeep-0.2.0/src/roadkeep/verbs/refusing.py +0 -146
- roadkeep-0.2.0/src/roadkeep.egg-info/PKG-INFO +0 -453
- roadkeep-0.2.0/src/roadkeep.egg-info/SOURCES.txt +0 -164
- roadkeep-0.2.0/tests/test_answers.py +0 -342
- roadkeep-0.2.0/tests/test_area.py +0 -212
- roadkeep-0.2.0/tests/test_composing.py +0 -387
- roadkeep-0.2.0/tests/test_configured.py +0 -145
- roadkeep-0.2.0/tests/test_installing.py +0 -1881
- roadkeep-0.2.0/tests/test_pairs.py +0 -304
- roadkeep-0.2.0/tests/test_ranking.py +0 -323
- {roadkeep-0.2.0 → roadkeep-0.2.535}/LICENSE +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/attesting.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/commanding.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/graph.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/kernel/__init__.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/locking.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/markers.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/merging.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/repairing.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/screening.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/storing.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/verbs/__init__.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep/verbs/reading.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep.egg-info/dependency_links.txt +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep.egg-info/entry_points.txt +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep.egg-info/requires.txt +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535/plugin}/src/roadkeep.egg-info/top_level.txt +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/setup.cfg +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_attesting.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_baseline.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_graph.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_hinting.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_ids.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_locking.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_markers.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_referring.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_shadowing.py +0 -0
- {roadkeep-0.2.0 → roadkeep-0.2.535}/tests/test_storing.py +0 -0
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: roadkeep
|
|
3
|
+
Version: 0.2.535
|
|
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
|
+
<!--
|
|
32
|
+
Assets in site/public/assets/ — the mark is task lines cut at a gate, with the refused
|
|
33
|
+
remainder faded beyond it. The SVGs follow the reader's light/dark theme; a PNG
|
|
34
|
+
cannot, so each carries a fixed dark palette.
|
|
35
|
+
|
|
36
|
+
roadkeep-mark.svg 160x160 icon, the header below. Absolute and served by the
|
|
37
|
+
site because this file is also the PyPI project page
|
|
38
|
+
(RK19): a relative path resolves against pypi.org, and
|
|
39
|
+
raw.githubusercontent serves an SVG as text/plain.
|
|
40
|
+
Every link below is absolute for the same reason.
|
|
41
|
+
roadkeep-logo.svg 520x160 mark + wordmark
|
|
42
|
+
roadkeep-banner.svg 1200x300 banner source
|
|
43
|
+
roadkeep-banner.png 1200x300 banner
|
|
44
|
+
roadkeep-social.svg 1280x640 source for the link preview
|
|
45
|
+
roadkeep-social.png 1280x640 upload at Settings > General > Social preview.
|
|
46
|
+
This is what renders when the repo URL is pasted
|
|
47
|
+
into LinkedIn, Slack or a link card anywhere else.
|
|
48
|
+
Re-render either PNG after editing its SVG:
|
|
49
|
+
msedge --headless=new --window-size=1200,300 \
|
|
50
|
+
--screenshot=site/public/assets/roadkeep-banner.png \
|
|
51
|
+
file:///.../site/public/assets/roadkeep-banner.svg
|
|
52
|
+
-->
|
|
53
|
+
|
|
54
|
+
<div align="center">
|
|
55
|
+
|
|
56
|
+
<img src="https://alegauss.github.io/roadkeep/assets/roadkeep-mark.svg" alt="roadkeep logo" width="120">
|
|
57
|
+
|
|
58
|
+
# roadkeep
|
|
59
|
+
|
|
60
|
+
**A Claude Code plugin that keeps your `ROADMAP.md`, `CHANGELOG.md` and `IMPROVEMENTS.md` to one format, by refusing the hand-edit and handing the agent the command that writes it properly.**
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
claude plugin marketplace add alegauss/roadkeep --scope project
|
|
64
|
+
claude plugin install roadkeep@alegauss --scope project
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Python 3.11+ · zero runtime dependencies · nothing to add to `PATH` · your files stay plain Markdown
|
|
68
|
+
|
|
69
|
+
**[alegauss.github.io/roadkeep](https://alegauss.github.io/roadkeep/)**: the site, and the
|
|
70
|
+
[docs](https://alegauss.github.io/roadkeep/docs/).
|
|
71
|
+
|
|
72
|
+
</div>
|
|
73
|
+
|
|
74
|
+
- **Refused before the prose exists.** A task line is fields with limits: `symptom` and `why`
|
|
75
|
+
have a `maxLength`, markers are an `enum`, ids have a pattern. A line that does not fit is
|
|
76
|
+
refused when it is written, not reported by a linter after the tokens are spent.
|
|
77
|
+
- **A hand-edit is denied, with the command to call instead.** The hook names the exact
|
|
78
|
+
`add`, `status` or `ship` that does the job, so the right path is also the cheapest one.
|
|
79
|
+
- **Ask instead of read.** `pick`, `brief`, `list` and `deps` answer what is next, what blocks
|
|
80
|
+
what and why a task exists, so an agent never reads a whole backlog to find one line.
|
|
81
|
+
- **It governs the file you already have.** One line per task in your existing `ROADMAP.md`,
|
|
82
|
+
not a new store to migrate into, and a write that would not round-trip byte for byte is
|
|
83
|
+
refused.
|
|
84
|
+
- **The same gate everywhere.** `roadkeep lint` runs as the hook at the end of a turn, as a
|
|
85
|
+
pre-commit hook and as a GitHub Action, and every finding names the command that fixes it.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
> **Unofficial / community project.** Not affiliated with, endorsed by, or sponsored by
|
|
90
|
+
> Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.
|
|
91
|
+
|
|
92
|
+
## Install
|
|
93
|
+
|
|
94
|
+
Run the two commands above in the repository you want governed. You need a **Python 3.11+**
|
|
95
|
+
interpreter as `python`; the plugin carries the package itself, so there is nothing to
|
|
96
|
+
`pip install`.
|
|
97
|
+
|
|
98
|
+
`--scope project` writes both declarations into that repository's `.claude/settings.json`:
|
|
99
|
+
|
|
100
|
+
```jsonc
|
|
101
|
+
"extraKnownMarketplaces": { "alegauss": { "source": { "source": "github", "repo": "alegauss/roadkeep" } } },
|
|
102
|
+
"enabledPlugins": { "roadkeep@alegauss": true }
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Commit that file and **every clone is wired**, with no step per machine. What arrives:
|
|
106
|
+
|
|
107
|
+
- the **hook** that denies a hand-edit of a governed file and names the command, and runs
|
|
108
|
+
`lint` before the turn ends;
|
|
109
|
+
- the **MCP tools** (`mcp__roadkeep__*`), whose input schema is *your* project's: its limits,
|
|
110
|
+
its markers, its id shape;
|
|
111
|
+
- four **slash commands**, `/roadkeep:add`, `/roadkeep:ship`, `/roadkeep:pick` and
|
|
112
|
+
`/roadkeep:lint`;
|
|
113
|
+
- the **skill**, loaded only when a governed file is in play.
|
|
114
|
+
|
|
115
|
+
Inside an interactive session, `/plugin marketplace add alegauss/roadkeep` and
|
|
116
|
+
`/plugin install roadkeep@alegauss` do the same for your user alone.
|
|
117
|
+
|
|
118
|
+
## First session
|
|
119
|
+
|
|
120
|
+
The format is declared once per repository, in `roadkeep.toml`. Ask for it:
|
|
121
|
+
|
|
122
|
+
> Adopt docs/ROADMAP.md under roadkeep, with the prefix SH.
|
|
123
|
+
|
|
124
|
+
For a backlog you already have, that runs `adopt` first, which measures your file and reports
|
|
125
|
+
what a limit would refuse before anything changes. Then it runs `init --existing`, which
|
|
126
|
+
declares your roadmap untouched: the prefix comes off the ids it already carries and the
|
|
127
|
+
blocks off its own headings. On a new project, a bare `init` writes the config and the empty
|
|
128
|
+
files. Years of lines written before the rules can be forgiven by name with `--baseline`, so
|
|
129
|
+
the gate goes into CI on the first day. The whole run, with every refusal it printed, is in
|
|
130
|
+
[Adopting a backlog you already have](https://alegauss.github.io/roadkeep/docs/adopting/).
|
|
131
|
+
|
|
132
|
+
From then on, ask in plain words:
|
|
133
|
+
|
|
134
|
+
> Add a task to block B: the export drops the last line when the file has no trailing newline.
|
|
135
|
+
|
|
136
|
+
> What should I work on next?
|
|
137
|
+
|
|
138
|
+
> Ship RK12: export keeps the last line.
|
|
139
|
+
|
|
140
|
+
Claude calls `add`, `pick` and `ship`. If the symptom is too long, the refusal says by how
|
|
141
|
+
much, and `ship` moves the line to the changelog and drops its rationale section in one write.
|
|
142
|
+
If Claude reaches for `Edit` on the roadmap out of habit, the hook stops it and names the call.
|
|
143
|
+
[In a session](https://alegauss.github.io/roadkeep/docs/session/) covers everything the agent
|
|
144
|
+
receives.
|
|
145
|
+
|
|
146
|
+
## Run it as a gate
|
|
147
|
+
|
|
148
|
+
`roadkeep lint` exits **1** on a file that drifted and **0** on one that did not. That exit
|
|
149
|
+
code is the whole contract, so every surface calls the same command:
|
|
150
|
+
|
|
151
|
+
```yaml
|
|
152
|
+
# .github/workflows/gate.yml — the action this repository ships
|
|
153
|
+
steps:
|
|
154
|
+
- uses: actions/checkout@v4
|
|
155
|
+
- uses: alegauss/roadkeep@v0.2.0 # with: {directory: .}
|
|
156
|
+
|
|
157
|
+
# .pre-commit-config.yaml — the same command, one step earlier
|
|
158
|
+
repos:
|
|
159
|
+
- repo: https://github.com/alegauss/roadkeep
|
|
160
|
+
rev: v0.2.0 # a release tag; `main` tracks unreleased
|
|
161
|
+
hooks:
|
|
162
|
+
- id: roadkeep-lint # or roadkeep-lint-fix, which normalizes first
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
`--fix` repairs only what the format *derives* — the dep annotation, the pointer, dep order,
|
|
166
|
+
an invisible codepoint, whitespace around a field, a queue entry whose task has left, a
|
|
167
|
+
criteria heading addressed to nothing — and
|
|
168
|
+
leaves every editorial finding to a human, which is what keeps a first run on a real backlog
|
|
169
|
+
down to a report somebody reads.
|
|
170
|
+
|
|
171
|
+
Every finding names the command that closes it. `roadkeep repair` runs the ones that need no
|
|
172
|
+
decision, `repair --dry-run` prints them without running, and `roadkeep explain <code>` says
|
|
173
|
+
what a finding code means.
|
|
174
|
+
|
|
175
|
+
## Without Claude Code
|
|
176
|
+
|
|
177
|
+
```sh
|
|
178
|
+
uvx roadkeep lint # no install, no checkout
|
|
179
|
+
pip install roadkeep # or into an environment you keep
|
|
180
|
+
|
|
181
|
+
# A fix that is on main and not yet released: the same run, resolved by URL
|
|
182
|
+
uvx --from git+https://github.com/alegauss/roadkeep roadkeep lint
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Every command takes `--json`, which also says which file and line the answer came from.
|
|
186
|
+
|
|
187
|
+
### On Claude Code on the web
|
|
188
|
+
|
|
189
|
+
[Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web) never
|
|
190
|
+
installs a marketplace plugin. It reads only what the repository commits, so the plugin
|
|
191
|
+
commands above wire nothing there, and an agent with no guard falls back to hand-editing the
|
|
192
|
+
governed files. The fix is a small launcher committed to the repository, which the hook and
|
|
193
|
+
the MCP server point at instead of the plugin root. It finds an engine at run time, and its
|
|
194
|
+
guard stands down where the plugin is installed. [Viglet Shio](https://github.com/openviglet/shio) carries
|
|
195
|
+
the reference copy at
|
|
196
|
+
[`.claude/hooks/roadkeep-launch.py`](https://github.com/openviglet/shio/blob/main/.claude/hooks/roadkeep-launch.py),
|
|
197
|
+
and [In a session](https://alegauss.github.io/roadkeep/docs/session/) explains the wiring.
|
|
198
|
+
|
|
199
|
+
### From a checkout beside it
|
|
200
|
+
|
|
201
|
+
A project adopting an unreleased version runs a sibling checkout, and `install` writes the
|
|
202
|
+
hook, the MCP server and the skill into that project itself:
|
|
203
|
+
|
|
204
|
+
```sh
|
|
205
|
+
python ../roadkeep/plugin/scripts/roadkeep.py -C . install
|
|
206
|
+
python ../roadkeep/plugin/scripts/roadkeep.py -C . install --check # in CI: still in step?
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## Why it exists
|
|
210
|
+
|
|
211
|
+
It started as three readings from a real production repository, where all three files
|
|
212
|
+
declared a format and none enforced it:
|
|
213
|
+
|
|
214
|
+
| Artefact | Declared rule | Actual reading |
|
|
215
|
+
|---|---|---|
|
|
216
|
+
| `docs/ROADMAP.md` | one sentence per task | 92 lines, **142 words** average, worst **1406 characters** |
|
|
217
|
+
| `agents.md` | index only, loaded every turn | grew to **186 KB (~46k tokens)** |
|
|
218
|
+
| `docs/IMPROVEMENTS.md` | rationale for *unshipped* work | a sibling project's reached **539 KB** |
|
|
219
|
+
|
|
220
|
+
Six of the eight worst lines were written in the session that then diagnosed the problem. An
|
|
221
|
+
author, human or model, who has the whole design in mind writes it where the reader is, and an
|
|
222
|
+
instruction to be terse does not survive that. A linter reports after the prose exists, when
|
|
223
|
+
the author is asked to delete work just done. A field with `maxLength: 200` refuses before the
|
|
224
|
+
sentence is composed.
|
|
225
|
+
|
|
226
|
+
Six laws bind the design, and a change that breaks one is wrong even if requested
|
|
227
|
+
([§0.3](https://github.com/alegauss/roadkeep/blob/main/docs/IMPROVEMENTS.md)):
|
|
228
|
+
|
|
229
|
+
| # | Law |
|
|
230
|
+
|---|---|
|
|
231
|
+
| L1 | The format is a schema, **enforced where the text is created**; `lint` is the backstop. |
|
|
232
|
+
| L2 | **The store is the repository**: Markdown, greppable, diffable. No database, no service. |
|
|
233
|
+
| L3 | **Round-trip or don't write**: parse → render → byte-identical. |
|
|
234
|
+
| L4 | **The tool never writes prose**: it validates and renders. |
|
|
235
|
+
| L5 | **Query instead of read**: every question is a command. |
|
|
236
|
+
| L6 | **Configuration, not convention**: prefix, paths, markers and limits are per project. |
|
|
237
|
+
|
|
238
|
+
The non-goals: no web UI and no server, no issue-tracker sync, no model and no prompts inside
|
|
239
|
+
the tool, and no dates, quarters or estimates.
|
|
240
|
+
|
|
241
|
+
## Status
|
|
242
|
+
|
|
243
|
+
The table below is **not written by hand**: `roadkeep export --readme` derives it from
|
|
244
|
+
`docs/`, so it cannot restate a backlog it no longer matches.
|
|
245
|
+
|
|
246
|
+
<!-- roadkeep:begin -->
|
|
247
|
+
<!-- generated by `roadkeep export --readme`; edit the governed files instead -->
|
|
248
|
+
|
|
249
|
+
| Block | Open | Shipped | Retired |
|
|
250
|
+
| --- | --- | --- | --- |
|
|
251
|
+
| A — The model (a task is data before it is a line) | 1 | 43 | 2 |
|
|
252
|
+
| B — Authoring (insert, never hand-edit) | 2 | 237 | 2 |
|
|
253
|
+
| C — Query (consult without reading the file) | 0 | 204 | 7 |
|
|
254
|
+
| D — The gate | 0 | 319 | 7 |
|
|
255
|
+
| E — Adoption | 1 | 123 | 1 |
|
|
256
|
+
| F — The Claude Code plugin (the guardrail at the agent boundary) | 1 | 167 | 4 |
|
|
257
|
+
| G — The editor surface (the backlog where the file is open) | 0 | 15 | 0 |
|
|
258
|
+
| H — The tool's own shape (what one verb costs to change) | 0 | 45 | 1 |
|
|
259
|
+
| I — The documentation area (what an adopter reads before there is a session to ask) | 1 | 21 | 0 |
|
|
260
|
+
| J — Validation (whether a person ever tried it) | 0 | 5 | 0 |
|
|
261
|
+
| K — The desktop app (one installer for the reader and the plugin) | 0 | 9 | 0 |
|
|
262
|
+
| L — Product sites on the package | 1 | 0 | 0 |
|
|
263
|
+
| **Total** | 7 | 1188 | 24 |
|
|
264
|
+
|
|
265
|
+
**Next ready:**
|
|
266
|
+
|
|
267
|
+
- 📋 **RK1715** (deps: —) **block add opens a label the ledger already declares under another title** — It writes the new heading where the label is missing and exits 0, so one label carries two titles across the governed files. → §RK1715
|
|
268
|
+
<!-- roadkeep:end -->
|
|
269
|
+
|
|
270
|
+
Open work is in
|
|
271
|
+
[docs/ROADMAP.md](https://github.com/alegauss/roadkeep/blob/main/docs/ROADMAP.md). Every
|
|
272
|
+
repository of its author is governed by it, and these have a public roadmap to read:
|
|
273
|
+
[Turing](https://github.com/openviglet/turing/blob/2026.3/docs/ROADMAP.md),
|
|
274
|
+
[Shio](https://github.com/openviglet/shio/blob/2026.3/docs/ROADMAP.md),
|
|
275
|
+
[Dumont](https://github.com/openviglet/dumont/blob/2026.3/docs/ROADMAP.md),
|
|
276
|
+
[polyweave](https://github.com/alegauss/polyweave/blob/main/docs/ROADMAP.md),
|
|
277
|
+
[winwright](https://github.com/alegauss/winwright/blob/main/docs/ROADMAP.md) and
|
|
278
|
+
[commitclerk](https://github.com/alegauss/commitclerk/blob/main/docs/ROADMAP.md). No adopter
|
|
279
|
+
outside the author is known yet. This repository is its
|
|
280
|
+
own conformance fixture: `roadkeep lint` must pass on `docs/` here, and the suite asserts it.
|
|
281
|
+
|
|
282
|
+
## More tools by alegauss
|
|
283
|
+
|
|
284
|
+
For Claude Code:
|
|
285
|
+
|
|
286
|
+
- **[Claude Code Tray](https://alegauss.github.io/claude-tray/)**: your rate-limit usage as a Windows tray icon that turns red before you run out.
|
|
287
|
+
- **[commitclerk](https://alegauss.github.io/commitclerk/)**: Conventional Commits messages from your staged diff, in a single-file Python CLI.
|
|
288
|
+
- **[polyweave](https://alegauss.github.io/polyweave/)**: a Claude Code plugin that makes a game's 3D assets, sounds and names by declaring what each has to satisfy.
|
|
289
|
+
|
|
290
|
+
For Windows developers:
|
|
291
|
+
|
|
292
|
+
- **[winwright](https://alegauss.github.io/winwright/)**: drives a Windows desktop app from a test and reports what was actually observed.
|
|
293
|
+
- **[FreeWilly](https://alegauss.github.io/freewilly/)**: Docker on Windows without Docker Desktop, with no admin prompt and no telemetry.
|
|
294
|
+
- **[Quickshell](https://alegauss.github.io/quickshell/)**: an SSH client for Windows with sessions, keys, SFTP and tunnels, and without the rest of the suite.
|
|
295
|
+
|
|
296
|
+
All of them: [alegauss.github.io](https://alegauss.github.io/)
|
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
Assets in site/public/assets/ — the mark is task lines cut at a gate, with the refused
|
|
3
|
+
remainder faded beyond it. The SVGs follow the reader's light/dark theme; a PNG
|
|
4
|
+
cannot, so each carries a fixed dark palette.
|
|
5
|
+
|
|
6
|
+
roadkeep-mark.svg 160x160 icon, the header below. Absolute and served by the
|
|
7
|
+
site because this file is also the PyPI project page
|
|
8
|
+
(RK19): a relative path resolves against pypi.org, and
|
|
9
|
+
raw.githubusercontent serves an SVG as text/plain.
|
|
10
|
+
Every link below is absolute for the same reason.
|
|
11
|
+
roadkeep-logo.svg 520x160 mark + wordmark
|
|
12
|
+
roadkeep-banner.svg 1200x300 banner source
|
|
13
|
+
roadkeep-banner.png 1200x300 banner
|
|
14
|
+
roadkeep-social.svg 1280x640 source for the link preview
|
|
15
|
+
roadkeep-social.png 1280x640 upload at Settings > General > Social preview.
|
|
16
|
+
This is what renders when the repo URL is pasted
|
|
17
|
+
into LinkedIn, Slack or a link card anywhere else.
|
|
18
|
+
Re-render either PNG after editing its SVG:
|
|
19
|
+
msedge --headless=new --window-size=1200,300 \
|
|
20
|
+
--screenshot=site/public/assets/roadkeep-banner.png \
|
|
21
|
+
file:///.../site/public/assets/roadkeep-banner.svg
|
|
22
|
+
-->
|
|
23
|
+
|
|
24
|
+
<div align="center">
|
|
25
|
+
|
|
26
|
+
<img src="https://alegauss.github.io/roadkeep/assets/roadkeep-mark.svg" alt="roadkeep logo" width="120">
|
|
27
|
+
|
|
28
|
+
# roadkeep
|
|
29
|
+
|
|
30
|
+
**A Claude Code plugin that keeps your `ROADMAP.md`, `CHANGELOG.md` and `IMPROVEMENTS.md` to one format, by refusing the hand-edit and handing the agent the command that writes it properly.**
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
claude plugin marketplace add alegauss/roadkeep --scope project
|
|
34
|
+
claude plugin install roadkeep@alegauss --scope project
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Python 3.11+ · zero runtime dependencies · nothing to add to `PATH` · your files stay plain Markdown
|
|
38
|
+
|
|
39
|
+
**[alegauss.github.io/roadkeep](https://alegauss.github.io/roadkeep/)**: the site, and the
|
|
40
|
+
[docs](https://alegauss.github.io/roadkeep/docs/).
|
|
41
|
+
|
|
42
|
+
</div>
|
|
43
|
+
|
|
44
|
+
- **Refused before the prose exists.** A task line is fields with limits: `symptom` and `why`
|
|
45
|
+
have a `maxLength`, markers are an `enum`, ids have a pattern. A line that does not fit is
|
|
46
|
+
refused when it is written, not reported by a linter after the tokens are spent.
|
|
47
|
+
- **A hand-edit is denied, with the command to call instead.** The hook names the exact
|
|
48
|
+
`add`, `status` or `ship` that does the job, so the right path is also the cheapest one.
|
|
49
|
+
- **Ask instead of read.** `pick`, `brief`, `list` and `deps` answer what is next, what blocks
|
|
50
|
+
what and why a task exists, so an agent never reads a whole backlog to find one line.
|
|
51
|
+
- **It governs the file you already have.** One line per task in your existing `ROADMAP.md`,
|
|
52
|
+
not a new store to migrate into, and a write that would not round-trip byte for byte is
|
|
53
|
+
refused.
|
|
54
|
+
- **The same gate everywhere.** `roadkeep lint` runs as the hook at the end of a turn, as a
|
|
55
|
+
pre-commit hook and as a GitHub Action, and every finding names the command that fixes it.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
> **Unofficial / community project.** Not affiliated with, endorsed by, or sponsored by
|
|
60
|
+
> Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.
|
|
61
|
+
|
|
62
|
+
## Install
|
|
63
|
+
|
|
64
|
+
Run the two commands above in the repository you want governed. You need a **Python 3.11+**
|
|
65
|
+
interpreter as `python`; the plugin carries the package itself, so there is nothing to
|
|
66
|
+
`pip install`.
|
|
67
|
+
|
|
68
|
+
`--scope project` writes both declarations into that repository's `.claude/settings.json`:
|
|
69
|
+
|
|
70
|
+
```jsonc
|
|
71
|
+
"extraKnownMarketplaces": { "alegauss": { "source": { "source": "github", "repo": "alegauss/roadkeep" } } },
|
|
72
|
+
"enabledPlugins": { "roadkeep@alegauss": true }
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Commit that file and **every clone is wired**, with no step per machine. What arrives:
|
|
76
|
+
|
|
77
|
+
- the **hook** that denies a hand-edit of a governed file and names the command, and runs
|
|
78
|
+
`lint` before the turn ends;
|
|
79
|
+
- the **MCP tools** (`mcp__roadkeep__*`), whose input schema is *your* project's: its limits,
|
|
80
|
+
its markers, its id shape;
|
|
81
|
+
- four **slash commands**, `/roadkeep:add`, `/roadkeep:ship`, `/roadkeep:pick` and
|
|
82
|
+
`/roadkeep:lint`;
|
|
83
|
+
- the **skill**, loaded only when a governed file is in play.
|
|
84
|
+
|
|
85
|
+
Inside an interactive session, `/plugin marketplace add alegauss/roadkeep` and
|
|
86
|
+
`/plugin install roadkeep@alegauss` do the same for your user alone.
|
|
87
|
+
|
|
88
|
+
## First session
|
|
89
|
+
|
|
90
|
+
The format is declared once per repository, in `roadkeep.toml`. Ask for it:
|
|
91
|
+
|
|
92
|
+
> Adopt docs/ROADMAP.md under roadkeep, with the prefix SH.
|
|
93
|
+
|
|
94
|
+
For a backlog you already have, that runs `adopt` first, which measures your file and reports
|
|
95
|
+
what a limit would refuse before anything changes. Then it runs `init --existing`, which
|
|
96
|
+
declares your roadmap untouched: the prefix comes off the ids it already carries and the
|
|
97
|
+
blocks off its own headings. On a new project, a bare `init` writes the config and the empty
|
|
98
|
+
files. Years of lines written before the rules can be forgiven by name with `--baseline`, so
|
|
99
|
+
the gate goes into CI on the first day. The whole run, with every refusal it printed, is in
|
|
100
|
+
[Adopting a backlog you already have](https://alegauss.github.io/roadkeep/docs/adopting/).
|
|
101
|
+
|
|
102
|
+
From then on, ask in plain words:
|
|
103
|
+
|
|
104
|
+
> Add a task to block B: the export drops the last line when the file has no trailing newline.
|
|
105
|
+
|
|
106
|
+
> What should I work on next?
|
|
107
|
+
|
|
108
|
+
> Ship RK12: export keeps the last line.
|
|
109
|
+
|
|
110
|
+
Claude calls `add`, `pick` and `ship`. If the symptom is too long, the refusal says by how
|
|
111
|
+
much, and `ship` moves the line to the changelog and drops its rationale section in one write.
|
|
112
|
+
If Claude reaches for `Edit` on the roadmap out of habit, the hook stops it and names the call.
|
|
113
|
+
[In a session](https://alegauss.github.io/roadkeep/docs/session/) covers everything the agent
|
|
114
|
+
receives.
|
|
115
|
+
|
|
116
|
+
## Run it as a gate
|
|
117
|
+
|
|
118
|
+
`roadkeep lint` exits **1** on a file that drifted and **0** on one that did not. That exit
|
|
119
|
+
code is the whole contract, so every surface calls the same command:
|
|
120
|
+
|
|
121
|
+
```yaml
|
|
122
|
+
# .github/workflows/gate.yml — the action this repository ships
|
|
123
|
+
steps:
|
|
124
|
+
- uses: actions/checkout@v4
|
|
125
|
+
- uses: alegauss/roadkeep@v0.2.0 # with: {directory: .}
|
|
126
|
+
|
|
127
|
+
# .pre-commit-config.yaml — the same command, one step earlier
|
|
128
|
+
repos:
|
|
129
|
+
- repo: https://github.com/alegauss/roadkeep
|
|
130
|
+
rev: v0.2.0 # a release tag; `main` tracks unreleased
|
|
131
|
+
hooks:
|
|
132
|
+
- id: roadkeep-lint # or roadkeep-lint-fix, which normalizes first
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`--fix` repairs only what the format *derives* — the dep annotation, the pointer, dep order,
|
|
136
|
+
an invisible codepoint, whitespace around a field, a queue entry whose task has left, a
|
|
137
|
+
criteria heading addressed to nothing — and
|
|
138
|
+
leaves every editorial finding to a human, which is what keeps a first run on a real backlog
|
|
139
|
+
down to a report somebody reads.
|
|
140
|
+
|
|
141
|
+
Every finding names the command that closes it. `roadkeep repair` runs the ones that need no
|
|
142
|
+
decision, `repair --dry-run` prints them without running, and `roadkeep explain <code>` says
|
|
143
|
+
what a finding code means.
|
|
144
|
+
|
|
145
|
+
## Without Claude Code
|
|
146
|
+
|
|
147
|
+
```sh
|
|
148
|
+
uvx roadkeep lint # no install, no checkout
|
|
149
|
+
pip install roadkeep # or into an environment you keep
|
|
150
|
+
|
|
151
|
+
# A fix that is on main and not yet released: the same run, resolved by URL
|
|
152
|
+
uvx --from git+https://github.com/alegauss/roadkeep roadkeep lint
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Every command takes `--json`, which also says which file and line the answer came from.
|
|
156
|
+
|
|
157
|
+
### On Claude Code on the web
|
|
158
|
+
|
|
159
|
+
[Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web) never
|
|
160
|
+
installs a marketplace plugin. It reads only what the repository commits, so the plugin
|
|
161
|
+
commands above wire nothing there, and an agent with no guard falls back to hand-editing the
|
|
162
|
+
governed files. The fix is a small launcher committed to the repository, which the hook and
|
|
163
|
+
the MCP server point at instead of the plugin root. It finds an engine at run time, and its
|
|
164
|
+
guard stands down where the plugin is installed. [Viglet Shio](https://github.com/openviglet/shio) carries
|
|
165
|
+
the reference copy at
|
|
166
|
+
[`.claude/hooks/roadkeep-launch.py`](https://github.com/openviglet/shio/blob/main/.claude/hooks/roadkeep-launch.py),
|
|
167
|
+
and [In a session](https://alegauss.github.io/roadkeep/docs/session/) explains the wiring.
|
|
168
|
+
|
|
169
|
+
### From a checkout beside it
|
|
170
|
+
|
|
171
|
+
A project adopting an unreleased version runs a sibling checkout, and `install` writes the
|
|
172
|
+
hook, the MCP server and the skill into that project itself:
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
python ../roadkeep/plugin/scripts/roadkeep.py -C . install
|
|
176
|
+
python ../roadkeep/plugin/scripts/roadkeep.py -C . install --check # in CI: still in step?
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Why it exists
|
|
180
|
+
|
|
181
|
+
It started as three readings from a real production repository, where all three files
|
|
182
|
+
declared a format and none enforced it:
|
|
183
|
+
|
|
184
|
+
| Artefact | Declared rule | Actual reading |
|
|
185
|
+
|---|---|---|
|
|
186
|
+
| `docs/ROADMAP.md` | one sentence per task | 92 lines, **142 words** average, worst **1406 characters** |
|
|
187
|
+
| `agents.md` | index only, loaded every turn | grew to **186 KB (~46k tokens)** |
|
|
188
|
+
| `docs/IMPROVEMENTS.md` | rationale for *unshipped* work | a sibling project's reached **539 KB** |
|
|
189
|
+
|
|
190
|
+
Six of the eight worst lines were written in the session that then diagnosed the problem. An
|
|
191
|
+
author, human or model, who has the whole design in mind writes it where the reader is, and an
|
|
192
|
+
instruction to be terse does not survive that. A linter reports after the prose exists, when
|
|
193
|
+
the author is asked to delete work just done. A field with `maxLength: 200` refuses before the
|
|
194
|
+
sentence is composed.
|
|
195
|
+
|
|
196
|
+
Six laws bind the design, and a change that breaks one is wrong even if requested
|
|
197
|
+
([§0.3](https://github.com/alegauss/roadkeep/blob/main/docs/IMPROVEMENTS.md)):
|
|
198
|
+
|
|
199
|
+
| # | Law |
|
|
200
|
+
|---|---|
|
|
201
|
+
| L1 | The format is a schema, **enforced where the text is created**; `lint` is the backstop. |
|
|
202
|
+
| L2 | **The store is the repository**: Markdown, greppable, diffable. No database, no service. |
|
|
203
|
+
| L3 | **Round-trip or don't write**: parse → render → byte-identical. |
|
|
204
|
+
| L4 | **The tool never writes prose**: it validates and renders. |
|
|
205
|
+
| L5 | **Query instead of read**: every question is a command. |
|
|
206
|
+
| L6 | **Configuration, not convention**: prefix, paths, markers and limits are per project. |
|
|
207
|
+
|
|
208
|
+
The non-goals: no web UI and no server, no issue-tracker sync, no model and no prompts inside
|
|
209
|
+
the tool, and no dates, quarters or estimates.
|
|
210
|
+
|
|
211
|
+
## Status
|
|
212
|
+
|
|
213
|
+
The table below is **not written by hand**: `roadkeep export --readme` derives it from
|
|
214
|
+
`docs/`, so it cannot restate a backlog it no longer matches.
|
|
215
|
+
|
|
216
|
+
<!-- roadkeep:begin -->
|
|
217
|
+
<!-- generated by `roadkeep export --readme`; edit the governed files instead -->
|
|
218
|
+
|
|
219
|
+
| Block | Open | Shipped | Retired |
|
|
220
|
+
| --- | --- | --- | --- |
|
|
221
|
+
| A — The model (a task is data before it is a line) | 1 | 43 | 2 |
|
|
222
|
+
| B — Authoring (insert, never hand-edit) | 2 | 237 | 2 |
|
|
223
|
+
| C — Query (consult without reading the file) | 0 | 204 | 7 |
|
|
224
|
+
| D — The gate | 0 | 319 | 7 |
|
|
225
|
+
| E — Adoption | 1 | 123 | 1 |
|
|
226
|
+
| F — The Claude Code plugin (the guardrail at the agent boundary) | 1 | 167 | 4 |
|
|
227
|
+
| G — The editor surface (the backlog where the file is open) | 0 | 15 | 0 |
|
|
228
|
+
| H — The tool's own shape (what one verb costs to change) | 0 | 45 | 1 |
|
|
229
|
+
| I — The documentation area (what an adopter reads before there is a session to ask) | 1 | 21 | 0 |
|
|
230
|
+
| J — Validation (whether a person ever tried it) | 0 | 5 | 0 |
|
|
231
|
+
| K — The desktop app (one installer for the reader and the plugin) | 0 | 9 | 0 |
|
|
232
|
+
| L — Product sites on the package | 1 | 0 | 0 |
|
|
233
|
+
| **Total** | 7 | 1188 | 24 |
|
|
234
|
+
|
|
235
|
+
**Next ready:**
|
|
236
|
+
|
|
237
|
+
- 📋 **RK1715** (deps: —) **block add opens a label the ledger already declares under another title** — It writes the new heading where the label is missing and exits 0, so one label carries two titles across the governed files. → §RK1715
|
|
238
|
+
<!-- roadkeep:end -->
|
|
239
|
+
|
|
240
|
+
Open work is in
|
|
241
|
+
[docs/ROADMAP.md](https://github.com/alegauss/roadkeep/blob/main/docs/ROADMAP.md). Every
|
|
242
|
+
repository of its author is governed by it, and these have a public roadmap to read:
|
|
243
|
+
[Turing](https://github.com/openviglet/turing/blob/2026.3/docs/ROADMAP.md),
|
|
244
|
+
[Shio](https://github.com/openviglet/shio/blob/2026.3/docs/ROADMAP.md),
|
|
245
|
+
[Dumont](https://github.com/openviglet/dumont/blob/2026.3/docs/ROADMAP.md),
|
|
246
|
+
[polyweave](https://github.com/alegauss/polyweave/blob/main/docs/ROADMAP.md),
|
|
247
|
+
[winwright](https://github.com/alegauss/winwright/blob/main/docs/ROADMAP.md) and
|
|
248
|
+
[commitclerk](https://github.com/alegauss/commitclerk/blob/main/docs/ROADMAP.md). No adopter
|
|
249
|
+
outside the author is known yet. This repository is its
|
|
250
|
+
own conformance fixture: `roadkeep lint` must pass on `docs/` here, and the suite asserts it.
|
|
251
|
+
|
|
252
|
+
## More tools by alegauss
|
|
253
|
+
|
|
254
|
+
For Claude Code:
|
|
255
|
+
|
|
256
|
+
- **[Claude Code Tray](https://alegauss.github.io/claude-tray/)**: your rate-limit usage as a Windows tray icon that turns red before you run out.
|
|
257
|
+
- **[commitclerk](https://alegauss.github.io/commitclerk/)**: Conventional Commits messages from your staged diff, in a single-file Python CLI.
|
|
258
|
+
- **[polyweave](https://alegauss.github.io/polyweave/)**: a Claude Code plugin that makes a game's 3D assets, sounds and names by declaring what each has to satisfy.
|
|
259
|
+
|
|
260
|
+
For Windows developers:
|
|
261
|
+
|
|
262
|
+
- **[winwright](https://alegauss.github.io/winwright/)**: drives a Windows desktop app from a test and reports what was actually observed.
|
|
263
|
+
- **[FreeWilly](https://alegauss.github.io/freewilly/)**: Docker on Windows without Docker Desktop, with no admin prompt and no telemetry.
|
|
264
|
+
- **[Quickshell](https://alegauss.github.io/quickshell/)**: an SSH client for Windows with sessions, keys, SFTP and tunnels, and without the rest of the suite.
|
|
265
|
+
|
|
266
|
+
All of them: [alegauss.github.io](https://alegauss.github.io/)
|
|
@@ -47,7 +47,7 @@ __all__ = [
|
|
|
47
47
|
#: The one place the version is written (RK19). `pyproject.toml` declares it `dynamic` and
|
|
48
48
|
#: reads this literal, so a release cannot ship a number the package disagrees with — which
|
|
49
49
|
#: is also why it stays eager: a build backend parses this file, it does not import it.
|
|
50
|
-
__version__ = "0.2.
|
|
50
|
+
__version__ = "0.2.535"
|
|
51
51
|
|
|
52
52
|
|
|
53
53
|
#: What the names above are, resolved once each. A frozenset and not a `TYPE_CHECKING`
|