geneseed 5.0.1 → 5.0.4

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 (185) hide show
  1. package/CHANGELOG.md +92 -0
  2. package/README.md +4 -4
  3. package/SHIPPED.md +2 -2
  4. package/adapters/claude-code/README.md +11 -5
  5. package/adapters/openclaude/README.md +3 -1
  6. package/adapters/opencode/HOW-OPENCODE-LOADS.md +3 -0
  7. package/adapters/opencode/plugins/geneseed-context.js +12 -1
  8. package/adapters/opencode/plugins/geneseed-guard.js +594 -73
  9. package/adapters/opencode/plugins/geneseed-learn.js +1 -1
  10. package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
  11. package/adapters/opencode/workflows/_runtime.js +1 -1
  12. package/bin/geneseed-cli.mjs +3 -0
  13. package/bin/geneseed-hook.mjs +31 -9
  14. package/docs/PRD.md +1 -1
  15. package/docs/README.md +4 -1
  16. package/docs/concepts/enforcement-table.md +23 -4
  17. package/docs/concepts/exclusions.md +48 -2
  18. package/docs/concepts/factories.md +151 -0
  19. package/docs/concepts/foreman-mode.md +19 -4
  20. package/docs/concepts/hook-gates.md +1 -1
  21. package/docs/concepts/hooks.md +53 -12
  22. package/docs/concepts/host-matrix.md +5 -3
  23. package/docs/concepts/hosts.md +1 -1
  24. package/docs/concepts/kits.md +18 -0
  25. package/docs/concepts/loop-gates.md +3 -0
  26. package/docs/concepts/loops.md +1 -0
  27. package/docs/concepts/rules.md +1 -1
  28. package/docs/concepts/shared-tier.md +1 -1
  29. package/docs/concepts/skills.md +1 -1
  30. package/docs/extending.md +8 -2
  31. package/docs/guides/autostart.md +29 -3
  32. package/docs/guides/choose-your-setup.md +1 -1
  33. package/docs/guides/migrate.md +1 -1
  34. package/docs/guides/run-a-factory.md +88 -0
  35. package/docs/guides/set-up-ownership.md +1 -0
  36. package/docs/guides/uninstall.md +1 -1
  37. package/docs/reference/factory-actions.md +22 -0
  38. package/docs/reference/loop-actions.md +1 -1
  39. package/docs/reference/plugin-activity.md +1 -1
  40. package/docs/reference/plugin-context.md +1 -1
  41. package/docs/reference/plugin-guard.md +24 -5
  42. package/docs/reference/troubleshoot-doctor.md +2 -2
  43. package/docs/understand/a-day.md +9 -5
  44. package/docs/web-ui.md +101 -17
  45. package/harness.config.json +1 -1
  46. package/js/README.md +21 -3
  47. package/js/build/args.mjs +14 -2
  48. package/js/build/emit-claude.mjs +9 -1
  49. package/js/build/emit-opencode.mjs +2 -1
  50. package/js/build/source.mjs +28 -3
  51. package/js/cli-table.json +287 -3
  52. package/js/factory/cli.mjs +153 -0
  53. package/js/factory/graph.mjs +245 -0
  54. package/js/factory/registry.mjs +71 -0
  55. package/js/factory/state.mjs +429 -0
  56. package/js/hosts/activity.mjs +3 -3
  57. package/js/hosts/geneseed-dir.mjs +2 -2
  58. package/js/hosts/gitref.mjs +21 -0
  59. package/js/hosts/hooks-context.mjs +71 -15
  60. package/js/hosts/hooks-done.mjs +3 -1
  61. package/js/hosts/hooks-learn.mjs +1 -1
  62. package/js/hosts/hooks-prims.mjs +271 -1
  63. package/js/hosts/hooks.mjs +409 -151
  64. package/js/hosts/hosts.mjs +22 -0
  65. package/js/hosts/installs.mjs +9 -5
  66. package/js/hosts/settings.mjs +128 -27
  67. package/js/hosts/shim.mjs +155 -7
  68. package/js/hosts/store-watch.mjs +36 -11
  69. package/js/inspect/checks-authoring.mjs +11 -1
  70. package/js/inspect/cost.mjs +91 -5
  71. package/js/inspect/diff.mjs +2 -1
  72. package/js/inspect/doctor.mjs +2 -1
  73. package/js/inspect/inventory.mjs +2 -1
  74. package/js/inspect/validate.mjs +1 -1
  75. package/js/loop/catalog.mjs +24 -12
  76. package/js/loop/cli.mjs +21 -15
  77. package/js/loop/graph.mjs +13 -4
  78. package/js/loop/registry.mjs +65 -28
  79. package/js/loop/state.mjs +18 -8
  80. package/js/maintain/migrate.mjs +2 -2
  81. package/js/maintain/uninstall.mjs +5 -1
  82. package/js/web/actions.mjs +17 -1
  83. package/js/web/api.mjs +52 -11
  84. package/js/web/catalog.mjs +38 -2
  85. package/js/web/daemon.mjs +136 -6
  86. package/js/web/handler.mjs +14 -5
  87. package/js/web/routes.mjs +12 -4
  88. package/js/web/server.mjs +4 -1
  89. package/package.json +1 -1
  90. package/registry.json +35 -0
  91. package/src/AGENT.md.tmpl +18 -24
  92. package/src/agents/_self-improvement.md +7 -6
  93. package/src/agents/developer.md +3 -2
  94. package/src/agents/docker-expert.md +1 -0
  95. package/src/agents/memory-curator.md +3 -2
  96. package/src/bricks/docs-update.md +5 -0
  97. package/src/bricks/holdout-write.md +23 -0
  98. package/src/bricks/holdout.md +25 -0
  99. package/src/bricks/intake.md +18 -0
  100. package/src/bricks/merge-gate.md +22 -0
  101. package/src/bricks/pr-open.md +21 -0
  102. package/src/bricks/retro.md +17 -0
  103. package/src/bricks/test.md +4 -1
  104. package/src/bricks/triage.md +19 -0
  105. package/src/doctrines/comms.md +29 -41
  106. package/src/doctrines/craft.md +3 -10
  107. package/src/doctrines/ops.md +4 -15
  108. package/src/doctrines/process.md +24 -19
  109. package/src/doctrines/rigor.md +1 -5
  110. package/src/factories/analysis-to-build.json +34 -0
  111. package/src/factories/bug-report-to-fix.json +32 -0
  112. package/src/factories/issue-to-pr.json +49 -0
  113. package/src/kits/ci-pipelines/rules.md +10 -0
  114. package/src/kits/ci-pipelines.json +14 -0
  115. package/src/kits/docker/rules.md +11 -0
  116. package/src/kits/docker.json +12 -0
  117. package/src/memory/README.md +5 -4
  118. package/src/modes/foreman.md +23 -10
  119. package/src/notebook/README.md +1 -1
  120. package/src/skills/_checkpoints.md +1 -0
  121. package/src/skills/_self-improvement.md +12 -9
  122. package/src/skills/adhd.md +1 -1
  123. package/src/skills/compose-ops.md +58 -0
  124. package/src/skills/factory-forge.md +97 -0
  125. package/src/skills/factory.md +126 -0
  126. package/src/skills/gitlab-ci.md +51 -0
  127. package/src/skills/jenkins-pipeline.md +56 -0
  128. package/src/skills/parallel-agents.md +1 -1
  129. package/src/skills/pipeline.md +2 -2
  130. package/src/skills/rule.md +24 -18
  131. package/src/skills/skill-forge.md +24 -6
  132. package/src/skills/workflow.md +2 -1
  133. package/themes/_TEMPLATE.json +9 -4
  134. package/themes/biker.json +9 -4
  135. package/themes/commentator.json +9 -4
  136. package/themes/cyberpunk.json +9 -4
  137. package/themes/gamer.json +9 -4
  138. package/themes/imperial.json +9 -4
  139. package/themes/joker.json +9 -4
  140. package/themes/marvin.json +9 -4
  141. package/themes/mean.json +9 -4
  142. package/themes/military.json +9 -4
  143. package/themes/neutral.json +9 -4
  144. package/themes/pirate.json +9 -4
  145. package/themes/sports.json +9 -4
  146. package/themes/verstappen.json +9 -4
  147. package/themes/wizard.json +9 -4
  148. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
  149. package/web/dist/assets/Activity-BaoxwVFH.js +1 -0
  150. package/web/dist/assets/ActivityDetail-C_bFD0rW.js +1 -0
  151. package/web/dist/assets/{Bonsai-C1iBAt4v.js → Bonsai-B01lLf0m.js} +1 -1
  152. package/web/dist/assets/{CopyButton-DJ3a4N88.js → CopyButton-Bc66KPyA.js} +1 -1
  153. package/web/dist/assets/Dashboard-X7GZzGJp.js +2 -0
  154. package/web/dist/assets/{Docs-Kffdg5uV.js → Docs-LRYVnGLG.js} +3 -3
  155. package/web/dist/assets/Factories-ARenKBiP.js +1 -0
  156. package/web/dist/assets/{GreenhouseView-k56_cBSF.js → GreenhouseView-CfWR2-sX.js} +1 -1
  157. package/web/dist/assets/{Installs-DtEKLC9h.js → Installs-nfFHnovH.js} +3 -3
  158. package/web/dist/assets/{JournalView-RQnk5l7I.js → JournalView-lpOHcHKK.js} +1 -1
  159. package/web/dist/assets/Kits-Bw5EQl_i.js +1 -0
  160. package/web/dist/assets/Laws-CnZJ0wjZ.js +4 -0
  161. package/web/dist/assets/LibRows-Hqvf1beK.js +1 -0
  162. package/web/dist/assets/Library-JaSsp6Yr.js +3 -0
  163. package/web/dist/assets/Loops-ZaHC5MVl.js +2 -0
  164. package/web/dist/assets/{OperatorHudView-CM5jNPwL.js → OperatorHudView-CggG0_sK.js} +1 -1
  165. package/web/dist/assets/Personal-BObvlb70.js +2 -0
  166. package/web/dist/assets/Settings-BFfPMPc9.js +1 -0
  167. package/web/dist/assets/Tabs-B594Pad_.js +1 -0
  168. package/web/dist/assets/api-DLDVY3K-.js +1 -0
  169. package/web/dist/assets/index-DsLmKHw0.js +6 -0
  170. package/web/dist/assets/index-DvPjphz0.css +1 -0
  171. package/web/dist/index.html +3 -3
  172. package/web/dist/assets/Activity-Ci4PZco3.js +0 -1
  173. package/web/dist/assets/ActivityDetail-C8hroCND.js +0 -1
  174. package/web/dist/assets/Dashboard-C_On4KXw.js +0 -2
  175. package/web/dist/assets/Kits-CXkEBpnf.js +0 -1
  176. package/web/dist/assets/Laws-DhhIVqmh.js +0 -3
  177. package/web/dist/assets/Library-CAUiEoJo.js +0 -3
  178. package/web/dist/assets/Loops-LKD8mF4E.js +0 -2
  179. package/web/dist/assets/Personal-B6Uoly3C.js +0 -2
  180. package/web/dist/assets/RailCats-DQxxYBEP.js +0 -1
  181. package/web/dist/assets/Settings-BTe6-wda.js +0 -1
  182. package/web/dist/assets/Tabs-CbdDWTp_.js +0 -1
  183. package/web/dist/assets/api-D_r0Jtla.js +0 -1
  184. package/web/dist/assets/index-HfGmYXab.js +0 -3
  185. package/web/dist/assets/index-ao3M-Fhm.css +0 -1
@@ -516,7 +516,7 @@ function storeScan(home, found = {}) {
516
516
  const stamp = (f) => {
517
517
  try { const s = statSync(f); if (s.isFile()) found[f] = `${s.size}:${Math.trunc(s.mtimeMs)}` } catch { /* absent */ }
518
518
  }
519
- for (const n of ["user-rules.md", "PROFILE.md", "geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) stamp(path.join(home, n))
519
+ for (const n of ["user-rules.md", "user-rules.draft.md", "PROFILE.md", "geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) stamp(path.join(home, n))
520
520
  const walk = (dir) => {
521
521
  let items = []
522
522
  try { items = readdirSync(dir, { withFileTypes: true }) } catch { return }
@@ -125,7 +125,7 @@ function isolationReport(stats) {
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
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!/protected-checks.txt\n!/done-checks.txt\n"
128
+ const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
129
129
  // Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
130
130
  // never a user edit, so it is upgraded. Any other content is the user's. Never throws.
131
131
  async function writeGitignore(file) {
@@ -198,7 +198,7 @@ async function runChildSession(client, { prompt, agent, model, title, directory
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
200
  // GENESEED_GITIGNORE in plugins/geneseed-workflow.js; both are pinned by tests.
201
- const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/protected-checks.txt\n!/done-checks.txt\n"
201
+ const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
202
202
  // Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
203
203
  // never a user edit, so it is upgraded. Any other content is the user's. Never throws.
204
204
  async function writeGitignore(file) {
@@ -143,6 +143,9 @@ const VERBS = {
143
143
  // Task 5. A fourth native verb: a state machine with
144
144
  // no recorded cell to compare against, only the absolute gates named beside it in `NATIVE`.
145
145
  loop: () => import('../js/loop/cli.mjs').then((m) => m.cmdLoop),
146
+ // The factory engine, the loop engine one level up: native like `loop`, gated absolutely by
147
+ // tests/unit/factory_cli.test.mjs.
148
+ factory: () => import('../js/factory/cli.mjs').then((m) => m.cmdFactory),
146
149
  // A fifth native verb, and a port rather than an invention: the AI Harness Scorecard
147
150
  // (upstream Python, pinned in the module's docblock). There is no recorded cell — its absolute gate is
148
151
  // tests/unit/scorecard.test.mjs. Lazy like every row: the 31 checks load only when asked.
@@ -79,13 +79,19 @@ const VERBS = {
79
79
  load: gates,
80
80
  fn: 'cmdGitGate',
81
81
  flags: HOSTED,
82
- switches: { '--no-consent': 'noConsent', '--no-deletion-gate': 'noDeletionGate' },
82
+ switches: {
83
+ '--no-consent': 'noConsent', '--no-deletion-gate': 'noDeletionGate', '--no-external-gate': 'noExternalGate',
84
+ '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
85
+ },
83
86
  },
84
87
  'rule-gate': {
85
88
  load: gates,
86
89
  fn: 'cmdRuleGate',
87
90
  flags: HOSTED,
88
- switches: { '--no-secrets-gate': 'noSecretsGate', '--no-ownership-gate': 'noOwnershipGate' },
91
+ switches: {
92
+ '--no-secrets-gate': 'noSecretsGate', '--no-ownership-gate': 'noOwnershipGate',
93
+ '--no-external-gate': 'noExternalGate', '--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore',
94
+ },
89
95
  },
90
96
  'tool-gate': {
91
97
  load: gates,
@@ -93,7 +99,8 @@ const VERBS = {
93
99
  flags: HOSTED,
94
100
  switches: {
95
101
  '--no-deletion-gate': 'noDeletionGate', '--no-secrets-gate': 'noSecretsGate',
96
- '--no-ownership-gate': 'noOwnershipGate',
102
+ '--no-ownership-gate': 'noOwnershipGate', '--no-external-gate': 'noExternalGate',
103
+ '--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
97
104
  },
98
105
  },
99
106
  learn: {
@@ -101,7 +108,10 @@ const VERBS = {
101
108
  fn: 'cmdLearn',
102
109
  // `--host` only keys the global stand-down's marker (js/hosts/hosts.mjs); learn has no dialect.
103
110
  flags: { '--memory': 'memory', '--host': 'host' },
104
- switches: { '--consolidate': 'consolidate', '--no-done-gate': 'noDoneGate' },
111
+ switches: {
112
+ '--consolidate': 'consolidate', '--no-done-gate': 'noDoneGate', '--no-test-note': 'noTestNote',
113
+ '--no-rule-store': 'noRuleStore',
114
+ },
105
115
  positional: 'file',
106
116
  },
107
117
  // UserPromptSubmit and SessionEnd: no verb runs there, and the activity view needs both.
@@ -115,11 +125,14 @@ const VERBS = {
115
125
  */
116
126
  async function baselineStores(verb, args) {
117
127
  try {
118
- if (verb !== 'context' || !args.root || process.env.GENESEED_LEARN_CHILD || isatty(0)) return;
128
+ // A SubagentStart carries the PARENT's session_id: a baseline there would reset the parent's.
129
+ if (verb !== 'context' || !args.root || args.event === 'SubagentStart' || process.env.GENESEED_LEARN_CHILD
130
+ || isatty(0)) return;
119
131
  const raw = readStdin();
120
132
  if (!raw.includes('session_id')) return;
121
133
  const { writeBaseline } = await import('../js/hosts/store-watch.mjs');
122
- writeBaseline(args.root, JSON.parse(raw).session_id);
134
+ const { session_id: sid, cwd } = JSON.parse(raw);
135
+ writeBaseline(args.root, sid, cwd);
123
136
  } catch { /* see above */ }
124
137
  }
125
138
 
@@ -164,14 +177,17 @@ function die(code, msg) {
164
177
  */
165
178
  function parse(spec, argv) {
166
179
  const args = {
167
- root: null, host: null, memory: null, consolidate: false, noConsent: false,
168
- noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false, file: null,
180
+ root: null, host: null, event: null, memory: null, consolidate: false, noConsent: false,
181
+ noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false,
182
+ noExternalGate: false, noTestNote: false, noRuleStore: false, noRootScan: false, file: null,
169
183
  };
170
184
  for (let i = 0; i < argv.length; i += 1) {
171
185
  const tok = argv[i];
172
186
  const eq = tok.indexOf('=');
173
187
  const name = tok.startsWith('--') && eq > 0 ? tok.slice(0, eq) : tok;
174
- if ((spec.switches || {})[name]) { args[spec.switches[name]] = true; continue; }
188
+ // Only the bare spelling sets a switch, and only that is emitted. `--no-external-gate=false` must
189
+ // not disarm a gate, and an argv error here would silence the whole verb, so it just does nothing.
190
+ if ((spec.switches || {})[name]) { if (tok === name) args[spec.switches[name]] = true; continue; }
175
191
  if ((spec.flags || {})[name]) {
176
192
  const value = eq > 0 && tok.startsWith('--') ? tok.slice(eq + 1) : argv[++i];
177
193
  if (value === undefined) return { error: `argument ${name}: expected one argument` };
@@ -248,6 +264,12 @@ async function main(argv) {
248
264
  // `hooks.md`, "Stop, SubagentStop, TaskCompleted, and TeammateIdle").
249
265
  return die(1, parsed.error);
250
266
  }
267
+ // `context` answers SessionStart and SubagentStart (settings.mjs), told apart by the payload's
268
+ // event name. Read here, not in the verb, so an in-process caller never blocks on fd 0; the read
269
+ // is cached, so `trackActivity` reuses it. A terminal sends no payload.
270
+ if (verb === 'context' && !isatty(0)) {
271
+ try { parsed.args.event = JSON.parse(readStdin() || '{}').hook_event_name ?? null; } catch { /* not JSON: SessionStart */ }
272
+ }
251
273
  const rc = (await spec.load())[spec.fn](parsed.args);
252
274
  await trackActivity(verb, parsed.args);
253
275
  await baselineStores(verb, parsed.args);
package/docs/PRD.md CHANGED
@@ -103,7 +103,7 @@ sequenceDiagram
103
103
  | NFR-001 | No runtime dependencies. | 0 installed; vendored only | `tests/unit/dependency_policy.test.mjs` | ✅ | `js/vendor/` |
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
- | NFR-004 | The rules file stays within its size ceiling. | 41 612 lean, 66 432 full | `CARRIER_CEILING` | ✅ | `js/inspect/cost.mjs` |
106
+ | NFR-004 | The rules file stays within its size ceiling. | 40 312 lean, 66 432 full | `CARRIER_CEILING` | ✅ | `js/inspect/cost.mjs` |
107
107
  | NFR-005 | The generator and hook path cannot spawn beyond what is declared. | No `child_process` on the generator; one spawn site on the hook path | Closure walks | ✅ | `tests/unit/hook_cli.test.mjs` |
108
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` |
package/docs/README.md CHANGED
@@ -29,6 +29,7 @@
29
29
  | Set up | [Connect your wiki](guides/wiki.md) | Giving the agent your own notes, machine-wide |
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
+ | Factories | [Run a factory](guides/run-a-factory.md) | Carrying one bug report or issue to an open PR with green CI |
32
33
  | Keep it running | [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
33
34
  | 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 |
34
35
  | Keep it running | [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
@@ -49,9 +50,11 @@
49
50
 
50
51
  **Loops** — [Loops](concepts/loops.md) · [Templates](concepts/loop-templates.md) · [Bricks and their origins](concepts/loop-bricks.md) · [Notes and rules](concepts/loop-notes.md) · [Risk, trust and validation levels](concepts/loop-risk.md) · [Human gates](concepts/loop-gates.md) · [Contracts and ignored deletions](concepts/loop-contracts.md) · [LOOP.md, trailers and the loop branch](concepts/loop-branch.md)
51
52
 
53
+ **Factories** — [Factories](concepts/factories.md)
54
+
52
55
  ## 4 · Reference
53
56
 
54
- **CLI & environment** — [CLI](reference/cli.md) · [Loop actions](reference/loop-actions.md) · [Environment variables](reference/environment.md) · [Context and memory variables](reference/env-context.md)
57
+ **CLI & environment** — [CLI](reference/cli.md) · [Loop actions](reference/loop-actions.md) · [Factory actions](reference/factory-actions.md) · [Environment variables](reference/environment.md) · [Context and memory variables](reference/env-context.md)
55
58
 
56
59
  **Troubleshooting** (by symptom) — [Overview](reference/troubleshooting.md) · [Install](reference/troubleshoot-install.md) · [Hooks, context and memory](reference/troubleshoot-hooks.md) · [Model, agents and MCP](reference/troubleshoot-tools.md) · [Updating](reference/troubleshoot-update.md) · [Doctor findings](reference/troubleshoot-doctor.md) · [Web console](reference/troubleshoot-web.md)
57
60
 
@@ -23,11 +23,11 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
23
23
  |---|---|---|---|---|---|
24
24
  | `sealed-secrets` | law | ask: rule-gate (credential-shaped content outside `.env*`). Switchable per install with `--no-secrets-gate` (see [Exclusions](exclusions.md)): this scan stands down on every host, the guard plugin's path block included | same as Claude Code | block: guard plugin (key/credential file path, or vendor-prefixed secret content); warns only on `.env*` | block (exit 2) |
25
25
  | `deletion-is-deliberate` | law | ask: git-gate, only on real data loss judged against the repository's state (the list in [Hooks](hooks.md): a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, the reflog pruned, files git cannot restore removed); asks when it cannot verify. Switchable per install with `--no-deletion-gate` (see [Exclusions](exclusions.md)): the real-loss check and the Law IV `permission.bash` keys stand down, everything else in this table stays **+** ask: git-gate, catastrophic shell (`rm -rf` of `/`, a drive root or `~`, `mkfs`, `dd` over a raw disk, `format`, fork bomb), whatever the state and even with the switch off | same as Claude Code | ask: permission prompt (`git reflog expire*`, `git gc --prune*`, a force push or delete of `main`/`master` by name) **+** block: guard plugin (catastrophic shell, the hook's check plus its own stricter text match: `rm -rf` of `/`, a drive root or `~`, fork bomb, `format`, `dd` over a raw disk) **+** block: guard plugin (every other real-loss case, the same state-aware decisions as the hook) | block (exit 2) |
26
- | `persist-insight` | process | ask: rule-gate (a write to `user-rules.md`, `user-rules.draft.md` or a memory store, shared one included) | same as Claude Code | ask: OpenCode's own prompt (`permission.edit`, and `evaluate` on OpenCode 2); the guard plugin refuses a file-tool write the host cannot prompt for | block a file-tool write: exit 2, no ask tier; a parsed shell write only warns |
27
- | `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed | log only |
26
+ | `persist-insight` | process | ask: rule-gate (a write to `user-rules.md` or `user-rules.draft.md`; memory is written freely, and the [change report](hooks.md#the-change-report) and the web console show it). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules`: the hook goes on every host (`--no-rule-store`), OpenCode's `permission.edit` keys on the rule files too. The change report still lists rule-file changes | same as Claude Code | ask: OpenCode's own prompt (`permission.edit`, and `evaluate` on OpenCode 2); the guard plugin refuses a file-tool write the host cannot prompt for | block a file-tool write: exit 2, no ask tier; a parsed shell write only warns |
27
+ | `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). A sub-agent's commit or merge (`agent_id` in the payload) in a linked worktree, on a branch that is not shared, passes: a Foreman worker's own batch ([Foreman mode](foreman-mode.md) has the exact conditions). A git hook or `core.hooksPath` that pushes on commit is not seen. A push, or a command that mixes one in, still asks. Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed. A glob sees only the command, never the worktree, so a worker's commit still asks | log only |
28
28
  | `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list, or to a gate's own configuration: hook settings, `excludes.json`, `AGENT.md` gate markers, the hook shim) | same as Claude Code | ask: OpenCode's own `permission.edit` rules, written by the emit (every `opencode.json(c)`, the hook settings, the install's `AGENT.md`, `excludes.json`, manifest, plugins, the hook shim); block: guard plugin (the protected-checks list, and the other hosts' Geneseed-only files) | block (exit 2), writes only; a hook `settings.json` only when the edit changes Geneseed's own hook entries |
29
29
  | `verify-before-asserting` | law | block at Stop, once per turn: the done gate in `learn` (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (**unverified live**: a frozen fork, and no check runs a model turn) | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
30
- | `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
30
+ | `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`). Togglable: build without the ops pack, or drop this rule alone with `--exclude-rules`: the check goes on every host (`--no-root-scan`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
31
31
 
32
32
  Bob has no "ask" tier (see [ADR 0007](../adr/0007-gates-fail-closed-per-host-ceiling.md)), so a
33
33
  rule the other hosts only ask about either blocks outright on Bob or degrades to a log line.
@@ -35,6 +35,16 @@ Never a silent pass; Bob runs every gate above through one fused command, `tool-
35
35
  on the payload shape rather than on separate matchers. OpenCode enforces through two separate
36
36
  mechanisms: its own permission prompt (`opencode.json`, static globs) and the guard plugin
37
37
  (`tool.execute.before`, pattern matching); a rule can use either or both.
38
+
39
+ `persist-insight` and `external-gate` also read a shell command's parsed forms on every host: a
40
+ redirect, `tee`, `sed -i`, `cp`, `mv`, `rm`, and the PowerShell writers `Add-Content`, `Set-Content`,
41
+ `Out-File`, `Clear-Content`, `Remove-Item`, `Copy-Item`, `Move-Item`, `New-Item`, `Rename-Item` with
42
+ the aliases `ac`, `sc`, `del`, `copy`, `move`, `ni` and `ren`. A parsed write to a store asks on
43
+ Claude Code, OpenClaude and OpenCode 2, is refused on OpenCode 1, and only warns on Bob. **Shell is
44
+ not a boundary:** `bash -c`, `pwsh -c`, an interpreter and a variable stay unread, so the host's own
45
+ command permission is the backstop, and the [change report](hooks.md#the-change-report) tells you
46
+ afterwards.
47
+
38
48
  See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) for why a gate that only
39
49
  one host can run still ships for every host it can.
40
50
 
@@ -47,6 +57,15 @@ and the next write passes. Off per repo with `mode: off`, for one developer with
47
57
  `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`, per install with
48
58
  `--no-ownership-gate` ([Exclusions](exclusions.md)).
49
59
 
60
+ ### Switches on two rows above
61
+
62
+ `--no-external-gate` stops every ask and refusal in the `external-gate` row, on every host, except
63
+ OpenCode's own `permission.edit` keys, which are host configuration and keep asking. It does not
64
+ touch the rule's text: `--exclude-rules rigor.5` does that, and leaves the hook asking.
65
+ `--no-test-note` stops the advisory weakened-test note that *Cure the Cause* carries at edit time
66
+ and at turn end, on every host. That note asks nothing and blocks nothing, so the rule stays
67
+ outside the hook-pinned ids. See [Exclusions](exclusions.md).
68
+
50
69
  | Gate | Claude Code | OpenClaude | OpenCode | Bob |
51
70
  |---|---|---|---|---|
52
71
  | ownership | deny once: rule-gate (`Write`/`Edit`/`NotebookEdit`; sub-agents defer) | same as Claude Code | block once: guard plugin (a child session defers) | block once (exit 2): tool-gate (sub-agent deferral unverified) |
@@ -78,7 +97,7 @@ follow them, not because a tool call was ever inspected.
78
97
  `prove-the-gate`.
79
98
 
80
99
  **Doctrine: comms** — `codes-that-persist` · `structure-beside-prose` · `declare-the-judgment-calls` ·
81
- `simplified-technical-english` · `mark-the-ask`.
100
+ `simplified-technical-english`.
82
101
 
83
102
  ---
84
103
 
@@ -56,7 +56,17 @@ The finer switch removes a single doctrine rule from an install while keeping th
56
56
  geneseed build --emit claude-global --exclude-rules "process 7"
57
57
  ```
58
58
 
59
- The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded. Picking packs and rules is covered in [Doctrine packs and single rules](../guides/setup-doctrines.md); what the layers are is in [Rules](rules.md).
59
+ The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. If a later version retires the rule (comms 5 merged into comms 1 on 2026-11-08), the rebuild prints a WARN, drops that address, and goes on. The always-on Rules and the Ethos cannot be excluded.
60
+
61
+ **A hook goes with its rule.** Three doctrine rules are also enforced by a hook with no switch of its own, and excluding the rule, or building without its pack, drops that hook in the same rebuild. Including the rule again re-arms it at the next rebuild.
62
+
63
+ | Rule | What stops | Flag |
64
+ | --- | --- | --- |
65
+ | process 5, *Consent Before Push* | the commit/push ask of `git-gate` and OpenCode's `git commit*`/`git push*` keys. Bob keeps its warning line | `--no-consent` |
66
+ | process 1, *Persist Insight* | the ask (on Bob the block or warning) on a write to `user-rules.md` or `user-rules.draft.md`, by write tool or parsed shell write, the hard-link check included: `rule-gate`, `git-gate`, Bob's `tool-gate`, the OpenCode guard, and OpenCode's `permission.edit` keys on those files | `--no-rule-store` |
67
+ | ops 2, *Commands Must Return* | the root-scan check of `git-gate`, Bob's `tool-gate` and the OpenCode guard | `--no-root-scan` |
68
+
69
+ Every other check of those hooks stays. The [change report](hooks.md#the-change-report) keeps reporting rule-file changes: with process 1 off, a rule write ran with no prompt, so it is never counted as approved. **With process 1 off, that report is the only signal that the agent changed your standing rules.** It detects and prevents nothing, and it can be fooled: the agent can write `memory/.own-writes.json`, the log of Geneseed's own writes, so a change it lists is excused. The OpenCode guard reads the same state from the install's `Active packs:` and `Excluded rules:` lines when it starts, so restart OpenCode after a rebuild. While the machine's hook shim points at an older checkout, that checkout refuses a flag it does not know and the gate verb lets every call through; run `geneseed rebuild-all` first. Rigor 5 is the exception: it has a switch of its own (below). Picking packs and rules is covered in [Doctrine packs and single rules](../guides/setup-doctrines.md); what the layers are is in [Rules](rules.md).
60
70
 
61
71
  ### Per-skill exclusion — skills you never use
62
72
 
@@ -97,7 +107,7 @@ geneseed build --emit claude-global --no-secrets-gate # Sealed Secrets
97
107
  geneseed build --emit claude-global --no-done-gate # Verify Before Asserting
98
108
  ```
99
109
 
100
- The console's Constitution page has a switch on Rule I's and Rule III's rows too (*Enforced by* reads **Gate off** while one is off); the other Rules show *no gate*, because only their text enforces them. The install records `Secrets gate: off` / `Done gate: off` beside `Deletion gate:`, written only when off; rebuilds, upgrades and `geneseed status` carry them like Law IV's.
110
+ The console's Constitution page has a switch on Rule I's and Rule III's rows too (*Enforced by* reads **Gate off** while one is off); Rule VIII has one for the [test note](#external-gate-and-the-test-note--on-or-off), and the other Rules show *no gate*, because only their text enforces them. The install records `Secrets gate: off` / `Done gate: off` beside `Deletion gate:`, written only when off; rebuilds, upgrades and `geneseed status` carry them like Law IV's.
101
111
 
102
112
  What stops, per host:
103
113
  - **`--no-secrets-gate`**: the credential scan of `rule-gate` (Claude Code, OpenClaude) and of `tool-gate` (Bob, which then no longer exits 2 for it), and on OpenCode the guard plugin's *Sealed Secrets* block — both the key/credential file path block and the content scan. *External Gate*, *Persist Insight*, the deletion gate and the root-scan check stay.
@@ -105,6 +115,42 @@ What stops, per host:
105
115
 
106
116
  Limits: OpenCode reads both switches from the install's `AGENT.md` when it starts, so restart it after flipping one. A global install beside a project install: `rule-gate` and Bob's `tool-gate` do not stand down for a project install on any host, and neither does the OpenCode guard, so an armed global install still asks about (or blocks) a credential write inside a project whose own install has the secrets gate off. `learn` does stand down on Claude Code and OpenClaude, so there the project's done gate switch decides. And the older-shim limit above is sharper for the done gate: its flag rides on `learn`, so while the shim points at an older checkout an install with the done gate off **loses learning too**, not only the gate. Run `geneseed rebuild-all` before switching either gate off.
107
117
 
118
+ ### External Gate and the test note — on or off
119
+
120
+ Two more switches. Both are armed by default and written only when off, so an armed install does not change.
121
+
122
+ ```bash
123
+ geneseed build --emit claude-global --no-external-gate # protected checks, gate configuration
124
+ geneseed build --emit claude-global --no-test-note # the weakened-test note
125
+ ```
126
+
127
+ The install records `External gate: off` / `Test note: off` beside the other gate markers. Rebuilds, upgrades and `geneseed status` carry them. Any other value reads as armed. `doctor --probe` is unaffected: it sends a shell command that neither switch judges.
128
+
129
+ **Run `geneseed rebuild-all` before you switch either one off.** The flags are new. While the machine's shared hook shim points at an older checkout, that checkout refuses the flag, and the gate verb then lets every call through: every gate on that verb is silent, not only this one.
130
+
131
+ What stops, per host:
132
+ - **`--no-external-gate`**: the protected-check and gate-configuration asks of `rule-gate` and of the shell path in `git-gate` (Claude Code, OpenClaude), the same blocks in `tool-gate` (Bob, which then no longer exits 2 for them), the OpenCode guard's refusals on its write and shell paths, and the `evaluate` ask over a gate's own file on OpenCode 2. Every other gate keeps running: secrets, real loss, root scans, the rule-store check, the wiki check and commit/push consent. The guard also keeps refusing an NTFS stream path, because that check protects every path gate.
133
+ - **`--no-test-note`**: the "this edit weakens a test" note at edit time (`rule-gate`, Bob's `tool-gate`), the `[done-gate] advisory` line at turn end (`learn`), and the OpenCode context plugin's reminder on both OpenCode versions. The done checks do not change. `--no-done-gate` still silences the turn-end line and the OpenCode reminder by itself, and it leaves the edit-time note on the hook hosts.
134
+
135
+ **What stays on OpenCode.** The `permission.edit` "ask" keys in `opencode.json` are host configuration, so `--no-external-gate` does not remove them. OpenCode keeps asking before an edit tool writes those files, and you remove the keys by hand if you want that gone. The guard no longer refuses them after an "always" answer, and no longer refuses a shell write to them.
136
+
137
+ **What this switch costs.** External Gate is what stops an agent from editing the gates' own wiring. With it off, the agent can write hook settings, the `AGENT.md` gate markers and `.geneseed/done-checks.txt` without an ask, so every other gate holds only while the agent leaves that wiring alone. Switch it off only where you accept that.
138
+
139
+ **The doctrine and the switch are two axes.** `--exclude-rules rigor.5` takes the rule's text out of the carrier. `--no-external-gate` stops the hook. Neither moves the other:
140
+
141
+ | Rule text (`--exclude-rules`) | Hook (`--no-external-gate`) | Result |
142
+ | --- | --- | --- |
143
+ | In | Armed | The agent is told, and the write asks |
144
+ | Excluded | Armed | The agent is not told, and the write still asks |
145
+ | In | Off | The agent is told, and nothing asks |
146
+ | Excluded | Off | Neither |
147
+
148
+ The console's Constitution page shows both on the same doctrine row: the row's own switch is the rule, and the *External gate* line inside the opened row is the hook. The test note's switch sits on Rule VIII's row, which reads *Hook gate* or **Gate off**. Each gate switch rebuilds at once; the rule switch stages with the other doctrine changes.
149
+
150
+ **Where a marker counts.** In a `CLAUDE.md` or `AGENTS.md`, which are your files, every gate marker counts only inside the `<!-- BEGIN GENESEED -->` block. A marker line outside it reads as armed, and a rebuild does not carry it. A generated `AGENT.md` or `rules/geneseed.md` counts whole, and External Gate protects both. Under External Gate, a write tool aimed at a `CLAUDE.md` or `AGENTS.md` is replayed, and the first block is compared before and after. Any difference asks (on Bob it blocks, and the OpenCode guard refuses). So does a call that cannot be replayed, an unreadable file, or a file over 1 MB. An edit wholly outside the block stays silent, so your own notes there are not interrupted. The name is normalized first, so `CLAUDE.md::$DATA` and `CLAUDE.md.` count as `CLAUDE.md`. A shell edit inside the block does not ask, and neither does a shell edit that puts a fake block before the real one, because only the first block is read. That is a limit: the hook has no replay for a shell write.
151
+
152
+ Limits, as for the gates above: OpenCode reads both markers from `AGENT.md` when it starts, so restart it after a rebuild. `rule-gate` and Bob's `tool-gate` do not stand down for a project install on any host, so an armed global install still asks inside a project built with the switch off. Only `git-gate` stands down, on Claude Code and OpenClaude.
153
+
108
154
  ### Ownership gate — on or off
109
155
 
110
156
  The [ownership](ownership.md) first-write gate is not a Rule's gate: it stops the first file write of a session, once, in an application repo whose root `AGENTS.md` has no `## Ownership` section, so the agent proposes the setup first. It is armed by default. Switch it off for one install:
@@ -0,0 +1,151 @@
1
+ ---
2
+ group: concepts
3
+ kind: "concept"
4
+ section: "Factories"
5
+ order: 24.5
6
+ title: "Factories"
7
+ link: {"hash":"#/docs/factory-actions","label":"The geneseed factory actions →"}
8
+ description: "What a factory is: one work item carried through bricks and whole loops to an open PR, with routes back when CI fails."
9
+ ---
10
+ To run one, see [Run a factory](../guides/run-a-factory.md).
11
+
12
+ A **factory** carries one work item (a request, a document or analysis, or a GitHub or GitLab
13
+ issue) through a graph of **stages** to an open pull request with green CI. A stage is a
14
+ [brick](loop-bricks.md) or a whole [loop](loops.md). `geneseed factory` is the state machine: it
15
+ decides every transition, cycle count and stop, and the `factory` [skill](skills.md) runs the stage
16
+ it is handed. **A run never merges.** It ends at "PR open, CI green", and the merge is yours.
17
+
18
+ > **You already know this:** a ticket moving across a board — triaged, worked, reviewed, shipped
19
+ > for review. A failed check sends the card back a column, but only so many times before someone
20
+ > has to look at it.
21
+
22
+ ## Stages, and the routes back
23
+
24
+ A factory is the loop graph one level up. Each stage reports an outcome, and each outcome has
25
+ one edge: to the next stage, to `$close`, or to `$stop`. A `loop:<name>` stage runs a whole loop
26
+ in the same worktree and reports `pass` when that loop closed, `fail` when it stopped.
27
+
28
+ A failure may route back to an earlier stage: red CI at `merge-gate` sends the work back to the
29
+ loop that wrote it. Every such route sits inside a declared **cycle** with a `max` (5 at most).
30
+ Each lap back to the cycle's first stage spends one; past the `max`, the run stops. A route back
31
+ always starts a **fresh** loop: a new `LOOP.md`, whose first note is the reason the last lap
32
+ failed. When two cycles share that first stage, the lap spends the smallest one that holds the
33
+ stage it came from: a failed `holdout` spends `holdout`, a red `merge-gate` spends `ci`. The commits made before stay on the branch. A run also stops after 30 stage transitions,
34
+ whatever its cycles say.
35
+
36
+ `geneseed factory check` refuses a factory before any stage runs: an unknown brick or loop, an
37
+ outcome with no edge, a `$close` nothing reaches, a cycle with no `max`, a cycle entered anywhere
38
+ but its first stage, or a route back that spends no cycle.
39
+
40
+ ## Forks and lanes
41
+
42
+ A **fork** is where the work takes one way or another. It is a brick that declares **named
43
+ outcomes**, any outcome other than `pass`, `fail`, `error` or `none`. `triage` is one: `bug`,
44
+ `feature`, `deps`, `refactor`, `docs` and `fail`. Each named outcome has its own edge to its own
45
+ stage, its **lane**, and the outcome the brick reports picks the lane. `geneseed factory next`
46
+ hands the fork its `lanes`: each outcome with the stage it leads to.
47
+
48
+ Not every factory runs a loop, and not every lane is one. A loop is the lane for work that
49
+ changes code, because the loop carries the test → fix → verify proof. A brick is the lane where a
50
+ loop adds nothing: in `issue-to-pr`, `docs` goes to the `docs-update` brick, which commits its own
51
+ change. Every lane joins the same path after it: `holdout`, then `pr-open` and `merge-gate`.
52
+
53
+ A route back after a fork targets **`$lane`**: the stage the run's most recent fork chose. The
54
+ engine records it in `FACTORY.md` when the fork's outcome is recorded, and an edge to `$lane` goes
55
+ there. A cycle may start at `$lane` too, and each route back to it spends one lap, as any route
56
+ back does. `check` refuses `$lane` in a factory with no fork, or where some path reaches it before
57
+ any fork. In its other checks, `$lane` stands for every lane, so a graph that passes holds for the
58
+ lane any run takes.
59
+
60
+ A factory written before forks used a `loop:$triaged` stage and a `loops` list. Both are retired:
61
+ `check` names each with its replacement, and the doctor reports it. Nothing rewrites your file.
62
+
63
+ ## One worktree, two state files
64
+
65
+ A run works on its own branch, `loop/factory-<slug>`, in its own worktree. `FACTORY.md` at the
66
+ root holds the run's state; while a loop stage runs, its `LOOP.md` sits beside it. The loop
67
+ engine treats `FACTORY.md` as bookkeeping, as it treats `LOOP.md`: it never scores it. A stage
68
+ that is not a loop records only on a clean worktree, and `factory record` refuses a dirty tree
69
+ after one. A brick that changes files, such as a `docs-update` lane, commits them first. The one
70
+ exception is the run's spec, `specs/<slug>/spec.md`: the `spec` stage writes it, and
71
+ 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
72
+ names the run it belongs to.
73
+
74
+ ## The shipped factories
75
+
76
+ | Factory | Stages |
77
+ | --- | --- |
78
+ | `analysis-to-build` | `intake` → `spec` → `holdout-write` → `loop:feature` → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. `spec` writes `specs/<slug>/spec.md` with an ordered task list, and you approve it at its gate. `loop:feature` then runs once per task, in order, in the same worktree, and one PR opens at the end. A failed `holdout` or a red `merge-gate` sends the work back to `loop:feature` as one extra task, twice at most each (cycles `holdout` and `ci`) |
79
+ | `bug-report-to-fix` | `intake` → `holdout-write` → `loop:bugfix` → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. A failed `holdout` or a red `merge-gate` sends the fix back to `loop:bugfix`, twice at most each (cycles `holdout` and `ci`) |
80
+ | `issue-to-pr` | `intake` → `holdout-write` → `triage`, a fork → one lane → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. `triage` reports the lane: `bug` → `loop:bugfix`, `feature` → `loop:feature`, `deps` → `loop:deps-upgrade`, `refactor` → `loop:refactor`, `docs` → the `docs-update` brick. A failed `holdout` or a red `merge-gate` sends the work back to `$lane`, that same lane, twice at most each (cycles `holdout` and `ci`) |
81
+
82
+ The bricks they add:
83
+
84
+ | Brick | Does | Outcomes |
85
+ | --- | --- | --- |
86
+ | `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria | `pass`, `fail` |
87
+ | `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` |
88
+ | `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` |
89
+ | `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` |
90
+ | `pr-open` | Pushes the branch (the push asks you) and opens the PR, or updates the one already open | `pass`, `fail` |
91
+ | `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 | `pass`, `fail`, `none` |
92
+ | `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, and keeps only a lasting lesson in memory | `pass` |
93
+
94
+ `analysis-to-build` also uses the loops' own `spec` brick (`gate: human`), the one the
95
+ `spec-first-feature` loop starts with, and `issue-to-pr` the loops' `docs-update` brick as its
96
+ docs lane.
97
+
98
+ The run report is git-ignored by the `.geneseed/.gitignore` Geneseed seeds. Where no such file is
99
+ in the worktree, `retro` writes the report to the OS temp directory instead, so the tree stays
100
+ clean. The report lives in the worktree and goes when you remove it.
101
+
102
+ ## Holdout scenarios
103
+
104
+ A loop's tests are written by the same agent that writes the code, so they can share its
105
+ blind spots. A factory therefore keeps a second set of checks the developer never sees. After
106
+ `intake` (or `spec`), the `holdout-write` stage writes 3 to 8 scenarios in plain prose, each a
107
+ `Given` / `When` / `Then`, to `~/.config/geneseed/holdout/<slug>/` (under `$XDG_CONFIG_HOME` when
108
+ it is set): outside the worktree, so no commit, diff or loop note carries them. After the loop,
109
+ the `holdout` stage plays each scenario against the change as built and reports.
110
+
111
+ - **On a failure**, the work goes back to the loop with one sentence per failed scenario: what was
112
+ observed against what was expected. Never the scenario's text. That lap spends the `holdout`
113
+ cycle, twice at most.
114
+ - **On `error`**, the run stops: the diff touches the holdout folder, or a scenario cannot be
115
+ played.
116
+ - **One folder per slug.** `holdout-write` reports `fail` when the folder already holds files from
117
+ an earlier run with the same slug; clear it yourself, then run again.
118
+ - **Who sees them.** Both stages run as the `tester` agent. The `factory` skill never puts holdout
119
+ content or the folder's path into a brief, a note or a carry.
120
+ - **No hook refuses a read of it**, on any host. A Claude Code read gate was built but is not
121
+ shipped: it would run a hook process on every Read, Grep and Glob of every session (about 90 ms
122
+ each on Windows) for a protection only a factory run uses. The folder is protected only by its place
123
+ outside the worktree, by `holdout`'s `error`, and by the skill's rule. A shell command such as
124
+ `cat` is not covered on any host.
125
+
126
+ ## In the console
127
+
128
+ The console's **Factories** page (in the Build group, after Loops) draws each factory as a
129
+ graph: its stages left to right, a `loop:` stage as a block that holds its loop's ring, each
130
+ route back as an arc above the row with its cycle and `max`, and `close` and `stop` as end caps.
131
+ Its **Active** tab lists every registered run, with the current stage lit, the laps spent on
132
+ each cycle and the child loop's current step. 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
133
+ agent's session.
134
+
135
+ ## Your own factories
136
+
137
+ Factories load from three levels, as bricks and loop templates do, and a later level overrides
138
+ an earlier one by name: shipped, global (`~/.config/geneseed/factories/`), and project
139
+ (`<repo>/.geneseed/factories/`).
140
+
141
+ To compose or change one, use the `factory-forge` skill — ask it. It interviews you for the
142
+ stages, the routes back and their `max`, writes the file at project or global level and runs
143
+ `geneseed factory check` until it passes. When a stage needs a brick that does not exist, it
144
+ offers the `brick-forge` skill: that skill alone writes bricks.
145
+
146
+ ## Read on
147
+
148
+ - [Run a factory](../guides/run-a-factory.md): how to start one, and what it asks you.
149
+ - [Loops](loops.md): what runs inside a `loop:` stage.
150
+ - [Human gates](loop-gates.md): the stages that wait for a person.
151
+ - [Factory actions](../reference/factory-actions.md): the `geneseed factory` commands.
@@ -30,10 +30,25 @@ When the session is unsure, it delegates. The test is still a count, because "su
30
30
 
31
31
  A task worker is one `developer` agent in its own git worktree. It explores, implements and tests in a single context, loading skills as it needs them, so nothing it read is lost in a hand-off. After two repair rounds on its own failing tests it returns with its findings instead of looping.
32
32
 
33
+ A worker can lead a small team inside its own worktree. It can start read-only helpers (`explorer`, `researcher`) at any time. It can also start writing **sub-workers**, each in its own worktree branched from the worker's branch. The worker commits and merges their branches into its own branch, locally, and re-runs the proof after each merge. *Consent Before Push* names this as a batch. The git gate lets a commit or merge through without a prompt only when all of these hold: the host marks the call as a sub-agent's (Claude Code's `agent_id`), the directory is a linked worktree, and its branch is not shared (`main`, `master`, `develop`, `development`, `release/*`, `hotfix/*`, a remote's default, or the branch the main checkout has, in any letter case). The command may hold only adds, read-only git commands and plain commit or merge arguments with one quoted message, after at most one `cd`; anything that can run a second command (`(`, `@`, `$`, `{`, a backtick) asks. A session that only runs in a worktree, as the desktop app's do, still asks. A push still asks everywhere. Bob sends no sub-agent field, so Bob still logs its warning. On OpenCode the static `git commit*` permission still asks, because a permission glob sees only the command, not the worktree. The gate reads the command, not git's own hooks: a `post-commit` hook or a `core.hooksPath` can push on commit, on any branch, as it always could. Nesting stops at two levels below the session: session → worker → sub-worker. A sub-worker starts nothing. A lead holds every member's result before it ends. The blind reviewer is still the session's, never the worker's.
34
+
35
+ | Host | What caps the depth |
36
+ | --- | --- |
37
+ | Claude Code | the install writes `env.CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH = "2"` into its settings file, only when the key is absent (Claude Code allows three levels by default) |
38
+ | OpenCode | the install writes a top-level `"subagent_depth": 2` into `opencode.json`, only when the key is absent |
39
+ | OpenClaude | nothing in the host: its source has no such cap (checked on 0.31). The rule text is the only bound |
40
+ | Bob | nothing documented. The rule text is the only bound |
41
+
42
+ A value you set yourself is kept. The value 2 is read as session → worker → sub-worker; that reading is the design's, not yet observed live on either host.
43
+
33
44
  When a worker returns green with a diff that touches two or more files or changes logic, the session sends a `reviewer` only your request and the diff — never the worker's reasoning — for a blind check. A failing verdict goes back to the same worker.
34
45
 
35
46
  The session keeps a ledger in its notebook (`notebook/foreman-ledger.md`), one line per task: the task, the agent id, the worktree and the state. A correction, a follow-up or a reviewer finding goes back to **the same worker**, which resumes with everything it already knows. A new worker starts only when the old one cannot be resumed, and it receives a note of the ask, the diff so far and what was tried. A worker serves one task and retires once that task is merged or dropped.
36
47
 
48
+ ### Status lines
49
+
50
+ A worker reports one line at start and on each change: `T<n> · <task> · files: <write set> · <state>`. On Claude Code it sends that line to the session with `SendMessage`; OpenClaude can do the same only in its agent-teams mode. OpenCode and Bob have no channel back to the session, so there the worker writes the line to its own file, `notebook/foreman/<task>.status`, which no other agent writes. The session reads all status files with one command, and only at two moments: before it starts a worker near the same files, and when a worker returns. When two write sets overlap, the session decides: one worker waits, or one worker owns the file. It records that decision in the ledger.
51
+
37
52
  > **Why not a crew by default?** Splitting a task by role — one agent reads, the next builds, the next tests — passes each result on as a summary, and the next agent reads the code again. Anthropic's guide [When to fold subagents into your main agent loop](https://claude.com/resources/articles/building-agents-when-to-fold-subagents-into-your-main-agent-loop) found one loop with skills usually beats that, and keeps separate agents for verification, parallel work and context that would overflow. The blind reviewer is that kind of split.
38
53
 
39
54
  ### What a pipeline is
@@ -53,15 +68,15 @@ The crew works in its own git worktree and branch. When worktrees are unavailabl
53
68
 
54
69
  Inside the crew, the developer implements and the tester runs the tests and lint. Failures go back to the developer for at most two repair rounds, then to one fresh developer carrying the tester's findings; if that fails too, the crew stops and reports the failure, leaving the branch for you to inspect.
55
70
 
56
- ### Neither commits nor merges
71
+ ### Nothing lands beyond the worker's branch
57
72
 
58
- When a worker or a crew is done, it hands back its worktree **uncommitted**, with the raw test and lint output and the list of files it changed. Then the session:
73
+ When a crew is done, it hands back its worktree **uncommitted**. A worker hands back its branch: the local commits from its own sub-workers' merges, and any uncommitted work. Each comes with the raw test and lint output and the list of files it changed. Then the session:
59
74
 
60
75
  1. re-runs the tests and lint itself — its log is its own account, not proof;
61
- 2. shows you the diff and the green output;
76
+ 2. shows you the diff from the base it recorded, and the green output;
62
77
  3. commits and merges **only once you accept**.
63
78
 
64
- Commit, push and merge belong to the session alone, under *Consent Before Push* ([Rules](rules.md)). A worker or crew that cannot get to green reports back instead of landing broken work.
79
+ Push, and every merge beyond a worker's own branch, belong to the session alone, under *Consent Before Push* ([Rules](rules.md)). A worker or crew that cannot get to green reports back instead of landing broken work.
65
80
 
66
81
  You can also start a pipeline without foreman mode: ask the agent to "run a pipeline" for a task, and the `pipeline` [skill](skills.md) takes it from there.
67
82
 
@@ -37,7 +37,7 @@ The merge is surgical. Every other key and every hook of your own survive, and t
37
37
  **Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher or `SubagentStop`. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet. So Bob gets four hooks:
38
38
 
39
39
  - `SessionStart` → `geneseed-hook context`.
40
- - `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all. The [ownership](ownership.md) gate also exits 2, but only once per session and repo: the same write passes after the developer answers.
40
+ - `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push check and a shell write to a rule store become a warning line, because a hard block would leave Bob unable to commit at all. The [ownership](ownership.md) gate also exits 2, but only once per session and repo: the same write passes after the developer answers.
41
41
  - `Stop` → `geneseed-hook learn`.
42
42
  - `UserPromptSubmit` → `geneseed-hook activity`, which records the turn for the Activity view.
43
43