geneseed 5.0.3 → 5.1.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 (141) hide show
  1. package/CHANGELOG.md +83 -0
  2. package/README.md +3 -3
  3. package/SHIPPED.md +2 -2
  4. package/adapters/claude-code/README.md +5 -1
  5. package/adapters/openclaude/README.md +3 -1
  6. package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
  7. package/adapters/opencode/workflows/_runtime.js +1 -1
  8. package/bin/geneseed-cli.mjs +3 -0
  9. package/bin/geneseed-hook.mjs +10 -2
  10. package/docs/PRD.md +1 -1
  11. package/docs/README.md +4 -1
  12. package/docs/concepts/enforcement-table.md +1 -1
  13. package/docs/concepts/exclusions.md +1 -1
  14. package/docs/concepts/factories.md +203 -0
  15. package/docs/concepts/hooks.md +1 -1
  16. package/docs/concepts/host-matrix.md +1 -0
  17. package/docs/concepts/loop-gates.md +6 -0
  18. package/docs/concepts/loops.md +1 -0
  19. package/docs/concepts/rules.md +1 -1
  20. package/docs/concepts/shared-tier.md +14 -0
  21. package/docs/extending.md +5 -1
  22. package/docs/guides/autostart.md +2 -0
  23. package/docs/guides/migrate.md +1 -1
  24. package/docs/guides/run-a-factory.md +116 -0
  25. package/docs/guides/set-up-ownership.md +1 -0
  26. package/docs/guides/upgrade-to-5.md +2 -2
  27. package/docs/reference/factory-actions.md +22 -0
  28. package/docs/reference/loop-actions.md +1 -1
  29. package/docs/reference/plugin-activity.md +1 -1
  30. package/docs/web-ui.md +47 -2
  31. package/harness.config.json +1 -1
  32. package/js/README.md +21 -2
  33. package/js/build/args.mjs +44 -12
  34. package/js/build/emit-claude.mjs +3 -0
  35. package/js/build/emit-opencode.mjs +4 -0
  36. package/js/build/retired-skills.mjs +158 -0
  37. package/js/build/source.mjs +41 -2
  38. package/js/cli-table.json +193 -3
  39. package/js/factory/cli.mjs +194 -0
  40. package/js/factory/graph.mjs +309 -0
  41. package/js/factory/registry.mjs +71 -0
  42. package/js/factory/state.mjs +511 -0
  43. package/js/hosts/activity.mjs +3 -3
  44. package/js/hosts/done-checks.mjs +3 -2
  45. package/js/hosts/geneseed-dir.mjs +1 -1
  46. package/js/hosts/gitref.mjs +21 -0
  47. package/js/hosts/hooks-context.mjs +63 -9
  48. package/js/hosts/hooks-prims.mjs +1 -1
  49. package/js/hosts/memory-files.mjs +4 -2
  50. package/js/hosts/settings.mjs +5 -4
  51. package/js/inspect/checks-authoring.mjs +11 -1
  52. package/js/inspect/cost.mjs +91 -5
  53. package/js/inspect/doctor.mjs +2 -1
  54. package/js/inspect/inventory.mjs +1 -1
  55. package/js/loop/catalog.mjs +30 -12
  56. package/js/loop/cli.mjs +27 -15
  57. package/js/loop/graph.mjs +13 -4
  58. package/js/loop/registry.mjs +65 -28
  59. package/js/loop/state.mjs +18 -8
  60. package/js/maintain/migrate.mjs +39 -25
  61. package/js/web/api.mjs +43 -1
  62. package/js/web/catalog.mjs +38 -2
  63. package/js/web/daemon.mjs +191 -6
  64. package/js/web/handler.mjs +27 -5
  65. package/js/web/routes.mjs +10 -3
  66. package/js/web/server.mjs +4 -1
  67. package/package.json +1 -1
  68. package/registry.json +14 -0
  69. package/src/AGENT.md.tmpl +5 -7
  70. package/src/bricks/checks.md +62 -0
  71. package/src/bricks/docs-update.md +5 -0
  72. package/src/bricks/holdout-write.md +23 -0
  73. package/src/bricks/holdout.md +25 -0
  74. package/src/bricks/intake.md +27 -0
  75. package/src/bricks/merge-gate.md +31 -0
  76. package/src/bricks/pr-open.md +21 -0
  77. package/src/bricks/retro.md +22 -0
  78. package/src/bricks/review-panel.md +43 -0
  79. package/src/bricks/spec.md +20 -6
  80. package/src/bricks/test.md +4 -1
  81. package/src/bricks/triage.md +19 -0
  82. package/src/doctrines/comms.md +29 -41
  83. package/src/doctrines/craft.md +3 -10
  84. package/src/doctrines/ops.md +4 -15
  85. package/src/doctrines/rigor.md +1 -5
  86. package/src/factories/analysis-to-build.json +52 -0
  87. package/src/factories/bug-report-to-fix.json +50 -0
  88. package/src/factories/issue-to-pr.json +67 -0
  89. package/src/skills/_checkpoints.md +1 -0
  90. package/src/skills/adhd.md +1 -1
  91. package/src/skills/factory-forge.md +115 -0
  92. package/src/skills/factory.md +196 -0
  93. package/src/skills/loop.md +3 -2
  94. package/src/skills/parallel-agents.md +1 -1
  95. package/src/skills/workflow.md +2 -1
  96. package/themes/_TEMPLATE.json +4 -2
  97. package/themes/biker.json +4 -2
  98. package/themes/commentator.json +4 -2
  99. package/themes/cyberpunk.json +4 -2
  100. package/themes/gamer.json +4 -2
  101. package/themes/imperial.json +4 -2
  102. package/themes/joker.json +4 -2
  103. package/themes/marvin.json +4 -2
  104. package/themes/mean.json +4 -2
  105. package/themes/military.json +4 -2
  106. package/themes/neutral.json +4 -2
  107. package/themes/pirate.json +4 -2
  108. package/themes/sports.json +4 -2
  109. package/themes/verstappen.json +4 -2
  110. package/themes/wizard.json +4 -2
  111. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
  112. package/web/dist/assets/{Activity-Ck_Xffpo.js → Activity-CpkBwpu7.js} +1 -1
  113. package/web/dist/assets/{ActivityDetail-CBxVS4mU.js → ActivityDetail-DTPziZWM.js} +1 -1
  114. package/web/dist/assets/{Bonsai-BlOwsvW6.js → Bonsai-hiG_gGNU.js} +1 -1
  115. package/web/dist/assets/{CopyButton-DFMOIGbe.js → CopyButton-DUIUfNp6.js} +1 -1
  116. package/web/dist/assets/Dashboard-Dnw6EyX7.js +2 -0
  117. package/web/dist/assets/{Docs-D_2Jt6gU.js → Docs-BEET_l16.js} +2 -2
  118. package/web/dist/assets/Factories-D6KXkfWw.js +1 -0
  119. package/web/dist/assets/{GreenhouseView-WalcX5bp.js → GreenhouseView-BKxy5apE.js} +1 -1
  120. package/web/dist/assets/{Installs-UGiPDMDt.js → Installs-CnFVlVD0.js} +3 -3
  121. package/web/dist/assets/{JournalView-CZtXQz-v.js → JournalView-ChFitHjo.js} +1 -1
  122. package/web/dist/assets/{Kits-XQHsazCN.js → Kits-CcR-OlwQ.js} +1 -1
  123. package/web/dist/assets/Laws-B1s5idOg.js +4 -0
  124. package/web/dist/assets/LibRows-BZgdbI1l.js +1 -0
  125. package/web/dist/assets/Library-x6TkkEVF.js +3 -0
  126. package/web/dist/assets/Loops-BH93KKxn.js +2 -0
  127. package/web/dist/assets/{OperatorHudView-CeDw5qMB.js → OperatorHudView-BO0aIKPL.js} +1 -1
  128. package/web/dist/assets/{Personal-PVmGA2-M.js → Personal-CE_0Vhh0.js} +2 -2
  129. package/web/dist/assets/{Settings-DWuxwh4i.js → Settings-CbpZvVN_.js} +1 -1
  130. package/web/dist/assets/{Tabs-d2RIRAKT.js → Tabs-C2oW7oEj.js} +1 -1
  131. package/web/dist/assets/api-DLDVY3K-.js +1 -0
  132. package/web/dist/assets/{index-BNttaGQb.js → index-BQwOmbor.js} +3 -3
  133. package/web/dist/assets/index-CuIop_pO.css +1 -0
  134. package/web/dist/index.html +3 -3
  135. package/web/dist/assets/Dashboard-BUdUTjbB.js +0 -2
  136. package/web/dist/assets/Laws-B6A55S-2.js +0 -4
  137. package/web/dist/assets/Library-D7L0Wdbh.js +0 -3
  138. package/web/dist/assets/Loops-C0loS73u.js +0 -2
  139. package/web/dist/assets/RailCats-BGZnJ6fa.js +0 -1
  140. package/web/dist/assets/api-BMFDSXoB.js +0 -1
  141. package/web/dist/assets/index-BEI5ugYQ.css +0 -1
@@ -410,10 +410,10 @@ function sessionEntry(rel, abs, text, label) {
410
410
  * A missing or unreadable file is simply absent — this is best-effort context, never a gate.
411
411
  * `host` is what the emitted hook passes (`emittedHost`), null for none, which reads as claude.
412
412
  */
413
- export function sessionFiles(hookRoot, host = null, carrier = installCarrier(hookRoot, host)) {
413
+ export function sessionFiles(hookRoot, host = null, carrier = installCarrier(hookRoot, host), rels = SESSION_FILES) {
414
414
  const tier = readsTier(hookRoot, host) || projectReadsTier(carrier);
415
415
  const found = [];
416
- for (const rel of SESSION_FILES) {
416
+ for (const rel of rels) {
417
417
  const wiki = rel === 'geneseed-wiki.jsonc';
418
418
  const pinned = wiki && process.env.GENESEED_WIKI && isFile(process.env.GENESEED_WIKI);
419
419
  const hostAbs = pinned ? process.env.GENESEED_WIKI
@@ -676,7 +676,12 @@ const installCarrier = (hookRoot, host) => installCarrierFile(hookRoot, host)[1]
676
676
  * instead of injected; a lazy listing shortened is not, since it only names files. `heads` are the
677
677
  * lines above the session block; `root` places `eager` and `lazy`. Reads, never prints.
678
678
  */
679
- function renderPayload({ heads, session, eager, lazy, source, root }) {
679
+ const SESSION_TITLE = '=== SESSION FILES — your harness files, injected at session start '
680
+ + '(untouched seeds skipped) ===';
681
+ // The sub-agent's banner (`subagentRules`): the user's rules alone, under their own title.
682
+ export const USER_RULES_TITLE = '=== USER RULES — the user\'s standing rules; obey them as you obey the Dictates ===';
683
+
684
+ function renderPayload({ heads, session, eager, lazy, source, root, title = SESSION_TITLE, budget = OUTPUT_BUDGET }) {
680
685
  const lines = [];
681
686
  // `spent` counts every character pushed, headers included: the budget is the host's cap on
682
687
  // the whole payload, not on the file bodies alone.
@@ -685,8 +690,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
685
690
  const push = (...ls) => { for (const l of ls) { lines.push(l); spent += cost(l); } };
686
691
  if (heads.length) push(...heads, '');
687
692
  if (session.length) {
688
- push('=== SESSION FILES \u2014 your harness files, injected at session start '
689
- + '(untouched seeds skipped) ===', '');
693
+ push(title, '');
690
694
  // Rules answer only to their own size: the lines above them never push one out, so they are
691
695
  // capped when their layers together pass the share, and everything after them spends `spent`.
692
696
  let rulesSpent = 0;
@@ -694,7 +698,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
694
698
  for (const s of session) {
695
699
  const head = `----- ${s.rel}${s.label ? ` (${s.label})` : ''} -----`;
696
700
  const rules = s.rel === 'user-rules.md';
697
- const room = OUTPUT_BUDGET - LAZY_RESERVE - (rules ? rulesSpent : spent) - cost(head) - cost('');
701
+ const room = budget - LAZY_RESERVE - (rules ? rulesSpent : spent) - cost(head) - cost('');
698
702
  const where = `${s.abs} on demand`;
699
703
  if (room <= 0) {
700
704
  left.push({ rel: s.rel, line: `[context] ${s.rel} not injected (session budget) \u2014 read ${where}` });
@@ -708,7 +712,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
708
712
  // Paths have no length limit, so these lines answer to the budget like any listing.
709
713
  if (left.length) {
710
714
  cut = true;
711
- const room = OUTPUT_BUDGET - LIST_RESERVE - spent - cost('');
715
+ const room = budget - LIST_RESERVE - spent - cost('');
712
716
  const tail = (n) => `[context] ${n} more session files not injected (session budget)`;
713
717
  // The memory map first, and by its short name when its path cannot fit: a count line must
714
718
  // never replace the one file C12 owes a line that names it.
@@ -739,7 +743,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
739
743
  push(head, `[context] MISSING eager file: ${asOsError(e, target)}`, '');
740
744
  continue;
741
745
  }
742
- if (spent + cost(head) + cost(text) + cost('') > OUTPUT_BUDGET - LAZY_RESERVE) {
746
+ if (spent + cost(head) + cost(text) + cost('') > budget - LAZY_RESERVE) {
743
747
  demoted.push({ ...entry, over: true });
744
748
  continue;
745
749
  }
@@ -749,7 +753,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
749
753
  if (lazy.length || demoted.length) {
750
754
  const title = '--- Lazy entries (load only when the task needs them) ---';
751
755
  push(title);
752
- push(...lazyLines([...lazy, ...demoted], root, OUTPUT_BUDGET - spent - cost('')), '');
756
+ push(...lazyLines([...lazy, ...demoted], root, budget - spent - cost('')), '');
753
757
  }
754
758
  return { text: `${lines.join('\n')}\n`, spent, cut: cut || demoted.length > 0 };
755
759
  }
@@ -769,6 +773,51 @@ export function sessionStartSize(hookRoot, host) {
769
773
  return { chars: spent, budget: OUTPUT_BUDGET, cut };
770
774
  }
771
775
 
776
+ /**
777
+ * The user-rules layers a sub-agent gets, in SessionStart's order and under its labels: the tier
778
+ * and the install, then the project root's own `user-rules.md`, each file once. Only these files
779
+ * are read: a sub-agent start must not pay for the profile, the memory map or a wiki walk. The
780
+ * project root is `root`, the same `$GENESEED_ROOT || $CLAUDE_PROJECT_DIR || cwd` SessionStart
781
+ * discovers from, and its file is read directly, as discovery's root entry: a `context.json` that
782
+ * names it lazy or leaves it out does not keep it from a sub-agent.
783
+ */
784
+ export function userRuleLayers(root, hookRoot, host) {
785
+ const rules = hookRoot ? sessionFiles(hookRoot, host, installCarrier(hookRoot, host), ['user-rules.md']) : [];
786
+ const abs = root ? path.join(root, 'user-rules.md') : null;
787
+ if (abs && !rules.some((s) => normcase(path.resolve(s.abs)) === normcase(path.resolve(abs)))) {
788
+ const text = sessionText(abs);
789
+ if (text !== null) rules.push({ rel: disp(abs, root), abs, label: '', text });
790
+ }
791
+ return rules;
792
+ }
793
+
794
+ /**
795
+ * A sub-agent's start (`SubagentStart`): no host hands a sub-agent the SessionStart output, so the
796
+ * user's rules reach it here, and nothing else (spec 2026-11-08, D4): not the profile, not the
797
+ * project context, which the root file already brings. Same renderer and same cut as SessionStart.
798
+ * Claude Code documents only the JSON form for this event, so the payload is ONE JSON object on
799
+ * stdout, and the budget holds for that line, not for the text inside it: `JSON.stringify` adds a
800
+ * character per `"`, `\` and line break, so a render whose line runs over is redone with the budget
801
+ * scaled by how far over it ran (each pass shrinks it, so a few converge). No rule anywhere prints
802
+ * nothing, as an empty SessionStart does.
803
+ */
804
+ function subagentRules(root, hookRoot, host) {
805
+ const rules = userRuleLayers(root, hookRoot, host);
806
+ if (!rules.length) return 0;
807
+ let budget = OUTPUT_BUDGET;
808
+ for (let pass = 0; pass < 6; pass += 1) {
809
+ const { text } = renderPayload({ heads: [], session: rules, eager: [], lazy: [], source: '', root, title: USER_RULES_TITLE, budget });
810
+ const line = JSON.stringify({ hookSpecificOutput: { hookEventName: 'SubagentStart', additionalContext: text } });
811
+ if (line.length + 2 <= OUTPUT_BUDGET) {
812
+ out(`${line}\n`);
813
+ return 0;
814
+ }
815
+ // Scaled, not cut by the overrun: a budget unit of escape-heavy text serializes to two or more.
816
+ budget = Math.min(budget - 1, Math.floor((budget * OUTPUT_BUDGET) / (line.length + 2)));
817
+ }
818
+ return 0; // never converged: nothing, rather than a payload the host would cut
819
+ }
820
+
772
821
  export function cmdContext(args) {
773
822
  const host = (args && args.host) || null;
774
823
  // Discovery (and the stand-down) runs against the SESSION's project root, not the harness
@@ -793,6 +842,11 @@ export function cmdContext(args) {
793
842
  // The RAW `args.host`, never defaulted to claude, which would key an older
794
843
  // OpenClaude emit's `~/.openclaude` (no `--host`) on `.claude` instead of its folder name.
795
844
  if (globalHookStandingDown(hookRoot, root, args.host, 'context')) return 0;
845
+ // A sub-agent starts without its rules rather than without its Activity record: a throw here
846
+ // would exit 1 and skip `trackActivity` (spec 2026-11-08, failure table).
847
+ if (args.event === 'SubagentStart') {
848
+ try { return subagentRules(root, hookRoot, host); } catch { return 0; }
849
+ }
796
850
  const [carrierFile, carrier] = hookRoot ? installCarrierFile(hookRoot, host) : ['', ''];
797
851
  const session = hookRoot ? sessionFiles(hookRoot, host, carrier) : [];
798
852
  // A session file discovery would also pick up (a `user-rules.md` at the repo root of an
@@ -493,7 +493,7 @@ export function activityOn(root) {
493
493
 
494
494
  /**
495
495
  * The `activity` verb, wired to the events no other verb runs on (UserPromptSubmit; SessionEnd
496
- * and SubagentStart on Claude and OpenClaude). It decides nothing and prints nothing: the entry's
496
+ * on Claude and OpenClaude; SubagentStart runs `context` since the agent loadout). It decides nothing and prints nothing: the entry's
497
497
  * `trackActivity` records the payload after every verb alike, this one included.
498
498
  */
499
499
  export const cmdActivity = () => 0;
@@ -441,15 +441,17 @@ function dropLines(p, needle) {
441
441
  * shortcut: rename only, and the day a store can live on another volume this needs a copy path.
442
442
  *
443
443
  * `move` is `copyFileSync` for a file that must stay readable until its replacement lands.
444
+ * `parent` is overridden only for a retired skill folder, whose sibling would sit inside the
445
+ * host's `skills/` scan root and load again: it goes to `<cfg>/archived-skills/<name>/` instead.
444
446
  */
445
- export function archiveStore(store, move = renameSync) {
447
+ export function archiveStore(store, move = renameSync,
448
+ parent = path.join(path.dirname(store), `archived-${path.basename(store)}`)) {
446
449
  // `toLocaleString('sv-SE')` — LOCAL time, matching the old hand-rolled stamp
447
450
  // (`getHours()`/`getMinutes()`/`getSeconds()` are all local-time getters, unlike
448
451
  // `toISOString()`'s UTC). sv-SE's default format is already zero-padded
449
452
  // "YYYY-MM-DD HH:MM:SS"; stripping the punctuation and reinserting one dash reproduces
450
453
  // the exact `YYYYMMDD-HHMMSS` shape the padStart version built by hand.
451
454
  const stamp = new Date().toLocaleString('sv-SE').replace(/\D/g, '').replace(/^(\d{8})/, '$1-');
452
- const parent = path.join(path.dirname(store), `archived-${path.basename(store)}`);
453
455
  // A taken name gets `-2`, …: two moves in one second must not fail the second.
454
456
  let dest = path.join(parent, stamp);
455
457
  for (let n = 2; existsSync(dest); n += 1) dest = path.join(parent, `${stamp}-${n}`);
@@ -952,10 +952,11 @@ export function claudeHookGroups(cfg, hookOpts, doctrines = null, excluded = [],
952
952
  // user's prompt, and the `activity` verb decides nothing.
953
953
  UserPromptSubmit: [{ hooks: [{ type: 'command', command: activity }] }],
954
954
  SessionEnd: [{ hooks: [{ type: 'command', command: activity }] }],
955
- // A sub-agent's branch at launch (the Activity garden): a read-only sub-agent fires no gated
956
- // hook, so without this it would never appear. Never on Bob (the early return above): Bob's
957
- // hook schema is strict, and one unknown event key drops its whole hooks block.
958
- SubagentStart: [{ hooks: [{ type: 'command', command: activity }] }],
955
+ // A sub-agent's start: `context` reads the event name and injects the user's rules, which no
956
+ // sub-agent gets from SessionStart (spec 2026-11-08, agent loadout). The Activity garden's
957
+ // branch at launch still records, since `trackActivity` runs after every verb. Never on Bob
958
+ // (the early return above): its schema is strict, one unknown event key drops the whole block.
959
+ SubagentStart: [{ hooks: [{ type: 'command', command: context }] }],
959
960
  };
960
961
  // Claude Code only: OpenClaude always runs Git Bash on Windows (its `findGitBashPath` exits
961
962
  // without one), and Bob takes the early return above.
@@ -26,7 +26,8 @@ import {
26
26
  } from './checks-repo.mjs';
27
27
  import { constitutionProblems, leanBlockProblems } from './checks-constitution.mjs';
28
28
  import { countTableProblems, kitProblems } from './checks-counts.mjs';
29
- import { catalogProblems } from '../loop/catalog.mjs';
29
+ import { catalogProblems, loadCatalog } from '../loop/catalog.mjs';
30
+ import { factoryCatalogProblems } from '../factory/graph.mjs';
30
31
  import { globSorted, isDir, isFile, rglob } from './scan.mjs';
31
32
  import { spawnSync } from 'node:child_process';
32
33
 
@@ -126,6 +127,15 @@ export function loopProblems() {
126
127
  return catalogProblems({ projectRoot: null, globalLevel: false });
127
128
  }
128
129
 
130
+ /**
131
+ * The shipped factories parse and pass `checkFactory` against the shipped bricks and loops —
132
+ * `loopProblems`' twin, same scope. `opts` reaches `loadCatalog`, so a test can point the gate
133
+ * at a fixture `srcRoot` and see it redden while no factory ships yet.
134
+ */
135
+ export function factoryProblems(opts = {}) {
136
+ return factoryCatalogProblems(loadCatalog({ projectRoot: null, globalLevel: false, ...opts }));
137
+ }
138
+
129
139
  /**
130
140
  * Author-time gates on the source specs and plugins.
131
141
  *
@@ -25,6 +25,7 @@ import { emittedHost, sessionFiles, tierSessionChars } from '../hosts/hooks-cont
25
25
  import { carriersFor } from '../hosts/installs.mjs';
26
26
  import { frontmatter } from '../hosts/memory-files.mjs';
27
27
  import { listDir } from '../hosts/hooks-prims.mjs';
28
+ import { liveRecordedHooks } from '../hosts/hosts.mjs';
28
29
  import { loadJsonObject, opencodeTarget } from '../hosts/settings.mjs';
29
30
  import { isDict } from '../lib/json.mjs';
30
31
  import { isFile, readText } from '../lib/fs.mjs';
@@ -35,7 +36,7 @@ import { isFile, readText } from '../lib/fs.mjs';
35
36
  * console draws it on the cost chart, so it lives here, once, where both read it. Raise it by
36
37
  * exactly the measured overrun and say why in that test's docblock, which keeps its history.
37
38
  */
38
- export const CARRIER_CEILING = { full: 66_432, lean: 41_612 };
39
+ export const CARRIER_CEILING = { full: 66_432, lean: 40_312 };
39
40
 
40
41
  /**
41
42
  * THE TRADE OF `--shared-tier on`, stated once. `--help` (js/cli-table.json), the console's toggle
@@ -111,10 +112,25 @@ function userOnlyTest(host, root) {
111
112
  * carrier answers `null` for the whole cost, so the console shows "not measured", not a tiny bar.
112
113
  */
113
114
  export function alwaysOnCost({ host, root, dir, footprint }) {
114
- const carrierPath = carriersFor(host).map((rel) => path.join(root, rel)).find(isFile);
115
+ const carrierPath = carrierOf(host, root);
115
116
  if (!carrierPath) return null;
116
117
  const carrier = readText(carrierPath).length;
118
+ const { skills, agents } = catalogueChars(host, root, dir);
119
+ let context = 0;
120
+ for (const s of sessionLayers(dir, host)) context += s.text.length;
121
+ return { carrier, skills, agents, context, ceiling: CARRIER_CEILING[footprint] ?? null };
122
+ }
123
+
124
+ /** The install's root instruction file, or undefined: the first of the host's carriers on disk. */
125
+ const carrierOf = (host, root) => carriersFor(host).map((rel) => path.join(root, rel)).find(isFile);
126
+
127
+ /** The session files the context hook injects, `[]` when none can be read. */
128
+ function sessionLayers(dir, host) {
129
+ try { return sessionFiles(dir, emittedHost(host)); } catch { return []; }
130
+ }
117
131
 
132
+ /** The skill and agent catalogues the model lists, in characters: `alwaysOnCost`'s two parts. */
133
+ function catalogueChars(host, root, dir) {
118
134
  let skills = 0;
119
135
  const skillsDir = path.join(dir, 'skills');
120
136
  const userOnly = userOnlyTest(host, root);
@@ -129,8 +145,78 @@ export function alwaysOnCost({ host, root, dir, footprint }) {
129
145
  if (name.endsWith('.md')) agents += listedChars(path.join(agentsDir, name), name.slice(0, -3));
130
146
  }
131
147
  }
132
- let context = 0;
133
- try { for (const s of sessionFiles(dir, emittedHost(host))) context += s.text.length; } catch { /* none */ }
148
+ return { skills, agents };
149
+ }
134
150
 
135
- return { carrier, skills, agents, context, ceiling: CARRIER_CEILING[footprint] ?? null };
151
+ /**
152
+ * The carrier cut into its `## ` sections, by index, so the slices add up to the whole file: the
153
+ * text above the first heading is a block of its own. `id` is the heading's slug.
154
+ */
155
+ function rootSections(text) {
156
+ const starts = [0, ...[...text.matchAll(/^## .*$/gm)].map((m) => m.index).filter((i) => i > 0)];
157
+ return starts.map((at, i) => {
158
+ const slice = text.slice(at, starts[i + 1] ?? text.length);
159
+ const head = /^## (.*)/.exec(slice);
160
+ const label = head ? head[1].trim() : 'Preamble';
161
+ const id = `root:${label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'preamble'}`;
162
+ return { id, label, chars: slice.length, source: 'root', loadedBy: 'host' };
163
+ });
164
+ }
165
+
166
+ /**
167
+ * Is the user-rules hook wired for a sub-agent of this install? `'wired'` when the emitted settings
168
+ * run `context` on SubagentStart, `'not-wired'` for an install emitted before (it runs `activity`
169
+ * there: re-emit), `'no-event'` for a host with no SubagentStart wiring at all (OpenCode until its
170
+ * slice lands, and Bob, whose strict schema has no such event).
171
+ */
172
+ export function subagentDelivery(host, dir) {
173
+ if (host !== 'claude' && host !== 'openclaude') return 'no-event';
174
+ return liveRecordedHooks(dir).some(([event, h]) => event === 'SubagentStart' && h.command.includes(' context --'))
175
+ ? 'wired' : 'not-wired';
176
+ }
177
+
178
+ /**
179
+ * WHAT ONE AGENT LOADS, block by block, in load order (spec 2026-11-08, agent loadout, D10–D11):
180
+ * the root file by section, the session files (the primary) or the user rules (a sub-agent), the
181
+ * two catalogues, and an Adept's own spec. THE SAME MEASUREMENTS AS `alwaysOnCost`, through the
182
+ * same helpers, so the console can never claim a load the emit does not produce: the root
183
+ * sections add up to `carrier`, the session block is `context`, the catalogues are `skills` and
184
+ * `agents` (tests/unit/agent_loadout.test.mjs holds the sums equal).
185
+ *
186
+ * `agent` is `'primary'` or an agent file's stem in `<dir>/agents/`; a stem with no file answers
187
+ * null, as does a missing carrier ("not measured"). The user-rules block counts the tier and the
188
+ * install's raw file sizes; the project root's own `user-rules.md` depends on the session's working
189
+ * dir and is listed under `notCounted`, as is everything the host loads that Geneseed did not write.
190
+ * Rules (`rules`) are the console's to add: they come from the install's inventory, not its files.
191
+ */
192
+ export function agentLoadout({ host, root, dir, agent = 'primary' }) {
193
+ const carrierPath = carrierOf(host, root);
194
+ if (!carrierPath) return null;
195
+ const primary = agent === 'primary';
196
+ let spec = null;
197
+ if (!primary) {
198
+ const f = path.join(dir, 'agents', `${agent}.md`);
199
+ if (host === 'bob' || !isFile(f)) return null;
200
+ spec = frontmatter(readText(f))[1];
201
+ }
202
+ /** @type {Array<{ id: string, label: string, chars: number, source: string, loadedBy: string, delivery?: string }>} */
203
+ const blocks = rootSections(readText(carrierPath));
204
+ const session = sessionLayers(dir, host);
205
+ const sum = (list) => list.reduce((n, s) => n + s.text.length, 0);
206
+ const delivery = primary ? null : subagentDelivery(host, dir);
207
+ if (primary) {
208
+ blocks.push({ id: 'session-files', label: 'session files (project context not counted)',
209
+ chars: sum(session), source: 'session', loadedBy: 'session-hook' });
210
+ } else {
211
+ blocks.push({ id: 'user-rules', label: 'user rules', delivery,
212
+ chars: delivery === 'wired' ? sum(session.filter((s) => s.rel === 'user-rules.md')) : 0,
213
+ source: 'user-rules', loadedBy: 'subagent-hook' });
214
+ }
215
+ const { skills, agents } = catalogueChars(host, root, dir);
216
+ blocks.push({ id: 'skills', label: 'skill catalogue', chars: skills, source: 'catalogue', loadedBy: 'host' });
217
+ blocks.push({ id: 'agents', label: 'agent catalogue', chars: agents, source: 'catalogue', loadedBy: 'host' });
218
+ if (spec !== null) blocks.push({ id: 'spec', label: `${agent} spec`, chars: spec.length, source: 'spec', loadedBy: 'host' });
219
+ const notCounted = ['host system prompt and tools', 'files outside Geneseed (other CLAUDE.md content)'];
220
+ if (!primary) notCounted.push("the project root's own user-rules.md (it depends on the working dir)");
221
+ return { agent, host, blocks, notCounted };
136
222
  }
@@ -39,7 +39,7 @@ import {
39
39
  } from '../hosts/installs.mjs';
40
40
  import { validateIsVendored } from '../hosts/native.mjs';
41
41
  import { printOut } from '../lib/fs.mjs';
42
- import { authoringProblems, loopProblems } from './checks-authoring.mjs';
42
+ import { authoringProblems, factoryProblems, loopProblems } from './checks-authoring.mjs';
43
43
  import { gateProbe, guardProbe } from './checks-probe.mjs';
44
44
  import {
45
45
  checkBuild, colorThemeProblems, renderedPathNotes, renderedProblems, themeParityProblems,
@@ -239,6 +239,7 @@ export function doctorCollect({
239
239
  problems = problems.concat(ran('colors', 'Colour themes', colorThemeProblems()));
240
240
  problems = problems.concat(ran('authoring', 'Authoring gates', authoringProblems()));
241
241
  problems = problems.concat(ran('loops', 'Loop catalogue', loopProblems()));
242
+ problems = problems.concat(ran('factories', 'Factory catalogue', factoryProblems()));
242
243
  problems = problems.concat(ran('shim', 'Hook shim', shimProbs));
243
244
  // Windows: a Claude install's hooks emitted for Git Bash on a machine that no longer has it
244
245
  // misbehave under PowerShell — context/learn fail open, and the two gates fail CLOSED
@@ -87,7 +87,7 @@ export const LAW_CLASSES = ['security', 'process', 'verify', 'craft', 'context',
87
87
  export const SKILL_CLASS = {
88
88
  brainstorm: 'design', plan: 'design', council: 'design',
89
89
  workflow: 'design', 'parallel-agents': 'design', pipeline: 'design',
90
- loop: 'design', 'brick-forge': 'design',
90
+ loop: 'design', factory: 'design', 'brick-forge': 'design', 'factory-forge': 'design',
91
91
  'codebase-design': 'design', wayfinder: 'design',
92
92
  develop: 'build', refactor: 'build', debug: 'build', dependencies: 'build',
93
93
  'frontend-design': 'build', prototype: 'build', deck: 'build',
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Where bricks and loop templates come from, and which one wins.
2
+ * Where bricks, loop templates and factories come from, and which one wins.
3
3
  *
4
4
  * THREE ORIGINS, ONE LADDER. Shipped (this package's own `src/`), global (the user's, beside
5
5
  * `installs.json` under XDG) and project (`<repo>/.geneseed/`, committed, shared with a team).
@@ -86,17 +86,16 @@ function availability(brick, srcRoot) {
86
86
  export function loadCatalog({
87
87
  projectRoot = process.cwd(), srcRoot = SRC, globalLevel = true,
88
88
  } = {}) {
89
- const levels = [
90
- ['shipped', path.join(srcRoot, 'bricks'), path.join(srcRoot, 'loops')],
91
- ];
92
- if (globalLevel) {
93
- levels.push(['global', path.join(userLoopsDir(), 'bricks'), path.join(userLoopsDir(), 'loops')]);
94
- }
95
- if (projectRoot) {
96
- levels.push(['project', path.join(projectRoot, '.geneseed', 'bricks'), path.join(projectRoot, '.geneseed', 'loops')]);
97
- }
89
+ const levels = [['shipped', srcRoot]];
90
+ if (globalLevel) levels.push(['global', userLoopsDir()]);
91
+ if (projectRoot) levels.push(['project', path.join(projectRoot, '.geneseed')]);
98
92
  const bricks = new Map(); const templates = new Map(); const problems = []; const overridden = [];
99
- for (const [origin, brickDir, loopDir] of levels) {
93
+ // Factories (`js/factory/`) are a third directory per level, same stem rule. Their parse
94
+ // problems stay apart from `problems`: that list is `catalogProblems`' and so `loop check`'s,
95
+ // and a broken factory file must not fail a loop.
96
+ const factories = new Map(); const factoryProblems = []; const factoryOverridden = [];
97
+ for (const [origin, dir] of levels) {
98
+ const brickDir = path.join(dir, 'bricks'); const loopDir = path.join(dir, 'loops');
100
99
  for (const f of listFiles(brickDir, '.md')) {
101
100
  const { brick, problems: p } = parseBrick(readText(path.join(brickDir, f)), origin);
102
101
  problems.push(...p.map((x) => `bricks/${f} (${origin}): ${x}`));
@@ -117,8 +116,27 @@ export function loadCatalog({
117
116
  }
118
117
  templates.set(stem, { ...graph, origin });
119
118
  }
119
+ // M8: a file that does not load still claims its name at its level: the factory of that name
120
+ // from a lower level is dropped, never run in its place, so `factory init` names the problem.
121
+ const factoryDir = path.join(dir, 'factories');
122
+ for (const f of listFiles(factoryDir, '.json')) {
123
+ const stem = f.slice(0, -'.json'.length);
124
+ const broken = (why) => { factoryProblems.push(`factories/${f} (${origin}): ${why}`); factories.delete(stem); };
125
+ let factory;
126
+ try { factory = JSON.parse(readText(path.join(factoryDir, f))); } catch { broken('not JSON'); continue; }
127
+ if (factory?.name !== stem) { broken(`name ${JSON.stringify(factory?.name)} does not match the file name`); continue; }
128
+ const prior = factories.get(stem);
129
+ if (prior) factoryOverridden.push(`${stem} (${origin}, overrides ${prior.origin})`);
130
+ factories.set(stem, { ...factory, origin });
131
+ }
120
132
  }
121
- return { bricks, templates, problems, overridden: overridden.sort() };
133
+ // The shipped agents, by stem: what a factory's `review.seats` may name (`checkFactory` rule 9),
134
+ // read where `availability` reads a brick's agent, so the two cannot disagree.
135
+ const agents = new Set(listFiles(path.join(srcRoot, 'agents'), '.md').map((f) => f.slice(0, -'.md'.length)));
136
+ return {
137
+ bricks, templates, problems, overridden: overridden.sort(), factories, factoryProblems,
138
+ factoryOverridden: factoryOverridden.sort(), agents,
139
+ };
122
140
  }
123
141
 
124
142
  /** `catalog`: an already-loaded `loadCatalog(opts)`, for a caller that needs the catalogue
package/js/loop/cli.mjs CHANGED
@@ -82,6 +82,29 @@ function resolveGraph(spec, catalog) {
82
82
  return graph;
83
83
  }
84
84
 
85
+ /**
86
+ * A text argument: `--<flag>`, or `--<flag>-file`'s content (`args[key]` / `args[key + 'File']`),
87
+ * null when neither is given. Text too long for a shell argument, or text that holds the word
88
+ * `commit` or `push` (GIT_GATE_RE asks on any line that also holds `git`), goes through a file
89
+ * instead — never through the shell at all. The path is relative to the current directory.
90
+ * CRLF-folded and trimmed the same way the porcelain stdin is, so a Windows-authored file
91
+ * round-trips identically. The one writer of this rule: `geneseed factory`'s `--carry-file` and
92
+ * `--note-file` call it too.
93
+ */
94
+ export function textArg(args, key, flag, action) {
95
+ const fileKey = `${key}File`;
96
+ if (args[key] && args[fileKey]) throw new Error(`${action} takes --${flag} or --${flag}-file, not both`);
97
+ if (!args[fileKey]) return args[key] ?? null;
98
+ let raw;
99
+ try { raw = readText(path.resolve(args[fileKey])); } catch (e) {
100
+ throw new Error(`cannot read --${flag}-file ${args[fileKey]}: ${e.message}`, { cause: e });
101
+ }
102
+ return raw.replace(/\r\n/g, '\n').trimEnd();
103
+ }
104
+
105
+ /** The note of `init` or `record`: `--note` or `--note-file`, '' when neither. */
106
+ const noteOf = (args, action) => textArg(args, 'note', 'note', action) ?? '';
107
+
85
108
  const ACTIONS = {
86
109
  check(args) {
87
110
  // The project level of the catalogue is `<git root>/.geneseed/`, as for `init` and `next`,
@@ -116,18 +139,19 @@ const ACTIONS = {
116
139
  const file = path.join(root, LOOP_FILE);
117
140
  if (isFile(file)) throw new Error(`${file} already exists — a loop is already running here`);
118
141
  if (!args.title || !args.requirement || !args.graph) throw new Error('init needs --title, --requirement and --graph');
142
+ const note = noteOf(args, 'init');
119
143
  const catalog = loadCatalog({ projectRoot: root });
120
144
  const graph = resolveGraph(args.graph, catalog);
121
145
  const problems = checkGraph(graph, catalog.bricks);
122
146
  if (problems.length) return { error: 'the graph does not pass loop check', problems };
123
147
  const state = initState({
124
148
  title: args.title, requirement: args.requirement, graph, preset: args.preset || DEFAULT_PRESET,
125
- contracts: list(args.contracts) ?? [],
149
+ contracts: list(args.contracts) ?? [], notes: note ? [note] : [],
126
150
  });
127
151
  writeLoopFile(file, state);
128
152
  // Best-effort: the registry is how the Active tab discovers this loop, but a registry
129
153
  // hiccup must never fail the init the loop itself just succeeded at.
130
- recordLoop({ root, branch: currentBranch(root), title: args.title });
154
+ recordLoop({ root, branch: currentBranch(root), title: args.title, factory: args.factory ?? null });
131
155
  return { file, graph: graph.name, preset: state.preset, status: state.status };
132
156
  },
133
157
  next: () => withState((s, b) => nextStep(s, b), { write: false }),
@@ -146,19 +170,7 @@ const ACTIONS = {
146
170
  },
147
171
  record(args) {
148
172
  if (!args.outcome) throw new Error('record needs --outcome');
149
- if (args.note && args.noteFile) throw new Error('record takes --note or --note-file, not both');
150
- let note = args.note ?? '';
151
- if (args.noteFile) {
152
- // A note too long for a shell argument, or one that mentions `git … commit`/`push` (and
153
- // would otherwise sit inside the command line GIT_GATE_RE matches whole), goes through a
154
- // file instead — never through the shell at all. CRLF-folded and trimmed the same way the
155
- // porcelain stdin below is, so a Windows-authored file round-trips identically.
156
- let raw;
157
- try { raw = readText(path.resolve(args.noteFile)); } catch (e) {
158
- throw new Error(`cannot read --note-file ${args.noteFile}: ${e.message}`, { cause: e });
159
- }
160
- note = raw.replace(/\r\n/g, '\n').trimEnd();
161
- }
173
+ const note = noteOf(args, 'record');
162
174
  let card = null;
163
175
  if (args.card) {
164
176
  try { card = JSON.parse(args.card); } catch (e) {
package/js/loop/graph.mjs CHANGED
@@ -53,6 +53,18 @@ function components(nodes, edges) {
53
53
  return out;
54
54
  }
55
55
 
56
+ /**
57
+ * Rule 4 on its own: every cycle (strongly connected component) whose nodes no single declared
58
+ * `loops` entry holds, each as its sorted node names joined by `, `. Exported for the factory
59
+ * graph (`js/factory/graph.mjs`), whose `cycles` follow the same rule; each caller words the
60
+ * problem itself, so a loop's message stays byte-identical.
61
+ */
62
+ export function undeclaredCycles(nodes, edges, loops) {
63
+ return components(nodes, edges)
64
+ .filter((comp) => !loops.some((l) => comp.every((n) => (l.nodes ?? []).includes(n))))
65
+ .map((comp) => comp.join(', '));
66
+ }
67
+
56
68
  export function checkGraph(graph, bricks) {
57
69
  const problems = [];
58
70
  const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
@@ -112,10 +124,7 @@ export function checkGraph(graph, bricks) {
112
124
  const iterations = loops.filter((l) => l.iteration === true).length;
113
125
  if (iterations !== 1) problems.push(`${iterations} loops are marked iteration; exactly one must be`);
114
126
  // rule 4 — every cycle is inside a declared loop
115
- for (const comp of components(nodes, edges)) {
116
- const covered = loops.some((l) => comp.every((n) => (l.nodes ?? []).includes(n)));
117
- if (!covered) problems.push(`cycle ${comp.join(', ')} has no declared loop around it`);
118
- }
127
+ for (const cycle of undeclaredCycles(nodes, edges, loops)) problems.push(`cycle ${cycle} has no declared loop around it`);
119
128
  // rule 4b — a cycle that never reaches the iteration head needs its own non-iteration loop
120
129
  const iterationLoops = loops.filter((l) => l.iteration === true);
121
130
  if (iterationLoops.length === 1) {