geneseed 5.0.1 → 5.0.3

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 (125) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/README.md +1 -1
  3. package/SHIPPED.md +1 -1
  4. package/adapters/claude-code/README.md +6 -4
  5. package/adapters/opencode/HOW-OPENCODE-LOADS.md +3 -0
  6. package/adapters/opencode/plugins/geneseed-context.js +12 -1
  7. package/adapters/opencode/plugins/geneseed-guard.js +594 -73
  8. package/adapters/opencode/plugins/geneseed-learn.js +1 -1
  9. package/bin/geneseed-hook.mjs +21 -7
  10. package/docs/concepts/enforcement-table.md +22 -3
  11. package/docs/concepts/exclusions.md +48 -2
  12. package/docs/concepts/foreman-mode.md +19 -4
  13. package/docs/concepts/hook-gates.md +1 -1
  14. package/docs/concepts/hooks.md +52 -11
  15. package/docs/concepts/host-matrix.md +4 -3
  16. package/docs/concepts/hosts.md +1 -1
  17. package/docs/concepts/kits.md +18 -0
  18. package/docs/concepts/shared-tier.md +1 -1
  19. package/docs/concepts/skills.md +1 -1
  20. package/docs/extending.md +3 -1
  21. package/docs/guides/autostart.md +27 -3
  22. package/docs/guides/choose-your-setup.md +1 -1
  23. package/docs/guides/migrate.md +1 -1
  24. package/docs/guides/uninstall.md +1 -1
  25. package/docs/reference/plugin-context.md +1 -1
  26. package/docs/reference/plugin-guard.md +24 -5
  27. package/docs/reference/troubleshoot-doctor.md +2 -2
  28. package/docs/understand/a-day.md +9 -5
  29. package/docs/web-ui.md +67 -16
  30. package/harness.config.json +1 -1
  31. package/js/README.md +1 -1
  32. package/js/build/emit-claude.mjs +9 -1
  33. package/js/build/emit-opencode.mjs +2 -1
  34. package/js/build/source.mjs +9 -3
  35. package/js/cli-table.json +121 -1
  36. package/js/hosts/geneseed-dir.mjs +1 -1
  37. package/js/hosts/hooks-context.mjs +8 -6
  38. package/js/hosts/hooks-done.mjs +3 -1
  39. package/js/hosts/hooks-learn.mjs +1 -1
  40. package/js/hosts/hooks-prims.mjs +270 -0
  41. package/js/hosts/hooks.mjs +409 -151
  42. package/js/hosts/hosts.mjs +22 -0
  43. package/js/hosts/installs.mjs +9 -5
  44. package/js/hosts/settings.mjs +123 -23
  45. package/js/hosts/shim.mjs +155 -7
  46. package/js/hosts/store-watch.mjs +36 -11
  47. package/js/inspect/diff.mjs +2 -1
  48. package/js/inspect/inventory.mjs +1 -0
  49. package/js/inspect/validate.mjs +1 -1
  50. package/js/maintain/migrate.mjs +2 -2
  51. package/js/maintain/uninstall.mjs +5 -1
  52. package/js/web/actions.mjs +17 -1
  53. package/js/web/api.mjs +9 -10
  54. package/js/web/routes.mjs +2 -1
  55. package/package.json +1 -1
  56. package/registry.json +21 -0
  57. package/src/AGENT.md.tmpl +17 -21
  58. package/src/agents/_self-improvement.md +7 -6
  59. package/src/agents/developer.md +3 -2
  60. package/src/agents/docker-expert.md +1 -0
  61. package/src/agents/memory-curator.md +3 -2
  62. package/src/doctrines/process.md +24 -19
  63. package/src/kits/ci-pipelines/rules.md +10 -0
  64. package/src/kits/ci-pipelines.json +14 -0
  65. package/src/kits/docker/rules.md +11 -0
  66. package/src/kits/docker.json +12 -0
  67. package/src/memory/README.md +5 -4
  68. package/src/modes/foreman.md +23 -10
  69. package/src/notebook/README.md +1 -1
  70. package/src/skills/_self-improvement.md +12 -9
  71. package/src/skills/compose-ops.md +58 -0
  72. package/src/skills/gitlab-ci.md +51 -0
  73. package/src/skills/jenkins-pipeline.md +56 -0
  74. package/src/skills/pipeline.md +2 -2
  75. package/src/skills/rule.md +24 -18
  76. package/src/skills/skill-forge.md +24 -6
  77. package/themes/_TEMPLATE.json +5 -2
  78. package/themes/biker.json +5 -2
  79. package/themes/commentator.json +5 -2
  80. package/themes/cyberpunk.json +5 -2
  81. package/themes/gamer.json +5 -2
  82. package/themes/imperial.json +5 -2
  83. package/themes/joker.json +5 -2
  84. package/themes/marvin.json +5 -2
  85. package/themes/mean.json +5 -2
  86. package/themes/military.json +5 -2
  87. package/themes/neutral.json +5 -2
  88. package/themes/pirate.json +5 -2
  89. package/themes/sports.json +5 -2
  90. package/themes/verstappen.json +5 -2
  91. package/themes/wizard.json +5 -2
  92. package/web/dist/assets/Activity-Ck_Xffpo.js +1 -0
  93. package/web/dist/assets/ActivityDetail-CBxVS4mU.js +1 -0
  94. package/web/dist/assets/{Bonsai-C1iBAt4v.js → Bonsai-BlOwsvW6.js} +1 -1
  95. package/web/dist/assets/{CopyButton-DJ3a4N88.js → CopyButton-DFMOIGbe.js} +1 -1
  96. package/web/dist/assets/Dashboard-BUdUTjbB.js +2 -0
  97. package/web/dist/assets/{Docs-Kffdg5uV.js → Docs-D_2Jt6gU.js} +3 -3
  98. package/web/dist/assets/{GreenhouseView-k56_cBSF.js → GreenhouseView-WalcX5bp.js} +1 -1
  99. package/web/dist/assets/{Installs-DtEKLC9h.js → Installs-UGiPDMDt.js} +3 -3
  100. package/web/dist/assets/{JournalView-RQnk5l7I.js → JournalView-CZtXQz-v.js} +1 -1
  101. package/web/dist/assets/Kits-XQHsazCN.js +1 -0
  102. package/web/dist/assets/Laws-B6A55S-2.js +4 -0
  103. package/web/dist/assets/Library-D7L0Wdbh.js +3 -0
  104. package/web/dist/assets/Loops-C0loS73u.js +2 -0
  105. package/web/dist/assets/{OperatorHudView-CM5jNPwL.js → OperatorHudView-CeDw5qMB.js} +1 -1
  106. package/web/dist/assets/Personal-PVmGA2-M.js +2 -0
  107. package/web/dist/assets/{RailCats-DQxxYBEP.js → RailCats-BGZnJ6fa.js} +1 -1
  108. package/web/dist/assets/Settings-DWuxwh4i.js +1 -0
  109. package/web/dist/assets/Tabs-d2RIRAKT.js +1 -0
  110. package/web/dist/assets/{api-D_r0Jtla.js → api-BMFDSXoB.js} +1 -1
  111. package/web/dist/assets/index-BEI5ugYQ.css +1 -0
  112. package/web/dist/assets/index-BNttaGQb.js +6 -0
  113. package/web/dist/index.html +3 -3
  114. package/web/dist/assets/Activity-Ci4PZco3.js +0 -1
  115. package/web/dist/assets/ActivityDetail-C8hroCND.js +0 -1
  116. package/web/dist/assets/Dashboard-C_On4KXw.js +0 -2
  117. package/web/dist/assets/Kits-CXkEBpnf.js +0 -1
  118. package/web/dist/assets/Laws-DhhIVqmh.js +0 -3
  119. package/web/dist/assets/Library-CAUiEoJo.js +0 -3
  120. package/web/dist/assets/Loops-LKD8mF4E.js +0 -2
  121. package/web/dist/assets/Personal-B6Uoly3C.js +0 -2
  122. package/web/dist/assets/Settings-BTe6-wda.js +0 -1
  123. package/web/dist/assets/Tabs-CbdDWTp_.js +0 -1
  124. package/web/dist/assets/index-HfGmYXab.js +0 -3
  125. package/web/dist/assets/index-ao3M-Fhm.css +0 -1
@@ -516,7 +516,7 @@ function storeScan(home, found = {}) {
516
516
  const stamp = (f) => {
517
517
  try { const s = statSync(f); if (s.isFile()) found[f] = `${s.size}:${Math.trunc(s.mtimeMs)}` } catch { /* absent */ }
518
518
  }
519
- for (const n of ["user-rules.md", "PROFILE.md", "geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) stamp(path.join(home, n))
519
+ for (const n of ["user-rules.md", "user-rules.draft.md", "PROFILE.md", "geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) stamp(path.join(home, n))
520
520
  const walk = (dir) => {
521
521
  let items = []
522
522
  try { items = readdirSync(dir, { withFileTypes: true }) } catch { return }
@@ -79,13 +79,19 @@ const VERBS = {
79
79
  load: gates,
80
80
  fn: 'cmdGitGate',
81
81
  flags: HOSTED,
82
- switches: { '--no-consent': 'noConsent', '--no-deletion-gate': 'noDeletionGate' },
82
+ switches: {
83
+ '--no-consent': 'noConsent', '--no-deletion-gate': 'noDeletionGate', '--no-external-gate': 'noExternalGate',
84
+ '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
85
+ },
83
86
  },
84
87
  'rule-gate': {
85
88
  load: gates,
86
89
  fn: 'cmdRuleGate',
87
90
  flags: HOSTED,
88
- switches: { '--no-secrets-gate': 'noSecretsGate', '--no-ownership-gate': 'noOwnershipGate' },
91
+ switches: {
92
+ '--no-secrets-gate': 'noSecretsGate', '--no-ownership-gate': 'noOwnershipGate',
93
+ '--no-external-gate': 'noExternalGate', '--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore',
94
+ },
89
95
  },
90
96
  'tool-gate': {
91
97
  load: gates,
@@ -93,7 +99,8 @@ const VERBS = {
93
99
  flags: HOSTED,
94
100
  switches: {
95
101
  '--no-deletion-gate': 'noDeletionGate', '--no-secrets-gate': 'noSecretsGate',
96
- '--no-ownership-gate': 'noOwnershipGate',
102
+ '--no-ownership-gate': 'noOwnershipGate', '--no-external-gate': 'noExternalGate',
103
+ '--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
97
104
  },
98
105
  },
99
106
  learn: {
@@ -101,7 +108,10 @@ const VERBS = {
101
108
  fn: 'cmdLearn',
102
109
  // `--host` only keys the global stand-down's marker (js/hosts/hosts.mjs); learn has no dialect.
103
110
  flags: { '--memory': 'memory', '--host': 'host' },
104
- switches: { '--consolidate': 'consolidate', '--no-done-gate': 'noDoneGate' },
111
+ switches: {
112
+ '--consolidate': 'consolidate', '--no-done-gate': 'noDoneGate', '--no-test-note': 'noTestNote',
113
+ '--no-rule-store': 'noRuleStore',
114
+ },
105
115
  positional: 'file',
106
116
  },
107
117
  // UserPromptSubmit and SessionEnd: no verb runs there, and the activity view needs both.
@@ -119,7 +129,8 @@ async function baselineStores(verb, args) {
119
129
  const raw = readStdin();
120
130
  if (!raw.includes('session_id')) return;
121
131
  const { writeBaseline } = await import('../js/hosts/store-watch.mjs');
122
- writeBaseline(args.root, JSON.parse(raw).session_id);
132
+ const { session_id: sid, cwd } = JSON.parse(raw);
133
+ writeBaseline(args.root, sid, cwd);
123
134
  } catch { /* see above */ }
124
135
  }
125
136
 
@@ -165,13 +176,16 @@ function die(code, msg) {
165
176
  function parse(spec, argv) {
166
177
  const args = {
167
178
  root: null, host: null, memory: null, consolidate: false, noConsent: false,
168
- noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false, file: null,
179
+ noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false,
180
+ noExternalGate: false, noTestNote: false, noRuleStore: false, noRootScan: false, file: null,
169
181
  };
170
182
  for (let i = 0; i < argv.length; i += 1) {
171
183
  const tok = argv[i];
172
184
  const eq = tok.indexOf('=');
173
185
  const name = tok.startsWith('--') && eq > 0 ? tok.slice(0, eq) : tok;
174
- if ((spec.switches || {})[name]) { args[spec.switches[name]] = true; continue; }
186
+ // Only the bare spelling sets a switch, and only that is emitted. `--no-external-gate=false` must
187
+ // not disarm a gate, and an argv error here would silence the whole verb, so it just does nothing.
188
+ if ((spec.switches || {})[name]) { if (tok === name) args[spec.switches[name]] = true; continue; }
175
189
  if ((spec.flags || {})[name]) {
176
190
  const value = eq > 0 && tok.startsWith('--') ? tok.slice(eq + 1) : argv[++i];
177
191
  if (value === undefined) return { error: `argument ${name}: expected one argument` };
@@ -23,11 +23,11 @@ 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`, `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
- | `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 |
26
+ | `persist-insight` | process | ask: rule-gate (a write to `user-rules.md` or `user-rules.draft.md`; memory is written freely, and the [change report](hooks.md#the-change-report) and the web console show it). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules`: the hook goes on every host (`--no-rule-store`), OpenCode's `permission.edit` keys on the rule files too. The change report still lists rule-file changes | 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
+ | `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). A sub-agent's commit or merge (`agent_id` in the payload) in a linked worktree, on a branch that is not shared, passes: a Foreman worker's own batch ([Foreman mode](foreman-mode.md) has the exact conditions). A git hook or `core.hooksPath` that pushes on commit is not seen. A push, or a command that mixes one in, still asks. 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. A glob sees only the command, never the worktree, so a worker's commit still asks | 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) |
30
- | `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
30
+ | `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`). Togglable: build without the ops pack, or drop this rule alone with `--exclude-rules`: the check goes on every host (`--no-root-scan`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
31
31
 
32
32
  Bob has no "ask" tier (see [ADR 0007](../adr/0007-gates-fail-closed-per-host-ceiling.md)), so a
33
33
  rule the other hosts only ask about either blocks outright on Bob or degrades to a log line.
@@ -35,6 +35,16 @@ Never a silent pass; Bob runs every gate above through one fused command, `tool-
35
35
  on the payload shape rather than on separate matchers. OpenCode enforces through two separate
36
36
  mechanisms: its own permission prompt (`opencode.json`, static globs) and the guard plugin
37
37
  (`tool.execute.before`, pattern matching); a rule can use either or both.
38
+
39
+ `persist-insight` and `external-gate` also read a shell command's parsed forms on every host: a
40
+ redirect, `tee`, `sed -i`, `cp`, `mv`, `rm`, and the PowerShell writers `Add-Content`, `Set-Content`,
41
+ `Out-File`, `Clear-Content`, `Remove-Item`, `Copy-Item`, `Move-Item`, `New-Item`, `Rename-Item` with
42
+ the aliases `ac`, `sc`, `del`, `copy`, `move`, `ni` and `ren`. A parsed write to a store asks on
43
+ Claude Code, OpenClaude and OpenCode 2, is refused on OpenCode 1, and only warns on Bob. **Shell is
44
+ not a boundary:** `bash -c`, `pwsh -c`, an interpreter and a variable stay unread, so the host's own
45
+ command permission is the backstop, and the [change report](hooks.md#the-change-report) tells you
46
+ afterwards.
47
+
38
48
  See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) for why a gate that only
39
49
  one host can run still ships for every host it can.
40
50
 
@@ -47,6 +57,15 @@ and the next write passes. Off per repo with `mode: off`, for one developer with
47
57
  `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`, per install with
48
58
  `--no-ownership-gate` ([Exclusions](exclusions.md)).
49
59
 
60
+ ### Switches on two rows above
61
+
62
+ `--no-external-gate` stops every ask and refusal in the `external-gate` row, on every host, except
63
+ OpenCode's own `permission.edit` keys, which are host configuration and keep asking. It does not
64
+ touch the rule's text: `--exclude-rules rigor.5` does that, and leaves the hook asking.
65
+ `--no-test-note` stops the advisory weakened-test note that *Cure the Cause* carries at edit time
66
+ and at turn end, on every host. That note asks nothing and blocks nothing, so the rule stays
67
+ outside the hook-pinned ids. See [Exclusions](exclusions.md).
68
+
50
69
  | Gate | Claude Code | OpenClaude | OpenCode | Bob |
51
70
  |---|---|---|---|---|
52
71
  | ownership | deny once: rule-gate (`Write`/`Edit`/`NotebookEdit`; sub-agents defer) | same as Claude Code | block once: guard plugin (a child session defers) | block once (exit 2): tool-gate (sub-agent deferral unverified) |
@@ -56,7 +56,17 @@ The finer switch removes a single doctrine rule from an install while keeping th
56
56
  geneseed build --emit claude-global --exclude-rules "process 7"
57
57
  ```
58
58
 
59
- The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded. Picking packs and rules is covered in [Doctrine packs and single rules](../guides/setup-doctrines.md); what the layers are is in [Rules](rules.md).
59
+ The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded.
60
+
61
+ **A hook goes with its rule.** Three doctrine rules are also enforced by a hook with no switch of its own, and excluding the rule, or building without its pack, drops that hook in the same rebuild. Including the rule again re-arms it at the next rebuild.
62
+
63
+ | Rule | What stops | Flag |
64
+ | --- | --- | --- |
65
+ | process 5, *Consent Before Push* | the commit/push ask of `git-gate` and OpenCode's `git commit*`/`git push*` keys. Bob keeps its warning line | `--no-consent` |
66
+ | process 1, *Persist Insight* | the ask (on Bob the block or warning) on a write to `user-rules.md` or `user-rules.draft.md`, by write tool or parsed shell write, the hard-link check included: `rule-gate`, `git-gate`, Bob's `tool-gate`, the OpenCode guard, and OpenCode's `permission.edit` keys on those files | `--no-rule-store` |
67
+ | ops 2, *Commands Must Return* | the root-scan check of `git-gate`, Bob's `tool-gate` and the OpenCode guard | `--no-root-scan` |
68
+
69
+ Every other check of those hooks stays. The [change report](hooks.md#the-change-report) keeps reporting rule-file changes: with process 1 off, a rule write ran with no prompt, so it is never counted as approved. **With process 1 off, that report is the only signal that the agent changed your standing rules.** It detects and prevents nothing, and it can be fooled: the agent can write `memory/.own-writes.json`, the log of Geneseed's own writes, so a change it lists is excused. The OpenCode guard reads the same state from the install's `Active packs:` and `Excluded rules:` lines when it starts, so restart OpenCode after a rebuild. While the machine's hook shim points at an older checkout, that checkout refuses a flag it does not know and the gate verb lets every call through; run `geneseed rebuild-all` first. Rigor 5 is the exception: it has a switch of its own (below). Picking packs and rules is covered in [Doctrine packs and single rules](../guides/setup-doctrines.md); what the layers are is in [Rules](rules.md).
60
70
 
61
71
  ### Per-skill exclusion — skills you never use
62
72
 
@@ -97,7 +107,7 @@ geneseed build --emit claude-global --no-secrets-gate # Sealed Secrets
97
107
  geneseed build --emit claude-global --no-done-gate # Verify Before Asserting
98
108
  ```
99
109
 
100
- The console's Constitution page has a switch on Rule I's and Rule III's rows too (*Enforced by* reads **Gate off** while one is off); the other Rules show *no gate*, because only their text enforces them. The install records `Secrets gate: off` / `Done gate: off` beside `Deletion gate:`, written only when off; rebuilds, upgrades and `geneseed status` carry them like Law IV's.
110
+ The console's Constitution page has a switch on Rule I's and Rule III's rows too (*Enforced by* reads **Gate off** while one is off); Rule VIII has one for the [test note](#external-gate-and-the-test-note--on-or-off), and the other Rules show *no gate*, because only their text enforces them. The install records `Secrets gate: off` / `Done gate: off` beside `Deletion gate:`, written only when off; rebuilds, upgrades and `geneseed status` carry them like Law IV's.
101
111
 
102
112
  What stops, per host:
103
113
  - **`--no-secrets-gate`**: the credential scan of `rule-gate` (Claude Code, OpenClaude) and of `tool-gate` (Bob, which then no longer exits 2 for it), and on OpenCode the guard plugin's *Sealed Secrets* block — both the key/credential file path block and the content scan. *External Gate*, *Persist Insight*, the deletion gate and the root-scan check stay.
@@ -105,6 +115,42 @@ What stops, per host:
105
115
 
106
116
  Limits: OpenCode reads both switches from the install's `AGENT.md` when it starts, so restart it after flipping one. A global install beside a project install: `rule-gate` and Bob's `tool-gate` do not stand down for a project install on any host, and neither does the OpenCode guard, so an armed global install still asks about (or blocks) a credential write inside a project whose own install has the secrets gate off. `learn` does stand down on Claude Code and OpenClaude, so there the project's done gate switch decides. And the older-shim limit above is sharper for the done gate: its flag rides on `learn`, so while the shim points at an older checkout an install with the done gate off **loses learning too**, not only the gate. Run `geneseed rebuild-all` before switching either gate off.
107
117
 
118
+ ### External Gate and the test note — on or off
119
+
120
+ Two more switches. Both are armed by default and written only when off, so an armed install does not change.
121
+
122
+ ```bash
123
+ geneseed build --emit claude-global --no-external-gate # protected checks, gate configuration
124
+ geneseed build --emit claude-global --no-test-note # the weakened-test note
125
+ ```
126
+
127
+ The install records `External gate: off` / `Test note: off` beside the other gate markers. Rebuilds, upgrades and `geneseed status` carry them. Any other value reads as armed. `doctor --probe` is unaffected: it sends a shell command that neither switch judges.
128
+
129
+ **Run `geneseed rebuild-all` before you switch either one off.** The flags are new. While the machine's shared hook shim points at an older checkout, that checkout refuses the flag, and the gate verb then lets every call through: every gate on that verb is silent, not only this one.
130
+
131
+ What stops, per host:
132
+ - **`--no-external-gate`**: the protected-check and gate-configuration asks of `rule-gate` and of the shell path in `git-gate` (Claude Code, OpenClaude), the same blocks in `tool-gate` (Bob, which then no longer exits 2 for them), the OpenCode guard's refusals on its write and shell paths, and the `evaluate` ask over a gate's own file on OpenCode 2. Every other gate keeps running: secrets, real loss, root scans, the rule-store check, the wiki check and commit/push consent. The guard also keeps refusing an NTFS stream path, because that check protects every path gate.
133
+ - **`--no-test-note`**: the "this edit weakens a test" note at edit time (`rule-gate`, Bob's `tool-gate`), the `[done-gate] advisory` line at turn end (`learn`), and the OpenCode context plugin's reminder on both OpenCode versions. The done checks do not change. `--no-done-gate` still silences the turn-end line and the OpenCode reminder by itself, and it leaves the edit-time note on the hook hosts.
134
+
135
+ **What stays on OpenCode.** The `permission.edit` "ask" keys in `opencode.json` are host configuration, so `--no-external-gate` does not remove them. OpenCode keeps asking before an edit tool writes those files, and you remove the keys by hand if you want that gone. The guard no longer refuses them after an "always" answer, and no longer refuses a shell write to them.
136
+
137
+ **What this switch costs.** External Gate is what stops an agent from editing the gates' own wiring. With it off, the agent can write hook settings, the `AGENT.md` gate markers and `.geneseed/done-checks.txt` without an ask, so every other gate holds only while the agent leaves that wiring alone. Switch it off only where you accept that.
138
+
139
+ **The doctrine and the switch are two axes.** `--exclude-rules rigor.5` takes the rule's text out of the carrier. `--no-external-gate` stops the hook. Neither moves the other:
140
+
141
+ | Rule text (`--exclude-rules`) | Hook (`--no-external-gate`) | Result |
142
+ | --- | --- | --- |
143
+ | In | Armed | The agent is told, and the write asks |
144
+ | Excluded | Armed | The agent is not told, and the write still asks |
145
+ | In | Off | The agent is told, and nothing asks |
146
+ | Excluded | Off | Neither |
147
+
148
+ The console's Constitution page shows both on the same doctrine row: the row's own switch is the rule, and the *External gate* line inside the opened row is the hook. The test note's switch sits on Rule VIII's row, which reads *Hook gate* or **Gate off**. Each gate switch rebuilds at once; the rule switch stages with the other doctrine changes.
149
+
150
+ **Where a marker counts.** In a `CLAUDE.md` or `AGENTS.md`, which are your files, every gate marker counts only inside the `<!-- BEGIN GENESEED -->` block. A marker line outside it reads as armed, and a rebuild does not carry it. A generated `AGENT.md` or `rules/geneseed.md` counts whole, and External Gate protects both. Under External Gate, a write tool aimed at a `CLAUDE.md` or `AGENTS.md` is replayed, and the first block is compared before and after. Any difference asks (on Bob it blocks, and the OpenCode guard refuses). So does a call that cannot be replayed, an unreadable file, or a file over 1 MB. An edit wholly outside the block stays silent, so your own notes there are not interrupted. The name is normalized first, so `CLAUDE.md::$DATA` and `CLAUDE.md.` count as `CLAUDE.md`. A shell edit inside the block does not ask, and neither does a shell edit that puts a fake block before the real one, because only the first block is read. That is a limit: the hook has no replay for a shell write.
151
+
152
+ Limits, as for the gates above: OpenCode reads both markers from `AGENT.md` when it starts, so restart it after a rebuild. `rule-gate` and Bob's `tool-gate` do not stand down for a project install on any host, so an armed global install still asks inside a project built with the switch off. Only `git-gate` stands down, on Claude Code and OpenClaude.
153
+
108
154
  ### Ownership gate — on or off
109
155
 
110
156
  The [ownership](ownership.md) first-write gate is not a Rule's gate: it stops the first file write of a session, once, in an application repo whose root `AGENTS.md` has no `## Ownership` section, so the agent proposes the setup first. It is armed by default. Switch it off for one install:
@@ -30,10 +30,25 @@ When the session is unsure, it delegates. The test is still a count, because "su
30
30
 
31
31
  A task worker is one `developer` agent in its own git worktree. It explores, implements and tests in a single context, loading skills as it needs them, so nothing it read is lost in a hand-off. After two repair rounds on its own failing tests it returns with its findings instead of looping.
32
32
 
33
+ A worker can lead a small team inside its own worktree. It can start read-only helpers (`explorer`, `researcher`) at any time. It can also start writing **sub-workers**, each in its own worktree branched from the worker's branch. The worker commits and merges their branches into its own branch, locally, and re-runs the proof after each merge. *Consent Before Push* names this as a batch. The git gate lets a commit or merge through without a prompt only when all of these hold: the host marks the call as a sub-agent's (Claude Code's `agent_id`), the directory is a linked worktree, and its branch is not shared (`main`, `master`, `develop`, `development`, `release/*`, `hotfix/*`, a remote's default, or the branch the main checkout has, in any letter case). The command may hold only adds, read-only git commands and plain commit or merge arguments with one quoted message, after at most one `cd`; anything that can run a second command (`(`, `@`, `$`, `{`, a backtick) asks. A session that only runs in a worktree, as the desktop app's do, still asks. A push still asks everywhere. Bob sends no sub-agent field, so Bob still logs its warning. On OpenCode the static `git commit*` permission still asks, because a permission glob sees only the command, not the worktree. The gate reads the command, not git's own hooks: a `post-commit` hook or a `core.hooksPath` can push on commit, on any branch, as it always could. Nesting stops at two levels below the session: session → worker → sub-worker. A sub-worker starts nothing. A lead holds every member's result before it ends. The blind reviewer is still the session's, never the worker's.
34
+
35
+ | Host | What caps the depth |
36
+ | --- | --- |
37
+ | Claude Code | the install writes `env.CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH = "2"` into its settings file, only when the key is absent (Claude Code allows three levels by default) |
38
+ | OpenCode | the install writes a top-level `"subagent_depth": 2` into `opencode.json`, only when the key is absent |
39
+ | OpenClaude | nothing in the host: its source has no such cap (checked on 0.31). The rule text is the only bound |
40
+ | Bob | nothing documented. The rule text is the only bound |
41
+
42
+ A value you set yourself is kept. The value 2 is read as session → worker → sub-worker; that reading is the design's, not yet observed live on either host.
43
+
33
44
  When a worker returns green with a diff that touches two or more files or changes logic, the session sends a `reviewer` only your request and the diff — never the worker's reasoning — for a blind check. A failing verdict goes back to the same worker.
34
45
 
35
46
  The session keeps a ledger in its notebook (`notebook/foreman-ledger.md`), one line per task: the task, the agent id, the worktree and the state. A correction, a follow-up or a reviewer finding goes back to **the same worker**, which resumes with everything it already knows. A new worker starts only when the old one cannot be resumed, and it receives a note of the ask, the diff so far and what was tried. A worker serves one task and retires once that task is merged or dropped.
36
47
 
48
+ ### Status lines
49
+
50
+ A worker reports one line at start and on each change: `T<n> · <task> · files: <write set> · <state>`. On Claude Code it sends that line to the session with `SendMessage`; OpenClaude can do the same only in its agent-teams mode. OpenCode and Bob have no channel back to the session, so there the worker writes the line to its own file, `notebook/foreman/<task>.status`, which no other agent writes. The session reads all status files with one command, and only at two moments: before it starts a worker near the same files, and when a worker returns. When two write sets overlap, the session decides: one worker waits, or one worker owns the file. It records that decision in the ledger.
51
+
37
52
  > **Why not a crew by default?** Splitting a task by role — one agent reads, the next builds, the next tests — passes each result on as a summary, and the next agent reads the code again. Anthropic's guide [When to fold subagents into your main agent loop](https://claude.com/resources/articles/building-agents-when-to-fold-subagents-into-your-main-agent-loop) found one loop with skills usually beats that, and keeps separate agents for verification, parallel work and context that would overflow. The blind reviewer is that kind of split.
38
53
 
39
54
  ### What a pipeline is
@@ -53,15 +68,15 @@ The crew works in its own git worktree and branch. When worktrees are unavailabl
53
68
 
54
69
  Inside the crew, the developer implements and the tester runs the tests and lint. Failures go back to the developer for at most two repair rounds, then to one fresh developer carrying the tester's findings; if that fails too, the crew stops and reports the failure, leaving the branch for you to inspect.
55
70
 
56
- ### Neither commits nor merges
71
+ ### Nothing lands beyond the worker's branch
57
72
 
58
- When a worker or a crew is done, it hands back its worktree **uncommitted**, with the raw test and lint output and the list of files it changed. Then the session:
73
+ When a crew is done, it hands back its worktree **uncommitted**. A worker hands back its branch: the local commits from its own sub-workers' merges, and any uncommitted work. Each comes with the raw test and lint output and the list of files it changed. Then the session:
59
74
 
60
75
  1. re-runs the tests and lint itself — its log is its own account, not proof;
61
- 2. shows you the diff and the green output;
76
+ 2. shows you the diff from the base it recorded, and the green output;
62
77
  3. commits and merges **only once you accept**.
63
78
 
64
- Commit, push and merge belong to the session alone, under *Consent Before Push* ([Rules](rules.md)). A worker or crew that cannot get to green reports back instead of landing broken work.
79
+ Push, and every merge beyond a worker's own branch, belong to the session alone, under *Consent Before Push* ([Rules](rules.md)). A worker or crew that cannot get to green reports back instead of landing broken work.
65
80
 
66
81
  You can also start a pipeline without foreman mode: ask the agent to "run a pipeline" for a task, and the `pipeline` [skill](skills.md) takes it from there.
67
82
 
@@ -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, 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.
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 check and a shell write to a rule store 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
 
@@ -18,7 +18,7 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
18
18
  | --- | --- | --- | --- | --- |
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
- | `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 |
21
+ | `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your standing rules; stops the session's first write once in an application repo with no `## Ownership` section | no |
22
22
  | `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into the memory store | needs `GENESEED_LLM` |
23
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` |
@@ -54,25 +54,25 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
54
54
 
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
- - **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.
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. It belongs to the **ops** pack: build without it, or exclude that rule, and the hook is wired with `--no-root-scan` and this check stands down (also on Bob and in the OpenCode guard); every other check stays ([Exclusions](exclusions.md)).
58
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.
59
59
  - Any other command passes untouched.
60
60
 
61
61
  **rule-gate.** Runs before every file write.
62
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)).
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.
63
+ - A write to `user-rules.md` or `user-rules.draft.md` gets a prompt citing *Persist Insight*: a standing rule is your call, settled through the `rule` [skill](skills.md). Memory is not gated: the agent writes `MEMORY.md` and the facts in a memory store on its own, and you see them afterwards in the web console (a shell write to one also shows in the [change report](#the-change-report)). A hard link has no target to follow, so a write to a second name of a known rule file gets the same prompt: the gate compares the file's device and inode with the `user-rules.md` and `user-rules.draft.md` of the install, the shared tier, the project at the session's git root and the homes `$GENESEED_HARNESS` and `$GENESEED_MEMORY` name. Any other hard-linked file, a pnpm store's for example, is ordinary work. On Bob it is blocked. This check belongs to the **process** pack: build without it, or exclude *Persist Insight*, and `rule-gate` and `git-gate` are wired with `--no-rule-store`, so a rule-file write is ordinary work on every host ([Exclusions](exclusions.md)). The change report still lists it.
64
+ - A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). An install built `--no-external-gate` drops this prompt and the two below it, and the agent can then rewrite the wiring of every other gate ([Exclusions](exclusions.md)). 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`, `rm` and the PowerShell writers (`Add-Content`, `Set-Content`, `Out-File`, `Clear-Content`, `Remove-Item`, `Copy-Item`, `Move-Item`, `New-Item`, `Rename-Item`, and their common aliases) 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, `pwsh -c`, scripts, `npm run`, variables other than the home, globs, subshell tricks, a folder removed above a listed file. So run the same checks in CI as the boundary that holds.
65
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.
66
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:
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
+ - 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` and Bob global's `rules/geneseed.md` (their `… gate: off` markers), `.geneseed-manifest.json` and `.geneseed-emit`; and `excludes.json` in the machine-wide `~/.config/geneseed/` folder, the shared exclude list.
68
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`.
69
69
  - The machine-wide hook shim in `~/.geneseed/bin/` (or `$GENESEED_HOME/bin/`).
70
70
  - On OpenCode, also the install's `opencode.json(c)` and its own `plugins/geneseed-*.js`.
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
+ - **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` and `user-rules.draft.md` by name, 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.
72
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.
73
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
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.
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. An install built `--no-test-note` gets no note, here or at turn end ([Exclusions](exclusions.md)). 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.
76
76
  - Ordinary edits pass untouched.
77
77
 
78
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)).
@@ -85,6 +85,45 @@ export GENESEED_LLM="claude -p"
85
85
 
86
86
  Unset, `learn` does nothing useful: on a real Stop/SubagentStop/PreCompact call it returns immediately rather than reading the transcript for nothing, and on a manual run it prints the prompt it would have sent. Geneseed never stores or embeds an API key. See [Memory](memory.md).
87
87
 
88
+ ## What a prompt says
89
+
90
+ When a gate stops a call, Geneseed writes the reason. An agent cannot change this fixed text. Each prompt is plain English, one sentence per line, and it puts the decision first:
91
+
92
+ ```text
93
+ This edit changes .github/workflows/ci.yml (+3 lines, -1 line), which defines the checks that run on every push.
94
+ Safe choice: Deny, unless you asked for this change. (External Gate)
95
+ It asks because the agent's own work is judged by this file.
96
+ If you allow it, those checks can get weaker or stop running, and a failure could go unseen.
97
+ Agent: if refused, do not write this file another way.
98
+ ```
99
+
100
+ The first line says what changes and what the file is, with the path from the repository root. The second gives the safe choice and names the rule. The last line is for the agent. A commit or a push is routine, so it gets one line.
101
+
102
+ On *Deletion Is Deliberate*, *Commands Must Return* and *Consent Before Push*, the prompt can also quote the `description` that the agent gave the command: `The agent says (not checked): "..."`. It never quotes the agent on *Sealed Secrets*, *External Gate* or *Persist Insight*, because there the agent's opinion is the conflict of interest.
103
+
104
+ If a loss command uses `--git-dir` or `--work-tree`, the prompt adds a line: the command runs on another repository, which the gate did not read.
105
+
106
+ Each host carries this text differently:
107
+
108
+ | Host | What you get |
109
+ | --- | --- |
110
+ | Claude Code, OpenClaude | The reason in the permission prompt |
111
+ | OpenCode | A note just before the dialog, for its two asks only ([guard](../reference/plugin-guard.md)). A refusal goes to the model |
112
+ | Bob | No prompt. A block tells the model to relay the text to you. A warning says the call ran without a prompt |
113
+
114
+ Know these limits:
115
+
116
+ - The text says what a file is and what is at risk. On a write or an edit, it cannot say why the agent wants the change.
117
+ - Claude's own title and prefix stay. Geneseed controls only the reason.
118
+ - The desktop card shows about 3 lines. Past those, you must scroll.
119
+ - OpenCode's note sits beside the dialog, not in it, and exists only for its two asks: a rule write that reaches a host prompt, and a gate configuration file.
120
+ - OpenCode 1's note is a toast, which can expire while the dialog is open.
121
+ - An unattended OpenCode 2 session posts the note, then denies the call.
122
+ - On Bob and on an OpenCode refusal, you depend on the model to relay the text. This is best effort. The change report below is the direct channel.
123
+ - The line count overstates a change with several regions. Shell writes show no count, and neither does a `replace_all`, a search-and-replace, a diff, a notebook cell, a text or an old file past 1 MB, or anything on OpenCode.
124
+ - A loss prompt names the kind of loss, not the files.
125
+ - The text is in English only.
126
+
88
127
  ## Verify
89
128
 
90
129
  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.
@@ -93,13 +132,15 @@ What happens when a gate cannot decide, where the hooks are written, and the one
93
132
 
94
133
  ## The change report
95
134
 
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.**
135
+ 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`, `user-rules.draft.md`, `PROFILE.md`, the wiki manifest, `memory/**/*.md`, and the project's own `user-rules.md` and `user-rules.draft.md` at the session's git root), 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
136
 
98
137
  | Host | Baseline | Approved means | You see |
99
138
  | --- | --- | --- | --- |
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) |
139
+ | Claude Code, OpenClaude | `<install>/notebook/store-baseline/`, at SessionStart | the transcript shows a Write, Edit or NotebookEdit ran; with *Persist Insight* excluded (`learn --no-rule-store`) a rule file never counts, because no prompt ran | a `systemMessage` at Stop |
140
+ | Bob | same | nothing: there is no transcript, so any change is reported, a memory write the agent made freely included | a stderr line at Stop, in Bob's hook log |
141
+ | OpenCode | in the guard plugin's memory | `tool.execute.after` on OpenCode's own edit tools; with *Persist Insight* excluded a rule file never counts | a toast (1.x), a synthetic message (2.x) |
142
+
143
+ With *Persist Insight* excluded nothing asks before a rule write, so this report is then the only signal that your standing rules changed, and the `.own-writes.json` limit below applies to it in full.
103
144
 
104
145
  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
146
 
@@ -18,9 +18,10 @@ 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 | 🔒 ask³ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
21
+ | Standing-rule 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
+ | Subagent depth capped at two ([Foreman mode](foreman-mode.md)) | ✅ `subagent_depth` | ✅ `env` setting | ➖ undocumented | ➖ no cap in the host |
24
25
  | MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
25
26
  | Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
26
27
 
@@ -28,13 +29,13 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
28
29
 
29
30
  ¹ **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
31
  ² **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 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
+ ³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so a standing-rule 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
33
  ⁴ 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
34
  ⁵ 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
35
 
35
36
  ## The one conditional row
36
37
 
37
- The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. Everything else in the table is always on.
38
+ The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. The standing-rule row is conditional the same way: it enforces *Persist Insight*, also in the process pack, and excluding it (or the pack) drops that hook on every host ([Exclusions](exclusions.md)). Everything else in the table is always on.
38
39
 
39
40
  One OpenCode asymmetry: Geneseed shares `opencode.json` with you and cannot tell its own `git commit*` permission entry from one you typed, so a rebuild without the process pack leaves an existing entry in place and says so instead of deleting it. A `permission.skill` deny is different: Geneseed records each one it writes, and a rebuild or uninstall takes back only those, never a deny you set yourself.
40
41
 
@@ -18,7 +18,7 @@ Each host has a **global** install (in its config directory, active in every rep
18
18
 
19
19
  ## Two engines
20
20
 
21
- - **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
21
+ - **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. The install also caps subagent nesting at two levels there (`subagent_depth`), as it does on Claude Code (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`); OpenClaude and Bob have no such cap ([Foreman mode](foreman-mode.md)). It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
22
22
  - **Claude Code**, **Bob** and **OpenClaude** share one Claude-shaped engine: Geneseed wires **hooks** into the host's `settings.json`, each calling `geneseed-hook <verb>`. See [Hooks](hooks.md).
23
23
 
24
24
  ## Where to go next
@@ -37,11 +37,29 @@ The second kit is `react`, for React 18 or 19 apps built with Vite or webpack, i
37
37
 
38
38
  It is adapted from [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT), rewritten and condensed for Vite and Jest; the webpack side file is first-party. It has no Server Components material: a client-rendered app has no server render.
39
39
 
40
+ The third kit is `ci-pipelines`, for CI pipelines on Jenkins and GitLab CI. It adds two skills and no agent:
41
+
42
+ | Member | Kind | What it is for |
43
+ |---|---|---|
44
+ | `jenkins-pipeline` | skill | Declarative `Jenkinsfile`, shared-library layout (`vars/`, `src/`, `resources/`), CPS and `@NonCPS`, sandbox and script approval, credentials binding, `parallel` and `when`, tests with JenkinsPipelineUnit |
45
+ | `gitlab-ci` | skill | `.gitlab-ci.yml`: `rules:`, the `needs:` DAG, `include:` and `extends:`, caching and artifacts, protected and masked variables, environments, CI lint |
46
+
47
+ Its rules keep the pipeline in one source of truth, take secrets only from the CI's own store, pin images and tool versions, and run fast feedback first. Its `banned` list refuses GitLab's older job-condition keywords, which GitLab no longer actively develops, in its files. It is first-party.
48
+
49
+ The fourth kit is `docker`, for Docker and Compose operations on any stack. It adds one skill:
50
+
51
+ | Member | Kind | What it is for |
52
+ |---|---|---|
53
+ | `compose-ops` | skill | Health-ordered startup (`depends_on` with `condition: service_healthy`), named volumes against bind mounts, pinned tags or digests, `.env` and secrets, restart policies, resource limits, logging, networks, minimal non-root multi-stage images, and safe updates: pull, recreate, roll back |
54
+
55
+ It does not overlap the spring-boot kit's `docker-expert` agent: that agent builds a Spring Boot service's own image (Buildpacks, layered or native) and its local-dev Compose file, and `compose-ops` operates any Compose stack. Either kit works without the other. `compose-ops` is adapted in part from the `docker-patterns` skill of [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT), rewritten for operations; its skill folder ships `LICENSE-everything-claude-code.txt`.
56
+
40
57
  ### Switching kits on and off
41
58
 
42
59
  ```bash
43
60
  geneseed build --emit claude-global --kits spring-boot
44
61
  geneseed build --emit claude-global --kits react,spring-boot
62
+ geneseed build --emit claude-global --kits ci-pipelines,docker
45
63
  geneseed build --emit claude-global --kits none
46
64
  ```
47
65
 
@@ -38,7 +38,7 @@ The same folder already held the install registry, your own loop bricks and temp
38
38
 
39
39
  When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
40
40
 
41
- A global install's text names these locations as absolute paths. A project install keeps its relative paths and its own `memory/`. Geneseed grants no directory permission for the tier, so an agent write there follows your host's permission mode, as a write to the host's own folder does. A write to the shared rules, draft or memory passes the same [rule gate](hooks.md) as a local one.
41
+ A global install's text names these locations as absolute paths. A project install keeps its relative paths and its own `memory/`. Geneseed grants no directory permission for the tier, so an agent write there follows your host's permission mode, as a write to the host's own folder does. A write to the shared rules or draft passes the same [rule gate](hooks.md) as a local one; the shared memory, like a local one, is written freely.
42
42
 
43
43
  ### How it is created
44
44
 
@@ -42,7 +42,7 @@ The full list, with each description, is in the catalog.
42
42
 
43
43
  ### Skills improve themselves
44
44
 
45
- Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with your assent, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and `doctor` would report it as drift. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> — seen: <what happened, against what was expected> (<date>)`: `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Most runs end with nothing to change.
45
+ Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with no prompt, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and `doctor` would report it as drift. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what was expected> (<date>)`: `situation:` says where the correction holds (it is optional, and older lines without it stay valid; without it, the circumstance in `seen:` stands in), `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Folding a skill or agent note is your call: the `skill-forge` skill first replays one past task whose original ask still exists, as two dispatched agents from the pre-fix revision, one told to read no notes and one given the note. The `fresh-eyes` skill freezes one rubric from the ask and judges both results blind against it. A note is folded only when it wins, on the result or on a stated process gain; on a tie or a loss you decide whether to keep or delete it. A trivial wording fix skips that probe. Most runs end with nothing to change.
46
46
 
47
47
  ### Old names keep working
48
48
 
package/docs/extending.md CHANGED
@@ -706,7 +706,9 @@ Two gates hold it: `tests/unit/hook_form.test.mjs` pins the rule (including the
706
706
  reachable because `ephemeralCheckout` takes the temp root as a parameter), and
707
707
  `tests/shim_intact.mjs` — a step in `ci.yml` and `publish.yml`, *after* `node --test`, because
708
708
  each test file runs in its own process and the file that causes this is not the file that would
709
- notice — fails if the suite left the shim naming anything that is not there.
709
+ notice — fails if the suite left the shim naming anything that is not there. The same step fails
710
+ if a test touched the machine tier: a change report naming test fixtures or the temp root, or, behind
711
+ CI's `.suite-fence`, any file in the tier.
710
712
 
711
713
  This is not hypothetical — it happened while this file was being written. Several agents were
712
714
  verifying gates out of copied checkouts (the `copyCheckout` fixture pattern