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
@@ -0,0 +1,34 @@
1
+ {
2
+ "name": "analysis-to-build",
3
+ "description": "Turn an analysis (a document, pasted text or a request) into a spec whose task list you approve, build each task in turn with the feature loop in one worktree, play the holdout scenarios it never saw, then open one pull request and wait for green CI; a failed scenario or red CI sends the work back to the loop as one more task, twice at most each. The merge stays yours.",
4
+ "category": "development",
5
+ "rules": [
6
+ "Never merge, and never enable auto-merge: the run ends at an open PR with green CI.",
7
+ "Push only this worktree's own branch."
8
+ ],
9
+ "stages": ["intake", "spec", "holdout-write", "loop:feature", "holdout", "pr-open", "merge-gate", "retro"],
10
+ "start": "intake",
11
+ "edges": [
12
+ { "from": "intake", "on": "pass", "to": "spec" },
13
+ { "from": "intake", "on": "fail", "to": "$stop" },
14
+ { "from": "spec", "on": "pass", "to": "holdout-write" },
15
+ { "from": "spec", "on": "fail", "to": "$stop" },
16
+ { "from": "holdout-write", "on": "pass", "to": "loop:feature" },
17
+ { "from": "holdout-write", "on": "fail", "to": "$stop" },
18
+ { "from": "loop:feature", "on": "pass", "to": "holdout" },
19
+ { "from": "loop:feature", "on": "fail", "to": "$stop" },
20
+ { "from": "holdout", "on": "pass", "to": "pr-open" },
21
+ { "from": "holdout", "on": "fail", "to": "loop:feature" },
22
+ { "from": "holdout", "on": "error", "to": "$stop" },
23
+ { "from": "pr-open", "on": "pass", "to": "merge-gate" },
24
+ { "from": "pr-open", "on": "fail", "to": "$stop" },
25
+ { "from": "merge-gate", "on": "pass", "to": "retro" },
26
+ { "from": "merge-gate", "on": "fail", "to": "loop:feature" },
27
+ { "from": "merge-gate", "on": "none", "to": "retro" },
28
+ { "from": "retro", "on": "pass", "to": "$close" }
29
+ ],
30
+ "cycles": [
31
+ { "name": "holdout", "nodes": ["loop:feature", "holdout"], "max": 2 },
32
+ { "name": "ci", "nodes": ["loop:feature", "holdout", "pr-open", "merge-gate"], "max": 2 }
33
+ ]
34
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "name": "bug-report-to-fix",
3
+ "description": "Take one bug report, fix it with the bugfix loop, play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed scenario or red CI sends the fix back to the loop, twice at most each. The merge stays yours.",
4
+ "category": "development",
5
+ "rules": [
6
+ "Never merge, and never enable auto-merge: the run ends at an open PR with green CI.",
7
+ "Push only this worktree's own branch."
8
+ ],
9
+ "stages": ["intake", "holdout-write", "loop:bugfix", "holdout", "pr-open", "merge-gate", "retro"],
10
+ "start": "intake",
11
+ "edges": [
12
+ { "from": "intake", "on": "pass", "to": "holdout-write" },
13
+ { "from": "intake", "on": "fail", "to": "$stop" },
14
+ { "from": "holdout-write", "on": "pass", "to": "loop:bugfix" },
15
+ { "from": "holdout-write", "on": "fail", "to": "$stop" },
16
+ { "from": "loop:bugfix", "on": "pass", "to": "holdout" },
17
+ { "from": "loop:bugfix", "on": "fail", "to": "$stop" },
18
+ { "from": "holdout", "on": "pass", "to": "pr-open" },
19
+ { "from": "holdout", "on": "fail", "to": "loop:bugfix" },
20
+ { "from": "holdout", "on": "error", "to": "$stop" },
21
+ { "from": "pr-open", "on": "pass", "to": "merge-gate" },
22
+ { "from": "pr-open", "on": "fail", "to": "$stop" },
23
+ { "from": "merge-gate", "on": "pass", "to": "retro" },
24
+ { "from": "merge-gate", "on": "fail", "to": "loop:bugfix" },
25
+ { "from": "merge-gate", "on": "none", "to": "retro" },
26
+ { "from": "retro", "on": "pass", "to": "$close" }
27
+ ],
28
+ "cycles": [
29
+ { "name": "holdout", "nodes": ["loop:bugfix", "holdout"], "max": 2 },
30
+ { "name": "ci", "nodes": ["loop:bugfix", "holdout", "pr-open", "merge-gate"], "max": 2 }
31
+ ]
32
+ }
@@ -0,0 +1,49 @@
1
+ {
2
+ "name": "issue-to-pr",
3
+ "description": "Take one issue, let triage pick the lane that fits (the bugfix, feature, deps-upgrade or refactor loop, or a docs-only update), play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed scenario or red CI sends the work back to that lane, twice at most each. The merge stays yours.",
4
+ "category": "development",
5
+ "rules": [
6
+ "Never merge, and never enable auto-merge: the run ends at an open PR with green CI.",
7
+ "Push only this worktree's own branch."
8
+ ],
9
+ "stages": [
10
+ "intake", "holdout-write", "triage",
11
+ "loop:bugfix", "loop:feature", "loop:deps-upgrade", "loop:refactor", "docs-update",
12
+ "holdout", "pr-open", "merge-gate", "retro"
13
+ ],
14
+ "start": "intake",
15
+ "edges": [
16
+ { "from": "intake", "on": "pass", "to": "holdout-write" },
17
+ { "from": "intake", "on": "fail", "to": "$stop" },
18
+ { "from": "holdout-write", "on": "pass", "to": "triage" },
19
+ { "from": "holdout-write", "on": "fail", "to": "$stop" },
20
+ { "from": "triage", "on": "bug", "to": "loop:bugfix" },
21
+ { "from": "triage", "on": "feature", "to": "loop:feature" },
22
+ { "from": "triage", "on": "deps", "to": "loop:deps-upgrade" },
23
+ { "from": "triage", "on": "refactor", "to": "loop:refactor" },
24
+ { "from": "triage", "on": "docs", "to": "docs-update" },
25
+ { "from": "triage", "on": "fail", "to": "$stop" },
26
+ { "from": "loop:bugfix", "on": "pass", "to": "holdout" },
27
+ { "from": "loop:bugfix", "on": "fail", "to": "$stop" },
28
+ { "from": "loop:feature", "on": "pass", "to": "holdout" },
29
+ { "from": "loop:feature", "on": "fail", "to": "$stop" },
30
+ { "from": "loop:deps-upgrade", "on": "pass", "to": "holdout" },
31
+ { "from": "loop:deps-upgrade", "on": "fail", "to": "$stop" },
32
+ { "from": "loop:refactor", "on": "pass", "to": "holdout" },
33
+ { "from": "loop:refactor", "on": "fail", "to": "$stop" },
34
+ { "from": "docs-update", "on": "pass", "to": "holdout" },
35
+ { "from": "holdout", "on": "pass", "to": "pr-open" },
36
+ { "from": "holdout", "on": "fail", "to": "$lane" },
37
+ { "from": "holdout", "on": "error", "to": "$stop" },
38
+ { "from": "pr-open", "on": "pass", "to": "merge-gate" },
39
+ { "from": "pr-open", "on": "fail", "to": "$stop" },
40
+ { "from": "merge-gate", "on": "pass", "to": "retro" },
41
+ { "from": "merge-gate", "on": "fail", "to": "$lane" },
42
+ { "from": "merge-gate", "on": "none", "to": "retro" },
43
+ { "from": "retro", "on": "pass", "to": "$close" }
44
+ ],
45
+ "cycles": [
46
+ { "name": "holdout", "nodes": ["$lane", "holdout"], "max": 2 },
47
+ { "name": "ci", "nodes": ["$lane", "holdout", "pr-open", "merge-gate"], "max": 2 }
48
+ ]
49
+ }
@@ -0,0 +1,10 @@
1
+ ### CI pipelines kit
2
+
3
+ Applies to Jenkins pipelines (declarative `Jenkinsfile`, shared libraries) and GitLab CI (`.gitlab-ci.yml` and its includes). Read the pipeline file and everything it loads before changing it.
4
+
5
+ - One source of truth: the pipeline lives in the repository's pipeline file and the libraries or includes it pins. No job configured by hand in the CI's web UI, no second copy of a step in another file.
6
+ - Secrets come only from the CI's own store (Jenkins credentials, GitLab masked and protected variables). Never in the pipeline file, a commit, a parameter default or the build log.
7
+ - Pin images, tools and shared code: image tags or digests, never `latest`; a fixed tool version; a library or include at a tag, never a moving branch.
8
+ - Fast feedback first: lint and unit tests run early and in parallel; slow stages wait on them.
9
+ - GitLab job conditions use `rules:`; Jenkins logic beyond declarative syntax goes into a tested shared-library step.
10
+ - Lint the pipeline before pushing, then prove the change with a real branch run, read from its log.
@@ -0,0 +1,14 @@
1
+ {
2
+ "description": "CI pipelines on Jenkins (declarative Jenkinsfile, shared libraries) and GitLab CI (.gitlab-ci.yml): job conditions, stage order, reuse, credentials, caching, testing the pipeline itself.",
3
+ "skills": ["jenkins-pipeline", "gitlab-ci"],
4
+ "agents": [],
5
+ "rules": "kits/ci-pipelines/rules.md",
6
+ "rulesWordBudget": 300,
7
+ "banned": ["only:", "except:"],
8
+ "catalogue": {
9
+ "skills": [
10
+ "| [jenkins-pipeline]({{DIR_SKILLS}}/jenkins-pipeline.md) | writing or fixing a declarative Jenkinsfile or a shared library: stages, when, parallel, credentials, CPS and @NonCPS, sandbox approval, JenkinsPipelineUnit tests |",
11
+ "| [gitlab-ci]({{DIR_SKILLS}}/gitlab-ci.md) | writing or fixing .gitlab-ci.yml: rules, needs, include and extends, cache and artifacts, protected and masked variables, environments, CI lint |"
12
+ ]
13
+ }
14
+ }
@@ -0,0 +1,11 @@
1
+ ### Docker kit
2
+
3
+ Applies to Docker images and Compose stacks. Run `docker compose config` and read the merged result before changing a stack.
4
+
5
+ - Pin every image to a version tag or a digest. Never `latest`, never an untagged image.
6
+ - Order startup by health: `depends_on` with `condition: service_healthy` on a real readiness check.
7
+ - State lives in named volumes. Never run `docker compose down -v` or prune volumes on a stack with data without a backup and an explicit go-ahead.
8
+ - No secret in an image layer, a build argument, the Compose file or a committed `.env`; use Compose `secrets:` or the runtime environment from a git-ignored file.
9
+ - Images run as a non-root user, built multi-stage, with a `.dockerignore`.
10
+ - Every long-running service has a restart policy, resource limits and capped logs.
11
+ - Before an update, know the rollback target (the previous tag or digest); confirm the new container is healthy before pruning the old image.
@@ -0,0 +1,12 @@
1
+ {
2
+ "description": "Docker and Compose operations for any stack: health-ordered startup, volumes, pinned images, env and secrets, restart, limits, logging, networks, lean non-root images, safe updates and rollback.",
3
+ "skills": ["compose-ops"],
4
+ "agents": [],
5
+ "rules": "kits/docker/rules.md",
6
+ "rulesWordBudget": 300,
7
+ "catalogue": {
8
+ "skills": [
9
+ "| [compose-ops]({{DIR_SKILLS}}/compose-ops.md) | writing, reviewing or operating a Compose stack or a generic Dockerfile: healthchecks, volumes, image pins, secrets, limits, logs, networks, safe update and rollback |"
10
+ ]
11
+ }
12
+ }
@@ -8,10 +8,11 @@
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,
11
- and opens the topic file a task needs (see *The index* below). A new fact is written through the rule {{SKILL}}, which settles with the user
12
- whether it is a fact for here or a standing rule ({{DOCTRINE:persist-insight}}) — never on the
13
- agent's own initiative. The one automatic writer is the `learn` hook, where the host
14
- runs it: a distiller the user opted into at install, not an agent's judgement call.
11
+ and opens the topic file a task needs (see *The index* below). The agent writes a new fact
12
+ here on its own, with no prompt, following Branch A of the rule {{SKILL}}; the user sees every
13
+ memory afterwards in the web console ({{DOCTRINE:persist-insight}}). A standing rule is different:
14
+ it goes to the user first, through the same {{SKILL}}. The `learn` hook writes here too, where the
15
+ host runs it: a distiller the user opted into at install.
15
16
 
16
17
  This store is for **curated facts**, written for recall. For freeform working space
17
18
  the agent shapes for itself — plans, scratch designs, working theories, with no
@@ -15,12 +15,24 @@ task that would block it to one background task worker, and keeps answering the
15
15
  and the brief carries the approved decisions.
16
16
  - **One worker per task.** Dispatch one developer {{AGENT}} in the background, in its own
17
17
  worktree. The brief carries the task as the user stated it, BASE, the write set, the
18
- proof commands, and the rule that it never commits, pushes or merges. The worker
19
- explores, implements and tests in its own context, loading {{SKILLS}} as it needs them;
20
- after two repair rounds on its own red tests it returns red with its findings
21
- ({{DOCTRINE:bound-the-loop}}). It dispatches no {{AGENTS}}, except a read-only explorer
22
- when its own context would overflow. Check its write set against every task in flight
18
+ proof commands, and the rule that it never pushes and never merges outside its own
19
+ branch. The worker explores, implements and tests in its own context, loading {{SKILLS}}
20
+ as it needs them; after two repair rounds on its own red tests it returns red with its
21
+ findings ({{DOCTRINE:bound-the-loop}}). Check its write set against every task in flight
23
22
  ({{DOCTRINE:one-writer-per-file}}).
23
+ - **A worker may lead, inside its worktree.** It may dispatch read-only helpers (explorer,
24
+ researcher) at any time, and writing sub-workers, each in its own worktree branched from
25
+ its branch. It may commit and merge their branches into its own, locally, and re-runs the
26
+ proof after each merge. Depth stops at main → worker → sub-worker: a sub-worker
27
+ dispatches nothing. Every lead holds every member's result before it ends. The blind
28
+ reviewer stays the parent's.
29
+ - **Status, one line per change.** A worker reports
30
+ `T<n> · <task> · files: <write set> · <state>` at start and on each change: by
31
+ `SendMessage` to the parent on Claude Code (on OpenClaude only in its agent-teams mode);
32
+ elsewhere in its own `{{DIR_NOTEBOOK}}/foreman/<task>.status`, one line it alone writes.
33
+ Read all status files with one command, only before dispatching near the same files and
34
+ when a worker returns, never every turn. On an overlap, one waits or one owns the file;
35
+ record the ruling in the ledger.
24
36
  - **Verify non-trivial diffs blind.** When a worker returns green with a diff that touches
25
37
  two or more files or changes logic, dispatch a reviewer (a tester for test-heavy work)
26
38
  with only the original ask and the diff, never the worker's reasoning. A failing verdict
@@ -36,11 +48,12 @@ task that would block it to one background task worker, and keeps answering the
36
48
  worker serves one task and retires when that task is merged or dropped.
37
49
  - **Isolate.** Each worker works in its own git worktree/branch; falls back to a single
38
50
  tree, one worker at a time, when worktrees are unavailable.
39
- - **Merge on proof you re-ran.** A worker hands back its worktree, uncommitted, with raw
40
- test + lint output. The parent re-runs those commands itself — a worker's log is the
41
- worker's account, not the state — shows the user the diff and the green output, and
42
- commits and merges only once the user accepts ({{DOCTRINE:consent-before-push}}). Commit,
43
- push and merge stay the parent's alone.
51
+ - **Merge on proof you re-ran.** A worker hands back its branch, its local commits and any
52
+ uncommitted work, with raw test + lint output. The parent re-runs those commands itself —
53
+ a worker's log is the worker's account, not the state — shows the user the diff from BASE
54
+ and the green output, and commits and merges only once the user accepts
55
+ ({{DOCTRINE:consent-before-push}}). Push, and every merge beyond a worker's own branch,
56
+ stay the parent's alone.
44
57
  - **Report and watch.** Surface completions, failures, and merges to the user as they
45
58
  happen; a worker that returns no proof, or goes silent, is handled as the pipeline
46
59
  {{SKILL}}'s step 2 says for a crew.
@@ -32,7 +32,7 @@ will, in whatever structure serves you.
32
32
  the host tree. The host tree receives only the
33
33
  deliverables of the task.
34
34
  - **Promote what hardens.** When something here crystallises into a durable
35
- fact worth recalling verbatim, propose it for {{MEMORY}} through the rule {{SKILL}}
35
+ fact worth recalling verbatim, write it to {{MEMORY}}
36
36
  ({{DOCTRINE:persist-insight}}).
37
37
  - **It is not the repo's.** Do not keep here what the repository already
38
38
  records (code, git history, the {{LAWS}}, `user-rules.md`). Keep what is
@@ -15,6 +15,7 @@ These rules hold for every checkpoint this {{SKILL}} raises.
15
15
  !/.gitignore
16
16
  !/bricks/
17
17
  !/loops/
18
+ !/factories/
18
19
  !/protected-checks.txt
19
20
  !/done-checks.txt
20
21
  ```
@@ -9,12 +9,14 @@ write, and no rebuild touches them.
9
9
  Close each run with one beat of reflection on the {{SKILL}} itself:
10
10
  - A step misled, a needed step was missing, or the trigger fired wrongly — that
11
11
  is a flaw in this file. Write the exact correction (trigger, procedure, or
12
- done-when) into the notes file, with the user's assent ({{LAW:one-intent-one-act}}), as one line:
13
- `- [skill|general] <correction> — seen: <what happened, against what you expected> (<date>)`.
14
- `seen:` is the evidence the correction is later judged by; `general` marks one
15
- that would fix other {{SKILLS}} too. Never
12
+ done-when) into the notes file on your own, with no prompt, as one line:
13
+ `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what you expected> (<date>)`.
14
+ `situation:` bounds where the correction holds; `seen:` is the evidence it is
15
+ later judged by; `general` marks one that would fix other {{SKILLS}} too. Never
16
16
  edit this file: it is a rendered copy, a rebuild overwrites it, and the doctor
17
- reports the edit as drift. `geneseed diff` carries the notes back to the source.
17
+ reports the edit as drift. `geneseed diff` carries the notes back to the source;
18
+ folding a note into the source is the user's call, through the skill-forge
19
+ {{SKILL}} ({{LAW:one-intent-one-act}}).
18
20
  - Keep the notes sharp: amend or delete a line before adding one — a line with no
19
21
  `seen:`, or whose `seen:` no longer happens, goes first — and prune past about
20
22
  twenty lines.
@@ -26,10 +28,11 @@ Close each run with one beat of reflection on the {{SKILL}} itself:
26
28
  runs end here.
27
29
  <!-- LEAN:else -->
28
30
  One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or a
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 `{{PATH_NOTES}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
31
- name) as `- [skill|general] <correction> — seen: <what happened vs expected> (<date>)`,
32
- never into this rendered file, which a rebuild overwrites. Read that notes
31
+ wrong trigger is a flaw in this file — write the exact correction on your own, with no
32
+ prompt, into `{{PATH_NOTES}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
33
+ name) as `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened vs expected> (<date>)`,
34
+ never into this rendered file, which a rebuild overwrites. Folding a note into the
35
+ source is the user's call ({{LAW:one-intent-one-act}}). Read that notes
33
36
  file before the first step when it exists; it wins where it disagrees. Keep it short.
34
37
  A lesson that is not about this file goes to {{MEMORY}} only if it clears
35
38
  {{DOCTRINE:persist-insight}}'s bar. Nothing learned — move on.
@@ -13,7 +13,7 @@
13
13
  **Precedence.** This mode shapes *presentation* only. The harness file itself — the {{LAWS}}, `user-rules.md`, the active doctrines (the comms ones above all) — outranks it; where they collide, the rule wins and the shape stays. The known collisions resolve so:
14
14
  - **Readiness sigil.** On a session's first reply the sigil stays the first line; the next action leads right after it.
15
15
  - **Cap at five** (step 9) groups and orders what is shown — it never renumbers, merges or drops a {{DOCTRINE:codes-that-persist}} code; an item gets its code when it is first shown, and a code once shown is never dropped.
16
- - **The closing next action** (step 3) takes the {{DOCTRINE:mark-the-ask}} form — `👉` for an act to do, `❓` for a question, one ask per block.
16
+ - **The closing next action** (step 3) takes the {{DOCTRINE:codes-that-persist}} form — `👉` for an act to do, `❓` for a question, one ask per block.
17
17
  - **No recap** (step 10) never deletes the verification command and its output owed by {{LAW:verify-before-asserting}}, nor the judgment calls owed by {{DOCTRINE:declare-the-judgment-calls}} — those are evidence, not recap.
18
18
  - **Harness duties** outrank brevity: announce a tool call when the host requires it, do the work rather than asking "want me to?", and point time estimates at whoever runs the steps.
19
19
 
@@ -0,0 +1,58 @@
1
+ # {{SKILL}}: compose-ops
2
+
3
+ > {{DESC_COMPOSE_OPS}}
4
+
5
+ {{CREDIT:everything-claude-code:skills/docker-patterns/SKILL.md}}
6
+
7
+ **Trigger:** writing, reviewing or operating a `compose.yaml` (or `docker-compose.yml`) stack, or a generic Dockerfile for it: startup order, health, volumes, image pins, env and secrets, restart, limits, logs, networks, image size and user, or an update that must be safe to roll back. Stack-agnostic. A Spring Boot service's own image (Buildpacks, layered or native jar) belongs to the spring-boot kit's `docker-expert` agent when that kit is on, and so does that service's local-dev Compose file; this skill owns how every other stack is composed and run.
8
+
9
+ ## Working loop
10
+ 1. Read the Compose file, every `-f` override and `.env` it uses, then the merged result: `docker compose config`. It resolves variables, merges overrides and fails on a bad key.
11
+ 2. Check what runs now before changing it: `docker compose ps`, `docker compose images` (the real tags and digests), `docker compose logs --tail=100 <svc>`.
12
+ 3. Change, `docker compose config` again, then apply and confirm each changed service is `healthy` (or, for a service with no healthcheck, `running` with clean logs).
13
+
14
+ ## Startup order and health
15
+ - `depends_on: { db: { condition: service_healthy } }` waits for the dependency's healthcheck. A bare `depends_on: [db]` waits only for the container to start, not for the database to accept connections.
16
+ - Give every service others depend on a `healthcheck:` that tests readiness: `test: ["CMD", "pg_isready", "-U", "app"]`, with `interval`, `timeout`, `retries` and a `start_period` long enough for a cold start. The command must exist in the image; a missing `curl` makes the check fail forever.
17
+ - `condition: service_completed_successfully` for a one-shot job (a migration) that must finish first.
18
+
19
+ ## Volumes
20
+ | Use | Mount |
21
+ |---|---|
22
+ | Data the service owns (database, uploads) | named volume: `pgdata:/var/lib/postgresql/data`, declared under top-level `volumes:` |
23
+ | Config or source you edit on the host | bind mount, read-only where possible: `./nginx.conf:/etc/nginx/nginx.conf:ro` |
24
+ | Scratch that must not persist | `tmpfs:` |
25
+
26
+ - A named volume survives `down` and keeps Docker-managed permissions; a bind mount takes the host path's owner and breaks a non-root container whose UID does not match.
27
+ - `docker compose down -v` deletes named volumes, which is data loss. Never run it on a stack with state unless deleting the data is the intent and a backup exists.
28
+ - An anonymous volume (a container path with no name) carries over when `up` recreates the container, but is orphaned after `down` then `up`, or with `up -V` (`--renew-anon-volumes`), and its data is no longer mounted; name it.
29
+
30
+ ## Images
31
+ - Pin every `image:` to a version tag (`postgres:16.4`), and to a digest (`postgres:16.4@sha256:...`) where the stack must reproduce exactly. Never `latest` and never no tag: an update must be a change in the file.
32
+ - Your own images: multi-stage builds, so the final stage carries only the runtime and the built output, not compilers or dev dependencies. Start from a slim or distroless base, and add a `.dockerignore` (`.git`, `node_modules`, build output, `.env`).
33
+ - Run as a non-root user: `USER app` in the Dockerfile, or `user: "1000:1000"` in Compose. Add `read_only: true` with a `tmpfs:` for write paths, `cap_drop: [ALL]` and `security_opt: ["no-new-privileges:true"]` where the service allows.
34
+
35
+ ## Env and secrets
36
+ - `.env` holds non-secret settings and the values the file interpolates (`${TAG:?set TAG}` fails loudly when unset). It is git-ignored; commit a `.env.example` with placeholders instead.
37
+ - Secrets go in `secrets:` (a file outside the repository, mounted at `/run/secrets/<name>`), read by images that support `*_FILE` variables (`POSTGRES_PASSWORD_FILE`). An `environment:` secret shows in `docker inspect` and in every child process.
38
+ - Never bake a secret into an image: `ARG`/`ENV` values stay in the layer history. Use `RUN --mount=type=secret,id=...` for a build-time secret.
39
+
40
+ ## Running: restart, limits, logs
41
+ - `restart: unless-stopped` for long-running services; `restart: "no"` for one-shot jobs. A service that crash-loops hides its error behind restarts: read `docker compose logs` before raising retries.
42
+ - Set limits so one service cannot starve the host: `deploy: { resources: { limits: { cpus: "1.0", memory: 512M } } }`, or `mem_limit:` on older engines. A JVM or Node process also needs its heap capped below the limit.
43
+ - Cap logs: `logging: { driver: json-file, options: { max-size: "10m", max-file: "3" } }` (or `local`). The default json-file driver grows until the disk is full.
44
+
45
+ ## Networks
46
+ - Services reach each other by service name on the stack's default network; never hard-code container IPs.
47
+ - Split networks by trust: a `frontend` network for the proxy and the app, a `backend` network with `internal: true` for the database, which then has no route out and no published port.
48
+ - Publish only the ports users reach, bound to an address where possible: `"127.0.0.1:5432:5432"` for a local-only database. A published port bypasses host firewall rules on most Linux setups.
49
+
50
+ ## Safe updates
51
+ 1. Record the current state: the running image digests (`docker compose images`) and the committed Compose file. Back up the named volumes of a stateful service before an update that may migrate its data.
52
+ 2. Change the pinned tag in the file, then `docker compose pull <svc>`.
53
+ 3. `docker compose up -d <svc>` recreates only the services whose image or configuration changed. Add `--wait` (with `--wait-timeout <seconds>`) to block until they are running or healthy; `--wait` only proves health for a service that has a healthcheck, so give one to every service you update.
54
+ 4. Check health and logs. Roll back by restoring the previous tag or digest and running `up -d` again; a data migration the new version ran may not roll back, which is why step 1 takes the backup.
55
+ 5. Prune old images only after the new version has proved itself: `docker image prune -a` deletes every image no container uses, the rollback target included (plain `docker image prune` removes only dangling images).
56
+
57
+ ## Done when
58
+ - `docker compose config` accepts the merged file, every changed service with a healthcheck reports `healthy` and the others are `running` with clean logs, images are pinned, no secret sits in the file, an image or `environment:`, and the rollback target (the previous tag or digest, and a backup for stateful data) is known.
@@ -0,0 +1,97 @@
1
+ # {{SKILL}}: factory-forge
2
+
3
+ > {{DESC_FACTORY_FORGE}}
4
+
5
+ **Trigger:** the user wants a new factory, or to change one. For example: "make a factory that
6
+ takes a feature request to a PR", "add a security scan before the PR opens", "send red CI back
7
+ to the loop three times, not two".
8
+
9
+ ## Procedure
10
+
11
+ 1. **See what exists:** `geneseed factory list` (the factories) and `geneseed loop check` (every
12
+ brick with its outcomes, and every loop template). Adapting a factory starts from its file.
13
+ 2. **Interview, one question at a time:**
14
+ - **name** — kebab-case, the file stem. A factory named like an existing one replaces it at
15
+ every level below; say so to the user.
16
+ - **what it does** — one line; it becomes `description`. A short `category` (`development`).
17
+ - **input** — what one run takes: a request, a document, or a GitHub or GitLab issue. The
18
+ first stage reads it, usually `intake`.
19
+ - **stages**, in order — each a brick name or `loop:<template>` (a whole loop: outcomes `pass`
20
+ and `fail`).
21
+ - **forks** — where the work takes one way or another, use a brick with named outcomes (a
22
+ **fork**, such as `triage`: `bug`, `feature`, `deps`, `refactor`, `docs`, `fail`). Give each
23
+ named outcome its own edge to its own **lane**: a loop for work that changes code, or a brick
24
+ where a loop adds nothing (`docs` → `docs-update`). Every lane joins the same path after it
25
+ (`holdout`, then `pr-open` and `merge-gate`). An outcome the factory does not offer goes to
26
+ `$stop`.
27
+ - **where a human gates** — a gate belongs to the brick (`gate: human` in its frontmatter,
28
+ narrowed by `gateOn`), never to the factory. A stage that must hold for a person uses a
29
+ gated brick: an existing one, or one from step 4.
30
+ - **routes** — for every outcome of every stage: the next stage, `$close` or `$stop`.
31
+ - **failures that route back** — each one to an earlier stage, with its `max` from 1 to 5.
32
+ Each becomes a `cycles` entry. After a fork, route back to `$lane`, the lane the run took,
33
+ and start the cycle's `nodes` with `$lane`.
34
+ - **rules** — optional lines every stage receives ("Never merge.").
35
+ - **level** — project `<repo>/.geneseed/factories/` (this repository, shared with the team
36
+ once committed) or global `$XDG_CONFIG_HOME/geneseed/factories/` (default
37
+ `~/.config/geneseed/factories/`, every project on this machine). Shipped `src/factories/`
38
+ only inside the Geneseed repository. At project level, when
39
+ `git check-ignore -q .geneseed/factories/<name>.json` exits 0, the repository's
40
+ `.geneseed/.gitignore` predates `!/factories/`: tell the user the file stays personal until
41
+ they add that line.
42
+ 3. **Write `<level>/<name>.json`**, `name` equal to the file stem, in the shape of the shipped
43
+ `bug-report-to-fix`:
44
+
45
+ ```json
46
+ {
47
+ "name": "<name>", "description": "<one line>", "category": "<category>",
48
+ "rules": ["<optional>"],
49
+ "stages": ["intake", "loop:<template>", "pr-open", "merge-gate", "retro"],
50
+ "start": "intake",
51
+ "edges": [{ "from": "<stage>", "on": "<outcome>", "to": "<stage | $lane | $close | $stop>" }],
52
+ "cycles": [{ "name": "<name>", "nodes": ["<first stage of the lap, or $lane>", "..."], "max": 2 }]
53
+ }
54
+ ```
55
+
56
+ A cycle's `nodes[0]` is where every lap starts, and every route back targets it. A factory
57
+ with a fork follows the shipped `issue-to-pr`: one edge per named outcome out of `triage`,
58
+ and `$lane` as the target of each route back and as `nodes[0]` of its cycles.
59
+ 4. **A brick that does not exist** — never write it here. Offer the `brick-forge` {{SKILL}}, or
60
+ run it when the user says so, then come back to this step. `brick-forge` is the only
61
+ {{SKILL}} that writes bricks.
62
+ 5. **Check:** `geneseed factory check --factory <name>` (or the `.json` path). For each problem,
63
+ tell the user which rule it names, then fix the file and re-run until it prints `ok: true`:
64
+ - `no factory named "<name>"` — `--factory <name>` found no loadable file of that name. Run
65
+ a bare `geneseed factory check`: it lists every catalogue problem, among them `not JSON`
66
+ (the file does not parse) and `does not match the file name` (its `name` is not its stem).
67
+ - `must be a non-empty string` / `entry … must have` / `is listed twice` / `rules: must be` —
68
+ the shape: a `name`, well-formed `edges` and `cycles` entries, each stage once, `rules` a
69
+ list of non-empty strings.
70
+ - `is not a stage` — an edge endpoint, `start` or a cycle node names no stage (often a typo).
71
+ - `no brick named` / `no loop template named` / `brick unavailable` — a stage that does not
72
+ exist or cannot run here: fix the name, or step 4.
73
+ - `is not an outcome of` / `no edge for outcome` / `edges for outcome` — every outcome of a
74
+ stage has exactly one edge, and an edge uses only outcomes the stage declares (`error` may
75
+ go without one: it stops the run).
76
+ - `$close is not reachable` — no path from `start` ends the run well.
77
+ - `has no declared cycle around it` — a route back with no `cycles` entry.
78
+ - `max must be an integer` — a cycle's `max` is 1 to 5.
79
+ - `entered at …, not at its first stage` — a way into the cycle lands mid-cycle: reorder its
80
+ `nodes` or move the edge.
81
+ - `laps without spending a declared cycle` — a route back to the middle of a cycle: target
82
+ its first stage.
83
+ - `$lane: no fork chooses a lane` / `before any fork has chosen a lane` — `$lane` needs a
84
+ fork on every path to it. `a fork's edge names its lane` — a fork's edge targets its lane
85
+ stage, never `$lane`.
86
+ - `retired` — the file still uses `loop:$triaged` or `loops`: list each loop as its own stage,
87
+ give the fork one edge per lane, and route back to `$lane`. Rewrite it with the user; never
88
+ silently.
89
+ 6. **Hand off:** tell the user the file, then the `factory` {{SKILL}} runs it
90
+ (`geneseed factory init --factory <name> …`). Do not start a run unasked.
91
+
92
+ ## Done when
93
+
94
+ - The factory file exists at the chosen level, `geneseed factory check --factory <name>` prints
95
+ `ok: true`, and no brick was written outside `brick-forge`.
96
+
97
+ <!-- INCLUDE: skills/_self-improvement.md -->
@@ -0,0 +1,126 @@
1
+ # {{SKILL}}: factory
2
+
3
+ > {{DESC_FACTORY}}
4
+
5
+ **Trigger:** the user asks to run a factory, or to carry one work item (a request, a document,
6
+ a GitHub or GitLab issue) through to an open pull request with green CI; or names a factory
7
+ (`analysis-to-build`, `bug-report-to-fix`, `issue-to-pr`).
8
+
9
+ ## What it is
10
+
11
+ `geneseed factory` is a state machine kept in `FACTORY.md` at the worktree's root. A stage is a
12
+ brick or a whole loop; the engine decides every transition, cycle count and stop, and you run the
13
+ stage it hands you and report the outcome. Every action prints one JSON object: act on its keys,
14
+ never on your own reading of the graph. The run ends at an open PR with green CI. **The merge is
15
+ never part of a run.**
16
+
17
+ **Holdout rule.** The `holdout-write` stage writes scenarios the developer never sees, and the
18
+ `holdout` stage plays them before the PR. Both run as the `tester` {{AGENT}}, never as the
19
+ developer and never inline. Never put holdout content (anything under `~/.config/geneseed/holdout/`)
20
+ into any brief, prompt, note or `--carry` you hand on; never name that folder to a developer or a
21
+ loop; never read it on a developer's behalf. Record `holdout-write`'s pass with the `--carry` it
22
+ received, unchanged, and a `holdout` fail with the one-sentence file it reported. No hook refuses a
23
+ read of the folder on any host: the folder is protected only by its place outside the worktree, by `holdout`'s `error`
24
+ when the diff touches it, and by this rule.
25
+
26
+ ## Setup
27
+
28
+ 1. Pick a short kebab-case `<slug>` from the work item. Create the run's worktree:
29
+ `git worktree add ../<repo>-factory-<slug> -b loop/factory-<slug>`, then make it the session's
30
+ working directory with its own command. Every later command runs there as written below: no
31
+ `cd` prefix, no `git -C`. Several runs may share a repo, each in its own worktree.
32
+ 2. Use the factory the user names, else `geneseed factory list` and pick the one whose
33
+ description fits; confirm the pick with the user when two fit. None fits → the `factory-forge` {{SKILL}}.
34
+ 3. `geneseed factory init --title "<title>" --requirement "<the user's ask, in their words>" --factory <name> --input "<issue URL, file path or pasted text>"`.
35
+ A refused factory prints `problems`: report them, never edit the graph to get past them.
36
+
37
+ ## The cycle
38
+
39
+ Repeat `geneseed factory next` and act on its JSON:
40
+
41
+ - **`{stage, prompt, outcomes}`** — a brick stage. Dispatch its `agent` (or follow its `skill`)
42
+ with the `prompt`, the `requirement`, the `input`, the `carry` and the factory's `rules`. Then:
43
+ `git status --porcelain --untracked-files=all | geneseed factory record --outcome <outcome> --carry "<the file path the stage reported>"`.
44
+ The `--carry` is how the next stage gets this one's finding. Always use that porcelain form:
45
+ plain `--porcelain` folds a new directory into one line, which the engine refuses.
46
+ A fork stage (such as `triage`) also gets `lanes`: each outcome it may report, with the stage
47
+ it leads to. Record the outcome it reported (`--outcome docs`): that outcome names the lane,
48
+ and a later route back to `$lane` returns to it.
49
+ A brick stage with `effect: mutate` (a `docs-update` lane) commits what it changed before the
50
+ record: `git add <the files it named>`, then `git commit -m "factory(<slug>): <stage>"`. The
51
+ engine refuses a dirty tree after any stage outside a loop.
52
+ The `spec` stage writes `specs/<slug>/spec.md` (the run's slug; a gate amend reaches it as the
53
+ `carry`, not as a LOOP.md note) and reports with
54
+ `git status --porcelain --untracked-files=all | geneseed factory record --outcome <outcome> --spec specs/<slug>/spec.md --carry <its finding file>`, so the gate shows the user what to review.
55
+ Its gate holds for the user's review of the task list. After `decide --verdict ok`, commit the
56
+ spec before the first loop: `git add specs/<slug>/spec.md`, then
57
+ `git commit -m "factory(<slug>): spec"` (it asks). An uncommitted spec stops the loop's first
58
+ read brick; the engine exempts it only until then.
59
+ - **`{stage, loop, notes}`** — a loop stage: see *Loop stages*.
60
+ - **`{awaiting}`** — a `gate: human` stage holds. Show the user the `stage`, the `outcome` it
61
+ reported and the file its `note` names, then **end the run** and wait. On their answer:
62
+ `geneseed factory decide --verdict ok|no|amend --note "<their words>"` — `ok` follows the
63
+ reported outcome's edge, `no` stops, `amend` re-runs the stage with their note — and continue.
64
+ - **`{terminal: "$close"}`** or **`{terminal: "$stop"}`** — see *The end*.
65
+ - A `record` or `decide` result (`{stage}`, `{awaiting}`, `{stopped}`) — call `next` again.
66
+ - **`{error}`** — read it; it names the step you skipped or the evidence `record` lacks. Do that
67
+ step. Never edit the state block in `FACTORY.md` to get past it.
68
+
69
+ ## Loop stages
70
+
71
+ 4. Call `next` before every loop, each task of a spec included: it records the launch that
72
+ `record` later checks. When it refuses a `LOOP.md` left by the previous loop, remove it:
73
+ `git rm -f LOOP.md` when git tracks it, else delete the file (a loop that made no commit
74
+ leaves it untracked). Commit only when `git status` then shows the removal:
75
+ `git commit -m "factory(<slug>): clear the previous loop"` (it asks). Then `next` again.
76
+ A loop that ended `done` may instead be recorded `pass` while its `LOOP.md` is still there.
77
+ 5. Start the loop in this same worktree:
78
+ `geneseed loop init --title "<title>" --requirement "<requirement, plus the task when next gave one>" --graph <loop> --preset {{TRUST}} --factory <slug> --note-file <notes[0]>`
79
+ where the task is item `task.index` under the spec's Tasks heading, written as
80
+ "task <index>/<count>: <its text>". When `task.extra` is set, the last task has passed and a
81
+ later stage sent the work back: the task is "make CI green" (or, for another stage, make it
82
+ pass), and `notes[0]` says why. Use `--note-file <notes[0]>`
83
+ when `notes[0]` is the path of a stage's finding file (the usual carry), so the loop gets the
84
+ finding, not its path; `--note "<notes[0]>"` when it is plain text; neither when `notes` is
85
+ empty. A loop
86
+ re-entered after a failure is a fresh loop: the reason arrives as its note.
87
+ 6. Follow the `loop` {{SKILL}} from *The cycle* through *The end*, skipping its Setup: the
88
+ worktree is this one, and its `loop/<slug>` is `loop/factory-<slug>` here, so every loop push
89
+ is `git push -u origin HEAD:loop/factory-<slug>`. Skip its final report too: the run goes on.
90
+ 7. When the loop reaches `$close` and its close commit has removed `LOOP.md`:
91
+ `git status --porcelain --untracked-files=all | geneseed factory record --outcome pass`.
92
+ When it reaches `$stop`, leave its `LOOP.md` in place:
93
+ `git status --porcelain --untracked-files=all | geneseed factory record --outcome fail --carry "<the stop reason>"`.
94
+
95
+ ## The end
96
+
97
+ 8. On `$close`: the `retro` stage has written the run report. Close the run with
98
+ `git rm -f FACTORY.md`, then `git commit -m "factory(<slug>): close"` and
99
+ `git push -u origin HEAD:loop/factory-<slug>`. The gate asks: that ask is the user's consent.
100
+ The push re-runs CI on the PR, after `merge-gate` saw it green. Read the PR's checks again
101
+ once, with the bounded wait the `merge-gate` brick names (30 minutes at most), and add the
102
+ final state (green, red with the failing checks, or still pending at the bound) to the run
103
+ report. A red result is reported, never reworked: the run has closed.
104
+ 9. On `$stop`: the engine hands out no stage after a stop, so have the `docs` {{AGENT}} write the
105
+ run report the `retro` brick would: the stop `reason` first, then the work item, the PR URL if
106
+ any, every stage with its outcome and each rework with its reason, read from `FACTORY.md` and
107
+ the loops' notes. It goes to `.geneseed/factory-runs/<slug>.md`, or to the OS temp directory
108
+ when `git check-ignore -q <that path>` exits non-zero. No tracked file changes, no commit; only
109
+ a lesson that holds beyond this run goes into memory, one entry. Leave the branch and
110
+ `FACTORY.md` as they are.
111
+ 10. Report: the PR URL, the final CI state after the close commit, the stages with their outcomes from `summary.history`, every rework and
112
+ its reason, the run report's path, and the branch. **Never merge.**
113
+
114
+ ## Resume
115
+
116
+ After a crash or an answered `awaiting`, from the worktree: `geneseed factory next`. When it
117
+ says a loop still runs, resume that loop first with `geneseed loop next` (the `loop`
118
+ {{SKILL}}'s *Resume*). The state is `FACTORY.md`, the child `LOOP.md` and the branch.
119
+
120
+ ## Done when
121
+
122
+ - `$close` is reported with the PR open, `FACTORY.md` removed, and the CI state after that
123
+ removal read and reported; or `$stop` is
124
+ reported with its reason and the run report. In both cases nothing was merged.
125
+
126
+ <!-- INCLUDE: skills/_self-improvement.md -->