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
@@ -18,13 +18,13 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
18
18
  | --- | --- | --- | --- | --- |
19
19
  | `SessionStart` | `startup`, `resume`, `clear`, `compact`, `fork` | `geneseed-hook context` | injects your harness files and the repo's docs, or re-injects them after a resume, a fork, or an auto-compaction summarised them away | no |
20
20
  | `PreToolUse` | `Bash`, `PowerShell` | `geneseed-hook git-gate` | asks before a command that would really lose data, and before a recursive scan of a whole filesystem; asks before every commit and push | the commit/push question only |
21
- | `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your rules or memory; stops the session's first write once in an application repo with no `## Ownership` section | no |
21
+ | `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your standing rules; stops the session's first write once in an application repo with no `## Ownership` section | no |
22
22
  | `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into the memory store | needs `GENESEED_LLM` |
23
23
  | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in the store's `agents/<name>.md` | needs `GENESEED_LLM` |
24
24
  | `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
25
25
  | `UserPromptSubmit` | you send a message | `geneseed-hook activity` | records the turn's start for the web console's Activity view; prints nothing | off with `GENESEED_ACTIVITY=off` |
26
26
  | `SessionEnd` | the session closes | `geneseed-hook activity` | marks the session ended and archives it | off with `GENESEED_ACTIVITY=off` |
27
- | `SubagentStart` | a subagent starts | `geneseed-hook activity` | records the subagent as a branch of its session, even one that only reads | off with `GENESEED_ACTIVITY=off` |
27
+ | `SubagentStart` | a subagent starts | `geneseed-hook context` | injects your `user-rules.md` layers into the subagent (as JSON `additionalContext`, under the same 9 000-character budget), and records the subagent as a branch of its session | the Activity record only, with `GENESEED_ACTIVITY=off` |
28
28
 
29
29
  Every hook above also feeds the [Activity view](../reference/plugin-activity.md) after it has decided, unless tracking is off: one file per session under `activity/` beside the install. The gates' verdicts never wait on it.
30
30
 
@@ -54,25 +54,25 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
54
54
 
55
55
  A force push to a feature branch, the protected-branch-only forms above on a feature branch, a new branch (`checkout -b`, `switch -c`), `reset --hard` over uncommitted work or to a commit that keeps every unpushed one, `branch -D` of a pushed branch, or `rm` of a tracked, unmodified file passes. When the gate cannot tell — a glob or `$variable` it would have to expand, a `cd` it cannot follow, `sh -c`/`xargs`, git failing or missing — it asks, and says it could not verify. To read the state it runs `git` itself, only once a command already looked destructive; every other command pays nothing. That is a Rule, so it holds in every build — unless you switch its gate off for one install with `--no-deletion-gate` (or the switch on Rule IV in the console's Constitution page). The hook is then wired with `--no-deletion-gate` and this check stands down; the Rule's text still binds the agent, and the catastrophic-command check above and the root-scan and consent checks below still run ([Exclusions](exclusions.md)).
56
56
  - **Every `git commit` and `git push`** gets a prompt citing *Consent Before Push*. This part belongs to the **process** doctrine pack: build without it, or exclude that rule, and the hook stays wired with `--no-consent` — commits and pushes go through without asking, real data loss is still stopped ([Rules](rules.md)).
57
- - **A recursive scan of a whole filesystem** — `find /`, `du -sh /`, `grep -r foo /`, `rg x C:\`, `Get-ChildItem C:\ -Recurse` — gets a prompt citing *Commands Must Return* (on Bob, it is blocked). In Git Bash `/` mounts every drive and mounted share, so such a scan runs for hours, and `| head` does not stop it. The prompt tells the agent to search a specific directory instead. A deeper path (`find /c/Users/me/project`), `ls /` without `-R` (`ls -r` is reverse order, not recursion), a quoted argument (a search pattern such as `grep -rn "/" src`), a `#` comment, and the remote half of an `ssh` command pass. This check is wired in every build, whatever packs or rules you excluded: it rides inside `git-gate` with no flag of its own, because a new flag or verb would reach machines still running an older hook shim, which would refuse it — and Claude Code blocks a tool call whose gate fails.
57
+ - **A recursive scan of a whole filesystem** — `find /`, `du -sh /`, `grep -r foo /`, `rg x C:\`, `Get-ChildItem C:\ -Recurse` — gets a prompt citing *Commands Must Return* (on Bob, it is blocked). In Git Bash `/` mounts every drive and mounted share, so such a scan runs for hours, and `| head` does not stop it. The prompt tells the agent to search a specific directory instead. A deeper path (`find /c/Users/me/project`), `ls /` without `-R` (`ls -r` is reverse order, not recursion), a quoted argument (a search pattern such as `grep -rn "/" src`), a `#` comment, and the remote half of an `ssh` command pass. It belongs to the **ops** pack: build without it, or exclude that rule, and the hook is wired with `--no-root-scan` and this check stands down (also on Bob and in the OpenCode guard); every other check stays ([Exclusions](exclusions.md)).
58
58
  - **A shell write to a protected check or a gate's own configuration** gets the same *External Gate* prompt as a write tool (see rule-gate below; on Bob, it is blocked). `--no-consent` does not touch it.
59
59
  - Any other command passes untouched.
60
60
 
61
61
  **rule-gate.** Runs before every file write.
62
62
  - Content that looks like a credential (a cloud access key, a GitHub or Anthropic token, a Slack token, a private-key block) going into any file other than `.env*` gets a prompt citing *Sealed Secrets*. An install built `--no-secrets-gate` wires the hook with that flag and this check alone stands down ([Exclusions](exclusions.md)).
63
- - A write to `user-rules.md`, `user-rules.draft.md`, `MEMORY.md` or a file in the install's `memory/` or the shared `~/.config/geneseed/memory/` gets a prompt citing *Persist Insight*: whether something is a standing rule or a fact to remember is your call, settled through the `rule` [skill](skills.md).
64
- - A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). The list is `.geneseed/protected-checks.txt` at the project's git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A project install (any host) seeds it when it is absent, with only the paths that exist there: CI (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`, `.circleci/`), lint, type and test config (`eslint.config.*`, `.eslintrc*`, `biome.json(c)`, `tsconfig.json`, `jest.config.*`, `vitest.config.*`, `pytest.ini`, `ruff.toml`, `.golangci.yml`, `checkstyle.xml`), and the manifests the done gate infers its checks from (`package.json`, `pom.xml`, `build.gradle(.kts)`, `pyproject.toml`, `Cargo.toml`, `go.mod`). It is seeded once and is yours from then on: Geneseed never rewrites it, never deletes it on uninstall, and never touches a list that already exists. To opt out, delete the listed paths (the comments may stay) but keep the file. An existing list, even one holding only comments, is never seeded again; a deleted file is. A global install seeds nothing. Whenever `.geneseed/` exists, the emit also makes sure it holds the personal-by-default `.gitignore`. A check the agent can edit is not a check. The list protects itself. A shell command is read too: the targets of `>`, `>>`, `tee`, `sed -i`, `cp`, `mv` and `rm` get the same check, by path only (no secret scan of the command), through the git gate. `mv` counts its source as well, and a read (`cat x > /tmp/y`) counts only `/tmp/y`. What the reader cannot follow stays unseen: interpreters with inline code, scripts, `npm run`, variables, globs, subshell tricks, a folder removed above a listed file. So run the same checks in CI as the boundary that holds.
63
+ - A write to `user-rules.md` or `user-rules.draft.md` gets a prompt citing *Persist Insight*: a standing rule is your call, settled through the `rule` [skill](skills.md). Memory is not gated: the agent writes `MEMORY.md` and the facts in a memory store on its own, and you see them afterwards in the web console (a shell write to one also shows in the [change report](#the-change-report)). A hard link has no target to follow, so a write to a second name of a known rule file gets the same prompt: the gate compares the file's device and inode with the `user-rules.md` and `user-rules.draft.md` of the install, the shared tier, the project at the session's git root and the homes `$GENESEED_HARNESS` and `$GENESEED_MEMORY` name. Any other hard-linked file, a pnpm store's for example, is ordinary work. On Bob it is blocked. This check belongs to the **process** pack: build without it, or exclude *Persist Insight*, and `rule-gate` and `git-gate` are wired with `--no-rule-store`, so a rule-file write is ordinary work on every host ([Exclusions](exclusions.md)). The change report still lists it.
64
+ - A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). An install built `--no-external-gate` drops this prompt and the two below it, and the agent can then rewrite the wiring of every other gate ([Exclusions](exclusions.md)). The list is `.geneseed/protected-checks.txt` at the project's git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A project install (any host) seeds it when it is absent, with only the paths that exist there: CI (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`, `.circleci/`), lint, type and test config (`eslint.config.*`, `.eslintrc*`, `biome.json(c)`, `tsconfig.json`, `jest.config.*`, `vitest.config.*`, `pytest.ini`, `ruff.toml`, `.golangci.yml`, `checkstyle.xml`), and the manifests the done gate infers its checks from (`package.json`, `pom.xml`, `build.gradle(.kts)`, `pyproject.toml`, `Cargo.toml`, `go.mod`). It is seeded once and is yours from then on: Geneseed never rewrites it, never deletes it on uninstall, and never touches a list that already exists. To opt out, delete the listed paths (the comments may stay) but keep the file. An existing list, even one holding only comments, is never seeded again; a deleted file is. A global install seeds nothing. Whenever `.geneseed/` exists, the emit also makes sure it holds the personal-by-default `.gitignore`. A check the agent can edit is not a check. The list protects itself. A shell command is read too: the targets of `>`, `>>`, `tee`, `sed -i`, `cp`, `mv`, `rm` and the PowerShell writers (`Add-Content`, `Set-Content`, `Out-File`, `Clear-Content`, `Remove-Item`, `Copy-Item`, `Move-Item`, `New-Item`, `Rename-Item`, and their common aliases) get the same check, by path only (no secret scan of the command), through the git gate. `mv` counts its source as well, and a read (`cat x > /tmp/y`) counts only `/tmp/y`. What the reader cannot follow stays unseen: interpreters with inline code, `pwsh -c`, scripts, `npm run`, variables other than the home, globs, subshell tricks, a folder removed above a listed file. So run the same checks in CI as the boundary that holds.
65
65
  - A write to `.geneseed/done-checks.txt`, the done gate's own list (below), gets the same *External Gate* prompt: emptying it would disarm the gate.
66
66
  - A write to a gate's own configuration gets the same *External Gate* prompt on Claude Code and OpenClaude. These files can switch a gate off:
67
- - In the install's own dir: `settings.json`, `settings.local.json` and Bob global's `settings/settings.json` (the hook wiring), `excludes.json`, `AGENT.md` (its `… gate: off` markers), `.geneseed-manifest.json` and `.geneseed-emit`; and `excludes.json` in the machine-wide `~/.config/geneseed/` folder, the shared exclude list.
67
+ - In the install's own dir: `settings.json`, `settings.local.json` and Bob global's `settings/settings.json` (the hook wiring), `excludes.json`, `AGENT.md` and Bob global's `rules/geneseed.md` (their `… gate: off` markers), `.geneseed-manifest.json` and `.geneseed-emit`; and `excludes.json` in the machine-wide `~/.config/geneseed/` folder, the shared exclude list.
68
68
  - In any project: the same names under a `.claude/`, `.openclaude/`, `.bob/` or `.opencode/` folder (at the git root, in a subpackage, or with no git at all), and any `opencode.json(c)`. A team `settings.json` can set `disableAllHooks`.
69
69
  - The machine-wide hook shim in `~/.geneseed/bin/` (or `$GENESEED_HOME/bin/`).
70
70
  - On OpenCode, also the install's `opencode.json(c)` and its own `plugins/geneseed-*.js`.
71
- - **OpenCode** asks with its own prompt. The emit writes `permission.edit` "ask" keys into `opencode.json`: every `opencode.json(c)`, the global `config.json`, the install's `AGENT.md` (where the emit put it), the install dir's `excludes.json`, manifest and `.geneseed-emit`, everything that can load code or set permissions there (`plugins/*`, `plugin/*`, `tool/*`, `tools/*`, `agents/*.md`, `agent/*.md`, `mode/*.md`, `modes/*.md`), `user-rules.md`, `user-rules.draft.md` and `MEMORY.md` by name, the install's and the shared `memory/*.md`, the `.claude/`, `.openclaude/` and `.bob/` hook settings, and the shim dir. A blanket `"edit": "allow"` becomes `{"*": "allow", …}` with the asks after it. A blanket `"ask"` or `"deny"` already covers them and is left alone; a key you set yourself is kept and named in a warning. The manifest records the keys Geneseed added (`edit_asks`, `edit_shorthand`); a rebuild drops a recorded key it no longer wants, and uninstall takes back the ones still set to `"ask"` and restores your `"allow"`. The guard plugin refuses only the other hosts' Geneseed-only files (`excludes.json`, `AGENT.md`, manifest) and an `AGENT.md` under `$GENESEED_HARNESS`. These rules match by name, not through a link, a project `opencode.json` with its own `"edit": "allow"` replaces a global install's object, and a custom `$GENESEED_HOME` is named by its absolute path, which only OpenCode 2 matches. In OpenCode's built-in plan agent, these files are asked about rather than refused.
71
+ - **OpenCode** asks with its own prompt. The emit writes `permission.edit` "ask" keys into `opencode.json`: every `opencode.json(c)`, the global `config.json`, the install's `AGENT.md` (where the emit put it), the install dir's `excludes.json`, manifest and `.geneseed-emit`, everything that can load code or set permissions there (`plugins/*`, `plugin/*`, `tool/*`, `tools/*`, `agents/*.md`, `agent/*.md`, `mode/*.md`, `modes/*.md`), `user-rules.md` and `user-rules.draft.md` by name, the `.claude/`, `.openclaude/` and `.bob/` hook settings, and the shim dir. A blanket `"edit": "allow"` becomes `{"*": "allow", …}` with the asks after it. A blanket `"ask"` or `"deny"` already covers them and is left alone; a key you set yourself is kept and named in a warning. The manifest records the keys Geneseed added (`edit_asks`, `edit_shorthand`); a rebuild drops a recorded key it no longer wants, and uninstall takes back the ones still set to `"ask"` and restores your `"allow"`. The guard plugin refuses only the other hosts' Geneseed-only files (`excludes.json`, `AGENT.md`, manifest) and an `AGENT.md` under `$GENESEED_HARNESS`. These rules match by name, not through a link, a project `opencode.json` with its own `"edit": "allow"` replaces a global install's object, and a custom `$GENESEED_HOME` is named by its absolute path, which only OpenCode 2 matches. In OpenCode's built-in plan agent, these files are asked about rather than refused.
72
72
  - **Bob** has no prompt, so it blocks, and only writes: a read passes, and so does a write to `opencode.json(c)`, which Bob never reads. A hook `settings.json` (or `settings.local.json`, or global `settings/settings.json`) is blocked only when the write changes Geneseed's own entries (a hook whose command names `geneseed-hook`, with its event and matcher), turns on `disableAllHooks`, or changes a `GENESEED_*`, `*_CONFIG_DIR` or `NODE_OPTIONS` env value. An MCP server or your own hook passes. An edit the hook cannot replay exactly is blocked: a regex, case-folded or line-ranged replace, a search not found exactly once, a diff of more than one block, an unknown write-shaped tool (its name says write, edit, diff, replace or insert; a tool named otherwise is not judged), or a file left unparseable or turned from strict JSON into JSONC. The other files stay blocked.
73
73
  Names match exactly, and on Windows without regard to case or slash direction; a link into one of these paths is caught too. To change one of these files, edit it yourself, or approve the prompt. `geneseed` commands (`exclude`, a rebuild) write these files directly and are never asked. Claude Code itself also prompts for writes under `.claude/` in its default and `acceptEdits` modes, but not in `bypassPermissions`, so you can see two prompts there. A shell write is read as above. On OpenCode `permission.edit` covers edit tools only, so the guard refuses a shell write to every file in this list; the same edit through an edit tool gets the prompt. On Bob a shell write to a hook `settings.json` is blocked: a command line cannot be replayed.
74
74
  - The first write of a session in an application repo (a git root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section is refused once, the **ownership gate**. Despite the name it is a reminder, not a gate, because the next write passes. It is not a prompt for you: the reason goes to the agent, which asks you to set ownership up now, skip this session, or skip in this repo until you ask (on Bob, exit 2, once). The next write passes, a sub-agent never triggers it on Claude Code and OpenClaude, and writes to `AGENTS.md` or `.geneseed/` pass. Off per repo with `mode: off` in that section; for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, which also makes every session start with the line `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it`; per install with `--no-ownership-gate`, which prints no such line ([Ownership](ownership.md), [Exclusions](exclusions.md)).
75
- - An edit that weakens a test gets a note to the agent, citing *Cure the Cause*. It is **advisory**: it asks nothing and blocks nothing. A test file has a path segment `test`, `tests`, `__tests__` or `spec`, or a name `*.test.*`, `*.spec.*`, `*_test.*` or `test_*`. The edit weakens it when it adds `.skip(`, `xit(`, `xfail`, `@Disabled`, `@Ignore`, `pytest.mark.skip` or `t.Skip(`, or when it removes an assertion line and adds no other. The done gate repeats it to you when the turn ends. On Bob the note is a line in the hook log. On OpenCode it is one reminder on the next request.
75
+ - An edit that weakens a test gets a note to the agent, citing *Cure the Cause*. It is **advisory**: it asks nothing and blocks nothing. An install built `--no-test-note` gets no note, here or at turn end ([Exclusions](exclusions.md)). A test file has a path segment `test`, `tests`, `__tests__` or `spec`, or a name `*.test.*`, `*.spec.*`, `*_test.*` or `test_*`. The edit weakens it when it adds `.skip(`, `xit(`, `xfail`, `@Disabled`, `@Ignore`, `pytest.mark.skip` or `t.Skip(`, or when it removes an assertion line and adds no other. The done gate repeats it to you when the turn ends. On Bob the note is a line in the hook log. On OpenCode it is one reminder on the next request.
76
76
  - Ordinary edits pass untouched.
77
77
 
78
78
  **The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**, and they stay advisory, with no date: only a list the project wrote can block. A turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test`. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. The gate never runs a check itself. It reads the transcript from its end, back only to the prompt that opened the turn, so its cost does not grow with the session. It blocks at most once per turn; the second stop ends the turn and leaves a line in the gate ledger. Only file-write tools count as edits: a shell `sed -i` or redirect is not one here. When a turn weakened a test (see the rule gate), the gate adds a line that the agent cannot suppress, `[done-gate] advisory — test weakened this turn: tests/a.test.js (.skip added)`. The line needs no checks and stays out of the ask counts. `--no-done-gate` silences this line and OpenCode's reminder, but not the note the agent gets at edit time on Claude Code, OpenClaude and Bob: the rule gate never receives that flag. A block prints only the block; the line comes at the stop that ends the turn. On OpenCode the gate is a reminder on the next request (OpenCode 1 only), listed or inferred; on Bob, whose Stop carries no transcript, the turn is not judged, and with a listed file a log line says so. An install built `--no-done-gate` wires `learn` with that flag: the check is skipped, learning still runs ([Exclusions](exclusions.md)).
@@ -85,6 +85,45 @@ export GENESEED_LLM="claude -p"
85
85
 
86
86
  Unset, `learn` does nothing useful: on a real Stop/SubagentStop/PreCompact call it returns immediately rather than reading the transcript for nothing, and on a manual run it prints the prompt it would have sent. Geneseed never stores or embeds an API key. See [Memory](memory.md).
87
87
 
88
+ ## What a prompt says
89
+
90
+ When a gate stops a call, Geneseed writes the reason. An agent cannot change this fixed text. Each prompt is plain English, one sentence per line, and it puts the decision first:
91
+
92
+ ```text
93
+ This edit changes .github/workflows/ci.yml (+3 lines, -1 line), which defines the checks that run on every push.
94
+ Safe choice: Deny, unless you asked for this change. (External Gate)
95
+ It asks because the agent's own work is judged by this file.
96
+ If you allow it, those checks can get weaker or stop running, and a failure could go unseen.
97
+ Agent: if refused, do not write this file another way.
98
+ ```
99
+
100
+ The first line says what changes and what the file is, with the path from the repository root. The second gives the safe choice and names the rule. The last line is for the agent. A commit or a push is routine, so it gets one line.
101
+
102
+ On *Deletion Is Deliberate*, *Commands Must Return* and *Consent Before Push*, the prompt can also quote the `description` that the agent gave the command: `The agent says (not checked): "..."`. It never quotes the agent on *Sealed Secrets*, *External Gate* or *Persist Insight*, because there the agent's opinion is the conflict of interest.
103
+
104
+ If a loss command uses `--git-dir` or `--work-tree`, the prompt adds a line: the command runs on another repository, which the gate did not read.
105
+
106
+ Each host carries this text differently:
107
+
108
+ | Host | What you get |
109
+ | --- | --- |
110
+ | Claude Code, OpenClaude | The reason in the permission prompt |
111
+ | OpenCode | A note just before the dialog, for its two asks only ([guard](../reference/plugin-guard.md)). A refusal goes to the model |
112
+ | Bob | No prompt. A block tells the model to relay the text to you. A warning says the call ran without a prompt |
113
+
114
+ Know these limits:
115
+
116
+ - The text says what a file is and what is at risk. On a write or an edit, it cannot say why the agent wants the change.
117
+ - Claude's own title and prefix stay. Geneseed controls only the reason.
118
+ - The desktop card shows about 3 lines. Past those, you must scroll.
119
+ - OpenCode's note sits beside the dialog, not in it, and exists only for its two asks: a rule write that reaches a host prompt, and a gate configuration file.
120
+ - OpenCode 1's note is a toast, which can expire while the dialog is open.
121
+ - An unattended OpenCode 2 session posts the note, then denies the call.
122
+ - On Bob and on an OpenCode refusal, you depend on the model to relay the text. This is best effort. The change report below is the direct channel.
123
+ - The line count overstates a change with several regions. Shell writes show no count, and neither does a `replace_all`, a search-and-replace, a diff, a notebook cell, a text or an old file past 1 MB, or anything on OpenCode.
124
+ - A loss prompt names the kind of loss, not the files.
125
+ - The text is in English only.
126
+
88
127
  ## Verify
89
128
 
90
129
  Open a session in a repo and ask the agent what it knows about the project — it should answer from the repo's docs without reading them first. Ask it to commit something: you should get a prompt before the commit runs.
@@ -93,13 +132,15 @@ What happens when a gate cannot decide, where the hooks are written, and the one
93
132
 
94
133
  ## The change report
95
134
 
96
- Shell is not a boundary. The gates read only parsed forms of a command, and the host's own command permission is the backstop for the rest. So Geneseed also checks afterwards: at session start it records each store file's size and modified time (`user-rules.md`, `PROFILE.md`, the wiki manifest, `memory/**/*.md`), and at the end of each turn it compares. A change outside this session's approved writes is told to you once, and `geneseed status` shows a `changes` row for seven days. **The report detects a change. It does not prevent one.**
135
+ Shell is not a boundary. The gates read only parsed forms of a command, and the host's own command permission is the backstop for the rest. So Geneseed also checks afterwards: at session start it records each store file's size and modified time (`user-rules.md`, `user-rules.draft.md`, `PROFILE.md`, the wiki manifest, `memory/**/*.md`, and the project's own `user-rules.md` and `user-rules.draft.md` at the session's git root), and at the end of each turn it compares. A change outside this session's approved writes is told to you once, and `geneseed status` shows a `changes` row for seven days. **The report detects a change. It does not prevent one.**
97
136
 
98
137
  | Host | Baseline | Approved means | You see |
99
138
  | --- | --- | --- | --- |
100
- | Claude Code, OpenClaude | `<install>/notebook/store-baseline/`, at SessionStart | the transcript shows a Write, Edit or NotebookEdit ran | a `systemMessage` at Stop |
101
- | Bob | same | nothing: a file-tool write is refused there, so any change is reported | a stderr line at Stop, in Bob's hook log |
102
- | OpenCode | in the guard plugin's memory | `tool.execute.after` on OpenCode's own edit tools | a toast (1.x), a synthetic message (2.x) |
139
+ | Claude Code, OpenClaude | `<install>/notebook/store-baseline/`, at SessionStart | the transcript shows a Write, Edit or NotebookEdit ran; with *Persist Insight* excluded (`learn --no-rule-store`) a rule file never counts, because no prompt ran | a `systemMessage` at Stop |
140
+ | Bob | same | nothing: there is no transcript, so any change is reported, a memory write the agent made freely included | a stderr line at Stop, in Bob's hook log |
141
+ | OpenCode | in the guard plugin's memory | `tool.execute.after` on OpenCode's own edit tools; with *Persist Insight* excluded a rule file never counts | a toast (1.x), a synthetic message (2.x) |
142
+
143
+ With *Persist Insight* excluded nothing asks before a rule write, so this report is then the only signal that your standing rules changed, and the `.own-writes.json` limit below applies to it in full.
103
144
 
104
145
  Geneseed's own writers do not count. `learn`, `geneseed memory rm`, the OpenCode learn plugin and the fold snapshot the store around their run and log what moved to `memory/.own-writes.json`, as an exact size and time. A change that matches is excused. Two limits follow: anything else that writes during that run is excused too, and the log is a plain file an agent could edit.
105
146
 
@@ -13,14 +13,16 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
13
13
  | Instructions file | `AGENT.md` via `opencode.json` | `CLAUDE.md` | `AGENTS.md` + `rules/geneseed.md` | `CLAUDE.md` (`.openclaude/` per repo) |
14
14
  | Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
15
15
  | Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
16
+ | Your `user-rules.md` handed to each sub-agent | — (later) | 🪝 hook | — (no `SubagentStart`) | 🪝 hook² |
16
17
  | Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
17
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² |
18
19
  | Real data loss (force-push to `main`, discarding uncommitted work, `rm` of untracked files…) | ⚙️ block³ · 🔒 ask (reflog, gc) | 🪝 ask | 🪝 block¹ | 🪝 ask² |
19
20
  | Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
20
21
  | Consent before every commit and push | 🔒 permission ask | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
21
- | Rule-or-memory write needs your call | 🔒 ask³ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
22
+ | Standing-rule write needs your call | 🔒 ask³ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
22
23
  | User-only skills hidden from the model | 🔒 `permission.skill` deny | ✅ `disable-model-invocation` | ✅ `/`-command, no skill | ✅ `disable-model-invocation` |
23
24
  | Sovereign-repo exclusions⁵ | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
25
+ | Subagent depth capped at two ([Foreman mode](foreman-mode.md)) | ✅ `subagent_depth` | ✅ `env` setting | ➖ undocumented | ➖ no cap in the host |
24
26
  | MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
25
27
  | Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
26
28
 
@@ -28,13 +30,13 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
28
30
 
29
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.
30
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
- ³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so a rule-or-memory write gets OpenCode's own prompt, and the guard refuses a file-tool write where no prompt can run. Shell is not a boundary on any host: only parsed forms are read, and the host's command permission is the backstop. A real data loss is blocked outright (as on Bob) rather than asked; `GENESEED_GUARD=warn` turns a block into a logged warning.
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.
32
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.
33
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).
34
36
 
35
37
  ## The one conditional row
36
38
 
37
- The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. Everything else in the table is always on.
39
+ The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. The standing-rule row is conditional the same way: it enforces *Persist Insight*, also in the process pack, and excluding it (or the pack) drops that hook on every host ([Exclusions](exclusions.md)). Everything else in the table is always on.
38
40
 
39
41
  One OpenCode asymmetry: Geneseed shares `opencode.json` with you and cannot tell its own `git commit*` permission entry from one you typed, so a rebuild without the process pack leaves an existing entry in place and says so instead of deleting it. A `permission.skill` deny is different: Geneseed records each one it writes, and a rebuild or uninstall takes back only those, never a deny you set yourself.
40
42
 
@@ -18,7 +18,7 @@ Each host has a **global** install (in its config directory, active in every rep
18
18
 
19
19
  ## Two engines
20
20
 
21
- - **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
21
+ - **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. The install also caps subagent nesting at two levels there (`subagent_depth`), as it does on Claude Code (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`); OpenClaude and Bob have no such cap ([Foreman mode](foreman-mode.md)). It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
22
22
  - **Claude Code**, **Bob** and **OpenClaude** share one Claude-shaped engine: Geneseed wires **hooks** into the host's `settings.json`, each calling `geneseed-hook <verb>`. See [Hooks](hooks.md).
23
23
 
24
24
  ## Where to go next
@@ -37,11 +37,29 @@ The second kit is `react`, for React 18 or 19 apps built with Vite or webpack, i
37
37
 
38
38
  It is adapted from [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT), rewritten and condensed for Vite and Jest; the webpack side file is first-party. It has no Server Components material: a client-rendered app has no server render.
39
39
 
40
+ The third kit is `ci-pipelines`, for CI pipelines on Jenkins and GitLab CI. It adds two skills and no agent:
41
+
42
+ | Member | Kind | What it is for |
43
+ |---|---|---|
44
+ | `jenkins-pipeline` | skill | Declarative `Jenkinsfile`, shared-library layout (`vars/`, `src/`, `resources/`), CPS and `@NonCPS`, sandbox and script approval, credentials binding, `parallel` and `when`, tests with JenkinsPipelineUnit |
45
+ | `gitlab-ci` | skill | `.gitlab-ci.yml`: `rules:`, the `needs:` DAG, `include:` and `extends:`, caching and artifacts, protected and masked variables, environments, CI lint |
46
+
47
+ Its rules keep the pipeline in one source of truth, take secrets only from the CI's own store, pin images and tool versions, and run fast feedback first. Its `banned` list refuses GitLab's older job-condition keywords, which GitLab no longer actively develops, in its files. It is first-party.
48
+
49
+ The fourth kit is `docker`, for Docker and Compose operations on any stack. It adds one skill:
50
+
51
+ | Member | Kind | What it is for |
52
+ |---|---|---|
53
+ | `compose-ops` | skill | Health-ordered startup (`depends_on` with `condition: service_healthy`), named volumes against bind mounts, pinned tags or digests, `.env` and secrets, restart policies, resource limits, logging, networks, minimal non-root multi-stage images, and safe updates: pull, recreate, roll back |
54
+
55
+ It does not overlap the spring-boot kit's `docker-expert` agent: that agent builds a Spring Boot service's own image (Buildpacks, layered or native) and its local-dev Compose file, and `compose-ops` operates any Compose stack. Either kit works without the other. `compose-ops` is adapted in part from the `docker-patterns` skill of [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT), rewritten for operations; its skill folder ships `LICENSE-everything-claude-code.txt`.
56
+
40
57
  ### Switching kits on and off
41
58
 
42
59
  ```bash
43
60
  geneseed build --emit claude-global --kits spring-boot
44
61
  geneseed build --emit claude-global --kits react,spring-boot
62
+ geneseed build --emit claude-global --kits ci-pipelines,docker
45
63
  geneseed build --emit claude-global --kits none
46
64
  ```
47
65
 
@@ -13,6 +13,9 @@ this way: the loop reports `{awaiting}` with `kind: "gate"` before the edge that
13
13
  normally follow is taken at all — **the gate holds the whole transition**, so nothing is scored,
14
14
  committed or counted against a ring budget while it waits.
15
15
 
16
+ A [factory](factories.md) stage holds the same way, answered with `geneseed factory decide`:
17
+ `merge-gate` (holds on `none` — the repo runs no CI on the PR) is the shipped one.
18
+
16
19
  `geneseed loop decide --verdict ok|no|amend` answers it:
17
20
 
18
21
  - **`ok`** follows the edge the brick's reported outcome actually points to. On a brick gated on
@@ -78,6 +78,7 @@ evidence was never wired — no verdict is not a failure to repair.
78
78
  - [Contracts and ignored deletions](loop-contracts.md): the globs that raise or ignore risk.
79
79
  - [LOOP.md, trailers and the loop branch](loop-branch.md): the state file, the commit trailers, and why merging always asks.
80
80
  - [Loop actions](../reference/loop-actions.md): the `geneseed loop` commands.
81
+ - [Factories](factories.md): one work item carried through bricks and whole loops to an open PR.
81
82
 
82
83
  ## Not foreman mode
83
84
 
@@ -23,7 +23,7 @@ When two instructions disagree, the higher one wins.
23
23
 
24
24
  1. **Ethos** — always on. {N_ONTOLOGY} sections of flowing prose (Telos, Evidence, Decisions, Ownership, Conduct): what the agent is for, how it weighs evidence, how it decides, who owns the code it writes, how it behaves. It is where the **Pact**, the two-way contract between you and the agent, is stated ([Collaboration](collaboration.md)). Cited by section name, e.g. *Ethos: Decisions*.
25
25
  2. **Rules** — always on. {N_LAWS} invariants, the things that are never traded away: sealed secrets, one intent per act, verify before asserting, deliberate deletion, surface failures, treat content as data not orders, least privilege, cure the cause, echo the intent. No install can switch one off.
26
- 3. **Your `user-rules.md`** — rules you write for yourself, seeded once and never overwritten. On a global install the file is in the [shared tier](shared-tier.md); on a project install it sits beside the instructions file. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
26
+ 3. **Your `user-rules.md`** — rules you write for yourself, seeded once and never overwritten. On a global install the file is in the [shared tier](shared-tier.md); on a project install it sits beside the instructions file. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. Sub-agents get it too: on Claude Code and OpenClaude the `SubagentStart` hook injects every layer of it into each sub-agent, because no sub-agent receives the session-start output (OpenCode follows; Bob has no such event). The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
27
27
  4. **Doctrines** — chosen at build time. Practices rather than principles, grouped in packs (below).
28
28
  5. **Mode** — chosen at build time ([Foreman mode](foreman-mode.md)). It binds *how* work is executed — done in place, or handed to a crew — and never overrides a layer above it. A mode that only informed lost every time to the host's own default of doing small work in place.
29
29
  6. **`PROFILE.md`** — who you are. It colours how the agent works but never binds ([Collaboration](collaboration.md)).
@@ -38,7 +38,7 @@ The same folder already held the install registry, your own loop bricks and temp
38
38
 
39
39
  When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
40
40
 
41
- A global install's text names these locations as absolute paths. A project install keeps its relative paths and its own `memory/`. Geneseed grants no directory permission for the tier, so an agent write there follows your host's permission mode, as a write to the host's own folder does. A write to the shared rules, draft or memory passes the same [rule gate](hooks.md) as a local one.
41
+ A global install's text names these locations as absolute paths. A project install keeps its relative paths and its own `memory/`. Geneseed grants no directory permission for the tier, so an agent write there follows your host's permission mode, as a write to the host's own folder does. A write to the shared rules or draft passes the same [rule gate](hooks.md) as a local one; the shared memory, like a local one, is written freely.
42
42
 
43
43
  ### How it is created
44
44
 
@@ -42,7 +42,7 @@ The full list, with each description, is in the catalog.
42
42
 
43
43
  ### Skills improve themselves
44
44
 
45
- Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with your assent, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and `doctor` would report it as drift. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> — seen: <what happened, against what was expected> (<date>)`: `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Most runs end with nothing to change.
45
+ Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with no prompt, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and `doctor` would report it as drift. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what was expected> (<date>)`: `situation:` says where the correction holds (it is optional, and older lines without it stay valid; without it, the circumstance in `seen:` stands in), `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Folding a skill or agent note is your call: the `skill-forge` skill first replays one past task whose original ask still exists, as two dispatched agents from the pre-fix revision, one told to read no notes and one given the note. The `fresh-eyes` skill freezes one rubric from the ask and judges both results blind against it. A note is folded only when it wins, on the result or on a stated process gain; on a tie or a loss you decide whether to keep or delete it. A trivial wording fix skips that probe. Most runs end with nothing to change.
46
46
 
47
47
  ### Old names keep working
48
48
 
package/docs/extending.md CHANGED
@@ -327,7 +327,9 @@ render — no citation moves, because none names a number. Then:
327
327
  1. `RETIRED_RULE_IDS` in `js/build/source.mjs` — add the id with what it was and where its text
328
328
  went. `constitutionProblems` refuses a retired id declared again, so an id that meant one rule in
329
329
  someone's notes can never come back meaning another. `liveAs` names the one tier that may still
330
- declare it (Law IX's `external-gate` lives on as a rigor rule).
330
+ declare it (Law IX's `external-gate` lives on as a rigor rule). For a doctrine rule, write `was`
331
+ as its address, `<pack> <n>` (`mark-the-ask` was `comms 5`): `retiredRuleAddresses` reads it, so
332
+ an install that still excludes that address gets a WARN and a rebuild, not a refusal.
331
333
  2. Every citation of the removed id — the doctor names each one; point it at the rule that now
332
334
  carries the text.
333
335
  3. Its `LEX_<ID>`/`DOC_<ID>` key in all fifteen theme files (the equality arm names each).
@@ -706,7 +708,9 @@ Two gates hold it: `tests/unit/hook_form.test.mjs` pins the rule (including the
706
708
  reachable because `ephemeralCheckout` takes the temp root as a parameter), and
707
709
  `tests/shim_intact.mjs` — a step in `ci.yml` and `publish.yml`, *after* `node --test`, because
708
710
  each test file runs in its own process and the file that causes this is not the file that would
709
- notice — fails if the suite left the shim naming anything that is not there.
711
+ notice — fails if the suite left the shim naming anything that is not there. The same step fails
712
+ if a test touched the machine tier: a change report naming test fixtures or the temp root, or, behind
713
+ CI's `.suite-fence`, any file in the tier.
710
714
 
711
715
  This is not hypothetical — it happened while this file was being written. Several agents were
712
716
  verifying gates out of copied checkouts (the `copyCheckout` fixture pattern
@@ -908,6 +912,8 @@ on N, and refuses (exit 1, nothing sent) when it names another port. A test inst
908
912
  port is therefore stopped with `--port`, never with a bare `web stop` — that one stops whatever
909
913
  the record names, usually the live console on 4747.
910
914
 
915
+ When the preferred port is taken, `clearPort` (`js/web/daemon.mjs`) asks `/api/ping` who holds it. The ping carries `rootId()`, a hash of the checkout root. A holder with our root is asked to shut down on `/api/shutdown` with `X-Geneseed-Secret`: a MAC of the port under the install secret in `.geneseed-web-secret` (32 random bytes, mode 0600, created once next to the daemon record). The secret itself is never sent, and no pid is ever signalled, so a listener that only claims our root cannot cause harm. Any other answer is left alone and named. A console older than the field has no root, so it is never assumed to be ours.
916
+
911
917
  ---
912
918
 
913
919
  ## 10 — What to settle before the next wave
@@ -19,11 +19,37 @@ Only one console runs at a time. A second `start` does nothing, so logging in tw
19
19
 
20
20
  > **Always use `web start` in a login item, never bare `web`.** Bare `geneseed web` runs in the foreground and leaves no record of itself. `web stop`, `web restart` and `web status` then cannot see it: they report no live server while it keeps serving. A `restart` would then start a second console that cannot take the busy port.
21
21
 
22
- > **This is a file you create. Geneseed never writes or edits a login item**, and that includes `geneseed migrate`. To remove the login item, delete the file.
22
+ **When the port is busy.** `web start` and `web restart` ask for port 4747 first. If something else holds it, they check what it is. A console of this same copy of Geneseed is ended and the port is taken. Anything else is left alone: another program, a console of another copy, or a console too old to say which copy it is. The command then prints a line naming the port and the holder, and serves on a free port instead (and says which). `geneseed web status` also lists a console on 4747 that is not the recorded one. If a page says *this console is not the recorded daemon*, you are on one of those older consoles: use the address `web status` prints, or end the pid it names.
23
+
24
+ ## From the web console
25
+
26
+ Open **Settings** and find the **Start at login** row in **Server**. The row shows the file and its state:
27
+
28
+ | State | What the row offers |
29
+ | --- | --- |
30
+ | Off | **Turn on** writes the login item for this platform |
31
+ | On · written by Geneseed | **Remove** deletes it |
32
+ | On · points at another copy or Node | **Update** rewrites it for this copy |
33
+ | On · set up by hand | A link to this guide. Geneseed does not change or delete the file |
34
+
35
+ Each button asks first, and the question names the file. Geneseed writes only one file per platform:
36
+
37
+ - **Windows:** `geneseed-web.vbs` in your Startup folder.
38
+ - **macOS:** `~/Library/LaunchAgents/dev.geneseed.web.plist`. It loads at your next login. Geneseed does not run `launchctl`. To start the console now, run `launchctl load` on the file, or run `geneseed web start`.
39
+
40
+ The file runs the Node that runs the console, by absolute path, with this copy's `bin/geneseed-cli.mjs` and `web start --no-browser`. Its second line (the third line of a plist) is a `GENESEED_AUTOSTART` comment. Geneseed updates or removes a file only when that exact line is in that place, so a file you wrote yourself stays yours. If you upgrade Node or move the copy, the row shows **Update**. The confirm names the copy the file runs, and it warns you when that copy is an agent worktree (`.claude/worktrees`) or an npx cache: such a folder can be deleted, and the login item then fails. On Windows, Geneseed refuses a path with a `%` (the login script would expand it) or a character outside ASCII. Set those up by hand.
41
+
42
+ > **The page token does not stop a local program.** Each write needs the page's token, which keeps other web pages in your browser from turning this on. A program that runs as you can read the token from the console's record, `.geneseed-web.json` in the install folder it serves, and send the same request. It could also write the file itself, so this adds no new risk. The confirm only asks you; it does not protect anything.
43
+
44
+ If the write fails, the row shows the error from the system. A managed Windows PC can block the Startup folder or VBS scripts. Then use the scheduled task below, or ask your administrator.
45
+
46
+ Only **Settings** writes a login item. `geneseed migrate` and uninstall do not write or delete one.
47
+
48
+ ## By hand
23
49
 
24
50
  The examples below assume `geneseed` is on your `PATH` (see [Run geneseed from anywhere](run-anywhere.md)). Login items do not see your shell's `PATH`, so always use the absolute path to the launcher. For an npm install, `npm prefix -g` shows where npm keeps it.
25
51
 
26
- ## Windows
52
+ ### Windows
27
53
 
28
54
  Press **Win+R**, type `shell:startup`, and create a file called `geneseed-web.vbs` in the folder that opens:
29
55
 
@@ -41,7 +67,7 @@ schtasks /Create /TN "Geneseed Web" /SC ONLOGON /TR "\"%LOCALAPPDATA%\Geneseed\b
41
67
  schtasks /Delete /TN "Geneseed Web" /F # to remove it
42
68
  ```
43
69
 
44
- ## macOS
70
+ ### macOS
45
71
 
46
72
  Create a LaunchAgent at `~/Library/LaunchAgents/dev.geneseed.web.plist`. Set `RunAtLoad` and **no** `KeepAlive`. The launcher exits as soon as it has started the background process, which keeps running on its own.
47
73
 
@@ -45,7 +45,7 @@ Pick **peer** unless you know you want another register. A theme changes the pro
45
45
  - **direct** *(default)*: the agent works every task itself, turn by turn.
46
46
  - **foreman**: the session sorts each incoming task. A small task gets done inline. A task that would block the session goes to one background **task worker** in its own git worktree, while the session keeps answering you; corrections go back to the same worker. A crew of agents (a **pipeline**) runs only when you ask for one.
47
47
 
48
- A worker never commits or merges. It hands back its worktree uncommitted, together with its test and lint output. The session then re-runs those commands itself, shows you the diff and the passing output, and commits and merges only after you accept. Foreman mode costs more per delegated task, because a worker and sometimes a reviewer run beside the session. In exchange, the session stays responsive.
48
+ A worker never pushes, and merges only into its own branch, from sub-workers it started. It hands back its branch, together with its test and lint output. The session then re-runs those commands itself, shows you the diff and the passing output, and commits and merges only after you accept. Foreman mode costs more per delegated task, because a worker and sometimes a reviewer run beside the session. In exchange, the session stays responsive.
49
49
 
50
50
  ```
51
51
  geneseed build --emit opencode-global --mode foreman
@@ -42,6 +42,6 @@ If an install's `.geneseed-emit` marker names something this version does not re
42
42
  `migrate` reports these instead of rewriting them:
43
43
 
44
44
  - **Hooks it did not write.** Your own hooks and any third-party hooks stay exactly as they are. A rebuild only replaces the hook groups that Geneseed's manifest says it owns.
45
- - **Login items.** If you set the web console to [start at login](autostart.md), you wrote that file yourself. If it still names your old clone, `migrate` prints its path and the command to put in it. You edit the file yourself.
45
+ - **Login items.** If the web console [starts at login](autostart.md) and its login item still names your old clone, `migrate` prints its path and the command to put in it. If Settings wrote that file, use **Update** on the **Start at login** row. If you wrote it yourself, edit it yourself.
46
46
 
47
47
  Your clone keeps working in the meantime, so you can migrate when it suits you.
@@ -0,0 +1,88 @@
1
+ ---
2
+ group: guides
3
+ order: 24.5
4
+ title: "Run a factory"
5
+ kind: "concept"
6
+ section: "Factories"
7
+ description: "Carry a bug report, an issue or an analysis to an open PR with green CI: what you need, how to ask, and where it stops for you."
8
+ ---
9
+ A **factory** carries one work item to an open pull request with green CI. Each stage is a brick or a whole loop, and a red CI run sends the work back to the loop, a bounded number of times. You ask in plain words. The agent drives `geneseed factory`, which decides every step. The run never merges: the PR is yours to review and merge.
10
+
11
+ This page is the how-to. For how the engine works (stages, cycles, state files), see [Factories](../concepts/factories.md).
12
+
13
+ ## Before you start
14
+
15
+ | You need | Why |
16
+ | --- | --- |
17
+ | An install that carries the `factory` and `loop` skills | The `factory` skill talks to `geneseed factory`, and runs each loop stage through the `loop` skill. After upgrading Geneseed, run `geneseed rebuild-all`. |
18
+ | A git repository with a remote named `origin` | Every loop iteration pushes to `loop/factory-<slug>`, and `pr-open` opens the PR from that branch. |
19
+ | The `gh` CLI (GitHub) or `glab` (GitLab), signed in | `intake` reads an issue with it, `pr-open` opens the PR, `merge-gate` reads the checks. |
20
+ | CI that runs on pull requests | `merge-gate` waits for it. With no CI, it reports `none` and asks you whether the run goes on. |
21
+ | A test command the agent can run | The `bugfix` loop inside the factory needs it, as any loop does. |
22
+
23
+ See the factories your repo can run:
24
+
25
+ ```bash
26
+ geneseed factory list
27
+ geneseed factory check
28
+ ```
29
+
30
+ ## Start a run
31
+
32
+ ```text
33
+ run the bug-report-to-fix factory on issue 412
34
+ take this bug report through the factory: totals round the wrong way on refunds
35
+ run the issue-to-pr factory on issue 418
36
+ ```
37
+
38
+ The agent then:
39
+
40
+ 1. Creates a worktree on a new branch, `git worktree add ../<repo>-factory-<slug> -b loop/factory-<slug>`, and works from there. Your own checkout is not touched.
41
+ 2. Runs `geneseed factory init --title … --requirement … --factory bug-report-to-fix --input <issue or text>`. This writes `FACTORY.md` at the worktree root and registers the run.
42
+ 3. Steps the run: `intake` writes the work item, `holdout-write` writes the holdout scenarios outside the worktree, the `bugfix` loop fixes it commit by commit, `holdout` plays the scenarios against the fix, `pr-open` opens the PR, `merge-gate` waits for CI, and `retro` writes the run report. In `issue-to-pr`, a `triage` stage comes after `holdout-write` and picks the lane: the `bugfix`, `feature`, `deps-upgrade` or `refactor` loop, or the `docs-update` brick for a docs-only change. A failed scenario or red CI then sends the work back to that lane.
43
+
44
+ The holdout scenarios are checks the developer never sees: see [Holdout scenarios](../concepts/factories.md#holdout-scenarios). You can read them yourself in `~/.config/geneseed/holdout/<slug>/`; never paste them into the chat while the run is going, or the developer may see them.
45
+
46
+ ## Build from an analysis
47
+
48
+ `analysis-to-build` takes a larger piece of work: a design document, an analysis pasted into the
49
+ chat, or a plain request. It splits the work into tasks that you approve, then builds them one by
50
+ one in the same worktree, and opens one PR at the end.
51
+
52
+ ```text
53
+ run the analysis-to-build factory on docs/analysis/export-csv.md
54
+ ```
55
+
56
+ 1. `intake` writes the work item from the document.
57
+ 2. `spec` writes `specs/<slug>/spec.md`: the scope, acceptance criteria in EARS form, and an
58
+ ordered task list (20 tasks at most). The run then stops for you. Read the spec and answer
59
+ `ok`, `no`, or `amend` with your corrections; an amend rewrites the spec.
60
+ 3. After your `ok`, the agent commits the spec (the commit asks you), `holdout-write` writes the
61
+ holdout scenarios from it, and the agent runs the `feature` loop once per task, in order.
62
+ `geneseed factory next` names each one as `task <i>/<n>`.
63
+ 4. After the last task, `holdout` plays the scenarios, `pr-open` opens one PR for all of them,
64
+ and `merge-gate` waits for CI.
65
+ 5. A failed scenario sends the work back to the `feature` loop as one extra task, with one
66
+ sentence per failure (observed against expected) as its first note. Red CI does the same, with
67
+ the failing checks as the note: "make CI green". Each is twice at most; a third failure stops
68
+ the run.
69
+
70
+ ## Where it stops for you
71
+
72
+ | Moment | What you decide |
73
+ | --- | --- |
74
+ | The `spec` gate (`analysis-to-build`) | The task list: `ok` starts the first task, `amend` revises the spec, `no` stops the run. The spec commit after your `ok` asks too. |
75
+ | A push | Every push that is not a loop's own commit asks you, `pr-open`'s included. |
76
+ | A loop gate | Anything the `bugfix` loop asks you, as in [While a loop runs](loop-running.md). |
77
+ | `merge-gate` reports `none` | The repo runs no CI on the PR: `ok` goes on to `retro`, `no` stops the run. |
78
+ | The close commit | The last commit removes `FACTORY.md`, and it asks. Its push runs CI again: the agent reads the checks once more and reports the final state. |
79
+
80
+ Red CI does not stop for you: it sends the work back to the run's loop (`bugfix`, or the lane `triage` chose) with the failing checks as its first note, twice at most. A third red result stops the run. A failed holdout scenario works the same way, with its own count of two. A holdout `error` stops the run: the diff touched the holdout folder, or a scenario could not be played.
81
+
82
+ ## When it ends
83
+
84
+ On success the agent reports the PR, every stage with its outcome, each rework and why, and the run report at `.geneseed/factory-runs/<slug>.md`. On a stop it reports the reason and still writes the run report; the branch and `FACTORY.md` stay as they were, so you can see where it stopped. After a crash, ask the agent to resume: it runs `geneseed factory next` in the worktree.
85
+
86
+ ---
87
+
88
+ **Next:** [Factories](../concepts/factories.md)
@@ -59,6 +59,7 @@ The setup writes no personal state; it only removes your `Setup: declined` line,
59
59
  !/.gitignore
60
60
  !/bricks/
61
61
  !/loops/
62
+ !/factories/
62
63
  !/protected-checks.txt
63
64
  !/done-checks.txt
64
65
  ```
@@ -53,4 +53,4 @@ npm uninstall -g geneseed # installed from npm
53
53
 
54
54
  From a clone, `geneseed unlink` removes the launcher that `geneseed link` put on your `PATH` (see [Run geneseed from anywhere](run-anywhere.md)). Then delete the clone folder.
55
55
 
56
- If you set the web console to start at login, delete that login item too. It is a file you created, and Geneseed never removes it (see [Start the web console at login](autostart.md)).
56
+ If the web console starts at login, remove that login item too. Do this before you delete the clone. If Settings wrote it, use **Remove** on the **Start at login** row. If you wrote it yourself, delete the file. Uninstall never removes it (see [Start the web console at login](autostart.md)).
@@ -0,0 +1,22 @@
1
+ ---
2
+ group: reference
3
+ order: 2.5
4
+ title: "Factory actions"
5
+ kind: "concept"
6
+ section: "CLI & environment"
7
+ description: "The geneseed factory actions, one line each."
8
+ ---
9
+ The actions of `geneseed factory`, the state machine that carries one work item through a graph of stages to an open PR. A stage is a brick or a whole loop (`loop:<template>`). A **fork** is a brick that declares a named outcome (one other than `pass`, `fail`, `error` or `none`), each outcome with its own edge to its own lane. An edge target or a cycle node may be `$lane`: the stage the run's most recent fork chose. The run state lives in `FACTORY.md` at the worktree root, beside the child loop's `LOOP.md` ([Loop actions](loop-actions.md)). Each action prints one JSON object and exits 1 on a refusal.
10
+
11
+ | action | what it does |
12
+ |---|---|
13
+ | `check` | checks every factory in the catalogue, or one factory (`--factory <name or .json file>`): the factory has a name and no stage twice, every stage exists, every outcome has one edge, `$close` is reachable, every cycle is declared with a `max` from 1 to 5, each cycle is entered only at its first stage, and every route back targets the first stage of a cycle that holds its source. `$lane` needs a fork on every path to it, and a fork's own edge never targets it. In those checks, `$lane` stands for every lane of every fork. A factory that still uses the retired `loop:$triaged` stage or `loops` list gets a problem that names the replacement; nothing rewrites the file |
14
+ | `list` | lists the factories of the three origins (shipped, global, project), with description, category and origin |
15
+ | `init` | writes a fresh `FACTORY.md` from a factory, under a title, a requirement and an optional `--input` (an issue URL, a file path or pasted text). A factory that fails `check` is refused before any stage runs. Each `init` also registers the run in `factories.json`, beside the loop registry |
16
+ | `next` | returns the next thing to do: run a brick stage, run a loop (with `notes` to start it with, and the `task` when a spec set tasks: the spec's `path`, the task `count` and this task's `index`), answer an `awaiting` gate, or a terminal. A fork stage also gets `lanes`: each outcome it may report, with the stage it leads to. Refused while a `LOOP.md` exists that is not `done` or `stopped` (an unreadable one counts as running): the child loop finishes first. On a loop stage, refused while any `LOOP.md` is left: `git rm -f LOOP.md` and commit that removal before `geneseed loop init`. On a loop stage, `next` also records the launch in `FACTORY.md`: the loop template, the HEAD commit and the time. When a later stage routes back to the loop stage that ran the tasks, after its last task passed (red CI at `merge-gate`, or a failed `holdout`), `next` hands out one extra task: the last `index` again, with `extra` set to the stage and outcome that sent it back (`"merge-gate reported fail"`). That lap spends the route's cycle and the transition ceilings like any other, and gives no fresh budget |
17
+ | `record` | records the current stage's outcome and follows its edge. A loop stage reports `pass` (its loop closed) or `fail` (it stopped), and only after `next` launched it. While its `LOOP.md` is still there, that file must name the stage's template, a `stopped` one admits only `fail`, and a `done` one only `pass`. With no `LOOP.md` left, `pass` and `fail` both need a HEAD that moved since `next`: the loop's close commit, or the commit that removes a stopped loop's `LOOP.md`. That is enough for `fail`. `pass` also needs the loop registry to show a `geneseed loop init` in this worktree after `next`. Without it, `pass` is refused: record it while the `done` `LOOP.md` is still at the root, or report `fail`. The registry does not keep a loop's final status, so a stopped loop whose `LOOP.md` was removed by hand can still pass. `--carry` hands a reason to the next stage; a re-entered loop starts with it as a note. On a fork, the outcome names the lane: the stage its edge reaches is stored as the run's `lane`, and an edge to `$lane` goes there. A route to `$lane` with no lane on record is refused. `--spec <path>` records a spec inside the worktree: the first loop stage recorded after it runs once per numbered item under its first `Tasks` heading, 20 at most. The count is frozen at the first `--spec`: a later one may keep or lower it, never raise it. After a stage outside a loop, pipe `git status --porcelain --untracked-files=all` on stdin. Plain `--porcelain` shows a new directory as one line (`?? specs/`), so a new spec is refused. The tree must be clean (a `mutate` brick such as a `docs-update` lane commits its change first), with two exceptions: engine files, and the run's spec at `specs/<slug>/spec.md` (the one recorded now, else the one on record). No stdin at all (a terminal) is refused. An empty pipe reads as a clean tree. Refused, as `next` is, while a child loop owns the worktree. Every state action also refuses a `FACTORY.md` that does not parse, or one that holds any of these: counters that are not non-negative integers, a run-wide ceiling above 600, a gate amend count above 3, a `lane` that no fork of the factory leads to, an unknown status, a `history` or `cycles` that is not a list, or a factory that no longer passes `check` |
18
+ | `decide` | answers a held `gate: human` stage: `ok` follows the edge (an edge to `$lane` goes to the lane on record), `no` stops, `amend` re-runs the stage with the `--note` as its carry (three times at most) |
19
+
20
+ A route back into a cycle spends the cycle whose first stage is the route's target; past its `max` the run stops. A run stops too after 30 stage transitions, counted again for each spec task the run reaches for the first time, and after 30 transitions per task of the first recorded spec (30 without a spec) over the whole run. That run-wide ceiling is set once and never changes.
21
+
22
+ Run `geneseed factory --help` for the full flag list.
@@ -11,7 +11,7 @@ The actions of `geneseed loop`, the state machine behind [Loops](../concepts/loo
11
11
  | action | what it does |
12
12
  |---|---|
13
13
  | `check` | lists templates and every brick (available, unavailable, overridden); validates one graph file (`--graph`) or one brick file (`--brick`) |
14
- | `init` | writes a fresh `LOOP.md` from a template or graph file, under a title, requirement and trust preset |
14
+ | `init` | writes a fresh `LOOP.md` from a template or graph file, under a title, requirement and trust preset; `--note` or `--note-file <path>` gives the loop the note it starts with (a factory hands its carry here). Each `init` also stamps the worktree's row in the loop registry with the time, which `geneseed factory record` reads ([Factory actions](factory-actions.md)); `--factory <slug>` stores on that row the factory run this loop is a stage of |
15
15
  | `next` | the only driver of the cycle — returns the next thing to do: run a node, score a card, answer an `awaiting`, or a terminal |
16
16
  | `score` | scores a declared card (`--declared`) before a mutate node runs, or the real diff (`--diff`, numstat piped on stdin) before a commit |
17
17
  | `record` | records a brick's reported outcome and advances the graph; `--note` or `--note-file <path>` carries a finding into `LOOP.md`'s notes for the bricks after it: a plan survives the unit, and `review` and `mutation-check` findings last until `apply` reports. `test` cannot report `pass` when that note lists a check as `SKIPPED`: the record is refused and `LOOP.md` does not change |
@@ -12,7 +12,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
12
12
 
13
13
  **When it runs.** On session events. A sub-agent's child session (one with a `parentID`) is folded into its root session: it becomes an `agents[]` row (`{id, type, status: "running" | "done"}`, the child's id and agent), and its files join the root's `files` with `by` set to the child's id. Only learn's throwaway `geneseed-*` sessions are skipped. On OpenCode 2 the files come from `session.step.ended`, which carries no line counts, so those read `null`. A session whose process died, went stale (30 minutes untouched) or ended leaves the live list and is listed as ended; the reader never deletes a file.
14
14
 
15
- **Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `SessionEnd` and `SubagentStart`. So a Claude session's phase moves on the gated tools (`Bash`, `PowerShell`, `Write`, `Edit`, `NotebookEdit`, `Skill`, `Agent`, `Task`), and the rest of the turn — every tool call, the model, the token totals, the last reply — arrives at `Stop`, read from the transcript where the previous `Stop` left off (at most 2 MB per turn). Bob sends no transcript, so a Bob session shows only the calls its `tool-gate` sees, and leaves the live list by staleness alone (Bob has no `SessionEnd`). Bob's `SessionStart` is recorded only after a compaction (`source: "compact"`, counted as one): a startup or resume fires just before the first prompt, which records the session anyway. Bob 2.2.3 writes every hook's payload to stdin and closes it, so reading it there is safe. These writers have no resident process, so their snapshots carry `pid: null` and stay live by staleness alone. Recorded: tool names, each changed file's path relative to the session's git root (a file outside the root, or a session outside any repo, keeps its basename only; a path is never stored absolute; labels show basenames), who changed it (the session or a subagent's `agent_id`), the subagents, the prompt count, the context size and the compactions, line counts, todo text, and 240-character snippets of the prompt and the last reply — never a shell command, a file's content or an edit's text — and any credential the secrets gate would catch in a snippet is written as `[redacted]`. A project install's `activity/` gets its own `.gitignore` (`*`), and the writer never writes through, or sweeps, an `activity/` or `activity/archive/` that is a link. Nothing is recorded in a repo listed in `excludes.json`, or inside a model CLI that `learn` started.
15
+ **Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `SessionEnd` (their `SubagentStart` runs `context`, which records the same way). So a Claude session's phase moves on the gated tools (`Bash`, `PowerShell`, `Write`, `Edit`, `NotebookEdit`, `Skill`, `Agent`, `Task`), and the rest of the turn — every tool call, the model, the token totals, the last reply — arrives at `Stop`, read from the transcript where the previous `Stop` left off (at most 2 MB per turn). Bob sends no transcript, so a Bob session shows only the calls its `tool-gate` sees, and leaves the live list by staleness alone (Bob has no `SessionEnd`). Bob's `SessionStart` is recorded only after a compaction (`source: "compact"`, counted as one): a startup or resume fires just before the first prompt, which records the session anyway. Bob 2.2.3 writes every hook's payload to stdin and closes it, so reading it there is safe. These writers have no resident process, so their snapshots carry `pid: null` and stay live by staleness alone. Recorded: tool names, each changed file's path relative to the session's git root (a file outside the root, or a session outside any repo, keeps its basename only; a path is never stored absolute; labels show basenames), who changed it (the session or a subagent's `agent_id`), the subagents, the prompt count, the context size and the compactions, line counts, todo text, and 240-character snippets of the prompt and the last reply — never a shell command, a file's content or an edit's text — and any credential the secrets gate would catch in a snippet is written as `[redacted]`. A project install's `activity/` gets its own `.gitignore` (`*`), and the writer never writes through, or sweeps, an `activity/` or `activity/archive/` that is a link. Nothing is recorded in a repo listed in `excludes.json`, or inside a model CLI that `learn` started.
16
16
 
17
17
  **Archive.** On `SessionStart` and `SessionEnd` the hook writer moves every snapshot that is no longer live into `activity/archive/`, keeping the newest 50 and none older than 7 days. `/api/activity` returns them, with the stale and dead ones still in `activity/`, in its `ended` list — capped there by the same rule, since the OpenCode plugin never sweeps.
18
18
 
@@ -18,7 +18,7 @@ One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed
18
18
 
19
19
  **When it runs.** On every request: the context rides invisibly in the request's message list, so it also survives compaction. If your OpenCode build lacks that (experimental) hook, the plugin notices and falls back to one visible message at session start, re-pushed when the session compacts.
20
20
 
21
- **The weakened-test reminder.** A write tool call that adds a skip marker to a test file or removes an assertion (the rule in [Hooks](../concepts/hooks.md)) makes the next request carry one invisible message citing *Cure the Cause*, on OpenCode 1 and 2. It is advisory, needs no checks, and an install built `--no-done-gate` does not say it. The call is read before it runs, so one the guard then refuses is still named.
21
+ **The weakened-test reminder.** A write tool call that adds a skip marker to a test file or removes an assertion (the rule in [Hooks](../concepts/hooks.md)) makes the next request carry one invisible message citing *Cure the Cause*, on OpenCode 1 and 2. It is advisory, needs no checks, and an install built `--no-done-gate` or `--no-test-note` does not say it. The call is read before it runs, so one the guard then refuses is still named.
22
22
 
23
23
  **The done gate's reminder.** The project's checks come from `.geneseed/done-checks.txt`, or, without that file, are inferred from the manifests at the project's git root (see [Hooks](../concepts/hooks.md)). A request that follows a turn which edited files without every check passing since gets one more invisible message naming the checks owed (inferred ones marked advisory). OpenCode has no turn-end event a plugin can block on, so this is a reminder, not a block. OpenCode 1 only: on OpenCode 2 the turn is not judged, and with a listed file the plugin logs that once. The context block also opens with one line naming the checks and their source (`Done gate: …`), ending `(reminder)` for a listed file or `(advisory)` for inferred checks on OpenCode 1, and `(not judged on this host)` on OpenCode 2. `GENESEED_CONTEXT_INJECT=off` does not turn the reminder off; a done list that lists nothing does, and so does an install built `--no-done-gate` (`Done gate: off` in its `AGENT.md`, read once when OpenCode starts), which also silences the OpenCode 2 log line and the context line.
24
24