geneseed 4.31.0 → 5.0.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 (272) hide show
  1. package/CHANGELOG.md +107 -0
  2. package/DESIGN.md +2 -2
  3. package/README.md +6 -5
  4. package/SHIPPED.md +4 -3
  5. package/adapters/bob/README.md +6 -5
  6. package/adapters/claude-code/README.md +4 -3
  7. package/adapters/claude-code/skills/geneseed/SKILL.md +1 -1
  8. package/adapters/openclaude/README.md +4 -3
  9. package/adapters/opencode/GLOBAL-HARNESS-SPEC.md +3 -1
  10. package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -1
  11. package/adapters/opencode/README.md +18 -18
  12. package/adapters/opencode/plugins/geneseed-activity.js +57 -1
  13. package/adapters/opencode/plugins/geneseed-context.js +220 -18
  14. package/adapters/opencode/plugins/geneseed-guard.js +578 -74
  15. package/adapters/opencode/plugins/geneseed-learn.js +97 -23
  16. package/bin/geneseed-cli.mjs +17 -25
  17. package/bin/geneseed-hook.mjs +23 -8
  18. package/docs/DESIGN.md +175 -0
  19. package/docs/PRD.md +111 -0
  20. package/docs/README.md +3 -2
  21. package/docs/architecture.md +145 -0
  22. package/docs/concepts/agents.md +1 -1
  23. package/docs/concepts/collaboration.md +1 -1
  24. package/docs/concepts/enforcement-table.md +1 -1
  25. package/docs/concepts/exclusions.md +6 -6
  26. package/docs/concepts/footprint.md +1 -1
  27. package/docs/concepts/foreman-mode.md +2 -2
  28. package/docs/concepts/hook-gates.md +1 -1
  29. package/docs/concepts/hooks.md +27 -11
  30. package/docs/concepts/host-matrix.md +3 -3
  31. package/docs/concepts/hosts.md +1 -1
  32. package/docs/concepts/kits.md +3 -1
  33. package/docs/concepts/loop-bricks.md +1 -1
  34. package/docs/concepts/loop-notes.md +4 -2
  35. package/docs/concepts/loop-templates.md +7 -4
  36. package/docs/concepts/loops.md +3 -0
  37. package/docs/concepts/ownership.md +2 -2
  38. package/docs/concepts/rules.md +15 -2
  39. package/docs/concepts/shared-tier.md +73 -0
  40. package/docs/concepts/skills.md +2 -2
  41. package/docs/concepts/themes.md +1 -1
  42. package/docs/extending.md +13 -12
  43. package/docs/guides/install-claude-code.md +1 -1
  44. package/docs/guides/install-opencode.md +1 -1
  45. package/docs/guides/migrate.md +4 -2
  46. package/docs/guides/project-context.md +2 -2
  47. package/docs/guides/run-a-loop.md +1 -1
  48. package/docs/guides/set-up-ownership.md +1 -1
  49. package/docs/guides/setup-footprint.md +1 -1
  50. package/docs/guides/uninstall.md +2 -1
  51. package/docs/guides/upgrade-to-5.md +116 -0
  52. package/docs/guides/upgrade.md +21 -9
  53. package/docs/guides/wiki.md +3 -3
  54. package/docs/reference/env-context.md +5 -3
  55. package/docs/reference/environment.md +1 -1
  56. package/docs/reference/glossary.md +2 -0
  57. package/docs/reference/loop-actions.md +1 -1
  58. package/docs/reference/opencode-plugins.md +3 -3
  59. package/docs/reference/plugin-activity.md +1 -1
  60. package/docs/reference/plugin-context.md +5 -0
  61. package/docs/reference/plugin-guard.md +14 -6
  62. package/docs/reference/plugin-learn.md +13 -6
  63. package/docs/reference/troubleshoot-hooks.md +3 -3
  64. package/docs/reference/troubleshoot-update.md +14 -0
  65. package/docs/token-footprint.md +4 -3
  66. package/docs/understand/a-day.md +2 -2
  67. package/docs/understand/design-choices-install.md +2 -1
  68. package/docs/understand/enforced-vs-asked.md +4 -3
  69. package/docs/understand/machine-bob.md +3 -1
  70. package/docs/understand/machine-claude.md +7 -5
  71. package/docs/understand/machine-opencode.md +7 -5
  72. package/docs/understand/on-your-machine.md +4 -0
  73. package/docs/understand/take-it-out.md +1 -1
  74. package/docs/web-ui.md +141 -73
  75. package/harness.config.json +1 -1
  76. package/js/README.md +10 -6
  77. package/js/build/args.mjs +10 -8
  78. package/js/build/bundle.mjs +11 -13
  79. package/js/build/driver.mjs +66 -65
  80. package/js/build/emit-claude.mjs +22 -16
  81. package/js/build/emit-common.mjs +4 -5
  82. package/js/build/emit-opencode.mjs +22 -22
  83. package/js/build/fold.mjs +515 -0
  84. package/js/build/generate.mjs +41 -52
  85. package/js/build/render.mjs +115 -29
  86. package/js/build/source.mjs +4 -1
  87. package/js/build/stubs.mjs +70 -9
  88. package/js/build/version.mjs +10 -10
  89. package/js/cli-table.json +23 -83
  90. package/js/hosts/activity.mjs +2 -2
  91. package/js/hosts/geneseed-dir.mjs +1 -1
  92. package/js/hosts/hooks-context.mjs +410 -99
  93. package/js/hosts/hooks-done.mjs +97 -31
  94. package/js/hosts/hooks-learn.mjs +38 -7
  95. package/js/hosts/hooks-prims.mjs +69 -2
  96. package/js/hosts/hooks.mjs +300 -64
  97. package/js/hosts/hosts.mjs +150 -51
  98. package/js/hosts/installs.mjs +55 -167
  99. package/js/hosts/link.mjs +3 -5
  100. package/js/hosts/mcp.mjs +1 -1
  101. package/js/hosts/memory-files.mjs +219 -17
  102. package/js/hosts/ownership-gate.mjs +1 -1
  103. package/js/hosts/settings.mjs +18 -13
  104. package/js/hosts/shim.mjs +4 -33
  105. package/js/hosts/store-watch.mjs +189 -0
  106. package/js/inspect/checks-authoring.mjs +3 -3
  107. package/js/inspect/checks-build.mjs +45 -18
  108. package/js/inspect/checks-counts.mjs +4 -4
  109. package/js/inspect/checks-repo.mjs +13 -14
  110. package/js/inspect/cost.mjs +24 -2
  111. package/js/inspect/diff.mjs +123 -123
  112. package/js/inspect/doctor.mjs +22 -27
  113. package/js/inspect/excludes.mjs +181 -62
  114. package/js/inspect/inventory.mjs +22 -27
  115. package/js/inspect/registry.mjs +106 -30
  116. package/js/inspect/scan.mjs +5 -5
  117. package/js/inspect/status.mjs +141 -119
  118. package/js/inspect/validate.mjs +22 -24
  119. package/js/lib/fs.mjs +47 -50
  120. package/js/lib/json.mjs +10 -17
  121. package/js/lib/machine-dir.mjs +73 -0
  122. package/js/lib/paths.mjs +22 -33
  123. package/js/lib/proc.mjs +1 -1
  124. package/js/lib/prompt.mjs +19 -27
  125. package/js/lib/text.mjs +8 -12
  126. package/js/lib/udiff.mjs +11 -15
  127. package/js/loop/catalog.mjs +2 -3
  128. package/js/loop/state.mjs +15 -5
  129. package/js/maintain/memory.mjs +17 -17
  130. package/js/maintain/migrate.mjs +79 -89
  131. package/js/maintain/setup.mjs +43 -32
  132. package/js/maintain/uninstall.mjs +43 -61
  133. package/js/maintain/update.mjs +200 -93
  134. package/js/ui/anim.mjs +21 -35
  135. package/js/ui/cli.mjs +36 -58
  136. package/js/ui/menu.mjs +22 -45
  137. package/js/ui/tui.mjs +27 -67
  138. package/js/web/actions.mjs +38 -38
  139. package/js/web/api.mjs +132 -76
  140. package/js/web/catalog.mjs +175 -46
  141. package/js/web/docs.mjs +33 -12
  142. package/js/web/doctor-worker.mjs +14 -0
  143. package/js/web/handler.mjs +14 -5
  144. package/js/web/routes.mjs +17 -19
  145. package/js/web/state.mjs +78 -19
  146. package/js/web/update-check.mjs +25 -10
  147. package/js/web/user-files.mjs +50 -105
  148. package/package.json +7 -4
  149. package/registry.json +48 -55
  150. package/src/AGENT.md.tmpl +13 -14
  151. package/src/agents/_self-improvement.md +1 -1
  152. package/src/agents/_template.md +4 -1
  153. package/src/agents/advocate.md +1 -1
  154. package/src/agents/architect.md +1 -1
  155. package/src/agents/developer.md +6 -3
  156. package/src/agents/devops-engineer.md +1 -1
  157. package/src/agents/docker-expert.md +1 -1
  158. package/src/agents/docs.md +1 -1
  159. package/src/agents/empiricist.md +1 -1
  160. package/src/agents/explorer.md +1 -1
  161. package/src/agents/framer.md +1 -1
  162. package/src/agents/historian.md +1 -1
  163. package/src/agents/kubernetes-specialist.md +1 -1
  164. package/src/agents/memory-curator.md +2 -2
  165. package/src/agents/operator.md +1 -1
  166. package/src/agents/performance.md +1 -1
  167. package/src/agents/pragmatist.md +1 -1
  168. package/src/agents/react-engineer.md +1 -1
  169. package/src/agents/react-reviewer.md +1 -1
  170. package/src/agents/researcher.md +1 -1
  171. package/src/agents/reviewer.md +1 -1
  172. package/src/agents/security.md +1 -1
  173. package/src/agents/skeptic.md +1 -1
  174. package/src/agents/spring-boot-engineer.md +1 -1
  175. package/src/agents/spring-reviewer.md +1 -1
  176. package/src/agents/spring-security.md +1 -1
  177. package/src/agents/steward.md +1 -1
  178. package/src/agents/tester.md +5 -2
  179. package/src/agents/user-advocate.md +1 -1
  180. package/src/agents/visionary.md +1 -1
  181. package/src/bricks/apply.md +3 -0
  182. package/src/bricks/test.md +6 -4
  183. package/src/loops/bugfix.json +11 -5
  184. package/src/loops/feature.json +7 -4
  185. package/src/memory/README.md +1 -1
  186. package/src/skills/_self-improvement.md +2 -2
  187. package/src/skills/daydream/SKILL.md +2 -2
  188. package/src/skills/daydream/instructions.md +1 -1
  189. package/src/skills/geneseed.md +1 -1
  190. package/src/skills/learn-mode.md +1 -2
  191. package/src/skills/loop.md +1 -0
  192. package/src/skills/profile.md +2 -2
  193. package/src/skills/rule/approve.md +69 -0
  194. package/src/skills/rule/consolidate.md +3 -3
  195. package/src/skills/rule.md +13 -5
  196. package/src/skills/ship.md +9 -1
  197. package/src/skills/skill-forge.md +1 -1
  198. package/src/skills/teach.md +29 -12
  199. package/src/skills/wiki.md +1 -1
  200. package/themes/_TEMPLATE.json +1 -2
  201. package/themes/biker.json +1 -2
  202. package/themes/commentator.json +1 -2
  203. package/themes/cyberpunk.json +1 -2
  204. package/themes/gamer.json +1 -2
  205. package/themes/imperial.json +1 -2
  206. package/themes/joker.json +1 -2
  207. package/themes/marvin.json +1 -2
  208. package/themes/mean.json +1 -2
  209. package/themes/military.json +1 -2
  210. package/themes/neutral.json +1 -2
  211. package/themes/pirate.json +1 -2
  212. package/themes/sports.json +1 -2
  213. package/themes/verstappen.json +1 -2
  214. package/themes/wizard.json +1 -2
  215. package/web/dist/assets/Activity-D8G4eClY.js +1 -0
  216. package/web/dist/assets/ActivityDetail-BtOBYk3M.js +1 -0
  217. package/web/dist/assets/AgentGlyph-k6o3gCM1.js +1 -0
  218. package/web/dist/assets/Bonsai-B_y20b3i.js +1 -0
  219. package/web/dist/assets/{CopyButton-IXnXzH4Y.js → CopyButton-CHQte7Ap.js} +1 -1
  220. package/web/dist/assets/Dashboard-B8uXeJZ_.js +2 -0
  221. package/web/dist/assets/{DataTable-BWbUx4bY.js → DataTable-b9zTShqJ.js} +1 -1
  222. package/web/dist/assets/Docs-Dgv_MWfT.js +5 -0
  223. package/web/dist/assets/{EmptyState-1sPNleqv.js → EmptyState-CY5Pm2xy.js} +1 -1
  224. package/web/dist/assets/FilterInput-qGKNSlxv.js +1 -0
  225. package/web/dist/assets/GreenhouseView-CSzTMSl_.js +1 -0
  226. package/web/dist/assets/Installs-BDk9lqBI.js +3 -0
  227. package/web/dist/assets/JournalView-CvRk1-m5.js +1 -0
  228. package/web/dist/assets/Kits-CoITzxWM.js +1 -0
  229. package/web/dist/assets/Laws-Ctf5r9rE.js +3 -0
  230. package/web/dist/assets/Library-DNwHYVXt.js +3 -0
  231. package/web/dist/assets/{Loops-C5u7fQOR.js → Loops-S85PMQ8m.js} +2 -2
  232. package/web/dist/assets/Markdown-0ORz7tAc.js +69 -0
  233. package/web/dist/assets/OperatorHudView-DuGz_sTk.js +1 -0
  234. package/web/dist/assets/Personal-afJNwvRS.js +2 -0
  235. package/web/dist/assets/RailCats-AW92uhsX.js +1 -0
  236. package/web/dist/assets/Settings-CGDFz-6j.js +1 -0
  237. package/web/dist/assets/Tabs-1qLrnqmn.js +1 -0
  238. package/web/dist/assets/api-C46vAuqp.js +1 -0
  239. package/web/dist/assets/controls-D4wmg_pl.js +1 -0
  240. package/web/dist/assets/index-COTd4TRZ.js +3 -0
  241. package/web/dist/assets/index-CtorA7uK.css +1 -0
  242. package/web/dist/assets/motion-RlUl1osO.js +1 -0
  243. package/web/dist/assets/react-C1iE8mnY.js +9 -0
  244. package/web/dist/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  245. package/web/dist/assets/{sections-ChwaobfW.js → sections-CtFz7HFH.js} +1 -1
  246. package/web/dist/assets/{usePoll-bDFN-Hr6.js → usePoll-o8ul-Sog.js} +1 -1
  247. package/web/dist/index.html +7 -7
  248. package/src/skills/quiz.md +0 -44
  249. package/web/dist/assets/Activity-B7cFtS00.js +0 -1
  250. package/web/dist/assets/ActivityDetail-C-GbMmuW.js +0 -1
  251. package/web/dist/assets/Bonsai-_YyexVC5.js +0 -1
  252. package/web/dist/assets/Dashboard-sCfEjowQ.js +0 -2
  253. package/web/dist/assets/Docs-w3Y7M5Ts.js +0 -5
  254. package/web/dist/assets/FilterInput-CZREvrjX.js +0 -1
  255. package/web/dist/assets/GreenhouseView-BWWbMKmg.js +0 -1
  256. package/web/dist/assets/Installs-CnkdJ-VA.js +0 -3
  257. package/web/dist/assets/JournalView-C7bPD3fZ.js +0 -1
  258. package/web/dist/assets/KitApply-CQQbnThf.js +0 -1
  259. package/web/dist/assets/Kits-aj07N7mT.js +0 -1
  260. package/web/dist/assets/Laws-DZ38nl_H.js +0 -3
  261. package/web/dist/assets/Library-QCGXPV5h.js +0 -2
  262. package/web/dist/assets/Markdown-DpmmtW2Y.js +0 -65
  263. package/web/dist/assets/OperatorHudView-Blu1lqiZ.js +0 -1
  264. package/web/dist/assets/Personal-ox_MktWO.js +0 -2
  265. package/web/dist/assets/RailCats-BuJD4Jou.js +0 -1
  266. package/web/dist/assets/Tabs-CIPyMAX-.js +0 -1
  267. package/web/dist/assets/api-BxjLd7Qd.js +0 -1
  268. package/web/dist/assets/index-0GCxkY7m.css +0 -1
  269. package/web/dist/assets/index-CzDi9JpF.js +0 -3
  270. package/web/dist/assets/motion-CXaUMNkg.js +0 -1
  271. package/web/dist/assets/react-DlYQp10C.js +0 -9
  272. package/web/dist/assets/rolldown-runtime-hePW80VL.js +0 -1
@@ -22,7 +22,7 @@
22
22
  <!-- bash: allow -->
23
23
 
24
24
  ## Procedure
25
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
26
26
  1. Confirm the change actually does what the task required (read the spec/issue). Where
27
27
  the spec is silent, judge by what a reasonable user would expect: a crash, hang or data
28
28
  loss on an input the spec implies but never names is blocking, not a nitpick.
@@ -18,7 +18,7 @@
18
18
  <!-- bash: allow -->
19
19
 
20
20
  ## Procedure
21
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
22
22
  1. Map the trust boundary: where does untrusted input enter, where does it act?
23
23
  2. Check for the common classes: injection, broken auth/authz, secret exposure,
24
24
  unsafe deserialization, path traversal, vulnerable dependencies.
@@ -18,7 +18,7 @@
18
18
  - **Read-only.** Search and read, to ground each objection in the real artifact. Never edits, never runs commands, never casts the verdict.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
22
22
  1. Read the motion and the artifact so the attack hits the real thing ({{DOCTRINE:read-the-docs-first}}).
23
23
  2. Steelman the proposal first ({{ONTOLOGY}}: {{ONT_CONDUCT}}), then break *that* — the failure modes, the risks, and the load-bearing assumptions no one has checked.
24
24
  3. Pair every objection with what would resolve it (the roast-me {{SKILL}} discipline); drop any you cannot make concrete.
@@ -22,7 +22,7 @@ Implements Spring Boot 4 / Java 21+ features, following the spring-boot, spring-
22
22
  - Never commits or pushes ({{DOCTRINE:consent-before-push}}).
23
23
 
24
24
  ## Procedure
25
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
26
26
  1. Follow the project's existing layout and build tool; match its group id, packages and CI. Lombok is fine when the project already uses it.
27
27
  2. Constructor injection; records for request and response DTOs; `@Valid` on request bodies; one `@RestControllerAdvice` for errors.
28
28
  3. Services: `@Transactional(readOnly = true)` on the class, `@Transactional` on mutating methods. Never call a transactional or `@Async` method through `this`.
@@ -22,7 +22,7 @@ Spring-specific review only. Generic correctness, naming and structure belong to
22
22
  <!-- bash: allow -->
23
23
 
24
24
  ## Procedure
25
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
26
26
  1. Read the changed files and the build file to learn the Boot version.
27
27
  2. Check, in this order:
28
28
  - Injection: field `@Autowired`, circular dependencies.
@@ -21,7 +21,7 @@ Spring Security 7 audit only. The generic audit (injection, secrets, dependencie
21
21
  <!-- bash: allow -->
22
22
 
23
23
  ## Procedure
24
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
24
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
25
  1. Read the `SecurityFilterChain` beans first, then method-security usage and config files.
26
26
  2. Check:
27
27
  - Filter chain: a bean, never `WebSecurityConfigurerAdapter`; `authorizeHttpRequests` ends in `anyRequest().authenticated()` or `denyAll()`; only health and login endpoints open.
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to judge fit against the real system. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
21
  1. Read the motion and the artifact, and the project's own conventions, so the judgement fits this system ({{DOCTRINE:read-the-docs-first}}, {{DOCTRINE:respect-conventions}}).
22
22
  2. Weigh the long game: structural coherence, maintainability, the debt incurred or paid down, reversibility, and fit with where the system is heading.
23
23
  3. Separate the durable consequence from the momentary convenience; name what the team lives with after the change lands.
@@ -18,7 +18,7 @@
18
18
  - Does not change production code; if a fix is needed, it reports the diagnosis.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
22
22
  1. For new tests: write the test, watch it fail with the behaviour absent or
23
23
  deliberately broken, then confirm it passes against the implementation —
24
24
  a test that has never failed verifies nothing ({{LAW:verify-before-asserting}}).
@@ -30,10 +30,13 @@
30
30
  is not proof.
31
31
 
32
32
  ## Output contract
33
+ - The report starts with one line, `STATUS: OK|BLOCKED|OUT_OF_SCOPE|ERROR`: `OK` the contract is met;
34
+ `BLOCKED` an input or a decision is missing; `OUT_OF_SCOPE` not this task; `ERROR` a step failed,
35
+ red tests included.
33
36
  - The test files written/changed, the command to run them, and the actual run
34
37
  output (pass/fail counts). For diagnosis: root cause + recommended fix location.
35
38
  - If the suite cannot be run or the expected behaviour is unspecified, report
36
- that blocker instead of delivering tests that were never seen to fail.
39
+ that blocker (`STATUS: BLOCKED`) instead of delivering tests that were never seen to fail.
37
40
 
38
41
  ## Pipeline role
39
42
 
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to ground the consumer's view in the real interface. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
21
  1. Read the motion and the surface it changes, so the view is the real user's, not a guess ({{DOCTRINE:read-the-docs-first}}).
22
22
  2. Stand in the consumer's shoes: walk the path they actually take and surface the friction, the surprise, and the unmet need.
23
23
  3. Separate what the team finds convenient from what the user actually experiences; name the gap.
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to ground the vision in what exists. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
21
  1. Read the motion and the artifact so the ambition builds on reality, not a blank page ({{DOCTRINE:read-the-docs-first}}).
22
22
  2. Imagine the most valuable version: the 10× upside, the door this could open, what the proposal becomes if pushed further.
23
23
  3. Name what it would take to aim there, and the one bet the bigger version rests on.
@@ -12,6 +12,9 @@ replaced.
12
12
  When this is a repair after `test`, act on the latest `test` note only — it is the verdict on
13
13
  the code as it stands. Fix every finding it lists in this one pass: repairs are capped at two.
14
14
 
15
+ When this is a repair after `mutation-check`, act on its latest note: add each assertion that
16
+ kills a survivor to a test in the `writeSet`. Production code stays as it is.
17
+
15
18
  Make no unrelated edits: no drive-by rename, no incidental cleanup, no touching a file the card
16
19
  did not declare. If the change genuinely needs a file outside the write set, stop and report that
17
20
  rather than widening scope unasked — the diff is scored against the declared set, not your
@@ -14,10 +14,12 @@ brick only observes; a fix belongs in `apply`, not here.
14
14
  failure: they check independent properties, and each repair must see every finding at once.
15
15
  3. **Full suite** — only when everything above passed; otherwise `SKIPPED (an earlier check failed)`.
16
16
 
17
- List every check with `PASS`, `FAIL`, `ERROR` or `SKIPPED (reason)` — one that did not run is
18
- never left out, and silence is never a pass. Write each failure as four lines: the check's
19
- purpose, the property it guards, a one-line diagnostic (not the raw log), and the command that
20
- reruns it alone. Keep full logs in a file, and write the list to the note file.
17
+ List every check on its own line as `<check>: <status>`, the status one of `PASS`, `FAIL`, `ERROR`
18
+ or `SKIPPED (reason)` — one that did not run is never left out, and silence is never a pass.
19
+ Write each failure as four lines: the check's purpose, the property it guards, a one-line
20
+ diagnostic (not the raw log), and the command that reruns it alone. Keep full logs in a file.
21
+ Write the list to a file in the OS temp directory (never inside the worktree) and report that
22
+ file's path with every outcome, `pass` included: the engine reads the list from it.
21
23
 
22
24
  Report `pass` only if every check passed. Report `error` if a check crashed or could not be run —
23
25
  no test runner, a missing tool, evidence never wired: that is a stop for a human, not a repair.
@@ -1,8 +1,11 @@
1
1
  {
2
2
  "name": "bugfix",
3
- "description": "Reproduce the bug with a failing test, then iterate: apply the fix, test, and review, until the requirement is met and the reproduction passes.",
3
+ "description": "Reproduce the bug with a failing test, then iterate: apply the fix, test, prove the tests bite by mutation, and review, until the requirement is met and the reproduction passes.",
4
4
  "category": "development",
5
- "nodes": ["reproduce", "identify", "apply", "test", "review"],
5
+ "rules": [
6
+ "Each card's writeSet names the reproduction test, so a mutation-check repair can strengthen it."
7
+ ],
8
+ "nodes": ["reproduce", "identify", "apply", "test", "mutation-check", "review"],
6
9
  "start": "reproduce",
7
10
  "edges": [
8
11
  { "from": "reproduce", "on": "pass", "to": "identify" },
@@ -11,13 +14,16 @@
11
14
  { "from": "identify", "on": "done", "to": "$close" },
12
15
  { "from": "apply", "on": "pass", "to": "test" },
13
16
  { "from": "test", "on": "fail", "to": "apply" },
14
- { "from": "test", "on": "pass", "to": "review" },
17
+ { "from": "test", "on": "pass", "to": "mutation-check" },
18
+ { "from": "mutation-check", "on": "pass", "to": "review" },
19
+ { "from": "mutation-check", "on": "fail", "to": "apply" },
20
+ { "from": "mutation-check", "on": "unavailable", "to": "review" },
15
21
  { "from": "review", "on": "pass", "to": "identify" },
16
22
  { "from": "review", "on": "fail", "to": "apply" }
17
23
  ],
18
24
  "loops": [
19
- { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
25
+ { "name": "iterations", "nodes": ["identify", "apply", "test", "mutation-check", "review"], "max": 20, "iteration": true },
20
26
  { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
21
- { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
27
+ { "name": "review-fix", "nodes": ["apply", "test", "mutation-check", "review"], "max": 3 }
22
28
  ]
23
29
  }
@@ -1,13 +1,16 @@
1
1
  {
2
2
  "name": "feature",
3
- "description": "Plan the feature into ordered iterations, then build each one: apply, test, and review, until the plan is complete — and an independent done-check maps every requirement to a passing test before the loop closes.",
3
+ "description": "Plan the feature into ordered iterations, then build each one test-first: a failing test, apply, test, and review, until the plan is complete — and an independent done-check maps every requirement to a passing test before the loop closes.",
4
4
  "category": "development",
5
- "nodes": ["plan", "identify", "apply", "test", "review", "done-check"],
5
+ "nodes": ["plan", "identify", "red-test", "apply", "test", "review", "done-check"],
6
6
  "start": "plan",
7
7
  "edges": [
8
8
  { "from": "plan", "on": "pass", "to": "identify" },
9
- { "from": "identify", "on": "more", "to": "apply" },
9
+ { "from": "identify", "on": "more", "to": "red-test" },
10
10
  { "from": "identify", "on": "done", "to": "done-check" },
11
+ { "from": "red-test", "on": "red", "to": "apply" },
12
+ { "from": "red-test", "on": "green", "to": "test" },
13
+ { "from": "red-test", "on": "untestable", "to": "$stop" },
11
14
  { "from": "apply", "on": "pass", "to": "test" },
12
15
  { "from": "test", "on": "pass", "to": "review" },
13
16
  { "from": "test", "on": "fail", "to": "apply" },
@@ -17,7 +20,7 @@
17
20
  { "from": "done-check", "on": "fail", "to": "identify" }
18
21
  ],
19
22
  "loops": [
20
- { "name": "iterations", "nodes": ["identify", "apply", "test", "review", "done-check"], "max": 20, "iteration": true },
23
+ { "name": "iterations", "nodes": ["identify", "red-test", "apply", "test", "review", "done-check"], "max": 20, "iteration": true },
21
24
  { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
22
25
  { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
23
26
  ]
@@ -4,7 +4,7 @@
4
4
  > to each developer, never committed or shared. The convention (`README.md`) and
5
5
  > the `.gitignore` are the only files tracked; your `MEMORY.md` index and all
6
6
  > fact files live only on your machine. (To share knowledge with the team, put
7
- > it in code, docs, or the project's `user-rules.md` instead.)
7
+ > it in code, docs, or the project's `user-rules.md` instead.){{SHARED_STORE_NOTE}}
8
8
 
9
9
  Durable knowledge that must survive across sessions lives here as **one fact per
10
10
  file**. An agent reads `MEMORY.md` (the local index map) at the start of a session,
@@ -1,7 +1,7 @@
1
1
  ## Self-improvement
2
2
 
3
3
  <!-- LEAN:begin -->
4
- This {{SKILL}} keeps its own notes in `{{DIR_NOTEBOOK}}/skill-notes/<name>.md`,
4
+ This {{SKILL}} keeps its own notes in `{{PATH_NOTES}}/skill-notes/<name>.md`,
5
5
  `<name>` being this {{SKILL}}'s name. When that file exists, read it before the
6
6
  first step — where it disagrees with this file, the notes win. They are yours to
7
7
  write, and no rebuild touches them.
@@ -27,7 +27,7 @@ Close each run with one beat of reflection on the {{SKILL}} itself:
27
27
  <!-- LEAN:else -->
28
28
  One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or a
29
29
  wrong trigger is a flaw in this file — write the exact correction, with the user's
30
- assent ({{LAW:one-intent-one-act}}), into `{{DIR_NOTEBOOK}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
30
+ assent ({{LAW:one-intent-one-act}}), into `{{PATH_NOTES}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
31
31
  name) as `- [skill|general] <correction> — seen: <what happened vs expected> (<date>)`,
32
32
  never into this rendered file, which a rebuild overwrites. Read that notes
33
33
  file before the first step when it exists; it wins where it disagrees. Keep it short.
@@ -23,7 +23,7 @@ procedure; this one is the overview.
23
23
 
24
24
  Before the first run, make sure the pieces this skill depends on are in place:
25
25
 
26
- 1. **A vault to mine.** Declare your Obsidian vault in the harness `geneseed-wiki.jsonc`
26
+ 1. **A vault to mine.** Declare your Obsidian vault in `geneseed-wiki.jsonc`, beside the harness{{WIKI_TIER}}
27
27
  (AGENT.md §8) — give a `wikis[]` entry a `path` to the vault root. Without it the
28
28
  skill falls back to detecting a `.obsidian/` folder in the current directory, then
29
29
  asks. No vault → nothing to daydream about.
@@ -46,7 +46,7 @@ Glob/Read/Write/Bash and subagent tools. See [VENDOR.md](VENDOR.md) for provenan
46
46
 
47
47
  ## What it does
48
48
 
49
- 1. Resolves vault root from the harness `geneseed-wiki.jsonc` manifest (a declared vault's `path`); falls back to auto-detecting `.obsidian/` from the current directory, then asks if still unfound
49
+ 1. Resolves vault root from the `geneseed-wiki.jsonc` manifest beside the harness{{WIKI_TIER}} (a declared vault's `path`); falls back to auto-detecting `.obsidian/` from the current directory, then asks if still unfound
50
50
  2. Scans vault for notes modified in last 120 days
51
51
  2. Generates 50 recency-weighted random pairs
52
52
  3. Synthesizes connections (Sonnet, parallel batches of 5)
@@ -5,7 +5,7 @@ You are running the Vault Daydream skill. Follow these steps precisely.
5
5
  ## Step 0: Resolve Vault Root
6
6
 
7
7
  Determine `VAULT_ROOT`:
8
- 1. **Geneseed `geneseed-wiki.jsonc` first.** Look for `geneseed-wiki.jsonc` beside the harness `AGENT.md` (or at `$GENESEED_WIKI`). Strip `//` and `/* */` comments, parse it, and take the first `wikis[].path` whose root exists on disk — that is the vault. Prefer a declared vault whose `path` contains a `.obsidian/` folder; if several qualify, ask which to use. (This is Geneseed's machine-wide knowledge-base manifest — see AGENT.md's Wiki section.)
8
+ 1. **Geneseed `geneseed-wiki.jsonc` first.** Look for `geneseed-wiki.jsonc` beside the harness `AGENT.md` (or at `$GENESEED_WIKI`){{WIKI_TIER}}. Strip `//` and `/* */` comments, parse it, and take the first `wikis[].path` whose root exists on disk — that is the vault. Prefer a declared vault whose `path` contains a `.obsidian/` folder; if several qualify, ask which to use. (This is Geneseed's machine-wide knowledge-base manifest — see AGENT.md's Wiki section.)
9
9
  2. Otherwise, check if the current working directory contains a `.obsidian/` folder. If yes, use it as `VAULT_ROOT`.
10
10
  3. If still unresolved, use `AskUserQuestion` to ask:
11
11
  - Question: "Where is your Obsidian vault located?"
@@ -11,7 +11,7 @@
11
11
  3. **Read a piece** from disk, not from recall ({{LAW:verify-before-asserting}}): `<root>/agents/<name>.md`, `<root>/skills/<name>/SKILL.md`, `<root>/memory/`, `<root>/notebook/`. The {{ONTOLOGY}}, the {{LAWS}} and the active {{DOCTRINES}} are numbered `## N. …` sections of the install's root file.
12
12
  4. **Change an install only when the user asked for that change** ({{LAW:one-intent-one-act}}). Take that install's `rebuild` command from step 1, edit only the flag the user named (add it if the command omits it — `--posture`, `--mode` and `--trust` are left out at their defaults) — `--theme`, `--footprint lean|full`, `--posture`, `--mode direct|foreman`, `--trust prudent|balanced|aggressive`, `--doctrines craft,rigor|none`, `--exclude-rules "process 7"|none` — dry-run it first by running the same flags through `geneseed validate`, show the command, and run it once the user agrees. Never rebuild from a bare `geneseed build`: every omitted flag resets that setting to the generator default. Confirm with `geneseed status`.
13
13
  5. **Other writes also need the user's word:** `geneseed memory rm <name>` (archives; `--purge` deletes for good), `geneseed exclude add|remove <path>`, `geneseed web start|stop`, `geneseed uninstall --target <root> --yes`. Personal rules and the profile belong to their own {{SKILLS}}; do not edit `user-rules.md` or `PROFILE.md` from here.
14
- 6. **Never on your own initiative:** `geneseed setup` (interactive only), `geneseed upgrade`, `geneseed update`, `geneseed bootstrap`, `geneseed sync-self`, `geneseed rebuild-all`, `geneseed migrate`, `geneseed link`, `geneseed unlink`. `learn`, `context` and the `*-gate` verbs are `geneseed-hook` verbs the host's hooks run — never run them by hand.
14
+ 6. **Never on your own initiative:** `geneseed setup` (interactive only), `geneseed upgrade`, `geneseed update`, `geneseed bootstrap`, `geneseed rebuild-all`, `geneseed migrate`, `geneseed link`, `geneseed unlink`. `learn`, `context` and the `*-gate` verbs are `geneseed-hook` verbs the host's hooks run — never run them by hand.
15
15
  7. Directory and section names are plain English in every theme; only prose changes. Do not search by flavour words.
16
16
  8. **Custom OpenCode colour theme** (a different concept from the `--theme` package name in step 4 — that one changes the agent's *voice*, this one its terminal colours): clone a shipped palette (`catppuccin tokyonight rosepine gruvbox nord everforest kanagawa dracula`) or derive one from a described vibe, filling all 19 roles in `themes/opencode/README.md` (`bg bgPanel bgElement fg fgMuted accent secondary border ok warn err kw str fn num type comment addBg delBg`) as `#rrggbb` hex. Keep `fg` on `bg` readable (~7:1), `error` red-family, `warning` amber, `success` green, and `addBg`/`delBg` distinct from each other and the background. Write the overrides to a small JSON (`{role: "#hex", …}` or `{"palette": {…}}`) and run `geneseed theme <name> --from <shipped> --palette <file.json>` — either flag alone works, both together lets the palette override the cloned base; `--solid-only`/`--transparent-only` for one flavour, `--global` to force the global dir from inside a repo. Tell the user to select it with `/theme geneseed-<name>` (opaque) or `/theme geneseed-<name>-transparent` (terminal background shows through) — a rebuild never erases it.
17
17
 
@@ -9,8 +9,7 @@
9
9
  **Trigger:** the user wants to *learn while building* rather than be handed finished code.
10
10
  Phrases: "learn mode", "turn on learning", "I want to understand what we build", "let me design it,
11
11
  you write it". Also "pause learning" / "resume learning" / "stop learn mode". To be taught a
12
- topic outside a build, use the [teach {{SKILL}}](teach.md); to have knowledge tested, the
13
- [quiz {{SKILL}}](quiz.md).
12
+ topic outside a build, use the [teach {{SKILL}}](teach.md), which also tests what you know.
14
13
 
15
14
  The user is the engineer and owns the decisions; you write the code for the design they
16
15
  chose and understand. Learning and the user's control outrank build speed.
@@ -87,6 +87,7 @@ What `score --diff`, `decide` and `record` print back:
87
87
  brick, `score --diff` before `record`). Do the step, never edit the state block to get past it.
88
88
  An `{error}` from `record` that mentions JSON means the shell mangled the card's quotes: retry
89
89
  with the card on a single line and no single quotes inside it.
90
+ A `test` `pass` with a `SKIPPED` entry is refused: run the check, or report `fail` or `error`.
90
91
 
91
92
  ## The end
92
93
 
@@ -7,7 +7,7 @@ the untouched stub. Phrases: "set up my profile", "create my profile", "update m
7
7
  profile". Also when an existing profile visibly contradicts how the user now works.
8
8
 
9
9
  ## Procedure
10
- 1. Locate `PROFILE.md` beside the deployed AGENT.md and read it ({{LAW:verify-before-asserting}} — the
10
+ 1. Locate {{PROFILE_LOCATION}} and read it ({{LAW:verify-before-asserting}} — the
11
11
  real current file, not a remembered copy). The build seeds it once and never
12
12
  overwrites it; if it is genuinely absent, start from the stub's three sections
13
13
  (below) and note that a rebuild would have seeded it.
@@ -30,7 +30,7 @@ profile". Also when an existing profile visibly contradicts how the user now wor
30
30
  prose, no placeholders left standing. Keep it lean: a profile is read every
31
31
  session, and bloat dilutes the parts that matter.
32
32
  5. Show the full draft and wait for explicit consent ({{LAW:deletion-is-deliberate}}) before writing
33
- `PROFILE.md`. Remind the user the file is theirs — hand-editable any time, and
33
+ `{{PATH_PROFILE}}`. Remind the user the file is theirs — hand-editable any time, and
34
34
  it survives updates, rebuilds, and theme switches.
35
35
 
36
36
  **Refresh flow** (on request, or when the profile has drifted): read the current
@@ -0,0 +1,69 @@
1
+ # {{SKILL}}: rule — approval flow
2
+
3
+ Decides what the fold left in `user-rules.draft.md`. That file sits in the shared tier, the
4
+ folder of `{{PATH_RULES}}` on a global install. If `{{PATH_RULES}}` is a relative path, this is
5
+ a project install: use `$XDG_CONFIG_HOME/geneseed/` (default `~/.config/geneseed/`) instead, and
6
+ never the project's own files. Below, "the shared file" is `user-rules.md` in that folder.
7
+ The draft is not active. Until the user decides, each drafted rule stays in its host file and
8
+ binds from there, so no step here may take a rule out of force. The ledger is `.fold-state.json`
9
+ in that folder: the `sha256` of a block is the key of its row under `items`. Writes here pass the
10
+ rule gate; that prompt is expected.
11
+
12
+ 1. **Read the draft and the ledger.** If the draft holds no block and no row is `pending`, say so
13
+ and stop.
14
+ 2. **Clear what is stale, and finish what a stop left.** Name each item to the user.
15
+ - A block whose row is not `pending` is already decided. For an `approved` rule, add its
16
+ `## Renumbered` line if that line is missing. Then delete the block and keep the row.
17
+ - Delete the block and the row of a `Choose` block whose host file is absent, is now its seed,
18
+ or now matches the shared file.
19
+ - Delete the block and the row of a `Choose` block whose `sha256` is not the host file's key
20
+ now: the host file changed, and the next fold asks about the current text. Order proves
21
+ nothing, because a host file can return to earlier text. Get the key from the row's `kind`
22
+ and `host`:
23
+ `node -e "const c=require('crypto'),f=require('fs');console.log(c.createHash('sha256').update('<kind>\0<host>\0').update(f.readFileSync('<host file>')).digest('hex'))"`
24
+ - A `Rule from` block whose rule the shared file now holds word for word needs no decision.
25
+ Skip it: the next fold of that host clears it.
26
+ 3. **Decide one item at a time.** Show the item, then ask. "Later" leaves the block and the row as
27
+ they are. For each decision, write in this order: the target file, the ledger row, the draft.
28
+ A stop between the writes leaves the rule in force, and step 2 or the next fold finishes it.
29
+
30
+ ### A `Rule from <host>` block
31
+ The lines under the pointer are the rule as it stands, with its own metadata line.
32
+
33
+ - **Approve** moves it to the shared file:
34
+ 1. Apply steps 4 and 8 of Branch B: the shared file binds every host on the machine.
35
+ 2. Read the shared file and each `user-rules-retired.md` ({{LAW:verify-before-asserting}}): the one
36
+ beside the shared file, the one beside each block's `source`, and the one in each global
37
+ install that `installs.json` in that folder lists. A host keeps its own retired rules, and a
38
+ retired number is never reused. The new number is one above the highest in all these files.
39
+ 3. Append to the shared file `## R<new> — <title>`, then the lines under the pointer, unchanged. The next fold
40
+ finds the host copy by its title and body, so never reword here. Other wording is a new
41
+ rule: reject this item and take the text through Branch B.
42
+ 4. Set the row's `state` to `approved`.
43
+ 5. Under the draft's `## Renumbered` heading, add `- <host> R<old> -> R<new>: <title>`. Add the
44
+ heading if it is absent; it can sit anywhere in the draft, because the fold appends new
45
+ blocks after it. This line is a record: leave every `R<n>` citation in the facts as it is.
46
+ 6. Delete the block.
47
+
48
+ Leave the host file alone. The next fold of that host removes the rule from it.
49
+ - **Reject** means "keep it on this host only". Set the row's `state` to `rejected`, and delete
50
+ the block. The rule stays in the host file, and the fold never drafts it again.
51
+
52
+ ### A `Choose: <file>` block
53
+ The block is a pointer: `paths` gives the shared file, then the host file. Read both, show what
54
+ differs, and ask which one becomes the shared file. Nothing is deleted: `<stamp>` is the local
55
+ time as `YYYYMMDD-HHMMSS`, and `archived-<file>/` sits beside the file it keeps.
56
+
57
+ - **The host file:** copy the shared file to `archived-<file>/<stamp>`, then copy the host file
58
+ over the shared file. Set the row's `state` to `approved`. The next fold sees two equal files,
59
+ sets the host file aside and returns it to its seed.
60
+ - **The shared file:** move the host file to `archived-<file>/<stamp>`. Set the row's `state` to
61
+ `approved`. The next emit of that host writes its seed.
62
+ - **Keep both:** set the row's `state` to `rejected`. The host file keeps its override on that
63
+ host, and the fold never asks again about these bytes.
64
+
65
+ Delete the block in each case.
66
+
67
+ ### Close
68
+ Tell the user that a host file changes at the next global emit of that host, and that
69
+ `geneseed rebuild-all` runs one for every host.
@@ -5,7 +5,7 @@ topic over 40 facts, or a `misc` topic) goes to the memory-curator {{AGENT}}
5
5
  instead: it runs this flow topic by topic in its own context and also assigns topics.
6
6
 
7
7
  1. **Read the whole set once**: `MEMORY.md`, its `topics/` files, every fact they
8
- index, and any file in `{{DIR_MEMORY}}/` they forgot, into a scratch table — name, type, the claim in one
8
+ index, and any file in `{{PATH_MEMORY}}/` they forgot, into a scratch table — name, type, the claim in one
9
9
  line, date written, and whether this session already saw it contradicted
10
10
  ({{DOCTRINE:context-economy}}: read to decide, not to reread).
11
11
  2. **Verify against the live repo, not memory** ({{LAW:verify-before-asserting}}): every path,
@@ -17,7 +17,7 @@ instead: it runs this flow topic by topic in its own context and also assigns to
17
17
  that fired three times or more goes through Branch B of the rule {{SKILL}}), *retire* (wrong, superseded,
18
18
  or re-derivable by a fresh read). In doubt between keep and retire, keep and date it.
19
19
  4. **Show the plan, apply it with consent** ({{LAW:deletion-is-deliberate}}). To retire is to
20
- archive: move the file into `{{DIR_MEMORY}}/archive/`, never delete it; deleting a file
20
+ archive: move the file into `{{PATH_MEMORY}}/archive/`, never delete it; deleting a file
21
21
  from `archive/` is a further act that needs its own consent. A merge archives the
22
22
  file that did not survive. Merges keep both parents' `[[links]]`; rewrites keep the file name so
23
23
  inbound links hold; every survivor keeps valid frontmatter and the `**Why** / **How
@@ -25,7 +25,7 @@ instead: it runs this flow topic by topic in its own context and also assigns to
25
25
  archiving would keep it on disk, so propose deleting it outright, on sight
26
26
  ({{LAW:sealed-secrets}}).
27
27
  5. **Rebuild the index** with
28
- `geneseed learn --consolidate --memory <the {{DIR_MEMORY}}/ dir's path>`: one pointer line per
28
+ `geneseed learn --consolidate --memory <the {{PATH_MEMORY}}/ dir's path>`: one pointer line per
29
29
  surviving file in its `topics/<topic>.md`, and the `MEMORY.md` map recounted. Each
30
30
  hook is the fact's `description`, so sharpen a weak hook there — it should say why a
31
31
  future session would open the fact.
@@ -15,6 +15,8 @@ fork — when the index outgrows one useful read (~40 lines) or holds duplicate,
15
15
  contradictory or stale entries (a file, flag or command that no longer exists), after
16
16
  a release or large refactor, or when the user says "clean up memory", "consolidate",
17
17
  "what do you actually remember". The user's wiki is the [wiki {{SKILL}}](wiki.md)'s.
18
+ Run the **approval flow**, not the fork, when an emit reports items `to approve`, when
19
+ `user-rules.draft.md` holds pending items, or when the user asks to review them.
18
20
 
19
21
  ## Procedure
20
22
 
@@ -37,7 +39,7 @@ re-derived. Then take exactly one branch.
37
39
  per the {{MEMORY}} convention, and **show the exact content, frontmatter
38
40
  included** — so a wrong inference is visible before it is written, not after.
39
41
  4. On the user's word, write the file and rebuild the index
40
- (`geneseed learn --consolidate --memory <the {{DIR_MEMORY}}/ dir's path>`) so its line
42
+ (`geneseed learn --consolidate --memory <the {{PATH_MEMORY}}/ dir's path>`) so its line
41
43
  lands in `topics/<topic>.md` and the `MEMORY.md` map recounts.
42
44
 
43
45
  ### Branch B — a standing rule
@@ -70,7 +72,7 @@ re-derived. Then take exactly one branch.
70
72
  rules into the {{ONTOLOGY}}, {{LAWS}}, or {{DOCTRINES}} files themselves: they are
71
73
  regenerated on every update and the edit would be silently lost.
72
74
  5. **Destination.** Scope decides the file: a rule that holds across all the user's
73
- work goes to the *global* install's `user-rules.md`, a rule bound to this
75
+ work goes to the *global* install's `{{PATH_RULES}}`, a rule bound to this
74
76
  codebase to the project's. Tag it to match: `scope: project` — this repo, committable,
75
77
  binds the team; `scope: global` — every repository on the machine. `user` is still read
76
78
  as `global`. Read the target first ({{LAW:verify-before-asserting}} — the real current
@@ -90,9 +92,11 @@ re-derived. Then take exactly one branch.
90
92
  appending it to `user-rules.md` (retired rules live in `user-rules-retired.md`, which is
91
93
  never loaded — never write a rule there). For a promotion, after the rule lands, archive the source memory into
92
94
  `archive/` (with the same consent) so the lesson is not loaded twice.
93
- 8. **Keep the set lean.** After writing, if the file holds more than ~15 rules or
94
- any rule no longer changes behaviour, say so and propose merges or prunes — every
95
- rule is loaded every session, and a bloated set dilutes the rules that matter.
95
+ 8. **Keep the set lean.** After writing, state the file's token total (characters / 4;
96
+ the console's Rules page shows it, with each rule's cost). If that total has grown
97
+ beyond what the rules earn, or any rule no longer changes behaviour, say so and propose
98
+ merges or prunes — every rule is loaded every session, and a bloated set dilutes the
99
+ rules that matter.
96
100
 
97
101
  The asymmetry is deliberate: Branch A costs one question, Branch B costs several.
98
102
  The price is the safeguard — make remembering cheap and legislating expensive, or
@@ -110,11 +114,15 @@ adoption. Two more cases are due at any time:
110
114
 
111
115
  **Consolidation flow** → read [rule/consolidate.md](rule/consolidate.md) and follow it.
112
116
 
117
+ **Approval flow** → read [rule/approve.md](rule/approve.md) and follow it.
118
+
113
119
  ## Done when
114
120
  - For a rule or memory: the fork was put to the user, and then either a {{MEMORY}} file exists carrying its
115
121
  `force`, its `type` and its index line — or a rule stands in the right
116
122
  `user-rules.md`, having survived reformulation, its own counter-example and the
117
123
  {{LAWS}}, consented to explicitly, with any promoted source memory archived. The
118
124
  {{ONTOLOGY}}, {{LAWS}} and {{DOCTRINES}} files are untouched either way.
125
+ - For an approval: each item the user decided has its ledger state and no draft block, and no
126
+ rule left a host file by hand.
119
127
 
120
128
  <!-- INCLUDE: skills/_self-improvement.md -->
@@ -36,7 +36,13 @@ request or merge the branch.
36
36
  it is wrong — consumers, layout, data), and any follow-up. Link the
37
37
  issue it closes; keep the title an imperative one-line summary.
38
38
  6. If the project merges locally instead, merge into the base branch only after
39
- review/approval, then delete the merged branch.
39
+ review/approval.
40
+ 7. Once the branch is merged — locally or through the PR — delete it, local and remote
41
+ (`git branch -d <branch>`, `git push origin --delete <branch>`), with consent: it is a
42
+ deletion ({{LAW:deletion-is-deliberate}}). A PR usually merges after your turn ends,
43
+ with nobody left to delete its branch, so the first time you ship in a repo, check
44
+ whether the forge deletes merged branches by itself (GitHub: *Automatically delete
45
+ head branches*) and recommend turning it on if not.
40
46
  If shipping triggers a production deploy, confirm a tested rollback or
41
47
  fix-forward path and a retained previous artifact *before* deploying — there must
42
48
  be a way back ({{LAW:deletion-is-deliberate}}); dispatch the
@@ -46,5 +52,7 @@ request or merge the branch.
46
52
  ## Done when
47
53
  - The diff passed review with no `blocking` finding, and the PR is open (or the branch is merged) with a Summary / Evidence / Merge danger
48
54
  body, and nothing unrelated rides along.
55
+ - A branch merged while you are still working is deleted, local and remote, or the user
56
+ declined.
49
57
 
50
58
  <!-- INCLUDE: skills/_self-improvement.md -->
@@ -5,7 +5,7 @@
5
5
  {{CREDIT:mattpocock-skills:skills/productivity/writing-for-agents/SKILL.md}}
6
6
 
7
7
  **Trigger:** a task has repeated and no {{SKILL}} covers it; a {{SKILL}}'s
8
- notes in `{{DIR_NOTEBOOK}}/skill-notes/` hold a correction worth making; the user says "make this a
8
+ notes in `{{PATH_NOTES}}/skill-notes/` hold a correction worth making; the user says "make this a
9
9
  skill", "write a skill for…", "fix the trigger of…"; or two {{SKILLS}} keep
10
10
  disambiguating against each other and should merge. Meta by nature: it edits the
11
11
  apparatus, so every step ends in the user's assent ({{LAW:one-intent-one-act}}, {{LAW:deletion-is-deliberate}}).
@@ -3,16 +3,18 @@
3
3
  > {{DESC_TEACH}}
4
4
 
5
5
  <!-- invocation: user -->
6
+ <!-- aliases: quiz -->
6
7
 
7
- **Trigger:** the user wants to *learn* something and asks to be taught. Phrases: "teach me X",
8
- "get me up to speed on X", "this is confusing, break it down", "explain this passage",
9
- "how do I get to X in N days". Three shapes, picked from the ask: a **crash course**
10
- (from zero to functional, fast), a **decode** (confusing material handed over, make it
11
- click), or a **path** (a specific result by a deadline, day by day). To *test* what the
12
- user already knows rather than teach it, use the [quiz {{SKILL}}](quiz.md); to learn while building, the
13
- [learn-mode {{SKILL}}](learn-mode.md); to gather
14
- facts from the web first, [research](research.md); to convert a PDF or web page into
15
- readable form, [ingest](ingest.md).
8
+ **Trigger:** the user asks to be taught something, or to have what they know tested. Phrases:
9
+ "teach me X", "get me up to speed on X", "this is confusing, break it down", "explain this passage", "how do I get to X in N days"; "test me on X", "quiz me until it
10
+ sticks", "let me explain X and catch me", "prove me wrong". Six shapes, picked from the ask.
11
+ To be taught: a **crash course** (from zero to functional, fast), a **decode** (confusing
12
+ material handed over, make it click), or a **path** (a specific result by a deadline, day by
13
+ day). To be tested, not lectured: a **drill** (practise until reflex), a **feynman** (explain
14
+ it back, get caught on the stumbles), or a **gap check** (a mastery claim stress-tested). To
15
+ learn while building, use the [learn-mode {{SKILL}}](learn-mode.md); to gather facts from the web
16
+ first, [research](research.md); to convert a PDF or web page into readable form,
17
+ [ingest](ingest.md).
16
18
 
17
19
  ## Procedure
18
20
  1. Pin the footing before teaching anything: what the user wants to be able to *do*
@@ -36,18 +38,33 @@ readable form, [ingest](ingest.md).
36
38
  concrete criterion so they can tell they did it right, and one explicit
37
39
  *what-not-to-do* that day. Trace the whole path against the goal; if finishing
38
40
  every day would not deliver the result, rebuild it until it does.
41
+ - **Drill** — set the contract first: you test, you do not lecture, you do not go easy.
42
+ Drop them into a realistic situation where they would slip. On a mistake, withhold the
43
+ answer and ask the one question that makes them find where their reasoning broke;
44
+ reveal only after two honest attempts. New situation each cycle, until it is reflex.
45
+ - **Feynman** — have them explain it as to a ten-year-old. Interrupt the moment they
46
+ (a) use jargon they cannot unpack, (b) skip a step, or (c) simplify until it is
47
+ wrong — name which of the three each time, and keep them going to the end.
48
+ - **Gap check** — ask five questions that look simple but separate deep from skimmed:
49
+ edge cases, the *why*, the assumption under the rule, where the standard answer breaks.
50
+ After each answer say what it shows is missing; name a shallow answer as shallow.
39
51
  3. Check it took: ask three questions only someone who understood could answer (a
40
52
  crash course or decode), or walk the first day together (a path). Check retention,
41
53
  not fluency — recall from memory, spaced across the session, not a fresh re-read. A
42
54
  miss goes back to the analogy or the exercise — re-anchor, don't hand over the answer.
55
+ The three test shapes are this check, run as the whole job.
43
56
  4. Close by naming what to practise next and the gap most likely to trip them, so the
44
- learning continues without you; offer the [quiz {{SKILL}}](quiz.md) for when they
45
- want it tested.
57
+ learning continues without you. After a test shape, give the honest readout, no
58
+ flattery: what is not yet solid and what to restudy. Offer a test after teaching, and
59
+ teaching after a test that found gaps.
46
60
 
47
61
  ## Done when
48
62
  - The user is functional (crash course), has the keystone idea in plain terms and
49
63
  passed the three questions (decode), or holds a dated path whose every day has a
50
64
  timed task, a criterion and a what-not-to-do (path) — and knows what to practise
51
- next.
65
+ next. A test shape ends differently: the user worked the situation without being handed
66
+ the answer (drill), explained it through with every stumble labelled (feynman), or
67
+ answered all five questions and holds a verdict on the gaps (gap check) — then a direct
68
+ readout, never empty praise.
52
69
 
53
70
  <!-- INCLUDE: skills/_self-improvement.md -->
@@ -10,7 +10,7 @@ durable cross-project fact worth writing back. The knowledge base is declared in
10
10
 
11
11
  ## Procedure
12
12
 
13
- **Locate.** Read `geneseed-wiki.jsonc` — beside `AGENT.md`, or at `$GENESEED_WIKI`. No
13
+ **Locate.** Read `geneseed-wiki.jsonc` — beside `AGENT.md`, or at `$GENESEED_WIKI`{{WIKI_TIER}}. No
14
14
  file, or an empty `wikis` list: stop; there is no knowledge base on this
15
15
  machine. Each declared wiki gives you its root `path`, its `entries`, a
16
16
  `conventions` note, an `inbox`, and `protected` folders.