geneseed 5.0.1 → 5.0.4

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 (185) hide show
  1. package/CHANGELOG.md +92 -0
  2. package/README.md +4 -4
  3. package/SHIPPED.md +2 -2
  4. package/adapters/claude-code/README.md +11 -5
  5. package/adapters/openclaude/README.md +3 -1
  6. package/adapters/opencode/HOW-OPENCODE-LOADS.md +3 -0
  7. package/adapters/opencode/plugins/geneseed-context.js +12 -1
  8. package/adapters/opencode/plugins/geneseed-guard.js +594 -73
  9. package/adapters/opencode/plugins/geneseed-learn.js +1 -1
  10. package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
  11. package/adapters/opencode/workflows/_runtime.js +1 -1
  12. package/bin/geneseed-cli.mjs +3 -0
  13. package/bin/geneseed-hook.mjs +31 -9
  14. package/docs/PRD.md +1 -1
  15. package/docs/README.md +4 -1
  16. package/docs/concepts/enforcement-table.md +23 -4
  17. package/docs/concepts/exclusions.md +48 -2
  18. package/docs/concepts/factories.md +151 -0
  19. package/docs/concepts/foreman-mode.md +19 -4
  20. package/docs/concepts/hook-gates.md +1 -1
  21. package/docs/concepts/hooks.md +53 -12
  22. package/docs/concepts/host-matrix.md +5 -3
  23. package/docs/concepts/hosts.md +1 -1
  24. package/docs/concepts/kits.md +18 -0
  25. package/docs/concepts/loop-gates.md +3 -0
  26. package/docs/concepts/loops.md +1 -0
  27. package/docs/concepts/rules.md +1 -1
  28. package/docs/concepts/shared-tier.md +1 -1
  29. package/docs/concepts/skills.md +1 -1
  30. package/docs/extending.md +8 -2
  31. package/docs/guides/autostart.md +29 -3
  32. package/docs/guides/choose-your-setup.md +1 -1
  33. package/docs/guides/migrate.md +1 -1
  34. package/docs/guides/run-a-factory.md +88 -0
  35. package/docs/guides/set-up-ownership.md +1 -0
  36. package/docs/guides/uninstall.md +1 -1
  37. package/docs/reference/factory-actions.md +22 -0
  38. package/docs/reference/loop-actions.md +1 -1
  39. package/docs/reference/plugin-activity.md +1 -1
  40. package/docs/reference/plugin-context.md +1 -1
  41. package/docs/reference/plugin-guard.md +24 -5
  42. package/docs/reference/troubleshoot-doctor.md +2 -2
  43. package/docs/understand/a-day.md +9 -5
  44. package/docs/web-ui.md +101 -17
  45. package/harness.config.json +1 -1
  46. package/js/README.md +21 -3
  47. package/js/build/args.mjs +14 -2
  48. package/js/build/emit-claude.mjs +9 -1
  49. package/js/build/emit-opencode.mjs +2 -1
  50. package/js/build/source.mjs +28 -3
  51. package/js/cli-table.json +287 -3
  52. package/js/factory/cli.mjs +153 -0
  53. package/js/factory/graph.mjs +245 -0
  54. package/js/factory/registry.mjs +71 -0
  55. package/js/factory/state.mjs +429 -0
  56. package/js/hosts/activity.mjs +3 -3
  57. package/js/hosts/geneseed-dir.mjs +2 -2
  58. package/js/hosts/gitref.mjs +21 -0
  59. package/js/hosts/hooks-context.mjs +71 -15
  60. package/js/hosts/hooks-done.mjs +3 -1
  61. package/js/hosts/hooks-learn.mjs +1 -1
  62. package/js/hosts/hooks-prims.mjs +271 -1
  63. package/js/hosts/hooks.mjs +409 -151
  64. package/js/hosts/hosts.mjs +22 -0
  65. package/js/hosts/installs.mjs +9 -5
  66. package/js/hosts/settings.mjs +128 -27
  67. package/js/hosts/shim.mjs +155 -7
  68. package/js/hosts/store-watch.mjs +36 -11
  69. package/js/inspect/checks-authoring.mjs +11 -1
  70. package/js/inspect/cost.mjs +91 -5
  71. package/js/inspect/diff.mjs +2 -1
  72. package/js/inspect/doctor.mjs +2 -1
  73. package/js/inspect/inventory.mjs +2 -1
  74. package/js/inspect/validate.mjs +1 -1
  75. package/js/loop/catalog.mjs +24 -12
  76. package/js/loop/cli.mjs +21 -15
  77. package/js/loop/graph.mjs +13 -4
  78. package/js/loop/registry.mjs +65 -28
  79. package/js/loop/state.mjs +18 -8
  80. package/js/maintain/migrate.mjs +2 -2
  81. package/js/maintain/uninstall.mjs +5 -1
  82. package/js/web/actions.mjs +17 -1
  83. package/js/web/api.mjs +52 -11
  84. package/js/web/catalog.mjs +38 -2
  85. package/js/web/daemon.mjs +136 -6
  86. package/js/web/handler.mjs +14 -5
  87. package/js/web/routes.mjs +12 -4
  88. package/js/web/server.mjs +4 -1
  89. package/package.json +1 -1
  90. package/registry.json +35 -0
  91. package/src/AGENT.md.tmpl +18 -24
  92. package/src/agents/_self-improvement.md +7 -6
  93. package/src/agents/developer.md +3 -2
  94. package/src/agents/docker-expert.md +1 -0
  95. package/src/agents/memory-curator.md +3 -2
  96. package/src/bricks/docs-update.md +5 -0
  97. package/src/bricks/holdout-write.md +23 -0
  98. package/src/bricks/holdout.md +25 -0
  99. package/src/bricks/intake.md +18 -0
  100. package/src/bricks/merge-gate.md +22 -0
  101. package/src/bricks/pr-open.md +21 -0
  102. package/src/bricks/retro.md +17 -0
  103. package/src/bricks/test.md +4 -1
  104. package/src/bricks/triage.md +19 -0
  105. package/src/doctrines/comms.md +29 -41
  106. package/src/doctrines/craft.md +3 -10
  107. package/src/doctrines/ops.md +4 -15
  108. package/src/doctrines/process.md +24 -19
  109. package/src/doctrines/rigor.md +1 -5
  110. package/src/factories/analysis-to-build.json +34 -0
  111. package/src/factories/bug-report-to-fix.json +32 -0
  112. package/src/factories/issue-to-pr.json +49 -0
  113. package/src/kits/ci-pipelines/rules.md +10 -0
  114. package/src/kits/ci-pipelines.json +14 -0
  115. package/src/kits/docker/rules.md +11 -0
  116. package/src/kits/docker.json +12 -0
  117. package/src/memory/README.md +5 -4
  118. package/src/modes/foreman.md +23 -10
  119. package/src/notebook/README.md +1 -1
  120. package/src/skills/_checkpoints.md +1 -0
  121. package/src/skills/_self-improvement.md +12 -9
  122. package/src/skills/adhd.md +1 -1
  123. package/src/skills/compose-ops.md +58 -0
  124. package/src/skills/factory-forge.md +97 -0
  125. package/src/skills/factory.md +126 -0
  126. package/src/skills/gitlab-ci.md +51 -0
  127. package/src/skills/jenkins-pipeline.md +56 -0
  128. package/src/skills/parallel-agents.md +1 -1
  129. package/src/skills/pipeline.md +2 -2
  130. package/src/skills/rule.md +24 -18
  131. package/src/skills/skill-forge.md +24 -6
  132. package/src/skills/workflow.md +2 -1
  133. package/themes/_TEMPLATE.json +9 -4
  134. package/themes/biker.json +9 -4
  135. package/themes/commentator.json +9 -4
  136. package/themes/cyberpunk.json +9 -4
  137. package/themes/gamer.json +9 -4
  138. package/themes/imperial.json +9 -4
  139. package/themes/joker.json +9 -4
  140. package/themes/marvin.json +9 -4
  141. package/themes/mean.json +9 -4
  142. package/themes/military.json +9 -4
  143. package/themes/neutral.json +9 -4
  144. package/themes/pirate.json +9 -4
  145. package/themes/sports.json +9 -4
  146. package/themes/verstappen.json +9 -4
  147. package/themes/wizard.json +9 -4
  148. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
  149. package/web/dist/assets/Activity-BaoxwVFH.js +1 -0
  150. package/web/dist/assets/ActivityDetail-C_bFD0rW.js +1 -0
  151. package/web/dist/assets/{Bonsai-C1iBAt4v.js → Bonsai-B01lLf0m.js} +1 -1
  152. package/web/dist/assets/{CopyButton-DJ3a4N88.js → CopyButton-Bc66KPyA.js} +1 -1
  153. package/web/dist/assets/Dashboard-X7GZzGJp.js +2 -0
  154. package/web/dist/assets/{Docs-Kffdg5uV.js → Docs-LRYVnGLG.js} +3 -3
  155. package/web/dist/assets/Factories-ARenKBiP.js +1 -0
  156. package/web/dist/assets/{GreenhouseView-k56_cBSF.js → GreenhouseView-CfWR2-sX.js} +1 -1
  157. package/web/dist/assets/{Installs-DtEKLC9h.js → Installs-nfFHnovH.js} +3 -3
  158. package/web/dist/assets/{JournalView-RQnk5l7I.js → JournalView-lpOHcHKK.js} +1 -1
  159. package/web/dist/assets/Kits-Bw5EQl_i.js +1 -0
  160. package/web/dist/assets/Laws-CnZJ0wjZ.js +4 -0
  161. package/web/dist/assets/LibRows-Hqvf1beK.js +1 -0
  162. package/web/dist/assets/Library-JaSsp6Yr.js +3 -0
  163. package/web/dist/assets/Loops-ZaHC5MVl.js +2 -0
  164. package/web/dist/assets/{OperatorHudView-CM5jNPwL.js → OperatorHudView-CggG0_sK.js} +1 -1
  165. package/web/dist/assets/Personal-BObvlb70.js +2 -0
  166. package/web/dist/assets/Settings-BFfPMPc9.js +1 -0
  167. package/web/dist/assets/Tabs-B594Pad_.js +1 -0
  168. package/web/dist/assets/api-DLDVY3K-.js +1 -0
  169. package/web/dist/assets/index-DsLmKHw0.js +6 -0
  170. package/web/dist/assets/index-DvPjphz0.css +1 -0
  171. package/web/dist/index.html +3 -3
  172. package/web/dist/assets/Activity-Ci4PZco3.js +0 -1
  173. package/web/dist/assets/ActivityDetail-C8hroCND.js +0 -1
  174. package/web/dist/assets/Dashboard-C_On4KXw.js +0 -2
  175. package/web/dist/assets/Kits-CXkEBpnf.js +0 -1
  176. package/web/dist/assets/Laws-DhhIVqmh.js +0 -3
  177. package/web/dist/assets/Library-CAUiEoJo.js +0 -3
  178. package/web/dist/assets/Loops-LKD8mF4E.js +0 -2
  179. package/web/dist/assets/Personal-B6Uoly3C.js +0 -2
  180. package/web/dist/assets/RailCats-DQxxYBEP.js +0 -1
  181. package/web/dist/assets/Settings-BTe6-wda.js +0 -1
  182. package/web/dist/assets/Tabs-CbdDWTp_.js +0 -1
  183. package/web/dist/assets/api-D_r0Jtla.js +0 -1
  184. package/web/dist/assets/index-HfGmYXab.js +0 -3
  185. package/web/dist/assets/index-ao3M-Fhm.css +0 -1
@@ -12,7 +12,7 @@ import { LEGACY_WIKI_SEED, WIKI_NAMES, sharedPaths } from '../lib/machine-dir.mj
12
12
  import { normcase, toPlatformPath } from '../lib/paths.mjs';
13
13
  import { relPosix } from '../lib/text.mjs';
14
14
  import {
15
- SHARED_TIER_RE, carriersFor, globalHookStandingDown, hookProjectDir, isGlobalInstall, resolvePath, sovereignBypass,
15
+ SHARED_TIER_RE, carriersFor, gateCarrierText, globalHookStandingDown, hookProjectDir, isGlobalInstall, resolvePath, sovereignBypass,
16
16
  } from './hosts.mjs';
17
17
  import { isFile, isDir, sortPaths, listDir } from './hooks-prims.mjs';
18
18
  import { gitRootOf } from './gitref.mjs';
@@ -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
@@ -658,15 +658,16 @@ function fitLines(lines, room, tailOf) {
658
658
  * a project install keeps it in the repo, one level above the harness dir. The first candidate
659
659
  * that exists answers, as `firstCarrier` does.
660
660
  */
661
- function installCarrier(hookRoot, host) {
661
+ function installCarrierFile(hookRoot, host) {
662
662
  const base = readsTier(hookRoot, host) ? hookRoot : path.dirname(hookRoot);
663
663
  // Last, a plain bundle or git-clone harness dir keeps its AGENT.md in the dir itself.
664
664
  const found = [...carriersFor(host || 'claude').map((rel) => path.join(base, rel)), path.join(hookRoot, 'AGENT.md')];
665
665
  for (const file of found) {
666
- try { return readFileSync(file, 'utf8'); } catch { /* next candidate */ }
666
+ try { return [file, readFileSync(file, 'utf8')]; } catch { /* next candidate */ }
667
667
  }
668
- return '';
668
+ return ['', ''];
669
669
  }
670
+ const installCarrier = (hookRoot, host) => installCarrierFile(hookRoot, host)[1];
670
671
 
671
672
  /**
672
673
  * The payload, what it spent against `OUTPUT_BUDGET`, and whether the budget `cut` content from it:
@@ -675,7 +676,12 @@ function installCarrier(hookRoot, host) {
675
676
  * instead of injected; a lazy listing shortened is not, since it only names files. `heads` are the
676
677
  * lines above the session block; `root` places `eager` and `lazy`. Reads, never prints.
677
678
  */
678
- 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 }) {
679
685
  const lines = [];
680
686
  // `spent` counts every character pushed, headers included: the budget is the host's cap on
681
687
  // the whole payload, not on the file bodies alone.
@@ -684,8 +690,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
684
690
  const push = (...ls) => { for (const l of ls) { lines.push(l); spent += cost(l); } };
685
691
  if (heads.length) push(...heads, '');
686
692
  if (session.length) {
687
- push('=== SESSION FILES \u2014 your harness files, injected at session start '
688
- + '(untouched seeds skipped) ===', '');
693
+ push(title, '');
689
694
  // Rules answer only to their own size: the lines above them never push one out, so they are
690
695
  // capped when their layers together pass the share, and everything after them spends `spent`.
691
696
  let rulesSpent = 0;
@@ -693,7 +698,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
693
698
  for (const s of session) {
694
699
  const head = `----- ${s.rel}${s.label ? ` (${s.label})` : ''} -----`;
695
700
  const rules = s.rel === 'user-rules.md';
696
- const room = OUTPUT_BUDGET - LAZY_RESERVE - (rules ? rulesSpent : spent) - cost(head) - cost('');
701
+ const room = budget - LAZY_RESERVE - (rules ? rulesSpent : spent) - cost(head) - cost('');
697
702
  const where = `${s.abs} on demand`;
698
703
  if (room <= 0) {
699
704
  left.push({ rel: s.rel, line: `[context] ${s.rel} not injected (session budget) \u2014 read ${where}` });
@@ -707,7 +712,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
707
712
  // Paths have no length limit, so these lines answer to the budget like any listing.
708
713
  if (left.length) {
709
714
  cut = true;
710
- const room = OUTPUT_BUDGET - LIST_RESERVE - spent - cost('');
715
+ const room = budget - LIST_RESERVE - spent - cost('');
711
716
  const tail = (n) => `[context] ${n} more session files not injected (session budget)`;
712
717
  // The memory map first, and by its short name when its path cannot fit: a count line must
713
718
  // never replace the one file C12 owes a line that names it.
@@ -738,7 +743,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
738
743
  push(head, `[context] MISSING eager file: ${asOsError(e, target)}`, '');
739
744
  continue;
740
745
  }
741
- if (spent + cost(head) + cost(text) + cost('') > OUTPUT_BUDGET - LAZY_RESERVE) {
746
+ if (spent + cost(head) + cost(text) + cost('') > budget - LAZY_RESERVE) {
742
747
  demoted.push({ ...entry, over: true });
743
748
  continue;
744
749
  }
@@ -748,7 +753,7 @@ function renderPayload({ heads, session, eager, lazy, source, root }) {
748
753
  if (lazy.length || demoted.length) {
749
754
  const title = '--- Lazy entries (load only when the task needs them) ---';
750
755
  push(title);
751
- push(...lazyLines([...lazy, ...demoted], root, OUTPUT_BUDGET - spent - cost('')), '');
756
+ push(...lazyLines([...lazy, ...demoted], root, budget - spent - cost('')), '');
752
757
  }
753
758
  return { text: `${lines.join('\n')}\n`, spent, cut: cut || demoted.length > 0 };
754
759
  }
@@ -768,6 +773,51 @@ export function sessionStartSize(hookRoot, host) {
768
773
  return { chars: spent, budget: OUTPUT_BUDGET, cut };
769
774
  }
770
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
+
771
821
  export function cmdContext(args) {
772
822
  const host = (args && args.host) || null;
773
823
  // Discovery (and the stand-down) runs against the SESSION's project root, not the harness
@@ -792,7 +842,12 @@ export function cmdContext(args) {
792
842
  // The RAW `args.host`, never defaulted to claude, which would key an older
793
843
  // OpenClaude emit's `~/.openclaude` (no `--host`) on `.claude` instead of its folder name.
794
844
  if (globalHookStandingDown(hookRoot, root, args.host, 'context')) return 0;
795
- const carrier = hookRoot ? installCarrier(hookRoot, host) : '';
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
+ }
850
+ const [carrierFile, carrier] = hookRoot ? installCarrierFile(hookRoot, host) : ['', ''];
796
851
  const session = hookRoot ? sessionFiles(hookRoot, host, carrier) : [];
797
852
  // A session file discovery would also pick up (a `user-rules.md` at the repo root of an
798
853
  // install whose harness dir IS the repo root) is injected once, in the session block.
@@ -807,7 +862,8 @@ export function cmdContext(args) {
807
862
  // `--no-done-gate` carries `Done gate: off` in its AGENT.md and gets no line — the OpenCode
808
863
  // context plugin's `doneGateOff` reads the same marker with the same pattern.
809
864
  const gitRoot = gitRootOf(root);
810
- const gateOff = (marker) => new RegExp(`^${marker}:[ \\t]*off[ \\t]*\\r?$`, 'm').test(carrier);
865
+ const gateOff = (marker) => new RegExp(`^${marker}:[ \\t]*off[ \\t]*\\r?$`, 'm')
866
+ .test(gateCarrierText(carrierFile, carrier));
811
867
  // Bob's Stop carries no transcript, so the gate never judges a turn there (`hooks-done.mjs`).
812
868
  const done = gitRoot && !gateOff('Done gate') ? doneLine(gitRoot, host !== 'bob') : null;
813
869
  // The ownership decline reminder (`./ownership-gate.mjs`), under the same contract: an install
@@ -269,7 +269,9 @@ export function doneGate(meta, args, install, read = tailReader()) {
269
269
  if (checks.length) err('[done-gate] transcript unreadable — turn not judged.\n');
270
270
  return null;
271
271
  }
272
- const { missing, weakened } = verdict;
272
+ const { missing } = verdict;
273
+ // `--no-test-note`: the line goes, the done checks do not.
274
+ const weakened = args.noTestNote ? [] : verdict.weakened;
273
275
  // One JSON document on stdout, whatever the advisories: Stop reads no second one.
274
276
  const advise = (...said) => {
275
277
  if (weakened.length) {
@@ -357,7 +357,7 @@ export function cmdLearn(args) {
357
357
  if (hookEvent === 'Stop' && !args.file && install) {
358
358
  const said = storeReport(install, meta.session_id, {
359
359
  transcript: typeof meta.transcript_path === 'string' ? meta.transcript_path : null,
360
- cwd: meta.cwd, host: args.host || 'claude',
360
+ cwd: meta.cwd, host: args.host || 'claude', ruleStore: !args.noRuleStore,
361
361
  });
362
362
  if (said && (verdict === 'advisory' || args.host === 'bob')) err(`[geneseed] ${said}\n`);
363
363
  else if (said) out(`${JSON.stringify({ systemMessage: said })}\n`);
@@ -204,6 +204,276 @@ export function editPairs(ti, whole = '') {
204
204
  return pairs;
205
205
  }
206
206
 
207
+ // ---- gate text twin: BEGIN — adapters/opencode/plugins/geneseed-guard.js carries everything down to
208
+ // the END marker verbatim, with `export ` dropped (tests/plugins/guard.test.mjs diffs the two).
209
+
210
+ /**
211
+ * What each protected check is, for a person who has not read the diff: the files, what they are,
212
+ * what an edit can do. Fixed text, so the governed agent cannot write its own case. A file is written
213
+ * as `CANDIDATES` (`./geneseed-dir.mjs`) writes it, so tests/unit/gate_text.test.mjs compares the
214
+ * two entry by entry, both ways: a string ending `/` is a folder, any other string a file, a regex
215
+ * a file name.
216
+ * @type {[(string | RegExp)[], string, string][]}
217
+ */
218
+ export const GATE_FILES = [
219
+ [['.github/workflows/', '.gitlab-ci.yml', 'Jenkinsfile', 'azure-pipelines.yml', '.circleci/'],
220
+ 'which defines the checks that run on every push',
221
+ 'those checks can get weaker or stop running, and a failure could go unseen'],
222
+ [[/^eslint\.config\./, /^\.eslintrc/, 'biome.json', 'biome.jsonc', 'ruff.toml', '.golangci.yml', 'checkstyle.xml'],
223
+ 'which sets the rules the linter enforces',
224
+ 'those rules can get weaker, and bad code could pass unseen'],
225
+ [['tsconfig.json'],
226
+ 'which sets how strictly types are checked',
227
+ 'the type checks can get weaker, and a type error could pass unseen'],
228
+ [[/^jest\.config\./, /^vitest\.config\./, 'pytest.ini'],
229
+ 'which decides how the tests run',
230
+ 'tests can be skipped or loosened, and a failure could go unseen'],
231
+ [['package.json', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'pyproject.toml', 'Cargo.toml', 'go.mod'],
232
+ 'which names the commands that test this project',
233
+ 'those commands can change, and a failing test could read as a pass'],
234
+ ];
235
+ /**
236
+ * Protected by being the lists themselves, so they are in no seed and stay outside `GATE_FILES`. Read
237
+ * at the repo root only: a `packages/a/.geneseed/done-checks.txt` someone listed feeds no gate.
238
+ * @type {[string, string, string][]}
239
+ */
240
+ const GATE_LISTS = [
241
+ ['.geneseed/protected-checks.txt', 'which lists the files this gate protects',
242
+ 'a check can lose its protection, and nothing would tell you'],
243
+ ['.geneseed/done-checks.txt', 'which lists the checks that must pass before work counts as done',
244
+ 'work could count as done without passing a check'],
245
+ ];
246
+ // Matches at any depth: a user may list `packages/a/tsconfig.json`, and it is still a tsconfig.
247
+ const gateIs = (rel, file) => {
248
+ if (typeof file !== 'string') return file.test(rel.slice(rel.lastIndexOf('/') + 1));
249
+ return file.endsWith('/') ? `/${rel}`.includes(`/${file}`) : `/${rel}`.endsWith(`/${file}`);
250
+ };
251
+ const GATE_FILE_OTHER = [null, 'which this project lists as a protected check',
252
+ 'that check can get weaker or stop running, and a failure could go unseen'];
253
+
254
+ // `ruleGateTarget`'s answers: name, what it is, what the safe line calls it, whose call it is, impact.
255
+ // Memory has none: it is written freely (owner decision, 2026-11-08).
256
+ const GATE_RULE = ['this rule', 'what becomes a rule'];
257
+ const GATE_STORES = {
258
+ 'user-rules.md': ['user-rules.md', 'your standing rules, which the agent obeys in every session', ...GATE_RULE,
259
+ 'the text binds every later session until you remove it'],
260
+ 'the rule draft': ['the rule draft', 'which can become one of your standing rules', ...GATE_RULE,
261
+ 'the text can become a rule that binds every later session'],
262
+ 'a hard link': ['a second name of a rule file', 'which writes to your standing rules or the rule draft', ...GATE_RULE,
263
+ 'the text can bind every later session until you remove it'],
264
+ };
265
+
266
+ // Bidi and zero-width marks too (`\p{C}`): they make a name read as something it is not. A double
267
+ // quote of any shape turns to `'`, or a name could seem to close its own quotes.
268
+ const gateStrip = (v) => String(v ?? '').replace(/[\p{C}\p{Zl}\p{Zp}]/gu, '').replace(/["\u201C-\u201F\uFF02]/g, "'").trim();
269
+
270
+ /**
271
+ * An agent-supplied value in the human part. Clipped in the middle, because the end of a path names
272
+ * the file. Quotes mark a name; they do not stop one reading like a sentence. `...` is ASCII so that
273
+ * clipping alone does not force the quotes.
274
+ */
275
+ export function gateName(value) {
276
+ const c = [...gateStrip(value)];
277
+ const text = c.length > 60 ? `${c.slice(0, 20).join('')}...${c.slice(-37).join('')}` : c.join('');
278
+ return /^[A-Za-z0-9._/-]+$/.test(text) ? text : `"${text}"`;
279
+ }
280
+
281
+ const gatePath = (p) => String(p ?? '').replace(/\\/g, '/');
282
+ // Every line end a viewer may honour: a line break that this missed would hide a line from the count.
283
+ const gateLines = (text) => {
284
+ const lines = text.split(/\r\n|[\r\n\u2028\u2029]/);
285
+ if (lines[lines.length - 1] === '') lines.pop();
286
+ return lines;
287
+ };
288
+
289
+ /**
290
+ * ` (+3 lines, -1 line)` from `editPairs`, or nothing when no line differs. Each pair loses its common
291
+ * leading and trailing lines. Exact for one changed region; with several it overstates, and it
292
+ * never hides a change. A pair says nothing of how often it applies, so a caller whose input has
293
+ * `replace_all`, at the top or in an `edits` entry, passes no pairs and no count shows: the agent sets
294
+ * that flag, and a 40-place edit must not read as `+1 line, -1 line`.
295
+ */
296
+ export function gateCount(pairs) {
297
+ let added = 0;
298
+ let removed = 0;
299
+ for (const [before, after] of pairs) {
300
+ const a = gateLines(before);
301
+ const b = gateLines(after);
302
+ const most = Math.min(a.length, b.length);
303
+ let head = 0;
304
+ while (head < most && a[head] === b[head]) head += 1;
305
+ let tail = 0;
306
+ while (tail < most - head && a[a.length - 1 - tail] === b[b.length - 1 - tail]) tail += 1;
307
+ removed += a.length - head - tail;
308
+ added += b.length - head - tail;
309
+ }
310
+ const n = (sign, v) => `${sign}${v} line${v === 1 ? '' : 's'}`;
311
+ const parts = [...(added ? [n('+', added)] : []), ...(removed ? [n('-', removed)] : [])];
312
+ return parts.length ? ` (${parts.join(', ')})` : '';
313
+ }
314
+
315
+ const gateEdit = (f, shown, what) => `${f.shell ? 'This command writes to' : 'This edit changes'} ${shown}`
316
+ + `${f.pairs ? gateCount(f.pairs) : ''}, ${what}.`;
317
+
318
+ const GATE_ELSEWHERE = 'This command runs on another repository, through --git-dir or --work-tree, which the gate did not read.';
319
+ const GATE_DO_IT = 'You can make this change yourself, outside the agent.';
320
+ const GATE_RUN_IT = 'You can run this command yourself, outside the agent.';
321
+ const GATE_EXTERNAL = { rule: 'External Gate', safe: 'Deny, unless you asked for this change.',
322
+ tail: 'do not write this file another way', can: GATE_DO_IT };
323
+ const GATE_LOSS = { rule: 'Deletion Is Deliberate', quote: true, can: GATE_RUN_IT };
324
+
325
+ // `quote` marks the only asks that may carry the agent's words. External Gate, Sealed Secrets and
326
+ // Persist Insight never do: there the agent's opinion is the conflict of interest.
327
+ const GATE_ASKS = {
328
+ check: (f) => {
329
+ const rel = gatePath(f.name);
330
+ const [, what, impact] = GATE_LISTS.find(([list]) => list === rel)
331
+ ?? GATE_FILES.find(([files]) => files.some((n) => gateIs(rel, n))) ?? GATE_FILE_OTHER;
332
+ return { ...GATE_EXTERNAL, line: gateEdit(f, gateName(rel), what), impact,
333
+ why: 'the agent\'s own work is judged by this file' };
334
+ },
335
+ config: (f) => ({ ...GATE_EXTERNAL, line: gateEdit(f, gateName(gatePath(f.name)), 'which controls the gates that watch the agent'),
336
+ why: 'a gate the agent can edit is a gate it can switch off',
337
+ impact: 'a gate can stop working, and nothing would tell you' }),
338
+ store: (f) => {
339
+ const [name, what, label, owner, impact] = GATE_STORES[f.name] ?? GATE_STORES['user-rules.md'];
340
+ return { rule: 'Persist Insight', line: gateEdit(f, name, what), safe: `Deny, unless you asked for ${label}.`,
341
+ why: `${owner} is your decision`, impact, tail: 'ask the user; do not write it another way', can: GATE_DO_IT };
342
+ },
343
+ secret: (f) => ({ rule: 'Sealed Secrets', line: `This edit puts a credential-shaped string in ${gateName(gatePath(f.name))}.`,
344
+ safe: 'Deny, then keep the value in .env or a secret manager.',
345
+ why: 'a secret in a tracked file reaches everyone who can read the repository',
346
+ impact: 'the secret can land in a commit, and then it must be rotated',
347
+ tail: 'keep the value in .env; do not write it another way',
348
+ can: 'You can put the value in .env or a secret manager yourself.' }),
349
+ 'force-push': (f) => ({ ...GATE_LOSS, line: `This command force-pushes the protected branch ${gateName(f.name)} on the remote.`,
350
+ safe: 'Deny, then push without --force.', why: 'a force push replaces the remote history',
351
+ impact: 'commits that exist only on the remote can be lost for everyone',
352
+ can: 'You can push without --force, or run this command yourself.' }),
353
+ 'branch-delete': (f) => ({ ...GATE_LOSS, line: `This command deletes the protected branch ${gateName(f.name)}.`,
354
+ safe: 'Deny, unless you mean to remove this branch.', why: 'the project depends on a protected branch',
355
+ impact: 'commits that only this branch holds can be lost for everyone' }),
356
+ 'remote-branches': () => ({ ...GATE_LOSS, line: 'This command rewrites or deletes many remote branches, protected ones included.',
357
+ safe: 'Deny, then push one named branch.', why: 'it makes the remote match this repository, branch by branch',
358
+ impact: 'branches and commits that exist only on the remote can be lost for everyone' }),
359
+ 'discard-work': () => ({ ...GATE_LOSS, line: 'This command discards uncommitted changes that git cannot bring back.',
360
+ safe: 'Deny, then commit or stash the work first.', why: 'uncommitted work exists nowhere else',
361
+ impact: 'those changes are gone for good' }),
362
+ 'lose-commits': () => ({ ...GATE_LOSS, line: 'This command drops commits that no remote and no other branch holds.',
363
+ safe: 'Deny, then keep them on a branch first.', why: 'those commits exist only here',
364
+ impact: 'only the reflog can bring them back, and only for a while' }),
365
+ // Git's safety net itself, so `lose-commits`' reflog line would be false here.
366
+ 'drop-recovery': () => ({ ...GATE_LOSS, line: 'This command deletes the history git uses to recover lost commits.',
367
+ safe: 'Deny, unless you mean to give up that recovery.', why: 'it is the last copy of work lost earlier',
368
+ impact: 'commits lost earlier can never come back' }),
369
+ 'delete-files': () => ({ ...GATE_LOSS, line: 'This command deletes files that git cannot restore.',
370
+ safe: 'Deny, unless you know these files can go.', why: 'git holds no copy of them',
371
+ impact: 'those files are gone for good' }),
372
+ unverified: () => ({ ...GATE_LOSS, line: 'This command may lose data, and the gate could not work out what it removes.',
373
+ safe: 'Deny, unless you have checked the command yourself.', why: 'the gate cannot read what this command touches',
374
+ impact: 'data that nothing else holds could be lost' }),
375
+ catastrophic: (f) => ({ ...GATE_LOSS,
376
+ line: `This command, ${gateName(f.name)}, would destroy a filesystem root, a drive, the home directory or a whole disk.`,
377
+ safe: 'Deny.', why: 'nothing could restore what it removes', impact: 'everything under that path is gone for good',
378
+ can: 'You can check what this command was meant to remove.' }),
379
+ 'root-scan': (f) => ({ rule: 'Commands Must Return', quote: true, line: `This command, ${gateName(f.name)}, scans a whole filesystem root.`,
380
+ safe: 'Deny, then search a specific directory.', why: 'a whole root spans every drive',
381
+ impact: 'the scan can run for hours', tail: 'search one named directory',
382
+ can: 'You can name the directory to search.' }),
383
+ // Routine and frequent, so one line: three more would train the user to stop reading all of them.
384
+ commit: () => ({ rule: 'Consent Before Push', quote: true, short: true,
385
+ line: 'This command commits or pushes with git, which needs your approval each time.',
386
+ why: 'every commit and push is your decision', can: GATE_RUN_IT }),
387
+ // The next four are the OpenCode guard's alone: no hook reads a key path, a stream, a wiki manifest
388
+ // or an unknown tool's arguments, and the guard only refuses them. `wiki` has no rule to name.
389
+ 'secret-file': (f) => ({ rule: 'Sealed Secrets', line: `This edit writes to ${gateName(gatePath(f.name))}, a file that holds a secret or key.`,
390
+ safe: 'Deny, then change this file yourself.', why: 'a secret or key file is never for the agent to write',
391
+ impact: 'the agent can replace a key that grants access', tail: 'leave this file alone', can: GATE_DO_IT }),
392
+ stream: (f) => ({ ...GATE_EXTERNAL, line: `This edit names ${gateName(gatePath(f.name))}, an NTFS stream that writes through to the file it hangs on.`,
393
+ safe: 'Deny, then have the agent name the file itself.', why: 'a stream hides which file really changes',
394
+ impact: 'a file can change with no gate seeing its name', tail: 'name the file itself' }),
395
+ wiki: (f) => ({ line: `This edit changes the protected wiki folder ${gateName(f.name)}.`,
396
+ safe: 'Deny, unless you asked for this change.', why: 'you marked this folder as closed to the agent',
397
+ impact: 'notes you protected can change', tail: 'leave this folder alone', can: GATE_DO_IT }),
398
+ 'deep-args': (f) => ({ rule: 'Persist Insight', line: `The arguments of ${gateName(f.name)} nest too deep to read, so a write to your rules cannot be ruled out.`,
399
+ safe: 'Deny, unless you know what this call writes.', why: 'what the gate cannot read, it cannot clear',
400
+ impact: 'the call can write to your rules unseen', tail: 'ask the user; do not write it another way', can: GATE_DO_IT }),
401
+ // It reports a crash, not a change, so it has no rule to name.
402
+ 'gate-error': (f) => ({ line: `Geneseed gate error: the check failed with ${gateName(f.name)}, so nothing judged this call.`,
403
+ safe: 'Deny, then run geneseed doctor.', why: 'a gate that crashed cannot say this call is safe',
404
+ impact: 'this call runs with no check at all', can: 'You can run geneseed doctor to find the fault.' }),
405
+ };
406
+
407
+ /**
408
+ * The text a gate shows, one sentence per line, so it reads the same if a host folds the newlines.
409
+ * `mode` is `ask` (a person can answer), `refused` (nothing can be allowed and the model is the only
410
+ * reader, so it must relay the words) or `warned` (the call runs anyway). `facts` is `name` (the path,
411
+ * branch, command excerpt, error or `ruleGateTarget` answer), `pairs` (`editPairs`, for the count),
412
+ * `shell` (reached through a command, which has no count), `says` (the call's own `description`) and
413
+ * `redirected` (`gateLoss`'s: the loss the text names was read from a repository the command leaves).
414
+ * The safe choice is line 2, so it stays in the part of a dialog that shows without scrolling. The
415
+ * caller adds the host's wrapping: Bob's `[geneseed]` prefix and `BOB_FINAL` are not here.
416
+ */
417
+ export function gateText(id, mode, facts = {}) {
418
+ const a = GATE_ASKS[id](facts);
419
+ const tag = a.rule ? ` (${a.rule})` : '';
420
+ // After the safe choice, so that it keeps its place in the part of a dialog that shows.
421
+ const far = facts.redirected ? [GATE_ELSEWHERE] : [];
422
+ if (mode === 'warned') return `${a.line}${tag}\nThis ran without a prompt, because Bob has no approval step.`;
423
+ if (mode === 'refused') {
424
+ return [`Tell the user this, word for word: ${a.line}`, ...far, `It was refused because ${a.why}.${tag}`, a.can,
425
+ ...(a.tail ? [`Agent: ${a.tail}.`] : [])].join('\n');
426
+ }
427
+ const c = [...(a.quote ? gateStrip(facts.says) : '')];
428
+ return [...(a.short ? [`${a.line}${tag}`]
429
+ : [a.line, `Safe choice: ${a.safe}${tag}`, ...far, `It asks because ${a.why}.`, `If you allow it, ${a.impact}.`]),
430
+ ...(c.length ? [`The agent says (not checked): "${c.length > 100 ? `${c.slice(0, 97).join('')}...` : c.join('')}"`] : []),
431
+ ...(a.tail ? [`Agent: if refused, ${a.tail}.`] : [])].join('\n');
432
+ }
433
+
434
+ // Said when `gateText` itself fails. It fits every mode, so nothing about it can fail.
435
+ const GATE_UNSAID = 'Geneseed could not describe this call. Check what it does before you trust it.';
436
+
437
+ /**
438
+ * `gateText` that cannot throw, and the only way a gate reaches it. Every catch around a gate is a
439
+ * pass or a lesser verdict (`guardGate`, a shell reader, the guard's own), so a bug in the words would
440
+ * otherwise change what the gate decides.
441
+ */
442
+ export function gateSafe(id, mode, facts) {
443
+ try { return gateText(id, mode, facts); } catch { return GATE_UNSAID; }
444
+ }
445
+
446
+ // `lossReason`'s sentences, by their fixed parts only: the rest is the agent's command, so a pattern
447
+ // anchored there could be steered. Order matters: `git clean` ends in an agent's path.
448
+ /** @type {[RegExp, string][]} */
449
+ const GATE_LOSS_REASONS = [
450
+ [/^the gate could not verify /, 'unverified'],
451
+ [/^`git push --(?:mirror|prune)` |^a forced `git push --all` /, 'remote-branches'],
452
+ [/^`git push` would force-push the protected branch (.+)$/, 'force-push'],
453
+ [/^`git (?:push|branch -D)\b.* (?:would delete|deletes) the protected branch (.+)$/, 'branch-delete'],
454
+ [/^`git clean` would delete untracked files | which (?:nothing could|git cannot) restore$| deletes git's own data$| deletes a whole repository or worktree$/, 'delete-files'],
455
+ [/ would discard uncommitted changes \(.*\)$| deletes stashed work$/, 'discard-work'],
456
+ [/ recovery depends on$/, 'drop-recovery'],
457
+ [/ holds$/, 'lose-commits'],
458
+ ];
459
+
460
+ /**
461
+ * The `gateText` id, branch and `redirected` flag for a `lossReason` sentence. One this table does not
462
+ * know reads as `unverified`, the most cautious text; tests/unit/gate_text.test.mjs holds every
463
+ * sentence to an id.
464
+ */
465
+ export function gateLoss(reason) {
466
+ const direct = reason.replace(/ \(and --git-dir\/--work-tree points it at a repository the gate did not read\)$/, '');
467
+ const redirected = direct !== reason;
468
+ const text = direct.replace(/ on the protected branch \S*$/, '');
469
+ for (const [re, id] of GATE_LOSS_REASONS) {
470
+ const m = re.exec(text);
471
+ if (m) return { id, name: m[1], redirected };
472
+ }
473
+ return { id: 'unverified', redirected };
474
+ }
475
+ // ---- gate text twin: END
476
+
207
477
  const OFF = ['off', '0', 'false', 'no'];
208
478
 
209
479
  /**
@@ -223,7 +493,7 @@ export function activityOn(root) {
223
493
 
224
494
  /**
225
495
  * The `activity` verb, wired to the events no other verb runs on (UserPromptSubmit; SessionEnd
226
- * 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
227
497
  * `trackActivity` records the payload after every verb alike, this one included.
228
498
  */
229
499
  export const cmdActivity = () => 0;