geneseed 5.3.0 → 5.4.0
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 +95 -0
- package/README.md +23 -20
- package/SHIPPED.md +7 -7
- 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/README.md +3 -2
- package/adapters/opencode/plugins/geneseed-activity.js +20 -21
- package/adapters/opencode/plugins/geneseed-context.js +175 -62
- package/adapters/opencode/plugins/geneseed-guard.js +419 -205
- package/adapters/opencode/plugins/geneseed-workflow.js +3 -2
- package/adapters/opencode/workflows/_runtime.js +3 -2
- package/bin/geneseed-cli.mjs +7 -0
- package/bin/geneseed-hook.mjs +59 -11
- package/docs/PRD.md +1 -1
- package/docs/README.md +1 -0
- package/docs/concepts/agents.md +1 -1
- package/docs/concepts/collaboration.md +2 -2
- package/docs/concepts/enforcement-table.md +5 -2
- package/docs/concepts/exclusions.md +18 -4
- package/docs/concepts/footprint.md +11 -1
- package/docs/concepts/foreman-mode.md +1 -1
- package/docs/concepts/hook-gates.md +5 -5
- package/docs/concepts/hooks.md +4 -3
- package/docs/concepts/host-matrix.md +24 -6
- package/docs/concepts/kits.md +12 -2
- package/docs/concepts/loop-bricks.md +3 -3
- package/docs/concepts/loops.md +6 -4
- package/docs/concepts/ownership.md +1 -1
- package/docs/concepts/rules.md +2 -2
- package/docs/concepts/skills.md +1 -1
- package/docs/design-history.md +8 -0
- package/docs/extending.md +112 -35
- package/docs/guides/auto-merge.md +100 -0
- package/docs/guides/choose-your-setup.md +1 -1
- package/docs/guides/headless.md +1 -1
- package/docs/guides/install-bob.md +2 -2
- package/docs/guides/install-clone.md +1 -1
- package/docs/guides/install-openclaude.md +1 -1
- package/docs/guides/install.md +1 -1
- package/docs/guides/loop-finish.md +3 -3
- package/docs/guides/loop-running.md +4 -4
- package/docs/guides/project-context.md +1 -1
- package/docs/guides/run-a-factory.md +2 -2
- package/docs/guides/setup-doctrines.md +2 -2
- package/docs/guides/setup-footprint.md +1 -1
- package/docs/guides/uninstall.md +3 -3
- package/docs/guides/upgrade.md +1 -1
- package/docs/guides/verify.md +12 -0
- package/docs/guides/worktree.md +1 -1
- package/docs/reference/environment.md +5 -2
- package/docs/reference/plugin-activity.md +1 -1
- package/docs/reference/plugin-guard.md +1 -1
- package/docs/reference/plugin-learn.md +1 -1
- package/docs/reference/plugin-workflow.md +1 -1
- package/docs/reference/troubleshoot-doctor.md +2 -2
- package/docs/reference/troubleshoot-hooks.md +2 -2
- package/docs/reference/troubleshoot-install.md +3 -3
- package/docs/reference/troubleshoot-tools.md +1 -1
- package/docs/token-footprint.md +68 -4
- 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 +2 -2
- package/docs/understand/machine-bob.md +1 -1
- package/docs/understand/machine-claude.md +2 -2
- package/docs/understand/on-your-machine.md +1 -1
- package/docs/web-ui.md +10 -5
- package/harness.config.json +1 -1
- package/js/README.md +5 -3
- package/js/build/args.mjs +13 -2
- package/js/build/driver.mjs +34 -7
- package/js/build/emit-claude.mjs +9 -5
- package/js/build/emit-opencode.mjs +13 -9
- package/js/build/generate.mjs +10 -165
- package/js/build/profile.mjs +318 -0
- package/js/build/render.mjs +81 -3
- package/js/build/retired-skills.mjs +60 -13
- package/js/build/source.mjs +15 -1
- package/js/build/stubs.mjs +4 -1
- package/js/cli-table.json +48 -3
- 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 +4 -2
- package/js/hosts/hooks-done.mjs +345 -55
- package/js/hosts/hooks-learn.mjs +51 -19
- package/js/hosts/hooks-prims.mjs +5 -3
- package/js/hosts/hooks.mjs +172 -19
- package/js/hosts/hosts.mjs +80 -12
- package/js/hosts/installs.mjs +26 -1
- package/js/hosts/native.mjs +33 -7
- package/js/hosts/owned.mjs +7 -6
- package/js/hosts/ownership-gate.mjs +14 -1
- package/js/hosts/settings.mjs +273 -105
- package/js/hosts/shim.mjs +4 -4
- package/js/hosts/usage.mjs +9 -3
- package/js/inspect/checks-constitution.mjs +32 -0
- 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 +21 -3
- package/js/inspect/doctor.mjs +6 -1
- package/js/inspect/inventory.mjs +1 -1
- package/js/lib/machine-dir.mjs +1 -1
- package/js/lib/node-floor.mjs +46 -6
- package/js/maintain/setup.mjs +5 -1
- package/js/maintain/uninstall.mjs +42 -16
- package/js/maintain/update.mjs +4 -2
- package/js/web/actions.mjs +17 -12
- package/js/web/api.mjs +7 -2
- package/package.json +1 -1
- package/registry.json +14 -0
- package/src/AGENT.md.tmpl +15 -17
- package/src/bricks/pr-open.md +3 -2
- package/src/doctrines/ops.md +2 -2
- package/src/doctrines/process.md +40 -36
- package/src/factories/analysis-to-build.json +1 -1
- package/src/factories/bug-report-to-fix.json +1 -1
- package/src/factories/issue-to-pr.json +1 -1
- package/src/kits/terminal-tools/rules.md +10 -0
- package/src/kits/terminal-tools.json +13 -0
- package/src/licenses/herdr.txt +201 -0
- package/src/modes/foreman.md +6 -3
- package/src/skills/_self-improvement.md +9 -7
- package/src/skills/commit.md +17 -17
- package/src/skills/debug/ci.md +1 -1
- package/src/skills/dependencies.md +3 -3
- package/src/skills/document-project.md +3 -2
- package/src/skills/factory.md +13 -4
- package/src/skills/geneseed.md +4 -2
- package/src/skills/git-history.md +5 -7
- package/src/skills/herdr.md +135 -0
- package/src/skills/loop.md +3 -2
- package/src/skills/opencode-cli.md +84 -0
- package/src/skills/pipeline.md +1 -1
- package/src/skills/release.md +5 -8
- package/src/skills/review-response.md +4 -2
- package/src/skills/rule.md +27 -1
- package/src/skills/ship.md +54 -7
- package/src/skills/worktree.md +2 -2
- package/src/upstreams.json +7 -0
- package/themes/_TEMPLATE.json +2 -0
- package/themes/biker.json +2 -0
- package/themes/commentator.json +2 -0
- package/themes/cyberpunk.json +2 -0
- package/themes/gamer.json +2 -0
- package/themes/imperial.json +2 -0
- package/themes/joker.json +2 -0
- package/themes/marvin.json +2 -0
- package/themes/mean.json +2 -0
- package/themes/military.json +2 -0
- package/themes/neutral.json +2 -0
- package/themes/pirate.json +2 -0
- package/themes/sports.json +2 -0
- package/themes/verstappen.json +2 -0
- package/themes/wizard.json +2 -0
- package/web/dist/assets/Activity-D2kOc3yi.js +1 -0
- package/web/dist/assets/ActivityDetail-By3xOr21.js +1 -0
- package/web/dist/assets/{Bonsai-Bfpb6W-1.js → Bonsai-CBWDTBA4.js} +1 -1
- package/web/dist/assets/{CopyButton-ByIntFtB.js → CopyButton-BVbpriMB.js} +1 -1
- package/web/dist/assets/Dashboard-CIJLPHM9.js +2 -0
- package/web/dist/assets/{Docs-DvlMJhpu.js → Docs-CiRRIELs.js} +3 -3
- package/web/dist/assets/Factories-DhyK0O8d.js +1 -0
- package/web/dist/assets/GreenhouseView-DW3PgTPy.js +1 -0
- package/web/dist/assets/Installs-B6nlo-Ly.js +3 -0
- package/web/dist/assets/JournalView-O65qEWfp.js +1 -0
- package/web/dist/assets/Kits-C5U-yT6Z.js +1 -0
- package/web/dist/assets/Laws-CuTw_XNf.js +4 -0
- package/web/dist/assets/{LibRows-DEHjIoD-.js → LibRows-D6-CVa3K.js} +1 -1
- package/web/dist/assets/Library-CzPlerd6.js +3 -0
- package/web/dist/assets/Loops-CqNF_-nS.js +2 -0
- package/web/dist/assets/Markdown-CxkA7940.js +71 -0
- package/web/dist/assets/OperatorHudView-BNr8K5qj.js +1 -0
- package/web/dist/assets/Personal-DeDb9e8O.js +2 -0
- package/web/dist/assets/Settings-B8MPN_AD.js +1 -0
- package/web/dist/assets/{Tabs-CWeQTADL.js → Tabs-DJzAez4h.js} +1 -1
- package/web/dist/assets/index-BL3P-9Rg.js +6 -0
- package/web/dist/assets/{index-CsAZq0BQ.css → index-CRWqKxfY.css} +1 -1
- package/web/dist/index.html +2 -2
- package/adapters/claude-code/settings.json +0 -52
- package/web/dist/assets/Activity-CqJiquEq.js +0 -1
- package/web/dist/assets/ActivityDetail-BSzevynX.js +0 -1
- package/web/dist/assets/Dashboard-DBOEi9lQ.js +0 -2
- package/web/dist/assets/Factories-Bpvv7L2H.js +0 -1
- package/web/dist/assets/GreenhouseView-GpBsYn50.js +0 -1
- package/web/dist/assets/Installs-BlGmVrFK.js +0 -3
- package/web/dist/assets/JournalView-iLuLrOxE.js +0 -1
- package/web/dist/assets/Kits-DRwpxC-J.js +0 -1
- package/web/dist/assets/Laws-CZkiNOWQ.js +0 -4
- package/web/dist/assets/Library-B4K-1iNF.js +0 -3
- package/web/dist/assets/Loops-BWSzaW8E.js +0 -2
- package/web/dist/assets/Markdown-0ORz7tAc.js +0 -69
- package/web/dist/assets/OperatorHudView-BAXwCEvY.js +0 -1
- package/web/dist/assets/Personal-Bp9nV4GR.js +0 -2
- package/web/dist/assets/Settings-CWWuaIp-.js +0 -1
- package/web/dist/assets/index-How7SzDZ.js +0 -6
|
@@ -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
|
@@ -387,6 +387,13 @@ async function main(argv) {
|
|
|
387
387
|
// A hook verb (`context`, `tool-gate`, …) is in the table but not here: the emitted
|
|
388
388
|
// settings call it through `geneseed-hook`, and saying so beats "unknown command".
|
|
389
389
|
if (cliCommand(verb) !== null) {
|
|
390
|
+
// Its help is a fair question, and `help context` arrives here as `context --help`: answer
|
|
391
|
+
// it with the hook binary's own help, under a line naming the binary that runs it.
|
|
392
|
+
if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
|
|
393
|
+
printOut(`'${verb}' is a hook verb: the host runs it as \`geneseed-hook ${verb}\` `
|
|
394
|
+
+ '(bin/geneseed-hook.mjs), not through this command.\n\n');
|
|
395
|
+
return printHelp('geneseed-hook', verb);
|
|
396
|
+
}
|
|
390
397
|
return die(2, `'${verb}' is a hook verb: the host runs it through geneseed-hook `
|
|
391
398
|
+ '(bin/geneseed-hook.mjs), not this command. See geneseed --help.');
|
|
392
399
|
}
|
package/bin/geneseed-hook.mjs
CHANGED
|
@@ -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 },
|
|
@@ -81,7 +82,7 @@ const VERBS = {
|
|
|
81
82
|
flags: HOSTED,
|
|
82
83
|
switches: {
|
|
83
84
|
'--no-consent': 'noConsent', '--no-deletion-gate': 'noDeletionGate', '--no-external-gate': 'noExternalGate',
|
|
84
|
-
'--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
|
|
85
|
+
'--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan', '--strict-consent': 'strictConsent',
|
|
85
86
|
},
|
|
86
87
|
},
|
|
87
88
|
'rule-gate': {
|
|
@@ -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', '--strict-consent': 'strictConsent',
|
|
104
107
|
},
|
|
105
108
|
},
|
|
106
109
|
learn: {
|
|
@@ -163,6 +166,21 @@ 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
|
+
|
|
166
184
|
/**
|
|
167
185
|
* A verb whose module failed to load, or threw past its own guard. `guardGate` only covers a gate
|
|
168
186
|
* once its module has loaded; a module that cannot (a file missing mid-`git pull` under the shared
|
|
@@ -199,6 +217,20 @@ function die(code, msg) {
|
|
|
199
217
|
return code;
|
|
200
218
|
}
|
|
201
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
|
+
|
|
202
234
|
/**
|
|
203
235
|
* `argparse`'s surface for these verbs, and only theirs: `--flag VALUE`, the
|
|
204
236
|
* `--flag=VALUE` spelling it also accepts, store_true switches, and one optional
|
|
@@ -206,7 +238,7 @@ function die(code, msg) {
|
|
|
206
238
|
*/
|
|
207
239
|
function parse(spec, argv) {
|
|
208
240
|
const args = {
|
|
209
|
-
root: null, host: null, event: null, memory: null, consolidate: false, noConsent: false,
|
|
241
|
+
root: null, host: null, event: null, memory: null, consolidate: false, noConsent: false, strictConsent: false,
|
|
210
242
|
noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false,
|
|
211
243
|
noExternalGate: false, noTestNote: false, noRuleStore: false, noRootScan: false, file: null,
|
|
212
244
|
};
|
|
@@ -278,11 +310,20 @@ async function main(argv) {
|
|
|
278
310
|
const parsed = parse(spec, argv.slice(1));
|
|
279
311
|
if (parsed.error) {
|
|
280
312
|
// A gate verb must never exit 2 on an argv error: that is indistinguishable, to Claude's
|
|
281
|
-
// PreToolUse, from the gate deliberately blocking (see I3/B1 above).
|
|
282
|
-
//
|
|
283
|
-
//
|
|
284
|
-
// `
|
|
285
|
-
|
|
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') {
|
|
286
327
|
printErr(`geneseed-hook: error: ${parsed.error}\n`);
|
|
287
328
|
return 0;
|
|
288
329
|
}
|
|
@@ -296,8 +337,14 @@ async function main(argv) {
|
|
|
296
337
|
// `context` answers SessionStart and SubagentStart (settings.mjs), told apart by the payload's
|
|
297
338
|
// event name. Read here, not in the verb, so an in-process caller never blocks on fd 0; the read
|
|
298
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`).
|
|
299
342
|
if (verb === 'context' && !isatty(0)) {
|
|
300
|
-
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 */ }
|
|
301
348
|
}
|
|
302
349
|
let rc;
|
|
303
350
|
try {
|
|
@@ -307,6 +354,7 @@ async function main(argv) {
|
|
|
307
354
|
}
|
|
308
355
|
await trackActivity(verb, parsed.args);
|
|
309
356
|
await baselineStores(verb, parsed.args);
|
|
357
|
+
if (process.env.GENESEED_HOOK_TAP) await tapHook(verb, parsed.args);
|
|
310
358
|
return rc;
|
|
311
359
|
}
|
|
312
360
|
|
package/docs/PRD.md
CHANGED
|
@@ -104,7 +104,7 @@ sequenceDiagram
|
|
|
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
106
|
| NFR-004 | The rules file stays within its size ceiling. | 40 312 lean, 66 432 full | `CARRIER_CEILING` | ✅ | `js/inspect/cost.mjs` |
|
|
107
|
-
| NFR-005 | The generator and hook path cannot spawn beyond what is declared. | No `child_process` on the generator;
|
|
107
|
+
| NFR-005 | The generator and hook path cannot spawn beyond what is declared. | No `child_process` on the generator; two spawn sites on the hook path (`learn`'s model CLI, `loss.mjs`'s one `git` read) | 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` |
|
|
110
110
|
| NFR-008 | Runs on Windows, macOS and Linux with no build step. | CI: Ubuntu and Windows. macOS: `⚠ to confirm`, no CI row | `web/dist/` tracked; `install`, `install.cmd`, `install.command` | ◐ | `.github/workflows/ci.yml` |
|
package/docs/README.md
CHANGED
|
@@ -30,6 +30,7 @@
|
|
|
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
32
|
| Factories | [Run a factory](guides/run-a-factory.md) | Carrying one bug report or issue to an open PR with green CI |
|
|
33
|
+
| Factories | [Auto-merge green PRs](guides/auto-merge.md) | Letting the forge merge a PR the agent opens once its required checks pass |
|
|
33
34
|
| Keep it running | [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
|
|
34
35
|
| 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 |
|
|
35
36
|
| Keep it running | [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
|
package/docs/concepts/agents.md
CHANGED
|
@@ -36,7 +36,7 @@ Ten read-only debaters — `advocate`, `skeptic`, `pragmatist`, `steward`, `oper
|
|
|
36
36
|
|
|
37
37
|
An agent is picked by **what the work needs**, not by **where the file lives**. There is no "agent for `src/api/`": a change to any folder goes to the `developer`, and its review to the `reviewer`. You can name one ("have the reviewer look at this"), or let the main session route the request to the right specialist itself.
|
|
38
38
|
|
|
39
|
-
In [foreman mode](foreman-mode.md) the session
|
|
39
|
+
In [foreman mode](foreman-mode.md) the session hands each task that would block it to one background `developer` worker. A pipeline crew — explorer, developer and tester, plus whatever specialists the task needs — runs only when you ask for one.
|
|
40
40
|
|
|
41
41
|
### Agents learn too
|
|
42
42
|
|
|
@@ -22,7 +22,7 @@ A **posture** is the register the agent works in. You choose it at setup and it
|
|
|
22
22
|
| **assistant** | precise execution, low initiative — you steer |
|
|
23
23
|
| **artisan** | a peer with toolsmith reflexes — terminal-first, automates repetition |
|
|
24
24
|
|
|
25
|
-
Posture is separate from the [theme](themes.md): the theme is the *voice*, the posture is the *relationship*. Every posture obeys the same rules; what shifts is how firmly and how loudly the agent voices disagreement. Change it with `geneseed setup`, the web console's
|
|
25
|
+
Posture is separate from the [theme](themes.md): the theme is the *voice*, the posture is the *relationship*. Every posture obeys the same rules; what shifts is how firmly and how loudly the agent voices disagreement. Change it with `geneseed setup`, the install's panel on the web console's Installs page, or:
|
|
26
26
|
|
|
27
27
|
```bash
|
|
28
28
|
geneseed build --emit claude-global --posture mentor
|
|
@@ -38,7 +38,7 @@ The **Pact** is stated in the first section of the Ethos, the layer that is alwa
|
|
|
38
38
|
2. serve your intent;
|
|
39
39
|
3. keep its own honesty.
|
|
40
40
|
|
|
41
|
-
Unusually,
|
|
41
|
+
Unusually, the Pact also has a side that *you* owe back. The install's text only points to it; the README states it:
|
|
42
42
|
|
|
43
43
|
- **Don't punish candour.** When the agent contradicts you with evidence, flags a risk or admits a doubt, that is the Pact working. Penalising it teaches the agent to flatter.
|
|
44
44
|
- **Give the context up front.** The agent cannot weigh what it was not told.
|
|
@@ -24,9 +24,9 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
|
|
|
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
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 (
|
|
27
|
+
| `consent-before-push` | process | ask: git-gate, on a commit or push onto the main branch (`main`, `master`, a remote's default branch, or the branch the main checkout holds when the command runs in a linked worktree). Off the main branch, a session's commit, local merge and plain push of the checked-out branch (`git push [-u] <remote> <branch>`, or `HEAD:<branch>`) pass. A bare `git push`, a push of another branch, a forced push, a tag push, or any form the gate cannot read still asks, and so does everything in a repository with no remote or whose remote has no default branch recorded (`git remote set-head origin --auto`). A sub-agent's push always asks. With `--strict-consent` (the *Strict consent* switch on the console's Constitution page), every commit and push asks again, as before 2026-11. 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,
|
|
29
|
+
| `verify-before-asserting` | law | block at Stop, again only after a new edit or a changed background verdict, at most 3 times per continuation and 10 per turn: the done gate in `learn`, at SubagentStop too for a sub-agent's own turn (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)); that its SubagentStop sends `agent_transcript_path` is unverified, and without it a sub-agent's turn is not judged | 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
|
|
@@ -45,6 +45,9 @@ not a boundary:** `bash -c`, `pwsh -c`, an interpreter and a variable stay unrea
|
|
|
45
45
|
command permission is the backstop, and the [change report](hooks.md#the-change-report) tells you
|
|
46
46
|
afterwards.
|
|
47
47
|
|
|
48
|
+
No host gates a forge merge (`gh pr merge`, `glab mr merge`, an MCP merge tool): the
|
|
49
|
+
[auto-merge guide](../guides/auto-merge.md) says what guards it instead.
|
|
50
|
+
|
|
48
51
|
See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) for why a gate that only
|
|
49
52
|
one host can run still ships for every host it can.
|
|
50
53
|
|
|
@@ -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
|
|
|
@@ -58,11 +58,13 @@ geneseed build --emit claude-global --exclude-rules "process 7"
|
|
|
58
58
|
|
|
59
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, the rebuild prints a WARN, drops that address, and goes on. The WARN says what the exclusion no longer does: comms 5 (*Mark the Ask*) merged into comms 1 on 2026-11-08, so excluding `comms 5` no longer removes the ask markers, which now bind inside comms 1. If a new rule later takes a retired rule's address, an old exclusion of that address removes the new rule; the build then prints a loud WARN that names both rules, and the exclusion still applies until you remove it. The always-on Rules and the Ethos cannot be excluded.
|
|
60
60
|
|
|
61
|
+
**Its citations go with it.** The instructions file stops citing an excluded rule: a parenthetical such as `(*Consent Before Push*)` after a sentence is removed, and in a list of citations only that name goes. A mention in running prose ("Where *Search Before Creating* refuses …") stays, because it describes a relation and binds nothing. The rule files on disk keep every citation, because they are the complete text. `geneseed doctor` refuses a parenthetical in the instructions-file sources that mixes a doctrine citation with other words, because the render could not remove it cleanly.
|
|
62
|
+
|
|
61
63
|
**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
64
|
|
|
63
65
|
| Rule | What stops | Flag |
|
|
64
66
|
| --- | --- | --- |
|
|
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` |
|
|
67
|
+
| process 5, *Consent Before Push* | the main-branch commit/push ask of `git-gate` (every commit and push under `--strict-consent`) and OpenCode's `git commit*`/`git push*` keys. Bob keeps its warning line | `--no-consent` |
|
|
66
68
|
| 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
69
|
| ops 2, *Commands Must Return* | the root-scan check of `git-gate`, Bob's `tool-gate` and the OpenCode guard | `--no-root-scan` |
|
|
68
70
|
|
|
@@ -95,7 +97,7 @@ What stops asking, per host: the real-loss check of `git-gate` (Claude Code, Ope
|
|
|
95
97
|
Limits:
|
|
96
98
|
- **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
99
|
- **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.
|
|
100
|
+
- **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
101
|
- **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
102
|
|
|
101
103
|
### Law I secrets gate and Law III done gate — on or off
|
|
@@ -111,10 +113,22 @@ The console's Constitution page has a switch on Rule I's and Rule III's rows too
|
|
|
111
113
|
|
|
112
114
|
What stops, per host:
|
|
113
115
|
- **`--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.
|
|
114
|
-
- **`--no-done-gate`**: the done check `learn` runs on Stop, listed or inferred (Claude Code, OpenClaude; on Bob, the "turn not judged" log line), and on OpenCode the context plugin's reminder (OpenCode 1), its one-line notice (OpenCode 2), and on every host the `Done gate:` line at session start. Learning itself still runs, and `.geneseed/done-checks.txt` stays protected by *External Gate*.
|
|
116
|
+
- **`--no-done-gate`**: the done check `learn` runs on Stop and SubagentStop, listed or inferred (Claude Code, OpenClaude; on Bob, the "turn not judged" log line), and on OpenCode the context plugin's reminder (OpenCode 1), its one-line notice (OpenCode 2), and on every host the `Done gate:` line at session start. Learning itself still runs, and `.geneseed/done-checks.txt` stays protected by *External Gate*.
|
|
115
117
|
|
|
116
118
|
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.
|
|
117
119
|
|
|
120
|
+
### Strict consent — every commit and push asks
|
|
121
|
+
|
|
122
|
+
By default *Consent Before Push* asks only for a commit or push onto the main branch: your own branch takes commits, local merges and plain pushes without a prompt. Strict consent brings back the ask on every commit and push.
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
geneseed build --emit claude-global --strict-consent
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The console's Constitution page has the same switch on the rule's row (*Strict consent*). The install records `Own-branch pass: off` beside the other gate markers, the carrier adds one sentence under the rule, and rebuilds, upgrades and `geneseed status` carry it. The switch adds asks, so its flag does not read `--no-*`; the marker still follows the gate-switch contract: written only when the pass is off.
|
|
129
|
+
|
|
130
|
+
What changes, per host: `git-gate` on Claude Code and OpenClaude asks for every commit and push again (the `loop/*` and Foreman worker passes stay), and Bob's `tool-gate` prints its warning line for each. OpenCode is unchanged: its `git commit*`/`git push*` keys already ask for every one. With process 5 excluded, the switch does nothing, because no consent check runs.
|
|
131
|
+
|
|
118
132
|
### External Gate and the test note — on or off
|
|
119
133
|
|
|
120
134
|
Two more switches. Both are armed by default and written only when off, so an armed install does not change.
|
|
@@ -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.
|
|
@@ -49,6 +59,6 @@ Footprint is stored in a `.geneseed-footprint` marker in the install and kept ac
|
|
|
49
59
|
geneseed build --emit claude-global --footprint full
|
|
50
60
|
```
|
|
51
61
|
|
|
52
|
-
On the command line, a flag you leave out takes the generator's default, not the install's current value. `geneseed status --json` shows
|
|
62
|
+
On the command line, a flag you leave out takes the generator's default, not the install's current value. A build that would change a setting of an existing install that you did not pass refuses: it lists each change and prints the command that keeps them. `geneseed status --json` shows that command for every install. Add `--reset` only to accept the defaults.
|
|
53
63
|
|
|
54
64
|
The walkthrough for all build-time choices is [Choose your setup](../guides/choose-your-setup.md).
|
|
@@ -76,7 +76,7 @@ A worker or crew commits only in its own worktree, never pushes, and never merge
|
|
|
76
76
|
2. shows you the diff from the base it recorded, and the green output;
|
|
77
77
|
3. commits and merges **only once you accept**.
|
|
78
78
|
|
|
79
|
-
Push, and every merge beyond a worker's own branch, belong to the session alone, under *Consent Before Push
|
|
79
|
+
Push, and every merge beyond a worker's own branch, belong to the session alone, under *Consent Before Push*: the session pushes the worker's branch and lands it on the main branch through a pull request with green checks ([Rules](rules.md)). A worker or crew that cannot get to green reports back instead of landing broken work.
|
|
80
80
|
|
|
81
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.
|
|
82
82
|
|
|
@@ -10,7 +10,7 @@ How Geneseed's [hooks](hooks.md) behave when something goes wrong, where they ar
|
|
|
10
10
|
|
|
11
11
|
## Gates fail closed, and leave a trace
|
|
12
12
|
|
|
13
|
-
If a gate cannot evaluate a call — an unreadable payload, a bug — it asks, with the error as its reason, rather than silently letting the call through. Every prompt a gate raises adds one line to `notebook/gates.jsonl` in the install: the rule and the
|
|
13
|
+
If a gate cannot evaluate a call — an unreadable payload, a bug — it asks, with the error as its reason, rather than silently letting the call through. Every prompt a gate raises adds one line to `notebook/gates.jsonl` in the install: the time, the verb, the rule and the working directory, never the command or content. `geneseed status` counts them by rule.
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
geneseed status
|
|
@@ -34,14 +34,14 @@ The merge is surgical. Every other key and every hook of your own survive, and t
|
|
|
34
34
|
|
|
35
35
|
**OpenClaude** is a Claude Code fork: it gets the same hooks and the same prompts, unchanged.
|
|
36
36
|
|
|
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
|
|
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 `SubagentStop`. Bob does document a regex matcher on the tool name, but Geneseed wires none: Bob's tool list and regex dialect are unverified, and a wrong matcher would silence the gate. 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.
|
|
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. (On Claude Code and OpenClaude the same verb only counts skill and subagent calls: see [Hooks](hooks.md).) 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
|
|
package/docs/concepts/hooks.md
CHANGED
|
@@ -17,8 +17,9 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
|
|
|
17
17
|
| Event | When | Command | What it does | Conditional? |
|
|
18
18
|
| --- | --- | --- | --- | --- |
|
|
19
19
|
| `SessionStart` | `startup`, `resume`, `clear`, `compact`, `fork` | `geneseed-hook context` | injects your harness files and the repo's docs, or re-injects them after a resume, a fork, or an auto-compaction summarised them away | no |
|
|
20
|
-
| `PreToolUse` | `Bash`, `PowerShell` | `geneseed-hook git-gate` | asks before a command that would really lose data, and before a recursive scan of a whole filesystem; asks before every commit and push | the commit/push question only |
|
|
20
|
+
| `PreToolUse` | `Bash`, `PowerShell`, `Monitor` | `geneseed-hook git-gate` | asks before a command that would really lose data, and before a recursive scan of a whole filesystem; asks before every commit and push | the commit/push question only |
|
|
21
21
|
| `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your standing rules; stops the session's first write once in an application repo with no `## Ownership` section | no |
|
|
22
|
+
| `PreToolUse` | `Skill`, `Agent`, `Task` | `geneseed-hook tool-gate` | records the skill or subagent call in the usage count; judges nothing and never blocks | no |
|
|
22
23
|
| `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into the memory store | needs `GENESEED_LLM` |
|
|
23
24
|
| `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in the store's `agents/<name>.md` | needs `GENESEED_LLM` |
|
|
24
25
|
| `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
|
|
@@ -53,7 +54,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
|
|
|
53
54
|
- removing files (`rm`, `rmdir`, `del`, `erase`, `Remove-Item`) that git cannot restore: untracked, ignored or modified files, a repository's `.git`, or anything outside a repository.
|
|
54
55
|
|
|
55
56
|
A force push to a feature branch, the protected-branch-only forms above on a feature branch, a new branch (`checkout -b`, `switch -c`), `reset --hard` over uncommitted work or to a commit that keeps every unpushed one, `branch -D` of a pushed branch, or `rm` of a tracked, unmodified file passes. When the gate cannot tell — a glob or `$variable` it would have to expand, a `cd` it cannot follow, `sh -c`/`xargs`, git failing or missing — it asks, and says it could not verify. To read the state it runs `git` itself, only once a command already looked destructive; every other command pays nothing. That is a Rule, so it holds in every build — unless you switch its gate off for one install with `--no-deletion-gate` (or the switch on Rule IV in the console's Constitution page). The hook is then wired with `--no-deletion-gate` and this check stands down; the Rule's text still binds the agent, and the catastrophic-command check above and the root-scan and consent checks below still run ([Exclusions](exclusions.md)).
|
|
56
|
-
- **
|
|
57
|
+
- **A `git commit` or `git push` onto the main branch** gets a prompt citing *Consent Before Push*: the main branch changes only through a pull request with green checks. The main branch is `main`, `master`, a remote's default branch, or, in a linked worktree, the branch the main checkout holds. On any other branch, a commit, a local merge and a plain push of the checked-out branch (`git push -u origin feature`, `git push origin HEAD:feature`) pass. A bare `git push` (where `push.default` and your git config decide the target), a push of a branch other than the checked-out one, a forced push, a tag push, a sub-agent's push, or a command the gate cannot read still asks. A quoted message is data: `git commit -m "fix(hooks): x"` passes, and so does a bash `git commit -F - <<'EOF'` heredoc whose delimiter is quoted; a `$(` or a backtick inside double quotes still asks. In a repository with no remote, or with a remote whose default branch is not recorded (`git remote add` records none; `git remote set-head origin --auto` does), the gate cannot tell your branch from the default one, so every commit and push asks. Build with `--strict-consent` (or turn on *Strict consent* on the console's Constitution page) and every commit and push asks again. This part belongs to the **process** doctrine pack: build without it, or exclude that rule, and the hook stays wired with `--no-consent` — commits and pushes go through without asking, real data loss is still stopped ([Rules](rules.md)).
|
|
57
58
|
- **A recursive scan of a whole filesystem** — `find /`, `du -sh /`, `grep -r foo /`, `rg x C:\`, `Get-ChildItem C:\ -Recurse` — gets a prompt citing *Commands Must Return* (on Bob, it is blocked). In Git Bash `/` mounts every drive and mounted share, so such a scan runs for hours, and `| head` does not stop it. The prompt tells the agent to search a specific directory instead. A deeper path (`find /c/Users/me/project`), `ls /` without `-R` (`ls -r` is reverse order, not recursion), a quoted argument (a search pattern such as `grep -rn "/" src`), a `#` comment, and the remote half of an `ssh` command pass. It belongs to the **ops** pack: build without it, or exclude that rule, and the hook is wired with `--no-root-scan` and this check stands down (also on Bob and in the OpenCode guard); every other check stays ([Exclusions](exclusions.md)).
|
|
58
59
|
- **A shell write to a protected check or a gate's own configuration** gets the same *External Gate* prompt as a write tool (see rule-gate below; on Bob, it is blocked). `--no-consent` does not touch it.
|
|
59
60
|
- Any other command passes untouched.
|
|
@@ -75,7 +76,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
|
|
|
75
76
|
- An edit that weakens a test gets a note to the agent, citing *Cure the Cause*. It is **advisory**: it asks nothing and blocks nothing. An install built `--no-test-note` gets no note, here or at turn end ([Exclusions](exclusions.md)). A test file has a path segment `test`, `tests`, `__tests__` or `spec`, or a name `*.test.*`, `*.spec.*`, `*_test.*` or `test_*`. The edit weakens it when it adds `.skip(`, `xit(`, `xfail`, `@Disabled`, `@Ignore`, `pytest.mark.skip` or `t.Skip(`, or when it removes an assertion line and adds no other. The done gate repeats it to you when the turn ends. On Bob the note is a line in the hook log. On OpenCode it is one reminder on the next request.
|
|
76
77
|
- Ordinary edits pass untouched.
|
|
77
78
|
|
|
78
|
-
**The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**, and they stay advisory, with no date: only a list the project wrote can block. A turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test`. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. The gate never runs a check itself. It reads the transcript from its end, back only to the prompt that
|
|
79
|
+
**The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**, and they stay advisory, with no date: only a list the project wrote can block. A turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test --test-reporter=tap "tests/**/*.test.mjs"`. A listed line matches as a prefix of the command: `node --test` listed would accept `node --test tests/one.test.mjs`, one file of the suite, so list each command whole. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. A check that runs in the background (Claude Code's `run_in_background`, or a command moved there after its foreground timeout) counts only when its task notification says it completed with exit code 0; the launch alone says only that it started. The gate never runs a check itself. It reads the transcript from its end, back only to the last prompt a person typed: a background task's notification opens no turn, so a turn spans every continuation the notifications drive. Its cost grows with that turn, not with the session; in a long run kept going by notifications it may read back to the start of the file. A sub-agent's turn is judged too, when it stops (SubagentStop): the gate reads the sub-agent's own transcript and judges each project it wrote files in by that project's git root and list, so a worker in its own worktree owes its worktree's checks, not its parent's. A block there keeps the sub-agent working, with the owed checks as its next instruction. An inferred check there is only a stderr line and a ledger entry, since nobody sees a sub-agent's warning. It blocks again only when the agent edited a file since the last block, or when a check's background run changed its verdict (still running, then failed), and at most 3 times per continuation: a stop with neither, or a fourth stop, ends the turn and leaves a `done-gate-cap` line in the gate ledger. A task notification starts a new continuation with a fresh count, so early blocks do not spend the cap for the rest of an unattended run. Over the whole turn, until the next prompt a person types, it blocks at most 10 times: a suite relaunched in the background after each failure would otherwise loop, one full run per cycle. Past that ceiling the turn ends, and the stderr line says the total ceiling was reached. The block names the checks whose background run is still running or reported a failure. The count is kept per session (and per sub-agent) in the install's `notebook/done-gate/`; without an install, the second stop ends the turn. Only file-write tools count as edits: a shell `sed -i` or redirect is not one here. When a turn weakened a test (see the rule gate), the gate adds a line that the agent cannot suppress, `[done-gate] advisory — test weakened this turn: tests/a.test.js (.skip added)`. The line needs no checks and stays out of the ask counts. `--no-done-gate` silences this line and OpenCode's reminder, but not the note the agent gets at edit time on Claude Code, OpenClaude and Bob: the rule gate never receives that flag. A block prints only the block; the line comes at the stop that ends the turn. On OpenCode the gate is a reminder on the next request (OpenCode 1 only), listed or inferred; on Bob, whose Stop carries no transcript, the turn is not judged, and with a listed file a log line says so. An install built `--no-done-gate` wires `learn` with that flag: the check is skipped, learning still runs ([Exclusions](exclusions.md)).
|
|
79
80
|
|
|
80
81
|
**learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries in the memory store: on a global install, the shared one when it exists. It is shown the facts already stored, so it updates one with the merged text rather than writing a twin (the old version is kept in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It needs `GENESEED_LLM` set to a model command, for example:
|
|
81
82
|
|
|
@@ -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² |
|
|
@@ -23,21 +23,39 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
|
|
|
23
23
|
| User-only skills hidden from the model | 🔒 `permission.skill` deny | ✅ `disable-model-invocation` | ✅ `/`-command, no skill | ✅ `disable-model-invocation` |
|
|
24
24
|
| Sovereign-repo exclusions⁵ | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
|
|
25
25
|
| Subagent depth capped at two ([Foreman mode](foreman-mode.md)) | ✅ `subagent_depth` | ✅ `env` setting | ➖ undocumented | ➖ no cap in the host |
|
|
26
|
-
| MCP
|
|
26
|
+
| MCP servers (Geneseed reads and lists them, never writes them) | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
|
|
27
27
|
| Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
|
|
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
|
-
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.
|
|
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)). By default it asks only for a commit or push onto the main branch; `--strict-consent` makes it ask for every one. OpenCode always asks for every commit and push: its permission globs cannot read which branch is checked out. 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).
|
package/docs/concepts/kits.md
CHANGED
|
@@ -54,18 +54,28 @@ The fourth kit is `docker`, for Docker and Compose operations on any stack. It a
|
|
|
54
54
|
|
|
55
55
|
It does not overlap the spring-boot kit's `docker-expert` agent: that agent builds a Spring Boot service's own image (Buildpacks, layered or native) and its local-dev Compose file, and `compose-ops` operates any Compose stack. Either kit works without the other. `compose-ops` is adapted in part from the `docker-patterns` skill of [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT), rewritten for operations; its skill folder ships `LICENSE-everything-claude-code.txt`.
|
|
56
56
|
|
|
57
|
+
The fifth kit is `terminal-tools`, for terminal programs the agent drives through their own CLI. It adds two skills:
|
|
58
|
+
|
|
59
|
+
| Member | Kind | What it is for |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `herdr` | skill | Herdr workspaces, tabs, panes and agents, from inside a Herdr pane (`HERDR_ENV=1`) and only when the user names Herdr: split a sibling pane, start and prompt another agent, wait on state, read output. It carries the Windows notes of herdr's own docs page (signed binaries unsupported, so SmartScreen may warn) |
|
|
62
|
+
| `opencode-cli` | skill | OpenCode V2 from another session: headless `opencode run` (JSON output, model, agent, continue and fork), the background service against `--standalone` and `--server`, `serve` and `pair`, sessions, MCP, plugins, models, stats, debug |
|
|
63
|
+
|
|
64
|
+
Its rules gate each tool on its environment, read live state before acting, close only what the agent opened, never stop the user's server or service, and leave every login and credential to the user. `herdr` is adapted from the official skill of [herdrdev/herdr](https://github.com/herdrdev/herdr) by herdrdev (Apache-2.0), condensed into house format; its skill folder ships `LICENSE-herdr.txt`. `opencode-cli` is first-party and targets OpenCode V2 only, verified against the V2 source at v2.3.0: the V1 commands top-level `export` and `import`, `attach`, `agent create` and `mcp debug` are not in its command table.
|
|
65
|
+
|
|
57
66
|
### Switching kits on and off
|
|
58
67
|
|
|
59
68
|
```bash
|
|
60
69
|
geneseed build --emit claude-global --kits spring-boot
|
|
61
70
|
geneseed build --emit claude-global --kits react,spring-boot
|
|
62
71
|
geneseed build --emit claude-global --kits ci-pipelines,docker
|
|
72
|
+
geneseed build --emit claude-global --kits terminal-tools
|
|
63
73
|
geneseed build --emit claude-global --kits none
|
|
64
74
|
```
|
|
65
75
|
|
|
66
76
|
`--kits` takes a comma-separated list. `none` and an empty value both mean no kits. An unknown kit name is refused with exit code 2, and the error lists the kits this Geneseed ships. `none` is reserved and can never name a kit. The flag's row is in the [CLI reference](../reference/cli.md), under `build`.
|
|
67
77
|
|
|
68
|
-
A build does exactly what its flags say
|
|
78
|
+
A build does exactly what its flags say, so a plain `build` without `--kits` would turn off a kit the install has on. Over an existing install it refuses instead: it names the change (`kits: <k> -> none`) and prints the command that keeps the kit. With `--reset` it goes ahead and first warns: `this install has kit <k>; this build turns it off — pass --kits <k> to keep it`.
|
|
69
79
|
|
|
70
80
|
The setup wizard asks one yes/no question per kit, each defaulting to whether the install has that kit on. It asks them only when at least one kit exists.
|
|
71
81
|
|
|
@@ -73,7 +83,7 @@ The setup wizard asks one yes/no question per kit, each defaulting to whether th
|
|
|
73
83
|
|
|
74
84
|
An install with a kit on records it in its instructions file, under the skill section: `Active kits: spring-boot`. The line is written only when at least one kit is on. A missing line means no kits, so an install built before kits existed reads as having none.
|
|
75
85
|
|
|
76
|
-
`geneseed rebuild-all`, `geneseed update` and `geneseed migrate` read the line back and rebuild with the same kits. `geneseed diff` and the web console read it too, so they compare against or rebuild that same set. `geneseed validate` does not read it: pass `--kits` to dry-run a kit build. A plain `build` does not read it; it
|
|
86
|
+
`geneseed rebuild-all`, `geneseed update` and `geneseed migrate` read the line back and rebuild with the same kits. `geneseed diff` and the web console read it too, so they compare against or rebuild that same set. `geneseed validate` does not read it: pass `--kits` to dry-run a kit build. A plain `build` does not read it; it refuses or warns, as above. If the line names a kit this Geneseed no longer ships, the rebuild drops that kit with a notice and keeps the others. It never fails `rebuild-all`. A retired kit name is never reused for a new kit.
|
|
77
87
|
|
|
78
88
|
`geneseed status` shows `kits: spring-boot` on the install's row, and `status --json` carries the same list.
|
|
79
89
|
|
|
@@ -43,6 +43,6 @@ the repository.
|
|
|
43
43
|
- **`fitness-define`** (`enforce-architecture-rule`) reaches for ArchUnit first on Java — a
|
|
44
44
|
`FreezingArchRule`, whose violation store doubles as the allowlist of today's violations —
|
|
45
45
|
before dependency-cruiser, import-linter, eslint-plugin-boundaries or size-limit elsewhere.
|
|
46
|
-
- **`
|
|
47
|
-
already records consumer contracts, as the check
|
|
48
|
-
|
|
46
|
+
- **`compat-check`** (`update-contract`) treats Pact or Spring Cloud Contract, where the repo
|
|
47
|
+
already records consumer contracts, as the check it runs against each step rather than only
|
|
48
|
+
the consumers' own test suites.
|