@yahyahammad/venastine 0.1.0

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 (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
@@ -0,0 +1,1563 @@
1
+ """
2
+ core/config_loader.py
3
+
4
+ ROADMAP_v2 §14. Discovers and parses agent/skill `.md` files across the
5
+ three tiers (D8) -- harness (`agents/builtin/`, `skills/builtin/` shipped
6
+ with the repo), project (`.venastine/`, only if trusted per D17), user
7
+ (`~/.config/venastine/`) -- merges `settings.json` across tiers, and
8
+ exposes the skill catalog (frontmatter only, never bodies) for system
9
+ prompt injection.
10
+
11
+ Progressive disclosure: the model sees name+description of every
12
+ discovered skill in its system prompt and must call the `load_skill`
13
+ tool to view a body. Bodies never enter context unrequested.
14
+
15
+ Tier precedence: a harness-tier name can never be shadowed -- a
16
+ project/user file colliding with a builtin is rejected with a warning
17
+ (D18). Project vs user collisions resolve USER-wins (D29): the user tier is
18
+ what you authored; the project tier is what arrived with a directory
19
+ you cloned.
20
+
21
+ `initialize(project_path)` is called once at startup (main.py) and caches
22
+ everything; getters return the cached state. Tests call initialize() with
23
+ their own tmp dirs and reset() afterwards.
24
+ """
25
+
26
+ import json
27
+ import logging
28
+ import os
29
+ import re
30
+ from dataclasses import dataclass
31
+ from typing import Optional
32
+
33
+ import yaml
34
+
35
+ import config
36
+ from core import workspace_trust
37
+
38
+ logger = logging.getLogger(__name__)
39
+
40
+ # The repo root (this file lives in <root>/core/). The harness tier is
41
+ # shipped with the harness itself, so it resolves from here, not from cwd.
42
+ HARNESS_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
43
+
44
+ NUMBER_TYPES = (int, float)
45
+
46
+ # §45 (SQ6): the closed vocabulary `confidence.grounding_weights`
47
+ # keys against. Re-exported from base.py rather than re-typed, the
48
+ # way payload_validation does -- a second hand-written copy of a
49
+ # vocabulary is a second thing to keep in step.
50
+ from core.reasoning.base import GROUNDING_STATUSES # noqa: E402
51
+
52
+
53
+ _FRONTMATTER_DELIM = re.compile(r"^---\s*$", re.MULTILINE)
54
+
55
+ _KNOWN_SETTINGS = {
56
+ "default_provider": str,
57
+ "default_model": str,
58
+ # Batch 25 (#139). The effort level every path runs at unless something
59
+ # more specific speaks: CLI flag > this key > config.DEFAULT_EFFORT,
60
+ # with tui.effort still winning INSIDE the TUI (it predates this key
61
+ # and changing its meaning would surprise existing configs).
62
+ #
63
+ # Deliberately NOT an R12 by-name rejection, and the reason is worth
64
+ # stating so nobody "completes" the pattern: R12 rejects keys that are
65
+ # AUTHORITY. This one is cost -- the worst a cloned repo's settings.json
66
+ # can do here is make runs think harder and spend more tokens, which is
67
+ # compaction-settings territory, not granted-tools territory.
68
+ "effort": str,
69
+ # Batch 27 (#4). The optional per-run SPEND ceiling, in billed
70
+ # input+output tokens. None/absent -- the default -- means UNCAPPED:
71
+ # hard spend limits are the provider's dashboard's job, and a harness
72
+ # cap that misreads as a context limit is the exact defect #4 records.
73
+ # Cost knob, not authority, so effort's merge rule applies (normal
74
+ # tiers; deliberately NOT an R12 by-name rejection).
75
+ "max_token_budget": (int, type(None)),
76
+ "ensemble_mode": bool,
77
+ "ensemble_n": int,
78
+ "compaction": dict,
79
+ "tui": dict,
80
+ "research": dict,
81
+ # ROADMAP_v2 §45 (SQ6). TOP-LEVEL, not nested under `research`:
82
+ # _NESTED_SETTINGS supports exactly one level and both the validator
83
+ # and the cross-tier merge iterate it, so `research.confidence` would
84
+ # need the merge deepened -- the code path review finding F2 broke
85
+ # once. These are cost/quality knobs, not authority, so effort's merge
86
+ # rule applies: normal tiers, deliberately NOT an R12 by-name
87
+ # rejection. The two keys that ARE authority -- critic_model and
88
+ # embedder_model -- are rejected above.
89
+ "confidence": dict,
90
+ "source_scoring": dict,
91
+ }
92
+ # ROADMAP_v2 §25 (R12). The authorization MODE is persistable and the
93
+ # grant LIST deliberately is not.
94
+ #
95
+ # The asymmetry is the design. A persisted mode can only ever ADD prompts,
96
+ # so the worst a hostile settings.json can do is make your runs more
97
+ # annoying. A persisted grant list could only ever REMOVE them -- standing
98
+ # authorization for named tools, carried by any repo you clone, and
99
+ # settings.json is the one config file where project tier beats user tier.
100
+ #
101
+ # `granted_tools` is therefore rejected BY NAME rather than left to the
102
+ # unknown-key branch, because "unknown key" reads as an oversight to be
103
+ # fixed by adding support for it. See _validate_settings.
104
+ _KNOWN_RESEARCH = {
105
+ "approval_mode": str, # "none" (default) or "attended"
106
+ # §20/D9. A MODE, so R12's rule permits persisting it: the worst a
107
+ # hostile settings.json can do here is make a run stop and ask you
108
+ # about corrections it wants to make, which is more friction and never
109
+ # more authority. --no-review escapes it for one run.
110
+ "subagent_review": bool,
111
+ }
112
+ RESEARCH_APPROVAL_MODES = ("none", "attended")
113
+ _KNOWN_COMPACTION = {
114
+ "strength": int,
115
+ "keep_recent_tokens": int,
116
+ # ROADMAP_v2 §21 (M1). This was `buffer_tokens` while §21 was specified
117
+ # as "headroom before the model's context window". It is not headroom:
118
+ # the trigger is a WORKING-SET TARGET -- a window-derived threshold
119
+ # sits at a size a working thread never reaches, while ~40k keeps turns
120
+ # cheap and their tool steps intact. Renamed rather than redefined -- a
121
+ # key that keeps its name and changes its meaning is worse than one
122
+ # that moves, and these keys have been inert since §14 so nothing
123
+ # depends on the old spelling.
124
+ "trigger_tokens": int,
125
+ "warning_margin_tokens": int,
126
+ # §21 M5 / M2 / retry bound.
127
+ "keep_recent_turns": int,
128
+ "strategy": str,
129
+ "max_retries": int,
130
+ }
131
+ # ROADMAP_v2 §16. TUI preferences live here rather than in a dotfile of
132
+ # their own because unknown settings keys RAISE (§14 amendment 1) -- a
133
+ # preference the loader doesn't know about is a startup error, not a
134
+ # silently ignored line. That is the tradeoff the loud-rejection rule
135
+ # buys: adding a preference is a schema change, on purpose.
136
+ _KNOWN_TUI = {
137
+ "theme": str, # one of tui/themes.py's registered names
138
+ "animations": bool, # master switch for the raven + transitions
139
+ "effort": str, # persisted reasoning-effort level (§16)
140
+ "todo_position": str, # §23 slice 2: one of TODO_POSITIONS below
141
+ # §38 (O6): render a turn's reasoning inline, or collapse it to an
142
+ # animated one-line indicator. Defaults to True in tui/app.py rather
143
+ # than to a config.py constant, following `animations` above -- config.py
144
+ # holds no TUI values and is plain-values-only.
145
+ "show_thinking": bool,
146
+ }
147
+
148
+ # §23 slice 2. Validated AT LOAD and raising, following
149
+ # research.approval_mode rather than tui.theme.
150
+ #
151
+ # tui.theme validates at use and falls back, for a stated reason: the loader
152
+ # cannot know the valid names without importing tui/themes.py, and a stale
153
+ # theme name should not stop the app from starting. Neither applies here --
154
+ # the vocabulary is three words that live in this file, and a position the
155
+ # renderer does not understand would silently put the panel somewhere the
156
+ # user did not ask for. tui.effort had neither check and that was a shipped
157
+ # bug (§16), which is the third precedent and the one that decided it.
158
+ TODO_POSITIONS = ("top", "bottom", "side")
159
+
160
+ # Settings whose value is a nested object. Both the validator and the
161
+ # cross-tier merge below iterate this rather than naming keys twice --
162
+ # `compaction` was the only member until §16 added `tui`, and hardcoding
163
+ # it in two places is what made the shallow-merge defect
164
+ # (review finding F2) possible in the first place.
165
+ _KNOWN_CONFIDENCE = {
166
+ "grounding_weight_factor": float,
167
+ "critic_weight_factor": float,
168
+ "assumption_flag_penalty": float,
169
+ "disagreement_penalty_factor": float,
170
+ "non_factual_score_cap": float,
171
+ "source_quality_floor": float,
172
+ "authority_full_credit": float,
173
+ "grounding_weights": dict,
174
+ "tier_thresholds": dict,
175
+ }
176
+
177
+ _KNOWN_SOURCE_SCORING = {
178
+ "similarity_floor": float,
179
+ "similarity_ceiling": float,
180
+ "authority_adjustment_cap": float,
181
+ "window_chars": int,
182
+ "max_windows": int,
183
+ "claim_min_chars": int,
184
+ "top_k": int,
185
+ "domain_overrides": dict,
186
+ "venue_weight": float,
187
+ "citation_weight": float,
188
+ "author_weight": float,
189
+ "h_saturation": int,
190
+ "min_cohort_size": int,
191
+ "min_citation_age_days": int,
192
+ }
193
+
194
+ _NESTED_SETTINGS = {
195
+ "compaction": _KNOWN_COMPACTION,
196
+ "tui": _KNOWN_TUI,
197
+ "research": _KNOWN_RESEARCH,
198
+ "confidence": _KNOWN_CONFIDENCE,
199
+ "source_scoring": _KNOWN_SOURCE_SCORING,
200
+ }
201
+
202
+
203
+ @dataclass
204
+ class SkillDef:
205
+ name: str
206
+ description: str
207
+ # ROADMAP_v2 §19 (K2): the tools this skill's methodology DEPENDS on,
208
+ # not tools it grants. It cannot grant any -- ToolContext.allowed_tools
209
+ # is a whitelist that narrows, and D14 forbids widening -- so this is
210
+ # checked at activation and reported, never applied. See SkillManager.
211
+ additional_tools: list
212
+ body: str
213
+ tier: str
214
+ path: str
215
+ # §19 (K4): folder path from the tier root, posix separators, "" for a
216
+ # skill sitting directly in skills/. Metadata, not identity -- the name
217
+ # stays global, so load_skill, /skill and D18's collision rule are
218
+ # untouched by where a file lives. Used to GROUP the catalog, which is
219
+ # the point: progressive disclosure puts every skill's name and
220
+ # description in every system prompt, and a flat list of forty is
221
+ # exactly what that design exists to avoid.
222
+ category: str = ""
223
+
224
+
225
+ @dataclass
226
+ class AgentDef:
227
+ name: str
228
+ description: str
229
+ model: Optional[str]
230
+ provider: Optional[str]
231
+ allowed_tools: Optional[list]
232
+ approval_overrides: dict
233
+ use_project_context: bool
234
+ use_memory: bool
235
+ max_steps: Optional[int]
236
+ body: str
237
+ tier: str
238
+ path: str
239
+ # ROADMAP_v2 §32 (A3), #69. Whether spawn_subagent can actually
240
+ # FEED this agent -- i.e. whether a task string, as the first
241
+ # message of a fresh thread, is the input its body expects.
242
+ #
243
+ # None means UNDECLARED, and what that means depends on who wrote
244
+ # the file. For the harness tier it is a build error, caught by
245
+ # assert_spawnable_declared below: our own omission is a bug, and
246
+ # R13's rule applies -- omission has to be a detectable mistake
247
+ # rather than an inherited answer. For the user and project tiers
248
+ # it reads as False, because a third party's silence must get the
249
+ # SAFE answer: an agent written for /agent and advertised as
250
+ # spawnable does not fail, it under-performs, and the parent has
251
+ # no way to tell (which is #69's actual complaint).
252
+ #
253
+ # Consulted by prompts.system_prompts.agent_catalog_text only.
254
+ # It is NOT a permission: C6 still caps a child's tools, and the
255
+ # depth limit still applies. This decides what the model is TOLD
256
+ # exists, which is D24's rule ("advertising an uncallable tool is
257
+ # not harmless: the model keeps choosing it") applied to the
258
+ # catalog's entries rather than to the tool itself.
259
+ spawnable: Optional[bool] = None
260
+
261
+
262
+ def _user_config_dir() -> str:
263
+ # Call-time resolution so tests can redirect it without touching the
264
+ # real user config dir.
265
+ return os.path.expanduser("~/.config/venastine")
266
+
267
+
268
+ def _catalog_text(value) -> str:
269
+ """One line, bounded, for a string that enters every system prompt.
270
+
271
+ Applied to a skill's and an agent's `name` and `description` at
272
+ PARSE TIME, for every tier -- ROADMAP_v2 §32 A5, #131.
273
+
274
+ TWO RULES, ONE FUNCTION, because they are one rule about one kind
275
+ of string:
276
+
277
+ COLLAPSE WHITESPACE, and this is the security half. The catalogs
278
+ render `- {name}: {description}`, so a value containing a
279
+ newline does not merely look untidy -- it LEAVES ITS BULLET.
280
+ A project skill described with a YAML block scalar holding
281
+ `## Available tools` renders as a top-level section of the
282
+ system prompt, indistinguishable from one this harness wrote.
283
+ Driven, and it worked.
284
+
285
+ CAP THE LENGTH, and this is the budget half. Progressive
286
+ disclosure puts every name and description in every prompt of
287
+ every run; without a bound, one project file sets that cost.
288
+
289
+ TRUNCATE RATHER THAN REFUSE THE FILE. `_parse_md_file` skips a
290
+ malformed definition, which is right for `additional_tools` --
291
+ a non-string element crashes its first consumer. A description is
292
+ advisory prose read by a model, so it degrades gracefully, and
293
+ losing a whole working skill over the length of its summary would
294
+ be the worse trade. The ellipsis is visible on purpose: a model
295
+ reading a cut-off summary should be able to tell.
296
+
297
+ EVERY TIER, not just project. A rule that applies only to
298
+ untrusted input is a second source of truth about what a catalog
299
+ entry is, and the harness tier is where a regression would be
300
+ least visible -- so the shipped files are held to it too, and
301
+ tests/test_catalog_text.py asserts they already comply.
302
+ """
303
+ text = " ".join(str(value).split())
304
+ if len(text) <= config.MAX_CATALOG_TEXT_CHARS:
305
+ return text
306
+ return text[:config.MAX_CATALOG_TEXT_CHARS - 1].rstrip() + "\u2026"
307
+
308
+
309
+ def _parse_frontmatter(text: str) -> tuple[dict, str]:
310
+ """Returns (frontmatter_dict, body). Uses a delimiter that must occupy
311
+ its own line -- NOT text.find("---"), which matches the first bare
312
+ '---' anywhere in the file, including a markdown horizontal rule
313
+ inside the body itself (a very common convention in longer
314
+ instructional content, which is exactly what agent/skill bodies are).
315
+ """
316
+ matches = list(_FRONTMATTER_DELIM.finditer(text))
317
+ if len(matches) < 2:
318
+ raise ValueError("No valid YAML frontmatter block found (need two '---' lines)")
319
+ # The opening delimiter must be the FIRST thing in the file. Without
320
+ # this, a file with no frontmatter at all but two horizontal rules in
321
+ # its body has the prose between them handed to yaml.safe_load --
322
+ # which usually fails the "is it a mapping / does it have a name"
323
+ # checks downstream, but reports the wrong reason when it does.
324
+ if matches[0].start() != 0:
325
+ raise ValueError(
326
+ "File does not begin with a YAML frontmatter block "
327
+ "(the opening '---' must be the first line)")
328
+ frontmatter_text = text[matches[0].end():matches[1].start()]
329
+ body = text[matches[1].end():].strip()
330
+ return yaml.safe_load(frontmatter_text), body
331
+
332
+
333
+ def _parse_md_file(path: str, kind: str, tier: str, category: str = ""):
334
+ """Parse one agent/skill .md file. Returns a SkillDef/AgentDef, or
335
+ None (with a warning) for malformed files -- a broken definition
336
+ warns and skips rather than taking down startup."""
337
+ try:
338
+ # utf-8-sig, not utf-8: a BOM (Notepad's default on this project's
339
+ # platform) is decoded as a leading , so the frontmatter's
340
+ # ^--- no longer sits at position 0 and the file is skipped with
341
+ # the false diagnosis "does not begin with a YAML frontmatter
342
+ # block". utf-8-sig strips a BOM and is a no-op without one.
343
+ with open(path, "r", encoding="utf-8-sig") as f:
344
+ text = f.read()
345
+ fm, body = _parse_frontmatter(text)
346
+ except (OSError, ValueError, yaml.YAMLError) as e:
347
+ logger.warning("Skipping %s file %s: %s", kind, path, e)
348
+ return None
349
+ if not isinstance(fm, dict):
350
+ logger.warning("Skipping %s file %s: frontmatter is not a YAML mapping", kind, path)
351
+ return None
352
+ name = fm.get("name")
353
+ if not isinstance(name, str) or not name:
354
+ logger.warning("Skipping %s file %s: missing 'name' in frontmatter", kind, path)
355
+ return None
356
+ # #131: the NAME is interpolated into the same catalog line as the
357
+ # description (`- {name}: {description}`), so it is the same
358
+ # injection surface and gets the same treatment. Bounded AFTER the
359
+ # emptiness check, because an all-whitespace name collapses to ""
360
+ # and must be reported as missing rather than registered as a
361
+ # nameless definition that D18's collision rule cannot reason about.
362
+ name = _catalog_text(name)
363
+ if not name:
364
+ logger.warning("Skipping %s file %s: 'name' is only whitespace",
365
+ kind, path)
366
+ return None
367
+ if kind == "skills":
368
+ tools = fm.get("additional_tools") or []
369
+ if not isinstance(tools, list):
370
+ logger.warning("Skipping skill file %s: additional_tools is not a list", path)
371
+ return None
372
+ # Element types, not just the container (review §19-20 f6): the
373
+ # first consumer feeds each element to a startswith() check, so a
374
+ # non-string element parsed cleanly here and crashed /skill at
375
+ # first consumption -- after "Activated" was already shown.
376
+ if not all(isinstance(t, str) for t in tools):
377
+ logger.warning("Skipping skill file %s: additional_tools is not a list of strings", path)
378
+ return None
379
+ return SkillDef(
380
+ name=name,
381
+ description=_catalog_text(fm.get("description", "")),
382
+ additional_tools=tools,
383
+ body=body,
384
+ tier=tier,
385
+ path=path,
386
+ category=category,
387
+ )
388
+ allowed = fm.get("allowed_tools")
389
+ if allowed is not None and not isinstance(allowed, list):
390
+ logger.warning("Skipping agent file %s: allowed_tools is not a list", path)
391
+ return None
392
+ overrides = fm.get("approval_overrides") or {}
393
+ if not isinstance(overrides, dict):
394
+ logger.warning("Skipping agent file %s: approval_overrides is not a mapping", path)
395
+ return None
396
+ max_steps = fm.get("max_steps")
397
+ # REPAIR, NOT REJECT (#45, batch 16 -- explicit owner decision). This
398
+ # guard used to SKIP the whole file for a bad max_steps, which made it
399
+ # the one frontmatter field whose typo cost the agent entirely while
400
+ # every sibling produced a warning-and-carry-on. Worse, a negative int
401
+ # passed the type check and crashed `_run` with an AttributeError on
402
+ # `response.stop_reason` three layers away from the line that caused it.
403
+ #
404
+ # Now: any unusable value -- non-int, YAML's bool-reading of yes/on,
405
+ # or < 1 (`isinstance(True, int)` is True in Python) -- is repaired to
406
+ # None with a warning NAMING the original. None is what "not declared"
407
+ # means downstream, so every call site's existing
408
+ # `max_steps or config.MAX_ITERATIONS` fallback applies unchanged, and
409
+ # the warning's default figure and the one that takes effect are the
410
+ # same number by construction rather than by two copies staying in
411
+ # step. The belt for values that bypass this loader lives in
412
+ # core/loop._run, which raises instead of repairing: a programmatic
413
+ # caller passing a bad value directly has no file to lose, only a bug
414
+ # worth naming.
415
+ if max_steps is not None:
416
+ valid = (isinstance(max_steps, int)
417
+ and not isinstance(max_steps, bool)
418
+ and max_steps >= 1)
419
+ if not valid:
420
+ logger.warning(
421
+ "Agent file %s: max_steps must be a positive integer, got "
422
+ "%r; defaulting to %s (config.MAX_ITERATIONS).",
423
+ path, max_steps, config.MAX_ITERATIONS)
424
+ max_steps = None
425
+ # Booleans are VALIDATED, not coerced. bool("false") is True, so
426
+ # `use_memory: "false"` would invert a deliberate opt-out with no
427
+ # warning -- and these two fields are exactly the ones a restrictive
428
+ # agent definition uses to opt OUT. Same warn-and-skip contract every
429
+ # other typed field in this function has.
430
+ flags = {}
431
+ for key, default in (("use_project_context", False), ("use_memory", True)):
432
+ value = fm.get(key, default)
433
+ if not isinstance(value, bool):
434
+ logger.warning(
435
+ "Skipping agent file %s: %s is not a boolean", path, key)
436
+ return None
437
+ flags[key] = value
438
+ spawnable = fm.get("spawnable")
439
+ if spawnable is not None and not isinstance(spawnable, bool):
440
+ logger.warning(
441
+ "Skipping agent file %s: spawnable is not a boolean", path)
442
+ return None
443
+ return AgentDef(
444
+ name=name,
445
+ description=_catalog_text(fm.get("description", "")),
446
+ model=fm.get("model"),
447
+ provider=fm.get("provider"),
448
+ allowed_tools=allowed,
449
+ approval_overrides=overrides,
450
+ use_project_context=flags["use_project_context"],
451
+ use_memory=flags["use_memory"],
452
+ spawnable=spawnable,
453
+ max_steps=max_steps,
454
+ body=body,
455
+ tier=tier,
456
+ path=path,
457
+ )
458
+
459
+
460
+ def _tier_dirs(kind: str, project_path: str, trusted: bool) -> list:
461
+ """Search order, and _discover() is first-wins, so this list IS the
462
+ precedence rule: harness > user > project.
463
+
464
+ ORDER CHANGED IN §17 (D29). It was harness > project > user, i.e. the
465
+ conventional "more specific config wins". That is the wrong default
466
+ here, because "project" does not mean "more specific" -- it means "it
467
+ arrived with a directory you cloned", which is the entire premise of
468
+ D17. The user tier is the one you actually authored, so it should
469
+ never be silently displaced by the tier you merely trusted once.
470
+
471
+ Harness stays first and un-overridable (D18, unchanged): a project can
472
+ still never impersonate a builtin.
473
+
474
+ Note this only ever breaks SAME-NAME ties. Non-colliding definitions
475
+ from every tier all load -- _discover() accumulates a union and
476
+ consults precedence only when a name repeats.
477
+ """
478
+ dirs = [("harness", os.path.join(HARNESS_ROOT, kind, "builtin"))]
479
+ dirs.append(("user", os.path.join(_user_config_dir(), kind)))
480
+ if trusted:
481
+ project_dir = os.path.join(
482
+ workspace_trust.venastine_dir(project_path), kind)
483
+ # #18. A SYMLINK at the project tier root escapes the D17 hash.
484
+ # `os.walk` follows the path handed to it as `top` but not
485
+ # symlinked subdirectories, and the two sides of the trust
486
+ # boundary start from different places: workspace_trust walks from
487
+ # `.venastine`, so a symlinked `skills/` is a subdirectory it will
488
+ # not descend, while _md_files walks from `.venastine/skills`, so
489
+ # it IS the top and gets followed. Directory names never enter the
490
+ # hash either, so the link contributes nothing -- not even its own
491
+ # name. The pointed-to definitions therefore load as project-tier
492
+ # agents/skills while being absent from the trust prompt's listing
493
+ # AND from the hash, so their bodies can be rewritten freely after
494
+ # one grant and `is_trusted()` keeps returning True.
495
+ #
496
+ # Treated as ABSENT rather than loaded-and-warned, matching the
497
+ # module's posture for untrusted content generally. The payload
498
+ # here is not data but instructions: a project-tier body becomes
499
+ # system-prompt content for the user's sessions.
500
+ #
501
+ # Scoped to the PROJECT tier deliberately. Harness and user
502
+ # directories are not hashed by anything, so a symlink in them is
503
+ # not a trust question -- and symlinking `~/.config/venastine/`
504
+ # into a dotfiles repo is a legitimate thing an operator does to
505
+ # their own config.
506
+ if os.path.islink(project_dir):
507
+ logger.warning(
508
+ "Ignoring project %s directory %s: it is a symlink, and "
509
+ "symlinked tier roots are invisible to the workspace-trust "
510
+ "content hash (see issue #18). Move the definitions inside "
511
+ ".venastine/ to load them.", kind, project_dir)
512
+ else:
513
+ dirs.append(("project", project_dir))
514
+ return dirs
515
+
516
+
517
+ def _md_files(directory: str, recursive: bool):
518
+ """(absolute path, category) for every .md file in a tier directory.
519
+
520
+ ROADMAP_v2 §19 (K4): SKILLS nest under category folders --
521
+ `skills/builtin/<category>/<skill>.md` -- and agents stay flat, since
522
+ `agents/builtin/` holds one file and speculative structure for it
523
+ would be structure nobody asked for. One branch here rather than a
524
+ second discovery function, so tier handling and collision handling
525
+ cannot diverge between the two kinds.
526
+
527
+ The category is DERIVED from the folder, never authored: a `category:`
528
+ frontmatter key would immediately be able to disagree with where the
529
+ file actually sits, and then two places would claim to know.
530
+
531
+ Walk order matches workspace_trust.content_files() -- dirs.sort() plus
532
+ sorted(files) -- because same-name collisions resolve first-wins, so a
533
+ nondeterministic order would make WHICH definition loads depend on the
534
+ filesystem.
535
+ """
536
+ if not recursive:
537
+ return [
538
+ (os.path.join(directory, f), "")
539
+ for f in sorted(os.listdir(directory)) if f.endswith(".md")
540
+ ]
541
+ out = []
542
+ for dirpath, dirs, files in os.walk(directory):
543
+ dirs.sort()
544
+ category = os.path.relpath(dirpath, directory).replace(os.sep, "/")
545
+ if category == ".":
546
+ category = ""
547
+ for fname in sorted(files):
548
+ if fname.endswith(".md"):
549
+ out.append((os.path.join(dirpath, fname), category))
550
+ return out
551
+
552
+
553
+ def _discover(kind: str, project_path: str, trusted: bool) -> dict:
554
+ found = {}
555
+ for tier, directory in _tier_dirs(kind, project_path, trusted):
556
+ if not os.path.isdir(directory):
557
+ continue
558
+ for path, category in _md_files(directory, recursive=(kind == "skills")):
559
+ defn = _parse_md_file(path, kind, tier, category)
560
+ if defn is None:
561
+ continue
562
+ if defn.name in found:
563
+ winner = found[defn.name]
564
+ if winner.tier == "harness":
565
+ logger.warning(
566
+ "%s-tier %s %r collides with a harness builtin; "
567
+ "the builtin wins and the %s file is ignored (D18).",
568
+ tier, kind, defn.name, tier,
569
+ )
570
+ else:
571
+ # Cross-tier, USER beats project for agents and skills:
572
+ # _tier_dirs returns [harness, user, project] and this
573
+ # loop is first-wins. That is D29, not D8 -- D8 is where
574
+ # definitions are discovered, D29 is the §17 inversion
575
+ # that put user ahead of project, because "project" does
576
+ # not mean "more specific", it means "it arrived with a
577
+ # directory you cloned". (This comment said the opposite
578
+ # and cited D8; it was pre-D29 text that survived the
579
+ # change. See audit #20 -- the warning below was always
580
+ # right, because it names the winner dynamically.)
581
+ #
582
+ # settings.json deliberately goes the OTHER way,
583
+ # project-over-user, at _load_merged_settings -- because
584
+ # the trust prompt shows its values verbatim. Two
585
+ # opposite rules in one module is exactly what a comment
586
+ # here should disambiguate.
587
+ #
588
+ # Same-tier is alphabetical-first-wins. None of this is
589
+ # guessable from the outside, so say so:
590
+ # Silently shadowing a definition is how someone spends
591
+ # an afternoon editing a file that is never loaded.
592
+ logger.warning(
593
+ "%s-tier %s %r at %s is shadowed by the %s-tier "
594
+ "definition at %s, which wins.",
595
+ tier, kind, defn.name, defn.path, winner.tier,
596
+ winner.path,
597
+ )
598
+ continue
599
+ found[defn.name] = defn
600
+ return found
601
+
602
+
603
+ def _type_ok(value, expected) -> bool:
604
+ # bool is a subclass of int in Python, so int-typed keys must reject
605
+ # booleans explicitly, and bool-typed keys must reject ints -- including
606
+ # through a tuple expected-type: isinstance(True, (int, type(None))) is
607
+ # True, and max_token_budget=True would otherwise sail through as 1.
608
+ expecteds = expected if isinstance(expected, tuple) else (expected,)
609
+ if isinstance(value, bool):
610
+ return bool in expecteds
611
+ ok = False
612
+ for e in expecteds:
613
+ if e is bool:
614
+ continue # a non-bool value can never match bool
615
+ if e is int:
616
+ ok = ok or isinstance(value, int)
617
+ else:
618
+ ok = ok or isinstance(value, e)
619
+ return ok
620
+
621
+
622
+ def _validate_settings(data, source: str) -> None:
623
+ """Loud rejection of unknown keys (a typo must not masquerade as a
624
+ setting) and type checks for known ones. Compaction keys are known
625
+ but not consumed until §21 -- they validate here and warn at init."""
626
+ if not isinstance(data, dict):
627
+ raise ValueError(f"settings.json at {source} is not a JSON object")
628
+ for key, value in data.items():
629
+ if key == "ensemble_models":
630
+ # ROADMAP §10 revisit (E2), and R12's rule applied to a second
631
+ # kind of authority. Rejected BY NAME rather than as an unknown
632
+ # key, because the generic message reads as an oversight to be
633
+ # fixed by adding support for it.
634
+ #
635
+ # Turning ensemble mode on can only spend more of the provider
636
+ # the user already chose. A ROSTER chooses providers -- so a
637
+ # project's settings.json, which beats the user's, could point N
638
+ # research passes at endpoints the user never configured for this
639
+ # work and multiply the run's cost by the length of a list it
640
+ # supplied. §14 already flagged project-tier provider selection as
641
+ # a distinct grant; this is that grant times N.
642
+ raise ValueError(
643
+ f"settings.json at {source}: ensemble_models is deliberately "
644
+ f"not supported -- a roster chooses which providers N research "
645
+ f"passes call, and a project's settings.json beats the "
646
+ f"user's. Set config.ENSEMBLE_MODELS in config.py instead "
647
+ f"(same posture as CRITIC_MODEL).")
648
+ if key == "shell_approval_mode":
649
+ # ROADMAP_v2 §28 (G7), and the third application of R12's rule.
650
+ # Rejected BY NAME for the reason the other two are: the
651
+ # generic unknown-key message reads as an oversight someone
652
+ # should fix by adding support, and this omission IS the
653
+ # design.
654
+ #
655
+ # A project's settings.json beats the user's (D29), and it
656
+ # arrives with a directory you cloned. This key decides
657
+ # whether shell commands are asked about at all -- so
658
+ # supporting it would let a cloned repo set "never" and turn
659
+ # `cat ~/.aws/credentials` into an unprompted host read. D17's
660
+ # trust gate is not a substitute: the same prompt covers a
661
+ # README-shaped AGENTS.md, and nobody reading it is deciding
662
+ # about their shell gate.
663
+ raise ValueError(
664
+ f"settings.json at {source}: shell_approval_mode is "
665
+ f"deliberately not supported -- it decides whether shell "
666
+ f"commands are approved at all, and a project's "
667
+ f"settings.json beats the user's. Set "
668
+ f"config.SHELL_APPROVAL_MODE in config.py instead (same "
669
+ f"posture as ensemble_models and research.granted_tools).")
670
+ if key in ("critic_model", "embedder_model"):
671
+ # ROADMAP_v2 §45 (SQ7), and the fourth application of R12's
672
+ # rule. Both name a PROVIDER the pipeline will call: the critic
673
+ # sees every claim, and the embedder is sent claim text and the
674
+ # text of every page the run fetched. A project's settings.json
675
+ # beats the user's and arrives with a directory you cloned, so
676
+ # supporting either would let that directory choose where a
677
+ # research run's content is sent.
678
+ #
679
+ # By name rather than as an unknown key for the reason the
680
+ # other three are: the generic message reads as an oversight
681
+ # someone should fix by adding support, and this omission is
682
+ # the design. `/critic` and `/embedder` write to the user-tier
683
+ # store in core/pipeline_models.py, which is the route.
684
+ raise ValueError(
685
+ f"settings.json at {source}: {key} is deliberately not "
686
+ f"supported -- it names a provider this harness sends "
687
+ f"research content to, and a project's settings.json beats "
688
+ f"the user's. Use /critic or /embedder, or set "
689
+ f"config.CRITIC_MODEL / config.EMBEDDER_MODEL in config.py "
690
+ f"(same posture as ensemble_models).")
691
+ if key not in _KNOWN_SETTINGS:
692
+ raise ValueError(f"settings.json at {source}: unknown key {key!r}")
693
+ expected = _KNOWN_SETTINGS[key]
694
+ if not _type_ok(value, expected):
695
+ expected_name = getattr(expected, "__name__", None) \
696
+ or "an int or null"
697
+ raise ValueError(
698
+ f"settings.json at {source}: key {key!r} must be {expected_name}, "
699
+ f"got {type(value).__name__}")
700
+ for section, known_keys in _NESTED_SETTINGS.items():
701
+ block = data.get(section)
702
+ if block is None:
703
+ continue
704
+ if not isinstance(block, dict):
705
+ raise ValueError(
706
+ f"settings.json at {source}: {section!r} must be an object")
707
+ for key, value in block.items():
708
+ if section == "research" and key == "granted_tools":
709
+ # §25 R12: rejected BY NAME, not as an unknown key. The
710
+ # generic message reads as an oversight someone should fix
711
+ # by adding support; this one says the omission is the
712
+ # design, so nobody "fixes" it into standing authorization
713
+ # that a cloned repo would carry.
714
+ raise ValueError(
715
+ f"settings.json at {source}: research.granted_tools is "
716
+ f"deliberately not supported -- a persisted grant list "
717
+ f"would authorise named tools for every future run, and "
718
+ f"a project's settings.json beats the user's. Grant per "
719
+ f"run with --grant / --grant-tools instead.")
720
+ if key not in known_keys:
721
+ raise ValueError(
722
+ f"settings.json at {source}: unknown {section} key {key!r}")
723
+ expected = known_keys[key]
724
+ if not _type_ok(value, expected):
725
+ raise ValueError(
726
+ f"settings.json at {source}: {section} key {key!r} must be "
727
+ f"{expected.__name__}, got {type(value).__name__}")
728
+ if section == "research" and key == "approval_mode" and \
729
+ value not in RESEARCH_APPROVAL_MODES:
730
+ raise ValueError(
731
+ f"settings.json at {source}: research.approval_mode must "
732
+ f"be one of {', '.join(RESEARCH_APPROVAL_MODES)}, "
733
+ f"got {value!r}")
734
+ if section == "tui" and key == "todo_position" and \
735
+ value not in TODO_POSITIONS:
736
+ raise ValueError(
737
+ f"settings.json at {source}: tui.todo_position must be "
738
+ f"one of {', '.join(TODO_POSITIONS)}, got {value!r}")
739
+
740
+
741
+ # ---------------------------------------------------------------------------
742
+ # ---- Compaction settings (ROADMAP_v2 §21, D27) ----------------------------
743
+ # ---------------------------------------------------------------------------
744
+ #
745
+ # Resolution lives HERE rather than in core/compaction.py because
746
+ # config_loader already owns the settings merge, and core/compaction.py
747
+ # reaches agents.manager, which imports this module -- resolving there and
748
+ # validating here would be a cycle. One function, called at startup so a
749
+ # bad value is a startup error, and called again per compaction so a
750
+ # per-invocation `/compact --strength 4` composes with the same rules.
751
+
752
+ _COMPACTION_DEFAULTS = {
753
+ "trigger_tokens": "COMPACTION_TRIGGER_TOKENS",
754
+ "warning_margin_tokens": "COMPACTION_WARNING_MARGIN_TOKENS",
755
+ "keep_recent_tokens": "COMPACTION_KEEP_RECENT_TOKENS",
756
+ "keep_recent_turns": "COMPACTION_KEEP_RECENT_TURNS",
757
+ "strength": "COMPACTION_STRENGTH",
758
+ "max_retries": "COMPACTION_MAX_RETRIES",
759
+ "strategy": "COMPACTION_STRATEGY",
760
+ }
761
+
762
+
763
+ def shipped_defaults() -> dict:
764
+ """Every nested knob at the value it takes when no settings.json
765
+ speaks. `{section: {key: default}}`, sections only -- the top-level
766
+ scalars are plain `config.py` constants and need no accessor.
767
+
768
+ EXISTS SO A TEMPLATE CANNOT QUOTE A STALE DEFAULT (§24 I15).
769
+ `/init --config` writes a settings.json of defaults, and a settings
770
+ file is unforgiving: `_validate_settings` raises on an unknown key, so
771
+ the scaffold has to be right the first time or the harness will not
772
+ start. Retyping these values there would be a second copy of them,
773
+ which is how the first one goes stale.
774
+
775
+ The two research-tuning builders live further down this file and are
776
+ resolved at call time, which is why this can sit beside the compaction
777
+ map it also reads.
778
+ """
779
+ return {
780
+ "compaction": {key: getattr(config, attr)
781
+ for key, attr in _COMPACTION_DEFAULTS.items()},
782
+ "confidence": _confidence_defaults(),
783
+ "source_scoring": _source_scoring_defaults(),
784
+ }
785
+
786
+
787
+ def effective_compaction(overrides: Optional[dict] = None,
788
+ warn: bool = False) -> dict:
789
+ """The compaction values actually in force.
790
+
791
+ A flat {key: value}. NOT where each came from -- see
792
+ TECHNICAL_DEBT.md item 12; the merge below overwrites without
793
+ recording which tier won, and D27's third implementation note asked
794
+ for provenance AND somewhere to show it. This sentence used to
795
+ promise both (audit #91).
796
+
797
+ config.py default -> user settings.json -> trusted project
798
+ settings.json -> `overrides` (a per-invocation `/compact --strength 4`,
799
+ which applies to that one run and persists nothing). Nearest wins,
800
+ which is the precedence the rest of the config system already uses.
801
+
802
+ RELATIONSHIPS ARE VALIDATED, not just documented -- §21's own
803
+ instruction about warning_margin, which is the one value whose wrong
804
+ setting is not self-correcting: a margin at or above the trigger fires
805
+ the warning after the thing it warns about, which is no warning at all.
806
+
807
+ Raises ValueError on a value that cannot produce coherent trigger
808
+ math. That is the same posture settings.json already takes toward an
809
+ unknown key: a project's settings are content the user may not have
810
+ authored (D17's premise), and while nothing here can destroy anything
811
+ -- the archive is never edited by compaction, which is exactly the
812
+ property that makes this safe -- an absurd trigger would force
813
+ compaction constantly, and every compaction is a real model call the
814
+ user pays for.
815
+ """
816
+ import config
817
+
818
+ values = shipped_defaults()["compaction"]
819
+ values.update(get_settings().get("compaction") or {})
820
+ values.update({k: v for k, v in (overrides or {}).items() if v is not None})
821
+
822
+ strength = values["strength"]
823
+ if strength not in config.COMPACTION_TARGET_RATIOS:
824
+ raise ValueError(
825
+ f"compaction.strength must be one of "
826
+ f"{sorted(config.COMPACTION_TARGET_RATIOS)}, got {strength!r}")
827
+ if values["strategy"] not in config.COMPACTION_STRATEGIES:
828
+ raise ValueError(
829
+ f"compaction.strategy must be one of "
830
+ f"{', '.join(config.COMPACTION_STRATEGIES)}, "
831
+ f"got {values['strategy']!r}")
832
+ if values["trigger_tokens"] < 1:
833
+ raise ValueError(
834
+ f"compaction.trigger_tokens must be positive, got "
835
+ f"{values['trigger_tokens']}")
836
+ if values["warning_margin_tokens"] >= values["trigger_tokens"]:
837
+ raise ValueError(
838
+ f"compaction.warning_margin_tokens ({values['warning_margin_tokens']}) "
839
+ f"must be strictly less than trigger_tokens "
840
+ f"({values['trigger_tokens']}), or the early warning fires after "
841
+ f"the compaction it is warning about.")
842
+ if values["keep_recent_tokens"] >= values["trigger_tokens"]:
843
+ raise ValueError(
844
+ f"compaction.keep_recent_tokens ({values['keep_recent_tokens']}) "
845
+ f"must be strictly less than trigger_tokens "
846
+ f"({values['trigger_tokens']}), or every message is protected at "
847
+ f"the moment compaction fires and there is nothing to summarize.")
848
+ for key in ("keep_recent_turns", "max_retries"):
849
+ if values[key] < 0:
850
+ raise ValueError(f"compaction.{key} must not be negative, "
851
+ f"got {values[key]}")
852
+
853
+ # M1's arithmetic, enforced rather than left in a comment. The prompt
854
+ # is re-billed on every step of a tool-using turn, so a turn starting
855
+ # at T tokens and running k steps spends roughly k*T against the
856
+ # CONFIGURED spend cap (settings.json max_token_budget). A trigger too
857
+ # close to that cap lets a thread reach a size where the cap ends the
858
+ # turn after one response -- compaction would then only ever fire on
859
+ # the turn AFTER the one it should have saved.
860
+ #
861
+ # ONLY MEANINGFUL WHEN A CAP EXISTS (#4). Uncapped -- the default --
862
+ # nothing competes with compaction: the trigger is a context-size
863
+ # target and always was; the billing meter never gated it and now
864
+ # gates nothing at all by default.
865
+ # WARN ONLY WHEN ASKED, which is once at startup. This function is
866
+ # on should_compact()'s path, so it runs once per step of every
867
+ # turn -- an unconditional warning here would repeat a
868
+ # configuration complaint dozens of times per conversation, which
869
+ # is how a real warning becomes one nobody reads. The VALIDATION
870
+ # above still raises on every call; only the advisory is gated.
871
+ cap = spend_cap()
872
+ if warn and cap is not None:
873
+ headroom = cap / max(values["trigger_tokens"], 1)
874
+ if headroom < 3:
875
+ logger.warning(
876
+ "compaction.trigger_tokens (%s) leaves room for only ~%.1f model "
877
+ "calls within your configured spend cap max_token_budget (%s), "
878
+ "because a tool-using turn re-sends its whole prompt each "
879
+ "step. Turns on a nearly-full thread will stop early with "
880
+ "token_budget_exceeded before compaction gets a chance. "
881
+ "Lower the trigger or raise the cap.",
882
+ values["trigger_tokens"], headroom, cap)
883
+ return values
884
+
885
+
886
+ def _read_settings_file(path: str) -> dict:
887
+ if not os.path.exists(path):
888
+ return {}
889
+ # utf-8-sig for the same reason as _parse_md_file: a BOM'd
890
+ # settings.json makes json.load raise at the first character.
891
+ with open(path, "r", encoding="utf-8-sig") as f:
892
+ data = json.load(f) # json.JSONError propagates as ValueError
893
+ _validate_settings(data, path)
894
+ return data
895
+
896
+
897
+ def user_settings() -> dict:
898
+ """The user tier's settings.json, alone and unmerged.
899
+
900
+ `get_settings()` answers what is IN FORCE, which is the wrong question
901
+ for two callers. The merge below needs the user tier before the
902
+ project tier lands on it, and `/init --config` needs it to say which
903
+ of the user's own keys the file it is about to write will start
904
+ deciding instead (§24 I16) -- a project key wins by PRESENCE, so a
905
+ scaffold of pure defaults still displaces a customised user tier.
906
+
907
+ Resolved at call time, like every other path in this module.
908
+ """
909
+ return _read_settings_file(
910
+ os.path.join(_user_config_dir(), "settings.json"))
911
+
912
+
913
+ def _load_merged_settings(project_path: str, trusted: bool) -> dict:
914
+ """Resolution order: project (trusted) > user. Anything absent falls
915
+ through to config.py defaults at the consumer.
916
+
917
+ Nested sections (`_NESTED_SETTINGS`) merge one level deeper than the
918
+ rest. Every other setting is a scalar, so whole-value replacement IS
919
+ per-key override for them; for a nested key, a plain dict.update()
920
+ would let a project setting `buffer_tokens` silently discard the
921
+ user's `strength` -- a per-key override everywhere else that becomes a
922
+ wholesale reset here, purely because of the value's type.
923
+
924
+ Driven off _NESTED_SETTINGS rather than naming sections inline: §16
925
+ added `tui` alongside `compaction`, and a second hardcoded section name
926
+ here is exactly how the first one came to be missed.
927
+ """
928
+ merged = user_settings()
929
+ if trusted:
930
+ project = _read_settings_file(os.path.join(
931
+ workspace_trust.venastine_dir(project_path), "settings.json"))
932
+ deep = {
933
+ section: {**merged.get(section, {}), **project.get(section, {})}
934
+ for section in _NESTED_SETTINGS
935
+ }
936
+ merged.update(project)
937
+ for section, value in deep.items():
938
+ if value:
939
+ merged[section] = value
940
+ return merged
941
+
942
+
943
+ _state: Optional[dict] = None
944
+
945
+
946
+ def initialize(project_path: str) -> None:
947
+ """Load everything once at startup. Untrusted project content is
948
+ absent entirely -- not loaded-but-disabled (D17)."""
949
+ global _state
950
+ trusted = workspace_trust.is_trusted(project_path)
951
+ if not trusted:
952
+ logger.warning(
953
+ "Project .venastine/ at %s is not trusted; project-level "
954
+ "content (agents, skills, settings, AGENTS.md) will not load.",
955
+ project_path,
956
+ )
957
+ settings = _load_merged_settings(project_path, trusted)
958
+ context = None
959
+ if trusted:
960
+ # §44: the project ROOT, not .venastine/. The hub is an ordinary
961
+ # committed file now, so a project shared WITHOUT its configuration
962
+ # is not a project with a dangling pointer -- which is the whole
963
+ # reason it moved. workspace_trust still covers it: the file is in
964
+ # content_files() and in the hash, because what reaches a system
965
+ # prompt is what a grant has to be about.
966
+ context_path = os.path.join(
967
+ project_path, workspace_trust.PROJECT_CONTEXT_FILENAME)
968
+ if os.path.exists(context_path):
969
+ # Degrade, don't abort. UnicodeDecodeError is a ValueError, so
970
+ # an unreadable AGENTS.md would reach main.load_project_config's
971
+ # handler and SystemExit(1) EVERY invocation in this directory
972
+ # -- including plain chat, which never reads the file. Every
973
+ # other malformed content file in this module warns and skips.
974
+ try:
975
+ with open(context_path, "r", encoding="utf-8-sig") as f:
976
+ context = f.read()
977
+ except (OSError, UnicodeDecodeError) as e:
978
+ logger.warning(
979
+ "Could not read %s; continuing without project "
980
+ "context: %s", context_path, e)
981
+ _state = {
982
+ "project_path": os.path.realpath(project_path),
983
+ "trusted": trusted,
984
+ "agents": _discover("agents", project_path, trusted),
985
+ "skills": _discover("skills", project_path, trusted),
986
+ "settings": settings,
987
+ "context": context,
988
+ }
989
+ # §32 A3. Before effective_compaction, because this one is about
990
+ # THIS repository's own files rather than about the user's -- if
991
+ # it fires, every other startup check is reporting on a build that
992
+ # should not have shipped.
993
+ assert_spawnable_declared(_state["agents"])
994
+ # AFTER _state is assigned, because effective_compaction() reads
995
+ # get_settings(). Called here so an incoherent compaction block is a
996
+ # STARTUP error naming the file, rather than a ValueError from inside
997
+ # a compaction three hours into a long thread -- which is the one
998
+ # moment the user least wants to find out. §21's "reject at load time,
999
+ # not incoherent trigger math later".
1000
+ effective_compaction(warn=True)
1001
+
1002
+
1003
+ def assert_spawnable_declared(agents: dict) -> None:
1004
+ """Every HARNESS-tier agent must say whether it is spawnable.
1005
+
1006
+ ROADMAP_v2 §32 (A3). The same shape as
1007
+ tools.base.assert_grant_policy_declared and
1008
+ assert_budget_declared, and for the same stated reason: a field
1009
+ whose absence silently means something is a field nobody will
1010
+ remember to set. #69 exists because there was no field at all, so
1011
+ every agent inherited "spawnable" and four shipped ones were
1012
+ advertised as a delegation route that cannot carry them.
1013
+
1014
+ HARNESS TIER ONLY, and that asymmetry is the decision rather than
1015
+ an omission. These are files this project ships, so a missing
1016
+ declaration is a build error and CI is where it should surface.
1017
+ A user's or a project's agent gets the safe default instead --
1018
+ raising there would take down startup over somebody else's file,
1019
+ which is the trade _parse_md_file already refuses everywhere else
1020
+ in this module.
1021
+ """
1022
+ undeclared = sorted(
1023
+ f"{a.name} ({a.path})" for a in agents.values()
1024
+ if a.tier == "harness" and a.spawnable is None)
1025
+ if undeclared:
1026
+ raise RuntimeError(
1027
+ "These harness agents do not declare `spawnable` in their "
1028
+ "frontmatter, so nothing can tell whether spawn_subagent "
1029
+ "is able to feed them (ROADMAP_v2 §32 A3): "
1030
+ + ", ".join(undeclared))
1031
+
1032
+
1033
+ def reset() -> None:
1034
+ """Clear the startup cache (tests)."""
1035
+ global _state
1036
+ _state = None
1037
+
1038
+
1039
+ def get_agents() -> dict:
1040
+ """Empty before initialize(), matching every other getter here.
1041
+
1042
+ Uninitialized means "no discovery has run", which is materially the
1043
+ same state as "discovery ran and found nothing" for every consumer --
1044
+ both mean there are no agents to offer. get_agents/get_skills used to
1045
+ raise while get_settings/get_skill/skill_catalog_text/context_for_agent
1046
+ returned empty, so the answer to "is calling this before startup an
1047
+ error?" depended on which getter you happened to pick. Only main.py's
1048
+ __main__ calls initialize(); §16's TUI, §18 and §19 add more entry
1049
+ points, so one convention now beats six discoveries later.
1050
+ """
1051
+ if _state is None:
1052
+ return {}
1053
+ return dict(_state["agents"])
1054
+
1055
+
1056
+ def get_skills() -> dict:
1057
+ """Empty before initialize() -- see get_agents()."""
1058
+ if _state is None:
1059
+ return {}
1060
+ return dict(_state["skills"])
1061
+
1062
+
1063
+ def get_settings() -> dict:
1064
+ if _state is None:
1065
+ return {} # pre-init consumers fall through to config.py defaults
1066
+ return dict(_state["settings"])
1067
+
1068
+
1069
+ def spend_cap() -> Optional[int]:
1070
+ """The configured per-run spend ceiling (#4), or None for uncapped.
1071
+
1072
+ The single resolution point every path reaches through the loop
1073
+ wrappers' `_SPEND_UNSET` sentinel: chat turns, each research pass,
1074
+ /init, the reviewer and its retries. One number applies per _run()
1075
+ invocation -- a user turn, a pass, an init run -- because that is what
1076
+ a spend ceiling means; nothing here reasons about context size, which
1077
+ is thresholds()/context_limit()'s instrument (compaction has NEVER
1078
+ keyed off this figure).
1079
+
1080
+ None -- the default, with or without the key present -- runs uncapped:
1081
+ #4's whole point is that the harness's cumulative counter is a billing
1082
+ meter, and hard spend limits belong to the provider's dashboard.
1083
+ """
1084
+ return get_settings().get("max_token_budget")
1085
+
1086
+
1087
+ def get_project_path() -> Optional[str]:
1088
+ """The RESOLVED project path this session was initialized against.
1089
+
1090
+ ROADMAP_v2 §21b (M12/D25): a project-scoped memory is keyed to "the
1091
+ same resolved project path the workspace-trust store uses", so there
1092
+ has to be exactly one answer to "which project" across trust, config
1093
+ and memory. This is it -- the realpath already computed at
1094
+ initialize() time, not a fresh resolution that could differ.
1095
+
1096
+ None before initialize(), matching every other getter here. A caller
1097
+ that gets None has no project to scope to, which memories/manager.py
1098
+ treats as "global memories only" rather than as "show everything":
1099
+ guessing a project would surface another one's facts.
1100
+ """
1101
+ if _state is None:
1102
+ return None
1103
+ return _state["project_path"]
1104
+
1105
+
1106
+ def get_skill(name: str) -> Optional[SkillDef]:
1107
+ if _state is None:
1108
+ return None
1109
+ return _state["skills"].get(name)
1110
+
1111
+
1112
+ def get_agent(name: str) -> Optional[AgentDef]:
1113
+ """None before initialize() or for an unknown name -- see
1114
+ get_agents(). AgentManager (§18) is the consumer."""
1115
+ if _state is None:
1116
+ return None
1117
+ return _state["agents"].get(name)
1118
+
1119
+
1120
+ def context_for_agent(agent: Optional[AgentDef]) -> Optional[str]:
1121
+ """AGENTS.md is opt-in per agent (use_project_context), so no agent
1122
+ (or an agent without the flag) never pays its token cost. Untrusted
1123
+ projects have context=None regardless."""
1124
+ if _state is None or agent is None or not agent.use_project_context:
1125
+ return None
1126
+ return _state["context"]
1127
+
1128
+
1129
+ def skill_catalog_text(active: Optional[list] = None) -> str:
1130
+ """Frontmatter-only catalog for system prompt injection. Bodies are
1131
+ deliberately absent -- the model requests them via load_skill.
1132
+ Empty string when uninitialized or when no skills exist, so prompt
1133
+ assembly is a no-op append.
1134
+
1135
+ GROUPED BY CATEGORY (§19 K4). Uncategorised skills come first, then
1136
+ categories alphabetically, so a flat catalog reads exactly as it did
1137
+ before any category folder existed.
1138
+
1139
+ `active` names skills whose full body is already pinned into this
1140
+ prompt (§19 K1). They are MARKED rather than omitted: dropping them
1141
+ would make the catalog disagree with `/skill`'s listing, and leaving
1142
+ them unmarked invites the model to spend a turn calling load_skill for
1143
+ text it can already read.
1144
+ """
1145
+ if _state is None or not _state["skills"]:
1146
+ return ""
1147
+ active_set = set(active or ())
1148
+ lines = [
1149
+ "## Available skills",
1150
+ "The skills below are available in this session. Only their "
1151
+ "summaries are listed here; call the load_skill tool with a "
1152
+ "skill name to view a skill's full instructions before "
1153
+ "following one.",
1154
+ ]
1155
+ by_category: dict = {}
1156
+ for name in sorted(_state["skills"]):
1157
+ skill = _state["skills"][name]
1158
+ by_category.setdefault(skill.category, []).append(skill)
1159
+ # "" sorts before any real category name, which is the order wanted:
1160
+ # uncategorised first, then categories alphabetically.
1161
+ for category in sorted(by_category):
1162
+ if category:
1163
+ lines.append(f"### {category}")
1164
+ for skill in by_category[category]:
1165
+ suffix = (" [ACTIVE — full text below]"
1166
+ if skill.name in active_set else "")
1167
+ lines.append(f"- {skill.name}: {skill.description}{suffix}")
1168
+ return "\n".join(lines)
1169
+
1170
+
1171
+ def _catalog_entries(root: str, files: list) -> list:
1172
+ """(kind, name, description) for every agent/skill in the listing.
1173
+
1174
+ ROADMAP_v2 §32 A6, #131. The trust prompt's stated criterion is
1175
+ written in describe_project_content below -- the files shown
1176
+ verbatim are "the ones whose contents change what runs". An
1177
+ agent's and a skill's `description` meets it exactly: one `y` puts
1178
+ both into the system prompt of every run in this project, with no
1179
+ tool call and no further consent, and the reason they were left
1180
+ out was that nobody had noticed they qualify.
1181
+
1182
+ PARSED THROUGH _parse_md_file, so what is shown is the NORMALISED
1183
+ text -- the same value A5 will put in the prompt, not the raw
1184
+ frontmatter. That is the whole point of showing it: a summary
1185
+ displaying something other than what gets injected is a worse
1186
+ answer than showing nothing, because it invites trust in the
1187
+ wrong string. It also means the listing is bounded by
1188
+ construction, which is what makes printing it safe at all.
1189
+
1190
+ Runs on UNTRUSTED content by definition, so a file that will not
1191
+ parse is reported as unreadable rather than skipped in silence:
1192
+ 'this file is here and I cannot tell you what it says' is a fact
1193
+ the person answering the prompt needs.
1194
+ """
1195
+ out = []
1196
+ for rel in files:
1197
+ # §44: the listing is PROJECT-relative now, so the .venastine/
1198
+ # prefix is stripped before matching. Matching the raw string
1199
+ # would silently describe nothing -- the trust prompt would still
1200
+ # render, still list the files, and simply stop saying what any of
1201
+ # them would tell the model, which is the half #131 added.
1202
+ if not rel.startswith(".venastine/"):
1203
+ continue
1204
+ parts = rel[len(".venastine/"):].split("/")
1205
+ if len(parts) < 2 or parts[0] not in ("agents", "skills"):
1206
+ continue
1207
+ if not rel.lower().endswith(".md"):
1208
+ continue
1209
+ kind = parts[0]
1210
+ defn = _parse_md_file(os.path.join(root, *parts), kind,
1211
+ "project")
1212
+ if defn is None:
1213
+ out.append((kind, "/".join(parts),
1214
+ "(could not be read -- see the log)"))
1215
+ else:
1216
+ out.append((kind, defn.name, defn.description))
1217
+ return out
1218
+
1219
+
1220
+ #: How much of the project context document the trust prompt shows. Enough
1221
+ #: to recognise what the file is for, short enough that the prompt stays
1222
+ #: readable -- the whole thing is what a grant covers, not what it prints.
1223
+ _HUB_PREVIEW_LINES = 20
1224
+
1225
+
1226
+ def describe_project_content(project_path: str) -> str:
1227
+ """Human-readable summary shown in the trust prompt, so approving
1228
+ trust is an informed decision -- a project's settings can choose the
1229
+ provider and multiply pipeline cost via ensemble_n, and an agent's
1230
+ or a skill's description reaches every system prompt (#131)."""
1231
+ root = workspace_trust.venastine_dir(project_path)
1232
+ files = workspace_trust.content_files(project_path)
1233
+ lines = [f"Project content ({os.path.realpath(project_path)}):"]
1234
+ lines += [f" - {rel}" for rel in files]
1235
+
1236
+ # §44. The hub is shown VERBATIM, and it is the strongest instance of
1237
+ # this function's own stated criterion -- "the ones whose contents
1238
+ # change what runs". settings.json picks a provider and mcp.json names
1239
+ # a command; AGENTS.md is prose that goes into the system prompt of
1240
+ # every opted-in agent, which is the plainest form of "tells the model
1241
+ # what to do" this prompt can be asked to cover. Bounded to the first
1242
+ # few lines because a project's context document is not small and an
1243
+ # unbounded paste is a prompt nobody reads to the end of.
1244
+ hub = os.path.join(os.path.realpath(project_path),
1245
+ workspace_trust.PROJECT_CONTEXT_FILENAME)
1246
+ if os.path.exists(hub):
1247
+ try:
1248
+ with open(hub, "r", encoding="utf-8-sig") as f:
1249
+ body = f.read()
1250
+ except (OSError, UnicodeDecodeError) as e:
1251
+ lines.append(
1252
+ f"{workspace_trust.PROJECT_CONTEXT_FILENAME}: could not be "
1253
+ f"read ({e})")
1254
+ else:
1255
+ shown = body.splitlines()
1256
+ lines.append(
1257
+ f"{workspace_trust.PROJECT_CONTEXT_FILENAME} would enter "
1258
+ f"every opted-in agent's system prompt; it begins:")
1259
+ lines += [" | " + line for line in shown[:_HUB_PREVIEW_LINES]]
1260
+ if len(shown) > _HUB_PREVIEW_LINES:
1261
+ lines.append(
1262
+ f" | … {len(shown) - _HUB_PREVIEW_LINES} more lines")
1263
+
1264
+ # settings.json and mcp.json are shown VERBATIM, the rest by name.
1265
+ # These two are the ones whose contents change what runs: settings can
1266
+ # pick the provider and multiply pipeline cost via ensemble_n, and
1267
+ # mcp.json names a local command to execute. Approving trust without
1268
+ # seeing that command is not an informed decision, which is the whole
1269
+ # reason §17 moved project MCP config under .venastine/ instead of
1270
+ # leaving it at the project root outside the trust boundary.
1271
+ for fname, label in (("settings.json", "settings.json contents:"),
1272
+ ("mcp.json", "mcp.json contents (these commands would run):")):
1273
+ path = os.path.join(root, fname)
1274
+ if not os.path.exists(path):
1275
+ continue
1276
+ try:
1277
+ with open(path, "r", encoding="utf-8-sig") as f:
1278
+ body = f.read()
1279
+ except (OSError, UnicodeDecodeError) as e:
1280
+ # This function runs ONLY for untrusted projects, i.e. content
1281
+ # that is adversarial by definition. UnicodeDecodeError is a
1282
+ # ValueError, not an OSError, so without it here a UTF-16
1283
+ # settings.json kills startup before the trust prompt renders
1284
+ # -- including the non-TTY notice and the --trust-project path,
1285
+ # making trust ungrantable for that project.
1286
+ lines.append(f"{fname}: could not be read ({e})")
1287
+ continue
1288
+ lines.append(label)
1289
+ lines += [" | " + line for line in body.splitlines()]
1290
+
1291
+ # §32 A6. Shown AFTER the two config files rather than beside the
1292
+ # file list, because the list answers "what is here" and this
1293
+ # answers "what would it say to the model" -- the same order the
1294
+ # two questions are asked in.
1295
+ entries = _catalog_entries(root, files)
1296
+ if entries:
1297
+ lines.append("these descriptions enter EVERY system prompt in "
1298
+ "this project:")
1299
+ for kind, name, description in entries:
1300
+ lines.append(f" | {kind[:-1]} {name}: {description}")
1301
+ return "\n".join(lines)
1302
+
1303
+
1304
+ # ---------------------------------------------------------------------------
1305
+ # ---- §45 (SQ6): the scoring knobs -----------------------------------------
1306
+ # ---------------------------------------------------------------------------
1307
+ #
1308
+ # WHY THESE TWO SECTIONS RESOLVE DIFFERENTLY FROM COMPACTION, and it is a
1309
+ # deliberate amendment rather than an oversight. `effective_compaction`
1310
+ # RAISES on an incoherent value, because a bad trigger burns real model
1311
+ # calls on every turn of every conversation. A bad scoring weight costs
1312
+ # the shape of one number in one report -- and refusing to start a
1313
+ # ten-pass run over a mistyped weight is the worse failure. So a known key
1314
+ # with an out-of-range value FALLS BACK to its own default and warns; only
1315
+ # that one value is discarded, never the whole section.
1316
+ #
1317
+ # Unknown KEYS still raise, unchanged. That is a schema question rather
1318
+ # than a range one, and §14's loud-rejection rule is what makes adding a
1319
+ # setting a deliberate act.
1320
+ #
1321
+ # TOP-LEVEL SECTIONS, not `research.confidence`. `_NESTED_SETTINGS`
1322
+ # supports exactly one level of nesting and both the validator and the
1323
+ # cross-tier merge iterate it; deepening that merge is the code path
1324
+ # review finding F2 already broke once, and these need no new mechanism to
1325
+ # sit beside `compaction` and `tui`.
1326
+
1327
+ # key -> (module attribute it defaults from, validator)
1328
+ #
1329
+ # The defaults live BESIDE THE FORMULA rather than in config.py: the
1330
+ # tunable-weights block at the top of confidence_scoring.py documents what
1331
+ # each number does and why it is that number, and a second copy here is a
1332
+ # second thing to keep in step. Imported lazily inside the resolver, the
1333
+ # same shape effective_compaction uses for `config`.
1334
+ _UNIT = ("a number between 0 and 1", lambda v: isinstance(v, NUMBER_TYPES)
1335
+ and not isinstance(v, bool) and 0.0 <= v <= 1.0)
1336
+ _POSITIVE_INT = ("a positive whole number",
1337
+ lambda v: isinstance(v, int) and not isinstance(v, bool) and v > 0)
1338
+ _NON_NEGATIVE_INT = ("a whole number of 0 or more",
1339
+ lambda v: isinstance(v, int) and not isinstance(v, bool) and v >= 0)
1340
+
1341
+ _CONFIDENCE_KNOBS = {
1342
+ "grounding_weight_factor": _UNIT,
1343
+ "critic_weight_factor": _UNIT,
1344
+ "assumption_flag_penalty": _UNIT,
1345
+ "disagreement_penalty_factor": _UNIT,
1346
+ "non_factual_score_cap": _UNIT,
1347
+ "source_quality_floor": _UNIT,
1348
+ "authority_full_credit": _UNIT,
1349
+ }
1350
+
1351
+ _SOURCE_SCORING_KNOBS = {
1352
+ "similarity_floor": _UNIT,
1353
+ "similarity_ceiling": _UNIT,
1354
+ "authority_adjustment_cap": _UNIT,
1355
+ "window_chars": _POSITIVE_INT,
1356
+ "max_windows": _POSITIVE_INT,
1357
+ "claim_min_chars": _NON_NEGATIVE_INT,
1358
+ "top_k": _POSITIVE_INT,
1359
+ "venue_weight": _UNIT,
1360
+ "citation_weight": _UNIT,
1361
+ "author_weight": _UNIT,
1362
+ "h_saturation": _POSITIVE_INT,
1363
+ "min_cohort_size": _POSITIVE_INT,
1364
+ "min_citation_age_days": _NON_NEGATIVE_INT,
1365
+ }
1366
+
1367
+
1368
+ def _confidence_defaults() -> dict:
1369
+ from core.reasoning import confidence_scoring as cs
1370
+
1371
+ return {
1372
+ "grounding_weight_factor": cs.GROUNDING_WEIGHT_FACTOR,
1373
+ "critic_weight_factor": cs.CRITIC_WEIGHT_FACTOR,
1374
+ "assumption_flag_penalty": cs.ASSUMPTION_FLAG_PENALTY,
1375
+ "disagreement_penalty_factor": cs.DISAGREEMENT_PENALTY_FACTOR,
1376
+ "non_factual_score_cap": cs.NON_FACTUAL_SCORE_CAP,
1377
+ "source_quality_floor": cs.SOURCE_QUALITY_FLOOR,
1378
+ "authority_full_credit": cs.AUTHORITY_FULL_CREDIT,
1379
+ "grounding_weights": dict(cs.GROUNDING_WEIGHTS),
1380
+ "tier_thresholds": {name: value for value, name in cs.TIER_THRESHOLDS},
1381
+ }
1382
+
1383
+
1384
+ def _source_scoring_defaults() -> dict:
1385
+ import config
1386
+ from core.reasoning import source_scoring as ss
1387
+
1388
+ return {
1389
+ "similarity_floor": None, # None means "use the per-model table"
1390
+ "similarity_ceiling": None,
1391
+ "authority_adjustment_cap": config.AUTHORITY_ADJUSTMENT_CAP,
1392
+ "window_chars": ss.WINDOW_CHARS,
1393
+ "max_windows": ss.MAX_WINDOWS,
1394
+ "claim_min_chars": ss.CLAIM_MIN_CHARS,
1395
+ "top_k": ss.TOP_K,
1396
+ "venue_weight": config.SCHOLAR_VENUE_WEIGHT,
1397
+ "citation_weight": config.SCHOLAR_CITATION_WEIGHT,
1398
+ "author_weight": config.SCHOLAR_AUTHOR_WEIGHT,
1399
+ "h_saturation": config.SCHOLAR_H_SATURATION,
1400
+ "min_cohort_size": config.SCHOLAR_MIN_COHORT_SIZE,
1401
+ "min_citation_age_days": config.SCHOLAR_MIN_CITATION_AGE_DAYS,
1402
+ "domain_overrides": {},
1403
+ }
1404
+
1405
+
1406
+ def _apply_scalar_knobs(values, supplied, knobs, section, warn):
1407
+ """Overlay `supplied` onto `values`, dropping what does not validate.
1408
+
1409
+ PER KEY, not per section. One mistyped weight must not discard the
1410
+ nine beside it that were right -- a user retuning six numbers and
1411
+ fat-fingering the seventh should get six retuned numbers and one
1412
+ sentence about the seventh, not silently get none of them.
1413
+ """
1414
+ for key, value in supplied.items():
1415
+ if key not in knobs:
1416
+ continue
1417
+ description, is_valid = knobs[key]
1418
+ if is_valid(value):
1419
+ values[key] = value
1420
+ elif warn:
1421
+ logger.warning(
1422
+ "%s.%s must be %s, got %r -- using the default %r for this "
1423
+ "run.", section, key, description, value, values[key])
1424
+
1425
+
1426
+ def _apply_grounding_weights(values, supplied, warn):
1427
+ """`grounding_weights` -- a dict whose KEYS are a closed vocabulary."""
1428
+ if not isinstance(supplied, dict):
1429
+ if warn and supplied is not None:
1430
+ logger.warning("confidence.grounding_weights must be an object, "
1431
+ "got %r -- using the defaults for this run.",
1432
+ type(supplied).__name__)
1433
+ return
1434
+ merged = dict(values["grounding_weights"])
1435
+ for status, weight in supplied.items():
1436
+ if status not in GROUNDING_STATUSES:
1437
+ if warn:
1438
+ logger.warning(
1439
+ "confidence.grounding_weights has an unknown status %r "
1440
+ "-- expected one of %s. Ignored for this run.",
1441
+ status, ", ".join(sorted(GROUNDING_STATUSES)))
1442
+ continue
1443
+ if isinstance(weight, NUMBER_TYPES) and not isinstance(weight, bool) \
1444
+ and 0.0 <= weight <= 1.0:
1445
+ merged[status] = weight
1446
+ elif warn:
1447
+ logger.warning(
1448
+ "confidence.grounding_weights[%r] must be a number between 0 "
1449
+ "and 1, got %r -- using the default for this run.",
1450
+ status, weight)
1451
+ values["grounding_weights"] = merged
1452
+
1453
+
1454
+ def _apply_tier_thresholds(values, supplied, warn):
1455
+ """`tier_thresholds` -- three numbers that must STAY ORDERED.
1456
+
1457
+ The relational check `effective_compaction` makes for warning_margin,
1458
+ applied to the one relationship here whose breakage is not
1459
+ self-correcting: thresholds out of order make a tier unreachable, so a
1460
+ claim scoring 0.9 could be published LOW while the table a reader
1461
+ consults says HIGH starts at 0.8. Out of order, the whole table falls
1462
+ back rather than a single value -- unlike the scalars above, because
1463
+ these three are only meaningful together.
1464
+ """
1465
+ if not isinstance(supplied, dict):
1466
+ if warn and supplied is not None:
1467
+ logger.warning("confidence.tier_thresholds must be an object, "
1468
+ "got %r -- using the defaults for this run.",
1469
+ type(supplied).__name__)
1470
+ return
1471
+ merged = dict(values["tier_thresholds"])
1472
+ for name, value in supplied.items():
1473
+ if name not in merged:
1474
+ if warn:
1475
+ logger.warning(
1476
+ "confidence.tier_thresholds has an unknown tier %r -- "
1477
+ "expected one of %s. Ignored for this run.",
1478
+ name, ", ".join(merged))
1479
+ continue
1480
+ if isinstance(value, NUMBER_TYPES) and not isinstance(value, bool) \
1481
+ and 0.0 <= value <= 1.0:
1482
+ merged[name] = value
1483
+ elif warn:
1484
+ logger.warning(
1485
+ "confidence.tier_thresholds[%r] must be a number between 0 "
1486
+ "and 1, got %r -- using the defaults for this run.",
1487
+ name, value)
1488
+
1489
+ ordered = [merged.get(name) for name in ("HIGH", "MEDIUM", "LOW")]
1490
+ if not (ordered[0] > ordered[1] > ordered[2]):
1491
+ if warn:
1492
+ logger.warning(
1493
+ "confidence.tier_thresholds must descend HIGH > MEDIUM > LOW, "
1494
+ "got %s -- using the defaults for this run. Out of order, a "
1495
+ "tier becomes unreachable and a published tier stops matching "
1496
+ "the table that defines it.", merged)
1497
+ return
1498
+ values["tier_thresholds"] = merged
1499
+
1500
+
1501
+ def effective_confidence(warn: bool = False) -> dict:
1502
+ """Pass 5's constants, as they are actually in force.
1503
+
1504
+ config default (from confidence_scoring's own tunable block) -> user
1505
+ settings.json -> trusted project settings.json. Nearest wins, the
1506
+ precedence the rest of the config system uses.
1507
+
1508
+ RESOLVED ONCE PER RUN by the caller, never per claim: score_claim is a
1509
+ pure function and stays one, the warnings are said once rather than
1510
+ once per claim (`effective_compaction`'s `warn=True` gating, for its
1511
+ reason), and a run's numbers cannot change halfway through.
1512
+ """
1513
+ values = _confidence_defaults()
1514
+ supplied = get_settings().get("confidence") or {}
1515
+ _apply_scalar_knobs(values, supplied, _CONFIDENCE_KNOBS, "confidence", warn)
1516
+ _apply_grounding_weights(values, supplied.get("grounding_weights"), warn)
1517
+ _apply_tier_thresholds(values, supplied.get("tier_thresholds"), warn)
1518
+ return values
1519
+
1520
+
1521
+ def effective_source_scoring(warn: bool = False) -> dict:
1522
+ """§45's scoring knobs, as they are actually in force.
1523
+
1524
+ `similarity_floor` / `similarity_ceiling` default to None, meaning
1525
+ "use the per-model calibration table". A user who sets them is saying
1526
+ their embedder's band is not what the table thinks, which outranks a
1527
+ table that cannot know about a model shipped after this release --
1528
+ `model_windows`' inversion, for its reason.
1529
+ """
1530
+ values = _source_scoring_defaults()
1531
+ supplied = get_settings().get("source_scoring") or {}
1532
+ _apply_scalar_knobs(values, supplied, _SOURCE_SCORING_KNOBS,
1533
+ "source_scoring", warn)
1534
+
1535
+ overrides = supplied.get("domain_overrides")
1536
+ if isinstance(overrides, dict):
1537
+ kept = {}
1538
+ for host, score in overrides.items():
1539
+ if isinstance(host, str) and host and \
1540
+ isinstance(score, NUMBER_TYPES) and \
1541
+ not isinstance(score, bool) and 0.0 <= score <= 1.0:
1542
+ kept[host.lower().lstrip(".")] = float(score)
1543
+ elif warn:
1544
+ logger.warning(
1545
+ "source_scoring.domain_overrides[%r] must be a number "
1546
+ "between 0 and 1, got %r -- ignored for this run.",
1547
+ host, score)
1548
+ values["domain_overrides"] = kept
1549
+ elif overrides is not None and warn:
1550
+ logger.warning("source_scoring.domain_overrides must be an object, "
1551
+ "got %r -- ignored for this run.",
1552
+ type(overrides).__name__)
1553
+
1554
+ floor = values["similarity_floor"]
1555
+ ceiling = values["similarity_ceiling"]
1556
+ if floor is not None and ceiling is not None and floor >= ceiling:
1557
+ if warn:
1558
+ logger.warning(
1559
+ "source_scoring.similarity_floor (%s) must be below "
1560
+ "similarity_ceiling (%s) -- falling back to this embedder's "
1561
+ "own calibration for this run.", floor, ceiling)
1562
+ values["similarity_floor"] = values["similarity_ceiling"] = None
1563
+ return values