geneseed 5.0.1 → 5.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +92 -0
- package/README.md +4 -4
- package/SHIPPED.md +2 -2
- package/adapters/claude-code/README.md +11 -5
- package/adapters/openclaude/README.md +3 -1
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +3 -0
- package/adapters/opencode/plugins/geneseed-context.js +12 -1
- package/adapters/opencode/plugins/geneseed-guard.js +594 -73
- package/adapters/opencode/plugins/geneseed-learn.js +1 -1
- package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
- package/adapters/opencode/workflows/_runtime.js +1 -1
- package/bin/geneseed-cli.mjs +3 -0
- package/bin/geneseed-hook.mjs +31 -9
- package/docs/PRD.md +1 -1
- package/docs/README.md +4 -1
- package/docs/concepts/enforcement-table.md +23 -4
- package/docs/concepts/exclusions.md +48 -2
- package/docs/concepts/factories.md +151 -0
- package/docs/concepts/foreman-mode.md +19 -4
- package/docs/concepts/hook-gates.md +1 -1
- package/docs/concepts/hooks.md +53 -12
- package/docs/concepts/host-matrix.md +5 -3
- package/docs/concepts/hosts.md +1 -1
- package/docs/concepts/kits.md +18 -0
- package/docs/concepts/loop-gates.md +3 -0
- package/docs/concepts/loops.md +1 -0
- package/docs/concepts/rules.md +1 -1
- package/docs/concepts/shared-tier.md +1 -1
- package/docs/concepts/skills.md +1 -1
- package/docs/extending.md +8 -2
- package/docs/guides/autostart.md +29 -3
- package/docs/guides/choose-your-setup.md +1 -1
- package/docs/guides/migrate.md +1 -1
- package/docs/guides/run-a-factory.md +88 -0
- package/docs/guides/set-up-ownership.md +1 -0
- package/docs/guides/uninstall.md +1 -1
- package/docs/reference/factory-actions.md +22 -0
- package/docs/reference/loop-actions.md +1 -1
- package/docs/reference/plugin-activity.md +1 -1
- package/docs/reference/plugin-context.md +1 -1
- package/docs/reference/plugin-guard.md +24 -5
- package/docs/reference/troubleshoot-doctor.md +2 -2
- package/docs/understand/a-day.md +9 -5
- package/docs/web-ui.md +101 -17
- package/harness.config.json +1 -1
- package/js/README.md +21 -3
- package/js/build/args.mjs +14 -2
- package/js/build/emit-claude.mjs +9 -1
- package/js/build/emit-opencode.mjs +2 -1
- package/js/build/source.mjs +28 -3
- package/js/cli-table.json +287 -3
- package/js/factory/cli.mjs +153 -0
- package/js/factory/graph.mjs +245 -0
- package/js/factory/registry.mjs +71 -0
- package/js/factory/state.mjs +429 -0
- package/js/hosts/activity.mjs +3 -3
- package/js/hosts/geneseed-dir.mjs +2 -2
- package/js/hosts/gitref.mjs +21 -0
- package/js/hosts/hooks-context.mjs +71 -15
- package/js/hosts/hooks-done.mjs +3 -1
- package/js/hosts/hooks-learn.mjs +1 -1
- package/js/hosts/hooks-prims.mjs +271 -1
- package/js/hosts/hooks.mjs +409 -151
- package/js/hosts/hosts.mjs +22 -0
- package/js/hosts/installs.mjs +9 -5
- package/js/hosts/settings.mjs +128 -27
- package/js/hosts/shim.mjs +155 -7
- package/js/hosts/store-watch.mjs +36 -11
- package/js/inspect/checks-authoring.mjs +11 -1
- package/js/inspect/cost.mjs +91 -5
- package/js/inspect/diff.mjs +2 -1
- package/js/inspect/doctor.mjs +2 -1
- package/js/inspect/inventory.mjs +2 -1
- package/js/inspect/validate.mjs +1 -1
- package/js/loop/catalog.mjs +24 -12
- package/js/loop/cli.mjs +21 -15
- package/js/loop/graph.mjs +13 -4
- package/js/loop/registry.mjs +65 -28
- package/js/loop/state.mjs +18 -8
- package/js/maintain/migrate.mjs +2 -2
- package/js/maintain/uninstall.mjs +5 -1
- package/js/web/actions.mjs +17 -1
- package/js/web/api.mjs +52 -11
- package/js/web/catalog.mjs +38 -2
- package/js/web/daemon.mjs +136 -6
- package/js/web/handler.mjs +14 -5
- package/js/web/routes.mjs +12 -4
- package/js/web/server.mjs +4 -1
- package/package.json +1 -1
- package/registry.json +35 -0
- package/src/AGENT.md.tmpl +18 -24
- package/src/agents/_self-improvement.md +7 -6
- package/src/agents/developer.md +3 -2
- package/src/agents/docker-expert.md +1 -0
- package/src/agents/memory-curator.md +3 -2
- package/src/bricks/docs-update.md +5 -0
- package/src/bricks/holdout-write.md +23 -0
- package/src/bricks/holdout.md +25 -0
- package/src/bricks/intake.md +18 -0
- package/src/bricks/merge-gate.md +22 -0
- package/src/bricks/pr-open.md +21 -0
- package/src/bricks/retro.md +17 -0
- package/src/bricks/test.md +4 -1
- package/src/bricks/triage.md +19 -0
- package/src/doctrines/comms.md +29 -41
- package/src/doctrines/craft.md +3 -10
- package/src/doctrines/ops.md +4 -15
- package/src/doctrines/process.md +24 -19
- package/src/doctrines/rigor.md +1 -5
- package/src/factories/analysis-to-build.json +34 -0
- package/src/factories/bug-report-to-fix.json +32 -0
- package/src/factories/issue-to-pr.json +49 -0
- package/src/kits/ci-pipelines/rules.md +10 -0
- package/src/kits/ci-pipelines.json +14 -0
- package/src/kits/docker/rules.md +11 -0
- package/src/kits/docker.json +12 -0
- package/src/memory/README.md +5 -4
- package/src/modes/foreman.md +23 -10
- package/src/notebook/README.md +1 -1
- package/src/skills/_checkpoints.md +1 -0
- package/src/skills/_self-improvement.md +12 -9
- package/src/skills/adhd.md +1 -1
- package/src/skills/compose-ops.md +58 -0
- package/src/skills/factory-forge.md +97 -0
- package/src/skills/factory.md +126 -0
- package/src/skills/gitlab-ci.md +51 -0
- package/src/skills/jenkins-pipeline.md +56 -0
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/pipeline.md +2 -2
- package/src/skills/rule.md +24 -18
- package/src/skills/skill-forge.md +24 -6
- package/src/skills/workflow.md +2 -1
- package/themes/_TEMPLATE.json +9 -4
- package/themes/biker.json +9 -4
- package/themes/commentator.json +9 -4
- package/themes/cyberpunk.json +9 -4
- package/themes/gamer.json +9 -4
- package/themes/imperial.json +9 -4
- package/themes/joker.json +9 -4
- package/themes/marvin.json +9 -4
- package/themes/mean.json +9 -4
- package/themes/military.json +9 -4
- package/themes/neutral.json +9 -4
- package/themes/pirate.json +9 -4
- package/themes/sports.json +9 -4
- package/themes/verstappen.json +9 -4
- package/themes/wizard.json +9 -4
- package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
- package/web/dist/assets/Activity-BaoxwVFH.js +1 -0
- package/web/dist/assets/ActivityDetail-C_bFD0rW.js +1 -0
- package/web/dist/assets/{Bonsai-C1iBAt4v.js → Bonsai-B01lLf0m.js} +1 -1
- package/web/dist/assets/{CopyButton-DJ3a4N88.js → CopyButton-Bc66KPyA.js} +1 -1
- package/web/dist/assets/Dashboard-X7GZzGJp.js +2 -0
- package/web/dist/assets/{Docs-Kffdg5uV.js → Docs-LRYVnGLG.js} +3 -3
- package/web/dist/assets/Factories-ARenKBiP.js +1 -0
- package/web/dist/assets/{GreenhouseView-k56_cBSF.js → GreenhouseView-CfWR2-sX.js} +1 -1
- package/web/dist/assets/{Installs-DtEKLC9h.js → Installs-nfFHnovH.js} +3 -3
- package/web/dist/assets/{JournalView-RQnk5l7I.js → JournalView-lpOHcHKK.js} +1 -1
- package/web/dist/assets/Kits-Bw5EQl_i.js +1 -0
- package/web/dist/assets/Laws-CnZJ0wjZ.js +4 -0
- package/web/dist/assets/LibRows-Hqvf1beK.js +1 -0
- package/web/dist/assets/Library-JaSsp6Yr.js +3 -0
- package/web/dist/assets/Loops-ZaHC5MVl.js +2 -0
- package/web/dist/assets/{OperatorHudView-CM5jNPwL.js → OperatorHudView-CggG0_sK.js} +1 -1
- package/web/dist/assets/Personal-BObvlb70.js +2 -0
- package/web/dist/assets/Settings-BFfPMPc9.js +1 -0
- package/web/dist/assets/Tabs-B594Pad_.js +1 -0
- package/web/dist/assets/api-DLDVY3K-.js +1 -0
- package/web/dist/assets/index-DsLmKHw0.js +6 -0
- package/web/dist/assets/index-DvPjphz0.css +1 -0
- package/web/dist/index.html +3 -3
- package/web/dist/assets/Activity-Ci4PZco3.js +0 -1
- package/web/dist/assets/ActivityDetail-C8hroCND.js +0 -1
- package/web/dist/assets/Dashboard-C_On4KXw.js +0 -2
- package/web/dist/assets/Kits-CXkEBpnf.js +0 -1
- package/web/dist/assets/Laws-DhhIVqmh.js +0 -3
- package/web/dist/assets/Library-CAUiEoJo.js +0 -3
- package/web/dist/assets/Loops-LKD8mF4E.js +0 -2
- package/web/dist/assets/Personal-B6Uoly3C.js +0 -2
- package/web/dist/assets/RailCats-DQxxYBEP.js +0 -1
- package/web/dist/assets/Settings-BTe6-wda.js +0 -1
- package/web/dist/assets/Tabs-CbdDWTp_.js +0 -1
- package/web/dist/assets/api-D_r0Jtla.js +0 -1
- package/web/dist/assets/index-HfGmYXab.js +0 -3
- package/web/dist/assets/index-ao3M-Fhm.css +0 -1
|
@@ -516,7 +516,7 @@ function storeScan(home, found = {}) {
|
|
|
516
516
|
const stamp = (f) => {
|
|
517
517
|
try { const s = statSync(f); if (s.isFile()) found[f] = `${s.size}:${Math.trunc(s.mtimeMs)}` } catch { /* absent */ }
|
|
518
518
|
}
|
|
519
|
-
for (const n of ["user-rules.md", "PROFILE.md", "geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) stamp(path.join(home, n))
|
|
519
|
+
for (const n of ["user-rules.md", "user-rules.draft.md", "PROFILE.md", "geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) stamp(path.join(home, n))
|
|
520
520
|
const walk = (dir) => {
|
|
521
521
|
let items = []
|
|
522
522
|
try { items = readdirSync(dir, { withFileTypes: true }) } catch { return }
|
|
@@ -125,7 +125,7 @@ function isolationReport(stats) {
|
|
|
125
125
|
// user's own edit survives; its failure never costs the trace. The same string lives in
|
|
126
126
|
// `workflows/_runtime.js` (a plugin cannot share a file — V2 loads every .js here as a
|
|
127
127
|
// plugin — and the runtime is imported lazily, from a configurable dir); tests pin both.
|
|
128
|
-
const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/protected-checks.txt\n!/done-checks.txt\n"
|
|
128
|
+
const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
|
|
129
129
|
// Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
|
|
130
130
|
// never a user edit, so it is upgraded. Any other content is the user's. Never throws.
|
|
131
131
|
async function writeGitignore(file) {
|
|
@@ -198,7 +198,7 @@ async function runChildSession(client, { prompt, agent, model, title, directory
|
|
|
198
198
|
// (bricks, loops, check lists) allowed back. Anchored `/*`, because a bare `*` matches at
|
|
199
199
|
// every depth and would hide `bricks/x.md` even under `!bricks/`. Same string as
|
|
200
200
|
// GENESEED_GITIGNORE in plugins/geneseed-workflow.js; both are pinned by tests.
|
|
201
|
-
const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/protected-checks.txt\n!/done-checks.txt\n"
|
|
201
|
+
const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
|
|
202
202
|
// Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
|
|
203
203
|
// never a user edit, so it is upgraded. Any other content is the user's. Never throws.
|
|
204
204
|
async function writeGitignore(file) {
|
package/bin/geneseed-cli.mjs
CHANGED
|
@@ -143,6 +143,9 @@ const VERBS = {
|
|
|
143
143
|
// Task 5. A fourth native verb: a state machine with
|
|
144
144
|
// no recorded cell to compare against, only the absolute gates named beside it in `NATIVE`.
|
|
145
145
|
loop: () => import('../js/loop/cli.mjs').then((m) => m.cmdLoop),
|
|
146
|
+
// The factory engine, the loop engine one level up: native like `loop`, gated absolutely by
|
|
147
|
+
// tests/unit/factory_cli.test.mjs.
|
|
148
|
+
factory: () => import('../js/factory/cli.mjs').then((m) => m.cmdFactory),
|
|
146
149
|
// A fifth native verb, and a port rather than an invention: the AI Harness Scorecard
|
|
147
150
|
// (upstream Python, pinned in the module's docblock). There is no recorded cell — its absolute gate is
|
|
148
151
|
// tests/unit/scorecard.test.mjs. Lazy like every row: the 31 checks load only when asked.
|
package/bin/geneseed-hook.mjs
CHANGED
|
@@ -79,13 +79,19 @@ const VERBS = {
|
|
|
79
79
|
load: gates,
|
|
80
80
|
fn: 'cmdGitGate',
|
|
81
81
|
flags: HOSTED,
|
|
82
|
-
switches: {
|
|
82
|
+
switches: {
|
|
83
|
+
'--no-consent': 'noConsent', '--no-deletion-gate': 'noDeletionGate', '--no-external-gate': 'noExternalGate',
|
|
84
|
+
'--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
|
|
85
|
+
},
|
|
83
86
|
},
|
|
84
87
|
'rule-gate': {
|
|
85
88
|
load: gates,
|
|
86
89
|
fn: 'cmdRuleGate',
|
|
87
90
|
flags: HOSTED,
|
|
88
|
-
switches: {
|
|
91
|
+
switches: {
|
|
92
|
+
'--no-secrets-gate': 'noSecretsGate', '--no-ownership-gate': 'noOwnershipGate',
|
|
93
|
+
'--no-external-gate': 'noExternalGate', '--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore',
|
|
94
|
+
},
|
|
89
95
|
},
|
|
90
96
|
'tool-gate': {
|
|
91
97
|
load: gates,
|
|
@@ -93,7 +99,8 @@ const VERBS = {
|
|
|
93
99
|
flags: HOSTED,
|
|
94
100
|
switches: {
|
|
95
101
|
'--no-deletion-gate': 'noDeletionGate', '--no-secrets-gate': 'noSecretsGate',
|
|
96
|
-
'--no-ownership-gate': 'noOwnershipGate',
|
|
102
|
+
'--no-ownership-gate': 'noOwnershipGate', '--no-external-gate': 'noExternalGate',
|
|
103
|
+
'--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
|
|
97
104
|
},
|
|
98
105
|
},
|
|
99
106
|
learn: {
|
|
@@ -101,7 +108,10 @@ const VERBS = {
|
|
|
101
108
|
fn: 'cmdLearn',
|
|
102
109
|
// `--host` only keys the global stand-down's marker (js/hosts/hosts.mjs); learn has no dialect.
|
|
103
110
|
flags: { '--memory': 'memory', '--host': 'host' },
|
|
104
|
-
switches: {
|
|
111
|
+
switches: {
|
|
112
|
+
'--consolidate': 'consolidate', '--no-done-gate': 'noDoneGate', '--no-test-note': 'noTestNote',
|
|
113
|
+
'--no-rule-store': 'noRuleStore',
|
|
114
|
+
},
|
|
105
115
|
positional: 'file',
|
|
106
116
|
},
|
|
107
117
|
// UserPromptSubmit and SessionEnd: no verb runs there, and the activity view needs both.
|
|
@@ -115,11 +125,14 @@ const VERBS = {
|
|
|
115
125
|
*/
|
|
116
126
|
async function baselineStores(verb, args) {
|
|
117
127
|
try {
|
|
118
|
-
|
|
128
|
+
// A SubagentStart carries the PARENT's session_id: a baseline there would reset the parent's.
|
|
129
|
+
if (verb !== 'context' || !args.root || args.event === 'SubagentStart' || process.env.GENESEED_LEARN_CHILD
|
|
130
|
+
|| isatty(0)) return;
|
|
119
131
|
const raw = readStdin();
|
|
120
132
|
if (!raw.includes('session_id')) return;
|
|
121
133
|
const { writeBaseline } = await import('../js/hosts/store-watch.mjs');
|
|
122
|
-
|
|
134
|
+
const { session_id: sid, cwd } = JSON.parse(raw);
|
|
135
|
+
writeBaseline(args.root, sid, cwd);
|
|
123
136
|
} catch { /* see above */ }
|
|
124
137
|
}
|
|
125
138
|
|
|
@@ -164,14 +177,17 @@ function die(code, msg) {
|
|
|
164
177
|
*/
|
|
165
178
|
function parse(spec, argv) {
|
|
166
179
|
const args = {
|
|
167
|
-
root: null, host: null, memory: null, consolidate: false, noConsent: false,
|
|
168
|
-
noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false,
|
|
180
|
+
root: null, host: null, event: null, memory: null, consolidate: false, noConsent: false,
|
|
181
|
+
noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false,
|
|
182
|
+
noExternalGate: false, noTestNote: false, noRuleStore: false, noRootScan: false, file: null,
|
|
169
183
|
};
|
|
170
184
|
for (let i = 0; i < argv.length; i += 1) {
|
|
171
185
|
const tok = argv[i];
|
|
172
186
|
const eq = tok.indexOf('=');
|
|
173
187
|
const name = tok.startsWith('--') && eq > 0 ? tok.slice(0, eq) : tok;
|
|
174
|
-
|
|
188
|
+
// Only the bare spelling sets a switch, and only that is emitted. `--no-external-gate=false` must
|
|
189
|
+
// not disarm a gate, and an argv error here would silence the whole verb, so it just does nothing.
|
|
190
|
+
if ((spec.switches || {})[name]) { if (tok === name) args[spec.switches[name]] = true; continue; }
|
|
175
191
|
if ((spec.flags || {})[name]) {
|
|
176
192
|
const value = eq > 0 && tok.startsWith('--') ? tok.slice(eq + 1) : argv[++i];
|
|
177
193
|
if (value === undefined) return { error: `argument ${name}: expected one argument` };
|
|
@@ -248,6 +264,12 @@ async function main(argv) {
|
|
|
248
264
|
// `hooks.md`, "Stop, SubagentStop, TaskCompleted, and TeammateIdle").
|
|
249
265
|
return die(1, parsed.error);
|
|
250
266
|
}
|
|
267
|
+
// `context` answers SessionStart and SubagentStart (settings.mjs), told apart by the payload's
|
|
268
|
+
// event name. Read here, not in the verb, so an in-process caller never blocks on fd 0; the read
|
|
269
|
+
// is cached, so `trackActivity` reuses it. A terminal sends no payload.
|
|
270
|
+
if (verb === 'context' && !isatty(0)) {
|
|
271
|
+
try { parsed.args.event = JSON.parse(readStdin() || '{}').hook_event_name ?? null; } catch { /* not JSON: SessionStart */ }
|
|
272
|
+
}
|
|
251
273
|
const rc = (await spec.load())[spec.fn](parsed.args);
|
|
252
274
|
await trackActivity(verb, parsed.args);
|
|
253
275
|
await baselineStores(verb, parsed.args);
|
package/docs/PRD.md
CHANGED
|
@@ -103,7 +103,7 @@ sequenceDiagram
|
|
|
103
103
|
| NFR-001 | No runtime dependencies. | 0 installed; vendored only | `tests/unit/dependency_policy.test.mjs` | ✅ | `js/vendor/` |
|
|
104
104
|
| NFR-002 | The hook is cheap: it loads on every tool call. | ~14 ms to load | Stated in `AGENTS.md`; no automated budget found, `⚠ to confirm` | ◐ | `bin/geneseed-hook.mjs` |
|
|
105
105
|
| NFR-003 | Context hook output stays under the host's cap. | 9 000 characters | `OUTPUT_BUDGET` | ✅ | `js/hosts/hooks-context.mjs` |
|
|
106
|
-
| NFR-004 | The rules file stays within its size ceiling. |
|
|
106
|
+
| NFR-004 | The rules file stays within its size ceiling. | 40 312 lean, 66 432 full | `CARRIER_CEILING` | ✅ | `js/inspect/cost.mjs` |
|
|
107
107
|
| NFR-005 | The generator and hook path cannot spawn beyond what is declared. | No `child_process` on the generator; one spawn site on the hook path | Closure walks | ✅ | `tests/unit/hook_cli.test.mjs` |
|
|
108
108
|
| NFR-006 | The upgrade doctor gate is bounded. | 300 s | A timeout reports a gate that did not finish | ✅ | `js/maintain/update.mjs` |
|
|
109
109
|
| NFR-007 | The console serves only this machine. | Local port 4747 by default, with request guards | [Web console security](web-ui.md#security-model) | ✅ | `js/web/server.mjs` |
|
package/docs/README.md
CHANGED
|
@@ -29,6 +29,7 @@
|
|
|
29
29
|
| Set up | [Connect your wiki](guides/wiki.md) | Giving the agent your own notes, machine-wide |
|
|
30
30
|
| Set up | [MCP servers](guides/mcp.md) · [MarkItDown](guides/mcp-markitdown.md) · [GitLab](guides/mcp-gitlab.md) · [Filesystem](guides/mcp-filesystem.md) · [Reading non-markdown docs](guides/read-non-markdown.md) | Where the config lives, the three presets, and reading PDF and Office files |
|
|
31
31
|
| Loops | [Run a loop](guides/run-a-loop.md) · [Which loop template](guides/loop-which-template.md) · [While a loop runs](guides/loop-running.md) · [Finish a loop](guides/loop-finish.md) | Working a requirement as small, validated, committed iterations |
|
|
32
|
+
| Factories | [Run a factory](guides/run-a-factory.md) | Carrying one bug report or issue to an open PR with green CI |
|
|
32
33
|
| Keep it running | [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
|
|
33
34
|
| Keep it running | [Upgrade to 5.0](guides/upgrade-to-5.md) | A 4.x machine reaching 5.0: what moves, what to check, how to go back |
|
|
34
35
|
| Keep it running | [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
|
|
@@ -49,9 +50,11 @@
|
|
|
49
50
|
|
|
50
51
|
**Loops** — [Loops](concepts/loops.md) · [Templates](concepts/loop-templates.md) · [Bricks and their origins](concepts/loop-bricks.md) · [Notes and rules](concepts/loop-notes.md) · [Risk, trust and validation levels](concepts/loop-risk.md) · [Human gates](concepts/loop-gates.md) · [Contracts and ignored deletions](concepts/loop-contracts.md) · [LOOP.md, trailers and the loop branch](concepts/loop-branch.md)
|
|
51
52
|
|
|
53
|
+
**Factories** — [Factories](concepts/factories.md)
|
|
54
|
+
|
|
52
55
|
## 4 · Reference
|
|
53
56
|
|
|
54
|
-
**CLI & environment** — [CLI](reference/cli.md) · [Loop actions](reference/loop-actions.md) · [Environment variables](reference/environment.md) · [Context and memory variables](reference/env-context.md)
|
|
57
|
+
**CLI & environment** — [CLI](reference/cli.md) · [Loop actions](reference/loop-actions.md) · [Factory actions](reference/factory-actions.md) · [Environment variables](reference/environment.md) · [Context and memory variables](reference/env-context.md)
|
|
55
58
|
|
|
56
59
|
**Troubleshooting** (by symptom) — [Overview](reference/troubleshooting.md) · [Install](reference/troubleshoot-install.md) · [Hooks, context and memory](reference/troubleshoot-hooks.md) · [Model, agents and MCP](reference/troubleshoot-tools.md) · [Updating](reference/troubleshoot-update.md) · [Doctor findings](reference/troubleshoot-doctor.md) · [Web console](reference/troubleshoot-web.md)
|
|
57
60
|
|
|
@@ -23,11 +23,11 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
|
|
|
23
23
|
|---|---|---|---|---|---|
|
|
24
24
|
| `sealed-secrets` | law | ask: rule-gate (credential-shaped content outside `.env*`). Switchable per install with `--no-secrets-gate` (see [Exclusions](exclusions.md)): this scan stands down on every host, the guard plugin's path block included | same as Claude Code | block: guard plugin (key/credential file path, or vendor-prefixed secret content); warns only on `.env*` | block (exit 2) |
|
|
25
25
|
| `deletion-is-deliberate` | law | ask: git-gate, only on real data loss judged against the repository's state (the list in [Hooks](hooks.md): a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, the reflog pruned, files git cannot restore removed); asks when it cannot verify. Switchable per install with `--no-deletion-gate` (see [Exclusions](exclusions.md)): the real-loss check and the Law IV `permission.bash` keys stand down, everything else in this table stays **+** ask: git-gate, catastrophic shell (`rm -rf` of `/`, a drive root or `~`, `mkfs`, `dd` over a raw disk, `format`, fork bomb), whatever the state and even with the switch off | same as Claude Code | ask: permission prompt (`git reflog expire*`, `git gc --prune*`, a force push or delete of `main`/`master` by name) **+** block: guard plugin (catastrophic shell, the hook's check plus its own stricter text match: `rm -rf` of `/`, a drive root or `~`, fork bomb, `format`, `dd` over a raw disk) **+** block: guard plugin (every other real-loss case, the same state-aware decisions as the hook) | block (exit 2) |
|
|
26
|
-
| `persist-insight` | process | ask: rule-gate (a write to `user-rules.md
|
|
27
|
-
| `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed | log only |
|
|
26
|
+
| `persist-insight` | process | ask: rule-gate (a write to `user-rules.md` or `user-rules.draft.md`; memory is written freely, and the [change report](hooks.md#the-change-report) and the web console show it). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules`: the hook goes on every host (`--no-rule-store`), OpenCode's `permission.edit` keys on the rule files too. The change report still lists rule-file changes | same as Claude Code | ask: OpenCode's own prompt (`permission.edit`, and `evaluate` on OpenCode 2); the guard plugin refuses a file-tool write the host cannot prompt for | block a file-tool write: exit 2, no ask tier; a parsed shell write only warns |
|
|
27
|
+
| `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). A sub-agent's commit or merge (`agent_id` in the payload) in a linked worktree, on a branch that is not shared, passes: a Foreman worker's own batch ([Foreman mode](foreman-mode.md) has the exact conditions). A git hook or `core.hooksPath` that pushes on commit is not seen. A push, or a command that mixes one in, still asks. Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed. A glob sees only the command, never the worktree, so a worker's commit still asks | log only |
|
|
28
28
|
| `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list, or to a gate's own configuration: hook settings, `excludes.json`, `AGENT.md` gate markers, the hook shim) | same as Claude Code | ask: OpenCode's own `permission.edit` rules, written by the emit (every `opencode.json(c)`, the hook settings, the install's `AGENT.md`, `excludes.json`, manifest, plugins, the hook shim); block: guard plugin (the protected-checks list, and the other hosts' Geneseed-only files) | block (exit 2), writes only; a hook `settings.json` only when the edit changes Geneseed's own hook entries |
|
|
29
29
|
| `verify-before-asserting` | law | block at Stop, once per turn: the done gate in `learn` (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (**unverified live**: a frozen fork, and no check runs a model turn) | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
|
|
30
|
-
| `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
|
|
30
|
+
| `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`). Togglable: build without the ops pack, or drop this rule alone with `--exclude-rules`: the check goes on every host (`--no-root-scan`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
|
|
31
31
|
|
|
32
32
|
Bob has no "ask" tier (see [ADR 0007](../adr/0007-gates-fail-closed-per-host-ceiling.md)), so a
|
|
33
33
|
rule the other hosts only ask about either blocks outright on Bob or degrades to a log line.
|
|
@@ -35,6 +35,16 @@ Never a silent pass; Bob runs every gate above through one fused command, `tool-
|
|
|
35
35
|
on the payload shape rather than on separate matchers. OpenCode enforces through two separate
|
|
36
36
|
mechanisms: its own permission prompt (`opencode.json`, static globs) and the guard plugin
|
|
37
37
|
(`tool.execute.before`, pattern matching); a rule can use either or both.
|
|
38
|
+
|
|
39
|
+
`persist-insight` and `external-gate` also read a shell command's parsed forms on every host: a
|
|
40
|
+
redirect, `tee`, `sed -i`, `cp`, `mv`, `rm`, and the PowerShell writers `Add-Content`, `Set-Content`,
|
|
41
|
+
`Out-File`, `Clear-Content`, `Remove-Item`, `Copy-Item`, `Move-Item`, `New-Item`, `Rename-Item` with
|
|
42
|
+
the aliases `ac`, `sc`, `del`, `copy`, `move`, `ni` and `ren`. A parsed write to a store asks on
|
|
43
|
+
Claude Code, OpenClaude and OpenCode 2, is refused on OpenCode 1, and only warns on Bob. **Shell is
|
|
44
|
+
not a boundary:** `bash -c`, `pwsh -c`, an interpreter and a variable stay unread, so the host's own
|
|
45
|
+
command permission is the backstop, and the [change report](hooks.md#the-change-report) tells you
|
|
46
|
+
afterwards.
|
|
47
|
+
|
|
38
48
|
See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) for why a gate that only
|
|
39
49
|
one host can run still ships for every host it can.
|
|
40
50
|
|
|
@@ -47,6 +57,15 @@ and the next write passes. Off per repo with `mode: off`, for one developer with
|
|
|
47
57
|
`Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`, per install with
|
|
48
58
|
`--no-ownership-gate` ([Exclusions](exclusions.md)).
|
|
49
59
|
|
|
60
|
+
### Switches on two rows above
|
|
61
|
+
|
|
62
|
+
`--no-external-gate` stops every ask and refusal in the `external-gate` row, on every host, except
|
|
63
|
+
OpenCode's own `permission.edit` keys, which are host configuration and keep asking. It does not
|
|
64
|
+
touch the rule's text: `--exclude-rules rigor.5` does that, and leaves the hook asking.
|
|
65
|
+
`--no-test-note` stops the advisory weakened-test note that *Cure the Cause* carries at edit time
|
|
66
|
+
and at turn end, on every host. That note asks nothing and blocks nothing, so the rule stays
|
|
67
|
+
outside the hook-pinned ids. See [Exclusions](exclusions.md).
|
|
68
|
+
|
|
50
69
|
| Gate | Claude Code | OpenClaude | OpenCode | Bob |
|
|
51
70
|
|---|---|---|---|---|
|
|
52
71
|
| ownership | deny once: rule-gate (`Write`/`Edit`/`NotebookEdit`; sub-agents defer) | same as Claude Code | block once: guard plugin (a child session defers) | block once (exit 2): tool-gate (sub-agent deferral unverified) |
|
|
@@ -78,7 +97,7 @@ follow them, not because a tool call was ever inspected.
|
|
|
78
97
|
`prove-the-gate`.
|
|
79
98
|
|
|
80
99
|
**Doctrine: comms** — `codes-that-persist` · `structure-beside-prose` · `declare-the-judgment-calls` ·
|
|
81
|
-
`simplified-technical-english
|
|
100
|
+
`simplified-technical-english`.
|
|
82
101
|
|
|
83
102
|
---
|
|
84
103
|
|
|
@@ -56,7 +56,17 @@ The finer switch removes a single doctrine rule from an install while keeping th
|
|
|
56
56
|
geneseed build --emit claude-global --exclude-rules "process 7"
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it.
|
|
59
|
+
The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. If a later version retires the rule (comms 5 merged into comms 1 on 2026-11-08), the rebuild prints a WARN, drops that address, and goes on. The always-on Rules and the Ethos cannot be excluded.
|
|
60
|
+
|
|
61
|
+
**A hook goes with its rule.** Three doctrine rules are also enforced by a hook with no switch of its own, and excluding the rule, or building without its pack, drops that hook in the same rebuild. Including the rule again re-arms it at the next rebuild.
|
|
62
|
+
|
|
63
|
+
| Rule | What stops | Flag |
|
|
64
|
+
| --- | --- | --- |
|
|
65
|
+
| process 5, *Consent Before Push* | the commit/push ask of `git-gate` and OpenCode's `git commit*`/`git push*` keys. Bob keeps its warning line | `--no-consent` |
|
|
66
|
+
| process 1, *Persist Insight* | the ask (on Bob the block or warning) on a write to `user-rules.md` or `user-rules.draft.md`, by write tool or parsed shell write, the hard-link check included: `rule-gate`, `git-gate`, Bob's `tool-gate`, the OpenCode guard, and OpenCode's `permission.edit` keys on those files | `--no-rule-store` |
|
|
67
|
+
| ops 2, *Commands Must Return* | the root-scan check of `git-gate`, Bob's `tool-gate` and the OpenCode guard | `--no-root-scan` |
|
|
68
|
+
|
|
69
|
+
Every other check of those hooks stays. The [change report](hooks.md#the-change-report) keeps reporting rule-file changes: with process 1 off, a rule write ran with no prompt, so it is never counted as approved. **With process 1 off, that report is the only signal that the agent changed your standing rules.** It detects and prevents nothing, and it can be fooled: the agent can write `memory/.own-writes.json`, the log of Geneseed's own writes, so a change it lists is excused. The OpenCode guard reads the same state from the install's `Active packs:` and `Excluded rules:` lines when it starts, so restart OpenCode after a rebuild. While the machine's hook shim points at an older checkout, that checkout refuses a flag it does not know and the gate verb lets every call through; run `geneseed rebuild-all` first. Rigor 5 is the exception: it has a switch of its own (below). Picking packs and rules is covered in [Doctrine packs and single rules](../guides/setup-doctrines.md); what the layers are is in [Rules](rules.md).
|
|
60
70
|
|
|
61
71
|
### Per-skill exclusion — skills you never use
|
|
62
72
|
|
|
@@ -97,7 +107,7 @@ geneseed build --emit claude-global --no-secrets-gate # Sealed Secrets
|
|
|
97
107
|
geneseed build --emit claude-global --no-done-gate # Verify Before Asserting
|
|
98
108
|
```
|
|
99
109
|
|
|
100
|
-
The console's Constitution page has a switch on Rule I's and Rule III's rows too (*Enforced by* reads **Gate off** while one is off); the other Rules show *no gate*, because only their text enforces them. The install records `Secrets gate: off` / `Done gate: off` beside `Deletion gate:`, written only when off; rebuilds, upgrades and `geneseed status` carry them like Law IV's.
|
|
110
|
+
The console's Constitution page has a switch on Rule I's and Rule III's rows too (*Enforced by* reads **Gate off** while one is off); Rule VIII has one for the [test note](#external-gate-and-the-test-note--on-or-off), and the other Rules show *no gate*, because only their text enforces them. The install records `Secrets gate: off` / `Done gate: off` beside `Deletion gate:`, written only when off; rebuilds, upgrades and `geneseed status` carry them like Law IV's.
|
|
101
111
|
|
|
102
112
|
What stops, per host:
|
|
103
113
|
- **`--no-secrets-gate`**: the credential scan of `rule-gate` (Claude Code, OpenClaude) and of `tool-gate` (Bob, which then no longer exits 2 for it), and on OpenCode the guard plugin's *Sealed Secrets* block — both the key/credential file path block and the content scan. *External Gate*, *Persist Insight*, the deletion gate and the root-scan check stay.
|
|
@@ -105,6 +115,42 @@ What stops, per host:
|
|
|
105
115
|
|
|
106
116
|
Limits: OpenCode reads both switches from the install's `AGENT.md` when it starts, so restart it after flipping one. A global install beside a project install: `rule-gate` and Bob's `tool-gate` do not stand down for a project install on any host, and neither does the OpenCode guard, so an armed global install still asks about (or blocks) a credential write inside a project whose own install has the secrets gate off. `learn` does stand down on Claude Code and OpenClaude, so there the project's done gate switch decides. And the older-shim limit above is sharper for the done gate: its flag rides on `learn`, so while the shim points at an older checkout an install with the done gate off **loses learning too**, not only the gate. Run `geneseed rebuild-all` before switching either gate off.
|
|
107
117
|
|
|
118
|
+
### External Gate and the test note — on or off
|
|
119
|
+
|
|
120
|
+
Two more switches. Both are armed by default and written only when off, so an armed install does not change.
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
geneseed build --emit claude-global --no-external-gate # protected checks, gate configuration
|
|
124
|
+
geneseed build --emit claude-global --no-test-note # the weakened-test note
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
The install records `External gate: off` / `Test note: off` beside the other gate markers. Rebuilds, upgrades and `geneseed status` carry them. Any other value reads as armed. `doctor --probe` is unaffected: it sends a shell command that neither switch judges.
|
|
128
|
+
|
|
129
|
+
**Run `geneseed rebuild-all` before you switch either one off.** The flags are new. While the machine's shared hook shim points at an older checkout, that checkout refuses the flag, and the gate verb then lets every call through: every gate on that verb is silent, not only this one.
|
|
130
|
+
|
|
131
|
+
What stops, per host:
|
|
132
|
+
- **`--no-external-gate`**: the protected-check and gate-configuration asks of `rule-gate` and of the shell path in `git-gate` (Claude Code, OpenClaude), the same blocks in `tool-gate` (Bob, which then no longer exits 2 for them), the OpenCode guard's refusals on its write and shell paths, and the `evaluate` ask over a gate's own file on OpenCode 2. Every other gate keeps running: secrets, real loss, root scans, the rule-store check, the wiki check and commit/push consent. The guard also keeps refusing an NTFS stream path, because that check protects every path gate.
|
|
133
|
+
- **`--no-test-note`**: the "this edit weakens a test" note at edit time (`rule-gate`, Bob's `tool-gate`), the `[done-gate] advisory` line at turn end (`learn`), and the OpenCode context plugin's reminder on both OpenCode versions. The done checks do not change. `--no-done-gate` still silences the turn-end line and the OpenCode reminder by itself, and it leaves the edit-time note on the hook hosts.
|
|
134
|
+
|
|
135
|
+
**What stays on OpenCode.** The `permission.edit` "ask" keys in `opencode.json` are host configuration, so `--no-external-gate` does not remove them. OpenCode keeps asking before an edit tool writes those files, and you remove the keys by hand if you want that gone. The guard no longer refuses them after an "always" answer, and no longer refuses a shell write to them.
|
|
136
|
+
|
|
137
|
+
**What this switch costs.** External Gate is what stops an agent from editing the gates' own wiring. With it off, the agent can write hook settings, the `AGENT.md` gate markers and `.geneseed/done-checks.txt` without an ask, so every other gate holds only while the agent leaves that wiring alone. Switch it off only where you accept that.
|
|
138
|
+
|
|
139
|
+
**The doctrine and the switch are two axes.** `--exclude-rules rigor.5` takes the rule's text out of the carrier. `--no-external-gate` stops the hook. Neither moves the other:
|
|
140
|
+
|
|
141
|
+
| Rule text (`--exclude-rules`) | Hook (`--no-external-gate`) | Result |
|
|
142
|
+
| --- | --- | --- |
|
|
143
|
+
| In | Armed | The agent is told, and the write asks |
|
|
144
|
+
| Excluded | Armed | The agent is not told, and the write still asks |
|
|
145
|
+
| In | Off | The agent is told, and nothing asks |
|
|
146
|
+
| Excluded | Off | Neither |
|
|
147
|
+
|
|
148
|
+
The console's Constitution page shows both on the same doctrine row: the row's own switch is the rule, and the *External gate* line inside the opened row is the hook. The test note's switch sits on Rule VIII's row, which reads *Hook gate* or **Gate off**. Each gate switch rebuilds at once; the rule switch stages with the other doctrine changes.
|
|
149
|
+
|
|
150
|
+
**Where a marker counts.** In a `CLAUDE.md` or `AGENTS.md`, which are your files, every gate marker counts only inside the `<!-- BEGIN GENESEED -->` block. A marker line outside it reads as armed, and a rebuild does not carry it. A generated `AGENT.md` or `rules/geneseed.md` counts whole, and External Gate protects both. Under External Gate, a write tool aimed at a `CLAUDE.md` or `AGENTS.md` is replayed, and the first block is compared before and after. Any difference asks (on Bob it blocks, and the OpenCode guard refuses). So does a call that cannot be replayed, an unreadable file, or a file over 1 MB. An edit wholly outside the block stays silent, so your own notes there are not interrupted. The name is normalized first, so `CLAUDE.md::$DATA` and `CLAUDE.md.` count as `CLAUDE.md`. A shell edit inside the block does not ask, and neither does a shell edit that puts a fake block before the real one, because only the first block is read. That is a limit: the hook has no replay for a shell write.
|
|
151
|
+
|
|
152
|
+
Limits, as for the gates above: OpenCode reads both markers from `AGENT.md` when it starts, so restart it after a rebuild. `rule-gate` and Bob's `tool-gate` do not stand down for a project install on any host, so an armed global install still asks inside a project built with the switch off. Only `git-gate` stands down, on Claude Code and OpenClaude.
|
|
153
|
+
|
|
108
154
|
### Ownership gate — on or off
|
|
109
155
|
|
|
110
156
|
The [ownership](ownership.md) first-write gate is not a Rule's gate: it stops the first file write of a session, once, in an application repo whose root `AGENTS.md` has no `## Ownership` section, so the agent proposes the setup first. It is armed by default. Switch it off for one install:
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
---
|
|
2
|
+
group: concepts
|
|
3
|
+
kind: "concept"
|
|
4
|
+
section: "Factories"
|
|
5
|
+
order: 24.5
|
|
6
|
+
title: "Factories"
|
|
7
|
+
link: {"hash":"#/docs/factory-actions","label":"The geneseed factory actions →"}
|
|
8
|
+
description: "What a factory is: one work item carried through bricks and whole loops to an open PR, with routes back when CI fails."
|
|
9
|
+
---
|
|
10
|
+
To run one, see [Run a factory](../guides/run-a-factory.md).
|
|
11
|
+
|
|
12
|
+
A **factory** carries one work item (a request, a document or analysis, or a GitHub or GitLab
|
|
13
|
+
issue) through a graph of **stages** to an open pull request with green CI. A stage is a
|
|
14
|
+
[brick](loop-bricks.md) or a whole [loop](loops.md). `geneseed factory` is the state machine: it
|
|
15
|
+
decides every transition, cycle count and stop, and the `factory` [skill](skills.md) runs the stage
|
|
16
|
+
it is handed. **A run never merges.** It ends at "PR open, CI green", and the merge is yours.
|
|
17
|
+
|
|
18
|
+
> **You already know this:** a ticket moving across a board — triaged, worked, reviewed, shipped
|
|
19
|
+
> for review. A failed check sends the card back a column, but only so many times before someone
|
|
20
|
+
> has to look at it.
|
|
21
|
+
|
|
22
|
+
## Stages, and the routes back
|
|
23
|
+
|
|
24
|
+
A factory is the loop graph one level up. Each stage reports an outcome, and each outcome has
|
|
25
|
+
one edge: to the next stage, to `$close`, or to `$stop`. A `loop:<name>` stage runs a whole loop
|
|
26
|
+
in the same worktree and reports `pass` when that loop closed, `fail` when it stopped.
|
|
27
|
+
|
|
28
|
+
A failure may route back to an earlier stage: red CI at `merge-gate` sends the work back to the
|
|
29
|
+
loop that wrote it. Every such route sits inside a declared **cycle** with a `max` (5 at most).
|
|
30
|
+
Each lap back to the cycle's first stage spends one; past the `max`, the run stops. A route back
|
|
31
|
+
always starts a **fresh** loop: a new `LOOP.md`, whose first note is the reason the last lap
|
|
32
|
+
failed. When two cycles share that first stage, the lap spends the smallest one that holds the
|
|
33
|
+
stage it came from: a failed `holdout` spends `holdout`, a red `merge-gate` spends `ci`. The commits made before stay on the branch. A run also stops after 30 stage transitions,
|
|
34
|
+
whatever its cycles say.
|
|
35
|
+
|
|
36
|
+
`geneseed factory check` refuses a factory before any stage runs: an unknown brick or loop, an
|
|
37
|
+
outcome with no edge, a `$close` nothing reaches, a cycle with no `max`, a cycle entered anywhere
|
|
38
|
+
but its first stage, or a route back that spends no cycle.
|
|
39
|
+
|
|
40
|
+
## Forks and lanes
|
|
41
|
+
|
|
42
|
+
A **fork** is where the work takes one way or another. It is a brick that declares **named
|
|
43
|
+
outcomes**, any outcome other than `pass`, `fail`, `error` or `none`. `triage` is one: `bug`,
|
|
44
|
+
`feature`, `deps`, `refactor`, `docs` and `fail`. Each named outcome has its own edge to its own
|
|
45
|
+
stage, its **lane**, and the outcome the brick reports picks the lane. `geneseed factory next`
|
|
46
|
+
hands the fork its `lanes`: each outcome with the stage it leads to.
|
|
47
|
+
|
|
48
|
+
Not every factory runs a loop, and not every lane is one. A loop is the lane for work that
|
|
49
|
+
changes code, because the loop carries the test → fix → verify proof. A brick is the lane where a
|
|
50
|
+
loop adds nothing: in `issue-to-pr`, `docs` goes to the `docs-update` brick, which commits its own
|
|
51
|
+
change. Every lane joins the same path after it: `holdout`, then `pr-open` and `merge-gate`.
|
|
52
|
+
|
|
53
|
+
A route back after a fork targets **`$lane`**: the stage the run's most recent fork chose. The
|
|
54
|
+
engine records it in `FACTORY.md` when the fork's outcome is recorded, and an edge to `$lane` goes
|
|
55
|
+
there. A cycle may start at `$lane` too, and each route back to it spends one lap, as any route
|
|
56
|
+
back does. `check` refuses `$lane` in a factory with no fork, or where some path reaches it before
|
|
57
|
+
any fork. In its other checks, `$lane` stands for every lane, so a graph that passes holds for the
|
|
58
|
+
lane any run takes.
|
|
59
|
+
|
|
60
|
+
A factory written before forks used a `loop:$triaged` stage and a `loops` list. Both are retired:
|
|
61
|
+
`check` names each with its replacement, and the doctor reports it. Nothing rewrites your file.
|
|
62
|
+
|
|
63
|
+
## One worktree, two state files
|
|
64
|
+
|
|
65
|
+
A run works on its own branch, `loop/factory-<slug>`, in its own worktree. `FACTORY.md` at the
|
|
66
|
+
root holds the run's state; while a loop stage runs, its `LOOP.md` sits beside it. The loop
|
|
67
|
+
engine treats `FACTORY.md` as bookkeeping, as it treats `LOOP.md`: it never scores it. A stage
|
|
68
|
+
that is not a loop records only on a clean worktree, and `factory record` refuses a dirty tree
|
|
69
|
+
after one. A brick that changes files, such as a `docs-update` lane, commits them first. The one
|
|
70
|
+
exception is the run's spec, `specs/<slug>/spec.md`: the `spec` stage writes it, and
|
|
71
|
+
it is committed once you approve it, before the first loop. Each run is listed in `factories.json` beside the loop registry, and each child loop's row
|
|
72
|
+
names the run it belongs to.
|
|
73
|
+
|
|
74
|
+
## The shipped factories
|
|
75
|
+
|
|
76
|
+
| Factory | Stages |
|
|
77
|
+
| --- | --- |
|
|
78
|
+
| `analysis-to-build` | `intake` → `spec` → `holdout-write` → `loop:feature` → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. `spec` writes `specs/<slug>/spec.md` with an ordered task list, and you approve it at its gate. `loop:feature` then runs once per task, in order, in the same worktree, and one PR opens at the end. A failed `holdout` or a red `merge-gate` sends the work back to `loop:feature` as one extra task, twice at most each (cycles `holdout` and `ci`) |
|
|
79
|
+
| `bug-report-to-fix` | `intake` → `holdout-write` → `loop:bugfix` → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. A failed `holdout` or a red `merge-gate` sends the fix back to `loop:bugfix`, twice at most each (cycles `holdout` and `ci`) |
|
|
80
|
+
| `issue-to-pr` | `intake` → `holdout-write` → `triage`, a fork → one lane → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. `triage` reports the lane: `bug` → `loop:bugfix`, `feature` → `loop:feature`, `deps` → `loop:deps-upgrade`, `refactor` → `loop:refactor`, `docs` → the `docs-update` brick. A failed `holdout` or a red `merge-gate` sends the work back to `$lane`, that same lane, twice at most each (cycles `holdout` and `ci`) |
|
|
81
|
+
|
|
82
|
+
The bricks they add:
|
|
83
|
+
|
|
84
|
+
| Brick | Does | Outcomes |
|
|
85
|
+
| --- | --- | --- |
|
|
86
|
+
| `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria | `pass`, `fail` |
|
|
87
|
+
| `holdout-write` | Writes 3 to 8 prose scenarios (given / when / then) for the work item into the holdout folder, outside the worktree, and hands the work item on unchanged | `pass`, `fail` |
|
|
88
|
+
| `holdout` | Plays every scenario against the built change. `fail` carries one sentence per failed scenario, observed against expected; `error` when the diff touches the holdout folder or a scenario cannot be played | `pass`, `fail`, `error` |
|
|
89
|
+
| `triage` | A fork: reads the work item and reports the outcome that names its lane, with its reason. `fail` when no lane fits | `bug`, `feature`, `deps`, `refactor`, `docs`, `fail` |
|
|
90
|
+
| `pr-open` | Pushes the branch (the push asks you) and opens the PR, or updates the one already open | `pass`, `fail` |
|
|
91
|
+
| `merge-gate` | Waits for the PR's CI with a watch that returns by itself (each call under 10 minutes), 30 minutes at most. A repo with no CI reports `none`, and you decide | `pass`, `fail`, `none` |
|
|
92
|
+
| `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, and keeps only a lasting lesson in memory | `pass` |
|
|
93
|
+
|
|
94
|
+
`analysis-to-build` also uses the loops' own `spec` brick (`gate: human`), the one the
|
|
95
|
+
`spec-first-feature` loop starts with, and `issue-to-pr` the loops' `docs-update` brick as its
|
|
96
|
+
docs lane.
|
|
97
|
+
|
|
98
|
+
The run report is git-ignored by the `.geneseed/.gitignore` Geneseed seeds. Where no such file is
|
|
99
|
+
in the worktree, `retro` writes the report to the OS temp directory instead, so the tree stays
|
|
100
|
+
clean. The report lives in the worktree and goes when you remove it.
|
|
101
|
+
|
|
102
|
+
## Holdout scenarios
|
|
103
|
+
|
|
104
|
+
A loop's tests are written by the same agent that writes the code, so they can share its
|
|
105
|
+
blind spots. A factory therefore keeps a second set of checks the developer never sees. After
|
|
106
|
+
`intake` (or `spec`), the `holdout-write` stage writes 3 to 8 scenarios in plain prose, each a
|
|
107
|
+
`Given` / `When` / `Then`, to `~/.config/geneseed/holdout/<slug>/` (under `$XDG_CONFIG_HOME` when
|
|
108
|
+
it is set): outside the worktree, so no commit, diff or loop note carries them. After the loop,
|
|
109
|
+
the `holdout` stage plays each scenario against the change as built and reports.
|
|
110
|
+
|
|
111
|
+
- **On a failure**, the work goes back to the loop with one sentence per failed scenario: what was
|
|
112
|
+
observed against what was expected. Never the scenario's text. That lap spends the `holdout`
|
|
113
|
+
cycle, twice at most.
|
|
114
|
+
- **On `error`**, the run stops: the diff touches the holdout folder, or a scenario cannot be
|
|
115
|
+
played.
|
|
116
|
+
- **One folder per slug.** `holdout-write` reports `fail` when the folder already holds files from
|
|
117
|
+
an earlier run with the same slug; clear it yourself, then run again.
|
|
118
|
+
- **Who sees them.** Both stages run as the `tester` agent. The `factory` skill never puts holdout
|
|
119
|
+
content or the folder's path into a brief, a note or a carry.
|
|
120
|
+
- **No hook refuses a read of it**, on any host. A Claude Code read gate was built but is not
|
|
121
|
+
shipped: it would run a hook process on every Read, Grep and Glob of every session (about 90 ms
|
|
122
|
+
each on Windows) for a protection only a factory run uses. The folder is protected only by its place
|
|
123
|
+
outside the worktree, by `holdout`'s `error`, and by the skill's rule. A shell command such as
|
|
124
|
+
`cat` is not covered on any host.
|
|
125
|
+
|
|
126
|
+
## In the console
|
|
127
|
+
|
|
128
|
+
The console's **Factories** page (in the Build group, after Loops) draws each factory as a
|
|
129
|
+
graph: its stages left to right, a `loop:` stage as a block that holds its loop's ring, each
|
|
130
|
+
route back as an arc above the row with its cycle and `max`, and `close` and `stop` as end caps.
|
|
131
|
+
Its **Active** tab lists every registered run, with the current stage lit, the laps spent on
|
|
132
|
+
each cycle and the child loop's current step. The page changes nothing in a run (its poll only drops finished runs older than 7 days from `factories.json`, as Loops does); you answer a run in the
|
|
133
|
+
agent's session.
|
|
134
|
+
|
|
135
|
+
## Your own factories
|
|
136
|
+
|
|
137
|
+
Factories load from three levels, as bricks and loop templates do, and a later level overrides
|
|
138
|
+
an earlier one by name: shipped, global (`~/.config/geneseed/factories/`), and project
|
|
139
|
+
(`<repo>/.geneseed/factories/`).
|
|
140
|
+
|
|
141
|
+
To compose or change one, use the `factory-forge` skill — ask it. It interviews you for the
|
|
142
|
+
stages, the routes back and their `max`, writes the file at project or global level and runs
|
|
143
|
+
`geneseed factory check` until it passes. When a stage needs a brick that does not exist, it
|
|
144
|
+
offers the `brick-forge` skill: that skill alone writes bricks.
|
|
145
|
+
|
|
146
|
+
## Read on
|
|
147
|
+
|
|
148
|
+
- [Run a factory](../guides/run-a-factory.md): how to start one, and what it asks you.
|
|
149
|
+
- [Loops](loops.md): what runs inside a `loop:` stage.
|
|
150
|
+
- [Human gates](loop-gates.md): the stages that wait for a person.
|
|
151
|
+
- [Factory actions](../reference/factory-actions.md): the `geneseed factory` commands.
|
|
@@ -30,10 +30,25 @@ When the session is unsure, it delegates. The test is still a count, because "su
|
|
|
30
30
|
|
|
31
31
|
A task worker is one `developer` agent in its own git worktree. It explores, implements and tests in a single context, loading skills as it needs them, so nothing it read is lost in a hand-off. After two repair rounds on its own failing tests it returns with its findings instead of looping.
|
|
32
32
|
|
|
33
|
+
A worker can lead a small team inside its own worktree. It can start read-only helpers (`explorer`, `researcher`) at any time. It can also start writing **sub-workers**, each in its own worktree branched from the worker's branch. The worker commits and merges their branches into its own branch, locally, and re-runs the proof after each merge. *Consent Before Push* names this as a batch. The git gate lets a commit or merge through without a prompt only when all of these hold: the host marks the call as a sub-agent's (Claude Code's `agent_id`), the directory is a linked worktree, and its branch is not shared (`main`, `master`, `develop`, `development`, `release/*`, `hotfix/*`, a remote's default, or the branch the main checkout has, in any letter case). The command may hold only adds, read-only git commands and plain commit or merge arguments with one quoted message, after at most one `cd`; anything that can run a second command (`(`, `@`, `$`, `{`, a backtick) asks. A session that only runs in a worktree, as the desktop app's do, still asks. A push still asks everywhere. Bob sends no sub-agent field, so Bob still logs its warning. On OpenCode the static `git commit*` permission still asks, because a permission glob sees only the command, not the worktree. The gate reads the command, not git's own hooks: a `post-commit` hook or a `core.hooksPath` can push on commit, on any branch, as it always could. Nesting stops at two levels below the session: session → worker → sub-worker. A sub-worker starts nothing. A lead holds every member's result before it ends. The blind reviewer is still the session's, never the worker's.
|
|
34
|
+
|
|
35
|
+
| Host | What caps the depth |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| Claude Code | the install writes `env.CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH = "2"` into its settings file, only when the key is absent (Claude Code allows three levels by default) |
|
|
38
|
+
| OpenCode | the install writes a top-level `"subagent_depth": 2` into `opencode.json`, only when the key is absent |
|
|
39
|
+
| OpenClaude | nothing in the host: its source has no such cap (checked on 0.31). The rule text is the only bound |
|
|
40
|
+
| Bob | nothing documented. The rule text is the only bound |
|
|
41
|
+
|
|
42
|
+
A value you set yourself is kept. The value 2 is read as session → worker → sub-worker; that reading is the design's, not yet observed live on either host.
|
|
43
|
+
|
|
33
44
|
When a worker returns green with a diff that touches two or more files or changes logic, the session sends a `reviewer` only your request and the diff — never the worker's reasoning — for a blind check. A failing verdict goes back to the same worker.
|
|
34
45
|
|
|
35
46
|
The session keeps a ledger in its notebook (`notebook/foreman-ledger.md`), one line per task: the task, the agent id, the worktree and the state. A correction, a follow-up or a reviewer finding goes back to **the same worker**, which resumes with everything it already knows. A new worker starts only when the old one cannot be resumed, and it receives a note of the ask, the diff so far and what was tried. A worker serves one task and retires once that task is merged or dropped.
|
|
36
47
|
|
|
48
|
+
### Status lines
|
|
49
|
+
|
|
50
|
+
A worker reports one line at start and on each change: `T<n> · <task> · files: <write set> · <state>`. On Claude Code it sends that line to the session with `SendMessage`; OpenClaude can do the same only in its agent-teams mode. OpenCode and Bob have no channel back to the session, so there the worker writes the line to its own file, `notebook/foreman/<task>.status`, which no other agent writes. The session reads all status files with one command, and only at two moments: before it starts a worker near the same files, and when a worker returns. When two write sets overlap, the session decides: one worker waits, or one worker owns the file. It records that decision in the ledger.
|
|
51
|
+
|
|
37
52
|
> **Why not a crew by default?** Splitting a task by role — one agent reads, the next builds, the next tests — passes each result on as a summary, and the next agent reads the code again. Anthropic's guide [When to fold subagents into your main agent loop](https://claude.com/resources/articles/building-agents-when-to-fold-subagents-into-your-main-agent-loop) found one loop with skills usually beats that, and keeps separate agents for verification, parallel work and context that would overflow. The blind reviewer is that kind of split.
|
|
38
53
|
|
|
39
54
|
### What a pipeline is
|
|
@@ -53,15 +68,15 @@ The crew works in its own git worktree and branch. When worktrees are unavailabl
|
|
|
53
68
|
|
|
54
69
|
Inside the crew, the developer implements and the tester runs the tests and lint. Failures go back to the developer for at most two repair rounds, then to one fresh developer carrying the tester's findings; if that fails too, the crew stops and reports the failure, leaving the branch for you to inspect.
|
|
55
70
|
|
|
56
|
-
###
|
|
71
|
+
### Nothing lands beyond the worker's branch
|
|
57
72
|
|
|
58
|
-
When a
|
|
73
|
+
When a crew is done, it hands back its worktree **uncommitted**. A worker hands back its branch: the local commits from its own sub-workers' merges, and any uncommitted work. Each comes with the raw test and lint output and the list of files it changed. Then the session:
|
|
59
74
|
|
|
60
75
|
1. re-runs the tests and lint itself — its log is its own account, not proof;
|
|
61
|
-
2. shows you the diff and the green output;
|
|
76
|
+
2. shows you the diff from the base it recorded, and the green output;
|
|
62
77
|
3. commits and merges **only once you accept**.
|
|
63
78
|
|
|
64
|
-
|
|
79
|
+
Push, and every merge beyond a worker's own branch, belong to the session alone, under *Consent Before Push* ([Rules](rules.md)). A worker or crew that cannot get to green reports back instead of landing broken work.
|
|
65
80
|
|
|
66
81
|
You can also start a pipeline without foreman mode: ask the agent to "run a pipeline" for a task, and the `pipeline` [skill](skills.md) takes it from there.
|
|
67
82
|
|
|
@@ -37,7 +37,7 @@ The merge is surgical. Every other key and every hook of your own survive, and t
|
|
|
37
37
|
**Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher or `SubagentStop`. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet. So Bob gets four hooks:
|
|
38
38
|
|
|
39
39
|
- `SessionStart` → `geneseed-hook context`.
|
|
40
|
-
- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and rule
|
|
40
|
+
- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push check and a shell write to a rule store become a warning line, because a hard block would leave Bob unable to commit at all. The [ownership](ownership.md) gate also exits 2, but only once per session and repo: the same write passes after the developer answers.
|
|
41
41
|
- `Stop` → `geneseed-hook learn`.
|
|
42
42
|
- `UserPromptSubmit` → `geneseed-hook activity`, which records the turn for the Activity view.
|
|
43
43
|
|