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
@@ -10,16 +10,18 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
10
10
 
11
11
  **What it does.** Enforces the safety rules at the tool boundary — before a tool call runs, not after. High-confidence patterns only, so legitimate work is not caught.
12
12
 
13
- - **Blocks** writes to private-key and credential files and writes whose content carries a credential (*Sealed Secrets*; an install built `--no-secrets-gate` carries `Secrets gate: off` in its `AGENT.md`, read once at load, and both stop blocking), catastrophic shell commands such as deleting the filesystem root and every command that would really lose data — a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, a protected branch force-moved off commits nothing else holds, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, files git cannot restore removed — judged against the repository's state, the same decisions the Claude/Bob hook makes (*Deletion Is Deliberate*; `reflog expire` and `gc --prune` are left to the `permission.bash` ask; an install built `--no-deletion-gate` carries `Deletion gate: off` in its `AGENT.md`, which the plugin reads once at load and then stops blocking real loss — catastrophic commands still block), a recursive scan rooted at a whole filesystem such as `find /` (*Commands Must Return* — search a specific directory instead), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `geneseed-wiki.jsonc`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)). The guard also refuses a write to the other hosts' Geneseed-only files (their `excludes.json`, `AGENT.md` and manifests) and to the shared exclude list in `~/.config/geneseed/`; OpenCode's own config and the shared hook settings get `permission.edit` "ask" keys in `opencode.json` instead, so you see OpenCode's prompt. A shell write is read as well: the targets of `>`, `>>`, `tee`, `sed -i`, `cp`, `mv` and `rm` get the same path checks, by path only. `permission.edit` never sees a shell command and this hook has no ask tier, so a shell write to those "ask" files is refused too.
13
+ - **Blocks** writes to private-key and credential files and writes whose content carries a credential (*Sealed Secrets*; an install built `--no-secrets-gate` carries `Secrets gate: off` in its `AGENT.md`, read once at load, and both stop blocking), catastrophic shell commands such as deleting the filesystem root and every command that would really lose data — a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, a protected branch force-moved off commits nothing else holds, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, files git cannot restore removed — judged against the repository's state, the same decisions the Claude/Bob hook makes (*Deletion Is Deliberate*; `reflog expire` and `gc --prune` are left to the `permission.bash` ask; an install built `--no-deletion-gate` carries `Deletion gate: off` in its `AGENT.md`, which the plugin reads once at load and then stops blocking real loss — catastrophic commands still block), a recursive scan rooted at a whole filesystem such as `find /` (*Commands Must Return* — search a specific directory instead), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `geneseed-wiki.jsonc`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)). The guard also refuses a write to the other hosts' Geneseed-only files (their `excludes.json`, `AGENT.md` and manifests) and to the shared exclude list in `~/.config/geneseed/`; OpenCode's own config and the shared hook settings get `permission.edit` "ask" keys in `opencode.json` instead, so you see OpenCode's prompt. A shell write is read as well: the targets of `>`, `>>`, `tee`, `sed -i`, `cp`, `mv`, `rm` and the PowerShell writers listed under **Shell is not a boundary** get the same path checks, by path only. `permission.edit` never sees a shell command and this hook has no ask tier, so a shell write to those "ask" files is refused too.
14
14
  - **Reminds, once:** it refuses 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, so the agent proposes the [ownership](../concepts/ownership.md) setup first. This is a reminder, not a gate: the next write passes whatever the agent did, and a sub-agent's session never triggers it. Off per repo with `mode: off` in that section, or for one developer with a personal `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`; an install built `--no-ownership-gate` carries `Ownership gate: off` in its `AGENT.md`, read once at load.
15
+ - **Stands down for `External gate: off`** in `AGENT.md` (an install built `--no-external-gate`, read once at load): it stops refusing protected checks and gate configuration on the write and shell paths, and OpenCode 2's `evaluate` stops asking over those files. The `permission.edit` keys in `opencode.json` are host configuration: they stay, and OpenCode keeps asking before an edit tool writes those files. Every other block stays, the NTFS stream refusal included.
16
+ - **Stands down for an excluded rule** read off `AGENT.md`'s `Active packs:` and `Excluded rules:` lines at load, the state the hooks get as flags: with *Persist Insight* (process 1) or its pack off it refuses no rule-store write, by any tool or shell, and OpenCode 2's `evaluate` stops asking over those files; with *Commands Must Return* (ops 2) or its pack off it stops refusing a root scan. The emit also drops the `permission.edit` keys on the rule files. The change report still lists a rule-file change. Every other block stays.
15
17
  - **Warns** (logged, allowed) on `.env` writes.
16
- - **Leaves to OpenCode's own prompt** a write to `user-rules.md`, `user-rules.draft.md` or a memory file (the install's own `memory/` or the shared one under `~/.config/geneseed/`), because whether something is a standing rule or a fact to remember is your call (*Persist Insight*). The emit writes `permission.edit` "ask" keys for them, so OpenCode asks you inside its edit, write and patch tools. On OpenCode 2 the `permission.hook("evaluate")` hook asks as well, even over an earlier "always". On OpenCode 1 the guard reads the merged config and refuses the write when it would not make the host ask. The check reads the file a write lands on: `..` and `//` folded, links followed and, on Windows, a stream or trailing dots and spaces taken off. It covers a project install's own store beside its `AGENT.md` (`Harness/memory` by default) and the stores `$GENESEED_HARNESS` and `$GENESEED_MEMORY` name. A file-tool write the host cannot prompt for is refused, so a re-issue changes nothing: any tool other than OpenCode's own edit tools and a named read set (the path-like arguments it carries are read), a config or an agent's own rules with no ask for that path, and on OpenCode 1 any write after you answered "always" to an edit.
18
+ - **Leaves to OpenCode's own prompt** a write to `user-rules.md` or `user-rules.draft.md`, because a standing rule is your call (*Persist Insight*). 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. The emit writes `permission.edit` "ask" keys for them, so OpenCode asks you inside its edit, write and patch tools. On OpenCode 2 the `permission.hook("evaluate")` hook asks as well, even over an earlier "always". On OpenCode 1 the guard reads the merged config and refuses the write when it would not make the host ask. The check reads the file a write lands on: `..` and `//` folded, links followed and, on Windows, a stream or trailing dots and spaces taken off, so a memory file linked to `user-rules.md` is still a rule write. 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. A file-tool write the host cannot prompt for is refused, so a re-issue changes nothing: any tool other than OpenCode's own edit tools and a named read set (the path-like arguments it carries are read), a config or an agent's own rules with no ask for that path, and on OpenCode 1 any write after you answered "always" to an edit.
17
19
 
18
- **Shell is not a boundary.** The guard reads only the parsed forms: a redirect, `tee`, `cp`, `mv`, `rm` and `sed -i`. One that lands in a store gets OpenCode's prompt on OpenCode 2, through `evaluate` on the shell tool's own permission check, and is refused on OpenCode 1, which cannot ask. Everything else in a command goes unread: `bash -c`, an interpreter, `dd`, `curl -o`, a variable. The host's own command permission (`permission.bash`) is the backstop for those, and the [change report](../concepts/hooks.md#the-change-report) tells you afterwards. It detects; it does not prevent.
20
+ **Shell is not a boundary.** The guard reads only the parsed forms: a redirect, `tee`, `cp`, `mv`, `rm` and `sed -i`, and in PowerShell `Add-Content`, `Set-Content`, `Out-File`, `Clear-Content`, `Remove-Item`, `Copy-Item`, `Move-Item`, `New-Item` and `Rename-Item`, with the aliases `ac`, `sc`, `del`, `copy`, `move`, `ni` and `ren`. A cmdlet name matches in any case, and a pipe into one counts (`| Out-File x`). The reader takes `-Path`, `-LiteralPath`, `-FilePath`, `-Destination` and a first positional path, quoted or bare. A path may open with `~`, `$HOME`, `${HOME}`, `$env:HOME` or `$env:USERPROFILE`. One that lands in a rule store gets OpenCode's prompt on OpenCode 2, through `evaluate` on the shell tool's own permission check, and is refused on OpenCode 1, which cannot ask. Everything else in a command goes unread: `bash -c`, `pwsh -c`, an interpreter, `dd`, `curl -o`, `[IO.File]::WriteAllText`, any other variable. The reader names real write targets; it is no text scan, so `Get-Content MEMORY.md` and a commit message that names the file stay free. The host's own command permission (`permission.bash`) is the backstop for those, and the [change report](../concepts/hooks.md#the-change-report) tells you afterwards. It detects; it does not prevent.
19
21
 
20
22
  It ships whole on every install, whatever [doctrine packs](../concepts/rules.md) you chose. On Claude Code the same checks are hooks, which can *ask* you instead of refusing; Bob has no ask tier, so its hook blocks or warns; OpenCode's tool hook has no ask tier either, so an ask there comes from `permission.edit`.
21
23
 
22
- **"Always" on OpenCode 1.** Its edit tools offer "always" with the pattern `*`, which approves every edit until OpenCode restarts. The host would then ask nothing, so the guard refuses rule and memory writes from that answer on, and writes to the files `permission.edit` asks about, such as `opencode.json` and the guard itself. Restart OpenCode to get the prompt back. The guard sees only an answer it heard: one given in this OpenCode instance after the plugin loaded. OpenCode 2 asks whatever you answered before.
24
+ **"Always" on OpenCode 1.** Its edit tools offer "always" with the pattern `*`, which approves every edit until OpenCode restarts. The host would then ask nothing, so the guard refuses rule writes from that answer on, and writes to the files `permission.edit` asks about, such as `opencode.json` and the guard itself. Restart OpenCode to get the prompt back. The guard sees only an answer it heard: one given in this OpenCode instance after the plugin loaded. OpenCode 2 asks whatever you answered before.
23
25
 
24
26
  **Agents on OpenCode 1.** The tool hook does not name the agent, so the guard reads every agent's rules through `client.app.agents()` and passes a write only if none of them allows it outright. One agent with its own `edit: allow` therefore refuses these writes for all of them.
25
27
 
@@ -29,7 +31,24 @@ There is no DYNAMIC loop/* exemption on OpenCode — OpenCode 1 declares a `perm
29
31
 
30
32
  **When it runs.** Before every tool call (`tool.execute.before`).
31
33
 
32
- **What you see.** A refused tool call: `[geneseed-guard] blocked: <reason>`. OpenCode 2 refuses by renaming the call and prints `No tool named "<name>"`, so there the name opens `BLOCKED, not a missing tool: `. The reason never names the switches below: the agent reads it, and a switch named there reads as leave to get round the block. The *Persist Insight* reason tells the agent to ask you and that a re-issue changes nothing — never to write the file another way (through a shell command, say). Warnings go to stderr.
34
+ **What you see.**
35
+ - **A refused call** reads `[geneseed-guard] blocked: Tell the user this, word for word: <what changes>`, then why it was refused, what you can do yourself, and a last line for the agent. Nothing can be allowed here, so you depend on the model to relay this text. That is best effort. The [change report](../concepts/hooks.md#the-change-report) reaches you directly. OpenCode 2 refuses by renaming the call and prints `No tool named "<name>"`, so there the name opens `BLOCKED, not a missing tool: `, and the model receives the whole text (seen on 2.2.6). The one exception is the ownership reminder above: it is an instruction to the agent, not text for you, so it keeps its own words.
36
+ - **A prompt** comes from OpenCode, and its dialog shows no plugin text. So for its two asks, a rule write that reaches a host prompt and a gate configuration file, the guard posts the reason just before the dialog, inside a delimiter:
37
+
38
+ ```text
39
+ ──── Geneseed · about the next permission request ────
40
+ This edit changes user-rules.md, your standing rules, which the agent obeys in every session.
41
+ Safe choice: Deny, unless you asked for this rule. (Persist Insight)
42
+ It asks because what becomes a rule is your decision.
43
+ If you allow it, the text binds every later session until you remove it.
44
+ ──── The dialog below is for this change ────
45
+ ```
46
+
47
+ OpenCode 2 shows it as a message in the session. The model gets one short line instead of this text. OpenCode 1 shows it as a toast, which can expire while the dialog is still open. `opencode run` and `mini` do not show the OpenCode 2 message. An unattended OpenCode 2 session posts the note and then denies the call. A failed post changes nothing: the prompt still asks. The note shows no line count.
48
+
49
+ [What a prompt says](../concepts/hooks.md#what-a-prompt-says) lists what this text can and cannot tell you.
50
+
51
+ The guard's reasons are the same words as the hooks'. The reason never names the switches below: the agent reads it, and a switch named there reads as leave to get round the block. The *Persist Insight* reason tells the agent to ask you and that a re-issue changes nothing — never to write the file another way (through a shell command, say). Warnings go to stderr.
33
52
 
34
53
  **Switches.**
35
54
  - `GENESEED_GUARD=warn` — log every block, allow the call.
@@ -43,8 +43,8 @@ These come only from `geneseed doctor --probe`. It runs each installed gate exac
43
43
  settings spell it, through the host's own shell, on `git reflog expire --expire=now --all` (which must be refused)
44
44
  and `git status` (which must go through). A gate wired with `--no-deletion-gate` lets the first one
45
45
  through by design, so it is probed on `find / -name geneseed-probe` instead — a root-wide scan it
46
- must still refuse. `--no-secrets-gate`, `--no-done-gate` and `--no-ownership-gate` change nothing here: none
47
- judges a shell command. An OpenCode install's guard plugin has no command to
46
+ must still refuse. `--no-secrets-gate`, `--no-done-gate`, `--no-ownership-gate`, `--no-external-gate` and
47
+ `--no-test-note` change nothing here: none judges either probe command. An OpenCode install's guard plugin has no command to
48
48
  run: the probe imports it and calls its hook through both plugin APIs (V1 and V2), with `rm -rf /`
49
49
  as the call it must refuse. `GENESEED_GUARD=off` or `warn` in your terminal makes that a note,
50
50
  not a failure.
@@ -20,17 +20,21 @@ You ask the agent to clean up history and it decides to force-push `main`. A gat
20
20
 
21
21
  ```text
22
22
  ● Bash(git push --force origin main)
23
- Geneseed (Deletion Is Deliberate) — `git push` would force-push the protected
24
- branch main. Confirm this specific command, or leave the data in place.
23
+ This command force-pushes the protected branch main on the remote.
24
+ Safe choice: Deny, then push without --force. (Deletion Is Deliberate)
25
+ It asks because a force push replaces the remote history.
26
+ If you allow it, commits that exist only on the remote can be lost for everyone.
25
27
  Do you want to proceed? Yes / No
26
28
  ```
27
29
 
28
- An ordinary `git commit` or `git push` gets a milder question when the **process** pack is on: *"Geneseed (Consent Before Push) — every git commit/push needs explicit approval; to see the change first, use the explain-changes skill"*. If you answer no, the command does not run, however the model phrased its reasoning.
30
+ An ordinary `git commit` or `git push` gets a milder question when the **process** pack is on: *"This command commits or pushes with git, which needs your approval each time. (Consent Before Push)"*. If you answer no, the command does not run, however the model phrased its reasoning.
29
31
 
30
- Bob has no prompt, so the same force-push is refused outright:
32
+ Bob has no prompt, so the same force-push is refused outright, and the model is told to relay why:
31
33
 
32
34
  ```text
33
- [geneseed] BLOCKED: Geneseed (Deletion Is Deliberate) — `git push` would force-push the protected branch main. Confirm this specific command, or leave the data in place.
35
+ [geneseed] BLOCKED: Tell the user this, word for word: This command force-pushes the protected branch main on the remote.
36
+ It was refused because a force push replaces the remote history. (Deletion Is Deliberate)
37
+ You can push without --force, or run this command yourself.
34
38
  ```
35
39
 
36
40
  OpenCode has no prompt a plugin can raise, so Geneseed's guard plugin refuses it the same way. Every catch goes into a log, and `geneseed status` counts the catches by rule.
package/docs/web-ui.md CHANGED
@@ -70,7 +70,7 @@ Every `/api/*` read takes and checks the pair, with these exceptions:
70
70
  - `/api/ping` and `/api/jobs` ignore it.
71
71
  - The machine-wide reads also ignore it: `/api/update`, `/api/installs`, `/api/fleet`, `/api/migrate/preview`,
72
72
  `/api/kits`, `/api/usage`, `/api/gates`, `/api/excludes`, `/api/mcp`, `/api/loops/active`,
73
- `/api/activity`, and the Library's skill, agent, memory and notebook lists,
73
+ `/api/factories/active`, `/api/activity`, and the Library's skill, agent, memory and notebook lists,
74
74
  `/api/catalog/skills`, `/api/catalog/agents`, `/api/catalog/memory` and
75
75
  `/api/catalog/notebook`. Such a read does not check the pair, and its answer does not change
76
76
  with the pair. The Activity detail (`/api/activity/<id>`) and the Activity toggle still take
@@ -91,6 +91,15 @@ it. The order is the host order (OpenCode, Claude Code, Bob, OpenClaude), then g
91
91
  project. The item's `install` field names the copy, and its `installs` field names every
92
92
  install that has the id.
93
93
 
94
+ Agents opens on a pinned row for the **primary agent** (the theme's `PRIMARY_AGENT` noun), with a
95
+ **base** pill: every agent inherits its root file. Each agent's detail, the primary's included,
96
+ shows a **Loadout** panel: what the agent loads, block by block (the root file by section, the
97
+ session files or, for a sub-agent, your user rules, both catalogues, the Adept's spec), and the
98
+ rules it follows, marked where its spec cites them. `GET /api/loadout` (the primary) and
99
+ `/api/loadout/<agent>` serve it, install-scoped like `/api/item/`; the figures are the same
100
+ measurements as the Overview's always-on cost. The project root's own `user-rules.md` is not
101
+ counted, because it depends on the session's working directory.
102
+
94
103
  A request that names no install reads the **default install**: the one you chose on the Installs
95
104
  page (*Make default* on an active row), while it stays active. With no choice, it is the first
96
105
  active one in the console's one install order (`fleetSort`): host order (opencode, claude, bob,
@@ -142,15 +151,22 @@ first read is out, a sentence when it failed, and what it found when it is empty
142
151
  before its data. The Constitution waits for the picked install's own overview too: a gate read
143
152
  before it would read as armed.
144
153
 
145
- At the foot of the rail sits a **vitals** card — the doctor's verdict, local edits, how long ago the
146
- harness was built, and a Voice button — so those facts are on screen from every page. It is
147
- hidden where the rail collapses to icons (≤960px) and returns with the phone drawer. The topbar's
154
+ The rail groups its pages under small mono headers, each with a square in the group's tint: the
155
+ Overview alone, then **Govern** (Constitution, Personal), **Build** (Library, Kits, Loops, Factories), **Run**
156
+ (Installs, Activity) and **Help** (Docs, Settings). Each icon sits in a 28 px chip tinted by its group
157
+ (`--sb-<group>-bg` and `-ink` in `styles.css`; light mode has pastel chips with deep ink, 5.3:1 or
158
+ better). The lit page gets a raised row and `aria-current="page"`; a count badge is muted mono on the
159
+ right. The chevron in the header collapses the rail to 64 px of chips (44 px targets, each link with an
160
+ `aria-label` and a tooltip, an expand button on top); the choice is kept per browser under
161
+ `geneseed-rail`. Below 960px the rail is always chips and the toggle is hidden; the phone drawer is
162
+ always full. The rail holds navigation only: the doctor's verdict, local edits and build age live on Doctor, Diff
163
+ and Overview, and the voice gallery on Installs. The topbar's
148
164
  breadcrumb starts at the page: it names no install.
149
165
 
150
166
  **Install pickers.** The console has no install switch. Where a page acts on one install, one
151
167
  `InstallPicker`, always labelled *Install:*, sits right above the heading of the view it acts on
152
168
  (under the tabs on a tabbed page, over the h1 on a page with none), and starts on the default install; with one active install it is not shown. A form or popover that
153
- acts on its own install holds the same control: the new-rule form, the rail's Voice popover, and a
169
+ acts on its own install holds the same control: the new-rule form and a
154
170
  Library entry with several copies. The Personal page names no harness for what the harnesses share:
155
171
  every global install reads one set of rules, one profile and one memory store in the shared tier
156
172
  (`~/.config/geneseed`), so Rules, Profile and Memory list each once. Its header states that scope
@@ -158,8 +174,8 @@ once, a list head or profile card says `shared`, and a project install keeps its
158
174
  install. Each `/api/installs` and `/api/fleet` row carries `shared`, which the pages read from
159
175
  `useInstalls`; `sharedTier` is only a project install's switch. A write goes back to the file an
160
176
  entry came from. Notebook stays per install, and its Forget acts on the install of the copy on
161
- screen. Doctor, Local edits, the Constitution (for its gate switches and doctrine Apply), Loops and
162
- the rail's Voice popover each keep their own pick (in the browser's localStorage). The Overview is
177
+ screen. Doctor, Local edits, the Constitution (for its gate switches and doctrine Apply), and Loops
178
+ each keep their own pick (in the browser's localStorage). The Overview is
163
179
  fleet-wide: each install's own facts (voice, footprint, posture, mode, local edits) sit on
164
180
  its row, and a figure still read off a project install set as the default (a suggestion, a lens)
165
181
  names that install once two or more are active. A *Needs you*
@@ -178,6 +194,25 @@ doctrine rule are all reachable by name; <kbd>↑</kbd>/<kbd>↓</kbd> to
178
194
  move, <kbd>Enter</kbd> to open, <kbd>Esc</kbd> to clear. A bottom **Console** drawer
179
195
  streams the output of background jobs and keeps their history across reloads.
180
196
 
197
+ **The Console drawer is a phase timeline.** The left column lists the runs, newest last. Each
198
+ row has a status dot (green done, amber done with warnings, red failed, pulsing while it runs),
199
+ the action, a short detail (the install, the commits pulled, the installs rebuilt) and the
200
+ duration, with `✗` (failed), `⚠` (warnings) or `running` written beside it. A run whose output
201
+ holds a failure line reads failed even when the job exited 0. The newest run is picked, and a new run takes the pick back from a click. The right
202
+ column shows the picked run: its status pill, a `<duration> · N warnings · N notices` line and
203
+ its numbered phases. A phase is one step the job ran (`$ <argv>`) or one install a `rebuild-all`
204
+ rebuilt (`[rebuild-all] <host>:<scope>`), so an upgrade reads *Update the source*, then one
205
+ *Rebuild* per install. Each phase states *Done*, *N warnings*, *N skipped*, *Failed* or
206
+ *Running*. A warning (`[geneseed] WARN`) is an amber box: a short title, one sentence, and its
207
+ full text under **Full text**. The `[rebuild-all] WARN` printed once after the last install is
208
+ about the whole run, so it shows under **Run warnings**, not under that install. A refused link is a grey notice and counts as skipped. A failure
209
+ line is red in its phase, and a failed job with no failure line marks its last phase failed
210
+ with the last line it printed. A line the reader does not know stays in its phase as printed;
211
+ lines before the first phase (the history keeps only an output's tail) go under **Other
212
+ output**. **Full log** shows the raw output unchanged, for the picked run only. The one reader is
213
+ `web/src/lib/runPhases.js`, and the prefixes it knows are listed at its top. On a narrow
214
+ screen the run list stacks above the detail.
215
+
181
216
  ## Views
182
217
 
183
218
  ### Dashboard
@@ -229,10 +264,22 @@ streams the output of background jobs and keeps their history across reloads.
229
264
  the **Ethos** (five prose sections), the **Dictates** (the nine numbered Rules, with
230
265
  a class facet — only non-empty classes render, and two of the six have had no invariant
231
266
  since the split), and the **Doctrines** (one group per pack, each marked active or not for
232
- this install). Rules I, III and IV each carry a switch for the install's hook gate — the
233
- secrets gate, the done gate and the deletion gate (`--no-secrets-gate`, `--no-done-gate`,
234
- `--no-deletion-gate`; *Enforced by* reads *Gate off* while one is off) — flipping one asks,
235
- then rebuilds the install once; the other Rules read *no gate*. The ownership gate belongs
267
+ this install). Where an install can be rebuilt, each Rule and doctrine row has two toggle
268
+ columns, headed *Rule text* and *Hook gate*. Each open band (Ethos, Dictates, every pack) repeats a compact column header under its title, and a folded pack shows none. Screen readers skip it: each row's label already reads its columns. The table sizes itself to the room it has, not to the window (beside the side panels a 1274 px window leaves it about 600 px): below 960 px of table the *Latin name* column folds under the rule name, below 760 px *Status* and *Enforced by* become two chips under it, and below 540 px *No.* moves above the name and the switch columns narrow to 44 px. Rule keeps at least 220 px down to that last step; the switches never drop, and each header drops exactly the columns its rows drop. *Rule text* is the doctrine switch, which stages
269
+ like any doctrine change; a Dictate cannot be excluded, so its cell is locked, with the reason.
270
+ *Hook gate* is the hook's switch: Rules I, III, IV and VIII (the secrets gate, the done gate,
271
+ the deletion gate and the test note: `--no-secrets-gate`, `--no-done-gate`,
272
+ `--no-deletion-gate`, `--no-test-note`) and doctrine rigor 5 (`--no-external-gate`). Flipping
273
+ one asks, then rebuilds the install once; *Enforced by* reads *Gate off* while one is off. A
274
+ hook with no switch shows a locked cell: process 5 reads *with text*, because excluding it
275
+ drops its commit/push ask (`--no-consent`), and so do process 1 (`--no-rule-store`) and ops 2
276
+ (`--no-root-scan`): excluding the rule, or its pack, drops its hook in the same rebuild. A row with no hook leaves the cell empty. Each switch's accessible
277
+ name names its rule (`Deletion gate: hook gate of Deletion Is Deliberate`, `External Gate rule
278
+ text`). Excluding rigor 5's text also switches its gate off in the same Apply, and the confirm
279
+ says so; including it again offers *Also turn the external gate back on*, checked by default.
280
+ A row whose text is excluded while its hook will still ask reads *Text excluded; the hook still
281
+ asks.*: rigor 5 only, once its exclusion is deployed with the gate armed. Excluding process 1
282
+ or ops 2 says in the confirm that its hook goes too. The ownership gate belongs
236
283
  to no Rule, so its switch (`--no-ownership-gate`) sits inside the Ethos band's *Ownership*
237
284
  row and works the same way. Closed, the row reads *Always* (the section's text binds whatever
238
285
  the gate does) and *Hook gate* or *Gate off*. Open, it shows the text, then a gate line with
@@ -240,6 +287,11 @@ streams the output of background jobs and keeps their history across reloads.
240
287
  can be rebuilt: with no install the row reads *Instruction*. The gate counts in *Gated* but
241
288
  not as a Rule or a section, and the Ethos rank's pill counts it while it is off. Every tab,
242
289
  view and filter shows the row, like the sections around it.
290
+ Every opened row that a hook gates (Rules I, III, IV and VIII, doctrines process 1, process 5,
291
+ rigor 5 and ops 2, and the Ownership section) folds a *What the hook does* block after the rule
292
+ text and before any gate line: what it triggers on, what each host does, what it does not see,
293
+ and what still holds with the gate off. It shows with or without an install to rebuild. The
294
+ text has one home, `GATE_HOOK` in `web/src/lib/constitution.js`; a text-only rule shows none.
243
295
  A precedence ladder heads the page (a state pill per rank; ranks 5–6 below). *Gated* and *Changed* narrow the rows; packs fold; staged doctrine changes
244
296
  collect in a sticky *Unapplied changes* bar that holds Revert and the page's one Apply.
245
297
  Every row expands to its full body, lazily fetched. The rail
@@ -295,6 +347,30 @@ streams the output of background jobs and keeps their history across reloads.
295
347
  the page's only write), what an awaiting loop waits on (launch / declared / actual / a
296
348
  human gate, with its node) — the answer is given in the agent's session, never here — and
297
349
  its ring with the current node filled, with its iteration history under it.
350
+ - **Factories** (`#/factories`) — the factory catalogue `geneseed factory` runs from, read-only,
351
+ in the Loops page's three panes with two sections. **Templates** are grouped by origin; the
352
+ reader draws the selected factory as a vertical graph (`web/src/lib/factoryFlow.js`): each
353
+ stage on the row of its longest path from `start`, top to bottom, joined by lines; a brick a
354
+ grey block, a fork amber, a `loop:` stage on the main path a teal block holding its loop's
355
+ ring. The targets of a fork share a row, side by side, each lane labelled with its outcome,
356
+ and join again at the first stage every lane reaches. Each route back (an edge into a cycle's
357
+ first stage, the edge that spends a lap, `$lane` included) is a rail on the left labelled
358
+ `↺ <cycle> · max N`, the smallest cycle that holds it; every stop edge on the main path runs
359
+ into one rail on the right, ending at the `stop` cap, and a lane's own stop edge is a
360
+ `fail → stop` tag under its box. A `gate: human` brick wears the
361
+ person badge. The graph never scrolls sideways: it fits its pane. Lanes side by side come
362
+ first; when the rails do not fit, they become tags under the stage they leave, and the lanes
363
+ shrink to compact boxes (named without `loop:`). Only when even those do not fit (below about
364
+ 524 px for five lanes) do the lanes stack as a list. Under it: a legend, the cycles in
365
+ words, the `geneseed factory init` command with a Copy button, and the
366
+ factory's rules. It reads `GET /api/factories/catalog` for the install the *Install:* picker
367
+ names. **Active** is every run `geneseed factory init` registered on this machine
368
+ (`GET /api/factories/active`, polled every 5 s, the graph read from each run's `FACTORY.md`),
369
+ grouped as Loops › Active is; the reader shows the run's stage, transitions, task number, its
370
+ child loop's step and iteration, what it awaits, and its graph with the current stage lit,
371
+ the lane its last fork took (the run's `lane`, else read from its `history`) lit, the child loop's node lit in
372
+ the stage's ring and each cycle's laps as `n / max`. No run
373
+ reports tab: a run's report lives in its own worktree.
298
374
  - **Profile** (`#/profile`) — `PROFILE.md`: who you are and how you like to work, one card
299
375
  per file: the shared one every global install reads, tagged `shared`, and each project
300
376
  install's own. Opens rendered; **Edit** is a whole-file editor. The save carries
@@ -332,12 +408,16 @@ streams the output of background jobs and keeps their history across reloads.
332
408
  between polls. Tracking is on or off per install: the tracking
333
409
  card has one switch per install, and each switch changes only that install. OpenCode project
334
410
  installs have no switch: their sessions appear under, and follow, the OpenCode global switch. Sessions that ended in the last 7 days are listed under
335
- **Recently ended**, below the live ones. Every host records it:
411
+ **Recently ended**, below the live ones, in the list view only; the Garden shows live sessions only. Every host records activity:
336
412
  the OpenCode plugin, and `geneseed-hook activity` on Claude Code, OpenClaude and Bob.
337
413
  The live sessions open in the **Garden** by default; a **List | Garden** switch (kept in the
338
414
  URL with the filters, which apply to both) shows them as a list of cards instead. The Garden
339
- shows them as pixel bonsai: one shelf per repository (worktrees stand on their
340
- repo's shelf, tagged ⎇), one tree per session. The pot's glaze is the host (clay Claude Code,
415
+ shows them as pixel bonsai: one wooden shelf per repository (worktrees stand on their
416
+ repo's shelf, tagged ⎇), one tree per session, its pot on the plank. A brass plate on the
417
+ plank names the repository and its session count. Under each pot a caption gives the session
418
+ title (two lines at most; the full title is the tooltip and the link's name), the install and
419
+ status pills (working green, your move amber, blocked red, idle grey) and `<turns> turns · <context>%`. A
420
+ narrow screen stacks a shelf's trees onto several planks, the plate on the first. The pot's glaze is the host (clay Claude Code,
341
421
  blue Bob, grey OpenCode, violet OpenClaude); the tree grows taller with turns, its crown
342
422
  with context fill, and the tips yellow past 80 %. A compaction cuts the crown flat (it
343
423
  regrows as context refills) and leaves a notch on the rim. A running sub-agent is a thick
@@ -346,7 +426,9 @@ streams the output of background jobs and keeps their history across reloads.
346
426
  cannot tell, so all its blossoms sit on the crown). An amber `!` means the session needs
347
427
  you, a red `x` an error, a grey tree an idle session. Two sessions changing the same file
348
428
  are tied together in red (same worktree) or dashed amber (two worktrees of the repo): tangled
349
- roots in the moss when they stand side by side, a thread under the pots when they do not.
429
+ roots in the moss when they stand side by side, a thread across the plank when they do not.
430
+ Two trees on different planks get no thread; the hover card and the link's name still list
431
+ the shared files.
350
432
  Hover a tree for its model, turns, context and compactions, or a pad for its author's files;
351
433
  click it to open the session. With no mouse, tap a pad to show its files (a second tap clears them,
352
434
  and neither opens the session), or focus the tree and walk its pads with the arrow keys; Escape leaves. Past ten trees, quiet shelves (no session working or waiting on
@@ -398,8 +480,10 @@ streams the output of background jobs and keeps their history across reloads.
398
480
  own, about the tool and never one install: a sheet with a section index. **Machine**:
399
481
  version + Update (labelled by how this copy updates: git pull, npm install -g, or the command
400
482
  to run by hand; on the Overview the button shows only when the pull can run), Add to PATH. **Server**: running · port ·
401
- pid · uptime, whether the code matches the disk (with Restart), start-at-login state (read
402
- only), and the four request guards; the index marks Server with a good/warn dot. **About**: version, changelog, credits, source, creator.
483
+ pid · uptime, whether the code matches the disk (with Restart), Start at login (the
484
+ login launcher's state; it writes the file when absent, updates it when stale and removes it when
485
+ Geneseed wrote it, each after a confirm that names the file; a hand-written one gets only a
486
+ link to the guide), and the four request guards; the index marks Server with a good/warn dot. **About**: version, changelog, credits, source, creator.
403
487
  **Danger zone**: Stop server, Remove from PATH, and a pointer to each install's own
404
488
  Uninstall in Hosts.
405
489
  - **Appearance** (the topbar's popover, on every page) — the one home of the skin and the accent (a
@@ -2,5 +2,5 @@
2
2
  "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
3
3
  "theme": "neutral",
4
4
  "product": "Geneseed",
5
- "version": "5.0.1"
5
+ "version": "5.0.4"
6
6
  }
package/js/README.md CHANGED
@@ -21,6 +21,7 @@ js/hosts/ where it stops being a renderer and touches the machine
21
21
  js/inspect/ the read-only half: doctor, status, diff, validate, catalog
22
22
  js/lib/ primitives, every one a deliberate divergence from the Node default
23
23
  js/loop/ `geneseed loop` — the state machine over LOOP.md, and what it steps through
24
+ js/factory/ `geneseed factory` — the state machine over FACTORY.md, one level above loops
24
25
  js/maintain/ lifecycle verbs that change an install that already exists
25
26
  js/ui/ what it prints at a terminal
26
27
  js/web/ the `geneseed web` console
@@ -103,10 +104,10 @@ user co-owns, and the hook verbs those emitted configs then run.
103
104
  | `usage.mjs` | The usage counter `tool-gate` runs: one `{day, kind, name}` line per Skill or subagent call into `notebook/usage.jsonl`. Hook path: builtins only, silent, never throws |
104
105
  | `memory-files.mjs` | The memory store's file format — `frontmatter`, `MEMORY.md` index writes, agent lessons, consolidate — the `user-rules.md` parser, the draft's format and the fold's ledger reader. No spawn: the CLI, web console and fold import it |
105
106
  | `geneseed-dir.mjs` | The Node writers into a project's `<git root>/.geneseed/`: the personal-by-default `.gitignore` (`GENESEED_GITIGNORE`, pinned to the two OpenCode copies), and the protected-checks seed every project emit runs (`seedProtectedChecks`: seed once when absent, then the user's — never recorded, rewritten or uninstalled). Never throws, never writes through a link. Spawn-free |
106
- | `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `gitCommonDirOf`, `currentBranch`, `protectedBranches`, `stashExists`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate, `loss.mjs` and `js/loop/cli.mjs`'s commit-message writer |
107
+ | `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `gitCommonDirOf`, `currentBranch`, `protectedBranches`, `stashExists`, `loopLaunched`, `headCommit` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate, `loss.mjs` and `js/loop/cli.mjs`'s commit-message writer; `headCommit` by `js/factory/cli.mjs` (R2) |
107
108
  | `loss.mjs` | Law IV calibrated to real loss: `lossReason` decides whether a command would really lose data (protected branch, unpushed branch, dirty tree, stash, reflog, files git cannot restore) and fails closed. The gate path's one `git` spawn, reached only after `LOSS_CANDIDATE_RE` matched. Twin: the OpenCode guard plugin |
108
109
  | `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json` (one `loadJsonObject` reader for all of them) and the managed blocks |
109
- | `shim.mjs` | The machine-wide hook shim: its path, body, liveness (`shimDead`, read on every CLI run), `hookPrefix`/`hookRunnerEntry`. Kept cheap to import |
110
+ | `shim.mjs` | The machine-wide hook shim: its path, body, liveness (`shimDead`, read on every CLI run), `hookPrefix`/`hookRunnerEntry`; and the web console's login launcher (`autostartState`/`autostartInstall`/`autostartRemove`). Kept cheap to import |
110
111
  | `native.mjs` | Capability specs → host-native subagents and skills. The impure half of the emit |
111
112
  | `opencode.mjs` | OpenCode-only extras: colour themes, primary agent, `/commands`, plugins, overrides stub |
112
113
  | `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture, mode and loop trust preset |
@@ -185,7 +186,7 @@ transition, score and stop is computed here.
185
186
  |---|---|
186
187
  | `graph.mjs` | `checkGraph` — the rules a loop graph must satisfy before a node runs: nodes name real bricks, edges cover every outcome, `$close` is reachable, every cycle is inside a declared loop |
187
188
  | `score.mjs` | The risk arithmetic: `WEIGHTS`, `PRESETS`, `declaredRisk`/`actualRisk`/`decide`, `parseNumstat`. Pure — no import but node builtins |
188
- | `catalog.mjs` | `loadCatalog` — bricks and loop templates from shipped/global/project origins, later overrides earlier BY NAME |
189
+ | `catalog.mjs` | `loadCatalog` — bricks, loop templates and factories from shipped/global/project origins, later overrides earlier BY NAME |
189
190
  | `state.mjs` | The engine itself: `initState`, `nextStep`, `scoreDeclared`/`scoreDiff`, `recordOutcome`, `decideAwaiting`, `renderLoopFile`/`parseLoopFile` |
190
191
  | `cli.mjs` | `geneseed loop check\|init\|next\|score\|record\|decide` — the only face either a model or a human reaches this engine through |
191
192
  | `registry.mjs` | `loops.json` under XDG — the launched-loop identity list `loop init` records into and the Active tab's `activeLoops`/`setLoopPreset` read and rewrite |
@@ -203,6 +204,23 @@ fails. `activeLoops` saves the registry back only when the kept set actually cha
203
204
  root, a loop newly seen finished or seen running again) — a routine poll from the Active tab must
204
205
  never be a write.
205
206
 
207
+ ## `js/factory/` — the factory engine
208
+
209
+ `geneseed factory` — the loop engine one level up: a state machine over a graph of stages (a
210
+ brick or a whole loop; a fork's named outcomes pick its lane), persisted as a JSON block in
211
+ `FACTORY.md` beside `LOOP.md`. A child loop runs through `js/loop/` unchanged.
212
+
213
+ | module | owns |
214
+ |---|---|
215
+ | `graph.mjs` | `checkFactory` — the rules a factory must satisfy before a stage runs: stages exist, edges cover every outcome, `$close` is reachable, every cycle is declared (the loop engine's `undeclaredCycles`), `$lane` only behind a fork. Also the fork helpers the engine shares: `isFork`, `lanesOf`, `laneTargets`, `spentCycle` |
216
+ | `state.mjs` | The engine itself: `initFactory`, `nextStage`, `recordStage`, `decideFactory`, `renderFactoryFile`/`parseFactoryFile`, `validateFactoryState`, `countSpecTasks` |
217
+ | `cli.mjs` | `geneseed factory check\|list\|init\|next\|record\|decide` — the only face of this engine |
218
+ | `registry.mjs` | `factories.json` beside `loops.json`: `recordFactory` (called by `factory init`) and `activeFactories`, on the loop registry's own `loadRows`/`saveRows`/`sweepRows`. A run and its child loop share a root, which is how a reader groups them |
219
+
220
+ **Before editing:** `FACTORY.md` is in `js/loop/state.mjs`'s `ENGINE_FILES`, so a child loop never
221
+ scores it; the clean-tree check after a stage outside a loop filters with that same list. `cli.mjs`
222
+ may not spawn, and refuses `next`/`record` while a `LOOP.md` exists at the root.
223
+
206
224
  ## `js/maintain/` — lifecycle
207
225
 
208
226
  Verbs that change an install that already exists, as opposed to rendering one.
package/js/build/args.mjs CHANGED
@@ -12,7 +12,7 @@ import { withPlatformNewlines } from '../lib/fs.mjs';
12
12
  import path from 'node:path';
13
13
  import {
14
14
  CONFIG, discoverNames, GATE_SWITCHES, PACK_ORDER, SRC, knownRuleIds, knownSkillIds, linkedSkillIds, loadKits,
15
- resolveSkillNames, skillAliases,
15
+ resolveSkillNames, retiredRuleAddresses, skillAliases,
16
16
  } from './source.mjs';
17
17
  // The loop engine's trust presets — the `--trust` choices. `score.mjs` imports nothing, which is
18
18
  // what lets it sit inside this module's `child_process` ban.
@@ -67,8 +67,12 @@ export function configDefaults() {
67
67
  // as a flag, and `parseExcludeRules` dies on it — every rebuild of that install,
68
68
  // forever. Unknown ids are dropped with a WARN; the known ones still bind.
69
69
  const known = knownRuleIds();
70
+ const retired = retiredRuleAddresses(known);
70
71
  const ids = data.excludeRules.map((x) => x.trim().replace(/[ \t]+/, '.'));
71
- const unknown = ids.filter((id) => !known.includes(id));
72
+ for (const id of ids.filter((x) => retired.has(x))) {
73
+ warnRetiredRule(id, retired, `${path.basename(CONFIG)} "excludeRules"`);
74
+ }
75
+ const unknown = ids.filter((id) => !known.includes(id) && !retired.has(id));
72
76
  if (unknown.length) {
73
77
  process.stderr.write(`[geneseed] WARN: ${path.basename(CONFIG)} "excludeRules" names `
74
78
  + `unknown rule(s) ${unknown.map((id) => `'${id.replace('.', ' ')}'`).join(', ')}`
@@ -174,9 +178,11 @@ function parseExcludeRules(value) {
174
178
  const s = value.trim();
175
179
  if (s === 'none' || s === '') return [];
176
180
  const known = knownRuleIds();
181
+ const retired = retiredRuleAddresses(known);
177
182
  const out = [];
178
183
  for (const raw of s.split(',').map((x) => x.trim()).filter(Boolean)) {
179
184
  const id = raw.replace(/[ \t]+/, '.');
185
+ if (retired.has(id)) { warnRetiredRule(id, retired, '--exclude-rules'); continue; }
180
186
  if (!known.includes(id)) {
181
187
  die(2, `argument --exclude-rules: invalid choice: '${raw}' (choose from `
182
188
  + `${known.map((c) => `'${c.replace('.', ' ')}'`).join(', ')}, or 'none')`);
@@ -186,6 +192,12 @@ function parseExcludeRules(value) {
186
192
  return [...new Set(out)].sort();
187
193
  }
188
194
 
195
+ /** One stderr line for a retired address: it excludes nothing now, and the build goes on. */
196
+ function warnRetiredRule(id, retired, where) {
197
+ process.stderr.write(`[geneseed] WARN: ${where}: '${id.replace('.', ' ')}' was retired `
198
+ + `(${retired.get(id)}) — ignoring it.\n`);
199
+ }
200
+
189
201
  /**
190
202
  * `--exclude-skills "bruno,openscad"` -> the cfg's skill exclusion array.
191
203
  *
@@ -11,7 +11,7 @@ import { claimer, loadAgentOverrides, writeNativeLayer } from '../hosts/native.m
11
11
  import { ensureAgentOverridesStub, writeAliasCommands } from '../hosts/opencode.mjs';
12
12
  import {
13
13
  managedBlockRemove, managedBlockWrite, mergeClaudeSettings,
14
- unwireClaudeExcludes, unwireClaudeSettings, wireClaudeExcludes,
14
+ unwireClaudeEnv, unwireClaudeExcludes, unwireClaudeSettings, wireClaudeEnv, wireClaudeExcludes,
15
15
  } from '../hosts/settings.mjs';
16
16
  import { get, isDict, isTruthy } from '../lib/json.mjs';
17
17
  import { relPosix } from '../lib/text.mjs';
@@ -281,6 +281,7 @@ function claudeWire(job, claudeMdText, hasAgentText, doctrines = null, excludeRu
281
281
  if (oldSf !== settingsName) {
282
282
  unwireClaudeSettings(path.join(cfgDir, oldSf), get(old, 'settings_hooks') || []);
283
283
  unwireClaudeExcludes(path.join(cfgDir, oldSf), get(old, 'settings_excludes') || []);
284
+ unwireClaudeEnv(path.join(cfgDir, oldSf), get(old, 'settings_env'));
284
285
  }
285
286
  // The merge prunes recorded groups that are no longer canonical and returns the
286
287
  // COMPLETE current claim set — store it as-is; unioning with prior would resurrect the
@@ -293,6 +294,13 @@ function claudeWire(job, claudeMdText, hasAgentText, doctrines = null, excludeRu
293
294
  doctrines, excludeRules, host, cfgDir, gates,
294
295
  );
295
296
  managed.settings_hooks = managedHooks;
297
+ // The subagent depth cap, Claude Code only (`CLAUDE_ENV` says why). The record is what this
298
+ // install wrote, prior plus new, so uninstall never takes a key the user set themselves.
299
+ if (host === 'claude') {
300
+ const priorEnv = oldSf === settingsName && isDict(get(old, 'settings_env')) ? old.settings_env : {};
301
+ const env = { ...priorEnv, ...wireClaudeEnv(settingsPath) };
302
+ if (Object.keys(env).length) managed.settings_env = env;
303
+ }
296
304
 
297
305
  // Project-bypasses-global (Claude and OpenClaude): a PROJECT install suppresses the GLOBAL
298
306
  // ~/.claude/CLAUDE.md (or ~/.openclaude/CLAUDE.md) while cwd is this repo, via the shared
@@ -98,7 +98,8 @@ function opencodeLayer(cfg, items, themeName, theme, dir, owned, opts) {
98
98
  const wired = {};
99
99
  const cfgName = path.basename(mergeOpencodeJson(path.join(wireBase, 'opencode.json'),
100
100
  agentPath, cfg.doctrines, cfg.excludeRules, userOnlySkills, staleSkillNames, wired,
101
- cfg.deletionGate, opencodeEditAsks(dir, wireBase === dir, wireBase === dir ? null : agentPath), oldEdit));
101
+ cfg.deletionGate, opencodeEditAsks(dir, wireBase === dir, wireBase === dir ? null : agentPath,
102
+ cfg.doctrines, cfg.excludeRules), oldEdit));
102
103
  // The next record: Geneseed's earlier denies still wanted, plus the ones it added now. A merge
103
104
  // that wrote nothing (`skillsAdded` unset) keeps the old record whole.
104
105
  const skillDenies = wired.skillsAdded
@@ -88,6 +88,8 @@ export const RULE_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
88
88
  export const RETIRED_RULE_IDS = {
89
89
  'external-gate': { was: 'Law IX', liveAs: 'DOCTRINE', note: 'moved to the rigor pack' },
90
90
  'absence-is-a-claim': { was: 'Law XI', liveAs: null, note: 'folded into verify-before-asserting' },
91
+ // 2026-11-08: both rules set the reply format and shared one example, so one rule now holds both.
92
+ 'mark-the-ask': { was: 'comms 5', liveAs: null, note: 'merged into comms 1, Codes and Markers' },
91
93
  };
92
94
 
93
95
  /**
@@ -388,6 +390,23 @@ export function knownRuleIds() {
388
390
  return ruleCanon(SRC).rules.filter((r) => r.kind === 'DOCTRINE').map((r) => `${r.pack}.${r.n}`);
389
391
  }
390
392
 
393
+ /**
394
+ * `<pack>.<n>` -> why it names nothing now, for every retired doctrine rule whose address no
395
+ * live rule took over. Read off `RETIRED_RULE_IDS`' `was`, so the reason has one home. An
396
+ * install that excluded `comms 5` replays it on every rebuild; refusing it would break that
397
+ * rebuild forever, so the flag parsers warn and drop it instead. A live address is never
398
+ * retired: a rule appended later at the same number takes the address back.
399
+ */
400
+ export function retiredRuleAddresses(known = knownRuleIds()) {
401
+ const out = new Map();
402
+ for (const { was, note } of Object.values(RETIRED_RULE_IDS)) {
403
+ const m = /^([a-z]+) (\d+)$/.exec(was);
404
+ const id = m && `${m[1]}.${m[2]}`;
405
+ if (id && PACK_ORDER.includes(m[1]) && !known.includes(id)) out.set(id, note);
406
+ }
407
+ return out;
408
+ }
409
+
391
410
  /**
392
411
  * Every skill this checkout ships: a flat `skills/<name>.md` (authoring `_` files are not
393
412
  * skills) or a vendored `skills/<name>/` folder. The one enumerator `--exclude-skills` closes
@@ -525,9 +544,9 @@ export function resolveSkillNames(names, {
525
544
  }
526
545
 
527
546
  /**
528
- * The hook gates an install can switch off (the laws', in law order, then the ownership gate,
529
- * which has no law: `law: null`): the cfg/profile key, the
530
- * build flag, the carrier marker (`<marker>: off`, written only when off) and the law. ONE
547
+ * The hook gates an install can switch off (the laws', in law order, then the rows no law owns:
548
+ * `law: null`, appended so an existing install's argv and marker order never move): the
549
+ * cfg/profile key, the build flag, the carrier marker (`<marker>: off`, written only when off) and the law. ONE
531
550
  * table, so the flag, the marker, the rebuild argv, the read-back and `status` cannot drift
532
551
  * apart. Every gate is ARMED by default and the law's text binds either way. The deletion row
533
552
  * is #319's, unchanged: existing installs carry its flag and marker.
@@ -539,6 +558,12 @@ export const GATE_SWITCHES = [
539
558
  // Not a law's gate (`law: null`): the ownership first-write gate (js/hosts/ownership-gate.mjs,
540
559
  // ruling D25). Its off switch is this flag, never `harness.config.json` (args.mjs says why).
541
560
  { key: 'ownershipGate', flag: '--no-ownership-gate', arg: 'noOwnershipGate', marker: 'Ownership gate', law: null },
561
+ // Rigor 5's hook, so a doctrine's and no law's: protected checks and the gates' own configuration
562
+ // stop asking. Excluding the doctrine is the other axis: it drops the text, never this hook.
563
+ { key: 'externalGate', flag: '--no-external-gate', arg: 'noExternalGate', marker: 'External gate', law: null },
564
+ // Cure the Cause's weakened-test note, edit time and turn end. Advisory, so no gate the doctor
565
+ // pins (`HOOK_PINNED`; ledger key `cure-the-cause`): `law: null`, though the console shows it on Rule VIII.
566
+ { key: 'testNote', flag: '--no-test-note', arg: 'noTestNote', marker: 'Test note', law: null },
542
567
  ];
543
568
 
544
569
  /**