geneseed 5.2.0 → 5.3.1

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 (190) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/README.md +4 -4
  3. package/SHIPPED.md +1 -1
  4. package/adapters/bob/README.md +31 -18
  5. package/adapters/claude-code/README.md +27 -22
  6. package/adapters/openclaude/README.md +18 -8
  7. package/adapters/opencode/HOW-OPENCODE-LOADS.md +8 -3
  8. package/adapters/opencode/plugins/geneseed-activity.js +20 -21
  9. package/adapters/opencode/plugins/geneseed-context.js +224 -71
  10. package/adapters/opencode/plugins/geneseed-guard.js +420 -203
  11. package/adapters/opencode/plugins/geneseed-workflow.js +3 -2
  12. package/adapters/opencode/workflows/_runtime.js +3 -2
  13. package/bin/geneseed-cli.mjs +61 -16
  14. package/bin/geneseed-hook.mjs +94 -12
  15. package/docs/concepts/enforcement-table.md +1 -1
  16. package/docs/concepts/exclusions.md +2 -2
  17. package/docs/concepts/factories.md +40 -6
  18. package/docs/concepts/footprint.md +11 -1
  19. package/docs/concepts/foreman-mode.md +2 -2
  20. package/docs/concepts/hook-gates.md +3 -3
  21. package/docs/concepts/host-matrix.md +22 -4
  22. package/docs/concepts/loop-gates.md +1 -1
  23. package/docs/concepts/loops.md +2 -2
  24. package/docs/concepts/shared-tier.md +1 -1
  25. package/docs/design-history.md +148 -0
  26. package/docs/extending.md +97 -163
  27. package/docs/guides/install-bob.md +2 -2
  28. package/docs/guides/install-openclaude.md +1 -1
  29. package/docs/guides/run-a-factory.md +15 -2
  30. package/docs/guides/upgrade.md +2 -2
  31. package/docs/guides/verify.md +12 -0
  32. package/docs/reference/environment.md +1 -0
  33. package/docs/reference/factory-actions.md +6 -5
  34. package/docs/reference/troubleshoot-doctor.md +1 -1
  35. package/docs/reference/troubleshoot-update.md +1 -1
  36. package/docs/token-footprint.md +66 -2
  37. package/docs/understand/design-choices-hosts.md +1 -1
  38. package/docs/understand/design-choices-shape.md +1 -0
  39. package/docs/understand/enforced-vs-asked.md +1 -1
  40. package/docs/understand/machine-bob.md +1 -1
  41. package/docs/web-ui.md +21 -3
  42. package/harness.config.json +1 -1
  43. package/js/README.md +7 -5
  44. package/js/build/args.mjs +4 -4
  45. package/js/build/driver.mjs +1 -1
  46. package/js/build/emit-claude.mjs +1 -1
  47. package/js/build/generate.mjs +5 -14
  48. package/js/build/render.mjs +44 -24
  49. package/js/cli-table.json +135 -59
  50. package/js/factory/cli.mjs +24 -5
  51. package/js/factory/graph.mjs +13 -9
  52. package/js/factory/metrics.mjs +93 -0
  53. package/js/factory/registry.mjs +37 -12
  54. package/js/factory/state.mjs +25 -6
  55. package/js/hosts/done-checks.mjs +6 -0
  56. package/js/hosts/geneseed-dir.mjs +3 -2
  57. package/js/hosts/gitref.mjs +5 -3
  58. package/js/hosts/hook-tap.mjs +104 -0
  59. package/js/hosts/hooks-context.mjs +30 -3
  60. package/js/hosts/hooks-learn.mjs +47 -16
  61. package/js/hosts/hooks-prims.mjs +52 -3
  62. package/js/hosts/hooks.mjs +69 -42
  63. package/js/hosts/hosts.mjs +80 -12
  64. package/js/hosts/installs.mjs +7 -0
  65. package/js/hosts/loss.mjs +6 -1
  66. package/js/hosts/native.mjs +14 -5
  67. package/js/hosts/owned.mjs +7 -6
  68. package/js/hosts/ownership-gate.mjs +14 -1
  69. package/js/hosts/settings.mjs +245 -103
  70. package/js/hosts/shim.mjs +4 -4
  71. package/js/hosts/usage.mjs +9 -3
  72. package/js/inspect/checks-probe.mjs +66 -5
  73. package/js/inspect/checks-repo.mjs +196 -2
  74. package/js/inspect/cost.mjs +34 -2
  75. package/js/inspect/diff.mjs +16 -1
  76. package/js/inspect/doctor.mjs +13 -4
  77. package/js/inspect/excludes.mjs +18 -6
  78. package/js/inspect/status.mjs +35 -7
  79. package/js/inspect/validate.mjs +44 -21
  80. package/js/lib/machine-dir.mjs +1 -1
  81. package/js/lib/node-floor.mjs +46 -6
  82. package/js/maintain/uninstall.mjs +70 -17
  83. package/js/maintain/update.mjs +31 -7
  84. package/js/ui/cli.mjs +34 -4
  85. package/js/ui/menu.mjs +1 -1
  86. package/js/ui/tui.mjs +11 -14
  87. package/js/web/actions.mjs +3 -9
  88. package/js/web/api.mjs +28 -10
  89. package/js/web/daemon.mjs +0 -1
  90. package/js/web/server.mjs +1 -0
  91. package/js/web/state.mjs +37 -16
  92. package/package.json +1 -1
  93. package/src/AGENT.md.tmpl +23 -17
  94. package/src/agents/_template.md +1 -1
  95. package/src/agents/advocate.md +1 -1
  96. package/src/agents/developer.md +12 -3
  97. package/src/agents/empiricist.md +1 -1
  98. package/src/agents/framer.md +1 -1
  99. package/src/agents/historian.md +1 -1
  100. package/src/agents/operator.md +1 -1
  101. package/src/agents/pragmatist.md +1 -1
  102. package/src/agents/researcher.md +1 -1
  103. package/src/agents/skeptic.md +1 -1
  104. package/src/agents/steward.md +1 -1
  105. package/src/agents/user-advocate.md +1 -1
  106. package/src/agents/visionary.md +1 -1
  107. package/src/bricks/intake.md +10 -3
  108. package/src/bricks/retro.md +13 -3
  109. package/src/doctrines/comms.md +1 -1
  110. package/src/doctrines/ops.md +1 -1
  111. package/src/doctrines/process.md +7 -5
  112. package/src/factories/analysis-to-build.json +1 -0
  113. package/src/factories/bug-report-to-fix.json +1 -0
  114. package/src/factories/issue-to-pr.json +1 -0
  115. package/src/laws/universal.md +2 -2
  116. package/src/modes/foreman.md +8 -14
  117. package/src/skills/commit.md +7 -2
  118. package/src/skills/debug.md +1 -1
  119. package/src/skills/diagram-design/SKILL.md +1 -1
  120. package/src/skills/diagram-design/VENDOR.md +3 -1
  121. package/src/skills/factory-forge.md +5 -3
  122. package/src/skills/factory.md +22 -1
  123. package/src/skills/geneseed.md +1 -1
  124. package/src/skills/handoff.md +1 -1
  125. package/src/skills/parallel-agents.md +1 -1
  126. package/src/skills/pipeline.md +6 -6
  127. package/src/skills/plan.md +7 -3
  128. package/src/skills/spring-testing.md +1 -1
  129. package/themes/biker.json +78 -78
  130. package/themes/commentator.json +81 -81
  131. package/themes/cyberpunk.json +79 -79
  132. package/themes/gamer.json +77 -77
  133. package/themes/imperial.json +82 -82
  134. package/themes/joker.json +79 -79
  135. package/themes/marvin.json +82 -82
  136. package/themes/mean.json +82 -82
  137. package/themes/military.json +78 -78
  138. package/themes/neutral.json +78 -78
  139. package/themes/pirate.json +79 -79
  140. package/themes/sports.json +79 -79
  141. package/themes/verstappen.json +78 -78
  142. package/themes/wizard.json +79 -79
  143. package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
  144. package/web/dist/assets/Activity-WQ3ykgxU.js +1 -0
  145. package/web/dist/assets/ActivityDetail-7rt04SkS.js +1 -0
  146. package/web/dist/assets/{Bonsai-DSwUbavu.js → Bonsai-BBl4XXqs.js} +1 -1
  147. package/web/dist/assets/{CopyButton-BzRQz7k2.js → CopyButton-Beven8yn.js} +1 -1
  148. package/web/dist/assets/Dashboard-BgLArtgu.js +2 -0
  149. package/web/dist/assets/Docs-B5aHp86J.js +5 -0
  150. package/web/dist/assets/Factories-BjqzXAw8.js +1 -0
  151. package/web/dist/assets/GreenhouseView-Bce212qd.js +1 -0
  152. package/web/dist/assets/Installs-B1OsrHXF.js +3 -0
  153. package/web/dist/assets/JournalView-CV4omyww.js +1 -0
  154. package/web/dist/assets/Kits-CW1e7xNa.js +1 -0
  155. package/web/dist/assets/Laws-1Ckf1lbs.js +4 -0
  156. package/web/dist/assets/LibRows-Dag1s0ZX.js +1 -0
  157. package/web/dist/assets/Library-B3FuFLel.js +3 -0
  158. package/web/dist/assets/Loops-CwqgnLNw.js +2 -0
  159. package/web/dist/assets/Markdown-CxkA7940.js +71 -0
  160. package/web/dist/assets/OperatorHudView-JmYY1pBR.js +1 -0
  161. package/web/dist/assets/Personal-DKLgLa7Z.js +2 -0
  162. package/web/dist/assets/Settings-BwErnh-R.js +1 -0
  163. package/web/dist/assets/Tabs-8zsyEPSK.js +1 -0
  164. package/web/dist/assets/index-CRWqKxfY.css +1 -0
  165. package/web/dist/assets/index-Ce6qF2nG.js +6 -0
  166. package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
  167. package/web/dist/index.html +2 -2
  168. package/adapters/claude-code/settings.json +0 -52
  169. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
  170. package/web/dist/assets/Activity-DlQ30znB.js +0 -1
  171. package/web/dist/assets/ActivityDetail-CG0mn5fW.js +0 -1
  172. package/web/dist/assets/Dashboard-Ce3UOsxJ.js +0 -2
  173. package/web/dist/assets/Docs-CisVnYqv.js +0 -5
  174. package/web/dist/assets/Factories-Dq5oW4CU.js +0 -1
  175. package/web/dist/assets/GreenhouseView-y9WAfcc_.js +0 -1
  176. package/web/dist/assets/Installs-m4GElwFW.js +0 -3
  177. package/web/dist/assets/JournalView-DeBLRNGc.js +0 -1
  178. package/web/dist/assets/Kits-DJYVAnyE.js +0 -1
  179. package/web/dist/assets/Laws-CNpc_8ZV.js +0 -4
  180. package/web/dist/assets/LibRows-RO5bvXth.js +0 -1
  181. package/web/dist/assets/Library-Dg0ScciC.js +0 -3
  182. package/web/dist/assets/Loops-CjEdo-NG.js +0 -2
  183. package/web/dist/assets/Markdown-0ORz7tAc.js +0 -69
  184. package/web/dist/assets/OperatorHudView-2ujVMjq1.js +0 -1
  185. package/web/dist/assets/Personal-D0yS7ahT.js +0 -2
  186. package/web/dist/assets/Settings-DEN0U8QI.js +0 -1
  187. package/web/dist/assets/Tabs-But5R6_r.js +0 -1
  188. package/web/dist/assets/index-Ck42AbRX.js +0 -6
  189. package/web/dist/assets/index-PG_ukkh6.css +0 -1
  190. package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
@@ -124,8 +124,9 @@ function isolationReport(stats) {
124
124
  // every depth and would hide `bricks/x.md` even under `!bricks/`. Create-if-absent (`wx`): a
125
125
  // user's own edit survives; its failure never costs the trace. The same string lives in
126
126
  // `workflows/_runtime.js` (a plugin cannot share a file — V2 loads every .js here as a
127
- // plugin — and the runtime is imported lazily, from a configurable dir); tests pin both.
128
- const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
127
+ // plugin — and the runtime is imported lazily, from a configurable dir). Both are
128
+ // js/hosts/geneseed-dir.mjs's line, kept by `node tests/twins.mjs --write`.
129
+ const GENESEED_GITIGNORE = '/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n';
129
130
  // Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
130
131
  // never a user edit, so it is upgraded. Any other content is the user's. Never throws.
131
132
  async function writeGitignore(file) {
@@ -197,8 +197,9 @@ async function runChildSession(client, { prompt, agent, model, title, directory
197
197
  // so neither the worktrees nor the traces show up as untracked files, with the team paths
198
198
  // (bricks, loops, check lists) allowed back. Anchored `/*`, because a bare `*` matches at
199
199
  // every depth and would hide `bricks/x.md` even under `!bricks/`. Same string as
200
- // GENESEED_GITIGNORE in plugins/geneseed-workflow.js; both are pinned by tests.
201
- const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
200
+ // GENESEED_GITIGNORE in plugins/geneseed-workflow.js: both are js/hosts/geneseed-dir.mjs's
201
+ // line, kept by `node tests/twins.mjs --write`.
202
+ const GENESEED_GITIGNORE = '/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n';
202
203
  // Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
203
204
  // never a user edit, so it is upgraded. Any other content is the user's. Never throws.
204
205
  async function writeGitignore(file) {
@@ -55,7 +55,8 @@
55
55
  // whole graph: `tests/unit/hook_cli.test.mjs`'s `importClosure` follows both import spellings.
56
56
  // FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
57
57
  import '../js/lib/node-floor.mjs';
58
- import { cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
58
+ import { readFileSync } from 'node:fs';
59
+ import { cliCommand, cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
59
60
  import { parseIntStrict } from '../js/lib/text.mjs';
60
61
  import { printErr, printOut } from '../js/lib/fs.mjs';
61
62
 
@@ -73,8 +74,8 @@ import { printErr, printOut } from '../js/lib/fs.mjs';
73
74
  *
74
75
  * IT IS STILL A TABLE and still the DISPATCH rather than a declaration beside one.
75
76
  * `tests/unit/hook_cli.test.mjs` scrapes `const VERBS = {` for its matrix gates, and
76
- * `main`'s refusal lists `Object.keys(VERBS)` IN THIS ORDER (no cell asserts the list
77
- * verbatim any more) — the order is the old table's and is not alphabetical.
77
+ * `main`'s unknown-verb refusal draws its nearest-match suggestion from `Object.keys(VERBS)`
78
+ * (it no longer prints the list) — the order is the old table's and is not alphabetical.
78
79
  *
79
80
  * FLATTENED TO `verb: fn` since Task 5, AND TO `verb: loader` since the lazy pass: every row
80
81
  * is now a thunk that imports the command's module and resolves to its function, so the one
@@ -115,13 +116,9 @@ const VERBS = {
115
116
  // argues both.
116
117
  menu: () => import('../js/ui/menu.mjs').then((m) => m.cmdMenu),
117
118
  home: () => import('../js/ui/menu.mjs').then((m) => m.cmdHome),
118
- // P7b, and it is the twenty-fifth and last. `cmd_tui`'s FIRST arm is `if not sys.stdin.
119
- // isatty()`, so off a TTY — which is every cell there is — the verb is one line and an
120
- // exit code, and that arm crosses byte for byte. The panel behind it is P7c's;
121
- // `js/ui/tui.mjs`'s header argues why this entry falls back to `cmd_tui`'s own
122
- // panel-unavailable line rather than inventing a second full-screen UI, and
123
- // `tests/unit/no_panel.test.mjs` asserts that no panel lies behind it — the module paints
124
- // nothing and refuses on a TTY too — rather than leaving that merely untested.
119
+ // RETIRED: there was never a panel behind it, so it refused on every terminal. Kept one
120
+ // release as an alias that prints one line pointing at `menu` and exits 0, as `menu` does off
121
+ // a terminal; `tests/unit/no_panel.test.mjs` asserts the module still paints nothing.
125
122
  tui: () => import('../js/ui/tui.mjs').then((m) => m.cmdTui),
126
123
  // THE THREE THAT NEVER HAD A PYTHON ORIGINAL, and they are last for that reason rather
127
124
  // than by alphabet: every row above is the twin of a subparser, and these three are not.
@@ -155,6 +152,34 @@ const VERBS = {
155
152
  scorecard: () => import('../js/inspect/scorecard.mjs').then((m) => m.cmdScorecard),
156
153
  };
157
154
 
155
+ /** Levenshtein distance, for the one "did you mean" an unknown verb gets. */
156
+ function editDistance(a, b) {
157
+ let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
158
+ for (let i = 1; i <= a.length; i += 1) {
159
+ const cur = [i];
160
+ for (let j = 1; j <= b.length; j += 1) {
161
+ cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
162
+ }
163
+ prev = cur;
164
+ }
165
+ return prev[b.length];
166
+ }
167
+
168
+ /**
169
+ * The closest verb to a mistyped one, or null when nothing is close. Close is at most a third
170
+ * of the typed word's length (and at least 1), so `stauts` finds `status` and `frobnicate`
171
+ * finds nothing: a suggestion for every typo is noise, not help.
172
+ */
173
+ function nearestVerb(typed, verbs) {
174
+ let best = null;
175
+ let bestD = Math.max(1, Math.floor(typed.length / 3)) + 1;
176
+ for (const v of verbs) {
177
+ const d = editDistance(typed, v);
178
+ if (d < bestD) { best = v; bestD = d; }
179
+ }
180
+ return best;
181
+ }
182
+
158
183
  function die(code, msg) {
159
184
  // CRLF on Windows, for the same reason `js/hosts/hooks.mjs`'s funnels translate: argparse writes
160
185
  // this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
@@ -293,11 +318,24 @@ async function main(argv) {
293
318
  // Bare = `home`, as both launchers (`geneseed`, `geneseed.cmd`) already did — but the npm
294
319
  // `bin` names THIS file, so a bare `geneseed` off PATH used to die asking for a verb.
295
320
  if (!argv.length) argv = ['home'];
321
+ // The package version, which `geneseed version` does NOT print: that verb compares the
322
+ // install's build fingerprint with this source's. Read off the package.json beside this file,
323
+ // so it is the version npm installed, and answered before the shim check.
324
+ if (argv[0] === '--version' || argv[0] === '-V') {
325
+ const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
326
+ printOut(`geneseed ${pkg.version}\n`);
327
+ return 0;
328
+ }
329
+ // `help` and `help <verb>` are spellings of `--help` and `<verb> --help`, and nothing more:
330
+ // a rewrite here rather than a VERBS row, because a row would owe the table a subcommand.
331
+ // `help help` is the listing too: `help` is not a VERBS row, so it has no help of its own.
332
+ if (argv[0] === 'help') argv = argv.length > 1 && argv[1] !== 'help' ? [argv[1], '--help'] : ['--help'];
296
333
  const verb = argv[0];
297
334
  if (verb === '-h' || verb === '--help') {
298
- return printVerbList('geneseed', [...Object.keys(VERBS), 'validate'], {
335
+ return printVerbList('geneseed', [...Object.keys(VERBS), 'validate', 'help'], {
299
336
  update: 'an alias of upgrade',
300
337
  validate: "check the source tree without emitting (the generator's --validate-only)",
338
+ help: "this list; help <command> prints that command's help",
301
339
  });
302
340
  }
303
341
  // A DEAD HOOK SHIM, SAID ON EVERY RUN. The shim is machine-wide, so one stale write turns off
@@ -323,12 +361,12 @@ async function main(argv) {
323
361
  if (verb === 'validate') {
324
362
  // Lazy for the same reason the table rows are — `parseDriverArgs` alone drags the whole
325
363
  // generator driver in, and every OTHER verb was paying for it.
326
- const [{ cmdValidate, VALIDATE_USAGE }, { parseDriverArgs }] = await Promise.all([
364
+ const [{ cmdValidate, validateUsage }, { parseDriverArgs }] = await Promise.all([
327
365
  import('../js/inspect/validate.mjs'), import('../js/build/driver.mjs'),
328
366
  ]);
329
367
  // Before the borrowed parser, whose own `-h` prints the GENERATOR's usage.
330
368
  if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
331
- printOut(VALIDATE_USAGE);
369
+ printOut(validateUsage());
332
370
  return 0;
333
371
  }
334
372
  try {
@@ -345,9 +383,16 @@ async function main(argv) {
345
383
  // named, the two entry points now cover every subcommand there is, so the clause was not
346
384
  // just about to become false — it was already claiming a third place for verbs that do
347
385
  // not exist.
348
- return die(2, `invalid choice: '${verb}'. This entry point carries only `
349
- + `${Object.keys(VERBS).join(', ')}; the six hook verbs live in `
350
- + 'bin/geneseed-hook.mjs.');
386
+ //
387
+ // A hook verb (`context`, `tool-gate`, …) is in the table but not here: the emitted
388
+ // settings call it through `geneseed-hook`, and saying so beats "unknown command".
389
+ if (cliCommand(verb) !== null) {
390
+ return die(2, `'${verb}' is a hook verb: the host runs it through geneseed-hook `
391
+ + '(bin/geneseed-hook.mjs), not this command. See geneseed --help.');
392
+ }
393
+ const near = nearestVerb(verb, [...Object.keys(VERBS), 'validate', 'help']);
394
+ return die(2, `unknown command '${verb}'.${near ? ` Did you mean '${near}'?` : ''} `
395
+ + 'See geneseed --help.');
351
396
  }
352
397
  // `js/cli-table.json`, the CLI as data. A verb this table dispatches and the file does not
353
398
  // describe is a REFUSAL and not a parse with no rules: an empty spec would accept every
@@ -50,10 +50,10 @@
50
50
  import '../js/lib/node-floor.mjs';
51
51
  // Not a new module on the hot path: every verb's module imports `js/lib/fs.mjs` too, so this
52
52
  // edge only loads early a file the process would load anyway.
53
- import { printErr } from '../js/lib/fs.mjs';
53
+ import { printErr, printOut } from '../js/lib/fs.mjs';
54
54
  // Also not a new module: every verb's module imports it. It carries the activity switch, so the
55
55
  // off path costs one file read and no import of the writer.
56
- import { activityOn, readStdin } from '../js/hosts/hooks-prims.mjs';
56
+ import { activityOn, askDecision, gateSafe, readStdin } from '../js/hosts/hooks-prims.mjs';
57
57
  import { isatty } from 'node:tty';
58
58
  import path from 'node:path';
59
59
 
@@ -69,9 +69,10 @@ const gates = () => import('../js/hosts/hooks.mjs');
69
69
  // Verbs PreToolUse/PostToolUse actually gate a tool call with. The machine-wide, last-writer-wins
70
70
  // shim (this file's header) means a stale checkout can be handed a flag only a newer install
71
71
  // knows (e.g. `--no-consent`); on Claude Code, exit 2 from one of THESE verbs blocks the tool
72
- // outright, with no ask. `main` below answers an argv error on a gate verb with exit 0 instead —
73
- // a gate's own decision still exits 0 and signals through stdout (`askDecision`), so this only
74
- // changes what used to be a hard lockout into "the gate is silent this one call" (see I3/B1).
72
+ // outright, with no ask. `main` below answers an argv error on a gate verb with exit 0 and the
73
+ // gate-error ask instead (a stderr warning on Bob) — a gate's own decision exits 0 and signals
74
+ // through stdout too (`askDecision`), so what used to be a hard lockout is a question the person
75
+ // can answer, never "the gate is silent this one call" (see I3/B1).
75
76
  const GATE_VERBS = new Set(['git-gate', 'rule-gate', 'tool-gate']);
76
77
  const VERBS = {
77
78
  context: { load: () => import('../js/hosts/hooks-context.mjs'), fn: 'cmdContext', flags: HOSTED },
@@ -101,6 +102,8 @@ const VERBS = {
101
102
  '--no-deletion-gate': 'noDeletionGate', '--no-secrets-gate': 'noSecretsGate',
102
103
  '--no-ownership-gate': 'noOwnershipGate', '--no-external-gate': 'noExternalGate',
103
104
  '--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
105
+ // Bob's commit/push warning, when process 5 is off: `gitDecide` reads it as on git-gate.
106
+ '--no-consent': 'noConsent',
104
107
  },
105
108
  },
106
109
  learn: {
@@ -163,6 +166,50 @@ async function trackActivity(verb, args) {
163
166
  } catch { /* the activity view is best-effort; a hook that fails is a tool call that fails */ }
164
167
  }
165
168
 
169
+ /**
170
+ * The tap (js/hosts/hook-tap.mjs): with `GENESEED_HOOK_TAP=<dir>` in the host's environment,
171
+ * the payload the verb just answered is written there as a fixture, values replaced by their
172
+ * shape. After the verdict, like `trackActivity`, and on the same cached stdin. The caller tests
173
+ * the variable, so an untapped hook never imports the module; a terminal sends no payload.
174
+ * Never prints, never changes the exit code.
175
+ */
176
+ async function tapHook(verb, args) {
177
+ try {
178
+ if (isatty(0)) return;
179
+ const { tapPayload } = await import('../js/hosts/hook-tap.mjs');
180
+ tapPayload(process.env.GENESEED_HOOK_TAP, readStdin(), { verb, host: args.host || 'claude' });
181
+ } catch { /* a capture is a favour to a maintainer; a hook that fails is a tool call that fails */ }
182
+ }
183
+
184
+ /**
185
+ * A verb whose module failed to load, or threw past its own guard. `guardGate` only covers a gate
186
+ * once its module has loaded; a module that cannot (a file missing mid-`git pull` under the shared
187
+ * shim, a syntax error) used to exit 1 with nothing on stdout, which Claude reads as "the gate
188
+ * deferred". So a gate verb gives the gate-error verdict `guardGate` gives — an ask on Claude and
189
+ * OpenClaude, a stderr warning on Bob, where gate-error is never a block — built from
190
+ * `./hooks-prims.mjs`, which the entry has already loaded. Not ledgered: the ledger's writer is
191
+ * in the module that failed. Every other verb exits 0 with stdout empty and one stderr line, so a
192
+ * broken context hook shows in the host's hook log: stdout is the only channel any host reads as
193
+ * a decision, and on Bob too a stderr line with exit 0 is a log entry (the gates' Bob warnings
194
+ * already are). The residual limit: a
195
+ * module this file imports statically (`fs.mjs`, `hooks-prims.mjs`) fails at link time, before
196
+ * any of this runs.
197
+ */
198
+ function verbFailed(verb, args, e) {
199
+ let name = e;
200
+ try { name = e.message || e; } catch { /* `gateSafe` meets `e` as it is */ }
201
+ if (!GATE_VERBS.has(verb)) {
202
+ try { printErr(`[geneseed-hook] ${verb} failed: ${name}\n`); } catch { /* an unprintable error says nothing */ }
203
+ return 0;
204
+ }
205
+ if (args.host === 'bob') {
206
+ printErr(`[geneseed] ${gateSafe('gate-error', 'warned', { name })}\n`);
207
+ return 0;
208
+ }
209
+ printOut(askDecision(gateSafe('gate-error', 'ask', { name })));
210
+ return 0;
211
+ }
212
+
166
213
  function die(code, msg) {
167
214
  // CRLF on Windows, for the same reason the hook verbs' funnels translate: argparse
168
215
  // writes this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
@@ -170,6 +217,20 @@ function die(code, msg) {
170
217
  return code;
171
218
  }
172
219
 
220
+ /**
221
+ * The `--host` an argv names, in both spellings `parse` takes, the last one winning as it does
222
+ * there. For the argv-error path only: `parse` returns no args with an error, and the gate-error
223
+ * answer still has to know whether its reader is Bob.
224
+ */
225
+ function hostNamed(argv) {
226
+ let host = null;
227
+ argv.forEach((tok, i) => {
228
+ if (tok.startsWith('--host=')) host = tok.slice('--host='.length);
229
+ else if (tok === '--host' && argv[i + 1] !== undefined) host = argv[i + 1];
230
+ });
231
+ return host;
232
+ }
233
+
173
234
  /**
174
235
  * `argparse`'s surface for these verbs, and only theirs: `--flag VALUE`, the
175
236
  * `--flag=VALUE` spelling it also accepts, store_true switches, and one optional
@@ -249,11 +310,20 @@ async function main(argv) {
249
310
  const parsed = parse(spec, argv.slice(1));
250
311
  if (parsed.error) {
251
312
  // A gate verb must never exit 2 on an argv error: that is indistinguishable, to Claude's
252
- // PreToolUse, from the gate deliberately blocking (see I3/B1 above). Print the same message
253
- // to stderr for a human debugging the shim, but return 0 with no stdout, exactly like a gate
254
- // that chose not to act.
255
- // `activity` too: it runs on UserPromptSubmit, where exit 2 erases the user's prompt.
256
- if (GATE_VERBS.has(verb) || verb === 'activity') {
313
+ // PreToolUse, from the gate deliberately blocking (see I3/B1 above). It must not exit 0 with
314
+ // stdout empty either: that reads as "the gate deferred", so a stale shim handed a newer flag
315
+ // let every call through unjudged. It answers as a gate whose module failed to load does
316
+ // (`verbFailed`): an ask on Claude and OpenClaude, where the person can still allow the call —
317
+ // so no lockout — and is told the gate is broken; a stderr warning and exit 0 on Bob, whose
318
+ // PreToolUse has no matcher, so exit 2 there would refuse every tool, reads included. The
319
+ // stderr line stays for a human debugging the shim.
320
+ if (GATE_VERBS.has(verb)) {
321
+ printErr(`geneseed-hook: error: ${parsed.error}\n`);
322
+ return verbFailed(verb, { host: hostNamed(argv.slice(1)) }, new Error(parsed.error));
323
+ }
324
+ // `activity` decides nothing, and it runs on UserPromptSubmit, where exit 2 erases the
325
+ // user's prompt: the stderr line, exit 0, stdout empty.
326
+ if (verb === 'activity') {
257
327
  printErr(`geneseed-hook: error: ${parsed.error}\n`);
258
328
  return 0;
259
329
  }
@@ -267,12 +337,24 @@ async function main(argv) {
267
337
  // `context` answers SessionStart and SubagentStart (settings.mjs), told apart by the payload's
268
338
  // event name. Read here, not in the verb, so an in-process caller never blocks on fd 0; the read
269
339
  // is cached, so `trackActivity` reuses it. A terminal sends no payload.
340
+ // The same parse hands `context` the payload's `cwd`, its project root on a host that sets no
341
+ // `$CLAUDE_PROJECT_DIR` (`hookProjectDir`).
270
342
  if (verb === 'context' && !isatty(0)) {
271
- try { parsed.args.event = JSON.parse(readStdin() || '{}').hook_event_name ?? null; } catch { /* not JSON: SessionStart */ }
343
+ try {
344
+ const payload = JSON.parse(readStdin() || '{}');
345
+ parsed.args.event = payload.hook_event_name ?? null;
346
+ parsed.args.cwd = typeof payload.cwd === 'string' ? payload.cwd : null;
347
+ } catch { /* not JSON: SessionStart */ }
348
+ }
349
+ let rc;
350
+ try {
351
+ rc = (await spec.load())[spec.fn](parsed.args);
352
+ } catch (e) {
353
+ return verbFailed(verb, parsed.args, e);
272
354
  }
273
- const rc = (await spec.load())[spec.fn](parsed.args);
274
355
  await trackActivity(verb, parsed.args);
275
356
  await baselineStores(verb, parsed.args);
357
+ if (process.env.GENESEED_HOOK_TAP) await tapHook(verb, parsed.args);
276
358
  return rc;
277
359
  }
278
360
 
@@ -26,7 +26,7 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
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
27
  | `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). A sub-agent's commit or merge (`agent_id` in the payload) in a linked worktree, on a branch that is not shared, passes: a Foreman worker's own batch ([Foreman mode](foreman-mode.md) has the exact conditions). A git hook or `core.hooksPath` that pushes on commit is not seen. A push, or a command that mixes one in, still asks. Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed. A glob sees only the command, never the worktree, so a worker's commit still asks | log only |
28
28
  | `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list, or to a gate's own configuration: hook settings, `excludes.json`, `AGENT.md` gate markers, the hook shim) | same as Claude Code | ask: OpenCode's own `permission.edit` rules, written by the emit (every `opencode.json(c)`, the hook settings, the install's `AGENT.md`, `excludes.json`, manifest, plugins, the hook shim); block: guard plugin (the protected-checks list, and the other hosts' Geneseed-only files) | block (exit 2), writes only; a hook `settings.json` only when the edit changes Geneseed's own hook entries |
29
- | `verify-before-asserting` | law | block at Stop, once per turn: the done gate in `learn` (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (**unverified live**: a frozen fork, and no check runs a model turn) | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
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) |
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
@@ -44,7 +44,7 @@ What "dormant" means per host:
44
44
 
45
45
  **Git worktrees.** A linked worktree of an excluded repo (`git worktree add`) is excluded too, wherever it sits on disk: the hooks and plugins follow its `.git` file back to the main repository. The global `CLAUDE.md` is the exception on Claude Code and OpenClaude: `settings.local.json` is gitignored, so a worktree never gets it. Geneseed writes no tracked file in a repo you told it to leave alone, so `exclude add` and `exclude list` print the snippet to commit yourself in the repo's tracked `.claude/settings.json` (`.openclaude/` for OpenClaude): `"claudeMdExcludes": ["<path to the global CLAUDE.md>"]`.
46
46
 
47
- **Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. And a global install created *after* you added exclusions is silent in those folders at once, through the shared list, and its next emit applies the repo-side wiring there. Until that emit, `geneseed exclude list` flags it.
47
+ **Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. That makes an exclusion a poor way to save tokens: the listings stay on Claude Code and OpenClaude, and on OpenCode the global instructions file still loads (see [Why there is no chat mode](../token-footprint.md#why-there-is-no-chat-mode)). And a global install created *after* you added exclusions is silent in those folders at once, through the shared list, and its next emit applies the repo-side wiring there. Until that emit, `geneseed exclude list` flags it.
48
48
 
49
49
  The web console has the same controls in the **Excluded folders** card on the Installs page, shown once a global install exists.
50
50
 
@@ -95,7 +95,7 @@ What stops asking, per host: the real-loss check of `git-gate` (Claude Code, Ope
95
95
  Limits:
96
96
  - **OpenCode reads the switch at start.** The guard plugin reads `Deletion gate:` from the install's `AGENT.md` once, when OpenCode loads it: restart OpenCode after flipping it.
97
97
  - **A global install beside a project install.** On Claude Code and OpenClaude the global `git-gate` stands down for a project install, so the project's switch decides. Bob's `tool-gate` and the OpenCode guard do not stand down: an armed global install still refuses real loss inside a project whose own install is off.
98
- - **An older `opencode.json` keeps its Law IV keys.** Switching off removes the `permission.bash` entries the manifest records Geneseed adding (`bash_gates`, since 5.2.0). An install made before that has no record, so the build warns that it keeps them and they keep asking. Run the build once with `--prune-gates` to remove those still set as Geneseed writes them, or delete them by hand. An entry you changed always stays, and a commented `opencode.jsonc` is never rewritten: the build names the entries to remove.
98
+ - **An older `opencode.json` keeps its Law IV keys.** Switching off removes the `permission.bash` entries the manifest records Geneseed adding (`bash_gates`, since 5.2.0). An install made before that has no record, so the build warns that it keeps them and they keep asking. Run the build once with `--prune-gates` to remove those still set as Geneseed writes them, or delete them by hand. An entry you changed always stays, and a commented `opencode.json` or `opencode.jsonc` is never rewritten: the build names the entries to remove.
99
99
  - **An older hook shim silences the whole gate.** The flag is new. While the machine's shared hook shim still points at an older checkout, that checkout refuses the flag and the gate verb lets every call through on a disarmed install — on Claude Code and OpenClaude the root-scan and consent checks too, on Bob also *Sealed Secrets* and *External Gate*. Update the checkout the shim points at (`geneseed rebuild-all`) before switching the gate off.
100
100
 
101
101
  ### Law I secrets gate and Law III done gate — on or off
@@ -44,7 +44,7 @@ but its first stage, or a route back that spends no cycle.
44
44
  ## Forks and lanes
45
45
 
46
46
  A **fork** is where the work takes one way or another. It is a brick that declares **named
47
- outcomes**, any outcome other than `pass`, `fail`, `error`, `none` or `needs-info`. `triage` is one: `bug`,
47
+ outcomes**, any outcome other than `pass`, `fail`, `error`, `none`, `needs-info` or `reject`. `triage` is one: `bug`,
48
48
  `feature`, `deps`, `refactor`, `docs` and `fail`. Each named outcome has its own edge to its own
49
49
  stage, its **lane**, and the outcome the brick reports picks the lane. `geneseed factory next`
50
50
  hands the fork its `lanes`: each outcome with the stage it leads to.
@@ -76,6 +76,37 @@ exception is the run's spec, `specs/<slug>/spec.md`: the `spec` stage writes it,
76
76
  it is committed once you approve it, before the first loop. Each run is listed in `factories.json` beside the loop registry, and each child loop's row
77
77
  names the run it belongs to.
78
78
 
79
+ ## The queue, and a refused item
80
+
81
+ A run takes one work item. To pick from several, ask the agent for the **queue**: it lists the
82
+ open issues that carry the label `factory` (or a label you name), and you pick one, several or
83
+ all. Several picks run one after the other, in the order you gave, each as its own run in its
84
+ own worktree, each with its own merge question. A run that holds a gate holds the queue. An
85
+ issue's text is the run's input, never an instruction to the agent. No file configures the queue,
86
+ and nothing starts a run by itself.
87
+
88
+ `intake` may also **refuse** an item, with the outcome `reject`: it is already done, it duplicates
89
+ another issue or pull request, or it goes against a rule the project states. The run holds and
90
+ shows you the reason and its evidence. `ok` accepts the refusal and stops the run, `amend` runs
91
+ `intake` again with your reason to build it, and `no` stops too. In each shipped factory the
92
+ `reject` edge goes to `$stop`; a factory of your own that has no such edge stops the same way.
93
+
94
+ ## What a run measures
95
+
96
+ Every `record` and `decide` writes the time on its history entry, and `init` writes when the run
97
+ started. From those, `geneseed factory report` gives each stage its runs, its reworks, its work
98
+ time and its tokens, and the run its work time and the time it waited for you at a gate. The time
99
+ between a held outcome and your answer is waiting time, never the stage's. A rework is an outcome
100
+ that spent a cycle: a failed `checks`, `review-panel` or `holdout`, or red CI.
101
+
102
+ Tokens are recorded only where the host reports a count for the agent that ran the stage
103
+ (`record --tokens <n>`); nothing estimates one, and a loop stage carries none. There is no cost in
104
+ money: Geneseed holds no price table. A number nobody recorded is `null` in the report, never 0,
105
+ so a `FACTORY.md` written before times were stamped still runs and reports `unknown`.
106
+
107
+ The `retro` stage copies those numbers into the run report, and adds, for each `review-panel`
108
+ seat, how many rounds it failed.
109
+
79
110
  ## The shipped factories
80
111
 
81
112
  | Factory | Stages |
@@ -88,7 +119,7 @@ The bricks they add:
88
119
 
89
120
  | Brick | Does | Outcomes |
90
121
  | --- | --- | --- |
91
- | `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria, its `size` and its `areas`. `needs-info` holds for your answers to its questions (`gate: human`) | `pass`, `fail`, `needs-info` |
122
+ | `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria, its `size` and its `areas`. `needs-info` holds for your answers to its questions, and `reject` holds when it finds the item already done, a duplicate, or against a rule the project states, with the reason and its evidence (`gate: human`). It never posts on the issue | `pass`, `fail`, `needs-info`, `reject` |
92
123
  | `holdout-write` | Writes 3 to 8 prose scenarios (given / when / then) for the work item into the holdout folder, outside the worktree, and hands the work item on unchanged | `pass`, `fail` |
93
124
  | `holdout` | Plays every scenario against the built change. `fail` carries one sentence per failed scenario, observed against expected; `error` when the diff touches the holdout folder or a scenario cannot be played | `pass`, `fail`, `error` |
94
125
  | `checks` | Runs the done list as the base branch holds it, never the branch's copy. `error` holds when the diff touches a locked path, or on an environment failure (a failed fetch, a timeout, a missing tool); `none` holds with a proposed list when the base has none | `pass`, `fail`, `error`, `none` |
@@ -96,7 +127,7 @@ The bricks they add:
96
127
  | `triage` | A fork: reads the work item and reports the outcome that names its lane, with its reason. `fail` when no lane fits | `bug`, `feature`, `deps`, `refactor`, `docs`, `fail` |
97
128
  | `pr-open` | Pushes the branch (the push asks you) and opens the PR, or updates the one already open | `pass`, `fail` |
98
129
  | `merge-gate` | Waits for the PR's CI with a watch that returns by itself (each call under 10 minutes), 30 minutes at most. A repo with no CI reports `none`, and you decide; so does CI still pending at the bound, or a `gh`/`glab` that is missing or fails | `pass`, `fail`, `none` |
99
- | `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, and keeps only a lasting lesson in memory | `pass` |
130
+ | `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, with the numbers of `geneseed factory report`, and keeps only a lasting lesson in memory | `pass` |
100
131
 
101
132
  `analysis-to-build` also uses the loops' own `spec` brick (`gate: human`), the one the
102
133
  `spec-first-feature` loop starts with, and `issue-to-pr` the loops' `docs-update` brick as its
@@ -179,9 +210,12 @@ graph: its stages top to bottom, a fork's lanes side by side, a `loop:` stage as
179
210
  that names its loop over `whole loop`, each route back as a rail on the left with its cycle and
180
211
  `max`, and `close` and `stop` as end caps.
181
212
  Each factory shows how to start it: the request to give the agent, and the commands to start it
182
- by hand, the worktree first and then `geneseed factory init`. Its **Active** tab lists every
183
- registered run, with the current stage lit, the laps spent on each cycle and the child loop's
184
- current step, written `at <node>` in the current stage's box. The page changes nothing in a run (its poll only drops finished runs older than 7 days from `factories.json`, as Loops does); you answer a run in the
213
+ by hand, the worktree first and then `geneseed factory init`. Its **Active** tab is a board of every
214
+ registered run, in three columns: **Waits for you**, **Running** and **Ended**. A card shows where
215
+ the run stands, its task, the laps spent on each cycle, and its work and waiting time. A card
216
+ opens the run: its graph with the current stage lit, the laps spent on each cycle, the child
217
+ loop's current step, written `at <node>` in the current stage's box, and a timeline of every
218
+ stage with its outcome, its time, its duration and each rework. The page changes nothing, neither a run nor `factories.json`: the next `geneseed factory init` on the machine drops a run whose worktree is gone, and a closed run 7 days after that init first saw it closed. You answer a run in the
185
219
  agent's session.
186
220
 
187
221
  ## Your own factories
@@ -14,7 +14,7 @@ link: {"hash": "#/installs/hosts", "label": "Change it on Installs →"}
14
14
  ### The difference
15
15
 
16
16
  - **Full** — the instructions file carries the Ethos, every Rule and every rule of the active doctrine packs at complete length, reasoning included, every turn.
17
- - **Lean** — each Rule and each doctrine rule is carried as its heading plus a short form written by hand (the rule and how it works, not the first sentence cut off). Each layer ends with a pointer to its complete text on disk, and the agent reads the reasoning when a rule's application is unclear. The Ethos gets one hand-written short form for the whole layer, because it is flowing prose rather than numbered rules.
17
+ - **Lean** — each Rule and each doctrine rule is carried as its heading plus a short form written by hand (the rule and how it works, not the first sentence cut off). One pointer after the doctrine packs names where the complete text of both layers is on disk, and the agent reads the reasoning when a rule's application is unclear. The Ethos gets one hand-written short form for the whole layer, because it is flowing prose rather than numbered rules. Lean also drops the voice's flourish: a heading names the rule by its plain principle (`Dictate I — Sealed Secrets`, not `Dictate I — Arcana Sigillata · Sealed Secrets`), and no section opens with an italic epigraph. Full keeps both, and so do the complete files on disk.
18
18
 
19
19
  Neither setting hides text from the agent. They decide what is in front of it on *every* turn.
20
20
 
@@ -32,6 +32,16 @@ Everything else is identical at both settings — the same agents, skills, plugi
32
32
 
33
33
  For measured numbers per host, see [docs/token-footprint.md](../token-footprint.md).
34
34
 
35
+ ### There is no chat mode
36
+
37
+ Footprint is the only token dial. There is no command that switches the harness off for a quick question, and that is deliberate.
38
+
39
+ - **What it costs.** Measured on 2026-11-12, the harness adds about 11–14k tokens to a session at lean and 18–21k at full, depending on the host. Where the provider caches prompts, that is billed at the full price once per session and at the cached rate on every later message.
40
+ - **Why not a command in the chat.** The harness is in the context before your first message, and no host can take it back out of a running conversation. A command could only tell the agent to ignore the rules, which saves nothing.
41
+ - **Why not a toggle on resume.** On Claude Code and OpenCode 2, resuming a conversation without the harness keeps it in the history, and resuming with it again loads it a second time.
42
+
43
+ So the harness stays in place in every session. For a single session without it, each host has its own launch option; the launch lines, their limits and every measurement are in [Why there is no chat mode](../token-footprint.md#why-there-is-no-chat-mode).
44
+
35
45
  ### How to set it
36
46
 
37
47
  Footprint is stored in a `.geneseed-footprint` marker in the install and kept across every rebuild and upgrade, on every host.
@@ -11,7 +11,7 @@ link: {"hash": "#/installs/hosts", "label": "Set the mode on Installs →"}
11
11
 
12
12
  > **You already know this:** a tech lead with a team. Quick questions get answered on the spot; a real feature becomes a ticket that someone builds on a branch, and the lead reviews the result before it is merged.
13
13
 
14
- Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a task worker or a pipeline is a one-shot, uncommitted run for a single task; a loop is a long-running state machine that commits each validated iteration on its own branch.
14
+ Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a task worker or a pipeline is a one-shot run for a single task, committed only on its own branch and merged by the session once you accept; a loop is a long-running state machine that commits each validated iteration on its own branch.
15
15
 
16
16
  ### direct — the default
17
17
 
@@ -70,7 +70,7 @@ Inside the crew, the developer implements and the tester runs the tests and lint
70
70
 
71
71
  ### Nothing lands beyond the worker's branch
72
72
 
73
- When a crew is done, it hands back its worktree **uncommitted**. A worker hands back its branch: the local commits from its own sub-workers' merges, and any uncommitted work. Each comes with the raw test and lint output and the list of files it changed. Then the session:
73
+ A worker or crew commits only in its own worktree, never pushes, and never merges outside its own branch. When it is done, it hands back that branch: its local commits (its own, and its sub-workers' merges) and any uncommitted work. Each comes with the raw test and lint output and the list of files it changed. Then the session:
74
74
 
75
75
  1. re-runs the tests and lint itself — its log is its own account, not proof;
76
76
  2. shows you the diff from the base it recorded, and the green output;
@@ -37,11 +37,11 @@ The merge is surgical. Every other key and every hook of your own survive, and t
37
37
  **Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher or `SubagentStop`. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet. So Bob gets four hooks:
38
38
 
39
39
  - `SessionStart` → `geneseed-hook context`.
40
- - `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push 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
- - `Stop` → `geneseed-hook learn`.
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.
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
 
44
- Neither host has been verified live on the authoring machine. If a hook does not fire, the same rules still reach the agent through the instructions file.
44
+ What was checked against each host itself is in [What is verified](host-matrix.md#what-is-verified). If a hook does not fire, the same rules still reach the agent through the instructions file.
45
45
 
46
46
  ## The hook shim
47
47
 
@@ -14,7 +14,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
14
14
  | Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
15
15
  | Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
16
16
  | Your `user-rules.md` handed to each sub-agent | — (later) | 🪝 hook | — (no `SubagentStart`) | 🪝 hook² |
17
- | Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
17
+ | Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | ➖ wired, inert: Bob's `Stop` carries no transcript¹ | 🪝 hook² |
18
18
  | Live sessions in the web console's [Activity view](../reference/plugin-activity.md) | ⚙️ plugin | 🪝 hook, files per subagent, context size | 🪝 hook, per tool call only (no transcript, no context size, subagent files not attributed)¹ | 🪝 hook, files per subagent, context size² |
19
19
  | Real data loss (force-push to `main`, discarding uncommitted work, `rm` of untracked files…) | ⚙️ block³ · 🔒 ask (reflog, gc) | 🪝 ask | 🪝 block¹ | 🪝 ask² |
20
20
  | Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
@@ -28,16 +28,34 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
28
28
 
29
29
  ✅ native · ⚙️ OpenCode plugin · 🔒 `permission` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
30
30
 
31
- ¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks only the rules that admit no judgement call — secrets, real data loss, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off — and turns the two consent checks into a logged warning. It has no `SubagentStop` event. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet, so learn runs on `Stop` only. **What is verified:** the payload shape (Claude's keys plus `cwd`), the event list and the strict settings schema were read in Bob 2.2.3's shipped bundle on the authoring machine, and a live prompt on 2026-10-25 wrote an Activity snapshot from `UserPromptSubmit`. The gates' block-by-exit-code behaviour is Bob's documented contract, not yet observed live; the rules preamble still holds if a hook does not fire.
32
- ² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). **Unverified live** for the same reason.
31
+ ¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks exactly the rules whose Bob cell says *block* in [Rule enforcement, by host](enforcement-table.md), and turns the commit/push consent into a logged warning. It has no `SubagentStop` event. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them. The `Stop` hook is wired and runs the [change report](hooks.md#the-change-report), but learns nothing: Bob's `Stop` payload carries no transcript, and the group is kept so that learning starts if Bob ever sends one. The rules preamble still holds if a hook does not fire. For what was checked against Bob itself, see [What is verified](#what-is-verified).
32
+ ² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). See [What is verified](#what-is-verified).
33
33
  ³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so a standing-rule write gets OpenCode's own prompt, and the guard refuses a file-tool write where no prompt can run. Shell is not a boundary on any host: only parsed forms are read, and the host's command permission is the backstop. A real data loss is blocked outright (as on Bob) rather than asked; `GENESEED_GUARD=warn` turns a block into a logged warning.
34
34
  ⁴ The checks differ in shape: OpenCode's guard plugin blocks writes *to* private-key and credential files by path; the Claude-shaped hook looks at the *content* being written for credential-shaped strings (cloud keys, tokens, private-key blocks) and asks. A `.env` file is exempt on the hook side — that is where a secret is allowed to live.
35
35
  ⁵ A linked git worktree of an excluded repo is excluded too: the hooks and plugins follow its `.git` file back to the main repository. `claudeMdExcludes` is the exception — it lives in the gitignored `settings.local.json`, which a worktree never gets — so `geneseed exclude add` and `exclude list` print the snippet to commit yourself. See [Exclusions](exclusions.md).
36
36
 
37
+ ## What is verified
38
+
39
+ This is the one place that says what was checked against each host itself, how, and when. Every other page links here and states nothing of its own; `geneseed doctor` fails a page that does.
40
+
41
+ | Host | Method | Date | Scope | Not covered |
42
+ | --- | --- | --- | --- | --- |
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
+ | 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
+ | 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 |
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
+ | Bob | live session | 2026-10-25 | a prompt wrote an Activity snapshot from `UserPromptSubmit` | |
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 |
50
+ | OpenCode V1 | canary | weekly in CI, at npm `latest` (log lines measured 2026-10-12) | no `failed to load plugin` line names a Geneseed plugin, and the workflow plugin's banner shows `.server` ran | the guard's refusal, which needs a model turn |
51
+ | OpenCode V2 | canary | weekly in CI, at npm `latest` (log lines measured 2026-10-12) | no `failed to load plugin` line names a Geneseed plugin, and a `loading plugin` line is logged for each | the guard's refusal, which needs a model turn |
52
+
53
+ No check on any host calls a model. `geneseed doctor --probe` covers the other half on your own machine: it runs the installed gates through each host's shell on calls they must refuse and calls they must let through.
54
+
37
55
  ## The one conditional row
38
56
 
39
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.
40
58
 
41
- 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, and uninstall takes those back too; uninstall leaves the `permission.bash` gates.
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.
42
60
 
43
61
  In plain terms: [Enforced vs. asked](../understand/enforced-vs-asked.md).
@@ -15,7 +15,7 @@ committed or counted against a ring budget while it waits.
15
15
 
16
16
  A [factory](factories.md) stage holds the same way, answered with `geneseed factory decide`.
17
17
  Three shipped bricks do: `intake` (holds on `needs-info` — it has questions only you can
18
- answer), `checks` (holds on `error` — the branch changed a locked path — and on `none` — the
18
+ answer — and on `reject` — it refuses the item as already done, a duplicate or against a rule), `checks` (holds on `error` — the branch changed a locked path — and on `none` — the
19
19
  base branch has no done list yet) and `merge-gate` (holds on `none` — the repo runs no CI on the
20
20
  PR).
21
21
 
@@ -83,7 +83,7 @@ evidence was never wired — no verdict is not a failure to repair.
83
83
  ## Not foreman mode
84
84
 
85
85
  A loop and a [foreman-mode](foreman-mode.md) pipeline are both "hand work off and keep going," but
86
- they solve different problems. A pipeline is a one-shot crew for a single task, uncommitted until
87
- you accept it. A loop is a long-running, self-scoring state machine that commits each validated
86
+ they solve different problems. A pipeline is a one-shot crew for a single task; it commits only on its
87
+ own branch, and nothing lands beyond it until you accept it. A loop is a long-running, self-scoring state machine that commits each validated
88
88
  iteration on its own branch as it goes, and only stops for a person when the risk crosses a
89
89
  threshold.
@@ -36,7 +36,7 @@ The same folder already held the install registry, your own loop bricks and temp
36
36
  | `PROFILE.md`, `geneseed-wiki.jsonc` | Whole file. A host file that is no longer its seed replaces the shared one. `$GENESEED_WIKI` overrides both |
37
37
  | `excludes.json` | A global install reads the union of the shared list and its own |
38
38
 
39
- When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
39
+ When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. In `user-rules.md`, the seed's explanation above the first `## R<n>` rule is skipped too while it is unchanged: only the rules are sent. Text you wrote above the rules, or an edited explanation, is sent as it is. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
40
40
 
41
41
  A global install's text names these locations as absolute paths. A project install keeps its relative paths and its own `memory/`. Geneseed grants no directory permission for the tier, so an agent write there follows your host's permission mode, as a write to the host's own folder does. A write to the shared rules or draft passes the same [rule gate](hooks.md) as a local one; the shared memory, like a local one, is written freely.
42
42