geneseed 5.3.1 → 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +21 -18
  3. package/SHIPPED.md +7 -7
  4. package/adapters/opencode/README.md +3 -2
  5. package/adapters/opencode/plugins/geneseed-context.js +6 -0
  6. package/adapters/opencode/plugins/geneseed-guard.js +5 -3
  7. package/bin/geneseed-cli.mjs +7 -0
  8. package/bin/geneseed-hook.mjs +3 -3
  9. package/docs/PRD.md +1 -1
  10. package/docs/README.md +1 -0
  11. package/docs/concepts/agents.md +1 -1
  12. package/docs/concepts/collaboration.md +2 -2
  13. package/docs/concepts/enforcement-table.md +5 -2
  14. package/docs/concepts/exclusions.md +16 -2
  15. package/docs/concepts/footprint.md +1 -1
  16. package/docs/concepts/foreman-mode.md +1 -1
  17. package/docs/concepts/hook-gates.md +3 -3
  18. package/docs/concepts/hooks.md +4 -3
  19. package/docs/concepts/host-matrix.md +2 -2
  20. package/docs/concepts/kits.md +12 -2
  21. package/docs/concepts/loop-bricks.md +3 -3
  22. package/docs/concepts/loops.md +6 -4
  23. package/docs/concepts/ownership.md +1 -1
  24. package/docs/concepts/rules.md +2 -2
  25. package/docs/concepts/skills.md +1 -1
  26. package/docs/extending.md +63 -28
  27. package/docs/guides/auto-merge.md +100 -0
  28. package/docs/guides/choose-your-setup.md +1 -1
  29. package/docs/guides/headless.md +1 -1
  30. package/docs/guides/install-clone.md +1 -1
  31. package/docs/guides/install.md +1 -1
  32. package/docs/guides/loop-finish.md +3 -3
  33. package/docs/guides/loop-running.md +4 -4
  34. package/docs/guides/project-context.md +1 -1
  35. package/docs/guides/run-a-factory.md +2 -2
  36. package/docs/guides/setup-doctrines.md +2 -2
  37. package/docs/guides/setup-footprint.md +1 -1
  38. package/docs/guides/uninstall.md +3 -3
  39. package/docs/guides/upgrade.md +1 -1
  40. package/docs/guides/worktree.md +1 -1
  41. package/docs/reference/environment.md +4 -2
  42. package/docs/reference/plugin-activity.md +1 -1
  43. package/docs/reference/plugin-guard.md +1 -1
  44. package/docs/reference/plugin-learn.md +1 -1
  45. package/docs/reference/plugin-workflow.md +1 -1
  46. package/docs/reference/troubleshoot-doctor.md +1 -1
  47. package/docs/reference/troubleshoot-hooks.md +2 -2
  48. package/docs/reference/troubleshoot-install.md +3 -3
  49. package/docs/reference/troubleshoot-tools.md +1 -1
  50. package/docs/token-footprint.md +2 -2
  51. package/docs/understand/enforced-vs-asked.md +1 -1
  52. package/docs/understand/machine-claude.md +2 -2
  53. package/docs/understand/on-your-machine.md +1 -1
  54. package/docs/web-ui.md +5 -5
  55. package/harness.config.json +1 -1
  56. package/js/README.md +2 -1
  57. package/js/build/args.mjs +12 -1
  58. package/js/build/driver.mjs +33 -6
  59. package/js/build/emit-claude.mjs +8 -4
  60. package/js/build/emit-opencode.mjs +13 -9
  61. package/js/build/generate.mjs +10 -156
  62. package/js/build/profile.mjs +318 -0
  63. package/js/build/render.mjs +81 -3
  64. package/js/build/retired-skills.mjs +60 -13
  65. package/js/build/source.mjs +15 -1
  66. package/js/build/stubs.mjs +4 -1
  67. package/js/cli-table.json +48 -3
  68. package/js/hosts/hooks-done.mjs +345 -55
  69. package/js/hosts/hooks-learn.mjs +4 -3
  70. package/js/hosts/hooks-prims.mjs +5 -3
  71. package/js/hosts/hooks.mjs +153 -6
  72. package/js/hosts/installs.mjs +19 -1
  73. package/js/hosts/native.mjs +19 -2
  74. package/js/hosts/settings.mjs +29 -3
  75. package/js/inspect/checks-constitution.mjs +32 -0
  76. package/js/inspect/diff.mjs +21 -3
  77. package/js/inspect/inventory.mjs +1 -1
  78. package/js/maintain/setup.mjs +5 -1
  79. package/js/maintain/update.mjs +4 -2
  80. package/js/web/actions.mjs +16 -3
  81. package/js/web/api.mjs +7 -2
  82. package/package.json +1 -1
  83. package/registry.json +14 -0
  84. package/src/AGENT.md.tmpl +15 -17
  85. package/src/bricks/pr-open.md +3 -2
  86. package/src/doctrines/ops.md +2 -2
  87. package/src/doctrines/process.md +40 -36
  88. package/src/factories/analysis-to-build.json +1 -1
  89. package/src/factories/bug-report-to-fix.json +1 -1
  90. package/src/factories/issue-to-pr.json +1 -1
  91. package/src/kits/terminal-tools/rules.md +10 -0
  92. package/src/kits/terminal-tools.json +13 -0
  93. package/src/licenses/herdr.txt +201 -0
  94. package/src/modes/foreman.md +6 -3
  95. package/src/skills/_self-improvement.md +9 -7
  96. package/src/skills/commit.md +17 -17
  97. package/src/skills/debug/ci.md +1 -1
  98. package/src/skills/dependencies.md +3 -3
  99. package/src/skills/document-project.md +3 -2
  100. package/src/skills/factory.md +13 -4
  101. package/src/skills/geneseed.md +4 -2
  102. package/src/skills/git-history.md +5 -7
  103. package/src/skills/herdr.md +135 -0
  104. package/src/skills/loop.md +3 -2
  105. package/src/skills/opencode-cli.md +84 -0
  106. package/src/skills/pipeline.md +1 -1
  107. package/src/skills/release.md +5 -8
  108. package/src/skills/review-response.md +4 -2
  109. package/src/skills/rule.md +27 -1
  110. package/src/skills/ship.md +54 -7
  111. package/src/skills/worktree.md +2 -2
  112. package/src/upstreams.json +7 -0
  113. package/themes/_TEMPLATE.json +2 -0
  114. package/themes/biker.json +2 -0
  115. package/themes/commentator.json +2 -0
  116. package/themes/cyberpunk.json +2 -0
  117. package/themes/gamer.json +2 -0
  118. package/themes/imperial.json +2 -0
  119. package/themes/joker.json +2 -0
  120. package/themes/marvin.json +2 -0
  121. package/themes/mean.json +2 -0
  122. package/themes/military.json +2 -0
  123. package/themes/neutral.json +2 -0
  124. package/themes/pirate.json +2 -0
  125. package/themes/sports.json +2 -0
  126. package/themes/verstappen.json +2 -0
  127. package/themes/wizard.json +2 -0
  128. package/web/dist/assets/Activity-D2kOc3yi.js +1 -0
  129. package/web/dist/assets/ActivityDetail-By3xOr21.js +1 -0
  130. package/web/dist/assets/{Bonsai-BBl4XXqs.js → Bonsai-CBWDTBA4.js} +1 -1
  131. package/web/dist/assets/{CopyButton-Beven8yn.js → CopyButton-BVbpriMB.js} +1 -1
  132. package/web/dist/assets/Dashboard-CIJLPHM9.js +2 -0
  133. package/web/dist/assets/Docs-CiRRIELs.js +5 -0
  134. package/web/dist/assets/Factories-DhyK0O8d.js +1 -0
  135. package/web/dist/assets/{GreenhouseView-Bce212qd.js → GreenhouseView-DW3PgTPy.js} +1 -1
  136. package/web/dist/assets/Installs-B6nlo-Ly.js +3 -0
  137. package/web/dist/assets/{JournalView-CV4omyww.js → JournalView-O65qEWfp.js} +1 -1
  138. package/web/dist/assets/Kits-C5U-yT6Z.js +1 -0
  139. package/web/dist/assets/Laws-CuTw_XNf.js +4 -0
  140. package/web/dist/assets/{LibRows-Dag1s0ZX.js → LibRows-D6-CVa3K.js} +1 -1
  141. package/web/dist/assets/Library-CzPlerd6.js +3 -0
  142. package/web/dist/assets/Loops-CqNF_-nS.js +2 -0
  143. package/web/dist/assets/{OperatorHudView-JmYY1pBR.js → OperatorHudView-BNr8K5qj.js} +1 -1
  144. package/web/dist/assets/Personal-DeDb9e8O.js +2 -0
  145. package/web/dist/assets/Settings-B8MPN_AD.js +1 -0
  146. package/web/dist/assets/{Tabs-8zsyEPSK.js → Tabs-DJzAez4h.js} +1 -1
  147. package/web/dist/assets/index-BL3P-9Rg.js +6 -0
  148. package/web/dist/index.html +1 -1
  149. package/web/dist/assets/Activity-WQ3ykgxU.js +0 -1
  150. package/web/dist/assets/ActivityDetail-7rt04SkS.js +0 -1
  151. package/web/dist/assets/Dashboard-BgLArtgu.js +0 -2
  152. package/web/dist/assets/Docs-B5aHp86J.js +0 -5
  153. package/web/dist/assets/Factories-BjqzXAw8.js +0 -1
  154. package/web/dist/assets/Installs-B1OsrHXF.js +0 -3
  155. package/web/dist/assets/Kits-CW1e7xNa.js +0 -1
  156. package/web/dist/assets/Laws-1Ckf1lbs.js +0 -4
  157. package/web/dist/assets/Library-B3FuFLel.js +0 -3
  158. package/web/dist/assets/Loops-CwqgnLNw.js +0 -2
  159. package/web/dist/assets/Personal-DKLgLa7Z.js +0 -2
  160. package/web/dist/assets/Settings-BwErnh-R.js +0 -1
  161. package/web/dist/assets/index-Ce6qF2nG.js +0 -6
@@ -28,13 +28,13 @@ geneseed loop next # what to do now, as one JSON
28
28
 
29
29
  Then repeat `geneseed loop next` and act on what it prints:
30
30
 
31
- | `next` prints | You run |
31
+ | The engine prints | You run |
32
32
  | --- | --- |
33
33
  | `{node, validate: true}` | `geneseed loop score --declared` (or, for a setup brick, `--actions … --write-set '…' --intent …`) |
34
34
  | `{node}` | the brick's prompt, then `git status --porcelain \| geneseed loop record --outcome <outcome>` (the iteration head adds `--card '<json>'` when it reports `more`) |
35
35
  | `{verify, run}` | exactly the printed `run` command, which pipes the staged numstat into `geneseed loop score --diff` |
36
36
  | `{awaiting}` | `geneseed loop decide --verdict ok\|no\|amend --note "…"` |
37
- | `{commit: true, message_file}` | `git add -A && git commit -F <message_file> && git push -u origin HEAD:loop/<slug>` |
37
+ | `{commit: true, message_file}` (from `score --diff` or `decide`, never from `next`) | `git add -A && git commit -F <message_file> && git push -u origin HEAD:loop/<slug>` |
38
38
  | `{terminal}` | nothing more: `$close` or `$stop` |
39
39
 
40
40
  Every flag is in `geneseed loop --help`. The full cycle, including discards and notes, is in [Loops](../concepts/loops.md).
@@ -43,7 +43,7 @@ Every flag is in `geneseed loop --help`. The full cycle, including discards and
43
43
 
44
44
  | Symptom | Cause and fix |
45
45
  | --- | --- |
46
- | It stopped as blocking on a small change | The diff touched a file outside the iteration's declared write set, which raises the score to at least the API weight. Check the reasons it shows. Answer ok if the file belongs to the change, or amend with a note to keep it out. |
46
+ | It stopped as blocking on a small change | The diff touched a file outside the iteration's declared write set, which raises the score to at least 0.8 (the default API weight). Check the reasons it shows. Answer ok if the file belongs to the change, or amend with a note to keep it out. |
47
47
  | The git gate asks on every iteration's commit | Only one exact shape is exempt. A `cd …` prefix, `git -C`, a quoted refspec (`"HEAD:loop/x"`), `git commit -m` or a message-file path with a space all fall back to asking. Make sure the session works from the worktree itself. |
48
48
  | The final `close` commit asks | Expected. The loop is over, and that ask is your consent to close it. |
49
49
  | `mutation-check` reported `unavailable` | No mutation tool is configured. The loop continues and records the gap in `LOOP.md`'s notes. Add PIT, Stryker, mutmut or cargo-mutants to make it bite. |
@@ -20,7 +20,7 @@ Each iteration is one commit on `loop/<slug>`, pushed as it lands. Work done bef
20
20
 
21
21
  The agent ends its turn and shows you what it is waiting on:
22
22
 
23
- - **A blocking score**: the change it plans (before it runs) or the staged diff (after), with the reasons for the score. One file outside the declared write set, more than 20 deleted lines, or a file that matches the loop's `contracts` is enough.
23
+ - **A blocking score**: the change it plans (before it runs) or the staged diff (after), with the reasons for the score. One file outside the declared write set, more than 20 deleted lines, or a file that matches the loop's `contracts` is enough under `prudent` and `balanced`; under `aggressive` each of these lands as a soft score, and a template can lower the deletion weight (`remove-dead-code` does).
24
24
  - **A human gate**: some bricks always stop for you, whatever the preset. An ADR that survived its skeptic (`adr-challenge`), an architecture rule and its allowlist (`fitness-define`), a contract migration plan (`migration-plan`) and a feature spec (`spec`) are all gated.
25
25
  - **Launch**, under `prudent`: the graph it is about to run.
26
26
 
@@ -29,8 +29,8 @@ Answer in the agent's session, in your own words:
29
29
  | You say | What happens |
30
30
  | --- | --- |
31
31
  | ok / go ahead | It continues. On a gate held on a failure, ok follows that failure's edge, which usually stops the loop. |
32
- | no | The loop stops at that node. |
33
- | amend, with a note ("keep the old field until v3") | The same brick runs again with your note added to `LOOP.md`. A gate can be amended three times per iteration; a fourth amend stops the loop. |
32
+ | no | At a gate, at the launch prompt or during a setup unit, the loop stops. On a blocking score, that iteration's change is dropped (the planned one) or discarded (the diff), and the loop goes on from the iteration head. |
33
+ | amend, with a note ("keep the old field until v3") | Your note is added to `LOOP.md`. At a gate the same brick runs again; on a blocking score the brick that changes code runs with your note. A gate can be amended three times per iteration; a fourth amend stops the loop. |
34
34
  | amend, at the `prudent` launch prompt | The loop stops ("graph to amend") with your note: nothing has run yet, so ask again for the loop you want. |
35
35
 
36
36
  The agent passes your answer on as `geneseed loop decide --verdict ok|no|amend --note "<your words>"`. The console never answers for you.
@@ -57,7 +57,7 @@ A loop ends one of two ways:
57
57
  | End | When |
58
58
  | --- | --- |
59
59
  | `$close` | The iteration head reports nothing left to do. Some templates first run an independent `done-check`. |
60
- | `$stop` | A brick reported an outcome wired to stop (a red baseline in `baseline-green`, say), you answered no, a gate was amended a fourth time, two iterations in a row produced no diff, an inner retry ring ran out twice in one iteration, a read-only brick changed files, or the iteration ceiling was reached (the template's `max`, never above 20). |
60
+ | `$stop` | A brick reported an outcome wired to stop (a red baseline in `baseline-green`, say), you answered no at a gate, at launch or during setup, a gate was amended a fourth time, two iterations in a row produced no diff, an inner retry ring ran out twice in one iteration, a read-only brick changed files, or the iteration ceiling was reached (the template's `max`, never above 20). |
61
61
 
62
62
  On `$stop` the agent reports the reason and leaves the branch as it is.
63
63
 
@@ -21,7 +21,7 @@ The context step sorts every doc it finds into one of two lists:
21
21
 
22
22
  With no configuration, the context step finds these files:
23
23
 
24
- - **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md` (or their AsciiDoc `.adoc` twins). The root file your tool already loads by itself is skipped, so you never pay for it twice. On Claude Code that covers `AGENTS.md` too, when `CLAUDE.md` imports it with `@AGENTS.md`, or when the repo has no `CLAUDE.md` and Claude Code is 2.1.277 or newer. If the hook cannot read the version, it injects the file.
24
+ - **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md` (or their AsciiDoc `.adoc` twins), and a repo-root `user-rules.md` and `PROFILE.md`. The root file your tool already loads by itself is skipped, so you never pay for it twice. On Claude Code that covers `AGENTS.md` too, when `CLAUDE.md` imports it with `@AGENTS.md`, or when the repo has no `CLAUDE.md` and Claude Code is 2.1.277 or newer. If the hook cannot read the version, it injects the file.
25
25
  - **Lazy:** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/` and `ADR/`, monorepo `packages/*/README.md` and `apps/*/README.md`, and any other root `*.md`. AsciiDoc docs (`.adoc`) are found everywhere a `.md` is.
26
26
  - **Never scanned:** `node_modules`, `.git`, `dist`, `build`, `vendor`, `.next`, `target`, `.venv`, `__pycache__`, `.opencode` and `.harness`.
27
27
 
@@ -6,7 +6,7 @@ kind: "concept"
6
6
  section: "Factories"
7
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
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. No stage merges: at the end the agent asks you once whether to merge, and merges only on your yes.
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. No stage merges: at the end the agent asks you once whether to merge, and merges only on your yes. With your standing auto-merge rule it arms the forge's auto-merge instead ([Auto-merge green PRs](auto-merge.md)).
10
10
 
11
11
  This page is the how-to. For how the engine works (stages, cycles, state files), see [Factories](../concepts/factories.md).
12
12
 
@@ -116,7 +116,7 @@ run the analysis-to-build factory on docs/analysis/export-csv.md
116
116
  | `merge-gate` reports `none` | The repo runs no CI on the PR: `ok` goes on to `retro`, `no` stops the run. Or the finding starts `environment:`: CI was still pending after 30 minutes, or `gh`/`glab` is missing or failed. `amend` waits again (after you fix the tool), `ok` goes on to `retro` without a green verdict (the close step reads CI once more, and proposes the merge only when it is green), `no` stops. |
117
117
  | A `geneseed factory record` line asks | The git gate asks on any command line that holds the word `git` and the word `commit` or `push`. A record line starts with `git status`, so a spec path, a finding's path or an outcome name with `commit` or `push` in it makes the gate ask. On a record line this is a false alarm: answer yes. |
118
118
  | 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. A run with no loop (the `docs` lane) never committed `FACTORY.md`: the agent deletes the file, there is no close commit, and the final state is the one `merge-gate` read. |
119
- | The merge proposal | Only when that final CI state is green: the agent shows the PR, the CI state and each review seat's verdict, and asks once whether to merge. Only on your explicit yes in chat does it squash-merge (`gh pr merge --squash`); no Geneseed gate asks before that command, so your answer is the only guard. Otherwise the PR stays open. It never turns on auto-merge. |
119
+ | The merge proposal | Only when that final CI state is green: the agent shows the PR, the CI state and each review seat's verdict, and asks once whether to merge. Only on your explicit yes in chat does it squash-merge (`gh pr merge --squash`); no Geneseed gate asks before that command, so your answer is the only guard. Otherwise the PR stays open. With your standing auto-merge rule, it arms the forge's auto-merge on the final head instead (the `review-panel` verdict counts as the `reviewer` pass), and a green head then merges at once; see [Auto-merge green PRs](auto-merge.md). |
120
120
 
121
121
  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, and so do a failed `checks` and a failed `review-panel`. A holdout `error` stops the run: the diff touched the holdout folder, or a scenario could not be played.
122
122
 
@@ -31,7 +31,7 @@ The packs always load in the same order (craft, rigor, ops, process, comms), wha
31
31
 
32
32
  **Dropping `process` changes what the machine does, not only what the agent reads.** The *Consent Before Push* rule in that pack is enforced at the tool boundary as well as in the prose:
33
33
 
34
- - On Claude Code and OpenClaude, the git hook stays wired but stops asking before a commit or push.
34
+ - On Claude Code and OpenClaude, the git hook stays wired but stops asking before a commit or push onto the main branch.
35
35
  - On OpenCode, a fresh install no longer gets the `git commit*` and `git push*` ask entries in `opencode.json`. On an existing install, the entries Geneseed recorded adding are removed. Entries you typed, and those on an install made before 5.2.0, are left in place and reported; build once with `--prune-gates` to remove the second kind.
36
36
 
37
37
  The refusals of destructive git and `rm -rf` belong to the always-on Rules, not to the pack, so they stay in every build. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
@@ -48,7 +48,7 @@ geneseed build --emit opencode-global --exclude-rules none
48
48
 
49
49
  The number in an address is the rule's position in its pack, so it can change if a rule is added or removed. To see the current addresses, pass an address that does not exist: the build refuses it and lists every valid address. The web console's **Constitution** page has one switch per rule. You stage the changes there and apply them in a single rebuild.
50
50
 
51
- Excluding *Consent Before Push* (`process 5` today) takes the commit and push consent gate with it, exactly as dropping the whole `process` pack does. The console and the wizard both warn you before applying it. A pack whose every rule is excluded drops out of the build entirely. See [Exclusions](../concepts/exclusions.md) for excluding whole folders instead.
51
+ Excluding *Consent Before Push* (`process 5` today) takes the commit and push consent gate with it, exactly as dropping the whole `process` pack does. To keep the rule but ask for every commit and push, not only those onto the main branch, keep it on and build with `--strict-consent` instead (the *Strict consent* switch on the Constitution page). The console and the wizard both warn you before applying it. A pack whose every rule is excluded drops out of the build entirely. See [Exclusions](../concepts/exclusions.md) for excluding whole folders instead.
52
52
 
53
53
  ---
54
54
 
@@ -41,7 +41,7 @@ You have three ways to change a choice:
41
41
 
42
42
  - **Re-run the wizard** with `geneseed setup`. It pre-selects what the install already has, so holding Enter cannot widen a set you narrowed on purpose. The wizard does not ask about single rules, but it keeps any rule exclusions already in place.
43
43
  - **Use the web console** (`geneseed web`). the **Installs** page changes theme, footprint and the rest per install. **Constitution** toggles packs and rules.
44
- - **Run the build yourself.** Watch out: a flag you leave out takes the *generator's* default, not your install's current value. `geneseed status --json` prints, for every install, the exact `geneseed build` command that rebuilds it as it is. Start from that command and change the one flag you want.
44
+ - **Run the build yourself.** Watch out: a flag you leave out takes the *generator's* default, not your install's current value. So a build over an existing install that would change a setting you did not pass refuses, names each change, and prints the command that keeps them. `geneseed status --json` prints, for every install, the exact `geneseed build` command that rebuilds it as it is. Start from that command and change the one flag you want. `--reset` returns the settings you left out to their defaults, for that one build.
45
45
 
46
46
  ---
47
47
 
@@ -11,12 +11,12 @@ description: "Remove an install, and what stays behind."
11
11
  ## Remove an install
12
12
 
13
13
  ```
14
- geneseed uninstall # the project install in this folder, else the OpenCode global one
14
+ geneseed uninstall # the project install in this folder, else the one global install
15
15
  geneseed uninstall --target /path/to/repo # a project install
16
16
  geneseed uninstall --target ~/.claude # a global install: pass its config directory
17
17
  ```
18
18
 
19
- Without `--target`, the command picks the project install in the current folder if there is one, and the OpenCode global install otherwise. It prints what it will remove and asks before going on. Pass `--yes` to skip the question. In a shell without an interactive terminal, `--yes` is required: without it, the command refuses and exits 1.
19
+ Without `--target`, the command picks the project install in the current folder if there is one, and the one global install on the machine otherwise, whatever its host. With several global installs it refuses (exit code 2) and prints the `--target` command for each. It prints what it will remove and asks before going on. Pass `--yes` to skip the question. In a shell without an interactive terminal, `--yes` is required: without it, the command refuses and exits 1.
20
20
 
21
21
  To see where each install lives, run `geneseed status`. The web console's **Installs** page can also uninstall.
22
22
 
@@ -24,7 +24,7 @@ To see where each install lives, run `geneseed status`. The web console's **Inst
24
24
 
25
25
  Each install keeps a manifest, a list of the files Geneseed wrote. **Uninstall deletes exactly those files and nothing else**, then removes any folders they leave empty. A file of yours that sits in the same folder stays.
26
26
 
27
- - **OpenCode global:** `AGENT.md`, `agents/`, `skills/`, `plugins/`, the marker files, and the `instructions` entry in `opencode.json`.
27
+ - **OpenCode global:** `AGENT.md`, Geneseed's managed block in `AGENTS.md`, `agents/`, `skills/`, `plugins/`, the marker files, and the `instructions` entry in `opencode.json`.
28
28
  - **OpenCode per repo:** `AGENT.md`, `.opencode/`, `laws/`, `agents/`, `skills/`, and the `instructions` entry in `opencode.json`.
29
29
  - **Claude Code, Bob, OpenClaude:** `agents/`, `skills/`, the marker files, Geneseed's managed block in the instructions file (`CLAUDE.md` or `AGENTS.md`), and Geneseed's own hooks and exclusions in `settings.json`. Your own settings keys and hooks stay.
30
30
 
@@ -88,7 +88,7 @@ geneseed diff --full # with line-level diffs
88
88
  geneseed diff --out improvements.md # write the improvements file
89
89
  ```
90
90
 
91
- `diff` compares the global OpenCode install by default. Pass `--target <config dir>` to compare another install. A file you replaced with a link to your own copy (a skill folder junctioned or symlinked elsewhere, say) is listed as `linked`: Geneseed never writes through a link, so it is yours and not drift, and it stays out of the improvements file. A file unmodified since its build that differs only because the source moved on is listed as behind source; a rebuild updates it, and it stays out of the improvements file too. `diff` also lists every non-empty self-improvement note, the tier's included, and `--out` copies them into the improvements file; the upgrade export does not fire on notes alone, since a rebuild cannot lose them. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The web console's **Changes** page exports the same file.
91
+ `diff` compares the global install there is by default, whatever its host (with several, the first, which it names on stderr). Pass `--target <config dir>` to compare another install. A file you replaced with a link to your own copy (a skill folder junctioned or symlinked elsewhere, say) is listed as `linked`: Geneseed never writes through a link, so it is yours and not drift, and it stays out of the improvements file. A file unmodified since its build that differs only because the source moved on is listed as behind source; a rebuild updates it, and it stays out of the improvements file too. `diff` also lists every non-empty self-improvement note, the tier's included, and `--out` copies them into the improvements file; the upgrade export does not fire on notes alone, since a rebuild cannot lose them. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The **Local edits** tab of the web console's **Installs** page exports the same file.
92
92
 
93
93
  ## Moving from a clone to npm
94
94
 
@@ -46,4 +46,4 @@ It cannot ride Geneseed's install. Geneseed's plugins are single dependency-free
46
46
 
47
47
  ## Consent
48
48
 
49
- `worktree_delete` **commits before it removes the worktree.** The harness's *Consent Before Push* rule (when the `process` pack is built in) asks before a *shell* `git commit` through `opencode.json` permissions. This plugin commits through its own tool, so that gate never sees the commit. Before you call delete, review what it will commit, or keep the worktree and commit yourself.
49
+ `worktree_delete` **commits before it removes the worktree.** The harness's *Consent Before Push* rule (when the `process` pack is built in) asks before a *shell* `git commit` through `opencode.json` permissions (OpenCode asks for every commit: its globs cannot see the branch). This plugin commits through its own tool, so that gate never sees the commit. Before you call delete, review what it will commit, or keep the worktree and commit yourself.
@@ -20,6 +20,8 @@ Where Geneseed writes an install, and what an upgrade re-renders.
20
20
  | --- | --- | --- |
21
21
  | `GENESEED_HOME` | build / hooks | Directory holding the hook shim `bin/geneseed-hook` (default `~/.geneseed`). Change it, then rebuild, so the emitted hooks point at the new location. |
22
22
  | `GENESEED_ACTIVITY` | hooks, OpenCode plugin | `off` (or `0`, `false`, `no`) stops the activity writer; the hooks then load none of its code. Absent means on. See [geneseed-activity](plugin-activity.md). |
23
+ | `GENESEED_NO_USAGE` | hooks, OpenCode guard plugin, web console | Any value stops the usage counter: no skill or subagent call is appended to `notebook/usage.jsonl`, and the console reports the counter as off. |
24
+ | `GENESEED_LLM_TIMEOUT` | `learn` hook | Seconds the `learn` hook waits for the model CLI before it stops it and drops the partial reply (default 120; anything but a positive number means the default). |
23
25
  | `GENESEED_HOOK_TAP` | hooks | An absolute directory outside any repository. Every hook call then writes one file there, `<host>-<event>-<n>.json`, holding the payload's shape: keys kept, every string replaced by its type and length. For recording what a host really sends; unset, nothing is written. A directory inside a git worktree is refused. See [Verify it works](../guides/verify.md#bob-by-hand). |
24
26
  | `GENESEED_NO_SHIM_CHECK` | CLI | `1` silences the warning every `geneseed` command prints when the hook shim points at a path that no longer exists. For scripted callers; the `status` gates row still says `DEAD`. |
25
27
  | `OPENCODE_CONFIG_DIR` | OpenCode emits, `diff`, plugins | OpenCode's config dir — where the global install is written. OpenCode still loads `$XDG_CONFIG_HOME/opencode` beside it, so `status` and `doctor` warn when both hold a Geneseed install. |
@@ -36,7 +38,7 @@ Where Geneseed writes an install, and what an upgrade re-renders.
36
38
 
37
39
  ## OpenCode plugin variables
38
40
 
39
- Each OpenCode plugin's page lists its own switches: [guard](plugin-guard.md) (`GENESEED_GUARD`), [notify](plugin-notify.md) (`GENESEED_NOTIFY`, `GENESEED_NOTIFY_MIN_SECONDS`, `GENESEED_NOTIFY_TITLE`), [ponytail](plugin-ponytail.md) (`GENESEED_PONYTAIL`), [workflow](plugin-workflow.md) (`GENESEED_WORKFLOWS_DIR`) and [activity](plugin-activity.md) (`GENESEED_ACTIVITY`). `GENESEED_DEBUG=1` makes every plugin but guard and learn (which always log) say what it decided on stderr. `OPENCODE_DISABLE_LSP_DOWNLOAD` belongs to OpenCode itself: see [Language servers](../concepts/lsp.md).
41
+ Each OpenCode plugin's page lists its own switches: [guard](plugin-guard.md) (`GENESEED_GUARD`), [notify](plugin-notify.md) (`GENESEED_NOTIFY`, `GENESEED_NOTIFY_MIN_SECONDS`, `GENESEED_NOTIFY_TITLE`), [ponytail](plugin-ponytail.md) (`GENESEED_PONYTAIL`), [workflow](plugin-workflow.md) (`GENESEED_WORKFLOWS_DIR`) and [activity](plugin-activity.md) (`GENESEED_ACTIVITY`). `GENESEED_DEBUG=1` makes every plugin but guard and learn (which always log) say what it decided. Context, notify, ponytail and activity write to stderr; guard, learn and workflow write to OpenCode's own log on OpenCode 1 (service `geneseed-<name>`) and to stderr on OpenCode 2. `OPENCODE_DISABLE_LSP_DOWNLOAD` belongs to OpenCode itself: see [Language servers](../concepts/lsp.md).
40
42
 
41
43
  ## Web console and CLI
42
44
 
@@ -44,7 +46,7 @@ How the `geneseed` command behaves and prints.
44
46
 
45
47
  | Variable | Read by | Effect |
46
48
  | --- | --- | --- |
47
- | `GENESEED_NO_WEB` | `geneseed` (bare) | `1` stops bare `geneseed` opening the web console; it falls back to the terminal menu. |
49
+ | `GENESEED_NO_WEB` | `geneseed` (bare) | Any value stops bare `geneseed` opening the web console; it prints the command list instead. |
48
50
  | `GENESEED_NODE` | `./geneseed`, `geneseed.cmd`, `install` scripts | Node interpreter to run (default `node` on PATH). |
49
51
  | `GENESEED_TUI_ASCII` | CLI output | Pure-ASCII output: no box-drawing or emoji. |
50
52
  | `GENESEED_TUI_PLAIN` | CLI output | Drop emoji and animation. |
@@ -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` (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.
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`, `Monitor`, `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
 
@@ -48,7 +48,7 @@ There is no DYNAMIC loop/* exemption on OpenCode — OpenCode 1 declares a `perm
48
48
 
49
49
  [What a prompt says](../concepts/hooks.md#what-a-prompt-says) lists what this text can and cannot tell you.
50
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.
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 OpenCode's own log on OpenCode 1 (service `geneseed-guard`) and to stderr on OpenCode 2.
52
52
 
53
53
  **Switches.**
54
54
  - `GENESEED_GUARD=warn` — log every block, allow the call.
@@ -12,7 +12,7 @@ One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed
12
12
 
13
13
  **When it runs.** After the session goes quiet. OpenCode signals "idle" after every turn, so each idle re-arms a timer and the distil runs once nothing has happened for `GENESEED_LEARN_DEBOUNCE_MS` (default 60 s). Trivial sessions are skipped.
14
14
 
15
- **What you see.** On stderr: `[geneseed-learn] wrote N memory file(s): …` (or `updated` / `archived`), or `skipped: <reason>`. Total silence means it did not load.
15
+ **What you see.** `wrote N memory file(s): …` (or `updated` / `archived`), or `skipped: <reason>`: in OpenCode's own log on OpenCode 1 (service `geneseed-learn`), on stderr as `[geneseed-learn] …` on OpenCode 2. Total silence in that place means it did not load.
16
16
 
17
17
  **Where it writes** — the first that resolves:
18
18
  1. `GENESEED_MEMORY` — an explicit memory dir;
@@ -20,6 +20,6 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
20
20
 
21
21
  **Switches.**
22
22
  - `GENESEED_WORKFLOWS_DIR` — load scripts from another directory.
23
- - `GENESEED_DEBUG=1` — log to stderr.
23
+ - `GENESEED_DEBUG=1` — log to OpenCode's own log on OpenCode 1 (service `geneseed-workflow`), to stderr on OpenCode 2.
24
24
 
25
25
  Ask the agent to *"list available workflows"* to check it loaded.
@@ -31,7 +31,7 @@ geneseed build
31
31
  git add Harness
32
32
  ```
33
33
 
34
- If the drift is your own edits, export them first — `geneseed diff` (or the console's **Changes** page) writes them up so they can be folded back into `src/`.
34
+ If the drift is your own edits, export them first — `geneseed diff --out` (or the **Local edits** tab of the console's **Installs** page) writes them up so they can be folded back into `src/`.
35
35
 
36
36
  **Confirm.** `geneseed doctor` no longer reports the bundle.
37
37
 
@@ -37,7 +37,7 @@ If you moved the shim itself with `GENESEED_HOME`, set it the same way before re
37
37
 
38
38
  ## A Bash/Write/Edit call is refused with `onFailure is "block"`
39
39
 
40
- Claude Code refuses a `Bash`, `PowerShell`, `Write`, `Edit` or `NotebookEdit` call outright, and the transcript carries wording like:
40
+ Claude Code refuses a `Bash`, `PowerShell`, `Monitor`, `Write`, `Edit` or `NotebookEdit` call outright, and the transcript carries wording like:
41
41
 
42
42
  > `PreToolUse:Bash hook error: [...]: failed; blocking because onFailure is "block"`
43
43
 
@@ -127,7 +127,7 @@ export GENESEED_MEMORY=/abs/path/to/memory
127
127
 
128
128
  This variable and `GENESEED_HARNESS` win over the shared store, so leave them unset on a global install. Both are deprecated, with removal planned for 6.0.
129
129
 
130
- **Confirm.** About a minute after the session goes quiet, stderr shows `[geneseed-learn] wrote N memory file(s): …` or a `skipped:` reason. Total silence means the plugin did not load.
130
+ **Confirm.** About a minute after the session goes quiet, OpenCode's own log (OpenCode 1, service `geneseed-learn`) or stderr (OpenCode 2, as `[geneseed-learn] …`) shows `wrote N memory file(s): …` or a `skipped:` reason. Total silence in that place means the plugin did not load.
131
131
  <!--/harness-->
132
132
 
133
133
  Model, read-only agent, document and MCP problems are on [their own page](troubleshoot-tools.md).
@@ -32,7 +32,7 @@ Run without the installer — `npx geneseed`, a global npm install, or a hook
32
32
 
33
33
  > `geneseed needs Node 22.7 or newer; this is Node 20.18.1. Install a current Node from https://nodejs.org (or your package manager), then run the command again.`
34
34
 
35
- **Cause.** The `node` on PATH is older than 22.7. npm only *warns* about the engine requirement, so a global install succeeds anyway. A hook prints the same sentence and lets the tool call through rather than block it, so on Claude Code, Bob or OpenClaude the hooks are off until Node is upgraded.
35
+ **Cause.** The `node` on PATH is older than 22.7. npm only *warns* about the engine requirement, so a global install succeeds anyway. A hook prints the same sentence on stderr and judges nothing: on Claude Code and OpenClaude each gated tool call then asks you, since no gate checked it, and on Bob the call passes. The other hooks (context, learn, activity) do nothing until Node is upgraded.
36
36
 
37
37
  **Fix.** Install the current Node.js LTS (see above), open a **new** terminal, and run the command again.
38
38
 
@@ -59,7 +59,7 @@ See [Install](../guides/install.md) for the emit target that matches your tool.
59
59
 
60
60
  Setup opens with `AI coding tools on this machine:` and an `ok` or `--` per tool.
61
61
 
62
- **Cause.** The check only asks whether the command (`opencode`, `claude`, `bob`, `openclaude`) is on your PATH. A desktop-only install with no command shows as missing; an unrelated program with the same name shows as present.
62
+ **Cause.** The check looks for the command (`opencode`, `claude`, `bob`, `openclaude`) on your PATH, then in the usual per-user folders, where a hit shows as `ok … (<where>, not on PATH)`. When it finds none of the four, it asks "Installed somewhere else?" and takes a path. An install in a folder it does not search shows as missing; an unrelated program with the same name shows as present.
63
63
 
64
64
  **Fix.** Nothing to fix — the line is advisory. Pick the install mode for the tool you actually use; a missing tool among several present is just a line, and you can continue without one.
65
65
 
@@ -85,7 +85,7 @@ reports `version "21` or higher.
85
85
 
86
86
  ## `geneseed: command not found`
87
87
 
88
- **Cause.** The `geneseed` launcher is not on your PATH. A git clone is not put there automatically (an `npm install -g geneseed` install is).
88
+ **Cause.** The `geneseed` launcher is not on your PATH. The clone's installer (`./install`, `install.cmd`) runs `link` for you, but a clone set up with `geneseed setup` alone is not linked, and a terminal opened before `link` ran does not see the change (an `npm install -g geneseed` install is put on PATH by npm).
89
89
 
90
90
  **Fix.** From the cloned folder:
91
91
 
@@ -22,7 +22,7 @@ export GENESEED_MODEL=provider/model
22
22
 
23
23
  ## A read-only agent won't run a command
24
24
 
25
- **Cause.** By design: read-only agents are denied the shell. The few that must run read-only commands (the reviewer, security) are allowed it in their own spec.
25
+ **Cause.** By design: read-only agents are denied the shell. Those that must run read-only commands (the reviewer, security and explorer, for example) are allowed it in their own spec.
26
26
 
27
27
  **Fix.** Hand the task to an agent that can run commands, or run it yourself. See [Agents](../concepts/agents.md).
28
28
 
@@ -94,12 +94,12 @@ until 2026-09 it did, and the whole harness was paid twice per session.
94
94
  - **User-only skills leave the catalogue.** A skill whose source carries
95
95
  `<!-- invocation: user -->` renders `disable-model-invocation: true`; Claude
96
96
  Code and Bob then drop its description from the always-on skill metadata and
97
- only `/name` opens it. The two teaching skills (`teach`, `learn-mode`)
97
+ only `/name` opens it. Three skills (`teach`, `learn-mode`, `adhd`)
98
98
  carry it today.
99
99
  - **Aliases cost 0 always-on.** A merged skill's old names (`<!-- aliases: -->`)
100
100
  ship as user-only stubs on Claude Code, Bob and OpenClaude, and as `/name` commands
101
101
  on OpenCode — never in the model's catalogue, so a rename or merge is free.
102
- - Plugin JavaScript (OpenCode, ~26k on disk) runs in the host runtime and
102
+ - Plugin JavaScript (OpenCode, about 380 KB on disk) runs in the host runtime and
103
103
  never enters the context window.
104
104
 
105
105
  ## Why there is no chat mode
@@ -29,7 +29,7 @@ On Claude Code and OpenClaude the hooks never block silently. They make the host
29
29
  - **Your rules and memory**: any write by the agent to `user-rules.md` or to the memory store. Whether something is a standing rule or a fact to remember is your call.
30
30
  - **The first write in an application with no ownership setup**: in a repo with a build manifest whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused once, as a reminder rather than a gate, with the reason sent to the agent rather than to you: it then asks you to set [ownership](../concepts/ownership.md) up now, skip this session, or skip in this repo until you ask. Off per repo with `mode: off`, for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, per install with `--no-ownership-gate`.
31
31
  - **The checks you are judged by, and the gates' own switches**: a write to a file listed in `.geneseed/protected-checks.txt`, to the done gate's list, or to a file that can switch a gate off (the hook settings, `excludes.json`, a gate marker in `AGENT.md`, the hook shim). You get a prompt. A shell write counts too, for the common forms: `>`, `>>`, `tee`, `sed -i`, `cp`, `mv`, `rm`. A script or an interpreter's inline code is not seen, so run the checks in CI as well.
32
- - **Ending a turn without the proof**: only in a project whose `.geneseed/done-checks.txt` lists at least one check; a file that lists none turns the gate off for that project. A turn that edited files cannot end until every listed check has passed since the last edit. The agent is stopped once, then the turn may end. Without that file, Geneseed infers the checks from the project's manifest (`package.json` scripts, Maven, Gradle, `pyproject.toml`, `Cargo.toml`, `go.mod`): you get a warning when a turn ends without them, but the turn is not stopped.
32
+ - **Ending a turn without the proof**: only in a project whose `.geneseed/done-checks.txt` lists at least one check; a file that lists none turns the gate off for that project. A turn that edited files cannot end until every listed check has passed since the last edit. The agent is stopped again only after a new edit or a changed background result, at most 3 times between two task notifications and 10 times in the whole turn, then the turn may end. A sub-agent is held to the same proof when it stops. Without that file, Geneseed infers the checks from the project's manifest (`package.json` scripts, Maven, Gradle, `pyproject.toml`, `Cargo.toml`, `go.mod`): you get a warning when a turn ends without them, but the turn is not stopped.
33
33
 
34
34
  If a gate crashes, it asks instead of letting the call through. If it cannot start at all (a deleted or broken shim) or times out, Claude Code blocks the call instead: see [Troubleshoot hooks](../reference/troubleshoot-hooks.md) to recover. Other shell commands go through Claude Code's normal permission flow; an `rm` of files git cannot restore is the real-loss case above.
35
35
 
@@ -14,11 +14,11 @@ What a Claude Code or OpenClaude install writes, piece by piece. The **Kind** wo
14
14
  | `CLAUDE.md` (managed block) | The rules, the pointers to agents and skills, and how memory works. Geneseed writes only its own block; your own lines in the file stay | asked | ~7.2k tokens every session | Shrink it with fewer doctrine packs (`--doctrines`); remove it with `geneseed uninstall` |
15
15
  | `user-rules.md` | Your own standing rules, read every session. A global install reads the [shared](../concepts/shared-tier.md) file first, then this one, which can narrow it. Seeded empty | asked | 0 until you write in it | Leave it empty |
16
16
  | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill. On a global install it lives in the shared tier, and a filled host file replaces the shared one | asked | 0 until you fill it | Leave the seeded text untouched |
17
- | context hook | At session start, and again after a resume or compaction, puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `geneseed exclude add <folder>` silences every hook in that folder |
17
+ | context hook | At session start, and again after a resume or compaction, puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs; the whole hook output is capped at 9,000 characters, and what does not fit is listed for the agent to read on demand | `geneseed exclude add <folder>` silences every hook in that folder |
18
18
  | git-gate hook | Before each shell command: asks you before any `git commit` or `git push`, and before a command that would really lose data — a force-push to `main`, a `reset --hard` that abandons unpushed commits, `branch -D` of an unpushed branch, an `rm` git cannot undo | enforced | ~14 ms per shell call | The commit/push question goes away if you build without the **process** pack; the destructive-git question has no switch except `geneseed exclude` |
19
19
  | rule-gate hook | Before each write or edit: asks you when the file would carry a credential-shaped string (outside `.env`), or when the agent writes to `user-rules.md` or memory. In an application repo with no `## Ownership` section in its root `AGENTS.md`, stops the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | ~14 ms per write | `geneseed exclude add <folder>`; the ownership stop alone: `mode: off` in the repo's `## Ownership`, `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, or rebuild with `--no-ownership-gate` |
20
20
  | learn hook | When the agent finishes a reply, and before compaction, distils durable facts from the recent conversation into the memory store. Off until you set `GENESEED_LLM` to a model command such as `claude -p` | automatic | One model call each time it runs, once enabled | Leave `GENESEED_LLM` unset (the default) |
21
- | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
21
+ | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~2.2k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
22
22
  | `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
23
23
  | `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context hook injects. A global install keeps them in the shared `~/.config/geneseed/memory/`; this folder holds only the convention and a seeded index | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
24
24
  | `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl`. It stays per host; on a global install only the self-improvement notes live in the shared `notes/` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
@@ -13,7 +13,7 @@ An install writes a handful of files into your host's config folder and, where t
13
13
  - **asked**: text the model reads every session. It usually follows it, but nothing makes it.
14
14
  - **on demand**: loads only when you or the agent call it by name.
15
15
 
16
- Token costs are for the default *lean* footprint. Before you type anything, a session carries about 12k tokens of harness. That is roughly 6% of a 200k window. A `--footprint full` build adds about 5k on the rules file. For a live figure on your own install, ask the agent to use the `token-report` skill.
16
+ Token costs are for the default *lean* footprint. Before you type anything, a session carries about 12k tokens of harness. That is roughly 6% of a 200k window. A `--footprint full` build adds about 7k on the rules file. For a live figure on your own install, ask the agent to use the `token-report` skill.
17
17
 
18
18
  ## One folder for the whole machine
19
19
 
package/docs/web-ui.md CHANGED
@@ -75,9 +75,9 @@ Every `/api/*` read takes and checks the pair, with these exceptions:
75
75
  - `/api/ping` and `/api/jobs` ignore it.
76
76
  - The machine-wide reads also ignore it: `/api/update`, `/api/installs`, `/api/fleet`, `/api/migrate/preview`,
77
77
  `/api/kits`, `/api/usage`, `/api/gates`, `/api/excludes`, `/api/mcp`, `/api/loops/active`,
78
- `/api/factories/active`, `/api/activity`, and the Library's skill, agent, memory and notebook lists,
79
- `/api/catalog/skills`, `/api/catalog/agents`, `/api/catalog/memory` and
80
- `/api/catalog/notebook`. Such a read does not check the pair, and its answer does not change
78
+ `/api/factories/active`, `/api/activity`, and the Library's skill, agent, memory, notebook, wiki and config lists,
79
+ `/api/catalog/skills`, `/api/catalog/agents`, `/api/catalog/memory`,
80
+ `/api/catalog/notebook`, `/api/catalog/wiki` and `/api/catalog/config`. Such a read does not check the pair, and its answer does not change
81
81
  with the pair. The Activity detail (`/api/activity/<id>`) and the Activity toggle still take
82
82
  the pair.
83
83
 
@@ -88,7 +88,7 @@ tier hold one memory store: it is listed under the first of them, and `/api/cata
88
88
  them all in `sharedInstalls`. Each row is one id (kind and name), and
89
89
  its `installs` field names the installs that have it, as `host:scope:root` keys (the same keys
90
90
  as `/api/usage`). An id that only some installs have lists only those installs, so an exclusion
91
- stays visible. The other catalog sections stay install-scoped. `/api/item/skill/<name>` and
91
+ stays visible. The laws section stays install-scoped. `/api/item/skill/<name>` and
92
92
  `/api/item/agent/<name>` stay install-scoped too, because each install renders its own copy in
93
93
  its own theme and footprint. With a pair, the item is that install's copy, and an id that
94
94
  install lacks gets a 404. Without a pair, the item is the copy of the first install that has
@@ -505,7 +505,7 @@ screen the run list stacks above the detail.
505
505
  - "Deploy to folder…" and "Rebuild all" apply to the whole set. An **Excluded folders**
506
506
  card (shown once a global install exists) manages sovereign repos — folders where every
507
507
  global harness goes dormant (hooks stay silent, the global preamble never loads);
508
- add or remove one here, the web mirror of `harness exclude add|remove|list`.
508
+ add or remove one here, the web mirror of `geneseed exclude add|remove|list`.
509
509
  - **Settings** (`#/settings`; `#/about` and `#/installs/server` resolve here) — a rail entry of its
510
510
  own, about the tool and never one install: a sheet with a section index. **Machine**:
511
511
  version + Update (labelled by how this copy updates: git pull, npm install -g, or the command
@@ -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.3.1"
5
+ "version": "5.4.0"
6
6
  }
package/js/README.md CHANGED
@@ -73,6 +73,7 @@ as a per-host install at project or global scope.
73
73
  | `driver.mjs` | The generator driver: the nine emit targets, per-host emit orchestration, the prune and the manifest. `bin/build-driver.mjs` is only its entry |
74
74
  | `args.mjs` | The generator's flag surface: `harness.config.json` defaults, the `--emit`/`--theme`/`--footprint` parse tables and choices, `-h`, and `die` (a throw, so `rebuild-all` survives one bad install) |
75
75
  | `generate.mjs` | CLI verbs `build`, `prompt`, `theme`, `rebuild-all` — the thin face over `driver.mjs` |
76
+ | `profile.mjs` | An install's profile (`installProfile`, `setupBuildArgs`, `rebuildCommand`: every setting read back, and the argv that re-emits it) and the preserve guard: a build over an existing install refuses to change a setting it was not given, unless `--reset`. A leaf the driver may import; `generate.mjs` re-exports the three |
76
77
  | `catalog.mjs` | `geneseed catalog` — prints the shipped roster. Classifies nothing itself |
77
78
  | `export.mjs` | `geneseed export` — skills, agents and the constitution as catalogue entities for a shared library (`SKILL.md`/`AGENT.md` + `metadata.yaml`), shaped by a profile kept outside the repo. One way, claim-on-create, not an install |
78
79
  | `themes.mjs` | Maintainer-only `--sync-themes`: inserts `_TEMPLATE.json`'s missing keys into the committed themes |
@@ -97,7 +98,7 @@ user co-owns, and the hook verbs those emitted configs then run.
97
98
  | `hooks.mjs` | The gate verbs, run on every tool call: `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), plus `ask`/the gate ledger/`guardGate`. `--host` picks the verdict dialect |
98
99
  | `hooks-context.mjs` | The `context` verb — SessionStart: session files (shared tier first on a global install, wiki rendered) plus the repo's context docs; `sessionStartSize`, the console's read of the same payload |
99
100
  | `ownership-gate.mjs` | The ownership first-write gate, last in `rule-gate`: in an application repo (git root + build manifest) whose root `AGENTS.md` has no `## Ownership` section, denies the session's first write once (a tmpdir marker per session). Builtins + `gitRootOf` only. Twin: the OpenCode guard plugin |
100
- | `hooks-done.mjs` | The done gate (#289): on Stop, inside `learn` and before its spawn, judges a turn that edited files against the project's checks — blocks until `.geneseed/done-checks.txt`'s checks passed after the last edit; without that file, the inferred checks are advisory (a `systemMessage`, never a block) |
101
+ | `hooks-done.mjs` | The done gate (#289): on Stop and SubagentStop, inside `learn` and before its spawn, judges a turn (a sub-agent's own, at SubagentStop, against each git root it wrote under) that edited files against the project's checks — blocks until `.geneseed/done-checks.txt`'s checks passed after the last edit; without that file, the inferred checks are advisory (a `systemMessage`, never a block) |
101
102
  | `done-checks.mjs` | Where the done gate's checks come from: `.geneseed/done-checks.txt`, else inferred from the git root's manifests (package.json scripts, pom.xml, Gradle, pyproject.toml, Cargo.toml, go.mod), each a group of accepted command forms; plus `doneLine`, the SessionStart line `context` prints. Spawn-free: `context` is in the CLI's closure. Twin: the OpenCode context plugin |
102
103
  | `hooks-learn.mjs` | The `learn` verb — Stop/SubagentStop/PreCompact distiller; the hook path's ONE spawn (`$GENESEED_LLM`) |
103
104
  | `hooks-prims.mjs` | The Python path/text primitives the hook verbs share (`splitLines`, `readStdin`, a never-throwing `isFile`), plus the activity off switch (`activityOn`) and the do-nothing `activity` verb |
package/js/build/args.mjs CHANGED
@@ -118,6 +118,10 @@ export const FLAGS = {
118
118
  // One build's instruction, never recorded: Geneseed's copy replaces a file the user edited
119
119
  // or put at a name Geneseed ships. `claimer` (js/hosts/native.mjs) holds the rule.
120
120
  '--force': 'force',
121
+ // One build's consent: the settings this build does not pass return to their defaults on the
122
+ // install it targets. Without it the preserve guard (js/build/profile.mjs) refuses such a
123
+ // build. Never recorded, never replayed.
124
+ '--reset': 'reset',
121
125
  '-v': 'verbose', '--verbose': 'verbose',
122
126
  };
123
127
 
@@ -374,9 +378,14 @@ export function parseArgs(argv, defaults) {
374
378
  kits: defaults.kits ?? [],
375
379
  sharedTier: 'off',
376
380
  out: 'Harness', emit: 'files', footprint: 'lean', root: null,
377
- syncThemes: false, validateOnly: false, verbose: false, pruneGates: false, force: false,
381
+ syncThemes: false, validateOnly: false, verbose: false, pruneGates: false, force: false, reset: false,
378
382
  ...Object.fromEntries(GATE_SWITCHES.map((g) => [g.arg, false])),
379
383
  };
384
+ // The keys the caller PASSED, for the preserve guard: after this walk a default and a value
385
+ // typed equal to it look the same, and only the second is intent. Non-enumerable, so
386
+ // `makeCfg(args)`'s rest spread never sees it.
387
+ const given = new Set();
388
+ Object.defineProperty(args, 'given', { value: given, enumerable: false });
380
389
  const { tokens } = nodeParseArgs({
381
390
  args: argv, options: PARSE_OPTIONS, allowPositionals: true, strict: false, tokens: true,
382
391
  });
@@ -393,6 +402,7 @@ export function parseArgs(argv, defaults) {
393
402
  if (tok.kind === 'option' && VALUED_BY_NAME[tok.name] !== undefined) {
394
403
  if (tok.value === undefined) die(2, `argument ${tok.rawName}: expected one argument`);
395
404
  args[VALUED_BY_NAME[tok.name]] = tok.value;
405
+ given.add(VALUED_BY_NAME[tok.name]);
396
406
  continue;
397
407
  }
398
408
  // `tok.value === undefined` excludes `--sync-themes=x` from matching here — a store_true
@@ -402,6 +412,7 @@ export function parseArgs(argv, defaults) {
402
412
  // given), so this must compare the VALUE, not `'value' in tok` — the key is always there.
403
413
  if (tok.kind === 'option' && tok.value === undefined && FLAG_BY_NAME[tok.name] !== undefined) {
404
414
  args[FLAG_BY_NAME[tok.name]] = true;
415
+ given.add(FLAG_BY_NAME[tok.name]);
405
416
  continue;
406
417
  }
407
418
  // Every other shape — an unrecognized option, a bare positional, or `--` (which `parseArgs`