geneseed 5.3.1 → 5.5.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 (248) hide show
  1. package/CHANGELOG.md +102 -0
  2. package/README.md +51 -18
  3. package/SHIPPED.md +7 -7
  4. package/adapters/bob/README.md +12 -1
  5. package/adapters/opencode/README.md +5 -3
  6. package/adapters/opencode/plugins/geneseed-context.js +77 -10
  7. package/adapters/opencode/plugins/geneseed-guard.js +106 -22
  8. package/adapters/opencode/plugins/geneseed-learn.js +641 -6
  9. package/bin/geneseed-cli.mjs +10 -0
  10. package/bin/geneseed-hook.mjs +5 -4
  11. package/docs/PRD.md +1 -1
  12. package/docs/README.md +1 -0
  13. package/docs/concepts/agents.md +14 -2
  14. package/docs/concepts/collaboration.md +2 -2
  15. package/docs/concepts/enforcement-table.md +5 -2
  16. package/docs/concepts/exclusions.md +16 -2
  17. package/docs/concepts/footprint.md +1 -1
  18. package/docs/concepts/foreman-mode.md +23 -4
  19. package/docs/concepts/hook-gates.md +4 -4
  20. package/docs/concepts/hooks.md +25 -7
  21. package/docs/concepts/host-matrix.md +4 -4
  22. package/docs/concepts/hosts.md +1 -1
  23. package/docs/concepts/kits.md +12 -2
  24. package/docs/concepts/loop-bricks.md +3 -3
  25. package/docs/concepts/loops.md +6 -4
  26. package/docs/concepts/ownership.md +1 -1
  27. package/docs/concepts/rules.md +2 -2
  28. package/docs/concepts/shared-tier.md +1 -1
  29. package/docs/concepts/skills.md +21 -1
  30. package/docs/concepts/themes.md +1 -1
  31. package/docs/extending.md +73 -29
  32. package/docs/guides/auto-merge.md +100 -0
  33. package/docs/guides/choose-your-setup.md +1 -1
  34. package/docs/guides/headless.md +1 -1
  35. package/docs/guides/install-clone.md +19 -1
  36. package/docs/guides/install-scripted.md +8 -2
  37. package/docs/guides/install.md +20 -2
  38. package/docs/guides/loop-finish.md +3 -3
  39. package/docs/guides/loop-running.md +4 -4
  40. package/docs/guides/project-context.md +1 -1
  41. package/docs/guides/run-a-factory.md +2 -2
  42. package/docs/guides/setup-doctrines.md +2 -2
  43. package/docs/guides/setup-footprint.md +1 -1
  44. package/docs/guides/uninstall.md +3 -3
  45. package/docs/guides/upgrade.md +2 -2
  46. package/docs/guides/worktree.md +1 -1
  47. package/docs/reference/env-context.md +1 -1
  48. package/docs/reference/environment.md +4 -2
  49. package/docs/reference/plugin-activity.md +1 -1
  50. package/docs/reference/plugin-guard.md +1 -1
  51. package/docs/reference/plugin-learn.md +5 -1
  52. package/docs/reference/plugin-workflow.md +1 -1
  53. package/docs/reference/profiles.md +142 -0
  54. package/docs/reference/troubleshoot-doctor.md +1 -1
  55. package/docs/reference/troubleshoot-hooks.md +2 -2
  56. package/docs/reference/troubleshoot-install.md +3 -3
  57. package/docs/reference/troubleshoot-tools.md +1 -1
  58. package/docs/token-footprint.md +11 -6
  59. package/docs/understand/design-choices-engineering.md +1 -1
  60. package/docs/understand/enforced-vs-asked.md +1 -1
  61. package/docs/understand/machine-claude.md +2 -2
  62. package/docs/understand/on-your-machine.md +1 -1
  63. package/docs/web-ui.md +8 -6
  64. package/harness.config.json +1 -1
  65. package/js/README.md +11 -3
  66. package/js/build/args.mjs +16 -4
  67. package/js/build/catalog.mjs +11 -1
  68. package/js/build/driver.mjs +74 -16
  69. package/js/build/emit-claude.mjs +32 -5
  70. package/js/build/emit-opencode.mjs +16 -9
  71. package/js/build/export.mjs +1 -1
  72. package/js/build/generate.mjs +12 -157
  73. package/js/build/notes-migrate.mjs +99 -0
  74. package/js/build/profile.mjs +326 -0
  75. package/js/build/render.mjs +110 -8
  76. package/js/build/retired-skills.mjs +60 -13
  77. package/js/build/source.mjs +100 -3
  78. package/js/build/stubs.mjs +4 -1
  79. package/js/cli-table.json +212 -7
  80. package/js/hosts/agent-runs.mjs +205 -0
  81. package/js/hosts/done-checks.mjs +3 -1
  82. package/js/hosts/hooks-done.mjs +428 -63
  83. package/js/hosts/hooks-learn.mjs +89 -3
  84. package/js/hosts/hooks-prims.mjs +44 -4
  85. package/js/hosts/hooks.mjs +159 -9
  86. package/js/hosts/hosts.mjs +10 -0
  87. package/js/hosts/installs.mjs +44 -2
  88. package/js/hosts/link.mjs +45 -10
  89. package/js/hosts/native.mjs +61 -7
  90. package/js/hosts/opencode.mjs +1 -1
  91. package/js/hosts/settings.mjs +101 -3
  92. package/js/hosts/spec-feedback.mjs +538 -0
  93. package/js/hosts/usage.mjs +67 -8
  94. package/js/inspect/agent-scores.mjs +118 -0
  95. package/js/inspect/checks-authoring.mjs +2 -1
  96. package/js/inspect/checks-build.mjs +20 -4
  97. package/js/inspect/checks-constitution.mjs +32 -0
  98. package/js/inspect/checks-repo.mjs +27 -2
  99. package/js/inspect/cost.mjs +6 -5
  100. package/js/inspect/diff.mjs +46 -8
  101. package/js/inspect/doctor.mjs +4 -0
  102. package/js/inspect/inventory.mjs +1 -1
  103. package/js/inspect/status.mjs +3 -1
  104. package/js/inspect/validate.mjs +1 -0
  105. package/js/lib/machine-dir.mjs +8 -0
  106. package/js/lib/paths.mjs +4 -1
  107. package/js/maintain/profile-scope.mjs +145 -0
  108. package/js/maintain/profiles.mjs +486 -0
  109. package/js/maintain/setup.mjs +413 -15
  110. package/js/maintain/uninstall.mjs +4 -1
  111. package/js/maintain/update.mjs +4 -2
  112. package/js/web/actions.mjs +44 -41
  113. package/js/web/api.mjs +13 -3
  114. package/js/web/handler.mjs +8 -0
  115. package/js/web/jobs.mjs +5 -4
  116. package/js/web/profiles-api.mjs +201 -0
  117. package/js/web/routes.mjs +5 -0
  118. package/package.json +2 -1
  119. package/profiles/guillaume-claude-global.json +16 -0
  120. package/profiles/starter.json +14 -0
  121. package/registry.json +14 -0
  122. package/src/AGENT.md.tmpl +16 -18
  123. package/src/agents/_self-improvement.md +15 -7
  124. package/src/agents/_template.md +4 -2
  125. package/src/agents/advocate.md +1 -1
  126. package/src/agents/architect.md +1 -1
  127. package/src/agents/developer.md +10 -3
  128. package/src/agents/devops-engineer.md +1 -1
  129. package/src/agents/docker-expert.md +1 -1
  130. package/src/agents/docs.md +1 -1
  131. package/src/agents/empiricist.md +1 -1
  132. package/src/agents/explorer.md +4 -2
  133. package/src/agents/framer.md +1 -1
  134. package/src/agents/historian.md +1 -1
  135. package/src/agents/kubernetes-specialist.md +1 -1
  136. package/src/agents/memory-curator.md +1 -1
  137. package/src/agents/operator.md +1 -1
  138. package/src/agents/performance.md +1 -1
  139. package/src/agents/pragmatist.md +1 -1
  140. package/src/agents/react-engineer.md +1 -1
  141. package/src/agents/react-reviewer.md +1 -1
  142. package/src/agents/researcher.md +1 -1
  143. package/src/agents/reviewer.md +10 -3
  144. package/src/agents/security.md +1 -1
  145. package/src/agents/skeptic.md +1 -1
  146. package/src/agents/spring-boot-engineer.md +1 -1
  147. package/src/agents/spring-reviewer.md +1 -1
  148. package/src/agents/spring-security.md +1 -1
  149. package/src/agents/steward.md +1 -1
  150. package/src/agents/tester.md +4 -2
  151. package/src/agents/user-advocate.md +1 -1
  152. package/src/agents/visionary.md +1 -1
  153. package/src/bricks/pr-open.md +3 -2
  154. package/src/doctrines/ops.md +2 -2
  155. package/src/doctrines/process.md +40 -36
  156. package/src/factories/analysis-to-build.json +1 -1
  157. package/src/factories/bug-report-to-fix.json +1 -1
  158. package/src/factories/issue-to-pr.json +1 -1
  159. package/src/kits/terminal-tools/rules.md +10 -0
  160. package/src/kits/terminal-tools.json +13 -0
  161. package/src/licenses/herdr.txt +201 -0
  162. package/src/memory/README.md +12 -2
  163. package/src/modes/foreman.md +25 -9
  164. package/src/skill-descriptions.json +63 -0
  165. package/src/skills/_self-improvement.md +42 -24
  166. package/src/skills/_template.md +3 -1
  167. package/src/skills/brainstorm.md +35 -22
  168. package/src/skills/commit.md +17 -17
  169. package/src/skills/daydream/VENDOR.md +6 -0
  170. package/src/skills/debug/ci.md +1 -1
  171. package/src/skills/dependencies.md +3 -3
  172. package/src/skills/diagram-design/VENDOR.md +4 -0
  173. package/src/skills/document-project.md +3 -2
  174. package/src/skills/explain-changes/VENDOR.md +5 -1
  175. package/src/skills/factory.md +13 -4
  176. package/src/skills/geneseed.md +4 -2
  177. package/src/skills/git-history.md +5 -7
  178. package/src/skills/herdr.md +135 -0
  179. package/src/skills/loop.md +3 -2
  180. package/src/skills/opencode-cli.md +84 -0
  181. package/src/skills/parallel-agents.md +11 -0
  182. package/src/skills/pipeline.md +3 -3
  183. package/src/skills/plan.md +5 -4
  184. package/src/skills/react-view-transitions/VENDOR.md +7 -1
  185. package/src/skills/release.md +11 -9
  186. package/src/skills/review-response.md +4 -2
  187. package/src/skills/rule/approve.md +2 -1
  188. package/src/skills/rule.md +27 -1
  189. package/src/skills/ship.md +54 -7
  190. package/src/skills/skill-forge.md +5 -3
  191. package/src/skills/token-report/VENDOR.md +5 -1
  192. package/src/skills/worktree.md +2 -2
  193. package/src/upstreams.json +9 -2
  194. package/themes/README.md +3 -1
  195. package/themes/_TEMPLATE.json +2 -0
  196. package/themes/biker.json +2 -0
  197. package/themes/commentator.json +2 -0
  198. package/themes/cyberpunk.json +2 -0
  199. package/themes/gamer.json +2 -0
  200. package/themes/imperial.json +2 -0
  201. package/themes/joker.json +2 -0
  202. package/themes/marvin.json +2 -0
  203. package/themes/mean.json +2 -0
  204. package/themes/military.json +2 -0
  205. package/themes/neutral.json +2 -0
  206. package/themes/pirate.json +2 -0
  207. package/themes/sports.json +2 -0
  208. package/themes/verstappen.json +2 -0
  209. package/themes/wizard.json +2 -0
  210. package/web/dist/assets/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
  211. package/web/dist/assets/Activity-LKsDzsnK.js +1 -0
  212. package/web/dist/assets/ActivityDetail-DhwTfPm6.js +1 -0
  213. package/web/dist/assets/{Bonsai-BBl4XXqs.js → Bonsai-CePMLrpr.js} +1 -1
  214. package/web/dist/assets/{CopyButton-Beven8yn.js → CopyButton-CuoaJ6k7.js} +1 -1
  215. package/web/dist/assets/Dashboard-D1VKuvLe.js +2 -0
  216. package/web/dist/assets/Docs-CUrHJKaU.js +5 -0
  217. package/web/dist/assets/Factories-Ci1XfmSy.js +1 -0
  218. package/web/dist/assets/{GreenhouseView-Bce212qd.js → GreenhouseView-CNfH2lPK.js} +1 -1
  219. package/web/dist/assets/Installs-ZHQZM1iS.js +3 -0
  220. package/web/dist/assets/{JournalView-CV4omyww.js → JournalView-CMsWahkS.js} +1 -1
  221. package/web/dist/assets/Kits-CkliyK0n.js +1 -0
  222. package/web/dist/assets/Laws-hh4O3HZ4.js +4 -0
  223. package/web/dist/assets/{LibRows-Dag1s0ZX.js → LibRows-Brv0Hmkr.js} +1 -1
  224. package/web/dist/assets/Library-BYmiLjJr.js +3 -0
  225. package/web/dist/assets/Loops-ytm-xJ68.js +2 -0
  226. package/web/dist/assets/{OperatorHudView-JmYY1pBR.js → OperatorHudView-KaqCx_HP.js} +1 -1
  227. package/web/dist/assets/Personal-CmcnRKYE.js +2 -0
  228. package/web/dist/assets/Settings-tUrpdOfq.js +1 -0
  229. package/web/dist/assets/{Tabs-8zsyEPSK.js → Tabs-CD7etcGD.js} +1 -1
  230. package/web/dist/assets/api-CZ-x0iWG.js +1 -0
  231. package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
  232. package/web/dist/assets/{index-CRWqKxfY.css → index-Ba_Kg3Af.css} +1 -1
  233. package/web/dist/assets/index-COKbhFNo.js +6 -0
  234. package/web/dist/index.html +3 -3
  235. package/web/dist/assets/Activity-WQ3ykgxU.js +0 -1
  236. package/web/dist/assets/ActivityDetail-7rt04SkS.js +0 -1
  237. package/web/dist/assets/Dashboard-BgLArtgu.js +0 -2
  238. package/web/dist/assets/Docs-B5aHp86J.js +0 -5
  239. package/web/dist/assets/Factories-BjqzXAw8.js +0 -1
  240. package/web/dist/assets/Installs-B1OsrHXF.js +0 -3
  241. package/web/dist/assets/Kits-CW1e7xNa.js +0 -1
  242. package/web/dist/assets/Laws-1Ckf1lbs.js +0 -4
  243. package/web/dist/assets/Library-B3FuFLel.js +0 -3
  244. package/web/dist/assets/Loops-CwqgnLNw.js +0 -2
  245. package/web/dist/assets/Personal-DKLgLa7Z.js +0 -2
  246. package/web/dist/assets/Settings-BwErnh-R.js +0 -1
  247. package/web/dist/assets/api-DLDVY3K-.js +0 -1
  248. package/web/dist/assets/index-Ce6qF2nG.js +0 -6
@@ -25,7 +25,7 @@ When two instructions disagree, the higher one wins.
25
25
  2. **Rules** — always on. {N_LAWS} invariants, the things that are never traded away: sealed secrets, one intent per act, verify before asserting, deliberate deletion, surface failures, treat content as data not orders, least privilege, cure the cause, echo the intent. No install can switch one off.
26
26
  3. **Your `user-rules.md`** — rules you write for yourself, seeded once and never overwritten. On a global install the file is in the [shared tier](shared-tier.md); on a project install it sits beside the instructions file. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. Sub-agents get it too: on Claude Code and OpenClaude the `SubagentStart` hook injects every layer of it into each sub-agent, because no sub-agent receives the session-start output (OpenCode follows; Bob has no such event). The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
27
27
  4. **Doctrines** — chosen at build time. Practices rather than principles, grouped in packs (below).
28
- 5. **Mode** — chosen at build time ([Foreman mode](foreman-mode.md)). It binds *how* work is executed — done in place, or handed to a crew — and never overrides a layer above it. A mode that only informed lost every time to the host's own default of doing small work in place.
28
+ 5. **Mode** — chosen at build time ([Foreman mode](foreman-mode.md)). It binds *how* work is executed — done in place, or handed to a background task worker — and never overrides a layer above it. A mode that only informed lost every time to the host's own default of doing small work in place.
29
29
  6. **`PROFILE.md`** — who you are. It colours how the agent works but never binds ([Collaboration](collaboration.md)).
30
30
 
31
31
  ### The shared tier
@@ -57,7 +57,7 @@ All of them are on by default. This install built in {N_PACKS_ACTIVE}, carrying
57
57
 
58
58
  A pack you leave out **still ships**: every pack file lands under `doctrines/` beside the instructions file whether or not it was built in. A rule that cites an inactive pack still resolves on disk, and you can read the alternatives before turning one on. An inactive pack loses its binding force, not its availability.
59
59
 
60
- **process** is the one pack whose removal changes what the machine does, not only what the agent reads: it holds *Consent Before Push*, which a hook enforces. Without it, commits and pushes are no longer stopped for a question — destructive git still is, because that is a Rule ([Hooks](hooks.md)).
60
+ **process** is the one pack whose removal changes what the machine does, not only what the agent reads: it holds *Consent Before Push*, which a hook enforces: the main branch changes only through a pull request with green checks, and your own branch takes commits and plain pushes freely (or every commit and push asks, with `--strict-consent`). Without it, commits and pushes are no longer stopped for a question — destructive git still is, because that is a Rule ([Hooks](hooks.md)).
61
61
 
62
62
  ### Themes do not move rules
63
63
 
@@ -19,7 +19,7 @@ A global install keeps what you teach it in one place for every host on the mach
19
19
  | `geneseed-wiki.jsonc` | Your [wiki](../guides/wiki.md) declaration |
20
20
  | `excludes.json` | [Sovereign folders](exclusions.md) |
21
21
  | `memory/` | The [memory](memory.md) store: facts, `MEMORY.md`, `topics/`, `agents/`, `archive/` |
22
- | `notes/` | The self-improvement notes: `skill-notes/`, `agent-notes/` |
22
+ | `notes/` | The self-improvement notes true in any repo: `skill-notes/`, `agent-notes/`. Every install writes them here, project installs included, and a project install's files name this folder as `~/.config/geneseed/notes`, the same on every machine. The notes true in one repo only live in that repo's `notebook/` |
23
23
  | `user-rules.draft.md` | What waits for your decision. Never loaded |
24
24
  | `.fold-state.json` | The record of each drafted or decided item |
25
25
  | `default-install.json` | The console's default install, once you pick one |
@@ -42,7 +42,7 @@ The full list, with each description, is in the catalog.
42
42
 
43
43
  ### Skills improve themselves
44
44
 
45
- Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with no prompt, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and `doctor` would report it as drift. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what was expected> (<date>)`: `situation:` says where the correction holds (it is optional, and older lines without it stay valid; without it, the circumstance in `seen:` stands in), `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Folding a skill or agent note is your call: the `skill-forge` skill first replays one past task whose original ask still exists, as two dispatched agents from the pre-fix revision, one told to read no notes and one given the note. The `fresh-eyes` skill freezes one rubric from the ask and judges both results blind against it. A note is folded only when it wins, on the result or on a stated process gain; on a tie or a loss you decide whether to keep or delete it. A trivial wording fix skips that probe. Most runs end with nothing to change.
45
+ Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent ends its reply with one line, `spec-feedback: [skill:<name>] <the fix> [— situation: <when it applies>] — seen: <what happened, against what was expected>`. When the turn ends, the hook copies that line, dated and with no model call, into the skill's notes file, and the skill reads those notes the next time it runs (see [Hooks](hooks.md)). The tag picks the file by one question: is it true in any repo, or only here? Any repo: `[skill:<name>]` goes into the machine notes, `skill-notes/<name>.md` under `notes/` in the [shared tier](shared-tier.md) (`~/.config/geneseed/notes/`), for every host and install kind. Only here: `[skill:<name>:project]` goes into `notebook/skill-notes/<name>.md` at the project root, one folder for every host, and `[skill:<name>:general:project]` into `notebook/skill-notes/_general.md` there. The skill reads the machine notes first, then the project notes, which win where they disagree. The agent used to be told to write the file itself, and it never did. It never edits the installed skill itself: that file is rendered from `src/`, and a rebuild would overwrite the edit. A bundled script that is broken is the one exception: fix it in place, and tell the user which file you changed. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill] <correction> [— situation: <when it applies>] — seen: <what happened, against what was expected> (<skill>, <date>)` (a line you write by hand may omit the skill's name, and the hook never drops it): `situation:` says where the correction holds (it is optional, and older lines without it stay valid; without it, the circumstance in `seen:` stands in), and `seen:` is what you judge the correction by before folding it in. A line tagged `[skill:<name>:general]` marks a fix other skills need too: it goes into `skill-notes/_general.md`, which every skill reads. On Bob, whose hook never sees the reply, the agent appends the line itself. `geneseed diff` lists the notes so you can fold them back into `src/`. Folding a skill or agent note is your call: the `skill-forge` skill first replays one past task whose original ask still exists, as two dispatched agents from the pre-fix revision, one told to read no notes and one given the note. The `fresh-eyes` skill freezes one rubric from the ask and judges both results blind against it. A note is folded only when it wins, on the result or on a stated process gain; on a tie or a loss you decide whether to keep or delete it. A trivial wording fix skips that probe. Most runs end with nothing to change.
46
46
 
47
47
  ### Old names keep working
48
48
 
@@ -52,6 +52,26 @@ When two skills merge, the old name still works as a slash command: `/deps-audit
52
52
 
53
53
  The skill *bodies* are read only when used. The *descriptions* are listed to the agent every turn so it can pick the right one — that list is part of the always-on cost described in [Footprint](footprint.md).
54
54
 
55
+ ### The listing budget on Claude Code
56
+
57
+ Claude Code builds the skill list under a character budget: the model's context window, times about 3 characters per token, times `skillListingBudgetFraction` (default 0.01). That is about 6 000 characters on a 200k-token model and 30 000 on a 1M one. Its bundled skills always keep their text. When the list is over budget, the other skills that are used least lose their description and show as a bare name, and the agent no longer knows when to use them. A fresh install on a 200k model lost all of them.
58
+
59
+ `geneseed build --context-window 200k|1m` (default `200k`) tells the build which model the install is for. On a Claude Code emit it writes two keys into the settings file Geneseed already merges (`settings.json`, or `settings.local.json` for a project):
60
+
61
+ | `--context-window` | `skillListingMaxDescChars` | `skillListingBudgetFraction` | Budget at 3 characters per token |
62
+ | --- | --- | --- | --- |
63
+ | `200k` | 80 | 0.013 | 7 800 |
64
+ | `1m` | 120 | not set (default 0.01) | 30 000 |
65
+
66
+ `skillListingMaxDescChars` cuts *every* skill's description to that length, Claude Code's own and other plugins' included, so each one costs less. Simulated on a fresh install (the 14 bundled skills and 46 Geneseed skills, no usage yet):
67
+
68
+ - `200k`: at the default fraction, every description fits with 395 characters to spare, and 113 with one kit. Five skills of your own would push some out. At 0.013, all of them fit with twenty more skills. The fraction is a ceiling, not a cost: a list that fits uses only its own length.
69
+ - `1m`: a fresh install fits even without a cap. The cap is for a machine with many skills: a 143-skill list of 47 617 characters fits whole in 19 427.
70
+
71
+ The keys are merged one by one. A key you set yourself is yours: the build never changes it, and uninstall never removes it. A key the build wrote moves with the setting (from `200k` to `1m` the cap goes to 120 and the fraction is removed), and uninstall removes it. A settings file with comments is never rewritten: the build prints the keys to merge by hand, and a key you merge that way is yours, so the build does not record it and uninstall leaves it. Project settings outrank your user settings, so a project install leaves any listing key that `~/.claude/settings.json` already sets (by a global install or by hand) to that file. A new project install with no `--context-window` and no `--reset` takes the value of the machine's global install; a profile, the console and the wizard pass their own value. A project built before the global install wrote its keys keeps its own until its next rebuild. The first build that writes the keys prints one line that names them and how to choose the other value. Claude Code reads these keys from about version 2.1.129; an older version keeps them and ignores them.
72
+
73
+ OpenClaude (checked on 0.31) and IBM Bob read neither key, and OpenCode does not cap its list, so on those hosts the option writes nothing. Every host records the choice: a `Context window: 1m` line in the install's instruction file, written only when it is not the default. Rebuilds, upgrades, `profile save` and the console read it back. The `setup` wizard keeps it without asking. Set it with the flag, a profile's `contextWindow` key, or the console's **Context window** picker on a Claude Code install.
74
+
55
75
  ### Related
56
76
 
57
77
  [Agents](agents.md) — who does the work · [Rules](rules.md) — what every skill obeys · writing your own: [docs/extending.md](../extending.md)
@@ -17,7 +17,7 @@ A **theme** changes the agent's *voice* and the words the harness uses for its o
17
17
  | how the agent phrases its replies | which rules apply, and their order |
18
18
  | the nouns for the harness's parts — an `imperial` install calls the Rules *Dictates*, agents *Adepts*, skills *Rites* | folder names: `agents/`, `skills/`, `memory/`, `laws/`, `doctrines/`… |
19
19
  | the banner, the readiness line the agent prints when it starts, the closing lines | section layout and the links between files |
20
- | the names and descriptions shown for rules, agents and skills | rule addresses such as `process 5` |
20
+ | the names and descriptions shown for rules, agents and skills, except the short description the host lists for each skill | rule addresses such as `process 5` |
21
21
 
22
22
  `neutral` keeps the plain words — Rule, Doctrine, Agent, Skill, Memory — so it is the theme to pick if you want no flavour at all. The [glossary](../reference/glossary.md) shows each themed word beside its neutral one.
23
23
 
package/docs/extending.md CHANGED
@@ -6,7 +6,7 @@ doctrine rule, one skill, one plugin, one hook verb, one doc page, one theme, on
6
6
  It exists because the answer is never one file. Every user-visible noun in Geneseed has
7
7
  *satellites* — a themed title in fourteen voices, a class in a hand-written map, a count in a
8
8
  badge, a row in a ledger, a page in the console — and the gates that keep them in step are spread
9
- across `doctor`, the Node suite and four CI jobs. A contributor who knows the satellites ships in
9
+ across `doctor`, the Node suite and the CI jobs (§1). A contributor who knows the satellites ships in
10
10
  one pass; one who does not discovers them one red gate at a time.
11
11
 
12
12
  The governance surface is three tiers and they cost very different amounts. **Adding a doctrine
@@ -53,12 +53,13 @@ literally, on the screen, as those nine characters.
53
53
 
54
54
  Typing a literal number into a `docs/web` page is caught by `proseMirrorProblems`. The README
55
55
  badges and prose, and the `N laws, N agents, N skills` line in `SHIPPED.md`, are the hand-written
56
- exceptions — and each has its own arm in `js/inspect/doctor.mjs` (`countTableProblems` walks the five
57
- badge keys `agents`/`skills`/`laws`/`themes`/`plugins`; `proseMirrorProblems` holds the prose).
56
+ exceptions — and each has its own arm in `js/inspect/checks-counts.mjs` (`countTableProblems` walks
57
+ the six badge keys `agents`/`skills`/`laws`/`doctrines`/`themes`/`plugins`, `doctrines` riding the
58
+ laws badge as `+ N doctrines`; `proseMirrorProblems` holds the prose).
58
59
 
59
60
  ---
60
61
 
61
- ## 1 — The baseline, and the seven commands that reproduce CI
62
+ ## 1 — The baseline, and the commands that reproduce CI
62
63
 
63
64
  The baseline is whatever these commands report on your checkout — run them; no count is
64
65
  written here, because a typed count is stale by the next commit.
@@ -68,6 +69,14 @@ Windows (the suite in shards, which `suite-count` sums), `node-cells` on Linux *
68
69
  `package-no-python`, `web`, `audit` and `links` on Linux; `ci-ok` is the one required check. From
69
70
  the repo root — never from a worktree, see §5.3:
70
71
 
72
+ ```bash
73
+ npm run lint
74
+ ```
75
+
76
+ ```bash
77
+ npm run typecheck
78
+ ```
79
+
71
80
  ```bash
72
81
  node bin/geneseed-cli.mjs doctor --all
73
82
  ```
@@ -76,6 +85,14 @@ node bin/geneseed-cli.mjs doctor --all
76
85
  node --test --test-reporter=tap "tests/**/*.test.mjs"
77
86
  ```
78
87
 
88
+ ```bash
89
+ node tests/shim_intact.mjs
90
+ ```
91
+
92
+ ```bash
93
+ node --test --test-reporter=tap "fuzz/*.fuzz.mjs"
94
+ ```
95
+
79
96
  ```bash
80
97
  node tests/golden.mjs --idempotent
81
98
  ```
@@ -114,12 +131,12 @@ Notes that matter:
114
131
  a `find` that stops matching exactly once fails the cell loudly.
115
132
  - `--deletion` is the only thing that exercises the write-before-delete prune. Anyone renaming or
116
133
  removing a plugin, a skill or an emitted file needs it.
117
- - **A local pass is weaker than CI.** ~18 tests in `tests/unit/package_manifest.test.mjs` carry
118
- `{ skip: NO_NPM }` (`:83`) — every tarball, install and rename gate. On a machine without `npm`
134
+ - **A local pass is weaker than CI.** The tests in `tests/unit/package_manifest.test.mjs` that carry
135
+ `{ skip: NO_NPM }` are every tarball, install and rename gate. On a machine without `npm`
119
136
  on PATH they report *skipped* and the run is green.
120
137
  - CI additionally re-runs the packaging suite under `npm@11`, the release's npm (Linux, last in the job), and
121
138
  packs the tarball into a `node:22-slim` container with no interpreter. Neither is reproducible
122
- from the seven commands; the container one is reachable locally through
139
+ from the commands above; the container one is reachable locally through
123
140
  `tests/helpers/no-python-container.sh` with a docker daemon.
124
141
  - **Two assertions in `tests/unit/claude.test.mjs` silently stand down** on any machine where an
125
142
  ancestor of the temp sandbox is a `.claude`/`.bob`/`.openclaude` install — which is every developer machine
@@ -128,9 +145,10 @@ Notes that matter:
128
145
 
129
146
  ### The gates CI does not run
130
147
 
131
- - **The mutation matrix itself.** `tests/mutate.mjs` — 35 rows, each a one-string edit to a
132
- product file with a written argument for which gate should catch it. The full run is **in no
133
- workflow** and should not be: it mutates the product tree 33 times and runs a gate per edit.
148
+ - **The mutation matrix itself.** `tests/mutate.mjs` — a table of rows (`--list` prints them), each a
149
+ one-string edit to a product file with a written argument for which gate should catch it. The
150
+ full run is **in no workflow** and should not be: it mutates the product tree once per row and
151
+ runs a gate per edit.
134
152
  Run `node tests/mutate.mjs --all` (or `--only M7`) by hand when you change something a gate is
135
153
  supposed to be watching. ⚠ An interrupted run leaves the **product tree mutated** — check
136
154
  `git status` before doing anything else.
@@ -148,7 +166,8 @@ Notes that matter:
148
166
  gate `publish.yml`'s shape (found by `publishWorkflow`), and the test *every workflow that
149
167
  count-gates `node --test` pins the TAP reporter* discovers every workflow with a test-count gate
150
168
  and pins `--test-reporter=tap` on each `node --test` line. A unit test gates the CI files.
151
- - **Adding any tracked file** — `tests/unit/package_manifest.test.mjs:401` demands every tracked
169
+ - **Adding any tracked file** — `tests/unit/package_manifest.test.mjs` (*every tracked file matches
170
+ exactly one side of the partition*) demands every tracked
152
171
  path fall on exactly one side of a declared partition, *with a written reason*. Adding this very
153
172
  document required a `SHIPS` row; without one the tarball test fails, and it fails **before** the
154
173
  file is committed too, because npm packs by glob while the partition reads `git ls-files`.
@@ -181,7 +200,7 @@ not.
181
200
 
182
201
  ### 2a — Adding a DOCTRINE RULE (the common case)
183
202
 
184
- Four files, plus the written-out rule totals in four test files. This is the slot most new
203
+ Five steps, plus the written-out rule totals in the test files named below. This is the slot most new
185
204
  material belongs in, and it is cheap on purpose so that the invariant slot stays scarce.
186
205
 
187
206
  1. `src/doctrines/<pack>.md` — add `### {{DOCTRINE:<new-id>}} <Principle Name>` plus the body,
@@ -211,13 +230,17 @@ material belongs in, and it is cheap on purpose so that the invariant slot stays
211
230
  `cmdBuild` (`BUILD_FORWARD`) does not forward `--sync-themes`. Then restyle all
212
231
  fourteen by hand: `--sync-themes` writes the template's placeholder and only *prints*
213
232
  `RESTYLE these`; a shipped placeholder passes every gate.
214
- 4. `CHANGELOG.md`.
233
+ 4. `README.md` — the `+ N doctrines` half of the laws badge (`badge/laws-N%20%2B%20N%20doctrines`).
234
+ `countTableProblems` holds it to the rule count across every pack, so `doctor` is red until it
235
+ is bumped.
236
+ 5. `CHANGELOG.md`.
215
237
 
216
238
  **What a doctrine rule does *not* cost**, and each of these is a deliberate asymmetry:
217
239
 
218
240
  - **No class entry.** There is no `LAW_CLASS` analogue: a doctrine rule's class *is* its pack, and
219
241
  there is no second taxonomy over it.
220
- - **No count in the product.** No badge, no `SHIPPED.md` triple, no prose mirror. The console spends
242
+ - **One count in the product, and only one.** The README laws badge (step 4); no `SHIPPED.md`
243
+ triple, no prose mirror. The console spends
221
244
  `{N_PACKS}` / `{N_PACKS_ACTIVE}` / `{N_DOCTRINE_RULES}`, all computed at request time.
222
245
  - **No citation to rewire.** But there *are* written-out rule totals to bump — expected values are
223
246
  written out, never recorded — in `tests/unit/emit_smoke.test.mjs`, `harness.test.mjs`,
@@ -229,6 +252,13 @@ material belongs in, and it is cheap on purpose so that the invariant slot stays
229
252
  `full` carrier ceiling in `emit_smoke` — raise it with a dated note there, as every earlier
230
253
  move did.
231
254
 
255
+ ⚠ **A doctrine citation in carrier text stands alone in its parentheses.** In
256
+ `src/AGENT.md.tmpl`, `src/modes/`, `src/postures/`, `src/doctrines/` and a kit's `rules.md`, write `… so X
257
+ ({{DOCTRINE:<id>}})`, never `({{DOCTRINE:<id>}} says X)`. `dropExcludedCitations`
258
+ (`js/build/render.mjs`) removes an excluded rule's citation from the carrier only when its group
259
+ holds citations alone; `citationGroupProblems` (`js/inspect/checks-constitution.mjs`) refuses
260
+ anything else. A prose mention outside parentheses is fine.
261
+
232
262
  ⚠ **Cite only downward.** An always-on tier may never reference a toggleable one:
233
263
  `constitutionProblems` refuses a `{{DOCTRINE:…}}` token anywhere under `src/ontology/` or
234
264
  `src/laws/`, because a `--doctrines craft` build would then ship an invariant pointing at text its
@@ -355,8 +385,8 @@ candidate for routing to choose between, so add only what no sharpened existing
355
385
 
356
386
  **Order matters at the first two steps.** `missingReferencedSpecs` (in `js/build/bundle.mjs`) *aborts the
357
387
  build* when `AGENT.md.tmpl` names a spec with no file — so the file comes before the table row, or
358
- nothing builds at all. The refusal is clean: `tests/unit/emit_gates.test.mjs:265` proves a refused
359
- emit leaves the prior install intact.
388
+ nothing builds at all. The refusal is clean: `tests/unit/emit_gates.test.mjs` (*a missing agent aborts a
389
+ global emit and leaves the install intact*) proves a refused emit leaves the prior install intact.
360
390
 
361
391
  1. `src/skills/<name>.md` or `src/agents/<name>.md`. The shape is load-bearing: `# {{SKILL}}: <name>`,
362
392
  a blank line, then a `>` blockquote holding `{{DESC_<NAME>}}` — title, blockquote, nothing
@@ -365,7 +395,16 @@ emit leaves the prior install intact.
365
395
  2. One row in the hand-authored table in `src/AGENT.md.tmpl` (the `## 3.` table for agents, the `## 4.` one for skills).
366
396
  Gated both ways: a row with no file, and a file with no row.
367
397
  3. `DESC_<NAME>` in **all fourteen** themes. Theme parity catches a missing one; nothing catches
368
- an unstyled placeholder.
398
+ an unstyled placeholder. That themed purpose opens the skill's body. **Skills only**, and
399
+ kit and vendored skills too: one line in `src/skill-descriptions.json`, purpose and trigger
400
+ in at most 80 characters, theme-neutral and in the third person. It is the emitted
401
+ `description:` on every host, the only text the model routes on, and a vendored skill's
402
+ upstream description moves to the first body line. 80 because the host lists skills under
403
+ a budget (about 6 000 characters on a 200k model) and drops the descriptions of the
404
+ least-used skills when the listing overruns it, which on a fresh install is any of them.
405
+ `catalogueLineProblems` refuses a missing, stale, empty or over-long line, and
406
+ `descriptionProblems` holds every emitted `SKILL.md` to the same limit. (This reverses the
407
+ 2026-11-11 themed-catalogue decision for the frontmatter line only, 2026-11-15.)
369
408
  4. **Skills only** — `SKILL_CLASS` in `js/inspect/inventory.mjs`. Gated both ways, inside
370
409
  `countTableProblems`, which matters because the runtime fallback is silent: an unclassified
371
410
  skill renders as `build`.
@@ -383,8 +422,8 @@ emit leaves the prior install intact.
383
422
  never fires. Hand-run, spends model calls on your own login, not part of the suite.
384
423
 
385
424
  **A vendored skill folder** (`src/skills/<name>/SKILL.md`) is a different shape: add it to
386
- `VENDORED_SKILL_DIRS` (`js/hosts/native.mjs:48` — the literal is frozen in
387
- `tests/unit/authoring_gates.test.mjs:421`), add a `src/upstreams.json` entry (`repo`, `commit` —
425
+ `VENDORED_SKILL_DIRS` (`js/hosts/native.mjs` — the literal is frozen in
426
+ `tests/unit/authoring_gates.test.mjs`), add a `src/upstreams.json` entry (`repo`, `commit` —
388
427
  a 40-hex commit, never a moving branch — `author`, `license`, and `licenseFile`, a path under
389
428
  `src/` or `null`; an optional `"frozen": true` marks text left at its pin on purpose: the weekly drift job skips it, `creditProblems` still validates it), write a `VENDOR.md` carrying `**Upstream key:** <that key>` and a
390
429
  `{{CREDIT:<key>:<upstream path>}}` line, which renders the attribution into every install (the
@@ -412,8 +451,8 @@ distinguishes it from first-party text.
412
451
  Two traps worth knowing before you write the spec:
413
452
 
414
453
  - **The word "Read-only" anywhere in an agent spec locks its emit.** It is a bare substring test
415
- (`js/hosts/native.mjs:148`). The escape hatches are explicit markers: `<!-- bash: allow -->`
416
- re-opens bash on all three hosts (OpenCode gates it to `ask`), and `<!-- webfetch: allow -->`
454
+ (`isReadonly` in `js/hosts/native.mjs`). The escape hatches are explicit markers: `<!-- bash: allow -->`
455
+ re-opens bash on every host (OpenCode gates it to `ask`), and `<!-- webfetch: allow -->`
417
456
  re-opens web fetch — the researcher is the one spec that carries it.
418
457
  - **The console has a fourth, ungated copy of the skill taxonomy.** `SKILL_CATS` in
419
458
  `web/src/lib/lawCats.js` mirrors `SKILL_CLASS` with nothing comparing them (contrast the
@@ -429,7 +468,10 @@ OpenClaude and Bob get a user-only `skills/<alias>/SKILL.md`, and OpenCode gets
429
468
  now excludes the merged skill (`resolveSkillNames` in `js/build/source.mjs`), so a rebuild still
430
469
  works. A skill removed with no successor goes into `RETIRED_SKILL_IDS` in the same file: its
431
470
  exclusion is dropped with a notice instead of failing the rebuild, and the name can never be
432
- used for a new skill. The doctor (`aliasProblems`) refuses an alias that is malformed, duplicated,
471
+ used for a new skill. The one exception is a skill that comes back for the same tool, where an
472
+ old exclusion keeps its meaning: `herdr` left the list when the terminal-tools kit brought it
473
+ back. Such a name moves to `REVIVED_SKILL_IDS`, so an older build's unowned render under it is
474
+ still moved aside on a canonical global emit, with the kit on or off. The doctor (`aliasProblems`) refuses an alias that is malformed, duplicated,
433
475
  already a skill, retired, or the name of an OpenCode command.
434
476
 
435
477
  **A rarely-needed half goes in a side file.** A skill body is paid in full every time the skill
@@ -553,7 +595,8 @@ The `geneseed-` prefix and the `.js` suffix are mechanically load-bearing: the b
553
595
  4. `docs/concepts/host-matrix.md` — check the capability matrix still tells the truth.
554
596
  5. `README.md` — **three** sites: the badge, the `N plugins` prose, and the 🔌 Plugins row.
555
597
  6. `SHIPPED.md` — the bare name inside `plugins (…)`; that list must equal the directory exactly,
556
- in both directions (`tests/unit/web_api_docs.test.mjs:329`).
598
+ in both directions (`tests/unit/web_api_docs.test.mjs`, *every plugin ships a reference page and
599
+ its README/SHIPPED rows*).
557
600
  7. `adapters/opencode/README.md` and `docs/opencode-plugin-setup.md` — spelled-out counts, in
558
601
  **word form** ("seven" → "eight"), the second file twice.
559
602
  8. `tests/plugins/<name>.test.mjs`. Auto-discovered; no workflow edit.
@@ -668,7 +711,8 @@ rather than assumed:
668
711
  `git ls-files --cached --others --exclude-standard`, which honours `.gitignore`, and
669
712
  `.gitignore` ignores `/node_modules/`. The copy is written outside the repository, under the OS
670
713
  temp root, and the product is run out of it as a real child process — so Node's upward resolver
671
- walk starts in temp and finds nothing. Eleven test files build such a copy. And this is not a
714
+ walk starts in temp and finds nothing. Every test file that calls `copyCheckout` builds such a
715
+ copy. And this is not a
672
716
  fixture defect to work around: a user's fresh `git clone` has no `node_modules` either. **The
673
717
  fixture is that clone.** Giving the fixture something the real install lacks makes it stop
674
718
  reproducing the failure it exists to catch.
@@ -721,7 +765,7 @@ anything owns **every** install's hooks. Emitting from a git worktree or a temp
721
765
  repoint the shim at that disposable path; removing the worktree then killed hooks for every
722
766
  install on the machine.
723
767
 
724
- **`hookPrefix` now refuses the claim** (`js/hosts/settings.mjs`, `ephemeralCheckout`): an emit whose
768
+ **`hookPrefix` now refuses the claim** (`js/hosts/shim.mjs`, `ephemeralCheckout`): an emit whose
725
769
  checkout is under the OS temp root, or is a linked git worktree (`.git` is a *file*), leaves a
726
770
  shim that still resolves exactly as it is and wires the emitted hooks to it anyway. The bundle it
727
771
  writes is byte-identical to a normal emit — the install simply keeps running the durable
@@ -739,7 +783,7 @@ CI's `.suite-fence`, any file in the tier.
739
783
 
740
784
  This is not hypothetical — it happened while this file was being written. Several agents were
741
785
  verifying gates out of copied checkouts (the `copyCheckout` fixture pattern
742
- `tests/unit/harness.test.mjs:173` uses), one of them emitted, and the shim ended up pointing at
786
+ `tests/unit/harness.test.mjs` uses), one of them emitted, and the shim ended up pointing at
743
787
  `…/Temp/gs-fix-8DYuJP/bin/geneseed-hook.mjs` — a directory that no longer existed. Every hook in
744
788
  every install on the machine was dead and nothing said so.
745
789
 
@@ -764,7 +808,7 @@ The CLI surface is no longer the most expensive thing in the repo to change. Edi
764
808
  text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
765
809
  `tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
766
810
  holds. Three hand-written equalities still converge on it and are cheap to keep in step — the
767
- 29-command count and the hidden-argument rule (`tests/unit/cli_table.test.mjs`), and
811
+ command count and the hidden-argument rule (`tests/unit/cli_table.test.mjs`), and
768
812
  `tests/unit/docs.test.mjs`, which validates every fenced `geneseed <verb> <flags>` line in
769
813
  `README.md`, `SHIPPED.md` and every page under `docs/{understand,guides,concepts,reference}/` against the table.
770
814
 
@@ -779,7 +823,7 @@ only, at best, on its presence.
779
823
  |---|---|---|
780
824
  | `§N` cross-references into `AGENT.md`'s anatomy | `src/skills/*`, `src/agents/*`, `adapters/**` | **range only.** `constitutionProblems` refuses a `§N` the template declares no section for — which catches a pointer past the end, the shape *removing* a section leaves. It cannot catch one that still resolves and now means something else, which is the shape *inserting* a section leaves, and is what actually happened when `## 2. Doctrines` pushed every later section down one. **Renumbering the anatomy means `grep -rn '§' src/ adapters/` and reading every hit.** Four satellites and a live OpenCode deny message shipped stale because the sweep stopped at `AGENT.md.tmpl` |
781
825
  | Per-rule Principle lines | the `<!-- note: summary: … -->` line under each rule heading in `src/laws/universal.md` and `src/doctrines/*.md` | presence and placement only (`ruleSummaryProblems`), never accuracy |
782
- | 588 themed constitution titles (42 keys × 14 voices) — `LEX_<ID>` (one per law), `DOC_<ID>` (one per doctrine rule), `PACK_<NAME>` | `themes/*.json` | key presence only — a shipped placeholder is green. `LEX_*` and `DOC_*` are held across the template too, and in both directions; `PACK_*` only across the voices |
826
+ | The themed constitution titles, one key per rule and per pack in each of the 14 voices — `LEX_<ID>` (one per law), `DOC_<ID>` (one per doctrine rule), `PACK_<NAME>` | `themes/*.json` | key presence only — a shipped placeholder is green. `LEX_*` and `DOC_*` are held across the template too, and in both directions; `PACK_*` only across the voices |
783
827
  | The README keyword enumerations | `README.md`, `docs/concepts/rules.md` | nothing |
784
828
  | The per-host map of what lands on a machine | `docs/understand/machine-opencode.md`, `docs/understand/machine-claude.md` | table shape only, never accuracy |
785
829
  | Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
@@ -814,7 +858,7 @@ gated. Every other appearance is derived at runtime (`.geneseed-version` markers
814
858
  why no test pins a version string and none should.
815
859
 
816
860
  Do not run `npm version`. Bump the two files by hand, add the `CHANGELOG` section, update
817
- `SHIPPED.md`, rebuild `web/dist` if `web/src` moved, run the seven commands from §1, and merge to
861
+ `SHIPPED.md`, rebuild `web/dist` if `web/src` moved, run the commands from §1, and merge to
818
862
  `main`. **The bump is the release** (since 2026-10-23): when CI finishes green on that push,
819
863
  `publish.yml` sees a version npm does not have, re-runs its gates, publishes it, and creates the
820
864
  `v<version>` tag and the GitHub release from the version's CHANGELOG section. A push that does not
@@ -0,0 +1,100 @@
1
+ ---
2
+ group: guides
3
+ order: 24.6
4
+ title: "Auto-merge green PRs"
5
+ kind: "concept"
6
+ section: "Factories"
7
+ description: "Let the forge merge a PR the agent opens once its required checks are green: how to turn it on and off, the forge settings it needs, and the three tiers."
8
+ ---
9
+ Auto-merge ships **off**. When it is off, the agent opens a PR and the merge stays yours. When you
10
+ turn it on, the agent arms the forge's own auto-merge on a PR it opens, and the forge merges the
11
+ PR when its required checks pass. The agent never decides that a PR is green: the forge does
12
+ (`external-gate`).
13
+
14
+ ## Turn it on or off
15
+
16
+ Say **"turn on auto-merge"**. The `rule` skill asks one question, every repo or this project only,
17
+ then shows a standing rule for `user-rules.md` and writes it on your yes:
18
+
19
+ ```
20
+ ## R<n> — Auto-merge green PRs
21
+ (scope: global | source: user, <date>)
22
+ Arm auto-merge on a PR I open, only when the forge has required checks.
23
+ - docs-tests: auto
24
+ - normal: human # human | reviewer
25
+ - sensitive: never
26
+ - Before any further push to a PR with auto-merge armed, disarm it first, then classify, review and arm again on the new head.
27
+ ```
28
+
29
+ The rule files are layered: shared, then host, then project, and the later layer wins. So a
30
+ global rule sets the default and a project's own copy overrides it. To turn it off, say **"turn
31
+ off auto-merge"**: the agent removes the rule, or writes a project copy with all three tier lines
32
+ `never`. When a repo has no rule, the agent tells you once per session in that repo, when it
33
+ opens a PR there, that auto-merge is off and how to turn it on.
34
+
35
+ The rule is your durable authorization for the forge's merge (`deletion-is-deliberate`). It arms
36
+ only that merge. Pushes still follow `consent-before-push`: a plain push of your own branch goes
37
+ through, and a push onto the main branch asks you.
38
+
39
+ ## The tiers
40
+
41
+ The agent sorts each PR by its diff, the first match wins:
42
+
43
+ | Tier | When | Accepted values |
44
+ |---|---|---|
45
+ | `sensitive` | Any file in a sensitive zone: each `sensitive:` zone of the ownership block in the **base** branch's `AGENTS.md` (see [Set up ownership](set-up-ownership.md)), plus auth and authz, secrets and credentials, data migrations and schema, CI and deploy config, dependency manifests and lockfiles, release and versioning, gate and hook config, `AGENTS.md`, `CLAUDE.md`, `CODEOWNERS`, any `user-rules.md`, agent, skill and instruction files, and gate machinery (check scripts, CI-only harnesses, coverage thresholds; not ordinary unit tests) | None: it never arms, whatever the rule says |
46
+ | `docs-tests` | Every file is docs (prose that is neither shipped nor executed) or tests, and no test or assertion is removed, skipped or loosened (that diff is `normal`) | `auto`, `human`, `reviewer`, `never` |
47
+ | `normal` | Anything else | `human`, `reviewer`, `never` (`auto` is not valid) |
48
+
49
+ `auto` arms. `human` arms only when the forge also requires one approving review and dismisses it on a new push. `reviewer` arms
50
+ after the agent's blind reviewer passes, with its verdict added to the PR body first (in a factory,
51
+ the `review-panel` verdict). `never` does not arm. A missing or other value counts as `human`. Use `reviewer` only in a solo repo: GitHub does not
52
+ let you approve your own PR, and a PR the agent opens carries your identity, so `human` would never
53
+ merge there.
54
+
55
+ ## Forge settings it needs
56
+
57
+ The agent arms auto-merge only when it can read all of these. When it cannot, it does not arm, and
58
+ the merge stays yours.
59
+
60
+ | Setting | GitHub (how the agent reads it) | GitLab |
61
+ |---|---|---|
62
+ | Auto-merge allowed | Settings › General › *Allow auto-merge* (`gh repo view --json autoMergeAllowed`) | No switch: GitLab offers auto-merge on every project, so the agent checks this on GitHub only |
63
+ | Required checks on the base branch | A ruleset (`required_status_checks` in `gh api repos/{owner}/{repo}/rules/branches/<base>`) or branch protection (`required_status_checks` in `.../branches/<base>/protection`), with a non-empty list of checks: an empty list requires nothing, and `--auto` then merges at once | *Pipelines must succeed* (`only_allow_merge_if_pipeline_succeeds` in `glab api projects/:id`) |
64
+ | One approving review (`human`) | A ruleset `pull_request` rule, or branch protection, with `required_approving_review_count` of 1 or more | An approval rule with `approvals_required` of 1 or more (`glab api projects/:id/approval_rules`) |
65
+ | Stale approvals (required for `human`) | *Dismiss stale pull request approvals when new commits are pushed* (`dismiss_stale_reviews_on_push` in the ruleset, `dismiss_stale_reviews` in the protection) | *Remove all approvals when commits are added* (`reset_approvals_on_push` in `glab api projects/:id/approvals`) |
66
+ | Backstop on sensitive paths (recommended) | `CODEOWNERS` plus *Require review from Code Owners* | `CODEOWNERS` plus code owner approval on the protected branch |
67
+
68
+ The agent arms on the head it classified and reviewed:
69
+
70
+ ```bash
71
+ gh pr merge <pr> --auto --squash --match-head-commit <sha>
72
+ glab mr merge <mr> --auto-merge --squash --sha <sha>
73
+ ```
74
+
75
+ `glab mr merge` arms auto-merge by default, so the agent always names the flag. On GitHub the
76
+ pinned head is checked only when auto-merge is armed: an armed PR stays armed after a later push by
77
+ someone with write access. So before any further push to an armed PR, the agent disarms it
78
+ (`gh pr merge <pr> --disable-auto`; on GitLab, `POST
79
+ projects/:id/merge_requests/:iid/cancel_merge_when_pipeline_succeeds` through `glab api`), then
80
+ classifies, reviews and arms again on the new head. If the head is already green when the agent
81
+ arms, the forge merges at once.
82
+
83
+ ## On each host
84
+
85
+ The rule is text in the `ship` and `factory` skills. No Geneseed gate guards a merge command, so all
86
+ four hosts behave the same:
87
+
88
+ | Host | What guards `gh pr merge` / `glab mr merge` |
89
+ |---|---|
90
+ | Claude Code | Nothing: the git gate matches only `git commit` and `git push` |
91
+ | OpenClaude | Same as Claude Code |
92
+ | OpenCode | Nothing: the permission globs cover only `git commit*` and `git push*` |
93
+ | Bob | Nothing: consent is a log line |
94
+
95
+ An MCP merge tool (a GitHub MCP server's merge, or a host's own auto-merge tool) is not a shell
96
+ command, so no shell gate sees it on any host. The forge's required checks and reviews are the
97
+ boundary.
98
+
99
+ A [factory](run-a-factory.md) follows the same rule: at the end of a green run it arms auto-merge
100
+ when the rule allows, and otherwise asks you once whether to merge.
@@ -14,7 +14,7 @@ All of these choices are made **at build time**. The build writes them into the
14
14
 
15
15
  ## Theme: the voice
16
16
 
17
- A theme changes how the harness *sounds*: the banner, the readiness sigil the agent opens with, and the vocabulary of its prose. It never changes which rules apply or which files ship. The wizard previews each theme live as you move through the list.
17
+ A theme changes how the harness *sounds*: the banner, the readiness sigil the agent opens with, and the vocabulary of its prose. It never changes which rules apply or which files ship. The wizard lists each theme with a one-line description.
18
18
 
19
19
  `neutral` is plain English. The others are `imperial`, `military`, `pirate`, `wizard`, `cyberpunk`, `gamer`, `sports`, `biker`, `commentator`, `joker`, `marvin`, `mean` and `verstappen`.
20
20
 
@@ -19,6 +19,6 @@ cat issue.md | opencode run "triage this and propose a fix plan" # pipe inp
19
19
 
20
20
  ## Things to know
21
21
 
22
- - **Permission prompts still apply, and in CI nobody can answer them.** Any command the config marks `ask` blocks a non-interactive run: `rm -rf`, and `git commit` and `git push` whenever the *Consent Before Push* rule is built in (it is part of the `process` pack; see [Doctrine packs and single rules](setup-doctrines.md)). A CI job that has to commit should set those commands back to `"allow"` in its own `permission.bash` map, or limit the run to read-only work. Do not disable the guards wholesale.
22
+ - **Permission prompts still apply, and in CI nobody can answer them.** Any command the config marks `ask` blocks a non-interactive run: `git commit` and `git push` whenever the *Consent Before Push* rule is built in (OpenCode's globs cannot see the branch, so they ask for every commit and push, not only those onto the main branch) (it is part of the `process` pack; see [Doctrine packs and single rules](setup-doctrines.md)). A CI job that has to commit should set those commands back to `"allow"` in its own `permission.bash` map, or limit the run to read-only work. Do not disable the guards wholesale.
23
23
  - **`--pure`** runs OpenCode without any local or global config. Use it to reproduce a bug without the harness in the way, or to confirm that a behaviour comes from the harness.
24
24
  - **The plugins still load.** The context plugin injects the repo's docs, and the learn plugin still writes memory when the session goes idle. To change their behaviour for a run, set `GENESEED_GUARD=warn` or `off`, `GENESEED_CONTEXT_INJECT=off`, or `GENESEED_DEBUG=1`. See [Context and memory variables](../reference/env-context.md) and [OpenCode plugins](../reference/opencode-plugins.md).
@@ -8,7 +8,7 @@ description: "Install from a git clone when npm is out of reach, or when you wan
8
8
  ---
9
9
  Clone the repository when npm is out of reach (for example, a corporate network with no registry access), or when you want to change the harness rather than just use it. A clone needs **git** as well as Node 22.7 or newer. git is what updates the clone.
10
10
 
11
- Each OS has a one-step installer at the root of the clone. It checks for Node and git. If one is missing, it names what to install and where to get it, then stops. **It never installs anything itself.** When the checks pass, it runs the setup wizard and offers to open the web console.
11
+ Each OS has a one-step installer at the root of the clone. It checks for Node and git and names what to install and where to get it. A missing Node stops the installer; a missing git only warns, because setup runs without it and updates need it. **It never installs anything itself.** When the checks pass, it runs the setup wizard (it then runs `geneseed link` if `geneseed` is not on your `PATH`) and offers to open the web console.
12
12
 
13
13
  ```bash
14
14
  git clone https://github.com/Arylmera/Geneseed.git
@@ -25,6 +25,24 @@ cd Geneseed
25
25
  .\install.cmd
26
26
  ```
27
27
 
28
+ ### With no questions: a profile
29
+
30
+ Add `--profile <name>` to either installer and it asks nothing. It installs that profile globally into every AI coding tool the profile lists and finds on the machine, puts `geneseed` on your `PATH`, sets the web console to start at login, starts it and runs the doctor. `starter` is the profile for a first install:
31
+
32
+ Windows (cmd or PowerShell):
33
+
34
+ ```bat
35
+ .\install.cmd --profile starter
36
+ ```
37
+
38
+ macOS, Linux:
39
+
40
+ ```bash
41
+ ./install --profile starter
42
+ ```
43
+
44
+ With `--profile`, the installer skips its own `link` and its "open the console now?" question, and `install.cmd` skips its final pause, so a script that runs it returns. Run the same line again to update and repair. [Install profiles](../reference/profiles.md) has the file format and what each run does.
45
+
28
46
  Later, run the launcher in the clone: `./geneseed setup` (Windows: `.\geneseed.cmd setup`) re-runs the wizard, and bare `./geneseed` opens the web console. Both launchers need `node` on `PATH`. If it is not there (some version managers only patch interactive shells), set `GENESEED_NODE` to the absolute path of the Node binary.
29
47
 
30
48
  From a clone, every `geneseed …` command on these pages is `./geneseed …` (Windows: `.\geneseed.cmd …`). To drop the `./`, see [Run geneseed from anywhere](run-anywhere.md).
@@ -6,13 +6,19 @@ kind: "concept"
6
6
  section: "Install"
7
7
  description: "The build command to run in a script, a CI job, or a shell with no terminal."
8
8
  ---
9
- `setup` needs an interactive terminal. In a script, a CI job, or any shell without one, it stops with exit code 1 and prints the build command to run instead:
9
+ `setup --profile <name>` needs no terminal. It installs a named profile (Shipped, from `profiles/`, or Personal, from `~/.config/geneseed/profiles/`) globally into each AI coding tool the profile lists and finds, with no question, and exits 1 when a build or the doctor fails. A profile with `"login": false` skips the login item and the console, which is what a server or a CI job wants. See [Install profiles](../reference/profiles.md).
10
+
11
+ ```
12
+ geneseed setup --profile starter
13
+ ```
14
+
15
+ The wizard, plain `setup`, needs an interactive terminal. In a script, a CI job, or any shell without one, it stops with exit code 1 and prints the build command to run instead:
10
16
 
11
17
  ```
12
18
  geneseed build --emit opencode-global --theme neutral
13
19
  ```
14
20
 
15
- `geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--trust`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md) and the two pages after it. `--exclude-skills` leaves skills you never use out of the install; see [Exclusions](../concepts/exclusions.md). `--kits <kit>` switches on an opt-in kit, and `--kits none` switches every kit off; see [Kits](../concepts/kits.md).
21
+ `geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--trust`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md) and the two pages after it. `--exclude-skills` leaves skills you never use out of the install; see [Exclusions](../concepts/exclusions.md). `--kits <kit>` switches on an opt-in kit, and `--kits none` switches every kit off; see [Kits](../concepts/kits.md). `--context-window 1m` builds a Claude Code install for a 1M-token model (the default is `200k`); see [the listing budget](../concepts/skills.md#the-listing-budget-on-claude-code).
16
22
 
17
23
  To test a build before writing anything, use `geneseed validate` with the same flags. See [Verify](verify.md).
18
24
 
@@ -8,6 +8,24 @@ description: "The one-command install, what it needs, and the page for each host
8
8
  ---
9
9
  Geneseed builds a harness (the rules, agents, skills and hooks your AI coding tool loads; see [What a harness is](../understand/harness.md)) and installs it into the tool you already use. Most people need one command.
10
10
 
11
+ ## New to AI agents: one line, no questions
12
+
13
+ You need **git** and **Node 22.7 or newer**. Clone Geneseed where you like, then run the installer with the `starter` profile:
14
+
15
+ Windows (cmd or PowerShell 7; on Windows PowerShell 5.1, put `;` in place of each `&&`):
16
+
17
+ ```bat
18
+ git clone https://github.com/Arylmera/Geneseed.git && cd Geneseed && .\install.cmd --profile starter
19
+ ```
20
+
21
+ macOS, Linux:
22
+
23
+ ```bash
24
+ git clone https://github.com/Arylmera/Geneseed.git && cd Geneseed && ./install --profile starter
25
+ ```
26
+
27
+ It asks nothing. It installs the harness globally into every AI coding tool it finds (OpenCode, IBM Bob, Claude Code, OpenClaude), puts `geneseed` on your `PATH`, sets the web console to start at login, starts it, runs the health check, and prints a summary with the console's address. With no tool on the machine it installs nothing and prints where to get each one. Run the same line again to update and repair. `starter` is a neutral voice, a candid peer posture, and every guardrail armed except the ownership gate. [Install profiles](../reference/profiles.md) has the details: how to save your own setup as a Personal profile, apply a profile to one project with `geneseed profile apply`, and how a team adds a Shipped one.
28
+
11
29
  ## The 5-minute path
12
30
 
13
31
  The only prerequisite is **Node 22.7 or newer**.
@@ -16,9 +34,9 @@ The only prerequisite is **Node 22.7 or newer**.
16
34
  npx geneseed setup
17
35
  ```
18
36
 
19
- The command is the same on macOS, Linux and Windows (cmd, PowerShell or any POSIX shell). The setup wizard lists the AI coding tools it found on your `PATH`, then asks for a theme, a posture, a mode, the doctrine packs, an install mode and a footprint. Each one has a safe default, so you can hold Enter through all of them. [Choose your setup](choose-your-setup.md) explains each question. **OpenCode global** is the recommended install mode: you install once and every repo inherits it, with nothing committed into your projects. The wizard then builds the harness and ends with a short summary: the root file your tool loads and where it was written, the hooks it wired (Claude Code, Bob and OpenClaude), whether memory learning is on, which tool to restart, and a link to what was installed. It then offers to run a health check.
37
+ The command is the same on macOS, Linux and Windows (cmd, PowerShell or any POSIX shell). The setup wizard lists the AI coding tools it found on your `PATH` or in the usual per-user folders, then asks for a theme, a posture, a mode, the doctrine packs, the kits, an install mode and a footprint. Each one has a safe default, so you can hold Enter through all of them. [Choose your setup](choose-your-setup.md) explains each question. **OpenCode global** is the recommended install mode: you install once and every repo inherits it, with nothing committed into your projects. The wizard then builds the harness and ends with a short summary: the root file your tool loads and where it was written, the hooks it wired (Claude Code, Bob and OpenClaude), whether memory learning is on, which tool to restart, and a link to what was installed. It then offers to run a health check.
20
38
 
21
- To keep the command on your machine:
39
+ `npx geneseed setup` puts no `geneseed` command in your terminal, and its summary ends with a note that says so. To keep the command on your machine:
22
40
 
23
41
  ```
24
42
  npm install -g geneseed
@@ -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. |