geneseed 5.2.0 → 5.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (190) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/README.md +4 -4
  3. package/SHIPPED.md +1 -1
  4. package/adapters/bob/README.md +31 -18
  5. package/adapters/claude-code/README.md +27 -22
  6. package/adapters/openclaude/README.md +18 -8
  7. package/adapters/opencode/HOW-OPENCODE-LOADS.md +8 -3
  8. package/adapters/opencode/plugins/geneseed-activity.js +20 -21
  9. package/adapters/opencode/plugins/geneseed-context.js +224 -71
  10. package/adapters/opencode/plugins/geneseed-guard.js +420 -203
  11. package/adapters/opencode/plugins/geneseed-workflow.js +3 -2
  12. package/adapters/opencode/workflows/_runtime.js +3 -2
  13. package/bin/geneseed-cli.mjs +61 -16
  14. package/bin/geneseed-hook.mjs +94 -12
  15. package/docs/concepts/enforcement-table.md +1 -1
  16. package/docs/concepts/exclusions.md +2 -2
  17. package/docs/concepts/factories.md +40 -6
  18. package/docs/concepts/footprint.md +11 -1
  19. package/docs/concepts/foreman-mode.md +2 -2
  20. package/docs/concepts/hook-gates.md +3 -3
  21. package/docs/concepts/host-matrix.md +22 -4
  22. package/docs/concepts/loop-gates.md +1 -1
  23. package/docs/concepts/loops.md +2 -2
  24. package/docs/concepts/shared-tier.md +1 -1
  25. package/docs/design-history.md +148 -0
  26. package/docs/extending.md +97 -163
  27. package/docs/guides/install-bob.md +2 -2
  28. package/docs/guides/install-openclaude.md +1 -1
  29. package/docs/guides/run-a-factory.md +15 -2
  30. package/docs/guides/upgrade.md +2 -2
  31. package/docs/guides/verify.md +12 -0
  32. package/docs/reference/environment.md +1 -0
  33. package/docs/reference/factory-actions.md +6 -5
  34. package/docs/reference/troubleshoot-doctor.md +1 -1
  35. package/docs/reference/troubleshoot-update.md +1 -1
  36. package/docs/token-footprint.md +66 -2
  37. package/docs/understand/design-choices-hosts.md +1 -1
  38. package/docs/understand/design-choices-shape.md +1 -0
  39. package/docs/understand/enforced-vs-asked.md +1 -1
  40. package/docs/understand/machine-bob.md +1 -1
  41. package/docs/web-ui.md +21 -3
  42. package/harness.config.json +1 -1
  43. package/js/README.md +7 -5
  44. package/js/build/args.mjs +4 -4
  45. package/js/build/driver.mjs +1 -1
  46. package/js/build/emit-claude.mjs +1 -1
  47. package/js/build/generate.mjs +5 -14
  48. package/js/build/render.mjs +44 -24
  49. package/js/cli-table.json +135 -59
  50. package/js/factory/cli.mjs +24 -5
  51. package/js/factory/graph.mjs +13 -9
  52. package/js/factory/metrics.mjs +93 -0
  53. package/js/factory/registry.mjs +37 -12
  54. package/js/factory/state.mjs +25 -6
  55. package/js/hosts/done-checks.mjs +6 -0
  56. package/js/hosts/geneseed-dir.mjs +3 -2
  57. package/js/hosts/gitref.mjs +5 -3
  58. package/js/hosts/hook-tap.mjs +104 -0
  59. package/js/hosts/hooks-context.mjs +30 -3
  60. package/js/hosts/hooks-learn.mjs +47 -16
  61. package/js/hosts/hooks-prims.mjs +52 -3
  62. package/js/hosts/hooks.mjs +69 -42
  63. package/js/hosts/hosts.mjs +80 -12
  64. package/js/hosts/installs.mjs +7 -0
  65. package/js/hosts/loss.mjs +6 -1
  66. package/js/hosts/native.mjs +14 -5
  67. package/js/hosts/owned.mjs +7 -6
  68. package/js/hosts/ownership-gate.mjs +14 -1
  69. package/js/hosts/settings.mjs +245 -103
  70. package/js/hosts/shim.mjs +4 -4
  71. package/js/hosts/usage.mjs +9 -3
  72. package/js/inspect/checks-probe.mjs +66 -5
  73. package/js/inspect/checks-repo.mjs +196 -2
  74. package/js/inspect/cost.mjs +34 -2
  75. package/js/inspect/diff.mjs +16 -1
  76. package/js/inspect/doctor.mjs +13 -4
  77. package/js/inspect/excludes.mjs +18 -6
  78. package/js/inspect/status.mjs +35 -7
  79. package/js/inspect/validate.mjs +44 -21
  80. package/js/lib/machine-dir.mjs +1 -1
  81. package/js/lib/node-floor.mjs +46 -6
  82. package/js/maintain/uninstall.mjs +70 -17
  83. package/js/maintain/update.mjs +31 -7
  84. package/js/ui/cli.mjs +34 -4
  85. package/js/ui/menu.mjs +1 -1
  86. package/js/ui/tui.mjs +11 -14
  87. package/js/web/actions.mjs +3 -9
  88. package/js/web/api.mjs +28 -10
  89. package/js/web/daemon.mjs +0 -1
  90. package/js/web/server.mjs +1 -0
  91. package/js/web/state.mjs +37 -16
  92. package/package.json +1 -1
  93. package/src/AGENT.md.tmpl +23 -17
  94. package/src/agents/_template.md +1 -1
  95. package/src/agents/advocate.md +1 -1
  96. package/src/agents/developer.md +12 -3
  97. package/src/agents/empiricist.md +1 -1
  98. package/src/agents/framer.md +1 -1
  99. package/src/agents/historian.md +1 -1
  100. package/src/agents/operator.md +1 -1
  101. package/src/agents/pragmatist.md +1 -1
  102. package/src/agents/researcher.md +1 -1
  103. package/src/agents/skeptic.md +1 -1
  104. package/src/agents/steward.md +1 -1
  105. package/src/agents/user-advocate.md +1 -1
  106. package/src/agents/visionary.md +1 -1
  107. package/src/bricks/intake.md +10 -3
  108. package/src/bricks/retro.md +13 -3
  109. package/src/doctrines/comms.md +1 -1
  110. package/src/doctrines/ops.md +1 -1
  111. package/src/doctrines/process.md +7 -5
  112. package/src/factories/analysis-to-build.json +1 -0
  113. package/src/factories/bug-report-to-fix.json +1 -0
  114. package/src/factories/issue-to-pr.json +1 -0
  115. package/src/laws/universal.md +2 -2
  116. package/src/modes/foreman.md +8 -14
  117. package/src/skills/commit.md +7 -2
  118. package/src/skills/debug.md +1 -1
  119. package/src/skills/diagram-design/SKILL.md +1 -1
  120. package/src/skills/diagram-design/VENDOR.md +3 -1
  121. package/src/skills/factory-forge.md +5 -3
  122. package/src/skills/factory.md +22 -1
  123. package/src/skills/geneseed.md +1 -1
  124. package/src/skills/handoff.md +1 -1
  125. package/src/skills/parallel-agents.md +1 -1
  126. package/src/skills/pipeline.md +6 -6
  127. package/src/skills/plan.md +7 -3
  128. package/src/skills/spring-testing.md +1 -1
  129. package/themes/biker.json +78 -78
  130. package/themes/commentator.json +81 -81
  131. package/themes/cyberpunk.json +79 -79
  132. package/themes/gamer.json +77 -77
  133. package/themes/imperial.json +82 -82
  134. package/themes/joker.json +79 -79
  135. package/themes/marvin.json +82 -82
  136. package/themes/mean.json +82 -82
  137. package/themes/military.json +78 -78
  138. package/themes/neutral.json +78 -78
  139. package/themes/pirate.json +79 -79
  140. package/themes/sports.json +79 -79
  141. package/themes/verstappen.json +78 -78
  142. package/themes/wizard.json +79 -79
  143. package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
  144. package/web/dist/assets/Activity-WQ3ykgxU.js +1 -0
  145. package/web/dist/assets/ActivityDetail-7rt04SkS.js +1 -0
  146. package/web/dist/assets/{Bonsai-DSwUbavu.js → Bonsai-BBl4XXqs.js} +1 -1
  147. package/web/dist/assets/{CopyButton-BzRQz7k2.js → CopyButton-Beven8yn.js} +1 -1
  148. package/web/dist/assets/Dashboard-BgLArtgu.js +2 -0
  149. package/web/dist/assets/Docs-B5aHp86J.js +5 -0
  150. package/web/dist/assets/Factories-BjqzXAw8.js +1 -0
  151. package/web/dist/assets/GreenhouseView-Bce212qd.js +1 -0
  152. package/web/dist/assets/Installs-B1OsrHXF.js +3 -0
  153. package/web/dist/assets/JournalView-CV4omyww.js +1 -0
  154. package/web/dist/assets/Kits-CW1e7xNa.js +1 -0
  155. package/web/dist/assets/Laws-1Ckf1lbs.js +4 -0
  156. package/web/dist/assets/LibRows-Dag1s0ZX.js +1 -0
  157. package/web/dist/assets/Library-B3FuFLel.js +3 -0
  158. package/web/dist/assets/Loops-CwqgnLNw.js +2 -0
  159. package/web/dist/assets/Markdown-CxkA7940.js +71 -0
  160. package/web/dist/assets/OperatorHudView-JmYY1pBR.js +1 -0
  161. package/web/dist/assets/Personal-DKLgLa7Z.js +2 -0
  162. package/web/dist/assets/Settings-BwErnh-R.js +1 -0
  163. package/web/dist/assets/Tabs-8zsyEPSK.js +1 -0
  164. package/web/dist/assets/index-CRWqKxfY.css +1 -0
  165. package/web/dist/assets/index-Ce6qF2nG.js +6 -0
  166. package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
  167. package/web/dist/index.html +2 -2
  168. package/adapters/claude-code/settings.json +0 -52
  169. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
  170. package/web/dist/assets/Activity-DlQ30znB.js +0 -1
  171. package/web/dist/assets/ActivityDetail-CG0mn5fW.js +0 -1
  172. package/web/dist/assets/Dashboard-Ce3UOsxJ.js +0 -2
  173. package/web/dist/assets/Docs-CisVnYqv.js +0 -5
  174. package/web/dist/assets/Factories-Dq5oW4CU.js +0 -1
  175. package/web/dist/assets/GreenhouseView-y9WAfcc_.js +0 -1
  176. package/web/dist/assets/Installs-m4GElwFW.js +0 -3
  177. package/web/dist/assets/JournalView-DeBLRNGc.js +0 -1
  178. package/web/dist/assets/Kits-DJYVAnyE.js +0 -1
  179. package/web/dist/assets/Laws-CNpc_8ZV.js +0 -4
  180. package/web/dist/assets/LibRows-RO5bvXth.js +0 -1
  181. package/web/dist/assets/Library-Dg0ScciC.js +0 -3
  182. package/web/dist/assets/Loops-CjEdo-NG.js +0 -2
  183. package/web/dist/assets/Markdown-0ORz7tAc.js +0 -69
  184. package/web/dist/assets/OperatorHudView-2ujVMjq1.js +0 -1
  185. package/web/dist/assets/Personal-D0yS7ahT.js +0 -2
  186. package/web/dist/assets/Settings-DEN0U8QI.js +0 -1
  187. package/web/dist/assets/Tabs-But5R6_r.js +0 -1
  188. package/web/dist/assets/index-Ck42AbRX.js +0 -6
  189. package/web/dist/assets/index-PG_ukkh6.css +0 -1
  190. package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
@@ -1347,3 +1347,151 @@ Geneseed did make are listed in [Why Geneseed works this way](understand/design-
1347
1347
  anchor stays. A runtime toggle that works beside the anchor, without replacing it, remains
1348
1348
  possible. See
1349
1349
  [Foreman mode](concepts/foreman-mode.md).
1350
+ - **A chat mode that switches the harness off for a quick question** (2026-11-12): a slash
1351
+ command, a ready-made excluded folder, or a `geneseed chat` verb. Measured on the real hosts,
1352
+ the harness adds 11–14k tokens per session at lean and 18–21k at full, billed in full once
1353
+ where the provider caches prompts. No host can unload it inside a conversation, an excluded
1354
+ folder leaves the skill listings (and removes nothing on OpenCode), and on Claude Code and
1355
+ OpenCode 2 a toggle on resume loads the harness twice. The hosts' own launch switches differ
1356
+ per host and per version, so a verb would have to track them. See
1357
+ [Token footprint](token-footprint.md#why-there-is-no-chat-mode).
1358
+
1359
+ ---
1360
+
1361
+ ## Extending guide — settled history (moved 2026-11-11)
1362
+
1363
+ [docs/extending.md](extending.md) carried these sections while they were live. Each one was
1364
+ settled, so they moved here as a record; the rules that still hold stayed in the guide. Section
1365
+ numbers below are the guide's numbers at the time, and "today" means the date in each heading.
1366
+
1367
+ ### 5.1 ✅ A fifth hook verb — resolved 2026-08-19
1368
+
1369
+ **This was a hard blocker and it is now open.** Recorded here because the shape of the problem
1370
+ recurs: any gate whose expected value lives in an artifact nothing can re-make will eventually
1371
+ stop a legitimate change, and the fix is never to delete the artifact.
1372
+
1373
+ `tests/unit/hook_cli.test.mjs` asserted a strict equality between the hook verbs the frozen
1374
+ matrix covers and the verbs `bin/geneseed-hook.mjs` carries. The CLI half of the same test
1375
+ already exempted a named `NATIVE` list; the hook half exempted nothing — so a fifth hook verb
1376
+ failed with **no green path**, since the recorder died on 2026-08-17 and the failure message
1377
+ correctly forbids deleting cells to pass.
1378
+
1379
+ `NATIVE` in `tests/unit/hook_cli.test.mjs` names the verbs held to the structural rules rather
1380
+ than to a per-verb gate, and the reverse check refuses an exemption for a verb neither entry point
1381
+ carries — so a name that stops meaning anything fails rather than sitting there.
1382
+
1383
+ **To add a hook verb today:** implement `cmd<Verb>` in `js/hosts/hooks.mjs`, wire the string in
1384
+ `claudeHookGroups`, add the `VERBS` entry, add the `js/cli-table.json` row, then give it an
1385
+ absolute unit gate. `NATIVE` used to be duplicated across two files that read each other's source
1386
+ to stay in step; there is one copy now, so there is nothing to keep in step.
1387
+
1388
+ ### 5.2 ✅ Theme text is free to edit — resolved 2026-08-23
1389
+
1390
+ Seven keys (`TAGLINE`, `LOADED_SIGIL`, `VOICE`, `LEX_I`, `BENEDICTION`, `ACCENT`, `BANNER`) used to
1391
+ be pinned byte-for-byte by a recording with no re-bless path, so restyling a theme's tagline was a
1392
+ red gate. **That recording is gone.** Theme text is now held only by `doctor --all` — key presence,
1393
+ cross-theme parity, and no unresolved tokens — which is a claim about structure, not wording.
1394
+
1395
+ Restyle freely. What still bites is `LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme
1396
+ detection and nothing checks it.
1397
+
1398
+ ### 5.4 ✅ Expected values are written out — resolved 2026-08-23
1399
+
1400
+ This section used to say that a snapshot red was a finding rather than a step: the recordings under
1401
+ `tests/__snapshots__/` came from an implementation that no longer existed, there was no `--record`,
1402
+ and a change that moved a recorded byte left only two honest options — revert it, or argue in
1403
+ writing that the recording was wrong. The rule that fell out of it was *when a frozen recording
1404
+ blocks a change, move the logic to the nearest caller that is not frozen*.
1405
+
1406
+ **None of that applies any more.** The recordings are retired (tag `corpus-reference-v3.1.2` is the
1407
+ only way back to them), and every expected value now lives in the test file that asserts it, above
1408
+ a sentence saying which decision it pins. The rule is correspondingly ordinary:
1409
+
1410
+ > **Change the expectation and the sentence that explains it in the same commit, and say why in
1411
+ > the message.**
1412
+
1413
+ A red test is a step again. What it costs is an argument, in prose, that the new answer is better —
1414
+ the cost that keeps the tables honest, and far cheaper than the one it replaced.
1415
+
1416
+ The CLI surface is no longer the most expensive thing in the repo to change. Editing a verb's help
1417
+ text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
1418
+ `tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
1419
+ holds. Three hand-written equalities still converge on it and are cheap to keep in step — the
1420
+ 29-command count and the hidden-argument rule (`tests/unit/cli_table.test.mjs`), and
1421
+ `tests/unit/docs.test.mjs`, which validates every fenced `geneseed <verb> <flags>` line in
1422
+ `README.md`, `SHIPPED.md` and every page under `docs/{understand,guides,concepts,reference}/` against the table.
1423
+
1424
+ ### 7 — Stale on 2026-08-18, fixed on 2026-08-19
1425
+
1426
+ Nine items were found while writing this file, and fixed the next day. They are recorded as a
1427
+ list rather than left as a diff, because the PATTERN is the useful part: every one was a document
1428
+ or a comment pointing a reader at something that is not there, and in each case the gate that
1429
+ should have caught it either did not cover that file — or was itself the frozen copy of a wrong
1430
+ answer.
1431
+
1432
+ **Fixed.**
1433
+
1434
+ 1. **`DESIGN.md` taught the deleted Python build.** Its header promises *"the spec behind the
1435
+ harness — read this before changing structure"*, and under it sat the six-edit checklist for
1436
+ adding a Law, naming a deleted generator, `rituals/_harness_tui.py` for `LAW_CLASS`, and an
1437
+ invocation of a program that no longer exists. Worse, `tests/unit/no_python.test.mjs` exempted
1438
+ the file as a *historical record* — so the gate that hunts pointers-to-nothing was looking away
1439
+ from the one document most likely to hold one. **Split**: the 190-line standing contract keeps
1440
+ the name and is now scanned; the 1,290-line port narrative moved to
1441
+ the port narrative above, which is exempt on the merits, and its dead links were
1442
+ repaired because a link is a pointer whatever the prose around it says.
1443
+ 2. **`doctor` printed a command that errors.** The theme-parity tip named
1444
+ `./geneseed build --sync-themes`; `cmdBuild` forwards `--theme` and nothing else. The comment
1445
+ above the tip argued that spelling on a premise the port had quietly stopped satisfying. It now
1446
+ names `geneseed-build --sync-themes`, which is what README and SETUP said all along.
1447
+ 3. **User-facing output named a program that does not exist.** `tui` and `uninstall` told users to
1448
+ run `harness setup` / `harness uninstall` — the reference's name, dropped in P0. Five sites.
1449
+ One of them was **pinned verbatim by a test**, so a gate was holding the wrong string in place;
1450
+ that assertion is now a property — every backticked command a refusal offers must be a verb
1451
+ `js/cli-table.json` declares — which is strictly stronger and fires on the next rename too.
1452
+ 4. **The `tui` help promised a "full-screen curses control panel"** for a verb that returns 1 on
1453
+ every path. `docs/limits.md` listed this as permanently unfixable, on the grounds that the help
1454
+ corpus is frozen — but `formatHelp` never reads `cmd.help`, so it was an ordinary edit all
1455
+ along. The limits row went with the fix.
1456
+ 5. **Numbers in docblocks that had drifted** — `_TEMPLATE.json`'s "137 values" (140), "the 145
1457
+ tokens" `src/` uses (148), and "sixteen `_*_problems` checks" (fifteen — the sixteenth was
1458
+ named as `cli`, which was removed).
1459
+ 6. **A claim that was simply false.** `js/build/render.mjs` said `--theme` is validated against
1460
+ `choices` before anything renders, which is why its own refusal read as an unreachable nicety.
1461
+ It is not in `choicesFor`; that refusal is the only one there is, on every path.
1462
+ 7. **Five dead cross-references** to `tests/snapshot/no_python_in_corpus.test.mjs`, retired with
1463
+ the corpora — three test files justified their own design by pointing at a gate that is gone.
1464
+ Plus a skip message naming a `record-corpus` CI job that no longer exists.
1465
+ 8. **`CHANGELOG.md` said 2.0.0 was "not yet published"**, with "no tag, no release and no install
1466
+ URL"; `geneseed@2.0.0` has been on npm since 2026-08-17. And **`SETUP.md`** documented
1467
+ `geneseed upgrade v1.0.0 # pin to a tag`, which `js/maintain/update.mjs` prints is IGNORED.
1468
+ 9. **`docs/web/agents.md`** enumerated 16 agents and omitted `developer`, where README says 17 —
1469
+ the doctor arm cannot fire, because the page spells `{N_AGENTS}` and that arm only ever catches
1470
+ a literal. **`docs/web/rules.md`** called each law "a short markdown file under `src/laws/`";
1471
+ there is one file.
1472
+
1473
+ ### 10 — What to settle before the next wave
1474
+
1475
+ Ordered by what unblocks the most work per unit of effort. Each is small; none is urgent enough to
1476
+ stop a change today, and all of them cost a contributor a wrong turn until they are done.
1477
+
1478
+ 1. **Extend the fenced-command gate to `DESIGN.md` and `docs/**/*.md` (§7.3).** One array literal.
1479
+ Today it covers four documents, and both of the pointer-to-nothing defects §7 records — the
1480
+ `DESIGN.md` authoring section and `doctor`'s theme-parity tip, since fixed — sat outside its
1481
+ reach. It keeps catching them.
1482
+ 2. **Decide the hook-verb question (§5.1) before it is asked under pressure.** Either mirror the
1483
+ CLI side's exemption list onto the hook half, or write down that the hook verb set is closed.
1484
+ Either answer is fine; discovering the question mid-feature is not.
1485
+ 3. **Write down the frozen-key list (§5.2) where a theme author will see it** — `themes/README.md`
1486
+ is the natural home. Seven keys × fifteen files is a small enough surface to name explicitly,
1487
+ and today nothing warns you before the snapshot goes red.
1488
+ 4. **Gate `AGENT_LESSON_PROMPT` like its sibling (§7.7), and either gate or delete
1489
+ `adapters/claude-code/settings.json` (§7.10).** Two silent failure modes, both cheap to close.
1490
+ 5. **Finish the `scripts` block in the root `package.json`.** `lint` landed with the ESLint
1491
+ config; the rest of what CI runs is still reassembled by hand from this file. A `verify` script
1492
+ chaining lint + suite + doctor is three lines and makes §1 executable rather than descriptive.
1493
+
1494
+ The list of hand-maintained satellites in §6 is the *design*, not a defect — this project
1495
+ deliberately keeps tables and prose hand-written and gates them from the source tree. The
1496
+ recommendations above are about the places where the gate is missing, wrong, or pointed at a file
1497
+ that no longer exists.
package/docs/extending.md CHANGED
@@ -63,9 +63,10 @@ badge keys `agents`/`skills`/`laws`/`themes`/`plugins`; `proseMirrorProblems` ho
63
63
  The baseline is whatever these commands report on your checkout — run them; no count is
64
64
  written here, because a typed count is stale by the next commit.
65
65
 
66
- CI is **four jobs expanding to six runs** (`.github/workflows/ci.yml`): `validate` and
67
- `node-cells` on Linux *and* Windows, plus `package-no-python` and `web` on Linux. From the repo
68
- root — never from a worktree, see §5:
66
+ CI (`.github/workflows/ci.yml`) runs `validate` on Linux (Node 22 under c8, and Node 24) and on
67
+ Windows (the suite in shards, which `suite-count` sums), `node-cells` on Linux *and* Windows, and
68
+ `package-no-python`, `web`, `audit` and `links` on Linux; `ci-ok` is the one required check. From
69
+ the repo root — never from a worktree, see §5.3:
69
70
 
70
71
  ```bash
71
72
  node bin/geneseed-cli.mjs doctor --all
@@ -97,13 +98,15 @@ cd web && npm ci && npm run lint && npm run format:check && npm test && npm run
97
98
 
98
99
  Notes that matter:
99
100
 
100
- - The root `package.json` has exactly one script, `lint`, and no pre-commit hook, Makefile or
101
+ - The root `package.json` has two scripts, `lint` and `typecheck`, and no pre-commit hook, Makefile or
101
102
  justfile exists. `npm test` at the root exits 1 with *Missing script: "test"*; the suite is run
102
103
  by hand with the glob above. `npm ci` once per clone installs the devDependencies `lint` needs
103
104
  — it pulls no runtime dependency, because there are none.
104
- - `--test-reporter=tap` is not decoration. Both workflows gate on the *count* (`# tests N ≥ 500`)
105
- because `node --test` over a glob that matches nothing prints `# tests 0` and **exits 0**. Node's
106
- default reporter changed between majors, which is how a green 1043-test suite once reported zero.
105
+ - `--test-reporter=tap` is not decoration. Both workflows gate on the *count* (`# tests N`, at
106
+ least 90 % of the `test(`/`it(` calls written in the tracked test files; the Windows shards are
107
+ held to it as a sum) because `node --test` over a glob that matches nothing prints `# tests 0`
108
+ and **exits 0**. Node's default reporter changed between majors, which is how a green 1043-test
109
+ suite once reported zero.
107
110
  - `--cli` runs the ~320-cell CLI/hook matrix against the expectations written in each cell —
108
111
  the only end-to-end gate on what a verb prints. CI runs it in `node-cells` on both platforms.
109
112
  A cell that needs a broken checkout plants its fault as an **edit of the real file**
@@ -114,7 +117,7 @@ Notes that matter:
114
117
  - **A local pass is weaker than CI.** ~18 tests in `tests/unit/package_manifest.test.mjs` carry
115
118
  `{ skip: NO_NPM }` (`:83`) — every tarball, install and rename gate. On a machine without `npm`
116
119
  on PATH they report *skipped* and the run is green.
117
- - CI additionally re-runs the packaging suite under `npm@latest` (Linux, last in the job) and
120
+ - CI additionally re-runs the packaging suite under `npm@11`, the release's npm (Linux, last in the job), and
118
121
  packs the tarball into a `node:22-slim` container with no interpreter. Neither is reproducible
119
122
  from the seven commands; the container one is reachable locally through
120
123
  `tests/helpers/no-python-container.sh` with a docker daemon.
@@ -134,7 +137,6 @@ Notes that matter:
134
137
  Its *anchors* are now in CI (`--verify`, above): a row whose anchor a refactor has moved counts
135
138
  as a **survivor**, not a skip, and until 2026-08-19 that only showed up for whoever ran the
136
139
  matrix by hand — which nothing did.
137
- - **Node 24.** No CI job runs it; `publish.yml` does. See §8.
138
140
  - **`tests/golden.mjs`** is absent from the publish path entirely.
139
141
 
140
142
  ### Gates that fire on changes you would not expect to be gated
@@ -142,10 +144,10 @@ Notes that matter:
142
144
  - **A new subprocess anywhere in `js/` or `bin/`** — `tests/unit/spawn_hygiene.test.mjs` requires
143
145
  capturing spawns to set `windowsHide` and inheriting spawns not to. (`adapters/` is *not*
144
146
  scanned, so a plugin that spawns is on its own.)
145
- - **Editing `.github/workflows/*.yml`** — seven structural assertions in
146
- `tests/unit/docs.test.mjs:336-399` gate `publish.yml`'s shape, and `:422-444` discovers every
147
- workflow with a test-count gate and pins `--test-reporter=tap` on it. A unit test gates the CI
148
- files.
147
+ - **Editing `.github/workflows/*.yml`** — structural assertions in `tests/unit/docs.test.mjs`
148
+ gate `publish.yml`'s shape (found by `publishWorkflow`), and the test *every workflow that
149
+ count-gates `node --test` pins the TAP reporter* discovers every workflow with a test-count gate
150
+ and pins `--test-reporter=tap` on each `node --test` line. A unit test gates the CI files.
149
151
  - **Adding any tracked file** — `tests/unit/package_manifest.test.mjs:401` demands every tracked
150
152
  path fall on exactly one side of a declared partition, *with a written reason*. Adding this very
151
153
  document required a `SHIPS` row; without one the tarball test fails, and it fails **before** the
@@ -205,8 +207,8 @@ material belongs in, and it is cheap on purpose so that the invariant slot stays
205
207
  node bin/build-driver.mjs --sync-themes
206
208
  ```
207
209
 
208
- ⚠ Four spellings of this command are in circulation and two of them fail — `doctor`'s own tip
209
- is one of the two. See §7.2 before you copy a command from anywhere else. Then restyle all
210
+ ⚠ `geneseed-build --sync-themes` is the same command; `geneseed build --sync-themes` is not —
211
+ `cmdBuild` (`BUILD_FORWARD`) does not forward `--sync-themes`. Then restyle all
210
212
  fourteen by hand: `--sync-themes` writes the template's placeholder and only *prints*
211
213
  `RESTYLE these`; a shipped placeholder passes every gate.
212
214
  4. `CHANGELOG.md`.
@@ -370,7 +372,7 @@ emit leaves the prior install intact.
370
372
  5. `registry.json` — a row keyed `skills/<name>` or `agents/<name>` with `status` ∈
371
373
  {`experimental`, `approved`, `deprecated`}, a semver `version`, a non-blank `owner`, an ISO
372
374
  `added`, and `last_verified: ""`. **This is the most forgettable step**: four hand-typed fields,
373
- and the gate fires in both directions (`js/inspect/doctor.mjs:388-436`).
375
+ and the gate fires in both directions (`registryProblems`, `js/inspect/checks-repo.mjs`).
374
376
  6. `README.md` — the badge, the `**🤖 Agents** (N)` / `**🛠 Skills** (N)` count, and for a skill the
375
377
  `·`-separated name in the 🛠 row (that enumeration is gated two ways, unlike the laws' one).
376
378
  7. `SHIPPED.md` — the `N laws, N agents, N skills` triple.
@@ -533,7 +535,7 @@ every pack, so a kit there would switch itself on in every install built before
533
535
 
534
536
  ---
535
537
 
536
- ## 4 — Adding a PLUGIN, a HOOK verb, or a doc page
538
+ ## 4 — Adding a PLUGIN, a HOOK verb, a doc page, or a HOST
537
539
 
538
540
  ### 4a — An OpenCode plugin
539
541
 
@@ -560,12 +562,12 @@ No `registry.json` row, no `package.json` edit — `files[]` ships `adapters/` w
560
562
 
561
563
  ### 4b — A hook verb (claude + bob)
562
564
 
563
- ⚠ **Read §5 first. A fifth hook verb has no green path today.**
564
-
565
565
  The mechanical part: implement `cmd<Verb>` in `js/hosts/hooks.mjs`; wire the command string in
566
- `claudeHookGroups` (`js/hosts/settings.mjs:434`, spelled `` `${run} <verb> …` `` — the gate scrapes that
567
- shape); add the entry to `bin/geneseed-hook.mjs:43` `VERBS` with **exactly two-space indent**; add
568
- a row to `js/cli-table.json` with a help string over 20 characters.
566
+ `claudeHookGroups` (`js/hosts/settings.mjs`, spelled `` `${run} <verb> …` `` — the gate scrapes that
567
+ shape); add the entry to `VERBS` in `bin/geneseed-hook.mjs` with **exactly two-space indent**; add
568
+ a row to `js/cli-table.json` with a help string over 20 characters. Then give the verb an absolute
569
+ unit gate, or name it in `NATIVE` (`tests/unit/hook_cli.test.mjs`), which holds a verb to the
570
+ structural rules instead; the reverse check refuses a `NATIVE` name no entry point carries.
569
571
 
570
572
  ### 4c — A documentation page
571
573
 
@@ -604,6 +606,54 @@ the page renders, wrong, with nothing red.
604
606
 
605
607
  ---
606
608
 
609
+ ### 4d — A host
610
+
611
+ **A host is not one row.** `HOSTS` (`js/hosts/hosts.mjs`) is the table two maps are derived
612
+ from (`EMIT_HOST_SCOPE` and `EMIT_FOR` in `js/hosts/installs.mjs`, and `CLAUDE_STYLE`). Every
613
+ other site below is typed by hand. `tests/unit/host_tables.test.mjs` fails for the tables marked
614
+ *(pinned)*; the rest have no gate, which is why this list exists.
615
+
616
+ Decide first: is the host **Claude-shaped** (a settings file that runs hook commands, a root
617
+ instruction file, `SKILL.md` skills) or does it need its own engine, as OpenCode does? A
618
+ Claude-shaped host rides `js/build/emit-claude.mjs`; anything else is a new emitter and a much
619
+ larger change than this list.
620
+
621
+ 1. `HOSTS` in `js/hosts/hosts.mjs`: the row (`host`, `family`, `configDir`, `projectMarker`,
622
+ `agentFile`, `catalog`), a `<host>ConfigDir()` beside the others, and `CARRIERS` /
623
+ `carriersFor` if the root file sits somewhere new. Set `catalog.agents` only for what you
624
+ have seen the host list to the model by itself.
625
+ 2. `EMITS` in `js/build/args.mjs` *(pinned)*: `<host>` and `<host>-global`.
626
+ 3. `CLAUDE_SHAPED` and the two dispatch tables under it in `js/build/driver.mjs`: one row per
627
+ scope, with the summary line the emit prints. Name the settings file by its real path.
628
+ 4. `claudeHookGroups` in `js/hosts/settings.mjs`: the hook groups in the host's own events and
629
+ verdict dialect, and `--host <id>` on each command. A host that cannot ask (Bob) needs its
630
+ block set decided in `BLOCK_RULES` (`js/hosts/hooks.mjs`).
631
+ 5. `js/hosts/native.mjs`: the agent and skill frontmatter dialect, and how a user-only skill
632
+ is hidden from the model.
633
+ 6. The gate-config markers: `GATE_CONFIG_MARKERS` in `js/hosts/hooks.mjs` *(pinned)* and its
634
+ hand copy in `adapters/opencode/plugins/geneseed-guard.js`, which leaves out `.opencode`.
635
+ A write under the new host's project layer can switch a gate off.
636
+ 7. `NATIVE_ROOT` in `js/hosts/hooks-context.mjs` *(pinned)*: the root file the host loads by
637
+ itself, so the context hook does not inject it a second time.
638
+ 8. `mcpConfigFor` in `js/hosts/mcp.mjs` *(pinned)*: where the host reads MCP servers from.
639
+ 9. `PROBED_VERB` and `probeShell` in `js/inspect/checks-probe.mjs` *(pinned)*: which verb
640
+ refuses on this host, under which shell, and `probesFor` if the host sends its own payload
641
+ shapes.
642
+ 10. `HOST_LABELS` in `js/inspect/checks-repo.mjs` *(pinned)*, then a column in
643
+ `docs/concepts/host-matrix.md` and `docs/concepts/enforcement-table.md` (`geneseed doctor`
644
+ fails without them), and a row in `## What is verified` saying how the host was checked.
645
+ 11. `DOC_HOSTS` in `js/web/docs.mjs` *(pinned)*: the Docs selector's entry and family.
646
+ 12. The setup menu, `js/maintain/setup.mjs`: `EMIT_OPTIONS` *(pinned)*, appended after the
647
+ last entry because the menu is answered by number; the host's display name, and its row in
648
+ the "is it installed" detection table.
649
+ 13. `js/inspect/cost.mjs` (`userOnlyTest`, `catalogueChars`), `js/inspect/excludes.mjs` and
650
+ `js/inspect/status.mjs`: each branches on the host id.
651
+ 14. `tests/host_canary.mjs`: a `HOSTS` entry if the host is on npm. If it is not, say so in
652
+ the docblock and in `## What is verified`, and write the by-hand steps into
653
+ `docs/guides/verify.md`. `GENESEED_HOOK_TAP` records what the host really sends.
654
+ 15. `tests/golden.mjs`: the emit cells. `adapters/<host>/README.md`, a
655
+ `docs/guides/install-<host>.md`, and the README's matrix.
656
+
607
657
  ## 4bis — Adding a RUNTIME DEPENDENCY
608
658
 
609
659
  **Short answer: you vendor it, or you do not add it.** A dependency arrives as tracked source under
@@ -653,41 +703,16 @@ specifiers under `js/`, `bin/` and `adapters/` and exactly one was bare — the
653
703
  exception above. The invariant already held; it had simply never been written down. A library that
654
704
  would delete fewer lines than its vendored source adds is not a saving.
655
705
 
656
- ## 5 — The four things that are genuinely hard
657
-
658
- These are not checklist items. They are structural, and each one should be settled *before* the
659
- change that needs it, not during.
660
-
661
- ### 5.1 ✅ A fifth hook verb — resolved 2026-08-19
662
-
663
- **This was a hard blocker and it is now open.** Recorded here because the shape of the problem
664
- recurs: any gate whose expected value lives in an artifact nothing can re-make will eventually
665
- stop a legitimate change, and the fix is never to delete the artifact.
666
-
667
- `tests/unit/hook_cli.test.mjs` asserted a strict equality between the hook verbs the frozen
668
- matrix covers and the verbs `bin/geneseed-hook.mjs` carries. The CLI half of the same test
669
- already exempted a named `NATIVE` list; the hook half exempted nothing — so a fifth hook verb
670
- failed with **no green path**, since the recorder died on 2026-08-17 and the failure message
671
- correctly forbids deleting cells to pass.
672
-
673
- `NATIVE` in `tests/unit/hook_cli.test.mjs` names the verbs held to the structural rules rather
674
- than to a per-verb gate, and the reverse check refuses an exemption for a verb neither entry point
675
- carries — so a name that stops meaning anything fails rather than sitting there.
676
-
677
- **To add a hook verb today:** implement `cmd<Verb>` in `js/hosts/hooks.mjs`, wire the string in
678
- `claudeHookGroups`, add the `VERBS` entry, add the `js/cli-table.json` row, then give it an
679
- absolute unit gate. `NATIVE` used to be duplicated across two files that read each other's source
680
- to stay in step; there is one copy now, so there is nothing to keep in step.
706
+ ## 5 — Rules that cost something to learn
681
707
 
682
- ### 5.2 ✅ Theme text is free to edit — resolved 2026-08-23
708
+ These are not checklist items. The numbers are kept because code cites §5.3; §5.1 (the hook-verb
709
+ gate, now in §4b) was settled, and the history of all four is in [design history](design-history.md).
683
710
 
684
- Seven keys (`TAGLINE`, `LOADED_SIGIL`, `VOICE`, `LEX_I`, `BENEDICTION`, `ACCENT`, `BANNER`) used to
685
- be pinned byte-for-byte by a recording with no re-bless path, so restyling a theme's tagline was a
686
- red gate. **That recording is gone.** Theme text is now held only by `doctor --all` — key presence,
687
- cross-theme parity, and no unresolved tokens — which is a claim about structure, not wording.
711
+ ### 5.2 Theme text is free to edit
688
712
 
689
- Restyle freely. What still bites is `LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme
690
- detection and nothing checks it.
713
+ Theme text is held only by `doctor --all` — key presence, cross-theme parity, and no unresolved
714
+ tokens — which is a claim about structure, not wording. Restyle freely. What still bites is
715
+ `LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme detection and nothing checks it.
691
716
 
692
717
  ### 5.3 ⚠ The hook shim is machine-wide and last-writer-wins
693
718
 
@@ -727,24 +752,14 @@ remains the cheapest thing to run.
727
752
  Related: a stray `console.log` on a hook path silently disables a gate. Hooks signal through
728
753
  stdout JSON and return 0 on every path — a printed byte is not a warning, it is a disabled gate.
729
754
 
730
- ### 5.4 ✅ Expected values are written out — resolved 2026-08-23
755
+ ### 5.4 Expected values are written out
731
756
 
732
- This section used to say that a snapshot red was a finding rather than a step: the recordings under
733
- `tests/__snapshots__/` came from an implementation that no longer existed, there was no `--record`,
734
- and a change that moved a recorded byte left only two honest options — revert it, or argue in
735
- writing that the recording was wrong. The rule that fell out of it was *when a frozen recording
736
- blocks a change, move the logic to the nearest caller that is not frozen*.
737
-
738
- **None of that applies any more.** The recordings are retired (tag `corpus-reference-v3.1.2` is the
739
- only way back to them), and every expected value now lives in the test file that asserts it, above
740
- a sentence saying which decision it pins. The rule is correspondingly ordinary:
757
+ Every expected value lives in the test file that asserts it, above a sentence saying which
758
+ decision it pins. There is no snapshot directory and no `--record`, so a red test is a step:
741
759
 
742
760
  > **Change the expectation and the sentence that explains it in the same commit, and say why in
743
761
  > the message.**
744
762
 
745
- A red test is a step again. What it costs is an argument, in prose, that the new answer is better —
746
- the cost that keeps the tables honest, and far cheaper than the one it replaced.
747
-
748
763
  The CLI surface is no longer the most expensive thing in the repo to change. Editing a verb's help
749
764
  text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
750
765
  `tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
@@ -770,75 +785,24 @@ only, at best, on its presence.
770
785
  | Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
771
786
  | `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/maintain/setup.mjs`, `js/ui/anim.mjs` | nothing — missing entries fall back silently |
772
787
  | `LOADED_SIGIL` uniqueness | `themes/*.json` | nothing, and it is load-bearing for theme detection |
773
- | `adapters/claude-code/settings.json` | — | nothing compares it to what the emitter writes; **it is already divergent** |
774
- | `NATIVE`, twice | two test files | they check each other, which is the gate that makes the duplication safe |
775
788
  | The emit-size `CEILING` | `tests/unit/emit_smoke.test.mjs` (`const CEILING`) | a hand-transcribed measurement |
776
- | Stale docblock counts | `js/build/themes.mjs:62` ("137 values" → 140), `js/build/render.mjs:116` ("145 tokens" → 148) | nothing |
777
789
 
778
790
  ---
779
791
 
780
- ## 7 — Stale on 2026-08-18, fixed on 2026-08-19
781
-
782
- Nine items were found while writing this file, and fixed the next day. They are recorded as a
783
- list rather than left as a diff, because the PATTERN is the useful part: every one was a document
784
- or a comment pointing a reader at something that is not there, and in each case the gate that
785
- should have caught it either did not cover that file — or was itself the frozen copy of a wrong
786
- answer.
787
-
788
- **Fixed.**
789
-
790
- 1. **`DESIGN.md` taught the deleted Python build.** Its header promises *"the spec behind the
791
- harness — read this before changing structure"*, and under it sat the six-edit checklist for
792
- adding a Law, naming a deleted generator, `rituals/_harness_tui.py` for `LAW_CLASS`, and an
793
- invocation of a program that no longer exists. Worse, `tests/unit/no_python.test.mjs` exempted
794
- the file as a *historical record* — so the gate that hunts pointers-to-nothing was looking away
795
- from the one document most likely to hold one. **Split**: the 190-line standing contract keeps
796
- the name and is now scanned; the 1,290-line port narrative moved to
797
- [design-history.md](design-history.md), which is exempt on the merits, and its dead links were
798
- repaired because a link is a pointer whatever the prose around it says.
799
- 2. **`doctor` printed a command that errors.** The theme-parity tip named
800
- `./geneseed build --sync-themes`; `cmdBuild` forwards `--theme` and nothing else. The comment
801
- above the tip argued that spelling on a premise the port had quietly stopped satisfying. It now
802
- names `geneseed-build --sync-themes`, which is what README and SETUP said all along.
803
- 3. **User-facing output named a program that does not exist.** `tui` and `uninstall` told users to
804
- run `harness setup` / `harness uninstall` — the reference's name, dropped in P0. Five sites.
805
- One of them was **pinned verbatim by a test**, so a gate was holding the wrong string in place;
806
- that assertion is now a property — every backticked command a refusal offers must be a verb
807
- `js/cli-table.json` declares — which is strictly stronger and fires on the next rename too.
808
- 4. **The `tui` help promised a "full-screen curses control panel"** for a verb that returns 1 on
809
- every path. `docs/limits.md` listed this as permanently unfixable, on the grounds that the help
810
- corpus is frozen — but `formatHelp` never reads `cmd.help`, so it was an ordinary edit all
811
- along. The limits row went with the fix.
812
- 5. **Numbers in docblocks that had drifted** — `_TEMPLATE.json`'s "137 values" (140), "the 145
813
- tokens" `src/` uses (148), and "sixteen `_*_problems` checks" (fifteen — the sixteenth was
814
- named as `cli`, which was removed).
815
- 6. **A claim that was simply false.** `js/build/render.mjs` said `--theme` is validated against
816
- `choices` before anything renders, which is why its own refusal read as an unreachable nicety.
817
- It is not in `choicesFor`; that refusal is the only one there is, on every path.
818
- 7. **Five dead cross-references** to `tests/snapshot/no_python_in_corpus.test.mjs`, retired with
819
- the corpora — three test files justified their own design by pointing at a gate that is gone.
820
- Plus a skip message naming a `record-corpus` CI job that no longer exists.
821
- 8. **`CHANGELOG.md` said 2.0.0 was "not yet published"**, with "no tag, no release and no install
822
- URL"; `geneseed@2.0.0` has been on npm since 2026-08-17. And **`SETUP.md`** documented
823
- `geneseed upgrade v1.0.0 # pin to a tag`, which `js/maintain/update.mjs` prints is IGNORED.
824
- 9. **`docs/web/agents.md`** enumerated 16 agents and omitted `developer`, where README says 17 —
825
- the doctor arm cannot fire, because the page spells `{N_AGENTS}` and that arm only ever catches
826
- a literal. **`docs/web/rules.md`** called each law "a short markdown file under `src/laws/`";
827
- there is one file.
828
-
829
- **Still open.**
830
-
831
- - **`adapters/claude-code/settings.json` is divergent documentation.** It writes
832
- `node bin/geneseed-hook.mjs <verb>` on seven lines, including one the emitter does not produce
833
- at all, and carries none of the flags `claudeHookGroups` emits. Nothing compares the two; the
834
- only reference to it anywhere is the error message that sends users to it. Either gate it
835
- against the emitter, or delete it.
792
+ ## 7 — Still open
793
+
794
+ Each is small, and each costs a contributor a wrong turn until it is done. What was found and
795
+ fixed here before is recorded in [design history](design-history.md).
796
+
836
797
  - **`AGENT_LESSON_PROMPT` has no drift gate.** Its sibling `LEARN_PROMPT_HEAD` is checked for
837
798
  extractability; this one's parity test was retired. Reformat the declaration in
838
799
  `geneseed-learn.js` and the per-agent lesson prompt silently degrades to a two-line fallback.
839
800
  - **The fenced-command gate skips the maintainer docs.** `tests/unit/docs.test.mjs` validates
840
801
  every `geneseed <verb> <flags>` line against `js/cli-table.json` in `README.md`, `SHIPPED.md`
841
802
  and the user docs tree — not in `DESIGN.md` or the `docs/*.md` maintainer pages.
803
+ - **No `verify` script.** The root `package.json` has `lint` and `typecheck`; the rest of what CI
804
+ runs is still reassembled by hand from §1. A script chaining lint, typecheck, the suite and
805
+ doctor would make §1 executable rather than descriptive.
842
806
 
843
807
  ---
844
808
 
@@ -862,18 +826,16 @@ gh workflow run publish.yml -f dry_run=true
862
826
 
863
827
  Two structural facts worth carrying:
864
828
 
865
- - **`publish.yml` deliberately runs a newer toolchain than `ci.yml`** — Node 24 and `npm@latest`,
866
- because trusted publishing requires them, against `ci.yml`'s Node 22. So toolchain-sensitive
867
- defaults break *first and only* at the release. That has now happened twice: `npm pack --json`
868
- changed its container between majors, and Node 24's default test reporter made the count gate
869
- read zero on a green suite.
829
+ - **`publish.yml` runs Node 24 and `npm@11`**, because trusted publishing requires them. Toolchain
830
+ defaults that differ from Node 22's broke the release twice: `npm pack --json` changed its
831
+ container between majors, and Node 24's default test reporter made the count gate read zero on
832
+ a green suite. `ci.yml` now meets both before a release does — a `validate` leg on Node 24, the
833
+ packaging suite re-run under `npm@11`, and the TAP reporter pinned in both workflows.
870
834
  - **Renaming `publish.yml` breaks publishing silently** — npm keys the trusted publisher on the
871
835
  filename.
872
836
 
873
- Both known breaks have been patched at the symptom (`ci.yml` re-runs the packaging suite under
874
- `npm@latest`; both workflows pin the TAP reporter). The *cause* is untouched: **no CI job runs
875
- Node 24 at all**, so the release still executes a runtime nothing exercises — and `publish.yml`
876
- never runs `tests/golden.mjs`, so the two self-comparisons are absent from the release path.
837
+ `publish.yml` never runs `tests/golden.mjs`, so the two self-comparisons are absent from the
838
+ release path; they run only in `ci.yml`'s `node-cells`.
877
839
 
878
840
  A sweep-and-replace version bump must not touch `registry.json`'s per-entity `"version": "1.0.0"`
879
841
  rows, nor `web/package.json`.
@@ -913,31 +875,3 @@ port is therefore stopped with `--port`, never with a bare `web stop` — that o
913
875
  the record names, usually the live console on 4747.
914
876
 
915
877
  When the preferred port is taken, `clearPort` (`js/web/daemon.mjs`) asks `/api/ping` who holds it. The ping carries `rootId()`, a hash of the checkout root. A holder with our root is asked for a nonce (`/api/ping?shutdown=1`), then asked to shut down on `/api/shutdown` with `X-Geneseed-Nonce` and `X-Geneseed-Secret`: a MAC of the port and the nonce under the install secret in `.geneseed-web-secret` (32 random bytes, created once next to the daemon record; mode 0600 on POSIX, the folder's inherited ACL on Windows). The console accepts each nonce it minted once, within 30 seconds, so a proof that an impostor collects is good nowhere later. The secret itself is never sent, and no pid is ever signalled, so a listener that only claims our root cannot cause harm. A holder of our root that answers `nonce: null` holds no secret (a foreground console, or a daemon that could not read its secret), and one that answers no `nonce` predates the handshake; both are named and left alone. Any other answer is left alone and named. A console older than the field has no root, so it is never assumed to be ours.
916
-
917
- ---
918
-
919
- ## 10 — What to settle before the next wave
920
-
921
- Ordered by what unblocks the most work per unit of effort. Each is small; none is urgent enough to
922
- stop a change today, and all of them cost a contributor a wrong turn until they are done.
923
-
924
- 1. **Extend the fenced-command gate to `DESIGN.md` and `docs/**/*.md` (§7.3).** One array literal.
925
- Today it covers four documents, and both of the pointer-to-nothing defects §7 records — the
926
- `DESIGN.md` authoring section and `doctor`'s theme-parity tip, since fixed — sat outside its
927
- reach. It keeps catching them.
928
- 2. **Decide the hook-verb question (§5.1) before it is asked under pressure.** Either mirror the
929
- CLI side's exemption list onto the hook half, or write down that the hook verb set is closed.
930
- Either answer is fine; discovering the question mid-feature is not.
931
- 3. **Write down the frozen-key list (§5.2) where a theme author will see it** — `themes/README.md`
932
- is the natural home. Seven keys × fifteen files is a small enough surface to name explicitly,
933
- and today nothing warns you before the snapshot goes red.
934
- 4. **Gate `AGENT_LESSON_PROMPT` like its sibling (§7.7), and either gate or delete
935
- `adapters/claude-code/settings.json` (§7.10).** Two silent failure modes, both cheap to close.
936
- 5. **Finish the `scripts` block in the root `package.json`.** `lint` landed with the ESLint
937
- config; the rest of what CI runs is still reassembled by hand from this file. A `verify` script
938
- chaining lint + suite + doctor is three lines and makes §1 executable rather than descriptive.
939
-
940
- The list of hand-maintained satellites in §6 is the *design*, not a defect — this project
941
- deliberately keeps tables and prose hand-written and gates them from the source tree. The
942
- recommendations above are about the places where the gate is missing, wrong, or pointed at a file
943
- that no longer exists.
@@ -13,9 +13,9 @@ geneseed build --emit bob-global # ~/.bob
13
13
  geneseed build --emit bob --out /path/to/repo --root /path/to/repo # one repo
14
14
  ```
15
15
 
16
- Bob is shaped like Claude Code, so it gets the same agents and skills. A read-only agent is limited with Bob's own `groups:` key, because Bob ignores Claude's `disallowedTools`. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2, and Bob has no `SubagentStop` or `PreCompact` events.
16
+ Bob is shaped like Claude Code, so it gets the same agents and skills. A read-only agent is limited with Bob's own `groups:` key, because Bob ignores Claude's `disallowedTools`. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2. Bob has no `SubagentStop` event; Bob 2.2.3 does have `PreCompact` and `PostCompact`, which Geneseed does not wire.
17
17
 
18
- Both scopes open Bob's carrier with a short first-reply override, so the theme's readiness line (for example "🧬 Gene-seed implanted…") starts the first reply. Without it, Bob's own greeting outranked the instruction lower in the file. A bare greeting such as "hi" still gets Bob's fixed welcome; the line appears on the first real request. That much was checked by hand in the Bob IDE (2026-10); the rest of the Bob support has not been verified against a live install.
18
+ Both scopes open Bob's carrier with a short first-reply override, so the theme's readiness line (for example "🧬 Gene-seed implanted…") starts the first reply. Without it, Bob's own greeting outranked the instruction lower in the file. A bare greeting such as "hi" still gets Bob's fixed welcome; the line appears on the first real request. For what was checked against Bob itself, and when, see [What is verified](../concepts/host-matrix.md#what-is-verified); [Verify it works](verify.md) has the steps to check your own install by hand.
19
19
 
20
20
  ---
21
21
 
@@ -18,7 +18,7 @@ geneseed build --emit openclaude --out /path/to/repo --root /path/to/repo # one
18
18
  - Per repo, the preamble is written to `.openclaude/CLAUDE.md` rather than a root file, and the hooks go into `.openclaude/settings.local.json`.
19
19
  - `$OPENCLAUDE_CONFIG_DIR` moves the global directory (default `~/.openclaude`).
20
20
 
21
- OpenClaude support has not yet been verified against a live install.
21
+ For what was checked against OpenClaude itself, see [What is verified](../concepts/host-matrix.md#what-is-verified).
22
22
 
23
23
  ---
24
24
 
@@ -43,7 +43,19 @@ Run the analysis-to-build factory on this request: add CSV export to the report
43
43
  On Claude Code, `/factory` with the same words is the explicit form: it loads the `factory`
44
44
  skill directly. The console's **Factories** page shows the request for each factory, ready to copy.
45
45
 
46
- The agent then:
46
+ To pick from the issues that wait, ask for the queue:
47
+
48
+ ```text
49
+ Show me the factory queue
50
+ Run the factory queue with the label ready-to-build
51
+ ```
52
+
53
+ The agent lists the open issues that carry the label `factory` (or the label you name), with
54
+ `gh issue list` or `glab issue list`. Pick one, several or all. Several picks run one after the
55
+ other, in your order, each in its own worktree, and each ends with its own merge question. A run
56
+ that waits for you holds the ones after it.
57
+
58
+ For each run, the agent then:
47
59
 
48
60
  1. Creates a worktree on a new branch, `git worktree add ../<repo>-factory-<slug> -b loop/factory-<slug>`, and works from there. Your own checkout is not touched. The slug never holds the word `git`, `commit` or `push`: `factory init` refuses it.
49
61
  2. Runs `geneseed factory init --title … --requirement … --factory bug-report-to-fix --input <issue or text>`. This writes `FACTORY.md` at the worktree root and registers the run.
@@ -95,6 +107,7 @@ run the analysis-to-build factory on docs/analysis/export-csv.md
95
107
  | Moment | What you decide |
96
108
  | --- | --- |
97
109
  | `intake` reports `needs-info` | The work item leaves a question only you can answer. The agent shows its numbered questions, each with the assumption it would make. Answer them (`amend`, three times at most), say `ok` to go on with the assumptions, or `no` to stop. |
110
+ | `intake` reports `reject` | The item should not be built: it is already done, a duplicate, or against a rule the project states. The agent shows the reason and its evidence. `ok` accepts the refusal and stops the run, `amend` with your reason runs `intake` again to build it, `no` stops too. Nothing is posted on the issue. |
98
111
  | `checks` reports `error` | Every check passed, but the branch changed a locked path: the done list, CI config, or a factory, loop or brick. `ok` lets it through (the run report names it), `no` stops. Or the finding starts `environment:`: the fetch failed, no default branch was found, or a check timed out or its tool is missing. The loop cannot fix that: fix the environment and answer `amend` to run the checks again, or `no` to stop; `ok` goes on without them. |
99
112
  | `checks` reports `none` | The base branch has no done list, or an empty one. The agent shows the one it proposes (or says no manifest gave one). On your yes it commits the file in a temporary worktree on its own branch, `geneseed/done-list-<slug>`, pushes that branch and opens a PR to the base branch (each step asks). You merge that PR. Once the file is on the base, `ok` runs the checks again. |
100
113
  | The `spec` gate (`analysis-to-build`) | The task list: `ok` starts the first task, `amend` revises the spec, `no` stops the run. The spec commit after your `ok` asks too. |
@@ -109,7 +122,7 @@ Red CI does not stop for you: it sends the work back to the run's loop (`bugfix`
109
122
 
110
123
  ## When it ends
111
124
 
112
- On success the agent reports the PR (merged on your yes, or open), every stage with its outcome, each rework and why, and the run report at `.geneseed/factory-runs/<slug>.md`. On a stop it reports the reason and still writes the run report; the branch and `FACTORY.md` stay as they were, so you can see where it stopped. After a crash, ask the agent to resume: it runs `geneseed factory next` in the worktree.
125
+ On success the agent reports the PR (merged on your yes, or open), every stage with its outcome, each rework and why, and the run report at `.geneseed/factory-runs/<slug>.md`. The run report has a table with one row per stage: its runs, its reworks, its work time and its tokens, where the host reports them. It also gives the time the run waited for you. To read the same numbers while a run is going, run `geneseed factory report` in its worktree, or open the console's **Factories › Active** board: the runs that wait for you come first, and a card opens the run's timeline. On a stop it reports the reason and still writes the run report; the branch and `FACTORY.md` stay as they were, so you can see where it stopped. After a crash, ask the agent to resume: it runs `geneseed factory next` in the worktree.
113
126
 
114
127
  ---
115
128