@yahyahammad/venastine 0.3.8 → 0.3.10

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 (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
@@ -1,282 +1,282 @@
1
- """
2
- project_init/config_files.py
3
-
4
- ROADMAP_v2 §24 (I14-I17): WHAT `/init --config` writes into `.venastine/`,
5
- and what it deliberately leaves out.
6
-
7
- Data and pure rendering only -- no filesystem, no model call, no decision
8
- about when to write. The same split as doc_sets.py and for the same
9
- reason: the templates can be asserted against directly, and the one place
10
- that decides whether anything is written stays generator.py.
11
-
12
- THE FILE CANNOT EXPLAIN ITSELF, SO THIS ONE HAS TO. `_validate_settings`
13
- raises on an unknown key (§14, amendment 1), so settings.json has no
14
- comment syntax, no `$schema` line, and no way to carry a key that is
15
- present but inert. Every line the scaffold writes is a live setting.
16
-
17
- WHICH MAKES "THE DEFAULT" A THING SOME KEYS CANNOT SAY. A key read by
18
- PRESENCE rather than by value is not restated by writing its default --
19
- it is decided. Six were found that way, by writing each key alone into a
20
- trusted project and diffing the observable state against a project with
21
- no file at all:
22
-
23
- default_provider, default_model the /model store's staleness key.
24
- `_startup_pair`: "edit either, ADD
25
- either, or remove either and the
26
- file re-asserts itself" -- so
27
- scaffolding them discards a
28
- remembered choice
29
- effort `_effort_named` flips False->True,
30
- and its own comment says a
31
- default-derived level must not fire
32
- the mount-time probe (#138)
33
- compaction.trigger_tokens `_trigger_is_configured()` is a
34
- presence test, and presence makes
35
- the fixed number outrank the
36
- window-derived trigger -- invisibly,
37
- since the file only says 40000
38
- ensemble_mode `config.ENSEMBLE_MODE if x is None`
39
- research.subagent_review `if persisted is not None` -- both
40
- of these freeze today's config.py
41
- value against a later edit of it
42
-
43
- All six are in OMITTED. What survives is a scaffold that changes NOTHING
44
- until a human edits it, which is the only claim "a template of defaults"
45
- can honestly make, and `test_the_scaffolded_settings_file_changes_nothing`
46
- asserts it over the whole observable set rather than key by key.
47
-
48
- THE DEFAULTS ARE READ, NOT RETYPED (I15) -- `config_loader.shipped_defaults()`
49
- and `config.py`'s own constants. A template that quotes a default is a
50
- second copy of it, in the one file that has to be right the first time or
51
- the harness will not start.
52
-
53
- WHAT IT WRITES IS STILL NOT NEUTRAL BETWEEN TIERS. A project settings.json
54
- beats the user's (D29) by PRESENCE and not by difference, so even this file
55
- takes every key it names away from `~/.config/venastine/settings.json`.
56
- `shadowed()` is how the command says so; generator.py renders it.
57
- """
58
-
59
- from __future__ import annotations
60
-
61
- import config
62
- from core import config_loader
63
-
64
- SETTINGS_FILENAME = "settings.json"
65
- MCP_FILENAME = "mcp.json"
66
-
67
- #: Tier directories the loader looks for under `.venastine/`, created
68
- #: EMPTY. They carry nothing into the trust hash -- `content_files()`
69
- #: walks files, and a directory name never enters the digest -- and git
70
- #: does not track an empty directory, so a project that commits its
71
- #: `.venastine/` does not ship them. They are a hint on the author's
72
- #: machine about where a project-tier agent or skill goes, and nothing
73
- #: more. Named here rather than in config_loader because the loader's
74
- #: `_tier_dirs` derives them from the `kind` argument it is called with,
75
- #: which is not a list anything can read.
76
- TIER_DIRS = ("agents", "skills")
77
-
78
- #: Settings the loader knows and this file does NOT write, each with the
79
- #: reason. Dotted `section.key` for a nested one.
80
- #:
81
- #: A SILENT OMISSION IS INDISTINGUISHABLE FROM AN OVERSIGHT, which is why
82
- #: this is data with prose in it rather than a set: the next person to
83
- #: read the scaffold and find `effort` missing should find out why here,
84
- #: and `test_the_template_omits_only_what_it_can_name` keeps the entries
85
- #: honest by requiring every one of them to still exist in the loader's
86
- #: vocabulary.
87
- OMITTED = {
88
- "default_provider":
89
- "presence, not value, is the /model store's staleness key -- "
90
- "adding this to a settings.json discards a remembered choice, "
91
- "which _startup_pair's own docstring says in as many words",
92
- "default_model":
93
- "the other half of the same staleness key; the pair is compared "
94
- "and restored whole or not at all",
95
- "effort":
96
- "sets _effort_named, which exists to tell a level a HUMAN chose "
97
- "from one derived from a default. Writing it makes every launch "
98
- "probe the provider's effort table, and warn on the models that "
99
- "have none (#138's healthy-mount silence)",
100
- "ensemble_n":
101
- "vestigial -- the roster's length decides the count now, and the "
102
- "loader warns when this is set, so a template carrying it would "
103
- "ship that warning to everyone who ran the command",
104
- "confidence.disagreement_penalty_factor":
105
- "retired by ROADMAP_v3 §90 for the same reason as ensemble_n: "
106
- "disagreement routes a claim to be checked and subtracts nothing, "
107
- "and the loader warns when this is set",
108
- "ensemble_mode":
109
- "resolved as `config.ENSEMBLE_MODE if value is None`, so writing "
110
- "`false` is not a restatement of the default but a decision to "
111
- "outrank whatever config.py says later",
112
- "compaction.trigger_tokens":
113
- "_trigger_is_configured() is a PRESENCE test: the window-derived "
114
- "trigger only applies while no human has named a number. Writing "
115
- "the default pins compaction to it for every model, and the file "
116
- "gives no hint that it did -- on a large-context model that is a "
117
- "much earlier fold with nothing on screen to explain it",
118
- "research.subagent_review":
119
- "same `is not None` shape as ensemble_mode: an explicit false "
120
- "beats config.SUBAGENT_REVIEW rather than deferring to it",
121
- "tui.theme":
122
- "no shipped default to write -- absent, _startup_theme() resolves "
123
- "one -- and an invented value would outrank a theme the user "
124
- "picked with /theme, for every session in this project",
125
- "tui.effort":
126
- "no shipped default either, and it feeds the same _effort_named "
127
- "flag as the top-level key above",
128
- "source_scoring.similarity_floor":
129
- "defaults to None against a `float` schema, so writing the "
130
- "default IS a startup error. None here means the per-model table "
131
- "decides, which no JSON value can say",
132
- "source_scoring.similarity_ceiling":
133
- "the other half of the same per-model pair",
134
- }
135
-
136
-
137
- def _defaults() -> dict:
138
- """Every setting that has a shipped default, at that default.
139
-
140
- Before OMITTED is applied, so the removal below is visible as a
141
- removal. `tui.theme` and `tui.effort` are the two entries in OMITTED
142
- that cannot appear here at all -- there is no default to produce --
143
- and the test asserts on the rendered key set rather than on which
144
- mechanism excluded a key, so both routes are covered.
145
-
146
- The three `tui` values are the only ones typed out rather than read.
147
- config.py holds no TUI values on purpose (the note beside `animations`
148
- in tui/app.py), so their defaults are literals in `VenastineApp.__init__`
149
- and there is no constant to import without dragging textual into
150
- project_init. `test_the_scaffolded_settings_file_changes_nothing`
151
- drives the real app, so a drift here fails there rather than here.
152
- """
153
- from core.loop import DEFAULT_PROVIDER
154
-
155
- shipped = config_loader.shipped_defaults()
156
- confidence = dict(shipped["confidence"])
157
- # JSON HAS NO NULL KEY. `grounding_weights` carries one -- the weight
158
- # for a claim with no grounding status at all -- and it serialises as
159
- # the string "null", which `_apply_grounding_weights` then rejects
160
- # against GROUNDING_STATUSES and logs about on every launch. The three
161
- # named statuses ARE settable and the None one is not, by that
162
- # vocabulary's own definition, so the template emits exactly the keys
163
- # the loader will take. Read from the loader's re-export rather than
164
- # retyped, like everything else here.
165
- confidence["grounding_weights"] = {
166
- status: weight
167
- for status, weight in confidence["grounding_weights"].items()
168
- if status in config_loader.GROUNDING_STATUSES
169
- }
170
- return {
171
- "default_provider": DEFAULT_PROVIDER,
172
- "default_model": config.MODEL_NAME,
173
- "effort": config.DEFAULT_EFFORT,
174
- "max_token_budget": None,
175
- "ensemble_mode": config.ENSEMBLE_MODE,
176
- "compaction": shipped["compaction"],
177
- "tui": {
178
- "animations": True,
179
- "show_thinking": True,
180
- "todo_position": "side",
181
- },
182
- "research": {
183
- # The vocabulary's first entry is the default, and
184
- # _KNOWN_RESEARCH says so beside it. Read rather than typed
185
- # for the same reason as everything else here.
186
- "approval_mode": config_loader.RESEARCH_APPROVAL_MODES[0],
187
- "subagent_review": config.SUBAGENT_REVIEW,
188
- },
189
- "confidence": confidence,
190
- "source_scoring": shipped["source_scoring"],
191
- }
192
-
193
-
194
- def _coerce(section: str, key: str, value):
195
- """A value declared `float` is emitted as one.
196
-
197
- Every confidence knob is a genuine float today, so this changes no
198
- byte of the current template. It is here because the failure it
199
- prevents is silent at the wrong end: a future default landing as an
200
- int (0.0 written as 0, say) makes `_type_ok(0, float)` False, and the
201
- scaffold this file exists to produce becomes a file that stops the
202
- harness from starting. Cheaper to make impossible than to catch.
203
- """
204
- known = config_loader._NESTED_SETTINGS.get(section)
205
- expected = (known or config_loader._KNOWN_SETTINGS).get(key)
206
- if expected is float and isinstance(value, (int, float)):
207
- return float(value)
208
- return value
209
-
210
-
211
- def render_settings() -> dict:
212
- """The scaffolded `.venastine/settings.json`, as a payload."""
213
- settings = _defaults()
214
- for path in OMITTED:
215
- section, dot, key = path.partition(".")
216
- if dot:
217
- settings.get(section, {}).pop(key, None)
218
- else:
219
- settings.pop(section, None)
220
- return {
221
- key: ({sub: _coerce(key, sub, value) for sub, value in block.items()}
222
- if isinstance(block, dict) and key in config_loader._NESTED_SETTINGS
223
- else _coerce("", key, block))
224
- for key, block in settings.items()
225
- }
226
-
227
-
228
- def render_mcp() -> dict:
229
- """The scaffolded `.venastine/mcp.json`.
230
-
231
- The skeleton and nothing else. mcp.json's validation is by CONNECTION
232
- rather than by schema (§17 decision G), so there is no equivalent
233
- "every key at its default" to write -- and a server entry is the one
234
- piece of project configuration that names a local command to execute,
235
- which is not a thing to pre-fill with an example somebody might leave
236
- in place.
237
- """
238
- return {"mcpServers": {}}
239
-
240
-
241
- def leaf_paths(settings: dict) -> set:
242
- """Dotted paths of the LEAF settings in a payload, `section.key` for
243
- a nested one. The shape both the omission list and the vocabulary
244
- check are written in."""
245
- out = set()
246
- for key, value in settings.items():
247
- if key in config_loader._NESTED_SETTINGS and isinstance(value, dict):
248
- out |= {"%s.%s" % (key, sub) for sub in value}
249
- else:
250
- out.add(key)
251
- return out
252
-
253
-
254
- def shadowed(user: dict) -> list:
255
- """(path, theirs, ours) for every key the scaffold would start
256
- deciding instead of the user's own settings.json.
257
-
258
- DIFFERENCES ONLY. A key set to the same value on both sides changes
259
- nothing anyone can observe, and a warning that lists it teaches the
260
- reader to skim the ones that matter.
261
-
262
- Nested sections compare per key, because that is how the merge treats
263
- them (`_load_merged_settings` deepens exactly one level); a whole-
264
- section comparison would report a `compaction` block as shadowed for
265
- one differing knob inside it.
266
- """
267
- ours = render_settings()
268
- out = []
269
- for path in sorted(leaf_paths(ours)):
270
- section, dot, key = path.partition(".")
271
- if dot:
272
- block = user.get(section)
273
- if not isinstance(block, dict) or key not in block:
274
- continue
275
- theirs, mine = block[key], ours[section][key]
276
- else:
277
- if path not in user:
278
- continue
279
- theirs, mine = user[path], ours[path]
280
- if theirs != mine:
281
- out.append((path, theirs, mine))
282
- return out
1
+ """
2
+ project_init/config_files.py
3
+
4
+ ROADMAP_v2 §24 (I14-I17): WHAT `/init --config` writes into `.venastine/`,
5
+ and what it deliberately leaves out.
6
+
7
+ Data and pure rendering only -- no filesystem, no model call, no decision
8
+ about when to write. The same split as doc_sets.py and for the same
9
+ reason: the templates can be asserted against directly, and the one place
10
+ that decides whether anything is written stays generator.py.
11
+
12
+ THE FILE CANNOT EXPLAIN ITSELF, SO THIS ONE HAS TO. `_validate_settings`
13
+ raises on an unknown key (§14, amendment 1), so settings.json has no
14
+ comment syntax, no `$schema` line, and no way to carry a key that is
15
+ present but inert. Every line the scaffold writes is a live setting.
16
+
17
+ WHICH MAKES "THE DEFAULT" A THING SOME KEYS CANNOT SAY. A key read by
18
+ PRESENCE rather than by value is not restated by writing its default --
19
+ it is decided. Six were found that way, by writing each key alone into a
20
+ trusted project and diffing the observable state against a project with
21
+ no file at all:
22
+
23
+ default_provider, default_model the /model store's staleness key.
24
+ `_startup_pair`: "edit either, ADD
25
+ either, or remove either and the
26
+ file re-asserts itself" -- so
27
+ scaffolding them discards a
28
+ remembered choice
29
+ effort `_effort_named` flips False->True,
30
+ and its own comment says a
31
+ default-derived level must not fire
32
+ the mount-time probe (#138)
33
+ compaction.trigger_tokens `_trigger_is_configured()` is a
34
+ presence test, and presence makes
35
+ the fixed number outrank the
36
+ window-derived trigger -- invisibly,
37
+ since the file only says 40000
38
+ ensemble_mode `config.ENSEMBLE_MODE if x is None`
39
+ research.subagent_review `if persisted is not None` -- both
40
+ of these freeze today's config.py
41
+ value against a later edit of it
42
+
43
+ All six are in OMITTED. What survives is a scaffold that changes NOTHING
44
+ until a human edits it, which is the only claim "a template of defaults"
45
+ can honestly make, and `test_the_scaffolded_settings_file_changes_nothing`
46
+ asserts it over the whole observable set rather than key by key.
47
+
48
+ THE DEFAULTS ARE READ, NOT RETYPED (I15) -- `config_loader.shipped_defaults()`
49
+ and `config.py`'s own constants. A template that quotes a default is a
50
+ second copy of it, in the one file that has to be right the first time or
51
+ the harness will not start.
52
+
53
+ WHAT IT WRITES IS STILL NOT NEUTRAL BETWEEN TIERS. A project settings.json
54
+ beats the user's (D29) by PRESENCE and not by difference, so even this file
55
+ takes every key it names away from `~/.config/venastine/settings.json`.
56
+ `shadowed()` is how the command says so; generator.py renders it.
57
+ """
58
+
59
+ from __future__ import annotations
60
+
61
+ import config
62
+ from core import config_loader
63
+
64
+ SETTINGS_FILENAME = "settings.json"
65
+ MCP_FILENAME = "mcp.json"
66
+
67
+ #: Tier directories the loader looks for under `.venastine/`, created
68
+ #: EMPTY. They carry nothing into the trust hash -- `content_files()`
69
+ #: walks files, and a directory name never enters the digest -- and git
70
+ #: does not track an empty directory, so a project that commits its
71
+ #: `.venastine/` does not ship them. They are a hint on the author's
72
+ #: machine about where a project-tier agent or skill goes, and nothing
73
+ #: more. Named here rather than in config_loader because the loader's
74
+ #: `_tier_dirs` derives them from the `kind` argument it is called with,
75
+ #: which is not a list anything can read.
76
+ TIER_DIRS = ("agents", "skills")
77
+
78
+ #: Settings the loader knows and this file does NOT write, each with the
79
+ #: reason. Dotted `section.key` for a nested one.
80
+ #:
81
+ #: A SILENT OMISSION IS INDISTINGUISHABLE FROM AN OVERSIGHT, which is why
82
+ #: this is data with prose in it rather than a set: the next person to
83
+ #: read the scaffold and find `effort` missing should find out why here,
84
+ #: and `test_the_template_omits_only_what_it_can_name` keeps the entries
85
+ #: honest by requiring every one of them to still exist in the loader's
86
+ #: vocabulary.
87
+ OMITTED = {
88
+ "default_provider":
89
+ "presence, not value, is the /model store's staleness key -- "
90
+ "adding this to a settings.json discards a remembered choice, "
91
+ "which _startup_pair's own docstring says in as many words",
92
+ "default_model":
93
+ "the other half of the same staleness key; the pair is compared "
94
+ "and restored whole or not at all",
95
+ "effort":
96
+ "sets _effort_named, which exists to tell a level a HUMAN chose "
97
+ "from one derived from a default. Writing it makes every launch "
98
+ "probe the provider's effort table, and warn on the models that "
99
+ "have none (#138's healthy-mount silence)",
100
+ "ensemble_n":
101
+ "vestigial -- the roster's length decides the count now, and the "
102
+ "loader warns when this is set, so a template carrying it would "
103
+ "ship that warning to everyone who ran the command",
104
+ "confidence.disagreement_penalty_factor":
105
+ "retired by ROADMAP_v3 §90 for the same reason as ensemble_n: "
106
+ "disagreement routes a claim to be checked and subtracts nothing, "
107
+ "and the loader warns when this is set",
108
+ "ensemble_mode":
109
+ "resolved as `config.ENSEMBLE_MODE if value is None`, so writing "
110
+ "`false` is not a restatement of the default but a decision to "
111
+ "outrank whatever config.py says later",
112
+ "compaction.trigger_tokens":
113
+ "_trigger_is_configured() is a PRESENCE test: the window-derived "
114
+ "trigger only applies while no human has named a number. Writing "
115
+ "the default pins compaction to it for every model, and the file "
116
+ "gives no hint that it did -- on a large-context model that is a "
117
+ "much earlier fold with nothing on screen to explain it",
118
+ "research.subagent_review":
119
+ "same `is not None` shape as ensemble_mode: an explicit false "
120
+ "beats config.SUBAGENT_REVIEW rather than deferring to it",
121
+ "tui.theme":
122
+ "no shipped default to write -- absent, _startup_theme() resolves "
123
+ "one -- and an invented value would outrank a theme the user "
124
+ "picked with /theme, for every session in this project",
125
+ "tui.effort":
126
+ "no shipped default either, and it feeds the same _effort_named "
127
+ "flag as the top-level key above",
128
+ "source_scoring.similarity_floor":
129
+ "defaults to None against a `float` schema, so writing the "
130
+ "default IS a startup error. None here means the per-model table "
131
+ "decides, which no JSON value can say",
132
+ "source_scoring.similarity_ceiling":
133
+ "the other half of the same per-model pair",
134
+ }
135
+
136
+
137
+ def _defaults() -> dict:
138
+ """Every setting that has a shipped default, at that default.
139
+
140
+ Before OMITTED is applied, so the removal below is visible as a
141
+ removal. `tui.theme` and `tui.effort` are the two entries in OMITTED
142
+ that cannot appear here at all -- there is no default to produce --
143
+ and the test asserts on the rendered key set rather than on which
144
+ mechanism excluded a key, so both routes are covered.
145
+
146
+ The three `tui` values are the only ones typed out rather than read.
147
+ config.py holds no TUI values on purpose (the note beside `animations`
148
+ in tui/app.py), so their defaults are literals in `VenastineApp.__init__`
149
+ and there is no constant to import without dragging textual into
150
+ project_init. `test_the_scaffolded_settings_file_changes_nothing`
151
+ drives the real app, so a drift here fails there rather than here.
152
+ """
153
+ from core.loop import DEFAULT_PROVIDER
154
+
155
+ shipped = config_loader.shipped_defaults()
156
+ confidence = dict(shipped["confidence"])
157
+ # JSON HAS NO NULL KEY. `grounding_weights` carries one -- the weight
158
+ # for a claim with no grounding status at all -- and it serialises as
159
+ # the string "null", which `_apply_grounding_weights` then rejects
160
+ # against GROUNDING_STATUSES and logs about on every launch. The three
161
+ # named statuses ARE settable and the None one is not, by that
162
+ # vocabulary's own definition, so the template emits exactly the keys
163
+ # the loader will take. Read from the loader's re-export rather than
164
+ # retyped, like everything else here.
165
+ confidence["grounding_weights"] = {
166
+ status: weight
167
+ for status, weight in confidence["grounding_weights"].items()
168
+ if status in config_loader.GROUNDING_STATUSES
169
+ }
170
+ return {
171
+ "default_provider": DEFAULT_PROVIDER,
172
+ "default_model": config.MODEL_NAME,
173
+ "effort": config.DEFAULT_EFFORT,
174
+ "max_token_budget": None,
175
+ "ensemble_mode": config.ENSEMBLE_MODE,
176
+ "compaction": shipped["compaction"],
177
+ "tui": {
178
+ "animations": True,
179
+ "show_thinking": True,
180
+ "todo_position": "side",
181
+ },
182
+ "research": {
183
+ # The vocabulary's first entry is the default, and
184
+ # _KNOWN_RESEARCH says so beside it. Read rather than typed
185
+ # for the same reason as everything else here.
186
+ "approval_mode": config_loader.RESEARCH_APPROVAL_MODES[0],
187
+ "subagent_review": config.SUBAGENT_REVIEW,
188
+ },
189
+ "confidence": confidence,
190
+ "source_scoring": shipped["source_scoring"],
191
+ }
192
+
193
+
194
+ def _coerce(section: str, key: str, value):
195
+ """A value declared `float` is emitted as one.
196
+
197
+ Every confidence knob is a genuine float today, so this changes no
198
+ byte of the current template. It is here because the failure it
199
+ prevents is silent at the wrong end: a future default landing as an
200
+ int (0.0 written as 0, say) makes `_type_ok(0, float)` False, and the
201
+ scaffold this file exists to produce becomes a file that stops the
202
+ harness from starting. Cheaper to make impossible than to catch.
203
+ """
204
+ known = config_loader._NESTED_SETTINGS.get(section)
205
+ expected = (known or config_loader._KNOWN_SETTINGS).get(key)
206
+ if expected is float and isinstance(value, (int, float)):
207
+ return float(value)
208
+ return value
209
+
210
+
211
+ def render_settings() -> dict:
212
+ """The scaffolded `.venastine/settings.json`, as a payload."""
213
+ settings = _defaults()
214
+ for path in OMITTED:
215
+ section, dot, key = path.partition(".")
216
+ if dot:
217
+ settings.get(section, {}).pop(key, None)
218
+ else:
219
+ settings.pop(section, None)
220
+ return {
221
+ key: ({sub: _coerce(key, sub, value) for sub, value in block.items()}
222
+ if isinstance(block, dict) and key in config_loader._NESTED_SETTINGS
223
+ else _coerce("", key, block))
224
+ for key, block in settings.items()
225
+ }
226
+
227
+
228
+ def render_mcp() -> dict:
229
+ """The scaffolded `.venastine/mcp.json`.
230
+
231
+ The skeleton and nothing else. mcp.json's validation is by CONNECTION
232
+ rather than by schema (§17 decision G), so there is no equivalent
233
+ "every key at its default" to write -- and a server entry is the one
234
+ piece of project configuration that names a local command to execute,
235
+ which is not a thing to pre-fill with an example somebody might leave
236
+ in place.
237
+ """
238
+ return {"mcpServers": {}}
239
+
240
+
241
+ def leaf_paths(settings: dict) -> set:
242
+ """Dotted paths of the LEAF settings in a payload, `section.key` for
243
+ a nested one. The shape both the omission list and the vocabulary
244
+ check are written in."""
245
+ out = set()
246
+ for key, value in settings.items():
247
+ if key in config_loader._NESTED_SETTINGS and isinstance(value, dict):
248
+ out |= {"%s.%s" % (key, sub) for sub in value}
249
+ else:
250
+ out.add(key)
251
+ return out
252
+
253
+
254
+ def shadowed(user: dict) -> list:
255
+ """(path, theirs, ours) for every key the scaffold would start
256
+ deciding instead of the user's own settings.json.
257
+
258
+ DIFFERENCES ONLY. A key set to the same value on both sides changes
259
+ nothing anyone can observe, and a warning that lists it teaches the
260
+ reader to skim the ones that matter.
261
+
262
+ Nested sections compare per key, because that is how the merge treats
263
+ them (`_load_merged_settings` deepens exactly one level); a whole-
264
+ section comparison would report a `compaction` block as shadowed for
265
+ one differing knob inside it.
266
+ """
267
+ ours = render_settings()
268
+ out = []
269
+ for path in sorted(leaf_paths(ours)):
270
+ section, dot, key = path.partition(".")
271
+ if dot:
272
+ block = user.get(section)
273
+ if not isinstance(block, dict) or key not in block:
274
+ continue
275
+ theirs, mine = block[key], ours[section][key]
276
+ else:
277
+ if path not in user:
278
+ continue
279
+ theirs, mine = user[path], ours[path]
280
+ if theirs != mine:
281
+ out.append((path, theirs, mine))
282
+ return out