geneseed 5.0.0 → 5.0.3
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 +70 -0
- package/README.md +1 -1
- package/SHIPPED.md +1 -1
- package/adapters/claude-code/README.md +6 -4
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +3 -0
- package/adapters/opencode/plugins/geneseed-context.js +13 -2
- package/adapters/opencode/plugins/geneseed-guard.js +595 -74
- package/adapters/opencode/plugins/geneseed-learn.js +1 -1
- package/bin/geneseed-hook.mjs +21 -7
- package/docs/PRD.md +1 -1
- package/docs/concepts/enforcement-table.md +22 -3
- package/docs/concepts/exclusions.md +48 -2
- package/docs/concepts/foreman-mode.md +19 -4
- package/docs/concepts/hook-gates.md +1 -1
- package/docs/concepts/hooks.md +53 -12
- package/docs/concepts/host-matrix.md +4 -3
- package/docs/concepts/hosts.md +1 -1
- package/docs/concepts/kits.md +18 -0
- package/docs/concepts/shared-tier.md +5 -5
- package/docs/concepts/skills.md +1 -1
- package/docs/extending.md +3 -1
- package/docs/guides/autostart.md +27 -3
- package/docs/guides/choose-your-setup.md +1 -1
- package/docs/guides/migrate.md +5 -3
- package/docs/guides/uninstall.md +1 -1
- package/docs/guides/upgrade-to-5.md +6 -4
- package/docs/reference/plugin-context.md +1 -1
- package/docs/reference/plugin-guard.md +24 -5
- package/docs/reference/troubleshoot-doctor.md +2 -2
- package/docs/understand/a-day.md +9 -5
- package/docs/web-ui.md +78 -20
- package/harness.config.json +1 -1
- package/js/README.md +3 -2
- package/js/build/emit-claude.mjs +9 -1
- package/js/build/emit-opencode.mjs +2 -1
- package/js/build/fold.mjs +7 -7
- package/js/build/rule-decide.mjs +273 -0
- package/js/build/source.mjs +9 -3
- package/js/cli-table.json +122 -2
- package/js/hosts/geneseed-dir.mjs +1 -1
- package/js/hosts/hooks-context.mjs +9 -7
- package/js/hosts/hooks-done.mjs +3 -1
- package/js/hosts/hooks-learn.mjs +1 -1
- package/js/hosts/hooks-prims.mjs +270 -0
- package/js/hosts/hooks.mjs +409 -151
- package/js/hosts/hosts.mjs +22 -0
- package/js/hosts/installs.mjs +13 -9
- package/js/hosts/memory-files.mjs +2 -2
- package/js/hosts/settings.mjs +123 -23
- package/js/hosts/shim.mjs +155 -7
- package/js/hosts/store-watch.mjs +41 -14
- package/js/inspect/diff.mjs +2 -1
- package/js/inspect/inventory.mjs +1 -0
- package/js/inspect/registry.mjs +4 -2
- package/js/inspect/validate.mjs +1 -1
- package/js/lib/paths.mjs +13 -0
- package/js/maintain/migrate.mjs +60 -22
- package/js/maintain/uninstall.mjs +5 -1
- package/js/web/actions.mjs +17 -1
- package/js/web/api.mjs +22 -16
- package/js/web/handler.mjs +2 -0
- package/js/web/routes.mjs +9 -4
- package/js/web/update-check.mjs +2 -2
- package/js/web/user-files.mjs +38 -11
- package/package.json +1 -1
- package/registry.json +21 -0
- package/src/AGENT.md.tmpl +17 -21
- package/src/agents/_self-improvement.md +7 -6
- package/src/agents/developer.md +3 -2
- package/src/agents/docker-expert.md +1 -0
- package/src/agents/memory-curator.md +3 -2
- package/src/doctrines/process.md +24 -19
- package/src/kits/ci-pipelines/rules.md +10 -0
- package/src/kits/ci-pipelines.json +14 -0
- package/src/kits/docker/rules.md +11 -0
- package/src/kits/docker.json +12 -0
- package/src/memory/README.md +5 -4
- package/src/modes/foreman.md +23 -10
- package/src/notebook/README.md +1 -1
- package/src/skills/_self-improvement.md +12 -9
- package/src/skills/compose-ops.md +58 -0
- package/src/skills/gitlab-ci.md +51 -0
- package/src/skills/jenkins-pipeline.md +56 -0
- package/src/skills/pipeline.md +2 -2
- package/src/skills/rule/approve.md +11 -5
- package/src/skills/rule.md +26 -19
- package/src/skills/skill-forge.md +24 -6
- package/themes/_TEMPLATE.json +5 -2
- package/themes/biker.json +5 -2
- package/themes/commentator.json +5 -2
- package/themes/cyberpunk.json +5 -2
- package/themes/gamer.json +5 -2
- package/themes/imperial.json +5 -2
- package/themes/joker.json +5 -2
- package/themes/marvin.json +5 -2
- package/themes/mean.json +5 -2
- package/themes/military.json +5 -2
- package/themes/neutral.json +5 -2
- package/themes/pirate.json +5 -2
- package/themes/sports.json +5 -2
- package/themes/verstappen.json +5 -2
- package/themes/wizard.json +5 -2
- package/web/dist/assets/Activity-Ck_Xffpo.js +1 -0
- package/web/dist/assets/ActivityDetail-CBxVS4mU.js +1 -0
- package/web/dist/assets/{Bonsai-B_y20b3i.js → Bonsai-BlOwsvW6.js} +1 -1
- package/web/dist/assets/{CopyButton-CHQte7Ap.js → CopyButton-DFMOIGbe.js} +1 -1
- package/web/dist/assets/Dashboard-BUdUTjbB.js +2 -0
- package/web/dist/assets/{Docs-Dgv_MWfT.js → Docs-D_2Jt6gU.js} +3 -3
- package/web/dist/assets/{GreenhouseView-CSzTMSl_.js → GreenhouseView-WalcX5bp.js} +1 -1
- package/web/dist/assets/Installs-UGiPDMDt.js +3 -0
- package/web/dist/assets/{JournalView-CvRk1-m5.js → JournalView-CZtXQz-v.js} +1 -1
- package/web/dist/assets/Kits-XQHsazCN.js +1 -0
- package/web/dist/assets/Laws-B6A55S-2.js +4 -0
- package/web/dist/assets/Library-D7L0Wdbh.js +3 -0
- package/web/dist/assets/Loops-C0loS73u.js +2 -0
- package/web/dist/assets/{OperatorHudView-DuGz_sTk.js → OperatorHudView-CeDw5qMB.js} +1 -1
- package/web/dist/assets/Personal-PVmGA2-M.js +2 -0
- package/web/dist/assets/{RailCats-AW92uhsX.js → RailCats-BGZnJ6fa.js} +1 -1
- package/web/dist/assets/Settings-DWuxwh4i.js +1 -0
- package/web/dist/assets/Tabs-d2RIRAKT.js +1 -0
- package/web/dist/assets/api-BMFDSXoB.js +1 -0
- package/web/dist/assets/index-BEI5ugYQ.css +1 -0
- package/web/dist/assets/index-BNttaGQb.js +6 -0
- package/web/dist/index.html +3 -3
- package/web/dist/assets/Activity-D8G4eClY.js +0 -1
- package/web/dist/assets/ActivityDetail-BtOBYk3M.js +0 -1
- package/web/dist/assets/Dashboard-B8uXeJZ_.js +0 -2
- package/web/dist/assets/Installs-BDk9lqBI.js +0 -3
- package/web/dist/assets/Kits-CoITzxWM.js +0 -1
- package/web/dist/assets/Laws-Ctf5r9rE.js +0 -3
- package/web/dist/assets/Library-DNwHYVXt.js +0 -3
- package/web/dist/assets/Loops-S85PMQ8m.js +0 -2
- package/web/dist/assets/Personal-afJNwvRS.js +0 -2
- package/web/dist/assets/Settings-CGDFz-6j.js +0 -1
- package/web/dist/assets/Tabs-1qLrnqmn.js +0 -1
- package/web/dist/assets/api-C46vAuqp.js +0 -1
- package/web/dist/assets/index-COTd4TRZ.js +0 -3
- package/web/dist/assets/index-CtorA7uK.css +0 -1
|
@@ -516,7 +516,7 @@ function storeScan(home, found = {}) {
|
|
|
516
516
|
const stamp = (f) => {
|
|
517
517
|
try { const s = statSync(f); if (s.isFile()) found[f] = `${s.size}:${Math.trunc(s.mtimeMs)}` } catch { /* absent */ }
|
|
518
518
|
}
|
|
519
|
-
for (const n of ["user-rules.md", "PROFILE.md", "geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) stamp(path.join(home, n))
|
|
519
|
+
for (const n of ["user-rules.md", "user-rules.draft.md", "PROFILE.md", "geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) stamp(path.join(home, n))
|
|
520
520
|
const walk = (dir) => {
|
|
521
521
|
let items = []
|
|
522
522
|
try { items = readdirSync(dir, { withFileTypes: true }) } catch { return }
|
package/bin/geneseed-hook.mjs
CHANGED
|
@@ -79,13 +79,19 @@ const VERBS = {
|
|
|
79
79
|
load: gates,
|
|
80
80
|
fn: 'cmdGitGate',
|
|
81
81
|
flags: HOSTED,
|
|
82
|
-
switches: {
|
|
82
|
+
switches: {
|
|
83
|
+
'--no-consent': 'noConsent', '--no-deletion-gate': 'noDeletionGate', '--no-external-gate': 'noExternalGate',
|
|
84
|
+
'--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
|
|
85
|
+
},
|
|
83
86
|
},
|
|
84
87
|
'rule-gate': {
|
|
85
88
|
load: gates,
|
|
86
89
|
fn: 'cmdRuleGate',
|
|
87
90
|
flags: HOSTED,
|
|
88
|
-
switches: {
|
|
91
|
+
switches: {
|
|
92
|
+
'--no-secrets-gate': 'noSecretsGate', '--no-ownership-gate': 'noOwnershipGate',
|
|
93
|
+
'--no-external-gate': 'noExternalGate', '--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore',
|
|
94
|
+
},
|
|
89
95
|
},
|
|
90
96
|
'tool-gate': {
|
|
91
97
|
load: gates,
|
|
@@ -93,7 +99,8 @@ const VERBS = {
|
|
|
93
99
|
flags: HOSTED,
|
|
94
100
|
switches: {
|
|
95
101
|
'--no-deletion-gate': 'noDeletionGate', '--no-secrets-gate': 'noSecretsGate',
|
|
96
|
-
'--no-ownership-gate': 'noOwnershipGate',
|
|
102
|
+
'--no-ownership-gate': 'noOwnershipGate', '--no-external-gate': 'noExternalGate',
|
|
103
|
+
'--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
|
|
97
104
|
},
|
|
98
105
|
},
|
|
99
106
|
learn: {
|
|
@@ -101,7 +108,10 @@ const VERBS = {
|
|
|
101
108
|
fn: 'cmdLearn',
|
|
102
109
|
// `--host` only keys the global stand-down's marker (js/hosts/hosts.mjs); learn has no dialect.
|
|
103
110
|
flags: { '--memory': 'memory', '--host': 'host' },
|
|
104
|
-
switches: {
|
|
111
|
+
switches: {
|
|
112
|
+
'--consolidate': 'consolidate', '--no-done-gate': 'noDoneGate', '--no-test-note': 'noTestNote',
|
|
113
|
+
'--no-rule-store': 'noRuleStore',
|
|
114
|
+
},
|
|
105
115
|
positional: 'file',
|
|
106
116
|
},
|
|
107
117
|
// UserPromptSubmit and SessionEnd: no verb runs there, and the activity view needs both.
|
|
@@ -119,7 +129,8 @@ async function baselineStores(verb, args) {
|
|
|
119
129
|
const raw = readStdin();
|
|
120
130
|
if (!raw.includes('session_id')) return;
|
|
121
131
|
const { writeBaseline } = await import('../js/hosts/store-watch.mjs');
|
|
122
|
-
|
|
132
|
+
const { session_id: sid, cwd } = JSON.parse(raw);
|
|
133
|
+
writeBaseline(args.root, sid, cwd);
|
|
123
134
|
} catch { /* see above */ }
|
|
124
135
|
}
|
|
125
136
|
|
|
@@ -165,13 +176,16 @@ function die(code, msg) {
|
|
|
165
176
|
function parse(spec, argv) {
|
|
166
177
|
const args = {
|
|
167
178
|
root: null, host: null, memory: null, consolidate: false, noConsent: false,
|
|
168
|
-
noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false,
|
|
179
|
+
noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false,
|
|
180
|
+
noExternalGate: false, noTestNote: false, noRuleStore: false, noRootScan: false, file: null,
|
|
169
181
|
};
|
|
170
182
|
for (let i = 0; i < argv.length; i += 1) {
|
|
171
183
|
const tok = argv[i];
|
|
172
184
|
const eq = tok.indexOf('=');
|
|
173
185
|
const name = tok.startsWith('--') && eq > 0 ? tok.slice(0, eq) : tok;
|
|
174
|
-
|
|
186
|
+
// Only the bare spelling sets a switch, and only that is emitted. `--no-external-gate=false` must
|
|
187
|
+
// not disarm a gate, and an argv error here would silence the whole verb, so it just does nothing.
|
|
188
|
+
if ((spec.switches || {})[name]) { if (tok === name) args[spec.switches[name]] = true; continue; }
|
|
175
189
|
if ((spec.flags || {})[name]) {
|
|
176
190
|
const value = eq > 0 && tok.startsWith('--') ? tok.slice(eq + 1) : argv[++i];
|
|
177
191
|
if (value === undefined) return { error: `argument ${name}: expected one argument` };
|
package/docs/PRD.md
CHANGED
|
@@ -83,7 +83,7 @@ sequenceDiagram
|
|
|
83
83
|
| FR-005 | OpenCode gets the same behaviour through plugins, on both plugin APIs. | The host loads every plugin | ✅ | `adapters/opencode/plugins/`, `tests/host_canary.mjs` |
|
|
84
84
|
| FR-006 | Global installs share memory, rules, profile, wiki manifest, exclude paths and notes. | Every global install reads the tier; project over host over shared | ✅ | `js/lib/machine-dir.mjs`, `js/hosts/hooks-context.mjs` |
|
|
85
85
|
| FR-007 | A global emit folds existing stores into the tier. | Copies read back before the old store moves; a second run writes nothing | ✅ | `js/build/fold.mjs` |
|
|
86
|
-
| FR-008 | A rule, profile or wiki that needs a decision waits in a draft. | A drafted rule stays in force on its host; only the `rule` skill decides | ✅ | `js/build/fold.mjs`, `src/skills/rule/approve.md` |
|
|
86
|
+
| FR-008 | A rule, profile or wiki that needs a decision waits in a draft. | A drafted rule stays in force on its host; only the `rule` skill or the console's Pending section decides | ✅ | `js/build/fold.mjs`, `js/build/rule-decide.mjs`, `src/skills/rule/approve.md` |
|
|
87
87
|
| FR-009 | A project install may opt in to read the tier. | Off by default; read-only and labelled; cost stated | ✅ | `js/inspect/cost.mjs`, `js/hosts/hooks-context.mjs` |
|
|
88
88
|
| FR-010 | The agent's memory is one fact per file, with a two-level index. | `geneseed memory list`, `rm` archive; `learn` updates and does not duplicate | ✅ | `js/hosts/memory-files.mjs`, `js/maintain/memory.mjs` |
|
|
89
89
|
| FR-011 | A folder can silence every global install. | `geneseed exclude add`; effect on the next tool call | ✅ | `js/inspect/excludes.mjs` |
|
|
@@ -23,11 +23,11 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
|
|
|
23
23
|
|---|---|---|---|---|---|
|
|
24
24
|
| `sealed-secrets` | law | ask: rule-gate (credential-shaped content outside `.env*`). Switchable per install with `--no-secrets-gate` (see [Exclusions](exclusions.md)): this scan stands down on every host, the guard plugin's path block included | same as Claude Code | block: guard plugin (key/credential file path, or vendor-prefixed secret content); warns only on `.env*` | block (exit 2) |
|
|
25
25
|
| `deletion-is-deliberate` | law | ask: git-gate, only on real data loss judged against the repository's state (the list in [Hooks](hooks.md): a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, the reflog pruned, files git cannot restore removed); asks when it cannot verify. Switchable per install with `--no-deletion-gate` (see [Exclusions](exclusions.md)): the real-loss check and the Law IV `permission.bash` keys stand down, everything else in this table stays **+** ask: git-gate, catastrophic shell (`rm -rf` of `/`, a drive root or `~`, `mkfs`, `dd` over a raw disk, `format`, fork bomb), whatever the state and even with the switch off | same as Claude Code | ask: permission prompt (`git reflog expire*`, `git gc --prune*`, a force push or delete of `main`/`master` by name) **+** block: guard plugin (catastrophic shell, the hook's check plus its own stricter text match: `rm -rf` of `/`, a drive root or `~`, fork bomb, `format`, `dd` over a raw disk) **+** block: guard plugin (every other real-loss case, the same state-aware decisions as the hook) | block (exit 2) |
|
|
26
|
-
| `persist-insight` | process | ask: rule-gate (a write to `user-rules.md
|
|
27
|
-
| `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed | log only |
|
|
26
|
+
| `persist-insight` | process | ask: rule-gate (a write to `user-rules.md` or `user-rules.draft.md`; memory is written freely, and the [change report](hooks.md#the-change-report) and the web console show it). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules`: the hook goes on every host (`--no-rule-store`), OpenCode's `permission.edit` keys on the rule files too. The change report still lists rule-file changes | same as Claude Code | ask: OpenCode's own prompt (`permission.edit`, and `evaluate` on OpenCode 2); the guard plugin refuses a file-tool write the host cannot prompt for | block a file-tool write: exit 2, no ask tier; a parsed shell write only warns |
|
|
27
|
+
| `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). A sub-agent's commit or merge (`agent_id` in the payload) in a linked worktree, on a branch that is not shared, passes: a Foreman worker's own batch ([Foreman mode](foreman-mode.md) has the exact conditions). A git hook or `core.hooksPath` that pushes on commit is not seen. A push, or a command that mixes one in, still asks. Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed. A glob sees only the command, never the worktree, so a worker's commit still asks | log only |
|
|
28
28
|
| `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list, or to a gate's own configuration: hook settings, `excludes.json`, `AGENT.md` gate markers, the hook shim) | same as Claude Code | ask: OpenCode's own `permission.edit` rules, written by the emit (every `opencode.json(c)`, the hook settings, the install's `AGENT.md`, `excludes.json`, manifest, plugins, the hook shim); block: guard plugin (the protected-checks list, and the other hosts' Geneseed-only files) | block (exit 2), writes only; a hook `settings.json` only when the edit changes Geneseed's own hook entries |
|
|
29
29
|
| `verify-before-asserting` | law | block at Stop, once per turn: the done gate in `learn` (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (**unverified live**: a frozen fork, and no check runs a model turn) | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
|
|
30
|
-
| `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
|
|
30
|
+
| `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`). Togglable: build without the ops pack, or drop this rule alone with `--exclude-rules`: the check goes on every host (`--no-root-scan`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
|
|
31
31
|
|
|
32
32
|
Bob has no "ask" tier (see [ADR 0007](../adr/0007-gates-fail-closed-per-host-ceiling.md)), so a
|
|
33
33
|
rule the other hosts only ask about either blocks outright on Bob or degrades to a log line.
|
|
@@ -35,6 +35,16 @@ Never a silent pass; Bob runs every gate above through one fused command, `tool-
|
|
|
35
35
|
on the payload shape rather than on separate matchers. OpenCode enforces through two separate
|
|
36
36
|
mechanisms: its own permission prompt (`opencode.json`, static globs) and the guard plugin
|
|
37
37
|
(`tool.execute.before`, pattern matching); a rule can use either or both.
|
|
38
|
+
|
|
39
|
+
`persist-insight` and `external-gate` also read a shell command's parsed forms on every host: a
|
|
40
|
+
redirect, `tee`, `sed -i`, `cp`, `mv`, `rm`, and the PowerShell writers `Add-Content`, `Set-Content`,
|
|
41
|
+
`Out-File`, `Clear-Content`, `Remove-Item`, `Copy-Item`, `Move-Item`, `New-Item`, `Rename-Item` with
|
|
42
|
+
the aliases `ac`, `sc`, `del`, `copy`, `move`, `ni` and `ren`. A parsed write to a store asks on
|
|
43
|
+
Claude Code, OpenClaude and OpenCode 2, is refused on OpenCode 1, and only warns on Bob. **Shell is
|
|
44
|
+
not a boundary:** `bash -c`, `pwsh -c`, an interpreter and a variable stay unread, so the host's own
|
|
45
|
+
command permission is the backstop, and the [change report](hooks.md#the-change-report) tells you
|
|
46
|
+
afterwards.
|
|
47
|
+
|
|
38
48
|
See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) for why a gate that only
|
|
39
49
|
one host can run still ships for every host it can.
|
|
40
50
|
|
|
@@ -47,6 +57,15 @@ and the next write passes. Off per repo with `mode: off`, for one developer with
|
|
|
47
57
|
`Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`, per install with
|
|
48
58
|
`--no-ownership-gate` ([Exclusions](exclusions.md)).
|
|
49
59
|
|
|
60
|
+
### Switches on two rows above
|
|
61
|
+
|
|
62
|
+
`--no-external-gate` stops every ask and refusal in the `external-gate` row, on every host, except
|
|
63
|
+
OpenCode's own `permission.edit` keys, which are host configuration and keep asking. It does not
|
|
64
|
+
touch the rule's text: `--exclude-rules rigor.5` does that, and leaves the hook asking.
|
|
65
|
+
`--no-test-note` stops the advisory weakened-test note that *Cure the Cause* carries at edit time
|
|
66
|
+
and at turn end, on every host. That note asks nothing and blocks nothing, so the rule stays
|
|
67
|
+
outside the hook-pinned ids. See [Exclusions](exclusions.md).
|
|
68
|
+
|
|
50
69
|
| Gate | Claude Code | OpenClaude | OpenCode | Bob |
|
|
51
70
|
|---|---|---|---|---|
|
|
52
71
|
| ownership | deny once: rule-gate (`Write`/`Edit`/`NotebookEdit`; sub-agents defer) | same as Claude Code | block once: guard plugin (a child session defers) | block once (exit 2): tool-gate (sub-agent deferral unverified) |
|
|
@@ -56,7 +56,17 @@ The finer switch removes a single doctrine rule from an install while keeping th
|
|
|
56
56
|
geneseed build --emit claude-global --exclude-rules "process 7"
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded.
|
|
59
|
+
The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded.
|
|
60
|
+
|
|
61
|
+
**A hook goes with its rule.** Three doctrine rules are also enforced by a hook with no switch of its own, and excluding the rule, or building without its pack, drops that hook in the same rebuild. Including the rule again re-arms it at the next rebuild.
|
|
62
|
+
|
|
63
|
+
| Rule | What stops | Flag |
|
|
64
|
+
| --- | --- | --- |
|
|
65
|
+
| process 5, *Consent Before Push* | the commit/push ask of `git-gate` and OpenCode's `git commit*`/`git push*` keys. Bob keeps its warning line | `--no-consent` |
|
|
66
|
+
| process 1, *Persist Insight* | the ask (on Bob the block or warning) on a write to `user-rules.md` or `user-rules.draft.md`, by write tool or parsed shell write, the hard-link check included: `rule-gate`, `git-gate`, Bob's `tool-gate`, the OpenCode guard, and OpenCode's `permission.edit` keys on those files | `--no-rule-store` |
|
|
67
|
+
| ops 2, *Commands Must Return* | the root-scan check of `git-gate`, Bob's `tool-gate` and the OpenCode guard | `--no-root-scan` |
|
|
68
|
+
|
|
69
|
+
Every other check of those hooks stays. The [change report](hooks.md#the-change-report) keeps reporting rule-file changes: with process 1 off, a rule write ran with no prompt, so it is never counted as approved. **With process 1 off, that report is the only signal that the agent changed your standing rules.** It detects and prevents nothing, and it can be fooled: the agent can write `memory/.own-writes.json`, the log of Geneseed's own writes, so a change it lists is excused. The OpenCode guard reads the same state from the install's `Active packs:` and `Excluded rules:` lines when it starts, so restart OpenCode after a rebuild. While the machine's hook shim points at an older checkout, that checkout refuses a flag it does not know and the gate verb lets every call through; run `geneseed rebuild-all` first. Rigor 5 is the exception: it has a switch of its own (below). Picking packs and rules is covered in [Doctrine packs and single rules](../guides/setup-doctrines.md); what the layers are is in [Rules](rules.md).
|
|
60
70
|
|
|
61
71
|
### Per-skill exclusion — skills you never use
|
|
62
72
|
|
|
@@ -97,7 +107,7 @@ geneseed build --emit claude-global --no-secrets-gate # Sealed Secrets
|
|
|
97
107
|
geneseed build --emit claude-global --no-done-gate # Verify Before Asserting
|
|
98
108
|
```
|
|
99
109
|
|
|
100
|
-
The console's Constitution page has a switch on Rule I's and Rule III's rows too (*Enforced by* reads **Gate off** while one is off); the other Rules show *no gate*, because only their text enforces them. The install records `Secrets gate: off` / `Done gate: off` beside `Deletion gate:`, written only when off; rebuilds, upgrades and `geneseed status` carry them like Law IV's.
|
|
110
|
+
The console's Constitution page has a switch on Rule I's and Rule III's rows too (*Enforced by* reads **Gate off** while one is off); Rule VIII has one for the [test note](#external-gate-and-the-test-note--on-or-off), and the other Rules show *no gate*, because only their text enforces them. The install records `Secrets gate: off` / `Done gate: off` beside `Deletion gate:`, written only when off; rebuilds, upgrades and `geneseed status` carry them like Law IV's.
|
|
101
111
|
|
|
102
112
|
What stops, per host:
|
|
103
113
|
- **`--no-secrets-gate`**: the credential scan of `rule-gate` (Claude Code, OpenClaude) and of `tool-gate` (Bob, which then no longer exits 2 for it), and on OpenCode the guard plugin's *Sealed Secrets* block — both the key/credential file path block and the content scan. *External Gate*, *Persist Insight*, the deletion gate and the root-scan check stay.
|
|
@@ -105,6 +115,42 @@ What stops, per host:
|
|
|
105
115
|
|
|
106
116
|
Limits: OpenCode reads both switches from the install's `AGENT.md` when it starts, so restart it after flipping one. A global install beside a project install: `rule-gate` and Bob's `tool-gate` do not stand down for a project install on any host, and neither does the OpenCode guard, so an armed global install still asks about (or blocks) a credential write inside a project whose own install has the secrets gate off. `learn` does stand down on Claude Code and OpenClaude, so there the project's done gate switch decides. And the older-shim limit above is sharper for the done gate: its flag rides on `learn`, so while the shim points at an older checkout an install with the done gate off **loses learning too**, not only the gate. Run `geneseed rebuild-all` before switching either gate off.
|
|
107
117
|
|
|
118
|
+
### External Gate and the test note — on or off
|
|
119
|
+
|
|
120
|
+
Two more switches. Both are armed by default and written only when off, so an armed install does not change.
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
geneseed build --emit claude-global --no-external-gate # protected checks, gate configuration
|
|
124
|
+
geneseed build --emit claude-global --no-test-note # the weakened-test note
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
The install records `External gate: off` / `Test note: off` beside the other gate markers. Rebuilds, upgrades and `geneseed status` carry them. Any other value reads as armed. `doctor --probe` is unaffected: it sends a shell command that neither switch judges.
|
|
128
|
+
|
|
129
|
+
**Run `geneseed rebuild-all` before you switch either one off.** The flags are new. While the machine's shared hook shim points at an older checkout, that checkout refuses the flag, and the gate verb then lets every call through: every gate on that verb is silent, not only this one.
|
|
130
|
+
|
|
131
|
+
What stops, per host:
|
|
132
|
+
- **`--no-external-gate`**: the protected-check and gate-configuration asks of `rule-gate` and of the shell path in `git-gate` (Claude Code, OpenClaude), the same blocks in `tool-gate` (Bob, which then no longer exits 2 for them), the OpenCode guard's refusals on its write and shell paths, and the `evaluate` ask over a gate's own file on OpenCode 2. Every other gate keeps running: secrets, real loss, root scans, the rule-store check, the wiki check and commit/push consent. The guard also keeps refusing an NTFS stream path, because that check protects every path gate.
|
|
133
|
+
- **`--no-test-note`**: the "this edit weakens a test" note at edit time (`rule-gate`, Bob's `tool-gate`), the `[done-gate] advisory` line at turn end (`learn`), and the OpenCode context plugin's reminder on both OpenCode versions. The done checks do not change. `--no-done-gate` still silences the turn-end line and the OpenCode reminder by itself, and it leaves the edit-time note on the hook hosts.
|
|
134
|
+
|
|
135
|
+
**What stays on OpenCode.** The `permission.edit` "ask" keys in `opencode.json` are host configuration, so `--no-external-gate` does not remove them. OpenCode keeps asking before an edit tool writes those files, and you remove the keys by hand if you want that gone. The guard no longer refuses them after an "always" answer, and no longer refuses a shell write to them.
|
|
136
|
+
|
|
137
|
+
**What this switch costs.** External Gate is what stops an agent from editing the gates' own wiring. With it off, the agent can write hook settings, the `AGENT.md` gate markers and `.geneseed/done-checks.txt` without an ask, so every other gate holds only while the agent leaves that wiring alone. Switch it off only where you accept that.
|
|
138
|
+
|
|
139
|
+
**The doctrine and the switch are two axes.** `--exclude-rules rigor.5` takes the rule's text out of the carrier. `--no-external-gate` stops the hook. Neither moves the other:
|
|
140
|
+
|
|
141
|
+
| Rule text (`--exclude-rules`) | Hook (`--no-external-gate`) | Result |
|
|
142
|
+
| --- | --- | --- |
|
|
143
|
+
| In | Armed | The agent is told, and the write asks |
|
|
144
|
+
| Excluded | Armed | The agent is not told, and the write still asks |
|
|
145
|
+
| In | Off | The agent is told, and nothing asks |
|
|
146
|
+
| Excluded | Off | Neither |
|
|
147
|
+
|
|
148
|
+
The console's Constitution page shows both on the same doctrine row: the row's own switch is the rule, and the *External gate* line inside the opened row is the hook. The test note's switch sits on Rule VIII's row, which reads *Hook gate* or **Gate off**. Each gate switch rebuilds at once; the rule switch stages with the other doctrine changes.
|
|
149
|
+
|
|
150
|
+
**Where a marker counts.** In a `CLAUDE.md` or `AGENTS.md`, which are your files, every gate marker counts only inside the `<!-- BEGIN GENESEED -->` block. A marker line outside it reads as armed, and a rebuild does not carry it. A generated `AGENT.md` or `rules/geneseed.md` counts whole, and External Gate protects both. Under External Gate, a write tool aimed at a `CLAUDE.md` or `AGENTS.md` is replayed, and the first block is compared before and after. Any difference asks (on Bob it blocks, and the OpenCode guard refuses). So does a call that cannot be replayed, an unreadable file, or a file over 1 MB. An edit wholly outside the block stays silent, so your own notes there are not interrupted. The name is normalized first, so `CLAUDE.md::$DATA` and `CLAUDE.md.` count as `CLAUDE.md`. A shell edit inside the block does not ask, and neither does a shell edit that puts a fake block before the real one, because only the first block is read. That is a limit: the hook has no replay for a shell write.
|
|
151
|
+
|
|
152
|
+
Limits, as for the gates above: OpenCode reads both markers from `AGENT.md` when it starts, so restart it after a rebuild. `rule-gate` and Bob's `tool-gate` do not stand down for a project install on any host, so an armed global install still asks inside a project built with the switch off. Only `git-gate` stands down, on Claude Code and OpenClaude.
|
|
153
|
+
|
|
108
154
|
### Ownership gate — on or off
|
|
109
155
|
|
|
110
156
|
The [ownership](ownership.md) first-write gate is not a Rule's gate: it stops the first file write of a session, once, in an application repo whose root `AGENTS.md` has no `## Ownership` section, so the agent proposes the setup first. It is armed by default. Switch it off for one install:
|
|
@@ -30,10 +30,25 @@ When the session is unsure, it delegates. The test is still a count, because "su
|
|
|
30
30
|
|
|
31
31
|
A task worker is one `developer` agent in its own git worktree. It explores, implements and tests in a single context, loading skills as it needs them, so nothing it read is lost in a hand-off. After two repair rounds on its own failing tests it returns with its findings instead of looping.
|
|
32
32
|
|
|
33
|
+
A worker can lead a small team inside its own worktree. It can start read-only helpers (`explorer`, `researcher`) at any time. It can also start writing **sub-workers**, each in its own worktree branched from the worker's branch. The worker commits and merges their branches into its own branch, locally, and re-runs the proof after each merge. *Consent Before Push* names this as a batch. The git gate lets a commit or merge through without a prompt only when all of these hold: the host marks the call as a sub-agent's (Claude Code's `agent_id`), the directory is a linked worktree, and its branch is not shared (`main`, `master`, `develop`, `development`, `release/*`, `hotfix/*`, a remote's default, or the branch the main checkout has, in any letter case). The command may hold only adds, read-only git commands and plain commit or merge arguments with one quoted message, after at most one `cd`; anything that can run a second command (`(`, `@`, `$`, `{`, a backtick) asks. A session that only runs in a worktree, as the desktop app's do, still asks. A push still asks everywhere. Bob sends no sub-agent field, so Bob still logs its warning. On OpenCode the static `git commit*` permission still asks, because a permission glob sees only the command, not the worktree. The gate reads the command, not git's own hooks: a `post-commit` hook or a `core.hooksPath` can push on commit, on any branch, as it always could. Nesting stops at two levels below the session: session → worker → sub-worker. A sub-worker starts nothing. A lead holds every member's result before it ends. The blind reviewer is still the session's, never the worker's.
|
|
34
|
+
|
|
35
|
+
| Host | What caps the depth |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| Claude Code | the install writes `env.CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH = "2"` into its settings file, only when the key is absent (Claude Code allows three levels by default) |
|
|
38
|
+
| OpenCode | the install writes a top-level `"subagent_depth": 2` into `opencode.json`, only when the key is absent |
|
|
39
|
+
| OpenClaude | nothing in the host: its source has no such cap (checked on 0.31). The rule text is the only bound |
|
|
40
|
+
| Bob | nothing documented. The rule text is the only bound |
|
|
41
|
+
|
|
42
|
+
A value you set yourself is kept. The value 2 is read as session → worker → sub-worker; that reading is the design's, not yet observed live on either host.
|
|
43
|
+
|
|
33
44
|
When a worker returns green with a diff that touches two or more files or changes logic, the session sends a `reviewer` only your request and the diff — never the worker's reasoning — for a blind check. A failing verdict goes back to the same worker.
|
|
34
45
|
|
|
35
46
|
The session keeps a ledger in its notebook (`notebook/foreman-ledger.md`), one line per task: the task, the agent id, the worktree and the state. A correction, a follow-up or a reviewer finding goes back to **the same worker**, which resumes with everything it already knows. A new worker starts only when the old one cannot be resumed, and it receives a note of the ask, the diff so far and what was tried. A worker serves one task and retires once that task is merged or dropped.
|
|
36
47
|
|
|
48
|
+
### Status lines
|
|
49
|
+
|
|
50
|
+
A worker reports one line at start and on each change: `T<n> · <task> · files: <write set> · <state>`. On Claude Code it sends that line to the session with `SendMessage`; OpenClaude can do the same only in its agent-teams mode. OpenCode and Bob have no channel back to the session, so there the worker writes the line to its own file, `notebook/foreman/<task>.status`, which no other agent writes. The session reads all status files with one command, and only at two moments: before it starts a worker near the same files, and when a worker returns. When two write sets overlap, the session decides: one worker waits, or one worker owns the file. It records that decision in the ledger.
|
|
51
|
+
|
|
37
52
|
> **Why not a crew by default?** Splitting a task by role — one agent reads, the next builds, the next tests — passes each result on as a summary, and the next agent reads the code again. Anthropic's guide [When to fold subagents into your main agent loop](https://claude.com/resources/articles/building-agents-when-to-fold-subagents-into-your-main-agent-loop) found one loop with skills usually beats that, and keeps separate agents for verification, parallel work and context that would overflow. The blind reviewer is that kind of split.
|
|
38
53
|
|
|
39
54
|
### What a pipeline is
|
|
@@ -53,15 +68,15 @@ The crew works in its own git worktree and branch. When worktrees are unavailabl
|
|
|
53
68
|
|
|
54
69
|
Inside the crew, the developer implements and the tester runs the tests and lint. Failures go back to the developer for at most two repair rounds, then to one fresh developer carrying the tester's findings; if that fails too, the crew stops and reports the failure, leaving the branch for you to inspect.
|
|
55
70
|
|
|
56
|
-
###
|
|
71
|
+
### Nothing lands beyond the worker's branch
|
|
57
72
|
|
|
58
|
-
When a
|
|
73
|
+
When a crew is done, it hands back its worktree **uncommitted**. A worker hands back its branch: the local commits from its own sub-workers' merges, and any uncommitted work. Each comes with the raw test and lint output and the list of files it changed. Then the session:
|
|
59
74
|
|
|
60
75
|
1. re-runs the tests and lint itself — its log is its own account, not proof;
|
|
61
|
-
2. shows you the diff and the green output;
|
|
76
|
+
2. shows you the diff from the base it recorded, and the green output;
|
|
62
77
|
3. commits and merges **only once you accept**.
|
|
63
78
|
|
|
64
|
-
|
|
79
|
+
Push, and every merge beyond a worker's own branch, belong to the session alone, under *Consent Before Push* ([Rules](rules.md)). A worker or crew that cannot get to green reports back instead of landing broken work.
|
|
65
80
|
|
|
66
81
|
You can also start a pipeline without foreman mode: ask the agent to "run a pipeline" for a task, and the `pipeline` [skill](skills.md) takes it from there.
|
|
67
82
|
|
|
@@ -37,7 +37,7 @@ The merge is surgical. Every other key and every hook of your own survive, and t
|
|
|
37
37
|
**Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher or `SubagentStop`. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet. So Bob gets four hooks:
|
|
38
38
|
|
|
39
39
|
- `SessionStart` → `geneseed-hook context`.
|
|
40
|
-
- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and rule
|
|
40
|
+
- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push check and a shell write to a rule store become a warning line, because a hard block would leave Bob unable to commit at all. The [ownership](ownership.md) gate also exits 2, but only once per session and repo: the same write passes after the developer answers.
|
|
41
41
|
- `Stop` → `geneseed-hook learn`.
|
|
42
42
|
- `UserPromptSubmit` → `geneseed-hook activity`, which records the turn for the Activity view.
|
|
43
43
|
|
package/docs/concepts/hooks.md
CHANGED
|
@@ -18,7 +18,7 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
|
|
|
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
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 |
|
|
21
|
-
| `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your rules
|
|
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
22
|
| `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into the memory store | needs `GENESEED_LLM` |
|
|
23
23
|
| `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in the store's `agents/<name>.md` | needs `GENESEED_LLM` |
|
|
24
24
|
| `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
|
|
@@ -54,25 +54,25 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
|
|
|
54
54
|
|
|
55
55
|
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
56
|
- **Every `git commit` and `git push`** gets a prompt citing *Consent Before Push*. 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
|
-
- **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.
|
|
57
|
+
- **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
58
|
- **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
59
|
- Any other command passes untouched.
|
|
60
60
|
|
|
61
61
|
**rule-gate.** Runs before every file write.
|
|
62
62
|
- Content that looks like a credential (a cloud access key, a GitHub or Anthropic token, a Slack token, a private-key block) going into any file other than `.env*` gets a prompt citing *Sealed Secrets*. An install built `--no-secrets-gate` wires the hook with that flag and this check alone stands down ([Exclusions](exclusions.md)).
|
|
63
|
-
- A write to `user-rules.md
|
|
64
|
-
- A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). The list is `.geneseed/protected-checks.txt` at the project's git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A project install (any host) seeds it when it is absent, with only the paths that exist there: CI (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`, `.circleci/`), lint, type and test config (`eslint.config.*`, `.eslintrc*`, `biome.json(c)`, `tsconfig.json`, `jest.config.*`, `vitest.config.*`, `pytest.ini`, `ruff.toml`, `.golangci.yml`, `checkstyle.xml`), and the manifests the done gate infers its checks from (`package.json`, `pom.xml`, `build.gradle(.kts)`, `pyproject.toml`, `Cargo.toml`, `go.mod`). It is seeded once and is yours from then on: Geneseed never rewrites it, never deletes it on uninstall, and never touches a list that already exists. To opt out, delete the listed paths (the comments may stay) but keep the file. An existing list, even one holding only comments, is never seeded again; a deleted file is. A global install seeds nothing. Whenever `.geneseed/` exists, the emit also makes sure it holds the personal-by-default `.gitignore`. A check the agent can edit is not a check. The list protects itself. A shell command is read too: the targets of `>`, `>>`, `tee`, `sed -i`, `cp`, `mv` and `
|
|
63
|
+
- A write to `user-rules.md` or `user-rules.draft.md` gets a prompt citing *Persist Insight*: a standing rule is your call, settled through the `rule` [skill](skills.md). Memory is not gated: the agent writes `MEMORY.md` and the facts in a memory store on its own, and you see them afterwards in the web console (a shell write to one also shows in the [change report](#the-change-report)). A hard link has no target to follow, so a write to a second name of a known rule file gets the same prompt: the gate compares the file's device and inode with the `user-rules.md` and `user-rules.draft.md` of the install, the shared tier, the project at the session's git root and the homes `$GENESEED_HARNESS` and `$GENESEED_MEMORY` name. Any other hard-linked file, a pnpm store's for example, is ordinary work. On Bob it is blocked. This check belongs to the **process** pack: build without it, or exclude *Persist Insight*, and `rule-gate` and `git-gate` are wired with `--no-rule-store`, so a rule-file write is ordinary work on every host ([Exclusions](exclusions.md)). The change report still lists it.
|
|
64
|
+
- A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). An install built `--no-external-gate` drops this prompt and the two below it, and the agent can then rewrite the wiring of every other gate ([Exclusions](exclusions.md)). The list is `.geneseed/protected-checks.txt` at the project's git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A project install (any host) seeds it when it is absent, with only the paths that exist there: CI (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`, `.circleci/`), lint, type and test config (`eslint.config.*`, `.eslintrc*`, `biome.json(c)`, `tsconfig.json`, `jest.config.*`, `vitest.config.*`, `pytest.ini`, `ruff.toml`, `.golangci.yml`, `checkstyle.xml`), and the manifests the done gate infers its checks from (`package.json`, `pom.xml`, `build.gradle(.kts)`, `pyproject.toml`, `Cargo.toml`, `go.mod`). It is seeded once and is yours from then on: Geneseed never rewrites it, never deletes it on uninstall, and never touches a list that already exists. To opt out, delete the listed paths (the comments may stay) but keep the file. An existing list, even one holding only comments, is never seeded again; a deleted file is. A global install seeds nothing. Whenever `.geneseed/` exists, the emit also makes sure it holds the personal-by-default `.gitignore`. A check the agent can edit is not a check. The list protects itself. A shell command is read too: the targets of `>`, `>>`, `tee`, `sed -i`, `cp`, `mv`, `rm` and the PowerShell writers (`Add-Content`, `Set-Content`, `Out-File`, `Clear-Content`, `Remove-Item`, `Copy-Item`, `Move-Item`, `New-Item`, `Rename-Item`, and their common aliases) get the same check, by path only (no secret scan of the command), through the git gate. `mv` counts its source as well, and a read (`cat x > /tmp/y`) counts only `/tmp/y`. What the reader cannot follow stays unseen: interpreters with inline code, `pwsh -c`, scripts, `npm run`, variables other than the home, globs, subshell tricks, a folder removed above a listed file. So run the same checks in CI as the boundary that holds.
|
|
65
65
|
- A write to `.geneseed/done-checks.txt`, the done gate's own list (below), gets the same *External Gate* prompt: emptying it would disarm the gate.
|
|
66
66
|
- A write to a gate's own configuration gets the same *External Gate* prompt on Claude Code and OpenClaude. These files can switch a gate off:
|
|
67
|
-
- In the install's own dir: `settings.json`, `settings.local.json` and Bob global's `settings/settings.json` (the hook wiring), `excludes.json`, `AGENT.md` (
|
|
67
|
+
- In the install's own dir: `settings.json`, `settings.local.json` and Bob global's `settings/settings.json` (the hook wiring), `excludes.json`, `AGENT.md` and Bob global's `rules/geneseed.md` (their `… gate: off` markers), `.geneseed-manifest.json` and `.geneseed-emit`; and `excludes.json` in the machine-wide `~/.config/geneseed/` folder, the shared exclude list.
|
|
68
68
|
- In any project: the same names under a `.claude/`, `.openclaude/`, `.bob/` or `.opencode/` folder (at the git root, in a subpackage, or with no git at all), and any `opencode.json(c)`. A team `settings.json` can set `disableAllHooks`.
|
|
69
69
|
- The machine-wide hook shim in `~/.geneseed/bin/` (or `$GENESEED_HOME/bin/`).
|
|
70
70
|
- On OpenCode, also the install's `opencode.json(c)` and its own `plugins/geneseed-*.js`.
|
|
71
|
-
- **OpenCode** asks with its own prompt. The emit writes `permission.edit` "ask" keys into `opencode.json`: every `opencode.json(c)`, the global `config.json`, the install's `AGENT.md` (where the emit put it), the install dir's `excludes.json`, manifest and `.geneseed-emit`, everything that can load code or set permissions there (`plugins/*`, `plugin/*`, `tool/*`, `tools/*`, `agents/*.md`, `agent/*.md`, `mode/*.md`, `modes/*.md`), `user-rules.md
|
|
71
|
+
- **OpenCode** asks with its own prompt. The emit writes `permission.edit` "ask" keys into `opencode.json`: every `opencode.json(c)`, the global `config.json`, the install's `AGENT.md` (where the emit put it), the install dir's `excludes.json`, manifest and `.geneseed-emit`, everything that can load code or set permissions there (`plugins/*`, `plugin/*`, `tool/*`, `tools/*`, `agents/*.md`, `agent/*.md`, `mode/*.md`, `modes/*.md`), `user-rules.md` and `user-rules.draft.md` by name, the `.claude/`, `.openclaude/` and `.bob/` hook settings, and the shim dir. A blanket `"edit": "allow"` becomes `{"*": "allow", …}` with the asks after it. A blanket `"ask"` or `"deny"` already covers them and is left alone; a key you set yourself is kept and named in a warning. The manifest records the keys Geneseed added (`edit_asks`, `edit_shorthand`); a rebuild drops a recorded key it no longer wants, and uninstall takes back the ones still set to `"ask"` and restores your `"allow"`. The guard plugin refuses only the other hosts' Geneseed-only files (`excludes.json`, `AGENT.md`, manifest) and an `AGENT.md` under `$GENESEED_HARNESS`. These rules match by name, not through a link, a project `opencode.json` with its own `"edit": "allow"` replaces a global install's object, and a custom `$GENESEED_HOME` is named by its absolute path, which only OpenCode 2 matches. In OpenCode's built-in plan agent, these files are asked about rather than refused.
|
|
72
72
|
- **Bob** has no prompt, so it blocks, and only writes: a read passes, and so does a write to `opencode.json(c)`, which Bob never reads. A hook `settings.json` (or `settings.local.json`, or global `settings/settings.json`) is blocked only when the write changes Geneseed's own entries (a hook whose command names `geneseed-hook`, with its event and matcher), turns on `disableAllHooks`, or changes a `GENESEED_*`, `*_CONFIG_DIR` or `NODE_OPTIONS` env value. An MCP server or your own hook passes. An edit the hook cannot replay exactly is blocked: a regex, case-folded or line-ranged replace, a search not found exactly once, a diff of more than one block, an unknown write-shaped tool (its name says write, edit, diff, replace or insert; a tool named otherwise is not judged), or a file left unparseable or turned from strict JSON into JSONC. The other files stay blocked.
|
|
73
73
|
Names match exactly, and on Windows without regard to case or slash direction; a link into one of these paths is caught too. To change one of these files, edit it yourself, or approve the prompt. `geneseed` commands (`exclude`, a rebuild) write these files directly and are never asked. Claude Code itself also prompts for writes under `.claude/` in its default and `acceptEdits` modes, but not in `bypassPermissions`, so you can see two prompts there. A shell write is read as above. On OpenCode `permission.edit` covers edit tools only, so the guard refuses a shell write to every file in this list; the same edit through an edit tool gets the prompt. On Bob a shell write to a hook `settings.json` is blocked: a command line cannot be replayed.
|
|
74
74
|
- The first write of a session in an application repo (a git root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section is refused once, the **ownership gate**. Despite the name it is a reminder, not a gate, because the next write passes. It is not a prompt for you: the reason goes to the agent, which asks you to set ownership up now, skip this session, or skip in this repo until you ask (on Bob, exit 2, once). The next write passes, a sub-agent never triggers it on Claude Code and OpenClaude, and writes to `AGENTS.md` or `.geneseed/` pass. Off per repo with `mode: off` in that section; for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, which also makes every session start with the line `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it`; per install with `--no-ownership-gate`, which prints no such line ([Ownership](ownership.md), [Exclusions](exclusions.md)).
|
|
75
|
-
- 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. 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.
|
|
75
|
+
- 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
76
|
- Ordinary edits pass untouched.
|
|
77
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 opened the turn, so its cost does not grow with the session. It blocks at most once per turn; the second stop ends the turn and leaves a line in the gate ledger. 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)).
|
|
@@ -85,6 +85,45 @@ export GENESEED_LLM="claude -p"
|
|
|
85
85
|
|
|
86
86
|
Unset, `learn` does nothing useful: on a real Stop/SubagentStop/PreCompact call it returns immediately rather than reading the transcript for nothing, and on a manual run it prints the prompt it would have sent. Geneseed never stores or embeds an API key. See [Memory](memory.md).
|
|
87
87
|
|
|
88
|
+
## What a prompt says
|
|
89
|
+
|
|
90
|
+
When a gate stops a call, Geneseed writes the reason. An agent cannot change this fixed text. Each prompt is plain English, one sentence per line, and it puts the decision first:
|
|
91
|
+
|
|
92
|
+
```text
|
|
93
|
+
This edit changes .github/workflows/ci.yml (+3 lines, -1 line), which defines the checks that run on every push.
|
|
94
|
+
Safe choice: Deny, unless you asked for this change. (External Gate)
|
|
95
|
+
It asks because the agent's own work is judged by this file.
|
|
96
|
+
If you allow it, those checks can get weaker or stop running, and a failure could go unseen.
|
|
97
|
+
Agent: if refused, do not write this file another way.
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The first line says what changes and what the file is, with the path from the repository root. The second gives the safe choice and names the rule. The last line is for the agent. A commit or a push is routine, so it gets one line.
|
|
101
|
+
|
|
102
|
+
On *Deletion Is Deliberate*, *Commands Must Return* and *Consent Before Push*, the prompt can also quote the `description` that the agent gave the command: `The agent says (not checked): "..."`. It never quotes the agent on *Sealed Secrets*, *External Gate* or *Persist Insight*, because there the agent's opinion is the conflict of interest.
|
|
103
|
+
|
|
104
|
+
If a loss command uses `--git-dir` or `--work-tree`, the prompt adds a line: the command runs on another repository, which the gate did not read.
|
|
105
|
+
|
|
106
|
+
Each host carries this text differently:
|
|
107
|
+
|
|
108
|
+
| Host | What you get |
|
|
109
|
+
| --- | --- |
|
|
110
|
+
| Claude Code, OpenClaude | The reason in the permission prompt |
|
|
111
|
+
| OpenCode | A note just before the dialog, for its two asks only ([guard](../reference/plugin-guard.md)). A refusal goes to the model |
|
|
112
|
+
| Bob | No prompt. A block tells the model to relay the text to you. A warning says the call ran without a prompt |
|
|
113
|
+
|
|
114
|
+
Know these limits:
|
|
115
|
+
|
|
116
|
+
- The text says what a file is and what is at risk. On a write or an edit, it cannot say why the agent wants the change.
|
|
117
|
+
- Claude's own title and prefix stay. Geneseed controls only the reason.
|
|
118
|
+
- The desktop card shows about 3 lines. Past those, you must scroll.
|
|
119
|
+
- OpenCode's note sits beside the dialog, not in it, and exists only for its two asks: a rule write that reaches a host prompt, and a gate configuration file.
|
|
120
|
+
- OpenCode 1's note is a toast, which can expire while the dialog is open.
|
|
121
|
+
- An unattended OpenCode 2 session posts the note, then denies the call.
|
|
122
|
+
- On Bob and on an OpenCode refusal, you depend on the model to relay the text. This is best effort. The change report below is the direct channel.
|
|
123
|
+
- The line count overstates a change with several regions. Shell writes show no count, and neither does a `replace_all`, a search-and-replace, a diff, a notebook cell, a text or an old file past 1 MB, or anything on OpenCode.
|
|
124
|
+
- A loss prompt names the kind of loss, not the files.
|
|
125
|
+
- The text is in English only.
|
|
126
|
+
|
|
88
127
|
## Verify
|
|
89
128
|
|
|
90
129
|
Open a session in a repo and ask the agent what it knows about the project — it should answer from the repo's docs without reading them first. Ask it to commit something: you should get a prompt before the commit runs.
|
|
@@ -93,14 +132,16 @@ What happens when a gate cannot decide, where the hooks are written, and the one
|
|
|
93
132
|
|
|
94
133
|
## The change report
|
|
95
134
|
|
|
96
|
-
Shell is not a boundary. The gates read only parsed forms of a command, and the host's own command permission is the backstop for the rest. So Geneseed also checks afterwards: at session start it records each store file's size and modified time (`user-rules.md`, `PROFILE.md`, the wiki manifest, `memory/**/*.md`), and at the end of each turn it compares. A change outside this session's approved writes is told to you once, and `geneseed status` shows a `changes` row for seven days. **The report detects a change. It does not prevent one.**
|
|
135
|
+
Shell is not a boundary. The gates read only parsed forms of a command, and the host's own command permission is the backstop for the rest. So Geneseed also checks afterwards: at session start it records each store file's size and modified time (`user-rules.md`, `user-rules.draft.md`, `PROFILE.md`, the wiki manifest, `memory/**/*.md`, and the project's own `user-rules.md` and `user-rules.draft.md` at the session's git root), and at the end of each turn it compares. A change outside this session's approved writes is told to you once, and `geneseed status` shows a `changes` row for seven days. **The report detects a change. It does not prevent one.**
|
|
97
136
|
|
|
98
137
|
| Host | Baseline | Approved means | You see |
|
|
99
138
|
| --- | --- | --- | --- |
|
|
100
|
-
| Claude Code, OpenClaude | `<install>/notebook/store-baseline/`, at SessionStart | the transcript shows a Write, Edit or NotebookEdit ran | a `systemMessage` at Stop |
|
|
101
|
-
| Bob | same | nothing:
|
|
102
|
-
| OpenCode | in the guard plugin's memory | `tool.execute.after` on OpenCode's own edit tools | a toast (1.x), a synthetic message (2.x) |
|
|
139
|
+
| Claude Code, OpenClaude | `<install>/notebook/store-baseline/`, at SessionStart | the transcript shows a Write, Edit or NotebookEdit ran; with *Persist Insight* excluded (`learn --no-rule-store`) a rule file never counts, because no prompt ran | a `systemMessage` at Stop |
|
|
140
|
+
| Bob | same | nothing: there is no transcript, so any change is reported, a memory write the agent made freely included | a stderr line at Stop, in Bob's hook log |
|
|
141
|
+
| OpenCode | in the guard plugin's memory | `tool.execute.after` on OpenCode's own edit tools; with *Persist Insight* excluded a rule file never counts | a toast (1.x), a synthetic message (2.x) |
|
|
142
|
+
|
|
143
|
+
With *Persist Insight* excluded nothing asks before a rule write, so this report is then the only signal that your standing rules changed, and the `.own-writes.json` limit below applies to it in full.
|
|
103
144
|
|
|
104
145
|
Geneseed's own writers do not count. `learn`, `geneseed memory rm`, the OpenCode learn plugin and the fold snapshot the store around their run and log what moved to `memory/.own-writes.json`, as an exact size and time. A change that matches is excused. Two limits follow: anything else that writes during that run is excused too, and the log is a plain file an agent could edit.
|
|
105
146
|
|
|
106
|
-
Other limits. Approval is per session and the shared tier is not, so another session's approved write is reported here too, and the line says it may be that.
|
|
147
|
+
Other limits. Approval is per session and the shared tier is not, so another session's approved write is reported here too, and the line says it may be that. Any web console write during a session is reported, your own decision on a drafted item included, because a console request proves no click: anything on the machine that reads the console's token can send one. The line names that case, so a report right after your click may be that click. On Claude Code a sub-agent's write sits in its own transcript, so it is reported the same way. The baseline is a plain file: an agent that can write there can edit it, or set a file's size and time back. The report is evidence, not a control. If a done-gate advisory already holds stdout at that Stop, the line goes to stderr and the `changes` row.
|
|
@@ -18,9 +18,10 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
|
|
|
18
18
|
| Real data loss (force-push to `main`, discarding uncommitted work, `rm` of untracked files…) | ⚙️ block³ · 🔒 ask (reflog, gc) | 🪝 ask | 🪝 block¹ | 🪝 ask² |
|
|
19
19
|
| Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
|
|
20
20
|
| Consent before every commit and push | 🔒 permission ask | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
|
|
21
|
-
|
|
|
21
|
+
| Standing-rule write needs your call | 🔒 ask³ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
|
|
22
22
|
| User-only skills hidden from the model | 🔒 `permission.skill` deny | ✅ `disable-model-invocation` | ✅ `/`-command, no skill | ✅ `disable-model-invocation` |
|
|
23
23
|
| Sovereign-repo exclusions⁵ | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
|
|
24
|
+
| Subagent depth capped at two ([Foreman mode](foreman-mode.md)) | ✅ `subagent_depth` | ✅ `env` setting | ➖ undocumented | ➖ no cap in the host |
|
|
24
25
|
| MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
|
|
25
26
|
| Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
|
|
26
27
|
|
|
@@ -28,13 +29,13 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
|
|
|
28
29
|
|
|
29
30
|
¹ **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 only the rules that admit no judgement call — secrets, real data loss, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off — and turns the two consent checks into a logged warning. It has no `SubagentStop` event. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet, so learn runs on `Stop` only. **What is verified:** the payload shape (Claude's keys plus `cwd`), the event list and the strict settings schema were read in Bob 2.2.3's shipped bundle on the authoring machine, and a live prompt on 2026-10-25 wrote an Activity snapshot from `UserPromptSubmit`. The gates' block-by-exit-code behaviour is Bob's documented contract, not yet observed live; the rules preamble still holds if a hook does not fire.
|
|
30
31
|
² **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). **Unverified live** for the same reason.
|
|
31
|
-
³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so a rule
|
|
32
|
+
³ 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.
|
|
32
33
|
⁴ 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.
|
|
33
34
|
⁵ 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).
|
|
34
35
|
|
|
35
36
|
## The one conditional row
|
|
36
37
|
|
|
37
|
-
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. Everything else in the table is always on.
|
|
38
|
+
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.
|
|
38
39
|
|
|
39
40
|
One OpenCode asymmetry: Geneseed shares `opencode.json` with you and cannot tell its own `git commit*` permission entry from one you typed, so a rebuild without the process pack leaves an existing entry in place and says so instead of deleting it. A `permission.skill` deny is different: Geneseed records each one it writes, and a rebuild or uninstall takes back only those, never a deny you set yourself.
|
|
40
41
|
|
package/docs/concepts/hosts.md
CHANGED
|
@@ -18,7 +18,7 @@ Each host has a **global** install (in its config directory, active in every rep
|
|
|
18
18
|
|
|
19
19
|
## Two engines
|
|
20
20
|
|
|
21
|
-
- **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
|
|
21
|
+
- **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. The install also caps subagent nesting at two levels there (`subagent_depth`), as it does on Claude Code (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`); OpenClaude and Bob have no such cap ([Foreman mode](foreman-mode.md)). It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
|
|
22
22
|
- **Claude Code**, **Bob** and **OpenClaude** share one Claude-shaped engine: Geneseed wires **hooks** into the host's `settings.json`, each calling `geneseed-hook <verb>`. See [Hooks](hooks.md).
|
|
23
23
|
|
|
24
24
|
## Where to go next
|
package/docs/concepts/kits.md
CHANGED
|
@@ -37,11 +37,29 @@ The second kit is `react`, for React 18 or 19 apps built with Vite or webpack, i
|
|
|
37
37
|
|
|
38
38
|
It is adapted from [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT), rewritten and condensed for Vite and Jest; the webpack side file is first-party. It has no Server Components material: a client-rendered app has no server render.
|
|
39
39
|
|
|
40
|
+
The third kit is `ci-pipelines`, for CI pipelines on Jenkins and GitLab CI. It adds two skills and no agent:
|
|
41
|
+
|
|
42
|
+
| Member | Kind | What it is for |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| `jenkins-pipeline` | skill | Declarative `Jenkinsfile`, shared-library layout (`vars/`, `src/`, `resources/`), CPS and `@NonCPS`, sandbox and script approval, credentials binding, `parallel` and `when`, tests with JenkinsPipelineUnit |
|
|
45
|
+
| `gitlab-ci` | skill | `.gitlab-ci.yml`: `rules:`, the `needs:` DAG, `include:` and `extends:`, caching and artifacts, protected and masked variables, environments, CI lint |
|
|
46
|
+
|
|
47
|
+
Its rules keep the pipeline in one source of truth, take secrets only from the CI's own store, pin images and tool versions, and run fast feedback first. Its `banned` list refuses GitLab's older job-condition keywords, which GitLab no longer actively develops, in its files. It is first-party.
|
|
48
|
+
|
|
49
|
+
The fourth kit is `docker`, for Docker and Compose operations on any stack. It adds one skill:
|
|
50
|
+
|
|
51
|
+
| Member | Kind | What it is for |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| `compose-ops` | skill | Health-ordered startup (`depends_on` with `condition: service_healthy`), named volumes against bind mounts, pinned tags or digests, `.env` and secrets, restart policies, resource limits, logging, networks, minimal non-root multi-stage images, and safe updates: pull, recreate, roll back |
|
|
54
|
+
|
|
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
|
+
|
|
40
57
|
### Switching kits on and off
|
|
41
58
|
|
|
42
59
|
```bash
|
|
43
60
|
geneseed build --emit claude-global --kits spring-boot
|
|
44
61
|
geneseed build --emit claude-global --kits react,spring-boot
|
|
62
|
+
geneseed build --emit claude-global --kits ci-pipelines,docker
|
|
45
63
|
geneseed build --emit claude-global --kits none
|
|
46
64
|
```
|
|
47
65
|
|
|
@@ -38,7 +38,7 @@ The same folder already held the install registry, your own loop bricks and temp
|
|
|
38
38
|
|
|
39
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.
|
|
40
40
|
|
|
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
|
|
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
|
|
|
43
43
|
### How it is created
|
|
44
44
|
|
|
@@ -46,7 +46,7 @@ The first global emit in a host's own config directory creates the folder and se
|
|
|
46
46
|
|
|
47
47
|
### The fold
|
|
48
48
|
|
|
49
|
-
Each global emit, in the host's own config directory, moves that host's stores into the tier and prints one line, such as `[shared] claude: 12 facts folded, 1 collision, 2 rules to approve, old store moved aside`. A host with nothing to move prints nothing, and a second emit writes nothing. `geneseed migrate --dry-run` previews the fold for each host, and [Upgrade to 5.0](../guides/upgrade-to-5.md) walks through a first run.
|
|
49
|
+
Each global emit, in the host's own config directory, moves that host's stores into the tier and prints one line, such as `[shared] claude: 12 facts folded, 1 collision, 2 rules to approve, old store moved aside`. A host with nothing to move prints nothing, and a second emit writes nothing. `geneseed migrate --dry-run` previews the fold for each host, *Preview next rebuild* on the console's Installs page shows the same, and [Upgrade to 5.0](../guides/upgrade-to-5.md) walks through a first run.
|
|
50
50
|
|
|
51
51
|
- **Facts** copy byte for byte. A fact with the same name and other text lands as `<name>-<host>.md`, then `-2`, `-3`. The memory-curator agent can merge them later. Agent lessons append to the tier's file for that agent.
|
|
52
52
|
- **Notes** in `notebook/skill-notes/` and `notebook/agent-notes/` copy the same way. The rest of the notebook stays per host.
|
|
@@ -54,15 +54,15 @@ Each global emit, in the host's own config directory, moves that host's stores i
|
|
|
54
54
|
- **Exclude paths** join the shared list, and a shared path the host never saw gets its wiring. The report line names each file this writes in your repo.
|
|
55
55
|
- **`user-rules.md`** merges rule by rule. A rule with the same title and body as a shared rule leaves the host file. Any other rule goes to `user-rules.draft.md` with its host and old number, and stays in the host file, still binding. A host file with no rules left and nothing else of yours returns to its seed; hand-written text keeps the file as it is.
|
|
56
56
|
|
|
57
|
-
**Approving a draft.** The [rule skill](skills.md) takes each item in turn; nothing else writes a decision. Approve a rule and it joins the shared file under a new number, and the next fold of that host removes the host copy. Reject it and it stays on that host only, and the fold never drafts it again. For a profile or wiki pointer, the file you choose becomes the shared one and the other moves aside, or you keep both and the host file goes on overriding. The draft is never loaded: a drafted rule binds only from its host file.
|
|
57
|
+
**Approving a draft.** The [rule skill](skills.md) takes each item in turn, and the console's **Pending** section decides the same items by the same steps; nothing else writes a decision. Approve a rule and it joins the shared file under a new number, and the next fold of that host removes the host copy. Reject it and it stays on that host only, and the fold never drafts it again. For a profile or wiki pointer, the file you choose becomes the shared one and the other moves aside, or you keep both and the host file goes on overriding. The draft is never loaded: a drafted rule binds only from its host file.
|
|
58
58
|
|
|
59
59
|
Nothing is deleted. After every copy is read back, the old `memory/` moves to `archived-memory/<stamp>/` beside it, and the notes and whole files move to the same kind of folder. The host store returns to its seed and keeps its `README.md`. Hand-written index text and `archive/` stay in that folder, and the report line names every other file that stayed there and did not fold. A store or file already linked to the tier, in either direction, is left alone. If a copy fails, the old store stays readable, the emit reports it on stderr and goes on, and the next emit retries. There is no automatic way back: to downgrade, restore the archived folder by hand.
|
|
60
60
|
|
|
61
61
|
### The console
|
|
62
62
|
|
|
63
|
-
The console has one hub and no install switch. On the **Personal** page, Rules, Profile and Memory list the shared store once, tagged `shared`, and name no harness; a project install keeps its own entry. Each rule row shows its token cost, and the page shows the total. There is no rule limit. A
|
|
63
|
+
The console has one hub and no install switch. On the **Personal** page, Rules, Profile and Memory list the shared store once, tagged `shared`, and name no harness; a project install keeps its own entry. Each rule row shows its token cost, and the page shows the total. There is no rule limit. A **Pending** section shows what waits in the draft, with *Approve* and *Reject* on a rule, and the two files with three choices on a profile or wiki pointer. A decision that moves a file offers *Rebuild all*, which removes the host copy. An edit in another session makes the decision reload instead of applying, and no decision applies while a rebuild runs.
|
|
64
64
|
|
|
65
|
-
On **Installs**, *Make default* on an active install picks the one the console's pickers start on and a request naming no install reads. The `install` and `theme` lines of `geneseed status` follow it. The pick is `default-install.json`; if that install goes away, the console returns to the fixed host order.
|
|
65
|
+
On **Installs**, *Preview next rebuild* shows what each global install would fold, and any orphans, and writes nothing. *Make default* on an active install picks the one the console's pickers start on and a request naming no install reads. The `install` and `theme` lines of `geneseed status` follow it. The pick is `default-install.json`; if that install goes away, the console returns to the fixed host order.
|
|
66
66
|
|
|
67
67
|
### Uninstall
|
|
68
68
|
|
package/docs/concepts/skills.md
CHANGED
|
@@ -42,7 +42,7 @@ The full list, with each description, is in the catalog.
|
|
|
42
42
|
|
|
43
43
|
### Skills improve themselves
|
|
44
44
|
|
|
45
|
-
Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with
|
|
45
|
+
Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with no prompt, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and `doctor` would report it as drift. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what was expected> (<date>)`: `situation:` says where the correction holds (it is optional, and older lines without it stay valid; without it, the circumstance in `seen:` stands in), `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Folding a skill or agent note is your call: the `skill-forge` skill first replays one past task whose original ask still exists, as two dispatched agents from the pre-fix revision, one told to read no notes and one given the note. The `fresh-eyes` skill freezes one rubric from the ask and judges both results blind against it. A note is folded only when it wins, on the result or on a stated process gain; on a tie or a loss you decide whether to keep or delete it. A trivial wording fix skips that probe. Most runs end with nothing to change.
|
|
46
46
|
|
|
47
47
|
### Old names keep working
|
|
48
48
|
|