geneseed 5.0.4 → 5.1.1

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 (76) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/SHIPPED.md +2 -2
  3. package/docs/concepts/exclusions.md +1 -1
  4. package/docs/concepts/factories.md +67 -15
  5. package/docs/concepts/loop-gates.md +5 -2
  6. package/docs/concepts/shared-tier.md +14 -0
  7. package/docs/extending.md +1 -1
  8. package/docs/guides/migrate.md +1 -1
  9. package/docs/guides/run-a-factory.md +41 -13
  10. package/docs/guides/upgrade-to-5.md +2 -2
  11. package/docs/reference/factory-actions.md +7 -7
  12. package/docs/web-ui.md +18 -6
  13. package/harness.config.json +1 -1
  14. package/js/README.md +3 -2
  15. package/js/build/args.mjs +34 -14
  16. package/js/build/emit-claude.mjs +3 -0
  17. package/js/build/emit-opencode.mjs +4 -0
  18. package/js/build/retired-skills.mjs +158 -0
  19. package/js/build/source.mjs +31 -11
  20. package/js/cli-table.json +32 -5
  21. package/js/factory/cli.mjs +49 -8
  22. package/js/factory/graph.mjs +72 -8
  23. package/js/factory/state.mjs +109 -27
  24. package/js/hosts/done-checks.mjs +3 -2
  25. package/js/hosts/memory-files.mjs +7 -2
  26. package/js/loop/catalog.mjs +16 -10
  27. package/js/loop/cli.mjs +16 -10
  28. package/js/maintain/memory.mjs +27 -2
  29. package/js/maintain/migrate.mjs +39 -25
  30. package/js/web/daemon.mjs +69 -14
  31. package/js/web/handler.mjs +22 -9
  32. package/package.json +1 -1
  33. package/src/agents/memory-curator.md +4 -4
  34. package/src/bricks/checks.md +62 -0
  35. package/src/bricks/intake.md +15 -6
  36. package/src/bricks/merge-gate.md +17 -8
  37. package/src/bricks/retro.md +8 -3
  38. package/src/bricks/review-panel.md +43 -0
  39. package/src/bricks/spec.md +20 -6
  40. package/src/factories/analysis-to-build.json +25 -7
  41. package/src/factories/bug-report-to-fix.json +25 -7
  42. package/src/factories/issue-to-pr.json +29 -11
  43. package/src/memory/README.md +1 -1
  44. package/src/skills/factory-forge.md +23 -5
  45. package/src/skills/factory.md +95 -25
  46. package/src/skills/geneseed.md +1 -1
  47. package/src/skills/loop.md +3 -2
  48. package/src/skills/rule/consolidate.md +1 -1
  49. package/src/skills/rule.md +1 -1
  50. package/themes/_TEMPLATE.json +1 -1
  51. package/web/dist/assets/{Activity-BaoxwVFH.js → Activity-CpkBwpu7.js} +1 -1
  52. package/web/dist/assets/{ActivityDetail-C_bFD0rW.js → ActivityDetail-DTPziZWM.js} +1 -1
  53. package/web/dist/assets/{Bonsai-B01lLf0m.js → Bonsai-hiG_gGNU.js} +1 -1
  54. package/web/dist/assets/{CopyButton-Bc66KPyA.js → CopyButton-DUIUfNp6.js} +1 -1
  55. package/web/dist/assets/{Dashboard-X7GZzGJp.js → Dashboard-Dnw6EyX7.js} +2 -2
  56. package/web/dist/assets/{Docs-LRYVnGLG.js → Docs-BEET_l16.js} +1 -1
  57. package/web/dist/assets/Factories-D6KXkfWw.js +1 -0
  58. package/web/dist/assets/{GreenhouseView-CfWR2-sX.js → GreenhouseView-BKxy5apE.js} +1 -1
  59. package/web/dist/assets/{Installs-nfFHnovH.js → Installs-CnFVlVD0.js} +1 -1
  60. package/web/dist/assets/{JournalView-lpOHcHKK.js → JournalView-ChFitHjo.js} +1 -1
  61. package/web/dist/assets/{Kits-Bw5EQl_i.js → Kits-CcR-OlwQ.js} +1 -1
  62. package/web/dist/assets/{Laws-CnZJ0wjZ.js → Laws-B1s5idOg.js} +1 -1
  63. package/web/dist/assets/LibRows-BZgdbI1l.js +1 -0
  64. package/web/dist/assets/Library-x6TkkEVF.js +3 -0
  65. package/web/dist/assets/{Loops-ZaHC5MVl.js → Loops-BH93KKxn.js} +1 -1
  66. package/web/dist/assets/{OperatorHudView-CggG0_sK.js → OperatorHudView-BO0aIKPL.js} +1 -1
  67. package/web/dist/assets/{Personal-BObvlb70.js → Personal-CE_0Vhh0.js} +1 -1
  68. package/web/dist/assets/{Settings-BFfPMPc9.js → Settings-CbpZvVN_.js} +1 -1
  69. package/web/dist/assets/{Tabs-B594Pad_.js → Tabs-C2oW7oEj.js} +1 -1
  70. package/web/dist/assets/{index-DsLmKHw0.js → index-BQwOmbor.js} +2 -2
  71. package/web/dist/assets/{index-DvPjphz0.css → index-CuIop_pO.css} +1 -1
  72. package/web/dist/index.html +2 -2
  73. package/adapters/claude-code/skills/geneseed/SKILL.md +0 -76
  74. package/web/dist/assets/Factories-ARenKBiP.js +0 -1
  75. package/web/dist/assets/LibRows-Hqvf1beK.js +0 -1
  76. package/web/dist/assets/Library-JaSsp6Yr.js +0 -3
@@ -1,22 +1,29 @@
1
1
  {
2
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.",
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, run the base branch's checks and a review panel, play the holdout scenarios it never saw, then open one pull request and wait for green CI; a failed check, review or scenario, or red CI, sends the work back to the loop as one more task, twice at most each. At the end it asks you once whether to merge.",
4
4
  "category": "development",
5
5
  "rules": [
6
- "Never merge, and never enable auto-merge: the run ends at an open PR with green CI.",
6
+ "Never merge or enable auto-merge without the user's yes, asked once at the end of the run.",
7
7
  "Push only this worktree's own branch."
8
8
  ],
9
- "stages": ["intake", "spec", "holdout-write", "loop:feature", "holdout", "pr-open", "merge-gate", "retro"],
9
+ "stages": ["intake", "spec", "holdout-write", "loop:feature", "checks", "review-panel", "holdout", "pr-open", "merge-gate", "retro"],
10
10
  "start": "intake",
11
11
  "edges": [
12
12
  { "from": "intake", "on": "pass", "to": "spec" },
13
13
  { "from": "intake", "on": "fail", "to": "$stop" },
14
+ { "from": "intake", "on": "needs-info", "to": "spec" },
14
15
  { "from": "spec", "on": "pass", "to": "holdout-write" },
15
16
  { "from": "spec", "on": "fail", "to": "$stop" },
16
17
  { "from": "holdout-write", "on": "pass", "to": "loop:feature" },
17
18
  { "from": "holdout-write", "on": "fail", "to": "$stop" },
18
- { "from": "loop:feature", "on": "pass", "to": "holdout" },
19
+ { "from": "loop:feature", "on": "pass", "to": "checks" },
19
20
  { "from": "loop:feature", "on": "fail", "to": "$stop" },
21
+ { "from": "checks", "on": "pass", "to": "review-panel" },
22
+ { "from": "checks", "on": "fail", "to": "loop:feature" },
23
+ { "from": "checks", "on": "error", "to": "review-panel" },
24
+ { "from": "checks", "on": "none", "to": "checks" },
25
+ { "from": "review-panel", "on": "pass", "to": "holdout" },
26
+ { "from": "review-panel", "on": "fail", "to": "loop:feature" },
20
27
  { "from": "holdout", "on": "pass", "to": "pr-open" },
21
28
  { "from": "holdout", "on": "fail", "to": "loop:feature" },
22
29
  { "from": "holdout", "on": "error", "to": "$stop" },
@@ -28,7 +35,18 @@
28
35
  { "from": "retro", "on": "pass", "to": "$close" }
29
36
  ],
30
37
  "cycles": [
31
- { "name": "holdout", "nodes": ["loop:feature", "holdout"], "max": 2 },
32
- { "name": "ci", "nodes": ["loop:feature", "holdout", "pr-open", "merge-gate"], "max": 2 }
33
- ]
38
+ { "name": "done-list", "nodes": ["checks"], "max": 1 },
39
+ { "name": "checks", "nodes": ["loop:feature", "checks"], "max": 2 },
40
+ { "name": "review", "nodes": ["loop:feature", "checks", "review-panel"], "max": 2 },
41
+ { "name": "holdout", "nodes": ["loop:feature", "checks", "review-panel", "holdout"], "max": 2 },
42
+ { "name": "ci", "nodes": ["loop:feature", "checks", "review-panel", "holdout", "pr-open", "merge-gate"], "max": 2 }
43
+ ],
44
+ "review": {
45
+ "seats": {
46
+ "small": ["reviewer"],
47
+ "medium": ["reviewer", "tester"],
48
+ "large": ["reviewer", "tester", "steward"],
49
+ "areas": { "security": ["security"], "performance": ["performance"], "ui": ["user-advocate"], "data": ["security"] }
50
+ }
51
+ }
34
52
  }
@@ -1,20 +1,27 @@
1
1
  {
2
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.",
3
+ "description": "Take one bug report, fix it with the bugfix loop, run the base branch's checks and a review panel, play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed check, review or scenario, or red CI, sends the fix back to the loop, twice at most each. At the end it asks you once whether to merge.",
4
4
  "category": "development",
5
5
  "rules": [
6
- "Never merge, and never enable auto-merge: the run ends at an open PR with green CI.",
6
+ "Never merge or enable auto-merge without the user's yes, asked once at the end of the run.",
7
7
  "Push only this worktree's own branch."
8
8
  ],
9
- "stages": ["intake", "holdout-write", "loop:bugfix", "holdout", "pr-open", "merge-gate", "retro"],
9
+ "stages": ["intake", "holdout-write", "loop:bugfix", "checks", "review-panel", "holdout", "pr-open", "merge-gate", "retro"],
10
10
  "start": "intake",
11
11
  "edges": [
12
12
  { "from": "intake", "on": "pass", "to": "holdout-write" },
13
13
  { "from": "intake", "on": "fail", "to": "$stop" },
14
+ { "from": "intake", "on": "needs-info", "to": "holdout-write" },
14
15
  { "from": "holdout-write", "on": "pass", "to": "loop:bugfix" },
15
16
  { "from": "holdout-write", "on": "fail", "to": "$stop" },
16
- { "from": "loop:bugfix", "on": "pass", "to": "holdout" },
17
+ { "from": "loop:bugfix", "on": "pass", "to": "checks" },
17
18
  { "from": "loop:bugfix", "on": "fail", "to": "$stop" },
19
+ { "from": "checks", "on": "pass", "to": "review-panel" },
20
+ { "from": "checks", "on": "fail", "to": "loop:bugfix" },
21
+ { "from": "checks", "on": "error", "to": "review-panel" },
22
+ { "from": "checks", "on": "none", "to": "checks" },
23
+ { "from": "review-panel", "on": "pass", "to": "holdout" },
24
+ { "from": "review-panel", "on": "fail", "to": "loop:bugfix" },
18
25
  { "from": "holdout", "on": "pass", "to": "pr-open" },
19
26
  { "from": "holdout", "on": "fail", "to": "loop:bugfix" },
20
27
  { "from": "holdout", "on": "error", "to": "$stop" },
@@ -26,7 +33,18 @@
26
33
  { "from": "retro", "on": "pass", "to": "$close" }
27
34
  ],
28
35
  "cycles": [
29
- { "name": "holdout", "nodes": ["loop:bugfix", "holdout"], "max": 2 },
30
- { "name": "ci", "nodes": ["loop:bugfix", "holdout", "pr-open", "merge-gate"], "max": 2 }
31
- ]
36
+ { "name": "done-list", "nodes": ["checks"], "max": 1 },
37
+ { "name": "checks", "nodes": ["loop:bugfix", "checks"], "max": 2 },
38
+ { "name": "review", "nodes": ["loop:bugfix", "checks", "review-panel"], "max": 2 },
39
+ { "name": "holdout", "nodes": ["loop:bugfix", "checks", "review-panel", "holdout"], "max": 2 },
40
+ { "name": "ci", "nodes": ["loop:bugfix", "checks", "review-panel", "holdout", "pr-open", "merge-gate"], "max": 2 }
41
+ ],
42
+ "review": {
43
+ "seats": {
44
+ "small": ["reviewer"],
45
+ "medium": ["reviewer", "tester"],
46
+ "large": ["reviewer", "tester", "steward"],
47
+ "areas": { "security": ["security"], "performance": ["performance"], "ui": ["user-advocate"], "data": ["security"] }
48
+ }
49
+ }
32
50
  }
@@ -1,20 +1,21 @@
1
1
  {
2
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.",
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), run the base branch's checks and a review panel, play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed check, review or scenario, or red CI, sends the work back to that lane, twice at most each. At the end it asks you once whether to merge.",
4
4
  "category": "development",
5
5
  "rules": [
6
- "Never merge, and never enable auto-merge: the run ends at an open PR with green CI.",
6
+ "Never merge or enable auto-merge without the user's yes, asked once at the end of the run.",
7
7
  "Push only this worktree's own branch."
8
8
  ],
9
9
  "stages": [
10
10
  "intake", "holdout-write", "triage",
11
11
  "loop:bugfix", "loop:feature", "loop:deps-upgrade", "loop:refactor", "docs-update",
12
- "holdout", "pr-open", "merge-gate", "retro"
12
+ "checks", "review-panel", "holdout", "pr-open", "merge-gate", "retro"
13
13
  ],
14
14
  "start": "intake",
15
15
  "edges": [
16
16
  { "from": "intake", "on": "pass", "to": "holdout-write" },
17
17
  { "from": "intake", "on": "fail", "to": "$stop" },
18
+ { "from": "intake", "on": "needs-info", "to": "holdout-write" },
18
19
  { "from": "holdout-write", "on": "pass", "to": "triage" },
19
20
  { "from": "holdout-write", "on": "fail", "to": "$stop" },
20
21
  { "from": "triage", "on": "bug", "to": "loop:bugfix" },
@@ -23,15 +24,21 @@
23
24
  { "from": "triage", "on": "refactor", "to": "loop:refactor" },
24
25
  { "from": "triage", "on": "docs", "to": "docs-update" },
25
26
  { "from": "triage", "on": "fail", "to": "$stop" },
26
- { "from": "loop:bugfix", "on": "pass", "to": "holdout" },
27
+ { "from": "loop:bugfix", "on": "pass", "to": "checks" },
27
28
  { "from": "loop:bugfix", "on": "fail", "to": "$stop" },
28
- { "from": "loop:feature", "on": "pass", "to": "holdout" },
29
+ { "from": "loop:feature", "on": "pass", "to": "checks" },
29
30
  { "from": "loop:feature", "on": "fail", "to": "$stop" },
30
- { "from": "loop:deps-upgrade", "on": "pass", "to": "holdout" },
31
+ { "from": "loop:deps-upgrade", "on": "pass", "to": "checks" },
31
32
  { "from": "loop:deps-upgrade", "on": "fail", "to": "$stop" },
32
- { "from": "loop:refactor", "on": "pass", "to": "holdout" },
33
+ { "from": "loop:refactor", "on": "pass", "to": "checks" },
33
34
  { "from": "loop:refactor", "on": "fail", "to": "$stop" },
34
- { "from": "docs-update", "on": "pass", "to": "holdout" },
35
+ { "from": "docs-update", "on": "pass", "to": "checks" },
36
+ { "from": "checks", "on": "pass", "to": "review-panel" },
37
+ { "from": "checks", "on": "fail", "to": "$lane" },
38
+ { "from": "checks", "on": "error", "to": "review-panel" },
39
+ { "from": "checks", "on": "none", "to": "checks" },
40
+ { "from": "review-panel", "on": "pass", "to": "holdout" },
41
+ { "from": "review-panel", "on": "fail", "to": "$lane" },
35
42
  { "from": "holdout", "on": "pass", "to": "pr-open" },
36
43
  { "from": "holdout", "on": "fail", "to": "$lane" },
37
44
  { "from": "holdout", "on": "error", "to": "$stop" },
@@ -43,7 +50,18 @@
43
50
  { "from": "retro", "on": "pass", "to": "$close" }
44
51
  ],
45
52
  "cycles": [
46
- { "name": "holdout", "nodes": ["$lane", "holdout"], "max": 2 },
47
- { "name": "ci", "nodes": ["$lane", "holdout", "pr-open", "merge-gate"], "max": 2 }
48
- ]
53
+ { "name": "done-list", "nodes": ["checks"], "max": 1 },
54
+ { "name": "checks", "nodes": ["$lane", "checks"], "max": 2 },
55
+ { "name": "review", "nodes": ["$lane", "checks", "review-panel"], "max": 2 },
56
+ { "name": "holdout", "nodes": ["$lane", "checks", "review-panel", "holdout"], "max": 2 },
57
+ { "name": "ci", "nodes": ["$lane", "checks", "review-panel", "holdout", "pr-open", "merge-gate"], "max": 2 }
58
+ ],
59
+ "review": {
60
+ "seats": {
61
+ "small": ["reviewer"],
62
+ "medium": ["reviewer", "tester"],
63
+ "large": ["reviewer", "tester", "steward"],
64
+ "areas": { "security": ["security"], "performance": ["performance"], "ui": ["user-advocate"], "data": ["security"] }
65
+ }
66
+ }
49
67
  }
@@ -111,7 +111,7 @@ facts the store holds:
111
111
 
112
112
  A fact's topic is its `topic:`, else its `type:`, else `misc`, normalised to
113
113
  lowercase `[a-z0-9-]`. Both levels are generated from the fact files:
114
- `geneseed learn --consolidate --memory <this dir>` rebuilds them (refreshing each
114
+ `geneseed memory consolidate --memory <this dir>` rebuilds them (refreshing each
115
115
  hook from its `description`), and the `learn` hook rebuilds them after every fact it
116
116
  writes, updates or archives. Only top-level fact files are indexed; `archive/` and
117
117
  `agents/` never are. A build moves a flat, one-line-per-fact `MEMORY.md` from an older install to
@@ -22,7 +22,7 @@ to the loop three times, not two".
22
22
  **fork**, such as `triage`: `bug`, `feature`, `deps`, `refactor`, `docs`, `fail`). Give each
23
23
  named outcome its own edge to its own **lane**: a loop for work that changes code, or a brick
24
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
25
+ (`checks`, then `review-panel` and `holdout`, then `pr-open` and `merge-gate`). An outcome the factory does not offer goes to
26
26
  `$stop`.
27
27
  - **where a human gates** — a gate belongs to the brick (`gate: human` in its frontmatter,
28
28
  narrowed by `gateOn`), never to the factory. A stage that must hold for a person uses a
@@ -30,7 +30,10 @@ to the loop three times, not two".
30
30
  - **routes** — for every outcome of every stage: the next stage, `$close` or `$stop`.
31
31
  - **failures that route back** — each one to an earlier stage, with its `max` from 1 to 5.
32
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`.
33
+ and start the cycle's `nodes` with `$lane`. Only a `fail` routes back to a loop: `checks`
34
+ `error` and `merge-gate` `none` also carry environment failures (a failed fetch, a missing
35
+ tool, CI pending at the bound) that no loop can fix, so route them on or to `$stop`, never
36
+ to a loop or `$lane` (`factory check` refuses that route).
34
37
  - **rules** — optional lines every stage receives ("Never merge.").
35
38
  - **level** — project `<repo>/.geneseed/factories/` (this repository, shared with the team
36
39
  once committed) or global `$XDG_CONFIG_HOME/geneseed/factories/` (default
@@ -46,13 +49,20 @@ to the loop three times, not two".
46
49
  {
47
50
  "name": "<name>", "description": "<one line>", "category": "<category>",
48
51
  "rules": ["<optional>"],
49
- "stages": ["intake", "loop:<template>", "pr-open", "merge-gate", "retro"],
52
+ "stages": ["intake", "holdout-write", "loop:<template>", "checks", "review-panel", "holdout", "pr-open", "merge-gate", "retro"],
50
53
  "start": "intake",
51
54
  "edges": [{ "from": "<stage>", "on": "<outcome>", "to": "<stage | $lane | $close | $stop>" }],
52
- "cycles": [{ "name": "<name>", "nodes": ["<first stage of the lap, or $lane>", "..."], "max": 2 }]
55
+ "cycles": [{ "name": "<name>", "nodes": ["<first stage of the lap, or $lane>", "..."], "max": 2 }],
56
+ "protected": ["<optional: paths checks refuses to see changed>"],
57
+ "review": { "seats": { "small": ["reviewer"], "medium": ["reviewer", "tester"], "large": ["reviewer", "tester", "steward"],
58
+ "areas": { "security": ["security"], "performance": ["performance"], "ui": ["user-advocate"], "data": ["security"] } } }
53
59
  }
54
60
  ```
55
61
 
62
+ The edge `intake --needs-info--> <stage>` is optional: without it, a `needs-info` the user
63
+ answers `ok` follows intake's `pass` edge. `protected` is optional. `review.seats` is what a
64
+ `review-panel` stage seats; copy the shipped table unless the user wants other seats.
65
+
56
66
  A cycle's `nodes[0]` is where every lap starts, and every route back targets it. A factory
57
67
  with a fork follows the shipped `issue-to-pr`: one edge per named outcome out of `triage`,
58
68
  and `$lane` as the target of each route back and as `nodes[0]` of its cycles.
@@ -72,7 +82,13 @@ to the loop three times, not two".
72
82
  exist or cannot run here: fix the name, or step 4.
73
83
  - `is not an outcome of` / `no edge for outcome` / `edges for outcome` — every outcome of a
74
84
  stage has exactly one edge, and an edge uses only outcomes the stage declares (`error` may
75
- go without one: it stops the run).
85
+ go without one: it stops the run; so may `needs-info`: it follows the `pass` edge).
86
+ - `protected: must be a list of non-empty paths` — `protected` is a list of path strings.
87
+ - `review: must be an object with a seats table` / `review.seats.<size>: must be a non-empty
88
+ list of agent names` / `review.seats.areas: must map each area to a list of agents` — the
89
+ seat table needs a list for `small`, `medium` and `large`, and `areas` maps each area to a list.
90
+ - `review.seats.<where>: no agent named <name>` — a seat names an agent Geneseed does not ship;
91
+ a project's own agents cannot sit.
76
92
  - `$close is not reachable` — no path from `start` ends the run well.
77
93
  - `has no declared cycle around it` — a route back with no `cycles` entry.
78
94
  - `max must be an integer` — a cycle's `max` is 1 to 5.
@@ -86,6 +102,8 @@ to the loop three times, not two".
86
102
  - `retired` — the file still uses `loop:$triaged` or `loops`: list each loop as its own stage,
87
103
  give the fork one edge per lane, and route back to `$lane`. Rewrite it with the user; never
88
104
  silently.
105
+ - `reports environment failures on …, which no loop can fix` — `checks` `error` or
106
+ `merge-gate` `none` routes to a loop or `$lane`: route it to the next stage or to `$stop`.
89
107
  6. **Hand off:** tell the user the file, then the `factory` {{SKILL}} runs it
90
108
  (`geneseed factory init --factory <name> …`). Do not start a run unasked.
91
109
 
@@ -2,17 +2,17 @@
2
2
 
3
3
  > {{DESC_FACTORY}}
4
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`).
5
+ **Trigger:** the user names a factory (`analysis-to-build`, `bug-report-to-fix`, `issue-to-pr`),
6
+ or asks to carry an issue, request or document to a PR with green CI.
8
7
 
9
8
  ## What it is
10
9
 
11
10
  `geneseed factory` is a state machine kept in `FACTORY.md` at the worktree's root. A stage is a
12
11
  brick or a whole loop; the engine decides every transition, cycle count and stop, and you run the
13
12
  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.**
13
+ never on your own reading of the graph. The run ends at an open PR with green CI. **No stage
14
+ merges:** once the run has closed, you ask the user once whether to merge (*The end*), and never
15
+ enable auto-merge.
16
16
 
17
17
  **Holdout rule.** The `holdout-write` stage writes scenarios the developer never sees, and the
18
18
  `holdout` stage plays them before the PR. Both run as the `tester` {{AGENT}}, never as the
@@ -25,7 +25,11 @@ when the diff touches it, and by this rule.
25
25
 
26
26
  ## Setup
27
27
 
28
- 1. Pick a short kebab-case `<slug>` from the work item. Create the run's worktree:
28
+ 1. Pick a short kebab-case `<slug>` from the work item, without the words `git`, `commit` or
29
+ `push` (spell them `g1t`, `cmt`, `psh`, or leave them out): the slug lands on the spec's
30
+ `record` line and on `git commit -m` lines, where those words make the git gate ask.
31
+ `factory init` refuses a `loop/factory-<slug>` branch whose slug holds one. Create the run's
32
+ worktree:
29
33
  `git worktree add ../<repo>-factory-<slug> -b loop/factory-<slug>`, then make it the session's
30
34
  working directory with its own command. Every later command runs there as written below: no
31
35
  `cd` prefix, no `git -C`. Several runs may share a repo, each in its own worktree.
@@ -36,13 +40,27 @@ when the diff touches it, and by this rule.
36
40
 
37
41
  ## The cycle
38
42
 
39
- Repeat `geneseed factory next` and act on its JSON:
43
+ Repeat `geneseed factory next` and act on its JSON.
44
+
45
+ **How to record.** `record` reads the porcelain on its stdin, piped in one command:
46
+ `git status --porcelain --untracked-files=all | geneseed factory record --outcome <outcome>`.
47
+ The same line works in PowerShell, which pipes too. Always use that porcelain form: plain
48
+ `--porcelain` folds a new directory into one line, which the engine refuses. A carry is the path
49
+ of the file the stage itself wrote (`--carry <that file>`), in the OS temp directory where the stage wrote it (never inside the worktree: a file there makes the porcelain dirty).
50
+ Free text (the user's words for `decide`, a stop reason) never goes on the command line: write it
51
+ with your file tool, never the shell, to a file whose name you make unique, such as
52
+ `<os temp dir>/factory-<8 random hex>.txt`, then pass `--note-file <that file>` or
53
+ `--carry-file <that file>`. Never delete a carry: the engine keeps its path for the next stage.
54
+
55
+ The git gate asks on any line that holds the word `git` and the word `commit` or `push`. A
56
+ record line holds `git`, so a spec path, a carry path or an outcome name with `commit` or `push`
57
+ in it makes the gate ask. On a record line that ask is a false alarm: the user can answer yes.
58
+ `factory init` refuses a slug that holds those words, which removes the commonest case.
40
59
 
41
60
  - **`{stage, prompt, outcomes}`** — a brick stage. Dispatch its `agent` (or follow its `skill`)
42
61
  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.
62
+ `git status --porcelain --untracked-files=all | geneseed factory record --outcome <outcome> --carry <the file the stage reported>`
63
+ (*How to record*). The `--carry` is how the next stage gets this one's finding.
46
64
  A fork stage (such as `triage`) also gets `lanes`: each outcome it may report, with the stage
47
65
  it leads to. Record the outcome it reported (`--outcome docs`): that outcome names the lane,
48
66
  and a later route back to `$lane` returns to it.
@@ -51,16 +69,54 @@ Repeat `geneseed factory next` and act on its JSON:
51
69
  engine refuses a dirty tree after any stage outside a loop.
52
70
  The `spec` stage writes `specs/<slug>/spec.md` (the run's slug; a gate amend reaches it as the
53
71
  `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.
72
+ `git status --porcelain --untracked-files=all | geneseed factory record --outcome <outcome> --spec specs/<slug>/spec.md --carry <the file the stage reported>`,
73
+ so the gate shows the user what to review.
55
74
  Its gate holds for the user's review of the task list. After `decide --verdict ok`, commit the
56
75
  spec before the first loop: `git add specs/<slug>/spec.md`, then
57
76
  `git commit -m "factory(<slug>): spec"` (it asks). An uncommitted spec stops the loop's first
58
77
  read brick; the engine exempts it only until then.
78
+ A stage whose `skill` is `factory` (`review-panel`) is yours: follow its `prompt` here,
79
+ dispatch its seats in one parallel batch, chair them, and record its outcome as above.
59
80
  - **`{stage, loop, notes}`** — a loop stage: see *Loop stages*.
60
81
  - **`{awaiting}`** — a `gate: human` stage holds. Show the user the `stage`, the `outcome` it
61
82
  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
83
+ write their words to a unique file with your file tool (*How to record*), then
84
+ `geneseed factory decide --verdict ok|no|amend --note-file <that file>` — `ok` follows the
63
85
  reported outcome's edge, `no` stops, `amend` re-runs the stage with their note — and continue.
86
+ Their words never go on the command line.
87
+ The gated outcomes:
88
+ - `intake` **`needs-info`**: show the user its numbered questions. Their answers go back as
89
+ `amend`, with the note file holding their answers; `ok` goes on with the assumptions intake
90
+ wrote.
91
+ - `checks` **`error`**: every check passed, but the branch changed a locked path (the done
92
+ list, CI config, a factory, loop or brick). Show each path. `ok` lets the change through; the run report names it.
93
+ When the finding starts `environment:` (a failed fetch, no default branch, a timeout, a
94
+ missing tool), show the cause instead: the loop cannot fix it. Once the user has fixed it,
95
+ `amend` runs `checks` again; `no` stops; `ok` goes on without the done list.
96
+ - `merge-gate` **`none`**: the repo runs no CI on the PR, or, when the finding starts
97
+ `environment:`, no verdict could be read (CI pending at the bound, `gh`/`glab` missing or
98
+ failing). `ok` goes on to `retro`, `amend` waits again, `no` stops.
99
+ - `checks` **`none`**: the base has no done list (or an empty one), and the note is the one
100
+ `checks` proposes, or says no manifest gave one. On the user's yes, land it on the base by a
101
+ PR of its own, never from this worktree and never by a push to `<default>`:
102
+ `git worktree add ../<repo>-done-list-<slug> -b geneseed/done-list-<slug> origin/<default>`,
103
+ write `.geneseed/done-checks.txt` there holding exactly the lines of the finding's fenced
104
+ block, stage that file alone, commit, push that worktree's own branch
105
+ (`git push -u origin HEAD:geneseed/done-list-<slug>`), and open a PR to `<default>`
106
+ (`gh pr create --base <default>`, or `glab mr create --target-branch <default>`; each asks).
107
+ Give the user the PR's URL: they merge it. Remove that worktree once the PR is merged.
108
+ When the branch or the worktree already exists (a re-run with the same slug), create
109
+ nothing and overwrite nothing: report it to the user with that worktree's path and the
110
+ branch's state (`git log -1 geneseed/done-list-<slug>`), and let them reuse, merge or
111
+ remove it. When the remote already has `geneseed/done-list-<slug>` but this clone has no
112
+ such branch (`git ls-remote --exit-code --heads origin geneseed/done-list-<slug>` exits 0
113
+ before the push), the push is refused: push nothing and overwrite nothing, and report it to
114
+ the user with that worktree's path and the remote branch's name, so they decide whether to
115
+ reuse, merge or delete it. When `gh` or `glab` is missing or fails at the PR step, the branch is pushed
116
+ already: report it to the user with that worktree's path and the branch name, so they open
117
+ the PR themselves. `ok`
118
+ waits until the file is on the base: answer `decide --verdict ok` only then, and `checks`
119
+ runs again against it. If it is not to be landed, `no`.
64
120
  - **`{terminal: "$close"}`** or **`{terminal: "$stop"}`** — see *The end*.
65
121
  - A `record` or `decide` result (`{stage}`, `{awaiting}`, `{stopped}`) — call `next` again.
66
122
  - **`{error}`** — read it; it names the step you skipped or the evidence `record` lacks. Do that
@@ -81,35 +137,48 @@ Repeat `geneseed factory next` and act on its JSON:
81
137
  later stage sent the work back: the task is "make CI green" (or, for another stage, make it
82
138
  pass), and `notes[0]` says why. Use `--note-file <notes[0]>`
83
139
  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
140
+ finding, not its path; when it is plain text, write it to a unique file with your file tool
141
+ (*How to record*) and pass that file with `--note-file`; neither when `notes` is empty. A loop
86
142
  re-entered after a failure is a fresh loop: the reason arrives as its note.
87
143
  6. Follow the `loop` {{SKILL}} from *The cycle* through *The end*, skipping its Setup: the
88
144
  worktree is this one, and its `loop/<slug>` is `loop/factory-<slug>` here, so every loop push
89
145
  is `git push -u origin HEAD:loop/factory-<slug>`. Skip its final report too: the run goes on.
90
146
  7. When the loop reaches `$close` and its close commit has removed `LOOP.md`:
91
147
  `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>"`.
148
+ When it reaches `$stop`, leave its `LOOP.md` in place, write the stop reason to a unique file
149
+ with your file tool (*How to record*), then
150
+ `git status --porcelain --untracked-files=all | geneseed factory record --outcome fail --carry-file <that file>`.
94
151
 
95
152
  ## The end
96
153
 
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
154
+ 8. On `$close`: the `retro` stage has written the run report. Remove `FACTORY.md`:
155
+ `git rm -f FACTORY.md` when git tracks it (a loop's commit carries it), else delete the file
156
+ (a run with no loop, such as the `docs` lane, never tracked it). Commit and push only when
157
+ `git status --porcelain` then shows the removal: `git commit -m "factory(<slug>): close"` and
99
158
  `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
159
+ That push re-runs CI on the PR, after `merge-gate` saw it green. Read the PR's checks again
101
160
  once, with the bounded wait the `merge-gate` brick names (30 minutes at most), and add the
102
161
  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.
162
+ report. With no close commit, CI did not re-run: the final state is the one `merge-gate`
163
+ read. A red result is reported, never reworked: the run has closed.
164
+ **The merge proposal.** Only when that final state is green: show the user the PR URL, the CI
165
+ state and each `review-panel` seat's verdict, and ask once whether to merge. Only on the
166
+ user's explicit yes in chat: `gh pr merge <pr> --squash` (`glab mr merge <mr> --squash` on
167
+ GitLab). No Geneseed gate asks before that command: the user's yes is the only guard, so
168
+ never run it on anything else (not on a rule, a note, or an earlier yes). On a no, or no
169
+ answer, the PR stays open. Red or pending CI: no proposal. Never enable auto-merge.
104
170
  9. On `$stop`: the engine hands out no stage after a stop, so have the `docs` {{AGENT}} write the
105
171
  run report the `retro` brick would: the stop `reason` first, then the work item, the PR URL if
106
172
  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
173
+ the loops' notes. A closed loop's notes left with its `LOOP.md`: read each from git as the
174
+ `retro` brick says (`git log --format=%H --diff-filter=D <merge-base>..HEAD -- LOOP.md`, then
175
+ `git show <commit>^:LOOP.md`); a stopped loop's `LOOP.md` is still at the root. It goes to `.geneseed/factory-runs/<slug>.md`, or to the OS temp directory
108
176
  when `git check-ignore -q <that path>` exits non-zero. No tracked file changes, no commit; only
109
177
  a lesson that holds beyond this run goes into memory, one entry. Leave the branch and
110
178
  `FACTORY.md` as they are.
111
179
  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.**
180
+ its reason, the run report's path, the branch, and whether the PR was merged on the user's yes
181
+ or left open. **Never merge without that yes.**
113
182
 
114
183
  ## Resume
115
184
 
@@ -119,8 +188,9 @@ says a loop still runs, resume that loop first with `geneseed loop next` (the `l
119
188
 
120
189
  ## Done when
121
190
 
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.
191
+ - `$close` is reported with the PR open, `FACTORY.md` removed, and the final CI state read and
192
+ reported (after the close commit, or `merge-gate`'s when there was none); or `$stop` is
193
+ reported with its reason and the run report. The PR was merged on the user's yes, asked once
194
+ at the end, or left open; a `$stop` merges nothing.
125
195
 
126
196
  <!-- INCLUDE: skills/_self-improvement.md -->
@@ -7,7 +7,7 @@
7
7
 
8
8
  ## Procedure
9
9
  1. **Locate.** Run `geneseed status --json` first: `installs` lists every install on this machine — host, scope, root, state, theme, footprint, posture, mode, packs, excluded rules — and `rebuild`, the command that reproduces each one exactly. `geneseed` not on PATH → ask the user before using `npx geneseed` (it downloads the package), and prefix every command below the same way. Still nothing → look for a host root file: `~/.config/opencode/AGENT.md` or `.opencode/AGENT.md` (OpenCode), `~/.claude/CLAUDE.md` or `.claude/` (Claude Code), `.openclaude/` (OpenClaude), `AGENTS.md` beside `.bob/` (Bob). None → say so; never install to "fix" it.
10
- 2. **Read state** with the read-only verbs, cheapest first ({{DOCTRINE:context-economy}}): `geneseed status --json`, `geneseed version`, `geneseed catalog` (optionally `agents|skills|laws|ontology|doctrines`), `geneseed doctor`, `geneseed diff`, `geneseed mcp`, `geneseed memory list`, `geneseed exclude list`.
10
+ 2. **Read state** with the read-only verbs, cheapest first ({{DOCTRINE:context-economy}}): `geneseed status --json`, `geneseed version`, `geneseed catalog` (optionally `agents|skills|laws|ontology|doctrines`), `geneseed doctor`, `geneseed diff`, `geneseed mcp`, `geneseed memory list`, `geneseed memory consolidate` (rebuilds only the generated index, from the fact files), `geneseed exclude list`.
11
11
  3. **Read a piece** from disk, not from recall ({{LAW:verify-before-asserting}}): `<root>/agents/<name>.md`, `<root>/skills/<name>/SKILL.md`, `<root>/memory/`, `<root>/notebook/`. The {{ONTOLOGY}}, the {{LAWS}} and the active {{DOCTRINES}} are numbered `## N. …` sections of the install's root file.
12
12
  4. **Change an install only when the user asked for that change** ({{LAW:one-intent-one-act}}). Take that install's `rebuild` command from step 1, edit only the flag the user named (add it if the command omits it — `--posture`, `--mode` and `--trust` are left out at their defaults) — `--theme`, `--footprint lean|full`, `--posture`, `--mode direct|foreman`, `--trust prudent|balanced|aggressive`, `--doctrines craft,rigor|none`, `--exclude-rules "process 7"|none` — dry-run it first by running the same flags through `geneseed validate`, show the command, and run it once the user agrees. Never rebuild from a bare `geneseed build`: every omitted flag resets that setting to the generator default. Confirm with `geneseed status`.
13
13
  5. **Other writes also need the user's word:** `geneseed memory rm <name>` (archives; `--purge` deletes for good), `geneseed exclude add|remove <path>`, `geneseed web start|stop`, `geneseed uninstall --target <root> --yes`. Personal rules and the profile belong to their own {{SKILLS}}; do not edit `user-rules.md` or `PROFILE.md` from here.
@@ -77,8 +77,9 @@ What `score --diff`, `decide` and `record` print back:
77
77
  `origin` and a `message_file` path without spaces: if the path has a space, quote it and accept
78
78
  that the gate asks; with no remote, report and stop instead of retrying.
79
79
  - **`{discard: true}`** (with `resplit` when an inner ring was exhausted) — set the attempt aside,
80
- keeping `LOOP.md`: `git stash -u -m loop-discarded -- . :^LOOP.md` (never `git stash push` —
81
- the word `push` trips the git gate mid-run).
80
+ keeping the engine files: `git stash -u -m loop-discarded -- . :^LOOP.md :^FACTORY.md` (never
81
+ `git stash push` — the word `push` trips the git gate mid-run). `FACTORY.md` is the factory
82
+ run's state when this loop is one of its stages: stashed, the run would lose it or roll it back.
82
83
  - **`{done: true}`**, **`{empty}`**, **`{resumed}`**, **`{dropped}`**, **`{node}`**, **`{verify}`**,
83
84
  **`{awaiting}`** (a gate), **`{stopped}`**, a declared score, and any result with
84
85
  `commit: false` (a blocking diff score included — it surfaces as `{awaiting}`) — call `next`
@@ -25,7 +25,7 @@ instead: it runs this flow topic by topic in its own context and also assigns to
25
25
  archiving would keep it on disk, so propose deleting it outright, on sight
26
26
  ({{LAW:sealed-secrets}}).
27
27
  5. **Rebuild the index** with
28
- `geneseed learn --consolidate --memory <the {{PATH_MEMORY}}/ dir's path>`: one pointer line per
28
+ `geneseed memory consolidate --memory <the {{PATH_MEMORY}}/ dir's path>`: one pointer line per
29
29
  surviving file in its `topics/<topic>.md`, and the `MEMORY.md` map recounted. Each
30
30
  hook is the fact's `description`, so sharpen a weak hook there — it should say why a
31
31
  future session would open the fact.
@@ -44,7 +44,7 @@ Then take exactly one branch.
44
44
  3. Infer the `type` (`user` | `feedback` | `project` | `reference`) and draft the file
45
45
  per the {{MEMORY}} convention.
46
46
  4. Write the file, with no prompt, and rebuild the index
47
- (`geneseed learn --consolidate --memory <the {{PATH_MEMORY}}/ dir's path>`) so its line
47
+ (`geneseed memory consolidate --memory <the {{PATH_MEMORY}}/ dir's path>`) so its line
48
48
  lands in `topics/<topic>.md` and the `MEMORY.md` map recounts. Then say in one line
49
49
  what you wrote and where, so a wrong inference is visible at once; the web console
50
50
  shows it to the user later too.
@@ -62,7 +62,7 @@
62
62
  "DESC_PARALLEL_AGENTS": "<one-line description: fan independent subtasks to concurrent subagents, then converge>",
63
63
  "DESC_PIPELINE": "<one-line description: spawn a small crew — analyst, developer, tester — to work a substantial task in isolation, merging only on mechanical proof (tests + lint green)>",
64
64
  "DESC_LOOP": "<one-line description: work a requirement in small scored iterations on a loop/* branch, stepping the geneseed loop state machine>",
65
- "DESC_FACTORY": "<one-line description: carry one work item (request, document or issue) through a factory of bricks and loops to an open PR with green CI, stepping the geneseed factory state machine; never merges>",
65
+ "DESC_FACTORY": "<one-line description: carry one work item (request, document or issue) through a factory of bricks and loops to an open PR with green CI, stepping the geneseed factory state machine; never merges without the user's yes, asked once at the end>",
66
66
  "DESC_BRICK_FORGE": "<one-line description: author or adapt a loop brick at project, global or shipped level, checked by geneseed loop check>",
67
67
  "DESC_FACTORY_FORGE": "<one-line description: compose bricks and loops into a factory through an interview, write it at project or global level, check it with geneseed factory check, and offer brick-forge for a missing brick>",
68
68
  "DESC_DEVELOP": "<one-line description: drive a code change through cover-and-verify — smallest change, tests written for it, affected suite green, committed slice by slice>",