geneseed 5.2.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +2 -2
  3. package/SHIPPED.md +1 -1
  4. package/adapters/opencode/plugins/geneseed-context.js +56 -10
  5. package/adapters/opencode/plugins/geneseed-guard.js +6 -1
  6. package/bin/geneseed-cli.mjs +61 -16
  7. package/bin/geneseed-hook.mjs +37 -3
  8. package/docs/concepts/factories.md +40 -6
  9. package/docs/concepts/footprint.md +1 -1
  10. package/docs/concepts/foreman-mode.md +2 -2
  11. package/docs/concepts/loop-gates.md +1 -1
  12. package/docs/concepts/loops.md +2 -2
  13. package/docs/concepts/shared-tier.md +1 -1
  14. package/docs/design-history.md +140 -0
  15. package/docs/extending.md +54 -162
  16. package/docs/guides/run-a-factory.md +15 -2
  17. package/docs/guides/upgrade.md +2 -2
  18. package/docs/reference/factory-actions.md +6 -5
  19. package/docs/reference/troubleshoot-update.md +1 -1
  20. package/docs/web-ui.md +16 -3
  21. package/harness.config.json +1 -1
  22. package/js/README.md +4 -3
  23. package/js/build/args.mjs +3 -3
  24. package/js/build/render.mjs +44 -24
  25. package/js/cli-table.json +135 -59
  26. package/js/factory/cli.mjs +24 -5
  27. package/js/factory/graph.mjs +13 -9
  28. package/js/factory/metrics.mjs +93 -0
  29. package/js/factory/registry.mjs +37 -12
  30. package/js/factory/state.mjs +25 -6
  31. package/js/hosts/hooks-context.mjs +26 -1
  32. package/js/hosts/hooks-prims.mjs +52 -3
  33. package/js/hosts/hooks.mjs +50 -29
  34. package/js/hosts/loss.mjs +6 -1
  35. package/js/inspect/diff.mjs +16 -1
  36. package/js/inspect/doctor.mjs +7 -3
  37. package/js/inspect/excludes.mjs +18 -6
  38. package/js/inspect/status.mjs +35 -7
  39. package/js/inspect/validate.mjs +44 -21
  40. package/js/maintain/uninstall.mjs +28 -1
  41. package/js/maintain/update.mjs +31 -7
  42. package/js/ui/cli.mjs +34 -4
  43. package/js/ui/menu.mjs +1 -1
  44. package/js/ui/tui.mjs +11 -14
  45. package/js/web/actions.mjs +2 -0
  46. package/js/web/api.mjs +28 -10
  47. package/js/web/daemon.mjs +0 -1
  48. package/js/web/server.mjs +1 -0
  49. package/js/web/state.mjs +37 -16
  50. package/package.json +1 -1
  51. package/src/AGENT.md.tmpl +23 -17
  52. package/src/agents/_template.md +1 -1
  53. package/src/agents/advocate.md +1 -1
  54. package/src/agents/developer.md +12 -3
  55. package/src/agents/empiricist.md +1 -1
  56. package/src/agents/framer.md +1 -1
  57. package/src/agents/historian.md +1 -1
  58. package/src/agents/operator.md +1 -1
  59. package/src/agents/pragmatist.md +1 -1
  60. package/src/agents/researcher.md +1 -1
  61. package/src/agents/skeptic.md +1 -1
  62. package/src/agents/steward.md +1 -1
  63. package/src/agents/user-advocate.md +1 -1
  64. package/src/agents/visionary.md +1 -1
  65. package/src/bricks/intake.md +10 -3
  66. package/src/bricks/retro.md +13 -3
  67. package/src/doctrines/comms.md +1 -1
  68. package/src/doctrines/ops.md +1 -1
  69. package/src/doctrines/process.md +7 -5
  70. package/src/factories/analysis-to-build.json +1 -0
  71. package/src/factories/bug-report-to-fix.json +1 -0
  72. package/src/factories/issue-to-pr.json +1 -0
  73. package/src/laws/universal.md +2 -2
  74. package/src/modes/foreman.md +8 -14
  75. package/src/skills/commit.md +7 -2
  76. package/src/skills/debug.md +1 -1
  77. package/src/skills/diagram-design/SKILL.md +1 -1
  78. package/src/skills/diagram-design/VENDOR.md +3 -1
  79. package/src/skills/factory-forge.md +5 -3
  80. package/src/skills/factory.md +22 -1
  81. package/src/skills/geneseed.md +1 -1
  82. package/src/skills/handoff.md +1 -1
  83. package/src/skills/parallel-agents.md +1 -1
  84. package/src/skills/pipeline.md +6 -6
  85. package/src/skills/plan.md +7 -3
  86. package/src/skills/spring-testing.md +1 -1
  87. package/themes/biker.json +78 -78
  88. package/themes/commentator.json +81 -81
  89. package/themes/cyberpunk.json +79 -79
  90. package/themes/gamer.json +77 -77
  91. package/themes/imperial.json +82 -82
  92. package/themes/joker.json +79 -79
  93. package/themes/marvin.json +82 -82
  94. package/themes/mean.json +82 -82
  95. package/themes/military.json +78 -78
  96. package/themes/neutral.json +78 -78
  97. package/themes/pirate.json +79 -79
  98. package/themes/sports.json +79 -79
  99. package/themes/verstappen.json +78 -78
  100. package/themes/wizard.json +79 -79
  101. package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
  102. package/web/dist/assets/Activity-CqJiquEq.js +1 -0
  103. package/web/dist/assets/ActivityDetail-BSzevynX.js +1 -0
  104. package/web/dist/assets/{Bonsai-DSwUbavu.js → Bonsai-Bfpb6W-1.js} +1 -1
  105. package/web/dist/assets/{CopyButton-BzRQz7k2.js → CopyButton-ByIntFtB.js} +1 -1
  106. package/web/dist/assets/Dashboard-DBOEi9lQ.js +2 -0
  107. package/web/dist/assets/Docs-DvlMJhpu.js +5 -0
  108. package/web/dist/assets/Factories-Bpvv7L2H.js +1 -0
  109. package/web/dist/assets/{GreenhouseView-y9WAfcc_.js → GreenhouseView-GpBsYn50.js} +1 -1
  110. package/web/dist/assets/Installs-BlGmVrFK.js +3 -0
  111. package/web/dist/assets/{JournalView-DeBLRNGc.js → JournalView-iLuLrOxE.js} +1 -1
  112. package/web/dist/assets/Kits-DRwpxC-J.js +1 -0
  113. package/web/dist/assets/Laws-CZkiNOWQ.js +4 -0
  114. package/web/dist/assets/LibRows-DEHjIoD-.js +1 -0
  115. package/web/dist/assets/Library-B4K-1iNF.js +3 -0
  116. package/web/dist/assets/Loops-BWSzaW8E.js +2 -0
  117. package/web/dist/assets/{OperatorHudView-2ujVMjq1.js → OperatorHudView-BAXwCEvY.js} +1 -1
  118. package/web/dist/assets/Personal-Bp9nV4GR.js +2 -0
  119. package/web/dist/assets/Settings-CWWuaIp-.js +1 -0
  120. package/web/dist/assets/Tabs-CWeQTADL.js +1 -0
  121. package/web/dist/assets/index-CsAZq0BQ.css +1 -0
  122. package/web/dist/assets/index-How7SzDZ.js +6 -0
  123. package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
  124. package/web/dist/index.html +2 -2
  125. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
  126. package/web/dist/assets/Activity-DlQ30znB.js +0 -1
  127. package/web/dist/assets/ActivityDetail-CG0mn5fW.js +0 -1
  128. package/web/dist/assets/Dashboard-Ce3UOsxJ.js +0 -2
  129. package/web/dist/assets/Docs-CisVnYqv.js +0 -5
  130. package/web/dist/assets/Factories-Dq5oW4CU.js +0 -1
  131. package/web/dist/assets/Installs-m4GElwFW.js +0 -3
  132. package/web/dist/assets/Kits-DJYVAnyE.js +0 -1
  133. package/web/dist/assets/Laws-CNpc_8ZV.js +0 -4
  134. package/web/dist/assets/LibRows-RO5bvXth.js +0 -1
  135. package/web/dist/assets/Library-Dg0ScciC.js +0 -3
  136. package/web/dist/assets/Loops-CjEdo-NG.js +0 -2
  137. package/web/dist/assets/Personal-D0yS7ahT.js +0 -2
  138. package/web/dist/assets/Settings-DEN0U8QI.js +0 -1
  139. package/web/dist/assets/Tabs-But5R6_r.js +0 -1
  140. package/web/dist/assets/index-Ck42AbRX.js +0 -6
  141. package/web/dist/assets/index-PG_ukkh6.css +0 -1
  142. package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
package/CHANGELOG.md CHANGED
@@ -8,6 +8,33 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ## [5.3.0] — 2026-11-11
12
+
13
+ ### Added
14
+ - **A factory run records its times, and `geneseed factory report` prints its numbers.** `init` stamps `started`, and `record` and `decide` stamp `at` on their history entry. `record --tokens <n>` stores the token count the host reported for the stage's agent; nothing estimates one, and there is no cost in money. `report` is read-only and prints one JSON object: per stage its runs, its reworks (an outcome that spent a cycle), its work time and its tokens, and for the run its work time, the time it waited at human gates, its tokens and its transitions. A number nobody recorded is `null`, never 0, so a `FACTORY.md` written before this release still validates and still runs. The `retro` brick and the Rite's stop report copy those numbers, and `retro` adds how many rounds each `review-panel` seat failed.
15
+ - **The factory queue.** Ask the agent for the queue, or name no work item: the `factory` Rite lists the open issues that carry the label `factory` (or the label you name) and you pick one, several or all. Several picks run in sequence, each as its own run in its own worktree with its own merge question; a run that holds a gate holds the queue. No config file, and nothing starts a run by itself.
16
+ - **`intake` can refuse a work item.** The new outcome `reject` holds the gate when the item is already done, a duplicate, or against a rule the project states, with the reason and its evidence: `ok` accepts the refusal and stops the run, `amend` re-runs `intake` with your reason to build it, `no` stops. The three shipped factories route `reject` to `$stop`. A factory with no `reject` edge still passes `check` and stops the same way, so a factory of your own, and a run already in flight, need no change. `reject` names no lane: `intake` stays a plain stage.
17
+ - **Factories › Active is a board.** With no run selected, the console shows every registered run as a card in three columns: **Waits for you** (a held gate, or a `FACTORY.md` that cannot be read), **Running**, and **Ended**. A card gives, on one line, where the run stands (a held gate as `stage · outcome`), its task as `i/n`, its work time, the wait still open at its gate, and each cycle spent above 0 as `name n/max`; the list rows carry the same line, and the list's header names an open run by its title, not its root path. `geneseed factory report` and the board add `openWaitMs`, the wait still open at a held gate, measured to the time of the call or the poll. A card opens the run, which gains a timeline: each history entry with its outcome or your answer, its time, its duration and a rework mark, and for a held run the gate's stage, outcome and the path of its note. `GET /api/factories/active` adds `metrics` to each live run. The board is read-only: you answer a gate in the agent's session. Its poll no longer writes `factories.json` either (it used to stamp a closed run and drop old rows every 5 s, and could race a `factory init`): `geneseed factory init` now does that tidying, dropping a run whose worktree is gone and a closed run 7 days after an init first saw it closed.
18
+ - **`geneseed --version`, `help [verb]`, and a nearest match for a mistyped verb.** `geneseed stauts` answers `unknown command 'stauts'. Did you mean 'status'?`. `build --help` and `validate --help` list every flag with its choices, read from the generator instead of a copy. A verb's long help moved to a `description` its own `--help` and the console's CLI page show; top-level help is one line per verb.
19
+ - **`doctor` prints one progress line per theme on stderr during a sweep.** stdout is unchanged.
20
+
21
+ ### Changed
22
+ - **The always-on catalogue is about 1 500 tokens lighter.** Every theme's skill and agent purpose line is about 40-60 characters, followed by the unchanged "Use when" trigger; the ten council seats are one line each. Measured on a Claude emit, imperial: 17 964 -> about 12 100 characters.
23
+ - **The lean root is lighter and says one thing about commits.** Consent Before Push gains a batch for a dispatched worker, crew or slice: it commits in its own worktree, never pushes, never merges outside its own branch. The commit, pipeline and parallel-agents Rites, the developer spec and Foreman mode now agree, and a Rite never loosens a Doctrina. Repeated always-on text is trimmed, and three clauses the lean text had lost are back.
24
+ - **Lean drops the Latin rule names and the section epigraphs.** `### Dictate I — Sealed Secrets` instead of `— Arcana Sigillata · Sealed Secrets`; the full footprint and the on-disk `laws/` and `doctrines/` keep the voice. The two "given in brief" notes are one. About -400 tokens on the imperial theme.
25
+ - **SessionStart and SubagentStart no longer send the untouched `user-rules.md` seed explanation** above your first rule (1 690 -> 315 bytes for a seed with two rules), on Claude Code and in the OpenCode context plugin. Text you wrote above your rules is still sent.
26
+ - **`status` piped or redirected prints no box and no padding** (4 783 -> 1 378 bytes on a typical machine).
27
+ - **`version`, `diff` and `uninstall` default to the one install there is.** With several global installs and no `--target`, `uninstall` refuses with exit 2 and lists the targets, also with `--yes`. On a machine with only a Claude install, `uninstall --yes` now removes it (it used to aim at an empty OpenCode folder and exit 1).
28
+ - **`tui` is retired and `bootstrap` is `upgrade --setup`.** Both still work for one release: `tui` points at `geneseed menu`, `bootstrap` prints a deprecation line and runs the same flow. `upgrade --theme NAME` is added.
29
+ - CI runs the Ubuntu suite once under c8 instead of a separate coverage job, and a new `suite-count` job requires the Windows shards' summed test count to reach the whole-suite floor.
30
+
31
+ ### Fixed
32
+ - **A very long command no longer outruns the hook gates.** Two gate regexes were quadratic: a 540 KB command took about 80 s, past the host's hook time-out, and the call went through unguarded. Both are linear with the same verdicts, and a command over 64 KB makes the gate ask before it reads it. The OpenCode guard gets the same regex.
33
+ - **A large `apply_diff` (Bob) no longer outruns the secrets gate.** The diff is read in one pass, and a diff over 64 KB asks.
34
+ - **A gate whose module fails to load asks instead of letting the call through.** A non-gate verb that fails writes one line on stderr and stays silent on stdout.
35
+ - **The console no longer freezes for about 12 s after a job.** The doctor runs on a worker thread for the daemon and for every per-install view (the Doctor page), and a worker that dies records a failed verdict instead of respawning on every poll.
36
+ - Console: truncated labels show their full text on hover; a failed Ledger read says why and offers a Retry that keeps focus; polls that return the same data no longer re-render; a Popover closes when Tab leaves it; the Loops jump respects reduced motion; a failed profile read says so.
37
+
11
38
  ## [5.2.0] — 2026-11-10
12
39
 
13
40
  ### Changed
package/README.md CHANGED
@@ -166,7 +166,7 @@ Full reference — every view, the launch/daemon/PWA surface, the security model
166
166
 
167
167
  ### ⌨️ Terminal — `geneseed`
168
168
 
169
- No browser? Every action the console offers is also a verb: `build`, `doctor`, `diff`, `rebuild-all`, `status`, `memory`, `catalog`, `exclude`, `mcp`, `link`/`unlink`, `uninstall` (global **or** per-repo). `geneseed setup` runs the install wizard — plain text prompts, every console, every OS; see [Setup](#-2--setup) above for the walkthrough. `geneseed --help` lists every command, and bare `geneseed` (or `./geneseed`) opens the web console when it can, else prints the command list. There is no full-screen panel: `tui` and `menu` are verbs that say so and print the command list.
169
+ No browser? Every action the console offers is also a verb: `build`, `doctor`, `diff`, `rebuild-all`, `status`, `memory`, `catalog`, `exclude`, `mcp`, `link`/`unlink`, `uninstall` (global **or** per-repo). `geneseed setup` runs the install wizard — plain text prompts, every console, every OS; see [Setup](#-2--setup) above for the walkthrough. `geneseed --help` lists every command, and bare `geneseed` (or `./geneseed`) opens the web console when it can, else prints the command list. There is no full-screen panel: `menu` prints the command list (`tui` is retired, and says so).
170
170
 
171
171
  ---
172
172
 
@@ -336,7 +336,7 @@ geneseed rebuild-all # re-render every registered install in its own theme + m
336
336
 
337
337
  ```bash
338
338
  ./geneseed update # everything in one: refresh the scripts + content, then rebuild
339
- ./geneseed bootstrap # update everything, then drop into the setup wizard
339
+ ./geneseed upgrade --setup # update everything, then drop into the setup wizard (was: bootstrap)
340
340
  ./geneseed upgrade # just the content refresh (remembers theme + emit mode)
341
341
  ```
342
342
 
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: **5.2.0**.
23
+ > string. Current label: **5.3.0**.
24
24
 
25
25
  ## Capabilities
26
26
 
@@ -284,12 +284,38 @@ async function draftLine() {
284
284
  } catch { return null }
285
285
  }
286
286
 
287
+ // ---- rules preamble twin: BEGIN — adapters/opencode/plugins/geneseed-context.js carries everything
288
+ // down to the END marker verbatim, with `export ` dropped (node tests/twins.mjs --write keeps it).
289
+
290
+ /**
291
+ * SHA-256 of the `user-rules.md` seed with its trailing newlines trimmed: the explanation every
292
+ * rules file starts with, until its owner edits it. Hashed, not imported, for `SEED_SHA256`'s
293
+ * reason; tests/unit/claude.test.mjs derives it from `SESSION_SEEDS`.
294
+ */
295
+ const RULES_PREAMBLE_SHA256 = 'd6973e837c9bf25b50ce068832ceef0a5e5ed2b5931c2c488428ad68aad758c3';
296
+ // A rule's heading, at column 0: the seed's own example (` ## R1 — …`) is indented.
297
+ const RULE_HEADING_RE = /^## R\d+\b/m;
298
+
299
+ /**
300
+ * `text` from its first rule on, when the text above that rule is still the seed's, byte for byte
301
+ * once CRLF is folded: the seed explains the file to its owner, and it cost 1 331 of 4 474
302
+ * characters at every session and sub-agent start. Any prose the owner wrote above the rules stays.
303
+ */
304
+ function withoutRulesPreamble(text) {
305
+ const rule = RULE_HEADING_RE.exec(text);
306
+ const head = rule ? text.slice(0, rule.index).replace(/\n+$/, '') : null;
307
+ return head !== null && createHash('sha256').update(head).digest('hex') === RULES_PREAMBLE_SHA256
308
+ ? text.slice(rule.index) : text;
309
+ }
310
+ // ---- rules preamble twin: END
311
+
287
312
  // A session file's text, CRLF-folded and trimmed; null when missing, unreadable or still its seed.
313
+ // A rules file's seed explanation above its first rule is dropped, as on the hook.
288
314
  async function sessionText(abs) {
289
315
  let text
290
316
  try { text = (await fs.readFile(abs, "utf8")).replace(/\r\n/g, "\n") } catch { return null }
291
317
  if (SEED_SHA256.has(createHash("sha256").update(text).digest("hex"))) return null
292
- return text.replace(/\n+$/, "")
318
+ return withoutRulesPreamble(text).replace(/\n+$/, "")
293
319
  }
294
320
 
295
321
  // Session files in force for the harness dir, changed from their seed: [{ rel, abs, text, label }],
@@ -947,6 +973,22 @@ async function cachedBlockText(root, cache) {
947
973
  return text
948
974
  }
949
975
 
976
+ // Per INSTANCE, as `cache` above, and keyed by directory: `sovereignBypass` (two JSON reads)
977
+ // and `doneChecksOf` (manifest reads) ran on EVERY request while the block they gate is cached
978
+ // for BLOCK_TTL_MS, so they get the same TTL. A rejection is not kept: the next call retries.
979
+ function ttlMemo(fn) {
980
+ const hits = new Map()
981
+ return (key) => {
982
+ const now = Date.now()
983
+ const hit = hits.get(key)
984
+ if (hit && now - hit.at < BLOCK_TTL_MS) return hit.p
985
+ const p = Promise.resolve().then(() => fn(key))
986
+ hits.set(key, { p, at: now })
987
+ p.catch(() => { if (hits.get(key)?.p === p) hits.delete(key) })
988
+ return p
989
+ }
990
+ }
991
+
950
992
  // ---- cross-instance idempotency ----------------------------------------------
951
993
  async function alreadyInjected(client, sid) {
952
994
  try {
@@ -1372,6 +1414,8 @@ export const GeneseedContext = async (ctx) => {
1372
1414
  const done = new Set()
1373
1415
  const root = repoRoot(ctx)
1374
1416
  const blockCache = { text: null, at: 0 }
1417
+ const bypassed = ttlMemo(sovereignBypass)
1418
+ const doneChecks = ttlMemo(doneChecksOf)
1375
1419
 
1376
1420
  // Visible delivery — post the block as a noReply session message. Used when
1377
1421
  // GENESEED_CONTEXT_VISIBLE forces it, and by the transform fallback below.
@@ -1430,7 +1474,7 @@ export const GeneseedContext = async (ctx) => {
1430
1474
 
1431
1475
  event: async ({ event }) => {
1432
1476
  if (!event || INJECT_OFF) return
1433
- if (await sovereignBypass(root)) return
1477
+ if (await bypassed(root)) return
1434
1478
  const sid =
1435
1479
  event.properties?.sessionID ?? event.payload?.sessionID ??
1436
1480
  event.properties?.info?.id ?? event.payload?.info?.id
@@ -1459,7 +1503,7 @@ export const GeneseedContext = async (ctx) => {
1459
1503
  // OpenCode hook; if it is absent in a build this key is simply never called.
1460
1504
  "experimental.session.compacting": async (_input, output) => {
1461
1505
  if (INJECT_OFF || (TRANSFORM && !fallbackVisible)) return
1462
- if (await sovereignBypass(root)) return
1506
+ if (await bypassed(root)) return
1463
1507
  try {
1464
1508
  const { block } = await resolveBlock(root)
1465
1509
  if (block && output && Array.isArray(output.context)) {
@@ -1482,13 +1526,13 @@ export const GeneseedContext = async (ctx) => {
1482
1526
  // both end on an empty request, an excluded repo, or a skipped session.
1483
1527
  if (!output || !Array.isArray(output.messages) || !output.messages.length) return
1484
1528
  const sid = output.messages[0]?.info?.sessionID
1485
- if (await sovereignBypass(root) || await skipSession(sid)) return
1529
+ if (await bypassed(root) || await skipSession(sid)) return
1486
1530
  // The done gate's reminder: FIRST, and independent of the context block:
1487
1531
  // INJECT_OFF and the visible delivery leave it on, and no early return below can skip it.
1488
1532
  // Its own function, so its early returns end the reminder, never the context injection.
1489
1533
  await (async () => {
1490
1534
  if (await doneGateOff()) return
1491
- const { root: gitRoot, source, blocking, checks } = await doneChecksOf(root)
1535
+ const { root: gitRoot, source, blocking, checks } = await doneChecks(root)
1492
1536
  if (!checks.length) return
1493
1537
  const owed = doneOwed(output.messages, checks, gitRoot)
1494
1538
  if (!owed.length) return
@@ -1562,6 +1606,8 @@ async function setupV2(ctx) {
1562
1606
  const root = repoRoot({ worktree: ctx?.location?.project?.directory, directory: ctx?.location?.directory })
1563
1607
  // `judged: false`: OpenCode 2 never judges a turn, so the done line claims no verdict.
1564
1608
  const blockCache = { text: null, at: 0, judged: false }
1609
+ const bypassed = ttlMemo(sovereignBypass)
1610
+ const doneChecks = ttlMemo(doneChecksOf)
1565
1611
  // Same scope rule as V1's skipSession. V2's info names the parent `parentID` only, so only
1566
1612
  // that and the title are passed on.
1567
1613
  const skipSession = sessionSkipper(async (sid) => {
@@ -1571,7 +1617,7 @@ async function setupV2(ctx) {
1571
1617
 
1572
1618
  // The done gate is not judged on OpenCode 2 (see `doneOwed`): said once, where its log goes.
1573
1619
  // The listed gate only: an inferred one would log in every repo with a manifest.
1574
- if (!(await doneGateOff()) && await doneChecksOf(root).then((d) => d.blocking && d.checks.length, () => false)) {
1620
+ if (!(await doneGateOff()) && await doneChecks(root).then((d) => d.blocking && d.checks.length, () => false)) {
1575
1621
  console.error(`[geneseed-context] done gate: ${DONE_LIST} found, but OpenCode 2 turns are not judged.`)
1576
1622
  }
1577
1623
 
@@ -1582,7 +1628,7 @@ async function setupV2(ctx) {
1582
1628
  })
1583
1629
  const remindWeakened = async (event) => {
1584
1630
  try {
1585
- if (!Array.isArray(event?.messages) || await sovereignBypass(root) || await doneGateOff()) return
1631
+ if (!Array.isArray(event?.messages) || await bypassed(root) || await doneGateOff()) return
1586
1632
  if (await skipSession(event.sessionID)) return
1587
1633
  const weakened = takeWeakened(event.sessionID)
1588
1634
  if (weakened) event.messages.unshift(v2UserMessage(event.messages, weakened))
@@ -1598,7 +1644,7 @@ async function setupV2(ctx) {
1598
1644
  await remindWeakened(event)
1599
1645
  if (INJECT_OFF) return
1600
1646
  try {
1601
- if (await sovereignBypass(root)) return
1647
+ if (await bypassed(root)) return
1602
1648
  if (!Array.isArray(event?.messages) || v2HasMarker(event.messages)) return
1603
1649
  if (await skipSession(event.sessionID)) return
1604
1650
  const cached = await cachedBlockText(root, blockCache)
@@ -1617,7 +1663,7 @@ async function setupV2(ctx) {
1617
1663
  await ctx.session.hook("compaction", async (event) => {
1618
1664
  if (INJECT_OFF) return
1619
1665
  try {
1620
- if (await sovereignBypass(root)) return
1666
+ if (await bypassed(root)) return
1621
1667
  if (!Array.isArray(event?.messages) || await skipSession(event.sessionID)) return
1622
1668
  const { block } = await resolveBlock(root, false)
1623
1669
  if (block) event.messages.unshift(v2UserMessage(event.messages, block.text))
@@ -1632,7 +1678,7 @@ async function setupV2(ctx) {
1632
1678
  const d = ev.data ?? {}
1633
1679
  try {
1634
1680
  if (isSkippedSession({ parentID: d.parentID, title: d.title })) continue
1635
- if (await sovereignBypass(root)) continue
1681
+ if (await bypassed(root)) continue
1636
1682
  const { block } = await resolveBlock(root, false)
1637
1683
  if (!block) continue
1638
1684
  await ctx.session.synthetic({
@@ -356,9 +356,14 @@ function stashExists(root) {
356
356
  * a spawn. A git destructive VERB anywhere after `git` on the same line, or a removal program
357
357
  * as a word at a command boundary. Deliberately loose — the parse decides; this only has to be
358
358
  * a superset of what the parse acts on.
359
+ *
360
+ * The git half is LINEAR: it starts only at the input's start or a `\n` and tries the line's
361
+ * first `git` alone, which matches whenever any later `git` would. `\bgit\b[^\n]*\b(?:…)` from
362
+ * every `git` was quadratic: a 270 KB `git -C x …` took seconds, and a hook past its timeout
363
+ * lets the call through. `(?<![\s\S])`, not `^`: under `m`, `^` also starts after `\r`.
359
364
  */
360
365
  const LOSS_CANDIDATE_RE =
361
- /\bgit\b[^\n]*\b(?:reset|clean|branch|checkout|switch|restore|stash|reflog|gc|push)\b|(?:^|[\s;&|("'`])(?:rm|rmdir|unlink|del|erase|remove-item|ri|rd)(?:\.exe)?(?=[\s;&|)"'`]|$)|(?:^|\s)-delete(?=\s|$)/im;
366
+ /(?:(?<![\s\S])|\n)(?:(?!\bgit\b)[^\n])*\bgit\b[^\n]*\b(?:reset|clean|branch|checkout|switch|restore|stash|reflog|gc|push)\b|(?:^|[\s;&|("'`])(?:rm|rmdir|unlink|del|erase|remove-item|ri|rd)(?:\.exe)?(?=[\s;&|)"'`]|$)|(?:^|\s)-delete(?=\s|$)/im;
362
367
 
363
368
  class Unverified extends Error {}
364
369
  const unverified = (why) => { throw new Unverified(why); };
@@ -55,7 +55,8 @@
55
55
  // whole graph: `tests/unit/hook_cli.test.mjs`'s `importClosure` follows both import spellings.
56
56
  // FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
57
57
  import '../js/lib/node-floor.mjs';
58
- import { cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
58
+ import { readFileSync } from 'node:fs';
59
+ import { cliCommand, cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
59
60
  import { parseIntStrict } from '../js/lib/text.mjs';
60
61
  import { printErr, printOut } from '../js/lib/fs.mjs';
61
62
 
@@ -73,8 +74,8 @@ import { printErr, printOut } from '../js/lib/fs.mjs';
73
74
  *
74
75
  * IT IS STILL A TABLE and still the DISPATCH rather than a declaration beside one.
75
76
  * `tests/unit/hook_cli.test.mjs` scrapes `const VERBS = {` for its matrix gates, and
76
- * `main`'s refusal lists `Object.keys(VERBS)` IN THIS ORDER (no cell asserts the list
77
- * verbatim any more) — the order is the old table's and is not alphabetical.
77
+ * `main`'s unknown-verb refusal draws its nearest-match suggestion from `Object.keys(VERBS)`
78
+ * (it no longer prints the list) — the order is the old table's and is not alphabetical.
78
79
  *
79
80
  * FLATTENED TO `verb: fn` since Task 5, AND TO `verb: loader` since the lazy pass: every row
80
81
  * is now a thunk that imports the command's module and resolves to its function, so the one
@@ -115,13 +116,9 @@ const VERBS = {
115
116
  // argues both.
116
117
  menu: () => import('../js/ui/menu.mjs').then((m) => m.cmdMenu),
117
118
  home: () => import('../js/ui/menu.mjs').then((m) => m.cmdHome),
118
- // P7b, and it is the twenty-fifth and last. `cmd_tui`'s FIRST arm is `if not sys.stdin.
119
- // isatty()`, so off a TTY — which is every cell there is — the verb is one line and an
120
- // exit code, and that arm crosses byte for byte. The panel behind it is P7c's;
121
- // `js/ui/tui.mjs`'s header argues why this entry falls back to `cmd_tui`'s own
122
- // panel-unavailable line rather than inventing a second full-screen UI, and
123
- // `tests/unit/no_panel.test.mjs` asserts that no panel lies behind it — the module paints
124
- // nothing and refuses on a TTY too — rather than leaving that merely untested.
119
+ // RETIRED: there was never a panel behind it, so it refused on every terminal. Kept one
120
+ // release as an alias that prints one line pointing at `menu` and exits 0, as `menu` does off
121
+ // a terminal; `tests/unit/no_panel.test.mjs` asserts the module still paints nothing.
125
122
  tui: () => import('../js/ui/tui.mjs').then((m) => m.cmdTui),
126
123
  // THE THREE THAT NEVER HAD A PYTHON ORIGINAL, and they are last for that reason rather
127
124
  // than by alphabet: every row above is the twin of a subparser, and these three are not.
@@ -155,6 +152,34 @@ const VERBS = {
155
152
  scorecard: () => import('../js/inspect/scorecard.mjs').then((m) => m.cmdScorecard),
156
153
  };
157
154
 
155
+ /** Levenshtein distance, for the one "did you mean" an unknown verb gets. */
156
+ function editDistance(a, b) {
157
+ let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
158
+ for (let i = 1; i <= a.length; i += 1) {
159
+ const cur = [i];
160
+ for (let j = 1; j <= b.length; j += 1) {
161
+ cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
162
+ }
163
+ prev = cur;
164
+ }
165
+ return prev[b.length];
166
+ }
167
+
168
+ /**
169
+ * The closest verb to a mistyped one, or null when nothing is close. Close is at most a third
170
+ * of the typed word's length (and at least 1), so `stauts` finds `status` and `frobnicate`
171
+ * finds nothing: a suggestion for every typo is noise, not help.
172
+ */
173
+ function nearestVerb(typed, verbs) {
174
+ let best = null;
175
+ let bestD = Math.max(1, Math.floor(typed.length / 3)) + 1;
176
+ for (const v of verbs) {
177
+ const d = editDistance(typed, v);
178
+ if (d < bestD) { best = v; bestD = d; }
179
+ }
180
+ return best;
181
+ }
182
+
158
183
  function die(code, msg) {
159
184
  // CRLF on Windows, for the same reason `js/hosts/hooks.mjs`'s funnels translate: argparse writes
160
185
  // this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
@@ -293,11 +318,24 @@ async function main(argv) {
293
318
  // Bare = `home`, as both launchers (`geneseed`, `geneseed.cmd`) already did — but the npm
294
319
  // `bin` names THIS file, so a bare `geneseed` off PATH used to die asking for a verb.
295
320
  if (!argv.length) argv = ['home'];
321
+ // The package version, which `geneseed version` does NOT print: that verb compares the
322
+ // install's build fingerprint with this source's. Read off the package.json beside this file,
323
+ // so it is the version npm installed, and answered before the shim check.
324
+ if (argv[0] === '--version' || argv[0] === '-V') {
325
+ const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
326
+ printOut(`geneseed ${pkg.version}\n`);
327
+ return 0;
328
+ }
329
+ // `help` and `help <verb>` are spellings of `--help` and `<verb> --help`, and nothing more:
330
+ // a rewrite here rather than a VERBS row, because a row would owe the table a subcommand.
331
+ // `help help` is the listing too: `help` is not a VERBS row, so it has no help of its own.
332
+ if (argv[0] === 'help') argv = argv.length > 1 && argv[1] !== 'help' ? [argv[1], '--help'] : ['--help'];
296
333
  const verb = argv[0];
297
334
  if (verb === '-h' || verb === '--help') {
298
- return printVerbList('geneseed', [...Object.keys(VERBS), 'validate'], {
335
+ return printVerbList('geneseed', [...Object.keys(VERBS), 'validate', 'help'], {
299
336
  update: 'an alias of upgrade',
300
337
  validate: "check the source tree without emitting (the generator's --validate-only)",
338
+ help: "this list; help <command> prints that command's help",
301
339
  });
302
340
  }
303
341
  // A DEAD HOOK SHIM, SAID ON EVERY RUN. The shim is machine-wide, so one stale write turns off
@@ -323,12 +361,12 @@ async function main(argv) {
323
361
  if (verb === 'validate') {
324
362
  // Lazy for the same reason the table rows are — `parseDriverArgs` alone drags the whole
325
363
  // generator driver in, and every OTHER verb was paying for it.
326
- const [{ cmdValidate, VALIDATE_USAGE }, { parseDriverArgs }] = await Promise.all([
364
+ const [{ cmdValidate, validateUsage }, { parseDriverArgs }] = await Promise.all([
327
365
  import('../js/inspect/validate.mjs'), import('../js/build/driver.mjs'),
328
366
  ]);
329
367
  // Before the borrowed parser, whose own `-h` prints the GENERATOR's usage.
330
368
  if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
331
- printOut(VALIDATE_USAGE);
369
+ printOut(validateUsage());
332
370
  return 0;
333
371
  }
334
372
  try {
@@ -345,9 +383,16 @@ async function main(argv) {
345
383
  // named, the two entry points now cover every subcommand there is, so the clause was not
346
384
  // just about to become false — it was already claiming a third place for verbs that do
347
385
  // not exist.
348
- return die(2, `invalid choice: '${verb}'. This entry point carries only `
349
- + `${Object.keys(VERBS).join(', ')}; the six hook verbs live in `
350
- + 'bin/geneseed-hook.mjs.');
386
+ //
387
+ // A hook verb (`context`, `tool-gate`, …) is in the table but not here: the emitted
388
+ // settings call it through `geneseed-hook`, and saying so beats "unknown command".
389
+ if (cliCommand(verb) !== null) {
390
+ return die(2, `'${verb}' is a hook verb: the host runs it through geneseed-hook `
391
+ + '(bin/geneseed-hook.mjs), not this command. See geneseed --help.');
392
+ }
393
+ const near = nearestVerb(verb, [...Object.keys(VERBS), 'validate', 'help']);
394
+ return die(2, `unknown command '${verb}'.${near ? ` Did you mean '${near}'?` : ''} `
395
+ + 'See geneseed --help.');
351
396
  }
352
397
  // `js/cli-table.json`, the CLI as data. A verb this table dispatches and the file does not
353
398
  // describe is a REFUSAL and not a parse with no rules: an empty spec would accept every
@@ -50,10 +50,10 @@
50
50
  import '../js/lib/node-floor.mjs';
51
51
  // Not a new module on the hot path: every verb's module imports `js/lib/fs.mjs` too, so this
52
52
  // edge only loads early a file the process would load anyway.
53
- import { printErr } from '../js/lib/fs.mjs';
53
+ import { printErr, printOut } from '../js/lib/fs.mjs';
54
54
  // Also not a new module: every verb's module imports it. It carries the activity switch, so the
55
55
  // off path costs one file read and no import of the writer.
56
- import { activityOn, readStdin } from '../js/hosts/hooks-prims.mjs';
56
+ import { activityOn, askDecision, gateSafe, readStdin } from '../js/hosts/hooks-prims.mjs';
57
57
  import { isatty } from 'node:tty';
58
58
  import path from 'node:path';
59
59
 
@@ -163,6 +163,35 @@ async function trackActivity(verb, args) {
163
163
  } catch { /* the activity view is best-effort; a hook that fails is a tool call that fails */ }
164
164
  }
165
165
 
166
+ /**
167
+ * A verb whose module failed to load, or threw past its own guard. `guardGate` only covers a gate
168
+ * once its module has loaded; a module that cannot (a file missing mid-`git pull` under the shared
169
+ * shim, a syntax error) used to exit 1 with nothing on stdout, which Claude reads as "the gate
170
+ * deferred". So a gate verb gives the gate-error verdict `guardGate` gives — an ask on Claude and
171
+ * OpenClaude, a stderr warning on Bob, where gate-error is never a block — built from
172
+ * `./hooks-prims.mjs`, which the entry has already loaded. Not ledgered: the ledger's writer is
173
+ * in the module that failed. Every other verb exits 0 with stdout empty and one stderr line, so a
174
+ * broken context hook shows in the host's hook log: stdout is the only channel any host reads as
175
+ * a decision, and on Bob too a stderr line with exit 0 is a log entry (the gates' Bob warnings
176
+ * already are). The residual limit: a
177
+ * module this file imports statically (`fs.mjs`, `hooks-prims.mjs`) fails at link time, before
178
+ * any of this runs.
179
+ */
180
+ function verbFailed(verb, args, e) {
181
+ let name = e;
182
+ try { name = e.message || e; } catch { /* `gateSafe` meets `e` as it is */ }
183
+ if (!GATE_VERBS.has(verb)) {
184
+ try { printErr(`[geneseed-hook] ${verb} failed: ${name}\n`); } catch { /* an unprintable error says nothing */ }
185
+ return 0;
186
+ }
187
+ if (args.host === 'bob') {
188
+ printErr(`[geneseed] ${gateSafe('gate-error', 'warned', { name })}\n`);
189
+ return 0;
190
+ }
191
+ printOut(askDecision(gateSafe('gate-error', 'ask', { name })));
192
+ return 0;
193
+ }
194
+
166
195
  function die(code, msg) {
167
196
  // CRLF on Windows, for the same reason the hook verbs' funnels translate: argparse
168
197
  // writes this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
@@ -270,7 +299,12 @@ async function main(argv) {
270
299
  if (verb === 'context' && !isatty(0)) {
271
300
  try { parsed.args.event = JSON.parse(readStdin() || '{}').hook_event_name ?? null; } catch { /* not JSON: SessionStart */ }
272
301
  }
273
- const rc = (await spec.load())[spec.fn](parsed.args);
302
+ let rc;
303
+ try {
304
+ rc = (await spec.load())[spec.fn](parsed.args);
305
+ } catch (e) {
306
+ return verbFailed(verb, parsed.args, e);
307
+ }
274
308
  await trackActivity(verb, parsed.args);
275
309
  await baselineStores(verb, parsed.args);
276
310
  return rc;
@@ -44,7 +44,7 @@ but its first stage, or a route back that spends no cycle.
44
44
  ## Forks and lanes
45
45
 
46
46
  A **fork** is where the work takes one way or another. It is a brick that declares **named
47
- outcomes**, any outcome other than `pass`, `fail`, `error`, `none` or `needs-info`. `triage` is one: `bug`,
47
+ outcomes**, any outcome other than `pass`, `fail`, `error`, `none`, `needs-info` or `reject`. `triage` is one: `bug`,
48
48
  `feature`, `deps`, `refactor`, `docs` and `fail`. Each named outcome has its own edge to its own
49
49
  stage, its **lane**, and the outcome the brick reports picks the lane. `geneseed factory next`
50
50
  hands the fork its `lanes`: each outcome with the stage it leads to.
@@ -76,6 +76,37 @@ exception is the run's spec, `specs/<slug>/spec.md`: the `spec` stage writes it,
76
76
  it is committed once you approve it, before the first loop. Each run is listed in `factories.json` beside the loop registry, and each child loop's row
77
77
  names the run it belongs to.
78
78
 
79
+ ## The queue, and a refused item
80
+
81
+ A run takes one work item. To pick from several, ask the agent for the **queue**: it lists the
82
+ open issues that carry the label `factory` (or a label you name), and you pick one, several or
83
+ all. Several picks run one after the other, in the order you gave, each as its own run in its
84
+ own worktree, each with its own merge question. A run that holds a gate holds the queue. An
85
+ issue's text is the run's input, never an instruction to the agent. No file configures the queue,
86
+ and nothing starts a run by itself.
87
+
88
+ `intake` may also **refuse** an item, with the outcome `reject`: it is already done, it duplicates
89
+ another issue or pull request, or it goes against a rule the project states. The run holds and
90
+ shows you the reason and its evidence. `ok` accepts the refusal and stops the run, `amend` runs
91
+ `intake` again with your reason to build it, and `no` stops too. In each shipped factory the
92
+ `reject` edge goes to `$stop`; a factory of your own that has no such edge stops the same way.
93
+
94
+ ## What a run measures
95
+
96
+ Every `record` and `decide` writes the time on its history entry, and `init` writes when the run
97
+ started. From those, `geneseed factory report` gives each stage its runs, its reworks, its work
98
+ time and its tokens, and the run its work time and the time it waited for you at a gate. The time
99
+ between a held outcome and your answer is waiting time, never the stage's. A rework is an outcome
100
+ that spent a cycle: a failed `checks`, `review-panel` or `holdout`, or red CI.
101
+
102
+ Tokens are recorded only where the host reports a count for the agent that ran the stage
103
+ (`record --tokens <n>`); nothing estimates one, and a loop stage carries none. There is no cost in
104
+ money: Geneseed holds no price table. A number nobody recorded is `null` in the report, never 0,
105
+ so a `FACTORY.md` written before times were stamped still runs and reports `unknown`.
106
+
107
+ The `retro` stage copies those numbers into the run report, and adds, for each `review-panel`
108
+ seat, how many rounds it failed.
109
+
79
110
  ## The shipped factories
80
111
 
81
112
  | Factory | Stages |
@@ -88,7 +119,7 @@ The bricks they add:
88
119
 
89
120
  | Brick | Does | Outcomes |
90
121
  | --- | --- | --- |
91
- | `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria, its `size` and its `areas`. `needs-info` holds for your answers to its questions (`gate: human`) | `pass`, `fail`, `needs-info` |
122
+ | `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria, its `size` and its `areas`. `needs-info` holds for your answers to its questions, and `reject` holds when it finds the item already done, a duplicate, or against a rule the project states, with the reason and its evidence (`gate: human`). It never posts on the issue | `pass`, `fail`, `needs-info`, `reject` |
92
123
  | `holdout-write` | Writes 3 to 8 prose scenarios (given / when / then) for the work item into the holdout folder, outside the worktree, and hands the work item on unchanged | `pass`, `fail` |
93
124
  | `holdout` | Plays every scenario against the built change. `fail` carries one sentence per failed scenario, observed against expected; `error` when the diff touches the holdout folder or a scenario cannot be played | `pass`, `fail`, `error` |
94
125
  | `checks` | Runs the done list as the base branch holds it, never the branch's copy. `error` holds when the diff touches a locked path, or on an environment failure (a failed fetch, a timeout, a missing tool); `none` holds with a proposed list when the base has none | `pass`, `fail`, `error`, `none` |
@@ -96,7 +127,7 @@ The bricks they add:
96
127
  | `triage` | A fork: reads the work item and reports the outcome that names its lane, with its reason. `fail` when no lane fits | `bug`, `feature`, `deps`, `refactor`, `docs`, `fail` |
97
128
  | `pr-open` | Pushes the branch (the push asks you) and opens the PR, or updates the one already open | `pass`, `fail` |
98
129
  | `merge-gate` | Waits for the PR's CI with a watch that returns by itself (each call under 10 minutes), 30 minutes at most. A repo with no CI reports `none`, and you decide; so does CI still pending at the bound, or a `gh`/`glab` that is missing or fails | `pass`, `fail`, `none` |
99
- | `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, and keeps only a lasting lesson in memory | `pass` |
130
+ | `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, with the numbers of `geneseed factory report`, and keeps only a lasting lesson in memory | `pass` |
100
131
 
101
132
  `analysis-to-build` also uses the loops' own `spec` brick (`gate: human`), the one the
102
133
  `spec-first-feature` loop starts with, and `issue-to-pr` the loops' `docs-update` brick as its
@@ -179,9 +210,12 @@ graph: its stages top to bottom, a fork's lanes side by side, a `loop:` stage as
179
210
  that names its loop over `whole loop`, each route back as a rail on the left with its cycle and
180
211
  `max`, and `close` and `stop` as end caps.
181
212
  Each factory shows how to start it: the request to give the agent, and the commands to start it
182
- by hand, the worktree first and then `geneseed factory init`. Its **Active** tab lists every
183
- registered run, with the current stage lit, the laps spent on each cycle and the child loop's
184
- current step, written `at <node>` in the current stage's box. The page changes nothing in a run (its poll only drops finished runs older than 7 days from `factories.json`, as Loops does); you answer a run in the
213
+ by hand, the worktree first and then `geneseed factory init`. Its **Active** tab is a board of every
214
+ registered run, in three columns: **Waits for you**, **Running** and **Ended**. A card shows where
215
+ the run stands, its task, the laps spent on each cycle, and its work and waiting time. A card
216
+ opens the run: its graph with the current stage lit, the laps spent on each cycle, the child
217
+ loop's current step, written `at <node>` in the current stage's box, and a timeline of every
218
+ stage with its outcome, its time, its duration and each rework. The page changes nothing, neither a run nor `factories.json`: the next `geneseed factory init` on the machine drops a run whose worktree is gone, and a closed run 7 days after that init first saw it closed. You answer a run in the
185
219
  agent's session.
186
220
 
187
221
  ## Your own factories
@@ -14,7 +14,7 @@ link: {"hash": "#/installs/hosts", "label": "Change it on Installs →"}
14
14
  ### The difference
15
15
 
16
16
  - **Full** — the instructions file carries the Ethos, every Rule and every rule of the active doctrine packs at complete length, reasoning included, every turn.
17
- - **Lean** — each Rule and each doctrine rule is carried as its heading plus a short form written by hand (the rule and how it works, not the first sentence cut off). Each layer ends with a pointer to its complete text on disk, and the agent reads the reasoning when a rule's application is unclear. The Ethos gets one hand-written short form for the whole layer, because it is flowing prose rather than numbered rules.
17
+ - **Lean** — each Rule and each doctrine rule is carried as its heading plus a short form written by hand (the rule and how it works, not the first sentence cut off). One pointer after the doctrine packs names where the complete text of both layers is on disk, and the agent reads the reasoning when a rule's application is unclear. The Ethos gets one hand-written short form for the whole layer, because it is flowing prose rather than numbered rules. Lean also drops the voice's flourish: a heading names the rule by its plain principle (`Dictate I — Sealed Secrets`, not `Dictate I — Arcana Sigillata · Sealed Secrets`), and no section opens with an italic epigraph. Full keeps both, and so do the complete files on disk.
18
18
 
19
19
  Neither setting hides text from the agent. They decide what is in front of it on *every* turn.
20
20
 
@@ -11,7 +11,7 @@ link: {"hash": "#/installs/hosts", "label": "Set the mode on Installs →"}
11
11
 
12
12
  > **You already know this:** a tech lead with a team. Quick questions get answered on the spot; a real feature becomes a ticket that someone builds on a branch, and the lead reviews the result before it is merged.
13
13
 
14
- Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a task worker or a pipeline is a one-shot, uncommitted run for a single task; a loop is a long-running state machine that commits each validated iteration on its own branch.
14
+ Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a task worker or a pipeline is a one-shot run for a single task, committed only on its own branch and merged by the session once you accept; a loop is a long-running state machine that commits each validated iteration on its own branch.
15
15
 
16
16
  ### direct — the default
17
17
 
@@ -70,7 +70,7 @@ Inside the crew, the developer implements and the tester runs the tests and lint
70
70
 
71
71
  ### Nothing lands beyond the worker's branch
72
72
 
73
- When a crew is done, it hands back its worktree **uncommitted**. A worker hands back its branch: the local commits from its own sub-workers' merges, and any uncommitted work. Each comes with the raw test and lint output and the list of files it changed. Then the session:
73
+ A worker or crew commits only in its own worktree, never pushes, and never merges outside its own branch. When it is done, it hands back that branch: its local commits (its own, and its sub-workers' merges) and any uncommitted work. Each comes with the raw test and lint output and the list of files it changed. Then the session:
74
74
 
75
75
  1. re-runs the tests and lint itself — its log is its own account, not proof;
76
76
  2. shows you the diff from the base it recorded, and the green output;
@@ -15,7 +15,7 @@ committed or counted against a ring budget while it waits.
15
15
 
16
16
  A [factory](factories.md) stage holds the same way, answered with `geneseed factory decide`.
17
17
  Three shipped bricks do: `intake` (holds on `needs-info` — it has questions only you can
18
- answer), `checks` (holds on `error` — the branch changed a locked path — and on `none` — the
18
+ answer — and on `reject` — it refuses the item as already done, a duplicate or against a rule), `checks` (holds on `error` — the branch changed a locked path — and on `none` — the
19
19
  base branch has no done list yet) and `merge-gate` (holds on `none` — the repo runs no CI on the
20
20
  PR).
21
21
 
@@ -83,7 +83,7 @@ evidence was never wired — no verdict is not a failure to repair.
83
83
  ## Not foreman mode
84
84
 
85
85
  A loop and a [foreman-mode](foreman-mode.md) pipeline are both "hand work off and keep going," but
86
- they solve different problems. A pipeline is a one-shot crew for a single task, uncommitted until
87
- you accept it. A loop is a long-running, self-scoring state machine that commits each validated
86
+ they solve different problems. A pipeline is a one-shot crew for a single task; it commits only on its
87
+ own branch, and nothing lands beyond it until you accept it. A loop is a long-running, self-scoring state machine that commits each validated
88
88
  iteration on its own branch as it goes, and only stops for a person when the risk crosses a
89
89
  threshold.
@@ -36,7 +36,7 @@ The same folder already held the install registry, your own loop bricks and temp
36
36
  | `PROFILE.md`, `geneseed-wiki.jsonc` | Whole file. A host file that is no longer its seed replaces the shared one. `$GENESEED_WIKI` overrides both |
37
37
  | `excludes.json` | A global install reads the union of the shared list and its own |
38
38
 
39
- When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
39
+ When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. In `user-rules.md`, the seed's explanation above the first `## R<n>` rule is skipped too while it is unchanged: only the rules are sent. Text you wrote above the rules, or an edited explanation, is sent as it is. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
40
40
 
41
41
  A global install's text names these locations as absolute paths. A project install keeps its relative paths and its own `memory/`. Geneseed grants no directory permission for the tier, so an agent write there follows your host's permission mode, as a write to the host's own folder does. A write to the shared rules or draft passes the same [rule gate](hooks.md) as a local one; the shared memory, like a local one, is written freely.
42
42