geneseed 5.4.0 → 5.5.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 (191) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +31 -1
  3. package/SHIPPED.md +1 -1
  4. package/adapters/bob/README.md +12 -1
  5. package/adapters/opencode/README.md +2 -1
  6. package/adapters/opencode/plugins/geneseed-context.js +71 -10
  7. package/adapters/opencode/plugins/geneseed-guard.js +101 -19
  8. package/adapters/opencode/plugins/geneseed-learn.js +641 -6
  9. package/bin/geneseed-cli.mjs +3 -0
  10. package/bin/geneseed-hook.mjs +2 -1
  11. package/docs/concepts/agents.md +13 -1
  12. package/docs/concepts/enforcement-table.md +1 -1
  13. package/docs/concepts/foreman-mode.md +22 -3
  14. package/docs/concepts/hook-gates.md +1 -1
  15. package/docs/concepts/hooks.md +22 -5
  16. package/docs/concepts/host-matrix.md +2 -2
  17. package/docs/concepts/hosts.md +1 -1
  18. package/docs/concepts/shared-tier.md +1 -1
  19. package/docs/concepts/skills.md +21 -1
  20. package/docs/concepts/themes.md +1 -1
  21. package/docs/extending.md +11 -2
  22. package/docs/guides/install-clone.md +18 -0
  23. package/docs/guides/install-scripted.md +8 -2
  24. package/docs/guides/install.md +19 -1
  25. package/docs/guides/upgrade.md +1 -1
  26. package/docs/reference/env-context.md +1 -1
  27. package/docs/reference/environment.md +1 -1
  28. package/docs/reference/plugin-learn.md +4 -0
  29. package/docs/reference/profiles.md +226 -0
  30. package/docs/token-footprint.md +9 -4
  31. package/docs/understand/design-choices-engineering.md +1 -1
  32. package/docs/web-ui.md +3 -1
  33. package/harness.config.json +1 -1
  34. package/js/README.md +9 -2
  35. package/js/build/args.mjs +4 -3
  36. package/js/build/catalog.mjs +11 -1
  37. package/js/build/driver.mjs +42 -11
  38. package/js/build/emit-claude.mjs +24 -1
  39. package/js/build/emit-opencode.mjs +3 -0
  40. package/js/build/export.mjs +12 -17
  41. package/js/build/generate.mjs +2 -1
  42. package/js/build/notes-migrate.mjs +99 -0
  43. package/js/build/profile.mjs +14 -6
  44. package/js/build/render.mjs +34 -10
  45. package/js/build/source.mjs +85 -2
  46. package/js/cli-table.json +164 -4
  47. package/js/hosts/agent-runs.mjs +205 -0
  48. package/js/hosts/done-checks.mjs +3 -1
  49. package/js/hosts/hooks-done.mjs +91 -16
  50. package/js/hosts/hooks-learn.mjs +85 -0
  51. package/js/hosts/hooks-prims.mjs +39 -1
  52. package/js/hosts/hooks.mjs +10 -4
  53. package/js/hosts/hosts.mjs +10 -0
  54. package/js/hosts/installs.mjs +25 -1
  55. package/js/hosts/link.mjs +45 -10
  56. package/js/hosts/native.mjs +42 -5
  57. package/js/hosts/opencode.mjs +1 -1
  58. package/js/hosts/settings.mjs +72 -0
  59. package/js/hosts/spec-feedback.mjs +538 -0
  60. package/js/hosts/usage.mjs +67 -8
  61. package/js/inspect/agent-scores.mjs +118 -0
  62. package/js/inspect/checks-authoring.mjs +2 -1
  63. package/js/inspect/checks-build.mjs +20 -4
  64. package/js/inspect/checks-repo.mjs +27 -2
  65. package/js/inspect/cost.mjs +6 -5
  66. package/js/inspect/diff.mjs +25 -5
  67. package/js/inspect/doctor.mjs +4 -0
  68. package/js/inspect/status.mjs +3 -1
  69. package/js/inspect/validate.mjs +1 -0
  70. package/js/lib/machine-dir.mjs +8 -0
  71. package/js/lib/paths.mjs +4 -1
  72. package/js/maintain/profile-scope.mjs +145 -0
  73. package/js/maintain/profiles.mjs +486 -0
  74. package/js/maintain/setup.mjs +409 -15
  75. package/js/maintain/uninstall.mjs +4 -1
  76. package/js/maintain/update.mjs +1 -1
  77. package/js/web/actions.mjs +28 -38
  78. package/js/web/api.mjs +7 -2
  79. package/js/web/handler.mjs +8 -0
  80. package/js/web/jobs.mjs +5 -4
  81. package/js/web/profiles-api.mjs +201 -0
  82. package/js/web/routes.mjs +5 -0
  83. package/package.json +2 -1
  84. package/profiles/autonomous.json +14 -0
  85. package/profiles/corporate.json +14 -0
  86. package/profiles/guillaume-claude-global.json +16 -0
  87. package/profiles/mentor.json +13 -0
  88. package/profiles/minimal.json +15 -0
  89. package/profiles/starter.json +14 -0
  90. package/src/AGENT.md.tmpl +1 -1
  91. package/src/agents/_self-improvement.md +15 -7
  92. package/src/agents/_template.md +4 -2
  93. package/src/agents/advocate.md +1 -1
  94. package/src/agents/architect.md +1 -1
  95. package/src/agents/developer.md +10 -3
  96. package/src/agents/devops-engineer.md +7 -6
  97. package/src/agents/docker-expert.md +1 -1
  98. package/src/agents/docs.md +1 -1
  99. package/src/agents/empiricist.md +1 -1
  100. package/src/agents/explorer.md +4 -2
  101. package/src/agents/framer.md +1 -1
  102. package/src/agents/historian.md +1 -1
  103. package/src/agents/kubernetes-specialist.md +4 -2
  104. package/src/agents/memory-curator.md +1 -1
  105. package/src/agents/operator.md +1 -1
  106. package/src/agents/performance.md +1 -1
  107. package/src/agents/pragmatist.md +1 -1
  108. package/src/agents/react-engineer.md +1 -1
  109. package/src/agents/react-reviewer.md +1 -1
  110. package/src/agents/researcher.md +1 -1
  111. package/src/agents/reviewer.md +10 -3
  112. package/src/agents/security.md +1 -1
  113. package/src/agents/skeptic.md +1 -1
  114. package/src/agents/spring-boot-engineer.md +4 -4
  115. package/src/agents/spring-reviewer.md +5 -3
  116. package/src/agents/spring-security.md +1 -1
  117. package/src/agents/steward.md +1 -1
  118. package/src/agents/tester.md +4 -2
  119. package/src/agents/user-advocate.md +1 -1
  120. package/src/agents/visionary.md +1 -1
  121. package/src/memory/README.md +12 -2
  122. package/src/modes/foreman.md +23 -10
  123. package/src/skill-descriptions.json +63 -0
  124. package/src/skills/_self-improvement.md +42 -26
  125. package/src/skills/_template.md +3 -1
  126. package/src/skills/brainstorm.md +35 -22
  127. package/src/skills/codebase-design.md +2 -2
  128. package/src/skills/daydream/VENDOR.md +6 -0
  129. package/src/skills/diagram-design/SKILL.md +12 -7
  130. package/src/skills/diagram-design/VENDOR.md +23 -14
  131. package/src/skills/diagram-design/references/layout-budget.md +7 -1
  132. package/src/skills/diagram-design/references/onboarding.md +1 -1
  133. package/src/skills/diagram-design/references/primitives-core.md +1 -1
  134. package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
  135. package/src/skills/diagram-design/references/style-guide.md +1 -1
  136. package/src/skills/diagram-design/references/type-dependency.md +69 -0
  137. package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
  138. package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
  139. package/src/skills/diagram-design/references/type-sbgn.md +80 -0
  140. package/src/skills/diagram-design/references/type-scatter.md +1 -1
  141. package/src/skills/diagram-design/references/type-steps.md +180 -0
  142. package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
  143. package/src/skills/explain-changes/VENDOR.md +5 -1
  144. package/src/skills/geneseed-code-review.md +2 -1
  145. package/src/skills/parallel-agents.md +12 -1
  146. package/src/skills/pipeline.md +3 -3
  147. package/src/skills/plan.md +5 -4
  148. package/src/skills/react-view-transitions/AGENTS.md +26 -26
  149. package/src/skills/react-view-transitions/SKILL.md +1 -1
  150. package/src/skills/react-view-transitions/VENDOR.md +19 -4
  151. package/src/skills/release.md +7 -2
  152. package/src/skills/rule/approve.md +2 -1
  153. package/src/skills/skill-forge.md +5 -3
  154. package/src/skills/spring-boot/cloud.md +19 -1
  155. package/src/skills/spring-boot/logging.md +5 -3
  156. package/src/skills/spring-boot/web.md +27 -2
  157. package/src/skills/spring-boot.md +4 -2
  158. package/src/skills/spring-data-jpa.md +18 -4
  159. package/src/skills/spring-testing.md +4 -0
  160. package/src/skills/token-report/VENDOR.md +5 -1
  161. package/src/upstreams.json +6 -6
  162. package/themes/README.md +3 -1
  163. package/web/dist/assets/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
  164. package/web/dist/assets/{Activity-D2kOc3yi.js → Activity-bUSPM3Dl.js} +1 -1
  165. package/web/dist/assets/{ActivityDetail-By3xOr21.js → ActivityDetail-AHRoXeFN.js} +1 -1
  166. package/web/dist/assets/{Bonsai-CBWDTBA4.js → Bonsai-B5XY9pid.js} +1 -1
  167. package/web/dist/assets/{CopyButton-BVbpriMB.js → CopyButton-C0wwRR9H.js} +1 -1
  168. package/web/dist/assets/{Dashboard-CIJLPHM9.js → Dashboard-DPAA96EI.js} +2 -2
  169. package/web/dist/assets/{Docs-CiRRIELs.js → Docs-CpGDq165.js} +1 -1
  170. package/web/dist/assets/{Factories-DhyK0O8d.js → Factories-cNhETa5Q.js} +1 -1
  171. package/web/dist/assets/{GreenhouseView-DW3PgTPy.js → GreenhouseView-DO3ADmT9.js} +1 -1
  172. package/web/dist/assets/Installs-D3dDyq10.js +3 -0
  173. package/web/dist/assets/{JournalView-O65qEWfp.js → JournalView--W-Lw_V9.js} +1 -1
  174. package/web/dist/assets/{Kits-C5U-yT6Z.js → Kits-ChfehxY6.js} +1 -1
  175. package/web/dist/assets/Laws-CNxYmV36.js +4 -0
  176. package/web/dist/assets/{LibRows-D6-CVa3K.js → LibRows-CiPvsRYB.js} +1 -1
  177. package/web/dist/assets/{Library-CzPlerd6.js → Library-BxQvbwVU.js} +1 -1
  178. package/web/dist/assets/{Loops-CqNF_-nS.js → Loops-DAblKkyq.js} +1 -1
  179. package/web/dist/assets/{OperatorHudView-BNr8K5qj.js → OperatorHudView-QtSaSyYm.js} +1 -1
  180. package/web/dist/assets/{Personal-DeDb9e8O.js → Personal-DxSGv638.js} +1 -1
  181. package/web/dist/assets/{Settings-B8MPN_AD.js → Settings-CgTbhvRv.js} +1 -1
  182. package/web/dist/assets/{Tabs-DJzAez4h.js → Tabs-Cf4X1hdz.js} +1 -1
  183. package/web/dist/assets/api-CZ-x0iWG.js +1 -0
  184. package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
  185. package/web/dist/assets/{index-BL3P-9Rg.js → index-B_pTwZra.js} +4 -4
  186. package/web/dist/assets/index-CzfImiYb.css +1 -0
  187. package/web/dist/index.html +3 -3
  188. package/web/dist/assets/Installs-B6nlo-Ly.js +0 -3
  189. package/web/dist/assets/Laws-CuTw_XNf.js +0 -4
  190. package/web/dist/assets/api-DLDVY3K-.js +0 -1
  191. package/web/dist/assets/index-CRWqKxfY.css +0 -1
@@ -31,8 +31,9 @@
31
31
  * An agent keeps the whole of its seven sections, step 0 and Self-improvement included: that
32
32
  * shape is the contract a persona library reads;
33
33
  * - host keys (`disable-model-invocation`, `disallowedTools`, ...) are not written at all.
34
- * A citation of a law or doctrine stays the principle's name, and the entity `requires` the
35
- * exported constitution, which is where that name is defined.
34
+ * A citation of a law or doctrine stays the principle's name, and the entity does NOT `require`
35
+ * the exported constitution: the laws are a side package a library may take or leave, and a
36
+ * skill or an agent installs without them (the user decided, 2026-11).
36
37
  *
37
38
  * NOT EXPORTED: an alias (a second name for one skill), the authoring templates, and a vendored
38
39
  * folder skill. The last is a third party's folder shipped verbatim under its own licence and
@@ -88,7 +89,6 @@ const PROFILE_DEFAULTS = {
88
89
  };
89
90
  const LIST_KEYS = ['compatibleTools', 'exclude'];
90
91
  const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
91
- const CITES_RE = /\{\{(?:LAW|DOCTRINE):[a-z0-9-]+\}\}/;
92
92
 
93
93
  /** A refusal: the message is the whole of what the user needs, so no stack is printed. */
94
94
  class ExportError extends Error {}
@@ -161,13 +161,6 @@ function metadataYaml(m) {
161
161
 
162
162
  const frontmatter = (name, description) => `---\nname: ${name}\ndescription: ${yamlStr(description)}\n---\n\n`;
163
163
 
164
- /** The registry's row for one entity: its version and nothing else is read. */
165
- function registryVersions() {
166
- try {
167
- return JSON.parse(readText(path.join(ROOT, 'registry.json'))).entities ?? {};
168
- } catch { return {}; }
169
- }
170
-
171
164
  /**
172
165
  * Rewrite every reference to another exported entity to its exported name, and collect them.
173
166
  * Two spellings carry a reference in the sources: a Markdown link to the entity's spec
@@ -226,7 +219,6 @@ export function planExport({ profile = { ...PROFILE_DEFAULTS }, theme = 'neutral
226
219
  // a lean line.
227
220
  const { items } = renderAll(cfg, theme, { footprint: 'full' });
228
221
  const srcRel = (it) => relPosix(cfg.src, it.src);
229
- const versions = registryVersions();
230
222
  const release = sourceReleaseVersion(cfg);
231
223
 
232
224
  // The roster: flat specs under skills/ and agents/, minus templates and what the profile drops.
@@ -274,7 +266,7 @@ export function planExport({ profile = { ...PROFILE_DEFAULTS }, theme = 'neutral
274
266
  let body = forLibrary(lstripNewlines(s.it.text), s);
275
267
  let description;
276
268
  if (s.kind === 'skill') {
277
- description = skillDescription(s.it.text);
269
+ description = skillDescription(s.it.text, s.stem, cfg.src);
278
270
  body = stripSkillBodyLinks(link(pointSideFiles(body, s.stem, 'references')));
279
271
  if (!profile.keepSkillSelfImprovement) body = dropSelfImprovement(body);
280
272
  for (const side of items) {
@@ -289,11 +281,12 @@ export function planExport({ profile = { ...PROFILE_DEFAULTS }, theme = 'neutral
289
281
  description = agentDescription(s.it.text);
290
282
  body = link(body);
291
283
  }
292
- if (profile.laws && CITES_RE.test(readText(s.it.src))) requires.add(lawsName);
293
284
  files.push({ rel: `${dir}/${s.kind === 'skill' ? 'SKILL.md' : 'AGENT.md'}`, text: frontmatter(s.name, description) + body });
294
285
  files.push({ rel: `${dir}/metadata.yaml`, text: metadataYaml({
295
286
  ...base, type: s.kind, requires: [...requires].sort(),
296
- version: versions[`${s.kind === 'skill' ? 'skills' : 'agents'}/${s.stem}`]?.version ?? release,
287
+ // Every entity carries the harness release, as the laws do: the set ships as one, and the
288
+ // per-entity versions in registry.json were never bumped (the user decided, 2026-11).
289
+ version: release,
297
290
  ...creditsOf(s.it.src, cfg.src),
298
291
  }) });
299
292
  entities.push({ type: s.kind, name: s.name, source: srcRel(s.it), path: dir });
@@ -325,15 +318,17 @@ export function planExport({ profile = { ...PROFILE_DEFAULTS }, theme = 'neutral
325
318
  : tier === 'laws'
326
319
  ? ['Laws', `the invariants, always in force (${rules} rules)`]
327
320
  : ['Ontology', 'how the agent thinks, decides and behaves'];
328
- const file = tier === 'doctrines' ? `doctrines-${stem}.md` : `${tier}.md`;
321
+ // `laws-<stem>.md`, never `laws.md`: beside the `LAWS.md` index that name is the SAME file
322
+ // on a case-insensitive file system (Windows, macOS), and the index was silently lost.
323
+ const file = tier === 'ontology' ? 'ontology.md' : `${tier}-${stem}.md`;
329
324
  parts.push({ rank: ['ontology', 'laws'].indexOf(tier) >= 0 ? ['ontology', 'laws'].indexOf(tier) : 2 + packs.indexOf(stem), file, title, what });
330
325
  files.push({ rel: `${dir}/${file}`, text: `# ${title}\n\n${body}\n` });
331
326
  }
332
327
  parts.sort((x, y) => x.rank - y.rank);
333
328
  files.push({ rel: `${dir}/LAWS.md`, text: [
334
329
  `# ${lawsName}`, '',
335
- 'The constitution the skills and agents of this collection cite by principle name. One '
336
- + 'file per category:', '',
330
+ 'The constitution the skills and agents of this collection cite by principle name. It is a '
331
+ + 'side package: no skill or agent requires it. One file per category:', '',
337
332
  ...parts.map((x) => `- \`${x.file}\` — ${x.title}: ${x.what}`), '',
338
333
  ].join('\n') });
339
334
  files.push({ rel: `${dir}/metadata.yaml`, text: metadataYaml({
@@ -91,7 +91,8 @@ function sysExit(msg) {
91
91
  const BUILD_FORWARD = [
92
92
  ['theme', '--theme'], ['emit', '--emit'], ['footprint', '--footprint'],
93
93
  ['posture', '--posture'], ['mode', '--mode'], ['trust', '--trust'], ['doctrines', '--doctrines'],
94
- ['excludeRules', '--exclude-rules'], ['excludeSkills', '--exclude-skills'], ['kits', '--kits'], ['sharedTier', '--shared-tier'], ['out', '--out'], ['root', '--root'],
94
+ ['excludeRules', '--exclude-rules'], ['excludeSkills', '--exclude-skills'], ['kits', '--kits'], ['sharedTier', '--shared-tier'],
95
+ ['contextWindow', '--context-window'], ['out', '--out'], ['root', '--root'],
95
96
  ['configDir', '--config-dir'],
96
97
  ];
97
98
 
@@ -0,0 +1,99 @@
1
+ /**
2
+ * The project notes, moved to their one folder (the owner's ruling, 2026-11-15).
3
+ *
4
+ * Before the two scopes, a PROJECT install kept every spec-feedback note in its own notebook,
5
+ * which differs per host: `.claude/notebook`, `.bob/notebook`, `.openclaude/notebook`, and
6
+ * `.opencode/notebook` for an OpenCode install older than #590. Those notes were written with no
7
+ * scope, so each counts as a PROJECT note now: on the next emit of that install they are merged
8
+ * into `<project>/notebook/{agent,skill}-notes/`, the one folder every host's step 0 reads.
9
+ *
10
+ * NO LOSS, BY CONSTRUCTION. The merge has no cap (`mergeNotesText`: a line the target already holds
11
+ * exactly is not added twice, and nothing is dropped), the target is read back and must hold every
12
+ * line of the source before the source moves, and the source then moves aside into
13
+ * `<project>/notebook/archived-<sub>/<stamp>/`, beside the target so a removed worktree cannot take
14
+ * the backup with it, as the fold sets a host store aside: never unlinked. A file
15
+ * that cannot be merged (not UTF-8 on either side, a read or write that fails) stays where it was,
16
+ * named in one line. A global install's notebook is the fold's (js/build/fold.mjs `foldNotes`), and
17
+ * a second emit finds nothing to move.
18
+ */
19
+ import { isUtf8 } from 'node:buffer';
20
+ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, statSync, writeFileSync } from 'node:fs';
21
+ import path from 'node:path';
22
+ import { NOTES_DIRS } from '../lib/machine-dir.mjs';
23
+ import { normcase } from '../lib/paths.mjs';
24
+ import { relPosix } from '../lib/text.mjs';
25
+ import { archiveStore } from '../hosts/memory-files.mjs';
26
+ import {
27
+ excludeProjectNotes, mergeNotesText, projectNotesDir, withLock,
28
+ } from '../hosts/spec-feedback.mjs';
29
+
30
+ const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
31
+ const readUtf8 = (p) => {
32
+ const raw = readFileSync(p);
33
+ if (!isUtf8(raw)) throw new Error('not UTF-8');
34
+ return raw.toString('utf8');
35
+ };
36
+ // Every line of a note, exact (a CR aside): what the read-back compares.
37
+ const linesOf = (text) => new Set(text.replace(/\r\n?/g, '\n').split('\n').filter((l) => l.trim()));
38
+
39
+ /**
40
+ * Merge `<cfgDir>/notebook/{agent,skill}-notes/*.md` into `<projectRoot>/notebook/…`. Returns
41
+ * `{ moved, kept, archived }`: the files merged and set aside, the files left in place with why,
42
+ * and where the moved ones went. Prints one line when it moved anything and one per file it kept.
43
+ */
44
+ export function migrateProjectNotes(cfgDir, projectRoot, say = (s) => process.stdout.write(s)) {
45
+ const report = { moved: [], kept: [], archived: [] };
46
+ // A linked worktree's notes go to its main checkout, as the hook writes them (`projectNotesDir`).
47
+ const target = projectNotesDir(projectRoot);
48
+ for (const sub of NOTES_DIRS) {
49
+ const src = path.join(cfgDir, 'notebook', sub);
50
+ const dst = path.join(target, sub);
51
+ if (normcase(path.resolve(src)) === normcase(path.resolve(dst))) continue;
52
+ let names;
53
+ try { names = readdirSync(src).filter((n) => n.endsWith('.md') && isFile(path.join(src, n))).sort(); } catch { continue; }
54
+ const merged = [];
55
+ for (const name of names) {
56
+ const from = path.join(src, name);
57
+ const to = path.join(dst, name);
58
+ const rel = relPosix(projectRoot, from) || from;
59
+ try {
60
+ const text = readUtf8(from);
61
+ mkdirSync(dst, { recursive: true });
62
+ // Under the capture's own lock: a hook may be adding a note to the same file right now.
63
+ const done = withLock(to, () => {
64
+ const next = mergeNotesText(existsSync(to) ? readUtf8(to) : '', text);
65
+ if (next !== null) writeFileSync(to, next, 'utf8');
66
+ return true;
67
+ });
68
+ if (done !== true) throw new Error('the notes file stayed locked');
69
+ const have = linesOf(readUtf8(to));
70
+ if ([...linesOf(text)].some((l) => !have.has(l))) throw new Error(`${relPosix(projectRoot, to)} does not hold every line`);
71
+ merged.push(name);
72
+ } catch (e) {
73
+ report.kept.push({ rel, why: e.message });
74
+ }
75
+ }
76
+ if (merged.length) {
77
+ // Beside the merge target, not the source: in a linked worktree the source goes with the
78
+ // worktree, and the backup must outlive it.
79
+ const dest = archiveStore(src, (_store, into) => {
80
+ mkdirSync(into, { recursive: true });
81
+ for (const name of merged) renameSync(path.join(src, name), path.join(String(into), name));
82
+ }, path.join(target, `archived-${sub}`));
83
+ report.archived.push(dest);
84
+ report.moved.push(...merged.map((n) => `${sub}/${n}`));
85
+ try { rmdirSync(src); } catch { /* not empty: a kept file, or one that is not a note */ }
86
+ }
87
+ }
88
+ if (report.moved.length) {
89
+ // The notes and their archives stay out of every commit (`.git/info/exclude`, per clone).
90
+ excludeProjectNotes(target);
91
+ say(`[geneseed] notes: merged ${report.moved.length} project note file(s) from `
92
+ + `${relPosix(projectRoot, path.join(cfgDir, 'notebook')) || cfgDir} into ${relPosix(projectRoot, target) || target}/; the originals `
93
+ + `are set aside in ${report.archived.map((a) => relPosix(projectRoot, a) || a).join(', ')}\n`);
94
+ }
95
+ for (const { rel, why } of report.kept) {
96
+ say(`[geneseed] notes: kept ${rel} where it is, not merged into ${relPosix(projectRoot, target) || target}/ (${why}); merge it by hand\n`);
97
+ }
98
+ return report;
99
+ }
@@ -11,11 +11,11 @@
11
11
  import { existsSync } from 'node:fs';
12
12
  import path from 'node:path';
13
13
 
14
- import { GATE_SWITCHES, PACK_ORDER } from './source.mjs';
14
+ import { DEFAULT_CONTEXT_WINDOW, GATE_SWITCHES, PACK_ORDER } from './source.mjs';
15
15
  import { DEFAULT_PRESET } from '../loop/score.mjs';
16
16
  import { CLAUDE_STYLE, GLOBAL_MANIFEST, HOSTS } from '../hosts/hosts.mjs';
17
17
  import {
18
- EMIT_FOR, EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
18
+ EMIT_FOR, EMIT_HOST_SCOPE, contextWindowOfDir, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
19
19
  emitHostScopeOf, excludedRulesOfDir, excludedSkillsOfDir, footprintOfDir, kitsOfDir, sharedTierOfDir,
20
20
  gatesOfDir, installState, modeOfDir, postureOfDir, readMaybe, themeOfDir, trustOfDir,
21
21
  } from '../hosts/installs.mjs';
@@ -55,7 +55,8 @@ import {
55
55
  */
56
56
  export function setupBuildArgs(theme, emit, out = null, root = null, footprint = 'lean',
57
57
  posture = 'peer', mode = 'direct', doctrines = null, allPacks = PACK_ORDER,
58
- excludeRules = null, trust = DEFAULT_PRESET, excludeSkills = null, gates = {}, kits = null, sharedTier = false) {
58
+ excludeRules = null, trust = DEFAULT_PRESET, excludeSkills = null, gates = {}, kits = null, sharedTier = false,
59
+ contextWindow = DEFAULT_CONTEXT_WINDOW) {
59
60
  const argv = ['--theme', theme, '--emit', emit];
60
61
  if (!emit.endsWith('-global')) {
61
62
  if (out) argv.push('--out', out);
@@ -93,6 +94,9 @@ export function setupBuildArgs(theme, emit, out = null, root = null, footprint =
93
94
  if (kits?.length) argv.push('--kits', [...kits].sort().join(','));
94
95
  // The shared tier elides when off, like the kits: the default is off, so only `on` speaks.
95
96
  if (sharedTier) argv.push('--shared-tier', 'on');
97
+ // The context window elides at its default, like the shared tier: no config key feeds it, so
98
+ // only `1m` speaks and every default argv stays the bytes it was before the flag existed.
99
+ if (contextWindow && contextWindow !== DEFAULT_CONTEXT_WINDOW) argv.push('--context-window', contextWindow);
96
100
  return argv;
97
101
  }
98
102
 
@@ -150,9 +154,11 @@ export function installProfile(host, scope, root, notify = null) {
150
154
  const kits = kitsOfDir(root, host, notify);
151
155
  // A project install's `Shared tier: on` stays on across a rebuild; a global install never has it.
152
156
  const sharedTier = sharedTierOfDir(root, host);
157
+ // `Context window: 1m` stays 1m: a rebuild that forgot it would shrink the listing cap.
158
+ const contextWindow = contextWindowOfDir(root, host);
153
159
  const out = scope === 'global' ? null : root;
154
160
  const argv = setupBuildArgs(theme, emit, out, out, footprint, posture, mode, doctrines,
155
- PACK_ORDER, excludeRules, trust, excludeSkills, gates, kits, sharedTier);
161
+ PACK_ORDER, excludeRules, trust, excludeSkills, gates, kits, sharedTier, contextWindow);
156
162
  // A GLOBAL ROW NAMES ITS OWN DIR. `root` came from the host's config-dir resolver, which
157
163
  // honours env overrides (`OPENCODE_CONFIG_DIR`, `CLAUDE_CONFIG_DIR`…); without the flag the
158
164
  // same argv run from a shell lacking that variable re-emits into the DEFAULT dir — a second
@@ -161,7 +167,7 @@ export function installProfile(host, scope, root, notify = null) {
161
167
  return {
162
168
  host, scope, root, state: installState(root, host, scope),
163
169
  emit, theme, footprint, posture, mode, trust, doctrines, excludeRules, excludeSkills,
164
- kits, sharedTier, ...gates, argv,
170
+ kits, sharedTier, contextWindow, ...gates, argv,
165
171
  };
166
172
  }
167
173
 
@@ -204,6 +210,8 @@ const GUARDED = [
204
210
  { name: 'kits', given: 'kits', flag: '--kits', now: (a) => show(sorted(a.kits)), was: (p) => show(sorted(p.kits)) },
205
211
  { name: 'shared-tier', given: 'sharedTier', flag: '--shared-tier',
206
212
  now: (a) => (a.sharedTier === 'on' ? 'on' : 'off'), was: (p) => (p.sharedTier ? 'on' : 'off') },
213
+ { name: 'context-window', given: 'contextWindow', flag: '--context-window',
214
+ now: (a) => a.contextWindow ?? DEFAULT_CONTEXT_WINDOW, was: (p) => p.contextWindow },
207
215
  // A switch reads as its flag says. `--no-deletion-gate` given is `deletion-gate: off`;
208
216
  // `--strict-consent` (the one switch whose flag adds asks, so it is not `--no-*`) given is
209
217
  // `strict-consent: on`. Either way the flag given means the switch's key is `false`.
@@ -236,7 +244,7 @@ function givenTokens(row, args) {
236
244
  * before it is ours, and the guard must never refuse a first install into a repo that already
237
245
  * uses OpenCode.
238
246
  */
239
- function guardTarget(args, out) {
247
+ export function guardTarget(args, out) {
240
248
  if (args.emit === 'files') return null;
241
249
  const [host, scope] = EMIT_HOST_SCOPE.get(args.emit) ?? [];
242
250
  if (!host) return null;
@@ -37,8 +37,11 @@ import { normcase, comparePaths } from '../lib/paths.mjs';
37
37
  import {
38
38
  CREDIT_RE, GATE_SWITCHES, PACK_ORDER, kitMembers, loadKits, readPackText, resolveCredits, resolveRuleIds, ruleCanon, titleKey, upstreamOf,
39
39
  } from './source.mjs';
40
+ import { CONTEXT_WINDOW_MARKER, DEFAULT_CONTEXT_WINDOW } from './source.mjs';
40
41
  import { SHARED_TIER_LINE } from '../hosts/hosts.mjs';
41
- import { VENDORED_SKILL_DIRS } from '../hosts/native.mjs';
42
+ import { PROJECT_NOTES_DIR } from '../hosts/spec-feedback.mjs';
43
+ import { PORTABLE_MACHINE_DIR } from '../lib/machine-dir.mjs';
44
+ import { VENDORED_SKILL_DIRS, vendoredWithCatalogueLine } from '../hosts/native.mjs';
42
45
  import { DEFAULT_PRESET } from '../loop/score.mjs';
43
46
 
44
47
  /** Document STRUCTURE is theme-INDEPENDENT — mirrors `_build_render.STRUCTURE`. */
@@ -72,7 +75,11 @@ export function pathTokens(theme, sharedRoot = null) {
72
75
  const at = sharedRoot ? `${sharedRoot}/` : theme.AT_HARNESS ?? '';
73
76
  return {
74
77
  PATH_MEMORY: sharedRoot ? `${at}memory` : memory,
75
- PATH_NOTES: sharedRoot ? `${at}notes` : theme.DIR_NOTEBOOK ?? 'notebook',
78
+ // The two notes scopes (js/hosts/spec-feedback.mjs `PROJECT_NOTES_DIR`). Machine: the tier,
79
+ // absolute on a global emit, the portable `~` form on any other (a project's files travel).
80
+ // Project: relative to the project root, the same on every host and never prefixed.
81
+ PATH_NOTES: `${sharedRoot ?? PORTABLE_MACHINE_DIR}/notes`,
82
+ PATH_PROJECT_NOTES: PROJECT_NOTES_DIR,
76
83
  PATH_RULES: `${at}user-rules.md`,
77
84
  PATH_PROFILE: `${at}PROFILE.md`,
78
85
  PATH_WIKI: `${at}geneseed-wiki.jsonc`,
@@ -95,9 +102,10 @@ export const SRC_DIR_TOKENS = {
95
102
  };
96
103
 
97
104
  const TEXT_SUFFIXES = new Set(['.md', '.tmpl', '.json', '.txt', '.yml', '.yaml']);
98
- /** Top-level `src/` entries the build reads but never ships: upstream-credit provenance, and the
99
- * kit manifests (a kit's members ship flat from `skills/` and `agents/`). */
100
- const NOT_BUNDLED = new Set(['upstreams.json', 'licenses', 'kits']);
105
+ /** Top-level `src/` entries the build reads but never ships: upstream-credit provenance, the
106
+ * kit manifests (a kit's members ship flat from `skills/` and `agents/`), and the skill
107
+ * catalogue lines (they ship inside each skill's frontmatter, `skillDescription`). */
108
+ const NOT_BUNDLED = new Set(['upstreams.json', 'licenses', 'kits', 'skill-descriptions.json']);
101
109
 
102
110
  // Digits are legal after the first character: `DOC_<PACK>_<n>` (the doctrine rule titles) are
103
111
  // the first token names in the project to carry one, and without `0-9` here `{{DOC_CRAFT_1}}`
@@ -397,6 +405,12 @@ function readSource(cfg, p) {
397
405
  return text;
398
406
  }
399
407
 
408
+ /** A skill spec's id, `skills/<id>.md` (a `_` file is a partial, not a skill), else null. */
409
+ function skillIdOf(file) {
410
+ const stem = path.basename(file, '.md');
411
+ return path.basename(path.dirname(file)) === 'skills' && file.endsWith('.md') && !stem.startsWith('_') ? stem : null;
412
+ }
413
+
400
414
  /**
401
415
  * `_build_render.render_file`.
402
416
  *
@@ -424,6 +438,11 @@ export function renderFile(cfg, filePath, theme, footprint = 'full', lawsPrefix
424
438
  .replace(/\n+$/, ''); // `.rstrip("\n")`
425
439
  });
426
440
 
441
+ // A skill's own id, for the notes path and the feedback tag its self-improvement include names
442
+ // (src/skills/_self-improvement.md): literal, so the model never guesses it from an alias it
443
+ // was run under. On the top-level file only, once the includes are flattened into it; any
444
+ // other file (the include itself, the template) keeps the `<name>` placeholder.
445
+ if (!visiting.size) text = text.replaceAll('{{SKILL_NAME}}', skillIdOf(here) ?? '<name>');
427
446
  text = resolveCatalogs(text, nativeCatalog, cfg.excludeSkills ?? [], cfg);
428
447
  text = resolveLean(text, footprint);
429
448
  if (footprint === 'lean') text = leanVoice(text, cfg.src);
@@ -627,12 +646,10 @@ export function effectiveTheme(cfg, themeName, {
627
646
  footprint = 'full', lawsPrefix = '', sharedRoot = null,
628
647
  } = {}) {
629
648
  const theme = { ...loadTheme(cfg, themeName), ...(cfg.structure ?? STRUCTURE) };
649
+ // Neither notes path takes `lawsPrefix`: the machine one is the tier's, and the project one is
650
+ // the project root's `notebook/` on every host. Prefixing it once sent OpenClaude's skills to
651
+ // `notebook/` while its hook wrote `.openclaude/notebook/` (T10).
630
652
  Object.assign(theme, pathTokens(theme, sharedRoot));
631
- // A skill or agent names its notes file as a path the agent opens from the project root, and
632
- // on an install whose harness sits a level down (`.claude/`) the notebook is there too. Only
633
- // the relative form takes the prefix; the root file's re-render (`prefixedAgentText`) derives
634
- // its own from its prefixed DIR_NOTEBOOK.
635
- if (!sharedRoot) theme.PATH_NOTES = `${lawsPrefix}${theme.PATH_NOTES}`;
636
653
  // Empty without a tier, so a project emit and a default build stay byte-identical (the
637
654
  // `EXCLUDED_SKILLS_LINE` contract). Each rides the end of a template line, so its value carries
638
655
  // the blank line. C1 lives in this text: the readers only concatenate, shared first.
@@ -689,6 +706,9 @@ export function effectiveTheme(cfg, themeName, {
689
706
  // The shared-tier marker, under the same contract (`sharedTierOfDir` reads it): written only when
690
707
  // `on`, so a default build stays byte-identical. Not `GATE_SWITCHES`, which holds `--no-*` disarms.
691
708
  theme.SHARED_TIER_LINE = cfg.sharedTier ? `\n${SHARED_TIER_LINE}\n` : '';
709
+ // `--context-window`, under the same contract (`contextWindowOfDir` reads it): a line only off the default.
710
+ theme.CONTEXT_WINDOW_LINE = cfg.contextWindow && cfg.contextWindow !== DEFAULT_CONTEXT_WINDOW
711
+ ? `\n${CONTEXT_WINDOW_MARKER}: ${cfg.contextWindow}\n` : '';
692
712
  // The gate switches (`GATE_SWITCHES`: Laws I, III, IV), under the same contract: a line is
693
713
  // written only when its gate is OFF, so a default build stays byte-identical and a missing
694
714
  // line reads back as armed (`gatesOfDir`). The OpenCode plugins read these lines at load, so
@@ -774,6 +794,10 @@ export function renderAll(cfg, themeName, {
774
794
  const fp = /^(?:laws|ontology|doctrines)[\\/]/.test(rel) ? 'full' : footprint;
775
795
  let text = TEXT_SUFFIXES.has(suffixOf(path.basename(file)))
776
796
  ? renderFile(cfg, file, theme, fp, lawsPrefix, new Set(), nativeCatalog) : null;
797
+ // A vendored skill's listed description is our catalogue line, on every host and in the
798
+ // bundle; here, once, so no writer applies it twice.
799
+ if (text !== null && sp[0] === 'skills' && sp.length === 3 && sp[2] === 'SKILL.md'
800
+ && VENDORED_SKILL_DIRS.has(sp[1])) text = vendoredWithCatalogueLine(text, sp[1], cfg.src);
777
801
  items.push({ rel: outRel, text, src: file });
778
802
  // A credited skill ships its upstream's licence beside it, one copy per (skill, key). The
779
803
  // token is gone from `text`, so the raw source is scanned; an unknown key or a null
@@ -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
 
@@ -600,6 +646,41 @@ export const GATE_SWITCHES = [
600
646
  { key: 'ownBranchPass', flag: '--strict-consent', arg: 'strictConsent', marker: 'Own-branch pass', law: null },
601
647
  ];
602
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
+
603
684
  /**
604
685
  * `_build_core.js_cfg()`, originated rather than received.
605
686
  *
@@ -615,7 +696,7 @@ export const GATE_SWITCHES = [
615
696
  export function makeCfg({
616
697
  posture = 'peer', mode = 'direct', trust = DEFAULT_PRESET, doctrines = PACK_ORDER,
617
698
  excludeRules = [], excludeSkills = [], kits = [], sharedTier = /** @type {boolean | string} */ (false),
618
- pruneGates = false, force = false, ...switches
699
+ contextWindow = DEFAULT_CONTEXT_WINDOW, pruneGates = false, force = false, ...switches
619
700
  } = {}) {
620
701
  return {
621
702
  root: ROOT,
@@ -647,6 +728,8 @@ export function makeCfg({
647
728
  kits: Array.isArray(kits) ? [...kits] : [],
648
729
  // The shared tier read by a PROJECT install (`--shared-tier on`); `on` from the flag, a boolean from a read-back.
649
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,
650
733
  // `--force`, for this one build: only a literal `true` forces. Never an axis of the install.
651
734
  force: force === true,
652
735
  // The gate switches (`GATE_SWITCHES`: `secretsGate`, `doneGate`, `deletionGate`), each armed