geneseed 4.31.0 → 5.0.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 +107 -0
- package/DESIGN.md +2 -2
- package/README.md +6 -5
- package/SHIPPED.md +4 -3
- package/adapters/bob/README.md +6 -5
- package/adapters/claude-code/README.md +4 -3
- package/adapters/claude-code/skills/geneseed/SKILL.md +1 -1
- package/adapters/openclaude/README.md +4 -3
- package/adapters/opencode/GLOBAL-HARNESS-SPEC.md +3 -1
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -1
- package/adapters/opencode/README.md +18 -18
- package/adapters/opencode/plugins/geneseed-activity.js +57 -1
- package/adapters/opencode/plugins/geneseed-context.js +220 -18
- package/adapters/opencode/plugins/geneseed-guard.js +578 -74
- package/adapters/opencode/plugins/geneseed-learn.js +97 -23
- package/bin/geneseed-cli.mjs +17 -25
- package/bin/geneseed-hook.mjs +23 -8
- package/docs/DESIGN.md +175 -0
- package/docs/PRD.md +111 -0
- package/docs/README.md +3 -2
- package/docs/architecture.md +145 -0
- package/docs/concepts/agents.md +1 -1
- package/docs/concepts/collaboration.md +1 -1
- package/docs/concepts/enforcement-table.md +1 -1
- package/docs/concepts/exclusions.md +6 -6
- package/docs/concepts/footprint.md +1 -1
- package/docs/concepts/foreman-mode.md +2 -2
- package/docs/concepts/hook-gates.md +1 -1
- package/docs/concepts/hooks.md +27 -11
- package/docs/concepts/host-matrix.md +3 -3
- package/docs/concepts/hosts.md +1 -1
- package/docs/concepts/kits.md +3 -1
- package/docs/concepts/loop-bricks.md +1 -1
- package/docs/concepts/loop-notes.md +4 -2
- package/docs/concepts/loop-templates.md +7 -4
- package/docs/concepts/loops.md +3 -0
- package/docs/concepts/ownership.md +2 -2
- package/docs/concepts/rules.md +15 -2
- package/docs/concepts/shared-tier.md +73 -0
- package/docs/concepts/skills.md +2 -2
- package/docs/concepts/themes.md +1 -1
- package/docs/extending.md +13 -12
- package/docs/guides/install-claude-code.md +1 -1
- package/docs/guides/install-opencode.md +1 -1
- package/docs/guides/migrate.md +4 -2
- package/docs/guides/project-context.md +2 -2
- package/docs/guides/run-a-loop.md +1 -1
- package/docs/guides/set-up-ownership.md +1 -1
- package/docs/guides/setup-footprint.md +1 -1
- package/docs/guides/uninstall.md +2 -1
- package/docs/guides/upgrade-to-5.md +116 -0
- package/docs/guides/upgrade.md +21 -9
- package/docs/guides/wiki.md +3 -3
- package/docs/reference/env-context.md +5 -3
- package/docs/reference/environment.md +1 -1
- package/docs/reference/glossary.md +2 -0
- package/docs/reference/loop-actions.md +1 -1
- package/docs/reference/opencode-plugins.md +3 -3
- package/docs/reference/plugin-activity.md +1 -1
- package/docs/reference/plugin-context.md +5 -0
- package/docs/reference/plugin-guard.md +14 -6
- package/docs/reference/plugin-learn.md +13 -6
- package/docs/reference/troubleshoot-hooks.md +3 -3
- package/docs/reference/troubleshoot-update.md +14 -0
- package/docs/token-footprint.md +4 -3
- package/docs/understand/a-day.md +2 -2
- package/docs/understand/design-choices-install.md +2 -1
- package/docs/understand/enforced-vs-asked.md +4 -3
- package/docs/understand/machine-bob.md +3 -1
- package/docs/understand/machine-claude.md +7 -5
- package/docs/understand/machine-opencode.md +7 -5
- package/docs/understand/on-your-machine.md +4 -0
- package/docs/understand/take-it-out.md +1 -1
- package/docs/web-ui.md +141 -73
- package/harness.config.json +1 -1
- package/js/README.md +10 -6
- package/js/build/args.mjs +10 -8
- package/js/build/bundle.mjs +11 -13
- package/js/build/driver.mjs +66 -65
- package/js/build/emit-claude.mjs +22 -16
- package/js/build/emit-common.mjs +4 -5
- package/js/build/emit-opencode.mjs +22 -22
- package/js/build/fold.mjs +515 -0
- package/js/build/generate.mjs +41 -52
- package/js/build/render.mjs +115 -29
- package/js/build/source.mjs +4 -1
- package/js/build/stubs.mjs +70 -9
- package/js/build/version.mjs +10 -10
- package/js/cli-table.json +23 -83
- package/js/hosts/activity.mjs +2 -2
- package/js/hosts/geneseed-dir.mjs +1 -1
- package/js/hosts/hooks-context.mjs +410 -99
- package/js/hosts/hooks-done.mjs +97 -31
- package/js/hosts/hooks-learn.mjs +38 -7
- package/js/hosts/hooks-prims.mjs +69 -2
- package/js/hosts/hooks.mjs +300 -64
- package/js/hosts/hosts.mjs +150 -51
- package/js/hosts/installs.mjs +55 -167
- package/js/hosts/link.mjs +3 -5
- package/js/hosts/mcp.mjs +1 -1
- package/js/hosts/memory-files.mjs +219 -17
- package/js/hosts/ownership-gate.mjs +1 -1
- package/js/hosts/settings.mjs +18 -13
- package/js/hosts/shim.mjs +4 -33
- package/js/hosts/store-watch.mjs +189 -0
- package/js/inspect/checks-authoring.mjs +3 -3
- package/js/inspect/checks-build.mjs +45 -18
- package/js/inspect/checks-counts.mjs +4 -4
- package/js/inspect/checks-repo.mjs +13 -14
- package/js/inspect/cost.mjs +24 -2
- package/js/inspect/diff.mjs +123 -123
- package/js/inspect/doctor.mjs +22 -27
- package/js/inspect/excludes.mjs +181 -62
- package/js/inspect/inventory.mjs +22 -27
- package/js/inspect/registry.mjs +106 -30
- package/js/inspect/scan.mjs +5 -5
- package/js/inspect/status.mjs +141 -119
- package/js/inspect/validate.mjs +22 -24
- package/js/lib/fs.mjs +47 -50
- package/js/lib/json.mjs +10 -17
- package/js/lib/machine-dir.mjs +73 -0
- package/js/lib/paths.mjs +22 -33
- package/js/lib/proc.mjs +1 -1
- package/js/lib/prompt.mjs +19 -27
- package/js/lib/text.mjs +8 -12
- package/js/lib/udiff.mjs +11 -15
- package/js/loop/catalog.mjs +2 -3
- package/js/loop/state.mjs +15 -5
- package/js/maintain/memory.mjs +17 -17
- package/js/maintain/migrate.mjs +79 -89
- package/js/maintain/setup.mjs +43 -32
- package/js/maintain/uninstall.mjs +43 -61
- package/js/maintain/update.mjs +200 -93
- package/js/ui/anim.mjs +21 -35
- package/js/ui/cli.mjs +36 -58
- package/js/ui/menu.mjs +22 -45
- package/js/ui/tui.mjs +27 -67
- package/js/web/actions.mjs +38 -38
- package/js/web/api.mjs +132 -76
- package/js/web/catalog.mjs +175 -46
- package/js/web/docs.mjs +33 -12
- package/js/web/doctor-worker.mjs +14 -0
- package/js/web/handler.mjs +14 -5
- package/js/web/routes.mjs +17 -19
- package/js/web/state.mjs +78 -19
- package/js/web/update-check.mjs +25 -10
- package/js/web/user-files.mjs +50 -105
- package/package.json +7 -4
- package/registry.json +48 -55
- package/src/AGENT.md.tmpl +13 -14
- package/src/agents/_self-improvement.md +1 -1
- package/src/agents/_template.md +4 -1
- package/src/agents/advocate.md +1 -1
- package/src/agents/architect.md +1 -1
- package/src/agents/developer.md +6 -3
- package/src/agents/devops-engineer.md +1 -1
- package/src/agents/docker-expert.md +1 -1
- package/src/agents/docs.md +1 -1
- package/src/agents/empiricist.md +1 -1
- package/src/agents/explorer.md +1 -1
- package/src/agents/framer.md +1 -1
- package/src/agents/historian.md +1 -1
- package/src/agents/kubernetes-specialist.md +1 -1
- package/src/agents/memory-curator.md +2 -2
- package/src/agents/operator.md +1 -1
- package/src/agents/performance.md +1 -1
- package/src/agents/pragmatist.md +1 -1
- package/src/agents/react-engineer.md +1 -1
- package/src/agents/react-reviewer.md +1 -1
- package/src/agents/researcher.md +1 -1
- package/src/agents/reviewer.md +1 -1
- package/src/agents/security.md +1 -1
- package/src/agents/skeptic.md +1 -1
- package/src/agents/spring-boot-engineer.md +1 -1
- package/src/agents/spring-reviewer.md +1 -1
- package/src/agents/spring-security.md +1 -1
- package/src/agents/steward.md +1 -1
- package/src/agents/tester.md +5 -2
- package/src/agents/user-advocate.md +1 -1
- package/src/agents/visionary.md +1 -1
- package/src/bricks/apply.md +3 -0
- package/src/bricks/test.md +6 -4
- package/src/loops/bugfix.json +11 -5
- package/src/loops/feature.json +7 -4
- package/src/memory/README.md +1 -1
- package/src/skills/_self-improvement.md +2 -2
- package/src/skills/daydream/SKILL.md +2 -2
- package/src/skills/daydream/instructions.md +1 -1
- package/src/skills/geneseed.md +1 -1
- package/src/skills/learn-mode.md +1 -2
- package/src/skills/loop.md +1 -0
- package/src/skills/profile.md +2 -2
- package/src/skills/rule/approve.md +69 -0
- package/src/skills/rule/consolidate.md +3 -3
- package/src/skills/rule.md +13 -5
- package/src/skills/ship.md +9 -1
- package/src/skills/skill-forge.md +1 -1
- package/src/skills/teach.md +29 -12
- package/src/skills/wiki.md +1 -1
- package/themes/_TEMPLATE.json +1 -2
- package/themes/biker.json +1 -2
- package/themes/commentator.json +1 -2
- package/themes/cyberpunk.json +1 -2
- package/themes/gamer.json +1 -2
- package/themes/imperial.json +1 -2
- package/themes/joker.json +1 -2
- package/themes/marvin.json +1 -2
- package/themes/mean.json +1 -2
- package/themes/military.json +1 -2
- package/themes/neutral.json +1 -2
- package/themes/pirate.json +1 -2
- package/themes/sports.json +1 -2
- package/themes/verstappen.json +1 -2
- package/themes/wizard.json +1 -2
- package/web/dist/assets/Activity-D8G4eClY.js +1 -0
- package/web/dist/assets/ActivityDetail-BtOBYk3M.js +1 -0
- package/web/dist/assets/AgentGlyph-k6o3gCM1.js +1 -0
- package/web/dist/assets/Bonsai-B_y20b3i.js +1 -0
- package/web/dist/assets/{CopyButton-IXnXzH4Y.js → CopyButton-CHQte7Ap.js} +1 -1
- package/web/dist/assets/Dashboard-B8uXeJZ_.js +2 -0
- package/web/dist/assets/{DataTable-BWbUx4bY.js → DataTable-b9zTShqJ.js} +1 -1
- package/web/dist/assets/Docs-Dgv_MWfT.js +5 -0
- package/web/dist/assets/{EmptyState-1sPNleqv.js → EmptyState-CY5Pm2xy.js} +1 -1
- package/web/dist/assets/FilterInput-qGKNSlxv.js +1 -0
- package/web/dist/assets/GreenhouseView-CSzTMSl_.js +1 -0
- package/web/dist/assets/Installs-BDk9lqBI.js +3 -0
- package/web/dist/assets/JournalView-CvRk1-m5.js +1 -0
- package/web/dist/assets/Kits-CoITzxWM.js +1 -0
- package/web/dist/assets/Laws-Ctf5r9rE.js +3 -0
- package/web/dist/assets/Library-DNwHYVXt.js +3 -0
- package/web/dist/assets/{Loops-C5u7fQOR.js → Loops-S85PMQ8m.js} +2 -2
- package/web/dist/assets/Markdown-0ORz7tAc.js +69 -0
- package/web/dist/assets/OperatorHudView-DuGz_sTk.js +1 -0
- package/web/dist/assets/Personal-afJNwvRS.js +2 -0
- package/web/dist/assets/RailCats-AW92uhsX.js +1 -0
- package/web/dist/assets/Settings-CGDFz-6j.js +1 -0
- package/web/dist/assets/Tabs-1qLrnqmn.js +1 -0
- package/web/dist/assets/api-C46vAuqp.js +1 -0
- package/web/dist/assets/controls-D4wmg_pl.js +1 -0
- package/web/dist/assets/index-COTd4TRZ.js +3 -0
- package/web/dist/assets/index-CtorA7uK.css +1 -0
- package/web/dist/assets/motion-RlUl1osO.js +1 -0
- package/web/dist/assets/react-C1iE8mnY.js +9 -0
- package/web/dist/assets/rolldown-runtime-XKyaHtl9.js +1 -0
- package/web/dist/assets/{sections-ChwaobfW.js → sections-CtFz7HFH.js} +1 -1
- package/web/dist/assets/{usePoll-bDFN-Hr6.js → usePoll-o8ul-Sog.js} +1 -1
- package/web/dist/index.html +7 -7
- package/src/skills/quiz.md +0 -44
- package/web/dist/assets/Activity-B7cFtS00.js +0 -1
- package/web/dist/assets/ActivityDetail-C-GbMmuW.js +0 -1
- package/web/dist/assets/Bonsai-_YyexVC5.js +0 -1
- package/web/dist/assets/Dashboard-sCfEjowQ.js +0 -2
- package/web/dist/assets/Docs-w3Y7M5Ts.js +0 -5
- package/web/dist/assets/FilterInput-CZREvrjX.js +0 -1
- package/web/dist/assets/GreenhouseView-BWWbMKmg.js +0 -1
- package/web/dist/assets/Installs-CnkdJ-VA.js +0 -3
- package/web/dist/assets/JournalView-C7bPD3fZ.js +0 -1
- package/web/dist/assets/KitApply-CQQbnThf.js +0 -1
- package/web/dist/assets/Kits-aj07N7mT.js +0 -1
- package/web/dist/assets/Laws-DZ38nl_H.js +0 -3
- package/web/dist/assets/Library-QCGXPV5h.js +0 -2
- package/web/dist/assets/Markdown-DpmmtW2Y.js +0 -65
- package/web/dist/assets/OperatorHudView-Blu1lqiZ.js +0 -1
- package/web/dist/assets/Personal-ox_MktWO.js +0 -2
- package/web/dist/assets/RailCats-BuJD4Jou.js +0 -1
- package/web/dist/assets/Tabs-CIPyMAX-.js +0 -1
- package/web/dist/assets/api-BxjLd7Qd.js +0 -1
- package/web/dist/assets/index-0GCxkY7m.css +0 -1
- package/web/dist/assets/index-CzDi9JpF.js +0 -3
- package/web/dist/assets/motion-CXaUMNkg.js +0 -1
- package/web/dist/assets/react-DlYQp10C.js +0 -9
- package/web/dist/assets/rolldown-runtime-hePW80VL.js +0 -1
package/docs/PRD.md
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: prd
|
|
3
|
+
mirrors-commit: 9c4af014
|
|
4
|
+
generated: 2026-11-06
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Geneseed product requirements
|
|
8
|
+
|
|
9
|
+
Reconstructed from the code and [`DESIGN.md`](../DESIGN.md). The items marked `⚠ to confirm` are
|
|
10
|
+
inferred and wait for the maintainer's word.
|
|
11
|
+
|
|
12
|
+
<!-- geneseed:doc:start -->
|
|
13
|
+
## Problem
|
|
14
|
+
|
|
15
|
+
An AI coding agent starts each session with no standing rules, no memory of the last session, and
|
|
16
|
+
nothing that stops a risky action. Writing that setup by hand means one set of files per tool, in
|
|
17
|
+
each tool's own format, and it drifts. Geneseed authors the setup once and generates it for each
|
|
18
|
+
host, with hooks or plugins that enforce what the host allows.
|
|
19
|
+
<!-- geneseed:doc:end -->
|
|
20
|
+
|
|
21
|
+
<!-- geneseed:doc:start -->
|
|
22
|
+
## Users
|
|
23
|
+
|
|
24
|
+
- **Developer on one machine:** installs globally, and wants the agent's rules and memory in every repo.
|
|
25
|
+
- **Team maintainer:** installs per repo, and wants rules and gates committed beside the code.
|
|
26
|
+
- **Locked-down corporate user:** has no npm access, and installs and updates from a git clone.
|
|
27
|
+
- **Harness contributor:** edits `src/`, and needs to know what an addition costs ([`extending.md`](extending.md)).
|
|
28
|
+
<!-- geneseed:doc:end -->
|
|
29
|
+
|
|
30
|
+
<!-- geneseed:doc:start -->
|
|
31
|
+
## Goals
|
|
32
|
+
|
|
33
|
+
1. One neutral source, generated into each supported host (`src/`, `js/build/`).
|
|
34
|
+
2. Enforce at the tool boundary what a host can enforce, and say plainly what is only asked ([Enforced vs. asked](understand/enforced-vs-asked.md)).
|
|
35
|
+
3. Knowledge that outlives a session and is the same for every host on the machine ([The shared tier](concepts/shared-tier.md)).
|
|
36
|
+
4. Nothing lost: uninstall, upgrades and the fold keep user data.
|
|
37
|
+
5. Install and update without a build step or runtime dependencies ([ADR 0001](adr/0001-zero-runtime-dependencies.md)).
|
|
38
|
+
<!-- geneseed:doc:end -->
|
|
39
|
+
|
|
40
|
+
<!-- geneseed:doc:start -->
|
|
41
|
+
## Non-goals
|
|
42
|
+
|
|
43
|
+
- Geneseed does not manage MCP servers. It lists them read-only (`geneseed mcp`).
|
|
44
|
+
- It does not sync between machines. The shared tier covers one machine; use git or a vault to carry it further.
|
|
45
|
+
- It does not call a model API or hold an API key. `learn` uses the host's model or a CLI the user names.
|
|
46
|
+
- It does not bypass a host's permission mode: no emit grants a directory permission.
|
|
47
|
+
- `DESIGN.md` has the full list under *Explicitly out of scope*.
|
|
48
|
+
<!-- geneseed:doc:end -->
|
|
49
|
+
|
|
50
|
+
<!-- geneseed:doc:start -->
|
|
51
|
+
## User journeys
|
|
52
|
+
|
|
53
|
+
1. As a developer, I want one command to install the harness, so that every repo inherits it.
|
|
54
|
+
2. As a developer with two tools, I want a fact taught in one to reach the other, so that I teach it once.
|
|
55
|
+
3. As a developer, I want to be asked before a force-push or a credential write, so that a mistake does not cost data.
|
|
56
|
+
4. As a 4.x user, I want the upgrade to move my stores without loss, so that I do not migrate by hand.
|
|
57
|
+
5. As a maintainer, I want to see every install's state in one place, so that I can keep them current.
|
|
58
|
+
|
|
59
|
+
```mermaid
|
|
60
|
+
sequenceDiagram
|
|
61
|
+
actor D as Developer
|
|
62
|
+
participant G as geneseed
|
|
63
|
+
participant T as shared tier
|
|
64
|
+
participant R as rule skill
|
|
65
|
+
D->>G: upgrade or rebuild-all
|
|
66
|
+
G->>T: fold facts, notes, exclude paths
|
|
67
|
+
G->>T: draft rules that need a decision
|
|
68
|
+
G-->>D: [shared] claude: 12 facts folded, 2 rules to approve
|
|
69
|
+
D->>R: review pending rules
|
|
70
|
+
R->>T: approve to the shared file, or keep on the host
|
|
71
|
+
```
|
|
72
|
+
<!-- geneseed:doc:end -->
|
|
73
|
+
|
|
74
|
+
<!-- geneseed:doc:start -->
|
|
75
|
+
## Functional requirements
|
|
76
|
+
|
|
77
|
+
| ID | Requirement | Acceptance criteria | Status | Code |
|
|
78
|
+
|---|---|---|---|---|
|
|
79
|
+
| FR-001 | The generator renders one source into each host's install. | Each emit target renders without error; a second emit changes nothing | ✅ | `js/build/`, `tests/golden.mjs` |
|
|
80
|
+
| FR-002 | A theme changes voice only. | Same rules and structure in every theme; theme keys in parity | ✅ | `themes/`, `js/build/render.mjs` |
|
|
81
|
+
| FR-003 | A user chooses doctrine packs, single rules, skills and kits per install. | The choice survives a rebuild | ✅ | `js/build/args.mjs`, `js/build/generate.mjs` |
|
|
82
|
+
| FR-004 | Hook hosts gate git, writes and session context. | A blocked or asked call reaches the host's verdict channel | ✅ | `bin/geneseed-hook.mjs`, `js/hosts/hooks*.mjs` |
|
|
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
|
+
| 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
|
+
| 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` |
|
|
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
|
+
| 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
|
+
| FR-011 | A folder can silence every global install. | `geneseed exclude add`; effect on the next tool call | ✅ | `js/inspect/excludes.mjs` |
|
|
90
|
+
| FR-012 | Uninstall removes only what the manifest owns. | User files stay; the tier is never touched | ✅ | `js/maintain/uninstall.mjs` |
|
|
91
|
+
| FR-013 | A clone updates itself with a checked pull; npm installs rebuild after an install. | A failed doctor rolls back; a doctor that cannot finish keeps the pull and rebuilds nothing | ✅ | `js/maintain/update.mjs` |
|
|
92
|
+
| FR-014 | `doctor`, `status`, `diff` and `validate` report state without changing it. | No install write | ✅ | `js/inspect/` |
|
|
93
|
+
| FR-015 | The web console shows the fleet and the shared stores once. | No install switch; default install selectable; rule costs shown with no limit; pending read-only; Update hidden when the pull cannot run | ✅ | `js/web/`, `web/src/` |
|
|
94
|
+
| FR-016 | Loops work a requirement as validated, committed iterations. | `geneseed loop` steps a state machine over `LOOP.md` | ✅ | `js/loop/` |
|
|
95
|
+
| FR-017 | Claude Code auto memory can be imported on request. | An explicit import verb | ✗ | Deferred past 5.0.0 |
|
|
96
|
+
<!-- geneseed:doc:end -->
|
|
97
|
+
|
|
98
|
+
<!-- geneseed:doc:start -->
|
|
99
|
+
## Non-functional requirements
|
|
100
|
+
|
|
101
|
+
| ID | Requirement | Threshold | Acceptance criteria | Status | Code |
|
|
102
|
+
|---|---|---|---|---|---|
|
|
103
|
+
| NFR-001 | No runtime dependencies. | 0 installed; vendored only | `tests/unit/dependency_policy.test.mjs` | ✅ | `js/vendor/` |
|
|
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
|
+
| NFR-003 | Context hook output stays under the host's cap. | 9 000 characters | `OUTPUT_BUDGET` | ✅ | `js/hosts/hooks-context.mjs` |
|
|
106
|
+
| NFR-004 | The rules file stays within its size ceiling. | 41 612 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; one spawn site on the hook path | Closure walks | ✅ | `tests/unit/hook_cli.test.mjs` |
|
|
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
|
+
| 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
|
+
| 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` |
|
|
111
|
+
<!-- geneseed:doc:end -->
|
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
|
| Keep it running | [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
|
|
33
|
+
| 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 |
|
|
33
34
|
| Keep it running | [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
|
|
34
35
|
| Keep it running | [Start the web console at login](guides/autostart.md) | Keeping the console running |
|
|
35
36
|
| Keep it running | [Uninstall](guides/uninstall.md) | Removing an install — and what stays behind |
|
|
@@ -40,7 +41,7 @@
|
|
|
40
41
|
|
|
41
42
|
**Harness** — [Hosts](concepts/hosts.md) · [What each host automates](concepts/host-matrix.md) · [Rules](concepts/rules.md) · [Agents](concepts/agents.md) · [Skills](concepts/skills.md) · [Hooks](concepts/hooks.md) · [Hook gates, settings and the shim](concepts/hook-gates.md)
|
|
42
43
|
|
|
43
|
-
**Memory** — [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md)
|
|
44
|
+
**Memory** — [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md) · [The shared tier](concepts/shared-tier.md)
|
|
44
45
|
|
|
45
46
|
**Configuration** — [Footprint](concepts/footprint.md) · [Themes](concepts/themes.md) · [Exclusions](concepts/exclusions.md) · [Kits](concepts/kits.md) · [Code intelligence (LSP)](concepts/lsp.md)
|
|
46
47
|
|
|
@@ -60,4 +61,4 @@
|
|
|
60
61
|
|
|
61
62
|
## For contributors
|
|
62
63
|
|
|
63
|
-
[Extending Geneseed](extending.md) — what each kind of addition costs · [DESIGN.md](../DESIGN.md) · [Design history](design-history.md) · [Token footprint](token-footprint.md) · [Web console internals](web-ui.md) · [OpenCode plugin wiring](opencode-plugin-setup.md) · [Candidate hosts](candidate-hosts.md) · adapters: [OpenCode](../adapters/opencode/README.md), [Claude Code](../adapters/claude-code/README.md), [Bob](../adapters/bob/README.md), [OpenClaude](../adapters/openclaude/README.md)
|
|
64
|
+
[Product requirements](PRD.md) · [Architecture, C4](architecture.md) · [Console design system](DESIGN.md) · [Extending Geneseed](extending.md) — what each kind of addition costs · [DESIGN.md](../DESIGN.md) · [Design history](design-history.md) · [Token footprint](token-footprint.md) · [Web console internals](web-ui.md) · [OpenCode plugin wiring](opencode-plugin-setup.md) · [Candidate hosts](candidate-hosts.md) · adapters: [OpenCode](../adapters/opencode/README.md), [Claude Code](../adapters/claude-code/README.md), [Bob](../adapters/bob/README.md), [OpenClaude](../adapters/openclaude/README.md)
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: architecture
|
|
3
|
+
mirrors-commit: 9c4af014
|
|
4
|
+
generated: 2026-11-06
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Geneseed architecture
|
|
8
|
+
|
|
9
|
+
The short map is the root [`ARCHITECTURE.md`](../ARCHITECTURE.md): parts, invariants and the lines
|
|
10
|
+
that must not be crossed. The module map is [`js/README.md`](../js/README.md). This page adds the C4
|
|
11
|
+
views and how the pieces meet at run time. It repeats neither.
|
|
12
|
+
|
|
13
|
+
<!-- geneseed:doc:start -->
|
|
14
|
+
## Context (C4 L1)
|
|
15
|
+
|
|
16
|
+
A developer drives an AI coding host. Geneseed sits beside that host: it writes the host's
|
|
17
|
+
instructions, skills and agents, and answers the host's hook calls. It calls no model itself,
|
|
18
|
+
unless the user sets `GENESEED_LLM` for `learn` on a hook host.
|
|
19
|
+
|
|
20
|
+
```mermaid
|
|
21
|
+
---
|
|
22
|
+
title: Context (C4 L1) — Geneseed
|
|
23
|
+
---
|
|
24
|
+
flowchart TB
|
|
25
|
+
dev(["Developer [person]"])
|
|
26
|
+
gs["Geneseed [software system · Node.js CLI, hooks, web console]"]
|
|
27
|
+
host["AI coding host [software system · Claude Code, OpenCode, Bob, OpenClaude]"]
|
|
28
|
+
npm["npm registry [external system]"]
|
|
29
|
+
git["Git remote [external system · a clone's origin]"]
|
|
30
|
+
vault["Wiki vault [external system · a folder of Markdown]"]
|
|
31
|
+
llm["Model CLI [external system · GENESEED_LLM, optional]"]
|
|
32
|
+
|
|
33
|
+
dev -->|"installs, upgrades, inspects · CLI, browser"| gs
|
|
34
|
+
dev -->|"works with the agent · host UI"| host
|
|
35
|
+
gs -->|"writes instructions, skills, agents, hook wiring · files"| host
|
|
36
|
+
host -->|"calls gates and context · process, stdin/stdout JSON"| gs
|
|
37
|
+
gs -->|"gets the package, checks for a release · HTTPS"| npm
|
|
38
|
+
gs -->|"self-updates a clone · git"| git
|
|
39
|
+
gs -->|"reads eager and lazy notes · files"| vault
|
|
40
|
+
gs -->|"distils facts on a hook host · process"| llm
|
|
41
|
+
subgraph Legend
|
|
42
|
+
l1(["person"]) ~~~ l2["software system"]
|
|
43
|
+
end
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Sources: `bin/geneseed-hook.mjs`, `js/hosts/settings.mjs`, `js/web/update-check.mjs`,
|
|
47
|
+
`js/maintain/update.mjs`, `js/hosts/hooks-learn.mjs`.
|
|
48
|
+
<!-- geneseed:doc:end -->
|
|
49
|
+
|
|
50
|
+
<!-- geneseed:doc:start -->
|
|
51
|
+
## Containers (C4 L2)
|
|
52
|
+
|
|
53
|
+
```mermaid
|
|
54
|
+
---
|
|
55
|
+
title: Containers (C4 L2) — Geneseed on one machine
|
|
56
|
+
---
|
|
57
|
+
flowchart TB
|
|
58
|
+
dev(["Developer [person]"])
|
|
59
|
+
host["AI coding host [software system]"]
|
|
60
|
+
|
|
61
|
+
subgraph gs["Geneseed"]
|
|
62
|
+
cli["geneseed [container · Node.js CLI, bin/geneseed-cli.mjs]"]
|
|
63
|
+
build["geneseed-build [container · Node.js generator, bin/build-driver.mjs]"]
|
|
64
|
+
hook["geneseed-hook [container · Node.js, bin/geneseed-hook.mjs]"]
|
|
65
|
+
shim["hook shim [container · script, ~/.geneseed/bin]"]
|
|
66
|
+
plugins["OpenCode plugins [container · JS in the host's process, adapters/opencode]"]
|
|
67
|
+
web["web console [container · Node.js daemon + React SPA, js/web, web/dist]"]
|
|
68
|
+
source[("source tree [database · src/, themes/]")]
|
|
69
|
+
install[("install [database · files in a host config dir or repo]")]
|
|
70
|
+
tier[("shared tier [database · files, ~/.config/geneseed]")]
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
dev -->|"runs verbs · shell"| cli
|
|
74
|
+
dev -->|"reads and acts · HTTP on localhost, port 4747"| web
|
|
75
|
+
cli -->|"starts an emit · in process, or via rebuild-all"| build
|
|
76
|
+
cli -->|"starts the daemon · process"| web
|
|
77
|
+
web -->|"runs jobs · process"| cli
|
|
78
|
+
build -->|"reads · files"| source
|
|
79
|
+
build -->|"renders and emits · files"| install
|
|
80
|
+
build -->|"seeds, then folds host stores · files"| tier
|
|
81
|
+
build -->|"rewrites, last writer wins · files"| shim
|
|
82
|
+
host -->|"loads text, skills, agents · files"| install
|
|
83
|
+
host -->|"runs on each hook event · process"| shim
|
|
84
|
+
host -->|"loads at start · in process"| plugins
|
|
85
|
+
shim -->|"calls · process"| hook
|
|
86
|
+
hook -->|"reads session files, writes facts · files"| tier
|
|
87
|
+
plugins -->|"reads session files, writes facts · files"| tier
|
|
88
|
+
hook -->|"reads context, gate markers · files"| install
|
|
89
|
+
plugins -->|"reads context, gate markers · files"| install
|
|
90
|
+
web -->|"reads and edits rules, profile, memory · files"| tier
|
|
91
|
+
web -->|"inspects and changes · files"| install
|
|
92
|
+
subgraph Legend
|
|
93
|
+
l1(["person"]) ~~~ l2["container"] ~~~ l3[("database")]
|
|
94
|
+
end
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The stores are plain files: no server or database engine runs. `installs.json`, the install
|
|
98
|
+
registry, sits in the tier's folder and tells the CLI and the console which installs exist.
|
|
99
|
+
|
|
100
|
+
| Container | Must not | Enforced by |
|
|
101
|
+
|---|---|---|
|
|
102
|
+
| `geneseed-build` | spawn | closure walks in `tests/unit/hook_cli.test.mjs` ([ADR 0002](adr/0002-no-spawn-on-the-generator-and-hook-path.md)) |
|
|
103
|
+
| `geneseed-hook` | print anything but its verdict | `fuzz/`, the golden CLI matrix |
|
|
104
|
+
| `geneseed` | spawn beyond its allow-list | [ADR 0002](adr/0002-no-spawn-on-the-generator-and-hook-path.md) |
|
|
105
|
+
| OpenCode plugins | import from `js/`, or throw on OpenCode 2 | `tests/plugins/helper_parity.test.mjs` |
|
|
106
|
+
|
|
107
|
+
### Build and install flow
|
|
108
|
+
|
|
109
|
+
```mermaid
|
|
110
|
+
---
|
|
111
|
+
title: What a global emit does
|
|
112
|
+
---
|
|
113
|
+
sequenceDiagram
|
|
114
|
+
participant U as geneseed / rebuild-all
|
|
115
|
+
participant B as geneseed-build
|
|
116
|
+
participant T as shared tier
|
|
117
|
+
participant I as host config dir
|
|
118
|
+
U->>B: --emit claude-global
|
|
119
|
+
B->>T: ensureSharedTier (canonical install only)
|
|
120
|
+
B->>B: renderAll, with absolute tier paths
|
|
121
|
+
B->>I: write files in the manifest, merge settings
|
|
122
|
+
B->>T: fold facts, read each copy back
|
|
123
|
+
B->>I: move the old store to archived-memory/
|
|
124
|
+
B->>T: fold notes, exclude paths, profile, wiki
|
|
125
|
+
B->>T: draft each rule that needs a decision
|
|
126
|
+
B-->>U: one [shared] report line
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
A non-canonical emit, such as `geneseed diff` into a temp folder, renders the same paths and
|
|
130
|
+
creates and folds nothing. [The shared tier](concepts/shared-tier.md) holds the user-facing rules.
|
|
131
|
+
<!-- geneseed:doc:end -->
|
|
132
|
+
|
|
133
|
+
<!-- geneseed:doc:start -->
|
|
134
|
+
## Decisions
|
|
135
|
+
|
|
136
|
+
The decisions are one file each in [`docs/adr/`](adr/README.md), and product decisions are in the
|
|
137
|
+
root [`DESIGN.md`](../DESIGN.md). They are not copied here. The structural ones behind this page:
|
|
138
|
+
|
|
139
|
+
- [0001](adr/0001-zero-runtime-dependencies.md) — vendored code, no installed runtime dependency.
|
|
140
|
+
- [0002](adr/0002-no-spawn-on-the-generator-and-hook-path.md) — who may spawn.
|
|
141
|
+
- [0004](adr/0004-uninstall-without-backups.md) — manifests and managed blocks.
|
|
142
|
+
- [0008](adr/0008-host-parity-ceiling-of-the-weakest-host.md) — a feature lands on every host.
|
|
143
|
+
- [0009](adr/0009-self-update-is-a-git-pull.md) — a clone updates itself with `git pull`.
|
|
144
|
+
- [0011](adr/0011-shared-tier.md) — one shared tier per machine.
|
|
145
|
+
<!-- geneseed:doc:end -->
|
package/docs/concepts/agents.md
CHANGED
|
@@ -40,7 +40,7 @@ In [foreman mode](foreman-mode.md) the session chains several of them into a pip
|
|
|
40
40
|
|
|
41
41
|
### Agents learn too
|
|
42
42
|
|
|
43
|
-
When a subagent finishes, the learn step can record a lesson for that agent alone, in `
|
|
43
|
+
When a subagent finishes, the learn step can record a lesson for that agent alone, in `agents/<name>.md` in the memory store (the [shared](shared-tier.md) one on a global install) — one bullet per lesson, capped so it never grows unbounded. The next time that agent runs, it starts with what it learned. See [Memory](memory.md). (Not on Bob, which has no subagent-finished event.)
|
|
44
44
|
|
|
45
45
|
<!--harness:opencode-->
|
|
46
46
|
*(OpenCode only)*
|
|
@@ -61,4 +61,4 @@ When new evidence contradicts a memory with a force, the agent must revise it in
|
|
|
61
61
|
|
|
62
62
|
### Profile — who you are
|
|
63
63
|
|
|
64
|
-
`PROFILE.md`
|
|
64
|
+
`PROFILE.md` is seeded once and never overwritten. A global install keeps it in the [shared tier](shared-tier.md), one for the machine; a project install keeps it beside the instructions file. It holds your role, habits and how you like answers pitched. It colours how the agent works but never binds — it is last in [precedence](rules.md). Edit the file directly, use the Profile tab in the web console, or let the `profile` [skill](skills.md) interview you and draft it; it writes only with your consent, and routes anything that is really a standing rule to `user-rules.md`.
|
|
@@ -23,7 +23,7 @@ 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` or
|
|
26
|
+
| `persist-insight` | process | ask: rule-gate (a write to `user-rules.md`, `user-rules.draft.md` or a memory store, shared one included) | same as Claude Code | ask: OpenCode's own prompt (`permission.edit`, and `evaluate` on OpenCode 2); the guard plugin refuses a file-tool write the host cannot prompt for | block a file-tool write: exit 2, no ask tier; a parsed shell write only warns |
|
|
27
27
|
| `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). 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 |
|
|
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) |
|
|
@@ -5,7 +5,7 @@ title: "Exclusions"
|
|
|
5
5
|
kind: "concept"
|
|
6
6
|
section: "Configuration"
|
|
7
7
|
description: "Three ways to switch things off: one rule, one skill, or every hook in a folder."
|
|
8
|
-
link: {"hash": "#/
|
|
8
|
+
link: {"hash": "#/installs/hosts", "label": "Manage on Installs →"}
|
|
9
9
|
---
|
|
10
10
|
Geneseed has three ways to switch something off, and they work at different scales (plus an on/off switch for the hook gates of Laws I, III and IV, and for the ownership gate, below):
|
|
11
11
|
|
|
@@ -31,22 +31,22 @@ geneseed exclude list
|
|
|
31
31
|
geneseed exclude remove ~/code/my-vault
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
One command updates every global install on the machine.
|
|
34
|
+
One command updates every global install on the machine. It writes the folder to the **shared list**, `excludes.json` in the machine-wide Geneseed folder (`~/.config/geneseed/`), and wires each global install. Every global hook and plugin reads the shared list on each call, beside the install's own `excludes.json`, so a change takes effect at once and the hosts cannot drift apart. The install's own file still holds the `wired` record of what the command set up on that host. A per-repo install never reads the shared list. An agent that edits either file is asked first, on every host: the list is a gate's own configuration.
|
|
35
35
|
|
|
36
36
|
What "dormant" means per host:
|
|
37
37
|
|
|
38
38
|
- **Claude Code** — every hook exits silently, and the global `CLAUDE.md` is suppressed natively through `claudeMdExcludes` in the repo's `.claude/settings.local.json`.
|
|
39
39
|
- **OpenClaude** — the same, in the repo's `.openclaude/settings.local.json`.
|
|
40
40
|
- **Bob** — every hook exits silently, and a stub `.bob/rules/geneseed.md` in the repo shadows the global rules file. A hand-written stub already there is never overwritten.
|
|
41
|
-
- **OpenCode** —
|
|
41
|
+
- **OpenCode** — the `geneseed-context`, `geneseed-guard`, `geneseed-learn` and `geneseed-activity` plugins stand down. Three plugins do not read the list: `geneseed-notify` still pings the desktop, `geneseed-ponytail` still injects its ruleset if you switched it on, and `geneseed-workflow` keeps its tool. The `permission` keys in a global `opencode.json` still apply, because OpenCode reads them before any plugin.
|
|
42
42
|
|
|
43
43
|
`geneseed exclude remove` undoes all of it.
|
|
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
|
|
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.
|
|
48
48
|
|
|
49
|
-
The web console has the same controls in the **Excluded folders** card on the
|
|
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
|
|
|
51
51
|
### Per-rule exclusion — one rule off
|
|
52
52
|
|
|
@@ -113,7 +113,7 @@ The [ownership](ownership.md) first-write gate is not a Rule's gate: it stops th
|
|
|
113
113
|
geneseed build --emit claude-global --no-ownership-gate
|
|
114
114
|
```
|
|
115
115
|
|
|
116
|
-
The install records `Ownership gate: off` beside the other gate markers, written only when off; rebuilds, upgrades and `geneseed status` carry it. The console has
|
|
116
|
+
The install records `Ownership gate: off` beside the other gate markers, written only when off; rebuilds, upgrades and `geneseed status` carry it. The console's Constitution page has a switch for it inside the *Ownership* row of the Credo band: open the row, and a gate line follows the section's text. The gate belongs to no Rule, and that line exists only in the console. The section's text always binds, so the row's status stays *Always*. *Enforced by* reads **Gate off** while the gate is off, and the Credo's pill on the Precedence ladder counts it. What stops: the ownership check of `rule-gate` (Claude Code, OpenClaude) and of `tool-gate` (Bob), on OpenCode the guard plugin's ownership refusal, the setup proposal in the install's `AGENT.md` (the build drops that passage, and the `/document-project` suggestion in it goes too), and the session-start decline reminder. A repo with `mode: on` still runs the ownership checkpoints, and every other check of those gates stays.
|
|
117
117
|
|
|
118
118
|
Two narrower ways out need no rebuild: `## Ownership` with `mode: off` in a repo's root `AGENTS.md` silences it for that repo and its team; answering "skip in this repo until I ask" writes `Setup: declined <YYYY-MM-DD>` into your personal `.geneseed/ownership.md`, which silences it for you alone in that repo until you delete the line or ask for the setup; and answering "skip this session" lets the session write on.
|
|
119
119
|
|
|
@@ -5,7 +5,7 @@ title: "Footprint (lean vs full)"
|
|
|
5
5
|
kind: "concept"
|
|
6
6
|
section: "Configuration"
|
|
7
7
|
description: "Lean or full: how much of the constitution rides inline every turn."
|
|
8
|
-
link: {"hash": "#/installs/hosts", "label": "Change it on
|
|
8
|
+
link: {"hash": "#/installs/hosts", "label": "Change it on Installs →"}
|
|
9
9
|
---
|
|
10
10
|
**Footprint** decides how much of the [constitution](rules.md) the agent carries *inline* in its instructions file on every turn. It has two settings, **lean** (the default) and **full**, chosen per install. It is a token-cost dial, not a rules dial: every rule the install adopted is in force at either setting.
|
|
11
11
|
|
|
@@ -5,7 +5,7 @@ title: "Foreman mode"
|
|
|
5
5
|
kind: "concept"
|
|
6
6
|
section: "Working together"
|
|
7
7
|
description: "Direct or foreman: whether the session does the work or hands it to a task worker."
|
|
8
|
-
link: {"hash": "#/
|
|
8
|
+
link: {"hash": "#/installs/hosts", "label": "Set the mode on Installs →"}
|
|
9
9
|
---
|
|
10
10
|
**Mode** decides how work gets executed in a session. Two modes ship: **direct**, the default, where the agent does every task itself, and **foreman**, where the session hands each task that would block it to a background [agent](agents.md) and keeps talking to you while it works.
|
|
11
11
|
|
|
@@ -73,7 +73,7 @@ You can also start a pipeline without foreman mode: ask the agent to "run a pipe
|
|
|
73
73
|
geneseed setup
|
|
74
74
|
```
|
|
75
75
|
|
|
76
|
-
- **Web console** — the per-install **Mode** dropdown on the
|
|
76
|
+
- **Web console** — the per-install **Mode** dropdown on the Installs page, then **Apply**.
|
|
77
77
|
- **Command line** — with the emit target of the install you are changing; switch back with `--mode direct`:
|
|
78
78
|
|
|
79
79
|
```bash
|
|
@@ -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,
|
|
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-or-memory checks 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
|
@@ -19,8 +19,8 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
|
|
|
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
21
|
| `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your rules or memory; stops the session's first write once in an application repo with no `## Ownership` section | no |
|
|
22
|
-
| `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into
|
|
23
|
-
| `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in `
|
|
22
|
+
| `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into the memory store | needs `GENESEED_LLM` |
|
|
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` |
|
|
25
25
|
| `UserPromptSubmit` | you send a message | `geneseed-hook activity` | records the turn's start for the web console's Activity view; prints nothing | off with `GENESEED_ACTIVITY=off` |
|
|
26
26
|
| `SessionEnd` | the session closes | `geneseed-hook activity` | marks the session ended and archives it | off with `GENESEED_ACTIVITY=off` |
|
|
@@ -39,7 +39,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
|
|
|
39
39
|
|
|
40
40
|
## What each one does, and what you see
|
|
41
41
|
|
|
42
|
-
**context.** Before your first message, the agent receives your own harness files — `user-rules.md`, `PROFILE.md`, the memory index, the notebook index, your wiki declaration — skipping any still untouched since install, then the repo's docs, discovered by convention or listed in a `context.json`.
|
|
42
|
+
**context.** Before your first message, the agent receives your own harness files — `user-rules.md`, `PROFILE.md`, the memory index, the notebook index, your wiki declaration — skipping any still untouched since install, then the repo's docs, discovered by convention or listed in a `context.json`. A global install reads these from the [shared tier](shared-tier.md) first, then from the host folder. The hook keeps its whole output under 9 000 characters, because the host cuts a longer one; what does not fit is listed for the agent to read on demand. A git root whose `package.json` has no `engines` field adds one `Runtime floor:` line, which asks the agent to name the supported runtime before it adds a dependency or a language feature. You see nothing, except that the agent already knows your project. See [Project context](../guides/project-context.md).
|
|
43
43
|
|
|
44
44
|
**git-gate.** Runs before every shell command and looks for `git` in it, including chained one-liners and `git -C <path>` forms, and for a recursive scan of a whole filesystem.
|
|
45
45
|
- **A catastrophic command** gets a confirmation prompt citing *Deletion Is Deliberate* (on Bob, it is refused with exit 2) whatever the repository holds, even with the deletion gate switched off: a recursive removal of `/`, a drive root (`C:\`, `/c`) or the home directory (`~`, `$HOME`), `mkfs` on a device, `dd` over a raw disk, `format C:`, a fork bomb. It judges the program, not the text: a `sudo`, a background `&`, a subshell, `bash -c '…'` or a heredoc fed to a shell (`bash <<'EOF'`) hides nothing, and a heredoc fed to anything else (`cat`, `git commit -F -`) or a commit message that only names `rm -rf /` passes. The OpenCode guard runs the same code, plus its own stricter text match.
|
|
@@ -55,27 +55,29 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
|
|
|
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
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. This check is wired in every build, whatever packs or rules you excluded: it rides inside `git-gate` with no flag of its own, because a new flag or verb would reach machines still running an older hook shim, which would refuse it — and Claude Code blocks a tool call whose gate fails.
|
|
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.
|
|
58
59
|
- Any other command passes untouched.
|
|
59
60
|
|
|
60
61
|
**rule-gate.** Runs before every file write.
|
|
61
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)).
|
|
62
|
-
- A write to `user-rules.md`, `MEMORY.md` or a file in the install's `memory/` gets a prompt citing *Persist Insight*: whether something is a standing rule or a fact to remember is your call, settled through the `rule` [skill](skills.md).
|
|
63
|
-
- 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.
|
|
63
|
+
- A write to `user-rules.md`, `user-rules.draft.md`, `MEMORY.md` or a file in the install's `memory/` or the shared `~/.config/geneseed/memory/` gets a prompt citing *Persist Insight*: whether something is a standing rule or a fact to remember is your call, settled through the `rule` [skill](skills.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 `rm` 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, scripts, `npm run`, variables, globs, subshell tricks, a folder removed above a listed file. So run the same checks in CI as the boundary that holds.
|
|
64
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.
|
|
65
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:
|
|
66
|
-
- 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` (its `… gate: off` markers), `.geneseed-manifest.json` and `.geneseed-emit
|
|
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` (its `… gate: off` markers), `.geneseed-manifest.json` and `.geneseed-emit`; and `excludes.json` in the machine-wide `~/.config/geneseed/` folder, the shared exclude list.
|
|
67
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`.
|
|
68
69
|
- The machine-wide hook shim in `~/.geneseed/bin/` (or `$GENESEED_HOME/bin/`).
|
|
69
70
|
- On OpenCode, also the install's `opencode.json(c)` and its own `plugins/geneseed-*.js`.
|
|
70
|
-
- **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
|
|
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`, `user-rules.draft.md` and `MEMORY.md` by name, the install's and the shared `memory/*.md`, 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.
|
|
71
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.
|
|
72
|
-
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.
|
|
73
|
-
- 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**. 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)).
|
|
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
|
+
- 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.
|
|
74
76
|
- Ordinary edits pass untouched.
|
|
75
77
|
|
|
76
|
-
**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
|
|
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)).
|
|
77
79
|
|
|
78
|
-
**learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries
|
|
80
|
+
**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:
|
|
79
81
|
|
|
80
82
|
```bash
|
|
81
83
|
export GENESEED_LLM="claude -p"
|
|
@@ -88,3 +90,17 @@ Unset, `learn` does nothing useful: on a real Stop/SubagentStop/PreCompact call
|
|
|
88
90
|
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.
|
|
89
91
|
|
|
90
92
|
What happens when a gate cannot decide, where the hooks are written, and the one file they all run through: [Hook gates, settings and the shim](hook-gates.md).
|
|
93
|
+
|
|
94
|
+
## The change report
|
|
95
|
+
|
|
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.**
|
|
97
|
+
|
|
98
|
+
| Host | Baseline | Approved means | You see |
|
|
99
|
+
| --- | --- | --- | --- |
|
|
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: a file-tool write is refused there, so any change is reported | a stderr line at Stop, in Bob's hook log |
|
|
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) |
|
|
103
|
+
|
|
104
|
+
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
|
+
|
|
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. An edit in the web console during a session is reported, because it is not logged. 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,7 +18,7 @@ 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
|
-
| Rule-or-memory write needs your call |
|
|
21
|
+
| Rule-or-memory 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
24
|
| MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
|
|
@@ -26,9 +26,9 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
|
|
|
26
26
|
|
|
27
27
|
✅ native · ⚙️ OpenCode plugin · 🔒 `permission` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
|
|
28
28
|
|
|
29
|
-
¹ **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,
|
|
29
|
+
¹ **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
30
|
² **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
|
|
31
|
+
³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so a rule-or-memory 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
32
|
⁴ 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
33
|
⁵ 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
34
|
|
package/docs/concepts/hosts.md
CHANGED
|
@@ -14,7 +14,7 @@ A **host** is the AI coding tool Geneseed installs into — OpenCode, Claude Cod
|
|
|
14
14
|
|
|
15
15
|
One build renders the same text for every host: the constitution ([rules](rules.md)), the {N_AGENTS} [agents](agents.md), the {N_SKILLS} [skills](skills.md), the [memory](memory.md) and [notebook](notebook.md) conventions, and the theme's voice. No host drops an agent, a skill or the memory convention.
|
|
16
16
|
|
|
17
|
-
Each host has a **global** install (in its config directory, active in every repo) and a **per-repo** install (inside one project). There is also a portable `files` bundle — a plain `Harness/` folder with an `AGENT.md` that any tool reading an instructions file can use, with no automation at all.
|
|
17
|
+
Each host has a **global** install (in its config directory, active in every repo) and a **per-repo** install (inside one project). There is also a portable `files` bundle — a plain `Harness/` folder with an `AGENT.md` that any tool reading an instructions file can use, with no automation at all. That file is `AGENT.md`, singular, and the bundle owns it. `AGENTS.md`, plural, is the cross-tool name that OpenCode, Bob and OpenClaude read; Claude Code reads it through an `@AGENTS.md` import in `CLAUDE.md`. This repository keeps its own guide in `AGENTS.md` that way.
|
|
18
18
|
|
|
19
19
|
## Two engines
|
|
20
20
|
|
package/docs/concepts/kits.md
CHANGED
|
@@ -59,7 +59,9 @@ An install with a kit on records it in its instructions file, under the skill se
|
|
|
59
59
|
|
|
60
60
|
`geneseed status` shows `kits: spring-boot` on the install's row, and `status --json` carries the same list.
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
Kits stay per install: the [shared tier](shared-tier.md) holds what you teach the agent, not what an install renders.
|
|
63
|
+
|
|
64
|
+
In the web console, the **Kits** page (`#/kits`) is the one home of the kit switches: a card per kit over a kits × installs matrix, disabled installs read-only. Toggling stages the set; **Apply** asks for confirmation, then rebuilds that one install with exactly that set as a console job (replace, not replay). Files you edited in a kit that is now off are kept, and the matrix lists them under their install so you can delete them by hand. A kit's page (`#/kits/<kit>`) shows its rules, banned APIs and upstream credits with the same per-install switch, and the Library tags each member skill or agent with a `kit:` badge.
|
|
63
65
|
|
|
64
66
|
### What a kit adds to an install
|
|
65
67
|
|
|
@@ -34,7 +34,7 @@ the repository.
|
|
|
34
34
|
|
|
35
35
|
## Java notes for the newer bricks
|
|
36
36
|
|
|
37
|
-
- **`mutation-check`** (`legacy-tests`) prefers PIT on a Maven build: `mvn test-compile
|
|
37
|
+
- **`mutation-check`** (`legacy-tests`, `bugfix`) prefers PIT on a Maven build: `mvn test-compile
|
|
38
38
|
org.pitest:pitest-maven:mutationCoverage -DtargetClasses=<fq.Class*>
|
|
39
39
|
-DreportsDirectory=<OS temp dir> -DtimestampedReports=false`, and needs `pitest-junit5-plugin`
|
|
40
40
|
on the classpath under JUnit 5; on Gradle, the `info.solidsoft.pitest` plugin's `pitest` task.
|