geneseed 6.0.3 → 6.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/DESIGN.md +1 -1
  3. package/SHIPPED.md +1 -1
  4. package/adapters/opencode/plugins/geneseed-context.js +0 -42
  5. package/adapters/opencode/plugins/geneseed-learn.js +13 -4
  6. package/bin/geneseed-hook.mjs +5 -0
  7. package/docs/concepts/hooks.md +6 -6
  8. package/docs/guides/install-scripted.md +1 -1
  9. package/docs/reference/env-context.md +2 -1
  10. package/docs/reference/plugin-activity.md +1 -1
  11. package/docs/reference/profiles.md +1 -0
  12. package/docs/understand/a-day.md +1 -1
  13. package/docs/understand/machine-claude.md +1 -1
  14. package/docs/web-ui.md +2 -2
  15. package/harness.config.json +1 -1
  16. package/js/build/args.mjs +4 -3
  17. package/js/build/driver.mjs +8 -8
  18. package/js/build/emit-claude.mjs +59 -4
  19. package/js/build/generate.mjs +11 -2
  20. package/js/build/profile.mjs +10 -5
  21. package/js/build/render.mjs +3 -1
  22. package/js/build/source.mjs +12 -1
  23. package/js/cli-table.json +37 -0
  24. package/js/hosts/hooks-context.mjs +1 -56
  25. package/js/hosts/hooks-learn.mjs +435 -55
  26. package/js/hosts/installs.mjs +22 -2
  27. package/js/hosts/memory-files.mjs +89 -6
  28. package/js/hosts/native.mjs +23 -1
  29. package/js/hosts/settings.mjs +77 -4
  30. package/js/inspect/diff.mjs +3 -1
  31. package/js/inspect/doctor.mjs +37 -3
  32. package/js/inspect/status.mjs +38 -5
  33. package/js/inspect/validate.mjs +1 -1
  34. package/js/lib/proc.mjs +36 -0
  35. package/js/maintain/profiles.mjs +15 -4
  36. package/js/maintain/setup.mjs +31 -7
  37. package/js/maintain/update.mjs +1 -1
  38. package/js/web/actions.mjs +5 -3
  39. package/js/web/api.mjs +2 -2
  40. package/js/web/profiles-api.mjs +2 -2
  41. package/js/web/state.mjs +13 -2
  42. package/package.json +1 -1
  43. package/src/AGENT.md.tmpl +1 -1
  44. package/src/agents/memory-curator.md +3 -0
  45. package/src/doctrines/process.md +2 -2
  46. package/src/memory/README.md +24 -4
  47. package/src/skills/rule.md +9 -5
  48. package/web/dist/assets/{Activity-IAxWF2wK.js → Activity-BsMFA5Aa.js} +1 -1
  49. package/web/dist/assets/{ActivityDetail-CtC2DLvh.js → ActivityDetail-C66n3oul.js} +1 -1
  50. package/web/dist/assets/{Bonsai-BoKo68Kw.js → Bonsai-BCd-qt7W.js} +1 -1
  51. package/web/dist/assets/{CopyButton-C0VTiqmb.js → CopyButton-Dpl0PFja.js} +1 -1
  52. package/web/dist/assets/{Dashboard-CRGCp2cV.js → Dashboard-CQxdiv7F.js} +2 -2
  53. package/web/dist/assets/{Docs-DwOwzaD6.js → Docs-D0XlXuiA.js} +1 -1
  54. package/web/dist/assets/{Factories-DxHD2T-1.js → Factories-CPVBoWoA.js} +1 -1
  55. package/web/dist/assets/{GreenhouseView-D5VOmhmR.js → GreenhouseView-C_2auUA8.js} +1 -1
  56. package/web/dist/assets/Installs-CXqjmqms.js +3 -0
  57. package/web/dist/assets/{JournalView-gUSGysTm.js → JournalView-S-igd-Nv.js} +1 -1
  58. package/web/dist/assets/{Kits-DYQvykZ0.js → Kits-K6mu91rm.js} +1 -1
  59. package/web/dist/assets/{Laws-UVk0uojS.js → Laws-j5vKNwLT.js} +1 -1
  60. package/web/dist/assets/{LibRows-CwK63kjB.js → LibRows-1yTY0Kwn.js} +1 -1
  61. package/web/dist/assets/{Library-DdzyrwUK.js → Library-BQZnFdWs.js} +1 -1
  62. package/web/dist/assets/{Loops-yHga7xdr.js → Loops-B5DgxpLm.js} +1 -1
  63. package/web/dist/assets/Models-C-4Y4jvx.js +1 -0
  64. package/web/dist/assets/{OperatorHudView-D1lQF-ZY.js → OperatorHudView-_8NBAvkd.js} +1 -1
  65. package/web/dist/assets/Personal-Bf7zHDc6.js +2 -0
  66. package/web/dist/assets/{Settings-Brgec4M0.js → Settings-BTrA6MXv.js} +1 -1
  67. package/web/dist/assets/{Tabs-BHjxciOL.js → Tabs-BDhZImxa.js} +1 -1
  68. package/web/dist/assets/controls-CREglcUF.js +1 -0
  69. package/web/dist/assets/{index-BfyZCNu7.css → index-9iBqq7i2.css} +1 -1
  70. package/web/dist/assets/{index-BILaKHbH.js → index-BiKWWv7Z.js} +3 -3
  71. package/web/dist/index.html +2 -2
  72. package/web/dist/assets/Installs-B5hFSUeN.js +0 -3
  73. package/web/dist/assets/Models-DAgkQ4CE.js +0 -1
  74. package/web/dist/assets/Personal-DjhIfa9v.js +0 -2
  75. package/web/dist/assets/controls-CK7qHA8H.js +0 -1
package/CHANGELOG.md CHANGED
@@ -8,6 +8,24 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ## [6.0.4] — 2026-11-18
12
+
13
+ ### Added
14
+
15
+ - `--learn off|light|standard|session`: the model memory learning distils with (default `light`). The build records it per install (`Learn model: <value>` in the carrier, written only off the default), `rebuild-all`, `upgrade`, profiles and the setup wizard keep it, `diff` reads it, and `status` shows it in an install's row when it is not `light`. Claude Code and OpenClaude use it (see Changed); the OpenCode plugin does not yet.
16
+
17
+ ### Changed
18
+
19
+ - Rules a tier migration drafted from the memory index no longer load at every session (6.0.3 loaded them until decided). They load only once approved: the 1 800-character bridge slot is gone, on the Claude Code hook and the OpenCode plugin alike. The one-line `[drafts] N drafted items … wait for the user's decision` reminder stays, and an approved draft moves into `user-rules.md`, which loads. The web console's Rules page now labels such a draft "not loaded until approved" instead of "binds on memory".
20
+ - **Memory learning on Claude Code and OpenClaude now follows `--learn` (default `light`: Haiku on Claude Code).** The next rebuild of a Claude or OpenClaude install that has no `GENESEED_LLM` writes `"GENESEED_LLM": "claude -p --model haiku"` into the install's settings `"env"`, so that install starts learning. Opt out with `--learn off` (the next rebuild removes the key). A `GENESEED_LLM` you set yourself, in the settings or the shell, is never overwritten, and `status` shows it as `active (set by you)`. On OpenClaude `light` and `standard` need a model named in the `tiers` map; without one it learns with your default model (`session`).
21
+ - Learning is cheaper and no longer slows a reply: the model runs at each `PreCompact` and at `SessionEnd`, not after every turn (a session with n compactions makes n + 1 calls). `Stop` keeps only its no-model work (spec-feedback copy, done check, change report); a sub-agent's lesson is queued at its stop and distilled in the next run. The run is a detached worker (`geneseed-hook learn-worker`) with a lean `claude -p` (no settings, MCP servers, tools or session file: about 3k tokens instead of 68k), so a closing session never cuts it short. On Windows an npm-installed `claude.cmd` or `openclaude.cmd` is found and run too (through `cmd.exe`, the prompt on stdin); before, `learn` could not start it. `SessionEnd` now runs `learn`, which records the activity view's session end as before. ADR 0002 names the second spawn and the one known limit: on the Windows `.cmd` path the timeout stops the wait (the model's answer and prompt travel through files, so an orphaned child cannot hold the call), but not the child itself, which ends when the CLI does. A custom `.cmd` or `.bat` model command gets its prompt on stdin. The worker has no terminal, so it records each run in `~/.config/geneseed/cache/learn-last.json`; `status` and `doctor` add `· last run failed <date>: <reason>` to the learn line when the last run failed (or `· last run stuck since <date>` when a run never ended; an empty reply and a reply that is prose, not a memory file, count as failures), and a hook that can name no install skips the distil instead of running the model inline.
22
+
23
+ ### Fixed
24
+
25
+ - `status` and `doctor` called memory learning dormant on installs that learn. The `learn` line read only the shell's `$GENESEED_LLM`. It now judges each installed host: OpenCode distils with the session model (active), Bob sends no transcript (n/a), and a Claude Code or OpenClaude hook also counts `GENESEED_LLM` set in the `"env"` of its settings files.
26
+ - The web console's Doctor counted `[note]` lines as problems, so a healthy machine read "1 problem". Notes are now split out as the CLI does and shown as muted lines.
27
+ - The Models page lost a routing flip (`off` ↔ `auto`). Save stayed disabled, the footer said "No unsaved changes", and a reload put the old value back: only *Rebuild…* applied it, and the page did not say so. A flip now counts as an unsaved change, and Save becomes *Save and rebuild…*: it writes any tier or pin edits, then rebuilds the install with the new routing.
28
+
11
29
  ## [6.0.3] — 2026-11-18
12
30
 
13
31
  ### Added
package/DESIGN.md CHANGED
@@ -204,7 +204,7 @@ theme file defines a `DIR_*` key, so `laws/` is `laws/` in all fourteen voices.
204
204
  | Generator | `bin/build-driver.mjs` (`geneseed-build`) | — | substitution + `<!-- INCLUDE: -->` inlining, and the eleven `--emit` targets |
205
205
  | CLI, as data | `js/cli-table.json` | — | the owned document the entry point parses its own argv from |
206
206
  | Automation | `bin/geneseed-cli.mjs` (`geneseed`) | — | 24 verbs — `build` / `doctor` / `status` / `prompt` / `diff` / `setup` / `web` / `upgrade` / … |
207
- | Hooks | `bin/geneseed-hook.mjs` (`geneseed-hook`) | — | the six verbs an emitted hook config invokes: `context` / `git-gate` / `rule-gate` / `tool-gate` / `learn` / `activity` |
207
+ | Hooks | `bin/geneseed-hook.mjs` (`geneseed-hook`) | — | the six verbs an emitted hook config invokes: `context` / `git-gate` / `rule-gate` / `tool-gate` / `learn` / `activity`, plus `learn-worker`, which no settings file wires (`learn` starts it) |
208
208
  | Adapters | `adapters/` | — | optional per-tool glue (hooks, OpenCode plugins) |
209
209
 
210
210
  ## ⚙️ Generator contract
package/SHIPPED.md CHANGED
@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
20
20
  > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
21
21
  > human-readable label only. The canonical identity of an installed harness is the
22
22
  > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
23
- > string. Current label: **6.0.3**.
23
+ > string. Current label: **6.0.4**.
24
24
 
25
25
  ## Capabilities
26
26
 
@@ -343,11 +343,6 @@ async function sessionFiles(dir) {
343
343
  entry(rel, sharedAbs, shared, "shared")
344
344
  }
345
345
  if (host !== null) entry(rel, abs, host, shared === null ? "" : "host: opencode")
346
- // The bridge slot is its own entry right after the rules, as in the hook (BRIDGE_REL there).
347
- if (rel === "user-rules.md" && tier) {
348
- const slot = await bridgeSlot()
349
- if (slot) found.push({ rel: "user-rules.draft.md", abs: path.join(machineDir(), "user-rules.draft.md"), label: "shared", text: slot })
350
- }
351
346
  }
352
347
  return found
353
348
  }
@@ -366,43 +361,6 @@ function memoryNudge(map) {
366
361
  return ""
367
362
  }
368
363
 
369
- // The bridge slot (D31), a hand twin of bridgeSlot in js/hosts/hooks-context.mjs (same constants,
370
- // same text; tests/unit/claude.test.mjs holds the two equal on one store): the facts a migration
371
- // drafted as standing rules keep loading, as an entry of their own after user-rules.md, until their draft is decided.
372
- const BRIDGE_CAP = 1800
373
- const BRIDGE_FACT_MAX = 300
374
- const BRIDGE_HEAD = "[memory] Standing rules from your old index, drafted in user-rules.draft.md and "
375
- + "loaded until you decide them:"
376
- const BRIDGE_SLUG_RE = /^[^/\\.\u0000-\u001f][^/\\\u0000-\u001f]*$/
377
- async function bridgeSlot() {
378
- let items
379
- try { ({ items } = JSON.parse(await fs.readFile(path.join(machineDir(), ".fold-state.json"), "utf8"))) } catch { return "" }
380
- // The hook counts a line as its characters plus a terminator of two (+1 per inner break).
381
- const cost = (s) => s.length + (s.match(/\n/g) || []).length + 2
382
- const lines = []
383
- for (const row of Object.values(items ?? {})) {
384
- if (row?.state !== "pending" || row.host !== "memory" || typeof row.fact !== "string" || !BRIDGE_SLUG_RE.test(row.fact)) continue
385
- let text
386
- try { text = (await fs.readFile(path.join(machineDir(), "memory", `${row.fact}.md`), "utf8")).replace(/\r\n/g, "\n") } catch { continue }
387
- const m = /^\s*---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/.exec(text)
388
- const desc = m ? (m[1].split("\n").map((l) => /^\s*description\s*:(.*)$/.exec(l)).find(Boolean)?.[1] ?? "").trim().replace(/^"+|"+$/g, "") : ""
389
- const rule = ((m ? m[2] : text).trim() || desc).replace(/\s+/g, " ")
390
- lines.push(`- ${row.fact}: ${rule.length > BRIDGE_FACT_MAX ? `${rule.slice(0, BRIDGE_FACT_MAX)}…` : rule}`)
391
- }
392
- if (!lines.length) return ""
393
- const tail = (n) => `- … ${n} more drafted rule${n === 1 ? "" : "s"} not shown (read them in memory/)`
394
- const room = BRIDGE_CAP - cost(BRIDGE_HEAD)
395
- const kept = []
396
- let used = 0
397
- for (const [i, l] of lines.entries()) {
398
- const t = tail(lines.length - i)
399
- if (used + cost(l) + (i < lines.length - 1 ? cost(t) : 0) > room) { kept.push(t); break }
400
- kept.push(l)
401
- used += cost(l)
402
- }
403
- return [BRIDGE_HEAD, ...kept].join("\n")
404
- }
405
-
406
364
  async function readJson(p) {
407
365
  try { return JSON.parse(await fs.readFile(p, "utf8")) } catch { return null }
408
366
  }
@@ -196,24 +196,33 @@ Markdown memory files in this exact format, separated by a line containing only
196
196
 
197
197
  ---
198
198
  name: <kebab-case-slug>
199
- description: <one-line summary>
199
+ description: <one line under 90 characters that states the claim>
200
200
  type: user | feedback | project | reference
201
201
  topic: <kebab-case-slug; reuse a topic from TOPICS IN USE below when one fits>
202
202
  ---
203
- <the fact, stated plainly. For 'feedback' and 'project', add **Why:** and
204
- **How to apply:** lines.>
203
+ <the fact in one or two sentences. For 'feedback' and 'project', add one-line
204
+ **Why:** and **How to apply:** lines.>
205
205
 
206
206
  MERGE BEFORE YOU CREATE. The facts already stored are listed below as
207
207
  'slug — description'. Never create a fact under one of those slugs. Instead:
208
208
  - If your memory refines, extends or corrects a stored fact, add the line
209
209
  'action: update' to its frontmatter and use that fact's own name. Your text
210
210
  REPLACES the stored file, so write the merged fact: keep everything the old
211
- one says that is still true, then add or correct what the notes show.
211
+ one says that is still true, then add or correct what the notes show. Then
212
+ write the merged fact to the same lean bar: drop what is no longer needed.
212
213
  - If the notes show a stored fact is now false or obsolete, output only
213
214
  frontmatter holding its 'name:' and the line 'action: archive'. It is moved
214
215
  out of the index, never deleted.
215
216
  - With no 'action:' line, the memory is a NEW fact under a NEW slug.
216
217
 
218
+ WRITE IT LEAN. Every word is re-read in later sessions.
219
+ - description: state the claim itself, specific enough to tell it from the
220
+ stored facts below; never a bare label.
221
+ - body: the fact in one or two sentences; Why and How to apply, one line each.
222
+ - no narrative, no session history, no PR or ticket numbers, no
223
+ session-specific counts; a date only when the fact depends on it, written
224
+ absolute.
225
+
217
226
  DEFAULT TO 'NOTHING'. Writing a memory is the rare exception, not the norm — most
218
227
  sessions should yield zero. Emit AT MOST ONE, and only if it is a GENERAL, reusable
219
228
  principle you would want at the START of an unrelated future task.
@@ -117,6 +117,11 @@ const VERBS = {
117
117
  },
118
118
  positional: 'file',
119
119
  },
120
+ // The detached distil (ADR 0002's second spawn): `learn` writes a job on PreCompact/SessionEnd and
121
+ // starts `<node> <this file> learn-worker <job>` apart from itself. Wired by no settings.json.
122
+ 'learn-worker': {
123
+ load: () => import('../js/hosts/hooks-learn.mjs'), fn: 'cmdLearnWorker', flags: {}, positional: 'file',
124
+ },
120
125
  // UserPromptSubmit and SessionEnd: no verb runs there, and the activity view needs both.
121
126
  activity: { load: () => import('../js/hosts/hooks-prims.mjs'), fn: 'cmdActivity', flags: HOSTED },
122
127
  };
@@ -20,11 +20,11 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
20
20
  | `PreToolUse` | `Bash`, `PowerShell`, `Monitor` | `geneseed-hook git-gate` | asks before a command that would really lose data, and before a recursive scan of a whole filesystem; asks before every commit and push | the commit/push question only |
21
21
  | `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your standing rules; stops the session's first write once in an application repo with no `## Ownership` section | no |
22
22
  | `PreToolUse` | `Skill`, `Agent`, `Task` | `geneseed-hook tool-gate` | records the skill or subagent call in the usage count; judges nothing and never blocks | no |
23
- | `Stop` | the agent finishes a reply | `geneseed-hook learn` | copies the reply's `spec-feedback: [skill:<name>]` lines into `skill-notes/<name>.md` (no model); distils durable facts into the memory store | the copy needs nothing; the distil needs `GENESEED_LLM` |
24
- | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | copies the `spec-feedback:` lines of its report into `agent-notes/<name>.md` (no model); appends one outcome line to `notebook/agent-runs.jsonl` (see [Agents](agents.md#did-a-spec-change-help)); records a lesson for that agent in the store's `agents/<name>.md` | the copy and the outcome line need nothing (the line is off with `GENESEED_NO_USAGE` or `.usage-off`); the lesson needs `GENESEED_LLM` |
25
- | `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
23
+ | `Stop` | the agent finishes a reply | `geneseed-hook learn` | copies the reply's `spec-feedback: [skill:<name>]` lines into `skill-notes/<name>.md` (no model), and runs the done check and the change report; calls no model | nothing: the distil no longer runs here (see `PreCompact` and `SessionEnd`) |
24
+ | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | copies the `spec-feedback:` lines of its report into `agent-notes/<name>.md` (no model); appends one outcome line to `notebook/agent-runs.jsonl` (see [Agents](agents.md#did-a-spec-change-help)); queues the agent's lesson, which the session's one distil writes into the store's `agents/<name>.md` (no model at the stop) | the copy and the outcome line need nothing (the line is off with `GENESEED_NO_USAGE` or `.usage-off`); the lesson needs `GENESEED_LLM` |
25
+ | `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised: writes a small job and starts a detached `geneseed-hook learn-worker`, which distils it, then returns at once | needs `GENESEED_LLM` (a Claude or OpenClaude build writes it from `--learn`) |
26
26
  | `UserPromptSubmit` | you send a message | `geneseed-hook activity` | records the turn's start for the web console's Activity view; when the message is `/<name>` and `<name>` is an installed skill, records it in the usage count as `via: "slash"`; prints nothing | the Activity record is off with `GENESEED_ACTIVITY=off`; the count is off with `GENESEED_NO_USAGE` or `.usage-off` |
27
- | `SessionEnd` | the session closes | `geneseed-hook activity` | marks the session ended and archives it | off with `GENESEED_ACTIVITY=off` |
27
+ | `SessionEnd` | the session closes | `geneseed-hook learn` | marks the session ended and archives it for the Activity view; starts the session's one distil (and its queued sub-agent lessons) in a detached `learn-worker`, so the closing session cannot cut it short | the Activity record is off with `GENESEED_ACTIVITY=off`; the distil needs `GENESEED_LLM` |
28
28
  | `SubagentStart` | a subagent starts | `geneseed-hook context` | injects your `user-rules.md` layers into the subagent (as JSON `additionalContext`, under the same 9 000-character budget), and records the subagent as a branch of its session | the Activity record only, with `GENESEED_ACTIVITY=off` |
29
29
 
30
30
  ### What the usage count records
@@ -91,13 +91,13 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
91
91
 
92
92
  **The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**, and they stay advisory, with no date: only a list the project wrote can block. A turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test --test-reporter=tap "tests/**/*.test.mjs"`. A listed line matches as a prefix of the command: `node --test` listed would accept `node --test tests/one.test.mjs`, one file of the suite, so list each command whole. Before the match, the gate removes three things from both the line and the command, and nothing else: `--prefix <dir>` (or `--prefix=<dir>`) on `npm`, and `-C <dir>` right after `git`, when `<dir>` is the judged project's own root (the worktree whose files were edited); and `--test-concurrency N` on `node --test`. So a worker's `npm --prefix <its worktree> run lint` proves `npm run lint`, and a suite run at the default concurrency proves a line that names `--test-concurrency=8`. A `--prefix` that names another project, a sibling worktree, the main checkout or a subfolder still reads as not run (that run never saw this tree's edits). A changed glob or reporter still does not match. The gate does not follow `cd`: it reads the command line only. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. A check that runs in the background (Claude Code's `run_in_background`, or a command moved there after its foreground timeout) counts only when its task notification says it completed with exit code 0; the launch alone says only that it started. The gate never runs a check itself. It reads the transcript from its end, back only to the last prompt a person typed: a background task's notification opens no turn, so a turn spans every continuation the notifications drive. Its cost grows with that turn, not with the session; in a long run kept going by notifications it may read back to the start of the file. A sub-agent's turn is judged too, when it stops (SubagentStop): the gate reads the sub-agent's own transcript and judges each project it wrote files in by that project's git root and list, so a worker in its own worktree owes its worktree's checks, not its parent's. A block there keeps the sub-agent working, with the owed checks as its next instruction. An inferred check there is only a stderr line and a ledger entry, since nobody sees a sub-agent's warning. It blocks again only when the agent edited a file since the last block, or when a check's background run changed its verdict (still running, then failed), and at most 3 times per continuation: a stop with neither, or a fourth stop, ends the turn and leaves a `done-gate-cap` line in the gate ledger. A task notification starts a new continuation with a fresh count, so early blocks do not spend the cap for the rest of an unattended run. Over the whole turn, until the next prompt a person types, it blocks at most 10 times: a suite relaunched in the background after each failure would otherwise loop, one full run per cycle. Past that ceiling the turn ends, and the stderr line says the total ceiling was reached. The block names the checks whose background run is still running or reported a failure. The count is kept per session (and per sub-agent) in the install's `notebook/done-gate/`; without an install, the second stop ends the turn. Only file-write tools count as edits: a shell `sed -i` or redirect is not one here. When a turn weakened a test (see the rule gate), the gate adds a line that the agent cannot suppress, `[done-gate] advisory — test weakened this turn: tests/a.test.js (.skip added)`. The line needs no checks and stays out of the ask counts. `--no-done-gate` silences this line and OpenCode's reminder, but not the note the agent gets at edit time on Claude Code, OpenClaude and Bob: the rule gate never receives that flag. A block prints only the block; the line comes at the stop that ends the turn. On OpenCode the gate is a reminder on the next request (OpenCode 1 only), listed or inferred; on Bob, whose Stop carries no transcript, the turn is not judged, and with a listed file a log line says so. An install built `--no-done-gate` wires `learn` with that flag: the check is skipped, learning still runs ([Exclusions](exclusions.md)).
93
93
 
94
- **learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries in the memory store: on a global install, the shared one when it exists. It is shown the facts already stored, so it updates one with the merged text rather than writing a twin (the old version is kept in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It needs `GENESEED_LLM` set to a model command, for example:
94
+ **learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries in the memory store: on a global install, the shared one when it exists. It is shown the facts already stored, so it updates one with the merged text rather than writing a twin (the old version is kept in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It runs on PreCompact and SessionEnd, never on Stop: the hook writes a job file and returns, and a detached worker (`geneseed-hook learn-worker`) calls the model, so a compaction or a closing session never waits on it. A session with n compactions makes n + 1 calls, each on the tail of the transcript. A sub-agent's stop only queues its lesson for the next run. It needs `GENESEED_LLM`, a model command. A Claude Code or OpenClaude build writes one into the install's settings by default (`--learn light`: `claude -p --model haiku`; `--learn off` removes it), so exporting it yourself is optional, and a value you set is never overwritten:
95
95
 
96
96
  ```bash
97
97
  export GENESEED_LLM="claude -p"
98
98
  ```
99
99
 
100
- Unset, `learn` distils nothing: on a real Stop/SubagentStop/PreCompact call it returns before it reads the transcript for a distil, and on a manual run it prints the prompt it would have sent. Geneseed never stores or embeds an API key. See [Memory](memory.md).
100
+ Unset, `learn` distils nothing: on a real PreCompact/SessionEnd call it returns before it reads the transcript for a distil, and on a manual run it prints the prompt it would have sent. The worker has no terminal, so it writes its verdict to `~/.config/geneseed/cache/learn-last.json` (the latest run of any install on the machine); when the last run failed (a lapsed login, a timeout, a command not found), `status` and `doctor` add `· last run failed <date>: <reason>` to the learn line (`· last run stuck since <date>` when a run never ended). A custom `.cmd` or `.bat` model command receives the prompt on stdin, not as an argument. Geneseed never stores or embeds an API key. See [Memory](memory.md).
101
101
 
102
102
  One part of `learn` needs no model. On SubagentStop it reads the subagent's final report (its last message, or the message of its hand-back call) and copies each `spec-feedback:` line into the notes that agent reads at its next dispatch. Each line names its scope. A machine line (`[agent]`, `[general]`, a skill's `[skill:<name>]` or `[skill:<name>:general]`) goes to the tier's `notes/`, for every host and install kind: `agent-notes/<name>.md`, or `agent-notes/_general.md` for a `general` line, which every agent reads. The tier's folder exists on any machine an emit has run on (the install registry lives there); only `notes/<sub>/` is made under it, and with no such folder a machine line is dropped. A project line (`[agent:project]`, `[skill:<name>:project]`) goes to `<project>/notebook/`: the install's parent for a project install, the git root of the session's project for a global one, a linked worktree's main checkout either way. A global session outside any repo has no project, so its project line is dropped, never sent to the machine notes. A `[general:project]` line goes to that folder's `agent-notes/_general.md`, which every agent reads in this repo. Geneseed writes no ignore file into the project: the notes folders and the migration's archives are named in the clone's own `.git/info/exclude`, once, in a marked block, so they never reach a commit, even in a repo whose `notebook/` is tracked. Outside a git repo nothing extra is written. Each note is one bullet that names its writer and its date, `- [agent] <fix> (<agent>, <date>)`, appended under a short file lock so parallel subagents do not lose each other's lines; a line already there is not added again, and the template placeholder, a quoted (`>`) or fenced line and a line holding a credential are skipped. The line is kept at every stop, one the done gate blocks included: the report that draws the block carries it, and the one that passes need not repeat it. Every dispatch reads these files, so they are capped: an agent's file at 100 bullets, `_general.md` at 30, each file at 8 000 characters. Past a cap the oldest bullets the hook wrote drop, told apart by the writer's name beside the date; a line written by hand is never moved or dropped, a dated one included. The OpenCode learn plugin does the same for a child session that names its agent. Bob has no subagent-finished event, so there the caller copies the line.
103
103
 
@@ -18,7 +18,7 @@ The wizard, plain `setup`, needs an interactive terminal. In a script, a CI job,
18
18
  geneseed build --emit opencode-global --theme neutral
19
19
  ```
20
20
 
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). `--tiers auto` (default `off`) routes sub-agents to cheaper models by tier on Claude Code; see [Model tiers](../concepts/agents.md#model-tiers).
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). `--tiers auto` (default `off`) routes sub-agents to cheaper models by tier on Claude Code; see [Model tiers](../concepts/agents.md#model-tiers). `--learn off|light|standard|session` (default `light`) records which model memory learning uses; the hosts start reading it in later changes.
22
22
 
23
23
  To test a build before writing anything, use `geneseed validate` with the same flags. See [Verify](verify.md).
24
24
 
@@ -38,6 +38,7 @@ Where distilled memories land at session end, and which model distils them. See
38
38
  | `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `geneseed-wiki.jsonc` is looked up). Optional — a global install finds the shared store by itself. Set it only to pin another store: it wins over the shared one, so a value such as `~/.config/opencode` keeps facts out of the tier. |
39
39
  | `GENESEED_MEMORY` | learn plugin, CLI, hand-run `learn` | Explicit memory dir; wins over `GENESEED_HARNESS` and the shared store. It moves what the OpenCode learn plugin, `geneseed memory` and a hand-run `learn` use. It does not move the `learn` hook, which is told its store by `--memory`, or what a session loads and the console shows: those read the tier. Without either variable, `geneseed memory`, `status` and a hand-run `learn` use a project install in the cwd or `./Harness`, then the shared store, then the OpenCode config store. A `memory/` folder counts only when an emit made it: a known `.geneseed-emit`, `.geneseed-version` beside the folder and `MEMORY.md` in it. Any other is not a store: name it with `--memory`. Two host installs in one repo keep two stores, and these commands use the one the marker names: name the other with `--memory`. |
40
40
  | `GENESEED_MODEL` | learn + context plugins | `provider/model` fallback when the session's model can't be read from the transcript. |
41
- | `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, a real Stop/SubagentStop/PreCompact call distils nothing and returns without reading the transcript for it — nothing reads its stdout there. The SubagentStop copy of `spec-feedback:` lines into `agent-notes/`, and the Stop copy of a skill's `[skill:<name>]` lines into `skill-notes/`, run either way; a manual `learn` run (notes piped or given as a file) still prints the prompt instead of distilling. |
41
+ | `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p --model haiku` (a Claude or OpenClaude build writes it into the install's settings `env` from `--learn`; a value you set is never overwritten). The distil runs at each PreCompact and at SessionEnd (a session with n compactions makes n + 1 calls), in a detached worker. Unset, a real PreCompact/SessionEnd call distils nothing and returns without reading the transcript for it — nothing reads its stdout there. The SubagentStop copy of `spec-feedback:` lines into `agent-notes/`, and the Stop copy of a skill's `[skill:<name>]` lines into `skill-notes/`, run either way; a manual `learn` run (notes piped or given as a file) still prints the prompt instead of distilling. |
42
+ | `GENESEED_LEARN_INLINE` | learn hook | Set to any value, `learn` runs the PreCompact/SessionEnd distil inside the hook process and waits for the model, instead of starting the detached worker. For tests and for debugging the distil; a real session should not set it. Without it a hook event never runs the model inline: with no install or machine folder to name, it skips and records the skip in `cache/learn-last.json`. |
42
43
  | `GENESEED_LEARN_CHILD` | learn hook | Set by `learn` itself on the model CLI it spawns; a nested session's own Stop hook sees it and returns immediately, which stops `GENESEED_LLM="claude -p"` (hooks not disabled) from recursing. Not meant to be set by hand. |
43
44
  | `GENESEED_LEARN_DEBOUNCE_MS` | learn plugin | Quiet period before distilling, in ms (default 60000). |
@@ -12,7 +12,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
12
12
 
13
13
  **When it runs.** On session events. A sub-agent's child session (one with a `parentID`) is folded into its root session: it becomes an `agents[]` row (`{id, type, status: "running" | "done"}`, the child's id and agent), and its files join the root's `files` with `by` set to the child's id. Only learn's throwaway `geneseed-*` sessions are skipped. On OpenCode 2 the files come from `session.step.ended`, which carries no line counts, so those read `null`. A session whose process died, went stale (30 minutes untouched) or ended leaves the live list and is listed as ended; the reader never deletes a file.
14
14
 
15
- **Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `SessionEnd` (their `SubagentStart` runs `context`, which records the same way). So a Claude session's phase moves on the gated tools (`Bash`, `PowerShell`, `Monitor`, `Write`, `Edit`, `NotebookEdit`, `Skill`, `Agent`, `Task`), and the rest of the turn — every tool call, the model, the token totals, the last reply — arrives at `Stop`, read from the transcript where the previous `Stop` left off (at most 2 MB per turn). Bob sends no transcript, so a Bob session shows only the calls its `tool-gate` sees, and leaves the live list by staleness alone (Bob has no `SessionEnd`). Bob's `SessionStart` is recorded only after a compaction (`source: "compact"`, counted as one): a startup or resume fires just before the first prompt, which records the session anyway. Bob 2.2.3 writes every hook's payload to stdin and closes it, so reading it there is safe. These writers have no resident process, so their snapshots carry `pid: null` and stay live by staleness alone. Recorded: tool names, each changed file's path relative to the session's git root (a file outside the root, or a session outside any repo, keeps its basename only; a path is never stored absolute; labels show basenames), who changed it (the session or a subagent's `agent_id`), the subagents, the prompt count, the context size and the compactions, line counts, todo text, and 240-character snippets of the prompt and the last reply — never a shell command, a file's content or an edit's text — and any credential the secrets gate would catch in a snippet is written as `[redacted]`. A project install's `activity/` gets its own `.gitignore` (`*`), and the writer never writes through, or sweeps, an `activity/` or `activity/archive/` that is a link. Nothing is recorded in a repo listed in `excludes.json`, or inside a model CLI that `learn` started.
15
+ **Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `geneseed-hook learn` on `SessionEnd` (their `SubagentStart` runs `context`, which records the same way). So a Claude session's phase moves on the gated tools (`Bash`, `PowerShell`, `Monitor`, `Write`, `Edit`, `NotebookEdit`, `Skill`, `Agent`, `Task`), and the rest of the turn — every tool call, the model, the token totals, the last reply — arrives at `Stop`, read from the transcript where the previous `Stop` left off (at most 2 MB per turn). Bob sends no transcript, so a Bob session shows only the calls its `tool-gate` sees, and leaves the live list by staleness alone (Bob has no `SessionEnd`). Bob's `SessionStart` is recorded only after a compaction (`source: "compact"`, counted as one): a startup or resume fires just before the first prompt, which records the session anyway. Bob 2.2.3 writes every hook's payload to stdin and closes it, so reading it there is safe. These writers have no resident process, so their snapshots carry `pid: null` and stay live by staleness alone. Recorded: tool names, each changed file's path relative to the session's git root (a file outside the root, or a session outside any repo, keeps its basename only; a path is never stored absolute; labels show basenames), who changed it (the session or a subagent's `agent_id`), the subagents, the prompt count, the context size and the compactions, line counts, todo text, and 240-character snippets of the prompt and the last reply — never a shell command, a file's content or an edit's text — and any credential the secrets gate would catch in a snippet is written as `[redacted]`. A project install's `activity/` gets its own `.gitignore` (`*`), and the writer never writes through, or sweeps, an `activity/` or `activity/archive/` that is a link. Nothing is recorded in a repo listed in `excludes.json`, or inside a model CLI that `learn` started.
16
16
 
17
17
  **Archive.** On `SessionStart` and `SessionEnd` the hook writer moves every snapshot that is no longer live into `activity/archive/`, keeping the newest 50 and none older than 7 days. `/api/activity` returns them, with the stale and dead ones still in `activity/`, in its `ended` list — capped there by the same rule, since the OpenCode plugin never sweeps.
18
18
 
@@ -91,6 +91,7 @@ A gate that is off in the global install runs nowhere, so the line does not name
91
91
  | `kitsByDetection` | no | A list of kits that a plugin can stand in for (today `superpowers`), decided when the profile is applied: on when the plugin is **not** seen on that host, off when it is. The rule is the wizard's. A kit may not appear here and in `kits`. [The superpowers kit](../concepts/superpowers-kit.md) says what is read and where |
92
92
  | `sharedTier` | no | `true` lets a **project** install read the machine-wide shared tier (`geneseed build --shared-tier on`). A global apply ignores it, because a global install owns the tier |
93
93
  | `tiers` | no | `"auto"` or `"off"`, as `geneseed build --tiers`: route sub-agents to cheaper models by tier ([Model tiers](../concepts/agents.md#model-tiers)). Absent means "not set by this profile": applying it keeps the install's own routing, and `off` on a new install. No shipped profile sets it. |
94
+ | `learn` | no | `"off"`, `"light"`, `"standard"` or `"session"`, as `geneseed build --learn`: which model memory learning is to distil with. Recorded per install; the hosts start reading it in later changes. Absent means "not set by this profile": applying it keeps the install's own choice, and `light` on a new install. No shipped profile sets it. |
94
95
  | `contextWindow` | no | `"200k"` (the default) or `"1m"`, as `geneseed build --context-window`: the model context the install is built for. On Claude Code it sets the skill-listing budget ([Skills](../concepts/skills.md#the-listing-budget-on-claude-code)); other hosts record it and write nothing |
95
96
  | `gates` | no | An object that maps a gate switch to `false` to turn it off. Each key is a gate flag of `geneseed build --help` (`deletionGate: false` is `--no-deletion-gate`); a wrong key's refusal lists them all. `ownBranchPass: false` is `--strict-consent`, which adds asks |
96
97
  | `login` | no | `true` (default) lets `setup --profile` set the console to start at login and start it; `false` does neither, for a server or a CI machine. `profile apply` ignores it |
@@ -57,7 +57,7 @@ The reviewer reads the change, runs the tests, and comes back with findings orde
57
57
 
58
58
  ### 4. The session teaches the next one
59
59
 
60
- When a session winds down, the **learn** step reads the conversation and keeps what is worth remembering. On OpenCode this happens by itself, with the model the session already uses. On Claude Code it is off until you set `GENESEED_LLM` to a model command, for example `claude -p`.
60
+ At each compaction and when a session winds down, the **learn** step reads the conversation and keeps what is worth remembering. On OpenCode this happens by itself, with the model the session already uses. On Claude Code and OpenClaude it is on by default (`--learn light`, Haiku): the build writes the model command into the install's settings, and a detached worker runs it. Choose another model, or none, with `--learn off|light|standard|session`.
61
61
 
62
62
  A new file appears in the memory store. On a global install that is `~/.config/geneseed/memory/`, so every host on the machine sees it; a project install keeps its own `memory/` folder:
63
63
 
@@ -17,7 +17,7 @@ What a Claude Code or OpenClaude install writes, piece by piece. The **Kind** wo
17
17
  | context hook | At session start, and again after a resume or compaction, puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs; the whole hook output is capped at 9,000 characters, and what does not fit is listed for the agent to read on demand | `geneseed exclude add <folder>` silences every hook in that folder |
18
18
  | git-gate hook | Before each shell command: asks you before any `git commit` or `git push`, and before a command that would really lose data — a force-push to `main`, a `reset --hard` that abandons unpushed commits, `branch -D` of an unpushed branch, an `rm` git cannot undo | enforced | ~14 ms per shell call | The commit/push question goes away if you build without the **process** pack; the destructive-git question has no switch except `geneseed exclude` |
19
19
  | rule-gate hook | Before each write or edit: asks you when the file would carry a credential-shaped string (outside `.env`), or when the agent writes to `user-rules.md` or memory. In an application repo with no `## Ownership` section in its root `AGENTS.md`, stops the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | ~14 ms per write | `geneseed exclude add <folder>`; the ownership stop alone: `mode: off` in the repo's `## Ownership`, `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, or rebuild with `--no-ownership-gate` |
20
- | learn hook | When the agent finishes a reply, and before compaction, distils durable facts from the recent conversation into the memory store. Off until you set `GENESEED_LLM` to a model command such as `claude -p` | automatic | One model call each time it runs, once enabled | Leave `GENESEED_LLM` unset (the default) |
20
+ | learn hook | At each compaction and when the session ends, distils durable facts from the recent conversation into the memory store, in a detached worker that never delays a reply. On by default (`--learn light`: Haiku through `claude -p`); the build writes `GENESEED_LLM` into the install's settings | automatic | One model call at each compaction and one at session end | Build with `--learn off`, or leave a `GENESEED_LLM` of your own in place (it is never overwritten) |
21
21
  | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~2.2k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
22
22
  | `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
23
23
  | `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context hook injects. A global install keeps them in the shared `~/.config/geneseed/memory/`; this folder holds only the convention and a seeded index | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
package/docs/web-ui.md CHANGED
@@ -286,8 +286,8 @@ A hidden part is not off. It keeps working, and a link, a bookmark or a search r
286
286
  (code points / 4 of its own block), and each list's head shows the one rule count and total, such
287
287
  as `4 rules · ≈1,055 tokens every turn · scope global unless marked`, which counts the file's
288
288
  header too. A row shows a scope only when it differs from that. There is no ceiling.
289
- A **Pending** section lists what waits undecided in `user-rules.draft.md`, and a pending rule still
290
- binds on its host. *Approve* and *Reject* decide a rule; a profile or wiki pointer shows both files,
289
+ A **Pending** section lists what waits undecided in `user-rules.draft.md`, and a pending rule for a host file
290
+ still binds on its host; one drafted from the memory index is not loaded until approved. *Approve* and *Reject* decide a rule; a profile or wiki pointer shows both files,
291
291
  with *Use the host file*, *Use the shared file* and *Keep both*. These apply the rule skill's own
292
292
  steps (`js/build/rule-decide.mjs`), and a decision that moves a file offers *Rebuild all*. No decision
293
293
  applies while a job runs. The [change report](concepts/hooks.md#the-change-report) lists a decision like
@@ -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": "6.0.3"
5
+ "version": "6.0.4"
6
6
  }
package/js/build/args.mjs CHANGED
@@ -11,7 +11,7 @@ import { parseArgs as nodeParseArgs } from 'node:util';
11
11
  import { withPlatformNewlines } from '../lib/fs.mjs';
12
12
  import path from 'node:path';
13
13
  import {
14
- CONFIG, CONTEXT_WINDOWS, DEFAULT_CONTEXT_WINDOW, DEFAULT_TIERS, discoverNames, GATE_SWITCHES, PACK_ORDER, SRC, TIERS_CHOICES, knownRuleIds, knownSkillIds, linkedSkillIds, loadKits,
14
+ CONFIG, CONTEXT_WINDOWS, DEFAULT_CONTEXT_WINDOW, DEFAULT_LEARN, DEFAULT_TIERS, LEARN_CHOICES, discoverNames, GATE_SWITCHES, PACK_ORDER, SRC, TIERS_CHOICES, knownRuleIds, knownSkillIds, linkedSkillIds, loadKits,
15
15
  resolveSkillNames, retiredRuleAddresses, reusedRuleAddresses, ruleCanon, skillAliases,
16
16
  } from './source.mjs';
17
17
  // The loop engine's trust presets — the `--trust` choices. `score.mjs` imports nothing, which is
@@ -103,7 +103,7 @@ 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', '--context-window': 'contextWindow',
106
- '--tiers': 'tiers',
106
+ '--tiers': 'tiers', '--learn': 'learn',
107
107
  '--out': 'out', '--target': 'out', '--emit': 'emit',
108
108
  '--footprint': 'footprint', '--root': 'root', '--config-dir': 'cfgDir',
109
109
  };
@@ -170,6 +170,7 @@ export function choicesFor() {
170
170
  '--shared-tier': ['on', 'off'],
171
171
  '--context-window': Object.keys(CONTEXT_WINDOWS),
172
172
  '--tiers': [...TIERS_CHOICES],
173
+ '--learn': [...LEARN_CHOICES],
173
174
  };
174
175
  }
175
176
 
@@ -379,7 +380,7 @@ export function parseArgs(argv, defaults) {
379
380
  excludeRules: defaults.excludeRules,
380
381
  excludeSkills: defaults.excludeSkills ?? [],
381
382
  kits: defaults.kits ?? [],
382
- sharedTier: 'off', contextWindow: DEFAULT_CONTEXT_WINDOW, tiers: DEFAULT_TIERS,
383
+ sharedTier: 'off', contextWindow: DEFAULT_CONTEXT_WINDOW, tiers: DEFAULT_TIERS, learn: DEFAULT_LEARN,
383
384
  out: 'Harness', emit: 'files', footprint: 'lean', root: null,
384
385
  syncThemes: false, validateOnly: false, verbose: false, pruneGates: false, force: false, reset: false,
385
386
  ...Object.fromEntries(GATE_SWITCHES.map((g) => [g.arg, false])),
@@ -724,13 +724,13 @@ const PROJECT_EMITS = {
724
724
  * carry straight past the parameter default.
725
725
  */
726
726
  function axesCfg({
727
- posture, mode, trust, doctrines, excludeRules, excludeSkills, kits, sharedTier, contextWindow, tiers, ...gates
727
+ posture, mode, trust, doctrines, excludeRules, excludeSkills, kits, sharedTier, contextWindow, tiers, learn, ...gates
728
728
  }) {
729
729
  return makeCfg({
730
730
  ...(posture ? { posture } : {}), ...(mode ? { mode } : {}), ...(trust ? { trust } : {}),
731
731
  ...(doctrines ? { doctrines } : {}), ...(excludeRules ? { excludeRules } : {}),
732
732
  ...(excludeSkills ? { excludeSkills } : {}), ...(kits ? { kits } : {}), ...(sharedTier ? { sharedTier } : {}),
733
- ...(contextWindow ? { contextWindow } : {}), ...(tiers ? { tiers } : {}),
733
+ ...(contextWindow ? { contextWindow } : {}), ...(tiers ? { tiers } : {}), ...(learn ? { learn } : {}),
734
734
  // The gate switches (`GATE_SWITCHES` keys): only an explicit `false` disarms; `null` (no
735
735
  // opinion) keeps the gate.
736
736
  ...Object.fromEntries(GATE_SWITCHES.filter((g) => gates[g.key] === false).map((g) => [g.arg, true])),
@@ -739,7 +739,7 @@ function axesCfg({
739
739
 
740
740
  export function emitProjectInto(host, {
741
741
  theme, out, root, footprint = 'full', posture = null, mode = null, trust = null,
742
- doctrines = null, excludeRules = null, excludeSkills = null, kits = null, sharedTier = false, contextWindow = null, tiers = null, seed = true, ...gates
742
+ doctrines = null, excludeRules = null, excludeSkills = null, kits = null, sharedTier = false, contextWindow = null, tiers = null, learn = null, seed = true, ...gates
743
743
  }) {
744
744
  const emit = PROJECT_EMITS[host];
745
745
  // The axes ride the same rail into every `*Into`, and for the same reason: a drift reader
@@ -750,7 +750,7 @@ export function emitProjectInto(host, {
750
750
  // the git root, which for a temp dir inside a repo is that repo, outside the sandbox.
751
751
  return withPlatformNewlines(() => emit(
752
752
  axesCfg({
753
- posture, mode, trust, doctrines, excludeRules, excludeSkills, kits, sharedTier, contextWindow, tiers, ...gates }),
753
+ posture, mode, trust, doctrines, excludeRules, excludeSkills, kits, sharedTier, contextWindow, tiers, learn, ...gates }),
754
754
  { theme, footprint, root, seed }, out,
755
755
  ));
756
756
  }
@@ -765,16 +765,16 @@ export function emitProjectInto(host, {
765
765
  */
766
766
  export function buildInto({
767
767
  theme, out, footprint = 'lean', posture = null, mode = null, trust = null, doctrines = null,
768
- excludeRules = null, excludeSkills = null, kits = null, sharedTier = false, contextWindow = null, tiers = null, ...gates
768
+ excludeRules = null, excludeSkills = null, kits = null, sharedTier = false, contextWindow = null, tiers = null, learn = null, ...gates
769
769
  }) {
770
770
  return withPlatformNewlines(() => build(axesCfg({
771
- posture, mode, trust, doctrines, excludeRules, excludeSkills, kits, sharedTier, contextWindow, tiers, ...gates }),
771
+ posture, mode, trust, doctrines, excludeRules, excludeSkills, kits, sharedTier, contextWindow, tiers, learn, ...gates }),
772
772
  theme, out, { footprint, nativeCatalog: false }));
773
773
  }
774
774
 
775
775
  export function emitGlobalInto(host, {
776
776
  theme, out, cfgDir, footprint, posture = null, mode = null, doctrines = null, trust = null,
777
- excludeRules = null, excludeSkills = null, kits = null, sharedTier = false, contextWindow = null, tiers = null,
777
+ excludeRules = null, excludeSkills = null, kits = null, sharedTier = false, contextWindow = null, tiers = null, learn = null,
778
778
  sharedRoot = undefined, ...gates
779
779
  }) {
780
780
  // `build.HOSTS.get(host, build.HOSTS["opencode"])` — an unknown host falls back rather than
@@ -792,7 +792,7 @@ export function emitGlobalInto(host, {
792
792
  // the same scar the footprint left in `diffCollect`, one axis over each time.
793
793
  return withPlatformNewlines(() => emit(
794
794
  axesCfg({
795
- posture, mode, trust, doctrines, excludeRules, excludeSkills, kits, sharedTier, contextWindow, tiers, ...gates }),
795
+ posture, mode, trust, doctrines, excludeRules, excludeSkills, kits, sharedTier, contextWindow, tiers, learn, ...gates }),
796
796
  { theme, footprint, root: null, cfgDir, sharedRoot }, out,
797
797
  ));
798
798
  }
@@ -7,16 +7,17 @@
7
7
  */
8
8
  import path from 'node:path';
9
9
  import { VERSION_MARKER } from '../hosts/hosts.mjs';
10
- import { claimer, loadAgentOverrides, loadTierMap, writeNativeLayer } from '../hosts/native.mjs';
10
+ import { claimer, learnModel, loadAgentOverrides, loadTierMap, writeNativeLayer } from '../hosts/native.mjs';
11
11
  import { ensureAgentOverridesStub, writeAliasCommands } from '../hosts/opencode.mjs';
12
12
  import {
13
- managedBlockRemove, managedBlockWrite, mergeClaudeSettings,
13
+ CLAUDE_ENV, managedBlockRemove, managedBlockWrite, mergeClaudeSettings,
14
14
  unwireClaudeEnv, unwireClaudeExcludes, unwireClaudeListing, unwireClaudeSettings, wireClaudeEnv,
15
15
  wireClaudeExcludes, wireClaudeListing,
16
16
  } from '../hosts/settings.mjs';
17
17
  import { CONTEXT_WINDOWS } from './source.mjs';
18
18
  import { get, isDict, isTruthy } from '../lib/json.mjs';
19
19
  import { relPosix } from '../lib/text.mjs';
20
+ import { claudeCfg, claudeReadManifest, installTargets } from '../hosts/installs.mjs';
20
21
  import { assertSourceComplete, phaseLog, ensureMemoryStore } from './bundle.mjs';
21
22
  import { foldOnEmit } from './fold.mjs';
22
23
  import { migrateProjectNotes } from './notes-migrate.mjs';
@@ -221,6 +222,36 @@ export function emitClaudeRender(cfg, job) {
221
222
  };
222
223
  }
223
224
 
225
+ /** Every `GENESEED_LLM` an install of a Claude-family host recorded (its manifest's `settings_env`), as a set. */
226
+ function recordedByAnyInstall() {
227
+ const found = new Set();
228
+ try {
229
+ for (const [host, scope, root] of installTargets()) {
230
+ if (host !== 'claude' && host !== 'openclaude') continue;
231
+ const cmd = claudeReadManifest(claudeCfg(root, scope, host)).managed?.settings_env?.[LEARN_ENV_KEY];
232
+ if (typeof cmd === 'string') found.add(cmd);
233
+ }
234
+ } catch { /* an unreadable machine registry: only this install's record counts */ }
235
+ return found;
236
+ }
237
+
238
+ /** The `env` key the hook's learn reads its model command from (`js/hosts/hooks-learn.mjs`). */
239
+ export const LEARN_ENV_KEY = 'GENESEED_LLM';
240
+
241
+ /**
242
+ * The command the emit writes into `env.GENESEED_LLM` for `learn` (spec 2026-11-18-learn-model-row, D4):
243
+ * `<cli> -p --model <model>`, or `<cli> -p` for `session` (the user's default model), with `<cli>` the
244
+ * host's own (`claude`, `openclaude`). null writes nothing: `off`, and Bob (`from: 'n/a'`). Pure.
245
+ * The lean flags are NOT here: learn appends them at run time, to a command whose first word is the CLI.
246
+ */
247
+ export function learnEnvCommand(learn, host, map = {}, env = {}) {
248
+ const cli = host === 'openclaude' ? 'openclaude' : host === 'claude' ? 'claude' : null;
249
+ const { model, from } = learnModel(learn, map, env, host);
250
+ if (!cli || from === 'off' || from === 'n/a') return null;
251
+ // `GENESEED_LLM` is split on whitespace: a model name holding one cannot ride in it.
252
+ return model && !/\s/.test(model) ?`${cli} -p --model ${model}` : `${cli} -p`;
253
+ }
254
+
224
255
  /**
225
256
  * `_build_global._claude_wire_py` — the files the Claude-shaped emits do NOT own: the
226
257
  * CLAUDE.md/AGENTS.md managed block and settings(.local).json.
@@ -312,10 +343,34 @@ function claudeWire(job, claudeMdText, hasAgentText, doctrines = null, excludeRu
312
343
  managed.settings_hooks = managedHooks;
313
344
  // The subagent depth cap, Claude Code only (`CLAUDE_ENV` says why). The record is what this
314
345
  // install wrote, prior plus new, so uninstall never takes a key the user set themselves.
315
- if (host === 'claude') {
346
+ if (host === 'claude' || host === 'openclaude') {
347
+ // Claude only for the depth cap; both hosts for the learn model (`learnEnvCommand`). The record is
348
+ // what Geneseed owns on file after the merge (`wireClaudeEnv`'s replace-if-ours form), so the model
349
+ // can change on a rebuild and a value the user set never lands in it.
316
350
  const priorEnv = oldSf === settingsName && isDict(get(old, 'settings_env')) ? old.settings_env : {};
317
- const env = { ...priorEnv, ...wireClaudeEnv(settingsPath) };
351
+ /** @type {Record<string, string>} */
352
+ const want = host === 'claude' ? { ...CLAUDE_ENV } : {};
353
+ const llm = learnEnvCommand(gates.learn, host, loadTierMap(cfgDir, () => {}), process.env);
354
+ // A shell that names a command of its own is the user's (D5): the settings `env` would override it in a
355
+ // session, so Geneseed stops managing the key, and removes its own value if it is still on file. A shell
356
+ // that holds a value some build recorded is only a session that inherited ours (the session's settings `env`
357
+ // reached it), and ours stays ours: a rebuild run from inside a session (the console, an agent, `rebuild-all`)
358
+ // must not give the key up, and a session of install A holds A's value while a rebuild reaches install B. The
359
+ // same for an install that has a record while the process runs inside Claude Code (`CLAUDECODE`, set by the app
360
+ // in every session: seen in a real session's environment), whatever the inherited value was.
361
+ const shellLlm = process.env.GENESEED_LLM;
362
+ const recordedLlm = Object.hasOwn(priorEnv, LEARN_ENV_KEY) ? priorEnv[LEARN_ENV_KEY] : null;
363
+ const shellIsUsers = Boolean(shellLlm) && shellLlm !== recordedLlm && !recordedByAnyInstall().has(shellLlm)
364
+ && !(recordedLlm !== null && process.env.CLAUDECODE);
365
+ if (llm && !shellIsUsers) want[LEARN_ENV_KEY] = llm;
366
+ if (shellIsUsers && recordedLlm !== null) {
367
+ process.stderr.write(`[geneseed] $GENESEED_LLM is set in your shell (${JSON.stringify(shellLlm)}): Geneseed stops managing `
368
+ + `env.GENESEED_LLM in ${settingsName} and removes its own value (${JSON.stringify(recordedLlm)}) if it is still there.\n`);
369
+ }
370
+ const env = wireClaudeEnv(settingsPath, want, priorEnv);
318
371
  if (Object.keys(env).length) managed.settings_env = env;
372
+ }
373
+ if (host === 'claude') {
319
374
  // The skill-listing budget of `--context-window` (`CONTEXT_WINDOWS` says why and why Claude
320
375
  // Code only). The record is what this install owns on file, so a value can change on a rebuild.
321
376
  const priorListing = oldSf === settingsName && isDict(get(old, 'settings_listing')) ? old.settings_listing : {};
@@ -35,7 +35,7 @@ import path from 'node:path';
35
35
  import { main as driverMain } from './driver.mjs';
36
36
  import { GATE_SWITCHES, makeCfg } from './source.mjs';
37
37
  import { opencodeConfigDir, resolvePath } from '../hosts/hosts.mjs';
38
- import { installState, installTargets } from '../hosts/installs.mjs';
38
+ import { claudeCfg, claudeReadManifest, installState, installTargets } from '../hosts/installs.mjs';
39
39
  import { installProfile } from './profile.mjs';
40
40
  import { colorThemeFiles, colorThemeJson, PALETTE_ROLES } from '../hosts/opencode.mjs';
41
41
  import { renderAll } from './render.mjs';
@@ -92,7 +92,7 @@ const BUILD_FORWARD = [
92
92
  ['theme', '--theme'], ['emit', '--emit'], ['footprint', '--footprint'],
93
93
  ['posture', '--posture'], ['mode', '--mode'], ['trust', '--trust'], ['doctrines', '--doctrines'],
94
94
  ['excludeRules', '--exclude-rules'], ['excludeSkills', '--exclude-skills'], ['kits', '--kits'], ['sharedTier', '--shared-tier'],
95
- ['contextWindow', '--context-window'], ['tiers', '--tiers'], ['out', '--out'], ['root', '--root'],
95
+ ['contextWindow', '--context-window'], ['tiers', '--tiers'], ['learn', '--learn'], ['out', '--out'], ['root', '--root'],
96
96
  ['configDir', '--config-dir'],
97
97
  ];
98
98
 
@@ -160,6 +160,10 @@ export function rebuildAll() {
160
160
  return 0;
161
161
  }
162
162
  const failures = [];
163
+ // D10: which Claude-family installs hold no learn command now, so the ones that start learning are said once.
164
+ const learnCmd = ([host, scope, root]) => (host === 'claude' || host === 'openclaude'
165
+ ? claudeReadManifest(claudeCfg(root, scope, host)).managed?.settings_env?.GENESEED_LLM ?? null : null);
166
+ const before = new Map(targets.map((t) => [t, learnCmd(t)]));
163
167
  for (const [host, scope, root] of targets) {
164
168
  const label = `${host}:${scope} (${root})`;
165
169
  // The one replay that speaks when an excluded skill's name got older: status and the console
@@ -185,6 +189,11 @@ export function rebuildAll() {
185
189
  + `${failures.join(', ')}\n`);
186
190
  return 1;
187
191
  }
192
+ const started = targets.filter((t) => before.get(t) === null && learnCmd(t) !== null).map(([h, sc]) => `${h}:${sc}`);
193
+ if (started.length) {
194
+ printOut(`[rebuild-all] memory learning now runs on ${started.join(', ')} (the --learn setting, default light); `
195
+ + 'rebuild with --learn off to stop it.\n');
196
+ }
188
197
  printOut(`[rebuild-all] rebuilt ${targets.length} install(s).\n`);
189
198
  return 0;
190
199
  }