geneseed 5.2.0 → 5.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +54 -0
- package/README.md +4 -4
- package/SHIPPED.md +1 -1
- package/adapters/bob/README.md +31 -18
- package/adapters/claude-code/README.md +27 -22
- package/adapters/openclaude/README.md +18 -8
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +8 -3
- package/adapters/opencode/plugins/geneseed-activity.js +20 -21
- package/adapters/opencode/plugins/geneseed-context.js +224 -71
- package/adapters/opencode/plugins/geneseed-guard.js +420 -203
- package/adapters/opencode/plugins/geneseed-workflow.js +3 -2
- package/adapters/opencode/workflows/_runtime.js +3 -2
- package/bin/geneseed-cli.mjs +61 -16
- package/bin/geneseed-hook.mjs +94 -12
- package/docs/concepts/enforcement-table.md +1 -1
- package/docs/concepts/exclusions.md +2 -2
- package/docs/concepts/factories.md +40 -6
- package/docs/concepts/footprint.md +11 -1
- package/docs/concepts/foreman-mode.md +2 -2
- package/docs/concepts/hook-gates.md +3 -3
- package/docs/concepts/host-matrix.md +22 -4
- package/docs/concepts/loop-gates.md +1 -1
- package/docs/concepts/loops.md +2 -2
- package/docs/concepts/shared-tier.md +1 -1
- package/docs/design-history.md +148 -0
- package/docs/extending.md +97 -163
- package/docs/guides/install-bob.md +2 -2
- package/docs/guides/install-openclaude.md +1 -1
- package/docs/guides/run-a-factory.md +15 -2
- package/docs/guides/upgrade.md +2 -2
- package/docs/guides/verify.md +12 -0
- package/docs/reference/environment.md +1 -0
- package/docs/reference/factory-actions.md +6 -5
- package/docs/reference/troubleshoot-doctor.md +1 -1
- package/docs/reference/troubleshoot-update.md +1 -1
- package/docs/token-footprint.md +66 -2
- package/docs/understand/design-choices-hosts.md +1 -1
- package/docs/understand/design-choices-shape.md +1 -0
- package/docs/understand/enforced-vs-asked.md +1 -1
- package/docs/understand/machine-bob.md +1 -1
- package/docs/web-ui.md +21 -3
- package/harness.config.json +1 -1
- package/js/README.md +7 -5
- package/js/build/args.mjs +4 -4
- package/js/build/driver.mjs +1 -1
- package/js/build/emit-claude.mjs +1 -1
- package/js/build/generate.mjs +5 -14
- package/js/build/render.mjs +44 -24
- package/js/cli-table.json +135 -59
- package/js/factory/cli.mjs +24 -5
- package/js/factory/graph.mjs +13 -9
- package/js/factory/metrics.mjs +93 -0
- package/js/factory/registry.mjs +37 -12
- package/js/factory/state.mjs +25 -6
- package/js/hosts/done-checks.mjs +6 -0
- package/js/hosts/geneseed-dir.mjs +3 -2
- package/js/hosts/gitref.mjs +5 -3
- package/js/hosts/hook-tap.mjs +104 -0
- package/js/hosts/hooks-context.mjs +30 -3
- package/js/hosts/hooks-learn.mjs +47 -16
- package/js/hosts/hooks-prims.mjs +52 -3
- package/js/hosts/hooks.mjs +69 -42
- package/js/hosts/hosts.mjs +80 -12
- package/js/hosts/installs.mjs +7 -0
- package/js/hosts/loss.mjs +6 -1
- package/js/hosts/native.mjs +14 -5
- package/js/hosts/owned.mjs +7 -6
- package/js/hosts/ownership-gate.mjs +14 -1
- package/js/hosts/settings.mjs +245 -103
- package/js/hosts/shim.mjs +4 -4
- package/js/hosts/usage.mjs +9 -3
- package/js/inspect/checks-probe.mjs +66 -5
- package/js/inspect/checks-repo.mjs +196 -2
- package/js/inspect/cost.mjs +34 -2
- package/js/inspect/diff.mjs +16 -1
- package/js/inspect/doctor.mjs +13 -4
- package/js/inspect/excludes.mjs +18 -6
- package/js/inspect/status.mjs +35 -7
- package/js/inspect/validate.mjs +44 -21
- package/js/lib/machine-dir.mjs +1 -1
- package/js/lib/node-floor.mjs +46 -6
- package/js/maintain/uninstall.mjs +70 -17
- package/js/maintain/update.mjs +31 -7
- package/js/ui/cli.mjs +34 -4
- package/js/ui/menu.mjs +1 -1
- package/js/ui/tui.mjs +11 -14
- package/js/web/actions.mjs +3 -9
- package/js/web/api.mjs +28 -10
- package/js/web/daemon.mjs +0 -1
- package/js/web/server.mjs +1 -0
- package/js/web/state.mjs +37 -16
- package/package.json +1 -1
- package/src/AGENT.md.tmpl +23 -17
- package/src/agents/_template.md +1 -1
- package/src/agents/advocate.md +1 -1
- package/src/agents/developer.md +12 -3
- package/src/agents/empiricist.md +1 -1
- package/src/agents/framer.md +1 -1
- package/src/agents/historian.md +1 -1
- package/src/agents/operator.md +1 -1
- package/src/agents/pragmatist.md +1 -1
- package/src/agents/researcher.md +1 -1
- package/src/agents/skeptic.md +1 -1
- package/src/agents/steward.md +1 -1
- package/src/agents/user-advocate.md +1 -1
- package/src/agents/visionary.md +1 -1
- package/src/bricks/intake.md +10 -3
- package/src/bricks/retro.md +13 -3
- package/src/doctrines/comms.md +1 -1
- package/src/doctrines/ops.md +1 -1
- package/src/doctrines/process.md +7 -5
- package/src/factories/analysis-to-build.json +1 -0
- package/src/factories/bug-report-to-fix.json +1 -0
- package/src/factories/issue-to-pr.json +1 -0
- package/src/laws/universal.md +2 -2
- package/src/modes/foreman.md +8 -14
- package/src/skills/commit.md +7 -2
- package/src/skills/debug.md +1 -1
- package/src/skills/diagram-design/SKILL.md +1 -1
- package/src/skills/diagram-design/VENDOR.md +3 -1
- package/src/skills/factory-forge.md +5 -3
- package/src/skills/factory.md +22 -1
- package/src/skills/geneseed.md +1 -1
- package/src/skills/handoff.md +1 -1
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/pipeline.md +6 -6
- package/src/skills/plan.md +7 -3
- package/src/skills/spring-testing.md +1 -1
- package/themes/biker.json +78 -78
- package/themes/commentator.json +81 -81
- package/themes/cyberpunk.json +79 -79
- package/themes/gamer.json +77 -77
- package/themes/imperial.json +82 -82
- package/themes/joker.json +79 -79
- package/themes/marvin.json +82 -82
- package/themes/mean.json +82 -82
- package/themes/military.json +78 -78
- package/themes/neutral.json +78 -78
- package/themes/pirate.json +79 -79
- package/themes/sports.json +79 -79
- package/themes/verstappen.json +78 -78
- package/themes/wizard.json +79 -79
- package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
- package/web/dist/assets/Activity-WQ3ykgxU.js +1 -0
- package/web/dist/assets/ActivityDetail-7rt04SkS.js +1 -0
- package/web/dist/assets/{Bonsai-DSwUbavu.js → Bonsai-BBl4XXqs.js} +1 -1
- package/web/dist/assets/{CopyButton-BzRQz7k2.js → CopyButton-Beven8yn.js} +1 -1
- package/web/dist/assets/Dashboard-BgLArtgu.js +2 -0
- package/web/dist/assets/Docs-B5aHp86J.js +5 -0
- package/web/dist/assets/Factories-BjqzXAw8.js +1 -0
- package/web/dist/assets/GreenhouseView-Bce212qd.js +1 -0
- package/web/dist/assets/Installs-B1OsrHXF.js +3 -0
- package/web/dist/assets/JournalView-CV4omyww.js +1 -0
- package/web/dist/assets/Kits-CW1e7xNa.js +1 -0
- package/web/dist/assets/Laws-1Ckf1lbs.js +4 -0
- package/web/dist/assets/LibRows-Dag1s0ZX.js +1 -0
- package/web/dist/assets/Library-B3FuFLel.js +3 -0
- package/web/dist/assets/Loops-CwqgnLNw.js +2 -0
- package/web/dist/assets/Markdown-CxkA7940.js +71 -0
- package/web/dist/assets/OperatorHudView-JmYY1pBR.js +1 -0
- package/web/dist/assets/Personal-DKLgLa7Z.js +2 -0
- package/web/dist/assets/Settings-BwErnh-R.js +1 -0
- package/web/dist/assets/Tabs-8zsyEPSK.js +1 -0
- package/web/dist/assets/index-CRWqKxfY.css +1 -0
- package/web/dist/assets/index-Ce6qF2nG.js +6 -0
- package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
- package/web/dist/index.html +2 -2
- package/adapters/claude-code/settings.json +0 -52
- package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
- package/web/dist/assets/Activity-DlQ30znB.js +0 -1
- package/web/dist/assets/ActivityDetail-CG0mn5fW.js +0 -1
- package/web/dist/assets/Dashboard-Ce3UOsxJ.js +0 -2
- package/web/dist/assets/Docs-CisVnYqv.js +0 -5
- package/web/dist/assets/Factories-Dq5oW4CU.js +0 -1
- package/web/dist/assets/GreenhouseView-y9WAfcc_.js +0 -1
- package/web/dist/assets/Installs-m4GElwFW.js +0 -3
- package/web/dist/assets/JournalView-DeBLRNGc.js +0 -1
- package/web/dist/assets/Kits-DJYVAnyE.js +0 -1
- package/web/dist/assets/Laws-CNpc_8ZV.js +0 -4
- package/web/dist/assets/LibRows-RO5bvXth.js +0 -1
- package/web/dist/assets/Library-Dg0ScciC.js +0 -3
- package/web/dist/assets/Loops-CjEdo-NG.js +0 -2
- package/web/dist/assets/Markdown-0ORz7tAc.js +0 -69
- package/web/dist/assets/OperatorHudView-2ujVMjq1.js +0 -1
- package/web/dist/assets/Personal-D0yS7ahT.js +0 -2
- package/web/dist/assets/Settings-DEN0U8QI.js +0 -1
- package/web/dist/assets/Tabs-But5R6_r.js +0 -1
- package/web/dist/assets/index-Ck42AbRX.js +0 -6
- package/web/dist/assets/index-PG_ukkh6.css +0 -1
- package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
|
@@ -124,8 +124,9 @@ function isolationReport(stats) {
|
|
|
124
124
|
// every depth and would hide `bricks/x.md` even under `!bricks/`. Create-if-absent (`wx`): a
|
|
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
|
-
// plugin — and the runtime is imported lazily, from a configurable dir)
|
|
128
|
-
|
|
127
|
+
// plugin — and the runtime is imported lazily, from a configurable dir). Both are
|
|
128
|
+
// js/hosts/geneseed-dir.mjs's line, kept by `node tests/twins.mjs --write`.
|
|
129
|
+
const GENESEED_GITIGNORE = '/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n';
|
|
129
130
|
// Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
|
|
130
131
|
// never a user edit, so it is upgraded. Any other content is the user's. Never throws.
|
|
131
132
|
async function writeGitignore(file) {
|
|
@@ -197,8 +197,9 @@ async function runChildSession(client, { prompt, agent, model, title, directory
|
|
|
197
197
|
// so neither the worktrees nor the traces show up as untracked files, with the team paths
|
|
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
|
-
// GENESEED_GITIGNORE in plugins/geneseed-workflow.js
|
|
201
|
-
|
|
200
|
+
// GENESEED_GITIGNORE in plugins/geneseed-workflow.js: both are js/hosts/geneseed-dir.mjs's
|
|
201
|
+
// line, kept by `node tests/twins.mjs --write`.
|
|
202
|
+
const GENESEED_GITIGNORE = '/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n';
|
|
202
203
|
// Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
|
|
203
204
|
// never a user edit, so it is upgraded. Any other content is the user's. Never throws.
|
|
204
205
|
async function writeGitignore(file) {
|
package/bin/geneseed-cli.mjs
CHANGED
|
@@ -55,7 +55,8 @@
|
|
|
55
55
|
// whole graph: `tests/unit/hook_cli.test.mjs`'s `importClosure` follows both import spellings.
|
|
56
56
|
// FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
|
|
57
57
|
import '../js/lib/node-floor.mjs';
|
|
58
|
-
import {
|
|
58
|
+
import { readFileSync } from 'node:fs';
|
|
59
|
+
import { cliCommand, cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
|
|
59
60
|
import { parseIntStrict } from '../js/lib/text.mjs';
|
|
60
61
|
import { printErr, printOut } from '../js/lib/fs.mjs';
|
|
61
62
|
|
|
@@ -73,8 +74,8 @@ import { printErr, printOut } from '../js/lib/fs.mjs';
|
|
|
73
74
|
*
|
|
74
75
|
* IT IS STILL A TABLE and still the DISPATCH rather than a declaration beside one.
|
|
75
76
|
* `tests/unit/hook_cli.test.mjs` scrapes `const VERBS = {` for its matrix gates, and
|
|
76
|
-
* `main`'s refusal
|
|
77
|
-
*
|
|
77
|
+
* `main`'s unknown-verb refusal draws its nearest-match suggestion from `Object.keys(VERBS)`
|
|
78
|
+
* (it no longer prints the list) — the order is the old table's and is not alphabetical.
|
|
78
79
|
*
|
|
79
80
|
* FLATTENED TO `verb: fn` since Task 5, AND TO `verb: loader` since the lazy pass: every row
|
|
80
81
|
* is now a thunk that imports the command's module and resolves to its function, so the one
|
|
@@ -115,13 +116,9 @@ const VERBS = {
|
|
|
115
116
|
// argues both.
|
|
116
117
|
menu: () => import('../js/ui/menu.mjs').then((m) => m.cmdMenu),
|
|
117
118
|
home: () => import('../js/ui/menu.mjs').then((m) => m.cmdHome),
|
|
118
|
-
//
|
|
119
|
-
//
|
|
120
|
-
//
|
|
121
|
-
// `js/ui/tui.mjs`'s header argues why this entry falls back to `cmd_tui`'s own
|
|
122
|
-
// panel-unavailable line rather than inventing a second full-screen UI, and
|
|
123
|
-
// `tests/unit/no_panel.test.mjs` asserts that no panel lies behind it — the module paints
|
|
124
|
-
// nothing and refuses on a TTY too — rather than leaving that merely untested.
|
|
119
|
+
// RETIRED: there was never a panel behind it, so it refused on every terminal. Kept one
|
|
120
|
+
// release as an alias that prints one line pointing at `menu` and exits 0, as `menu` does off
|
|
121
|
+
// a terminal; `tests/unit/no_panel.test.mjs` asserts the module still paints nothing.
|
|
125
122
|
tui: () => import('../js/ui/tui.mjs').then((m) => m.cmdTui),
|
|
126
123
|
// THE THREE THAT NEVER HAD A PYTHON ORIGINAL, and they are last for that reason rather
|
|
127
124
|
// than by alphabet: every row above is the twin of a subparser, and these three are not.
|
|
@@ -155,6 +152,34 @@ const VERBS = {
|
|
|
155
152
|
scorecard: () => import('../js/inspect/scorecard.mjs').then((m) => m.cmdScorecard),
|
|
156
153
|
};
|
|
157
154
|
|
|
155
|
+
/** Levenshtein distance, for the one "did you mean" an unknown verb gets. */
|
|
156
|
+
function editDistance(a, b) {
|
|
157
|
+
let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
|
|
158
|
+
for (let i = 1; i <= a.length; i += 1) {
|
|
159
|
+
const cur = [i];
|
|
160
|
+
for (let j = 1; j <= b.length; j += 1) {
|
|
161
|
+
cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
|
|
162
|
+
}
|
|
163
|
+
prev = cur;
|
|
164
|
+
}
|
|
165
|
+
return prev[b.length];
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* The closest verb to a mistyped one, or null when nothing is close. Close is at most a third
|
|
170
|
+
* of the typed word's length (and at least 1), so `stauts` finds `status` and `frobnicate`
|
|
171
|
+
* finds nothing: a suggestion for every typo is noise, not help.
|
|
172
|
+
*/
|
|
173
|
+
function nearestVerb(typed, verbs) {
|
|
174
|
+
let best = null;
|
|
175
|
+
let bestD = Math.max(1, Math.floor(typed.length / 3)) + 1;
|
|
176
|
+
for (const v of verbs) {
|
|
177
|
+
const d = editDistance(typed, v);
|
|
178
|
+
if (d < bestD) { best = v; bestD = d; }
|
|
179
|
+
}
|
|
180
|
+
return best;
|
|
181
|
+
}
|
|
182
|
+
|
|
158
183
|
function die(code, msg) {
|
|
159
184
|
// CRLF on Windows, for the same reason `js/hosts/hooks.mjs`'s funnels translate: argparse writes
|
|
160
185
|
// this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
|
|
@@ -293,11 +318,24 @@ async function main(argv) {
|
|
|
293
318
|
// Bare = `home`, as both launchers (`geneseed`, `geneseed.cmd`) already did — but the npm
|
|
294
319
|
// `bin` names THIS file, so a bare `geneseed` off PATH used to die asking for a verb.
|
|
295
320
|
if (!argv.length) argv = ['home'];
|
|
321
|
+
// The package version, which `geneseed version` does NOT print: that verb compares the
|
|
322
|
+
// install's build fingerprint with this source's. Read off the package.json beside this file,
|
|
323
|
+
// so it is the version npm installed, and answered before the shim check.
|
|
324
|
+
if (argv[0] === '--version' || argv[0] === '-V') {
|
|
325
|
+
const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
|
|
326
|
+
printOut(`geneseed ${pkg.version}\n`);
|
|
327
|
+
return 0;
|
|
328
|
+
}
|
|
329
|
+
// `help` and `help <verb>` are spellings of `--help` and `<verb> --help`, and nothing more:
|
|
330
|
+
// a rewrite here rather than a VERBS row, because a row would owe the table a subcommand.
|
|
331
|
+
// `help help` is the listing too: `help` is not a VERBS row, so it has no help of its own.
|
|
332
|
+
if (argv[0] === 'help') argv = argv.length > 1 && argv[1] !== 'help' ? [argv[1], '--help'] : ['--help'];
|
|
296
333
|
const verb = argv[0];
|
|
297
334
|
if (verb === '-h' || verb === '--help') {
|
|
298
|
-
return printVerbList('geneseed', [...Object.keys(VERBS), 'validate'], {
|
|
335
|
+
return printVerbList('geneseed', [...Object.keys(VERBS), 'validate', 'help'], {
|
|
299
336
|
update: 'an alias of upgrade',
|
|
300
337
|
validate: "check the source tree without emitting (the generator's --validate-only)",
|
|
338
|
+
help: "this list; help <command> prints that command's help",
|
|
301
339
|
});
|
|
302
340
|
}
|
|
303
341
|
// A DEAD HOOK SHIM, SAID ON EVERY RUN. The shim is machine-wide, so one stale write turns off
|
|
@@ -323,12 +361,12 @@ async function main(argv) {
|
|
|
323
361
|
if (verb === 'validate') {
|
|
324
362
|
// Lazy for the same reason the table rows are — `parseDriverArgs` alone drags the whole
|
|
325
363
|
// generator driver in, and every OTHER verb was paying for it.
|
|
326
|
-
const [{ cmdValidate,
|
|
364
|
+
const [{ cmdValidate, validateUsage }, { parseDriverArgs }] = await Promise.all([
|
|
327
365
|
import('../js/inspect/validate.mjs'), import('../js/build/driver.mjs'),
|
|
328
366
|
]);
|
|
329
367
|
// Before the borrowed parser, whose own `-h` prints the GENERATOR's usage.
|
|
330
368
|
if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
|
|
331
|
-
printOut(
|
|
369
|
+
printOut(validateUsage());
|
|
332
370
|
return 0;
|
|
333
371
|
}
|
|
334
372
|
try {
|
|
@@ -345,9 +383,16 @@ async function main(argv) {
|
|
|
345
383
|
// named, the two entry points now cover every subcommand there is, so the clause was not
|
|
346
384
|
// just about to become false — it was already claiming a third place for verbs that do
|
|
347
385
|
// not exist.
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
386
|
+
//
|
|
387
|
+
// A hook verb (`context`, `tool-gate`, …) is in the table but not here: the emitted
|
|
388
|
+
// settings call it through `geneseed-hook`, and saying so beats "unknown command".
|
|
389
|
+
if (cliCommand(verb) !== null) {
|
|
390
|
+
return die(2, `'${verb}' is a hook verb: the host runs it through geneseed-hook `
|
|
391
|
+
+ '(bin/geneseed-hook.mjs), not this command. See geneseed --help.');
|
|
392
|
+
}
|
|
393
|
+
const near = nearestVerb(verb, [...Object.keys(VERBS), 'validate', 'help']);
|
|
394
|
+
return die(2, `unknown command '${verb}'.${near ? ` Did you mean '${near}'?` : ''} `
|
|
395
|
+
+ 'See geneseed --help.');
|
|
351
396
|
}
|
|
352
397
|
// `js/cli-table.json`, the CLI as data. A verb this table dispatches and the file does not
|
|
353
398
|
// describe is a REFUSAL and not a parse with no rules: an empty spec would accept every
|
package/bin/geneseed-hook.mjs
CHANGED
|
@@ -50,10 +50,10 @@
|
|
|
50
50
|
import '../js/lib/node-floor.mjs';
|
|
51
51
|
// Not a new module on the hot path: every verb's module imports `js/lib/fs.mjs` too, so this
|
|
52
52
|
// edge only loads early a file the process would load anyway.
|
|
53
|
-
import { printErr } from '../js/lib/fs.mjs';
|
|
53
|
+
import { printErr, printOut } from '../js/lib/fs.mjs';
|
|
54
54
|
// Also not a new module: every verb's module imports it. It carries the activity switch, so the
|
|
55
55
|
// off path costs one file read and no import of the writer.
|
|
56
|
-
import { activityOn, readStdin } from '../js/hosts/hooks-prims.mjs';
|
|
56
|
+
import { activityOn, askDecision, gateSafe, readStdin } from '../js/hosts/hooks-prims.mjs';
|
|
57
57
|
import { isatty } from 'node:tty';
|
|
58
58
|
import path from 'node:path';
|
|
59
59
|
|
|
@@ -69,9 +69,10 @@ const gates = () => import('../js/hosts/hooks.mjs');
|
|
|
69
69
|
// Verbs PreToolUse/PostToolUse actually gate a tool call with. The machine-wide, last-writer-wins
|
|
70
70
|
// shim (this file's header) means a stale checkout can be handed a flag only a newer install
|
|
71
71
|
// knows (e.g. `--no-consent`); on Claude Code, exit 2 from one of THESE verbs blocks the tool
|
|
72
|
-
// outright, with no ask. `main` below answers an argv error on a gate verb with exit 0
|
|
73
|
-
// a gate's own decision
|
|
74
|
-
//
|
|
72
|
+
// outright, with no ask. `main` below answers an argv error on a gate verb with exit 0 and the
|
|
73
|
+
// gate-error ask instead (a stderr warning on Bob) — a gate's own decision exits 0 and signals
|
|
74
|
+
// through stdout too (`askDecision`), so what used to be a hard lockout is a question the person
|
|
75
|
+
// can answer, never "the gate is silent this one call" (see I3/B1).
|
|
75
76
|
const GATE_VERBS = new Set(['git-gate', 'rule-gate', 'tool-gate']);
|
|
76
77
|
const VERBS = {
|
|
77
78
|
context: { load: () => import('../js/hosts/hooks-context.mjs'), fn: 'cmdContext', flags: HOSTED },
|
|
@@ -101,6 +102,8 @@ const VERBS = {
|
|
|
101
102
|
'--no-deletion-gate': 'noDeletionGate', '--no-secrets-gate': 'noSecretsGate',
|
|
102
103
|
'--no-ownership-gate': 'noOwnershipGate', '--no-external-gate': 'noExternalGate',
|
|
103
104
|
'--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
|
|
105
|
+
// Bob's commit/push warning, when process 5 is off: `gitDecide` reads it as on git-gate.
|
|
106
|
+
'--no-consent': 'noConsent',
|
|
104
107
|
},
|
|
105
108
|
},
|
|
106
109
|
learn: {
|
|
@@ -163,6 +166,50 @@ async function trackActivity(verb, args) {
|
|
|
163
166
|
} catch { /* the activity view is best-effort; a hook that fails is a tool call that fails */ }
|
|
164
167
|
}
|
|
165
168
|
|
|
169
|
+
/**
|
|
170
|
+
* The tap (js/hosts/hook-tap.mjs): with `GENESEED_HOOK_TAP=<dir>` in the host's environment,
|
|
171
|
+
* the payload the verb just answered is written there as a fixture, values replaced by their
|
|
172
|
+
* shape. After the verdict, like `trackActivity`, and on the same cached stdin. The caller tests
|
|
173
|
+
* the variable, so an untapped hook never imports the module; a terminal sends no payload.
|
|
174
|
+
* Never prints, never changes the exit code.
|
|
175
|
+
*/
|
|
176
|
+
async function tapHook(verb, args) {
|
|
177
|
+
try {
|
|
178
|
+
if (isatty(0)) return;
|
|
179
|
+
const { tapPayload } = await import('../js/hosts/hook-tap.mjs');
|
|
180
|
+
tapPayload(process.env.GENESEED_HOOK_TAP, readStdin(), { verb, host: args.host || 'claude' });
|
|
181
|
+
} catch { /* a capture is a favour to a maintainer; a hook that fails is a tool call that fails */ }
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* A verb whose module failed to load, or threw past its own guard. `guardGate` only covers a gate
|
|
186
|
+
* once its module has loaded; a module that cannot (a file missing mid-`git pull` under the shared
|
|
187
|
+
* shim, a syntax error) used to exit 1 with nothing on stdout, which Claude reads as "the gate
|
|
188
|
+
* deferred". So a gate verb gives the gate-error verdict `guardGate` gives — an ask on Claude and
|
|
189
|
+
* OpenClaude, a stderr warning on Bob, where gate-error is never a block — built from
|
|
190
|
+
* `./hooks-prims.mjs`, which the entry has already loaded. Not ledgered: the ledger's writer is
|
|
191
|
+
* in the module that failed. Every other verb exits 0 with stdout empty and one stderr line, so a
|
|
192
|
+
* broken context hook shows in the host's hook log: stdout is the only channel any host reads as
|
|
193
|
+
* a decision, and on Bob too a stderr line with exit 0 is a log entry (the gates' Bob warnings
|
|
194
|
+
* already are). The residual limit: a
|
|
195
|
+
* module this file imports statically (`fs.mjs`, `hooks-prims.mjs`) fails at link time, before
|
|
196
|
+
* any of this runs.
|
|
197
|
+
*/
|
|
198
|
+
function verbFailed(verb, args, e) {
|
|
199
|
+
let name = e;
|
|
200
|
+
try { name = e.message || e; } catch { /* `gateSafe` meets `e` as it is */ }
|
|
201
|
+
if (!GATE_VERBS.has(verb)) {
|
|
202
|
+
try { printErr(`[geneseed-hook] ${verb} failed: ${name}\n`); } catch { /* an unprintable error says nothing */ }
|
|
203
|
+
return 0;
|
|
204
|
+
}
|
|
205
|
+
if (args.host === 'bob') {
|
|
206
|
+
printErr(`[geneseed] ${gateSafe('gate-error', 'warned', { name })}\n`);
|
|
207
|
+
return 0;
|
|
208
|
+
}
|
|
209
|
+
printOut(askDecision(gateSafe('gate-error', 'ask', { name })));
|
|
210
|
+
return 0;
|
|
211
|
+
}
|
|
212
|
+
|
|
166
213
|
function die(code, msg) {
|
|
167
214
|
// CRLF on Windows, for the same reason the hook verbs' funnels translate: argparse
|
|
168
215
|
// writes this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
|
|
@@ -170,6 +217,20 @@ function die(code, msg) {
|
|
|
170
217
|
return code;
|
|
171
218
|
}
|
|
172
219
|
|
|
220
|
+
/**
|
|
221
|
+
* The `--host` an argv names, in both spellings `parse` takes, the last one winning as it does
|
|
222
|
+
* there. For the argv-error path only: `parse` returns no args with an error, and the gate-error
|
|
223
|
+
* answer still has to know whether its reader is Bob.
|
|
224
|
+
*/
|
|
225
|
+
function hostNamed(argv) {
|
|
226
|
+
let host = null;
|
|
227
|
+
argv.forEach((tok, i) => {
|
|
228
|
+
if (tok.startsWith('--host=')) host = tok.slice('--host='.length);
|
|
229
|
+
else if (tok === '--host' && argv[i + 1] !== undefined) host = argv[i + 1];
|
|
230
|
+
});
|
|
231
|
+
return host;
|
|
232
|
+
}
|
|
233
|
+
|
|
173
234
|
/**
|
|
174
235
|
* `argparse`'s surface for these verbs, and only theirs: `--flag VALUE`, the
|
|
175
236
|
* `--flag=VALUE` spelling it also accepts, store_true switches, and one optional
|
|
@@ -249,11 +310,20 @@ async function main(argv) {
|
|
|
249
310
|
const parsed = parse(spec, argv.slice(1));
|
|
250
311
|
if (parsed.error) {
|
|
251
312
|
// A gate verb must never exit 2 on an argv error: that is indistinguishable, to Claude's
|
|
252
|
-
// PreToolUse, from the gate deliberately blocking (see I3/B1 above).
|
|
253
|
-
//
|
|
254
|
-
//
|
|
255
|
-
// `
|
|
256
|
-
|
|
313
|
+
// PreToolUse, from the gate deliberately blocking (see I3/B1 above). It must not exit 0 with
|
|
314
|
+
// stdout empty either: that reads as "the gate deferred", so a stale shim handed a newer flag
|
|
315
|
+
// let every call through unjudged. It answers as a gate whose module failed to load does
|
|
316
|
+
// (`verbFailed`): an ask on Claude and OpenClaude, where the person can still allow the call —
|
|
317
|
+
// so no lockout — and is told the gate is broken; a stderr warning and exit 0 on Bob, whose
|
|
318
|
+
// PreToolUse has no matcher, so exit 2 there would refuse every tool, reads included. The
|
|
319
|
+
// stderr line stays for a human debugging the shim.
|
|
320
|
+
if (GATE_VERBS.has(verb)) {
|
|
321
|
+
printErr(`geneseed-hook: error: ${parsed.error}\n`);
|
|
322
|
+
return verbFailed(verb, { host: hostNamed(argv.slice(1)) }, new Error(parsed.error));
|
|
323
|
+
}
|
|
324
|
+
// `activity` decides nothing, and it runs on UserPromptSubmit, where exit 2 erases the
|
|
325
|
+
// user's prompt: the stderr line, exit 0, stdout empty.
|
|
326
|
+
if (verb === 'activity') {
|
|
257
327
|
printErr(`geneseed-hook: error: ${parsed.error}\n`);
|
|
258
328
|
return 0;
|
|
259
329
|
}
|
|
@@ -267,12 +337,24 @@ async function main(argv) {
|
|
|
267
337
|
// `context` answers SessionStart and SubagentStart (settings.mjs), told apart by the payload's
|
|
268
338
|
// event name. Read here, not in the verb, so an in-process caller never blocks on fd 0; the read
|
|
269
339
|
// is cached, so `trackActivity` reuses it. A terminal sends no payload.
|
|
340
|
+
// The same parse hands `context` the payload's `cwd`, its project root on a host that sets no
|
|
341
|
+
// `$CLAUDE_PROJECT_DIR` (`hookProjectDir`).
|
|
270
342
|
if (verb === 'context' && !isatty(0)) {
|
|
271
|
-
try {
|
|
343
|
+
try {
|
|
344
|
+
const payload = JSON.parse(readStdin() || '{}');
|
|
345
|
+
parsed.args.event = payload.hook_event_name ?? null;
|
|
346
|
+
parsed.args.cwd = typeof payload.cwd === 'string' ? payload.cwd : null;
|
|
347
|
+
} catch { /* not JSON: SessionStart */ }
|
|
348
|
+
}
|
|
349
|
+
let rc;
|
|
350
|
+
try {
|
|
351
|
+
rc = (await spec.load())[spec.fn](parsed.args);
|
|
352
|
+
} catch (e) {
|
|
353
|
+
return verbFailed(verb, parsed.args, e);
|
|
272
354
|
}
|
|
273
|
-
const rc = (await spec.load())[spec.fn](parsed.args);
|
|
274
355
|
await trackActivity(verb, parsed.args);
|
|
275
356
|
await baselineStores(verb, parsed.args);
|
|
357
|
+
if (process.env.GENESEED_HOOK_TAP) await tapHook(verb, parsed.args);
|
|
276
358
|
return rc;
|
|
277
359
|
}
|
|
278
360
|
|
|
@@ -26,7 +26,7 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
|
|
|
26
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
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
|
-
| `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 (
|
|
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 (a frozen fork, and no check runs a model turn: [What is verified](host-matrix.md#what-is-verified)) | 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
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
|
|
@@ -44,7 +44,7 @@ What "dormant" means per host:
|
|
|
44
44
|
|
|
45
45
|
**Git worktrees.** A linked worktree of an excluded repo (`git worktree add`) is excluded too, wherever it sits on disk: the hooks and plugins follow its `.git` file back to the main repository. The global `CLAUDE.md` is the exception on Claude Code and OpenClaude: `settings.local.json` is gitignored, so a worktree never gets it. Geneseed writes no tracked file in a repo you told it to leave alone, so `exclude add` and `exclude list` print the snippet to commit yourself in the repo's tracked `.claude/settings.json` (`.openclaude/` for OpenClaude): `"claudeMdExcludes": ["<path to the global CLAUDE.md>"]`.
|
|
46
46
|
|
|
47
|
-
**Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. And a global install created *after* you added exclusions is silent in those folders at once, through the shared list, and its next emit applies the repo-side wiring there. Until that emit, `geneseed exclude list` flags it.
|
|
47
|
+
**Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. That makes an exclusion a poor way to save tokens: the listings stay on Claude Code and OpenClaude, and on OpenCode the global instructions file still loads (see [Why there is no chat mode](../token-footprint.md#why-there-is-no-chat-mode)). And a global install created *after* you added exclusions is silent in those folders at once, through the shared list, and its next emit applies the repo-side wiring there. Until that emit, `geneseed exclude list` flags it.
|
|
48
48
|
|
|
49
49
|
The web console has the same controls in the **Excluded folders** card on the Installs page, shown once a global install exists.
|
|
50
50
|
|
|
@@ -95,7 +95,7 @@ What stops asking, per host: the real-loss check of `git-gate` (Claude Code, Ope
|
|
|
95
95
|
Limits:
|
|
96
96
|
- **OpenCode reads the switch at start.** The guard plugin reads `Deletion gate:` from the install's `AGENT.md` once, when OpenCode loads it: restart OpenCode after flipping it.
|
|
97
97
|
- **A global install beside a project install.** On Claude Code and OpenClaude the global `git-gate` stands down for a project install, so the project's switch decides. Bob's `tool-gate` and the OpenCode guard do not stand down: an armed global install still refuses real loss inside a project whose own install is off.
|
|
98
|
-
- **An older `opencode.json` keeps its Law IV keys.** Switching off removes the `permission.bash` entries the manifest records Geneseed adding (`bash_gates`, since 5.2.0). An install made before that has no record, so the build warns that it keeps them and they keep asking. Run the build once with `--prune-gates` to remove those still set as Geneseed writes them, or delete them by hand. An entry you changed always stays, and a commented `opencode.jsonc` is never rewritten: the build names the entries to remove.
|
|
98
|
+
- **An older `opencode.json` keeps its Law IV keys.** Switching off removes the `permission.bash` entries the manifest records Geneseed adding (`bash_gates`, since 5.2.0). An install made before that has no record, so the build warns that it keeps them and they keep asking. Run the build once with `--prune-gates` to remove those still set as Geneseed writes them, or delete them by hand. An entry you changed always stays, and a commented `opencode.json` or `opencode.jsonc` is never rewritten: the build names the entries to remove.
|
|
99
99
|
- **An older hook shim silences the whole gate.** The flag is new. While the machine's shared hook shim still points at an older checkout, that checkout refuses the flag and the gate verb lets every call through on a disarmed install — on Claude Code and OpenClaude the root-scan and consent checks too, on Bob also *Sealed Secrets* and *External Gate*. Update the checkout the shim points at (`geneseed rebuild-all`) before switching the gate off.
|
|
100
100
|
|
|
101
101
|
### Law I secrets gate and Law III done gate — on or off
|
|
@@ -44,7 +44,7 @@ but its first stage, or a route back that spends no cycle.
|
|
|
44
44
|
## Forks and lanes
|
|
45
45
|
|
|
46
46
|
A **fork** is where the work takes one way or another. It is a brick that declares **named
|
|
47
|
-
outcomes**, any outcome other than `pass`, `fail`, `error`, `none` or `
|
|
47
|
+
outcomes**, any outcome other than `pass`, `fail`, `error`, `none`, `needs-info` or `reject`. `triage` is one: `bug`,
|
|
48
48
|
`feature`, `deps`, `refactor`, `docs` and `fail`. Each named outcome has its own edge to its own
|
|
49
49
|
stage, its **lane**, and the outcome the brick reports picks the lane. `geneseed factory next`
|
|
50
50
|
hands the fork its `lanes`: each outcome with the stage it leads to.
|
|
@@ -76,6 +76,37 @@ exception is the run's spec, `specs/<slug>/spec.md`: the `spec` stage writes it,
|
|
|
76
76
|
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
|
|
77
77
|
names the run it belongs to.
|
|
78
78
|
|
|
79
|
+
## The queue, and a refused item
|
|
80
|
+
|
|
81
|
+
A run takes one work item. To pick from several, ask the agent for the **queue**: it lists the
|
|
82
|
+
open issues that carry the label `factory` (or a label you name), and you pick one, several or
|
|
83
|
+
all. Several picks run one after the other, in the order you gave, each as its own run in its
|
|
84
|
+
own worktree, each with its own merge question. A run that holds a gate holds the queue. An
|
|
85
|
+
issue's text is the run's input, never an instruction to the agent. No file configures the queue,
|
|
86
|
+
and nothing starts a run by itself.
|
|
87
|
+
|
|
88
|
+
`intake` may also **refuse** an item, with the outcome `reject`: it is already done, it duplicates
|
|
89
|
+
another issue or pull request, or it goes against a rule the project states. The run holds and
|
|
90
|
+
shows you the reason and its evidence. `ok` accepts the refusal and stops the run, `amend` runs
|
|
91
|
+
`intake` again with your reason to build it, and `no` stops too. In each shipped factory the
|
|
92
|
+
`reject` edge goes to `$stop`; a factory of your own that has no such edge stops the same way.
|
|
93
|
+
|
|
94
|
+
## What a run measures
|
|
95
|
+
|
|
96
|
+
Every `record` and `decide` writes the time on its history entry, and `init` writes when the run
|
|
97
|
+
started. From those, `geneseed factory report` gives each stage its runs, its reworks, its work
|
|
98
|
+
time and its tokens, and the run its work time and the time it waited for you at a gate. The time
|
|
99
|
+
between a held outcome and your answer is waiting time, never the stage's. A rework is an outcome
|
|
100
|
+
that spent a cycle: a failed `checks`, `review-panel` or `holdout`, or red CI.
|
|
101
|
+
|
|
102
|
+
Tokens are recorded only where the host reports a count for the agent that ran the stage
|
|
103
|
+
(`record --tokens <n>`); nothing estimates one, and a loop stage carries none. There is no cost in
|
|
104
|
+
money: Geneseed holds no price table. A number nobody recorded is `null` in the report, never 0,
|
|
105
|
+
so a `FACTORY.md` written before times were stamped still runs and reports `unknown`.
|
|
106
|
+
|
|
107
|
+
The `retro` stage copies those numbers into the run report, and adds, for each `review-panel`
|
|
108
|
+
seat, how many rounds it failed.
|
|
109
|
+
|
|
79
110
|
## The shipped factories
|
|
80
111
|
|
|
81
112
|
| Factory | Stages |
|
|
@@ -88,7 +119,7 @@ The bricks they add:
|
|
|
88
119
|
|
|
89
120
|
| Brick | Does | Outcomes |
|
|
90
121
|
| --- | --- | --- |
|
|
91
|
-
| `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria, its `size` and its `areas`. `needs-info` holds for your answers to its questions (`gate: human`) | `pass`, `fail`, `needs-info` |
|
|
122
|
+
| `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria, its `size` and its `areas`. `needs-info` holds for your answers to its questions, and `reject` holds when it finds the item already done, a duplicate, or against a rule the project states, with the reason and its evidence (`gate: human`). It never posts on the issue | `pass`, `fail`, `needs-info`, `reject` |
|
|
92
123
|
| `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` |
|
|
93
124
|
| `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` |
|
|
94
125
|
| `checks` | Runs the done list as the base branch holds it, never the branch's copy. `error` holds when the diff touches a locked path, or on an environment failure (a failed fetch, a timeout, a missing tool); `none` holds with a proposed list when the base has none | `pass`, `fail`, `error`, `none` |
|
|
@@ -96,7 +127,7 @@ The bricks they add:
|
|
|
96
127
|
| `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` |
|
|
97
128
|
| `pr-open` | Pushes the branch (the push asks you) and opens the PR, or updates the one already open | `pass`, `fail` |
|
|
98
129
|
| `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; so does CI still pending at the bound, or a `gh`/`glab` that is missing or fails | `pass`, `fail`, `none` |
|
|
99
|
-
| `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, and keeps only a lasting lesson in memory | `pass` |
|
|
130
|
+
| `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, with the numbers of `geneseed factory report`, and keeps only a lasting lesson in memory | `pass` |
|
|
100
131
|
|
|
101
132
|
`analysis-to-build` also uses the loops' own `spec` brick (`gate: human`), the one the
|
|
102
133
|
`spec-first-feature` loop starts with, and `issue-to-pr` the loops' `docs-update` brick as its
|
|
@@ -179,9 +210,12 @@ graph: its stages top to bottom, a fork's lanes side by side, a `loop:` stage as
|
|
|
179
210
|
that names its loop over `whole loop`, each route back as a rail on the left with its cycle and
|
|
180
211
|
`max`, and `close` and `stop` as end caps.
|
|
181
212
|
Each factory shows how to start it: the request to give the agent, and the commands to start it
|
|
182
|
-
by hand, the worktree first and then `geneseed factory init`. Its **Active** tab
|
|
183
|
-
registered run,
|
|
184
|
-
|
|
213
|
+
by hand, the worktree first and then `geneseed factory init`. Its **Active** tab is a board of every
|
|
214
|
+
registered run, in three columns: **Waits for you**, **Running** and **Ended**. A card shows where
|
|
215
|
+
the run stands, its task, the laps spent on each cycle, and its work and waiting time. A card
|
|
216
|
+
opens the run: its graph with the current stage lit, the laps spent on each cycle, the child
|
|
217
|
+
loop's current step, written `at <node>` in the current stage's box, and a timeline of every
|
|
218
|
+
stage with its outcome, its time, its duration and each rework. The page changes nothing, neither a run nor `factories.json`: the next `geneseed factory init` on the machine drops a run whose worktree is gone, and a closed run 7 days after that init first saw it closed. You answer a run in the
|
|
185
219
|
agent's session.
|
|
186
220
|
|
|
187
221
|
## Your own factories
|
|
@@ -14,7 +14,7 @@ link: {"hash": "#/installs/hosts", "label": "Change it on Installs →"}
|
|
|
14
14
|
### The difference
|
|
15
15
|
|
|
16
16
|
- **Full** — the instructions file carries the Ethos, every Rule and every rule of the active doctrine packs at complete length, reasoning included, every turn.
|
|
17
|
-
- **Lean** — each Rule and each doctrine rule is carried as its heading plus a short form written by hand (the rule and how it works, not the first sentence cut off).
|
|
17
|
+
- **Lean** — each Rule and each doctrine rule is carried as its heading plus a short form written by hand (the rule and how it works, not the first sentence cut off). One pointer after the doctrine packs names where the complete text of both layers is on disk, and the agent reads the reasoning when a rule's application is unclear. The Ethos gets one hand-written short form for the whole layer, because it is flowing prose rather than numbered rules. Lean also drops the voice's flourish: a heading names the rule by its plain principle (`Dictate I — Sealed Secrets`, not `Dictate I — Arcana Sigillata · Sealed Secrets`), and no section opens with an italic epigraph. Full keeps both, and so do the complete files on disk.
|
|
18
18
|
|
|
19
19
|
Neither setting hides text from the agent. They decide what is in front of it on *every* turn.
|
|
20
20
|
|
|
@@ -32,6 +32,16 @@ Everything else is identical at both settings — the same agents, skills, plugi
|
|
|
32
32
|
|
|
33
33
|
For measured numbers per host, see [docs/token-footprint.md](../token-footprint.md).
|
|
34
34
|
|
|
35
|
+
### There is no chat mode
|
|
36
|
+
|
|
37
|
+
Footprint is the only token dial. There is no command that switches the harness off for a quick question, and that is deliberate.
|
|
38
|
+
|
|
39
|
+
- **What it costs.** Measured on 2026-11-12, the harness adds about 11–14k tokens to a session at lean and 18–21k at full, depending on the host. Where the provider caches prompts, that is billed at the full price once per session and at the cached rate on every later message.
|
|
40
|
+
- **Why not a command in the chat.** The harness is in the context before your first message, and no host can take it back out of a running conversation. A command could only tell the agent to ignore the rules, which saves nothing.
|
|
41
|
+
- **Why not a toggle on resume.** On Claude Code and OpenCode 2, resuming a conversation without the harness keeps it in the history, and resuming with it again loads it a second time.
|
|
42
|
+
|
|
43
|
+
So the harness stays in place in every session. For a single session without it, each host has its own launch option; the launch lines, their limits and every measurement are in [Why there is no chat mode](../token-footprint.md#why-there-is-no-chat-mode).
|
|
44
|
+
|
|
35
45
|
### How to set it
|
|
36
46
|
|
|
37
47
|
Footprint is stored in a `.geneseed-footprint` marker in the install and kept across every rebuild and upgrade, on every host.
|
|
@@ -11,7 +11,7 @@ link: {"hash": "#/installs/hosts", "label": "Set the mode on Installs →"}
|
|
|
11
11
|
|
|
12
12
|
> **You already know this:** a tech lead with a team. Quick questions get answered on the spot; a real feature becomes a ticket that someone builds on a branch, and the lead reviews the result before it is merged.
|
|
13
13
|
|
|
14
|
-
Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a task worker or a pipeline is a one-shot
|
|
14
|
+
Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a task worker or a pipeline is a one-shot run for a single task, committed only on its own branch and merged by the session once you accept; a loop is a long-running state machine that commits each validated iteration on its own branch.
|
|
15
15
|
|
|
16
16
|
### direct — the default
|
|
17
17
|
|
|
@@ -70,7 +70,7 @@ Inside the crew, the developer implements and the tester runs the tests and lint
|
|
|
70
70
|
|
|
71
71
|
### Nothing lands beyond the worker's branch
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
A worker or crew commits only in its own worktree, never pushes, and never merges outside its own branch. When it is done, it hands back that branch: its local commits (its own, and its 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:
|
|
74
74
|
|
|
75
75
|
1. re-runs the tests and lint itself — its log is its own account, not proof;
|
|
76
76
|
2. shows you the diff from the base it recorded, and the green output;
|
|
@@ -37,11 +37,11 @@ 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)
|
|
41
|
-
- `Stop` → `geneseed-hook learn`.
|
|
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) exactly the rules whose Bob cell says *block* in [Rule enforcement, by host](enforcement-table.md). 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
|
+
- `Stop` → `geneseed-hook learn`. Bob's `Stop` carries no transcript, so nothing is learned there; the [change report](hooks.md#the-change-report) still runs.
|
|
42
42
|
- `UserPromptSubmit` → `geneseed-hook activity`, which records the turn for the Activity view.
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
What was checked against each host itself is in [What is verified](host-matrix.md#what-is-verified). If a hook does not fire, the same rules still reach the agent through the instructions file.
|
|
45
45
|
|
|
46
46
|
## The hook shim
|
|
47
47
|
|
|
@@ -14,7 +14,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
|
|
|
14
14
|
| Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
|
|
15
15
|
| Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
|
|
16
16
|
| Your `user-rules.md` handed to each sub-agent | — (later) | 🪝 hook | — (no `SubagentStart`) | 🪝 hook² |
|
|
17
|
-
| Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook |
|
|
17
|
+
| Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | ➖ wired, inert: Bob's `Stop` carries no transcript¹ | 🪝 hook² |
|
|
18
18
|
| Live sessions in the web console's [Activity view](../reference/plugin-activity.md) | ⚙️ plugin | 🪝 hook, files per subagent, context size | 🪝 hook, per tool call only (no transcript, no context size, subagent files not attributed)¹ | 🪝 hook, files per subagent, context size² |
|
|
19
19
|
| Real data loss (force-push to `main`, discarding uncommitted work, `rm` of untracked files…) | ⚙️ block³ · 🔒 ask (reflog, gc) | 🪝 ask | 🪝 block¹ | 🪝 ask² |
|
|
20
20
|
| Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
|
|
@@ -28,16 +28,34 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
|
|
|
28
28
|
|
|
29
29
|
✅ native · ⚙️ OpenCode plugin · 🔒 `permission` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
|
|
30
30
|
|
|
31
|
-
¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks
|
|
32
|
-
² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo).
|
|
31
|
+
¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks exactly the rules whose Bob cell says *block* in [Rule enforcement, by host](enforcement-table.md), and turns the commit/push consent into a logged warning. It has no `SubagentStop` event. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them. The `Stop` hook is wired and runs the [change report](hooks.md#the-change-report), but learns nothing: Bob's `Stop` payload carries no transcript, and the group is kept so that learning starts if Bob ever sends one. The rules preamble still holds if a hook does not fire. For what was checked against Bob itself, see [What is verified](#what-is-verified).
|
|
32
|
+
² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). See [What is verified](#what-is-verified).
|
|
33
33
|
³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so a standing-rule write gets OpenCode's own prompt, and the guard refuses a file-tool write where no prompt can run. Shell is not a boundary on any host: only parsed forms are read, and the host's command permission is the backstop. A real data loss is blocked outright (as on Bob) rather than asked; `GENESEED_GUARD=warn` turns a block into a logged warning.
|
|
34
34
|
⁴ The checks differ in shape: OpenCode's guard plugin blocks writes *to* private-key and credential files by path; the Claude-shaped hook looks at the *content* being written for credential-shaped strings (cloud keys, tokens, private-key blocks) and asks. A `.env` file is exempt on the hook side — that is where a secret is allowed to live.
|
|
35
35
|
⁵ A linked git worktree of an excluded repo is excluded too: the hooks and plugins follow its `.git` file back to the main repository. `claudeMdExcludes` is the exception — it lives in the gitignored `settings.local.json`, which a worktree never gets — so `geneseed exclude add` and `exclude list` print the snippet to commit yourself. See [Exclusions](exclusions.md).
|
|
36
36
|
|
|
37
|
+
## What is verified
|
|
38
|
+
|
|
39
|
+
This is the one place that says what was checked against each host itself, how, and when. Every other page links here and states nothing of its own; `geneseed doctor` fails a page that does.
|
|
40
|
+
|
|
41
|
+
| Host | Method | Date | Scope | Not covered |
|
|
42
|
+
| --- | --- | --- | --- | --- |
|
|
43
|
+
| Claude Code | canary: `tests/host_canary.mjs` installs the host from npm and starts it in a throwaway home | weekly in CI, at npm `latest` | `claude doctor` lists no invalid setting in the emitted `settings.json`; a logged-out `-p` run shows `SessionStart` running the context hook | hooks that need a model turn: the `PreToolUse` gates, `Stop` |
|
|
44
|
+
| OpenClaude | canary, the same run | weekly in CI, at npm `latest` | the emitted settings load; `SessionStart` runs the context hook. Its `doctor` checks only the auto-updater, so there is no settings verdict to read | hooks that need a model turn |
|
|
45
|
+
| OpenClaude | source read | 2026-09 | the config directory, the root files it loads, the settings and hook types (`src/utils/envUtils.ts`, `claudemd.ts`, `config.ts`, `src/types/hooks.ts`) | |
|
|
46
|
+
| Bob | bundle read: Bob 2.2.3's shipped `bob-code/dist/extension.js` | 2026-10 | the hook payload (Claude's keys plus `cwd`), the event list, the strict settings schema, the agent frontmatter reader | whether Bob lists agents to the model; a sub-agent depth cap |
|
|
47
|
+
| Bob | live session, Bob IDE | 2026-10-23 | a `tool-gate` refusal (exit 2) stopped the call and its reason reached the model; Bob ignores Claude's `disallowedTools`, which is why a read-only agent carries `groups:`; the first-reply override | the `Stop` hook; the ownership gate's sub-agent deferral |
|
|
48
|
+
| Bob | live session | 2026-10-25 | a prompt wrote an Activity snapshot from `UserPromptSubmit` | |
|
|
49
|
+
| Bob | canary | never | nothing: IBM does not publish Bob Shell on npm, so the canary reports Bob as `skip` | everything above is a one-time read, not a standing check. [Verify it works](../guides/verify.md) has the by-hand steps |
|
|
50
|
+
| OpenCode V1 | canary | weekly in CI, at npm `latest` (log lines measured 2026-10-12) | no `failed to load plugin` line names a Geneseed plugin, and the workflow plugin's banner shows `.server` ran | the guard's refusal, which needs a model turn |
|
|
51
|
+
| OpenCode V2 | canary | weekly in CI, at npm `latest` (log lines measured 2026-10-12) | no `failed to load plugin` line names a Geneseed plugin, and a `loading plugin` line is logged for each | the guard's refusal, which needs a model turn |
|
|
52
|
+
|
|
53
|
+
No check on any host calls a model. `geneseed doctor --probe` covers the other half on your own machine: it runs the installed gates through each host's shell on calls they must refuse and calls they must let through.
|
|
54
|
+
|
|
37
55
|
## The one conditional row
|
|
38
56
|
|
|
39
57
|
The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. The standing-rule row is conditional the same way: it enforces *Persist Insight*, also in the process pack, and excluding it (or the pack) drops that hook on every host ([Exclusions](exclusions.md)). Everything else in the table is always on.
|
|
40
58
|
|
|
41
|
-
One OpenCode asymmetry: Geneseed shares `opencode.json` with you, so it removes only what it recorded writing. The manifest lists the `permission.bash` gates it added (`bash_gates`), and a rebuild without the process pack, or with `--no-deletion-gate`, takes back those that still read as it wrote them. An entry that was already there, one you changed, and every gate on an install made before 5.2.0 (which has no record) stays and is named in a warning; `--prune-gates` on one build removes the last kind. A `permission.skill` deny works the same way
|
|
59
|
+
One OpenCode asymmetry: Geneseed shares `opencode.json` with you, so it removes only what it recorded writing. The manifest lists the `permission.bash` gates it added (`bash_gates`), and a rebuild without the process pack, or with `--no-deletion-gate`, takes back those that still read as it wrote them. An entry that was already there, one you changed, and every gate on an install made before 5.2.0 (which has no record) stays and is named in a warning; `--prune-gates` on one build removes the last kind. A `permission.skill` deny works the same way. Uninstall takes back both: every recorded deny and every recorded `permission.bash` gate that still reads as Geneseed wrote it. A gate you changed, and one with no record, stays.
|
|
42
60
|
|
|
43
61
|
In plain terms: [Enforced vs. asked](../understand/enforced-vs-asked.md).
|
|
@@ -15,7 +15,7 @@ committed or counted against a ring budget while it waits.
|
|
|
15
15
|
|
|
16
16
|
A [factory](factories.md) stage holds the same way, answered with `geneseed factory decide`.
|
|
17
17
|
Three shipped bricks do: `intake` (holds on `needs-info` — it has questions only you can
|
|
18
|
-
answer), `checks` (holds on `error` — the branch changed a locked path — and on `none` — the
|
|
18
|
+
answer — and on `reject` — it refuses the item as already done, a duplicate or against a rule), `checks` (holds on `error` — the branch changed a locked path — and on `none` — the
|
|
19
19
|
base branch has no done list yet) and `merge-gate` (holds on `none` — the repo runs no CI on the
|
|
20
20
|
PR).
|
|
21
21
|
|
package/docs/concepts/loops.md
CHANGED
|
@@ -83,7 +83,7 @@ evidence was never wired — no verdict is not a failure to repair.
|
|
|
83
83
|
## Not foreman mode
|
|
84
84
|
|
|
85
85
|
A loop and a [foreman-mode](foreman-mode.md) pipeline are both "hand work off and keep going," but
|
|
86
|
-
they solve different problems. A pipeline is a one-shot crew for a single task
|
|
87
|
-
you accept it. A loop is a long-running, self-scoring state machine that commits each validated
|
|
86
|
+
they solve different problems. A pipeline is a one-shot crew for a single task; it commits only on its
|
|
87
|
+
own branch, and nothing lands beyond it until you accept it. A loop is a long-running, self-scoring state machine that commits each validated
|
|
88
88
|
iteration on its own branch as it goes, and only stops for a person when the risk crosses a
|
|
89
89
|
threshold.
|
|
@@ -36,7 +36,7 @@ The same folder already held the install registry, your own loop bricks and temp
|
|
|
36
36
|
| `PROFILE.md`, `geneseed-wiki.jsonc` | Whole file. A host file that is no longer its seed replaces the shared one. `$GENESEED_WIKI` overrides both |
|
|
37
37
|
| `excludes.json` | A global install reads the union of the shared list and its own |
|
|
38
38
|
|
|
39
|
-
When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
|
|
39
|
+
When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. In `user-rules.md`, the seed's explanation above the first `## R<n>` rule is skipped too while it is unchanged: only the rules are sent. Text you wrote above the rules, or an edited explanation, is sent as it is. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
|
|
40
40
|
|
|
41
41
|
A global install's text names these locations as absolute paths. A project install keeps its relative paths and its own `memory/`. Geneseed grants no directory permission for the tier, so an agent write there follows your host's permission mode, as a write to the host's own folder does. A write to the shared rules or draft passes the same [rule gate](hooks.md) as a local one; the shared memory, like a local one, is written freely.
|
|
42
42
|
|