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
package/src/AGENT.md.tmpl CHANGED
@@ -189,19 +189,16 @@ contract you do not already know.
189
189
  <!-- CATALOG:end -->
190
190
 
191
191
  **Rule of delegation:** read-only investigation can be dispatched freely; any
192
- {{AGENT}} that *writes* must return a summary of exactly what it changed. Every
193
- {{AGENT}} spec ends with a **self-improvement loop**: when a report carries a
194
- `spec-feedback:` line, weigh it — record a real flaw (with the user's assent) in
195
- `{{PATH_NOTES}}/agent-notes/<name>.md` and pass it to later dispatches;
196
- {{MEMORY}} gets a record only when it clears {{DOCTRINE:persist-insight}}'s bar.
192
+ {{AGENT}} that *writes* must return a summary of exactly what it changed. Weigh any
193
+ `spec-feedback:` line an {{AGENT}}'s report carries, as its spec's self-improvement loop says.
197
194
 
198
195
  <!-- LEAN:begin -->
199
196
  **Dispatching a multi-part goal.** When a goal spans several capabilities,
200
197
  decompose it into independent subtasks, route each to the single owning {{AGENT}}
201
198
  above, and converge the results yourself. Every handoff carries an **envelope** —
202
199
  the subtask goal, the inputs the {{AGENT}} needs, and its output contract — and the
203
- constraints travel with it: dispatched {{AGENTS}} never commit or push ({{DOCTRINE:consent-before-push}}
204
- stays with you), and an unfulfilled contract returns as a stated gap, never invented
200
+ constraints travel with it: dispatched {{AGENTS}} never push, and commit only in their own
201
+ worktree ({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented
205
202
  content. Where the host exposes a `workflow` tool, prefer the saved `dispatch`
206
203
  workflow ([workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md)); where it does not, run
207
204
  the same shape model-driven via the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md).
@@ -212,8 +209,8 @@ Ten of them — `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`,
212
209
  dispatched alone; the [council {{SKILL}}]({{DIR_SKILLS}}/council.md) convenes the
213
210
  subset that productively clashes on a given motion.
214
211
  <!-- LEAN:else -->
215
- Dispatched {{AGENTS}} never commit or push ({{DOCTRINE:consent-before-push}} stays with
216
- you), and an unfulfilled contract returns as a stated gap, never invented content. A
212
+ Dispatched {{AGENTS}} commit only in their worktree, never push
213
+ ({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented content. A
217
214
  multi-part goal goes through the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md)
218
215
  (or the [workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md) where the host has a workflow tool);
219
216
  the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/council.md).
@@ -268,7 +265,9 @@ the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/cou
268
265
  | [workflow]({{DIR_SKILLS}}/workflow.md) | deterministic, code-driven orchestration of subagents (fan-out, find→verify, phased handoff) and the host exposes a workflow tool |
269
266
  | [pipeline]({{DIR_SKILLS}}/pipeline.md) | the user asks for a crew, or foreman mode needs several specialists (analyst → developer → tester) on one, isolated in its own worktree and merged on mechanical proof |
270
267
  | [loop]({{DIR_SKILLS}}/loop.md) | the user asks to run a loop |
268
+ | [factory]({{DIR_SKILLS}}/factory.md) | carry one work item to an open PR through a factory |
271
269
  | [brick-forge]({{DIR_SKILLS}}/brick-forge.md) | a new or adapted loop brick |
270
+ | [factory-forge]({{DIR_SKILLS}}/factory-forge.md) | a new or changed factory of bricks and loops |
272
271
  | [wiki]({{DIR_SKILLS}}/wiki.md) | consulting or growing the user's machine-wide knowledge base declared in `geneseed-wiki.jsonc` (§8) |
273
272
  | [rule]({{DIR_SKILLS}}/rule.md) | anything the user wants to outlive this session — a standing rule of their own (§1) or a durable fact to remember (§5); also tending the {{MEMORY}} set — duplicates, stale facts, a recurring lesson due for promotion |
274
273
  | [profile]({{DIR_SKILLS}}/profile.md) | the user wants the agent to know who they are — creating or refreshing the `PROFILE.md` identity file (§1) through a short interview |
@@ -309,11 +308,8 @@ the file, or to {{MEMORY}} ({{DOCTRINE:persist-insight}}).
309
308
 
310
309
  <!-- LEAN:begin -->
311
310
  Persistent facts live in {{LINK_MEMORY}} — one fact per file, indexed by a
312
- local `MEMORY.md`, a session file (**Session start**, above); write a new memory
313
- whenever the conversation yields a durable fact, a correction, or a decision worth
314
- keeping — through the [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}, which settles with
315
- the user whether it is a memory or a standing rule before either is written
316
- ({{DOCTRINE:persist-insight}}). The `{{PATH_MEMORY}}/` directory is **personal and git-ignored** — it is
311
+ local `MEMORY.md`, a session file (**Session start**, above). Write a fact on your own; a standing rule goes
312
+ only through the [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}} ({{DOCTRINE:persist-insight}}). The `{{PATH_MEMORY}}/` directory is **personal and git-ignored** — it is
317
313
  never committed or shared; to share knowledge, put it in code, docs, or the
318
314
  project's `user-rules.md` (§1). When the same feedback lesson keeps recurring,
319
315
  propose promoting it into a standing rule — the [rule]({{DIR_SKILLS}}/rule.md)
@@ -325,9 +321,8 @@ the session — memory, notebook, notes, commits, docs — cite a rule by its pr
325
321
  ("Verify Before Asserting"), never its number: numbers are positional. Full convention: [`{{DIR_MEMORY}}/README.md`]({{DIR_MEMORY}}/README.md).
326
322
  <!-- LEAN:else -->
327
323
  Durable facts live in {{LINK_MEMORY}}, one per file, indexed by
328
- `MEMORY.md`, a session file. Write one through the
329
- [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}, which settles with the user whether a
330
- lesson is a memory or a standing rule ({{DOCTRINE:persist-insight}}). The directory is
324
+ `MEMORY.md`, a session file. Write a fact on your own; a standing rule goes only through the
325
+ [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}} ({{DOCTRINE:persist-insight}}). The directory is
331
326
  **personal and git-ignored**; shared knowledge goes in code, docs, or `user-rules.md`
332
327
  (§1). In anything that outlives the session, cite a rule by its principle ("Verify Before
333
328
  Asserting"), never its number — numbers change. Convention, incl. `force`:
@@ -355,8 +350,8 @@ own benefit — a scratch script, an analysis dump, a draft, an experiment, a
355
350
  tool you build for yourself — belongs in `{{DIR_NOTEBOOK}}/`, never in the host
356
351
  tree. `NOTEBOOK.md`, a session file, recalls what you keep here; keep the space referable across sessions — the seeded index
357
352
  is one way; replace it with whatever scheme serves you better. When a note
358
- hardens into a durable fact worth recalling verbatim, propose it for {{MEMORY}}
359
- through the rule {{SKILL}} (§5, {{DOCTRINE:persist-insight}}). Keep the two stores distinct by *role*, not just by
353
+ hardens into a durable fact worth recalling verbatim, write it to {{MEMORY}}
354
+ (§5, {{DOCTRINE:persist-insight}}). Keep the two stores distinct by *role*, not just by
360
355
  format: {{MEMORY}} holds durable insight for future sessions, the {{NOTEBOOK}}
361
356
  holds your working artifacts. The one fixed law: `{{DIR_NOTEBOOK}}/` is **personal and
362
357
  git-ignored** — never committed or shared, and the `.gitignore` that guarantees
@@ -365,8 +360,7 @@ it is not yours to lift.
365
360
  Your own working space, [`{{DIR_NOTEBOOK}}/`]({{DIR_NOTEBOOK}}/): any file you make
366
361
  for your own benefit — scratch code, drafts, datasets, experiments — goes here, never
367
362
  in the host tree, in whatever format serves; its index `NOTEBOOK.md` is a session
368
- file. A note that hardens into a durable fact is proposed for {{MEMORY}} through
369
- the rule {{SKILL}} (§5).
363
+ file. A note that hardens into a durable fact goes to {{MEMORY}} (§5).
370
364
  The charter [`{{DIR_NOTEBOOK}}/README.md`]({{DIR_NOTEBOOK}}/README.md) is yours to
371
365
  rewrite; the one fixed law is that the folder is **personal and git-ignored**, and
372
366
  that `.gitignore` is not yours to lift.
@@ -385,8 +379,8 @@ configs, documents, prior work. All of it is context you may use.
385
379
 
386
380
  After reading this file, take stock of what surrounds it. That non-harness
387
381
  content is knowledge to **read and learn from**, not scaffolding to reorganise.
388
- When you find a durable fact there worth keeping, propose it for {{MEMORY}} through
389
- the rule {{SKILL}} (§5) so it outlives the session.
382
+ When you find a durable fact there worth keeping, write it to {{MEMORY}} (§5) so it
383
+ outlives the session.
390
384
 
391
385
  Because the folder is shared, two cautions hold:
392
386
  - **You do not own it.** Files you did not create are not yours to move, rename,
@@ -400,7 +394,7 @@ scratch scripts, analysis dumps, drafts, experiments — are made in the
400
394
  <!-- LEAN:else -->
401
395
  {{INTRO_WORKSPACE}} Whatever sits beside the harness files — notes, data, configs,
402
396
  prior work — is knowledge to read and learn from, not scaffolding to reorganise;
403
- propose a durable fact from it for {{MEMORY}} through the rule {{SKILL}} (§5). You do not own the folder: files
397
+ write a durable fact from it to {{MEMORY}} (§5). You do not own the folder: files
404
398
  you did not create are not yours to move or delete unless the task requires it
405
399
  ({{LAW:deletion-is-deliberate}}), and a file is verified before it is treated as disposable ({{LAW:verify-before-asserting}}).
406
400
  It receives only the task's deliverables; your working files go in the {{NOTEBOOK}}
@@ -2,10 +2,11 @@
2
2
 
3
3
  If this spec misled you — an input you needed but were not given, a boundary
4
4
  that proved wrong, a step you could not execute — end your report with one line:
5
- `spec-feedback: [agent|general] <the one-line fix> — seen: <what happened, against
6
- what this spec led you to expect>`. `general` marks a fix other {{AGENTS}} need too.
7
- Omit the line when there is no friction. The caller weighs the feedback and, with the
8
- user's assent, writes a real flaw, dated, into `{{PATH_NOTES}}/agent-notes/<name>.md`
9
- — never into this rendered file, which a rebuild overwrites — and hands those notes
10
- to every later dispatch of this {{AGENT}}. It records the feedback to {{MEMORY}} only if it clears
5
+ `spec-feedback: [agent|general] <the one-line fix> [— situation: <when it applies>] — seen:
6
+ <what happened, against what this spec led you to expect>`. `general` marks a fix other
7
+ {{AGENTS}} need too. Omit the line when there is no friction. The caller weighs the
8
+ feedback and writes a real flaw, dated, into `{{PATH_NOTES}}/agent-notes/<name>.md` on
9
+ its own, with no prompt — never into this rendered file, which a rebuild overwrites —
10
+ and hands those notes to every later dispatch of this {{AGENT}}. Folding a note into the
11
+ source is the user's call, after the skill-forge {{SKILL}}'s probe. It records the feedback to {{MEMORY}} only if it clears
11
12
  {{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
@@ -25,8 +25,9 @@
25
25
  - **Read + write to the assigned worktree.** May run the project's own build/lint
26
26
  commands to self-check before handing off.
27
27
  <!-- bash: allow -->
28
- - Never commits or pushes ({{DOCTRINE:consent-before-push}}) — the parent re-runs the proof and
29
- commits once the user accepts.
28
+ - Never pushes ({{DOCTRINE:consent-before-push}}). It commits and merges only inside its own
29
+ worktree branch, from sub-workers it started; the parent re-runs the proof and merges
30
+ beyond it once the user accepts.
30
31
 
31
32
  ## Procedure
32
33
  0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
@@ -11,6 +11,7 @@ Builds small, safe container images for Spring Boot 4 applications.
11
11
 
12
12
  ## When NOT to dispatch
13
13
  - Cluster manifests — use [kubernetes-specialist](kubernetes-specialist.md). Pipelines — use [devops-engineer](devops-engineer.md).
14
+ - Operating a Compose stack (updates, rollback, limits, logs, networks) — the docker kit's `compose-ops` skill, when that kit is on.
14
15
 
15
16
  ## Inputs
16
17
  - The build tool (Maven or Gradle), the Java version and any registry or base-image policy.
@@ -20,8 +20,9 @@
20
20
 
21
21
  ## Allowed tools
22
22
  - **Read + write to the {{MEMORY}} store only.** May run `geneseed memory` and
23
- `geneseed learn --consolidate`. A write into the store may stop for the user's consent
24
- at the tool boundary, so it batches its edits per topic behind one plan.
23
+ `geneseed learn --consolidate`. A write into the store meets no prompt at the tool boundary
24
+ (memory is written freely), but bulk curation reworks facts the user already keeps, so it still
25
+ shows each topic's plan and applies it with the user's consent.
25
26
  <!-- bash: allow -->
26
27
  - Moves a fact out with `geneseed memory rm <name>`, which archives it — never a raw
27
28
  `mv` or `rm` past that gate. Deletes only with `--purge`, and only what the user
@@ -13,5 +13,10 @@ prose, reorganize a page, or fix an unrelated staleness you happen to notice whi
13
13
  Keep each doc in the format it is already in (Markdown or AsciiDoc) — never convert one; a new
14
14
  page follows the `Docs format:` line in the root `AGENTS.md`.
15
15
 
16
+ As a factory's docs lane, there is no iteration diff: the stage hands you the work item as
17
+ `carry` (and, when a later stage sent the work back, the reason). Make the doc change the work
18
+ item asks for, under the same limits, then commit the files you changed: the factory records a
19
+ stage only on a clean tree.
20
+
16
21
  Report `pass` once every doc the diff touched is back in sync, naming the files you changed — or
17
22
  that none needed it, if the diff left nothing stale.
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: holdout-write
3
+ description: Write 3 to 8 holdout scenarios for the work item, outside the worktree, where the developer never reads them.
4
+ effect: read
5
+ agent: tester
6
+ outcomes: pass, fail
7
+ ---
8
+ The stage hands you the work item's file (or the spec) as `carry`. Read it in full, then the code
9
+ it names. Write 3 to 8 scenarios that a correct change must pass and a careless one may not: each
10
+ one a short prose file with three lines, `Given` (the starting state), `When` (one act a user or a
11
+ caller takes) and `Then` (the behaviour a user can see), concrete enough to play by hand or with a
12
+ command. Cover the acceptance criteria, plus the edges they imply but do not name.
13
+
14
+ Write them to the holdout folder, `$XDG_CONFIG_HOME/geneseed/holdout/<slug>/` (by default
15
+ `~/.config/geneseed/holdout/<slug>/`), one `NN-<name>.md` per scenario; `<slug>` is this branch's
16
+ name after `loop/factory-`. Never write into the worktree, never into any brief, note or carry.
17
+ When that folder already holds files (an earlier run with the same slug), write nothing and report
18
+ `fail`: the user decides whether to clear it.
19
+
20
+ Report `pass` with the `carry` you were handed, unchanged: the next stage needs the work item, and
21
+ must never get the scenarios' content or the folder's path. Report `fail` when the work item gives
22
+ too little to write three scenarios, or the folder is not empty — say why in a file in the OS temp
23
+ directory, and report its path.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: holdout
3
+ description: Play the holdout scenarios against the built change and report each one; a failure carries one sentence, never the scenario.
4
+ effect: read
5
+ agent: tester
6
+ outcomes: pass, fail, error
7
+ ---
8
+ Read every scenario in the holdout folder, `$XDG_CONFIG_HOME/geneseed/holdout/<slug>/` (by default
9
+ `~/.config/geneseed/holdout/<slug>/`; `<slug>` is this branch's name after `loop/factory-`). Play
10
+ each one against the change as built on this branch: run the app, the tests or the commands its
11
+ `Given` and `When` describe, and compare what you observe with its `Then`. Never edit a file. Leave
12
+ `git status` exactly as you found it: remove any build output or log a run left in the worktree.
13
+
14
+ First read the branch's diff against the default branch it started from (`git merge-base HEAD
15
+ origin/<default>`; `gh repo view --json defaultBranchRef` or `git remote show origin` names it).
16
+ Report `error` when a changed file resolves under the holdout folder, or an added line holds that
17
+ folder's resolved absolute path (a docs line naming `~/.config/geneseed/holdout/` in general is
18
+ not a leak). Report `error` too when the folder is missing or holds no scenario (nothing played is
19
+ not a pass), or a scenario cannot be played (a tool or a service it needs is missing).
20
+
21
+ Report `pass` when every scenario passes. Report `fail` otherwise, with a file in the OS temp
22
+ directory, never in the holdout folder or the worktree, that holds ONE sentence per failed
23
+ scenario: what you observed against what was expected, e.g. "Rounding 2.5 gave 3; expected 2".
24
+ Never copy a scenario's text, its name or its `Given`/`When` into that file: it goes back to the
25
+ developer, who must never see the scenarios. Report that file's path.
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: intake
3
+ description: Read the work item — a request, a document or an issue — and write it down as one clear item for the run.
4
+ effect: read
5
+ agent: explorer
6
+ outcomes: pass, fail
7
+ ---
8
+ The stage hands you the run's `requirement` and its `input`: free text, a file path, or an issue (a
9
+ GitHub URL or `#<n>`: `gh issue view <n> --json title,body,comments,labels`; a GitLab one:
10
+ `glab issue view <n> --comments`). Read the input in full, then the code it names. Never edit any
11
+ file, and never post on the issue.
12
+
13
+ Write the work item to a file in the OS temp directory, never inside the worktree: a one-line
14
+ title, what happens now, what should happen, how to reproduce it, the files it likely touches,
15
+ and the acceptance criteria, each one testable. Quote the source for each claim (issue comment,
16
+ document section, file:line). Report `pass` with that file's path. Report `fail` when the input
17
+ cannot be read, or says too little to state one testable criterion — list the open questions in
18
+ such a file and report its path.
@@ -0,0 +1,22 @@
1
+ ---
2
+ name: merge-gate
3
+ description: Wait for the pull request's CI, at most 30 minutes, and report green, red, or no CI at all. Never merges.
4
+ effect: read
5
+ agent: tester
6
+ gate: human
7
+ gateOn: none
8
+ outcomes: pass, fail, none
9
+ ---
10
+ Wait with a command that returns by itself, never a foreground `sleep`: `gh pr checks <pr> --watch
11
+ --interval 30`, or `glab ci status --wait --branch <this branch>`. Bound each call under 10
12
+ minutes, by your shell tool's timeout or `timeout 540` in a POSIX shell, and repeat it up to 30
13
+ minutes in all. Then read the verdict once: `gh pr checks <pr> --json name,bucket,link` (exit 8:
14
+ pending), or `glab ci status --branch <this branch>`. A PR pushed moments ago may show no checks
15
+ yet, and a watch then returns at once: re-check for about 2 minutes before you conclude it has
16
+ none. Never merge, re-run or cancel a check, and never edit any file.
17
+
18
+ Report `pass` when every check is green. Report `fail` when one is red — for each failing check,
19
+ its name and the cause read from its log (`gh run view <id> --log-failed`), never guessed from its
20
+ title — or with "CI pending after 30 minutes" when checks still run at the bound. Report `none`
21
+ when the repo runs no CI on this PR: the user decides whether the run goes on. Write the findings
22
+ to a file in the OS temp directory and report that file's path.
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: pr-open
3
+ description: Push the run's branch and open its pull request, or update the one already open. Never merges.
4
+ effect: read
5
+ skill: ship
6
+ outcomes: pass, fail
7
+ ---
8
+ Follow the `ship` skill's pull-request path only: never merge, never enable auto-merge, never
9
+ push to any branch but this worktree's own. First look for a PR already open on this branch
10
+ (`gh pr view --json url,state` or `glab mr view`): after a rework lap it exists, and this stage
11
+ only pushes the new commits to it.
12
+
13
+ Push with `git push -u origin HEAD:<this branch>`. The push asks the user: wait for that answer,
14
+ never work around it. With no PR yet, open one (`gh pr create` / `glab mr create`) titled from the
15
+ run's title, its body built from the run's `requirement` and `input` (as `next` gives them) and
16
+ the branch's commit subjects (`git log --oneline origin/<default>..HEAD`; the loop's notes left
17
+ with its `LOOP.md`), naming the issue it closes when the input was one. Change no file in the worktree.
18
+
19
+ Report `pass` with the PR URL in a file in the OS temp directory — report that file's path. Report
20
+ `fail` when the push is refused or fails, or the PR cannot be opened, with the exact error in
21
+ such a file.
@@ -0,0 +1,17 @@
1
+ ---
2
+ name: retro
3
+ description: Write the factory run's report — what failed, what was reworked — and keep only a durable lesson in memory.
4
+ effect: read
5
+ agent: docs
6
+ outcomes: pass
7
+ ---
8
+ Read `FACTORY.md` (stage history, cycle counters, reason, carry) and the notes of the run's loops,
9
+ then write the run report to `.geneseed/factory-runs/<slug>.md` at the worktree root, `<slug>`
10
+ being the branch name after `loop/factory-`. First run `git check-ignore -q <that path>`: when it
11
+ exits non-zero the path is not ignored, so write the report to the OS temp directory instead.
12
+ The report holds the work item, the PR URL, every stage with its outcome, each rework and its
13
+ reason, and how the run ended (closed, or stopped and why).
14
+
15
+ Change nothing else: no tracked file, no commit. Only a lesson that will hold beyond this run —
16
+ a cause that will recur, a check this project lacks — goes into memory, one entry, under Persist
17
+ Insight; a fact about this run alone stays in the report. Report `pass` with the report's path.
@@ -15,7 +15,10 @@ brick only observes; a fix belongs in `apply`, not here.
15
15
  3. **Full suite** — only when everything above passed; otherwise `SKIPPED (an earlier check failed)`.
16
16
 
17
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.
18
+ or `SKIPPED (reason)` — one that did not run is never left out, and silence is never a pass. A
19
+ check this project does not have at all (no linter configured, no build step) is not skipped:
20
+ list it as `<check>: N/A (not configured)`. It neither passes nor blocks; never use it for a
21
+ check that exists but was not run.
19
22
  Write each failure as four lines: the check's purpose, the property it guards, a one-line
20
23
  diagnostic (not the raw log), and the command that reruns it alone. Keep full logs in a file.
21
24
  Write the list to a file in the OS temp directory (never inside the worktree) and report that
@@ -0,0 +1,19 @@
1
+ ---
2
+ name: triage
3
+ description: Pick the lane that fits the work item, from the lanes the factory offers, and say why.
4
+ effect: read
5
+ agent: explorer
6
+ outcomes: bug, feature, deps, refactor, docs, fail
7
+ ---
8
+ The stage hands you the work item's file as `carry` and the factory's lanes as `lanes`: each
9
+ outcome you may report, with the stage it leads to. Read the work item in full, then the code it
10
+ names. Pick the one outcome that fits: `bug` for a defect with a way to reproduce it, `feature`
11
+ for new behaviour, `deps` for a dependency to raise, `refactor` for a change of structure with no
12
+ change of behaviour, `docs` for a change to the documentation alone. Never report an outcome that
13
+ is not in `lanes`, and never edit any file.
14
+
15
+ Write a file in the OS temp directory, never inside the worktree: one paragraph on why the lane
16
+ fits and why the next-best one does not, then the work item copied in full, so the lane starts
17
+ from it. Report the outcome that names the lane, with that file's path. Report `fail` when no lane
18
+ fits the work item, or it mixes two kinds of work that need two runs — say which, in such a file,
19
+ and report its path.
@@ -1,7 +1,7 @@
1
1
  **{{PACK_COMMS}}** — how answers are presented.
2
2
 
3
- ### {{DOCTRINE:codes-that-persist}} Codes That Persist
4
- <!-- note: summary: Give tracked items stable reference codes; never renumber one. -->
3
+ ### {{DOCTRINE:codes-that-persist}} Codes and Markers
4
+ <!-- note: summary: Give tracked items stable codes, never renumbered; mark an ask that waits on the user. -->
5
5
  <!-- LEAN:begin -->
6
6
  Give every tracked item a short reference code and keep it unchanged for the rest of
7
7
  the session — `D` decisions, `O` options, `F` findings, `R` risks, `Q` questions,
@@ -15,16 +15,35 @@ for a kind the list omits, and never renumber a code once issued — the user wi
15
15
  it back, and a moved code makes their reply mean something you did not say. A code is an address, not an ornament:
16
16
  it lets a long exchange be answered by reference, and a decision taken on turn
17
17
  three still be named on turn thirty. Where the {{ONTOLOGY}}'s {{ONT_CONDUCT}}
18
- governs how an answer speaks, this is only the addressing convention — a practice
18
+ governs how an answer speaks, this is only the addressing and marking convention — a practice
19
19
  a repository adopts or drops like any other rule in these {{DOCTRINES}}.
20
+
21
+ When a reply stops and waits on the user — a question, a choice, an approval, a blocker —
22
+ make the ask stand apart from the work around it, so a reader who skims finds it first. Open
23
+ the ask with one emoji marker that names its kind: `❓` a question, `👉` an act the user must
24
+ do, `⚠️` a risk or a blocker, `✅` work done that waits on their sign-off. The marker comes
25
+ before the code: `❓ **Q3** — keep the v1 route?`. Lay out
26
+ the options and the flows with arrows — `→ yes: keep it · → no: remove it` — one option per
27
+ line past two, the recommended one first and named as such. Put one ask in each block; where
28
+ the answer to one question changes the next, ask them one at a time. Use colour only where
29
+ the surface renders it, such as markdown or a rich host; never write ANSI escapes or colour
30
+ markup into plain text that prints them raw. Routine output stays plain: a reply that waits
31
+ on nothing carries no marker, and a marker on every line marks nothing. The markers are
32
+ signs, not words, so the prose around them keeps {{DOCTRINE:simplified-technical-english}}.
33
+ Make the ask understood, not only seen. Before a command the user must run or approve, or a
34
+ question or a choice that is not clear by itself, write one or two plain lines: what it does,
35
+ why now, and what it changes or risks when that is not obvious. For a question, say what the
36
+ answer decides. An ask that is clear by itself stays bare: `ls`, or a yes/no question with no
37
+ stakes.
20
38
  <!-- LEAN:else -->
21
- Give every tracked item a short reference code, unchanged for the session —
22
- `D` decisions, `O` options, `F` findings, `R` risks, `Q` questions, `A` actions.
23
- Any reply naming two or more such items takes codes, a {{SKILL}}'s or {{AGENT}}'s
24
- report included; one item or none takes none. The code opens the line, never a bare
25
- `1.` or bullet: `**F1** — token logged in plain text`, `**Q2** — keep the v1 route?`
26
- Number from one within each kind and keep counting across turns (after `F3` comes
27
- `F4`), invent letters for missing kinds, never renumber a code once issued.
39
+ Give every tracked item a code that never changes in the session — `D` decisions, `O` options,
40
+ `F` findings, `R` risks, `Q` questions, `A` actions; invent letters for other kinds. A reply naming
41
+ two or more items codes them, reports included; the code opens the line:
42
+ `**F1** — token logged in plain text`. Count on across turns, never renumber. When a reply waits
43
+ on the user, open that ask with one marker before its code — `❓` question, `👉` act to do, `⚠️`
44
+ risk or blocker, `✅` done, waits on sign-off: `❓ **Q3** — keep the v1 route?`. One ask per block,
45
+ the recommended option first (`→`). An ask not clear alone gets one or two plain lines: what it
46
+ does, why now, what it risks or decides. Routine output stays plain; no raw ANSI.
28
47
  <!-- LEAN:end -->
29
48
 
30
49
  ### {{DOCTRINE:structure-beside-prose}} Structure Beside Prose
@@ -95,34 +114,3 @@ most in an instruction, 25 in a description. Instructions: imperative, one actio
95
114
  condition first. Active voice, no -ing forms, no dropped articles, one word per meaning
96
115
  (`use`, not `utilize`). In another language, keep it and these rules.
97
116
  <!-- LEAN:end -->
98
-
99
- ### {{DOCTRINE:mark-the-ask}} Mark the Ask
100
- <!-- note: summary: Mark an ask that waits on the user, and explain it when it is not clear alone; routine output stays plain. -->
101
- <!-- LEAN:begin -->
102
- When a reply stops and waits on the user — a question, a choice, an approval, a blocker —
103
- make the ask stand apart from the work around it, so a reader who skims finds it first. Open
104
- the ask with one emoji marker that names its kind: `❓` a question, `👉` an act the user must
105
- do, `⚠️` a risk or a blocker, `✅` work done that waits on their sign-off. The marker comes
106
- before the code ({{DOCTRINE:codes-that-persist}}): `❓ **Q3** — keep the v1 route?`. Lay out
107
- the options and the flows with arrows — `→ yes: keep it · → no: remove it` — one option per
108
- line past two, the recommended one first and named as such. Put one ask in each block; where
109
- the answer to one question changes the next, ask them one at a time. Use colour only where
110
- the surface renders it, such as markdown or a rich host; never write ANSI escapes or colour
111
- markup into plain text that prints them raw. Routine output stays plain: a reply that waits
112
- on nothing carries no marker, and a marker on every line marks nothing. The markers are
113
- signs, not words, so the prose around them keeps {{DOCTRINE:simplified-technical-english}}.
114
- Make the ask understood, not only seen. Before a command the user must run or approve, or a
115
- question or a choice that is not clear by itself, write one or two plain lines: what it does,
116
- why now, and what it changes or risks when that is not obvious. For a question, say what the
117
- answer decides. An ask that is clear by itself stays bare: `ls`, or a yes/no question with no
118
- stakes.
119
- <!-- LEAN:else -->
120
- When a reply waits on the user — a question, a choice, an approval, a blocker — mark the
121
- ask. Open it with one marker: `❓` question, `👉` act to do, `⚠️` risk or blocker, `✅` done,
122
- waits on sign-off; it comes before the code: `❓ **Q3** — keep the v1 route?`. Arrows (`→`)
123
- lay out options and flows, the recommended option first. One ask per block. Colour only
124
- where the host renders it, never raw ANSI in plain text. Routine output stays plain; markers
125
- are signs, not words. An ask that is not clear by itself carries one or two plain lines before
126
- it: what it does, why now, what it changes or risks; for a question, what the answer decides.
127
- A clear ask stays bare.
128
- <!-- LEAN:end -->
@@ -1,7 +1,7 @@
1
1
  **{{PACK_CRAFT}}** — how code is written.
2
2
 
3
3
  ### {{DOCTRINE:automate-repetition}} Automate Repetition
4
- <!-- note: summary: If it repeats, make it a script or skill; reuse first. -->
4
+ <!-- note: summary: If it repeats, automate it: script, skill or code, by the task. -->
5
5
  <!-- LEAN:begin -->
6
6
  When an action repeats, automate it — and choose the vessel by the nature of the task,
7
7
  not by how many similar steps one session needs. Do not
@@ -14,18 +14,13 @@ perform by hand what the machine can perform a thousand times.
14
14
  - a recurring, deterministic, exact operation (parsing, counting, API calls, anything
15
15
  run unattended or where a model would err) → kept, versioned code.
16
16
  Markdown is the default for what recurs; code is kept only where exactness or unattended
17
- automation demands it. When you build a {{SKILL}}, make it a vessel for one coherent
18
- domain — not a single command and not a grab-bag: seek an existing {{SKILL}} whose domain
19
- already covers the need and extend it before forging a new one, and name {{SKILLS}} by
20
- domain. Reuse before creating.
17
+ automation demands it.
21
18
  <!-- LEAN:else -->
22
19
  When an action repeats, automate it — choosing the vessel by the task, not the step
23
20
  count: a one-off batch gets a throwaway {{SCRIPT}} outside the repository, never kept; a
24
21
  recurring judgement procedure gets a markdown rule in the domain {{SKILL}} or {{AGENT}}
25
22
  spec; a recurring exact or unattended operation gets kept, versioned code. Markdown is
26
- the default for what recurs. Before forging a new {{SKILL}}, seek an existing one whose
27
- domain covers the need and extend it; build each {{SKILL}} for one coherent domain — not
28
- a single command, not a grab-bag — and name {{SKILLS}} by domain. Reuse before creating.
23
+ the default for what recurs.
29
24
  <!-- LEAN:end -->
30
25
 
31
26
  ### {{DOCTRINE:english-configuration}} English Configuration
@@ -58,11 +53,9 @@ drifts from the code is a defect, not a deferred task.
58
53
  <!-- LEAN:begin -->
59
54
  Before adding a file, module, function, or abstraction, confirm an equivalent
60
55
  does not already exist; prefer extending what is there. Duplication is a defect.
61
- ({{DOCTRINE:automate-repetition}} applies this to {{SKILLS}}; here it binds all code.)
62
56
  <!-- LEAN:else -->
63
57
  Before adding a file, module, function, or abstraction, confirm an equivalent does not
64
58
  already exist; prefer extending what is there. Duplication is a defect.
65
- ({{DOCTRINE:automate-repetition}} applies this to {{SKILLS}}; here it binds all code.)
66
59
  <!-- LEAN:end -->
67
60
 
68
61
  ### {{DOCTRINE:respect-conventions}} Respect Conventions
@@ -54,9 +54,7 @@ applied, yet did not endure. Before altering any configuration, ask which layer
54
54
  authoritative and write there alone. Persistence lives at the source, not the
55
55
  surface.
56
56
  <!-- LEAN:else -->
57
- Where a system renders live state from a source layer — a database the UI re-reads, a
58
- compose file regenerated from stored config — edit the source, never the rendered artifact.
59
- Before altering any configuration, ask which layer is authoritative and write there alone.
57
+ Edit the authoritative layer, never the rendered artifact.
60
58
  <!-- LEAN:end -->
61
59
 
62
60
  ### {{DOCTRINE:complete-the-teardown}} Complete the Teardown
@@ -85,9 +83,7 @@ citing it, this governs what to record in the first place: not the volatile valu
85
83
  but the means to derive it — the probe, the query, the live computation. Record
86
84
  how to check, and check at the hour of need.
87
85
  <!-- LEAN:else -->
88
- A fact that renews itself — a rotating certificate — is never inscribed as a snapshot.
89
- Record not the volatile value but the means to derive it — the probe, the query — and check
90
- at the hour of need ({{LAW:verify-before-asserting}}).
86
+ Record how to derive a volatile fact, never its value.
91
87
  <!-- LEAN:end -->
92
88
 
93
89
  ### {{DOCTRINE:restart-is-not-reload}} Restart Is Not Reload
@@ -103,10 +99,7 @@ recreate, down-and-up, reload, or full restart — perform it, then confirm the
103
99
  value in the *running* system, not the file ({{LAW:verify-before-asserting}}). A correct file above a
104
100
  stale process looks like a finished job and is not one.
105
101
  <!-- LEAN:else -->
106
- A running process holds the config it read at start. After editing any config, ask what act
107
- makes it be *read* — often not a restart. Establish which — recreate, down-and-up, reload,
108
- full restart — perform it, then confirm the new value in the *running* system, not the file
109
- ({{LAW:verify-before-asserting}}).
102
+ After a config edit, confirm the new value in the running process, not the file.
110
103
  <!-- LEAN:end -->
111
104
 
112
105
  ### {{DOCTRINE:serialize-against-a-rationed-resource}} Serialize Against a Rationed Resource
@@ -124,9 +117,5 @@ unchanged on retry is a hard limit, not transient backpressure: stop and report
124
117
  batches independent calls, this names the calls that are not independent — they draw on
125
118
  one allowance. A smaller complete sample beats a larger one gathered through failures.
126
119
  <!-- LEAN:else -->
127
- A shared resource that rations its answers — a rate-limited API, a quota, a single
128
- gateway — is called in sequence, never fanned out. Before any parallelism, divide the
129
- quota by its callers; if one share cannot finish the work, do not parallelise. Back off on
130
- each refusal, within a retry cap set first. A refusal repeating unchanged is a hard limit:
131
- stop and report it ({{LAW:surface-failures}}), never re-send the batch.
120
+ Call a rationed resource in sequence; a repeated refusal is a hard limit — stop and report.
132
121
  <!-- LEAN:end -->
@@ -1,18 +1,20 @@
1
1
  **{{PACK_PROCESS}}** — how a task is run.
2
2
 
3
3
  ### {{DOCTRINE:persist-insight}} Persist Insight
4
- <!-- note: summary: Durable decisions are recorded before the session ends — and rule or memory is the user's call. -->
4
+ <!-- note: summary: Durable insight is recorded before the session ends — memory on your own, a standing rule only with the user. -->
5
5
  <!-- LEAN:begin -->
6
6
  When a session yields a durable decision, correction, non-obvious discovery, or
7
- architectural stance, record it before the session ends — through the rule {{SKILL}},
8
- which settles with the user whether it belongs in {{MEMORY}} or as a standing rule,
9
- never on your own initiative. No valuable insight perishes at session's end, and which
10
- store holds it is the user's call, never yours.
7
+ architectural stance, record it before the session ends. A durable fact goes into
8
+ {{MEMORY}} on your own, with no prompt: the user sees every memory later in the web
9
+ console. A standing rule binds every later session, so it is the user's call: take it to
10
+ them through the rule {{SKILL}}. A memory phrased as an instruction to later sessions
11
+ ("always…", "never…", `force: constraint`) is a standing rule.
11
12
  <!-- LEAN:else -->
12
13
  When a session yields a durable decision, correction, non-obvious discovery, or
13
- architectural stance, record it before it ends — through the rule {{SKILL}}, which settles
14
- with the user whether it belongs in {{MEMORY}} or a standing rule, never on your own
15
- initiative.
14
+ architectural stance, record it before it ends: a durable fact into {{MEMORY}} on your
15
+ own (the user sees it in the web console); a standing rule, which includes
16
+ any instruction to later sessions ("always…", "never…", `force: constraint`), only through
17
+ the rule {{SKILL}}, with the user's consent.
16
18
  <!-- LEAN:end -->
17
19
 
18
20
  ### {{DOCTRINE:plan-before-acting}} Plan Before Acting
@@ -92,9 +94,10 @@ stands for commits on that branch until the session ends or the scope changes; a
92
94
  new session, a new branch, or a widened scope re-asks. Push earns no such default
93
95
  and stays per-ask unless granted in the same named form. A launched loop's batch
94
96
  covers commit and push on its own `loop/*` branch; merging that branch into a
95
- shared one never is. Before each, present in
96
- order (1) a plain-language summary of what changed and why and (2) the exact
97
- commit message you intend to use, then wait. Never push on your own initiative.
97
+ shared one never is. A Foreman worker's batch covers commit and merge in its own
98
+ worktree, off any shared branch. Before each, present in order (1) a plain-language
99
+ summary of what changed and why and (2) the exact commit message you intend to use,
100
+ then wait. Never push on your own initiative.
98
101
  On a **shared branch** — `main`, `master`, `develop`, `development`, a
99
102
  `release`/`hotfix` branch, or anything that is not a dedicated feature branch —
100
103
  the same gate applies with extra care; when unsure, treat the branch as shared.
@@ -104,14 +107,16 @@ through the git-history {{SKILL}} behind a backup. The host gates commit and pus
104
107
  the tool boundary too, so this consent cannot be lost to a sticky allowlist.
105
108
  <!-- LEAN:else -->
106
109
  Recording and sharing code is consented, never unilateral: **every** `git commit` and
107
- `git push` needs **explicit acceptance**, every branch, every time; one-time approval is
108
- not standing consent. A named batch ("commit as you go") stands until the session ends or
109
- scope changes; push earns no default. A launched loop's batch covers commit and push on
110
- its own `loop/*` branch only; merging it never. Show the plain summary and the exact
111
- commit message before each, then wait. Shared branches — `main`, `master`, `develop`,
112
- `development`, `release`/`hotfix`, any unsure — take the same gate. Never force-push,
113
- hard-reset, or rebase one: undo with a revert commit (git-history {{SKILL}} for a
114
- legitimate rewrite). The host gates both at the tool boundary.
110
+ `git push` needs **explicit acceptance**, every branch, every time — a personal feature
111
+ branch included; one-time approval is not standing consent. A named batch ("commit as
112
+ you go") stands until the session ends or scope changes; push earns no default. Never
113
+ push on your own initiative. A launched loop's batch covers commit and push on its own
114
+ `loop/*` branch only; merging it never. A Foreman worker's covers commit and merge in its
115
+ own worktree, off any shared branch. Show the plain summary and the exact commit message
116
+ before each, then wait. Shared branches — `main`, `master`, `develop`, `development`,
117
+ `release`/`hotfix`, any unsure — take the same gate. Never force-push, hard-reset, or
118
+ rebase one: undo with a revert commit (git-history {{SKILL}} for a legitimate rewrite).
119
+ The host gates both at the tool boundary.
115
120
  <!-- LEAN:end -->
116
121
 
117
122
  ### {{DOCTRINE:bound-the-loop}} Bound the Loop
@@ -103,9 +103,5 @@ confused, or steered by untrusted input ({{LAW:data-not-orders}}). Where {{LAW:l
103
103
  power you take, this governs the power you hand out; {{DOCTRINE:prove-the-gate}} proves the
104
104
  gate once it stands.
105
105
  <!-- LEAN:else -->
106
- Wherever a system lets an agent act, ask approval of a party it cannot satisfy alone,
107
- enforce the allowlist at the boundary the call must cross, and validate against real state.
108
- Never let permission live in the governed agent's own prompt. Ship anything taking
109
- autonomous control of physical state, money, or production disarmed, armed only by explicit
110
- human act ({{LAW:data-not-orders}}).
106
+ Permission lives at a boundary the agent cannot satisfy alone; autonomous control ships disarmed.
111
107
  <!-- LEAN:end -->