geneseed 5.3.1 β†’ 5.5.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 (248) hide show
  1. package/CHANGELOG.md +102 -0
  2. package/README.md +51 -18
  3. package/SHIPPED.md +7 -7
  4. package/adapters/bob/README.md +12 -1
  5. package/adapters/opencode/README.md +5 -3
  6. package/adapters/opencode/plugins/geneseed-context.js +77 -10
  7. package/adapters/opencode/plugins/geneseed-guard.js +106 -22
  8. package/adapters/opencode/plugins/geneseed-learn.js +641 -6
  9. package/bin/geneseed-cli.mjs +10 -0
  10. package/bin/geneseed-hook.mjs +5 -4
  11. package/docs/PRD.md +1 -1
  12. package/docs/README.md +1 -0
  13. package/docs/concepts/agents.md +14 -2
  14. package/docs/concepts/collaboration.md +2 -2
  15. package/docs/concepts/enforcement-table.md +5 -2
  16. package/docs/concepts/exclusions.md +16 -2
  17. package/docs/concepts/footprint.md +1 -1
  18. package/docs/concepts/foreman-mode.md +23 -4
  19. package/docs/concepts/hook-gates.md +4 -4
  20. package/docs/concepts/hooks.md +25 -7
  21. package/docs/concepts/host-matrix.md +4 -4
  22. package/docs/concepts/hosts.md +1 -1
  23. package/docs/concepts/kits.md +12 -2
  24. package/docs/concepts/loop-bricks.md +3 -3
  25. package/docs/concepts/loops.md +6 -4
  26. package/docs/concepts/ownership.md +1 -1
  27. package/docs/concepts/rules.md +2 -2
  28. package/docs/concepts/shared-tier.md +1 -1
  29. package/docs/concepts/skills.md +21 -1
  30. package/docs/concepts/themes.md +1 -1
  31. package/docs/extending.md +73 -29
  32. package/docs/guides/auto-merge.md +100 -0
  33. package/docs/guides/choose-your-setup.md +1 -1
  34. package/docs/guides/headless.md +1 -1
  35. package/docs/guides/install-clone.md +19 -1
  36. package/docs/guides/install-scripted.md +8 -2
  37. package/docs/guides/install.md +20 -2
  38. package/docs/guides/loop-finish.md +3 -3
  39. package/docs/guides/loop-running.md +4 -4
  40. package/docs/guides/project-context.md +1 -1
  41. package/docs/guides/run-a-factory.md +2 -2
  42. package/docs/guides/setup-doctrines.md +2 -2
  43. package/docs/guides/setup-footprint.md +1 -1
  44. package/docs/guides/uninstall.md +3 -3
  45. package/docs/guides/upgrade.md +2 -2
  46. package/docs/guides/worktree.md +1 -1
  47. package/docs/reference/env-context.md +1 -1
  48. package/docs/reference/environment.md +4 -2
  49. package/docs/reference/plugin-activity.md +1 -1
  50. package/docs/reference/plugin-guard.md +1 -1
  51. package/docs/reference/plugin-learn.md +5 -1
  52. package/docs/reference/plugin-workflow.md +1 -1
  53. package/docs/reference/profiles.md +142 -0
  54. package/docs/reference/troubleshoot-doctor.md +1 -1
  55. package/docs/reference/troubleshoot-hooks.md +2 -2
  56. package/docs/reference/troubleshoot-install.md +3 -3
  57. package/docs/reference/troubleshoot-tools.md +1 -1
  58. package/docs/token-footprint.md +11 -6
  59. package/docs/understand/design-choices-engineering.md +1 -1
  60. package/docs/understand/enforced-vs-asked.md +1 -1
  61. package/docs/understand/machine-claude.md +2 -2
  62. package/docs/understand/on-your-machine.md +1 -1
  63. package/docs/web-ui.md +8 -6
  64. package/harness.config.json +1 -1
  65. package/js/README.md +11 -3
  66. package/js/build/args.mjs +16 -4
  67. package/js/build/catalog.mjs +11 -1
  68. package/js/build/driver.mjs +74 -16
  69. package/js/build/emit-claude.mjs +32 -5
  70. package/js/build/emit-opencode.mjs +16 -9
  71. package/js/build/export.mjs +1 -1
  72. package/js/build/generate.mjs +12 -157
  73. package/js/build/notes-migrate.mjs +99 -0
  74. package/js/build/profile.mjs +326 -0
  75. package/js/build/render.mjs +110 -8
  76. package/js/build/retired-skills.mjs +60 -13
  77. package/js/build/source.mjs +100 -3
  78. package/js/build/stubs.mjs +4 -1
  79. package/js/cli-table.json +212 -7
  80. package/js/hosts/agent-runs.mjs +205 -0
  81. package/js/hosts/done-checks.mjs +3 -1
  82. package/js/hosts/hooks-done.mjs +428 -63
  83. package/js/hosts/hooks-learn.mjs +89 -3
  84. package/js/hosts/hooks-prims.mjs +44 -4
  85. package/js/hosts/hooks.mjs +159 -9
  86. package/js/hosts/hosts.mjs +10 -0
  87. package/js/hosts/installs.mjs +44 -2
  88. package/js/hosts/link.mjs +45 -10
  89. package/js/hosts/native.mjs +61 -7
  90. package/js/hosts/opencode.mjs +1 -1
  91. package/js/hosts/settings.mjs +101 -3
  92. package/js/hosts/spec-feedback.mjs +538 -0
  93. package/js/hosts/usage.mjs +67 -8
  94. package/js/inspect/agent-scores.mjs +118 -0
  95. package/js/inspect/checks-authoring.mjs +2 -1
  96. package/js/inspect/checks-build.mjs +20 -4
  97. package/js/inspect/checks-constitution.mjs +32 -0
  98. package/js/inspect/checks-repo.mjs +27 -2
  99. package/js/inspect/cost.mjs +6 -5
  100. package/js/inspect/diff.mjs +46 -8
  101. package/js/inspect/doctor.mjs +4 -0
  102. package/js/inspect/inventory.mjs +1 -1
  103. package/js/inspect/status.mjs +3 -1
  104. package/js/inspect/validate.mjs +1 -0
  105. package/js/lib/machine-dir.mjs +8 -0
  106. package/js/lib/paths.mjs +4 -1
  107. package/js/maintain/profile-scope.mjs +145 -0
  108. package/js/maintain/profiles.mjs +486 -0
  109. package/js/maintain/setup.mjs +413 -15
  110. package/js/maintain/uninstall.mjs +4 -1
  111. package/js/maintain/update.mjs +4 -2
  112. package/js/web/actions.mjs +44 -41
  113. package/js/web/api.mjs +13 -3
  114. package/js/web/handler.mjs +8 -0
  115. package/js/web/jobs.mjs +5 -4
  116. package/js/web/profiles-api.mjs +201 -0
  117. package/js/web/routes.mjs +5 -0
  118. package/package.json +2 -1
  119. package/profiles/guillaume-claude-global.json +16 -0
  120. package/profiles/starter.json +14 -0
  121. package/registry.json +14 -0
  122. package/src/AGENT.md.tmpl +16 -18
  123. package/src/agents/_self-improvement.md +15 -7
  124. package/src/agents/_template.md +4 -2
  125. package/src/agents/advocate.md +1 -1
  126. package/src/agents/architect.md +1 -1
  127. package/src/agents/developer.md +10 -3
  128. package/src/agents/devops-engineer.md +1 -1
  129. package/src/agents/docker-expert.md +1 -1
  130. package/src/agents/docs.md +1 -1
  131. package/src/agents/empiricist.md +1 -1
  132. package/src/agents/explorer.md +4 -2
  133. package/src/agents/framer.md +1 -1
  134. package/src/agents/historian.md +1 -1
  135. package/src/agents/kubernetes-specialist.md +1 -1
  136. package/src/agents/memory-curator.md +1 -1
  137. package/src/agents/operator.md +1 -1
  138. package/src/agents/performance.md +1 -1
  139. package/src/agents/pragmatist.md +1 -1
  140. package/src/agents/react-engineer.md +1 -1
  141. package/src/agents/react-reviewer.md +1 -1
  142. package/src/agents/researcher.md +1 -1
  143. package/src/agents/reviewer.md +10 -3
  144. package/src/agents/security.md +1 -1
  145. package/src/agents/skeptic.md +1 -1
  146. package/src/agents/spring-boot-engineer.md +1 -1
  147. package/src/agents/spring-reviewer.md +1 -1
  148. package/src/agents/spring-security.md +1 -1
  149. package/src/agents/steward.md +1 -1
  150. package/src/agents/tester.md +4 -2
  151. package/src/agents/user-advocate.md +1 -1
  152. package/src/agents/visionary.md +1 -1
  153. package/src/bricks/pr-open.md +3 -2
  154. package/src/doctrines/ops.md +2 -2
  155. package/src/doctrines/process.md +40 -36
  156. package/src/factories/analysis-to-build.json +1 -1
  157. package/src/factories/bug-report-to-fix.json +1 -1
  158. package/src/factories/issue-to-pr.json +1 -1
  159. package/src/kits/terminal-tools/rules.md +10 -0
  160. package/src/kits/terminal-tools.json +13 -0
  161. package/src/licenses/herdr.txt +201 -0
  162. package/src/memory/README.md +12 -2
  163. package/src/modes/foreman.md +25 -9
  164. package/src/skill-descriptions.json +63 -0
  165. package/src/skills/_self-improvement.md +42 -24
  166. package/src/skills/_template.md +3 -1
  167. package/src/skills/brainstorm.md +35 -22
  168. package/src/skills/commit.md +17 -17
  169. package/src/skills/daydream/VENDOR.md +6 -0
  170. package/src/skills/debug/ci.md +1 -1
  171. package/src/skills/dependencies.md +3 -3
  172. package/src/skills/diagram-design/VENDOR.md +4 -0
  173. package/src/skills/document-project.md +3 -2
  174. package/src/skills/explain-changes/VENDOR.md +5 -1
  175. package/src/skills/factory.md +13 -4
  176. package/src/skills/geneseed.md +4 -2
  177. package/src/skills/git-history.md +5 -7
  178. package/src/skills/herdr.md +135 -0
  179. package/src/skills/loop.md +3 -2
  180. package/src/skills/opencode-cli.md +84 -0
  181. package/src/skills/parallel-agents.md +11 -0
  182. package/src/skills/pipeline.md +3 -3
  183. package/src/skills/plan.md +5 -4
  184. package/src/skills/react-view-transitions/VENDOR.md +7 -1
  185. package/src/skills/release.md +11 -9
  186. package/src/skills/review-response.md +4 -2
  187. package/src/skills/rule/approve.md +2 -1
  188. package/src/skills/rule.md +27 -1
  189. package/src/skills/ship.md +54 -7
  190. package/src/skills/skill-forge.md +5 -3
  191. package/src/skills/token-report/VENDOR.md +5 -1
  192. package/src/skills/worktree.md +2 -2
  193. package/src/upstreams.json +9 -2
  194. package/themes/README.md +3 -1
  195. package/themes/_TEMPLATE.json +2 -0
  196. package/themes/biker.json +2 -0
  197. package/themes/commentator.json +2 -0
  198. package/themes/cyberpunk.json +2 -0
  199. package/themes/gamer.json +2 -0
  200. package/themes/imperial.json +2 -0
  201. package/themes/joker.json +2 -0
  202. package/themes/marvin.json +2 -0
  203. package/themes/mean.json +2 -0
  204. package/themes/military.json +2 -0
  205. package/themes/neutral.json +2 -0
  206. package/themes/pirate.json +2 -0
  207. package/themes/sports.json +2 -0
  208. package/themes/verstappen.json +2 -0
  209. package/themes/wizard.json +2 -0
  210. package/web/dist/assets/{ActiveLoops-BJJN3P-V.js β†’ ActiveLoops-DOJCPPPc.js} +1 -1
  211. package/web/dist/assets/Activity-LKsDzsnK.js +1 -0
  212. package/web/dist/assets/ActivityDetail-DhwTfPm6.js +1 -0
  213. package/web/dist/assets/{Bonsai-BBl4XXqs.js β†’ Bonsai-CePMLrpr.js} +1 -1
  214. package/web/dist/assets/{CopyButton-Beven8yn.js β†’ CopyButton-CuoaJ6k7.js} +1 -1
  215. package/web/dist/assets/Dashboard-D1VKuvLe.js +2 -0
  216. package/web/dist/assets/Docs-CUrHJKaU.js +5 -0
  217. package/web/dist/assets/Factories-Ci1XfmSy.js +1 -0
  218. package/web/dist/assets/{GreenhouseView-Bce212qd.js β†’ GreenhouseView-CNfH2lPK.js} +1 -1
  219. package/web/dist/assets/Installs-ZHQZM1iS.js +3 -0
  220. package/web/dist/assets/{JournalView-CV4omyww.js β†’ JournalView-CMsWahkS.js} +1 -1
  221. package/web/dist/assets/Kits-CkliyK0n.js +1 -0
  222. package/web/dist/assets/Laws-hh4O3HZ4.js +4 -0
  223. package/web/dist/assets/{LibRows-Dag1s0ZX.js β†’ LibRows-Brv0Hmkr.js} +1 -1
  224. package/web/dist/assets/Library-BYmiLjJr.js +3 -0
  225. package/web/dist/assets/Loops-ytm-xJ68.js +2 -0
  226. package/web/dist/assets/{OperatorHudView-JmYY1pBR.js β†’ OperatorHudView-KaqCx_HP.js} +1 -1
  227. package/web/dist/assets/Personal-CmcnRKYE.js +2 -0
  228. package/web/dist/assets/Settings-tUrpdOfq.js +1 -0
  229. package/web/dist/assets/{Tabs-8zsyEPSK.js β†’ Tabs-CD7etcGD.js} +1 -1
  230. package/web/dist/assets/api-CZ-x0iWG.js +1 -0
  231. package/web/dist/assets/{controls-D4wmg_pl.js β†’ controls-CK7qHA8H.js} +1 -1
  232. package/web/dist/assets/{index-CRWqKxfY.css β†’ index-Ba_Kg3Af.css} +1 -1
  233. package/web/dist/assets/index-COKbhFNo.js +6 -0
  234. package/web/dist/index.html +3 -3
  235. package/web/dist/assets/Activity-WQ3ykgxU.js +0 -1
  236. package/web/dist/assets/ActivityDetail-7rt04SkS.js +0 -1
  237. package/web/dist/assets/Dashboard-BgLArtgu.js +0 -2
  238. package/web/dist/assets/Docs-B5aHp86J.js +0 -5
  239. package/web/dist/assets/Factories-BjqzXAw8.js +0 -1
  240. package/web/dist/assets/Installs-B1OsrHXF.js +0 -3
  241. package/web/dist/assets/Kits-CW1e7xNa.js +0 -1
  242. package/web/dist/assets/Laws-1Ckf1lbs.js +0 -4
  243. package/web/dist/assets/Library-B3FuFLel.js +0 -3
  244. package/web/dist/assets/Loops-CwqgnLNw.js +0 -2
  245. package/web/dist/assets/Personal-DKLgLa7Z.js +0 -2
  246. package/web/dist/assets/Settings-BwErnh-R.js +0 -1
  247. package/web/dist/assets/api-DLDVY3K-.js +0 -1
  248. package/web/dist/assets/index-Ce6qF2nG.js +0 -6
@@ -150,6 +150,9 @@ const VERBS = {
150
150
  // (upstream Python, pinned in the module's docblock). There is no recorded cell β€” its absolute gate is
151
151
  // tests/unit/scorecard.test.mjs. Lazy like every row: the 31 checks load only when asked.
152
152
  scorecard: () => import('../js/inspect/scorecard.mjs').then((m) => m.cmdScorecard),
153
+ // Native: writes an install profile from a global install (`setup --profile` installs one).
154
+ // Its absolute gate is tests/unit/profiles.test.mjs.
155
+ profile: () => import('../js/maintain/profiles.mjs').then((m) => m.cmdProfile),
153
156
  };
154
157
 
155
158
  /** Levenshtein distance, for the one "did you mean" an unknown verb gets. */
@@ -387,6 +390,13 @@ async function main(argv) {
387
390
  // A hook verb (`context`, `tool-gate`, …) is in the table but not here: the emitted
388
391
  // settings call it through `geneseed-hook`, and saying so beats "unknown command".
389
392
  if (cliCommand(verb) !== null) {
393
+ // Its help is a fair question, and `help context` arrives here as `context --help`: answer
394
+ // it with the hook binary's own help, under a line naming the binary that runs it.
395
+ if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
396
+ printOut(`'${verb}' is a hook verb: the host runs it as \`geneseed-hook ${verb}\` `
397
+ + '(bin/geneseed-hook.mjs), not through this command.\n\n');
398
+ return printHelp('geneseed-hook', verb);
399
+ }
390
400
  return die(2, `'${verb}' is a hook verb: the host runs it through geneseed-hook `
391
401
  + '(bin/geneseed-hook.mjs), not this command. See geneseed --help.');
392
402
  }
@@ -82,7 +82,7 @@ const VERBS = {
82
82
  flags: HOSTED,
83
83
  switches: {
84
84
  '--no-consent': 'noConsent', '--no-deletion-gate': 'noDeletionGate', '--no-external-gate': 'noExternalGate',
85
- '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
85
+ '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan', '--strict-consent': 'strictConsent',
86
86
  },
87
87
  },
88
88
  'rule-gate': {
@@ -103,7 +103,7 @@ const VERBS = {
103
103
  '--no-ownership-gate': 'noOwnershipGate', '--no-external-gate': 'noExternalGate',
104
104
  '--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
105
105
  // Bob's commit/push warning, when process 5 is off: `gitDecide` reads it as on git-gate.
106
- '--no-consent': 'noConsent',
106
+ '--no-consent': 'noConsent', '--strict-consent': 'strictConsent',
107
107
  },
108
108
  },
109
109
  learn: {
@@ -238,7 +238,7 @@ function hostNamed(argv) {
238
238
  */
239
239
  function parse(spec, argv) {
240
240
  const args = {
241
- root: null, host: null, event: null, memory: null, consolidate: false, noConsent: false,
241
+ root: null, host: null, event: null, memory: null, consolidate: false, noConsent: false, strictConsent: false,
242
242
  noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false,
243
243
  noExternalGate: false, noTestNote: false, noRuleStore: false, noRootScan: false, file: null,
244
244
  };
@@ -348,7 +348,8 @@ async function main(argv) {
348
348
  }
349
349
  let rc;
350
350
  try {
351
- rc = (await spec.load())[spec.fn](parsed.args);
351
+ // Awaited: `activity` is async (its slash counter imports on demand); the rest return a number.
352
+ rc = await (await spec.load())[spec.fn](parsed.args);
352
353
  } catch (e) {
353
354
  return verbFailed(verb, parsed.args, e);
354
355
  }
package/docs/PRD.md CHANGED
@@ -104,7 +104,7 @@ sequenceDiagram
104
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
105
  | NFR-003 | Context hook output stays under the host's cap. | 9 000 characters | `OUTPUT_BUDGET` | βœ… | `js/hosts/hooks-context.mjs` |
106
106
  | NFR-004 | The rules file stays within its size ceiling. | 40 312 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` |
107
+ | NFR-005 | The generator and hook path cannot spawn beyond what is declared. | No `child_process` on the generator; two spawn sites on the hook path (`learn`'s model CLI, `loss.mjs`'s one `git` read) | Closure walks | βœ… | `tests/unit/hook_cli.test.mjs` |
108
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
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
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` |
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
  | Factories | [Run a factory](guides/run-a-factory.md) | Carrying one bug report or issue to an open PR with green CI |
33
+ | Factories | [Auto-merge green PRs](guides/auto-merge.md) | Letting the forge merge a PR the agent opens once its required checks pass |
33
34
  | Keep it running | [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
34
35
  | 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 |
35
36
  | Keep it running | [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
@@ -36,11 +36,23 @@ Ten read-only debaters β€” `advocate`, `skeptic`, `pragmatist`, `steward`, `oper
36
36
 
37
37
  An agent is picked by **what the work needs**, not by **where the file lives**. There is no "agent for `src/api/`": a change to any folder goes to the `developer`, and its review to the `reviewer`. You can name one ("have the reviewer look at this"), or let the main session route the request to the right specialist itself.
38
38
 
39
- In [foreman mode](foreman-mode.md) the session chains several of them into a pipeline β€” explorer, developer and tester, plus whatever specialists the task needs.
39
+ In [foreman mode](foreman-mode.md) the session hands each task that would block it to one background `developer` worker. A pipeline crew β€” explorer, developer and tester, plus whatever specialists the task needs β€” runs only when you ask for one.
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 `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.)
43
+ When a subagent finishes, the hook copies each `spec-feedback:` line its report ends with into a notes file, with no model call. The line picks its scope with one question: is it true in any repo, or only here? A flaw of the spec is true in any repo: `[agent]` goes into the machine notes, `agent-notes/<name>.md` under `~/.config/geneseed/notes/` (a `[general]` line into `agent-notes/_general.md` there, which every agent reads). A fact true only in this repo is tagged `[agent:project]` and goes into `notebook/agent-notes/<name>.md` at the project root, one folder for every host (in a linked worktree, the main checkout's); a `[general:project]` line goes into `notebook/agent-notes/_general.md`, which every agent reads in that repo. The agent reads the machine notes and then the project notes first at its next dispatch; where they disagree, the project notes win. So a flaw it reported is in front of it until the user folds the fix into the source. See [Hooks](hooks.md). (Not on Bob, which has no subagent-finished event: there the caller copies the line into the machine or the project file.)
44
+
45
+ ### Did a spec change help?
46
+
47
+ When a named subagent finishes, the same hook appends one line to `notebook/agent-runs.jsonl` in the install, beside `usage.jsonl`. The line holds only facts the hook can read: the day, the agent, a short hash of its rendered spec (`agents/<name>.md`, or none for an agent Geneseed does not ship), whether the done gate let the turn end and how many times it blocked it first, the number of tool calls and of refused calls (a call a host or a gate did not run; a red test is not one), the number of `spec-feedback:` lines, and whether a report came back. There is no self-score and no model call. A stop that the done gate blocks writes no line: the line comes at the stop that ends the turn.
48
+
49
+ `geneseed catalog agents --scores` prints one row per agent and spec hash, so the runs before a spec edit and the runs after it are two rows to compare. The UNBLOCKED column is `never blocked / judged`, over the runs the gate judged. It is not a pass rate: the gate cannot tell a pass from an advisory, and a stop past the gate's block limit also ends the turn. REFUSED and TOOLS are means, with the number of runs behind each in brackets; below 3 runs they show `-`.
50
+
51
+ The hash is of the rendered file, so anything that renders the spec differently starts a new row, even with no change to the agent's source: a theme switch, the first seeding of the shared tier, a Geneseed upgrade that changes the renderer, or an agent override. A spec you edited by hand in the install is no longer the file Geneseed shipped, so its runs read `spec: null`.
52
+
53
+ The counts are per turn, as the done gate reads one. A message sent to a running subagent (SendMessage) opens a new turn, so the line written at that turn's end counts only the tools used after the message. On OpenCode the line is written at a child session's first quiet period in each OpenCode process, and it counts the whole child session on OpenCode 1. The same switch as `usage.jsonl` turns the ledger off: `GENESEED_NO_USAGE`, or a `.usage-off` file in the install. On OpenCode the learn plugin writes the line for a named child session, with no done-gate fields, because that host's gate is in another plugin. Bob has no subagent-finished event, so it writes no line.
54
+
55
+ The learn step can also 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
56
 
45
57
  <!--harness:opencode-->
46
58
  *(OpenCode only)*
@@ -22,7 +22,7 @@ A **posture** is the register the agent works in. You choose it at setup and it
22
22
  | **assistant** | precise execution, low initiative β€” you steer |
23
23
  | **artisan** | a peer with toolsmith reflexes β€” terminal-first, automates repetition |
24
24
 
25
- Posture is separate from the [theme](themes.md): the theme is the *voice*, the posture is the *relationship*. Every posture obeys the same rules; what shifts is how firmly and how loudly the agent voices disagreement. Change it with `geneseed setup`, the web console's Harness page, or:
25
+ Posture is separate from the [theme](themes.md): the theme is the *voice*, the posture is the *relationship*. Every posture obeys the same rules; what shifts is how firmly and how loudly the agent voices disagreement. Change it with `geneseed setup`, the install's panel on the web console's Installs page, or:
26
26
 
27
27
  ```bash
28
28
  geneseed build --emit claude-global --posture mentor
@@ -38,7 +38,7 @@ The **Pact** is stated in the first section of the Ethos, the layer that is alwa
38
38
  2. serve your intent;
39
39
  3. keep its own honesty.
40
40
 
41
- Unusually, it also says what *you* owe back:
41
+ Unusually, the Pact also has a side that *you* owe back. The install's text only points to it; the README states it:
42
42
 
43
43
  - **Don't punish candour.** When the agent contradicts you with evidence, flags a risk or admits a doubt, that is the Pact working. Penalising it teaches the agent to flatter.
44
44
  - **Give the context up front.** The agent cannot weigh what it was not told.
@@ -24,9 +24,9 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
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
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 |
27
+ | `consent-before-push` | process | ask: git-gate, on a commit or push onto the main branch (`main`, `master`, a remote's default branch, or the branch the main checkout holds when the command runs in a linked worktree). Off the main branch, a session's commit, local merge and plain push of the checked-out branch (`git push [-u] <remote> <branch>`, or `HEAD:<branch>`) pass. A bare `git push`, a push of another branch, a forced push, a tag push, or any form the gate cannot read still asks, and so does everything in a repository with no remote or whose remote has no default branch recorded (`git remote set-head origin --auto`). A sub-agent's push always asks. With `--strict-consent` (the *Strict consent* switch on the console's Constitution page), every commit and push asks again, as before 2026-11. 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
- | `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 (a frozen fork, and no check runs a model turn: [What is verified](host-matrix.md#what-is-verified)) | 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) |
29
+ | `verify-before-asserting` | law | block at Stop, again only after a new edit or a changed background verdict, at most 3 times per continuation and 10 per turn: the done gate in `learn`, at SubagentStop too for a sub-agent's own turn (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit; a check matches as a prefix of the command once both drop `npm --prefix`/`git -C` naming the judged project's own root and `--test-concurrency N`). 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 (a frozen fork, and no check runs a model turn: [What is verified](host-matrix.md#what-is-verified)); that its SubagentStop sends `agent_transcript_path` is unverified, and without it a sub-agent's turn is not judged | 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
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
@@ -45,6 +45,9 @@ not a boundary:** `bash -c`, `pwsh -c`, an interpreter and a variable stay unrea
45
45
  command permission is the backstop, and the [change report](hooks.md#the-change-report) tells you
46
46
  afterwards.
47
47
 
48
+ No host gates a forge merge (`gh pr merge`, `glab mr merge`, an MCP merge tool): the
49
+ [auto-merge guide](../guides/auto-merge.md) says what guards it instead.
50
+
48
51
  See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) for why a gate that only
49
52
  one host can run still ships for every host it can.
50
53
 
@@ -58,11 +58,13 @@ geneseed build --emit claude-global --exclude-rules "process 7"
58
58
 
59
59
  The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. If a later version retires the rule, the rebuild prints a WARN, drops that address, and goes on. The WARN says what the exclusion no longer does: comms 5 (*Mark the Ask*) merged into comms 1 on 2026-11-08, so excluding `comms 5` no longer removes the ask markers, which now bind inside comms 1. If a new rule later takes a retired rule's address, an old exclusion of that address removes the new rule; the build then prints a loud WARN that names both rules, and the exclusion still applies until you remove it. The always-on Rules and the Ethos cannot be excluded.
60
60
 
61
+ **Its citations go with it.** The instructions file stops citing an excluded rule: a parenthetical such as `(*Consent Before Push*)` after a sentence is removed, and in a list of citations only that name goes. A mention in running prose ("Where *Search Before Creating* refuses …") stays, because it describes a relation and binds nothing. The rule files on disk keep every citation, because they are the complete text. `geneseed doctor` refuses a parenthetical in the instructions-file sources that mixes a doctrine citation with other words, because the render could not remove it cleanly.
62
+
61
63
  **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
64
 
63
65
  | Rule | What stops | Flag |
64
66
  | --- | --- | --- |
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` |
67
+ | process 5, *Consent Before Push* | the main-branch commit/push ask of `git-gate` (every commit and push under `--strict-consent`) and OpenCode's `git commit*`/`git push*` keys. Bob keeps its warning line | `--no-consent` |
66
68
  | 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
69
  | ops 2, *Commands Must Return* | the root-scan check of `git-gate`, Bob's `tool-gate` and the OpenCode guard | `--no-root-scan` |
68
70
 
@@ -111,10 +113,22 @@ The console's Constitution page has a switch on Rule I's and Rule III's rows too
111
113
 
112
114
  What stops, per host:
113
115
  - **`--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.
114
- - **`--no-done-gate`**: the done check `learn` runs on Stop, listed or inferred (Claude Code, OpenClaude; on Bob, the "turn not judged" log line), and on OpenCode the context plugin's reminder (OpenCode 1), its one-line notice (OpenCode 2), and on every host the `Done gate:` line at session start. Learning itself still runs, and `.geneseed/done-checks.txt` stays protected by *External Gate*.
116
+ - **`--no-done-gate`**: the done check `learn` runs on Stop and SubagentStop, listed or inferred (Claude Code, OpenClaude; on Bob, the "turn not judged" log line), and on OpenCode the context plugin's reminder (OpenCode 1), its one-line notice (OpenCode 2), and on every host the `Done gate:` line at session start. Learning itself still runs, and `.geneseed/done-checks.txt` stays protected by *External Gate*.
115
117
 
116
118
  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.
117
119
 
120
+ ### Strict consent β€” every commit and push asks
121
+
122
+ By default *Consent Before Push* asks only for a commit or push onto the main branch: your own branch takes commits, local merges and plain pushes without a prompt. Strict consent brings back the ask on every commit and push.
123
+
124
+ ```bash
125
+ geneseed build --emit claude-global --strict-consent
126
+ ```
127
+
128
+ The console's Constitution page has the same switch on the rule's row (*Strict consent*). The install records `Own-branch pass: off` beside the other gate markers, the carrier adds one sentence under the rule, and rebuilds, upgrades and `geneseed status` carry it. The switch adds asks, so its flag does not read `--no-*`; the marker still follows the gate-switch contract: written only when the pass is off.
129
+
130
+ What changes, per host: `git-gate` on Claude Code and OpenClaude asks for every commit and push again (the `loop/*` and Foreman worker passes stay), and Bob's `tool-gate` prints its warning line for each. OpenCode is unchanged: its `git commit*`/`git push*` keys already ask for every one. With process 5 excluded, the switch does nothing, because no consent check runs.
131
+
118
132
  ### External Gate and the test note β€” on or off
119
133
 
120
134
  Two more switches. Both are armed by default and written only when off, so an armed install does not change.
@@ -59,6 +59,6 @@ Footprint is stored in a `.geneseed-footprint` marker in the install and kept ac
59
59
  geneseed build --emit claude-global --footprint full
60
60
  ```
61
61
 
62
- On the command line, a flag you leave out takes the generator's default, not the install's current value. `geneseed status --json` shows what an install currently has.
62
+ On the command line, a flag you leave out takes the generator's default, not the install's current value. A build that would change a setting of an existing install that you did not pass refuses: it lists each change and prints the command that keeps them. `geneseed status --json` shows that command for every install. Add `--reset` only to accept the defaults.
63
63
 
64
64
  The walkthrough for all build-time choices is [Choose your setup](../guides/choose-your-setup.md).
@@ -26,6 +26,14 @@ The session sorts every request:
26
26
 
27
27
  When the session is unsure, it delegates. The test is still a count, because "substantial" left to judgement lost every time to the host's own default of doing small work in place. The count asks what would block the session, not how big the task looks.
28
28
 
29
+ ### No dispatch tool, no foreman
30
+
31
+ Foreman needs a tool that can start a writing (`developer`) worker: `Agent` on Claude Code and OpenClaude, `subagent` (V1: `task`) on OpenCode, `spawn_subagent` on Bob. When the session holds no such tool, it works as in direct mode: it does each task itself, one at a time, in one tree, and tells you so once.
32
+
33
+ The check is on the tool the session holds, not on the host, because the same install can run with and without that tool. Bob IDE and Bob Shell (the terminal CLI) read the same `~/.bob` install, so a build cannot tell them apart. Bob IDE 2.2.3 gives `spawn_subagent` only when the `session.subagents` setting is on (the default) and only to a mode whose groups hold `subagent`: the built-in `agent` and `plan` modes can start every subagent. The `ask` mode holds `spawn_subagent` too, but it may start only `explore`, so it cannot start a worker and Foreman runs as direct there. Bob Shell has no subagents, no worktrees and no parallel dispatch; this is reported by Bob Shell itself, not read in code, because IBM does not publish Bob Shell on npm.
34
+
35
+ Bob's `start_subtask` (the `subtask` group, held by the `agent` mode) does not count as a Foreman dispatch tool: it appears to make the parent wait until the subtask ends, which blocks the session. That is inferred from the bundle, not observed live.
36
+
29
37
  ### The task worker
30
38
 
31
39
  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.
@@ -37,13 +45,24 @@ A worker can lead a small team inside its own worktree. It can start read-only h
37
45
  | 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
46
  | OpenCode | the install writes a top-level `"subagent_depth": 2` into `opencode.json`, only when the key is absent |
39
47
  | 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 |
48
+ | Bob | Bob itself: a subagent cannot spawn another (`spawn_subagent` is forbidden to subagents, read in Bob IDE 2.2.3), so one level only, session β†’ worker, and no sub-workers. A Bob worker does the work itself. Bob Shell has no subagents at all (reported by Bob Shell itself, not read in code) |
41
49
 
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.
50
+ A value you set yourself is kept. On Claude Code and OpenCode, the value 2 is read as session β†’ worker β†’ sub-worker; that reading is the design's, not yet observed live on either host.
43
51
 
44
52
  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.
45
53
 
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.
54
+ 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. Each host resumes a worker its own way:
55
+
56
+ | Host | How the session resumes a worker |
57
+ | --- | --- |
58
+ | Claude Code | `SendMessage` with the worker's id or name |
59
+ | OpenCode | the `subagent` tool with the worker's `sessionID` (V1: the `task` tool with `task_id`); the TUI shows `↳` on such a call. The same call without `sessionID` (V1: `task_id`) starts a fresh worker |
60
+ | OpenClaude | `SendMessage`, only in its agent-teams mode (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` or `--agent-teams`); otherwise no resume |
61
+ | Bob | no resume: each `spawn_subagent` call starts a fresh subagent |
62
+
63
+ 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.
64
+
65
+ A new task gets a new worker by default. The session may give it to an idle worker whose own task is already merged or dropped, when the new task works in the same files or context and that worker has used little of its context. The worker then starts the new task on a new branch from the current BASE. It gets the full brief that any new worker gets (BASE, write set, proof commands, the Brief checklist), and the session checks its write set against every task in flight. Whether a context is light or heavy is a judgement call, not a number: the session writes its reason (same files, context used) in the new task's ledger line. A worker never holds two live tasks at once. A worker whose context is heavy, or whose last task touched other code, retires.
47
66
 
48
67
  ### Status lines
49
68
 
@@ -76,7 +95,7 @@ A worker or crew commits only in its own worktree, never pushes, and never merge
76
95
  2. shows you the diff from the base it recorded, and the green output;
77
96
  3. commits and merges **only once you accept**.
78
97
 
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.
98
+ Push, and every merge beyond a worker's own branch, belong to the session alone, under *Consent Before Push*: the session pushes the worker's branch and lands it on the main branch through a pull request with green checks ([Rules](rules.md)). A worker or crew that cannot get to green reports back instead of landing broken work.
80
99
 
81
100
  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.
82
101
 
@@ -10,13 +10,13 @@ How Geneseed's [hooks](hooks.md) behave when something goes wrong, where they ar
10
10
 
11
11
  ## Gates fail closed, and leave a trace
12
12
 
13
- If a gate cannot evaluate a call β€” an unreadable payload, a bug β€” it asks, with the error as its reason, rather than silently letting the call through. Every prompt a gate raises adds one line to `notebook/gates.jsonl` in the install: the rule and the time, never the command or content. `geneseed status` counts them by rule.
13
+ If a gate cannot evaluate a call β€” an unreadable payload, a bug β€” it asks, with the error as its reason, rather than silently letting the call through. Every prompt a gate raises adds one line to `notebook/gates.jsonl` in the install: the time, the verb, the rule and the working directory, never the command or content. `geneseed status` counts them by rule.
14
14
 
15
15
  ```bash
16
16
  geneseed status
17
17
  ```
18
18
 
19
- In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context`, `git-gate` and `learn` hooks stand down when the session's project folder (the one the session started in, not a parent of it) has its own live per-repo install of the same host that wires the same hook, so nothing is injected, asked or learned twice. A per-repo install that is deactivated, or whose hooks were never wired, does not count: the global hook keeps running. `GENESEED_STACK_GLOBAL=1` keeps both.
19
+ In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context`, `git-gate` and `learn` hooks stand down when the session's project folder (the one the session started in, not a parent of it) has its own live per-repo install of the same host that wires the same hook, so nothing is injected, asked or learned twice. The usage count of `tool-gate` and `activity` stands down in the same case, so a call is counted once ([What the usage count records](hooks.md#what-the-usage-count-records)); those two hooks still do the rest of their work. A per-repo install that is deactivated, or whose hooks were never wired, does not count: the global hook keeps running. `GENESEED_STACK_GLOBAL=1` keeps both.
20
20
 
21
21
  ## Where they are written
22
22
 
@@ -34,10 +34,10 @@ The merge is surgical. Every other key and every hook of your own survive, and t
34
34
 
35
35
  **OpenClaude** is a Claude Code fork: it gets the same hooks and the same prompts, unchanged.
36
36
 
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:
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 `SubagentStop`. Bob does document a regex matcher on the tool name, but Geneseed wires none: Bob's tool list and regex dialect are unverified, and a wrong matcher would silence the gate. 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) exactly the rules whose Bob cell says *block* in [Rule enforcement, by host](enforcement-table.md). 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.
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. (On Claude Code and OpenClaude the same verb only counts skill and subagent calls: see [Hooks](hooks.md).) It **blocks** (exit 2) exactly the rules whose Bob cell says *block* in [Rule enforcement, by host](enforcement-table.md). 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`. Bob's `Stop` carries no transcript, so nothing is learned there; the [change report](hooks.md#the-change-report) still runs.
42
42
  - `UserPromptSubmit` β†’ `geneseed-hook activity`, which records the turn for the Activity view.
43
43
 
@@ -17,15 +17,29 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
17
17
  | Event | When | Command | What it does | Conditional? |
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
- | `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 |
20
+ | `PreToolUse` | `Bash`, `PowerShell`, `Monitor` | `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 standing rules; 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 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` |
22
+ | `PreToolUse` | `Skill`, `Agent`, `Task` | `geneseed-hook tool-gate` | records the skill or subagent call in the usage count; judges nothing and never blocks | no |
23
+ | `Stop` | the agent finishes a reply | `geneseed-hook learn` | copies the reply's `spec-feedback: [skill:<name>]` lines into `skill-notes/<name>.md` (no model); distils durable facts into the memory store | the copy needs nothing; the distil needs `GENESEED_LLM` |
24
+ | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | copies the `spec-feedback:` lines of its report into `agent-notes/<name>.md` (no model); appends one outcome line to `notebook/agent-runs.jsonl` (see [Agents](agents.md#did-a-spec-change-help)); records a lesson for that agent in the store's `agents/<name>.md` | the copy and the outcome line need nothing (the line is off with `GENESEED_NO_USAGE` or `.usage-off`); the lesson needs `GENESEED_LLM` |
24
25
  | `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
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
+ | `UserPromptSubmit` | you send a message | `geneseed-hook activity` | records the turn's start for the web console's Activity view; when the message is `/<name>` and `<name>` is an installed skill, records it in the usage count as `via: "slash"`; prints nothing | the Activity record is off with `GENESEED_ACTIVITY=off`; the count is off with `GENESEED_NO_USAGE` or `.usage-off` |
26
27
  | `SessionEnd` | the session closes | `geneseed-hook activity` | marks the session ended and archives it | off with `GENESEED_ACTIVITY=off` |
27
28
  | `SubagentStart` | a subagent starts | `geneseed-hook context` | injects your `user-rules.md` layers into the subagent (as JSON `additionalContext`, under the same 9 000-character budget), and records the subagent as a branch of its session | the Activity record only, with `GENESEED_ACTIVITY=off` |
28
29
 
30
+ ### What the usage count records
31
+
32
+ The web console's "What fires" chart reads `notebook/usage.jsonl` in every install it finds, and adds the counts together. Each line holds the day, `skill` or `agent`, and the name. A line for a typed skill also holds `"via":"slash"`. A line never holds the prompt or the arguments.
33
+
34
+ - **A skill call and a subagent call.** The `Skill|Agent|Task` hook records one line per call.
35
+ - **A skill that you type as `/<name>`.** A typed skill makes no `Skill` tool call, so the `UserPromptSubmit` hook records it, with `"via":"slash"`. It counts only when `<name>/SKILL.md` exists in the install's `skills/` folder, in the global config folder's `skills/` (`~/.claude/skills/`), or in the project's own `.claude/skills/`. A built-in command such as `/clear` or `/model` is not counted. A plugin skill typed as `/<plugin>:<skill>` is not counted either, because its folder is in the host's plugin cache.
36
+ - **A session in an excluded folder.** It is not counted. In a folder that `geneseed exclude` lists, every hook of that install stays quiet, the counter included. So a repo that was excluded for a time shows fewer calls than its transcripts hold.
37
+ - **A global install beside a project install of the same host.** When the session's project folder holds a live, wired project install, both hooks run. Only the project install counts the call, and the global one stands down, so the console does not count the call twice. `GENESEED_STACK_GLOBAL` makes both count.
38
+
39
+ On OpenCode the guard plugin counts the same calls. A project install writes to `<repo>/notebook/usage.jsonl`. OpenCode loads the global plugins and every project `.opencode/plugins/` from the session's folder up to its worktree. Only one copy counts a call: the copy of the nearest project that can count (it has a `notebook/` and no `.usage-off`). If no project can count, the global copy counts. A `/<name>` command counts on OpenCode 1 (`command.execute.before`), but not on OpenCode 2, which gives the plugin the expanded command text and no name.
40
+
41
+ On Bob two parts are not verified on a live Bob session. The typed-skill count reads the payload's `prompt` field as on Claude Code. The global install finds the project folder from the payload's `cwd`, because Bob sets no project variable. If Bob's `cwd` follows a `cd` into another repo that has a Bob project install, which Bob never loaded, the global install stands down and that call is not counted.
42
+
29
43
  Every hook above also feeds the [Activity view](../reference/plugin-activity.md) after it has decided, unless tracking is off: one file per session under `activity/` beside the install. The gates' verdicts never wait on it.
30
44
 
31
45
  What that file holds for the Activity garden:
@@ -53,7 +67,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
53
67
  - removing files (`rm`, `rmdir`, `del`, `erase`, `Remove-Item`) that git cannot restore: untracked, ignored or modified files, a repository's `.git`, or anything outside a repository.
54
68
 
55
69
  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
- - **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)).
70
+ - **A `git commit` or `git push` onto the main branch** gets a prompt citing *Consent Before Push*: the main branch changes only through a pull request with green checks. The main branch is `main`, `master`, a remote's default branch, or, in a linked worktree, the branch the main checkout holds. On any other branch, a commit, a local merge and a plain push of the checked-out branch (`git push -u origin feature`, `git push origin HEAD:feature`) pass. A bare `git push` (where `push.default` and your git config decide the target), a push of a branch other than the checked-out one, a forced push, a tag push, a sub-agent's push, or a command the gate cannot read still asks. A quoted message is data: `git commit -m "fix(hooks): x"` passes, and so does a bash `git commit -F - <<'EOF'` heredoc whose delimiter is quoted; a `$(` or a backtick inside double quotes still asks. In a repository with no remote, or with a remote whose default branch is not recorded (`git remote add` records none; `git remote set-head origin --auto` does), the gate cannot tell your branch from the default one, so every commit and push asks. Build with `--strict-consent` (or turn on *Strict consent* on the console's Constitution page) and every commit and push asks again. 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
71
  - **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
72
  - **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
73
  - Any other command passes untouched.
@@ -75,7 +89,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
75
89
  - 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
90
  - Ordinary edits pass untouched.
77
91
 
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)).
92
+ **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 --test-reporter=tap "tests/**/*.test.mjs"`. A listed line matches as a prefix of the command: `node --test` listed would accept `node --test tests/one.test.mjs`, one file of the suite, so list each command whole. Before the match, the gate removes three things from both the line and the command, and nothing else: `--prefix <dir>` (or `--prefix=<dir>`) on `npm`, and `-C <dir>` right after `git`, when `<dir>` is the judged project's own root (the worktree whose files were edited); and `--test-concurrency N` on `node --test`. So a worker's `npm --prefix <its worktree> run lint` proves `npm run lint`, and a suite run at the default concurrency proves a line that names `--test-concurrency=8`. A `--prefix` that names another project, a sibling worktree, the main checkout or a subfolder still reads as not run (that run never saw this tree's edits). A changed glob or reporter still does not match. The gate does not follow `cd`: it reads the command line only. 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. A check that runs in the background (Claude Code's `run_in_background`, or a command moved there after its foreground timeout) counts only when its task notification says it completed with exit code 0; the launch alone says only that it started. The gate never runs a check itself. It reads the transcript from its end, back only to the last prompt a person typed: a background task's notification opens no turn, so a turn spans every continuation the notifications drive. Its cost grows with that turn, not with the session; in a long run kept going by notifications it may read back to the start of the file. A sub-agent's turn is judged too, when it stops (SubagentStop): the gate reads the sub-agent's own transcript and judges each project it wrote files in by that project's git root and list, so a worker in its own worktree owes its worktree's checks, not its parent's. A block there keeps the sub-agent working, with the owed checks as its next instruction. An inferred check there is only a stderr line and a ledger entry, since nobody sees a sub-agent's warning. It blocks again only when the agent edited a file since the last block, or when a check's background run changed its verdict (still running, then failed), and at most 3 times per continuation: a stop with neither, or a fourth stop, ends the turn and leaves a `done-gate-cap` line in the gate ledger. A task notification starts a new continuation with a fresh count, so early blocks do not spend the cap for the rest of an unattended run. Over the whole turn, until the next prompt a person types, it blocks at most 10 times: a suite relaunched in the background after each failure would otherwise loop, one full run per cycle. Past that ceiling the turn ends, and the stderr line says the total ceiling was reached. The block names the checks whose background run is still running or reported a failure. The count is kept per session (and per sub-agent) in the install's `notebook/done-gate/`; without an install, the second stop ends the turn. 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)).
79
93
 
80
94
  **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:
81
95
 
@@ -83,7 +97,11 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
83
97
  export GENESEED_LLM="claude -p"
84
98
  ```
85
99
 
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).
100
+ Unset, `learn` distils nothing: on a real Stop/SubagentStop/PreCompact call it returns before it reads the transcript for a distil, 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).
101
+
102
+ One part of `learn` needs no model. On SubagentStop it reads the subagent's final report (its last message, or the message of its hand-back call) and copies each `spec-feedback:` line into the notes that agent reads at its next dispatch. Each line names its scope. A machine line (`[agent]`, `[general]`, a skill's `[skill:<name>]` or `[skill:<name>:general]`) goes to the tier's `notes/`, for every host and install kind: `agent-notes/<name>.md`, or `agent-notes/_general.md` for a `general` line, which every agent reads. The tier's folder exists on any machine an emit has run on (the install registry lives there); only `notes/<sub>/` is made under it, and with no such folder a machine line is dropped. A project line (`[agent:project]`, `[skill:<name>:project]`) goes to `<project>/notebook/`: the install's parent for a project install, the git root of the session's project for a global one, a linked worktree's main checkout either way. A global session outside any repo has no project, so its project line is dropped, never sent to the machine notes. A `[general:project]` line goes to that folder's `agent-notes/_general.md`, which every agent reads in this repo. Geneseed writes no ignore file into the project: the notes folders and the migration's archives are named in the clone's own `.git/info/exclude`, once, in a marked block, so they never reach a commit, even in a repo whose `notebook/` is tracked. Outside a git repo nothing extra is written. Each note is one bullet that names its writer and its date, `- [agent] <fix> (<agent>, <date>)`, appended under a short file lock so parallel subagents do not lose each other's lines; a line already there is not added again, and the template placeholder, a quoted (`>`) or fenced line and a line holding a credential are skipped. The line is kept at every stop, one the done gate blocks included: the report that draws the block carries it, and the one that passes need not repeat it. Every dispatch reads these files, so they are capped: an agent's file at 100 bullets, `_general.md` at 30, each file at 8 000 characters. Past a cap the oldest bullets the hook wrote drop, told apart by the writer's name beside the date; a line written by hand is never moved or dropped, a dated one included. The OpenCode learn plugin does the same for a child session that names its agent. Bob has no subagent-finished event, so there the caller copies the line.
103
+
104
+ Skills close the same loop. A skill runs in the main conversation, so no SubagentStop sees it: on Stop, `learn` reads the reply that ends the turn (the host's `last_assistant_message`, and the transcript's final message only when that copy mentions `spec-feedback`) and copies each `spec-feedback: [skill:<name>]` line into `skill-notes/<name>.md`, a `[skill:<name>:general]` line into `skill-notes/_general.md`, which every skill reads (both machine notes), or a `[skill:<name>:project]` line into the project's `notebook/skill-notes/<name>.md` (a `[skill:<name>:general:project]` line into its `_general.md`). The same lines in a subagent's report go there too, on SubagentStop. The tag must name the skill: the main reply often relays a subagent's `[agent]` or `[general]` line, and those are not copied on Stop. A line counts only for a skill the install serves under that name: `<install>/skills/<name>/SKILL.md` names its own notes file (the render writes each skill's id into it), so an invented name, an alias folder an older build left, or a skill rendered before this writes no file. A tag that does not parse (`[skill:a:b]`, `[skill:a, b]`) drops the line, and a line in inline code or a fence is an example the reply quotes, not a note. The bullets, caps, lock and duplicate rule are the agents' (`- [skill] … (<skill>, <date>)`); the `- [skill] … (<date>)` lines written by hand before the hook are never dropped. A Stop the done gate blocks copies its reply's lines too, since the reply that finally ends the turn does not repeat them. An excluded folder copies nothing, as it learns nothing. Bob's Stop payload carries neither a transcript nor the reply, so there the skill text tells the model to append the line itself.
87
105
 
88
106
  ## What a prompt says
89
107
 
@@ -22,8 +22,8 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
22
22
  | Standing-rule write needs your call | πŸ”’ askΒ³ | πŸͺ ask | πŸͺ blockΒΉ | πŸͺ askΒ² |
23
23
  | User-only skills hidden from the model | πŸ”’ `permission.skill` deny | βœ… `disable-model-invocation` | βœ… `/`-command, no skill | βœ… `disable-model-invocation` |
24
24
  | Sovereign-repo exclusions⁡ | βš™οΈ plugins stand down | βœ… `claudeMdExcludes` | βœ… rules shadow stub | βœ… `claudeMdExcludes` |
25
- | Subagent depth capped at two ([Foreman mode](foreman-mode.md)) | βœ… `subagent_depth` | βœ… `env` setting | βž– undocumented | βž– no cap in the host |
26
- | MCP server wiring | βœ… `mcp` | βœ… `mcpServers` | βœ… `mcp.json` | βœ… `mcpServers` |
25
+ | Subagent depth capped at two ([Foreman mode](foreman-mode.md)) | βœ… `subagent_depth` | βœ… `env` setting | βœ… one level, set by Bob itself: a subagent cannot spawn another | βž– no cap in the host |
26
+ | MCP servers (Geneseed reads and lists them, never writes them) | βœ… `mcp` | βœ… `mcpServers` | βœ… `mcp.json` | βœ… `mcpServers` |
27
27
  | Colour themes Β· LSP Β· workflow runner Β· primary agent Β· `/`-commands | βœ… | βž– | βž– | βž– |
28
28
 
29
29
  βœ… native Β· βš™οΈ OpenCode plugin Β· πŸ”’ `permission` entry in `opencode.json` Β· πŸͺ `settings.json` hook Β· βž– no host mechanism (the rule still applies as prose).
@@ -43,7 +43,7 @@ This is the one place that says what was checked against each host itself, how,
43
43
  | Claude Code | canary: `tests/host_canary.mjs` installs the host from npm and starts it in a throwaway home | weekly in CI, at npm `latest` | `claude doctor` lists no invalid setting in the emitted `settings.json`; a logged-out `-p` run shows `SessionStart` running the context hook | hooks that need a model turn: the `PreToolUse` gates, `Stop` |
44
44
  | OpenClaude | canary, the same run | weekly in CI, at npm `latest` | the emitted settings load; `SessionStart` runs the context hook. Its `doctor` checks only the auto-updater, so there is no settings verdict to read | hooks that need a model turn |
45
45
  | OpenClaude | source read | 2026-09 | the config directory, the root files it loads, the settings and hook types (`src/utils/envUtils.ts`, `claudemd.ts`, `config.ts`, `src/types/hooks.ts`) | |
46
- | Bob | bundle read: Bob 2.2.3's shipped `bob-code/dist/extension.js` | 2026-10 | the hook payload (Claude's keys plus `cwd`), the event list, the strict settings schema, the agent frontmatter reader | whether Bob lists agents to the model; a sub-agent depth cap |
46
+ | Bob | bundle read: Bob 2.2.3's shipped `bob-code/dist/extension.js` | 2026-10 | the hook payload (Claude's keys plus `cwd`), the event list, the strict settings schema, the agent frontmatter reader; the sub-agent depth (one level: `SUBAGENT_FORBIDDEN_TOOLS` denies subagents `spawn_subagent` and `start_subtask`) | whether Bob lists agents to the model |
47
47
  | Bob | live session, Bob IDE | 2026-10-23 | a `tool-gate` refusal (exit 2) stopped the call and its reason reached the model; Bob ignores Claude's `disallowedTools`, which is why a read-only agent carries `groups:`; the first-reply override | the `Stop` hook; the ownership gate's sub-agent deferral |
48
48
  | Bob | live session | 2026-10-25 | a prompt wrote an Activity snapshot from `UserPromptSubmit` | |
49
49
  | Bob | canary | never | nothing: IBM does not publish Bob Shell on npm, so the canary reports Bob as `skip` | everything above is a one-time read, not a standing check. [Verify it works](../guides/verify.md) has the by-hand steps |
@@ -54,7 +54,7 @@ No check on any host calls a model. `geneseed doctor --probe` covers the other h
54
54
 
55
55
  ## The one conditional row
56
56
 
57
- 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.
57
+ 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)). By default it asks only for a commit or push onto the main branch; `--strict-consent` makes it ask for every one. OpenCode always asks for every commit and push: its permission globs cannot read which branch is checked out. 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.
58
58
 
59
59
  One OpenCode asymmetry: Geneseed shares `opencode.json` with you, so it removes only what it recorded writing. The manifest lists the `permission.bash` gates it added (`bash_gates`), and a rebuild without the process pack, or with `--no-deletion-gate`, takes back those that still read as it wrote them. An entry that was already there, one you changed, and every gate on an install made before 5.2.0 (which has no record) stays and is named in a warning; `--prune-gates` on one build removes the last kind. A `permission.skill` deny works the same way. Uninstall takes back both: every recorded deny and every recorded `permission.bash` gate that still reads as Geneseed wrote it. A gate you changed, and one with no record, stays.
60
60
 
@@ -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`. 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.
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 has no such cap, and Bob needs none, because a Bob subagent cannot start another ([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
@@ -54,18 +54,28 @@ The fourth kit is `docker`, for Docker and Compose operations on any stack. It a
54
54
 
55
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
56
 
57
+ The fifth kit is `terminal-tools`, for terminal programs the agent drives through their own CLI. It adds two skills:
58
+
59
+ | Member | Kind | What it is for |
60
+ |---|---|---|
61
+ | `herdr` | skill | Herdr workspaces, tabs, panes and agents, from inside a Herdr pane (`HERDR_ENV=1`) and only when the user names Herdr: split a sibling pane, start and prompt another agent, wait on state, read output. It carries the Windows notes of herdr's own docs page (signed binaries unsupported, so SmartScreen may warn) |
62
+ | `opencode-cli` | skill | OpenCode V2 from another session: headless `opencode run` (JSON output, model, agent, continue and fork), the background service against `--standalone` and `--server`, `serve` and `pair`, sessions, MCP, plugins, models, stats, debug |
63
+
64
+ Its rules gate each tool on its environment, read live state before acting, close only what the agent opened, never stop the user's server or service, and leave every login and credential to the user. `herdr` is adapted from the official skill of [herdrdev/herdr](https://github.com/herdrdev/herdr) by herdrdev (Apache-2.0), condensed into house format; its skill folder ships `LICENSE-herdr.txt`. `opencode-cli` is first-party and targets OpenCode V2 only, verified against the V2 source at v2.3.0: the V1 commands top-level `export` and `import`, `attach`, `agent create` and `mcp debug` are not in its command table.
65
+
57
66
  ### Switching kits on and off
58
67
 
59
68
  ```bash
60
69
  geneseed build --emit claude-global --kits spring-boot
61
70
  geneseed build --emit claude-global --kits react,spring-boot
62
71
  geneseed build --emit claude-global --kits ci-pipelines,docker
72
+ geneseed build --emit claude-global --kits terminal-tools
63
73
  geneseed build --emit claude-global --kits none
64
74
  ```
65
75
 
66
76
  `--kits` takes a comma-separated list. `none` and an empty value both mean no kits. An unknown kit name is refused with exit code 2, and the error lists the kits this Geneseed ships. `none` is reserved and can never name a kit. The flag's row is in the [CLI reference](../reference/cli.md), under `build`.
67
77
 
68
- A build does exactly what its flags say. A plain `build` without `--kits` therefore turns off a kit the install has on. Before it does, it warns: `this install has kit <k>; this build turns it off β€” pass --kits <k> to keep it`.
78
+ A build does exactly what its flags say, so a plain `build` without `--kits` would turn off a kit the install has on. Over an existing install it refuses instead: it names the change (`kits: <k> -> none`) and prints the command that keeps the kit. With `--reset` it goes ahead and first warns: `this install has kit <k>; this build turns it off β€” pass --kits <k> to keep it`.
69
79
 
70
80
  The setup wizard asks one yes/no question per kit, each defaulting to whether the install has that kit on. It asks them only when at least one kit exists.
71
81
 
@@ -73,7 +83,7 @@ The setup wizard asks one yes/no question per kit, each defaulting to whether th
73
83
 
74
84
  An install with a kit on records it in its instructions file, under the skill section: `Active kits: spring-boot`. The line is written only when at least one kit is on. A missing line means no kits, so an install built before kits existed reads as having none.
75
85
 
76
- `geneseed rebuild-all`, `geneseed update` and `geneseed migrate` read the line back and rebuild with the same kits. `geneseed diff` and the web console read it too, so they compare against or rebuild that same set. `geneseed validate` does not read it: pass `--kits` to dry-run a kit build. A plain `build` does not read it; it only warns, as above. If the line names a kit this Geneseed no longer ships, the rebuild drops that kit with a notice and keeps the others. It never fails `rebuild-all`. A retired kit name is never reused for a new kit.
86
+ `geneseed rebuild-all`, `geneseed update` and `geneseed migrate` read the line back and rebuild with the same kits. `geneseed diff` and the web console read it too, so they compare against or rebuild that same set. `geneseed validate` does not read it: pass `--kits` to dry-run a kit build. A plain `build` does not read it; it refuses or warns, as above. If the line names a kit this Geneseed no longer ships, the rebuild drops that kit with a notice and keeps the others. It never fails `rebuild-all`. A retired kit name is never reused for a new kit.
77
87
 
78
88
  `geneseed status` shows `kits: spring-boot` on the install's row, and `status --json` carries the same list.
79
89
 
@@ -43,6 +43,6 @@ the repository.
43
43
  - **`fitness-define`** (`enforce-architecture-rule`) reaches for ArchUnit first on Java β€” a
44
44
  `FreezingArchRule`, whose violation store doubles as the allowlist of today's violations β€”
45
45
  before dependency-cruiser, import-linter, eslint-plugin-boundaries or size-limit elsewhere.
46
- - **`migration-plan`** (`update-contract`) treats Pact or Spring Cloud Contract, where the repo
47
- already records consumer contracts, as the check `compat-check` runs against each step rather
48
- than only the consumers' own test suites.
46
+ - **`compat-check`** (`update-contract`) treats Pact or Spring Cloud Contract, where the repo
47
+ already records consumer contracts, as the check it runs against each step rather than only
48
+ the consumers' own test suites.
@@ -27,10 +27,12 @@ array names every cycle that is allowed to exist, each with a `max` number of ti
27
27
  it may be re-entered. Picture it as rings: the outer ring is the iteration itself (plan, apply,
28
28
  test, review, back to plan), and inner rings sit inside it for retries (apply failed its test, try
29
29
  `apply` again without going all the way back around). The shipped templates that center on
30
- `apply` β€” `bugfix`, `feature`, `refactor`, `tdd`, `legacy-refactor`, `deps-upgrade` β€” all nest a
31
- short `apply`↔`test` retry ring inside the iteration ring, and most nest a second, wider
32
- `review-fix` ring around that. `legacy-tests` and `ci-repair` have no `apply` at all: the first
33
- only ever writes tests, the second repairs CI directly through `ci-fix`.
30
+ `apply` β€” `bugfix`, `feature`, `refactor`, `tdd`, `legacy-refactor`, `deps-upgrade` among them β€”
31
+ all nest a short retry ring inside the iteration ring (`apply`↔`test`; `apply`↔`flake-check` in
32
+ `fix-flaky-tests`), and most nest a second, wider `review-fix` ring around that. `legacy-tests`,
33
+ `ci-repair` and `architecture-decision` have no `apply` at all: the first only ever writes
34
+ tests, the second repairs CI directly through `ci-fix`, the third drafts a decision record and
35
+ challenges it.
34
36
 
35
37
  Work closes into a commit whenever the graph re-enters the iteration loop's head β€” so any setup
36
38
  work before the loop starts (reproducing a bug, say) is its own unit, numbered iteration 0, kept
@@ -30,7 +30,7 @@ sensitive: # always a checkpoint, whatever the granularity
30
30
  - src/main/resources/db/migration/**
31
31
  ```
32
32
 
33
- The rest of `AGENTS.md` holds the project's coding rules: conventions, build and test commands, project rules. Each developer's own state β€” their granularity and a short `## Preferences` list of how they steer β€” lives in `.geneseed/ownership.md`. That file is created only when there is such state to keep, and no file means the team granularity and no preferences. It is never committed: from its first write, `.geneseed/` gets a `.gitignore` that ignores everything in it except the team's files β€” the `.gitignore` itself, `bricks/`, `loops/`, `protected-checks.txt` and `done-checks.txt`. [Set up ownership](../guides/set-up-ownership.md) walks through the setup, which writes `AGENTS.md` only.
33
+ The rest of `AGENTS.md` holds the project's coding rules: conventions, build and test commands, project rules. Each developer's own state β€” their granularity and a short `## Preferences` list of how they steer β€” lives in `.geneseed/ownership.md`. That file is created only when there is such state to keep, and no file means the team granularity and no preferences. It is never committed: from its first write, `.geneseed/` gets a `.gitignore` that ignores everything in it except the team's files β€” the `.gitignore` itself, `bricks/`, `loops/`, `factories/`, `protected-checks.txt` and `done-checks.txt`. [Set up ownership](../guides/set-up-ownership.md) walks through the setup, which writes `AGENTS.md` only.
34
34
 
35
35
  ## Granularity
36
36