geneseed 4.31.0 → 5.0.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 (272) hide show
  1. package/CHANGELOG.md +107 -0
  2. package/DESIGN.md +2 -2
  3. package/README.md +6 -5
  4. package/SHIPPED.md +4 -3
  5. package/adapters/bob/README.md +6 -5
  6. package/adapters/claude-code/README.md +4 -3
  7. package/adapters/claude-code/skills/geneseed/SKILL.md +1 -1
  8. package/adapters/openclaude/README.md +4 -3
  9. package/adapters/opencode/GLOBAL-HARNESS-SPEC.md +3 -1
  10. package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -1
  11. package/adapters/opencode/README.md +18 -18
  12. package/adapters/opencode/plugins/geneseed-activity.js +57 -1
  13. package/adapters/opencode/plugins/geneseed-context.js +220 -18
  14. package/adapters/opencode/plugins/geneseed-guard.js +578 -74
  15. package/adapters/opencode/plugins/geneseed-learn.js +97 -23
  16. package/bin/geneseed-cli.mjs +17 -25
  17. package/bin/geneseed-hook.mjs +23 -8
  18. package/docs/DESIGN.md +175 -0
  19. package/docs/PRD.md +111 -0
  20. package/docs/README.md +3 -2
  21. package/docs/architecture.md +145 -0
  22. package/docs/concepts/agents.md +1 -1
  23. package/docs/concepts/collaboration.md +1 -1
  24. package/docs/concepts/enforcement-table.md +1 -1
  25. package/docs/concepts/exclusions.md +6 -6
  26. package/docs/concepts/footprint.md +1 -1
  27. package/docs/concepts/foreman-mode.md +2 -2
  28. package/docs/concepts/hook-gates.md +1 -1
  29. package/docs/concepts/hooks.md +27 -11
  30. package/docs/concepts/host-matrix.md +3 -3
  31. package/docs/concepts/hosts.md +1 -1
  32. package/docs/concepts/kits.md +3 -1
  33. package/docs/concepts/loop-bricks.md +1 -1
  34. package/docs/concepts/loop-notes.md +4 -2
  35. package/docs/concepts/loop-templates.md +7 -4
  36. package/docs/concepts/loops.md +3 -0
  37. package/docs/concepts/ownership.md +2 -2
  38. package/docs/concepts/rules.md +15 -2
  39. package/docs/concepts/shared-tier.md +73 -0
  40. package/docs/concepts/skills.md +2 -2
  41. package/docs/concepts/themes.md +1 -1
  42. package/docs/extending.md +13 -12
  43. package/docs/guides/install-claude-code.md +1 -1
  44. package/docs/guides/install-opencode.md +1 -1
  45. package/docs/guides/migrate.md +4 -2
  46. package/docs/guides/project-context.md +2 -2
  47. package/docs/guides/run-a-loop.md +1 -1
  48. package/docs/guides/set-up-ownership.md +1 -1
  49. package/docs/guides/setup-footprint.md +1 -1
  50. package/docs/guides/uninstall.md +2 -1
  51. package/docs/guides/upgrade-to-5.md +116 -0
  52. package/docs/guides/upgrade.md +21 -9
  53. package/docs/guides/wiki.md +3 -3
  54. package/docs/reference/env-context.md +5 -3
  55. package/docs/reference/environment.md +1 -1
  56. package/docs/reference/glossary.md +2 -0
  57. package/docs/reference/loop-actions.md +1 -1
  58. package/docs/reference/opencode-plugins.md +3 -3
  59. package/docs/reference/plugin-activity.md +1 -1
  60. package/docs/reference/plugin-context.md +5 -0
  61. package/docs/reference/plugin-guard.md +14 -6
  62. package/docs/reference/plugin-learn.md +13 -6
  63. package/docs/reference/troubleshoot-hooks.md +3 -3
  64. package/docs/reference/troubleshoot-update.md +14 -0
  65. package/docs/token-footprint.md +4 -3
  66. package/docs/understand/a-day.md +2 -2
  67. package/docs/understand/design-choices-install.md +2 -1
  68. package/docs/understand/enforced-vs-asked.md +4 -3
  69. package/docs/understand/machine-bob.md +3 -1
  70. package/docs/understand/machine-claude.md +7 -5
  71. package/docs/understand/machine-opencode.md +7 -5
  72. package/docs/understand/on-your-machine.md +4 -0
  73. package/docs/understand/take-it-out.md +1 -1
  74. package/docs/web-ui.md +141 -73
  75. package/harness.config.json +1 -1
  76. package/js/README.md +10 -6
  77. package/js/build/args.mjs +10 -8
  78. package/js/build/bundle.mjs +11 -13
  79. package/js/build/driver.mjs +66 -65
  80. package/js/build/emit-claude.mjs +22 -16
  81. package/js/build/emit-common.mjs +4 -5
  82. package/js/build/emit-opencode.mjs +22 -22
  83. package/js/build/fold.mjs +515 -0
  84. package/js/build/generate.mjs +41 -52
  85. package/js/build/render.mjs +115 -29
  86. package/js/build/source.mjs +4 -1
  87. package/js/build/stubs.mjs +70 -9
  88. package/js/build/version.mjs +10 -10
  89. package/js/cli-table.json +23 -83
  90. package/js/hosts/activity.mjs +2 -2
  91. package/js/hosts/geneseed-dir.mjs +1 -1
  92. package/js/hosts/hooks-context.mjs +410 -99
  93. package/js/hosts/hooks-done.mjs +97 -31
  94. package/js/hosts/hooks-learn.mjs +38 -7
  95. package/js/hosts/hooks-prims.mjs +69 -2
  96. package/js/hosts/hooks.mjs +300 -64
  97. package/js/hosts/hosts.mjs +150 -51
  98. package/js/hosts/installs.mjs +55 -167
  99. package/js/hosts/link.mjs +3 -5
  100. package/js/hosts/mcp.mjs +1 -1
  101. package/js/hosts/memory-files.mjs +219 -17
  102. package/js/hosts/ownership-gate.mjs +1 -1
  103. package/js/hosts/settings.mjs +18 -13
  104. package/js/hosts/shim.mjs +4 -33
  105. package/js/hosts/store-watch.mjs +189 -0
  106. package/js/inspect/checks-authoring.mjs +3 -3
  107. package/js/inspect/checks-build.mjs +45 -18
  108. package/js/inspect/checks-counts.mjs +4 -4
  109. package/js/inspect/checks-repo.mjs +13 -14
  110. package/js/inspect/cost.mjs +24 -2
  111. package/js/inspect/diff.mjs +123 -123
  112. package/js/inspect/doctor.mjs +22 -27
  113. package/js/inspect/excludes.mjs +181 -62
  114. package/js/inspect/inventory.mjs +22 -27
  115. package/js/inspect/registry.mjs +106 -30
  116. package/js/inspect/scan.mjs +5 -5
  117. package/js/inspect/status.mjs +141 -119
  118. package/js/inspect/validate.mjs +22 -24
  119. package/js/lib/fs.mjs +47 -50
  120. package/js/lib/json.mjs +10 -17
  121. package/js/lib/machine-dir.mjs +73 -0
  122. package/js/lib/paths.mjs +22 -33
  123. package/js/lib/proc.mjs +1 -1
  124. package/js/lib/prompt.mjs +19 -27
  125. package/js/lib/text.mjs +8 -12
  126. package/js/lib/udiff.mjs +11 -15
  127. package/js/loop/catalog.mjs +2 -3
  128. package/js/loop/state.mjs +15 -5
  129. package/js/maintain/memory.mjs +17 -17
  130. package/js/maintain/migrate.mjs +79 -89
  131. package/js/maintain/setup.mjs +43 -32
  132. package/js/maintain/uninstall.mjs +43 -61
  133. package/js/maintain/update.mjs +200 -93
  134. package/js/ui/anim.mjs +21 -35
  135. package/js/ui/cli.mjs +36 -58
  136. package/js/ui/menu.mjs +22 -45
  137. package/js/ui/tui.mjs +27 -67
  138. package/js/web/actions.mjs +38 -38
  139. package/js/web/api.mjs +132 -76
  140. package/js/web/catalog.mjs +175 -46
  141. package/js/web/docs.mjs +33 -12
  142. package/js/web/doctor-worker.mjs +14 -0
  143. package/js/web/handler.mjs +14 -5
  144. package/js/web/routes.mjs +17 -19
  145. package/js/web/state.mjs +78 -19
  146. package/js/web/update-check.mjs +25 -10
  147. package/js/web/user-files.mjs +50 -105
  148. package/package.json +7 -4
  149. package/registry.json +48 -55
  150. package/src/AGENT.md.tmpl +13 -14
  151. package/src/agents/_self-improvement.md +1 -1
  152. package/src/agents/_template.md +4 -1
  153. package/src/agents/advocate.md +1 -1
  154. package/src/agents/architect.md +1 -1
  155. package/src/agents/developer.md +6 -3
  156. package/src/agents/devops-engineer.md +1 -1
  157. package/src/agents/docker-expert.md +1 -1
  158. package/src/agents/docs.md +1 -1
  159. package/src/agents/empiricist.md +1 -1
  160. package/src/agents/explorer.md +1 -1
  161. package/src/agents/framer.md +1 -1
  162. package/src/agents/historian.md +1 -1
  163. package/src/agents/kubernetes-specialist.md +1 -1
  164. package/src/agents/memory-curator.md +2 -2
  165. package/src/agents/operator.md +1 -1
  166. package/src/agents/performance.md +1 -1
  167. package/src/agents/pragmatist.md +1 -1
  168. package/src/agents/react-engineer.md +1 -1
  169. package/src/agents/react-reviewer.md +1 -1
  170. package/src/agents/researcher.md +1 -1
  171. package/src/agents/reviewer.md +1 -1
  172. package/src/agents/security.md +1 -1
  173. package/src/agents/skeptic.md +1 -1
  174. package/src/agents/spring-boot-engineer.md +1 -1
  175. package/src/agents/spring-reviewer.md +1 -1
  176. package/src/agents/spring-security.md +1 -1
  177. package/src/agents/steward.md +1 -1
  178. package/src/agents/tester.md +5 -2
  179. package/src/agents/user-advocate.md +1 -1
  180. package/src/agents/visionary.md +1 -1
  181. package/src/bricks/apply.md +3 -0
  182. package/src/bricks/test.md +6 -4
  183. package/src/loops/bugfix.json +11 -5
  184. package/src/loops/feature.json +7 -4
  185. package/src/memory/README.md +1 -1
  186. package/src/skills/_self-improvement.md +2 -2
  187. package/src/skills/daydream/SKILL.md +2 -2
  188. package/src/skills/daydream/instructions.md +1 -1
  189. package/src/skills/geneseed.md +1 -1
  190. package/src/skills/learn-mode.md +1 -2
  191. package/src/skills/loop.md +1 -0
  192. package/src/skills/profile.md +2 -2
  193. package/src/skills/rule/approve.md +69 -0
  194. package/src/skills/rule/consolidate.md +3 -3
  195. package/src/skills/rule.md +13 -5
  196. package/src/skills/ship.md +9 -1
  197. package/src/skills/skill-forge.md +1 -1
  198. package/src/skills/teach.md +29 -12
  199. package/src/skills/wiki.md +1 -1
  200. package/themes/_TEMPLATE.json +1 -2
  201. package/themes/biker.json +1 -2
  202. package/themes/commentator.json +1 -2
  203. package/themes/cyberpunk.json +1 -2
  204. package/themes/gamer.json +1 -2
  205. package/themes/imperial.json +1 -2
  206. package/themes/joker.json +1 -2
  207. package/themes/marvin.json +1 -2
  208. package/themes/mean.json +1 -2
  209. package/themes/military.json +1 -2
  210. package/themes/neutral.json +1 -2
  211. package/themes/pirate.json +1 -2
  212. package/themes/sports.json +1 -2
  213. package/themes/verstappen.json +1 -2
  214. package/themes/wizard.json +1 -2
  215. package/web/dist/assets/Activity-D8G4eClY.js +1 -0
  216. package/web/dist/assets/ActivityDetail-BtOBYk3M.js +1 -0
  217. package/web/dist/assets/AgentGlyph-k6o3gCM1.js +1 -0
  218. package/web/dist/assets/Bonsai-B_y20b3i.js +1 -0
  219. package/web/dist/assets/{CopyButton-IXnXzH4Y.js → CopyButton-CHQte7Ap.js} +1 -1
  220. package/web/dist/assets/Dashboard-B8uXeJZ_.js +2 -0
  221. package/web/dist/assets/{DataTable-BWbUx4bY.js → DataTable-b9zTShqJ.js} +1 -1
  222. package/web/dist/assets/Docs-Dgv_MWfT.js +5 -0
  223. package/web/dist/assets/{EmptyState-1sPNleqv.js → EmptyState-CY5Pm2xy.js} +1 -1
  224. package/web/dist/assets/FilterInput-qGKNSlxv.js +1 -0
  225. package/web/dist/assets/GreenhouseView-CSzTMSl_.js +1 -0
  226. package/web/dist/assets/Installs-BDk9lqBI.js +3 -0
  227. package/web/dist/assets/JournalView-CvRk1-m5.js +1 -0
  228. package/web/dist/assets/Kits-CoITzxWM.js +1 -0
  229. package/web/dist/assets/Laws-Ctf5r9rE.js +3 -0
  230. package/web/dist/assets/Library-DNwHYVXt.js +3 -0
  231. package/web/dist/assets/{Loops-C5u7fQOR.js → Loops-S85PMQ8m.js} +2 -2
  232. package/web/dist/assets/Markdown-0ORz7tAc.js +69 -0
  233. package/web/dist/assets/OperatorHudView-DuGz_sTk.js +1 -0
  234. package/web/dist/assets/Personal-afJNwvRS.js +2 -0
  235. package/web/dist/assets/RailCats-AW92uhsX.js +1 -0
  236. package/web/dist/assets/Settings-CGDFz-6j.js +1 -0
  237. package/web/dist/assets/Tabs-1qLrnqmn.js +1 -0
  238. package/web/dist/assets/api-C46vAuqp.js +1 -0
  239. package/web/dist/assets/controls-D4wmg_pl.js +1 -0
  240. package/web/dist/assets/index-COTd4TRZ.js +3 -0
  241. package/web/dist/assets/index-CtorA7uK.css +1 -0
  242. package/web/dist/assets/motion-RlUl1osO.js +1 -0
  243. package/web/dist/assets/react-C1iE8mnY.js +9 -0
  244. package/web/dist/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  245. package/web/dist/assets/{sections-ChwaobfW.js → sections-CtFz7HFH.js} +1 -1
  246. package/web/dist/assets/{usePoll-bDFN-Hr6.js → usePoll-o8ul-Sog.js} +1 -1
  247. package/web/dist/index.html +7 -7
  248. package/src/skills/quiz.md +0 -44
  249. package/web/dist/assets/Activity-B7cFtS00.js +0 -1
  250. package/web/dist/assets/ActivityDetail-C-GbMmuW.js +0 -1
  251. package/web/dist/assets/Bonsai-_YyexVC5.js +0 -1
  252. package/web/dist/assets/Dashboard-sCfEjowQ.js +0 -2
  253. package/web/dist/assets/Docs-w3Y7M5Ts.js +0 -5
  254. package/web/dist/assets/FilterInput-CZREvrjX.js +0 -1
  255. package/web/dist/assets/GreenhouseView-BWWbMKmg.js +0 -1
  256. package/web/dist/assets/Installs-CnkdJ-VA.js +0 -3
  257. package/web/dist/assets/JournalView-C7bPD3fZ.js +0 -1
  258. package/web/dist/assets/KitApply-CQQbnThf.js +0 -1
  259. package/web/dist/assets/Kits-aj07N7mT.js +0 -1
  260. package/web/dist/assets/Laws-DZ38nl_H.js +0 -3
  261. package/web/dist/assets/Library-QCGXPV5h.js +0 -2
  262. package/web/dist/assets/Markdown-DpmmtW2Y.js +0 -65
  263. package/web/dist/assets/OperatorHudView-Blu1lqiZ.js +0 -1
  264. package/web/dist/assets/Personal-ox_MktWO.js +0 -2
  265. package/web/dist/assets/RailCats-BuJD4Jou.js +0 -1
  266. package/web/dist/assets/Tabs-CIPyMAX-.js +0 -1
  267. package/web/dist/assets/api-BxjLd7Qd.js +0 -1
  268. package/web/dist/assets/index-0GCxkY7m.css +0 -1
  269. package/web/dist/assets/index-CzDi9JpF.js +0 -3
  270. package/web/dist/assets/motion-CXaUMNkg.js +0 -1
  271. package/web/dist/assets/react-DlYQp10C.js +0 -9
  272. package/web/dist/assets/rolldown-runtime-hePW80VL.js +0 -1
package/docs/PRD.md ADDED
@@ -0,0 +1,111 @@
1
+ ---
2
+ type: prd
3
+ mirrors-commit: 9c4af014
4
+ generated: 2026-11-06
5
+ ---
6
+
7
+ # Geneseed product requirements
8
+
9
+ Reconstructed from the code and [`DESIGN.md`](../DESIGN.md). The items marked `⚠ to confirm` are
10
+ inferred and wait for the maintainer's word.
11
+
12
+ <!-- geneseed:doc:start -->
13
+ ## Problem
14
+
15
+ An AI coding agent starts each session with no standing rules, no memory of the last session, and
16
+ nothing that stops a risky action. Writing that setup by hand means one set of files per tool, in
17
+ each tool's own format, and it drifts. Geneseed authors the setup once and generates it for each
18
+ host, with hooks or plugins that enforce what the host allows.
19
+ <!-- geneseed:doc:end -->
20
+
21
+ <!-- geneseed:doc:start -->
22
+ ## Users
23
+
24
+ - **Developer on one machine:** installs globally, and wants the agent's rules and memory in every repo.
25
+ - **Team maintainer:** installs per repo, and wants rules and gates committed beside the code.
26
+ - **Locked-down corporate user:** has no npm access, and installs and updates from a git clone.
27
+ - **Harness contributor:** edits `src/`, and needs to know what an addition costs ([`extending.md`](extending.md)).
28
+ <!-- geneseed:doc:end -->
29
+
30
+ <!-- geneseed:doc:start -->
31
+ ## Goals
32
+
33
+ 1. One neutral source, generated into each supported host (`src/`, `js/build/`).
34
+ 2. Enforce at the tool boundary what a host can enforce, and say plainly what is only asked ([Enforced vs. asked](understand/enforced-vs-asked.md)).
35
+ 3. Knowledge that outlives a session and is the same for every host on the machine ([The shared tier](concepts/shared-tier.md)).
36
+ 4. Nothing lost: uninstall, upgrades and the fold keep user data.
37
+ 5. Install and update without a build step or runtime dependencies ([ADR 0001](adr/0001-zero-runtime-dependencies.md)).
38
+ <!-- geneseed:doc:end -->
39
+
40
+ <!-- geneseed:doc:start -->
41
+ ## Non-goals
42
+
43
+ - Geneseed does not manage MCP servers. It lists them read-only (`geneseed mcp`).
44
+ - It does not sync between machines. The shared tier covers one machine; use git or a vault to carry it further.
45
+ - It does not call a model API or hold an API key. `learn` uses the host's model or a CLI the user names.
46
+ - It does not bypass a host's permission mode: no emit grants a directory permission.
47
+ - `DESIGN.md` has the full list under *Explicitly out of scope*.
48
+ <!-- geneseed:doc:end -->
49
+
50
+ <!-- geneseed:doc:start -->
51
+ ## User journeys
52
+
53
+ 1. As a developer, I want one command to install the harness, so that every repo inherits it.
54
+ 2. As a developer with two tools, I want a fact taught in one to reach the other, so that I teach it once.
55
+ 3. As a developer, I want to be asked before a force-push or a credential write, so that a mistake does not cost data.
56
+ 4. As a 4.x user, I want the upgrade to move my stores without loss, so that I do not migrate by hand.
57
+ 5. As a maintainer, I want to see every install's state in one place, so that I can keep them current.
58
+
59
+ ```mermaid
60
+ sequenceDiagram
61
+ actor D as Developer
62
+ participant G as geneseed
63
+ participant T as shared tier
64
+ participant R as rule skill
65
+ D->>G: upgrade or rebuild-all
66
+ G->>T: fold facts, notes, exclude paths
67
+ G->>T: draft rules that need a decision
68
+ G-->>D: [shared] claude: 12 facts folded, 2 rules to approve
69
+ D->>R: review pending rules
70
+ R->>T: approve to the shared file, or keep on the host
71
+ ```
72
+ <!-- geneseed:doc:end -->
73
+
74
+ <!-- geneseed:doc:start -->
75
+ ## Functional requirements
76
+
77
+ | ID | Requirement | Acceptance criteria | Status | Code |
78
+ |---|---|---|---|---|
79
+ | FR-001 | The generator renders one source into each host's install. | Each emit target renders without error; a second emit changes nothing | ✅ | `js/build/`, `tests/golden.mjs` |
80
+ | FR-002 | A theme changes voice only. | Same rules and structure in every theme; theme keys in parity | ✅ | `themes/`, `js/build/render.mjs` |
81
+ | FR-003 | A user chooses doctrine packs, single rules, skills and kits per install. | The choice survives a rebuild | ✅ | `js/build/args.mjs`, `js/build/generate.mjs` |
82
+ | FR-004 | Hook hosts gate git, writes and session context. | A blocked or asked call reaches the host's verdict channel | ✅ | `bin/geneseed-hook.mjs`, `js/hosts/hooks*.mjs` |
83
+ | FR-005 | OpenCode gets the same behaviour through plugins, on both plugin APIs. | The host loads every plugin | ✅ | `adapters/opencode/plugins/`, `tests/host_canary.mjs` |
84
+ | FR-006 | Global installs share memory, rules, profile, wiki manifest, exclude paths and notes. | Every global install reads the tier; project over host over shared | ✅ | `js/lib/machine-dir.mjs`, `js/hosts/hooks-context.mjs` |
85
+ | FR-007 | A global emit folds existing stores into the tier. | Copies read back before the old store moves; a second run writes nothing | ✅ | `js/build/fold.mjs` |
86
+ | FR-008 | A rule, profile or wiki that needs a decision waits in a draft. | A drafted rule stays in force on its host; only the `rule` skill decides | ✅ | `js/build/fold.mjs`, `src/skills/rule/approve.md` |
87
+ | FR-009 | A project install may opt in to read the tier. | Off by default; read-only and labelled; cost stated | ✅ | `js/inspect/cost.mjs`, `js/hosts/hooks-context.mjs` |
88
+ | FR-010 | The agent's memory is one fact per file, with a two-level index. | `geneseed memory list`, `rm` archive; `learn` updates and does not duplicate | ✅ | `js/hosts/memory-files.mjs`, `js/maintain/memory.mjs` |
89
+ | FR-011 | A folder can silence every global install. | `geneseed exclude add`; effect on the next tool call | ✅ | `js/inspect/excludes.mjs` |
90
+ | FR-012 | Uninstall removes only what the manifest owns. | User files stay; the tier is never touched | ✅ | `js/maintain/uninstall.mjs` |
91
+ | FR-013 | A clone updates itself with a checked pull; npm installs rebuild after an install. | A failed doctor rolls back; a doctor that cannot finish keeps the pull and rebuilds nothing | ✅ | `js/maintain/update.mjs` |
92
+ | FR-014 | `doctor`, `status`, `diff` and `validate` report state without changing it. | No install write | ✅ | `js/inspect/` |
93
+ | FR-015 | The web console shows the fleet and the shared stores once. | No install switch; default install selectable; rule costs shown with no limit; pending read-only; Update hidden when the pull cannot run | ✅ | `js/web/`, `web/src/` |
94
+ | FR-016 | Loops work a requirement as validated, committed iterations. | `geneseed loop` steps a state machine over `LOOP.md` | ✅ | `js/loop/` |
95
+ | FR-017 | Claude Code auto memory can be imported on request. | An explicit import verb | ✗ | Deferred past 5.0.0 |
96
+ <!-- geneseed:doc:end -->
97
+
98
+ <!-- geneseed:doc:start -->
99
+ ## Non-functional requirements
100
+
101
+ | ID | Requirement | Threshold | Acceptance criteria | Status | Code |
102
+ |---|---|---|---|---|---|
103
+ | NFR-001 | No runtime dependencies. | 0 installed; vendored only | `tests/unit/dependency_policy.test.mjs` | ✅ | `js/vendor/` |
104
+ | NFR-002 | The hook is cheap: it loads on every tool call. | ~14 ms to load | Stated in `AGENTS.md`; no automated budget found, `⚠ to confirm` | ◐ | `bin/geneseed-hook.mjs` |
105
+ | NFR-003 | Context hook output stays under the host's cap. | 9 000 characters | `OUTPUT_BUDGET` | ✅ | `js/hosts/hooks-context.mjs` |
106
+ | NFR-004 | The rules file stays within its size ceiling. | 41 612 lean, 66 432 full | `CARRIER_CEILING` | ✅ | `js/inspect/cost.mjs` |
107
+ | NFR-005 | The generator and hook path cannot spawn beyond what is declared. | No `child_process` on the generator; one spawn site on the hook path | Closure walks | ✅ | `tests/unit/hook_cli.test.mjs` |
108
+ | NFR-006 | The upgrade doctor gate is bounded. | 300 s | A timeout reports a gate that did not finish | ✅ | `js/maintain/update.mjs` |
109
+ | NFR-007 | The console serves only this machine. | Local port 4747 by default, with request guards | [Web console security](web-ui.md#security-model) | ✅ | `js/web/server.mjs` |
110
+ | NFR-008 | Runs on Windows, macOS and Linux with no build step. | CI: Ubuntu and Windows. macOS: `⚠ to confirm`, no CI row | `web/dist/` tracked; `install`, `install.cmd`, `install.command` | ◐ | `.github/workflows/ci.yml` |
111
+ <!-- geneseed:doc:end -->
package/docs/README.md CHANGED
@@ -30,6 +30,7 @@
30
30
  | Set up | [MCP servers](guides/mcp.md) · [MarkItDown](guides/mcp-markitdown.md) · [GitLab](guides/mcp-gitlab.md) · [Filesystem](guides/mcp-filesystem.md) · [Reading non-markdown docs](guides/read-non-markdown.md) | Where the config lives, the three presets, and reading PDF and Office files |
31
31
  | Loops | [Run a loop](guides/run-a-loop.md) · [Which loop template](guides/loop-which-template.md) · [While a loop runs](guides/loop-running.md) · [Finish a loop](guides/loop-finish.md) | Working a requirement as small, validated, committed iterations |
32
32
  | Keep it running | [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
33
+ | Keep it running | [Upgrade to 5.0](guides/upgrade-to-5.md) | A 4.x machine reaching 5.0: what moves, what to check, how to go back |
33
34
  | Keep it running | [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
34
35
  | Keep it running | [Start the web console at login](guides/autostart.md) | Keeping the console running |
35
36
  | Keep it running | [Uninstall](guides/uninstall.md) | Removing an install — and what stays behind |
@@ -40,7 +41,7 @@
40
41
 
41
42
  **Harness** — [Hosts](concepts/hosts.md) · [What each host automates](concepts/host-matrix.md) · [Rules](concepts/rules.md) · [Agents](concepts/agents.md) · [Skills](concepts/skills.md) · [Hooks](concepts/hooks.md) · [Hook gates, settings and the shim](concepts/hook-gates.md)
42
43
 
43
- **Memory** — [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md)
44
+ **Memory** — [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md) · [The shared tier](concepts/shared-tier.md)
44
45
 
45
46
  **Configuration** — [Footprint](concepts/footprint.md) · [Themes](concepts/themes.md) · [Exclusions](concepts/exclusions.md) · [Kits](concepts/kits.md) · [Code intelligence (LSP)](concepts/lsp.md)
46
47
 
@@ -60,4 +61,4 @@
60
61
 
61
62
  ## For contributors
62
63
 
63
- [Extending Geneseed](extending.md) — what each kind of addition costs · [DESIGN.md](../DESIGN.md) · [Design history](design-history.md) · [Token footprint](token-footprint.md) · [Web console internals](web-ui.md) · [OpenCode plugin wiring](opencode-plugin-setup.md) · [Candidate hosts](candidate-hosts.md) · adapters: [OpenCode](../adapters/opencode/README.md), [Claude Code](../adapters/claude-code/README.md), [Bob](../adapters/bob/README.md), [OpenClaude](../adapters/openclaude/README.md)
64
+ [Product requirements](PRD.md) · [Architecture, C4](architecture.md) · [Console design system](DESIGN.md) · [Extending Geneseed](extending.md) — what each kind of addition costs · [DESIGN.md](../DESIGN.md) · [Design history](design-history.md) · [Token footprint](token-footprint.md) · [Web console internals](web-ui.md) · [OpenCode plugin wiring](opencode-plugin-setup.md) · [Candidate hosts](candidate-hosts.md) · adapters: [OpenCode](../adapters/opencode/README.md), [Claude Code](../adapters/claude-code/README.md), [Bob](../adapters/bob/README.md), [OpenClaude](../adapters/openclaude/README.md)
@@ -0,0 +1,145 @@
1
+ ---
2
+ type: architecture
3
+ mirrors-commit: 9c4af014
4
+ generated: 2026-11-06
5
+ ---
6
+
7
+ # Geneseed architecture
8
+
9
+ The short map is the root [`ARCHITECTURE.md`](../ARCHITECTURE.md): parts, invariants and the lines
10
+ that must not be crossed. The module map is [`js/README.md`](../js/README.md). This page adds the C4
11
+ views and how the pieces meet at run time. It repeats neither.
12
+
13
+ <!-- geneseed:doc:start -->
14
+ ## Context (C4 L1)
15
+
16
+ A developer drives an AI coding host. Geneseed sits beside that host: it writes the host's
17
+ instructions, skills and agents, and answers the host's hook calls. It calls no model itself,
18
+ unless the user sets `GENESEED_LLM` for `learn` on a hook host.
19
+
20
+ ```mermaid
21
+ ---
22
+ title: Context (C4 L1) — Geneseed
23
+ ---
24
+ flowchart TB
25
+ dev(["Developer [person]"])
26
+ gs["Geneseed [software system · Node.js CLI, hooks, web console]"]
27
+ host["AI coding host [software system · Claude Code, OpenCode, Bob, OpenClaude]"]
28
+ npm["npm registry [external system]"]
29
+ git["Git remote [external system · a clone's origin]"]
30
+ vault["Wiki vault [external system · a folder of Markdown]"]
31
+ llm["Model CLI [external system · GENESEED_LLM, optional]"]
32
+
33
+ dev -->|"installs, upgrades, inspects · CLI, browser"| gs
34
+ dev -->|"works with the agent · host UI"| host
35
+ gs -->|"writes instructions, skills, agents, hook wiring · files"| host
36
+ host -->|"calls gates and context · process, stdin/stdout JSON"| gs
37
+ gs -->|"gets the package, checks for a release · HTTPS"| npm
38
+ gs -->|"self-updates a clone · git"| git
39
+ gs -->|"reads eager and lazy notes · files"| vault
40
+ gs -->|"distils facts on a hook host · process"| llm
41
+ subgraph Legend
42
+ l1(["person"]) ~~~ l2["software system"]
43
+ end
44
+ ```
45
+
46
+ Sources: `bin/geneseed-hook.mjs`, `js/hosts/settings.mjs`, `js/web/update-check.mjs`,
47
+ `js/maintain/update.mjs`, `js/hosts/hooks-learn.mjs`.
48
+ <!-- geneseed:doc:end -->
49
+
50
+ <!-- geneseed:doc:start -->
51
+ ## Containers (C4 L2)
52
+
53
+ ```mermaid
54
+ ---
55
+ title: Containers (C4 L2) — Geneseed on one machine
56
+ ---
57
+ flowchart TB
58
+ dev(["Developer [person]"])
59
+ host["AI coding host [software system]"]
60
+
61
+ subgraph gs["Geneseed"]
62
+ cli["geneseed [container · Node.js CLI, bin/geneseed-cli.mjs]"]
63
+ build["geneseed-build [container · Node.js generator, bin/build-driver.mjs]"]
64
+ hook["geneseed-hook [container · Node.js, bin/geneseed-hook.mjs]"]
65
+ shim["hook shim [container · script, ~/.geneseed/bin]"]
66
+ plugins["OpenCode plugins [container · JS in the host's process, adapters/opencode]"]
67
+ web["web console [container · Node.js daemon + React SPA, js/web, web/dist]"]
68
+ source[("source tree [database · src/, themes/]")]
69
+ install[("install [database · files in a host config dir or repo]")]
70
+ tier[("shared tier [database · files, ~/.config/geneseed]")]
71
+ end
72
+
73
+ dev -->|"runs verbs · shell"| cli
74
+ dev -->|"reads and acts · HTTP on localhost, port 4747"| web
75
+ cli -->|"starts an emit · in process, or via rebuild-all"| build
76
+ cli -->|"starts the daemon · process"| web
77
+ web -->|"runs jobs · process"| cli
78
+ build -->|"reads · files"| source
79
+ build -->|"renders and emits · files"| install
80
+ build -->|"seeds, then folds host stores · files"| tier
81
+ build -->|"rewrites, last writer wins · files"| shim
82
+ host -->|"loads text, skills, agents · files"| install
83
+ host -->|"runs on each hook event · process"| shim
84
+ host -->|"loads at start · in process"| plugins
85
+ shim -->|"calls · process"| hook
86
+ hook -->|"reads session files, writes facts · files"| tier
87
+ plugins -->|"reads session files, writes facts · files"| tier
88
+ hook -->|"reads context, gate markers · files"| install
89
+ plugins -->|"reads context, gate markers · files"| install
90
+ web -->|"reads and edits rules, profile, memory · files"| tier
91
+ web -->|"inspects and changes · files"| install
92
+ subgraph Legend
93
+ l1(["person"]) ~~~ l2["container"] ~~~ l3[("database")]
94
+ end
95
+ ```
96
+
97
+ The stores are plain files: no server or database engine runs. `installs.json`, the install
98
+ registry, sits in the tier's folder and tells the CLI and the console which installs exist.
99
+
100
+ | Container | Must not | Enforced by |
101
+ |---|---|---|
102
+ | `geneseed-build` | spawn | closure walks in `tests/unit/hook_cli.test.mjs` ([ADR 0002](adr/0002-no-spawn-on-the-generator-and-hook-path.md)) |
103
+ | `geneseed-hook` | print anything but its verdict | `fuzz/`, the golden CLI matrix |
104
+ | `geneseed` | spawn beyond its allow-list | [ADR 0002](adr/0002-no-spawn-on-the-generator-and-hook-path.md) |
105
+ | OpenCode plugins | import from `js/`, or throw on OpenCode 2 | `tests/plugins/helper_parity.test.mjs` |
106
+
107
+ ### Build and install flow
108
+
109
+ ```mermaid
110
+ ---
111
+ title: What a global emit does
112
+ ---
113
+ sequenceDiagram
114
+ participant U as geneseed / rebuild-all
115
+ participant B as geneseed-build
116
+ participant T as shared tier
117
+ participant I as host config dir
118
+ U->>B: --emit claude-global
119
+ B->>T: ensureSharedTier (canonical install only)
120
+ B->>B: renderAll, with absolute tier paths
121
+ B->>I: write files in the manifest, merge settings
122
+ B->>T: fold facts, read each copy back
123
+ B->>I: move the old store to archived-memory/
124
+ B->>T: fold notes, exclude paths, profile, wiki
125
+ B->>T: draft each rule that needs a decision
126
+ B-->>U: one [shared] report line
127
+ ```
128
+
129
+ A non-canonical emit, such as `geneseed diff` into a temp folder, renders the same paths and
130
+ creates and folds nothing. [The shared tier](concepts/shared-tier.md) holds the user-facing rules.
131
+ <!-- geneseed:doc:end -->
132
+
133
+ <!-- geneseed:doc:start -->
134
+ ## Decisions
135
+
136
+ The decisions are one file each in [`docs/adr/`](adr/README.md), and product decisions are in the
137
+ root [`DESIGN.md`](../DESIGN.md). They are not copied here. The structural ones behind this page:
138
+
139
+ - [0001](adr/0001-zero-runtime-dependencies.md) — vendored code, no installed runtime dependency.
140
+ - [0002](adr/0002-no-spawn-on-the-generator-and-hook-path.md) — who may spawn.
141
+ - [0004](adr/0004-uninstall-without-backups.md) — manifests and managed blocks.
142
+ - [0008](adr/0008-host-parity-ceiling-of-the-weakest-host.md) — a feature lands on every host.
143
+ - [0009](adr/0009-self-update-is-a-git-pull.md) — a clone updates itself with `git pull`.
144
+ - [0011](adr/0011-shared-tier.md) — one shared tier per machine.
145
+ <!-- geneseed:doc:end -->
@@ -40,7 +40,7 @@ In [foreman mode](foreman-mode.md) the session chains several of them into a pip
40
40
 
41
41
  ### Agents learn too
42
42
 
43
- When a subagent finishes, the learn step can record a lesson for that agent alone, in `memory/agents/<name>.md` — one bullet per lesson, capped so it never grows unbounded. The next time that agent runs, it starts with what it learned. See [Memory](memory.md). (Not on Bob, which has no subagent-finished event.)
43
+ When a subagent finishes, the learn step can record a lesson for that agent alone, in `agents/<name>.md` in the memory store (the [shared](shared-tier.md) one on a global install) — one bullet per lesson, capped so it never grows unbounded. The next time that agent runs, it starts with what it learned. See [Memory](memory.md). (Not on Bob, which has no subagent-finished event.)
44
44
 
45
45
  <!--harness:opencode-->
46
46
  *(OpenCode only)*
@@ -61,4 +61,4 @@ When new evidence contradicts a memory with a force, the agent must revise it in
61
61
 
62
62
  ### Profile — who you are
63
63
 
64
- `PROFILE.md` sits beside the instructions file, is seeded once and is never overwritten. It holds your role, habits and how you like answers pitched. It colours how the agent works but never binds — it is last in [precedence](rules.md). Edit the file directly, use the Profile tab in the web console, or let the `profile` [skill](skills.md) interview you and draft it; it writes only with your consent, and routes anything that is really a standing rule to `user-rules.md`.
64
+ `PROFILE.md` is seeded once and never overwritten. A global install keeps it in the [shared tier](shared-tier.md), one for the machine; a project install keeps it beside the instructions file. It holds your role, habits and how you like answers pitched. It colours how the agent works but never binds — it is last in [precedence](rules.md). Edit the file directly, use the Profile tab in the web console, or let the `profile` [skill](skills.md) interview you and draft it; it writes only with your consent, and routes anything that is really a standing rule to `user-rules.md`.
@@ -23,7 +23,7 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
23
23
  |---|---|---|---|---|---|
24
24
  | `sealed-secrets` | law | ask: rule-gate (credential-shaped content outside `.env*`). Switchable per install with `--no-secrets-gate` (see [Exclusions](exclusions.md)): this scan stands down on every host, the guard plugin's path block included | same as Claude Code | block: guard plugin (key/credential file path, or vendor-prefixed secret content); warns only on `.env*` | block (exit 2) |
25
25
  | `deletion-is-deliberate` | law | ask: git-gate, only on real data loss judged against the repository's state (the list in [Hooks](hooks.md): a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, the reflog pruned, files git cannot restore removed); asks when it cannot verify. Switchable per install with `--no-deletion-gate` (see [Exclusions](exclusions.md)): the real-loss check and the Law IV `permission.bash` keys stand down, everything else in this table stays **+** ask: git-gate, catastrophic shell (`rm -rf` of `/`, a drive root or `~`, `mkfs`, `dd` over a raw disk, `format`, fork bomb), whatever the state and even with the switch off | same as Claude Code | ask: permission prompt (`git reflog expire*`, `git gc --prune*`, a force push or delete of `main`/`master` by name) **+** block: guard plugin (catastrophic shell, the hook's check plus its own stricter text match: `rm -rf` of `/`, a drive root or `~`, fork bomb, `format`, `dd` over a raw disk) **+** block: guard plugin (every other real-loss case, the same state-aware decisions as the hook) | block (exit 2) |
26
- | `persist-insight` | process | ask: rule-gate (a write to `user-rules.md` or the memory store) | same as Claude Code | ask once: guard plugin (refuses the *first* write to that path; a re-issued write goes through) | log only (warning, call goes through) |
26
+ | `persist-insight` | process | ask: rule-gate (a write to `user-rules.md`, `user-rules.draft.md` or a memory store, shared one included) | same as Claude Code | ask: OpenCode's own prompt (`permission.edit`, and `evaluate` on OpenCode 2); the guard plugin refuses a file-tool write the host cannot prompt for | block a file-tool write: exit 2, no ask tier; a parsed shell write only warns |
27
27
  | `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed | log only |
28
28
  | `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list, or to a gate's own configuration: hook settings, `excludes.json`, `AGENT.md` gate markers, the hook shim) | same as Claude Code | ask: OpenCode's own `permission.edit` rules, written by the emit (every `opencode.json(c)`, the hook settings, the install's `AGENT.md`, `excludes.json`, manifest, plugins, the hook shim); block: guard plugin (the protected-checks list, and the other hosts' Geneseed-only files) | block (exit 2), writes only; a hook `settings.json` only when the edit changes Geneseed's own hook entries |
29
29
  | `verify-before-asserting` | law | block at Stop, once per turn: the done gate in `learn` (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (**unverified live**: a frozen fork, and no check runs a model turn) | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
@@ -5,7 +5,7 @@ title: "Exclusions"
5
5
  kind: "concept"
6
6
  section: "Configuration"
7
7
  description: "Three ways to switch things off: one rule, one skill, or every hook in a folder."
8
- link: {"hash": "#/harness", "label": "Manage in Harness →"}
8
+ link: {"hash": "#/installs/hosts", "label": "Manage on Installs →"}
9
9
  ---
10
10
  Geneseed has three ways to switch something off, and they work at different scales (plus an on/off switch for the hook gates of Laws I, III and IV, and for the ownership gate, below):
11
11
 
@@ -31,22 +31,22 @@ geneseed exclude list
31
31
  geneseed exclude remove ~/code/my-vault
32
32
  ```
33
33
 
34
- One command updates every global install on the machine. Each keeps the list in its own `excludes.json`, and every hook and plugin reads it on each call, so a change takes effect at once.
34
+ One command updates every global install on the machine. It writes the folder to the **shared list**, `excludes.json` in the machine-wide Geneseed folder (`~/.config/geneseed/`), and wires each global install. Every global hook and plugin reads the shared list on each call, beside the install's own `excludes.json`, so a change takes effect at once and the hosts cannot drift apart. The install's own file still holds the `wired` record of what the command set up on that host. A per-repo install never reads the shared list. An agent that edits either file is asked first, on every host: the list is a gate's own configuration.
35
35
 
36
36
  What "dormant" means per host:
37
37
 
38
38
  - **Claude Code** — every hook exits silently, and the global `CLAUDE.md` is suppressed natively through `claudeMdExcludes` in the repo's `.claude/settings.local.json`.
39
39
  - **OpenClaude** — the same, in the repo's `.openclaude/settings.local.json`.
40
40
  - **Bob** — every hook exits silently, and a stub `.bob/rules/geneseed.md` in the repo shadows the global rules file. A hand-written stub already there is never overwritten.
41
- - **OpenCode** — Geneseed's plugins stand down.
41
+ - **OpenCode** — the `geneseed-context`, `geneseed-guard`, `geneseed-learn` and `geneseed-activity` plugins stand down. Three plugins do not read the list: `geneseed-notify` still pings the desktop, `geneseed-ponytail` still injects its ruleset if you switched it on, and `geneseed-workflow` keeps its tool. The `permission` keys in a global `opencode.json` still apply, because OpenCode reads them before any plugin.
42
42
 
43
43
  `geneseed exclude remove` undoes all of it.
44
44
 
45
45
  **Git worktrees.** A linked worktree of an excluded repo (`git worktree add`) is excluded too, wherever it sits on disk: the hooks and plugins follow its `.git` file back to the main repository. The global `CLAUDE.md` is the exception on Claude Code and OpenClaude: `settings.local.json` is gitignored, so a worktree never gets it. Geneseed writes no tracked file in a repo you told it to leave alone, so `exclude add` and `exclude list` print the snippet to commit yourself in the repo's tracked `.claude/settings.json` (`.openclaude/` for OpenClaude): `"claudeMdExcludes": ["<path to the global CLAUDE.md>"]`.
46
46
 
47
- **Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. And a global install created *after* you added exclusions starts with an empty list: run `geneseed exclude add` again (`geneseed exclude list` flags installs whose lists differ).
47
+ **Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. And a global install created *after* you added exclusions is silent in those folders at once, through the shared list, and its next emit applies the repo-side wiring there. Until that emit, `geneseed exclude list` flags it.
48
48
 
49
- The web console has the same controls in the **Excluded folders** card on the Harness page, shown once a global install exists.
49
+ The web console has the same controls in the **Excluded folders** card on the Installs page, shown once a global install exists.
50
50
 
51
51
  ### Per-rule exclusion — one rule off
52
52
 
@@ -113,7 +113,7 @@ The [ownership](ownership.md) first-write gate is not a Rule's gate: it stops th
113
113
  geneseed build --emit claude-global --no-ownership-gate
114
114
  ```
115
115
 
116
- The install records `Ownership gate: off` beside the other gate markers, written only when off; rebuilds, upgrades and `geneseed status` carry it. The console has no switch for it, because it has no Rule row. What stops: the ownership check of `rule-gate` (Claude Code, OpenClaude) and of `tool-gate` (Bob), on OpenCode the guard plugin's ownership refusal, the setup proposal in the install's `AGENT.md` (the build drops that sentence), and the session-start decline reminder. A repo with `mode: on` still runs the ownership checkpoints, and every other check of those gates stays.
116
+ The install records `Ownership gate: off` beside the other gate markers, written only when off; rebuilds, upgrades and `geneseed status` carry it. The console's Constitution page has a switch for it inside the *Ownership* row of the Credo band: open the row, and a gate line follows the section's text. The gate belongs to no Rule, and that line exists only in the console. The section's text always binds, so the row's status stays *Always*. *Enforced by* reads **Gate off** while the gate is off, and the Credo's pill on the Precedence ladder counts it. What stops: the ownership check of `rule-gate` (Claude Code, OpenClaude) and of `tool-gate` (Bob), on OpenCode the guard plugin's ownership refusal, the setup proposal in the install's `AGENT.md` (the build drops that passage, and the `/document-project` suggestion in it goes too), and the session-start decline reminder. A repo with `mode: on` still runs the ownership checkpoints, and every other check of those gates stays.
117
117
 
118
118
  Two narrower ways out need no rebuild: `## Ownership` with `mode: off` in a repo's root `AGENTS.md` silences it for that repo and its team; answering "skip in this repo until I ask" writes `Setup: declined <YYYY-MM-DD>` into your personal `.geneseed/ownership.md`, which silences it for you alone in that repo until you delete the line or ask for the setup; and answering "skip this session" lets the session write on.
119
119
 
@@ -5,7 +5,7 @@ title: "Footprint (lean vs full)"
5
5
  kind: "concept"
6
6
  section: "Configuration"
7
7
  description: "Lean or full: how much of the constitution rides inline every turn."
8
- link: {"hash": "#/installs/hosts", "label": "Change it on Hosts →"}
8
+ link: {"hash": "#/installs/hosts", "label": "Change it on Installs →"}
9
9
  ---
10
10
  **Footprint** decides how much of the [constitution](rules.md) the agent carries *inline* in its instructions file on every turn. It has two settings, **lean** (the default) and **full**, chosen per install. It is a token-cost dial, not a rules dial: every rule the install adopted is in force at either setting.
11
11
 
@@ -5,7 +5,7 @@ title: "Foreman mode"
5
5
  kind: "concept"
6
6
  section: "Working together"
7
7
  description: "Direct or foreman: whether the session does the work or hands it to a task worker."
8
- link: {"hash": "#/harness", "label": "Set the mode in Harness →"}
8
+ link: {"hash": "#/installs/hosts", "label": "Set the mode on Installs →"}
9
9
  ---
10
10
  **Mode** decides how work gets executed in a session. Two modes ship: **direct**, the default, where the agent does every task itself, and **foreman**, where the session hands each task that would block it to a background [agent](agents.md) and keeps talking to you while it works.
11
11
 
@@ -73,7 +73,7 @@ You can also start a pipeline without foreman mode: ask the agent to "run a pipe
73
73
  geneseed setup
74
74
  ```
75
75
 
76
- - **Web console** — the per-install **Mode** dropdown on the Harness page, then **Apply**.
76
+ - **Web console** — the per-install **Mode** dropdown on the Installs page, then **Apply**.
77
77
  - **Command line** — with the emit target of the install you are changing; switch back with `--mode direct`:
78
78
 
79
79
  ```bash
@@ -37,7 +37,7 @@ The merge is surgical. Every other key and every hook of your own survive, and t
37
37
  **Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher or `SubagentStop`. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet. So Bob gets four hooks:
38
38
 
39
39
  - `SessionStart` → `geneseed-hook context`.
40
- - `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, and a write under a project's own protected-checks list. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all. The [ownership](ownership.md) gate also exits 2, but only once per session and repo: the same write passes after the developer answers.
40
+ - `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all. The [ownership](ownership.md) gate also exits 2, but only once per session and repo: the same write passes after the developer answers.
41
41
  - `Stop` → `geneseed-hook learn`.
42
42
  - `UserPromptSubmit` → `geneseed-hook activity`, which records the turn for the Activity view.
43
43
 
@@ -19,8 +19,8 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
19
19
  | `SessionStart` | `startup`, `resume`, `clear`, `compact`, `fork` | `geneseed-hook context` | injects your harness files and the repo's docs, or re-injects them after a resume, a fork, or an auto-compaction summarised them away | no |
20
20
  | `PreToolUse` | `Bash`, `PowerShell` | `geneseed-hook git-gate` | asks before a command that would really lose data, and before a recursive scan of a whole filesystem; asks before every commit and push | the commit/push question only |
21
21
  | `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your rules or memory; stops the session's first write once in an application repo with no `## Ownership` section | no |
22
- | `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into `memory/` | needs `GENESEED_LLM` |
23
- | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in `memory/agents/<name>.md` | needs `GENESEED_LLM` |
22
+ | `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into the memory store | needs `GENESEED_LLM` |
23
+ | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in the store's `agents/<name>.md` | needs `GENESEED_LLM` |
24
24
  | `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
25
25
  | `UserPromptSubmit` | you send a message | `geneseed-hook activity` | records the turn's start for the web console's Activity view; prints nothing | off with `GENESEED_ACTIVITY=off` |
26
26
  | `SessionEnd` | the session closes | `geneseed-hook activity` | marks the session ended and archives it | off with `GENESEED_ACTIVITY=off` |
@@ -39,7 +39,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
39
39
 
40
40
  ## What each one does, and what you see
41
41
 
42
- **context.** Before your first message, the agent receives your own harness files — `user-rules.md`, `PROFILE.md`, the memory index, the notebook index, your wiki declaration — skipping any still untouched since install, then the repo's docs, discovered by convention or listed in a `context.json`. Each file is capped at 16 KB and the whole injection at 48 KB; what does not fit is listed for the agent to read on demand. You see nothing, except that the agent already knows your project. See [Project context](../guides/project-context.md).
42
+ **context.** Before your first message, the agent receives your own harness files — `user-rules.md`, `PROFILE.md`, the memory index, the notebook index, your wiki declaration — skipping any still untouched since install, then the repo's docs, discovered by convention or listed in a `context.json`. A global install reads these from the [shared tier](shared-tier.md) first, then from the host folder. The hook keeps its whole output under 9 000 characters, because the host cuts a longer one; what does not fit is listed for the agent to read on demand. A git root whose `package.json` has no `engines` field adds one `Runtime floor:` line, which asks the agent to name the supported runtime before it adds a dependency or a language feature. You see nothing, except that the agent already knows your project. See [Project context](../guides/project-context.md).
43
43
 
44
44
  **git-gate.** Runs before every shell command and looks for `git` in it, including chained one-liners and `git -C <path>` forms, and for a recursive scan of a whole filesystem.
45
45
  - **A catastrophic command** gets a confirmation prompt citing *Deletion Is Deliberate* (on Bob, it is refused with exit 2) whatever the repository holds, even with the deletion gate switched off: a recursive removal of `/`, a drive root (`C:\`, `/c`) or the home directory (`~`, `$HOME`), `mkfs` on a device, `dd` over a raw disk, `format C:`, a fork bomb. It judges the program, not the text: a `sudo`, a background `&`, a subshell, `bash -c '…'` or a heredoc fed to a shell (`bash <<'EOF'`) hides nothing, and a heredoc fed to anything else (`cat`, `git commit -F -`) or a commit message that only names `rm -rf /` passes. The OpenCode guard runs the same code, plus its own stricter text match.
@@ -55,27 +55,29 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
55
55
  A force push to a feature branch, the protected-branch-only forms above on a feature branch, a new branch (`checkout -b`, `switch -c`), `reset --hard` over uncommitted work or to a commit that keeps every unpushed one, `branch -D` of a pushed branch, or `rm` of a tracked, unmodified file passes. When the gate cannot tell — a glob or `$variable` it would have to expand, a `cd` it cannot follow, `sh -c`/`xargs`, git failing or missing — it asks, and says it could not verify. To read the state it runs `git` itself, only once a command already looked destructive; every other command pays nothing. That is a Rule, so it holds in every build — unless you switch its gate off for one install with `--no-deletion-gate` (or the switch on Rule IV in the console's Constitution page). The hook is then wired with `--no-deletion-gate` and this check stands down; the Rule's text still binds the agent, and the catastrophic-command check above and the root-scan and consent checks below still run ([Exclusions](exclusions.md)).
56
56
  - **Every `git commit` and `git push`** gets a prompt citing *Consent Before Push*. This part belongs to the **process** doctrine pack: build without it, or exclude that rule, and the hook stays wired with `--no-consent` — commits and pushes go through without asking, real data loss is still stopped ([Rules](rules.md)).
57
57
  - **A recursive scan of a whole filesystem** — `find /`, `du -sh /`, `grep -r foo /`, `rg x C:\`, `Get-ChildItem C:\ -Recurse` — gets a prompt citing *Commands Must Return* (on Bob, it is blocked). In Git Bash `/` mounts every drive and mounted share, so such a scan runs for hours, and `| head` does not stop it. The prompt tells the agent to search a specific directory instead. A deeper path (`find /c/Users/me/project`), `ls /` without `-R` (`ls -r` is reverse order, not recursion), a quoted argument (a search pattern such as `grep -rn "/" src`), a `#` comment, and the remote half of an `ssh` command pass. This check is wired in every build, whatever packs or rules you excluded: it rides inside `git-gate` with no flag of its own, because a new flag or verb would reach machines still running an older hook shim, which would refuse it — and Claude Code blocks a tool call whose gate fails.
58
+ - **A shell write to a protected check or a gate's own configuration** gets the same *External Gate* prompt as a write tool (see rule-gate below; on Bob, it is blocked). `--no-consent` does not touch it.
58
59
  - Any other command passes untouched.
59
60
 
60
61
  **rule-gate.** Runs before every file write.
61
62
  - Content that looks like a credential (a cloud access key, a GitHub or Anthropic token, a Slack token, a private-key block) going into any file other than `.env*` gets a prompt citing *Sealed Secrets*. An install built `--no-secrets-gate` wires the hook with that flag and this check alone stands down ([Exclusions](exclusions.md)).
62
- - A write to `user-rules.md`, `MEMORY.md` or a file in the install's `memory/` gets a prompt citing *Persist Insight*: whether something is a standing rule or a fact to remember is your call, settled through the `rule` [skill](skills.md).
63
- - A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). The list is `.geneseed/protected-checks.txt` at the project's git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A project install (any host) seeds it when it is absent, with only the paths that exist there: CI (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`, `.circleci/`), lint, type and test config (`eslint.config.*`, `.eslintrc*`, `biome.json(c)`, `tsconfig.json`, `jest.config.*`, `vitest.config.*`, `pytest.ini`, `ruff.toml`, `.golangci.yml`, `checkstyle.xml`), and the manifests the done gate infers its checks from (`package.json`, `pom.xml`, `build.gradle(.kts)`, `pyproject.toml`, `Cargo.toml`, `go.mod`). It is seeded once and is yours from then on: Geneseed never rewrites it, never deletes it on uninstall, and never touches a list that already exists. To opt out, delete the listed paths (the comments may stay) but keep the file. An existing list, even one holding only comments, is never seeded again; a deleted file is. A global install seeds nothing. Whenever `.geneseed/` exists, the emit also makes sure it holds the personal-by-default `.gitignore`. A check the agent can edit is not a check. The list protects itself. Only file-write tools are seen: a shell `sed -i` or redirect is not, so run the same checks in CI as the boundary that holds.
63
+ - A write to `user-rules.md`, `user-rules.draft.md`, `MEMORY.md` or a file in the install's `memory/` or the shared `~/.config/geneseed/memory/` gets a prompt citing *Persist Insight*: whether something is a standing rule or a fact to remember is your call, settled through the `rule` [skill](skills.md).
64
+ - A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). The list is `.geneseed/protected-checks.txt` at the project's git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A project install (any host) seeds it when it is absent, with only the paths that exist there: CI (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`, `.circleci/`), lint, type and test config (`eslint.config.*`, `.eslintrc*`, `biome.json(c)`, `tsconfig.json`, `jest.config.*`, `vitest.config.*`, `pytest.ini`, `ruff.toml`, `.golangci.yml`, `checkstyle.xml`), and the manifests the done gate infers its checks from (`package.json`, `pom.xml`, `build.gradle(.kts)`, `pyproject.toml`, `Cargo.toml`, `go.mod`). It is seeded once and is yours from then on: Geneseed never rewrites it, never deletes it on uninstall, and never touches a list that already exists. To opt out, delete the listed paths (the comments may stay) but keep the file. An existing list, even one holding only comments, is never seeded again; a deleted file is. A global install seeds nothing. Whenever `.geneseed/` exists, the emit also makes sure it holds the personal-by-default `.gitignore`. A check the agent can edit is not a check. The list protects itself. A shell command is read too: the targets of `>`, `>>`, `tee`, `sed -i`, `cp`, `mv` and `rm` get the same check, by path only (no secret scan of the command), through the git gate. `mv` counts its source as well, and a read (`cat x > /tmp/y`) counts only `/tmp/y`. What the reader cannot follow stays unseen: interpreters with inline code, scripts, `npm run`, variables, globs, subshell tricks, a folder removed above a listed file. So run the same checks in CI as the boundary that holds.
64
65
  - A write to `.geneseed/done-checks.txt`, the done gate's own list (below), gets the same *External Gate* prompt: emptying it would disarm the gate.
65
66
  - A write to a gate's own configuration gets the same *External Gate* prompt on Claude Code and OpenClaude. These files can switch a gate off:
66
- - In the install's own dir: `settings.json`, `settings.local.json` and Bob global's `settings/settings.json` (the hook wiring), `excludes.json`, `AGENT.md` (its `… gate: off` markers), `.geneseed-manifest.json` and `.geneseed-emit`.
67
+ - In the install's own dir: `settings.json`, `settings.local.json` and Bob global's `settings/settings.json` (the hook wiring), `excludes.json`, `AGENT.md` (its `… gate: off` markers), `.geneseed-manifest.json` and `.geneseed-emit`; and `excludes.json` in the machine-wide `~/.config/geneseed/` folder, the shared exclude list.
67
68
  - In any project: the same names under a `.claude/`, `.openclaude/`, `.bob/` or `.opencode/` folder (at the git root, in a subpackage, or with no git at all), and any `opencode.json(c)`. A team `settings.json` can set `disableAllHooks`.
68
69
  - The machine-wide hook shim in `~/.geneseed/bin/` (or `$GENESEED_HOME/bin/`).
69
70
  - On OpenCode, also the install's `opencode.json(c)` and its own `plugins/geneseed-*.js`.
70
- - **OpenCode** asks with its own prompt. The emit writes `permission.edit` "ask" keys into `opencode.json`: every `opencode.json(c)`, the global `config.json`, the install's `AGENT.md` (where the emit put it), the install dir's `excludes.json`, manifest, `.geneseed-emit` and `plugins/geneseed-*.js`, the `.claude/`, `.openclaude/` and `.bob/` hook settings, and the shim dir. A blanket `"edit": "allow"` becomes `{"*": "allow", …}` with the asks after it. A blanket `"ask"` or `"deny"` already covers them and is left alone; a key you set yourself is kept and named in a warning. The manifest records the keys Geneseed added (`edit_asks`, `edit_shorthand`); a rebuild drops a recorded key it no longer wants, and uninstall takes back the ones still set to `"ask"` and restores your `"allow"`. The guard plugin refuses only the other hosts' Geneseed-only files (`excludes.json`, `AGENT.md`, manifest) and an `AGENT.md` under `$GENESEED_HARNESS`. These rules match by name, not through a link, a project `opencode.json` with its own `"edit": "allow"` replaces a global install's object, and a custom `$GENESEED_HOME` is named by its absolute path, which only OpenCode 2 matches. In OpenCode's built-in plan agent, these files are asked about rather than refused.
71
+ - **OpenCode** asks with its own prompt. The emit writes `permission.edit` "ask" keys into `opencode.json`: every `opencode.json(c)`, the global `config.json`, the install's `AGENT.md` (where the emit put it), the install dir's `excludes.json`, manifest and `.geneseed-emit`, everything that can load code or set permissions there (`plugins/*`, `plugin/*`, `tool/*`, `tools/*`, `agents/*.md`, `agent/*.md`, `mode/*.md`, `modes/*.md`), `user-rules.md`, `user-rules.draft.md` and `MEMORY.md` by name, the install's and the shared `memory/*.md`, the `.claude/`, `.openclaude/` and `.bob/` hook settings, and the shim dir. A blanket `"edit": "allow"` becomes `{"*": "allow", …}` with the asks after it. A blanket `"ask"` or `"deny"` already covers them and is left alone; a key you set yourself is kept and named in a warning. The manifest records the keys Geneseed added (`edit_asks`, `edit_shorthand`); a rebuild drops a recorded key it no longer wants, and uninstall takes back the ones still set to `"ask"` and restores your `"allow"`. The guard plugin refuses only the other hosts' Geneseed-only files (`excludes.json`, `AGENT.md`, manifest) and an `AGENT.md` under `$GENESEED_HARNESS`. These rules match by name, not through a link, a project `opencode.json` with its own `"edit": "allow"` replaces a global install's object, and a custom `$GENESEED_HOME` is named by its absolute path, which only OpenCode 2 matches. In OpenCode's built-in plan agent, these files are asked about rather than refused.
71
72
  - **Bob** has no prompt, so it blocks, and only writes: a read passes, and so does a write to `opencode.json(c)`, which Bob never reads. A hook `settings.json` (or `settings.local.json`, or global `settings/settings.json`) is blocked only when the write changes Geneseed's own entries (a hook whose command names `geneseed-hook`, with its event and matcher), turns on `disableAllHooks`, or changes a `GENESEED_*`, `*_CONFIG_DIR` or `NODE_OPTIONS` env value. An MCP server or your own hook passes. An edit the hook cannot replay exactly is blocked: a regex, case-folded or line-ranged replace, a search not found exactly once, a diff of more than one block, an unknown write-shaped tool (its name says write, edit, diff, replace or insert; a tool named otherwise is not judged), or a file left unparseable or turned from strict JSON into JSONC. The other files stay blocked.
72
- Names match exactly, and on Windows without regard to case or slash direction; a link into one of these paths is caught too. To change one of these files, edit it yourself, or approve the prompt. `geneseed` commands (`exclude`, a rebuild) write these files directly and are never asked. Claude Code itself also prompts for writes under `.claude/` in its default and `acceptEdits` modes, but not in `bypassPermissions`, so you can see two prompts there. Only file-write tools are seen, as above.
73
- - The first write of a session in an application repo (a git root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section is refused once, the **ownership gate**. It is not a prompt for you: the reason goes to the agent, which asks you to set ownership up now, skip this session, or skip in this repo until you ask (on Bob, exit 2, once). The next write passes, a sub-agent never triggers it on Claude Code and OpenClaude, and writes to `AGENTS.md` or `.geneseed/` pass. Off per repo with `mode: off` in that section; for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, which also makes every session start with the line `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it`; per install with `--no-ownership-gate`, which prints no such line ([Ownership](ownership.md), [Exclusions](exclusions.md)).
73
+ Names match exactly, and on Windows without regard to case or slash direction; a link into one of these paths is caught too. To change one of these files, edit it yourself, or approve the prompt. `geneseed` commands (`exclude`, a rebuild) write these files directly and are never asked. Claude Code itself also prompts for writes under `.claude/` in its default and `acceptEdits` modes, but not in `bypassPermissions`, so you can see two prompts there. A shell write is read as above. On OpenCode `permission.edit` covers edit tools only, so the guard refuses a shell write to every file in this list; the same edit through an edit tool gets the prompt. On Bob a shell write to a hook `settings.json` is blocked: a command line cannot be replayed.
74
+ - The first write of a session in an application repo (a git root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section is refused once, the **ownership gate**. Despite the name it is a reminder, not a gate, because the next write passes. It is not a prompt for you: the reason goes to the agent, which asks you to set ownership up now, skip this session, or skip in this repo until you ask (on Bob, exit 2, once). The next write passes, a sub-agent never triggers it on Claude Code and OpenClaude, and writes to `AGENTS.md` or `.geneseed/` pass. Off per repo with `mode: off` in that section; for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, which also makes every session start with the line `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it`; per install with `--no-ownership-gate`, which prints no such line ([Ownership](ownership.md), [Exclusions](exclusions.md)).
75
+ - An edit that weakens a test gets a note to the agent, citing *Cure the Cause*. It is **advisory**: it asks nothing and blocks nothing. A test file has a path segment `test`, `tests`, `__tests__` or `spec`, or a name `*.test.*`, `*.spec.*`, `*_test.*` or `test_*`. The edit weakens it when it adds `.skip(`, `xit(`, `xfail`, `@Disabled`, `@Ignore`, `pytest.mark.skip` or `t.Skip(`, or when it removes an assertion line and adds no other. The done gate repeats it to you when the turn ends. On Bob the note is a line in the hook log. On OpenCode it is one reminder on the next request.
74
76
  - Ordinary edits pass untouched.
75
77
 
76
- **The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**: a turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test`. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. The gate never runs a check itself. It reads the transcript from its end, back only to the prompt that opened the turn, so its cost does not grow with the session. It blocks at most once per turn; the second stop ends the turn and leaves a line in the gate ledger. Only file-write tools count as edits: a shell `sed -i` or redirect is not seen. On OpenCode the gate is a reminder on the next request (OpenCode 1 only), listed or inferred; on Bob, whose Stop carries no transcript, the turn is not judged, and with a listed file a log line says so. An install built `--no-done-gate` wires `learn` with that flag: the check is skipped, learning still runs ([Exclusions](exclusions.md)).
78
+ **The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**, and they stay advisory, with no date: only a list the project wrote can block. A turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test`. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. The gate never runs a check itself. It reads the transcript from its end, back only to the prompt that opened the turn, so its cost does not grow with the session. It blocks at most once per turn; the second stop ends the turn and leaves a line in the gate ledger. Only file-write tools count as edits: a shell `sed -i` or redirect is not one here. When a turn weakened a test (see the rule gate), the gate adds a line that the agent cannot suppress, `[done-gate] advisory — test weakened this turn: tests/a.test.js (.skip added)`. The line needs no checks and stays out of the ask counts. `--no-done-gate` silences this line and OpenCode's reminder, but not the note the agent gets at edit time on Claude Code, OpenClaude and Bob: the rule gate never receives that flag. A block prints only the block; the line comes at the stop that ends the turn. On OpenCode the gate is a reminder on the next request (OpenCode 1 only), listed or inferred; on Bob, whose Stop carries no transcript, the turn is not judged, and with a listed file a log line says so. An install built `--no-done-gate` wires `learn` with that flag: the check is skipped, learning still runs ([Exclusions](exclusions.md)).
77
79
 
78
- **learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries under `memory/`. It is shown the facts already stored, so it updates one with the merged text rather than writing a twin (the old version is kept in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It needs `GENESEED_LLM` set to a model command, for example:
80
+ **learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries in the memory store: on a global install, the shared one when it exists. It is shown the facts already stored, so it updates one with the merged text rather than writing a twin (the old version is kept in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It needs `GENESEED_LLM` set to a model command, for example:
79
81
 
80
82
  ```bash
81
83
  export GENESEED_LLM="claude -p"
@@ -88,3 +90,17 @@ Unset, `learn` does nothing useful: on a real Stop/SubagentStop/PreCompact call
88
90
  Open a session in a repo and ask the agent what it knows about the project — it should answer from the repo's docs without reading them first. Ask it to commit something: you should get a prompt before the commit runs.
89
91
 
90
92
  What happens when a gate cannot decide, where the hooks are written, and the one file they all run through: [Hook gates, settings and the shim](hook-gates.md).
93
+
94
+ ## The change report
95
+
96
+ Shell is not a boundary. The gates read only parsed forms of a command, and the host's own command permission is the backstop for the rest. So Geneseed also checks afterwards: at session start it records each store file's size and modified time (`user-rules.md`, `PROFILE.md`, the wiki manifest, `memory/**/*.md`), and at the end of each turn it compares. A change outside this session's approved writes is told to you once, and `geneseed status` shows a `changes` row for seven days. **The report detects a change. It does not prevent one.**
97
+
98
+ | Host | Baseline | Approved means | You see |
99
+ | --- | --- | --- | --- |
100
+ | Claude Code, OpenClaude | `<install>/notebook/store-baseline/`, at SessionStart | the transcript shows a Write, Edit or NotebookEdit ran | a `systemMessage` at Stop |
101
+ | Bob | same | nothing: a file-tool write is refused there, so any change is reported | a stderr line at Stop, in Bob's hook log |
102
+ | OpenCode | in the guard plugin's memory | `tool.execute.after` on OpenCode's own edit tools | a toast (1.x), a synthetic message (2.x) |
103
+
104
+ Geneseed's own writers do not count. `learn`, `geneseed memory rm`, the OpenCode learn plugin and the fold snapshot the store around their run and log what moved to `memory/.own-writes.json`, as an exact size and time. A change that matches is excused. Two limits follow: anything else that writes during that run is excused too, and the log is a plain file an agent could edit.
105
+
106
+ Other limits. Approval is per session and the shared tier is not, so another session's approved write is reported here too, and the line says it may be that. An edit in the web console during a session is reported, because it is not logged. On Claude Code a sub-agent's write sits in its own transcript, so it is reported the same way. The baseline is a plain file: an agent that can write there can edit it, or set a file's size and time back. The report is evidence, not a control. If a done-gate advisory already holds stdout at that Stop, the line goes to stderr and the `changes` row.
@@ -18,7 +18,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
18
18
  | Real data loss (force-push to `main`, discarding uncommitted work, `rm` of untracked files…) | ⚙️ block³ · 🔒 ask (reflog, gc) | 🪝 ask | 🪝 block¹ | 🪝 ask² |
19
19
  | Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
20
20
  | Consent before every commit and push | 🔒 permission ask | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
21
- | Rule-or-memory write needs your call | ⚙️ speed bump³ | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
21
+ | Rule-or-memory write needs your call | 🔒 ask³ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
22
22
  | User-only skills hidden from the model | 🔒 `permission.skill` deny | ✅ `disable-model-invocation` | ✅ `/`-command, no skill | ✅ `disable-model-invocation` |
23
23
  | Sovereign-repo exclusions⁵ | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
24
24
  | MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
@@ -26,9 +26,9 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
26
26
 
27
27
  ✅ native · ⚙️ OpenCode plugin · 🔒 `permission` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
28
28
 
29
- ¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks only the rules that admit no judgement call — secrets, real data loss, a recursive scan of a whole filesystem, and a write under a project's own protected-checks list — and turns the two consent checks into a logged warning. It has no `SubagentStop` event. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet, so learn runs on `Stop` only. **What is verified:** the payload shape (Claude's keys plus `cwd`), the event list and the strict settings schema were read in Bob 2.2.3's shipped bundle on the authoring machine, and a live prompt on 2026-10-25 wrote an Activity snapshot from `UserPromptSubmit`. The gates' block-by-exit-code behaviour is Bob's documented contract, not yet observed live; the rules preamble still holds if a hook does not fire.
29
+ ¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks only the rules that admit no judgement call — secrets, real data loss, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off — and turns the two consent checks into a logged warning. It has no `SubagentStop` event. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet, so learn runs on `Stop` only. **What is verified:** the payload shape (Claude's keys plus `cwd`), the event list and the strict settings schema were read in Bob 2.2.3's shipped bundle on the authoring machine, and a live prompt on 2026-10-25 wrote an Activity snapshot from `UserPromptSubmit`. The gates' block-by-exit-code behaviour is Bob's documented contract, not yet observed live; the rules preamble still holds if a hook does not fire.
30
30
  ² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). **Unverified live** for the same reason.
31
- ³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so the rule-or-memory check stops the first such write once rather than prompting, and a real data loss is blocked outright (as on Bob) rather than asked; `GENESEED_GUARD=warn` turns the block into a logged warning.
31
+ ³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so a rule-or-memory write gets OpenCode's own prompt, and the guard refuses a file-tool write where no prompt can run. Shell is not a boundary on any host: only parsed forms are read, and the host's command permission is the backstop. A real data loss is blocked outright (as on Bob) rather than asked; `GENESEED_GUARD=warn` turns a block into a logged warning.
32
32
  ⁴ The checks differ in shape: OpenCode's guard plugin blocks writes *to* private-key and credential files by path; the Claude-shaped hook looks at the *content* being written for credential-shaped strings (cloud keys, tokens, private-key blocks) and asks. A `.env` file is exempt on the hook side — that is where a secret is allowed to live.
33
33
  ⁵ A linked git worktree of an excluded repo is excluded too: the hooks and plugins follow its `.git` file back to the main repository. `claudeMdExcludes` is the exception — it lives in the gitignored `settings.local.json`, which a worktree never gets — so `geneseed exclude add` and `exclude list` print the snippet to commit yourself. See [Exclusions](exclusions.md).
34
34
 
@@ -14,7 +14,7 @@ A **host** is the AI coding tool Geneseed installs into — OpenCode, Claude Cod
14
14
 
15
15
  One build renders the same text for every host: the constitution ([rules](rules.md)), the {N_AGENTS} [agents](agents.md), the {N_SKILLS} [skills](skills.md), the [memory](memory.md) and [notebook](notebook.md) conventions, and the theme's voice. No host drops an agent, a skill or the memory convention.
16
16
 
17
- Each host has a **global** install (in its config directory, active in every repo) and a **per-repo** install (inside one project). There is also a portable `files` bundle — a plain `Harness/` folder with an `AGENT.md` that any tool reading an instructions file can use, with no automation at all.
17
+ Each host has a **global** install (in its config directory, active in every repo) and a **per-repo** install (inside one project). There is also a portable `files` bundle — a plain `Harness/` folder with an `AGENT.md` that any tool reading an instructions file can use, with no automation at all. That file is `AGENT.md`, singular, and the bundle owns it. `AGENTS.md`, plural, is the cross-tool name that OpenCode, Bob and OpenClaude read; Claude Code reads it through an `@AGENTS.md` import in `CLAUDE.md`. This repository keeps its own guide in `AGENTS.md` that way.
18
18
 
19
19
  ## Two engines
20
20
 
@@ -59,7 +59,9 @@ An install with a kit on records it in its instructions file, under the skill se
59
59
 
60
60
  `geneseed status` shows `kits: spring-boot` on the install's row, and `status --json` carries the same list.
61
61
 
62
- In the web console, **Installs → Kits** (`#/installs/kits`) lists every install (disabled ones read-only) with one switch per kit. Toggling stages the set; **Apply** asks for confirmation, then rebuilds that one install with exactly that set as a console job (replace, not replay). Files you edited in a kit that is now off are kept, and the row names them so you can delete them by hand. The top-level **Kits** page (`#/kits`) lists the kits; a kit's page (`#/kits/<kit>`) shows its rules, banned APIs and upstream credits with the same per-install switch, and the Library tags each member skill or agent with a `kit:` badge.
62
+ Kits stay per install: the [shared tier](shared-tier.md) holds what you teach the agent, not what an install renders.
63
+
64
+ In the web console, the **Kits** page (`#/kits`) is the one home of the kit switches: a card per kit over a kits × installs matrix, disabled installs read-only. Toggling stages the set; **Apply** asks for confirmation, then rebuilds that one install with exactly that set as a console job (replace, not replay). Files you edited in a kit that is now off are kept, and the matrix lists them under their install so you can delete them by hand. A kit's page (`#/kits/<kit>`) shows its rules, banned APIs and upstream credits with the same per-install switch, and the Library tags each member skill or agent with a `kit:` badge.
63
65
 
64
66
  ### What a kit adds to an install
65
67
 
@@ -34,7 +34,7 @@ the repository.
34
34
 
35
35
  ## Java notes for the newer bricks
36
36
 
37
- - **`mutation-check`** (`legacy-tests`) prefers PIT on a Maven build: `mvn test-compile
37
+ - **`mutation-check`** (`legacy-tests`, `bugfix`) prefers PIT on a Maven build: `mvn test-compile
38
38
  org.pitest:pitest-maven:mutationCoverage -DtargetClasses=<fq.Class*>
39
39
  -DreportsDirectory=<OS temp dir> -DtimestampedReports=false`, and needs `pitest-junit5-plugin`
40
40
  on the classpath under JUnit 5; on Gradle, the `info.solidsoft.pitest` plugin's `pitest` task.