@yahyahammad/venastine 0.2.0 → 0.3.9

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 (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -1,278 +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
- "ensemble_mode":
105
- "resolved as `config.ENSEMBLE_MODE if value is None`, so writing "
106
- "`false` is not a restatement of the default but a decision to "
107
- "outrank whatever config.py says later",
108
- "compaction.trigger_tokens":
109
- "_trigger_is_configured() is a PRESENCE test: the window-derived "
110
- "trigger only applies while no human has named a number. Writing "
111
- "the default pins compaction to it for every model, and the file "
112
- "gives no hint that it did -- on a large-context model that is a "
113
- "much earlier fold with nothing on screen to explain it",
114
- "research.subagent_review":
115
- "same `is not None` shape as ensemble_mode: an explicit false "
116
- "beats config.SUBAGENT_REVIEW rather than deferring to it",
117
- "tui.theme":
118
- "no shipped default to write -- absent, _startup_theme() resolves "
119
- "one -- and an invented value would outrank a theme the user "
120
- "picked with /theme, for every session in this project",
121
- "tui.effort":
122
- "no shipped default either, and it feeds the same _effort_named "
123
- "flag as the top-level key above",
124
- "source_scoring.similarity_floor":
125
- "defaults to None against a `float` schema, so writing the "
126
- "default IS a startup error. None here means the per-model table "
127
- "decides, which no JSON value can say",
128
- "source_scoring.similarity_ceiling":
129
- "the other half of the same per-model pair",
130
- }
131
-
132
-
133
- def _defaults() -> dict:
134
- """Every setting that has a shipped default, at that default.
135
-
136
- Before OMITTED is applied, so the removal below is visible as a
137
- removal. `tui.theme` and `tui.effort` are the two entries in OMITTED
138
- that cannot appear here at all -- there is no default to produce --
139
- and the test asserts on the rendered key set rather than on which
140
- mechanism excluded a key, so both routes are covered.
141
-
142
- The three `tui` values are the only ones typed out rather than read.
143
- config.py holds no TUI values on purpose (the note beside `animations`
144
- in tui/app.py), so their defaults are literals in `VenastineApp.__init__`
145
- and there is no constant to import without dragging textual into
146
- project_init. `test_the_scaffolded_settings_file_changes_nothing`
147
- drives the real app, so a drift here fails there rather than here.
148
- """
149
- from core.loop import DEFAULT_PROVIDER
150
-
151
- shipped = config_loader.shipped_defaults()
152
- confidence = dict(shipped["confidence"])
153
- # JSON HAS NO NULL KEY. `grounding_weights` carries one -- the weight
154
- # for a claim with no grounding status at all -- and it serialises as
155
- # the string "null", which `_apply_grounding_weights` then rejects
156
- # against GROUNDING_STATUSES and logs about on every launch. The three
157
- # named statuses ARE settable and the None one is not, by that
158
- # vocabulary's own definition, so the template emits exactly the keys
159
- # the loader will take. Read from the loader's re-export rather than
160
- # retyped, like everything else here.
161
- confidence["grounding_weights"] = {
162
- status: weight
163
- for status, weight in confidence["grounding_weights"].items()
164
- if status in config_loader.GROUNDING_STATUSES
165
- }
166
- return {
167
- "default_provider": DEFAULT_PROVIDER,
168
- "default_model": config.MODEL_NAME,
169
- "effort": config.DEFAULT_EFFORT,
170
- "max_token_budget": None,
171
- "ensemble_mode": config.ENSEMBLE_MODE,
172
- "compaction": shipped["compaction"],
173
- "tui": {
174
- "animations": True,
175
- "show_thinking": True,
176
- "todo_position": "side",
177
- },
178
- "research": {
179
- # The vocabulary's first entry is the default, and
180
- # _KNOWN_RESEARCH says so beside it. Read rather than typed
181
- # for the same reason as everything else here.
182
- "approval_mode": config_loader.RESEARCH_APPROVAL_MODES[0],
183
- "subagent_review": config.SUBAGENT_REVIEW,
184
- },
185
- "confidence": confidence,
186
- "source_scoring": shipped["source_scoring"],
187
- }
188
-
189
-
190
- def _coerce(section: str, key: str, value):
191
- """A value declared `float` is emitted as one.
192
-
193
- Every confidence knob is a genuine float today, so this changes no
194
- byte of the current template. It is here because the failure it
195
- prevents is silent at the wrong end: a future default landing as an
196
- int (0.0 written as 0, say) makes `_type_ok(0, float)` False, and the
197
- scaffold this file exists to produce becomes a file that stops the
198
- harness from starting. Cheaper to make impossible than to catch.
199
- """
200
- known = config_loader._NESTED_SETTINGS.get(section)
201
- expected = (known or config_loader._KNOWN_SETTINGS).get(key)
202
- if expected is float and isinstance(value, (int, float)):
203
- return float(value)
204
- return value
205
-
206
-
207
- def render_settings() -> dict:
208
- """The scaffolded `.venastine/settings.json`, as a payload."""
209
- settings = _defaults()
210
- for path in OMITTED:
211
- section, dot, key = path.partition(".")
212
- if dot:
213
- settings.get(section, {}).pop(key, None)
214
- else:
215
- settings.pop(section, None)
216
- return {
217
- key: ({sub: _coerce(key, sub, value) for sub, value in block.items()}
218
- if isinstance(block, dict) and key in config_loader._NESTED_SETTINGS
219
- else _coerce("", key, block))
220
- for key, block in settings.items()
221
- }
222
-
223
-
224
- def render_mcp() -> dict:
225
- """The scaffolded `.venastine/mcp.json`.
226
-
227
- The skeleton and nothing else. mcp.json's validation is by CONNECTION
228
- rather than by schema (§17 decision G), so there is no equivalent
229
- "every key at its default" to write -- and a server entry is the one
230
- piece of project configuration that names a local command to execute,
231
- which is not a thing to pre-fill with an example somebody might leave
232
- in place.
233
- """
234
- return {"mcpServers": {}}
235
-
236
-
237
- def leaf_paths(settings: dict) -> set:
238
- """Dotted paths of the LEAF settings in a payload, `section.key` for
239
- a nested one. The shape both the omission list and the vocabulary
240
- check are written in."""
241
- out = set()
242
- for key, value in settings.items():
243
- if key in config_loader._NESTED_SETTINGS and isinstance(value, dict):
244
- out |= {"%s.%s" % (key, sub) for sub in value}
245
- else:
246
- out.add(key)
247
- return out
248
-
249
-
250
- def shadowed(user: dict) -> list:
251
- """(path, theirs, ours) for every key the scaffold would start
252
- deciding instead of the user's own settings.json.
253
-
254
- DIFFERENCES ONLY. A key set to the same value on both sides changes
255
- nothing anyone can observe, and a warning that lists it teaches the
256
- reader to skim the ones that matter.
257
-
258
- Nested sections compare per key, because that is how the merge treats
259
- them (`_load_merged_settings` deepens exactly one level); a whole-
260
- section comparison would report a `compaction` block as shadowed for
261
- one differing knob inside it.
262
- """
263
- ours = render_settings()
264
- out = []
265
- for path in sorted(leaf_paths(ours)):
266
- section, dot, key = path.partition(".")
267
- if dot:
268
- block = user.get(section)
269
- if not isinstance(block, dict) or key not in block:
270
- continue
271
- theirs, mine = block[key], ours[section][key]
272
- else:
273
- if path not in user:
274
- continue
275
- theirs, mine = user[path], ours[path]
276
- if theirs != mine:
277
- out.append((path, theirs, mine))
278
- 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