geneseed 5.2.0 → 5.3.1

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 (190) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/README.md +4 -4
  3. package/SHIPPED.md +1 -1
  4. package/adapters/bob/README.md +31 -18
  5. package/adapters/claude-code/README.md +27 -22
  6. package/adapters/openclaude/README.md +18 -8
  7. package/adapters/opencode/HOW-OPENCODE-LOADS.md +8 -3
  8. package/adapters/opencode/plugins/geneseed-activity.js +20 -21
  9. package/adapters/opencode/plugins/geneseed-context.js +224 -71
  10. package/adapters/opencode/plugins/geneseed-guard.js +420 -203
  11. package/adapters/opencode/plugins/geneseed-workflow.js +3 -2
  12. package/adapters/opencode/workflows/_runtime.js +3 -2
  13. package/bin/geneseed-cli.mjs +61 -16
  14. package/bin/geneseed-hook.mjs +94 -12
  15. package/docs/concepts/enforcement-table.md +1 -1
  16. package/docs/concepts/exclusions.md +2 -2
  17. package/docs/concepts/factories.md +40 -6
  18. package/docs/concepts/footprint.md +11 -1
  19. package/docs/concepts/foreman-mode.md +2 -2
  20. package/docs/concepts/hook-gates.md +3 -3
  21. package/docs/concepts/host-matrix.md +22 -4
  22. package/docs/concepts/loop-gates.md +1 -1
  23. package/docs/concepts/loops.md +2 -2
  24. package/docs/concepts/shared-tier.md +1 -1
  25. package/docs/design-history.md +148 -0
  26. package/docs/extending.md +97 -163
  27. package/docs/guides/install-bob.md +2 -2
  28. package/docs/guides/install-openclaude.md +1 -1
  29. package/docs/guides/run-a-factory.md +15 -2
  30. package/docs/guides/upgrade.md +2 -2
  31. package/docs/guides/verify.md +12 -0
  32. package/docs/reference/environment.md +1 -0
  33. package/docs/reference/factory-actions.md +6 -5
  34. package/docs/reference/troubleshoot-doctor.md +1 -1
  35. package/docs/reference/troubleshoot-update.md +1 -1
  36. package/docs/token-footprint.md +66 -2
  37. package/docs/understand/design-choices-hosts.md +1 -1
  38. package/docs/understand/design-choices-shape.md +1 -0
  39. package/docs/understand/enforced-vs-asked.md +1 -1
  40. package/docs/understand/machine-bob.md +1 -1
  41. package/docs/web-ui.md +21 -3
  42. package/harness.config.json +1 -1
  43. package/js/README.md +7 -5
  44. package/js/build/args.mjs +4 -4
  45. package/js/build/driver.mjs +1 -1
  46. package/js/build/emit-claude.mjs +1 -1
  47. package/js/build/generate.mjs +5 -14
  48. package/js/build/render.mjs +44 -24
  49. package/js/cli-table.json +135 -59
  50. package/js/factory/cli.mjs +24 -5
  51. package/js/factory/graph.mjs +13 -9
  52. package/js/factory/metrics.mjs +93 -0
  53. package/js/factory/registry.mjs +37 -12
  54. package/js/factory/state.mjs +25 -6
  55. package/js/hosts/done-checks.mjs +6 -0
  56. package/js/hosts/geneseed-dir.mjs +3 -2
  57. package/js/hosts/gitref.mjs +5 -3
  58. package/js/hosts/hook-tap.mjs +104 -0
  59. package/js/hosts/hooks-context.mjs +30 -3
  60. package/js/hosts/hooks-learn.mjs +47 -16
  61. package/js/hosts/hooks-prims.mjs +52 -3
  62. package/js/hosts/hooks.mjs +69 -42
  63. package/js/hosts/hosts.mjs +80 -12
  64. package/js/hosts/installs.mjs +7 -0
  65. package/js/hosts/loss.mjs +6 -1
  66. package/js/hosts/native.mjs +14 -5
  67. package/js/hosts/owned.mjs +7 -6
  68. package/js/hosts/ownership-gate.mjs +14 -1
  69. package/js/hosts/settings.mjs +245 -103
  70. package/js/hosts/shim.mjs +4 -4
  71. package/js/hosts/usage.mjs +9 -3
  72. package/js/inspect/checks-probe.mjs +66 -5
  73. package/js/inspect/checks-repo.mjs +196 -2
  74. package/js/inspect/cost.mjs +34 -2
  75. package/js/inspect/diff.mjs +16 -1
  76. package/js/inspect/doctor.mjs +13 -4
  77. package/js/inspect/excludes.mjs +18 -6
  78. package/js/inspect/status.mjs +35 -7
  79. package/js/inspect/validate.mjs +44 -21
  80. package/js/lib/machine-dir.mjs +1 -1
  81. package/js/lib/node-floor.mjs +46 -6
  82. package/js/maintain/uninstall.mjs +70 -17
  83. package/js/maintain/update.mjs +31 -7
  84. package/js/ui/cli.mjs +34 -4
  85. package/js/ui/menu.mjs +1 -1
  86. package/js/ui/tui.mjs +11 -14
  87. package/js/web/actions.mjs +3 -9
  88. package/js/web/api.mjs +28 -10
  89. package/js/web/daemon.mjs +0 -1
  90. package/js/web/server.mjs +1 -0
  91. package/js/web/state.mjs +37 -16
  92. package/package.json +1 -1
  93. package/src/AGENT.md.tmpl +23 -17
  94. package/src/agents/_template.md +1 -1
  95. package/src/agents/advocate.md +1 -1
  96. package/src/agents/developer.md +12 -3
  97. package/src/agents/empiricist.md +1 -1
  98. package/src/agents/framer.md +1 -1
  99. package/src/agents/historian.md +1 -1
  100. package/src/agents/operator.md +1 -1
  101. package/src/agents/pragmatist.md +1 -1
  102. package/src/agents/researcher.md +1 -1
  103. package/src/agents/skeptic.md +1 -1
  104. package/src/agents/steward.md +1 -1
  105. package/src/agents/user-advocate.md +1 -1
  106. package/src/agents/visionary.md +1 -1
  107. package/src/bricks/intake.md +10 -3
  108. package/src/bricks/retro.md +13 -3
  109. package/src/doctrines/comms.md +1 -1
  110. package/src/doctrines/ops.md +1 -1
  111. package/src/doctrines/process.md +7 -5
  112. package/src/factories/analysis-to-build.json +1 -0
  113. package/src/factories/bug-report-to-fix.json +1 -0
  114. package/src/factories/issue-to-pr.json +1 -0
  115. package/src/laws/universal.md +2 -2
  116. package/src/modes/foreman.md +8 -14
  117. package/src/skills/commit.md +7 -2
  118. package/src/skills/debug.md +1 -1
  119. package/src/skills/diagram-design/SKILL.md +1 -1
  120. package/src/skills/diagram-design/VENDOR.md +3 -1
  121. package/src/skills/factory-forge.md +5 -3
  122. package/src/skills/factory.md +22 -1
  123. package/src/skills/geneseed.md +1 -1
  124. package/src/skills/handoff.md +1 -1
  125. package/src/skills/parallel-agents.md +1 -1
  126. package/src/skills/pipeline.md +6 -6
  127. package/src/skills/plan.md +7 -3
  128. package/src/skills/spring-testing.md +1 -1
  129. package/themes/biker.json +78 -78
  130. package/themes/commentator.json +81 -81
  131. package/themes/cyberpunk.json +79 -79
  132. package/themes/gamer.json +77 -77
  133. package/themes/imperial.json +82 -82
  134. package/themes/joker.json +79 -79
  135. package/themes/marvin.json +82 -82
  136. package/themes/mean.json +82 -82
  137. package/themes/military.json +78 -78
  138. package/themes/neutral.json +78 -78
  139. package/themes/pirate.json +79 -79
  140. package/themes/sports.json +79 -79
  141. package/themes/verstappen.json +78 -78
  142. package/themes/wizard.json +79 -79
  143. package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
  144. package/web/dist/assets/Activity-WQ3ykgxU.js +1 -0
  145. package/web/dist/assets/ActivityDetail-7rt04SkS.js +1 -0
  146. package/web/dist/assets/{Bonsai-DSwUbavu.js → Bonsai-BBl4XXqs.js} +1 -1
  147. package/web/dist/assets/{CopyButton-BzRQz7k2.js → CopyButton-Beven8yn.js} +1 -1
  148. package/web/dist/assets/Dashboard-BgLArtgu.js +2 -0
  149. package/web/dist/assets/Docs-B5aHp86J.js +5 -0
  150. package/web/dist/assets/Factories-BjqzXAw8.js +1 -0
  151. package/web/dist/assets/GreenhouseView-Bce212qd.js +1 -0
  152. package/web/dist/assets/Installs-B1OsrHXF.js +3 -0
  153. package/web/dist/assets/JournalView-CV4omyww.js +1 -0
  154. package/web/dist/assets/Kits-CW1e7xNa.js +1 -0
  155. package/web/dist/assets/Laws-1Ckf1lbs.js +4 -0
  156. package/web/dist/assets/LibRows-Dag1s0ZX.js +1 -0
  157. package/web/dist/assets/Library-B3FuFLel.js +3 -0
  158. package/web/dist/assets/Loops-CwqgnLNw.js +2 -0
  159. package/web/dist/assets/Markdown-CxkA7940.js +71 -0
  160. package/web/dist/assets/OperatorHudView-JmYY1pBR.js +1 -0
  161. package/web/dist/assets/Personal-DKLgLa7Z.js +2 -0
  162. package/web/dist/assets/Settings-BwErnh-R.js +1 -0
  163. package/web/dist/assets/Tabs-8zsyEPSK.js +1 -0
  164. package/web/dist/assets/index-CRWqKxfY.css +1 -0
  165. package/web/dist/assets/index-Ce6qF2nG.js +6 -0
  166. package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
  167. package/web/dist/index.html +2 -2
  168. package/adapters/claude-code/settings.json +0 -52
  169. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
  170. package/web/dist/assets/Activity-DlQ30znB.js +0 -1
  171. package/web/dist/assets/ActivityDetail-CG0mn5fW.js +0 -1
  172. package/web/dist/assets/Dashboard-Ce3UOsxJ.js +0 -2
  173. package/web/dist/assets/Docs-CisVnYqv.js +0 -5
  174. package/web/dist/assets/Factories-Dq5oW4CU.js +0 -1
  175. package/web/dist/assets/GreenhouseView-y9WAfcc_.js +0 -1
  176. package/web/dist/assets/Installs-m4GElwFW.js +0 -3
  177. package/web/dist/assets/JournalView-DeBLRNGc.js +0 -1
  178. package/web/dist/assets/Kits-DJYVAnyE.js +0 -1
  179. package/web/dist/assets/Laws-CNpc_8ZV.js +0 -4
  180. package/web/dist/assets/LibRows-RO5bvXth.js +0 -1
  181. package/web/dist/assets/Library-Dg0ScciC.js +0 -3
  182. package/web/dist/assets/Loops-CjEdo-NG.js +0 -2
  183. package/web/dist/assets/Markdown-0ORz7tAc.js +0 -69
  184. package/web/dist/assets/OperatorHudView-2ujVMjq1.js +0 -1
  185. package/web/dist/assets/Personal-D0yS7ahT.js +0 -2
  186. package/web/dist/assets/Settings-DEN0U8QI.js +0 -1
  187. package/web/dist/assets/Tabs-But5R6_r.js +0 -1
  188. package/web/dist/assets/index-Ck42AbRX.js +0 -6
  189. package/web/dist/assets/index-PG_ukkh6.css +0 -1
  190. package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
@@ -19,7 +19,7 @@ geneseed rebuild-all # rebuild every install with its own settings
19
19
 
20
20
  `rebuild-all` re-renders each registered install in place, keeping its own theme, host, footprint, posture, mode, packs and rule exclusions. It is best-effort: when one install fails, it reports the failure and carries on with the rest.
21
21
 
22
- `upgrade`, `update` and `bootstrap` are the clone route. Run from an npm install, they stop before touching anything and point you to `npm install -g geneseed@latest` instead.
22
+ `upgrade` and `update` (and the deprecated `bootstrap`) are the clone route. Run from an npm install, they stop before touching anything and point you to `npm install -g geneseed@latest` instead.
23
23
 
24
24
  ## Installed from a clone
25
25
 
@@ -36,7 +36,7 @@ geneseed upgrade imperial # the same, switching the theme
36
36
 
37
37
  If the `doctor` pass cannot finish, for example on a busy machine after 300 seconds, `upgrade` keeps the pull, rebuilds nothing, and exits 1. The pulled source is unchecked, not bad. Run `geneseed upgrade` again: it runs `doctor` first, rebuilds on a pass, and rolls back to the last checked commit on a failure.
38
38
 
39
- A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` is an alias of `upgrade`; `sync-self` was removed in 5.0.0, and `upgrade` takes only a theme. `bootstrap` does the same and then opens the setup wizard (`--no-setup` skips the wizard).
39
+ A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` is an alias of `upgrade`; `sync-self` was removed in 5.0.0, and `upgrade` takes only a theme (as an argument or `--theme`). `upgrade --setup` does the same and then opens the setup wizard; `bootstrap`, its old name, still works for one release and says so.
40
40
 
41
41
  ## The Update button in the web console
42
42
 
@@ -52,6 +52,18 @@ Start a session with `GENESEED_DEBUG=1` set. The context plugin then logs what i
52
52
  At session start, the context hook adds the repo's docs to the conversation. Ask the agent what project context it received. It should name your `README.md` and list your `docs/`.
53
53
  <!--/harness-->
54
54
 
55
+ ## Bob, by hand
56
+
57
+ No automated check runs IBM Bob: it is not published on npm, so the host canary cannot install it ([What is verified](../concepts/host-matrix.md#what-is-verified)). `geneseed doctor --probe` runs Bob's installed gate through Bob's shell, which proves the gate. Only Bob can prove that Bob calls it. Five steps, in a scratch repository:
58
+
59
+ 1. **The hooks are loaded.** Type `/hooks` in Bob Shell. For a global install it lists four groups from `~/.bob/settings/settings.json`: `SessionStart`, `PreToolUse`, `Stop` and `UserPromptSubmit`. If Geneseed's are missing, Bob is reading another file.
60
+ 2. **A credential write is refused.** Ask Bob to write a file holding an AWS access key id (the example one from the AWS documentation will do). The write does not happen, and Bob shows the gate's reason, which says that no confirmation in the chat lifts it.
61
+ 3. **A destructive git command is refused.** Ask Bob to run `git reflog expire --expire=now --all`. It is refused the same way.
62
+ 4. **A commit warns.** Ask Bob to commit a change. The commit goes through, and Bob's hook log has a Geneseed line about consent: Bob cannot ask, so this rule is a warning there.
63
+ 5. **Record what Bob sends.** Start Bob with `GENESEED_HOOK_TAP` set to an absolute directory outside any repository, for example `GENESEED_HOOK_TAP=$HOME/geneseed-tap`. Then start a session, send a prompt, let Bob run one command and edit one file, and let the turn end. Each hook call writes one file, `bob-<event>-<n>.json`.
64
+
65
+ A tap file holds the payload's shape and not its content. Every key is kept; every string is replaced by its type and length, except the event name and the tool name. Your prompt, file contents, commands and paths are not in it. Read the files before you send them all the same, then attach them to an issue at <https://github.com/Arylmera/Geneseed/issues>, with your Bob version. One file per event is enough. Unset the variable afterwards: nothing is written without it, and Geneseed never puts it in a settings file. The tap works the same way on Claude Code and OpenClaude.
66
+
55
67
  ## Dry-run a build before you write it
56
68
 
57
69
  `geneseed validate` takes the same flags as `geneseed build`. It renders into a throwaway sandbox and runs every doctor check against the result. Nothing is written under the real `--out` or `--root`: no marker files, no settings merge, no registry record.
@@ -20,6 +20,7 @@ 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_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). |
23
24
  | `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`. |
24
25
  | `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. |
25
26
  | `XDG_CONFIG_HOME` | every emit, hooks, plugins, web console | The base of the [shared tier](../concepts/shared-tier.md), `$XDG_CONFIG_HOME/geneseed` (default `~/.config/geneseed`), on every host. Also used when `OPENCODE_CONFIG_DIR` is unset: the install goes to `$XDG_CONFIG_HOME/opencode` (default `~/.config/opencode`). |
@@ -6,16 +6,17 @@ kind: "concept"
6
6
  section: "CLI & environment"
7
7
  description: "The geneseed factory actions, one line each."
8
8
  ---
9
- The actions of `geneseed factory`, the state machine that carries one work item through a graph of stages to an open PR. A stage is a brick or a whole loop (`loop:<template>`). A **fork** is a brick that declares a named outcome (one other than `pass`, `fail`, `error`, `none` or `needs-info`), each outcome with its own edge to its own lane. An edge target or a cycle node may be `$lane`: the stage the run's most recent fork chose. The run state lives in `FACTORY.md` at the worktree root, beside the child loop's `LOOP.md` ([Loop actions](loop-actions.md)). Each action prints one JSON object and exits 1 on a refusal.
9
+ The actions of `geneseed factory`, the state machine that carries one work item through a graph of stages to an open PR. A stage is a brick or a whole loop (`loop:<template>`). A **fork** is a brick that declares a named outcome (one other than `pass`, `fail`, `error`, `none`, `needs-info` or `reject`), each outcome with its own edge to its own lane. An edge target or a cycle node may be `$lane`: the stage the run's most recent fork chose. The run state lives in `FACTORY.md` at the worktree root, beside the child loop's `LOOP.md` ([Loop actions](loop-actions.md)). Each action prints one JSON object and exits 1 on a refusal.
10
10
 
11
11
  | action | what it does |
12
12
  |---|---|
13
- | `check` | checks every factory in the catalogue, or one factory (`--factory <name or .json file>`): the factory has a name and no stage twice, every stage exists, every outcome has one edge (`error` and `needs-info` may go without one: `error` then stops the run, and `needs-info` follows the stage's `pass` edge), `$close` is reachable, every cycle is declared with a `max` from 1 to 5, each cycle is entered only at its first stage, and every route back targets the first stage of a cycle that holds its source. `$lane` needs a fork on every path to it, and a fork's own edge never targets it. In those checks, `$lane` stands for every lane of every fork. A factory that still uses the retired `loop:$triaged` stage or `loops` list gets a problem that names the replacement; nothing rewrites the file. An optional `protected` must be a list of non-empty paths. An outcome on which a brick reports environment failures (`checks` `error`, `merge-gate` `none`) never routes to a `loop:` stage or `$lane`: no loop can fix a failed fetch, a missing tool or CI pending at the bound. An optional `review.seats` needs a non-empty list of agents for each of `small`, `medium` and `large`, and `areas`, when present, maps each area to such a list; every seat must name a shipped agent (`review.seats.medium: no agent named <name>`). A project factory overrides a global or shipped one of the same name, and a global one a shipped one: `check` lists each in `overridden`. A file that does not load is a problem that names its level (`factories/<name>.json (project): not JSON`), and it drops the factory of that name from lower levels, so `init` refuses with that problem instead of running another graph |
13
+ | `check` | checks every factory in the catalogue, or one factory (`--factory <name or .json file>`): the factory has a name and no stage twice, every stage exists, every outcome has one edge (`error`, `reject` and `needs-info` may go without one: `error` and `reject` then stop the run, and `needs-info` follows the stage's `pass` edge), `$close` is reachable, every cycle is declared with a `max` from 1 to 5, each cycle is entered only at its first stage, and every route back targets the first stage of a cycle that holds its source. `$lane` needs a fork on every path to it, and a fork's own edge never targets it. In those checks, `$lane` stands for every lane of every fork. A factory that still uses the retired `loop:$triaged` stage or `loops` list gets a problem that names the replacement; nothing rewrites the file. An optional `protected` must be a list of non-empty paths. An outcome on which a brick reports environment failures (`checks` `error`, `merge-gate` `none`) never routes to a `loop:` stage or `$lane`: no loop can fix a failed fetch, a missing tool or CI pending at the bound. An optional `review.seats` needs a non-empty list of agents for each of `small`, `medium` and `large`, and `areas`, when present, maps each area to such a list; every seat must name a shipped agent (`review.seats.medium: no agent named <name>`). A project factory overrides a global or shipped one of the same name, and a global one a shipped one: `check` lists each in `overridden`. A file that does not load is a problem that names its level (`factories/<name>.json (project): not JSON`), and it drops the factory of that name from lower levels, so `init` refuses with that problem instead of running another graph |
14
14
  | `list` | lists the factories of the three origins (shipped, global, project), with description, category and origin |
15
- | `init` | writes a fresh `FACTORY.md` from a factory, under a title, a requirement and an optional `--input` (an issue URL, a file path or pasted text). A factory that fails `check` is refused before any stage runs, and so is a run branch `loop/factory-<slug>` whose slug holds the word `git`, `commit` or `push`: the slug lands on lines the git gate reads. Each `init` also registers the run in `factories.json`, beside the loop registry |
15
+ | `init` | writes a fresh `FACTORY.md` from a factory, under a title, a requirement and an optional `--input` (an issue URL, a file path or pasted text), and stamps the time as the run's `started`. A factory that fails `check` is refused before any stage runs, and so is a run branch `loop/factory-<slug>` whose slug holds the word `git`, `commit` or `push`: the slug lands on lines the git gate reads. Each `init` also registers the run in `factories.json`, beside the loop registry |
16
16
  | `next` | returns the next thing to do: run a brick stage, run a loop (with `notes` to start it with, and the `task` when a spec set tasks: the spec's `path`, the task `count` and this task's `index`), answer an `awaiting` gate, or a terminal. A fork stage also gets `lanes`: each outcome it may report, with the stage it leads to. Every stage gets the factory's `rules`, and its `protected` paths when it declares any. Refused while a `LOOP.md` exists that is not `done` or `stopped` (an unreadable one counts as running): the child loop finishes first. On a loop stage, refused while any `LOOP.md` is left: `git rm -f LOOP.md` and commit that removal before `geneseed loop init`. On a loop stage, `next` also records the launch in `FACTORY.md`: the loop template, the HEAD commit and the time. When a later stage routes back to the loop stage that ran the tasks, after its last task passed (a failed `checks`, `review-panel` or `holdout`, or red CI at `merge-gate`), `next` hands out one extra task: the last `index` again, with `extra` set to the stage and outcome that sent it back (`"merge-gate reported fail"`). That lap spends the route's cycle and the transition ceilings like any other, and gives no fresh budget |
17
- | `record` | records the current stage's outcome and follows its edge. A loop stage reports `pass` (its loop closed) or `fail` (it stopped), and only after `next` launched it. While its `LOOP.md` is still there, that file must name the stage's template, a `stopped` one admits only `fail`, and a `done` one only `pass`. With no `LOOP.md` left, `pass` and `fail` both need a HEAD that moved since `next`: the loop's close commit, or the commit that removes a stopped loop's `LOOP.md`. That is enough for `fail`. `pass` also needs the loop registry to show a `geneseed loop init` in this worktree after `next`. Without it, `pass` is refused: record it while the `done` `LOOP.md` is still at the root, or report `fail`. The registry does not keep a loop's final status, so a stopped loop whose `LOOP.md` was removed by hand can still pass. `--carry` hands a reason to the next stage; a re-entered loop starts with it as a note. `--carry-file <file>` reads it from a file instead (CRLF folded, trimmed), for free text, which never goes on the command line: the skill writes it with the host's file tool, never the shell, to a file it names uniquely. Every path argument (`--spec`, `--factory <file>`, `--carry-file`, `--note-file`) is relative to the current directory; only `FACTORY.md` is found at the git root. On a fork, the outcome names the lane: the stage its edge reaches is stored as the run's `lane`, and an edge to `$lane` goes there. A route to `$lane` with no lane on record is refused. `--spec <path>` records the run's spec, which must be at `specs/<slug>/spec.md` (any other path is refused before the state changes): the first loop stage recorded after it runs once per numbered item (`1.` or `1)`, indented 3 spaces at most) under its first heading that contains the word `task` or `tasks`, up to the next heading of the same or a higher level (`#`, indented 3 spaces at most, or a setext heading), 20 at most. As in CommonMark, a numbered item indented as far as the text of the task above it is a sub-item, and a fenced block (```` ``` ```` or `~~~`) is skipped whole. Until the first task loop launches (the first loop after a spec is on record; a loop that ran before any spec does not count), each `--spec` sets the count again, so a spec amended at its gate may list more tasks. From that launch the count is frozen: a later `--spec` may keep or lower it, never raise it. After a stage outside a loop, pipe it `git status --porcelain --untracked-files=all` in one command: `git status --porcelain --untracked-files=all | geneseed factory record …`. PowerShell pipes the same way; the CRLF that Windows PowerShell 5.1 adds, and the leading BOM it adds when `$OutputEncoding` is UTF-8, are stripped. The git gate asks on any line that holds the word `git` and the word `commit` or `push`, so a record line whose spec path, carry path or outcome holds `commit` or `push` asks: a false alarm the user can answer yes to. `init` refuses a slug with those words, which removes the commonest case. Plain `--porcelain` shows a new directory as one line (`?? specs/`), so a new spec is refused. The tree must be clean (a `mutate` brick such as a `docs-update` lane commits its change first), with two exceptions: engine files, and the run's spec at `specs/<slug>/spec.md` (the one recorded now, else the one on record). No stdin at all (a terminal) is refused. An empty pipe reads as a clean tree. Refused, as `next` is, while a child loop owns the worktree. Every state action also refuses a `FACTORY.md` that does not parse, or one that holds any of these: counters that are not non-negative integers, a run-wide ceiling above 1200, a gate amend count above 3, a `lane` that no fork of the factory leads to, a current stage, task-owning stage, launched loop or held gate that the factory does not hold, an `awaiting` that does not match the status, an unknown status, a `history` or `cycles` that is not a list, or a factory that no longer passes `check` |
18
- | `decide` | answers a held `gate: human` stage: `ok` follows the edge (an edge to `$lane` goes to the lane on record), `no` stops, `amend` re-runs the stage with the `--note` as its carry (three times at most). `--note-file <file>` reads the note from a file instead, as `--carry-file` does |
17
+ | `record` | records the current stage's outcome and follows its edge. The history entry it writes carries the time as `at`. `--tokens <n>` stores on that entry the token count the host reported for the agent that ran the stage: a positive integer written in digits, anything else is refused before the state changes. Leave it out when the host gave no count; nothing estimates one. A loop stage reports `pass` (its loop closed) or `fail` (it stopped), and only after `next` launched it. While its `LOOP.md` is still there, that file must name the stage's template, a `stopped` one admits only `fail`, and a `done` one only `pass`. With no `LOOP.md` left, `pass` and `fail` both need a HEAD that moved since `next`: the loop's close commit, or the commit that removes a stopped loop's `LOOP.md`. That is enough for `fail`. `pass` also needs the loop registry to show a `geneseed loop init` in this worktree after `next`. Without it, `pass` is refused: record it while the `done` `LOOP.md` is still at the root, or report `fail`. The registry does not keep a loop's final status, so a stopped loop whose `LOOP.md` was removed by hand can still pass. `--carry` hands a reason to the next stage; a re-entered loop starts with it as a note. `--carry-file <file>` reads it from a file instead (CRLF folded, trimmed), for free text, which never goes on the command line: the skill writes it with the host's file tool, never the shell, to a file it names uniquely. Every path argument (`--spec`, `--factory <file>`, `--carry-file`, `--note-file`) is relative to the current directory; only `FACTORY.md` is found at the git root. On a fork, the outcome names the lane: the stage its edge reaches is stored as the run's `lane`, and an edge to `$lane` goes there. A route to `$lane` with no lane on record is refused. `--spec <path>` records the run's spec, which must be at `specs/<slug>/spec.md` (any other path is refused before the state changes): the first loop stage recorded after it runs once per numbered item (`1.` or `1)`, indented 3 spaces at most) under its first heading that contains the word `task` or `tasks`, up to the next heading of the same or a higher level (`#`, indented 3 spaces at most, or a setext heading), 20 at most. As in CommonMark, a numbered item indented as far as the text of the task above it is a sub-item, and a fenced block (```` ``` ```` or `~~~`) is skipped whole. Until the first task loop launches (the first loop after a spec is on record; a loop that ran before any spec does not count), each `--spec` sets the count again, so a spec amended at its gate may list more tasks. From that launch the count is frozen: a later `--spec` may keep or lower it, never raise it. After a stage outside a loop, pipe it `git status --porcelain --untracked-files=all` in one command: `git status --porcelain --untracked-files=all | geneseed factory record …`. PowerShell pipes the same way; the CRLF that Windows PowerShell 5.1 adds, and the leading BOM it adds when `$OutputEncoding` is UTF-8, are stripped. The git gate asks on any line that holds the word `git` and the word `commit` or `push`, so a record line whose spec path, carry path or outcome holds `commit` or `push` asks: a false alarm the user can answer yes to. `init` refuses a slug with those words, which removes the commonest case. Plain `--porcelain` shows a new directory as one line (`?? specs/`), so a new spec is refused. The tree must be clean (a `mutate` brick such as a `docs-update` lane commits its change first), with two exceptions: engine files, and the run's spec at `specs/<slug>/spec.md` (the one recorded now, else the one on record). No stdin at all (a terminal) is refused. An empty pipe reads as a clean tree. Refused, as `next` is, while a child loop owns the worktree. Every state action also refuses a `FACTORY.md` that does not parse, or one that holds any of these: counters that are not non-negative integers, a run-wide ceiling above 1200, a gate amend count above 3, a `lane` that no fork of the factory leads to, a current stage, task-owning stage, launched loop or held gate that the factory does not hold, an `awaiting` that does not match the status, an unknown status, a `history` or `cycles` that is not a list, or a factory that no longer passes `check` |
18
+ | `decide` | answers a held `gate: human` stage, and stamps the time on its history entry as `at`: `ok` follows the edge (an edge to `$lane` goes to the lane on record), `no` stops, `amend` re-runs the stage with the `--note` as its carry (three times at most). On `intake`'s `reject`, `ok` accepts the refusal: the edge goes to `$stop`, and the run stops with the reason `intake reported reject`. `--note-file <file>` reads the note from a file instead, as `--carry-file` does |
19
+ | `report` | prints the run's numbers as one JSON object and writes nothing. `stages` lists each stage the run recorded, in the order it first ran, with its `runs`, its `reworks` (an outcome that spent a cycle; a held outcome counts only once you answer `ok`), its `workMs` and its `tokens`. `workMs`, `waitMs`, `tokens` and `transitions` are the run's totals; `waitMs` counts a wait once its gate is answered, and `openWaitMs` is the wait still open while the run is held at a gate (the time now minus that record's time; `null` when no gate is held), and `entries` gives, for each history entry in order, its duration `ms`, whether it is waiting time (`wait`) and whether it is a rework. A duration is an entry's `at` minus the `at` of the entry before it (`started` for the first): work time on a `record` entry, waiting time on a `decide` entry. An entry with no time, as in a `FACTORY.md` written before times were stamped, gives `null`, and so does every total that holds it: never 0. `tokens` adds the counts recorded, and is `null` when none was. There is no cost in money |
19
20
 
20
21
  A route back into a cycle spends the cycle whose first stage is the route's target; past its `max` the run stops. A run stops too after 60 stage transitions, counted again for each spec task the run reaches for the first time, and after 60 transitions per task of the spec (60 without a spec) over the whole run. That run-wide ceiling follows the spec's task count until the first task loop launches (the first spec sets it even after an earlier loop), and never changes after.
21
22
 
@@ -44,7 +44,7 @@ settings spell it, through the host's own shell, on `git reflog expire --expire=
44
44
  and `git status` (which must go through). A gate wired with `--no-deletion-gate` lets the first one
45
45
  through by design, so it is probed on `find / -name geneseed-probe` instead — a root-wide scan it
46
46
  must still refuse. `--no-secrets-gate`, `--no-done-gate`, `--no-ownership-gate`, `--no-external-gate` and
47
- `--no-test-note` change nothing here: none judges either probe command. An OpenCode install's guard plugin has no command to
47
+ `--no-test-note` change nothing here: none judges either probe command. A Bob gate is asked twice more, in Bob's own shapes: the same two commands in its older `{event, tool, input}` payload, and a `write_file` carrying a made-up credential, which it must refuse. A problem line from one of those ends with the shape in brackets, and a gate wired `--no-secrets-gate` is not asked the last one. An OpenCode install's guard plugin has no command to
48
48
  run: the probe imports it and calls its hook through both plugin APIs (V1 and V2), with `rm -rf /`
49
49
  as the call it must refuse. `GENESEED_GUARD=off` or `warn` in your terminal makes that a note,
50
50
  not a failure.
@@ -26,7 +26,7 @@ The upgrade is a `git pull`, so it first checks the folder. Each refusal says wh
26
26
 
27
27
  | What you see | Cause and fix |
28
28
  | --- | --- |
29
- | `geneseed: error: invalid choice: 'sync-self'.` | The verb is gone. Run `geneseed upgrade`. |
29
+ | `geneseed: error: unknown command 'sync-self'. See geneseed --help.` | The verb is gone. Run `geneseed upgrade`. |
30
30
  | `geneseed: error: unrecognized arguments: imperial` from `upgrade main imperial` | `upgrade` takes only a theme. Run `geneseed upgrade imperial`. |
31
31
  | A host's `memory/` folder holds only its seed | Expected: [the fold](../concepts/shared-tier.md#the-fold) moved the facts to `~/.config/geneseed/memory/`. `geneseed memory list` shows them, and the old store is in `archived-memory/<stamp>/`. |
32
32
  | `[shared] <host>: … rules to approve` | Those rules wait in `user-rules.draft.md` and still bind from the host file. Ask the agent to review the pending rules; the `rule` skill decides them. |
@@ -8,8 +8,9 @@ chars/4 estimates and shift a little with theme and version.
8
8
  the default doctrine packs, 47 skills (plus 12 alias stubs) and 18 agents, and nothing
9
9
  re-measures this page automatically. For a
10
10
  live figure on your own install, ask the agent for the `token-report` skill —
11
- that is what it is for. A `--footprint full` build runs roughly 5k tokens
12
- heavier on the root file.
11
+ that is what it is for. A `--footprint full` build ran about 7k tokens heavier
12
+ when the whole request was captured on 2026-11-12 (see
13
+ [Why there is no chat mode](#why-there-is-no-chat-mode)).
13
14
 
14
15
  ## Always-on cost per session
15
16
 
@@ -101,6 +102,69 @@ until 2026-09 it did, and the whole harness was paid twice per session.
101
102
  - Plugin JavaScript (OpenCode, ~26k on disk) runs in the host runtime and
102
103
  never enters the context window.
103
104
 
105
+ ## Why there is no chat mode
106
+
107
+ A "chat mode" would switch the harness off for a quick question, so a "hey, how are you?"
108
+ does not load the rules. It was measured on 2026-11-12 and turned down: the harness stays
109
+ loaded in every session.
110
+
111
+ **What was measured.** Each host was installed from npm and pointed at a local endpoint that
112
+ captured the request it sent for one short prompt, in an empty folder, with and without a
113
+ default global install. Sizes are characters of the request; tokens are chars/4.
114
+
115
+ | Host | No harness | Lean (default) | Full | Harness share, lean | Harness share, full |
116
+ |---|---|---|---|---|---|
117
+ | Claude Code 2.1.322 | 45,964 | 89,935 | 118,486 | ~11k tokens | ~18k tokens |
118
+ | OpenClaude 0.32.0 | 86,122 | 128,457 | 157,003 | ~11k tokens | ~18k tokens |
119
+ | OpenCode 1.19.5 | 30,435 | 86,811 | 115,599 | ~14k tokens | ~21k tokens |
120
+ | OpenCode 2.2.7 | 22,654 | 70,506 | 99,054 | ~12k tokens | ~19k tokens |
121
+
122
+ Bob was not measured: IBM does not publish Bob Shell on npm.
123
+
124
+ **Why the saving is small.** The harness share is 5–10% of a 200k window. The host re-sends
125
+ it with every message, but where the provider caches prompts it is billed at the full input
126
+ price once per session and at the cached rate after that. A chat mode would save that one
127
+ payment on sessions that stay small talk, and nothing else.
128
+
129
+ **Why it cannot be a command inside the chat.** The harness is in the context before the
130
+ first message, and no host can take text back out of a running conversation. A slash command
131
+ can only tell the model to ignore the rules, which saves no tokens. Switching on a resumed
132
+ conversation was measured too (harness on, resumed without it, resumed with it again):
133
+
134
+ | Host | Resumed without the harness | Resumed with it again |
135
+ |---|---|---|
136
+ | OpenClaude | sheds it (86,390) | back to normal (128,963) |
137
+ | OpenCode 1 | sheds it (30,606) | back to normal (87,250) |
138
+ | Claude Code | keeps it in the history (91,213) | loads it a second time (126,697) |
139
+ | OpenCode 2 | keeps it in the system prompt (68,273) | loads it a second time (118,720) |
140
+
141
+ On Claude Code and OpenCode 2 a toggle therefore costs more than it saves. A plain resume,
142
+ with the same configuration, adds only the new message on all four hosts.
143
+
144
+ **Why not a ready-made excluded folder.** An [excluded folder](concepts/exclusions.md) is for a
145
+ repo that brings its own setup, not for saving tokens. On Claude Code and OpenClaude it
146
+ removes the instructions file but leaves the skill and agent listings (about 3k tokens). On
147
+ OpenCode the request was byte-identical with and without the exclusion.
148
+
149
+ **If you want a session without the harness anyway**, each host has its own launch switch.
150
+ These are the hosts' options, not Geneseed's: they were checked on the versions above, in
151
+ non-interactive mode with an API key, and a host update can change them.
152
+
153
+ | Host | Launch line | Measured |
154
+ |---|---|---|
155
+ | Claude Code | `claude --setting-sources project,local` | 45,963 — the no-harness size |
156
+ | OpenClaude | `openclaude --setting-sources project,local` | 86,124 — the no-harness size |
157
+ | OpenCode 1 | `XDG_CONFIG_HOME=<empty dir> opencode` | 30,435 — the no-harness size |
158
+ | OpenCode 2 | `OPENCODE_CONFIG_DIR=<empty dir> opencode --standalone` | 22,654 — the no-harness size |
159
+
160
+ Such a session has no rules and no gates, and on Claude Code and OpenCode 2 they cannot be
161
+ added back to the same conversation cleanly. `XDG_CONFIG_HOME` is inherited by every program
162
+ the session starts, so git and other tools lose their own configuration too. On OpenCode 1,
163
+ `OPENCODE_CONFIG_DIR` changes nothing. Whether a subscription login survives
164
+ `--setting-sources` on Claude Code was not checked.
165
+
166
+ The decision is recorded in [Considered and refused](design-history.md#considered-and-refused).
167
+
104
168
  ## Why your session may show more
105
169
 
106
170
  The always-on figures above are the *harness's* share. A real session's
@@ -17,5 +17,5 @@ How Geneseed treats each host it installs into. Part of [Why Geneseed works this
17
17
  - **OpenCode gets a one-line managed `AGENTS.md` when that file is missing.** OpenCode falls back to `~/.claude/CLAUDE.md` when `AGENTS.md` is absent, which would load the harness twice beside a Claude install. An existing `AGENTS.md` is left alone. See [Install for OpenCode](../guides/install-opencode.md).
18
18
  - **Per-repo hooks go into the untracked `settings.local.json`.** The hook commands hold paths on your machine, and the team-shared `settings.json` would hand every teammate broken hooks. See [Hook gates](../concepts/hook-gates.md).
19
19
  - **The manifest records which settings file holds the hooks.** Uninstall and the gate stand-down read the manifest's `settings_file` back (`settingsFile` in `js/hosts/hosts.mjs`) rather than assume a path, since the file differs by host and scope (Bob's global one is nested). See [Hook gates](../concepts/hook-gates.md).
20
- - **Copilot was removed in one pass.** It was never verified live, its hook output never reached the model, and it shared no surface with the other hosts. See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) and [Candidate hosts](../candidate-hosts.md).
20
+ - **Copilot was removed in one pass.** Nobody had ever run it against a real Copilot, its hook output never reached the model, and it shared no surface with the other hosts. See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) and [Candidate hosts](../candidate-hosts.md).
21
21
  - **What belongs to the host stays with the host.** Compaction, sandboxing and the plugin runtime are each host's own territory; Geneseed configures them where a host allows and builds no replacement. See [Hosts](../concepts/hosts.md).
@@ -19,3 +19,4 @@ How the generated harness is assembled, ranked and sized. Part of [Why Geneseed
19
19
  - **Marker lines (`Excluded rules:`, `Excluded skills:`) are written only when non-empty.** A default build then stays byte-identical to one from before the option existed. See [DESIGN.md](../../DESIGN.md) and [Exclusions](../concepts/exclusions.md).
20
20
  - **Session files are injected at start unless still identical to their seed, and the root file is never injected a second time.** The host already loads the root file itself; injecting it again paid for the whole harness twice per session. See [Token footprint](../token-footprint.md).
21
21
  - **The context hook keeps its whole output under `OUTPUT_BUDGET`, counting each line's Windows line ending.** Claude Code moves a longer hook output to a file and shows the model a short preview, so everything past the cut is lost without a warning. Splitting the hook into two commands was measured and turned down (see [Considered and refused](../design-history.md#considered-and-refused)). See [Token footprint](../token-footprint.md).
22
+ - **The harness loads in every session; there is no chat mode.** It adds about 11–14k tokens at lean, billed in full once per session where the provider caches prompts, and no host can unload it inside a conversation. A mode that switches it off was measured and turned down (see [Considered and refused](../design-history.md#considered-and-refused)). See [Token footprint](../token-footprint.md#why-there-is-no-chat-mode).
@@ -33,7 +33,7 @@ On Claude Code and OpenClaude the hooks never block silently. They make the host
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
 
36
- **Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for the rules that admit no judgement call: credentials, destructive git, a scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and memory checks become a log line, and the call goes through. The ownership gate also refuses with exit 2, but once: the same write passes after you answer. Bob's hook wiring follows its documentation but has not been tested on a live Bob install.
36
+ **Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for the rules whose Bob cell says *block* in [Rule enforcement, by host](../concepts/enforcement-table.md). The commit/push check becomes a log line, and the call goes through. The ownership gate also refuses with exit 2, but once: the same write passes after you answer. For what was checked against Bob itself, see [What is verified](../concepts/host-matrix.md#what-is-verified).
37
37
 
38
38
  <!--/harness-->
39
39
  <!--harness:opencode-->
@@ -8,7 +8,7 @@ description: "Where an install lands on IBM Bob or as a plain AGENT.md bundle, a
8
8
  ---
9
9
  Bob and the plain bundle carry the same rules, agents and skills as the other hosts. What differs is where they land and how much of it is enforced. The **Kind** words are explained in [What lands on your machine](on-your-machine.md).
10
10
 
11
- **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for the checks that admit no judgement call: credentials, destructive git, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and memory questions become log lines. One more refusal happens only once: in an application repo whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused so the agent proposes the [ownership](../concepts/ownership.md) setup, and the same write passes after you answer. Turn it off per repo with `mode: off` in that section, for yourself in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, or per install with `--no-ownership-gate`.
11
+ **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Geneseed wires four: context at session start, one combined gate before each tool call, the Activity record on each prompt, and learn at the end of a turn (wired, but Bob sends it no transcript, so only the change report runs). Bob has no "ask" prompt, so the gate refuses outright, and only for the rules whose Bob cell says *block* in [Rule enforcement, by host](../concepts/enforcement-table.md). The commit/push question becomes a log line. One more refusal happens only once: in an application repo whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused so the agent proposes the [ownership](../concepts/ownership.md) setup, and the same write passes after you answer. Turn it off per repo with `mode: off` in that section, for yourself in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, or per install with `--no-ownership-gate`.
12
12
 
13
13
  **Shared by every host.** A global Bob install reads and writes the same machine-wide folder as the other hosts, `~/.config/geneseed/`: your rules, profile, memory, wiki manifest, exclude paths and notes. See [The shared tier](../concepts/shared-tier.md).
14
14
 
package/docs/web-ui.md CHANGED
@@ -191,6 +191,11 @@ budget, measured without project context, for the install whose content was cut,
191
191
  largest. It turns amber at 85% of the budget or whenever content was cut, and Needs you adds one
192
192
  suggestion at the same point.
193
193
 
194
+ A row's details draw the skill list against its own ceiling (`SKILL_LISTING_CEILING`,
195
+ `js/inspect/cost.mjs`) under the cost breakdown, as the row draws the root file against its
196
+ ceiling: a bar, then `part / ceiling · share`, red past 100%. Only a Claude Code install has that
197
+ ceiling, so no other host's details show the bar.
198
+
194
199
  A global **Spotlight** search lives in the topbar — press <kbd>/</kbd> to focus it (or
195
200
  <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>K</kbd>, which also works from inside a text field), type
196
201
  to jump to any agent, skill, doc, MCP server, or constitutional rule — the `laws`
@@ -359,7 +364,7 @@ screen the run list stacks above the detail.
359
364
  grey block, a fork amber, a `loop:` stage a teal box that names its loop (without `loop:`)
360
365
  over `whole loop`, or `not in catalogue` when this install lacks it; the ring itself is on the
361
366
  Loops page. A fork is what the engine calls one: a brick that declares a named outcome
362
- (one outside `pass`, `fail`, `error`, `none` and `needs-info`), never a `loop:` stage, however
367
+ (one outside `pass`, `fail`, `error`, `none`, `needs-info` and `reject`), never a `loop:` stage, however
363
368
  many stages its edges reach. The targets of a fork share a row, side by side, each lane labelled with its outcome,
364
369
  and join again at the first stage every lane reaches. Each route back (an edge into a cycle's
365
370
  first stage, the edge that spends a lap, `$lane` included) is a rail on the left labelled
@@ -376,13 +381,26 @@ screen the run list stacks above the detail.
376
381
  factory's rules. It reads `GET /api/factories/catalog` for the install the *Install:* picker
377
382
  names. **Active** is every run `geneseed factory init` registered on this machine
378
383
  (`GET /api/factories/active`, polled every 5 s, the graph read from each run's `FACTORY.md`),
379
- grouped as Loops › Active is; the reader shows the run's stage, transitions, task number, its
384
+ shown as a **board** while no run is selected: three columns of cards, **Waits for you** (a
385
+ held gate, or a `FACTORY.md` that cannot be read), **Running**, and **Ended** (stopped, closed,
386
+ or its `FACTORY.md` gone). A card gives the run's title, its factory, and one line of facts: where it
387
+ stands (a held gate as `stage · outcome`), its task as `i/n`, its work time so far, the wait
388
+ still open at its gate (`waiting 25 min`), and each cycle spent above 0 as `name n/max`. A
389
+ run with no state says why instead. The list beside it groups the runs under the same three
390
+ names, each row with the same facts under its factory, and while a run is open the list's
391
+ header names it by its title. A card opens the run: the reader
392
+ shows the run's stage, transitions, task number, its
380
393
  child loop's step and iteration, what it awaits, and its graph with the current stage lit,
381
394
  the lane its last fork took (the run's `lane`, else read from its `history`) lit, the child
382
395
  loop's node named under the current stage (`at <node>`) and each cycle's laps as `n / max`. A
383
396
  run carries its graph but no bricks or loops: the graph borrows those from the catalogue of the
384
397
  install the Templates tab's picker names, which the run's project may not share, and the reader
385
- says which. No run reports tab: a run's report lives in its own worktree.
398
+ says which. Under the graph, a **timeline** has one row per history entry: the stage, its
399
+ outcome or your answer at a gate, the time it was recorded (UTC), its duration (waiting time on
400
+ an answer) and a rework mark. A held run names its gate's stage, its outcome and the path of
401
+ its note; the console does not read the note. The numbers are the ones `geneseed factory report`
402
+ prints, and a time nobody recorded reads `unknown`. The board changes nothing: you answer a gate
403
+ in the agent's session. No run reports tab: a run's report lives in its own worktree.
386
404
  - **Profile** (`#/profile`) — `PROFILE.md`: who you are and how you like to work, one card
387
405
  per file: the shared one every global install reads, tagged `shared`, and each project
388
406
  install's own. Opens rendered; **Edit** is a whole-file editor. The save carries
@@ -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.2.0"
5
+ "version": "5.3.1"
6
6
  }
package/js/README.md CHANGED
@@ -39,7 +39,7 @@ layers. These pairs import each other (relative imports between folders, measure
39
39
  | build ↔ hosts | 24 / 5 | hosts reads `build/source.mjs` (`installs`, `link`, `native`, `opencode`) and `build/version.mjs` (`opencode`) |
40
40
  | build ↔ inspect | 2 / 23 | `build/driver.mjs` records deploy roots in `inspect/registry.mjs`; `build/catalog.mjs` reads `inspect/inventory.mjs` |
41
41
  | build ↔ loop | 4 / 1 | `loop/catalog.mjs` reads `build/source.mjs` |
42
- | build ↔ ui | 2 / 1 | `ui/cli.mjs` reads `ROOT` from `build/source.mjs` |
42
+ | build ↔ ui | 2 / 2 | `ui/cli.mjs` reads `ROOT` from `build/source.mjs` and the generator's choice lists from `build/args.mjs` |
43
43
  | build ↔ web | 1 / 9 | `build/generate.mjs` lazily imports `web/daemon.mjs` to restart a stale console after `rebuild-all` |
44
44
  | hosts ↔ inspect | 1 / 36 | `hosts/installs.mjs` reads `inspect/registry.mjs`'s deploy roots |
45
45
  | ui ↔ web | 1 / 1 | `ui/menu.mjs` starts the daemon; `web/docs.mjs` renders `ui/cli.mjs`'s CLI reference |
@@ -103,6 +103,7 @@ user co-owns, and the hook verbs those emitted configs then run.
103
103
  | `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 |
104
104
  | `store-watch.mjs` | The change report: a session's baseline of the rule and memory files (`writeBaseline`, from the hook entry after `context`), the compare at Stop (`storeReport`, from `learn`), and `recordOwnWrites`, around Geneseed's own writers. It detects; it prevents nothing. The OpenCode guard holds the twin |
105
105
  | `activity.mjs` | The hook-side activity writer and the owner of snapshot liveness: `recordActivity` (one payload into `<root>/activity/`), `readTranscriptDelta`, `sweepActivity` (archive, newest 50, 7 days). Loaded only when tracking is on; never prints |
106
+ | `hook-tap.mjs` | The opt-in tap: with `GENESEED_HOOK_TAP=<dir>` set, one file per hook call recording the payload's SHAPE (keys kept, every string replaced by its type and length), for fixtures from a host the canary cannot run. Refuses a directory inside a git worktree. Imported only when the variable is set; never prints, never throws |
106
107
  | `usage.mjs` | The usage counter `tool-gate` runs: one `{day, kind, name}` line per Skill or subagent call into `notebook/usage.jsonl`. Hook path: builtins only, silent, never throws |
107
108
  | `memory-files.mjs` | The memory store's file format — `frontmatter`, `MEMORY.md` index writes, agent lessons, consolidate — the `user-rules.md` parser, the draft's format and the fold's ledger reader. No spawn: the CLI, web console and fold import it |
108
109
  | `geneseed-dir.mjs` | The Node writers into a project's `<git root>/.geneseed/`: the personal-by-default `.gitignore` (`GENESEED_GITIGNORE`, pinned to the two OpenCode copies), and the protected-checks seed every project emit runs (`seedProtectedChecks`: seed once when absent, then the user's — never recorded, rewritten or uninstalled). Never throws, never writes through a link. Spawn-free |
@@ -141,7 +142,7 @@ Everything that inspects an already-built or already-deployed harness and report
141
142
  | `validate.mjs` | The `validate` verb (the generator's old `--validate-only`): renders a sandbox, scans it for tokens and dead links, own exit contract |
142
143
  | `inventory.mjs` | The one catalog walk and its taxonomy tables, read by status, the TUI and the web console |
143
144
  | `status.mjs` | `geneseed status` and `version` — the panel data, counts, accent colour, version verdict |
144
- | `cost.mjs` | What one install injects every session, by part (root file, skill and agent lists, session files), in characters; owns `CARRIER_CEILING`, which the smoke test gates and the console draws |
145
+ | `cost.mjs` | What one install injects every session, by part (root file, skill and agent lists, session files), in characters; owns `CARRIER_CEILING`, which the smoke test gates and the console draws, and `SKILL_LISTING_CEILING`, which the smoke test gates and the console draws on a Claude Code install |
145
146
  | `diff.mjs` | `geneseed diff` — what a deployed install has that a fresh render of `src/` does not |
146
147
  | `excludes.mjs` | `geneseed exclude add|remove|list` — the WRITER for `excludes.json` and the shared list in the machine tier; `hosts.mjs` `sovereignBypass` reads both |
147
148
  | `registry.mjs` | `installs.json` under XDG — the persistent deploy-root list `rebuild-all` re-emits into |
@@ -172,7 +173,7 @@ into files users have committed, so change the test that states it in the same c
172
173
  | `prompt.mjs` | The line-mode stdin readers — `ask`, `promptLine`, `confirm`, `askChoice` — read a byte at a time so they stop where Enter stops. Shared by `setup`, `uninstall` and `web` without dragging in the wizard |
173
174
  | `managed-block.mjs` | Where the `<!-- BEGIN/END GENESEED -->` block is in a co-owned file: whole-line markers, the first END with the last BEGIN above it. One definition for the writer (`settings.mjs`) and the hook-side readers; no imports, so the hook path may load it. The OpenCode plugins carry `BLOCK_RE_SOURCE` by value |
174
175
  | `machine-dir.mjs` | `machineDir()`, `sharedPaths()`, `readDefaultInstall()` and `WIKI_NAMES`: the one home of `$XDG_CONFIG_HOME/geneseed`, the names beneath it, the reader of the chosen default install, and the wiki manifest's names. Spawn-free, so the hook and driver may import it |
175
- | `node-floor.mjs` | The first import of all three binaries: below Node 22.7, one sentence on stderr and exit 1 (0 in the hook) instead of a stack trace |
176
+ | `node-floor.mjs` | The first import of all three binaries: below Node 22.7, one sentence on stderr and exit 1 (0 in the hook, where a gate verb also asks) instead of a stack trace |
176
177
 
177
178
  **Before editing:** parse with `parseJson`, never `JSON.parse` — the latter collapses int `1` and
178
179
  float `1.0` into one double, and that value gets written into a user's file. Do not swap in a diff
@@ -217,8 +218,9 @@ brick or a whole loop; a fork's named outcomes pick its lane), persisted as a JS
217
218
  |---|---|
218
219
  | `graph.mjs` | `checkFactory` — the rules a factory must satisfy before a stage runs: stages exist, edges cover every outcome, `$close` is reachable, every cycle is declared (the loop engine's `undeclaredCycles`), `$lane` only behind a fork, `protected` a list of paths, and every `review.seats` entry a shipped agent. Also the fork helpers the engine shares: `isFork`, `lanesOf`, `laneTargets`, `spentCycle` |
219
220
  | `state.mjs` | The engine itself: `initFactory`, `nextStage`, `recordStage`, `decideFactory`, `renderFactoryFile`/`parseFactoryFile`, `validateFactoryState`, `countSpecTasks` |
220
- | `cli.mjs` | `geneseed factory check\|list\|init\|next\|record\|decide` — the only face of this engine |
221
- | `registry.mjs` | `factories.json` beside `loops.json`: `recordFactory` (called by `factory init`) and `activeFactories`, on the loop registry's own `loadRows`/`saveRows`/`sweepRows`. A run and its child loop share a root, which is how a reader groups them |
221
+ | `metrics.mjs` | `runMetrics(state, { now })` — pure: per stage its runs, reworks, work time and tokens, and per run its work time, waiting time, the wait still open at a held gate (to `now`, which the caller reads), tokens and transitions, from the history's `at` stamps. Unknown is `null`, never 0. The one writer of those numbers: `factory report` prints it, and the console reads it through `registry.mjs` |
222
+ | `cli.mjs` | `geneseed factory check\|list\|init\|next\|record\|decide\|report` — the only face of this engine. It reads the clock; the engine stays pure |
223
+ | `registry.mjs` | `factories.json` beside `loops.json`: `recordFactory` (called by `factory init`, and the one place the registry is swept and pruned), `listFactories` (the console's read-only rows, each live row with its `metrics`), on the loop registry's own `loadRows`/`saveRows`/`sweepRows`. A run and its child loop share a root, which is how a reader groups them |
222
224
 
223
225
  **Before editing:** `FACTORY.md` is in `js/loop/state.mjs`'s `ENGINE_FILES`, so a child loop never
224
226
  scores it; the clean-tree check after a stage outside a loop filters with that same list. `cli.mjs`
package/js/build/args.mjs CHANGED
@@ -19,7 +19,7 @@ import {
19
19
  import { DEFAULT_PRESET, PRESETS } from '../loop/score.mjs';
20
20
 
21
21
  /** The nine `--emit` choices: a plain bundle, then a project and a global emit per host. */
22
- const EMITS = ['files', 'opencode', 'opencode-global', 'claude', 'claude-global',
22
+ export const EMITS = ['files', 'opencode', 'opencode-global', 'claude', 'claude-global',
23
23
  'bob', 'bob-global', 'openclaude', 'openclaude-global'];
24
24
 
25
25
  /**
@@ -99,14 +99,14 @@ export function configDefaults(config = CONFIG, rules = ruleCanon(SRC).rules) {
99
99
  * own private copy of the flags is a second source that drifts silently the first time a
100
100
  * flag is added to one and not the other, and nothing downstream would say so.
101
101
  */
102
- const VALUED = {
102
+ export const VALUED = {
103
103
  '--theme': 'theme', '--posture': 'posture', '--mode': 'mode', '--trust': 'trust',
104
104
  '--doctrines': 'doctrines', '--exclude-rules': 'excludeRules', '--exclude-skills': 'excludeSkills',
105
105
  '--kits': 'kits', '--shared-tier': 'sharedTier',
106
106
  '--out': 'out', '--target': 'out', '--emit': 'emit',
107
107
  '--footprint': 'footprint', '--root': 'root', '--config-dir': 'cfgDir',
108
108
  };
109
- const FLAGS = {
109
+ export const FLAGS = {
110
110
  '--sync-themes': 'syncThemes', '--validate-only': 'validateOnly',
111
111
  // The gate switches (`GATE_SWITCHES`, law order). No `harness.config.json` key feeds them,
112
112
  // deliberately: a rebuild elides a flag when armed, so a config default could disarm an armed
@@ -155,7 +155,7 @@ const FLAG_BY_NAME = Object.fromEntries(
155
155
  * advertised a metavar that lies. It is validated by `parseDoctrines` instead and prints the
156
156
  * plain `DOCTRINES` metavar, exactly as `--theme` (also open-ended) already does.
157
157
  */
158
- function choicesFor() {
158
+ export function choicesFor() {
159
159
  return {
160
160
  '--emit': EMITS,
161
161
  '--footprint': ['lean', 'full'],
@@ -576,7 +576,7 @@ const CLAUDE_SHAPED = {
576
576
  summary: (at, r) => `[geneseed] bob-global -> ${at}: ${r.nAgents} subagents, `
577
577
  + `${r.nSkills} skills, rules/geneseed.md (Bob's always-injected channel; a global `
578
578
  + 'AGENTS.md is not auto-loaded, so none is written), '
579
- + `${r.nHooks} hook group(s), settings.json, ${r.memStatus}, ${r.nbStatus}.\n`,
579
+ + `${r.nHooks} hook group(s), settings/settings.json, ${r.memStatus}, ${r.nbStatus}.\n`,
580
580
  },
581
581
  // Per-repo: AGENTS.md at the root + a `.bob/` layer.
582
582
  bob: {
@@ -283,7 +283,7 @@ function claudeWire(job, claudeMdText, hasAgentText, doctrines = null, excludeRu
283
283
  // recorded claims there, or they linger (and run) forever.
284
284
  const oldSf = get(old, 'settings_file') || 'settings.json';
285
285
  if (oldSf !== settingsName) {
286
- unwireClaudeSettings(path.join(cfgDir, oldSf), get(old, 'settings_hooks') || []);
286
+ unwireClaudeSettings(path.join(cfgDir, oldSf), get(old, 'settings_hooks') || [], cfgDir);
287
287
  unwireClaudeExcludes(path.join(cfgDir, oldSf), get(old, 'settings_excludes') || []);
288
288
  unwireClaudeEnv(path.join(cfgDir, oldSf), get(old, 'settings_env'));
289
289
  }
@@ -37,7 +37,7 @@ import { GATE_SWITCHES, makeCfg, PACK_ORDER } from './source.mjs';
37
37
  import { DEFAULT_PRESET } from '../loop/score.mjs';
38
38
  import { opencodeConfigDir, resolvePath } from '../hosts/hosts.mjs';
39
39
  import {
40
- EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
40
+ EMIT_FOR, EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
41
41
  excludedRulesOfDir, excludedSkillsOfDir, footprintOfDir, kitsOfDir, sharedTierOfDir, gatesOfDir, installState, installTargets,
42
42
  modeOfDir, postureOfDir, readMaybe, themeOfDir, trustOfDir,
43
43
  } from '../hosts/installs.mjs';
@@ -185,18 +185,9 @@ export function setupBuildArgs(theme, emit, out = null, root = null, footprint =
185
185
  return argv;
186
186
  }
187
187
 
188
- /**
189
- * `_harness_build._DEFAULT_EMIT` — the emit to use for an install carrying NO marker.
190
- *
191
- * A pre-marker install still has a (host, scope), which is what the walk found it by, so it
192
- * is rebuilt in its own mode rather than defaulted to OpenCode.
193
- */
194
- const DEFAULT_EMIT = new Map([
195
- ['opencode global', 'opencode-global'], ['opencode project', 'opencode'],
196
- ['claude global', 'claude-global'], ['claude project', 'claude'],
197
- ['bob global', 'bob-global'], ['bob project', 'bob'],
198
- ['openclaude global', 'openclaude-global'], ['openclaude project', 'openclaude'],
199
- ]);
188
+ // The emit for an install carrying NO marker is `EMIT_FOR` (`js/hosts/installs.mjs`): a
189
+ // pre-marker install still has a (host, scope), which is what the walk found it by, so it is
190
+ // rebuilt in its own mode rather than defaulted to OpenCode.
200
191
 
201
192
  /**
202
193
  * Everything `rebuild-all` reads back off one install, and the argv that re-emits it unchanged.
@@ -216,7 +207,7 @@ export function installProfile(host, scope, root, notify = null) {
216
207
  const raw = readMaybe(path.join(root, '.geneseed-emit'));
217
208
  let marker = raw === null ? '' : raw.trim();
218
209
  if (marker && (EMIT_HOST_SCOPE.get(marker) ?? ['', ''])[0] !== host) marker = '';
219
- const emit = marker || DEFAULT_EMIT.get(`${host} ${scope}`) || 'opencode-global';
210
+ const emit = marker || EMIT_FOR.get(`${host} ${scope}`) || 'opencode-global';
220
211
  // Every read-back below is narrowed to `host`'s OWN carrier (host-compat B1): in a repo
221
212
  // shared with another Claude-style host, an un-narrowed scan answers with WHICHEVER host's
222
213
  // carrier the shared `CARRIERS` order favours — the wrong carrier for every host but one.
@@ -35,7 +35,7 @@ import { parseJson } from '../lib/json.mjs';
35
35
  import { normcase, comparePaths } from '../lib/paths.mjs';
36
36
  // `js/build/source.mjs` imports nothing but node builtins, so this direction cannot cycle.
37
37
  import {
38
- CREDIT_RE, GATE_SWITCHES, PACK_ORDER, kitMembers, loadKits, readPackText, resolveCredits, resolveRuleIds, ruleCanon, upstreamOf,
38
+ CREDIT_RE, GATE_SWITCHES, PACK_ORDER, kitMembers, loadKits, readPackText, resolveCredits, resolveRuleIds, ruleCanon, titleKey, upstreamOf,
39
39
  } from './source.mjs';
40
40
  import { SHARED_TIER_LINE } from '../hosts/hosts.mjs';
41
41
  import { VENDORED_SKILL_DIRS } from '../hosts/native.mjs';
@@ -296,14 +296,41 @@ export function splitAtLawHeadings(text) {
296
296
  return out;
297
297
  }
298
298
 
299
- /** The pointer under §1 at lean. The laws' lean text itself is authored in LEAN blocks. */
300
- export function lawsPointer(theme, lawsPrefix = '') {
299
+ /**
300
+ * The one pointer at lean, closing §2 for both tiers: the laws' and the rules' lean text is
301
+ * authored in LEAN blocks, and this names where the complete text of each lives. It was two notes,
302
+ * one under each section, saying the same thing (owner decision D2, 2026-11-11).
303
+ */
304
+ export function briefPointer(theme, lawsPrefix = '', anyPack = true) {
301
305
  const law = theme.LAW ?? 'Law';
306
+ const doctrine = theme.DOCTRINE ?? 'Doctrine';
302
307
  const lawsDir = theme.DIR_LAWS ?? 'laws';
303
- return `> Each ${law} above is given in brief — the rule, not its reasoning. The `
304
- + `complete, binding text of every ${law} is in \`${lawsPrefix}${lawsDir}/universal.md\`; `
305
- + `read it whenever a ${law}'s application is unclear, and before any act touching `
306
- + 'secrets, deletion, git history, scope, or untrusted content.';
308
+ const dir = theme.DIR_DOCTRINES ?? 'doctrines';
309
+ // With no pack active only the laws are above; the packs' folder is still named, as it ships.
310
+ const above = anyPack ? `${law} and ${doctrine}` : law;
311
+ return `> Each ${above} above is given in brief — the rule, not its reasoning. `
312
+ + `The complete text is in \`${lawsPrefix}${lawsDir}/universal.md\` (binding) and in `
313
+ + `\`${lawsPrefix}${dir}/\` (every pack, active or not). Read the matching file whenever a rule's application `
314
+ + `is unclear; read \`${lawsPrefix}${lawsDir}/universal.md\` before any act touching secrets, `
315
+ + 'deletion, git history, scope, or untrusted content.';
316
+ }
317
+
318
+ /**
319
+ * LEAN DROPS THE VOICE'S HALF of each rule title and the italic epigraph under each § heading
320
+ * (owner decision D2, 2026-11-11). A theme spells a title `Arcana Sigillata · Sealed Secrets`;
321
+ * lean renders the principle alone, the name every citation already renders (`*Sealed
322
+ * Secrets*`), so one rule reads the same at its heading and where it is cited. Done here, on the
323
+ * unsubstituted tokens, so all fourteen voices follow without a theme edit. Keyed on the PER-FILE
324
+ * footprint: the on-disk `laws/`, `ontology/` and `doctrines/` render full even in a lean install,
325
+ * keep the voice, and are what `js/inspect/inventory.mjs` and the console parse.
326
+ */
327
+ const TITLE_TOKEN_RE = /\{\{((?:LEX|DOC)_[A-Z0-9_]+)\}\}/g;
328
+ const EPIGRAPH_LINE_RE = /^\*\{\{EPI_[A-Z_]+\}\}\*\n\n/gm;
329
+ function leanVoice(text, src) {
330
+ text = text.replace(EPIGRAPH_LINE_RE, '');
331
+ if (!text.includes('{{LEX_') && !text.includes('{{DOC_')) return text;
332
+ const names = new Map(ruleCanon(src).rules.map((r) => [titleKey(r.kind, r.id), r.name]));
333
+ return text.replace(TITLE_TOKEN_RE, (whole, key) => names.get(key) ?? whole);
307
334
  }
308
335
 
309
336
  /**
@@ -392,17 +419,14 @@ export function renderFile(cfg, filePath, theme, footprint = 'full', lawsPrefix
392
419
  if (normcase(target) === normcase(here) || visiting.has(normcase(target))) {
393
420
  return `<!-- CIRCULAR INCLUDE: ${rel} -->`;
394
421
  }
395
- let inner = renderFile(cfg, target, theme, footprint, lawsPrefix,
396
- new Set(visiting).add(normcase(here)), nativeCatalog)
422
+ return renderFile(cfg, target, theme, footprint, lawsPrefix,
423
+ new Set(visiting).add(normcase(here)), nativeCatalog)
397
424
  .replace(/\n+$/, ''); // `.rstrip("\n")`
398
- if (footprint === 'lean' && rel === 'laws/universal.md') {
399
- inner = `${inner}\n\n${lawsPointer(theme, lawsPrefix)}`;
400
- }
401
- return inner;
402
425
  });
403
426
 
404
427
  text = resolveCatalogs(text, nativeCatalog, cfg.excludeSkills ?? [], cfg);
405
428
  text = resolveLean(text, footprint);
429
+ if (footprint === 'lean') text = leanVoice(text, cfg.src);
406
430
  return substitute(text, theme);
407
431
  }
408
432
 
@@ -503,7 +527,8 @@ function dropExcludedRules(text, pack, excluded) {
503
527
  }
504
528
 
505
529
  function doctrinesBody(cfg, theme, active, footprint, lawsPrefix) {
506
- if (!active.length) return '';
530
+ // At lean the section still carries the one pointer with no pack active: it names the laws too.
531
+ if (!active.length) return footprint === 'lean' ? briefPointer(theme, lawsPrefix, false) : '';
507
532
  const excluded = new Set(cfg.excludeRules ?? []);
508
533
  const parts = active.map((name) => {
509
534
  const raw = dropExcludedRules(readPackText(path.join(cfg.src, 'doctrines', `${name}.md`)),
@@ -512,15 +537,10 @@ function doctrinesBody(cfg, theme, active, footprint, lawsPrefix) {
512
537
  // voice second. THE ORDER IS LOAD-BEARING — `resolveLean` reads HTML markers, and
513
538
  // substituting first would hand it prose in fourteen voices. The first-sentence cut is gone;
514
539
  // a rule's lean text is written in `src/doctrines/<pack>.md`, not measured out of its prose.
515
- return substitute(resolveLean(raw, footprint), theme).trim();
540
+ const text = resolveLean(raw, footprint);
541
+ return substitute(footprint === 'lean' ? leanVoice(text, cfg.src) : text, theme).trim();
516
542
  });
517
- if (footprint === 'lean') {
518
- const doctrine = theme.DOCTRINE ?? 'Doctrine';
519
- const dir = theme.DIR_DOCTRINES ?? 'doctrines';
520
- parts.push(`> Each ${doctrine} above is given in brief — the rule, not its reasoning. `
521
- + `The complete text of every pack, active or not, is in \`${lawsPrefix}${dir}/\`; read `
522
- + `the pack file whenever a ${doctrine}'s application is unclear.`);
523
- }
543
+ if (footprint === 'lean') parts.push(briefPointer(theme, lawsPrefix));
524
544
  return parts.join('\n\n');
525
545
  }
526
546
 
@@ -667,8 +687,8 @@ export function renderAll(cfg, themeName, {
667
687
  if (NOT_BUNDLED.has(sp[0])) continue;
668
688
  if (sp.length >= 2 && Object.hasOwn(off, sp[0]) && off[sp[0]].has(sp[1].replace(/\.md$/, ''))) continue;
669
689
  const outRel = destRel(themedRel(rel, theme)).split(path.sep).join('/'); // as_posix()
670
- // The on-disk `laws/`, `ontology/` and `doctrines/` are the "complete text" the two lean
671
- // pointers promise — §1's and the Doctrines section's. They render at full whatever the
690
+ // The on-disk `laws/`, `ontology/` and `doctrines/` are the "complete text" the lean
691
+ // pointer under the Doctrines section promises. They render at full whatever the
672
692
  // footprint; only what AGENT.md INLINES leans. `doctrines/` joined them when its rules got
673
693
  // authored LEAN blocks: before that a pack file carried no markers and shipped whole by
674
694
  // accident, which is a different thing from shipping whole by contract.