@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,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)