geneseed 5.1.1 → 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 (163) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/README.md +2 -2
  3. package/SHIPPED.md +1 -1
  4. package/adapters/opencode/README.md +4 -3
  5. package/adapters/opencode/plugins/geneseed-context.js +82 -29
  6. package/adapters/opencode/plugins/geneseed-guard.js +118 -8
  7. package/bin/geneseed-cli.mjs +64 -16
  8. package/bin/geneseed-hook.mjs +37 -3
  9. package/docs/concepts/exclusions.md +1 -1
  10. package/docs/concepts/factories.md +40 -6
  11. package/docs/concepts/footprint.md +1 -1
  12. package/docs/concepts/foreman-mode.md +2 -2
  13. package/docs/concepts/host-matrix.md +1 -1
  14. package/docs/concepts/loop-gates.md +1 -1
  15. package/docs/concepts/loops.md +2 -2
  16. package/docs/concepts/shared-tier.md +1 -1
  17. package/docs/design-history.md +140 -0
  18. package/docs/extending.md +54 -162
  19. package/docs/guides/run-a-factory.md +15 -2
  20. package/docs/guides/setup-doctrines.md +1 -1
  21. package/docs/guides/upgrade.md +2 -2
  22. package/docs/reference/factory-actions.md +6 -5
  23. package/docs/reference/troubleshoot-update.md +1 -1
  24. package/docs/understand/enforced-vs-asked.md +1 -1
  25. package/docs/web-ui.md +16 -3
  26. package/harness.config.json +1 -1
  27. package/js/README.md +10 -7
  28. package/js/build/args.mjs +10 -4
  29. package/js/build/bundle.mjs +122 -23
  30. package/js/build/driver.mjs +32 -12
  31. package/js/build/emit-claude.mjs +2 -1
  32. package/js/build/emit-common.mjs +2 -2
  33. package/js/build/emit-opencode.mjs +22 -10
  34. package/js/build/export.mjs +431 -0
  35. package/js/build/generate.mjs +3 -0
  36. package/js/build/render.mjs +44 -24
  37. package/js/build/source.mjs +6 -1
  38. package/js/cli-table.json +232 -57
  39. package/js/factory/cli.mjs +24 -5
  40. package/js/factory/graph.mjs +13 -9
  41. package/js/factory/metrics.mjs +93 -0
  42. package/js/factory/registry.mjs +37 -12
  43. package/js/factory/state.mjs +25 -6
  44. package/js/hosts/hooks-context.mjs +26 -1
  45. package/js/hosts/hooks-done.mjs +8 -2
  46. package/js/hosts/hooks-prims.mjs +52 -3
  47. package/js/hosts/hooks.mjs +155 -33
  48. package/js/hosts/hosts.mjs +2 -4
  49. package/js/hosts/installs.mjs +28 -0
  50. package/js/hosts/loss.mjs +25 -3
  51. package/js/hosts/native.mjs +30 -2
  52. package/js/hosts/owned.mjs +55 -1
  53. package/js/hosts/ownership-gate.mjs +5 -5
  54. package/js/hosts/settings.mjs +83 -33
  55. package/js/inspect/diff.mjs +16 -1
  56. package/js/inspect/doctor.mjs +7 -3
  57. package/js/inspect/excludes.mjs +18 -6
  58. package/js/inspect/status.mjs +35 -7
  59. package/js/inspect/validate.mjs +44 -21
  60. package/js/lib/managed-block.mjs +74 -0
  61. package/js/maintain/uninstall.mjs +85 -15
  62. package/js/maintain/update.mjs +31 -7
  63. package/js/ui/cli.mjs +34 -4
  64. package/js/ui/menu.mjs +1 -1
  65. package/js/ui/tui.mjs +11 -14
  66. package/js/web/actions.mjs +5 -0
  67. package/js/web/api.mjs +32 -11
  68. package/js/web/daemon.mjs +0 -1
  69. package/js/web/server.mjs +1 -0
  70. package/js/web/state.mjs +37 -16
  71. package/package.json +1 -1
  72. package/src/AGENT.md.tmpl +23 -17
  73. package/src/agents/_template.md +1 -1
  74. package/src/agents/advocate.md +1 -1
  75. package/src/agents/developer.md +12 -3
  76. package/src/agents/empiricist.md +1 -1
  77. package/src/agents/framer.md +1 -1
  78. package/src/agents/historian.md +1 -1
  79. package/src/agents/operator.md +1 -1
  80. package/src/agents/pragmatist.md +1 -1
  81. package/src/agents/researcher.md +1 -1
  82. package/src/agents/skeptic.md +1 -1
  83. package/src/agents/steward.md +1 -1
  84. package/src/agents/user-advocate.md +1 -1
  85. package/src/agents/visionary.md +1 -1
  86. package/src/bricks/intake.md +10 -3
  87. package/src/bricks/retro.md +13 -3
  88. package/src/doctrines/comms.md +1 -1
  89. package/src/doctrines/ops.md +1 -1
  90. package/src/doctrines/process.md +7 -5
  91. package/src/factories/analysis-to-build.json +1 -0
  92. package/src/factories/bug-report-to-fix.json +1 -0
  93. package/src/factories/issue-to-pr.json +1 -0
  94. package/src/laws/universal.md +2 -2
  95. package/src/modes/foreman.md +8 -14
  96. package/src/skills/commit.md +7 -2
  97. package/src/skills/debug.md +1 -1
  98. package/src/skills/diagram-design/SKILL.md +1 -1
  99. package/src/skills/diagram-design/VENDOR.md +3 -1
  100. package/src/skills/factory-forge.md +5 -3
  101. package/src/skills/factory.md +22 -1
  102. package/src/skills/geneseed.md +1 -1
  103. package/src/skills/handoff.md +1 -1
  104. package/src/skills/parallel-agents.md +1 -1
  105. package/src/skills/pipeline.md +6 -6
  106. package/src/skills/plan.md +7 -3
  107. package/src/skills/spring-testing.md +1 -1
  108. package/themes/biker.json +78 -78
  109. package/themes/commentator.json +81 -81
  110. package/themes/cyberpunk.json +79 -79
  111. package/themes/gamer.json +77 -77
  112. package/themes/imperial.json +82 -82
  113. package/themes/joker.json +79 -79
  114. package/themes/marvin.json +82 -82
  115. package/themes/mean.json +82 -82
  116. package/themes/military.json +78 -78
  117. package/themes/neutral.json +78 -78
  118. package/themes/pirate.json +79 -79
  119. package/themes/sports.json +79 -79
  120. package/themes/verstappen.json +78 -78
  121. package/themes/wizard.json +79 -79
  122. package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
  123. package/web/dist/assets/Activity-CqJiquEq.js +1 -0
  124. package/web/dist/assets/ActivityDetail-BSzevynX.js +1 -0
  125. package/web/dist/assets/{Bonsai-hiG_gGNU.js → Bonsai-Bfpb6W-1.js} +1 -1
  126. package/web/dist/assets/{CopyButton-DUIUfNp6.js → CopyButton-ByIntFtB.js} +1 -1
  127. package/web/dist/assets/Dashboard-DBOEi9lQ.js +2 -0
  128. package/web/dist/assets/Docs-DvlMJhpu.js +5 -0
  129. package/web/dist/assets/Factories-Bpvv7L2H.js +1 -0
  130. package/web/dist/assets/{GreenhouseView-BKxy5apE.js → GreenhouseView-GpBsYn50.js} +1 -1
  131. package/web/dist/assets/Installs-BlGmVrFK.js +3 -0
  132. package/web/dist/assets/{JournalView-ChFitHjo.js → JournalView-iLuLrOxE.js} +1 -1
  133. package/web/dist/assets/Kits-DRwpxC-J.js +1 -0
  134. package/web/dist/assets/Laws-CZkiNOWQ.js +4 -0
  135. package/web/dist/assets/LibRows-DEHjIoD-.js +1 -0
  136. package/web/dist/assets/Library-B4K-1iNF.js +3 -0
  137. package/web/dist/assets/Loops-BWSzaW8E.js +2 -0
  138. package/web/dist/assets/{OperatorHudView-BO0aIKPL.js → OperatorHudView-BAXwCEvY.js} +1 -1
  139. package/web/dist/assets/Personal-Bp9nV4GR.js +2 -0
  140. package/web/dist/assets/Settings-CWWuaIp-.js +1 -0
  141. package/web/dist/assets/Tabs-CWeQTADL.js +1 -0
  142. package/web/dist/assets/index-CsAZq0BQ.css +1 -0
  143. package/web/dist/assets/index-How7SzDZ.js +6 -0
  144. package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
  145. package/web/dist/index.html +2 -2
  146. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
  147. package/web/dist/assets/Activity-CpkBwpu7.js +0 -1
  148. package/web/dist/assets/ActivityDetail-DTPziZWM.js +0 -1
  149. package/web/dist/assets/Dashboard-Dnw6EyX7.js +0 -2
  150. package/web/dist/assets/Docs-BEET_l16.js +0 -5
  151. package/web/dist/assets/Factories-D6KXkfWw.js +0 -1
  152. package/web/dist/assets/Installs-CnFVlVD0.js +0 -3
  153. package/web/dist/assets/Kits-CcR-OlwQ.js +0 -1
  154. package/web/dist/assets/Laws-B1s5idOg.js +0 -4
  155. package/web/dist/assets/LibRows-BZgdbI1l.js +0 -1
  156. package/web/dist/assets/Library-x6TkkEVF.js +0 -3
  157. package/web/dist/assets/Loops-BH93KKxn.js +0 -2
  158. package/web/dist/assets/Personal-CE_0Vhh0.js +0 -2
  159. package/web/dist/assets/Settings-CbpZvVN_.js +0 -1
  160. package/web/dist/assets/Tabs-C2oW7oEj.js +0 -1
  161. package/web/dist/assets/index-BQwOmbor.js +0 -6
  162. package/web/dist/assets/index-CuIop_pO.css +0 -1
  163. package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
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.
@@ -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
 
@@ -653,41 +655,16 @@ specifiers under `js/`, `bin/` and `adapters/` and exactly one was bare — the
653
655
  exception above. The invariant already held; it had simply never been written down. A library that
654
656
  would delete fewer lines than its vendored source adds is not a saving.
655
657
 
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.
658
+ ## 5 — Rules that cost something to learn
681
659
 
682
- ### 5.2 ✅ Theme text is free to edit — resolved 2026-08-23
660
+ These are not checklist items. The numbers are kept because code cites §5.3; §5.1 (the hook-verb
661
+ gate, now in §4b) was settled, and the history of all four is in [design history](design-history.md).
683
662
 
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.
663
+ ### 5.2 Theme text is free to edit
688
664
 
689
- Restyle freely. What still bites is `LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme
690
- detection and nothing checks it.
665
+ Theme text is held only by `doctor --all` — key presence, cross-theme parity, and no unresolved
666
+ tokens — which is a claim about structure, not wording. Restyle freely. What still bites is
667
+ `LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme detection and nothing checks it.
691
668
 
692
669
  ### 5.3 ⚠ The hook shim is machine-wide and last-writer-wins
693
670
 
@@ -727,24 +704,14 @@ remains the cheapest thing to run.
727
704
  Related: a stray `console.log` on a hook path silently disables a gate. Hooks signal through
728
705
  stdout JSON and return 0 on every path — a printed byte is not a warning, it is a disabled gate.
729
706
 
730
- ### 5.4 ✅ Expected values are written out — resolved 2026-08-23
707
+ ### 5.4 Expected values are written out
731
708
 
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:
709
+ Every expected value lives in the test file that asserts it, above a sentence saying which
710
+ decision it pins. There is no snapshot directory and no `--record`, so a red test is a step:
741
711
 
742
712
  > **Change the expectation and the sentence that explains it in the same commit, and say why in
743
713
  > the message.**
744
714
 
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
715
  The CLI surface is no longer the most expensive thing in the repo to change. Editing a verb's help
749
716
  text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
750
717
  `tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
@@ -770,75 +737,30 @@ only, at best, on its presence.
770
737
  | Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
771
738
  | `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/maintain/setup.mjs`, `js/ui/anim.mjs` | nothing — missing entries fall back silently |
772
739
  | `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 |
740
+ | The hand-wiring copy of the Claude hooks | `adapters/claude-code/settings.json` — it ships (`files[]` takes `adapters/` whole), and `js/hosts/settings.mjs` sends a user whose `settings.json` has comments to it | nothing compares it with what `claudeHookGroups` emits (§7) |
775
741
  | 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
742
 
778
743
  ---
779
744
 
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.
745
+ ## 7 — Still open
746
+
747
+ Each is small, and each costs a contributor a wrong turn until it is done. What was found and
748
+ fixed here before is recorded in [design history](design-history.md).
749
+
750
+ - **`adapters/claude-code/settings.json` has no gate.** It ships, and the refusal for a commented
751
+ `settings.json` tells users to copy hooks from it. It writes `node bin/geneseed-hook.mjs <verb>`,
752
+ a path that resolves only from a checkout root, and none of the `--no-*-gate` flags
753
+ `claudeHookGroups` emits. Nothing compares the two. Either gate it against the emitter, or point
754
+ the refusal at an emitted file and delete it.
836
755
  - **`AGENT_LESSON_PROMPT` has no drift gate.** Its sibling `LEARN_PROMPT_HEAD` is checked for
837
756
  extractability; this one's parity test was retired. Reformat the declaration in
838
757
  `geneseed-learn.js` and the per-agent lesson prompt silently degrades to a two-line fallback.
839
758
  - **The fenced-command gate skips the maintainer docs.** `tests/unit/docs.test.mjs` validates
840
759
  every `geneseed <verb> <flags>` line against `js/cli-table.json` in `README.md`, `SHIPPED.md`
841
760
  and the user docs tree — not in `DESIGN.md` or the `docs/*.md` maintainer pages.
761
+ - **No `verify` script.** The root `package.json` has `lint` and `typecheck`; the rest of what CI
762
+ runs is still reassembled by hand from §1. A script chaining lint, typecheck, the suite and
763
+ doctor would make §1 executable rather than descriptive.
842
764
 
843
765
  ---
844
766
 
@@ -862,18 +784,16 @@ gh workflow run publish.yml -f dry_run=true
862
784
 
863
785
  Two structural facts worth carrying:
864
786
 
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.
787
+ - **`publish.yml` runs Node 24 and `npm@11`**, because trusted publishing requires them. Toolchain
788
+ defaults that differ from Node 22's broke the release twice: `npm pack --json` changed its
789
+ container between majors, and Node 24's default test reporter made the count gate read zero on
790
+ a green suite. `ci.yml` now meets both before a release does — a `validate` leg on Node 24, the
791
+ packaging suite re-run under `npm@11`, and the TAP reporter pinned in both workflows.
870
792
  - **Renaming `publish.yml` breaks publishing silently** — npm keys the trusted publisher on the
871
793
  filename.
872
794
 
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.
795
+ `publish.yml` never runs `tests/golden.mjs`, so the two self-comparisons are absent from the
796
+ release path; they run only in `ci.yml`'s `node-cells`.
877
797
 
878
798
  A sweep-and-replace version bump must not touch `registry.json`'s per-entity `"version": "1.0.0"`
879
799
  rows, nor `web/package.json`.
@@ -913,31 +833,3 @@ port is therefore stopped with `--port`, never with a bare `web stop` — that o
913
833
  the record names, usually the live console on 4747.
914
834
 
915
835
  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.
@@ -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
 
@@ -32,7 +32,7 @@ The packs always load in the same order (craft, rigor, ops, process, comms), wha
32
32
  **Dropping `process` changes what the machine does, not only what the agent reads.** The *Consent Before Push* rule in that pack is enforced at the tool boundary as well as in the prose:
33
33
 
34
34
  - On Claude Code and OpenClaude, the git hook stays wired but stops asking before a commit or push.
35
- - On OpenCode, a fresh install no longer gets the `git commit*` and `git push*` ask entries in `opencode.json`. On an existing install, entries that are already there are left in place and reported, because Geneseed cannot tell its own entries from ones you typed.
35
+ - On OpenCode, a fresh install no longer gets the `git commit*` and `git push*` ask entries in `opencode.json`. On an existing install, the entries Geneseed recorded adding are removed. Entries you typed, and those on an install made before 5.2.0, are left in place and reported; build once with `--prune-gates` to remove the second kind.
36
36
 
37
37
  The refusals of destructive git and `rm -rf` belong to the always-on Rules, not to the pack, so they stay in every build. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
38
38
 
@@ -19,7 +19,7 @@ geneseed rebuild-all # rebuild every install with its own settings
19
19
 
20
20
  `rebuild-all` re-renders each registered install in place, keeping its own theme, host, footprint, posture, mode, packs and rule exclusions. It is best-effort: when one install fails, it reports the failure and carries on with the rest.
21
21
 
22
- `upgrade`, `update` and `bootstrap` are the clone route. Run from an npm install, they stop before touching anything and point you to `npm install -g geneseed@latest` instead.
22
+ `upgrade` and `update` (and the deprecated `bootstrap`) are the clone route. Run from an npm install, they stop before touching anything and point you to `npm install -g geneseed@latest` instead.
23
23
 
24
24
  ## Installed from a clone
25
25
 
@@ -36,7 +36,7 @@ geneseed upgrade imperial # the same, switching the theme
36
36
 
37
37
  If the `doctor` pass cannot finish, for example on a busy machine after 300 seconds, `upgrade` keeps the pull, rebuilds nothing, and exits 1. The pulled source is unchecked, not bad. Run `geneseed upgrade` again: it runs `doctor` first, rebuilds on a pass, and rolls back to the last checked commit on a failure.
38
38
 
39
- A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` is an alias of `upgrade`; `sync-self` was removed in 5.0.0, and `upgrade` takes only a theme. `bootstrap` does the same and then opens the setup wizard (`--no-setup` skips the wizard).
39
+ A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` is an alias of `upgrade`; `sync-self` was removed in 5.0.0, and `upgrade` takes only a theme (as an argument or `--theme`). `upgrade --setup` does the same and then opens the setup wizard; `bootstrap`, its old name, still works for one release and says so.
40
40
 
41
41
  ## The Update button in the web console
42
42
 
@@ -6,16 +6,17 @@ kind: "concept"
6
6
  section: "CLI & environment"
7
7
  description: "The geneseed factory actions, one line each."
8
8
  ---
9
- The actions of `geneseed factory`, the state machine that carries one work item through a graph of stages to an open PR. A stage is a brick or a whole loop (`loop:<template>`). A **fork** is a brick that declares a named outcome (one other than `pass`, `fail`, `error`, `none` or `needs-info`), each outcome with its own edge to its own lane. An edge target or a cycle node may be `$lane`: the stage the run's most recent fork chose. The run state lives in `FACTORY.md` at the worktree root, beside the child loop's `LOOP.md` ([Loop actions](loop-actions.md)). Each action prints one JSON object and exits 1 on a refusal.
9
+ The actions of `geneseed factory`, the state machine that carries one work item through a graph of stages to an open PR. A stage is a brick or a whole loop (`loop:<template>`). A **fork** is a brick that declares a named outcome (one other than `pass`, `fail`, `error`, `none`, `needs-info` or `reject`), each outcome with its own edge to its own lane. An edge target or a cycle node may be `$lane`: the stage the run's most recent fork chose. The run state lives in `FACTORY.md` at the worktree root, beside the child loop's `LOOP.md` ([Loop actions](loop-actions.md)). Each action prints one JSON object and exits 1 on a refusal.
10
10
 
11
11
  | action | what it does |
12
12
  |---|---|
13
- | `check` | checks every factory in the catalogue, or one factory (`--factory <name or .json file>`): the factory has a name and no stage twice, every stage exists, every outcome has one edge (`error` and `needs-info` may go without one: `error` then stops the run, and `needs-info` follows the stage's `pass` edge), `$close` is reachable, every cycle is declared with a `max` from 1 to 5, each cycle is entered only at its first stage, and every route back targets the first stage of a cycle that holds its source. `$lane` needs a fork on every path to it, and a fork's own edge never targets it. In those checks, `$lane` stands for every lane of every fork. A factory that still uses the retired `loop:$triaged` stage or `loops` list gets a problem that names the replacement; nothing rewrites the file. An optional `protected` must be a list of non-empty paths. An outcome on which a brick reports environment failures (`checks` `error`, `merge-gate` `none`) never routes to a `loop:` stage or `$lane`: no loop can fix a failed fetch, a missing tool or CI pending at the bound. An optional `review.seats` needs a non-empty list of agents for each of `small`, `medium` and `large`, and `areas`, when present, maps each area to such a list; every seat must name a shipped agent (`review.seats.medium: no agent named <name>`). A project factory overrides a global or shipped one of the same name, and a global one a shipped one: `check` lists each in `overridden`. A file that does not load is a problem that names its level (`factories/<name>.json (project): not JSON`), and it drops the factory of that name from lower levels, so `init` refuses with that problem instead of running another graph |
13
+ | `check` | checks every factory in the catalogue, or one factory (`--factory <name or .json file>`): the factory has a name and no stage twice, every stage exists, every outcome has one edge (`error`, `reject` and `needs-info` may go without one: `error` and `reject` then stop the run, and `needs-info` follows the stage's `pass` edge), `$close` is reachable, every cycle is declared with a `max` from 1 to 5, each cycle is entered only at its first stage, and every route back targets the first stage of a cycle that holds its source. `$lane` needs a fork on every path to it, and a fork's own edge never targets it. In those checks, `$lane` stands for every lane of every fork. A factory that still uses the retired `loop:$triaged` stage or `loops` list gets a problem that names the replacement; nothing rewrites the file. An optional `protected` must be a list of non-empty paths. An outcome on which a brick reports environment failures (`checks` `error`, `merge-gate` `none`) never routes to a `loop:` stage or `$lane`: no loop can fix a failed fetch, a missing tool or CI pending at the bound. An optional `review.seats` needs a non-empty list of agents for each of `small`, `medium` and `large`, and `areas`, when present, maps each area to such a list; every seat must name a shipped agent (`review.seats.medium: no agent named <name>`). A project factory overrides a global or shipped one of the same name, and a global one a shipped one: `check` lists each in `overridden`. A file that does not load is a problem that names its level (`factories/<name>.json (project): not JSON`), and it drops the factory of that name from lower levels, so `init` refuses with that problem instead of running another graph |
14
14
  | `list` | lists the factories of the three origins (shipped, global, project), with description, category and origin |
15
- | `init` | writes a fresh `FACTORY.md` from a factory, under a title, a requirement and an optional `--input` (an issue URL, a file path or pasted text). A factory that fails `check` is refused before any stage runs, and so is a run branch `loop/factory-<slug>` whose slug holds the word `git`, `commit` or `push`: the slug lands on lines the git gate reads. Each `init` also registers the run in `factories.json`, beside the loop registry |
15
+ | `init` | writes a fresh `FACTORY.md` from a factory, under a title, a requirement and an optional `--input` (an issue URL, a file path or pasted text), and stamps the time as the run's `started`. A factory that fails `check` is refused before any stage runs, and so is a run branch `loop/factory-<slug>` whose slug holds the word `git`, `commit` or `push`: the slug lands on lines the git gate reads. Each `init` also registers the run in `factories.json`, beside the loop registry |
16
16
  | `next` | returns the next thing to do: run a brick stage, run a loop (with `notes` to start it with, and the `task` when a spec set tasks: the spec's `path`, the task `count` and this task's `index`), answer an `awaiting` gate, or a terminal. A fork stage also gets `lanes`: each outcome it may report, with the stage it leads to. Every stage gets the factory's `rules`, and its `protected` paths when it declares any. Refused while a `LOOP.md` exists that is not `done` or `stopped` (an unreadable one counts as running): the child loop finishes first. On a loop stage, refused while any `LOOP.md` is left: `git rm -f LOOP.md` and commit that removal before `geneseed loop init`. On a loop stage, `next` also records the launch in `FACTORY.md`: the loop template, the HEAD commit and the time. When a later stage routes back to the loop stage that ran the tasks, after its last task passed (a failed `checks`, `review-panel` or `holdout`, or red CI at `merge-gate`), `next` hands out one extra task: the last `index` again, with `extra` set to the stage and outcome that sent it back (`"merge-gate reported fail"`). That lap spends the route's cycle and the transition ceilings like any other, and gives no fresh budget |
17
- | `record` | records the current stage's outcome and follows its edge. A loop stage reports `pass` (its loop closed) or `fail` (it stopped), and only after `next` launched it. While its `LOOP.md` is still there, that file must name the stage's template, a `stopped` one admits only `fail`, and a `done` one only `pass`. With no `LOOP.md` left, `pass` and `fail` both need a HEAD that moved since `next`: the loop's close commit, or the commit that removes a stopped loop's `LOOP.md`. That is enough for `fail`. `pass` also needs the loop registry to show a `geneseed loop init` in this worktree after `next`. Without it, `pass` is refused: record it while the `done` `LOOP.md` is still at the root, or report `fail`. The registry does not keep a loop's final status, so a stopped loop whose `LOOP.md` was removed by hand can still pass. `--carry` hands a reason to the next stage; a re-entered loop starts with it as a note. `--carry-file <file>` reads it from a file instead (CRLF folded, trimmed), for free text, which never goes on the command line: the skill writes it with the host's file tool, never the shell, to a file it names uniquely. Every path argument (`--spec`, `--factory <file>`, `--carry-file`, `--note-file`) is relative to the current directory; only `FACTORY.md` is found at the git root. On a fork, the outcome names the lane: the stage its edge reaches is stored as the run's `lane`, and an edge to `$lane` goes there. A route to `$lane` with no lane on record is refused. `--spec <path>` records the run's spec, which must be at `specs/<slug>/spec.md` (any other path is refused before the state changes): the first loop stage recorded after it runs once per numbered item (`1.` or `1)`, indented 3 spaces at most) under its first heading that contains the word `task` or `tasks`, up to the next heading of the same or a higher level (`#`, indented 3 spaces at most, or a setext heading), 20 at most. As in CommonMark, a numbered item indented as far as the text of the task above it is a sub-item, and a fenced block (```` ``` ```` or `~~~`) is skipped whole. Until the first task loop launches (the first loop after a spec is on record; a loop that ran before any spec does not count), each `--spec` sets the count again, so a spec amended at its gate may list more tasks. From that launch the count is frozen: a later `--spec` may keep or lower it, never raise it. After a stage outside a loop, pipe it `git status --porcelain --untracked-files=all` in one command: `git status --porcelain --untracked-files=all | geneseed factory record …`. PowerShell pipes the same way; the CRLF that Windows PowerShell 5.1 adds, and the leading BOM it adds when `$OutputEncoding` is UTF-8, are stripped. The git gate asks on any line that holds the word `git` and the word `commit` or `push`, so a record line whose spec path, carry path or outcome holds `commit` or `push` asks: a false alarm the user can answer yes to. `init` refuses a slug with those words, which removes the commonest case. Plain `--porcelain` shows a new directory as one line (`?? specs/`), so a new spec is refused. The tree must be clean (a `mutate` brick such as a `docs-update` lane commits its change first), with two exceptions: engine files, and the run's spec at `specs/<slug>/spec.md` (the one recorded now, else the one on record). No stdin at all (a terminal) is refused. An empty pipe reads as a clean tree. Refused, as `next` is, while a child loop owns the worktree. Every state action also refuses a `FACTORY.md` that does not parse, or one that holds any of these: counters that are not non-negative integers, a run-wide ceiling above 1200, a gate amend count above 3, a `lane` that no fork of the factory leads to, a current stage, task-owning stage, launched loop or held gate that the factory does not hold, an `awaiting` that does not match the status, an unknown status, a `history` or `cycles` that is not a list, or a factory that no longer passes `check` |
18
- | `decide` | answers a held `gate: human` stage: `ok` follows the edge (an edge to `$lane` goes to the lane on record), `no` stops, `amend` re-runs the stage with the `--note` as its carry (three times at most). `--note-file <file>` reads the note from a file instead, as `--carry-file` does |
17
+ | `record` | records the current stage's outcome and follows its edge. The history entry it writes carries the time as `at`. `--tokens <n>` stores on that entry the token count the host reported for the agent that ran the stage: a positive integer written in digits, anything else is refused before the state changes. Leave it out when the host gave no count; nothing estimates one. A loop stage reports `pass` (its loop closed) or `fail` (it stopped), and only after `next` launched it. While its `LOOP.md` is still there, that file must name the stage's template, a `stopped` one admits only `fail`, and a `done` one only `pass`. With no `LOOP.md` left, `pass` and `fail` both need a HEAD that moved since `next`: the loop's close commit, or the commit that removes a stopped loop's `LOOP.md`. That is enough for `fail`. `pass` also needs the loop registry to show a `geneseed loop init` in this worktree after `next`. Without it, `pass` is refused: record it while the `done` `LOOP.md` is still at the root, or report `fail`. The registry does not keep a loop's final status, so a stopped loop whose `LOOP.md` was removed by hand can still pass. `--carry` hands a reason to the next stage; a re-entered loop starts with it as a note. `--carry-file <file>` reads it from a file instead (CRLF folded, trimmed), for free text, which never goes on the command line: the skill writes it with the host's file tool, never the shell, to a file it names uniquely. Every path argument (`--spec`, `--factory <file>`, `--carry-file`, `--note-file`) is relative to the current directory; only `FACTORY.md` is found at the git root. On a fork, the outcome names the lane: the stage its edge reaches is stored as the run's `lane`, and an edge to `$lane` goes there. A route to `$lane` with no lane on record is refused. `--spec <path>` records the run's spec, which must be at `specs/<slug>/spec.md` (any other path is refused before the state changes): the first loop stage recorded after it runs once per numbered item (`1.` or `1)`, indented 3 spaces at most) under its first heading that contains the word `task` or `tasks`, up to the next heading of the same or a higher level (`#`, indented 3 spaces at most, or a setext heading), 20 at most. As in CommonMark, a numbered item indented as far as the text of the task above it is a sub-item, and a fenced block (```` ``` ```` or `~~~`) is skipped whole. Until the first task loop launches (the first loop after a spec is on record; a loop that ran before any spec does not count), each `--spec` sets the count again, so a spec amended at its gate may list more tasks. From that launch the count is frozen: a later `--spec` may keep or lower it, never raise it. After a stage outside a loop, pipe it `git status --porcelain --untracked-files=all` in one command: `git status --porcelain --untracked-files=all | geneseed factory record …`. PowerShell pipes the same way; the CRLF that Windows PowerShell 5.1 adds, and the leading BOM it adds when `$OutputEncoding` is UTF-8, are stripped. The git gate asks on any line that holds the word `git` and the word `commit` or `push`, so a record line whose spec path, carry path or outcome holds `commit` or `push` asks: a false alarm the user can answer yes to. `init` refuses a slug with those words, which removes the commonest case. Plain `--porcelain` shows a new directory as one line (`?? specs/`), so a new spec is refused. The tree must be clean (a `mutate` brick such as a `docs-update` lane commits its change first), with two exceptions: engine files, and the run's spec at `specs/<slug>/spec.md` (the one recorded now, else the one on record). No stdin at all (a terminal) is refused. An empty pipe reads as a clean tree. Refused, as `next` is, while a child loop owns the worktree. Every state action also refuses a `FACTORY.md` that does not parse, or one that holds any of these: counters that are not non-negative integers, a run-wide ceiling above 1200, a gate amend count above 3, a `lane` that no fork of the factory leads to, a current stage, task-owning stage, launched loop or held gate that the factory does not hold, an `awaiting` that does not match the status, an unknown status, a `history` or `cycles` that is not a list, or a factory that no longer passes `check` |
18
+ | `decide` | answers a held `gate: human` stage, and stamps the time on its history entry as `at`: `ok` follows the edge (an edge to `$lane` goes to the lane on record), `no` stops, `amend` re-runs the stage with the `--note` as its carry (three times at most). On `intake`'s `reject`, `ok` accepts the refusal: the edge goes to `$stop`, and the run stops with the reason `intake reported reject`. `--note-file <file>` reads the note from a file instead, as `--carry-file` does |
19
+ | `report` | prints the run's numbers as one JSON object and writes nothing. `stages` lists each stage the run recorded, in the order it first ran, with its `runs`, its `reworks` (an outcome that spent a cycle; a held outcome counts only once you answer `ok`), its `workMs` and its `tokens`. `workMs`, `waitMs`, `tokens` and `transitions` are the run's totals; `waitMs` counts a wait once its gate is answered, and `openWaitMs` is the wait still open while the run is held at a gate (the time now minus that record's time; `null` when no gate is held), and `entries` gives, for each history entry in order, its duration `ms`, whether it is waiting time (`wait`) and whether it is a rework. A duration is an entry's `at` minus the `at` of the entry before it (`started` for the first): work time on a `record` entry, waiting time on a `decide` entry. An entry with no time, as in a `FACTORY.md` written before times were stamped, gives `null`, and so does every total that holds it: never 0. `tokens` adds the counts recorded, and is `null` when none was. There is no cost in money |
19
20
 
20
21
  A route back into a cycle spends the cycle whose first stage is the route's target; past its `max` the run stops. A run stops too after 60 stage transitions, counted again for each spec task the run reaches for the first time, and after 60 transitions per task of the spec (60 without a spec) over the whole run. That run-wide ceiling follows the spec's task count until the first task loop launches (the first spec sets it even after an earlier loop), and never changes after.
21
22
 
@@ -26,7 +26,7 @@ The upgrade is a `git pull`, so it first checks the folder. Each refusal says wh
26
26
 
27
27
  | What you see | Cause and fix |
28
28
  | --- | --- |
29
- | `geneseed: error: invalid choice: 'sync-self'.` | The verb is gone. Run `geneseed upgrade`. |
29
+ | `geneseed: error: unknown command 'sync-self'. See geneseed --help.` | The verb is gone. Run `geneseed upgrade`. |
30
30
  | `geneseed: error: unrecognized arguments: imperial` from `upgrade main imperial` | `upgrade` takes only a theme. Run `geneseed upgrade imperial`. |
31
31
  | A host's `memory/` folder holds only its seed | Expected: [the fold](../concepts/shared-tier.md#the-fold) moved the facts to `~/.config/geneseed/memory/`. `geneseed memory list` shows them, and the old store is in `archived-memory/<stamp>/`. |
32
32
  | `[shared] <host>: … rules to approve` | Those rules wait in `user-rules.draft.md` and still bind from the host file. Ask the agent to review the pending rules; the `rule` skill decides them. |
@@ -44,7 +44,7 @@ On OpenCode, two mechanisms enforce rules:
44
44
  - **OpenCode's own permission prompt**, which Geneseed configures in `opencode.json`. It asks you before `git reflog expire`, `git gc --prune` and a force-push or delete of `main`/`master`, and, when the **process** pack is on, before every commit and push.
45
45
  - **The guard plugin**, which blocks outright: writes to key and credential files (`id_rsa`, `*.pem`, `.ssh/`, `.npmrc`…), catastrophic commands (`rm -rf /`, `rm -rf ~`, formatting or overwriting a disk), every other real data loss (the same state-aware decisions as the hook), a recursive scan of a whole filesystem (`find /`, `du -sh /`, `Get-ChildItem C:\ -Recurse`), and any change inside a folder your wiki marks `protected`. It also refuses the first write to `user-rules.md` or memory once. Re-issue the write and it goes through. And in an application repo with no `## Ownership` section in its root `AGENTS.md`, it refuses the session's first write once, so the agent proposes the [ownership](../concepts/ownership.md) setup (off with `mode: off`, a personal `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`, or `--no-ownership-gate`).
46
46
 
47
- The guard only warns on `.env` edits. It checks credentials by **file path**, not by content, so a key pasted into an ordinary source file is not caught here. One caveat about the process pack: if your `opencode.json` already has a `git commit*` entry, a rebuild without the pack leaves that entry in place and reports it. Geneseed cannot tell its own entry from one you typed.
47
+ The guard only warns on `.env` edits. It checks credentials by **file path**, not by content, so a key pasted into an ordinary source file is not caught here. One caveat about the process pack: a rebuild without the pack removes the `git commit*` entry only when Geneseed recorded adding it. An entry you typed, or one from an install made before 5.2.0, stays and is reported; `--prune-gates` removes the second kind.
48
48
 
49
49
  <!--/harness-->
50
50
 
package/docs/web-ui.md CHANGED
@@ -359,7 +359,7 @@ screen the run list stacks above the detail.
359
359
  grey block, a fork amber, a `loop:` stage a teal box that names its loop (without `loop:`)
360
360
  over `whole loop`, or `not in catalogue` when this install lacks it; the ring itself is on the
361
361
  Loops page. A fork is what the engine calls one: a brick that declares a named outcome
362
- (one outside `pass`, `fail`, `error`, `none` and `needs-info`), never a `loop:` stage, however
362
+ (one outside `pass`, `fail`, `error`, `none`, `needs-info` and `reject`), never a `loop:` stage, however
363
363
  many stages its edges reach. The targets of a fork share a row, side by side, each lane labelled with its outcome,
364
364
  and join again at the first stage every lane reaches. Each route back (an edge into a cycle's
365
365
  first stage, the edge that spends a lap, `$lane` included) is a rail on the left labelled
@@ -376,13 +376,26 @@ screen the run list stacks above the detail.
376
376
  factory's rules. It reads `GET /api/factories/catalog` for the install the *Install:* picker
377
377
  names. **Active** is every run `geneseed factory init` registered on this machine
378
378
  (`GET /api/factories/active`, polled every 5 s, the graph read from each run's `FACTORY.md`),
379
- grouped as Loops › Active is; the reader shows the run's stage, transitions, task number, its
379
+ shown as a **board** while no run is selected: three columns of cards, **Waits for you** (a
380
+ held gate, or a `FACTORY.md` that cannot be read), **Running**, and **Ended** (stopped, closed,
381
+ or its `FACTORY.md` gone). A card gives the run's title, its factory, and one line of facts: where it
382
+ stands (a held gate as `stage · outcome`), its task as `i/n`, its work time so far, the wait
383
+ still open at its gate (`waiting 25 min`), and each cycle spent above 0 as `name n/max`. A
384
+ run with no state says why instead. The list beside it groups the runs under the same three
385
+ names, each row with the same facts under its factory, and while a run is open the list's
386
+ header names it by its title. A card opens the run: the reader
387
+ shows the run's stage, transitions, task number, its
380
388
  child loop's step and iteration, what it awaits, and its graph with the current stage lit,
381
389
  the lane its last fork took (the run's `lane`, else read from its `history`) lit, the child
382
390
  loop's node named under the current stage (`at <node>`) and each cycle's laps as `n / max`. A
383
391
  run carries its graph but no bricks or loops: the graph borrows those from the catalogue of the
384
392
  install the Templates tab's picker names, which the run's project may not share, and the reader
385
- says which. No run reports tab: a run's report lives in its own worktree.
393
+ says which. Under the graph, a **timeline** has one row per history entry: the stage, its
394
+ outcome or your answer at a gate, the time it was recorded (UTC), its duration (waiting time on
395
+ an answer) and a rework mark. A held run names its gate's stage, its outcome and the path of
396
+ its note; the console does not read the note. The numbers are the ones `geneseed factory report`
397
+ prints, and a time nobody recorded reads `unknown`. The board changes nothing: you answer a gate
398
+ in the agent's session. No run reports tab: a run's report lives in its own worktree.
386
399
  - **Profile** (`#/profile`) — `PROFILE.md`: who you are and how you like to work, one card
387
400
  per file: the shared one every global install reads, tagged `shared`, and each project
388
401
  install's own. Opens rendered; **Edit** is a whole-file editor. The save carries
@@ -2,5 +2,5 @@
2
2
  "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
3
3
  "theme": "neutral",
4
4
  "product": "Geneseed",
5
- "version": "5.1.1"
5
+ "version": "5.3.0"
6
6
  }