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
package/js/cli-table.json CHANGED
@@ -42,7 +42,7 @@
42
42
  },
43
43
  {
44
44
  "name": "bootstrap",
45
- "help": "update everything (upgrade) with a progress UI, then run setup",
45
+ "help": "deprecated: use upgrade --setup (kept for one release)",
46
46
  "description": "",
47
47
  "positionals": [],
48
48
  "options": [
@@ -66,8 +66,8 @@
66
66
  },
67
67
  {
68
68
  "name": "build",
69
- "help": "render the harness (same flags as geneseed-build; an omitted flag takes the generator default, not the install's — see geneseed status --json for an install's own; dry run: geneseed validate)",
70
- "description": "",
69
+ "help": "render the harness with the generator's flags (dry run: geneseed validate)",
70
+ "description": "render the harness (same flags as geneseed-build; an omitted flag takes the generator default, not the install's — see geneseed status --json for an install's own; dry run: geneseed validate)",
71
71
  "positionals": [],
72
72
  "options": [
73
73
  {
@@ -76,7 +76,7 @@
76
76
  ],
77
77
  "dest": "theme",
78
78
  "metavar": null,
79
- "help": "",
79
+ "help": "theme to render (default: harness.config.json's, else neutral)",
80
80
  "choices": null,
81
81
  "default": null,
82
82
  "required": false,
@@ -90,8 +90,8 @@
90
90
  "--emit"
91
91
  ],
92
92
  "dest": "emit",
93
- "metavar": null,
94
- "help": "",
93
+ "metavar": "EMIT",
94
+ "help": "what to write: a plain bundle (files), a project install for a host, or a -global one",
95
95
  "choices": null,
96
96
  "default": null,
97
97
  "required": false,
@@ -106,7 +106,7 @@
106
106
  ],
107
107
  "dest": "footprint",
108
108
  "metavar": null,
109
- "help": "",
109
+ "help": "lean (the default) carries each rule in brief; full carries the whole text",
110
110
  "choices": null,
111
111
  "default": null,
112
112
  "required": false,
@@ -121,7 +121,7 @@
121
121
  ],
122
122
  "dest": "posture",
123
123
  "metavar": null,
124
- "help": "",
124
+ "help": "the register the agent holds (default: harness.config.json's, else peer)",
125
125
  "choices": null,
126
126
  "default": null,
127
127
  "required": false,
@@ -136,7 +136,7 @@
136
136
  ],
137
137
  "dest": "mode",
138
138
  "metavar": null,
139
- "help": "",
139
+ "help": "how work runs (default: harness.config.json's, else direct)",
140
140
  "choices": null,
141
141
  "default": null,
142
142
  "required": false,
@@ -166,7 +166,7 @@
166
166
  ],
167
167
  "dest": "doctrines",
168
168
  "metavar": null,
169
- "help": "",
169
+ "help": "doctrine packs to switch on, comma-separated, or 'none' (default: every pack)",
170
170
  "choices": null,
171
171
  "default": null,
172
172
  "required": false,
@@ -181,7 +181,7 @@
181
181
  ],
182
182
  "dest": "exclude_rules",
183
183
  "metavar": null,
184
- "help": "",
184
+ "help": "rules to switch off, comma-separated ('process 7,craft 3'), or 'none'",
185
185
  "choices": null,
186
186
  "default": null,
187
187
  "required": false,
@@ -196,7 +196,7 @@
196
196
  ],
197
197
  "dest": "exclude_skills",
198
198
  "metavar": null,
199
- "help": "",
199
+ "help": "skills to leave out, comma-separated, or 'none'",
200
200
  "choices": null,
201
201
  "default": null,
202
202
  "required": false,
@@ -241,7 +241,7 @@
241
241
  ],
242
242
  "dest": "out",
243
243
  "metavar": null,
244
- "help": "",
244
+ "help": "output dir (default: Harness); a project emit installs into it unless --root is given",
245
245
  "choices": null,
246
246
  "default": null,
247
247
  "required": false,
@@ -256,7 +256,7 @@
256
256
  ],
257
257
  "dest": "root",
258
258
  "metavar": null,
259
- "help": "",
259
+ "help": "the repo a project emit installs into (default: --out)",
260
260
  "choices": null,
261
261
  "default": null,
262
262
  "required": false,
@@ -405,8 +405,8 @@
405
405
  },
406
406
  {
407
407
  "name": "catalog",
408
- "help": "list what this harness ships: every agent, skill and constitutional rule, with its one-line purpose and lifecycle status",
409
- "description": "",
408
+ "help": "list every agent, skill and constitutional rule this harness ships",
409
+ "description": "list what this harness ships: every agent, skill and constitutional rule, with its one-line purpose and lifecycle status",
410
410
  "positionals": [
411
411
  {
412
412
  "names": [],
@@ -513,7 +513,7 @@
513
513
  ],
514
514
  "dest": "target",
515
515
  "metavar": null,
516
- "help": "deployed config dir (default: $OPENCODE_CONFIG_DIR / ~/.config/opencode)",
516
+ "help": "deployed config dir (default: the global install there is; with several, the first, named on stderr)",
517
517
  "choices": null,
518
518
  "default": null,
519
519
  "required": false,
@@ -572,8 +572,8 @@
572
572
  },
573
573
  {
574
574
  "name": "doctor",
575
- "help": "validate the build: unresolved tokens, dead links, non-hermetic escapes, theme-key parity, and that a committed bundle matches src. Defaults to the INSTALLED theme (--theme NAME for one, --all to sweep every theme)",
576
- "description": "",
575
+ "help": "validate the build (the installed theme; --all sweeps every theme, slowly)",
576
+ "description": "validate the build: unresolved tokens, dead links, non-hermetic escapes, theme-key parity, and that a committed bundle matches src. Defaults to the INSTALLED theme (--theme NAME for one, --all to sweep every theme). --all renders every theme through every emit, so it takes minutes rather than seconds; it prints one progress line per theme on stderr.",
577
577
  "positionals": [],
578
578
  "options": [
579
579
  {
@@ -582,7 +582,7 @@
582
582
  ],
583
583
  "dest": "theme",
584
584
  "metavar": null,
585
- "help": "",
585
+ "help": "theme to check (default: the installed theme)",
586
586
  "choices": null,
587
587
  "default": null,
588
588
  "required": false,
@@ -597,7 +597,7 @@
597
597
  ],
598
598
  "dest": "all",
599
599
  "metavar": null,
600
- "help": "sweep EVERY theme (maintainer full check / CI), not just the installed one — the default scopes to the installed theme",
600
+ "help": "sweep EVERY theme (maintainer full check / CI), not just the installed one — the default scopes to the installed theme; it renders every theme through every emit, so it takes minutes and prints one progress line per theme on stderr",
601
601
  "choices": null,
602
602
  "default": false,
603
603
  "required": false,
@@ -656,8 +656,8 @@
656
656
  },
657
657
  {
658
658
  "name": "exclude",
659
- "help": "manage sovereign-repo exclusions: folders where the GLOBAL installs go dormant (hooks silent, preamble suppressed); stored in the shared tier's excludes.json, with the repo-side wiring per host",
660
- "description": "",
659
+ "help": "manage the folders where the global installs go dormant",
660
+ "description": "manage sovereign-repo exclusions: folders where the GLOBAL installs go dormant (hooks silent, preamble suppressed); stored in the shared tier's excludes.json, with the repo-side wiring per host",
661
661
  "positionals": [
662
662
  {
663
663
  "names": [],
@@ -695,8 +695,8 @@
695
695
  },
696
696
  {
697
697
  "name": "export",
698
- "help": "write the skills, the agents and the constitution as catalogue entities for a shared library: one folder each with SKILL.md or AGENT.md (frontmatter name and description only) and a metadata.yaml. One way: the source stays src/. Not an install: no carrier, hooks or settings",
699
- "description": "",
698
+ "help": "write the skills, agents and constitution as entities for a shared library",
699
+ "description": "write the skills, the agents and the constitution as catalogue entities for a shared library: one folder each with SKILL.md or AGENT.md (frontmatter name and description only) and a metadata.yaml. One way: the source stays src/. Not an install: no carrier, hooks or settings",
700
700
  "positionals": [],
701
701
  "options": [
702
702
  {
@@ -764,8 +764,8 @@
764
764
  },
765
765
  {
766
766
  "name": "factory",
767
- "help": "run a factory: carry one work item through a graph of bricks and whole loops to an open PR (check/list/init/next/record/decide)",
768
- "description": "",
767
+ "help": "run a factory: carry one work item through bricks and loops to an open PR",
768
+ "description": "run a factory: carry one work item through a graph of bricks and whole loops to an open PR (check/list/init/next/record/decide/report)",
769
769
  "positionals": [
770
770
  {
771
771
  "names": [],
@@ -778,7 +778,8 @@
778
778
  "init",
779
779
  "next",
780
780
  "record",
781
- "decide"
781
+ "decide",
782
+ "report"
782
783
  ],
783
784
  "default": null,
784
785
  "required": true,
@@ -880,6 +881,19 @@
880
881
  "type": null,
881
882
  "hidden": false
882
883
  },
884
+ {
885
+ "names": ["--tokens"],
886
+ "dest": "tokens",
887
+ "metavar": null,
888
+ "help": "the token count the host reported for the agent that ran the stage, a positive integer; left out when the host gave none (record)",
889
+ "choices": null,
890
+ "default": null,
891
+ "required": false,
892
+ "nargs": null,
893
+ "is_flag": false,
894
+ "type": null,
895
+ "hidden": false
896
+ },
883
897
  {
884
898
  "names": ["--carry-file"],
885
899
  "dest": "carry_file",
@@ -1025,8 +1039,8 @@
1025
1039
  },
1026
1040
  {
1027
1041
  "name": "home",
1028
- "help": "default entry for a bare ./geneseed: open the web UI when possible (interactive + GUI browser), else the TUI menu",
1029
- "description": "",
1042
+ "help": "default for a bare geneseed: the web UI when possible, else the menu",
1043
+ "description": "default entry for a bare `geneseed`: open the web UI when possible (an interactive terminal and a GUI browser), else print the menu",
1030
1044
  "positionals": [],
1031
1045
  "options": [],
1032
1046
  "mutex": []
@@ -1138,8 +1152,8 @@
1138
1152
  },
1139
1153
  {
1140
1154
  "name": "loop",
1141
- "help": "run a loop: check graphs, start one in LOOP.md, and step its state machine (next/score/record/decide)",
1142
- "description": "",
1155
+ "help": "run a loop: check graphs, start one in LOOP.md, and step its state machine",
1156
+ "description": "run a loop: check graphs, start one in LOOP.md, and step its state machine (next/score/record/decide)",
1143
1157
  "positionals": [
1144
1158
  {
1145
1159
  "names": [],
@@ -1405,8 +1419,8 @@
1405
1419
  },
1406
1420
  {
1407
1421
  "name": "memory",
1408
- "help": "manage the memory store: list the facts the agent reads, remove one by name (archived into memory/archive/; --purge deletes), or rebuild the index by hand with consolidate (MEMORY.md and topics/, from the fact files on disk). A global install's store is the shared tier, ~/.config/geneseed/memory; a project install keeps its own",
1409
- "description": "",
1422
+ "help": "manage the memory store: list, remove, or rebuild the index",
1423
+ "description": "manage the memory store: list the facts the agent reads, remove one by name (archived into memory/archive/; --purge deletes), or rebuild the index by hand with consolidate (MEMORY.md and topics/, from the fact files on disk). A global install's store is the shared tier, ~/.config/geneseed/memory; a project install keeps its own",
1410
1424
  "positionals": [
1411
1425
  {
1412
1426
  "names": [],
@@ -1490,7 +1504,7 @@
1490
1504
  },
1491
1505
  {
1492
1506
  "name": "menu",
1493
- "help": "interactive main menu (the default for ./geneseed)",
1507
+ "help": "print the main command list",
1494
1508
  "description": "",
1495
1509
  "positionals": [],
1496
1510
  "options": [],
@@ -1498,8 +1512,8 @@
1498
1512
  },
1499
1513
  {
1500
1514
  "name": "migrate",
1501
- "help": "move this machine from the git-checkout install shape to the npm one: run from the npm package, it re-emits every registered install, which points the hook shim at that package, and reports what must be fixed by hand. A git clone or a bundle is refused with exit 3. Use --dry-run alone, from anywhere, to preview the shared-tier fold",
1502
- "description": "",
1515
+ "help": "move this machine from the git-checkout install shape to the npm one",
1516
+ "description": "move this machine from the git-checkout install shape to the npm one: run from the npm package, it re-emits every registered install, which points the hook shim at that package, and reports what must be fixed by hand. A git clone or a bundle is refused with exit 3. Use --dry-run alone, from anywhere, to preview the shared-tier fold",
1503
1517
  "positionals": [],
1504
1518
  "options": [
1505
1519
  {
@@ -1522,7 +1536,7 @@
1522
1536
  },
1523
1537
  {
1524
1538
  "name": "prompt",
1525
- "help": "emit a self-contained install prompt (no Python needed to use it)",
1539
+ "help": "emit a self-contained install prompt",
1526
1540
  "description": "",
1527
1541
  "positionals": [],
1528
1542
  "options": [
@@ -1532,7 +1546,7 @@
1532
1546
  ],
1533
1547
  "dest": "theme",
1534
1548
  "metavar": null,
1535
- "help": "",
1549
+ "help": "theme of the prompt (default: harness.config.json's, else neutral)",
1536
1550
  "choices": null,
1537
1551
  "default": null,
1538
1552
  "required": false,
@@ -1561,8 +1575,8 @@
1561
1575
  },
1562
1576
  {
1563
1577
  "name": "rebuild-all",
1564
- "help": "rebuild every active install in place (each in its own theme+emit), best-effort — continue past failures",
1565
- "description": "",
1578
+ "help": "rebuild every active install in place, each in its own theme and emit",
1579
+ "description": "rebuild every active install in place (each in its own theme+emit), best-effort — continue past failures",
1566
1580
  "positionals": [],
1567
1581
  "options": [],
1568
1582
  "mutex": []
@@ -1668,8 +1682,8 @@
1668
1682
  },
1669
1683
  {
1670
1684
  "name": "scorecard",
1671
- "help": "grade a repo with the AI Harness Scorecard (31 checks, five pillars) — scores the repo itself (CI, tests, docs), not the harness files; a reading, never a gate",
1672
- "description": "",
1685
+ "help": "grade a repo with the AI Harness Scorecard (a reading, never a gate)",
1686
+ "description": "grade a repo with the AI Harness Scorecard (31 checks, five pillars) — scores the repo itself (CI, tests, docs), not the harness files; a reading, never a gate",
1673
1687
  "positionals": [
1674
1688
  {
1675
1689
  "names": [],
@@ -1729,8 +1743,8 @@
1729
1743
  },
1730
1744
  {
1731
1745
  "name": "status",
1732
- "help": "print the install dashboard as text (theme, mode, counts, memory, version)",
1733
- "description": "",
1746
+ "help": "print the install dashboard (theme, installs, memory, version, gates)",
1747
+ "description": "print the install dashboard: theme, every install with its settings, components, memory, version, and the state of the tool-boundary gates. --json prints the same payload for a script. Off a terminal the rows are plain, with no box.",
1734
1748
  "positionals": [],
1735
1749
  "options": [
1736
1750
  {
@@ -1751,8 +1765,8 @@
1751
1765
  },
1752
1766
  {
1753
1767
  "name": "theme",
1754
- "help": "create a user OpenCode colour theme (solid + transparent) in the live themes dir; survives rebuilds",
1755
- "description": "",
1768
+ "help": "create a user OpenCode colour theme in the live themes dir",
1769
+ "description": "create a user OpenCode colour theme (solid + transparent) in the live themes dir; survives rebuilds",
1756
1770
  "positionals": [
1757
1771
  {
1758
1772
  "names": [],
@@ -1983,7 +1997,7 @@
1983
1997
  },
1984
1998
  {
1985
1999
  "name": "tui",
1986
- "help": "print the harness at a glance (interactive terminals only)",
2000
+ "help": "retired: prints one line pointing at menu (kept for one release)",
1987
2001
  "description": "",
1988
2002
  "positionals": [],
1989
2003
  "options": [
@@ -2007,8 +2021,8 @@
2007
2021
  },
2008
2022
  {
2009
2023
  "name": "uninstall",
2010
- "help": "remove a global or project-scoped Geneseed install (manifest-tracked); memory/notebook are never deleted (--archive-memory moves them aside), and the shared tier, ~/.config/geneseed, is left alone",
2011
- "description": "",
2024
+ "help": "remove a global or project install (memory and notebook are kept)",
2025
+ "description": "remove a global or project-scoped Geneseed install (manifest-tracked); memory/notebook are never deleted (--archive-memory moves them aside), and the shared tier, ~/.config/geneseed, is left alone",
2012
2026
  "positionals": [],
2013
2027
  "options": [
2014
2028
  {
@@ -2017,7 +2031,7 @@
2017
2031
  ],
2018
2032
  "dest": "target",
2019
2033
  "metavar": null,
2020
- "help": "repo (project scope) or config dir (global scope) to uninstall from; default: the cwd if it holds a project install, else the OpenCode global config dir",
2034
+ "help": "repo (project scope) or config dir (global scope) to uninstall from; default: the cwd if it holds a project install, else the one global install (refused, exit 2, when there are several)",
2021
2035
  "choices": null,
2022
2036
  "default": null,
2023
2037
  "required": false,
@@ -2101,13 +2115,44 @@
2101
2115
  "hidden": false
2102
2116
  }
2103
2117
  ],
2104
- "options": [],
2118
+ "options": [
2119
+ {
2120
+ "names": [
2121
+ "--setup"
2122
+ ],
2123
+ "dest": "setup",
2124
+ "metavar": null,
2125
+ "help": "after the update, run the setup wizard (what bootstrap did)",
2126
+ "choices": null,
2127
+ "default": false,
2128
+ "required": false,
2129
+ "nargs": "0",
2130
+ "is_flag": true,
2131
+ "type": null,
2132
+ "hidden": false
2133
+ },
2134
+ {
2135
+ "names": [
2136
+ "--theme"
2137
+ ],
2138
+ "dest": "theme_opt",
2139
+ "metavar": "THEME",
2140
+ "help": "force a theme, as the theme argument does",
2141
+ "choices": null,
2142
+ "default": null,
2143
+ "required": false,
2144
+ "nargs": null,
2145
+ "is_flag": false,
2146
+ "type": null,
2147
+ "hidden": false
2148
+ }
2149
+ ],
2105
2150
  "mutex": []
2106
2151
  },
2107
2152
  {
2108
2153
  "name": "upgrade",
2109
- "help": "self-update: git pull the install's origin (ff-only), validate, then rebuild the bundle + every install",
2110
- "description": "",
2154
+ "help": "self-update: git pull (ff-only), validate, then rebuild every install",
2155
+ "description": "self-update: git pull the install's origin (ff-only), validate, then rebuild the bundle + every install",
2111
2156
  "positionals": [
2112
2157
  {
2113
2158
  "names": [],
@@ -2123,12 +2168,43 @@
2123
2168
  "hidden": false
2124
2169
  }
2125
2170
  ],
2126
- "options": [],
2171
+ "options": [
2172
+ {
2173
+ "names": [
2174
+ "--setup"
2175
+ ],
2176
+ "dest": "setup",
2177
+ "metavar": null,
2178
+ "help": "after the update, run the setup wizard (what bootstrap did)",
2179
+ "choices": null,
2180
+ "default": false,
2181
+ "required": false,
2182
+ "nargs": "0",
2183
+ "is_flag": true,
2184
+ "type": null,
2185
+ "hidden": false
2186
+ },
2187
+ {
2188
+ "names": [
2189
+ "--theme"
2190
+ ],
2191
+ "dest": "theme_opt",
2192
+ "metavar": "THEME",
2193
+ "help": "force a theme, as the theme argument does",
2194
+ "choices": null,
2195
+ "default": null,
2196
+ "required": false,
2197
+ "nargs": null,
2198
+ "is_flag": false,
2199
+ "type": null,
2200
+ "hidden": false
2201
+ }
2202
+ ],
2127
2203
  "mutex": []
2128
2204
  },
2129
2205
  {
2130
2206
  "name": "version",
2131
- "help": "show installed vs current-source fingerprint and whether they match",
2207
+ "help": "compare the installed build's fingerprint with this source",
2132
2208
  "description": "",
2133
2209
  "positionals": [],
2134
2210
  "options": [
@@ -2138,7 +2214,7 @@
2138
2214
  ],
2139
2215
  "dest": "target",
2140
2216
  "metavar": null,
2141
- "help": "deployed dir to check (default: the OpenCode global config dir)",
2217
+ "help": "deployed dir to check (default: the global install there is; with several, the first, named on stderr)",
2142
2218
  "choices": null,
2143
2219
  "default": null,
2144
2220
  "required": false,
@@ -2152,8 +2228,8 @@
2152
2228
  },
2153
2229
  {
2154
2230
  "name": "web",
2155
- "help": "serve the deployed harness as a local web UI (browse agents/skills/laws/memory + run actions)",
2156
- "description": "",
2231
+ "help": "serve the deployed harness as a local web UI",
2232
+ "description": "serve the deployed harness as a local web UI (browse agents/skills/laws/memory + run actions)",
2157
2233
  "positionals": [
2158
2234
  {
2159
2235
  "names": [],
@@ -42,6 +42,10 @@
42
42
  * `--carry-file` AND `--note-file` (M7) take the text from a file, never the command line
43
43
  * (`textArg`, shared with `geneseed loop`): free text can hold any word and any quote. The Rite
44
44
  * writes that file with the host's file tool, never the shell, under a name it makes unique.
45
+ *
46
+ * THE CLOCK IS READ HERE (D2): `init`, `next`, `record` and `decide` pass the time now to the
47
+ * engine, which stays pure. `report` prints `runMetrics` and writes nothing, so the `retro` brick
48
+ * and the Rite read durations off it and no model does date arithmetic (D5).
45
49
  */
46
50
  import { readFileSync } from 'node:fs';
47
51
  import path from 'node:path';
@@ -57,6 +61,7 @@ import {
57
61
  FACTORY_FILE, initFactory, nextStage, recordStage, decideFactory, writeFactoryFile, parseFactoryFile,
58
62
  validateFactoryState, countSpecTasks,
59
63
  } from './state.mjs';
64
+ import { runMetrics } from './metrics.mjs';
60
65
 
61
66
  const emit = (obj) => { printOut(`${JSON.stringify(obj)}\n`); return obj.error || obj.ok === false ? 1 : 0; };
62
67
  const stdin = () => (process.stdin.isTTY ? null : readFileSync(0, 'utf8'));
@@ -83,18 +88,25 @@ function requireRoot() {
83
88
  * R4: an unreadable FACTORY.md throws in `parseFactoryFile` or `validateFactoryState`, before `fn`
84
89
  * runs or anything is written.
85
90
  */
86
- function withState(fn) {
91
+ function readState() {
87
92
  const root = requireRoot();
88
93
  const file = path.join(root, FACTORY_FILE);
89
94
  if (!isFile(file)) throw new Error(`${file} does not exist — run \`geneseed factory init\` first`);
90
95
  const state = parseFactoryFile(readText(file));
91
96
  const catalog = loadCatalog({ projectRoot: root });
92
97
  validateFactoryState(state, catalog);
98
+ return { root, file, state, catalog };
99
+ }
100
+
101
+ function withState(fn) {
102
+ const { root, file, state, catalog } = readState();
93
103
  const result = fn(state, catalog, { root, head: headCommit(root), ...loopFileOf(root) });
94
104
  writeFactoryFile(file, state);
95
105
  return result;
96
106
  }
97
107
 
108
+ const nowIso = () => new Date().toISOString();
109
+
98
110
  function resolveFactory(spec, catalog) {
99
111
  if (spec.endsWith('.json')) return JSON.parse(readText(path.resolve(spec)));
100
112
  const f = catalog.factories.get(spec);
@@ -149,17 +161,22 @@ const ACTIONS = {
149
161
  const factory = resolveFactory(args.factory, catalog);
150
162
  const problems = checkFactory(factory, catalog);
151
163
  if (problems.length) return { error: 'the factory does not pass factory check', problems };
152
- const state = initFactory({ title: args.title, requirement: args.requirement, factory, input: args.input ?? null });
164
+ const state = initFactory({ title: args.title, requirement: args.requirement, factory, input: args.input ?? null, now: nowIso() });
153
165
  writeFactoryFile(file, state);
154
166
  // Best-effort, as `loop init`'s `recordLoop`: the registry is how the console finds the run.
155
167
  recordFactory({ root, branch: currentBranch(root), factory: factory.name, title: args.title });
156
168
  return { file, factory: factory.name, stage: state.stage, status: state.status };
157
169
  },
158
- next: () => withState((s, c, { loopStatus, head }) => nextStage(s, c, { loopStatus, head, now: new Date().toISOString() })),
170
+ next: () => withState((s, c, { loopStatus, head }) => nextStage(s, c, { loopStatus, head, now: nowIso() })),
159
171
  record(args) {
160
172
  if (!args.outcome) throw new Error('record needs --outcome');
161
173
  const carry = textArg(args, 'carry', 'carry', 'record');
162
174
  const porcelain = stdin();
175
+ // D3: digits only, so `1e3`, `1.5`, `-4` and `0` are refused here, before the state is read
176
+ if (args.tokens != null && !/^[1-9]\d*$/.test(String(args.tokens))) {
177
+ throw new Error(`--tokens ${args.tokens} is not a positive integer: pass the count the host reported, or leave it out`);
178
+ }
179
+ const tokens = args.tokens != null ? Number(args.tokens) : null;
163
180
  return withState((s, c, { root, loopStatus, loopTemplate, head }) => {
164
181
  let specPath = null; let taskCount = null;
165
182
  if (args.spec) {
@@ -175,14 +192,16 @@ const ACTIONS = {
175
192
  // Windows PowerShell 5.1 re-encodes a native pipe: CRLF line ends, and a leading BOM when $OutputEncoding is UTF-8
176
193
  porcelain: porcelain === null ? null : porcelain.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n').trimEnd(),
177
194
  specPath, taskCount, carry, loopStatus, loopTemplate, head,
178
- loopInitAt: loopInitAt(root),
195
+ loopInitAt: loopInitAt(root), now: nowIso(), tokens,
179
196
  });
180
197
  });
181
198
  },
182
199
  decide(args) {
183
200
  const note = textArg(args, 'note', 'note', 'decide') ?? '';
184
- return withState((s, c) => decideFactory(s, c, args.verdict, note));
201
+ return withState((s, c) => decideFactory(s, c, args.verdict, note, { now: nowIso() }));
185
202
  },
203
+ // D5: read-only, and validated like every state action, so the numbers come from a state the engine could have written
204
+ report: () => runMetrics(readState().state, { now: nowIso() }),
186
205
  };
187
206
 
188
207
  export function cmdFactory(args) {
@@ -11,7 +11,7 @@
11
11
  * rather than copied, so the two engines cannot drift on what "declared" means.
12
12
  *
13
13
  * FORKS AND `$lane` (D11, D13). A fork is a brick stage that declares an outcome other than
14
- * `pass`, `fail`, `error`, `none` or `needs-info` — a named outcome, such as `triage`'s `bug` or `docs`. Each
14
+ * `pass`, `fail`, `error`, `none`, `needs-info` or `reject` — a named outcome, such as `triage`'s `bug` or `docs`. Each
15
15
  * outcome has its own edge (rule 3), so the edges out of a fork ARE its lanes: an outcome whose
16
16
  * edge reaches a stage. An edge target or a cycle node may be `$lane`: the stage the run's most
17
17
  * recent fork chose, which the engine records in FACTORY.md and resolves at runtime. Statically,
@@ -55,10 +55,13 @@ export const LOOP_OUTCOMES = ['pass', 'fail'];
55
55
  /**
56
56
  * The outcomes that name no lane; any other declared outcome makes its brick a fork (D11).
57
57
  * `needs-info` is `intake`'s question to the user (a gate), never a lane: listed here, it sets
58
- * no `state.lane`, hands no `lanes` and leaves `$lane` alone.
58
+ * no `state.lane`, hands no `lanes` and leaves `$lane` alone. `reject` is `intake`'s refusal of
59
+ * the work item (already done, a duplicate, against a stated rule): a gate too, and no lane, so a
60
+ * brick that declares it stays a plain stage.
59
61
  */
60
62
  const NEEDS_INFO = 'needs-info';
61
- const PLAIN_OUTCOMES = new Set(['pass', 'fail', 'error', 'none', NEEDS_INFO]);
63
+ const REJECT = 'reject';
64
+ const PLAIN_OUTCOMES = new Set(['pass', 'fail', 'error', 'none', NEEDS_INFO, REJECT]);
62
65
  /** The work item sizes `intake` rates; `review.seats` needs a list for each (rule 9). */
63
66
  const SEAT_SIZES = ['small', 'medium', 'large'];
64
67
  /**
@@ -72,13 +75,14 @@ const edgeShaped = (e) => ['from', 'on', 'to'].every((k) => typeof e?.[k] === 's
72
75
 
73
76
  /**
74
77
  * The edge an outcome follows: its own, else for `needs-info` the stage's `pass` edge (a factory
75
- * with no needs-info edge goes on as if intake had passed), else for `error` a stop. Null when
76
- * none applies. The engine's one lookup, so `record` and a gate's `ok` cannot disagree.
78
+ * with no needs-info edge goes on as if intake had passed), else for `error` and `reject` a stop
79
+ * (a refused item has nowhere to go but `$stop`, so a factory written before intake could refuse
80
+ * needs no new edge). Null when none applies. The engine's one lookup, so `record` and a gate's `ok` cannot disagree.
77
81
  */
78
82
  export function edgeFor(factory, from, outcome) {
79
83
  const own = (on) => (Array.isArray(factory?.edges) ? factory.edges : []).find((e) => e?.from === from && e.on === on);
80
84
  return own(outcome) ?? (outcome === NEEDS_INFO ? own('pass') : undefined)
81
- ?? (outcome === 'error' ? { from, on: 'error', to: '$stop' } : null);
85
+ ?? (outcome === 'error' || outcome === REJECT ? { from, on: outcome, to: '$stop' } : null);
82
86
  }
83
87
 
84
88
  /** The template a `loop:` stage names, or null for a brick stage. */
@@ -210,13 +214,13 @@ export function checkFactory(factory, { bricks, templates, agents }) {
210
214
  const outcomes = stageOutcomes(e.from, bricks);
211
215
  if (outcomes && !outcomes.includes(e.on)) problems.push(`${label}: ${e.on} is not an outcome of ${e.from}`);
212
216
  }
213
- // rule 3 — exactly one edge per outcome; `error` may go without one (the engine routes it to
214
- // $stop), and so may `needs-info` when the stage has a `pass` edge for it to follow (`edgeFor`),
217
+ // rule 3 — exactly one edge per outcome; `error` and `reject` may go without one (the engine
218
+ // routes each to $stop), and so may `needs-info` when the stage has a `pass` edge for it to follow (`edgeFor`),
215
219
  // so a factory written before intake could ask stays valid, and so does a FACTORY.md that embeds one
216
220
  for (const s of [...stages].sort()) {
217
221
  for (const o of stageOutcomes(s, bricks) ?? []) {
218
222
  const count = edges.filter((e) => e.from === s && e.on === o).length;
219
- const exempt = o === 'error' || (o === NEEDS_INFO && edges.some((e) => e.from === s && e.on === 'pass'));
223
+ const exempt = o === 'error' || o === REJECT || (o === NEEDS_INFO && edges.some((e) => e.from === s && e.on === 'pass'));
220
224
  if (count === 0 && !exempt) problems.push(`stage ${s}: no edge for outcome ${o}`);
221
225
  else if (count > 1) problems.push(`stage ${s}: ${count} edges for outcome ${o}`);
222
226
  }