geneseed 5.3.1 → 5.5.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 (248) hide show
  1. package/CHANGELOG.md +102 -0
  2. package/README.md +51 -18
  3. package/SHIPPED.md +7 -7
  4. package/adapters/bob/README.md +12 -1
  5. package/adapters/opencode/README.md +5 -3
  6. package/adapters/opencode/plugins/geneseed-context.js +77 -10
  7. package/adapters/opencode/plugins/geneseed-guard.js +106 -22
  8. package/adapters/opencode/plugins/geneseed-learn.js +641 -6
  9. package/bin/geneseed-cli.mjs +10 -0
  10. package/bin/geneseed-hook.mjs +5 -4
  11. package/docs/PRD.md +1 -1
  12. package/docs/README.md +1 -0
  13. package/docs/concepts/agents.md +14 -2
  14. package/docs/concepts/collaboration.md +2 -2
  15. package/docs/concepts/enforcement-table.md +5 -2
  16. package/docs/concepts/exclusions.md +16 -2
  17. package/docs/concepts/footprint.md +1 -1
  18. package/docs/concepts/foreman-mode.md +23 -4
  19. package/docs/concepts/hook-gates.md +4 -4
  20. package/docs/concepts/hooks.md +25 -7
  21. package/docs/concepts/host-matrix.md +4 -4
  22. package/docs/concepts/hosts.md +1 -1
  23. package/docs/concepts/kits.md +12 -2
  24. package/docs/concepts/loop-bricks.md +3 -3
  25. package/docs/concepts/loops.md +6 -4
  26. package/docs/concepts/ownership.md +1 -1
  27. package/docs/concepts/rules.md +2 -2
  28. package/docs/concepts/shared-tier.md +1 -1
  29. package/docs/concepts/skills.md +21 -1
  30. package/docs/concepts/themes.md +1 -1
  31. package/docs/extending.md +73 -29
  32. package/docs/guides/auto-merge.md +100 -0
  33. package/docs/guides/choose-your-setup.md +1 -1
  34. package/docs/guides/headless.md +1 -1
  35. package/docs/guides/install-clone.md +19 -1
  36. package/docs/guides/install-scripted.md +8 -2
  37. package/docs/guides/install.md +20 -2
  38. package/docs/guides/loop-finish.md +3 -3
  39. package/docs/guides/loop-running.md +4 -4
  40. package/docs/guides/project-context.md +1 -1
  41. package/docs/guides/run-a-factory.md +2 -2
  42. package/docs/guides/setup-doctrines.md +2 -2
  43. package/docs/guides/setup-footprint.md +1 -1
  44. package/docs/guides/uninstall.md +3 -3
  45. package/docs/guides/upgrade.md +2 -2
  46. package/docs/guides/worktree.md +1 -1
  47. package/docs/reference/env-context.md +1 -1
  48. package/docs/reference/environment.md +4 -2
  49. package/docs/reference/plugin-activity.md +1 -1
  50. package/docs/reference/plugin-guard.md +1 -1
  51. package/docs/reference/plugin-learn.md +5 -1
  52. package/docs/reference/plugin-workflow.md +1 -1
  53. package/docs/reference/profiles.md +142 -0
  54. package/docs/reference/troubleshoot-doctor.md +1 -1
  55. package/docs/reference/troubleshoot-hooks.md +2 -2
  56. package/docs/reference/troubleshoot-install.md +3 -3
  57. package/docs/reference/troubleshoot-tools.md +1 -1
  58. package/docs/token-footprint.md +11 -6
  59. package/docs/understand/design-choices-engineering.md +1 -1
  60. package/docs/understand/enforced-vs-asked.md +1 -1
  61. package/docs/understand/machine-claude.md +2 -2
  62. package/docs/understand/on-your-machine.md +1 -1
  63. package/docs/web-ui.md +8 -6
  64. package/harness.config.json +1 -1
  65. package/js/README.md +11 -3
  66. package/js/build/args.mjs +16 -4
  67. package/js/build/catalog.mjs +11 -1
  68. package/js/build/driver.mjs +74 -16
  69. package/js/build/emit-claude.mjs +32 -5
  70. package/js/build/emit-opencode.mjs +16 -9
  71. package/js/build/export.mjs +1 -1
  72. package/js/build/generate.mjs +12 -157
  73. package/js/build/notes-migrate.mjs +99 -0
  74. package/js/build/profile.mjs +326 -0
  75. package/js/build/render.mjs +110 -8
  76. package/js/build/retired-skills.mjs +60 -13
  77. package/js/build/source.mjs +100 -3
  78. package/js/build/stubs.mjs +4 -1
  79. package/js/cli-table.json +212 -7
  80. package/js/hosts/agent-runs.mjs +205 -0
  81. package/js/hosts/done-checks.mjs +3 -1
  82. package/js/hosts/hooks-done.mjs +428 -63
  83. package/js/hosts/hooks-learn.mjs +89 -3
  84. package/js/hosts/hooks-prims.mjs +44 -4
  85. package/js/hosts/hooks.mjs +159 -9
  86. package/js/hosts/hosts.mjs +10 -0
  87. package/js/hosts/installs.mjs +44 -2
  88. package/js/hosts/link.mjs +45 -10
  89. package/js/hosts/native.mjs +61 -7
  90. package/js/hosts/opencode.mjs +1 -1
  91. package/js/hosts/settings.mjs +101 -3
  92. package/js/hosts/spec-feedback.mjs +538 -0
  93. package/js/hosts/usage.mjs +67 -8
  94. package/js/inspect/agent-scores.mjs +118 -0
  95. package/js/inspect/checks-authoring.mjs +2 -1
  96. package/js/inspect/checks-build.mjs +20 -4
  97. package/js/inspect/checks-constitution.mjs +32 -0
  98. package/js/inspect/checks-repo.mjs +27 -2
  99. package/js/inspect/cost.mjs +6 -5
  100. package/js/inspect/diff.mjs +46 -8
  101. package/js/inspect/doctor.mjs +4 -0
  102. package/js/inspect/inventory.mjs +1 -1
  103. package/js/inspect/status.mjs +3 -1
  104. package/js/inspect/validate.mjs +1 -0
  105. package/js/lib/machine-dir.mjs +8 -0
  106. package/js/lib/paths.mjs +4 -1
  107. package/js/maintain/profile-scope.mjs +145 -0
  108. package/js/maintain/profiles.mjs +486 -0
  109. package/js/maintain/setup.mjs +413 -15
  110. package/js/maintain/uninstall.mjs +4 -1
  111. package/js/maintain/update.mjs +4 -2
  112. package/js/web/actions.mjs +44 -41
  113. package/js/web/api.mjs +13 -3
  114. package/js/web/handler.mjs +8 -0
  115. package/js/web/jobs.mjs +5 -4
  116. package/js/web/profiles-api.mjs +201 -0
  117. package/js/web/routes.mjs +5 -0
  118. package/package.json +2 -1
  119. package/profiles/guillaume-claude-global.json +16 -0
  120. package/profiles/starter.json +14 -0
  121. package/registry.json +14 -0
  122. package/src/AGENT.md.tmpl +16 -18
  123. package/src/agents/_self-improvement.md +15 -7
  124. package/src/agents/_template.md +4 -2
  125. package/src/agents/advocate.md +1 -1
  126. package/src/agents/architect.md +1 -1
  127. package/src/agents/developer.md +10 -3
  128. package/src/agents/devops-engineer.md +1 -1
  129. package/src/agents/docker-expert.md +1 -1
  130. package/src/agents/docs.md +1 -1
  131. package/src/agents/empiricist.md +1 -1
  132. package/src/agents/explorer.md +4 -2
  133. package/src/agents/framer.md +1 -1
  134. package/src/agents/historian.md +1 -1
  135. package/src/agents/kubernetes-specialist.md +1 -1
  136. package/src/agents/memory-curator.md +1 -1
  137. package/src/agents/operator.md +1 -1
  138. package/src/agents/performance.md +1 -1
  139. package/src/agents/pragmatist.md +1 -1
  140. package/src/agents/react-engineer.md +1 -1
  141. package/src/agents/react-reviewer.md +1 -1
  142. package/src/agents/researcher.md +1 -1
  143. package/src/agents/reviewer.md +10 -3
  144. package/src/agents/security.md +1 -1
  145. package/src/agents/skeptic.md +1 -1
  146. package/src/agents/spring-boot-engineer.md +1 -1
  147. package/src/agents/spring-reviewer.md +1 -1
  148. package/src/agents/spring-security.md +1 -1
  149. package/src/agents/steward.md +1 -1
  150. package/src/agents/tester.md +4 -2
  151. package/src/agents/user-advocate.md +1 -1
  152. package/src/agents/visionary.md +1 -1
  153. package/src/bricks/pr-open.md +3 -2
  154. package/src/doctrines/ops.md +2 -2
  155. package/src/doctrines/process.md +40 -36
  156. package/src/factories/analysis-to-build.json +1 -1
  157. package/src/factories/bug-report-to-fix.json +1 -1
  158. package/src/factories/issue-to-pr.json +1 -1
  159. package/src/kits/terminal-tools/rules.md +10 -0
  160. package/src/kits/terminal-tools.json +13 -0
  161. package/src/licenses/herdr.txt +201 -0
  162. package/src/memory/README.md +12 -2
  163. package/src/modes/foreman.md +25 -9
  164. package/src/skill-descriptions.json +63 -0
  165. package/src/skills/_self-improvement.md +42 -24
  166. package/src/skills/_template.md +3 -1
  167. package/src/skills/brainstorm.md +35 -22
  168. package/src/skills/commit.md +17 -17
  169. package/src/skills/daydream/VENDOR.md +6 -0
  170. package/src/skills/debug/ci.md +1 -1
  171. package/src/skills/dependencies.md +3 -3
  172. package/src/skills/diagram-design/VENDOR.md +4 -0
  173. package/src/skills/document-project.md +3 -2
  174. package/src/skills/explain-changes/VENDOR.md +5 -1
  175. package/src/skills/factory.md +13 -4
  176. package/src/skills/geneseed.md +4 -2
  177. package/src/skills/git-history.md +5 -7
  178. package/src/skills/herdr.md +135 -0
  179. package/src/skills/loop.md +3 -2
  180. package/src/skills/opencode-cli.md +84 -0
  181. package/src/skills/parallel-agents.md +11 -0
  182. package/src/skills/pipeline.md +3 -3
  183. package/src/skills/plan.md +5 -4
  184. package/src/skills/react-view-transitions/VENDOR.md +7 -1
  185. package/src/skills/release.md +11 -9
  186. package/src/skills/review-response.md +4 -2
  187. package/src/skills/rule/approve.md +2 -1
  188. package/src/skills/rule.md +27 -1
  189. package/src/skills/ship.md +54 -7
  190. package/src/skills/skill-forge.md +5 -3
  191. package/src/skills/token-report/VENDOR.md +5 -1
  192. package/src/skills/worktree.md +2 -2
  193. package/src/upstreams.json +9 -2
  194. package/themes/README.md +3 -1
  195. package/themes/_TEMPLATE.json +2 -0
  196. package/themes/biker.json +2 -0
  197. package/themes/commentator.json +2 -0
  198. package/themes/cyberpunk.json +2 -0
  199. package/themes/gamer.json +2 -0
  200. package/themes/imperial.json +2 -0
  201. package/themes/joker.json +2 -0
  202. package/themes/marvin.json +2 -0
  203. package/themes/mean.json +2 -0
  204. package/themes/military.json +2 -0
  205. package/themes/neutral.json +2 -0
  206. package/themes/pirate.json +2 -0
  207. package/themes/sports.json +2 -0
  208. package/themes/verstappen.json +2 -0
  209. package/themes/wizard.json +2 -0
  210. package/web/dist/assets/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
  211. package/web/dist/assets/Activity-LKsDzsnK.js +1 -0
  212. package/web/dist/assets/ActivityDetail-DhwTfPm6.js +1 -0
  213. package/web/dist/assets/{Bonsai-BBl4XXqs.js → Bonsai-CePMLrpr.js} +1 -1
  214. package/web/dist/assets/{CopyButton-Beven8yn.js → CopyButton-CuoaJ6k7.js} +1 -1
  215. package/web/dist/assets/Dashboard-D1VKuvLe.js +2 -0
  216. package/web/dist/assets/Docs-CUrHJKaU.js +5 -0
  217. package/web/dist/assets/Factories-Ci1XfmSy.js +1 -0
  218. package/web/dist/assets/{GreenhouseView-Bce212qd.js → GreenhouseView-CNfH2lPK.js} +1 -1
  219. package/web/dist/assets/Installs-ZHQZM1iS.js +3 -0
  220. package/web/dist/assets/{JournalView-CV4omyww.js → JournalView-CMsWahkS.js} +1 -1
  221. package/web/dist/assets/Kits-CkliyK0n.js +1 -0
  222. package/web/dist/assets/Laws-hh4O3HZ4.js +4 -0
  223. package/web/dist/assets/{LibRows-Dag1s0ZX.js → LibRows-Brv0Hmkr.js} +1 -1
  224. package/web/dist/assets/Library-BYmiLjJr.js +3 -0
  225. package/web/dist/assets/Loops-ytm-xJ68.js +2 -0
  226. package/web/dist/assets/{OperatorHudView-JmYY1pBR.js → OperatorHudView-KaqCx_HP.js} +1 -1
  227. package/web/dist/assets/Personal-CmcnRKYE.js +2 -0
  228. package/web/dist/assets/Settings-tUrpdOfq.js +1 -0
  229. package/web/dist/assets/{Tabs-8zsyEPSK.js → Tabs-CD7etcGD.js} +1 -1
  230. package/web/dist/assets/api-CZ-x0iWG.js +1 -0
  231. package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
  232. package/web/dist/assets/{index-CRWqKxfY.css → index-Ba_Kg3Af.css} +1 -1
  233. package/web/dist/assets/index-COKbhFNo.js +6 -0
  234. package/web/dist/index.html +3 -3
  235. package/web/dist/assets/Activity-WQ3ykgxU.js +0 -1
  236. package/web/dist/assets/ActivityDetail-7rt04SkS.js +0 -1
  237. package/web/dist/assets/Dashboard-BgLArtgu.js +0 -2
  238. package/web/dist/assets/Docs-B5aHp86J.js +0 -5
  239. package/web/dist/assets/Factories-BjqzXAw8.js +0 -1
  240. package/web/dist/assets/Installs-B1OsrHXF.js +0 -3
  241. package/web/dist/assets/Kits-CW1e7xNa.js +0 -1
  242. package/web/dist/assets/Laws-1Ckf1lbs.js +0 -4
  243. package/web/dist/assets/Library-B3FuFLel.js +0 -3
  244. package/web/dist/assets/Loops-CwqgnLNw.js +0 -2
  245. package/web/dist/assets/Personal-DKLgLa7Z.js +0 -2
  246. package/web/dist/assets/Settings-BwErnh-R.js +0 -1
  247. package/web/dist/assets/api-DLDVY3K-.js +0 -1
  248. package/web/dist/assets/index-Ce6qF2nG.js +0 -6
@@ -6,25 +6,43 @@
6
6
  *
7
7
  * An alias is a plain word, so a folder under one may be the user's own (`grill-me` on this very
8
8
  * machine is a user skill, and a link). A folder moves only when ALL of these hold:
9
- * (a) its name is retired and not a live skill;
9
+ * (a) its name is retired and not a live skill, or it is a REVIVED name (below);
10
10
  * (b) no manifest owns a path under it — an owned one is the ordinary prune's;
11
11
  * (c) it, the `skills/` root, and everything inside it are real entries, never a link;
12
12
  * (d) its SKILL.md carries the render's fingerprint (`isRendered`).
13
13
  * Anything else stays where it is and `migrate --dry-run` keeps calling it an orphan.
14
14
  *
15
+ * A revived name (`REVIVED_SKILL_IDS`) is live again. An unowned render under it is one of two
16
+ * things: the copy an older build wrote before it retired the name, or a file the user edited and
17
+ * a later emit declined to overwrite (`claimer` records that refusal in the manifest's `kept` and
18
+ * drops the file from `owned`). The `kept` record tells them apart:
19
+ * - nothing under the folder is in `kept`: the older build's copy. It moves aside whether or
20
+ * not this emit ships the skill. Kit off, that is the cleanup it got while the name was
21
+ * retired. Kit on, the emit then claims a free folder and writes the current copy, where
22
+ * `claimer` would otherwise keep the stale file as the user's;
23
+ * - a path under it is in `kept`: the user's edit. It stays, and `held` hands those `kept`
24
+ * entries back to the emit, which records them again. A kit-off emit claims nothing under
25
+ * the folder, so without that carry the record would lapse and the next emit would take the
26
+ * edit for an old copy.
27
+ * Only revived names get this: an unowned render of any other live skill is never a candidate.
28
+ *
15
29
  * Moved, not deleted: to `<cfg>/archived-skills/<name>/<stamp>/`, outside the `skills/` root a
16
30
  * host scans (`archiveStore`'s sibling would sit inside it and load again).
17
31
  */
18
32
  import { lstatSync, readdirSync, readFileSync, renameSync } from 'node:fs';
19
33
  import path from 'node:path';
20
34
 
21
- import { RETIRED_SKILL_IDS, THEMES, knownSkillIds, skillAliases } from './source.mjs';
22
- import { isCanonical } from '../hosts/hosts.mjs';
35
+ import { RETIRED_SKILL_IDS, REVIVED_SKILL_IDS, THEMES, knownSkillIds, skillAliases } from './source.mjs';
36
+ import { GLOBAL_MANIFEST, isCanonical } from '../hosts/hosts.mjs';
23
37
  import { archiveStore } from '../hosts/memory-files.mjs';
24
38
 
25
- /** Every name an earlier build shipped a skill folder under and this one does not. */
26
- export function retiredSkillNames({ live = knownSkillIds(), aliases = skillAliases() } = {}) {
27
- return [...new Set([...aliases.keys(), ...Object.keys(RETIRED_SKILL_IDS)])].filter((n) => !live.includes(n));
39
+ /**
40
+ * Every name an earlier build shipped a skill folder under and this one does not, plus every
41
+ * revived name, whose unowned render is an older build's copy whether or not it ships today.
42
+ */
43
+ export function retiredSkillNames({ live = knownSkillIds(), aliases = skillAliases(), revived = REVIVED_SKILL_IDS } = {}) {
44
+ const gone = [...aliases.keys(), ...Object.keys(RETIRED_SKILL_IDS)].filter((n) => !live.includes(n));
45
+ return [...new Set([...gone, ...Object.keys(revived)])];
28
46
  }
29
47
 
30
48
  /** Whether a manifest `owned` list holds `rel` or a path under it. */
@@ -103,26 +121,50 @@ export function isRendered(dir, name, { aliases = skillAliases(), labels = skill
103
121
  * The retired folders of `cfg` split by what the next canonical emit does with them:
104
122
  * `prune` (a-d all hold) and `keep` (unowned, present, but failing c or d). Paths are absolute.
105
123
  * `unreadable` names each folder kept because it could not be listed, with the reason.
124
+ * `held` lists the manifest `kept` entries under a revived folder that stays as the user's edit
125
+ * (see the module docblock); the emit records them again. Neither pruned nor an orphan.
106
126
  * `opts.readdir` is the listing call, injectable so a test can make a folder unreadable.
127
+ * `opts.kept` is the manifest's `kept` from BEFORE this emit; by default it is read from `cfg`.
107
128
  */
108
129
  export function retiredSkillFolders(cfg, owned, opts = {}) {
109
- const { readdir = readdirSync } = opts;
130
+ const { readdir = readdirSync, kept = recordedKept(cfg), revived = REVIVED_SKILL_IDS } = opts;
110
131
  const prune = [];
111
132
  const keep = [];
112
133
  const unreadable = [];
134
+ const held = [];
113
135
  const root = path.join(cfg, 'skills');
114
136
  const rootStat = lstat(root);
115
- if (!rootStat) return { prune, keep, unreadable };
137
+ if (!rootStat) return { prune, keep, unreadable, held };
116
138
  // A linked `skills/` root (a dotfiles setup) is the user's whole tree: nothing in it moves.
117
139
  const linkedRoot = rootStat.isSymbolicLink();
118
140
  const aliases = opts.aliases ?? skillAliases();
119
- for (const name of retiredSkillNames({ ...opts, aliases })) {
120
- if (ownsRel(owned, `skills/${name}`)) continue;
141
+ for (const name of retiredSkillNames({ ...opts, aliases, revived })) {
142
+ const rel = `skills/${name}`;
121
143
  const dir = path.join(root, name);
144
+ // Before the `owned` skip: an owned side file (a LICENSE) must not hide the kept SKILL.md
145
+ // beside it, or the record lapses in that emit and the next one archives the edit.
146
+ // Only an entry whose own file is still there and not owned is held: once the user deletes
147
+ // the edit, the record must lapse, or the manifest would call Geneseed's new copy theirs.
148
+ const live = Object.hasOwn(revived, name)
149
+ ? kept.filter((k) => (k === rel || k.startsWith(`${rel}/`)) && !owned.includes(k) && lstat(path.join(cfg, k)))
150
+ : [];
151
+ if (live.length) {
152
+ held.push(...live);
153
+ continue;
154
+ }
155
+ if (ownsRel(owned, rel)) continue;
122
156
  if (!lstat(dir)) continue;
123
157
  (!linkedRoot && plainTree(dir, readdir, unreadable) && isRendered(dir, name, { aliases }) ? prune : keep).push(dir);
124
158
  }
125
- return { prune, keep, unreadable };
159
+ return { prune, keep, unreadable, held };
160
+ }
161
+
162
+ /** The manifest's `kept` list in `cfg`, or `[]` when there is no readable manifest. */
163
+ function recordedKept(cfg) {
164
+ try {
165
+ const man = JSON.parse(readFileSync(path.join(cfg, GLOBAL_MANIFEST), 'utf8'));
166
+ return Array.isArray(man?.kept) ? man.kept.filter((k) => typeof k === 'string') : [];
167
+ } catch { return []; }
126
168
  }
127
169
 
128
170
  /** Where `pruneRetiredSkills` moves `skills/<name>`: the stamp folder goes under it. */
@@ -135,13 +177,17 @@ export const retiredArchiveOf = (cfg, name) => path.join(cfg, 'archived-skills',
135
177
  * A folder it cannot read, or a failed move, warns and leaves the folder; it never fails the emit.
136
178
  * Raw stream writes, as `pruneOwned`'s: the driver's `withPlatformNewlines` already translates,
137
179
  * and `printOut` on top of it would print `\r\r\n` on Windows.
180
+ * Returns `held`: the `kept` entries of user edits under revived names, for the emit to record
181
+ * again in its manifest (`[]` off the canonical path, where nothing is ever pruned). A survey that
182
+ * throws moves nothing and holds every recorded `kept` entry under a revived name, so a failed
183
+ * run never lapses one.
138
184
  */
139
185
  export function pruneRetiredSkills(host, cfg, oldOwned) {
140
- if (!isCanonical(cfg, host)) return;
186
+ if (!isCanonical(cfg, host)) return [];
141
187
  let found;
142
188
  try { found = retiredSkillFolders(cfg, oldOwned); } catch (e) {
143
189
  process.stderr.write(`[geneseed] WARN: ${host}: could not survey retired skills (${e.message}); nothing moved\n`);
144
- return;
190
+ return recordedKept(cfg).filter((k) => Object.keys(REVIVED_SKILL_IDS).some((n) => k.startsWith(`skills/${n}/`)));
145
191
  }
146
192
  for (const u of found.unreadable) {
147
193
  process.stderr.write(`[geneseed] WARN: ${host}: could not read retired skill folder ${u}; it stays\n`);
@@ -155,4 +201,5 @@ export function pruneRetiredSkills(host, cfg, oldOwned) {
155
201
  process.stderr.write(`[geneseed] WARN: ${host}: could not move retired skill skills/${name} aside (${e.message}); it stays\n`);
156
202
  }
157
203
  }
204
+ return found.held;
158
205
  }
@@ -253,6 +253,35 @@ export function upstreams(src = SRC) {
253
253
  return entries;
254
254
  }
255
255
 
256
+ /**
257
+ * The longest model-visible skill description, in characters. Claude Code lists skills under
258
+ * a budget of about 1% of the context window (some 6 000 characters on a 200k model) and,
259
+ * when the listing overruns it, drops the descriptions of the least-used skills first; a fresh
260
+ * install has no usage history, so every long description is at risk. 80 characters keeps the
261
+ * whole default catalogue far inside that budget, purpose and trigger both.
262
+ */
263
+ export const DESCRIPTION_LIMIT = 80;
264
+
265
+ const _descriptions = new Map();
266
+ /**
267
+ * `src/skill-descriptions.json` — skill stem -> its catalogue line, the ONE home of the
268
+ * `description:` every host's model routes on (`skillDescription`). Theme-neutral on purpose:
269
+ * the themed purpose of each skill still opens its body (`{{DESC_*}}`), but the frontmatter
270
+ * line has to fit `DESCRIPTION_LIMIT`, which no themed purpose plus trigger did (the user
271
+ * reversed the 2026-11-11 themed-catalogue decision for this line only, 2026-11-15).
272
+ * Memoised on the raw text, as `upstreams` is. A tree without the file has no lines.
273
+ */
274
+ export function skillDescriptions(src = SRC) {
275
+ const file = path.join(src, 'skill-descriptions.json');
276
+ let text;
277
+ try { text = readFileSync(file, 'utf8'); } catch { return {}; }
278
+ const hit = _descriptions.get(file);
279
+ if (hit && hit.text === text) return hit.entries;
280
+ const entries = JSON.parse(text);
281
+ _descriptions.set(file, { text, entries });
282
+ return entries;
283
+ }
284
+
256
285
  /** The entry a credit key names, or null — `hasOwn`, so `constructor` is not a key. */
257
286
  export function upstreamOf(key, src = SRC) {
258
287
  const u = upstreams(src);
@@ -504,7 +533,23 @@ export function aliasesOf(text) {
504
533
  return m ? m[1].split(',').map((s) => s.trim()).filter(Boolean) : [];
505
534
  }
506
535
 
507
- /** Every declared alias -> the skill that declares it. First declaration wins; the doctor names a duplicate. */
536
+ /**
537
+ * Aliases taken OUT of a spec's marker -> the skill they used to alias. No emit writes them any
538
+ * more (the emitters read the marker, `aliasesOf`), but everything that reads an OLDER install
539
+ * still must: an `Excluded skills:` line that names one, and the alias folder an older build
540
+ * rendered, whose heading names the former target (`isRendered`, `staleRetired`). So
541
+ * `skillAliases` serves them beside the live markers, and the old render is moved aside like any
542
+ * retired alias's. `grill-me` left `brainstorm` because the user keeps a grill-me skill of
543
+ * their own, and an alias folder under that name collides with it.
544
+ */
545
+ export const RETIRED_ALIASES = {
546
+ 'grill-me': 'brainstorm',
547
+ };
548
+
549
+ /**
550
+ * Every declared alias -> the skill that declares it, then each `RETIRED_ALIASES` entry no
551
+ * marker declares. First declaration wins; the doctor names a duplicate.
552
+ */
508
553
  export function skillAliases(src = SRC) {
509
554
  const map = new Map();
510
555
  const dir = path.join(src, 'skills');
@@ -513,6 +558,7 @@ export function skillAliases(src = SRC) {
513
558
  if (!map.has(a)) map.set(a, f.slice(0, -3));
514
559
  }
515
560
  }
561
+ for (const [a, target] of Object.entries(RETIRED_ALIASES)) if (!map.has(a)) map.set(a, target);
516
562
  return map;
517
563
  }
518
564
 
@@ -523,10 +569,20 @@ export function skillAliases(src = SRC) {
523
569
  * the whole rebuild. A retired name is dropped with a notice instead (excluding a skill that
524
570
  * no longer ships is already true), and the doctor refuses it as a new skill or alias name, so
525
571
  * it never comes back meaning something else — `RETIRED_RULE_IDS`' contract, for skills.
572
+ * A name taken back out moves to `REVIVED_SKILL_IDS` below.
526
573
  */
527
574
  export const RETIRED_SKILL_IDS = {
528
575
  tickets: 'removed in the 2026-10 sharpen; plan slices the work now',
529
- herdr: 'removed 2026-10; Orca covers multi-pane and multi-agent work',
576
+ };
577
+
578
+ /**
579
+ * Retired names that ship again, for the same tool, so an old `--exclude-skills <name>` still
580
+ * means what it meant. Kept because an older build's render may still sit unowned under the
581
+ * name: `retiredSkillNames` (`./retired-skills.mjs`) keeps each one a prune candidate, so that
582
+ * copy is moved aside instead of being kept as the user's file.
583
+ */
584
+ export const REVIVED_SKILL_IDS = {
585
+ herdr: 'retired 2026-10; back 2026-11 as a terminal-tools kit skill for the same tool',
530
586
  };
531
587
 
532
588
  /**
@@ -584,8 +640,47 @@ export const GATE_SWITCHES = [
584
640
  // Cure the Cause's weakened-test note, edit time and turn end. Advisory, so no gate the doctor
585
641
  // pins (`HOOK_PINNED`; ledger key `cure-the-cause`): `law: null`, though the console shows it on Rule VIII.
586
642
  { key: 'testNote', flag: '--no-test-note', arg: 'noTestNote', marker: 'Test note', law: null },
643
+ // Consent Before Push's own-branch pass (user decision 2026-11-13): off is STRICT consent, every
644
+ // commit and push asks again. A switch that adds asks, so its flag does not read `--no-*`; the
645
+ // contract is the others' all the same: armed by default, a marker line only when off.
646
+ { key: 'ownBranchPass', flag: '--strict-consent', arg: 'strictConsent', marker: 'Own-branch pass', law: null },
587
647
  ];
588
648
 
649
+ /**
650
+ * `--context-window 200k|1m`: the model context the install is built for, and the Claude Code
651
+ * settings it writes for the skill listing. ONE table, so the flag, the carrier marker, the
652
+ * rebuild argv, the profile and the console read the same two values.
653
+ *
654
+ * WHY. Claude Code builds its skill listing under a character budget: context window x bytes
655
+ * per token (3, or 4 for some older models) x `skillListingBudgetFraction` (default 0.01). That
656
+ * is about 6 000 characters on a 200k model and 30 000 on a 1M one. Over budget, a skill with
657
+ * low usage loses its description, so a fresh install on a 200k model listed none of
658
+ * Geneseed's descriptions (measured 2026-11-15: a fresh neutral emit plus the 14 bundled skills
659
+ * is 11 482 characters at the default 1 536-character cap, the bundled skills' long texts most
660
+ * of it, even with Geneseed's own lines at 80 characters or less).
661
+ *
662
+ * THE VALUES (simulated 2026-11-15 on a fresh emit, no usage; the docs keep the table):
663
+ * - `200k`: `skillListingMaxDescChars` 80 fits all 46 descriptions in 5 605 of 6 000
664
+ * characters. That 395-character slack is too thin: with one shipped kit (spring-boot) it is
665
+ * 113, and five third-party skills push descriptions out. `skillListingBudgetFraction` 0.013
666
+ * (7 800 characters) keeps all of them with twenty third-party skills beside them. The
667
+ * fraction is a ceiling, not a cost: a listing that fits uses only its own length, so the
668
+ * extra 1 800 characters (about 600 tokens, 0.3 % of the window) are spent only when filled.
669
+ * - `1m`: a fresh install fits even at the default cap (11 482 of 30 000), so the fraction stays
670
+ * at its default. The cap 120 is for a machine with many skills: this laptop's 143-skill
671
+ * listing (47 617 characters) fits whole at 19 427 with it, where today 53 lose their text.
672
+ *
673
+ * Claude Code only: OpenClaude (checked on 0.31) and Bob read neither key, and OpenCode does
674
+ * not cap its list. Those emits record the choice and write nothing.
675
+ */
676
+ export const CONTEXT_WINDOWS = Object.freeze({
677
+ '200k': Object.freeze({ skillListingMaxDescChars: 80, skillListingBudgetFraction: 0.013 }),
678
+ '1m': Object.freeze({ skillListingMaxDescChars: 120 }),
679
+ });
680
+ export const DEFAULT_CONTEXT_WINDOW = '200k';
681
+ /** The carrier marker, written only when the value is not the default (the kits line's contract). */
682
+ export const CONTEXT_WINDOW_MARKER = 'Context window';
683
+
589
684
  /**
590
685
  * `_build_core.js_cfg()`, originated rather than received.
591
686
  *
@@ -601,7 +696,7 @@ export const GATE_SWITCHES = [
601
696
  export function makeCfg({
602
697
  posture = 'peer', mode = 'direct', trust = DEFAULT_PRESET, doctrines = PACK_ORDER,
603
698
  excludeRules = [], excludeSkills = [], kits = [], sharedTier = /** @type {boolean | string} */ (false),
604
- pruneGates = false, force = false, ...switches
699
+ contextWindow = DEFAULT_CONTEXT_WINDOW, pruneGates = false, force = false, ...switches
605
700
  } = {}) {
606
701
  return {
607
702
  root: ROOT,
@@ -633,6 +728,8 @@ export function makeCfg({
633
728
  kits: Array.isArray(kits) ? [...kits] : [],
634
729
  // The shared tier read by a PROJECT install (`--shared-tier on`); `on` from the flag, a boolean from a read-back.
635
730
  sharedTier: sharedTier === true || sharedTier === 'on',
731
+ // The context window the install is built for (`CONTEXT_WINDOWS`); anything unknown is the default.
732
+ contextWindow: Object.hasOwn(CONTEXT_WINDOWS, contextWindow) ? contextWindow : DEFAULT_CONTEXT_WINDOW,
636
733
  // `--force`, for this one build: only a literal `true` forces. Never an axis of the install.
637
734
  force: force === true,
638
735
  // The gate switches (`GATE_SWITCHES`: `secretsGate`, `doneGate`, `deletionGate`), each armed
@@ -146,11 +146,14 @@ the project's own. Follow the root \`AGENTS.md\`.
146
146
  * template's sigil paragraph — below the banner — the first reply to a real request carried
147
147
  * no sigil; with this paragraph on top it did. Bob's own greeting persona outranks a rule
148
148
  * that does not say it overrides it. A bare "hi" still gets Bob's fixed welcome either way.
149
+ * Seen live (2026-11): told only "begin with this line", Bob also echoed the theme's fenced
150
+ * banner right under it — two banners per first reply — so the override forbids the echo.
149
151
  */
150
152
  export function bobFirstReply(sigil) {
151
153
  return '**First-reply override — highest priority.** Your very first reply in every '
152
154
  + 'conversation MUST begin with this exact line, before anything else and instead of any '
153
- + `default greeting or self-introduction:\n\n> ${sigil}\n\n`;
155
+ + 'default greeting or self-introduction. Print that line once and never reproduce the '
156
+ + `fenced banner block below it: the line is the whole greeting:\n\n> ${sigil}\n\n`;
154
157
  }
155
158
 
156
159
  /** `_build_render.PROFILE_FILE`. */
package/js/cli-table.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "commands": [
4
4
  {
5
5
  "name": "activity",
6
- "help": "UserPromptSubmit/SessionEnd hook: records the session into <root>/activity/ for the web console's live view; decides nothing and prints nothing (off with $GENESEED_ACTIVITY=off or the console toggle)",
6
+ "help": "UserPromptSubmit/SessionEnd hook: records the session into <root>/activity/ for the web console's live view (off with $GENESEED_ACTIVITY=off or the console toggle), and counts a typed /<skill> into <root>/notebook/usage.jsonl (off with $GENESEED_NO_USAGE or .usage-off); decides nothing and prints nothing",
7
7
  "description": "",
8
8
  "positionals": [],
9
9
  "options": [
@@ -67,7 +67,7 @@
67
67
  {
68
68
  "name": "build",
69
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)",
70
+ "description": "render the harness (same flags as geneseed-build; an omitted flag takes the generator default, not the install's, so a build over an existing install that would change a setting it was not given refuses and prints the install's own rebuild command, as geneseed status --json shows it — --reset accepts the defaults; dry run: geneseed validate)",
71
71
  "positionals": [],
72
72
  "options": [
73
73
  {
@@ -235,6 +235,21 @@
235
235
  "type": null,
236
236
  "hidden": false
237
237
  },
238
+ {
239
+ "names": [
240
+ "--context-window"
241
+ ],
242
+ "dest": "context_window",
243
+ "metavar": null,
244
+ "help": "the model context window the install is built for: 200k|1m (default: 200k). On Claude Code it sets the skill-listing budget in settings.json so every skill keeps a description; other hosts record it and write nothing",
245
+ "choices": null,
246
+ "default": null,
247
+ "required": false,
248
+ "nargs": null,
249
+ "is_flag": false,
250
+ "type": null,
251
+ "hidden": false
252
+ },
238
253
  {
239
254
  "names": [
240
255
  "--out"
@@ -370,6 +385,21 @@
370
385
  "type": null,
371
386
  "hidden": false
372
387
  },
388
+ {
389
+ "names": [
390
+ "--strict-consent"
391
+ ],
392
+ "dest": "strict_consent",
393
+ "metavar": null,
394
+ "help": "Consent Before Push asks for every git commit and push, own branch included (records `Own-branch pass: off`); default: only the main branch asks",
395
+ "choices": null,
396
+ "default": false,
397
+ "required": false,
398
+ "nargs": "0",
399
+ "is_flag": true,
400
+ "type": null,
401
+ "hidden": false
402
+ },
373
403
  {
374
404
  "names": [
375
405
  "--prune-gates"
@@ -399,6 +429,21 @@
399
429
  "is_flag": true,
400
430
  "type": null,
401
431
  "hidden": false
432
+ },
433
+ {
434
+ "names": [
435
+ "--reset"
436
+ ],
437
+ "dest": "reset",
438
+ "metavar": null,
439
+ "help": "for this one build, return every setting this build does not pass to its default on the install it targets. Without it, a build over an existing install that would change a setting it was not given refuses, lists each change and prints the command that keeps them (the install's own rebuild, as geneseed status --json shows it). Not recorded",
440
+ "choices": null,
441
+ "default": false,
442
+ "required": false,
443
+ "nargs": "0",
444
+ "is_flag": true,
445
+ "type": null,
446
+ "hidden": false
402
447
  }
403
448
  ],
404
449
  "mutex": []
@@ -458,6 +503,21 @@
458
503
  "is_flag": true,
459
504
  "type": null,
460
505
  "hidden": false
506
+ },
507
+ {
508
+ "names": [
509
+ "--scores"
510
+ ],
511
+ "dest": "scores",
512
+ "metavar": null,
513
+ "help": "with the agents section: each agent's recorded runs per spec hash, from each active install's notebook/agent-runs.jsonl (read-only)",
514
+ "choices": null,
515
+ "default": false,
516
+ "required": false,
517
+ "nargs": "0",
518
+ "is_flag": true,
519
+ "type": null,
520
+ "hidden": false
461
521
  }
462
522
  ],
463
523
  "mutex": []
@@ -955,7 +1015,7 @@
955
1015
  },
956
1016
  {
957
1017
  "name": "git-gate",
958
- "help": "PreToolUse hook: ASK before a history-discarding git act (Deletion Is Deliberate), a recursive scan of a whole filesystem (Commands Must Return) and every git commit/push (Consent Before Push backstop)",
1018
+ "help": "PreToolUse hook: ASK before a history-discarding git act (Deletion Is Deliberate), a recursive scan of a whole filesystem (Commands Must Return) and a git commit or push onto the main branch (Consent Before Push backstop)",
959
1019
  "description": "",
960
1020
  "positionals": [],
961
1021
  "options": [
@@ -995,7 +1055,22 @@
995
1055
  ],
996
1056
  "dest": "no_consent",
997
1057
  "metavar": null,
998
- "help": "skip the Consent Before Push commit/push ask (set by the emit when the process pack or that rule is off); Deletion Is Deliberate still asks",
1058
+ "help": "skip the Consent Before Push main-branch commit/push ask (set by the emit when the process pack or that rule is off); Deletion Is Deliberate still asks",
1059
+ "choices": null,
1060
+ "default": false,
1061
+ "required": false,
1062
+ "nargs": "0",
1063
+ "is_flag": true,
1064
+ "type": null,
1065
+ "hidden": false
1066
+ },
1067
+ {
1068
+ "names": [
1069
+ "--strict-consent"
1070
+ ],
1071
+ "dest": "strict_consent",
1072
+ "metavar": null,
1073
+ "help": "ask on every git commit and push, own branch included (set by the emit for a strict-consent install); the main-branch ask is the same either way",
999
1074
  "choices": null,
1000
1075
  "default": false,
1001
1076
  "required": false,
@@ -1534,6 +1609,120 @@
1534
1609
  ],
1535
1610
  "mutex": []
1536
1611
  },
1612
+ {
1613
+ "name": "profile",
1614
+ "help": "apply an install profile, or save an install as one",
1615
+ "description": "apply an install profile globally or to one project folder, or save an existing install as one. Profiles come from two sources: Shipped (profiles/ in this checkout) and Personal (profiles/ in the machine-wide Geneseed folder, beside memory and rules). apply builds the profile into each host it names that this machine has (--hosts narrows it) and touches no other install; it puts nothing on PATH and starts no console. save copies every build setting of one install as it is, gates switched off included, writes a Personal profile unless --shipped, and prints how it differs from starter. It reads no user rules, profile, memory, wiki or notebook",
1616
+ "positionals": [
1617
+ {
1618
+ "names": [],
1619
+ "dest": "action",
1620
+ "metavar": null,
1621
+ "help": "save — write NAME.json from the install named by --from; apply — build profile NAME into this machine's hosts",
1622
+ "choices": [
1623
+ "save",
1624
+ "apply"
1625
+ ],
1626
+ "default": null,
1627
+ "required": true,
1628
+ "nargs": null,
1629
+ "is_flag": false,
1630
+ "type": null,
1631
+ "hidden": false
1632
+ },
1633
+ {
1634
+ "names": [],
1635
+ "dest": "name",
1636
+ "metavar": null,
1637
+ "help": "the profile name (a file stem: letters, digits, '.', '_' and '-')",
1638
+ "choices": null,
1639
+ "default": null,
1640
+ "required": true,
1641
+ "nargs": null,
1642
+ "is_flag": false,
1643
+ "type": null,
1644
+ "hidden": false
1645
+ }
1646
+ ],
1647
+ "options": [
1648
+ {
1649
+ "names": [
1650
+ "--from"
1651
+ ],
1652
+ "dest": "from",
1653
+ "metavar": "EMIT",
1654
+ "help": "save: the install to read — opencode-global, claude-global, bob-global or openclaude-global, or a bare host (opencode, claude, bob, openclaude) with --project for a project install",
1655
+ "choices": null,
1656
+ "default": null,
1657
+ "required": false,
1658
+ "nargs": null,
1659
+ "is_flag": false,
1660
+ "type": null,
1661
+ "hidden": false
1662
+ },
1663
+ {
1664
+ "names": [
1665
+ "--project"
1666
+ ],
1667
+ "dest": "project",
1668
+ "metavar": "DIR",
1669
+ "help": "apply: build into this project folder instead of globally; save: the folder of the project install --from names",
1670
+ "choices": null,
1671
+ "default": null,
1672
+ "required": false,
1673
+ "nargs": null,
1674
+ "is_flag": false,
1675
+ "type": null,
1676
+ "hidden": false
1677
+ },
1678
+ {
1679
+ "names": [
1680
+ "--hosts"
1681
+ ],
1682
+ "dest": "hosts",
1683
+ "metavar": "HOSTS",
1684
+ "help": "apply: comma-separated hosts to build, a subset of the profile's (default: each of them this machine has)",
1685
+ "choices": null,
1686
+ "default": null,
1687
+ "required": false,
1688
+ "nargs": null,
1689
+ "is_flag": false,
1690
+ "type": null,
1691
+ "hidden": false
1692
+ },
1693
+ {
1694
+ "names": [
1695
+ "--shipped"
1696
+ ],
1697
+ "dest": "shipped",
1698
+ "metavar": null,
1699
+ "help": "save: write profiles/NAME.json in this checkout (a git clone only) instead of a Personal profile",
1700
+ "choices": null,
1701
+ "default": false,
1702
+ "required": false,
1703
+ "nargs": "0",
1704
+ "is_flag": true,
1705
+ "type": null,
1706
+ "hidden": false
1707
+ },
1708
+ {
1709
+ "names": [
1710
+ "--force"
1711
+ ],
1712
+ "dest": "force",
1713
+ "metavar": null,
1714
+ "help": "save: replace NAME.json when it already exists in the same source (that file only)",
1715
+ "choices": null,
1716
+ "default": false,
1717
+ "required": false,
1718
+ "nargs": "0",
1719
+ "is_flag": true,
1720
+ "type": null,
1721
+ "hidden": false
1722
+ }
1723
+ ],
1724
+ "mutex": []
1725
+ },
1537
1726
  {
1538
1727
  "name": "prompt",
1539
1728
  "help": "emit a self-contained install prompt",
@@ -1735,10 +1924,26 @@
1735
1924
  },
1736
1925
  {
1737
1926
  "name": "setup",
1738
- "help": "interactive install wizard (dependency-free, all OSes)",
1739
- "description": "",
1927
+ "help": "install wizard; --profile NAME installs a profile with no questions",
1928
+ "description": "interactive install wizard (dependency-free, all OSes). With --profile <name>, it asks nothing: it installs that profile (Shipped, from profiles/ in this checkout, or Personal, from profiles/ in the machine-wide Geneseed folder) globally into each AI coding tool the profile lists that is found on this machine, puts geneseed on PATH, sets the web console to start at login, starts it, and runs the doctor",
1740
1929
  "positionals": [],
1741
- "options": [],
1930
+ "options": [
1931
+ {
1932
+ "names": [
1933
+ "--profile"
1934
+ ],
1935
+ "dest": "profile",
1936
+ "metavar": "NAME",
1937
+ "help": "install profile NAME (Shipped, in profiles/, or Personal, in the machine-wide profiles/) globally with no questions (e.g. starter); works without a terminal",
1938
+ "choices": null,
1939
+ "default": null,
1940
+ "required": false,
1941
+ "nargs": null,
1942
+ "is_flag": false,
1943
+ "type": null,
1944
+ "hidden": false
1945
+ }
1946
+ ],
1742
1947
  "mutex": []
1743
1948
  },
1744
1949
  {