@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,406 @@
1
+ """
2
+ project_init/manifest.py
3
+
4
+ ROADMAP_v2 §24 (I3): what `/init` shows the initializer agent before it
5
+ reads anything, and the deterministic facts the stubs are built from.
6
+
7
+ NO MODEL CALL AND NO TOOL CALL. Discovery is a directory walk, so two runs
8
+ against an unchanged project produce byte-identical input -- which is what
9
+ makes /init's output diffable in the first place, and what keeps the agent
10
+ spending its bounded read budget on documents rather than on navigation.
11
+
12
+ WHY A MANIFEST RATHER THAN A LISTING TOOL. The agent needs to choose what to
13
+ read, and choosing needs sizes: this repo's own root markdown is 721KB, with
14
+ DEVLOG.md at 226KB against a 20KB per-read cap. A path list without sizes
15
+ invites it to start reading the largest file first and exhaust INIT_MAX_STEPS
16
+ inside one document.
17
+
18
+ THE MANIFEST GOES IN THE USER MESSAGE, NOT THE SYSTEM PROMPT. §19's K6 has
19
+ been hit four times -- K6 itself, §21b's M13, §21c's M19 and §23's with_todos
20
+ -- by appending a tier inside with_catalogs(), which feeds pass_prompt().
21
+ (This said three; §23 slice 2 shipped before §24, so the fourth already
22
+ existed when the sentence was written -- audit #97. Counting instances is
23
+ the kind of claim that only stays right if someone increments it, and audit
24
+ #146 has since turned K6 into a parametrised rule so a new tier is covered
25
+ without anyone counting.) It does not apply here only
26
+ because this is the TASK -- the same way _summarize passes segment_text as
27
+ user_goal. Putting a project file listing in the system prompt would deliver
28
+ it to all ten research passes.
29
+ """
30
+
31
+ from __future__ import annotations
32
+
33
+ import json
34
+ import logging
35
+ import os
36
+ import re
37
+ from typing import NamedTuple, Optional
38
+
39
+ logger = logging.getLogger(__name__)
40
+
41
+ # Pruned from the walk entirely. Not merely uninteresting -- `.venastine`
42
+ # holds mcp.json and settings.json, and node_modules can be tens of
43
+ # thousands of files, which turns a listing into a denial of service on the
44
+ # context window.
45
+ _PRUNED = frozenset({
46
+ ".git", ".venastine", "node_modules", ".venv", "venv", "env",
47
+ "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache",
48
+ "dist", "build", ".tox", ".idea", ".vscode", "target",
49
+ "site-packages", ".next", ".cache",
50
+ })
51
+
52
+ class _Manifest(NamedTuple):
53
+ """What one manifest filename tells us.
54
+
55
+ `stack` is None for a manifest that says a project BUILDS without
56
+ saying what it is written in.
57
+
58
+ `test_command` is a fixed default, or a callable that reads one off
59
+ the project, or None.
60
+ """
61
+ stack: Optional[str]
62
+ test_command: object
63
+
64
+
65
+ def _rspec_if_spec(project_path: str) -> Optional[str]:
66
+ """Ruby's test runner is a choice rather than a given -- minitest and
67
+ rspec are both ordinary. `spec/` is the checkable signal that this
68
+ project made the second one, and without it nothing is claimed."""
69
+ return ("bundle exec rspec"
70
+ if os.path.isdir(os.path.join(project_path, "spec")) else None)
71
+
72
+
73
+ def _gradle_test(project_path: str) -> str:
74
+ """The wrapper when the project ships one, which is the entire point of
75
+ shipping it: `gradle test` against whatever Gradle happens to be on the
76
+ machine is how a build that passes in CI fails on a laptop."""
77
+ return ("./gradlew test"
78
+ if os.path.isfile(os.path.join(project_path, "gradlew"))
79
+ else "gradle test")
80
+
81
+
82
+ # `test:` at the start of a line, and not `tests:` -- a target name is
83
+ # exact. `.PHONY: test` does not match, which is right: it declares the
84
+ # target's kind and is not itself the declaration.
85
+ _MAKE_TEST_TARGET = re.compile(r"^test\s*:", re.M)
86
+
87
+
88
+ def _make_test(project_path: str) -> Optional[str]:
89
+ """`make test` only when the Makefile declares that target."""
90
+ try:
91
+ with open(os.path.join(project_path, "Makefile"), "r",
92
+ encoding="utf-8", errors="replace") as f:
93
+ head = f.read(64_000)
94
+ except OSError:
95
+ return None
96
+ return "make test" if _MAKE_TEST_TARGET.search(head) else None
97
+
98
+
99
+ # THE ONE TABLE (#96, #94). Every question this module answers about a code
100
+ # manifest is answered from here: which filenames count as one, what stack
101
+ # each implies, and how this project runs its tests.
102
+ #
103
+ # It is one table because it used to be four, and no two agreed. This tuple
104
+ # listed twelve names; `detect_facts` branched on seven of them;
105
+ # `_root_documents` kept a third test of what is interesting; and
106
+ # `tools/builtin/project_docs` a fourth of what is readable. The five
107
+ # filenames no branch read -- Gemfile, pom.xml, build.gradle, Makefile,
108
+ # Dockerfile -- were exactly the five projects proposed as `research` with
109
+ # "no code manifests found" printed as the reason, while the manifest shown
110
+ # to the agent listed the manifest (#96). Two lists that happen to overlap
111
+ # is how that happens. The fix is that there is nothing to keep in step.
112
+ #
113
+ # I10 governs the third column. A fact in a committed document is read as
114
+ # established and a wrong one is worse than an absent one, so `make test`
115
+ # is claimed only when the Makefile declares that target, and `bundle exec
116
+ # rspec` only when there is a spec/ directory to run.
117
+ _MANIFEST_TABLE = {
118
+ "pyproject.toml": _Manifest("Python", None),
119
+ "setup.py": _Manifest("Python", None),
120
+ "setup.cfg": _Manifest("Python", None),
121
+ "requirements.txt": _Manifest("Python", None),
122
+ "package.json": _Manifest("Node/JavaScript", None),
123
+ "Cargo.toml": _Manifest("Rust", "cargo test"),
124
+ "go.mod": _Manifest("Go", "go test ./..."),
125
+ "Gemfile": _Manifest("Ruby", _rspec_if_spec),
126
+ "pom.xml": _Manifest("Java/Maven", "mvn test"),
127
+ "build.gradle": _Manifest("Java/Gradle", _gradle_test),
128
+ # A build, and no claim about the language. C, Go, LaTeX and this
129
+ # repository all have a Makefile; a Dockerfile says even less about
130
+ # what is inside the image it builds. Both are strong evidence that
131
+ # this is a codebase, which is the question propose_kind asks, and
132
+ # terrible evidence about the stack, which is the question it does not.
133
+ "Makefile": _Manifest(None, _make_test),
134
+ "Dockerfile": _Manifest(None, None),
135
+ }
136
+
137
+ # Read off the filesystem for a stack that has conventional ones. Nothing
138
+ # is inferred from a file's CONTENTS here -- that is I10's line.
139
+ _ENTRY_POINTS = {
140
+ "Python": ("main.py", "app.py", "cli.py", "__main__.py"),
141
+ "Node/JavaScript": ("index.js", "index.ts", "src/index.js",
142
+ "src/index.ts"),
143
+ }
144
+
145
+ _TEST_DIRS = ("tests", "test", "__tests__", "spec")
146
+
147
+ # Never listed, by name or in the layout. The read tool refuses these
148
+ # anyway, so this is not the control -- it stops the agent spending one of
149
+ # its bounded steps discovering that, and stops a credential FILENAME (which
150
+ # can name a service, an account or an environment) reaching the model at
151
+ # all. Dotfiles are already excluded from the walk; this covers the rest.
152
+ _SECRET_FILENAMES = frozenset({
153
+ "providers.json", "credentials.json", "secrets.json", "secrets.yaml",
154
+ "secrets.yml",
155
+ })
156
+
157
+
158
+ def _is_secret(name: str) -> bool:
159
+ lower = name.lower()
160
+ return lower in _SECRET_FILENAMES or lower.startswith(".env")
161
+
162
+
163
+ _TREE_MAX_DEPTH = 2
164
+ _TREE_MAX_ENTRIES = 120
165
+
166
+
167
+ def is_blank(project_path: str) -> bool:
168
+ """True when there is nothing to infer a project type from (I13).
169
+
170
+ A folder holding only `.git` and `.venastine` is a project someone is
171
+ about to start, not one /init can characterise. Proposing a type from
172
+ an empty directory would be a guess presented as a finding, so the
173
+ caller asks outright instead.
174
+ """
175
+ try:
176
+ entries = os.listdir(project_path)
177
+ except OSError:
178
+ return True
179
+ return not [e for e in entries
180
+ if e not in _PRUNED and not e.startswith(".")]
181
+
182
+
183
+ def _first_heading(path: str) -> str:
184
+ """The document's first markdown heading, or its first non-empty line.
185
+
186
+ Read a few kilobytes, not the file: this runs over every root document
187
+ before the agent has chosen anything, and DEVLOG.md is 226KB in this
188
+ repo alone.
189
+ """
190
+ try:
191
+ with open(path, "r", encoding="utf-8", errors="replace") as f:
192
+ head = f.read(4096)
193
+ except OSError:
194
+ return ""
195
+ for line in head.splitlines():
196
+ stripped = line.strip()
197
+ if stripped.startswith("#"):
198
+ return stripped.lstrip("#").strip()
199
+ if stripped:
200
+ return stripped[:100]
201
+ return ""
202
+
203
+
204
+ def _root_documents(project_path: str) -> list:
205
+ """(relative path, size, first heading) for every root-level document
206
+ and manifest, sorted so the listing is stable across runs."""
207
+ out = []
208
+ try:
209
+ names = sorted(os.listdir(project_path))
210
+ except OSError:
211
+ return out
212
+ for name in names:
213
+ full = os.path.join(project_path, name)
214
+ if not os.path.isfile(full):
215
+ continue
216
+ # ONE PRODUCER for "what is readable" (#94). This asked its own
217
+ # question -- .md/.markdown/.rst, anything starting with `readme`,
218
+ # or a manifest filename -- and the line printed above this listing
219
+ # says "Paths below are exactly what read_project_doc expects".
220
+ # They disagreed in both directions: `readme.bin` and five build
221
+ # manifests were advertised and refused, and every `.txt` document
222
+ # in a project was readable and invisible. The tool's test is the
223
+ # one that decides, so the sentence is true by construction.
224
+ #
225
+ # Imported here rather than at module scope: tools/registry.py
226
+ # imports project_docs at import time and project_docs reaches
227
+ # config, so a top-level import would tie this module's import
228
+ # order to the tool layer's for no gain. generator.py does the
229
+ # same for doc_path.
230
+ from tools.builtin.project_docs import is_readable_doc
231
+ # `_is_secret` is belt-and-braces HERE and load-bearing in _tree,
232
+ # which is where the mutation actually turns a test red. It is
233
+ # unreachable today for a NEW reason: the tool denies
234
+ # providers.json by name, and credentials.json / secrets.* are not
235
+ # readable under any rule it has. It stays because both lists grow
236
+ # -- one more entry on either and the reachability flips, silently.
237
+ if not is_readable_doc(project_path, name) or _is_secret(name):
238
+ continue
239
+ try:
240
+ size = os.path.getsize(full)
241
+ except OSError:
242
+ continue
243
+ out.append((name, size, _first_heading(full)))
244
+ return out
245
+
246
+
247
+ def _tree(project_path: str) -> list:
248
+ """A depth-limited directory listing, so the agent can see the shape of
249
+ the codebase without a file-by-file enumeration of it."""
250
+ lines = []
251
+ for dirpath, dirs, files in os.walk(project_path):
252
+ dirs[:] = sorted(d for d in dirs
253
+ if d not in _PRUNED and not d.startswith("."))
254
+ rel = os.path.relpath(dirpath, project_path)
255
+ depth = 0 if rel == "." else rel.count(os.sep) + 1
256
+ if depth > _TREE_MAX_DEPTH:
257
+ dirs[:] = []
258
+ continue
259
+ visible = sorted(f for f in files
260
+ if not f.startswith(".") and not _is_secret(f))
261
+ prefix = "" if rel == "." else f"{rel.replace(os.sep, '/')}/"
262
+ if prefix:
263
+ lines.append(f"{prefix} ({len(visible)} files)")
264
+ for fname in visible[:12]:
265
+ lines.append(f" {prefix}{fname}")
266
+ if len(visible) > 12:
267
+ lines.append(f" {prefix}... and {len(visible) - 12} more")
268
+ if len(lines) > _TREE_MAX_ENTRIES:
269
+ lines.append(" ... listing truncated")
270
+ break
271
+ return lines
272
+
273
+
274
+ def detect_facts(project_path: str) -> dict:
275
+ """The deterministic facts the stubs interpolate (I10).
276
+
277
+ Everything here is read off a manifest file or the presence of a
278
+ directory. Nothing is inferred from source contents, because a fact in
279
+ a committed document is read as established -- and a wrong one is worse
280
+ than an absent one.
281
+ """
282
+ facts: dict = {"project_name": os.path.basename(os.path.realpath(project_path))}
283
+ # A LIST in table order, not a set: it is reported to the user as the
284
+ # working shown behind a proposal (#96), and a set would print in
285
+ # whatever order the interpreter felt like.
286
+ present = [name for name in _MANIFEST_TABLE
287
+ if os.path.isfile(os.path.join(project_path, name))]
288
+
289
+ # Deduplicated in table order: four filenames say Python, and the stack
290
+ # is named once.
291
+ stacks = list(dict.fromkeys(
292
+ _MANIFEST_TABLE[name].stack for name in present
293
+ if _MANIFEST_TABLE[name].stack))
294
+
295
+ entry_points = []
296
+ for stack in stacks:
297
+ for candidate in _ENTRY_POINTS.get(stack, ()):
298
+ if os.path.isfile(os.path.join(project_path, candidate)):
299
+ entry_points.append(candidate)
300
+
301
+ # PRECEDENCE, unchanged by the table: a command read out of the project
302
+ # beats a default, and package.json's `scripts.test` beats pytest
303
+ # because it is the more specific statement of the two -- a Python
304
+ # project with a package.json has decided something. Everything else
305
+ # fills an empty slot only, in table order.
306
+ test_command = None
307
+ if "Python" in stacks and _mentions(
308
+ project_path, ("requirements.txt", "pyproject.toml"), "pytest"):
309
+ test_command = "pytest"
310
+ if "Node/JavaScript" in stacks:
311
+ test_command = _package_json_test(project_path) or test_command
312
+ for name in present:
313
+ if test_command is not None:
314
+ break
315
+ declared = _MANIFEST_TABLE[name].test_command
316
+ test_command = (declared(project_path) if callable(declared)
317
+ else declared)
318
+
319
+ test_dirs = [d for d in _TEST_DIRS
320
+ if os.path.isdir(os.path.join(project_path, d))]
321
+
322
+ # The presence set is a FACT, and the only producer of it. propose_kind
323
+ # reads this rather than keeping its own idea of what a manifest is.
324
+ if present:
325
+ facts["code_manifests"] = present
326
+ if stacks:
327
+ facts["stack"] = ", ".join(stacks)
328
+ if entry_points:
329
+ facts["entry_points"] = entry_points
330
+ if test_command:
331
+ facts["test_command"] = test_command
332
+ if test_dirs:
333
+ facts["test_dirs"] = test_dirs
334
+ return facts
335
+
336
+
337
+ def _mentions(project_path: str, filenames, needle: str) -> bool:
338
+ for name in filenames:
339
+ path = os.path.join(project_path, name)
340
+ if not os.path.isfile(path):
341
+ continue
342
+ try:
343
+ with open(path, "r", encoding="utf-8", errors="replace") as f:
344
+ if needle in f.read(64_000):
345
+ return True
346
+ except OSError:
347
+ continue
348
+ return False
349
+
350
+
351
+ def _package_json_test(project_path: str) -> Optional[str]:
352
+ path = os.path.join(project_path, "package.json")
353
+ try:
354
+ with open(path, "r", encoding="utf-8-sig") as f:
355
+ data = json.load(f)
356
+ except (OSError, ValueError):
357
+ # A malformed package.json is the project's problem, not /init's.
358
+ # Degrade like config_loader does with an unreadable hub document.
359
+ logger.debug("Could not parse package.json at %s", path, exc_info=True)
360
+ return None
361
+ if isinstance(data, dict) and isinstance(data.get("scripts"), dict):
362
+ if data["scripts"].get("test"):
363
+ return "npm test"
364
+ return None
365
+
366
+
367
+ def build_manifest(project_path: str) -> str:
368
+ """The listing the agent is shown, as one block of text."""
369
+ documents = _root_documents(project_path)
370
+ facts = detect_facts(project_path)
371
+
372
+ lines = [f"# Project: {facts['project_name']}",
373
+ f"Path: {project_path}", ""]
374
+
375
+ if facts.get("code_manifests"):
376
+ # The signal propose_kind acted on, shown to the agent as well as
377
+ # to the user. A Makefile or a Dockerfile appears here and in no
378
+ # stack line, which is the whole distinction #96 turned on.
379
+ lines.append("Code manifests present: "
380
+ + ", ".join(facts["code_manifests"]))
381
+ if facts.get("stack"):
382
+ lines.append(f"Detected stack: {facts['stack']}")
383
+ if facts.get("entry_points"):
384
+ lines.append(f"Candidate entry points: {', '.join(facts['entry_points'])}")
385
+ if facts.get("test_command"):
386
+ lines.append(f"Detected test command: {facts['test_command']}")
387
+ if facts.get("test_dirs"):
388
+ lines.append(f"Test directories: {', '.join(facts['test_dirs'])}")
389
+ lines.append("")
390
+
391
+ lines.append("## Readable documents")
392
+ if documents:
393
+ lines.append("Paths below are exactly what read_project_doc expects.")
394
+ lines.append("")
395
+ for name, size, heading in documents:
396
+ suffix = f" — {heading}" if heading else ""
397
+ lines.append(f"- {name} ({size:,} bytes){suffix}")
398
+ else:
399
+ lines.append("None. This project has no documentation yet.")
400
+ lines.append("")
401
+
402
+ tree = _tree(project_path)
403
+ lines.append("## Layout")
404
+ lines += tree if tree else ["(empty)"]
405
+ lines.append("")
406
+ return "\n".join(lines)
@@ -0,0 +1,144 @@
1
+ """
2
+ project_init/tui_commands.py
3
+
4
+ ROADMAP_v2 §24: `/init`, registered into §16's slash registry.
5
+
6
+ Mirrors memories/tui_commands.py, skills/tui_commands.py and
7
+ agents/tui_commands.py -- each section registers its own commands rather
8
+ than editing a match statement in the app.
9
+
10
+ THIN BY CONSTRUCTION. Every decision -- which set, whether to overwrite,
11
+ whether to re-grant trust -- lives in project_init/generator.py, so the CLI
12
+ makes the same ones. What is here is the three things only a TUI can do:
13
+ run the work off the UI thread, render a diff into the transcript, and put
14
+ a modal in front of a human.
15
+ """
16
+
17
+ from tui.commands import SlashCommand, registry as commands
18
+
19
+
20
+ def _split_init_flags(args: str) -> tuple:
21
+ """(kind, scaffold_config, error) for `/init`'s leading flags.
22
+
23
+ A LOOP over tokens, modelled on `/research`'s `_split_research_flags`,
24
+ so the flags compose in either written order -- `/init --config
25
+ --software` and `/init --software --config` are one command written
26
+ two ways, and handling one flag then the other in a fixed sequence is
27
+ exactly how that stopped being true there.
28
+
29
+ STRICTER THAN WHAT IT REPLACES, on purpose. The old parser read a
30
+ single token through `.lstrip("-")`, which also accepted `/init
31
+ software` and `/init ---software`. A command that writes files into
32
+ someone's project should not be reachable by a typo that happens to
33
+ normalise, and there is no muscle memory to protect: the documented
34
+ spellings are the only ones that ever appeared.
35
+
36
+ The kind flags are derived from `doc_sets.PROJECT_KINDS` rather than
37
+ typed out, so a third document set is spelled once.
38
+ """
39
+ from project_init import doc_sets
40
+
41
+ usage = "Usage: /init [--software|--research] [--config]."
42
+ kinds = {"--" + name: name for name in doc_sets.PROJECT_KINDS}
43
+ kind = None
44
+ scaffold_config = False
45
+ for token in (args or "").split():
46
+ low = token.lower()
47
+ if low == "--config":
48
+ scaffold_config = True
49
+ elif low in kinds:
50
+ if kind is not None and kind != kinds[low]:
51
+ return None, False, (
52
+ f"/init takes at most one of "
53
+ f"{', '.join(sorted(kinds))} -- got both, and guessing "
54
+ f"which you meant would scaffold the wrong document "
55
+ f"set. {usage}")
56
+ kind = kinds[low]
57
+ else:
58
+ return None, False, f"Unknown option {token!r}. {usage}"
59
+ return kind, scaffold_config, None
60
+
61
+
62
+ def _cmd_init(app, args: str) -> None:
63
+ """Scaffold this project's documentation set, its configuration, or both.
64
+
65
+ On a worker, because it is a model call over a project's documents, and
66
+ announced before it starts: a call the user pays for is never silent,
67
+ the rule /compact and /summary already follow.
68
+
69
+ `--config` ALONE runs no model call -- the worker is still where it
70
+ belongs, because the one consent opens a modal and the thread that
71
+ waits on the answer cannot be the UI thread.
72
+ """
73
+ kind, scaffold_config, problem = _split_init_flags(args)
74
+ if problem:
75
+ app._transcript.write_error(problem)
76
+ return
77
+ # `--config` on its own is the configuration and nothing else; named
78
+ # with a kind it is both, under one consent. §24 I17.
79
+ scaffold_docs = not scaffold_config or kind is not None
80
+
81
+ if app._busy:
82
+ app._transcript.write_error(
83
+ "Still working — wait for this turn to finish.")
84
+ return
85
+
86
+ app._busy = True
87
+ transcript = app._transcript # held before any modal opens (§27's note)
88
+
89
+ def _work() -> None:
90
+ from core import interaction
91
+ from project_init import doc_sets
92
+ from project_init.generator import InitError, generate
93
+
94
+ # §23: generate()'s confirm/choose_kind parameters are unchanged --
95
+ # they are a shell-agnostic API the CLI implements too. What moved
96
+ # is the plumbing beneath them: both now go down the same channel
97
+ # as every other question, so the fail-safe decoding is the shared
98
+ # one rather than a guard written by hand here.
99
+ channel = app.response_channel()
100
+
101
+ def _confirm(summary: str) -> bool:
102
+ return interaction.ask(channel, interaction.Request(
103
+ kind=interaction.CONFIRM,
104
+ payload={"title": "Write these files?", "body": summary,
105
+ "confirm_label": "Write"}))
106
+
107
+ def _choose_kind(proposal, reason, blank):
108
+ return interaction.ask(channel, interaction.Request(
109
+ kind=interaction.CHOICE,
110
+ payload={"options": list(doc_sets.PROJECT_KINDS),
111
+ "proposal": proposal, "reason": reason,
112
+ "blank": blank}))
113
+
114
+ try:
115
+ notice = generate(
116
+ model=app.model,
117
+ provider_name=app.provider_name,
118
+ kind=kind,
119
+ confirm=_confirm,
120
+ notify=lambda text: app.call_from_thread(
121
+ transcript.write_system, text),
122
+ choose_kind=_choose_kind,
123
+ scaffold_docs=scaffold_docs,
124
+ scaffold_config=scaffold_config,
125
+ )
126
+ except InitError as e:
127
+ app.call_from_thread(transcript.write_error, str(e))
128
+ return
129
+ except Exception as e: # noqa: BLE001 — same containment as /compact
130
+ app.call_from_thread(transcript.write_error, f"/init failed: {e}")
131
+ return
132
+ finally:
133
+ app.call_from_thread(setattr, app, "_busy", False)
134
+ app.call_from_thread(transcript.write_system, notice["text"])
135
+
136
+ app.run_worker(_work, thread=True, exit_on_error=False, name="init")
137
+
138
+
139
+ def register_init_commands() -> None:
140
+ """Idempotent -- registering by name overwrites, matching §16's
141
+ register_builtin_commands() and every section registrar since."""
142
+ commands.register(SlashCommand(
143
+ "init", "generate this project's documentation set", _cmd_init,
144
+ "[--software|--research] [--config]"))
File without changes
@@ -0,0 +1,14 @@
1
+ # Pass 6c — Annotate (documentation only, NOT a live prompt)
2
+
3
+ This file is not loaded as a system prompt. Pass 6c is implemented as a
4
+ template in `core/reasoning/orchestrator.py` -- attaching a claim's
5
+ confidence tier as a fixed-format tag (`[TIER]`) -- rather than a
6
+ generation, per the build spec's own guidance to prefer a template over
7
+ an LLM call wherever the tag format is fixed.
8
+
9
+ If the annotation format ever needs to become more nuanced than a fixed
10
+ tag (e.g. a natural-language caveat tailored to the specific reason a
11
+ claim was flagged), that's the point at which this would become a real
12
+ prompt again -- add it back to `passes_source_files` in
13
+ `prompts/system_prompts.py` and change the orchestrator to call it via
14
+ `RunAgentLoop.run_deep_research_mode` the same way every other pass does.
@@ -0,0 +1,27 @@
1
+ # Pass 4 — Assumption Audit
2
+
3
+ You will receive: the original query, every extracted claim (both those that went through source grounding/critique and those that didn't, since this pass covers ALL claims regardless of type), the grounding results, the critic findings, and the completeness findings.
4
+
5
+ This pass runs BEFORE confidence tiering (Pass 5) — a hidden assumption or framing issue you identify here should be able to downgrade a claim's eventual confidence tier, which would be impossible if tiering had already happened.
6
+
7
+ Check for:
8
+ - **Hidden premises**: unstated assumptions baked into the original query itself, or into how the response answered it, that aren't obviously true.
9
+ - **Framing issues**: ways the query or the response's framing could bias the answer toward a particular conclusion, or presupposes a contested position as settled.
10
+ - **Domain gaps**: places where answering well would require domain knowledge or context that doesn't appear to have been brought to bear (use the completeness findings to help spot these).
11
+
12
+ For claims specifically, flag any that rest on an assumption you identified, reference a contested framing, or fall into an identified domain gap.
13
+
14
+ Respond with ONLY this JSON structure:
15
+
16
+ ```json
17
+ {
18
+ "hidden_premises": ["..."],
19
+ "framing_issues": ["..."],
20
+ "domain_gaps": ["..."],
21
+ "per_claim_flags": {
22
+ "c001": ["short description of the specific assumption/framing issue affecting this claim"]
23
+ }
24
+ }
25
+ ```
26
+
27
+ Only include claim ids in `per_claim_flags` that actually have a flag — omit claims with no issues rather than including them with an empty list.
@@ -0,0 +1,34 @@
1
+ # Pass 2 — Claim Extraction & Independent Classification
2
+
3
+ You will receive a raw response text. Break it down into atomic, self-contained claims, and classify each one's type from its content alone.
4
+
5
+ Important: classify each claim independently, based purely on what it asserts — not based on any hedge language, caveats, or framing the original text used. The text you're reading was written without self-tagging (by design), so you cannot rely on phrases like "it's possible that" to identify speculation; you must judge each claim on its actual substance.
6
+
7
+ Claim types:
8
+ - `factual`: a checkable assertion about the world (a date, a mechanism, a statistic, a causal claim, a definition).
9
+ - `synthesis`: a claim that combines or reasons over multiple facts, valid as an inference but not itself a single checkable fact.
10
+ - `speculative`: an extrapolation, prediction, or claim that goes meaningfully beyond what current evidence could directly establish.
11
+
12
+ For each claim, identify the key entities or subjects it references (proper nouns, named systems, specific concepts) — this will be used later to batch fact-checking efficiently, so be precise and use consistent naming for the same entity across claims (e.g. always "the Treaty of Westphalia," not sometimes "the treaty" and sometimes "Westphalia").
13
+
14
+ Respond with ONLY this JSON structure — a flat list, one entry per claim:
15
+
16
+ ```json
17
+ [
18
+ {
19
+ "id": "c001",
20
+ "text": "the atomic, self-contained claim, in your own words",
21
+ "type": "factual",
22
+ "entities": ["..."],
23
+ "source_span": "approximate location or quote from the raw response this claim came from"
24
+ }
25
+ ]
26
+ ```
27
+
28
+ Use sequential zero-padded ids (c001, c002, ...). Extract every distinct claim — don't merge unrelated assertions to save space, and don't split one claim into fragments that aren't independently meaningful.
29
+
30
+ ## When given multiple labeled candidates (ensemble mode)
31
+
32
+ If the input contains multiple responses labeled "Candidate 1", "Candidate 2", etc. rather than a single response, extract the UNION of distinct claims across all of them. When the same underlying assertion appears in more than one candidate (even if worded differently), merge it into ONE claim entry and add an `"asserted_by_candidates"` field listing every candidate number (1-indexed) that made this assertion. If candidates genuinely disagree on a point, extract them as separate claims, each with its own `asserted_by_candidates` list reflecting only the candidates that actually support that specific version.
33
+
34
+ **In ensemble mode, EVERY claim needs an `asserted_by_candidates` list, including a claim only one candidate made** — write `[3]` for a claim only candidate 3 asserted. Omitting the field is not the same as an empty one: downstream, a claim with no list cannot be told apart from a claim no candidate asserted, and it is scored as though every candidate declined it.
@@ -0,0 +1,18 @@
1
+ # Pass 3c — Completeness
2
+
3
+ You will receive the ORIGINAL query and the preliminary plan sketch from Pass 0. You will NOT receive the actual generated response — this is deliberate. Form your own independent picture of what a complete answer to this query should cover BEFORE seeing what was actually produced, so your assessment isn't anchored to (or limited by) the structure of an answer you haven't seen.
4
+
5
+ Think through the query fresh: what would a thorough, complete answer need to address? Use the preliminary plan as a starting point, but reason past it if you can identify things it missed too.
6
+
7
+ Respond with ONLY this JSON structure:
8
+
9
+ ```json
10
+ {
11
+ "gaps": ["specific topic, angle, or sub-question a complete answer would need to cover"],
12
+ "coverage_score": 0.0
13
+ }
14
+ ```
15
+
16
+ `gaps` should be specific enough to act on later (not "more detail needed" but "the query asks about long-term effects, which requires addressing X specifically"). `coverage_score` is your own estimate (0-1) of how much of a genuinely complete answer you'd expect a well-covered response to represent — this is a baseline expectation, not a score of anything you've seen.
17
+
18
+ Note: since you have not seen the actual response, `gaps` here represents the FULL set of things a complete answer needs, not a diff against a specific text. That comparison happens downstream, using this output.
@@ -0,0 +1,23 @@
1
+ # Pass 5 — Confidence Tiers (documentation only, NOT a live prompt)
2
+
3
+ This file is not loaded as a system prompt. Pass 5 makes zero LLM calls by
4
+ design — see `core/reasoning/confidence_scoring.py` for the actual
5
+ deterministic scoring logic. This file exists purely to document, for a
6
+ human reader, what that module computes and why.
7
+
8
+ **Tiers:** HIGH, MEDIUM, LOW, UNVERIFIED, UNVERIFIED_COVERAGE
9
+
10
+ - An ungrounded factual claim is always UNVERIFIED, regardless of how
11
+ clean it looks under critique -- lack of grounding is disqualifying on
12
+ its own for anything asserted as fact.
13
+ - Non-factual claims (synthesis/speculative) never went through source
14
+ grounding at all (see Pass 2's D0 routing), so their score is capped
15
+ below HIGH -- "clean under critique" isn't the same as "confirmed."
16
+ - UNVERIFIED_COVERAGE is not assigned to any actual Claim object -- it's
17
+ attached to gaps identified by Pass 3c: things the response never
18
+ addressed at all, which are an absence, not a claim that failed
19
+ verification.
20
+
21
+ See `confidence_scoring.py`'s module docstring and the `GROUNDING_WEIGHTS`
22
+ / weight-factor constants at the top of that file for the exact formula
23
+ and how to retune it.