geneseed 5.0.3 → 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 (128) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +3 -3
  3. package/SHIPPED.md +2 -2
  4. package/adapters/claude-code/README.md +5 -1
  5. package/adapters/openclaude/README.md +3 -1
  6. package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
  7. package/adapters/opencode/workflows/_runtime.js +1 -1
  8. package/bin/geneseed-cli.mjs +3 -0
  9. package/bin/geneseed-hook.mjs +10 -2
  10. package/docs/PRD.md +1 -1
  11. package/docs/README.md +4 -1
  12. package/docs/concepts/enforcement-table.md +1 -1
  13. package/docs/concepts/exclusions.md +1 -1
  14. package/docs/concepts/factories.md +151 -0
  15. package/docs/concepts/hooks.md +1 -1
  16. package/docs/concepts/host-matrix.md +1 -0
  17. package/docs/concepts/loop-gates.md +3 -0
  18. package/docs/concepts/loops.md +1 -0
  19. package/docs/concepts/rules.md +1 -1
  20. package/docs/extending.md +5 -1
  21. package/docs/guides/autostart.md +2 -0
  22. package/docs/guides/run-a-factory.md +88 -0
  23. package/docs/guides/set-up-ownership.md +1 -0
  24. package/docs/reference/factory-actions.md +22 -0
  25. package/docs/reference/loop-actions.md +1 -1
  26. package/docs/reference/plugin-activity.md +1 -1
  27. package/docs/web-ui.md +35 -2
  28. package/harness.config.json +1 -1
  29. package/js/README.md +20 -2
  30. package/js/build/args.mjs +14 -2
  31. package/js/build/source.mjs +19 -0
  32. package/js/cli-table.json +166 -2
  33. package/js/factory/cli.mjs +153 -0
  34. package/js/factory/graph.mjs +245 -0
  35. package/js/factory/registry.mjs +71 -0
  36. package/js/factory/state.mjs +429 -0
  37. package/js/hosts/activity.mjs +3 -3
  38. package/js/hosts/geneseed-dir.mjs +1 -1
  39. package/js/hosts/gitref.mjs +21 -0
  40. package/js/hosts/hooks-context.mjs +63 -9
  41. package/js/hosts/hooks-prims.mjs +1 -1
  42. package/js/hosts/settings.mjs +5 -4
  43. package/js/inspect/checks-authoring.mjs +11 -1
  44. package/js/inspect/cost.mjs +91 -5
  45. package/js/inspect/doctor.mjs +2 -1
  46. package/js/inspect/inventory.mjs +1 -1
  47. package/js/loop/catalog.mjs +24 -12
  48. package/js/loop/cli.mjs +21 -15
  49. package/js/loop/graph.mjs +13 -4
  50. package/js/loop/registry.mjs +65 -28
  51. package/js/loop/state.mjs +18 -8
  52. package/js/web/api.mjs +43 -1
  53. package/js/web/catalog.mjs +38 -2
  54. package/js/web/daemon.mjs +136 -6
  55. package/js/web/handler.mjs +14 -5
  56. package/js/web/routes.mjs +10 -3
  57. package/js/web/server.mjs +4 -1
  58. package/package.json +1 -1
  59. package/registry.json +14 -0
  60. package/src/AGENT.md.tmpl +5 -7
  61. package/src/bricks/docs-update.md +5 -0
  62. package/src/bricks/holdout-write.md +23 -0
  63. package/src/bricks/holdout.md +25 -0
  64. package/src/bricks/intake.md +18 -0
  65. package/src/bricks/merge-gate.md +22 -0
  66. package/src/bricks/pr-open.md +21 -0
  67. package/src/bricks/retro.md +17 -0
  68. package/src/bricks/test.md +4 -1
  69. package/src/bricks/triage.md +19 -0
  70. package/src/doctrines/comms.md +29 -41
  71. package/src/doctrines/craft.md +3 -10
  72. package/src/doctrines/ops.md +4 -15
  73. package/src/doctrines/rigor.md +1 -5
  74. package/src/factories/analysis-to-build.json +34 -0
  75. package/src/factories/bug-report-to-fix.json +32 -0
  76. package/src/factories/issue-to-pr.json +49 -0
  77. package/src/skills/_checkpoints.md +1 -0
  78. package/src/skills/adhd.md +1 -1
  79. package/src/skills/factory-forge.md +97 -0
  80. package/src/skills/factory.md +126 -0
  81. package/src/skills/parallel-agents.md +1 -1
  82. package/src/skills/workflow.md +2 -1
  83. package/themes/_TEMPLATE.json +4 -2
  84. package/themes/biker.json +4 -2
  85. package/themes/commentator.json +4 -2
  86. package/themes/cyberpunk.json +4 -2
  87. package/themes/gamer.json +4 -2
  88. package/themes/imperial.json +4 -2
  89. package/themes/joker.json +4 -2
  90. package/themes/marvin.json +4 -2
  91. package/themes/mean.json +4 -2
  92. package/themes/military.json +4 -2
  93. package/themes/neutral.json +4 -2
  94. package/themes/pirate.json +4 -2
  95. package/themes/sports.json +4 -2
  96. package/themes/verstappen.json +4 -2
  97. package/themes/wizard.json +4 -2
  98. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
  99. package/web/dist/assets/{Activity-Ck_Xffpo.js → Activity-BaoxwVFH.js} +1 -1
  100. package/web/dist/assets/{ActivityDetail-CBxVS4mU.js → ActivityDetail-C_bFD0rW.js} +1 -1
  101. package/web/dist/assets/{Bonsai-BlOwsvW6.js → Bonsai-B01lLf0m.js} +1 -1
  102. package/web/dist/assets/{CopyButton-DFMOIGbe.js → CopyButton-Bc66KPyA.js} +1 -1
  103. package/web/dist/assets/Dashboard-X7GZzGJp.js +2 -0
  104. package/web/dist/assets/{Docs-D_2Jt6gU.js → Docs-LRYVnGLG.js} +2 -2
  105. package/web/dist/assets/Factories-ARenKBiP.js +1 -0
  106. package/web/dist/assets/{GreenhouseView-WalcX5bp.js → GreenhouseView-CfWR2-sX.js} +1 -1
  107. package/web/dist/assets/{Installs-UGiPDMDt.js → Installs-nfFHnovH.js} +3 -3
  108. package/web/dist/assets/{JournalView-CZtXQz-v.js → JournalView-lpOHcHKK.js} +1 -1
  109. package/web/dist/assets/{Kits-XQHsazCN.js → Kits-Bw5EQl_i.js} +1 -1
  110. package/web/dist/assets/Laws-CnZJ0wjZ.js +4 -0
  111. package/web/dist/assets/LibRows-Hqvf1beK.js +1 -0
  112. package/web/dist/assets/Library-JaSsp6Yr.js +3 -0
  113. package/web/dist/assets/Loops-ZaHC5MVl.js +2 -0
  114. package/web/dist/assets/{OperatorHudView-CeDw5qMB.js → OperatorHudView-CggG0_sK.js} +1 -1
  115. package/web/dist/assets/{Personal-PVmGA2-M.js → Personal-BObvlb70.js} +2 -2
  116. package/web/dist/assets/{Settings-DWuxwh4i.js → Settings-BFfPMPc9.js} +1 -1
  117. package/web/dist/assets/{Tabs-d2RIRAKT.js → Tabs-B594Pad_.js} +1 -1
  118. package/web/dist/assets/api-DLDVY3K-.js +1 -0
  119. package/web/dist/assets/{index-BNttaGQb.js → index-DsLmKHw0.js} +3 -3
  120. package/web/dist/assets/index-DvPjphz0.css +1 -0
  121. package/web/dist/index.html +3 -3
  122. package/web/dist/assets/Dashboard-BUdUTjbB.js +0 -2
  123. package/web/dist/assets/Laws-B6A55S-2.js +0 -4
  124. package/web/dist/assets/Library-D7L0Wdbh.js +0 -3
  125. package/web/dist/assets/Loops-C0loS73u.js +0 -2
  126. package/web/dist/assets/RailCats-BGZnJ6fa.js +0 -1
  127. package/web/dist/assets/api-BMFDSXoB.js +0 -1
  128. package/web/dist/assets/index-BEI5ugYQ.css +0 -1
@@ -1,7 +1,7 @@
1
1
  **{{PACK_COMMS}}** — how answers are presented.
2
2
 
3
- ### {{DOCTRINE:codes-that-persist}} Codes That Persist
4
- <!-- note: summary: Give tracked items stable reference codes; never renumber one. -->
3
+ ### {{DOCTRINE:codes-that-persist}} Codes and Markers
4
+ <!-- note: summary: Give tracked items stable codes, never renumbered; mark an ask that waits on the user. -->
5
5
  <!-- LEAN:begin -->
6
6
  Give every tracked item a short reference code and keep it unchanged for the rest of
7
7
  the session — `D` decisions, `O` options, `F` findings, `R` risks, `Q` questions,
@@ -15,16 +15,35 @@ for a kind the list omits, and never renumber a code once issued — the user wi
15
15
  it back, and a moved code makes their reply mean something you did not say. A code is an address, not an ornament:
16
16
  it lets a long exchange be answered by reference, and a decision taken on turn
17
17
  three still be named on turn thirty. Where the {{ONTOLOGY}}'s {{ONT_CONDUCT}}
18
- governs how an answer speaks, this is only the addressing convention — a practice
18
+ governs how an answer speaks, this is only the addressing and marking convention — a practice
19
19
  a repository adopts or drops like any other rule in these {{DOCTRINES}}.
20
+
21
+ When a reply stops and waits on the user — a question, a choice, an approval, a blocker —
22
+ make the ask stand apart from the work around it, so a reader who skims finds it first. Open
23
+ the ask with one emoji marker that names its kind: `❓` a question, `👉` an act the user must
24
+ do, `⚠️` a risk or a blocker, `✅` work done that waits on their sign-off. The marker comes
25
+ before the code: `❓ **Q3** — keep the v1 route?`. Lay out
26
+ the options and the flows with arrows — `→ yes: keep it · → no: remove it` — one option per
27
+ line past two, the recommended one first and named as such. Put one ask in each block; where
28
+ the answer to one question changes the next, ask them one at a time. Use colour only where
29
+ the surface renders it, such as markdown or a rich host; never write ANSI escapes or colour
30
+ markup into plain text that prints them raw. Routine output stays plain: a reply that waits
31
+ on nothing carries no marker, and a marker on every line marks nothing. The markers are
32
+ signs, not words, so the prose around them keeps {{DOCTRINE:simplified-technical-english}}.
33
+ Make the ask understood, not only seen. Before a command the user must run or approve, or a
34
+ question or a choice that is not clear by itself, write one or two plain lines: what it does,
35
+ why now, and what it changes or risks when that is not obvious. For a question, say what the
36
+ answer decides. An ask that is clear by itself stays bare: `ls`, or a yes/no question with no
37
+ stakes.
20
38
  <!-- LEAN:else -->
21
- Give every tracked item a short reference code, unchanged for the session —
22
- `D` decisions, `O` options, `F` findings, `R` risks, `Q` questions, `A` actions.
23
- Any reply naming two or more such items takes codes, a {{SKILL}}'s or {{AGENT}}'s
24
- report included; one item or none takes none. The code opens the line, never a bare
25
- `1.` or bullet: `**F1** — token logged in plain text`, `**Q2** — keep the v1 route?`
26
- Number from one within each kind and keep counting across turns (after `F3` comes
27
- `F4`), invent letters for missing kinds, never renumber a code once issued.
39
+ Give every tracked item a code that never changes in the session — `D` decisions, `O` options,
40
+ `F` findings, `R` risks, `Q` questions, `A` actions; invent letters for other kinds. A reply naming
41
+ two or more items codes them, reports included; the code opens the line:
42
+ `**F1** — token logged in plain text`. Count on across turns, never renumber. When a reply waits
43
+ on the user, open that ask with one marker before its code — `❓` question, `👉` act to do, `⚠️`
44
+ risk or blocker, `✅` done, waits on sign-off: `❓ **Q3** — keep the v1 route?`. One ask per block,
45
+ the recommended option first (`→`). An ask not clear alone gets one or two plain lines: what it
46
+ does, why now, what it risks or decides. Routine output stays plain; no raw ANSI.
28
47
  <!-- LEAN:end -->
29
48
 
30
49
  ### {{DOCTRINE:structure-beside-prose}} Structure Beside Prose
@@ -95,34 +114,3 @@ most in an instruction, 25 in a description. Instructions: imperative, one actio
95
114
  condition first. Active voice, no -ing forms, no dropped articles, one word per meaning
96
115
  (`use`, not `utilize`). In another language, keep it and these rules.
97
116
  <!-- LEAN:end -->
98
-
99
- ### {{DOCTRINE:mark-the-ask}} Mark the Ask
100
- <!-- note: summary: Mark an ask that waits on the user, and explain it when it is not clear alone; routine output stays plain. -->
101
- <!-- LEAN:begin -->
102
- When a reply stops and waits on the user — a question, a choice, an approval, a blocker —
103
- make the ask stand apart from the work around it, so a reader who skims finds it first. Open
104
- the ask with one emoji marker that names its kind: `❓` a question, `👉` an act the user must
105
- do, `⚠️` a risk or a blocker, `✅` work done that waits on their sign-off. The marker comes
106
- before the code ({{DOCTRINE:codes-that-persist}}): `❓ **Q3** — keep the v1 route?`. Lay out
107
- the options and the flows with arrows — `→ yes: keep it · → no: remove it` — one option per
108
- line past two, the recommended one first and named as such. Put one ask in each block; where
109
- the answer to one question changes the next, ask them one at a time. Use colour only where
110
- the surface renders it, such as markdown or a rich host; never write ANSI escapes or colour
111
- markup into plain text that prints them raw. Routine output stays plain: a reply that waits
112
- on nothing carries no marker, and a marker on every line marks nothing. The markers are
113
- signs, not words, so the prose around them keeps {{DOCTRINE:simplified-technical-english}}.
114
- Make the ask understood, not only seen. Before a command the user must run or approve, or a
115
- question or a choice that is not clear by itself, write one or two plain lines: what it does,
116
- why now, and what it changes or risks when that is not obvious. For a question, say what the
117
- answer decides. An ask that is clear by itself stays bare: `ls`, or a yes/no question with no
118
- stakes.
119
- <!-- LEAN:else -->
120
- When a reply waits on the user — a question, a choice, an approval, a blocker — mark the
121
- ask. Open it with one marker: `❓` question, `👉` act to do, `⚠️` risk or blocker, `✅` done,
122
- waits on sign-off; it comes before the code: `❓ **Q3** — keep the v1 route?`. Arrows (`→`)
123
- lay out options and flows, the recommended option first. One ask per block. Colour only
124
- where the host renders it, never raw ANSI in plain text. Routine output stays plain; markers
125
- are signs, not words. An ask that is not clear by itself carries one or two plain lines before
126
- it: what it does, why now, what it changes or risks; for a question, what the answer decides.
127
- A clear ask stays bare.
128
- <!-- LEAN:end -->
@@ -1,7 +1,7 @@
1
1
  **{{PACK_CRAFT}}** — how code is written.
2
2
 
3
3
  ### {{DOCTRINE:automate-repetition}} Automate Repetition
4
- <!-- note: summary: If it repeats, make it a script or skill; reuse first. -->
4
+ <!-- note: summary: If it repeats, automate it: script, skill or code, by the task. -->
5
5
  <!-- LEAN:begin -->
6
6
  When an action repeats, automate it — and choose the vessel by the nature of the task,
7
7
  not by how many similar steps one session needs. Do not
@@ -14,18 +14,13 @@ perform by hand what the machine can perform a thousand times.
14
14
  - a recurring, deterministic, exact operation (parsing, counting, API calls, anything
15
15
  run unattended or where a model would err) → kept, versioned code.
16
16
  Markdown is the default for what recurs; code is kept only where exactness or unattended
17
- automation demands it. When you build a {{SKILL}}, make it a vessel for one coherent
18
- domain — not a single command and not a grab-bag: seek an existing {{SKILL}} whose domain
19
- already covers the need and extend it before forging a new one, and name {{SKILLS}} by
20
- domain. Reuse before creating.
17
+ automation demands it.
21
18
  <!-- LEAN:else -->
22
19
  When an action repeats, automate it — choosing the vessel by the task, not the step
23
20
  count: a one-off batch gets a throwaway {{SCRIPT}} outside the repository, never kept; a
24
21
  recurring judgement procedure gets a markdown rule in the domain {{SKILL}} or {{AGENT}}
25
22
  spec; a recurring exact or unattended operation gets kept, versioned code. Markdown is
26
- the default for what recurs. Before forging a new {{SKILL}}, seek an existing one whose
27
- domain covers the need and extend it; build each {{SKILL}} for one coherent domain — not
28
- a single command, not a grab-bag — and name {{SKILLS}} by domain. Reuse before creating.
23
+ the default for what recurs.
29
24
  <!-- LEAN:end -->
30
25
 
31
26
  ### {{DOCTRINE:english-configuration}} English Configuration
@@ -58,11 +53,9 @@ drifts from the code is a defect, not a deferred task.
58
53
  <!-- LEAN:begin -->
59
54
  Before adding a file, module, function, or abstraction, confirm an equivalent
60
55
  does not already exist; prefer extending what is there. Duplication is a defect.
61
- ({{DOCTRINE:automate-repetition}} applies this to {{SKILLS}}; here it binds all code.)
62
56
  <!-- LEAN:else -->
63
57
  Before adding a file, module, function, or abstraction, confirm an equivalent does not
64
58
  already exist; prefer extending what is there. Duplication is a defect.
65
- ({{DOCTRINE:automate-repetition}} applies this to {{SKILLS}}; here it binds all code.)
66
59
  <!-- LEAN:end -->
67
60
 
68
61
  ### {{DOCTRINE:respect-conventions}} Respect Conventions
@@ -54,9 +54,7 @@ applied, yet did not endure. Before altering any configuration, ask which layer
54
54
  authoritative and write there alone. Persistence lives at the source, not the
55
55
  surface.
56
56
  <!-- LEAN:else -->
57
- Where a system renders live state from a source layer — a database the UI re-reads, a
58
- compose file regenerated from stored config — edit the source, never the rendered artifact.
59
- Before altering any configuration, ask which layer is authoritative and write there alone.
57
+ Edit the authoritative layer, never the rendered artifact.
60
58
  <!-- LEAN:end -->
61
59
 
62
60
  ### {{DOCTRINE:complete-the-teardown}} Complete the Teardown
@@ -85,9 +83,7 @@ citing it, this governs what to record in the first place: not the volatile valu
85
83
  but the means to derive it — the probe, the query, the live computation. Record
86
84
  how to check, and check at the hour of need.
87
85
  <!-- LEAN:else -->
88
- A fact that renews itself — a rotating certificate — is never inscribed as a snapshot.
89
- Record not the volatile value but the means to derive it — the probe, the query — and check
90
- at the hour of need ({{LAW:verify-before-asserting}}).
86
+ Record how to derive a volatile fact, never its value.
91
87
  <!-- LEAN:end -->
92
88
 
93
89
  ### {{DOCTRINE:restart-is-not-reload}} Restart Is Not Reload
@@ -103,10 +99,7 @@ recreate, down-and-up, reload, or full restart — perform it, then confirm the
103
99
  value in the *running* system, not the file ({{LAW:verify-before-asserting}}). A correct file above a
104
100
  stale process looks like a finished job and is not one.
105
101
  <!-- LEAN:else -->
106
- A running process holds the config it read at start. After editing any config, ask what act
107
- makes it be *read* — often not a restart. Establish which — recreate, down-and-up, reload,
108
- full restart — perform it, then confirm the new value in the *running* system, not the file
109
- ({{LAW:verify-before-asserting}}).
102
+ After a config edit, confirm the new value in the running process, not the file.
110
103
  <!-- LEAN:end -->
111
104
 
112
105
  ### {{DOCTRINE:serialize-against-a-rationed-resource}} Serialize Against a Rationed Resource
@@ -124,9 +117,5 @@ unchanged on retry is a hard limit, not transient backpressure: stop and report
124
117
  batches independent calls, this names the calls that are not independent — they draw on
125
118
  one allowance. A smaller complete sample beats a larger one gathered through failures.
126
119
  <!-- LEAN:else -->
127
- A shared resource that rations its answers — a rate-limited API, a quota, a single
128
- gateway — is called in sequence, never fanned out. Before any parallelism, divide the
129
- quota by its callers; if one share cannot finish the work, do not parallelise. Back off on
130
- each refusal, within a retry cap set first. A refusal repeating unchanged is a hard limit:
131
- stop and report it ({{LAW:surface-failures}}), never re-send the batch.
120
+ Call a rationed resource in sequence; a repeated refusal is a hard limit — stop and report.
132
121
  <!-- LEAN:end -->
@@ -103,9 +103,5 @@ confused, or steered by untrusted input ({{LAW:data-not-orders}}). Where {{LAW:l
103
103
  power you take, this governs the power you hand out; {{DOCTRINE:prove-the-gate}} proves the
104
104
  gate once it stands.
105
105
  <!-- LEAN:else -->
106
- Wherever a system lets an agent act, ask approval of a party it cannot satisfy alone,
107
- enforce the allowlist at the boundary the call must cross, and validate against real state.
108
- Never let permission live in the governed agent's own prompt. Ship anything taking
109
- autonomous control of physical state, money, or production disarmed, armed only by explicit
110
- human act ({{LAW:data-not-orders}}).
106
+ Permission lives at a boundary the agent cannot satisfy alone; autonomous control ships disarmed.
111
107
  <!-- LEAN:end -->
@@ -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
+ }
@@ -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
  ```
@@ -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,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 -->
@@ -11,7 +11,7 @@
11
11
  ## Procedure
12
12
  1. Confirm independence: the subtasks must not depend on each other's output or write the same files ({{DOCTRINE:one-writer-per-file}}). Write down each unit's **write set** — the files or globs it may change — and intersect them; an overlap runs in sequence or goes to one owner, and shared append files (registries, index tables, lockfiles, generated bundles) stay with you. If they're sequential or share state, use [plan](plan.md) instead.
13
13
  2. Split the work into self-contained units, each with one clear goal and a defined output contract — what it must return. Several small edits of one kind (the same fix, constant or field across files) form ONE unit with the union write set and get one review.
14
- 3. Dispatch each unit to its own subagent in one batch, each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (no commit/push — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
14
+ 3. Dispatch each unit to its own subagent in one batch — units that call one rationed resource run in sequence instead ({{DOCTRINE:serialize-against-a-rationed-resource}}) — each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (no commit/push — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
15
15
  4. Keep the main context lean: collect each subagent's distilled result, not its working transcript. Watch every unit you dispatched in the background as the [pipeline {{SKILL}}](pipeline.md)'s step 2 watches a crew: a result without its check, or one that says it is still waiting, is a failure to act on at once — resume the unit or redo it — never a notification to wait for.
16
16
  5. Converge: compare each unit's changed files against its write set and against its siblings' — an edit outside the set, a file two units touched, or a file in a batch's set that never changed is a conflict you resolve before anything else — apply the shared-file rows yourself, then verify the combined outcome. A conflict or ambiguity between the plan, the findings and the code is yours to decide: decide it, record `Ruling: <choice> — <why> — <cost if wrong>` in the worklog, and continue. Stop only for what {{LAW:echo-the-intent}}, {{LAW:deletion-is-deliberate}} or {{DOCTRINE:consent-before-push}} names; every ruling goes in the final report ({{DOCTRINE:declare-the-judgment-calls}}).
17
17
  6. **A plan with blocking edges.** To build a [plan](plan.md) file's slices — each with its `Blocked by:` line — in one run, dispatch every unblocked slice on its own branch off one integration branch, merge each into it as it returns (each merge is a commit — {{DOCTRINE:consent-before-push}} stays with you), and recompute the unblocked set from the plan after every merge — newly freed slices go out at once. When the plan names a `Spec:`, every slice reads it once; the spec outranks the plan where they conflict. Each slice branches off the integration tip at its own dispatch (its BASE) and merges the current tip back into its branch before returning, so a conflict with a sibling resolves on the slice's branch; before re-running the proof, confirm the branch descends from BASE and the diff is non-empty — an empty diff is a failure, not a clean result. Never diff against `HEAD~1`. When the plan is exhausted, review the integration branch whole with [geneseed-code-review](geneseed-code-review.md) before reporting.
@@ -64,7 +64,8 @@ carries the script API — load it before writing one).
64
64
  `parallel()`. Pass `isolation: 'worktree'` to each agent that edits in parallel — both
65
65
  runtimes take it; read-only agents need none. After the fan-out, compare the changed
66
66
  files in plain script code (OpenCode hands them to you as `overlaps()`) — a file two
67
- agents touched goes to one merge agent, never to whoever wrote last.
67
+ agents touched goes to one merge agent, never to whoever wrote last. Agents that call one
68
+ rationed resource run in sequence, never in one `parallel()` ({{DOCTRINE:serialize-against-a-rationed-resource}}).
68
69
  5. **Pass the task as `args`, never baked in** — target paths, the motion, the question,
69
70
  any timestamp. Scripts stay deterministic: no wall clock, no randomness, nothing
70
71
  read from the environment that the next run would see differently, so a run is a
@@ -62,7 +62,9 @@
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
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
+ "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>",
66
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>",
67
69
  "DESC_TEACH": "<one-line description: teach toward a result — crash course, decode confusing material, or a day-by-day path to a deadline — or test what the user knows with a drill, an explain-it-back check or a gap check>",
68
70
  "DESC_ADHD": "<one-line description: an opt-in output mode for a reader with ADHD — next action first, numbered steps, state restated, tangents held back; on until \"stop adhd mode\">",
@@ -120,11 +122,10 @@
120
122
  "DOC_CONSENT_BEFORE_PUSH": "<themed title for the process rule Consent Before Push>",
121
123
  "DOC_BOUND_THE_LOOP": "<themed title for the process rule Bound the Loop>",
122
124
  "DOC_ONE_WRITER_PER_FILE": "<themed title for the process rule One Writer Per File>",
123
- "DOC_CODES_THAT_PERSIST": "<themed title for the comms rule Codes That Persist>",
125
+ "DOC_CODES_THAT_PERSIST": "<themed title for the comms rule Codes and Markers>",
124
126
  "DOC_STRUCTURE_BESIDE_PROSE": "<themed title for the comms rule Structure Beside Prose>",
125
127
  "DOC_DECLARE_THE_JUDGMENT_CALLS": "<themed title for the comms rule Declare the Judgment Calls>",
126
128
  "DOC_SIMPLIFIED_TECHNICAL_ENGLISH": "<themed title for the comms rule Simplified Technical English>",
127
- "DOC_MARK_THE_ASK": "<themed title for the comms rule Mark the Ask>",
128
129
  "INTRO_DOC": "<themed intro: this file is the entry point an AI agent reads in this repo>",
129
130
  "INTRO_AGENTS": "<themed intro to the Agents section — delegate focused work to a specialist>",
130
131
  "INTRO_SKILLS": "<themed intro to the Skills section — run the written procedure before improvising>",
@@ -138,6 +139,7 @@
138
139
  "DOCTRINES": "<plural of DOCTRINE — the tier/section noun>",
139
140
  "AGENT": "<singular noun for an agent in this theme, e.g. Agent / Adept>",
140
141
  "AGENTS": "<plural of AGENT>",
142
+ "PRIMARY_AGENT": "<the main agent, the one every agent inherits from>",
141
143
  "SKILL": "<singular noun for a skill in this theme, e.g. Skill / Rite>",
142
144
  "SKILLS": "<plural of SKILL>",
143
145
  "MEMORY": "<noun for the memory store in this theme, e.g. Memory>",