@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.
- package/.env.example +14 -0
- package/LICENSE +201 -0
- package/NOTICE +14 -0
- package/PRIVACY.md +66 -0
- package/README.md +878 -0
- package/SECURITY.md +88 -0
- package/THIRD_PARTY_NOTICES.md +100 -0
- package/agents/builtin/compactor.md +75 -0
- package/agents/builtin/explore.md +77 -0
- package/agents/builtin/grill-me.md +27 -0
- package/agents/builtin/initializer.md +94 -0
- package/agents/builtin/pipeline-reviewer.md +100 -0
- package/agents/builtin/plan.md +88 -0
- package/agents/builtin/review.md +74 -0
- package/agents/manager.py +195 -0
- package/agents/subagent_tool.py +215 -0
- package/agents/tui_commands.py +136 -0
- package/bin/venastine.mjs +382 -0
- package/config.py +1198 -0
- package/core/__init__.py +0 -0
- package/core/approval.py +115 -0
- package/core/client.py +1548 -0
- package/core/compaction.py +959 -0
- package/core/config_loader.py +1563 -0
- package/core/events.py +61 -0
- package/core/interaction.py +328 -0
- package/core/loop.py +1353 -0
- package/core/memory.py +370 -0
- package/core/model_windows.py +175 -0
- package/core/pipeline_models.py +176 -0
- package/core/reasoning/__init__.py +0 -0
- package/core/reasoning/authorization.py +130 -0
- package/core/reasoning/base.py +219 -0
- package/core/reasoning/confidence_scoring.py +468 -0
- package/core/reasoning/events.py +149 -0
- package/core/reasoning/json_retry.py +219 -0
- package/core/reasoning/orchestrator.py +1382 -0
- package/core/reasoning/output_writer.py +286 -0
- package/core/reasoning/payload_validation.py +398 -0
- package/core/reasoning/pipeline_storage.py +361 -0
- package/core/reasoning/review.py +615 -0
- package/core/reasoning/scholar.py +434 -0
- package/core/reasoning/source_corpus.py +327 -0
- package/core/reasoning/source_scoring.py +855 -0
- package/core/replay.py +167 -0
- package/core/session.py +153 -0
- package/core/workspace_trust.py +207 -0
- package/credentials.py +180 -0
- package/database.py +252 -0
- package/env_secrets.py +77 -0
- package/json_store.py +123 -0
- package/logging_setup.py +185 -0
- package/main.py +1959 -0
- package/mcp_client/__init__.py +15 -0
- package/mcp_client/client.py +499 -0
- package/mcp_client/config.py +379 -0
- package/mcp_client/registration.py +182 -0
- package/memories/manager.py +132 -0
- package/memories/tui_commands.py +232 -0
- package/package.json +73 -0
- package/project_init/config_files.py +278 -0
- package/project_init/doc_sets.py +330 -0
- package/project_init/generator.py +564 -0
- package/project_init/manifest.py +406 -0
- package/project_init/tui_commands.py +144 -0
- package/prompts/__init__.py +0 -0
- package/prompts/annotate.md +14 -0
- package/prompts/assumption_audit.md +27 -0
- package/prompts/claim_extraction.md +34 -0
- package/prompts/completeness.md +18 -0
- package/prompts/confidence_tiers.md +23 -0
- package/prompts/critic_pass.md +24 -0
- package/prompts/final_synthesis.md +13 -0
- package/prompts/initial_generation.md +14 -0
- package/prompts/preliminary_plan.md +23 -0
- package/prompts/revalidate.md +25 -0
- package/prompts/revise.md +15 -0
- package/prompts/source_grounding.md +66 -0
- package/prompts/system_prompts.py +262 -0
- package/prompts/universal_system_prompt +7 -0
- package/prompts/untrusted_content +1 -0
- package/providers.json.example +92 -0
- package/pyproject.toml +100 -0
- package/requirements.txt +72 -0
- package/safety/__init__.py +0 -0
- package/safety/policy_enforcement.py +682 -0
- package/security/__init__.py +0 -0
- package/security/capability.py +177 -0
- package/security/permissions.py +190 -0
- package/security/posture.py +302 -0
- package/security/protected_paths.py +309 -0
- package/security/sandbox.py +985 -0
- package/skills/builtin/crypto/cryptography-verification.md +66 -0
- package/skills/builtin/math/formal-specification.md +67 -0
- package/skills/builtin/math/numerical-methods.md +66 -0
- package/skills/builtin/math/proof-writing.md +61 -0
- package/skills/builtin/research/experiment-design.md +62 -0
- package/skills/builtin/research/literature-review.md +65 -0
- package/skills/builtin/research/reproducibility.md +55 -0
- package/skills/builtin/research/source-evaluation.md +70 -0
- package/skills/builtin/research/statistical-inference.md +63 -0
- package/skills/builtin/research/technical-writing.md +59 -0
- package/skills/builtin/security/cybersecurity-research.md +63 -0
- package/skills/builtin/software/code-review.md +61 -0
- package/skills/builtin/software/debugging.md +61 -0
- package/skills/builtin/software/test-design.md +67 -0
- package/skills/manager.py +138 -0
- package/skills/tui_commands.py +111 -0
- package/storage.py +1005 -0
- package/tools/base.py +305 -0
- package/tools/builtin/__init__.py +0 -0
- package/tools/builtin/_math_common.py +377 -0
- package/tools/builtin/_net_common.py +61 -0
- package/tools/builtin/arxiv.py +223 -0
- package/tools/builtin/ask_user.py +213 -0
- package/tools/builtin/discrete_math.py +134 -0
- package/tools/builtin/fetch_url.py +153 -0
- package/tools/builtin/file_ops.py +412 -0
- package/tools/builtin/geometry.py +148 -0
- package/tools/builtin/get_time.py +20 -0
- package/tools/builtin/linear_algebra.py +155 -0
- package/tools/builtin/load_skill.py +66 -0
- package/tools/builtin/logic.py +96 -0
- package/tools/builtin/pin.py +193 -0
- package/tools/builtin/probability_stats.py +228 -0
- package/tools/builtin/project_docs.py +405 -0
- package/tools/builtin/remember.py +158 -0
- package/tools/builtin/shell.py +461 -0
- package/tools/builtin/symbolic_math.py +119 -0
- package/tools/builtin/todo.py +147 -0
- package/tools/builtin/web_search.py +151 -0
- package/tools/context.py +136 -0
- package/tools/isolation.py +314 -0
- package/tools/registry.py +897 -0
- package/tui/app.py +3423 -0
- package/tui/app.tcss +458 -0
- package/tui/commands.py +61 -0
- package/tui/diffs.py +265 -0
- package/tui/preferences.py +182 -0
- package/tui/ravens.py +146 -0
- package/tui/screens.py +943 -0
- package/tui/themes.py +366 -0
- package/tui/widgets.py +1239 -0
|
@@ -0,0 +1,278 @@
|
|
|
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
|
|
@@ -0,0 +1,330 @@
|
|
|
1
|
+
"""
|
|
2
|
+
project_init/doc_sets.py
|
|
3
|
+
|
|
4
|
+
ROADMAP_v2 §24 (I9-I12): WHICH documents `/init` scaffolds, where each one
|
|
5
|
+
lives, and what an unwritten one looks like.
|
|
6
|
+
|
|
7
|
+
Data and pure rendering only -- no model call, no filesystem, no decisions
|
|
8
|
+
about when to write. That split is why the allowlist `write_project_doc`
|
|
9
|
+
enforces can be read from here without a cycle, and why the templates below
|
|
10
|
+
can be asserted against directly in tests.
|
|
11
|
+
|
|
12
|
+
THE HUB IS THE POINT. AGENTS.md is the only document §14's loader reads,
|
|
13
|
+
and the only one injected into an opted-in agent's prompt. Everything else
|
|
14
|
+
is an ordinary committed root file that AGENTS.md links out to -- so the
|
|
15
|
+
one file the model always sees is also the map of the ones it does not.
|
|
16
|
+
That index is generated from these tuples rather than written by the model
|
|
17
|
+
(I11): a model listing its own documents is a model that can get a relative
|
|
18
|
+
path wrong in the single file every agent reads.
|
|
19
|
+
|
|
20
|
+
THE HUB IS AGENTS.md AND IT LIVES AT THE ROOT (§44, reversing I9). I9 put
|
|
21
|
+
it in `.venastine/` so the one file every agent reads sat inside the trust
|
|
22
|
+
boundary. The boundary is still there -- workspace_trust.content_files()
|
|
23
|
+
covers the root AGENTS.md explicitly, and a grant is still what lets it
|
|
24
|
+
load -- but the FILE is now an ordinary committed document, for two
|
|
25
|
+
reasons that pull the same way. A project shared without `.venastine/`
|
|
26
|
+
(because its owner did not want to ship their configuration) previously
|
|
27
|
+
arrived as a set of documents pointing at a hub that was not in the
|
|
28
|
+
archive. And AGENTS.md is the filename other harnesses already look for,
|
|
29
|
+
so a project this command initializes is legible to them without a second
|
|
30
|
+
copy of the same content under a second name -- which is the failure this
|
|
31
|
+
repository records about itself at the top of its own AGENTS.md.
|
|
32
|
+
|
|
33
|
+
STUBS, NOT INVENTED CONTENT (I10). AGENTS.md is generated in full by a
|
|
34
|
+
model that has actually read the project. These are skeletons: real
|
|
35
|
+
headings, and for each one a statement of what belongs in it and what does
|
|
36
|
+
not. A DEVLOG written for a project with no history, or an ARCHITECTURE
|
|
37
|
+
describing code an agent skimmed once, is confident fiction -- in files
|
|
38
|
+
that then get committed, linked from the hub, and read as established fact.
|
|
39
|
+
An honest empty section outperforms a plausible wrong one.
|
|
40
|
+
"""
|
|
41
|
+
|
|
42
|
+
from __future__ import annotations
|
|
43
|
+
|
|
44
|
+
from typing import Optional
|
|
45
|
+
|
|
46
|
+
# The name lives in core/workspace_trust because the load-bearing fact
|
|
47
|
+
# about it is that a grant covers it. Imported rather than repeated: three
|
|
48
|
+
# copies of this literal is how one of them goes stale.
|
|
49
|
+
from core.workspace_trust import PROJECT_CONTEXT_FILENAME as HUB
|
|
50
|
+
|
|
51
|
+
SOFTWARE = "software"
|
|
52
|
+
RESEARCH = "research"
|
|
53
|
+
PROJECT_KINDS = (SOFTWARE, RESEARCH)
|
|
54
|
+
|
|
55
|
+
# The shared spine. DOCUMENTATION_STANDARDS is in both sets because the
|
|
56
|
+
# question it answers -- how this project writes things down -- is not
|
|
57
|
+
# specific to either kind, and a project that answers it early is the one
|
|
58
|
+
# whose docs still agree with each other a year later.
|
|
59
|
+
_SHARED = ("DOCUMENTATION_STANDARDS.md",)
|
|
60
|
+
|
|
61
|
+
_SOFTWARE_DOCS = _SHARED + (
|
|
62
|
+
"ARCHITECTURE.md",
|
|
63
|
+
"ROADMAP.md",
|
|
64
|
+
"DEVLOG.md",
|
|
65
|
+
"TECHNICAL_DEBT.md",
|
|
66
|
+
"TEST_WRITING.md",
|
|
67
|
+
"BREAKING_CHANGES.md",
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
_RESEARCH_DOCS = _SHARED + (
|
|
71
|
+
"RESEARCH_QUESTIONS.md",
|
|
72
|
+
"METHODOLOGY.md",
|
|
73
|
+
"SOURCES.md",
|
|
74
|
+
"FINDINGS.md",
|
|
75
|
+
"LIMITATIONS.md",
|
|
76
|
+
"EXPERIMENT_LOG.md",
|
|
77
|
+
"OPEN_QUESTIONS.md",
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
_SETS = {SOFTWARE: _SOFTWARE_DOCS, RESEARCH: _RESEARCH_DOCS}
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def document_set(kind: str) -> tuple:
|
|
84
|
+
"""The non-hub documents for a project kind, in the order they should
|
|
85
|
+
appear in AGENTS.md's index. Raises on an unknown kind rather than
|
|
86
|
+
defaulting to software: a caller that got the kind wrong would scaffold
|
|
87
|
+
the wrong seven files and only find out by reading them."""
|
|
88
|
+
if kind not in _SETS:
|
|
89
|
+
raise ValueError(
|
|
90
|
+
f"Unknown project kind {kind!r}; expected one of "
|
|
91
|
+
f"{', '.join(PROJECT_KINDS)}.")
|
|
92
|
+
return _SETS[kind]
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def all_document_names() -> frozenset:
|
|
96
|
+
"""Every name `write_project_doc` will accept -- both sets plus the hub.
|
|
97
|
+
|
|
98
|
+
The union, not the current project's set, and deliberately: a project
|
|
99
|
+
that started as research and grew a codebase should be able to gain an
|
|
100
|
+
ARCHITECTURE.md without /init having to re-classify it first. The
|
|
101
|
+
confinement this provides is "a known document name, never a path",
|
|
102
|
+
which is unaffected by the set being the larger one.
|
|
103
|
+
"""
|
|
104
|
+
return frozenset((HUB,) + _SOFTWARE_DOCS + _RESEARCH_DOCS)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
# ---------------------------------------------------------------------------
|
|
108
|
+
# ---- Stub content ---------------------------------------------------------
|
|
109
|
+
# ---------------------------------------------------------------------------
|
|
110
|
+
|
|
111
|
+
# name -> (one-line purpose, belongs, does not belong, [section headings])
|
|
112
|
+
_STUBS: dict = {
|
|
113
|
+
"DOCUMENTATION_STANDARDS.md": (
|
|
114
|
+
"How this project writes things down, so its documents stay usable "
|
|
115
|
+
"as they grow.",
|
|
116
|
+
"Where each kind of information goes; what a good entry looks like; "
|
|
117
|
+
"the conventions that keep documents from drifting apart.",
|
|
118
|
+
"The information itself. This describes the containers, not the "
|
|
119
|
+
"contents.",
|
|
120
|
+
["Which document holds what", "Writing conventions",
|
|
121
|
+
"When to update which file", "Review checklist"],
|
|
122
|
+
),
|
|
123
|
+
"ARCHITECTURE.md": (
|
|
124
|
+
"What exists, how the pieces fit, and which boundaries are "
|
|
125
|
+
"deliberate.",
|
|
126
|
+
"Component responsibilities stated as what belongs here and what "
|
|
127
|
+
"does NOT; the data flow between them; the constraints a change has "
|
|
128
|
+
"to respect; known gotchas that have already cost someone a day.",
|
|
129
|
+
"Plans and intentions -- those are ROADMAP.md. A narrative of how "
|
|
130
|
+
"the code got this way -- that is DEVLOG.md.",
|
|
131
|
+
["Overview", "Components and their boundaries", "Data flow",
|
|
132
|
+
"Invariants that look like simplification opportunities",
|
|
133
|
+
"Known gotchas"],
|
|
134
|
+
),
|
|
135
|
+
"ROADMAP.md": (
|
|
136
|
+
"What is planned, what is built, and the decisions that are locked.",
|
|
137
|
+
"Sections with stable numbers so they can be cross-referenced; "
|
|
138
|
+
"acceptance criteria per section; a decisions record whose entries "
|
|
139
|
+
"are never renumbered.",
|
|
140
|
+
"What was actually done and how it deviated -- that is DEVLOG.md.",
|
|
141
|
+
["Status index", "Planned work", "Acceptance criteria",
|
|
142
|
+
"Decisions record"],
|
|
143
|
+
),
|
|
144
|
+
"DEVLOG.md": (
|
|
145
|
+
"What was actually built, in order, including where it departed "
|
|
146
|
+
"from the plan.",
|
|
147
|
+
"One entry per unit of work: what was followed verbatim, what was "
|
|
148
|
+
"deviated from and on whose decision, what the implementation "
|
|
149
|
+
"turned up that the plan did not anticipate.",
|
|
150
|
+
"Anything speculative. An entry is written after the work, not "
|
|
151
|
+
"before it.",
|
|
152
|
+
["How to read this file", "Entries"],
|
|
153
|
+
),
|
|
154
|
+
"TECHNICAL_DEBT.md": (
|
|
155
|
+
"Known compromises, why they were accepted, and what it would take "
|
|
156
|
+
"to undo them.",
|
|
157
|
+
"Numbered items that stay numbered; the symptom, the cause, the "
|
|
158
|
+
"cost of leaving it, and the shape of the real fix.",
|
|
159
|
+
"Bugs. A bug is something to fix; debt is something that was chosen "
|
|
160
|
+
"with the tradeoff understood.",
|
|
161
|
+
["Open items", "Resolved items"],
|
|
162
|
+
),
|
|
163
|
+
"TEST_WRITING.md": (
|
|
164
|
+
"How this project tests, and what makes a test here worth having.",
|
|
165
|
+
"How to run the suite; the fixtures and doubles available and what "
|
|
166
|
+
"they do NOT model; the rule that a new test must fail when the fix "
|
|
167
|
+
"it covers is reverted.",
|
|
168
|
+
"What each individual test asserts -- the tests say that "
|
|
169
|
+
"themselves.",
|
|
170
|
+
["Running the tests", "Fixtures and test doubles",
|
|
171
|
+
"What makes a test worth having", "Patterns to follow",
|
|
172
|
+
"Patterns to avoid"],
|
|
173
|
+
),
|
|
174
|
+
"BREAKING_CHANGES.md": (
|
|
175
|
+
"What breaks each test when production code changes, and how to "
|
|
176
|
+
"fix it.",
|
|
177
|
+
"Per area: the change that breaks it, the symptom you will see, and "
|
|
178
|
+
"the fix. Written for the person staring at a red suite who did not "
|
|
179
|
+
"write the test.",
|
|
180
|
+
"Changes that break nothing. This file earns its keep by being "
|
|
181
|
+
"short and true.",
|
|
182
|
+
["How to use this file", "By area"],
|
|
183
|
+
),
|
|
184
|
+
"RESEARCH_QUESTIONS.md": (
|
|
185
|
+
"What this project is trying to find out, and why it is worth "
|
|
186
|
+
"finding out.",
|
|
187
|
+
"Each question stated so it could be answered wrongly; why it "
|
|
188
|
+
"matters; what would count as an answer.",
|
|
189
|
+
"Answers. Those are FINDINGS.md, and keeping them apart is what "
|
|
190
|
+
"stops a question being quietly rewritten to match what was found.",
|
|
191
|
+
["Primary questions", "Secondary questions",
|
|
192
|
+
"What would count as an answer", "Out of scope"],
|
|
193
|
+
),
|
|
194
|
+
"METHODOLOGY.md": (
|
|
195
|
+
"How evidence is gathered here, and how it is judged.",
|
|
196
|
+
"The procedure, in enough detail to be repeated; inclusion and "
|
|
197
|
+
"exclusion criteria; how confidence is assigned; what is done about "
|
|
198
|
+
"a result that does not replicate.",
|
|
199
|
+
"The results of applying it.",
|
|
200
|
+
["Approach", "Procedure", "Inclusion and exclusion criteria",
|
|
201
|
+
"How confidence is assigned", "Threats to validity"],
|
|
202
|
+
),
|
|
203
|
+
"SOURCES.md": (
|
|
204
|
+
"Where the evidence came from, in enough detail to be checked.",
|
|
205
|
+
"Full citations; data provenance and retrieval dates; what each "
|
|
206
|
+
"source is relied on FOR, which is the part a bare bibliography "
|
|
207
|
+
"loses.",
|
|
208
|
+
"Conclusions drawn from a source.",
|
|
209
|
+
["Primary sources", "Secondary sources", "Datasets",
|
|
210
|
+
"Retrieval notes"],
|
|
211
|
+
),
|
|
212
|
+
"FINDINGS.md": (
|
|
213
|
+
"What has been established, and how firmly.",
|
|
214
|
+
"One finding per entry, each with its supporting sources and a "
|
|
215
|
+
"stated confidence; negative results, which are findings and are "
|
|
216
|
+
"the ones most often left out.",
|
|
217
|
+
"Anything unsupported. A hypothesis lives in RESEARCH_QUESTIONS.md "
|
|
218
|
+
"until something backs it.",
|
|
219
|
+
["Established", "Provisional", "Negative results"],
|
|
220
|
+
),
|
|
221
|
+
"LIMITATIONS.md": (
|
|
222
|
+
"What this work cannot claim, stated by the people best placed to "
|
|
223
|
+
"know.",
|
|
224
|
+
"Scope boundaries; where the method is weakest; the results a "
|
|
225
|
+
"reader might reasonably over-read, named before someone else "
|
|
226
|
+
"names them.",
|
|
227
|
+
"Apologies. A limitation is a fact about the work's reach.",
|
|
228
|
+
["Scope", "Methodological limitations", "Known confounds",
|
|
229
|
+
"What these results do not show"],
|
|
230
|
+
),
|
|
231
|
+
"EXPERIMENT_LOG.md": (
|
|
232
|
+
"What was run, when, and what came out -- including the runs that "
|
|
233
|
+
"went nowhere.",
|
|
234
|
+
"One entry per run: configuration, date, outcome, and what was "
|
|
235
|
+
"changed as a result. Failed and abandoned runs especially, since "
|
|
236
|
+
"they are what stops the same dead end being explored twice.",
|
|
237
|
+
"Polished conclusions. Those are FINDINGS.md.",
|
|
238
|
+
["How to read this file", "Entries"],
|
|
239
|
+
),
|
|
240
|
+
"OPEN_QUESTIONS.md": (
|
|
241
|
+
"What is still unresolved, and what it would take to resolve it.",
|
|
242
|
+
"Questions raised by the work so far; what has been ruled out "
|
|
243
|
+
"already; the next step each one needs.",
|
|
244
|
+
"Questions the project has decided not to pursue -- say so in "
|
|
245
|
+
"RESEARCH_QUESTIONS.md's out-of-scope section instead, where it "
|
|
246
|
+
"reads as a decision rather than a gap.",
|
|
247
|
+
["Unresolved", "Ruled out", "Next steps"],
|
|
248
|
+
),
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
def render_stub(name: str, facts: Optional[dict] = None) -> str:
|
|
253
|
+
"""A skeleton for one document: title, purpose, the belongs/does-not
|
|
254
|
+
pair, and empty sections.
|
|
255
|
+
|
|
256
|
+
`facts` are the DETERMINISTIC ones the manifest established -- project
|
|
257
|
+
name, stack, test command. They are interpolated only where they are
|
|
258
|
+
genuinely known; nothing here guesses.
|
|
259
|
+
"""
|
|
260
|
+
if name not in _STUBS:
|
|
261
|
+
raise ValueError(f"No stub template for {name!r}.")
|
|
262
|
+
purpose, belongs, excludes, sections = _STUBS[name]
|
|
263
|
+
facts = facts or {}
|
|
264
|
+
|
|
265
|
+
title = name[:-3].replace("_", " ").title()
|
|
266
|
+
out = [f"# {title}", "", purpose, "",
|
|
267
|
+
f"**What belongs here:** {belongs}", "",
|
|
268
|
+
f"**What does NOT:** {excludes}", ""]
|
|
269
|
+
|
|
270
|
+
extra = _fact_lines(name, facts)
|
|
271
|
+
if extra:
|
|
272
|
+
out += ["## What `/init` established", ""] + extra + [""]
|
|
273
|
+
|
|
274
|
+
out.append("---")
|
|
275
|
+
out.append("")
|
|
276
|
+
for heading in sections:
|
|
277
|
+
out += [f"## {heading}", "", "_Not yet written._", ""]
|
|
278
|
+
# A plain sibling link since §44: the hub is a root file now, so the
|
|
279
|
+
# `.venastine/` hop this used to make is gone in both directions.
|
|
280
|
+
out += [f"Linked from [{HUB}]({HUB}).", ""]
|
|
281
|
+
return "\n".join(out)
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def _fact_lines(name: str, facts: dict) -> list:
|
|
285
|
+
"""The handful of places a detected fact belongs in a stub.
|
|
286
|
+
|
|
287
|
+
Kept narrow on purpose. Sprinkling the same three facts through every
|
|
288
|
+
document would make each one look more complete than it is, which is
|
|
289
|
+
the failure mode this whole file is arranged against.
|
|
290
|
+
"""
|
|
291
|
+
lines = []
|
|
292
|
+
if name == "ARCHITECTURE.md":
|
|
293
|
+
if facts.get("stack"):
|
|
294
|
+
lines.append(f"- Detected stack: {facts['stack']}")
|
|
295
|
+
if facts.get("entry_points"):
|
|
296
|
+
lines.append(
|
|
297
|
+
f"- Candidate entry points: {', '.join(facts['entry_points'])}")
|
|
298
|
+
elif name == "TEST_WRITING.md":
|
|
299
|
+
if facts.get("test_command"):
|
|
300
|
+
lines.append(f"- Detected test command: `{facts['test_command']}`")
|
|
301
|
+
if facts.get("test_dirs"):
|
|
302
|
+
lines.append(f"- Test locations: {', '.join(facts['test_dirs'])}")
|
|
303
|
+
return lines
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
def render_index(kind: str) -> str:
|
|
307
|
+
"""AGENTS.md's documentation index, generated from the set (I11).
|
|
308
|
+
|
|
309
|
+
A PURE FUNCTION OF THE KIND, and that is load-bearing rather than tidy.
|
|
310
|
+
The first version marked which documents already existed, so /init left
|
|
311
|
+
them alone (I12) but said so in the hub. Two things were wrong with it,
|
|
312
|
+
both found by running the command twice: the index changed on the second
|
|
313
|
+
run purely because the first had created the files, which rewrote
|
|
314
|
+
AGENTS.md for no reason and defeated the "nothing to do" path -- and the
|
|
315
|
+
mark itself was false, labelling documents /init had authored moments
|
|
316
|
+
earlier as pre-existing work it had preserved.
|
|
317
|
+
|
|
318
|
+
Which files were left untouched is a fact about one RUN, not about the
|
|
319
|
+
project, so it belongs in that run's report. It is there.
|
|
320
|
+
"""
|
|
321
|
+
lines = ["## Project documentation", "",
|
|
322
|
+
"This file is the hub. Each document below states what belongs "
|
|
323
|
+
"in it and what does not.", ""]
|
|
324
|
+
for name in document_set(kind):
|
|
325
|
+
# A SIBLING path, not `../` (§44). The hub sat in `.venastine/`
|
|
326
|
+
# and had to climb out; it is a root file now and every document
|
|
327
|
+
# it links is beside it.
|
|
328
|
+
lines.append(f"- [{name}]({name}) — {_STUBS[name][0]}")
|
|
329
|
+
lines.append("")
|
|
330
|
+
return "\n".join(lines)
|