roadmodel 0.2.45__tar.gz → 0.2.47__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 (49) hide show
  1. {roadmodel-0.2.45 → roadmodel-0.2.47}/PKG-INFO +7 -6
  2. {roadmodel-0.2.45 → roadmodel-0.2.47}/README.md +6 -5
  3. {roadmodel-0.2.45 → roadmodel-0.2.47}/docs/benchmarks.json +53 -53
  4. {roadmodel-0.2.45 → roadmodel-0.2.47}/docs/catalog.json +1 -1
  5. {roadmodel-0.2.45/roadmodel/data → roadmodel-0.2.47/docs/templates}/phase-roadmap-template.md +15 -9
  6. {roadmodel-0.2.45/roadmodel/data → roadmodel-0.2.47/docs/templates}/planning-kit-how-to-use.md +2 -2
  7. {roadmodel-0.2.45 → roadmodel-0.2.47}/docs/templates/project-roadmap-template.md +6 -0
  8. {roadmodel-0.2.45/roadmodel/data → roadmodel-0.2.47/docs/templates}/prompt-phase-roadmap.md +23 -6
  9. {roadmodel-0.2.45/roadmodel/data → roadmodel-0.2.47/docs/templates}/prompt-project-roadmap.md +18 -1
  10. {roadmodel-0.2.45 → roadmodel-0.2.47}/pyproject.toml +1 -1
  11. {roadmodel-0.2.45 → roadmodel-0.2.47}/roadmodel/data/benchmarks.json +53 -53
  12. {roadmodel-0.2.45 → roadmodel-0.2.47}/roadmodel/data/catalog.json +1 -1
  13. {roadmodel-0.2.45/docs/templates → roadmodel-0.2.47/roadmodel/data}/phase-roadmap-template.md +15 -9
  14. {roadmodel-0.2.45/docs/templates → roadmodel-0.2.47/roadmodel/data}/planning-kit-how-to-use.md +2 -2
  15. {roadmodel-0.2.45 → roadmodel-0.2.47}/roadmodel/data/project-roadmap-template.md +6 -0
  16. {roadmodel-0.2.45/docs/templates → roadmodel-0.2.47/roadmodel/data}/prompt-phase-roadmap.md +23 -6
  17. {roadmodel-0.2.45/docs/templates → roadmodel-0.2.47/roadmodel/data}/prompt-project-roadmap.md +18 -1
  18. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/__init__.py +1 -1
  19. {roadmodel-0.2.45 → roadmodel-0.2.47}/.gitignore +0 -0
  20. {roadmodel-0.2.45 → roadmodel-0.2.47}/LICENSE +0 -0
  21. {roadmodel-0.2.45 → roadmodel-0.2.47}/NOTICE +0 -0
  22. {roadmodel-0.2.45 → roadmodel-0.2.47}/docs/model-selector.txt +0 -0
  23. {roadmodel-0.2.45 → roadmodel-0.2.47}/docs/model-tier-cost-scale.md +0 -0
  24. {roadmodel-0.2.45 → roadmodel-0.2.47}/docs/settings-display.md +0 -0
  25. {roadmodel-0.2.45 → roadmodel-0.2.47}/docs/user-context.example.md +0 -0
  26. {roadmodel-0.2.45 → roadmodel-0.2.47}/hatch_build.py +0 -0
  27. {roadmodel-0.2.45 → roadmodel-0.2.47}/infra/README.md +0 -0
  28. {roadmodel-0.2.45 → roadmodel-0.2.47}/infra/gcp-killswitch/README.md +0 -0
  29. {roadmodel-0.2.45 → roadmodel-0.2.47}/infra/supabase/README.md +0 -0
  30. {roadmodel-0.2.45 → roadmodel-0.2.47}/roadmodel/data/model-selector.txt +0 -0
  31. {roadmodel-0.2.45 → roadmodel-0.2.47}/roadmodel/data/model-tier-cost-scale.md +0 -0
  32. {roadmodel-0.2.45 → roadmodel-0.2.47}/roadmodel/data/settings-display.md +0 -0
  33. {roadmodel-0.2.45 → roadmodel-0.2.47}/roadmodel/data/user-context.example.md +0 -0
  34. {roadmodel-0.2.45 → roadmodel-0.2.47}/scripts/update_projects.py +0 -0
  35. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/__main__.py +0 -0
  36. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/cli.py +0 -0
  37. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/config.py +0 -0
  38. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/cost.py +0 -0
  39. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/errors.py +0 -0
  40. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/mcp_server.py +0 -0
  41. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/providers/__init__.py +0 -0
  42. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/providers/anthropic.py +0 -0
  43. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/providers/google.py +0 -0
  44. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/providers/openai.py +0 -0
  45. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/providers/openai_compatible.py +0 -0
  46. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/providers/registry.py +0 -0
  47. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/recommend.py +0 -0
  48. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/scoring.py +0 -0
  49. {roadmodel-0.2.45 → roadmodel-0.2.47}/src/roadmodel/user_context.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: roadmodel
3
- Version: 0.2.45
3
+ Version: 0.2.47
4
4
  Summary: BYO-key CLI that recommends the right AI model, platform, and settings for a prompt.
5
5
  Project-URL: Homepage, https://roadmodel.ai
6
6
  Project-URL: Repository, https://github.com/nathanramoscfa/roadmodel
@@ -288,11 +288,12 @@ picks the model. The loop is the same in every repo, in every
288
288
  language, on every machine where the commands are installed:
289
289
 
290
290
  ```
291
- /roadmap-project ROADMAP.md — phases, acceptance criteria, and
292
- the security / release / operations strategy
293
- /roadmap-phase 1 docs/phase01-roadmap.md — Phase 1 broken into
294
- steps; each names its branch, its model and
295
- settings, and carries a <task> prompt
291
+ /roadmap-project docs/roadmap/ROADMAP.md — phases, acceptance
292
+ criteria, and the security / release /
293
+ operations strategy
294
+ /roadmap-phase 1 docs/roadmap/phase01-roadmap.md — Phase 1
295
+ broken into steps; each names its branch, its
296
+ model and settings, and carries a <task> prompt
296
297
  /roadmap-step 1 1 a NEW chat runs Step 1: branch → work → PR →
297
298
  /roadmap-step 1 2 merge → "Step 1 is complete." One step per
298
299
  … conversation; no work straddles two steps
@@ -38,11 +38,12 @@ picks the model. The loop is the same in every repo, in every
38
38
  language, on every machine where the commands are installed:
39
39
 
40
40
  ```
41
- /roadmap-project ROADMAP.md — phases, acceptance criteria, and
42
- the security / release / operations strategy
43
- /roadmap-phase 1 docs/phase01-roadmap.md — Phase 1 broken into
44
- steps; each names its branch, its model and
45
- settings, and carries a <task> prompt
41
+ /roadmap-project docs/roadmap/ROADMAP.md — phases, acceptance
42
+ criteria, and the security / release /
43
+ operations strategy
44
+ /roadmap-phase 1 docs/roadmap/phase01-roadmap.md — Phase 1
45
+ broken into steps; each names its branch, its
46
+ model and settings, and carries a <task> prompt
46
47
  /roadmap-step 1 1 a NEW chat runs Step 1: branch → work → PR →
47
48
  /roadmap-step 1 2 merge → "Step 1 is complete." One step per
48
49
  … conversation; no work straddles two steps
@@ -6,7 +6,7 @@
6
6
  "endpoint": "https://artificialanalysis.ai/api/v2/data/llms/models",
7
7
  "attribution": "Benchmark data © Artificial Analysis, used under its API terms with attribution."
8
8
  },
9
- "generated_at_utc": "2026-09-25T22:10:15Z",
9
+ "generated_at_utc": "2026-09-28T22:11:10Z",
10
10
  "model_count": 50,
11
11
  "unmapped": [],
12
12
  "missing_slugs": [],
@@ -36,8 +36,8 @@
36
36
  "tau2": 0.546783625730994,
37
37
  "tau_banking": 0.0927835051546392
38
38
  },
39
- "median_output_tokens_per_second": 112.331,
40
- "median_time_to_first_token_seconds": 14.822
39
+ "median_output_tokens_per_second": 108.201,
40
+ "median_time_to_first_token_seconds": 13.415
41
41
  },
42
42
  "claude-fable-5": {
43
43
  "aa_id": "cd55210d-358e-4df1-ba9c-9acb5f186cc9",
@@ -92,8 +92,8 @@
92
92
  "tau2": null,
93
93
  "tau_banking": 0.472164948453608
94
94
  },
95
- "median_output_tokens_per_second": 71.496,
96
- "median_time_to_first_token_seconds": 137.695
95
+ "median_output_tokens_per_second": 68.949,
96
+ "median_time_to_first_token_seconds": 119.525
97
97
  },
98
98
  "claude-opus-5": {
99
99
  "aa_id": "b8fc61f7-5e9a-49e6-8547-6ac56db24627",
@@ -120,8 +120,8 @@
120
120
  "tau2": null,
121
121
  "tau_banking": 0.420618556701031
122
122
  },
123
- "median_output_tokens_per_second": 67.509,
124
- "median_time_to_first_token_seconds": 34.244
123
+ "median_output_tokens_per_second": 0,
124
+ "median_time_to_first_token_seconds": 0
125
125
  },
126
126
  "claude-opus-5-5": {
127
127
  "aa_id": "2f3c4dc9-a450-4303-8697-0237257cf08f",
@@ -148,8 +148,8 @@
148
148
  "tau2": null,
149
149
  "tau_banking": null
150
150
  },
151
- "median_output_tokens_per_second": 101.998,
152
- "median_time_to_first_token_seconds": 276.865
151
+ "median_output_tokens_per_second": 95.316,
152
+ "median_time_to_first_token_seconds": 443.347
153
153
  },
154
154
  "claude-sonnet-5": {
155
155
  "aa_id": "23c86e4a-c769-43c0-a056-79e3cd15834f",
@@ -176,8 +176,8 @@
176
176
  "tau2": null,
177
177
  "tau_banking": 0.37319587628866
178
178
  },
179
- "median_output_tokens_per_second": 86.276,
180
- "median_time_to_first_token_seconds": 138.497
179
+ "median_output_tokens_per_second": 81.852,
180
+ "median_time_to_first_token_seconds": 120.172
181
181
  },
182
182
  "deepseek-flash": {
183
183
  "aa_id": "dbe7c625-3100-4463-b479-a228c41f75dd",
@@ -204,8 +204,8 @@
204
204
  "tau2": null,
205
205
  "tau_banking": null
206
206
  },
207
- "median_output_tokens_per_second": 225.054,
208
- "median_time_to_first_token_seconds": 0.77
207
+ "median_output_tokens_per_second": 218.778,
208
+ "median_time_to_first_token_seconds": 0.821
209
209
  },
210
210
  "deepseek-v4-pro": {
211
211
  "aa_id": "83173329-c09a-41f1-a028-a282a5f908d7",
@@ -232,8 +232,8 @@
232
232
  "tau2": null,
233
233
  "tau_banking": 0.395876288659794
234
234
  },
235
- "median_output_tokens_per_second": 79.847,
236
- "median_time_to_first_token_seconds": 1.103
235
+ "median_output_tokens_per_second": 91.715,
236
+ "median_time_to_first_token_seconds": 1.148
237
237
  },
238
238
  "gemini-2.5-flash": {
239
239
  "aa_id": "219ed587-60c5-4a48-9517-8480e08d0ca1",
@@ -344,8 +344,8 @@
344
344
  "tau2": 0.956140350877193,
345
345
  "tau_banking": 0.214432989690722
346
346
  },
347
- "median_output_tokens_per_second": 130.627,
348
- "median_time_to_first_token_seconds": 18.476
347
+ "median_output_tokens_per_second": 131.428,
348
+ "median_time_to_first_token_seconds": 20.309
349
349
  },
350
350
  "gemini-3.5-flash": {
351
351
  "aa_id": "0097ebf5-124f-42f6-9463-33b00e711f03",
@@ -456,8 +456,8 @@
456
456
  "tau2": null,
457
457
  "tau_banking": 0.449484536082474
458
458
  },
459
- "median_output_tokens_per_second": 277.514,
460
- "median_time_to_first_token_seconds": 8.773
459
+ "median_output_tokens_per_second": 238.119,
460
+ "median_time_to_first_token_seconds": 10.447
461
461
  },
462
462
  "glm-4.5-air": {
463
463
  "aa_id": "5d303dc9-c027-401f-9803-4e9aa3331007",
@@ -736,8 +736,8 @@
736
736
  "tau2": 0.859649122807018,
737
737
  "tau_banking": null
738
738
  },
739
- "median_output_tokens_per_second": 117.009,
740
- "median_time_to_first_token_seconds": 39.444
739
+ "median_output_tokens_per_second": 113.84,
740
+ "median_time_to_first_token_seconds": 35.088
741
741
  },
742
742
  "gpt-5.4": {
743
743
  "aa_id": "a89c4b28-2d8c-456e-88ea-255fb51fd2b6",
@@ -876,8 +876,8 @@
876
876
  "tau2": null,
877
877
  "tau_banking": 0.311340206185567
878
878
  },
879
- "median_output_tokens_per_second": 102.358,
880
- "median_time_to_first_token_seconds": 22.543
879
+ "median_output_tokens_per_second": 0,
880
+ "median_time_to_first_token_seconds": 0
881
881
  },
882
882
  "gpt-5.6-sol": {
883
883
  "aa_id": "d93edfe8-bf35-49ad-b56e-b18116142a1c",
@@ -904,8 +904,8 @@
904
904
  "tau2": 0.850877192982456,
905
905
  "tau_banking": 0.443298969072165
906
906
  },
907
- "median_output_tokens_per_second": 86.318,
908
- "median_time_to_first_token_seconds": 45.71
907
+ "median_output_tokens_per_second": 0,
908
+ "median_time_to_first_token_seconds": 0
909
909
  },
910
910
  "gpt-5.6-terra": {
911
911
  "aa_id": "bcf8db0a-3bb6-4d82-9516-0f57370c85a6",
@@ -932,8 +932,8 @@
932
932
  "tau2": 0.862573099415205,
933
933
  "tau_banking": 0.402061855670103
934
934
  },
935
- "median_output_tokens_per_second": 86.687,
936
- "median_time_to_first_token_seconds": 143.358
935
+ "median_output_tokens_per_second": 109.005,
936
+ "median_time_to_first_token_seconds": 62.897
937
937
  },
938
938
  "gpt-6-astra": {
939
939
  "aa_id": "2f339a97-9a0d-499a-9cb5-e0db665bfa25",
@@ -960,8 +960,8 @@
960
960
  "tau2": null,
961
961
  "tau_banking": 0.414432989690722
962
962
  },
963
- "median_output_tokens_per_second": 54.12,
964
- "median_time_to_first_token_seconds": 214.045
963
+ "median_output_tokens_per_second": 61.67,
964
+ "median_time_to_first_token_seconds": 179.198
965
965
  },
966
966
  "gpt-6-luna": {
967
967
  "aa_id": "6fb13851-40ce-4bda-ad3f-6b38e0c5daa7",
@@ -988,8 +988,8 @@
988
988
  "tau2": null,
989
989
  "tau_banking": null
990
990
  },
991
- "median_output_tokens_per_second": 125.845,
992
- "median_time_to_first_token_seconds": 127.063
991
+ "median_output_tokens_per_second": 143.33,
992
+ "median_time_to_first_token_seconds": 67.692
993
993
  },
994
994
  "gpt-6-sol": {
995
995
  "aa_id": "c50ea08c-88c0-4eb7-85b8-27f2bbf6d527",
@@ -1016,8 +1016,8 @@
1016
1016
  "tau2": null,
1017
1017
  "tau_banking": null
1018
1018
  },
1019
- "median_output_tokens_per_second": 85.316,
1020
- "median_time_to_first_token_seconds": 98.805
1019
+ "median_output_tokens_per_second": 86.998,
1020
+ "median_time_to_first_token_seconds": 98.304
1021
1021
  },
1022
1022
  "gpt-oss-120b": {
1023
1023
  "aa_id": "f0083258-8646-45b8-8082-7aaf6c2ea82a",
@@ -1044,8 +1044,8 @@
1044
1044
  "tau2": 0.657894736842105,
1045
1045
  "tau_banking": 0.127835051546392
1046
1046
  },
1047
- "median_output_tokens_per_second": 174.466,
1048
- "median_time_to_first_token_seconds": 0.512
1047
+ "median_output_tokens_per_second": 220.222,
1048
+ "median_time_to_first_token_seconds": 0.564
1049
1049
  },
1050
1050
  "gpt-oss-20b": {
1051
1051
  "aa_id": "36f73aaf-d38a-4b56-a2b3-d04d17186910",
@@ -1072,8 +1072,8 @@
1072
1072
  "tau2": 0.60233918128655,
1073
1073
  "tau_banking": 0.0701030927835052
1074
1074
  },
1075
- "median_output_tokens_per_second": 194.912,
1076
- "median_time_to_first_token_seconds": 0.439
1075
+ "median_output_tokens_per_second": 187.455,
1076
+ "median_time_to_first_token_seconds": 0.418
1077
1077
  },
1078
1078
  "grok-4.3": {
1079
1079
  "aa_id": "948892b5-db03-4118-a4a8-ccd51ed871ea",
@@ -1128,8 +1128,8 @@
1128
1128
  "tau2": null,
1129
1129
  "tau_banking": 0.507216494845361
1130
1130
  },
1131
- "median_output_tokens_per_second": 68.306,
1132
- "median_time_to_first_token_seconds": 33.772
1131
+ "median_output_tokens_per_second": 77.163,
1132
+ "median_time_to_first_token_seconds": 22.098
1133
1133
  },
1134
1134
  "grok-4.7": {
1135
1135
  "aa_id": "59627802-1546-422c-9a65-65b61c022d36",
@@ -1156,8 +1156,8 @@
1156
1156
  "tau2": null,
1157
1157
  "tau_banking": null
1158
1158
  },
1159
- "median_output_tokens_per_second": 58.859,
1160
- "median_time_to_first_token_seconds": 0.806
1159
+ "median_output_tokens_per_second": 72.266,
1160
+ "median_time_to_first_token_seconds": 19.841
1161
1161
  },
1162
1162
  "kimi-k2.7-code": {
1163
1163
  "aa_id": "8d0cb231-7303-452c-9923-a9620b948475",
@@ -1184,8 +1184,8 @@
1184
1184
  "tau2": 0.900584795321637,
1185
1185
  "tau_banking": 0.202061855670103
1186
1186
  },
1187
- "median_output_tokens_per_second": 79.482,
1188
- "median_time_to_first_token_seconds": 1.058
1187
+ "median_output_tokens_per_second": 0,
1188
+ "median_time_to_first_token_seconds": 0
1189
1189
  },
1190
1190
  "kimi-k3": {
1191
1191
  "aa_id": "f7d2fc3e-1f7b-405f-818c-07952a4af78f",
@@ -1212,8 +1212,8 @@
1212
1212
  "tau2": null,
1213
1213
  "tau_banking": 0.45979381443299
1214
1214
  },
1215
- "median_output_tokens_per_second": 36.835,
1216
- "median_time_to_first_token_seconds": 3.827
1215
+ "median_output_tokens_per_second": 0,
1216
+ "median_time_to_first_token_seconds": 0
1217
1217
  },
1218
1218
  "mistral-large-3": {
1219
1219
  "aa_id": "4928e950-7f37-4475-b0dc-c5bad781a321",
@@ -1240,8 +1240,8 @@
1240
1240
  "tau2": 0.245614035087719,
1241
1241
  "tau_banking": 0.0577319587628866
1242
1242
  },
1243
- "median_output_tokens_per_second": 73.103,
1244
- "median_time_to_first_token_seconds": 0.698
1243
+ "median_output_tokens_per_second": 78.991,
1244
+ "median_time_to_first_token_seconds": 0.744
1245
1245
  },
1246
1246
  "mistral-medium-3.5": {
1247
1247
  "aa_id": "dd059b25-d82a-4ead-82a4-4adceaaec48b",
@@ -1268,8 +1268,8 @@
1268
1268
  "tau2": 0.941520467836257,
1269
1269
  "tau_banking": 0.150515463917526
1270
1270
  },
1271
- "median_output_tokens_per_second": 151.825,
1272
- "median_time_to_first_token_seconds": 0.635
1271
+ "median_output_tokens_per_second": 170.109,
1272
+ "median_time_to_first_token_seconds": 0.614
1273
1273
  },
1274
1274
  "mistral-small-4": {
1275
1275
  "aa_id": "3fd96175-4ef1-434c-8795-f873aec2abc1",
@@ -1296,8 +1296,8 @@
1296
1296
  "tau2": 0.412280701754386,
1297
1297
  "tau_banking": 0.0494845360824742
1298
1298
  },
1299
- "median_output_tokens_per_second": 159.678,
1300
- "median_time_to_first_token_seconds": 0.561
1299
+ "median_output_tokens_per_second": 174.145,
1300
+ "median_time_to_first_token_seconds": 0.573
1301
1301
  },
1302
1302
  "muse-spark-1.3": {
1303
1303
  "aa_id": "9999672c-b687-4026-9c15-5cef02ff53bb",
@@ -1324,8 +1324,8 @@
1324
1324
  "tau2": null,
1325
1325
  "tau_banking": 0.505154639175258
1326
1326
  },
1327
- "median_output_tokens_per_second": 217.276,
1328
- "median_time_to_first_token_seconds": 20.362
1327
+ "median_output_tokens_per_second": 168.815,
1328
+ "median_time_to_first_token_seconds": 19.256
1329
1329
  },
1330
1330
  "opus-4.7": {
1331
1331
  "aa_id": "e9a09db3-8fd6-41dd-ba2f-20e0a2bff7f2",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": "3",
3
3
  "output_contract_version": 2,
4
- "generated_at_utc": "2026-09-25T22:10:07Z",
4
+ "generated_at_utc": "2026-09-28T22:11:02Z",
5
5
  "source_doc_sha256": {
6
6
  "model-selector.txt": "dd4715585f2f251b6635b65ad3a4cc82eb9ea22b8ed14c494313416a15407c58",
7
7
  "model-tier-cost-scale.md": "9b9f57f5367b553ab11c1116ff69b89eb4d3a9251a7f1caebd813dbdc0c4716a"
@@ -19,6 +19,12 @@ WHEN TO USE
19
19
  - Numbering convention: `phaseNN-roadmap.md` where NN is
20
20
  the phase number (e.g. `phase31-roadmap.md` for
21
21
  Phase 31, `phase04-roadmap.md` for Phase 4).
22
+ - Location: `docs/roadmap/`, beside the project's
23
+ `ROADMAP.md` — every roadmap in one folder. A project
24
+ that keeps its roadmaps git-excluded (e.g. `private/`)
25
+ keeps them there. Relative links resolve from
26
+ `docs/roadmap/` (`../phase{{N}}-qa-findings.md`,
27
+ `../../scripts/…`).
22
28
 
23
29
  PLACEHOLDER SYNTAX
24
30
  - Prose placeholders use {{double-curly}} form so that
@@ -1444,9 +1450,9 @@ that surface has neither dial.
1444
1450
  executable.
1445
1451
  {{last-2}}. docs/phase{{N}}-qa-
1446
1452
  findings.md exists.
1447
- {{last-1}}. docs/phase{{N}}-
1448
- roadmap.md exists (this
1449
- doc).
1453
+ {{last-1}}. docs/roadmap/
1454
+ phase{{N}}-roadmap.md
1455
+ exists (this doc).
1450
1456
  {{last}}. .github/workflows/
1451
1457
  phase-verify.yml matrix
1452
1458
  includes `{{N}}`.
@@ -1644,9 +1650,9 @@ that surface has neither dial.
1644
1650
  <requirement>
1645
1651
  Mark the phase complete in
1646
1652
  the parent project roadmap
1647
- (docs/ROADMAP.md, or
1648
- wherever this project keeps
1649
- it) in the SAME Stage-3
1653
+ (docs/roadmap/ROADMAP.md,
1654
+ beside this file) in the
1655
+ SAME Stage-3
1650
1656
  commit that marks this step
1651
1657
  (Status rule):
1652
1658
  - `### Phase {{N}}` gets
@@ -2029,7 +2035,7 @@ Each item is one bullet, two sentences max. Lead with the
2029
2035
  deferred thing, follow with where / when it lives instead.
2030
2036
  -->
2031
2037
 
2032
- Per [`docs/ROADMAP.md`](ROADMAP.md) Phase {{N}} "Not in
2038
+ Per [`docs/roadmap/ROADMAP.md`](ROADMAP.md) Phase {{N}} "Not in
2033
2039
  scope":
2034
2040
 
2035
2041
  - Item explicitly deferred by the parent roadmap, with a
@@ -2092,9 +2098,9 @@ Example skeleton:
2092
2098
  QA findings rollup, and any tests that need re-running.}}
2093
2099
 
2094
2100
  Audit cross-reference: see
2095
- [`docs/phase{{N}}-website-audit.md`](phase{{N}}-website-audit.md)
2101
+ [`docs/phase{{N}}-website-audit.md`](../phase{{N}}-website-audit.md)
2096
2102
  finding `PHASE{{N}}-AUDIT-NNN`. QA cross-reference: see
2097
- [`docs/phase{{N}}-qa-findings.md`](phase{{N}}-qa-findings.md)
2103
+ [`docs/phase{{N}}-qa-findings.md`](../phase{{N}}-qa-findings.md)
2098
2104
  § "{{Back-patch rollup heading}}".
2099
2105
  =============================================================
2100
2106
  -->
@@ -15,8 +15,8 @@ paid API.
15
15
  | `model-tier-cost-scale.md` | Per-token **prices** and **subscription tiers** — the funding/cost data the selector's access-selection step consumes. |
16
16
  | `settings-display.md` | The **display contract**: how the selector's setting fields map to the real controls each surface exposes (which dials to show, which to omit). Read it before writing any Settings table. |
17
17
  | `user-context.md` | The operator's **subscriptions + API keys + platform preference order** — decides *which platform pays* for each pick. |
18
- | `templates/project-roadmap-template.md` | Skeleton for a whole-project `ROADMAP.md`. |
19
- | `templates/phase-roadmap-template.md` | Skeleton for one `phaseNN-roadmap.md`. |
18
+ | `templates/project-roadmap-template.md` | Skeleton for a whole-project `docs/roadmap/ROADMAP.md`. |
19
+ | `templates/phase-roadmap-template.md` | Skeleton for one `docs/roadmap/phaseNN-roadmap.md`, beside it. |
20
20
  | `prompts/project-roadmap.md` | **Fill-in paste-prompt** that writes `ROADMAP.md` from the project template — refreshes the kit first. |
21
21
  | `prompts/phase-roadmap.md` | **Fill-in paste-prompt** that writes one `phaseNN-roadmap.md` — refreshes the kit first. |
22
22
 
@@ -22,6 +22,12 @@ STYLE RULES (the AI MUST follow)
22
22
  a per-phase exit gate, never a final-phase afterthought —
23
23
  an issue introduced in Phase 2 must be caught in Phase 2,
24
24
  before its work is committed, pushed, or merged.
25
+ - This file lives at `docs/roadmap/ROADMAP.md`, and every
26
+ phase roadmap (`phaseNN-roadmap.md`) is written beside it:
27
+ all roadmaps in one folder, none at the repo root. A
28
+ project that keeps its roadmaps git-excluded (e.g.
29
+ `private/`) keeps them there. Relative links resolve from
30
+ `docs/roadmap/` (`../../README.md`, `../ci.md`).
25
31
  - Every phase carries a one-line metadata badge:
26
32
  **Complexity:** … · **Risk:** … · **Cloud cost:** … ·
27
33
  **Handles sensitive data:** <Yes/No — PII, secrets, auth>
@@ -6,12 +6,12 @@ into a **new** chat in the project and submit. Defaults are shown
6
6
  for every placeholder; delete a bracketed line if it does not
7
7
  apply.
8
8
 
9
- | Placeholder | Meaning | Default |
10
- | -------------------- | ----------------------------------------- | ---------------------------------- |
11
- | `{{N}}` | Phase number (two digits in filenames) | — |
12
- | `{{PROJECT_ROADMAP}}` | The parent project roadmap | `@ROADMAP.md` |
13
- | `{{OUTPUT}}` | Where the phase roadmap is written | `docs/phase{{NN}}-roadmap.md` |
14
- | `{{PRIOR}}` | Previous phase roadmap(s), for continuity | `@docs/phase{{NN-1}}-roadmap.md` |
9
+ | Placeholder | Meaning | Default |
10
+ | -------------------- | ----------------------------------------- | ------------------------------------------ |
11
+ | `{{N}}` | Phase number (two digits in filenames) | — |
12
+ | `{{PROJECT_ROADMAP}}` | The parent project roadmap | `@docs/roadmap/ROADMAP.md` |
13
+ | `{{OUTPUT}}` | Where the phase roadmap is written | `docs/roadmap/phase{{NN}}-roadmap.md` |
14
+ | `{{PRIOR}}` | Previous phase roadmap(s), for continuity | `@docs/roadmap/phase{{NN-1}}-roadmap.md` |
15
15
 
16
16
  ---
17
17
 
@@ -31,6 +31,23 @@ line, a step's Status line sits after its `**Deploys:**` line, or its
31
31
  Settings tables have no `Backup` row, STOP
32
32
  and tell me the kit is stale — do not write the roadmap from it.
33
33
 
34
+ Step 0b — roadmaps live in `docs/roadmap/`: `ROADMAP.md` and every
35
+ `phaseNN-roadmap.md`, together. A project that keeps them git-excluded
36
+ (e.g. `private/`) keeps them there, and the rest of this step does not
37
+ apply: a tracked `ROADMAP.md` beside them is a published copy.
38
+ Otherwise, STOP and tell me to run `/roadmap-refresh` first when this
39
+ project's roadmaps have not moved yet: a `phaseNN-roadmap.md` that git
40
+ does not ignore (committed, or written and not yet committed) sits
41
+ outside `docs/roadmap/`, or `docs/roadmap/` holds no project roadmap
42
+ while this project's roadmap sits elsewhere. `/roadmap-refresh` moves
43
+ them into `docs/roadmap/` and updates every reference to them. Do not
44
+ write a new roadmap beside them. Once the project roadmap is in
45
+ `docs/roadmap/`, any other file named `ROADMAP.md` is a different
46
+ document (a brief's status page, a published copy): leave it alone. A
47
+ project roadmap written before this convention may carry another name
48
+ (e.g. `agentic-bot-farm-v1.md`); it is the file in `docs/roadmap/` the
49
+ phase roadmaps name as their parent.
50
+
34
51
  Step 1 — write `{{OUTPUT}}` from
35
52
  `@planning/templates/phase-roadmap-template.md`, expanding the
36
53
  Phase {{N}} section of `{{PROJECT_ROADMAP}}` into an executable plan.
@@ -9,7 +9,7 @@ apply.
9
9
  | Placeholder | Meaning | Default |
10
10
  | -------------- | -------------------------------------------------------- | --------------------------- |
11
11
  | `{{BRIEF}}` | Where the project is described: files, or inline prose | `@README.md` |
12
- | `{{OUTPUT}}` | Where the roadmap is written | `ROADMAP.md` |
12
+ | `{{OUTPUT}}` | Where the roadmap is written | `docs/roadmap/ROADMAP.md` |
13
13
  | `{{CONSTRAINTS}}` | Hard constraints the roadmap must respect (optional) | — |
14
14
 
15
15
  ---
@@ -29,6 +29,23 @@ completion line, or a `### Phase` section's `**Status:**` line sits
29
29
  after its **Goal:** rather than directly under its heading, STOP and
30
30
  tell me the kit is stale — do not write the roadmap from it.
31
31
 
32
+ Step 0b — roadmaps live in `docs/roadmap/`: `ROADMAP.md` and every
33
+ `phaseNN-roadmap.md`, together. A project that keeps them git-excluded
34
+ (e.g. `private/`) keeps them there, and the rest of this step does not
35
+ apply: a tracked `ROADMAP.md` beside them is a published copy.
36
+ Otherwise, STOP and tell me to run `/roadmap-refresh` first when this
37
+ project's roadmaps have not moved yet: a `phaseNN-roadmap.md` that git
38
+ does not ignore (committed, or written and not yet committed) sits
39
+ outside `docs/roadmap/`, or `docs/roadmap/` holds no project roadmap
40
+ while this project's roadmap sits elsewhere. `/roadmap-refresh` moves
41
+ them into `docs/roadmap/` and updates every reference to them. Do not
42
+ write a new roadmap beside them. Once the project roadmap is in
43
+ `docs/roadmap/`, any other file named `ROADMAP.md` is a different
44
+ document (a brief's status page, a published copy): leave it alone. A
45
+ project roadmap written before this convention may carry another name
46
+ (e.g. `agentic-bot-farm-v1.md`); it is the file in `docs/roadmap/` the
47
+ phase roadmaps name as their parent.
48
+
32
49
  Step 1 — write `{{OUTPUT}}` from
33
50
  `@planning/templates/project-roadmap-template.md`. The project brief
34
51
  is {{BRIEF}}. [Hard constraints: {{CONSTRAINTS}}.] Read the codebase
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "roadmodel"
7
- version = "0.2.45"
7
+ version = "0.2.47"
8
8
  description = "BYO-key CLI that recommends the right AI model, platform, and settings for a prompt."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -6,7 +6,7 @@
6
6
  "endpoint": "https://artificialanalysis.ai/api/v2/data/llms/models",
7
7
  "attribution": "Benchmark data © Artificial Analysis, used under its API terms with attribution."
8
8
  },
9
- "generated_at_utc": "2026-09-25T22:10:15Z",
9
+ "generated_at_utc": "2026-09-28T22:11:10Z",
10
10
  "model_count": 50,
11
11
  "unmapped": [],
12
12
  "missing_slugs": [],
@@ -36,8 +36,8 @@
36
36
  "tau2": 0.546783625730994,
37
37
  "tau_banking": 0.0927835051546392
38
38
  },
39
- "median_output_tokens_per_second": 112.331,
40
- "median_time_to_first_token_seconds": 14.822
39
+ "median_output_tokens_per_second": 108.201,
40
+ "median_time_to_first_token_seconds": 13.415
41
41
  },
42
42
  "claude-fable-5": {
43
43
  "aa_id": "cd55210d-358e-4df1-ba9c-9acb5f186cc9",
@@ -92,8 +92,8 @@
92
92
  "tau2": null,
93
93
  "tau_banking": 0.472164948453608
94
94
  },
95
- "median_output_tokens_per_second": 71.496,
96
- "median_time_to_first_token_seconds": 137.695
95
+ "median_output_tokens_per_second": 68.949,
96
+ "median_time_to_first_token_seconds": 119.525
97
97
  },
98
98
  "claude-opus-5": {
99
99
  "aa_id": "b8fc61f7-5e9a-49e6-8547-6ac56db24627",
@@ -120,8 +120,8 @@
120
120
  "tau2": null,
121
121
  "tau_banking": 0.420618556701031
122
122
  },
123
- "median_output_tokens_per_second": 67.509,
124
- "median_time_to_first_token_seconds": 34.244
123
+ "median_output_tokens_per_second": 0,
124
+ "median_time_to_first_token_seconds": 0
125
125
  },
126
126
  "claude-opus-5-5": {
127
127
  "aa_id": "2f3c4dc9-a450-4303-8697-0237257cf08f",
@@ -148,8 +148,8 @@
148
148
  "tau2": null,
149
149
  "tau_banking": null
150
150
  },
151
- "median_output_tokens_per_second": 101.998,
152
- "median_time_to_first_token_seconds": 276.865
151
+ "median_output_tokens_per_second": 95.316,
152
+ "median_time_to_first_token_seconds": 443.347
153
153
  },
154
154
  "claude-sonnet-5": {
155
155
  "aa_id": "23c86e4a-c769-43c0-a056-79e3cd15834f",
@@ -176,8 +176,8 @@
176
176
  "tau2": null,
177
177
  "tau_banking": 0.37319587628866
178
178
  },
179
- "median_output_tokens_per_second": 86.276,
180
- "median_time_to_first_token_seconds": 138.497
179
+ "median_output_tokens_per_second": 81.852,
180
+ "median_time_to_first_token_seconds": 120.172
181
181
  },
182
182
  "deepseek-flash": {
183
183
  "aa_id": "dbe7c625-3100-4463-b479-a228c41f75dd",
@@ -204,8 +204,8 @@
204
204
  "tau2": null,
205
205
  "tau_banking": null
206
206
  },
207
- "median_output_tokens_per_second": 225.054,
208
- "median_time_to_first_token_seconds": 0.77
207
+ "median_output_tokens_per_second": 218.778,
208
+ "median_time_to_first_token_seconds": 0.821
209
209
  },
210
210
  "deepseek-v4-pro": {
211
211
  "aa_id": "83173329-c09a-41f1-a028-a282a5f908d7",
@@ -232,8 +232,8 @@
232
232
  "tau2": null,
233
233
  "tau_banking": 0.395876288659794
234
234
  },
235
- "median_output_tokens_per_second": 79.847,
236
- "median_time_to_first_token_seconds": 1.103
235
+ "median_output_tokens_per_second": 91.715,
236
+ "median_time_to_first_token_seconds": 1.148
237
237
  },
238
238
  "gemini-2.5-flash": {
239
239
  "aa_id": "219ed587-60c5-4a48-9517-8480e08d0ca1",
@@ -344,8 +344,8 @@
344
344
  "tau2": 0.956140350877193,
345
345
  "tau_banking": 0.214432989690722
346
346
  },
347
- "median_output_tokens_per_second": 130.627,
348
- "median_time_to_first_token_seconds": 18.476
347
+ "median_output_tokens_per_second": 131.428,
348
+ "median_time_to_first_token_seconds": 20.309
349
349
  },
350
350
  "gemini-3.5-flash": {
351
351
  "aa_id": "0097ebf5-124f-42f6-9463-33b00e711f03",
@@ -456,8 +456,8 @@
456
456
  "tau2": null,
457
457
  "tau_banking": 0.449484536082474
458
458
  },
459
- "median_output_tokens_per_second": 277.514,
460
- "median_time_to_first_token_seconds": 8.773
459
+ "median_output_tokens_per_second": 238.119,
460
+ "median_time_to_first_token_seconds": 10.447
461
461
  },
462
462
  "glm-4.5-air": {
463
463
  "aa_id": "5d303dc9-c027-401f-9803-4e9aa3331007",
@@ -736,8 +736,8 @@
736
736
  "tau2": 0.859649122807018,
737
737
  "tau_banking": null
738
738
  },
739
- "median_output_tokens_per_second": 117.009,
740
- "median_time_to_first_token_seconds": 39.444
739
+ "median_output_tokens_per_second": 113.84,
740
+ "median_time_to_first_token_seconds": 35.088
741
741
  },
742
742
  "gpt-5.4": {
743
743
  "aa_id": "a89c4b28-2d8c-456e-88ea-255fb51fd2b6",
@@ -876,8 +876,8 @@
876
876
  "tau2": null,
877
877
  "tau_banking": 0.311340206185567
878
878
  },
879
- "median_output_tokens_per_second": 102.358,
880
- "median_time_to_first_token_seconds": 22.543
879
+ "median_output_tokens_per_second": 0,
880
+ "median_time_to_first_token_seconds": 0
881
881
  },
882
882
  "gpt-5.6-sol": {
883
883
  "aa_id": "d93edfe8-bf35-49ad-b56e-b18116142a1c",
@@ -904,8 +904,8 @@
904
904
  "tau2": 0.850877192982456,
905
905
  "tau_banking": 0.443298969072165
906
906
  },
907
- "median_output_tokens_per_second": 86.318,
908
- "median_time_to_first_token_seconds": 45.71
907
+ "median_output_tokens_per_second": 0,
908
+ "median_time_to_first_token_seconds": 0
909
909
  },
910
910
  "gpt-5.6-terra": {
911
911
  "aa_id": "bcf8db0a-3bb6-4d82-9516-0f57370c85a6",
@@ -932,8 +932,8 @@
932
932
  "tau2": 0.862573099415205,
933
933
  "tau_banking": 0.402061855670103
934
934
  },
935
- "median_output_tokens_per_second": 86.687,
936
- "median_time_to_first_token_seconds": 143.358
935
+ "median_output_tokens_per_second": 109.005,
936
+ "median_time_to_first_token_seconds": 62.897
937
937
  },
938
938
  "gpt-6-astra": {
939
939
  "aa_id": "2f339a97-9a0d-499a-9cb5-e0db665bfa25",
@@ -960,8 +960,8 @@
960
960
  "tau2": null,
961
961
  "tau_banking": 0.414432989690722
962
962
  },
963
- "median_output_tokens_per_second": 54.12,
964
- "median_time_to_first_token_seconds": 214.045
963
+ "median_output_tokens_per_second": 61.67,
964
+ "median_time_to_first_token_seconds": 179.198
965
965
  },
966
966
  "gpt-6-luna": {
967
967
  "aa_id": "6fb13851-40ce-4bda-ad3f-6b38e0c5daa7",
@@ -988,8 +988,8 @@
988
988
  "tau2": null,
989
989
  "tau_banking": null
990
990
  },
991
- "median_output_tokens_per_second": 125.845,
992
- "median_time_to_first_token_seconds": 127.063
991
+ "median_output_tokens_per_second": 143.33,
992
+ "median_time_to_first_token_seconds": 67.692
993
993
  },
994
994
  "gpt-6-sol": {
995
995
  "aa_id": "c50ea08c-88c0-4eb7-85b8-27f2bbf6d527",
@@ -1016,8 +1016,8 @@
1016
1016
  "tau2": null,
1017
1017
  "tau_banking": null
1018
1018
  },
1019
- "median_output_tokens_per_second": 85.316,
1020
- "median_time_to_first_token_seconds": 98.805
1019
+ "median_output_tokens_per_second": 86.998,
1020
+ "median_time_to_first_token_seconds": 98.304
1021
1021
  },
1022
1022
  "gpt-oss-120b": {
1023
1023
  "aa_id": "f0083258-8646-45b8-8082-7aaf6c2ea82a",
@@ -1044,8 +1044,8 @@
1044
1044
  "tau2": 0.657894736842105,
1045
1045
  "tau_banking": 0.127835051546392
1046
1046
  },
1047
- "median_output_tokens_per_second": 174.466,
1048
- "median_time_to_first_token_seconds": 0.512
1047
+ "median_output_tokens_per_second": 220.222,
1048
+ "median_time_to_first_token_seconds": 0.564
1049
1049
  },
1050
1050
  "gpt-oss-20b": {
1051
1051
  "aa_id": "36f73aaf-d38a-4b56-a2b3-d04d17186910",
@@ -1072,8 +1072,8 @@
1072
1072
  "tau2": 0.60233918128655,
1073
1073
  "tau_banking": 0.0701030927835052
1074
1074
  },
1075
- "median_output_tokens_per_second": 194.912,
1076
- "median_time_to_first_token_seconds": 0.439
1075
+ "median_output_tokens_per_second": 187.455,
1076
+ "median_time_to_first_token_seconds": 0.418
1077
1077
  },
1078
1078
  "grok-4.3": {
1079
1079
  "aa_id": "948892b5-db03-4118-a4a8-ccd51ed871ea",
@@ -1128,8 +1128,8 @@
1128
1128
  "tau2": null,
1129
1129
  "tau_banking": 0.507216494845361
1130
1130
  },
1131
- "median_output_tokens_per_second": 68.306,
1132
- "median_time_to_first_token_seconds": 33.772
1131
+ "median_output_tokens_per_second": 77.163,
1132
+ "median_time_to_first_token_seconds": 22.098
1133
1133
  },
1134
1134
  "grok-4.7": {
1135
1135
  "aa_id": "59627802-1546-422c-9a65-65b61c022d36",
@@ -1156,8 +1156,8 @@
1156
1156
  "tau2": null,
1157
1157
  "tau_banking": null
1158
1158
  },
1159
- "median_output_tokens_per_second": 58.859,
1160
- "median_time_to_first_token_seconds": 0.806
1159
+ "median_output_tokens_per_second": 72.266,
1160
+ "median_time_to_first_token_seconds": 19.841
1161
1161
  },
1162
1162
  "kimi-k2.7-code": {
1163
1163
  "aa_id": "8d0cb231-7303-452c-9923-a9620b948475",
@@ -1184,8 +1184,8 @@
1184
1184
  "tau2": 0.900584795321637,
1185
1185
  "tau_banking": 0.202061855670103
1186
1186
  },
1187
- "median_output_tokens_per_second": 79.482,
1188
- "median_time_to_first_token_seconds": 1.058
1187
+ "median_output_tokens_per_second": 0,
1188
+ "median_time_to_first_token_seconds": 0
1189
1189
  },
1190
1190
  "kimi-k3": {
1191
1191
  "aa_id": "f7d2fc3e-1f7b-405f-818c-07952a4af78f",
@@ -1212,8 +1212,8 @@
1212
1212
  "tau2": null,
1213
1213
  "tau_banking": 0.45979381443299
1214
1214
  },
1215
- "median_output_tokens_per_second": 36.835,
1216
- "median_time_to_first_token_seconds": 3.827
1215
+ "median_output_tokens_per_second": 0,
1216
+ "median_time_to_first_token_seconds": 0
1217
1217
  },
1218
1218
  "mistral-large-3": {
1219
1219
  "aa_id": "4928e950-7f37-4475-b0dc-c5bad781a321",
@@ -1240,8 +1240,8 @@
1240
1240
  "tau2": 0.245614035087719,
1241
1241
  "tau_banking": 0.0577319587628866
1242
1242
  },
1243
- "median_output_tokens_per_second": 73.103,
1244
- "median_time_to_first_token_seconds": 0.698
1243
+ "median_output_tokens_per_second": 78.991,
1244
+ "median_time_to_first_token_seconds": 0.744
1245
1245
  },
1246
1246
  "mistral-medium-3.5": {
1247
1247
  "aa_id": "dd059b25-d82a-4ead-82a4-4adceaaec48b",
@@ -1268,8 +1268,8 @@
1268
1268
  "tau2": 0.941520467836257,
1269
1269
  "tau_banking": 0.150515463917526
1270
1270
  },
1271
- "median_output_tokens_per_second": 151.825,
1272
- "median_time_to_first_token_seconds": 0.635
1271
+ "median_output_tokens_per_second": 170.109,
1272
+ "median_time_to_first_token_seconds": 0.614
1273
1273
  },
1274
1274
  "mistral-small-4": {
1275
1275
  "aa_id": "3fd96175-4ef1-434c-8795-f873aec2abc1",
@@ -1296,8 +1296,8 @@
1296
1296
  "tau2": 0.412280701754386,
1297
1297
  "tau_banking": 0.0494845360824742
1298
1298
  },
1299
- "median_output_tokens_per_second": 159.678,
1300
- "median_time_to_first_token_seconds": 0.561
1299
+ "median_output_tokens_per_second": 174.145,
1300
+ "median_time_to_first_token_seconds": 0.573
1301
1301
  },
1302
1302
  "muse-spark-1.3": {
1303
1303
  "aa_id": "9999672c-b687-4026-9c15-5cef02ff53bb",
@@ -1324,8 +1324,8 @@
1324
1324
  "tau2": null,
1325
1325
  "tau_banking": 0.505154639175258
1326
1326
  },
1327
- "median_output_tokens_per_second": 217.276,
1328
- "median_time_to_first_token_seconds": 20.362
1327
+ "median_output_tokens_per_second": 168.815,
1328
+ "median_time_to_first_token_seconds": 19.256
1329
1329
  },
1330
1330
  "opus-4.7": {
1331
1331
  "aa_id": "e9a09db3-8fd6-41dd-ba2f-20e0a2bff7f2",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": "3",
3
3
  "output_contract_version": 2,
4
- "generated_at_utc": "2026-09-25T22:10:07Z",
4
+ "generated_at_utc": "2026-09-28T22:11:02Z",
5
5
  "source_doc_sha256": {
6
6
  "model-selector.txt": "dd4715585f2f251b6635b65ad3a4cc82eb9ea22b8ed14c494313416a15407c58",
7
7
  "model-tier-cost-scale.md": "9b9f57f5367b553ab11c1116ff69b89eb4d3a9251a7f1caebd813dbdc0c4716a"
@@ -19,6 +19,12 @@ WHEN TO USE
19
19
  - Numbering convention: `phaseNN-roadmap.md` where NN is
20
20
  the phase number (e.g. `phase31-roadmap.md` for
21
21
  Phase 31, `phase04-roadmap.md` for Phase 4).
22
+ - Location: `docs/roadmap/`, beside the project's
23
+ `ROADMAP.md` — every roadmap in one folder. A project
24
+ that keeps its roadmaps git-excluded (e.g. `private/`)
25
+ keeps them there. Relative links resolve from
26
+ `docs/roadmap/` (`../phase{{N}}-qa-findings.md`,
27
+ `../../scripts/…`).
22
28
 
23
29
  PLACEHOLDER SYNTAX
24
30
  - Prose placeholders use {{double-curly}} form so that
@@ -1444,9 +1450,9 @@ that surface has neither dial.
1444
1450
  executable.
1445
1451
  {{last-2}}. docs/phase{{N}}-qa-
1446
1452
  findings.md exists.
1447
- {{last-1}}. docs/phase{{N}}-
1448
- roadmap.md exists (this
1449
- doc).
1453
+ {{last-1}}. docs/roadmap/
1454
+ phase{{N}}-roadmap.md
1455
+ exists (this doc).
1450
1456
  {{last}}. .github/workflows/
1451
1457
  phase-verify.yml matrix
1452
1458
  includes `{{N}}`.
@@ -1644,9 +1650,9 @@ that surface has neither dial.
1644
1650
  <requirement>
1645
1651
  Mark the phase complete in
1646
1652
  the parent project roadmap
1647
- (docs/ROADMAP.md, or
1648
- wherever this project keeps
1649
- it) in the SAME Stage-3
1653
+ (docs/roadmap/ROADMAP.md,
1654
+ beside this file) in the
1655
+ SAME Stage-3
1650
1656
  commit that marks this step
1651
1657
  (Status rule):
1652
1658
  - `### Phase {{N}}` gets
@@ -2029,7 +2035,7 @@ Each item is one bullet, two sentences max. Lead with the
2029
2035
  deferred thing, follow with where / when it lives instead.
2030
2036
  -->
2031
2037
 
2032
- Per [`docs/ROADMAP.md`](ROADMAP.md) Phase {{N}} "Not in
2038
+ Per [`docs/roadmap/ROADMAP.md`](ROADMAP.md) Phase {{N}} "Not in
2033
2039
  scope":
2034
2040
 
2035
2041
  - Item explicitly deferred by the parent roadmap, with a
@@ -2092,9 +2098,9 @@ Example skeleton:
2092
2098
  QA findings rollup, and any tests that need re-running.}}
2093
2099
 
2094
2100
  Audit cross-reference: see
2095
- [`docs/phase{{N}}-website-audit.md`](phase{{N}}-website-audit.md)
2101
+ [`docs/phase{{N}}-website-audit.md`](../phase{{N}}-website-audit.md)
2096
2102
  finding `PHASE{{N}}-AUDIT-NNN`. QA cross-reference: see
2097
- [`docs/phase{{N}}-qa-findings.md`](phase{{N}}-qa-findings.md)
2103
+ [`docs/phase{{N}}-qa-findings.md`](../phase{{N}}-qa-findings.md)
2098
2104
  § "{{Back-patch rollup heading}}".
2099
2105
  =============================================================
2100
2106
  -->
@@ -15,8 +15,8 @@ paid API.
15
15
  | `model-tier-cost-scale.md` | Per-token **prices** and **subscription tiers** — the funding/cost data the selector's access-selection step consumes. |
16
16
  | `settings-display.md` | The **display contract**: how the selector's setting fields map to the real controls each surface exposes (which dials to show, which to omit). Read it before writing any Settings table. |
17
17
  | `user-context.md` | The operator's **subscriptions + API keys + platform preference order** — decides *which platform pays* for each pick. |
18
- | `templates/project-roadmap-template.md` | Skeleton for a whole-project `ROADMAP.md`. |
19
- | `templates/phase-roadmap-template.md` | Skeleton for one `phaseNN-roadmap.md`. |
18
+ | `templates/project-roadmap-template.md` | Skeleton for a whole-project `docs/roadmap/ROADMAP.md`. |
19
+ | `templates/phase-roadmap-template.md` | Skeleton for one `docs/roadmap/phaseNN-roadmap.md`, beside it. |
20
20
  | `prompts/project-roadmap.md` | **Fill-in paste-prompt** that writes `ROADMAP.md` from the project template — refreshes the kit first. |
21
21
  | `prompts/phase-roadmap.md` | **Fill-in paste-prompt** that writes one `phaseNN-roadmap.md` — refreshes the kit first. |
22
22
 
@@ -22,6 +22,12 @@ STYLE RULES (the AI MUST follow)
22
22
  a per-phase exit gate, never a final-phase afterthought —
23
23
  an issue introduced in Phase 2 must be caught in Phase 2,
24
24
  before its work is committed, pushed, or merged.
25
+ - This file lives at `docs/roadmap/ROADMAP.md`, and every
26
+ phase roadmap (`phaseNN-roadmap.md`) is written beside it:
27
+ all roadmaps in one folder, none at the repo root. A
28
+ project that keeps its roadmaps git-excluded (e.g.
29
+ `private/`) keeps them there. Relative links resolve from
30
+ `docs/roadmap/` (`../../README.md`, `../ci.md`).
25
31
  - Every phase carries a one-line metadata badge:
26
32
  **Complexity:** … · **Risk:** … · **Cloud cost:** … ·
27
33
  **Handles sensitive data:** <Yes/No — PII, secrets, auth>
@@ -6,12 +6,12 @@ into a **new** chat in the project and submit. Defaults are shown
6
6
  for every placeholder; delete a bracketed line if it does not
7
7
  apply.
8
8
 
9
- | Placeholder | Meaning | Default |
10
- | -------------------- | ----------------------------------------- | ---------------------------------- |
11
- | `{{N}}` | Phase number (two digits in filenames) | — |
12
- | `{{PROJECT_ROADMAP}}` | The parent project roadmap | `@ROADMAP.md` |
13
- | `{{OUTPUT}}` | Where the phase roadmap is written | `docs/phase{{NN}}-roadmap.md` |
14
- | `{{PRIOR}}` | Previous phase roadmap(s), for continuity | `@docs/phase{{NN-1}}-roadmap.md` |
9
+ | Placeholder | Meaning | Default |
10
+ | -------------------- | ----------------------------------------- | ------------------------------------------ |
11
+ | `{{N}}` | Phase number (two digits in filenames) | — |
12
+ | `{{PROJECT_ROADMAP}}` | The parent project roadmap | `@docs/roadmap/ROADMAP.md` |
13
+ | `{{OUTPUT}}` | Where the phase roadmap is written | `docs/roadmap/phase{{NN}}-roadmap.md` |
14
+ | `{{PRIOR}}` | Previous phase roadmap(s), for continuity | `@docs/roadmap/phase{{NN-1}}-roadmap.md` |
15
15
 
16
16
  ---
17
17
 
@@ -31,6 +31,23 @@ line, a step's Status line sits after its `**Deploys:**` line, or its
31
31
  Settings tables have no `Backup` row, STOP
32
32
  and tell me the kit is stale — do not write the roadmap from it.
33
33
 
34
+ Step 0b — roadmaps live in `docs/roadmap/`: `ROADMAP.md` and every
35
+ `phaseNN-roadmap.md`, together. A project that keeps them git-excluded
36
+ (e.g. `private/`) keeps them there, and the rest of this step does not
37
+ apply: a tracked `ROADMAP.md` beside them is a published copy.
38
+ Otherwise, STOP and tell me to run `/roadmap-refresh` first when this
39
+ project's roadmaps have not moved yet: a `phaseNN-roadmap.md` that git
40
+ does not ignore (committed, or written and not yet committed) sits
41
+ outside `docs/roadmap/`, or `docs/roadmap/` holds no project roadmap
42
+ while this project's roadmap sits elsewhere. `/roadmap-refresh` moves
43
+ them into `docs/roadmap/` and updates every reference to them. Do not
44
+ write a new roadmap beside them. Once the project roadmap is in
45
+ `docs/roadmap/`, any other file named `ROADMAP.md` is a different
46
+ document (a brief's status page, a published copy): leave it alone. A
47
+ project roadmap written before this convention may carry another name
48
+ (e.g. `agentic-bot-farm-v1.md`); it is the file in `docs/roadmap/` the
49
+ phase roadmaps name as their parent.
50
+
34
51
  Step 1 — write `{{OUTPUT}}` from
35
52
  `@planning/templates/phase-roadmap-template.md`, expanding the
36
53
  Phase {{N}} section of `{{PROJECT_ROADMAP}}` into an executable plan.
@@ -9,7 +9,7 @@ apply.
9
9
  | Placeholder | Meaning | Default |
10
10
  | -------------- | -------------------------------------------------------- | --------------------------- |
11
11
  | `{{BRIEF}}` | Where the project is described: files, or inline prose | `@README.md` |
12
- | `{{OUTPUT}}` | Where the roadmap is written | `ROADMAP.md` |
12
+ | `{{OUTPUT}}` | Where the roadmap is written | `docs/roadmap/ROADMAP.md` |
13
13
  | `{{CONSTRAINTS}}` | Hard constraints the roadmap must respect (optional) | — |
14
14
 
15
15
  ---
@@ -29,6 +29,23 @@ completion line, or a `### Phase` section's `**Status:**` line sits
29
29
  after its **Goal:** rather than directly under its heading, STOP and
30
30
  tell me the kit is stale — do not write the roadmap from it.
31
31
 
32
+ Step 0b — roadmaps live in `docs/roadmap/`: `ROADMAP.md` and every
33
+ `phaseNN-roadmap.md`, together. A project that keeps them git-excluded
34
+ (e.g. `private/`) keeps them there, and the rest of this step does not
35
+ apply: a tracked `ROADMAP.md` beside them is a published copy.
36
+ Otherwise, STOP and tell me to run `/roadmap-refresh` first when this
37
+ project's roadmaps have not moved yet: a `phaseNN-roadmap.md` that git
38
+ does not ignore (committed, or written and not yet committed) sits
39
+ outside `docs/roadmap/`, or `docs/roadmap/` holds no project roadmap
40
+ while this project's roadmap sits elsewhere. `/roadmap-refresh` moves
41
+ them into `docs/roadmap/` and updates every reference to them. Do not
42
+ write a new roadmap beside them. Once the project roadmap is in
43
+ `docs/roadmap/`, any other file named `ROADMAP.md` is a different
44
+ document (a brief's status page, a published copy): leave it alone. A
45
+ project roadmap written before this convention may carry another name
46
+ (e.g. `agentic-bot-farm-v1.md`); it is the file in `docs/roadmap/` the
47
+ phase roadmaps name as their parent.
48
+
32
49
  Step 1 — write `{{OUTPUT}}` from
33
50
  `@planning/templates/project-roadmap-template.md`. The project brief
34
51
  is {{BRIEF}}. [Hard constraints: {{CONSTRAINTS}}.] Read the codebase
@@ -1,2 +1,2 @@
1
1
  # src/roadmodel/__init__.py
2
- __version__ = "0.2.45"
2
+ __version__ = "0.2.47"
File without changes
File without changes
File without changes
File without changes
File without changes