roadkeep 0.2.0__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.0/LICENSE +202 -0
- roadkeep-0.2.0/PKG-INFO +453 -0
- roadkeep-0.2.0/README.md +423 -0
- roadkeep-0.2.0/pyproject.toml +90 -0
- roadkeep-0.2.0/setup.cfg +4 -0
- roadkeep-0.2.0/src/roadkeep/__init__.py +79 -0
- roadkeep-0.2.0/src/roadkeep/adopting.py +2347 -0
- roadkeep-0.2.0/src/roadkeep/attesting.py +293 -0
- roadkeep-0.2.0/src/roadkeep/authoring.py +2117 -0
- roadkeep-0.2.0/src/roadkeep/backlog.py +767 -0
- roadkeep-0.2.0/src/roadkeep/blocking.py +1622 -0
- roadkeep-0.2.0/src/roadkeep/briefing.py +970 -0
- roadkeep-0.2.0/src/roadkeep/budgeting.py +2056 -0
- roadkeep-0.2.0/src/roadkeep/capturing.py +1699 -0
- roadkeep-0.2.0/src/roadkeep/claiming.py +1019 -0
- roadkeep-0.2.0/src/roadkeep/cli.py +638 -0
- roadkeep-0.2.0/src/roadkeep/commanding.py +487 -0
- roadkeep-0.2.0/src/roadkeep/config.py +1832 -0
- roadkeep-0.2.0/src/roadkeep/counting.py +376 -0
- roadkeep-0.2.0/src/roadkeep/criteria.py +933 -0
- roadkeep-0.2.0/src/roadkeep/deferring.py +708 -0
- roadkeep-0.2.0/src/roadkeep/describing.py +568 -0
- roadkeep-0.2.0/src/roadkeep/exporting.py +808 -0
- roadkeep-0.2.0/src/roadkeep/fixing.py +629 -0
- roadkeep-0.2.0/src/roadkeep/governing.py +934 -0
- roadkeep-0.2.0/src/roadkeep/graph.py +395 -0
- roadkeep-0.2.0/src/roadkeep/guarding.py +1028 -0
- roadkeep-0.2.0/src/roadkeep/history.py +2403 -0
- roadkeep-0.2.0/src/roadkeep/ids.py +301 -0
- roadkeep-0.2.0/src/roadkeep/installing.py +2145 -0
- roadkeep-0.2.0/src/roadkeep/kernel/__init__.py +24 -0
- roadkeep-0.2.0/src/roadkeep/kernel/document.py +1719 -0
- roadkeep-0.2.0/src/roadkeep/kernel/schema.py +2308 -0
- roadkeep-0.2.0/src/roadkeep/linting.py +4420 -0
- roadkeep-0.2.0/src/roadkeep/locking.py +209 -0
- roadkeep-0.2.0/src/roadkeep/markers.py +172 -0
- roadkeep-0.2.0/src/roadkeep/merging.py +1159 -0
- roadkeep-0.2.0/src/roadkeep/picking.py +772 -0
- roadkeep-0.2.0/src/roadkeep/provenance.py +789 -0
- roadkeep-0.2.0/src/roadkeep/queueing.py +752 -0
- roadkeep-0.2.0/src/roadkeep/ranking.py +139 -0
- roadkeep-0.2.0/src/roadkeep/referring.py +231 -0
- roadkeep-0.2.0/src/roadkeep/remaining.py +336 -0
- roadkeep-0.2.0/src/roadkeep/remedying.py +1989 -0
- roadkeep-0.2.0/src/roadkeep/rendering.py +1601 -0
- roadkeep-0.2.0/src/roadkeep/renumbering.py +503 -0
- roadkeep-0.2.0/src/roadkeep/repairing.py +295 -0
- roadkeep-0.2.0/src/roadkeep/reverting.py +144 -0
- roadkeep-0.2.0/src/roadkeep/scoping.py +708 -0
- roadkeep-0.2.0/src/roadkeep/screening.py +196 -0
- roadkeep-0.2.0/src/roadkeep/sections.py +4121 -0
- roadkeep-0.2.0/src/roadkeep/serving.py +2909 -0
- roadkeep-0.2.0/src/roadkeep/shipping.py +3993 -0
- roadkeep-0.2.0/src/roadkeep/showing.py +613 -0
- roadkeep-0.2.0/src/roadkeep/storing.py +224 -0
- roadkeep-0.2.0/src/roadkeep/verbs/__init__.py +26 -0
- roadkeep-0.2.0/src/roadkeep/verbs/adopting.py +974 -0
- roadkeep-0.2.0/src/roadkeep/verbs/authoring.py +566 -0
- roadkeep-0.2.0/src/roadkeep/verbs/declaring.py +335 -0
- roadkeep-0.2.0/src/roadkeep/verbs/linting.py +645 -0
- roadkeep-0.2.0/src/roadkeep/verbs/querying.py +2138 -0
- roadkeep-0.2.0/src/roadkeep/verbs/reading.py +307 -0
- roadkeep-0.2.0/src/roadkeep/verbs/refusing.py +146 -0
- roadkeep-0.2.0/src/roadkeep/verbs/sections.py +1433 -0
- roadkeep-0.2.0/src/roadkeep/verbs/shipping.py +819 -0
- roadkeep-0.2.0/src/roadkeep/weighing.py +380 -0
- roadkeep-0.2.0/src/roadkeep.egg-info/PKG-INFO +453 -0
- roadkeep-0.2.0/src/roadkeep.egg-info/SOURCES.txt +164 -0
- roadkeep-0.2.0/src/roadkeep.egg-info/dependency_links.txt +1 -0
- roadkeep-0.2.0/src/roadkeep.egg-info/entry_points.txt +2 -0
- roadkeep-0.2.0/src/roadkeep.egg-info/requires.txt +4 -0
- roadkeep-0.2.0/src/roadkeep.egg-info/top_level.txt +1 -0
- roadkeep-0.2.0/tests/test_adopting.py +2886 -0
- roadkeep-0.2.0/tests/test_answers.py +342 -0
- roadkeep-0.2.0/tests/test_area.py +212 -0
- roadkeep-0.2.0/tests/test_asking.py +95 -0
- roadkeep-0.2.0/tests/test_attesting.py +301 -0
- roadkeep-0.2.0/tests/test_authoring.py +2719 -0
- roadkeep-0.2.0/tests/test_backlog.py +938 -0
- roadkeep-0.2.0/tests/test_backstop.py +303 -0
- roadkeep-0.2.0/tests/test_baseline.py +1165 -0
- roadkeep-0.2.0/tests/test_blocking.py +1501 -0
- roadkeep-0.2.0/tests/test_briefing.py +918 -0
- roadkeep-0.2.0/tests/test_budgeted.py +202 -0
- roadkeep-0.2.0/tests/test_budgeting.py +3167 -0
- roadkeep-0.2.0/tests/test_caches.py +198 -0
- roadkeep-0.2.0/tests/test_capturing.py +1555 -0
- roadkeep-0.2.0/tests/test_carrying.py +112 -0
- roadkeep-0.2.0/tests/test_checkout.py +125 -0
- roadkeep-0.2.0/tests/test_claiming.py +2122 -0
- roadkeep-0.2.0/tests/test_commanding.py +253 -0
- roadkeep-0.2.0/tests/test_commands.py +265 -0
- roadkeep-0.2.0/tests/test_composing.py +387 -0
- roadkeep-0.2.0/tests/test_config.py +832 -0
- roadkeep-0.2.0/tests/test_configured.py +145 -0
- roadkeep-0.2.0/tests/test_corpora.py +343 -0
- roadkeep-0.2.0/tests/test_counting.py +532 -0
- roadkeep-0.2.0/tests/test_criteria.py +633 -0
- roadkeep-0.2.0/tests/test_cycles.py +147 -0
- roadkeep-0.2.0/tests/test_deferring.py +918 -0
- roadkeep-0.2.0/tests/test_describing.py +412 -0
- roadkeep-0.2.0/tests/test_document.py +1343 -0
- roadkeep-0.2.0/tests/test_doors.py +323 -0
- roadkeep-0.2.0/tests/test_doors_in_both_registers.py +214 -0
- roadkeep-0.2.0/tests/test_editor.py +706 -0
- roadkeep-0.2.0/tests/test_encoding.py +527 -0
- roadkeep-0.2.0/tests/test_events.py +464 -0
- roadkeep-0.2.0/tests/test_exporting.py +903 -0
- roadkeep-0.2.0/tests/test_findings.py +181 -0
- roadkeep-0.2.0/tests/test_fixing.py +634 -0
- roadkeep-0.2.0/tests/test_governing.py +723 -0
- roadkeep-0.2.0/tests/test_graph.py +346 -0
- roadkeep-0.2.0/tests/test_guarding.py +1385 -0
- roadkeep-0.2.0/tests/test_hinting.py +183 -0
- roadkeep-0.2.0/tests/test_history.py +2203 -0
- roadkeep-0.2.0/tests/test_ids.py +439 -0
- roadkeep-0.2.0/tests/test_importing.py +274 -0
- roadkeep-0.2.0/tests/test_installing.py +1881 -0
- roadkeep-0.2.0/tests/test_invariants.py +1094 -0
- roadkeep-0.2.0/tests/test_kernel.py +182 -0
- roadkeep-0.2.0/tests/test_launching.py +1110 -0
- roadkeep-0.2.0/tests/test_linting.py +2772 -0
- roadkeep-0.2.0/tests/test_locking.py +294 -0
- roadkeep-0.2.0/tests/test_markers.py +285 -0
- roadkeep-0.2.0/tests/test_merging.py +1102 -0
- roadkeep-0.2.0/tests/test_model_page.py +128 -0
- roadkeep-0.2.0/tests/test_namespaces.py +617 -0
- roadkeep-0.2.0/tests/test_owned.py +144 -0
- roadkeep-0.2.0/tests/test_packaging.py +577 -0
- roadkeep-0.2.0/tests/test_pairs.py +304 -0
- roadkeep-0.2.0/tests/test_payloads.py +426 -0
- roadkeep-0.2.0/tests/test_picking.py +770 -0
- roadkeep-0.2.0/tests/test_plugin.py +557 -0
- roadkeep-0.2.0/tests/test_prevention.py +446 -0
- roadkeep-0.2.0/tests/test_provenance.py +642 -0
- roadkeep-0.2.0/tests/test_queueing.py +797 -0
- roadkeep-0.2.0/tests/test_ranking.py +323 -0
- roadkeep-0.2.0/tests/test_recording.py +1439 -0
- roadkeep-0.2.0/tests/test_reference.py +283 -0
- roadkeep-0.2.0/tests/test_referring.py +210 -0
- roadkeep-0.2.0/tests/test_remaining.py +366 -0
- roadkeep-0.2.0/tests/test_remedying.py +1604 -0
- roadkeep-0.2.0/tests/test_renumbering.py +543 -0
- roadkeep-0.2.0/tests/test_repairing.py +364 -0
- roadkeep-0.2.0/tests/test_replaying.py +588 -0
- roadkeep-0.2.0/tests/test_retiring.py +457 -0
- roadkeep-0.2.0/tests/test_reverting.py +173 -0
- roadkeep-0.2.0/tests/test_schema.py +994 -0
- roadkeep-0.2.0/tests/test_scoping.py +721 -0
- roadkeep-0.2.0/tests/test_screening.py +292 -0
- roadkeep-0.2.0/tests/test_sections.py +4245 -0
- roadkeep-0.2.0/tests/test_serving.py +2796 -0
- roadkeep-0.2.0/tests/test_session_page.py +143 -0
- roadkeep-0.2.0/tests/test_shadowing.py +113 -0
- roadkeep-0.2.0/tests/test_shipping.py +3575 -0
- roadkeep-0.2.0/tests/test_showing.py +688 -0
- roadkeep-0.2.0/tests/test_skill.py +364 -0
- roadkeep-0.2.0/tests/test_spelling.py +297 -0
- roadkeep-0.2.0/tests/test_status.py +948 -0
- roadkeep-0.2.0/tests/test_storing.py +128 -0
- roadkeep-0.2.0/tests/test_surfaces.py +408 -0
- roadkeep-0.2.0/tests/test_turning.py +201 -0
- roadkeep-0.2.0/tests/test_twins.py +158 -0
- roadkeep-0.2.0/tests/test_unpaired.py +200 -0
- roadkeep-0.2.0/tests/test_walkthrough.py +167 -0
- roadkeep-0.2.0/tests/test_weighing.py +435 -0
roadkeep-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright 2026 Alexandre Oliveira
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
roadkeep-0.2.0/PKG-INFO
ADDED
|
@@ -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`.
|