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.
Files changed (166) hide show
  1. roadkeep-0.2.0/LICENSE +202 -0
  2. roadkeep-0.2.0/PKG-INFO +453 -0
  3. roadkeep-0.2.0/README.md +423 -0
  4. roadkeep-0.2.0/pyproject.toml +90 -0
  5. roadkeep-0.2.0/setup.cfg +4 -0
  6. roadkeep-0.2.0/src/roadkeep/__init__.py +79 -0
  7. roadkeep-0.2.0/src/roadkeep/adopting.py +2347 -0
  8. roadkeep-0.2.0/src/roadkeep/attesting.py +293 -0
  9. roadkeep-0.2.0/src/roadkeep/authoring.py +2117 -0
  10. roadkeep-0.2.0/src/roadkeep/backlog.py +767 -0
  11. roadkeep-0.2.0/src/roadkeep/blocking.py +1622 -0
  12. roadkeep-0.2.0/src/roadkeep/briefing.py +970 -0
  13. roadkeep-0.2.0/src/roadkeep/budgeting.py +2056 -0
  14. roadkeep-0.2.0/src/roadkeep/capturing.py +1699 -0
  15. roadkeep-0.2.0/src/roadkeep/claiming.py +1019 -0
  16. roadkeep-0.2.0/src/roadkeep/cli.py +638 -0
  17. roadkeep-0.2.0/src/roadkeep/commanding.py +487 -0
  18. roadkeep-0.2.0/src/roadkeep/config.py +1832 -0
  19. roadkeep-0.2.0/src/roadkeep/counting.py +376 -0
  20. roadkeep-0.2.0/src/roadkeep/criteria.py +933 -0
  21. roadkeep-0.2.0/src/roadkeep/deferring.py +708 -0
  22. roadkeep-0.2.0/src/roadkeep/describing.py +568 -0
  23. roadkeep-0.2.0/src/roadkeep/exporting.py +808 -0
  24. roadkeep-0.2.0/src/roadkeep/fixing.py +629 -0
  25. roadkeep-0.2.0/src/roadkeep/governing.py +934 -0
  26. roadkeep-0.2.0/src/roadkeep/graph.py +395 -0
  27. roadkeep-0.2.0/src/roadkeep/guarding.py +1028 -0
  28. roadkeep-0.2.0/src/roadkeep/history.py +2403 -0
  29. roadkeep-0.2.0/src/roadkeep/ids.py +301 -0
  30. roadkeep-0.2.0/src/roadkeep/installing.py +2145 -0
  31. roadkeep-0.2.0/src/roadkeep/kernel/__init__.py +24 -0
  32. roadkeep-0.2.0/src/roadkeep/kernel/document.py +1719 -0
  33. roadkeep-0.2.0/src/roadkeep/kernel/schema.py +2308 -0
  34. roadkeep-0.2.0/src/roadkeep/linting.py +4420 -0
  35. roadkeep-0.2.0/src/roadkeep/locking.py +209 -0
  36. roadkeep-0.2.0/src/roadkeep/markers.py +172 -0
  37. roadkeep-0.2.0/src/roadkeep/merging.py +1159 -0
  38. roadkeep-0.2.0/src/roadkeep/picking.py +772 -0
  39. roadkeep-0.2.0/src/roadkeep/provenance.py +789 -0
  40. roadkeep-0.2.0/src/roadkeep/queueing.py +752 -0
  41. roadkeep-0.2.0/src/roadkeep/ranking.py +139 -0
  42. roadkeep-0.2.0/src/roadkeep/referring.py +231 -0
  43. roadkeep-0.2.0/src/roadkeep/remaining.py +336 -0
  44. roadkeep-0.2.0/src/roadkeep/remedying.py +1989 -0
  45. roadkeep-0.2.0/src/roadkeep/rendering.py +1601 -0
  46. roadkeep-0.2.0/src/roadkeep/renumbering.py +503 -0
  47. roadkeep-0.2.0/src/roadkeep/repairing.py +295 -0
  48. roadkeep-0.2.0/src/roadkeep/reverting.py +144 -0
  49. roadkeep-0.2.0/src/roadkeep/scoping.py +708 -0
  50. roadkeep-0.2.0/src/roadkeep/screening.py +196 -0
  51. roadkeep-0.2.0/src/roadkeep/sections.py +4121 -0
  52. roadkeep-0.2.0/src/roadkeep/serving.py +2909 -0
  53. roadkeep-0.2.0/src/roadkeep/shipping.py +3993 -0
  54. roadkeep-0.2.0/src/roadkeep/showing.py +613 -0
  55. roadkeep-0.2.0/src/roadkeep/storing.py +224 -0
  56. roadkeep-0.2.0/src/roadkeep/verbs/__init__.py +26 -0
  57. roadkeep-0.2.0/src/roadkeep/verbs/adopting.py +974 -0
  58. roadkeep-0.2.0/src/roadkeep/verbs/authoring.py +566 -0
  59. roadkeep-0.2.0/src/roadkeep/verbs/declaring.py +335 -0
  60. roadkeep-0.2.0/src/roadkeep/verbs/linting.py +645 -0
  61. roadkeep-0.2.0/src/roadkeep/verbs/querying.py +2138 -0
  62. roadkeep-0.2.0/src/roadkeep/verbs/reading.py +307 -0
  63. roadkeep-0.2.0/src/roadkeep/verbs/refusing.py +146 -0
  64. roadkeep-0.2.0/src/roadkeep/verbs/sections.py +1433 -0
  65. roadkeep-0.2.0/src/roadkeep/verbs/shipping.py +819 -0
  66. roadkeep-0.2.0/src/roadkeep/weighing.py +380 -0
  67. roadkeep-0.2.0/src/roadkeep.egg-info/PKG-INFO +453 -0
  68. roadkeep-0.2.0/src/roadkeep.egg-info/SOURCES.txt +164 -0
  69. roadkeep-0.2.0/src/roadkeep.egg-info/dependency_links.txt +1 -0
  70. roadkeep-0.2.0/src/roadkeep.egg-info/entry_points.txt +2 -0
  71. roadkeep-0.2.0/src/roadkeep.egg-info/requires.txt +4 -0
  72. roadkeep-0.2.0/src/roadkeep.egg-info/top_level.txt +1 -0
  73. roadkeep-0.2.0/tests/test_adopting.py +2886 -0
  74. roadkeep-0.2.0/tests/test_answers.py +342 -0
  75. roadkeep-0.2.0/tests/test_area.py +212 -0
  76. roadkeep-0.2.0/tests/test_asking.py +95 -0
  77. roadkeep-0.2.0/tests/test_attesting.py +301 -0
  78. roadkeep-0.2.0/tests/test_authoring.py +2719 -0
  79. roadkeep-0.2.0/tests/test_backlog.py +938 -0
  80. roadkeep-0.2.0/tests/test_backstop.py +303 -0
  81. roadkeep-0.2.0/tests/test_baseline.py +1165 -0
  82. roadkeep-0.2.0/tests/test_blocking.py +1501 -0
  83. roadkeep-0.2.0/tests/test_briefing.py +918 -0
  84. roadkeep-0.2.0/tests/test_budgeted.py +202 -0
  85. roadkeep-0.2.0/tests/test_budgeting.py +3167 -0
  86. roadkeep-0.2.0/tests/test_caches.py +198 -0
  87. roadkeep-0.2.0/tests/test_capturing.py +1555 -0
  88. roadkeep-0.2.0/tests/test_carrying.py +112 -0
  89. roadkeep-0.2.0/tests/test_checkout.py +125 -0
  90. roadkeep-0.2.0/tests/test_claiming.py +2122 -0
  91. roadkeep-0.2.0/tests/test_commanding.py +253 -0
  92. roadkeep-0.2.0/tests/test_commands.py +265 -0
  93. roadkeep-0.2.0/tests/test_composing.py +387 -0
  94. roadkeep-0.2.0/tests/test_config.py +832 -0
  95. roadkeep-0.2.0/tests/test_configured.py +145 -0
  96. roadkeep-0.2.0/tests/test_corpora.py +343 -0
  97. roadkeep-0.2.0/tests/test_counting.py +532 -0
  98. roadkeep-0.2.0/tests/test_criteria.py +633 -0
  99. roadkeep-0.2.0/tests/test_cycles.py +147 -0
  100. roadkeep-0.2.0/tests/test_deferring.py +918 -0
  101. roadkeep-0.2.0/tests/test_describing.py +412 -0
  102. roadkeep-0.2.0/tests/test_document.py +1343 -0
  103. roadkeep-0.2.0/tests/test_doors.py +323 -0
  104. roadkeep-0.2.0/tests/test_doors_in_both_registers.py +214 -0
  105. roadkeep-0.2.0/tests/test_editor.py +706 -0
  106. roadkeep-0.2.0/tests/test_encoding.py +527 -0
  107. roadkeep-0.2.0/tests/test_events.py +464 -0
  108. roadkeep-0.2.0/tests/test_exporting.py +903 -0
  109. roadkeep-0.2.0/tests/test_findings.py +181 -0
  110. roadkeep-0.2.0/tests/test_fixing.py +634 -0
  111. roadkeep-0.2.0/tests/test_governing.py +723 -0
  112. roadkeep-0.2.0/tests/test_graph.py +346 -0
  113. roadkeep-0.2.0/tests/test_guarding.py +1385 -0
  114. roadkeep-0.2.0/tests/test_hinting.py +183 -0
  115. roadkeep-0.2.0/tests/test_history.py +2203 -0
  116. roadkeep-0.2.0/tests/test_ids.py +439 -0
  117. roadkeep-0.2.0/tests/test_importing.py +274 -0
  118. roadkeep-0.2.0/tests/test_installing.py +1881 -0
  119. roadkeep-0.2.0/tests/test_invariants.py +1094 -0
  120. roadkeep-0.2.0/tests/test_kernel.py +182 -0
  121. roadkeep-0.2.0/tests/test_launching.py +1110 -0
  122. roadkeep-0.2.0/tests/test_linting.py +2772 -0
  123. roadkeep-0.2.0/tests/test_locking.py +294 -0
  124. roadkeep-0.2.0/tests/test_markers.py +285 -0
  125. roadkeep-0.2.0/tests/test_merging.py +1102 -0
  126. roadkeep-0.2.0/tests/test_model_page.py +128 -0
  127. roadkeep-0.2.0/tests/test_namespaces.py +617 -0
  128. roadkeep-0.2.0/tests/test_owned.py +144 -0
  129. roadkeep-0.2.0/tests/test_packaging.py +577 -0
  130. roadkeep-0.2.0/tests/test_pairs.py +304 -0
  131. roadkeep-0.2.0/tests/test_payloads.py +426 -0
  132. roadkeep-0.2.0/tests/test_picking.py +770 -0
  133. roadkeep-0.2.0/tests/test_plugin.py +557 -0
  134. roadkeep-0.2.0/tests/test_prevention.py +446 -0
  135. roadkeep-0.2.0/tests/test_provenance.py +642 -0
  136. roadkeep-0.2.0/tests/test_queueing.py +797 -0
  137. roadkeep-0.2.0/tests/test_ranking.py +323 -0
  138. roadkeep-0.2.0/tests/test_recording.py +1439 -0
  139. roadkeep-0.2.0/tests/test_reference.py +283 -0
  140. roadkeep-0.2.0/tests/test_referring.py +210 -0
  141. roadkeep-0.2.0/tests/test_remaining.py +366 -0
  142. roadkeep-0.2.0/tests/test_remedying.py +1604 -0
  143. roadkeep-0.2.0/tests/test_renumbering.py +543 -0
  144. roadkeep-0.2.0/tests/test_repairing.py +364 -0
  145. roadkeep-0.2.0/tests/test_replaying.py +588 -0
  146. roadkeep-0.2.0/tests/test_retiring.py +457 -0
  147. roadkeep-0.2.0/tests/test_reverting.py +173 -0
  148. roadkeep-0.2.0/tests/test_schema.py +994 -0
  149. roadkeep-0.2.0/tests/test_scoping.py +721 -0
  150. roadkeep-0.2.0/tests/test_screening.py +292 -0
  151. roadkeep-0.2.0/tests/test_sections.py +4245 -0
  152. roadkeep-0.2.0/tests/test_serving.py +2796 -0
  153. roadkeep-0.2.0/tests/test_session_page.py +143 -0
  154. roadkeep-0.2.0/tests/test_shadowing.py +113 -0
  155. roadkeep-0.2.0/tests/test_shipping.py +3575 -0
  156. roadkeep-0.2.0/tests/test_showing.py +688 -0
  157. roadkeep-0.2.0/tests/test_skill.py +364 -0
  158. roadkeep-0.2.0/tests/test_spelling.py +297 -0
  159. roadkeep-0.2.0/tests/test_status.py +948 -0
  160. roadkeep-0.2.0/tests/test_storing.py +128 -0
  161. roadkeep-0.2.0/tests/test_surfaces.py +408 -0
  162. roadkeep-0.2.0/tests/test_turning.py +201 -0
  163. roadkeep-0.2.0/tests/test_twins.py +158 -0
  164. roadkeep-0.2.0/tests/test_unpaired.py +200 -0
  165. roadkeep-0.2.0/tests/test_walkthrough.py +167 -0
  166. 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.
@@ -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`.