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/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,
@@ -369,14 +369,44 @@
369
369
  "is_flag": true,
370
370
  "type": null,
371
371
  "hidden": false
372
+ },
373
+ {
374
+ "names": [
375
+ "--prune-gates"
376
+ ],
377
+ "dest": "prune_gates",
378
+ "metavar": null,
379
+ "help": "OpenCode only, this build only: remove from opencode.json the permission.bash gates whose rule this build has off (a doctrine, or the deletion gate) and that still read as Geneseed writes them, on an install made before Geneseed recorded which gates it added; an entry you changed stays. Never replayed by rebuilds",
380
+ "choices": null,
381
+ "default": false,
382
+ "required": false,
383
+ "nargs": "0",
384
+ "is_flag": true,
385
+ "type": null,
386
+ "hidden": false
387
+ },
388
+ {
389
+ "names": [
390
+ "--force"
391
+ ],
392
+ "dest": "force",
393
+ "metavar": null,
394
+ "help": "for this one build, take Geneseed's copy of every file it ships: replaces a shipped file you edited and a file of yours at a shipped name, removes a retired file you edited, and removes retired skills an older build left in a bundle. Each file is named. A skill or agent under a name Geneseed does not ship is never touched, nor is memory, the notebook, your rules or your profile. Not recorded: the next build is an ordinary one",
395
+ "choices": null,
396
+ "default": false,
397
+ "required": false,
398
+ "nargs": "0",
399
+ "is_flag": true,
400
+ "type": null,
401
+ "hidden": false
372
402
  }
373
403
  ],
374
404
  "mutex": []
375
405
  },
376
406
  {
377
407
  "name": "catalog",
378
- "help": "list what this harness ships: every agent, skill and constitutional rule, with its one-line purpose and lifecycle status",
379
- "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",
380
410
  "positionals": [
381
411
  {
382
412
  "names": [],
@@ -483,7 +513,7 @@
483
513
  ],
484
514
  "dest": "target",
485
515
  "metavar": null,
486
- "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)",
487
517
  "choices": null,
488
518
  "default": null,
489
519
  "required": false,
@@ -542,8 +572,8 @@
542
572
  },
543
573
  {
544
574
  "name": "doctor",
545
- "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)",
546
- "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.",
547
577
  "positionals": [],
548
578
  "options": [
549
579
  {
@@ -552,7 +582,7 @@
552
582
  ],
553
583
  "dest": "theme",
554
584
  "metavar": null,
555
- "help": "",
585
+ "help": "theme to check (default: the installed theme)",
556
586
  "choices": null,
557
587
  "default": null,
558
588
  "required": false,
@@ -567,7 +597,7 @@
567
597
  ],
568
598
  "dest": "all",
569
599
  "metavar": null,
570
- "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",
571
601
  "choices": null,
572
602
  "default": false,
573
603
  "required": false,
@@ -626,8 +656,8 @@
626
656
  },
627
657
  {
628
658
  "name": "exclude",
629
- "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",
630
- "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",
631
661
  "positionals": [
632
662
  {
633
663
  "names": [],
@@ -663,10 +693,79 @@
663
693
  "options": [],
664
694
  "mutex": []
665
695
  },
696
+ {
697
+ "name": "export",
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
+ "positionals": [],
701
+ "options": [
702
+ {
703
+ "names": [
704
+ "--out"
705
+ ],
706
+ "dest": "out",
707
+ "metavar": null,
708
+ "help": "the folder the entity folders are written into (required); it may be a checkout of the library: only files an earlier export wrote there are replaced or pruned",
709
+ "choices": null,
710
+ "default": null,
711
+ "required": false,
712
+ "nargs": null,
713
+ "is_flag": false,
714
+ "type": null,
715
+ "hidden": false
716
+ },
717
+ {
718
+ "names": [
719
+ "--profile"
720
+ ],
721
+ "dest": "profile",
722
+ "metavar": null,
723
+ "help": "a JSON file with the receiving library's rules, prefix, owner, maintainer, status, compatibleTools, skillsDir, agentsDir, lawsDir, lawsName, laws, only, exclude, keepSkillSelfImprovement (default: export.profile.json at the root of a git checkout when it has one, else none; `none` exports under the source names with no owner)",
724
+ "choices": null,
725
+ "default": null,
726
+ "required": false,
727
+ "nargs": null,
728
+ "is_flag": false,
729
+ "type": null,
730
+ "hidden": false
731
+ },
732
+ {
733
+ "names": [
734
+ "--theme"
735
+ ],
736
+ "dest": "theme",
737
+ "metavar": null,
738
+ "help": "the voice the text is rendered in (default: neutral)",
739
+ "choices": null,
740
+ "default": null,
741
+ "required": false,
742
+ "nargs": null,
743
+ "is_flag": false,
744
+ "type": null,
745
+ "hidden": false
746
+ },
747
+ {
748
+ "names": [
749
+ "--kits"
750
+ ],
751
+ "dest": "kits",
752
+ "metavar": null,
753
+ "help": "comma-separated kits whose skills and agents are exported, or none (default: every kit)",
754
+ "choices": null,
755
+ "default": null,
756
+ "required": false,
757
+ "nargs": null,
758
+ "is_flag": false,
759
+ "type": null,
760
+ "hidden": false
761
+ }
762
+ ],
763
+ "mutex": []
764
+ },
666
765
  {
667
766
  "name": "factory",
668
- "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)",
669
- "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)",
670
769
  "positionals": [
671
770
  {
672
771
  "names": [],
@@ -679,7 +778,8 @@
679
778
  "init",
680
779
  "next",
681
780
  "record",
682
- "decide"
781
+ "decide",
782
+ "report"
683
783
  ],
684
784
  "default": null,
685
785
  "required": true,
@@ -781,6 +881,19 @@
781
881
  "type": null,
782
882
  "hidden": false
783
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
+ },
784
897
  {
785
898
  "names": ["--carry-file"],
786
899
  "dest": "carry_file",
@@ -926,8 +1039,8 @@
926
1039
  },
927
1040
  {
928
1041
  "name": "home",
929
- "help": "default entry for a bare ./geneseed: open the web UI when possible (interactive + GUI browser), else the TUI menu",
930
- "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",
931
1044
  "positionals": [],
932
1045
  "options": [],
933
1046
  "mutex": []
@@ -1039,8 +1152,8 @@
1039
1152
  },
1040
1153
  {
1041
1154
  "name": "loop",
1042
- "help": "run a loop: check graphs, start one in LOOP.md, and step its state machine (next/score/record/decide)",
1043
- "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)",
1044
1157
  "positionals": [
1045
1158
  {
1046
1159
  "names": [],
@@ -1306,8 +1419,8 @@
1306
1419
  },
1307
1420
  {
1308
1421
  "name": "memory",
1309
- "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",
1310
- "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",
1311
1424
  "positionals": [
1312
1425
  {
1313
1426
  "names": [],
@@ -1391,7 +1504,7 @@
1391
1504
  },
1392
1505
  {
1393
1506
  "name": "menu",
1394
- "help": "interactive main menu (the default for ./geneseed)",
1507
+ "help": "print the main command list",
1395
1508
  "description": "",
1396
1509
  "positionals": [],
1397
1510
  "options": [],
@@ -1399,8 +1512,8 @@
1399
1512
  },
1400
1513
  {
1401
1514
  "name": "migrate",
1402
- "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",
1403
- "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",
1404
1517
  "positionals": [],
1405
1518
  "options": [
1406
1519
  {
@@ -1423,7 +1536,7 @@
1423
1536
  },
1424
1537
  {
1425
1538
  "name": "prompt",
1426
- "help": "emit a self-contained install prompt (no Python needed to use it)",
1539
+ "help": "emit a self-contained install prompt",
1427
1540
  "description": "",
1428
1541
  "positionals": [],
1429
1542
  "options": [
@@ -1433,7 +1546,7 @@
1433
1546
  ],
1434
1547
  "dest": "theme",
1435
1548
  "metavar": null,
1436
- "help": "",
1549
+ "help": "theme of the prompt (default: harness.config.json's, else neutral)",
1437
1550
  "choices": null,
1438
1551
  "default": null,
1439
1552
  "required": false,
@@ -1462,8 +1575,8 @@
1462
1575
  },
1463
1576
  {
1464
1577
  "name": "rebuild-all",
1465
- "help": "rebuild every active install in place (each in its own theme+emit), best-effort — continue past failures",
1466
- "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",
1467
1580
  "positionals": [],
1468
1581
  "options": [],
1469
1582
  "mutex": []
@@ -1569,8 +1682,8 @@
1569
1682
  },
1570
1683
  {
1571
1684
  "name": "scorecard",
1572
- "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",
1573
- "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",
1574
1687
  "positionals": [
1575
1688
  {
1576
1689
  "names": [],
@@ -1630,8 +1743,8 @@
1630
1743
  },
1631
1744
  {
1632
1745
  "name": "status",
1633
- "help": "print the install dashboard as text (theme, mode, counts, memory, version)",
1634
- "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.",
1635
1748
  "positionals": [],
1636
1749
  "options": [
1637
1750
  {
@@ -1652,8 +1765,8 @@
1652
1765
  },
1653
1766
  {
1654
1767
  "name": "theme",
1655
- "help": "create a user OpenCode colour theme (solid + transparent) in the live themes dir; survives rebuilds",
1656
- "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",
1657
1770
  "positionals": [
1658
1771
  {
1659
1772
  "names": [],
@@ -1884,7 +1997,7 @@
1884
1997
  },
1885
1998
  {
1886
1999
  "name": "tui",
1887
- "help": "print the harness at a glance (interactive terminals only)",
2000
+ "help": "retired: prints one line pointing at menu (kept for one release)",
1888
2001
  "description": "",
1889
2002
  "positionals": [],
1890
2003
  "options": [
@@ -1908,8 +2021,8 @@
1908
2021
  },
1909
2022
  {
1910
2023
  "name": "uninstall",
1911
- "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",
1912
- "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",
1913
2026
  "positionals": [],
1914
2027
  "options": [
1915
2028
  {
@@ -1918,7 +2031,7 @@
1918
2031
  ],
1919
2032
  "dest": "target",
1920
2033
  "metavar": null,
1921
- "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)",
1922
2035
  "choices": null,
1923
2036
  "default": null,
1924
2037
  "required": false,
@@ -2002,13 +2115,44 @@
2002
2115
  "hidden": false
2003
2116
  }
2004
2117
  ],
2005
- "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
+ ],
2006
2150
  "mutex": []
2007
2151
  },
2008
2152
  {
2009
2153
  "name": "upgrade",
2010
- "help": "self-update: git pull the install's origin (ff-only), validate, then rebuild the bundle + every install",
2011
- "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",
2012
2156
  "positionals": [
2013
2157
  {
2014
2158
  "names": [],
@@ -2024,12 +2168,43 @@
2024
2168
  "hidden": false
2025
2169
  }
2026
2170
  ],
2027
- "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
+ ],
2028
2203
  "mutex": []
2029
2204
  },
2030
2205
  {
2031
2206
  "name": "version",
2032
- "help": "show installed vs current-source fingerprint and whether they match",
2207
+ "help": "compare the installed build's fingerprint with this source",
2033
2208
  "description": "",
2034
2209
  "positionals": [],
2035
2210
  "options": [
@@ -2039,7 +2214,7 @@
2039
2214
  ],
2040
2215
  "dest": "target",
2041
2216
  "metavar": null,
2042
- "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)",
2043
2218
  "choices": null,
2044
2219
  "default": null,
2045
2220
  "required": false,
@@ -2053,8 +2228,8 @@
2053
2228
  },
2054
2229
  {
2055
2230
  "name": "web",
2056
- "help": "serve the deployed harness as a local web UI (browse agents/skills/laws/memory + run actions)",
2057
- "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)",
2058
2233
  "positionals": [
2059
2234
  {
2060
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) {