geneseed 4.25.1 → 4.27.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.
Files changed (97) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/DESIGN.md +6 -5
  3. package/README.md +10 -6
  4. package/SHIPPED.md +4 -3
  5. package/adapters/bob/README.md +26 -4
  6. package/adapters/claude-code/README.md +6 -2
  7. package/adapters/claude-code/skills/geneseed/SKILL.md +2 -2
  8. package/adapters/opencode/HOW-OPENCODE-LOADS.md +4 -2
  9. package/adapters/opencode/README.md +5 -2
  10. package/adapters/opencode/plugins/geneseed-activity.js +331 -31
  11. package/adapters/opencode/plugins/geneseed-guard.js +79 -4
  12. package/bin/geneseed-hook.mjs +13 -7
  13. package/docs/concepts/enforcement-table.md +12 -0
  14. package/docs/concepts/exclusions.md +15 -1
  15. package/docs/concepts/hook-gates.md +3 -2
  16. package/docs/concepts/hooks.md +12 -1
  17. package/docs/concepts/host-matrix.md +2 -2
  18. package/docs/concepts/ownership.md +79 -0
  19. package/docs/concepts/rules.md +1 -1
  20. package/docs/guides/set-up-ownership.md +77 -0
  21. package/docs/reference/glossary.md +1 -1
  22. package/docs/reference/opencode-plugins.md +1 -1
  23. package/docs/reference/plugin-activity.md +4 -2
  24. package/docs/reference/plugin-guard.md +1 -0
  25. package/docs/reference/troubleshoot-doctor.md +2 -2
  26. package/docs/understand/enforced-vs-asked.md +3 -2
  27. package/docs/understand/machine-bob.md +1 -1
  28. package/docs/understand/machine-claude.md +1 -1
  29. package/docs/understand/machine-opencode.md +2 -2
  30. package/docs/web-ui.md +21 -2
  31. package/harness.config.json +1 -1
  32. package/js/README.md +1 -0
  33. package/js/build/render.mjs +1 -1
  34. package/js/build/source.mjs +5 -1
  35. package/js/cli-table.json +46 -1
  36. package/js/hosts/activity.mjs +175 -30
  37. package/js/hosts/hooks-prims.mjs +2 -2
  38. package/js/hosts/hooks.mjs +45 -5
  39. package/js/hosts/ownership-gate.mjs +105 -0
  40. package/js/hosts/settings.mjs +14 -4
  41. package/js/inspect/cost.mjs +1 -1
  42. package/js/inspect/inventory.mjs +1 -1
  43. package/js/inspect/status.mjs +1 -1
  44. package/js/loop/registry.mjs +17 -0
  45. package/js/web/activity.mjs +116 -5
  46. package/package.json +1 -1
  47. package/registry.json +7 -0
  48. package/src/AGENT.md.tmpl +5 -0
  49. package/src/agents/developer.md +7 -1
  50. package/src/modes/foreman.md +4 -1
  51. package/src/ontology/universal.md +19 -0
  52. package/src/skills/_checkpoints.md +15 -0
  53. package/src/skills/develop.md +4 -0
  54. package/src/skills/document-project.md +2 -1
  55. package/src/skills/learn-mode.md +13 -17
  56. package/src/skills/ownership.md +139 -0
  57. package/src/skills/pipeline.md +1 -1
  58. package/themes/README.md +2 -2
  59. package/themes/_TEMPLATE.json +1 -0
  60. package/themes/biker.json +1 -0
  61. package/themes/commentator.json +1 -0
  62. package/themes/cyberpunk.json +1 -0
  63. package/themes/gamer.json +1 -0
  64. package/themes/imperial.json +1 -0
  65. package/themes/joker.json +1 -0
  66. package/themes/marvin.json +1 -0
  67. package/themes/mean.json +1 -0
  68. package/themes/military.json +1 -0
  69. package/themes/neutral.json +1 -0
  70. package/themes/pirate.json +1 -0
  71. package/themes/sports.json +1 -0
  72. package/themes/verstappen.json +1 -0
  73. package/themes/wizard.json +1 -0
  74. package/web/dist/assets/Activity-DfETiyWm.js +1 -0
  75. package/web/dist/assets/ActivityDetail-CnP3GPAN.js +1 -0
  76. package/web/dist/assets/Bonsai-CN4rRAHc.js +1 -0
  77. package/web/dist/assets/{CopyButton-B6myFV7a.js → CopyButton-CRAUXSG7.js} +1 -1
  78. package/web/dist/assets/{Dashboard-DEQCBcUW.js → Dashboard-CaqOqtkG.js} +2 -2
  79. package/web/dist/assets/Docs-BFxyAVdN.js +5 -0
  80. package/web/dist/assets/{GreenhouseView-CV1squu6.js → GreenhouseView-19roNb5W.js} +1 -1
  81. package/web/dist/assets/{Installs-C4TQVZ_-.js → Installs-BSoQN7w7.js} +3 -3
  82. package/web/dist/assets/{JournalView-CpXsT_JD.js → JournalView-BgU2ybaq.js} +1 -1
  83. package/web/dist/assets/{KitApply-fYh_YjQA.js → KitApply-Ckc0P5kt.js} +1 -1
  84. package/web/dist/assets/{Kits-BMuGOiTg.js → Kits-BZqWGWMu.js} +1 -1
  85. package/web/dist/assets/Laws-CnUWiNIx.js +3 -0
  86. package/web/dist/assets/{Library-DiZqRFL5.js → Library-rYO8owx_.js} +2 -2
  87. package/web/dist/assets/{Loops-DkwWkdPc.js → Loops-CljFhhQV.js} +2 -2
  88. package/web/dist/assets/{OperatorHudView-CLmq0lNh.js → OperatorHudView-xs7SCwCe.js} +1 -1
  89. package/web/dist/assets/{Personal-C70XacpA.js → Personal-CMPwtl36.js} +2 -2
  90. package/web/dist/assets/{Tabs-ChFhPGP6.js → Tabs-CEfSUVQp.js} +1 -1
  91. package/web/dist/assets/{index-DxCqnFPy.js → index-FLVXXvV3.js} +2 -2
  92. package/web/dist/assets/{index-Cqqs-PbJ.css → index-XTGBLKQr.css} +1 -1
  93. package/web/dist/index.html +2 -2
  94. package/web/dist/assets/Activity-BdMwEnFN.js +0 -1
  95. package/web/dist/assets/ActivityDetail-BgUjDuxO.js +0 -1
  96. package/web/dist/assets/Docs-ChBYcQbT.js +0 -5
  97. package/web/dist/assets/Laws-ndHW7Onu.js +0 -3
@@ -82,13 +82,19 @@ const VERBS = {
82
82
  switches: { '--no-consent': 'noConsent', '--no-deletion-gate': 'noDeletionGate' },
83
83
  },
84
84
  'rule-gate': {
85
- load: gates, fn: 'cmdRuleGate', flags: HOSTED, switches: { '--no-secrets-gate': 'noSecretsGate' },
85
+ load: gates,
86
+ fn: 'cmdRuleGate',
87
+ flags: HOSTED,
88
+ switches: { '--no-secrets-gate': 'noSecretsGate', '--no-ownership-gate': 'noOwnershipGate' },
86
89
  },
87
90
  'tool-gate': {
88
91
  load: gates,
89
92
  fn: 'cmdToolGate',
90
93
  flags: HOSTED,
91
- switches: { '--no-deletion-gate': 'noDeletionGate', '--no-secrets-gate': 'noSecretsGate' },
94
+ switches: {
95
+ '--no-deletion-gate': 'noDeletionGate', '--no-secrets-gate': 'noSecretsGate',
96
+ '--no-ownership-gate': 'noOwnershipGate',
97
+ },
92
98
  },
93
99
  learn: {
94
100
  load: () => import('../js/hosts/hooks-learn.mjs'),
@@ -118,10 +124,10 @@ async function trackActivity(verb, args) {
118
124
  const root = verb === 'learn' ? (args.memory && !args.file ? path.dirname(args.memory) : null)
119
125
  : args.root;
120
126
  if (!root || process.env.GENESEED_LEARN_CHILD || isatty(0) || !activityOn(root)) return;
121
- // `context` never read stdin before this writer, and whether Bob's SessionStart pipes one
122
- // and closes it is unverified: a read there could hold the session's start. A Bob session
123
- // is first recorded by its first prompt or tool call instead.
124
- if (verb === 'context' && args.host === 'bob') return;
127
+ // `context` never read stdin before this writer. On Bob that read is safe: Bob 2.2.3's hook
128
+ // runner writes the payload and closes stdin for every event (`stdin.end(JSON.stringify(...))`
129
+ // in its bundle), so the read returns at once. The writer keeps only a Bob SessionStart that
130
+ // reports a compaction (`applyHookEvent`).
125
131
  const raw = readStdin();
126
132
  if (!raw.includes('session_id')) return;
127
133
  const { recordActivity } = await import('../js/hosts/activity.mjs');
@@ -144,7 +150,7 @@ function die(code, msg) {
144
150
  function parse(spec, argv) {
145
151
  const args = {
146
152
  root: null, host: null, memory: null, consolidate: false, noConsent: false,
147
- noDeletionGate: false, noSecretsGate: false, noDoneGate: false, file: null,
153
+ noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false, file: null,
148
154
  };
149
155
  for (let i = 0; i < argv.length; i += 1) {
150
156
  const tok = argv[i];
@@ -38,6 +38,18 @@ mechanisms: its own permission prompt (`opencode.json`, static globs) and the gu
38
38
  See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) for why a gate that only
39
39
  one host can run still ships for every host it can.
40
40
 
41
+ ### Not a rule: the ownership gate
42
+
43
+ The [ownership](ownership.md) first-write gate enforces the Credo's Ownership section, not a law
44
+ or doctrine rule, so it has no id above. In an application repo whose root `AGENTS.md` has no
45
+ `## Ownership` section, it refuses the session's first write once; the reason goes to the agent,
46
+ and the next write passes. Off per repo with `mode: off`, per install with
47
+ `--no-ownership-gate` ([Exclusions](exclusions.md)).
48
+
49
+ | Gate | Claude Code | OpenClaude | OpenCode | Bob |
50
+ |---|---|---|---|---|
51
+ | 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) |
52
+
41
53
  A gate that is registered but broken looks exactly like a working one. `geneseed doctor --probe`
42
54
  runs the installed Claude Code, OpenClaude and Bob gates through each host's own shell, and calls
43
55
  the OpenCode guard plugin in-process, on one call each must refuse and one it must let through
@@ -7,7 +7,7 @@ section: "Configuration"
7
7
  description: "Three ways to switch things off: one rule, one skill, or every hook in a folder."
8
8
  link: {"hash": "#/harness", "label": "Manage in Harness →"}
9
9
  ---
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, below):
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
 
12
12
  | | Sovereign repo | Per-rule exclusion | Per-skill exclusion |
13
13
  | --- | --- | --- | --- |
@@ -104,3 +104,17 @@ What stops, per host:
104
104
  - **`--no-done-gate`**: the done check `learn` runs on Stop (Claude Code, OpenClaude; on Bob, the "turn not judged" log line), and on OpenCode the context plugin's reminder (OpenCode 1) and its one-line notice (OpenCode 2). Learning itself still runs, and `.geneseed/done-checks.txt` stays protected by *External Gate*.
105
105
 
106
106
  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
+
108
+ ### Ownership gate — on or off
109
+
110
+ 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:
111
+
112
+ ```bash
113
+ geneseed build --emit claude-global --no-ownership-gate
114
+ ```
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 no switch for it, because it has no Rule row. What stops: the ownership check of `rule-gate` (Claude Code, OpenClaude) and of `tool-gate` (Bob), and on OpenCode the guard plugin's ownership refusal. A repo with `mode: on` still runs the ownership checkpoints, and every other check of those gates stays.
117
+
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 answering "proceed without" lets the session write on.
119
+
120
+ Limits, as for the gates above: OpenCode reads the marker from `AGENT.md` when it starts, so restart it after a rebuild. A global install's `rule-gate` does not stand down for a project install, so an armed global gate still stops the first write inside a project built `--no-ownership-gate`. And while the machine's hook shim points at an older checkout, that checkout refuses the flag and the gate verb lets every call through on a disarmed install — on Claude Code and OpenClaude all of `rule-gate` (the credential scan, *Persist Insight* and *External Gate* too), on Bob all of `tool-gate` (credentials, destructive git, the root scan and the protected checks too). Run `geneseed rebuild-all` first.
@@ -34,11 +34,12 @@ The merge is surgical. Every other key and every hook of your own survive, and t
34
34
 
35
35
  **OpenClaude** is a Claude Code fork: it gets the same hooks and the same prompts, unchanged.
36
36
 
37
- **Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher, `SubagentStop` or `PreCompact`. So Bob gets three hooks:
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, and a write under a project's own protected-checks list. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all.
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, and a write under a project's own protected-checks list. 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
+ - `UserPromptSubmit` → `geneseed-hook activity`, which records the turn for the Activity view.
42
43
 
43
44
  Neither host has been verified live on the authoring machine. If a hook does not fire, the same rules still reach the agent through the instructions file.
44
45
 
@@ -18,15 +18,25 @@ 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 or memory | no |
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
22
  | `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into `memory/` | needs `GENESEED_LLM` |
23
23
  | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in `memory/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` |
27
+ | `SubagentStart` | a subagent starts | `geneseed-hook activity` | records the subagent as a branch of its session, even one that only reads | off with `GENESEED_ACTIVITY=off` |
27
28
 
28
29
  Every hook above also feeds the [Activity view](../reference/plugin-activity.md) after it has decided, unless tracking is off: one file per session under `activity/` beside the install. The gates' verdicts never wait on it.
29
30
 
31
+ What that file holds for the Activity garden:
32
+ - **Files.** Each changed file is stored relative to the session's git root, with `/` separators. A file outside the root, or a session outside any repo, gets no path (`path: null`) and keeps only its basename, so it never matches a file of the same name inside the repo. A path is never stored absolute. Each file also records who changed it: the session, or the subagent's `agent_id`.
33
+ - **Where the session runs.** `root` is the worktree's git root and `repo` is the main repository's root, so the linked worktrees of one repo can be grouped together. Only the session's own events set them; a subagent working in another worktree does not move them.
34
+ - **Subagents.** `agents` lists each subagent with its type and `running` or `done`.
35
+ - **Turns and context.** `turns` counts your prompts. `context` is the size of the context now, taken from the transcript's last assistant message. The window size is an estimate: 200k, or 1M once the context is past 200k.
36
+ - **Compactions.** `compactions`, `compacted_at` and `context_at_compaction` record each compaction (on `PreCompact`). After a compaction, `context` is unknown (`null`) until the next `Stop` reads it again. Claude Code's `<synthetic>` messages and messages with no input-side tokens never change it.
37
+
38
+ On Bob, a subagent's files cannot be told apart from its session's files (its hook payloads carry no subagent id), so the session is marked `attribution: false`. A compaction is counted on Bob's `SessionStart` with `source: "compact"`, and there is no context size.
39
+
30
40
  ## What each one does, and what you see
31
41
 
32
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`. Each file is capped at 16 KB and the whole injection at 48 KB; what does not fit is listed for the agent to read on demand. You see nothing, except that the agent already knows your project. See [Project context](../guides/project-context.md).
@@ -52,6 +62,7 @@ Every hook above also feeds the [Activity view](../reference/plugin-activity.md)
52
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).
53
63
  - A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). A project opts in with `.geneseed/protected-checks.txt` at its git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A check the agent can edit is not a check. The list protects itself. Only file-write tools are seen: a shell `sed -i` or redirect is not, so run the same checks in CI as the boundary that holds.
54
64
  - 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
+ - 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 or proceed without (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, per install with `--no-ownership-gate` ([Ownership](ownership.md), [Exclusions](exclusions.md)).
55
66
  - Ordinary edits pass untouched.
56
67
 
57
68
  **The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. A project opts in with `.geneseed/done-checks.txt` at its git root: one command per line, `#` for comments — the checks that prove the work, for example `npm run lint` and `node --test`. 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*. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), 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 seen. Without the file, nothing changes. On OpenCode the gate is a reminder on the next request (OpenCode 1 only); on Bob, whose Stop carries no transcript, the turn is not judged and 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)).
@@ -14,7 +14,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
14
14
  | Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
15
15
  | Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
16
16
  | Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
17
- | Live sessions in the web console's [Activity view](../reference/plugin-activity.md) | ⚙️ plugin | 🪝 hook | 🪝 hook, per tool call only (no transcript)¹ | 🪝 hook² |
17
+ | Live sessions in the web console's [Activity view](../reference/plugin-activity.md) | ⚙️ plugin | 🪝 hook, files per subagent, context size | 🪝 hook, per tool call only (no transcript, no context size, subagent files not attributed)¹ | 🪝 hook, files per subagent, context size² |
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² |
@@ -26,7 +26,7 @@ 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, and a write under a project's own protected-checks list — and turns the two consent checks into a logged warning. It has no `SubagentStop` or `PreCompact` event, so learn runs on `Stop` only. **Unverified live** — there is no Bob install on the authoring machine; the rules preamble still holds if a hook does not fire.
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, and a write under a project's own protected-checks list — 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
31
  ³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so the rule-or-memory check stops the first such write once rather than prompting, and a real data loss is blocked outright (as on Bob) rather than asked; `GENESEED_GUARD=warn` turns the 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.
@@ -0,0 +1,79 @@
1
+ ---
2
+ group: concepts
3
+ order: 17
4
+ title: "Ownership"
5
+ kind: "concept"
6
+ section: "Working together"
7
+ description: "The developer decides each part of production code, at a granularity the team sets."
8
+ ---
9
+ **Ownership** keeps the developer the author of production code. The agent proposes options, interfaces and placements; the developer decides each part, at a granularity the team chooses, and can answer for every line that lands.
10
+
11
+ > **You already know this:** pair programming where you hold the keyboard rights. Your partner suggests, explains the hard parts and types what you approve — but you must be able to defend every change in review without them.
12
+
13
+ ## Why
14
+
15
+ The Credo carries an **Ownership** section, always in force: the code belongs to whoever will answer for it — the developer who ships it, the team that maintains it — never to the agent that typed it. Work is handed over only when the developer can say what changed, where and why. Approval without understanding is not ownership, so a genuinely complex part is explained before it lands, unasked.
16
+
17
+ The `ownership` [skill](skills.md) carries the procedure; a repository switches it on for its team.
18
+
19
+ ## The `## Ownership` section
20
+
21
+ The team's settings live in the committed root `AGENTS.md`, the cross-tool rules file, outside any `<!-- BEGIN GENESEED -->` block:
22
+
23
+ ```markdown
24
+ ## Ownership
25
+
26
+ mode: on # on | off
27
+ granularity: file # feature | file | function — the team default
28
+ sensitive: # always a checkpoint, whatever the granularity
29
+ - src/main/java/**/payment/**
30
+ - src/main/resources/db/migration/**
31
+ ```
32
+
33
+ The rest of `AGENTS.md` holds the project's coding rules: conventions, build and test commands, project rules. Each developer's own state — a finer granularity, the pending checkpoint, the log of decisions — lives in the git-ignored `.geneseed/ownership.md`. [Set up ownership](../guides/set-up-ownership.md) walks through writing both.
34
+
35
+ ## Granularity
36
+
37
+ - **`feature`** — one checkpoint on the plan, then each file is announced and its edit is the approval.
38
+ - **`file`** — the default: one checkpoint per file.
39
+ - **`function`** — the signature, then the body.
40
+
41
+ Whatever the level, an **interface is always a checkpoint** — a public signature, an API contract, a database schema, a new dependency — and so is every change in a `sensitive:` zone. The developer can change the level for the current task at any moment ("go finer here", "do the rest in one go"); the file keeps its default.
42
+
43
+ On complex code (business branching, transactions, concurrency, security) the agent goes finer by itself and explains why; on trivial code it may only *propose* a coarser batch. It announces routine steps — the host's diff prompt is the approval — and asks only at a real fork, recommended option first.
44
+
45
+ ## The first-write gate
46
+
47
+ On every host, a hook stops the first write in an application that has not decided yet:
48
+
49
+ - **Where.** An *application repo*: a git root holding a build manifest — `package.json`, `pom.xml`, `build.gradle*`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `*.csproj`, `composer.json` or `Gemfile`. A folder with no git or no manifest is never gated.
50
+ - **When.** Its root `AGENTS.md` has no `## Ownership` heading outside Geneseed's managed block. The heading with `mode: on` or `mode: off` both count: the team has decided.
51
+ - **What.** The first Write, Edit or NotebookEdit of the session in that repo is refused once. The refusal's reason goes to the agent, which then asks you: set ownership up, or proceed without for this session. The next write passes. Writes to `AGENTS.md` and `.geneseed/` themselves always pass.
52
+ - **What it skips.** Sub-agents defer on Claude Code and OpenClaude, which name them in the hook's input, and on OpenCode, whose guard sees that the session has a parent: a sub-agent cannot ask you, so it never spends the session's one stop. Shell writes are not seen; the line in the harness file covers them.
53
+
54
+ Per host: Claude Code and OpenClaude deny the call with the reason; Bob refuses it with exit 2, once; OpenCode's guard plugin refuses it. See [Hooks](hooks.md) and [Rule enforcement, by host](enforcement-table.md).
55
+
56
+ ## Turning it off
57
+
58
+ | Scope | How | Lasts |
59
+ | --- | --- | --- |
60
+ | One session | Answer "proceed without" when the agent asks | This session; it asks again in the next one |
61
+ | One repo | `## Ownership` with `mode: off` in the root `AGENTS.md` | Until the line changes; travels with the repo |
62
+ | One install | Rebuild with `--no-ownership-gate` ([Exclusions](exclusions.md)) | Every rebuild replays it |
63
+
64
+ The per-install switch stops only the gate. A repo with `mode: on` still runs the ownership checkpoints, and the Credo section still binds.
65
+
66
+ ## learn-mode comes first
67
+
68
+ While `.geneseed/learn.md` says `Learning mode: active`, learn-mode drives the flow. It is the developer's personal choice, and no project can forbid a developer from learning. The team's `AGENTS.md` rules still apply on top: conventions, and interfaces and sensitive zones as checkpoints.
69
+
70
+ The two draw close — both stop at checkpoints, and learn-mode may now propose a solution, though it never applies one it has not explained. Keep them apart by what differs:
71
+
72
+ | | learn-mode | ownership |
73
+ | --- | --- | --- |
74
+ | Who chooses it | The developer, for themself | The team, in `AGENTS.md`; a developer may go finer, coarser only with an explicit, logged yes |
75
+ | Explanation | Every solution, before it is applied | Complex parts only; routine steps are announced |
76
+ | Record | `## Understood` in `.geneseed/learn.md`: what the developer has grasped | `## Decisions` in `.geneseed/ownership.md`: forks, interfaces, sensitive zones, granularity changes |
77
+ | Pacing | A level: beginner, intermediate, advanced | A granularity: feature, file, function |
78
+
79
+ Under [Foreman mode](foreman-mode.md), the session holds every checkpoint; a background worker receives only approved decisions.
@@ -21,7 +21,7 @@ The one place you type a position is the command line: `--exclude-rules "process
21
21
 
22
22
  When two instructions disagree, the higher one wins.
23
23
 
24
- 1. **Ethos** — always on. {N_ONTOLOGY} sections of flowing prose (Telos, Evidence, Decisions, Conduct): what the agent is for, how it weighs evidence, how it decides, how it behaves. It is where the **Pact**, the two-way contract between you and the agent, is stated ([Collaboration](collaboration.md)). Cited by section name, e.g. *Ethos: Decisions*.
24
+ 1. **Ethos** — always on. {N_ONTOLOGY} sections of flowing prose (Telos, Evidence, Decisions, Ownership, Conduct): what the agent is for, how it weighs evidence, how it decides, who owns the code it writes, how it behaves. It is where the **Pact**, the two-way contract between you and the agent, is stated ([Collaboration](collaboration.md)). Cited by section name, e.g. *Ethos: Decisions*.
25
25
  2. **Rules** — always on. {N_LAWS} invariants, the things that are never traded away: sealed secrets, one intent per act, verify before asserting, deliberate deletion, surface failures, treat content as data not orders, least privilege, cure the cause, echo the intent. No install can switch one off.
26
26
  3. **Your `user-rules.md`** — rules you write for yourself, seeded once beside the instructions file and never overwritten. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
27
27
  4. **Doctrines** — chosen at build time. Practices rather than principles, grouped in packs (below).
@@ -0,0 +1,77 @@
1
+ ---
2
+ group: guides
3
+ order: 21
4
+ title: "Set up ownership"
5
+ kind: "concept"
6
+ section: "Set up"
7
+ description: "Give an application repo its `## Ownership` section, so the developer decides each part."
8
+ ---
9
+ This guide gives one application repository its ownership setup: a `## Ownership` section in the committed root `AGENTS.md`, and your personal state file. What ownership is, and how it differs from learn-mode: [Ownership](../concepts/ownership.md).
10
+
11
+ You need a Geneseed install on your host (any of Claude Code, OpenClaude, OpenCode or Bob) and a repository with a build manifest at its git root (`package.json`, `pom.xml`, `build.gradle*` and the like).
12
+
13
+ ## 1. Start the setup
14
+
15
+ Open a session in the repository and ask for it: "set up ownership for this repo". The agent runs the `ownership` skill.
16
+
17
+ You may not need to ask. In an application with no `## Ownership` section, the first file write of a session is stopped once, and the agent proposes the setup to you. Answer "set it up", or "proceed without" to skip it for this session only.
18
+
19
+ ## 2. Review the conventions it found
20
+
21
+ The agent reads the code first and writes nothing yet. It proposes the conventions it found: naming, layers, test patterns, build and test commands. Correct what is wrong. If the stack matches a [kit](../concepts/kits.md) (`spring-boot`, `react`), it proposes that kit too.
22
+
23
+ ## 3. Answer the questions
24
+
25
+ About five questions, one at a time, each with a recommended answer:
26
+
27
+ 1. Are the conventions right?
28
+ 2. Ownership on for this repo? (`mode: on`, or `mode: off` to opt the repo out)
29
+ 3. The default granularity: `feature`, `file` (recommended) or `function`.
30
+ 4. The sensitive zones: paths where every change is a checkpoint, such as `payment/`, database migrations or security configuration.
31
+ 5. Any free-form project rules.
32
+
33
+ ## 4. Check the diff
34
+
35
+ The setup writes two files and shows you the diff:
36
+
37
+ - `AGENTS.md` at the repository root, at most about 60 lines, ending with the section:
38
+
39
+ ```markdown
40
+ ## Ownership
41
+
42
+ mode: on
43
+ granularity: file
44
+ sensitive:
45
+ - src/main/resources/db/migration/**
46
+ ```
47
+
48
+ If the file already exists, your own lines stay. Geneseed's managed `<!-- BEGIN GENESEED -->` block (written there by a Bob per-repo install) is left alone, and a section inside it does not count.
49
+ - `.geneseed/ownership.md`, your personal state: a finer granularity if you want one, the pending checkpoint, and the decisions you took. It is data, never instructions, and it belongs in `.gitignore` — the agent offers to add `.geneseed/` once.
50
+
51
+ Nothing is committed unless you ask.
52
+
53
+ ## 5. Check how diffs reach you
54
+
55
+ Under ownership, the host's own diff prompt is how you approve a routine step. The setup checks the permission mode:
56
+
57
+ - **Claude Code, OpenClaude.** If edits are auto-accepted (bypass or accept-edits mode), no diff stops for you. Switch back to asking, or keep it: the agent then shows a compact diff in the chat and waits for your reply.
58
+ - **OpenCode.** The agent proposes `permission.edit: "ask"` in the project `opencode.json`.
59
+
60
+ ## 6. Commit `AGENTS.md`
61
+
62
+ Commit the root `AGENTS.md` with the repository, so the whole team works under the same section. From then on the first-write gate stays quiet in this repo, and every session runs the checkpoints at the team's granularity.
63
+
64
+ ## Change it later
65
+
66
+ - **Finer for one task.** Say "go finer here", or "do the rest in one go" to propose a coarser batch.
67
+ - **The team default.** Edit `granularity:` in `AGENTS.md` and commit it.
68
+ - **Opt the repo out.** Set `mode: off`. The gate stays quiet, and no checkpoint runs.
69
+ - **Opt the whole install out of the gate.** Rebuild with the flag, as [Exclusions](../concepts/exclusions.md) shows:
70
+
71
+ ```bash
72
+ geneseed build --emit claude-global --no-ownership-gate
73
+ ```
74
+
75
+ ## Verify
76
+
77
+ In a fresh session, ask for a small change in the repository. The agent should announce the file it will touch, or ask at a real fork, before the edit — and the first write should pass without the gate stopping it.
@@ -12,7 +12,7 @@ Every word Geneseed uses that you would not find in a general programming glossa
12
12
  |---|---|---|---|
13
13
  | Harness | — | everything Geneseed installs around the model: the rules it loads, the gates that run before its actions, the workflows it can call | git hooks + CI + a runbook, for an agent |
14
14
  | Hook | — | a command your tool runs before or after an agent action; Geneseed's hooks gate risky actions and load context | a git hook, fired on every tool call |
15
- | Ethos (Ontology) | ONTOLOGY | the always-on worldview under the rules — telos, evidence, decisions, conduct; it holds the Pact | the team's engineering principles |
15
+ | Ethos (Ontology) | ONTOLOGY | the always-on worldview under the rules — telos, evidence, decisions, ownership, conduct; it holds the Pact | the team's engineering principles |
16
16
  | Rule (Law) | LAW | one of the nine always-on invariants: what is never done | a lint rule set to error |
17
17
  | Rules (Laws) | LAWS | the body of always-on invariants | the error-level rule set |
18
18
  | Doctrine | DOCTRINE | one practice rule, cited `<pack> <n>` — how work is done here | a team convention in CONTRIBUTING.md |
@@ -19,7 +19,7 @@ Every plugin swallows its own errors — none can block or crash a session. Each
19
19
  The same files work on OpenCode 1 (1.3.4 or newer) and OpenCode 2. OpenCode 2 rewrote the plugin API, and each plugin carries both halves. You don't need to configure anything. Two differences show on OpenCode 2:
20
20
 
21
21
  - **A guard block shows up as a failed tool call.** The call never runs. The model gets an error that starts with `[geneseed-guard] blocked:` and gives the reason.
22
- - **The Activity view shows no todo list or files-touched count.** OpenCode 2 publishes no event for either.
22
+ - **The Activity view shows no todo list, and files touched have no line counts.** OpenCode 2 publishes no todo event. It names the files each step changed, but not how many lines, and an undo does not remove a file from the list.
23
23
 
24
24
  If a plugin seems silent on OpenCode 2, check that `~/.config/opencode/plugins/` holds the current files. Copies from before this change fail to load with *"Plugin must export a default definition with an id and an effect or setup function"*. Running `geneseed rebuild-all` replaces them.
25
25
 
@@ -10,12 +10,14 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
10
10
 
11
11
  **What it does.** Feeds the web console's **Activity** view: one small JSON file per session under `activity/` beside OpenCode's config, recording what the session is doing — phase, model, token and cost totals, files touched, plan, last error. The console only reads those files; the two only meet on disk, so a crash on either side never blocks a session.
12
12
 
13
- **When it runs.** On session events, for top-level sessions only (sub-agents and learn's sessions are skipped). A session whose process died, went stale (30 minutes untouched) or ended leaves the live list and is listed as ended; the reader never deletes a file.
13
+ **When it runs.** On session events. A sub-agent's child session (one with a `parentID`) is folded into its root session: it becomes an `agents[]` row (`{id, type, status: "running" | "done"}`, the child's id and agent), and its files join the root's `files` with `by` set to the child's id. Only learn's throwaway `geneseed-*` sessions are skipped. On OpenCode 2 the files come from `session.step.ended`, which carries no line counts, so those read `null`. A session whose process died, went stale (30 minutes untouched) or ended leaves the live list and is listed as ended; the reader never deletes a file.
14
14
 
15
- **Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `SessionEnd`. So a Claude session's phase moves on the gated tools (`Bash`, `PowerShell`, `Write`, `Edit`, `NotebookEdit`, `Skill`, `Agent`, `Task`), and the rest of the turn — every tool call, the model, the token totals, the last reply — arrives at `Stop`, read from the transcript where the previous `Stop` left off (at most 2 MB per turn). Bob sends no transcript, so a Bob session shows only the calls its `tool-gate` sees, and leaves the live list by staleness alone (Bob has no `SessionEnd`). Bob's `SessionStart` is not recorded either — whether Bob pipes a payload there is unverified, and reading one that never closes would hold the session's start — so a Bob session first appears at its first prompt or tool call. These writers have no resident process, so their snapshots carry `pid: null` and stay live by staleness alone. Recorded: tool names, file basenames, line counts, todo text, and 240-character snippets of the prompt and the last reply — never a shell command, a file's content or an edit's text — and any credential the secrets gate would catch in a snippet is written as `[redacted]`. A project install's `activity/` gets its own `.gitignore` (`*`), and the writer never writes through, or sweeps, an `activity/` or `activity/archive/` that is a link. Nothing is recorded in a repo listed in `excludes.json`, or inside a model CLI that `learn` started.
15
+ **Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `SessionEnd` and `SubagentStart`. So a Claude session's phase moves on the gated tools (`Bash`, `PowerShell`, `Write`, `Edit`, `NotebookEdit`, `Skill`, `Agent`, `Task`), and the rest of the turn — every tool call, the model, the token totals, the last reply — arrives at `Stop`, read from the transcript where the previous `Stop` left off (at most 2 MB per turn). Bob sends no transcript, so a Bob session shows only the calls its `tool-gate` sees, and leaves the live list by staleness alone (Bob has no `SessionEnd`). Bob's `SessionStart` is recorded only after a compaction (`source: "compact"`, counted as one): a startup or resume fires just before the first prompt, which records the session anyway. Bob 2.2.3 writes every hook's payload to stdin and closes it, so reading it there is safe. These writers have no resident process, so their snapshots carry `pid: null` and stay live by staleness alone. Recorded: tool names, each changed file's path relative to the session's git root (a file outside the root, or a session outside any repo, keeps its basename only; a path is never stored absolute; labels show basenames), who changed it (the session or a subagent's `agent_id`), the subagents, the prompt count, the context size and the compactions, line counts, todo text, and 240-character snippets of the prompt and the last reply — never a shell command, a file's content or an edit's text — and any credential the secrets gate would catch in a snippet is written as `[redacted]`. A project install's `activity/` gets its own `.gitignore` (`*`), and the writer never writes through, or sweeps, an `activity/` or `activity/archive/` that is a link. Nothing is recorded in a repo listed in `excludes.json`, or inside a model CLI that `learn` started.
16
16
 
17
17
  **Archive.** On `SessionStart` and `SessionEnd` the hook writer moves every snapshot that is no longer live into `activity/archive/`, keeping the newest 50 and none older than 7 days. `/api/activity` returns them, with the stale and dead ones still in `activity/`, in its `ended` list — capped there by the same rule, since the OpenCode plugin never sweeps.
18
18
 
19
+ **What `/api/activity` returns.** `activity` (the live sessions), `ended`, and `collisions`. Each session carries the snapshot as written, plus the v2 fields: `root` (the worktree's git root), `repo` (its main worktree), `agents` (`{id, type, status, started}`), `attribution` (`false` only on a Bob session that ran a sub-agent, else `null`), `turns`, `context` (`{used, window}`), `compactions`, `compacted_at` and `context_at_compaction` (either `context` field can be `null`, right after a compaction for one), and `repo_key`, the repo (else the root) case-folded on Windows, to group a repo's sessions whatever case each host spelled it in. A v1 snapshot reads `null` for those, `[]` for `agents` and `0` for the counts. A live session also gets `files_all`, the uncapped file rows from its detail file (`files` stays the capped summary), and `loops`: `{title, iteration, status}` for each loop registered on its `root`, a finished or unreadable loop left out. `collisions` lists each `{repo, path}` that two or more writers changed among the live sessions — a writer is a session or one of its sub-agents (`{sid, by, root}`) — with `kind: "same-worktree"` when two of them share a `root`, else `"cross-worktree"`. A file outside the root is stored with `path: null` (its `file` keeps the basename) and takes no part in a collision. Roots and paths compare case-folded on Windows, and a session root is resolved to its real path before the loop join, as the loop registry stores it. `/api/activity/<id>` returns the same fields for one session, an archived one included.
20
+
19
21
  **What you see.** A card per live session in **Activity** (`geneseed web`).
20
22
 
21
23
  **Switches.**
@@ -11,6 +11,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
11
11
  **What it does.** Enforces the safety rules at the tool boundary — before a tool call runs, not after. High-confidence patterns only, so legitimate work is not caught.
12
12
 
13
13
  - **Blocks** writes to private-key and credential files and writes whose content carries a credential (*Sealed Secrets*; an install built `--no-secrets-gate` carries `Secrets gate: off` in its `AGENT.md`, read once at load, and both stop blocking), catastrophic shell commands such as deleting the filesystem root and every command that would really lose data — a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, a protected branch force-moved off commits nothing else holds, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, files git cannot restore removed — judged against the repository's state, the same decisions the Claude/Bob hook makes (*Deletion Is Deliberate*; `reflog expire` and `gc --prune` are left to the `permission.bash` ask; an install built `--no-deletion-gate` carries `Deletion gate: off` in its `AGENT.md`, which the plugin reads once at load and then stops blocking real loss — catastrophic commands still block), a recursive scan rooted at a whole filesystem such as `find /` (*Commands Must Return* — search a specific directory instead), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `geneseed-wiki.jsonc`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)).
14
+ - **Refuses once** 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, so the agent proposes the [ownership](../concepts/ownership.md) setup first; the next write passes, and a sub-agent's session never triggers it. Off per repo with `mode: off` in that section; an install built `--no-ownership-gate` carries `Ownership gate: off` in its `AGENT.md`, read once at load.
14
15
  - **Warns** (logged, allowed) on `.env` writes.
15
16
  - **Speed-bumps** the *first* write to `user-rules.md` or a memory file: it is refused once, naming *Persist Insight* — whether something is a standing rule or a fact to remember is your call, settled through the `rule` skill. The re-issued write goes through.
16
17
 
@@ -43,8 +43,8 @@ These come only from `geneseed doctor --probe`. It runs each installed gate exac
43
43
  settings spell it, through the host's own shell, on `git reflog expire --expire=now --all` (which must be refused)
44
44
  and `git status` (which must go through). A gate wired with `--no-deletion-gate` lets the first one
45
45
  through by design, so it is probed on `find / -name geneseed-probe` instead — a root-wide scan it
46
- must still refuse. `--no-secrets-gate` and `--no-done-gate` change nothing here: neither judges a
47
- shell command. An OpenCode install's guard plugin has no command to
46
+ must still refuse. `--no-secrets-gate`, `--no-done-gate` and `--no-ownership-gate` change nothing here: none
47
+ judges a shell command. An OpenCode install's guard plugin has no command to
48
48
  run: the probe imports it and calls its hook through both plugin APIs (V1 and V2), with `rm -rf /`
49
49
  as the call it must refuse. `GENESEED_GUARD=off` or `warn` in your terminal makes that a note,
50
50
  not a failure.
@@ -27,11 +27,12 @@ On Claude Code and OpenClaude the hooks never block silently. They make the host
27
27
  - **A scan of a whole filesystem**: a recursive `find`, `du`, `grep -r`, `rg` or `Get-ChildItem -Recurse` rooted at `/`, `/c` or `C:\`, which in Git Bash walks every drive for hours. Wired in every build.
28
28
  - **Credentials**: a write or edit whose content looks like a real key (AWS, GitHub, Anthropic, Slack, or a private-key block), anywhere except a `.env` file.
29
29
  - **Your rules and memory**: any write by the agent to `user-rules.md` or to the memory store. Whether something is a standing rule or a fact to remember is your call.
30
+ - **The first write in an application with no ownership setup**: in a repo with a build manifest whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused once, with the reason sent to the agent rather than to you: it then asks you to set [ownership](../concepts/ownership.md) up or proceed without. Off per repo with `mode: off`, per install with `--no-ownership-gate`.
30
31
  - **Ending a turn without the proof**: only in a project that lists its checks in `.geneseed/done-checks.txt`. A turn that edited files cannot end until every listed check has passed since the last edit. The agent is stopped once, then the turn may end.
31
32
 
32
33
  If a gate crashes, it asks instead of letting the call through. If it cannot start at all (a deleted or broken shim) or times out, Claude Code blocks the call instead: see [Troubleshoot hooks](../reference/troubleshoot-hooks.md) to recover. Other shell commands go through Claude Code's normal permission flow; an `rm` of files git cannot restore is the real-loss case above.
33
34
 
34
- **Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for the rules that admit no judgement call: credentials, destructive git, a scan of a whole filesystem, and a write under a project's own protected-checks list. The commit/push and memory checks become a log line, and the call goes through. Bob's hook wiring follows its documentation but has not been tested on a live Bob install.
35
+ **Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for the rules that admit no judgement call: credentials, destructive git, a scan of a whole filesystem, and a write under a project's own protected-checks list. The commit/push and memory checks become a log line, and the call goes through. The ownership gate also refuses with exit 2, but once: the same write passes after you answer. Bob's hook wiring follows its documentation but has not been tested on a live Bob install.
35
36
 
36
37
  <!--/harness-->
37
38
  <!--harness:opencode-->
@@ -40,7 +41,7 @@ If a gate crashes, it asks instead of letting the call through. If it cannot sta
40
41
  On OpenCode, two mechanisms enforce rules:
41
42
 
42
43
  - **OpenCode's own permission prompt**, which Geneseed configures in `opencode.json`. It asks you before `git reflog expire`, `git gc --prune` and a force-push or delete of `main`/`master`, and, when the **process** pack is on, before every commit and push.
43
- - **The guard plugin**, which blocks outright: writes to key and credential files (`id_rsa`, `*.pem`, `.ssh/`, `.npmrc`…), catastrophic commands (`rm -rf /`, `rm -rf ~`, formatting or overwriting a disk), every other real data loss (the same state-aware decisions as the hook), a recursive scan of a whole filesystem (`find /`, `du -sh /`, `Get-ChildItem C:\ -Recurse`), and any change inside a folder your wiki marks `protected`. It also refuses the first write to `user-rules.md` or memory once. Re-issue the write and it goes through.
44
+ - **The guard plugin**, which blocks outright: writes to key and credential files (`id_rsa`, `*.pem`, `.ssh/`, `.npmrc`…), catastrophic commands (`rm -rf /`, `rm -rf ~`, formatting or overwriting a disk), every other real data loss (the same state-aware decisions as the hook), a recursive scan of a whole filesystem (`find /`, `du -sh /`, `Get-ChildItem C:\ -Recurse`), and any change inside a folder your wiki marks `protected`. It also refuses the first write to `user-rules.md` or memory once. Re-issue the write and it goes through. And in an application repo with no `## Ownership` section in its root `AGENTS.md`, it refuses the session's first write once, so the agent proposes the [ownership](../concepts/ownership.md) setup (off with `mode: off` or `--no-ownership-gate`).
44
45
 
45
46
  The guard only warns on `.env` edits. It checks credentials by **file path**, not by content, so a key pasted into an ordinary source file is not caught here. One caveat about the process pack: if your `opencode.json` already has a `git commit*` entry, a rebuild without the pack leaves that entry in place and reports it. Geneseed cannot tell its own entry from one you typed.
46
47
 
@@ -8,7 +8,7 @@ description: "Where an install lands on IBM Bob or as a plain AGENT.md bundle, a
8
8
  ---
9
9
  Bob and the plain bundle carry the same rules, agents and skills as the other hosts. What differs is where they land and how much of it is enforced. The **Kind** words are explained in [What lands on your machine](on-your-machine.md).
10
10
 
11
- **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for the checks that admit no judgement call: credentials, destructive git, and a write under a project's own protected-checks list. The commit/push and memory questions become log lines.
11
+ **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for the checks that admit no judgement call: credentials, destructive git, and a write under a project's own protected-checks list. The commit/push and memory questions become log lines. One more refusal happens only once: in an application repo whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused so the agent proposes the [ownership](../concepts/ownership.md) setup, and the same write passes after you answer. Turn it off per repo with `mode: off` in that section, or per install with `--no-ownership-gate`.
12
12
 
13
13
  **Plain bundle.** The `files` target writes `AGENT.md` and the same folders into `./Harness/` for any tool that reads `AGENT.md`. It installs no hooks and no plugins, so nothing in it is enforced.
14
14
 
@@ -16,7 +16,7 @@ What a Claude Code or OpenClaude install writes, piece by piece. The **Kind** wo
16
16
  | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
17
17
  | context hook | At session start, and again after a resume or compaction, puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `geneseed exclude add <folder>` silences every hook in that folder |
18
18
  | git-gate hook | Before each shell command: asks you before any `git commit` or `git push`, and before a command that would really lose data — a force-push to `main`, a `reset --hard` that abandons unpushed commits, `branch -D` of an unpushed branch, an `rm` git cannot undo | enforced | ~14 ms per shell call | The commit/push question goes away if you build without the **process** pack; the destructive-git question has no switch except `geneseed exclude` |
19
- | rule-gate hook | Before each write or edit: asks you when the file would carry a credential-shaped string (outside `.env`), or when the agent writes to `user-rules.md` or memory | enforced | ~14 ms per write | `geneseed exclude add <folder>` |
19
+ | rule-gate hook | Before each write or edit: asks you when the file would carry a credential-shaped string (outside `.env`), or when the agent writes to `user-rules.md` or memory. In an application repo with no `## Ownership` section in its root `AGENTS.md`, stops the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | ~14 ms per write | `geneseed exclude add <folder>`; the ownership stop alone: `mode: off` in the repo's `## Ownership`, or rebuild with `--no-ownership-gate` |
20
20
  | learn hook | When the agent finishes a reply, and before compaction, distils durable facts from the recent conversation into `memory/`. Off until you set `GENESEED_LLM` to a model command such as `claude -p` | automatic | One model call each time it runs, once enabled | Leave `GENESEED_LLM` unset (the default) |
21
21
  | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
22
22
  | `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
@@ -16,9 +16,9 @@ What an OpenCode install writes, piece by piece. The **Kind** words are explaine
16
16
  | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
17
17
  | `opencode.json` entries | `instructions` points OpenCode at `AGENT.md`. `permission.bash` makes OpenCode ask before `git reflog expire`, `git gc --prune` or a force-push or delete of `main`/`master`, and before every commit and push when the **process** pack is on. `permission.skill` denies each user-only skill, so the model never starts it but `/name` still runs it; Geneseed takes back only the denies it wrote | enforced | No tokens | Edit the `permission` block yourself. The commit/push questions follow the **process** pack |
18
18
  | context plugin | Puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `GENESEED_CONTEXT_INJECT=off` |
19
- | guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), every other real data loss judged against the repository's state, a recursive scan of a whole filesystem (`find /`), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block |
19
+ | guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), every other real data loss judged against the repository's state, a recursive scan of a whole filesystem (`find /`), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours. In an application repo with no `## Ownership` section in its root `AGENTS.md`, refuses the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block; the ownership refusal alone: `mode: off` in the repo's `## Ownership`, or rebuild with `--no-ownership-gate` |
20
20
  | learn plugin | Once a session has been quiet for 60 seconds, distils durable facts into `memory/` with the model the session already uses | automatic | One model call per quiet session | `geneseed exclude add <folder>` silences it in that folder |
21
- | activity plugin | Writes one small file per session that the web console's Activity view shows | automatic | No tokens | `GENESEED_ACTIVITY=off` |
21
+ | activity plugin | Writes one small file per session that the web console's Activity view shows: what the session does now, its sub-agents, the files each of them changed (by path inside the repository), its turns, how full its context is and its compactions | automatic | No tokens | `GENESEED_ACTIVITY=off` |
22
22
  | notify plugin | A desktop notification when a turn took longer than 30 seconds | automatic | No tokens | `GENESEED_NOTIFY=off` |
23
23
  | ponytail plugin | Minimal-code mode. `/ponytail lite`, `full` or `ultra` adds a short ruleset to every turn until you switch it off | on demand | 0 while off, which is the default | `/ponytail off` |
24
24
  | workflow plugin | Adds a `workflow` tool that runs saved orchestration scripts | on demand | Runs only when called | `geneseed uninstall` |
package/docs/web-ui.md CHANGED
@@ -111,13 +111,14 @@ streams the output of background jobs and keeps their history across reloads.
111
111
  content the page last read — if an agent session edited the file meanwhile, the save
112
112
  409s and the page reloads instead of clobbering it.
113
113
  - **Constitution** (`#/laws`) — the whole governance surface on one page, in three bands:
114
- the **Ethos** (four prose sections), the **Dictates** (the nine numbered Rules, with
114
+ the **Ethos** (five prose sections), the **Dictates** (the nine numbered Rules, with
115
115
  a class facet — only non-empty classes render, and two of the six have had no invariant
116
116
  since the split), and the **Doctrines** (one group per pack, each marked active or not for
117
117
  this install). Rules I, III and IV each carry a switch for the install's hook gate — the
118
118
  secrets gate, the done gate and the deletion gate (`--no-secrets-gate`, `--no-done-gate`,
119
119
  `--no-deletion-gate`; *Enforced by* reads *Gate off* while one is off) — flipping one asks,
120
- then rebuilds the install once; the other Rules read *no gate*. A precedence ladder heads the page (a state pill per rung; ranks 5–6 below). *Gated* and *Changed* narrow the rows; packs fold; staged doctrine changes collect in a sticky *Unapplied changes* bar that holds Revert and the page's one Apply. Every row expands to its full body, lazily fetched. The rail entry is
120
+ then rebuilds the install once; the other Rules read *no gate*. The ownership gate belongs
121
+ to no Rule, so it has no switch here: rebuild with `--no-ownership-gate` instead. A precedence ladder heads the page (a state pill per rung; ranks 5–6 below). *Gated* and *Changed* narrow the rows; packs fold; staged doctrine changes collect in a sticky *Unapplied changes* bar that holds Revert and the page's one Apply. Every row expands to its full body, lazily fetched. The rail entry is
121
122
  labelled *Constitution* while the route, the id and the badge key stay `laws`; deep links
122
123
  are `#/item/law/ont:telos`, `#/item/law/IV` and `#/item/law/process.5` — three address
123
124
  shapes that cannot collide, because a slug carries a colon no numeral has and a doctrine
@@ -187,6 +188,24 @@ streams the output of background jobs and keeps their history across reloads.
187
188
  the files it touched and its todo progress; open one for its detail. Sessions that ended in the last 7 days are listed under
188
189
  **Recently ended**, below the live ones. Every host records it:
189
190
  the OpenCode plugin, and `geneseed-hook activity` on Claude Code, OpenClaude and Bob.
191
+ The live sessions open in the **Garden** by default; a **List | Garden** switch (kept in the
192
+ URL with the filters, which apply to both) shows them as a list of cards instead. The Garden
193
+ shows them as pixel bonsai: one shelf per repository (worktrees stand on their
194
+ repo's shelf, tagged ⎇), one tree per session. The pot's glaze is the host (clay Claude Code,
195
+ blue Bob, grey OpenCode, violet OpenClaude); the tree grows taller with turns, its crown
196
+ with context fill, and the tips yellow past 80 %. A compaction cuts the crown flat (it
197
+ regrows as context refills) and leaves a notch on the rim. A running sub-agent is a thick
198
+ branch with its own pad, coloured by agent type; a finished one is a pruned stub and a
199
+ fallen leaf. A cream blossom is a changed file, on the pad of the AI that changed it (Bob
200
+ cannot tell, so all its blossoms sit on the crown). An amber `!` means the session needs
201
+ you, a red `x` an error, a grey tree an idle session. Two sessions changing the same file
202
+ are tied together in red (same worktree) or dashed amber (two worktrees of the repo): tangled
203
+ roots in the moss when they stand side by side, a thread under the pots when they do not.
204
+ Hover a tree for its model, turns, context and compactions, or a pad for its author's files;
205
+ click it to open the session. Past ten trees, quiet shelves (no session working or waiting on
206
+ you) fold into chips, the largest first; the last standing shelf never folds. **Sakura** repaints the crowns pink, nothing more.
207
+ A session's detail page shows its tree too, live or ended, with the same pad hovers and a
208
+ legend of its turns, context, compactions and sub-agents; an ended session's tree stands still, without the `!`.
190
209
  - **Changes** (`#/diff`) — the diff between the deployed harness and the source: edited /
191
210
  added / missing files, and files only behind the source (unedited; a rebuild updates them)
192
211
  listed apart under **Behind source**, with per-file expansion and coloured unified-diff lines. Select
@@ -2,5 +2,5 @@
2
2
  "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
3
3
  "theme": "neutral",
4
4
  "product": "Geneseed",
5
- "version": "4.25.1"
5
+ "version": "4.27.0"
6
6
  }
package/js/README.md CHANGED
@@ -91,6 +91,7 @@ user co-owns, and the hook verbs those emitted configs then run.
91
91
  | `hosts.mjs` | The four host config dirs (opencode/claude/bob/openclaude), their `family` (`CLAUDE_STYLE`), plus `resolvePath`/`expanduser` |
92
92
  | `hooks.mjs` | The gate verbs, run on every tool call: `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), plus `ask`/the gate ledger/`guardGate`. `--host` picks the verdict dialect |
93
93
  | `hooks-context.mjs` | The `context` verb — SessionStart: session files plus the repo's context docs |
94
+ | `ownership-gate.mjs` | The ownership first-write gate, last in `rule-gate`: in an application repo (git root + build manifest) whose root `AGENTS.md` has no `## Ownership` section, denies the session's first write once (a tmpdir marker per session). Builtins + `gitRootOf` only. Twin: the OpenCode guard plugin |
94
95
  | `hooks-done.mjs` | The done gate (#289): on Stop, inside `learn` and before its spawn, blocks a turn that edited files until `.geneseed/done-checks.txt`'s checks passed after the last edit |
95
96
  | `hooks-learn.mjs` | The `learn` verb — Stop/SubagentStop/PreCompact distiller; the hook path's ONE spawn (`$GENESEED_LLM`) |
96
97
  | `hooks-prims.mjs` | The Python path/text primitives the hook verbs share (`splitLines`, `readStdin`, a never-throwing `isFile`), plus the activity off switch (`activityOn`) and the do-nothing `activity` verb |
@@ -54,7 +54,7 @@ export const STRUCTURE = {
54
54
  // `({{ONTOLOGY}}: {{ONT_TELOS}})` — token on both sides, so the heading and every
55
55
  // reference to it move together and a rename can never desync them.
56
56
  ONT_TELOS: 'Telos', ONT_EVIDENCE: 'Evidence', ONT_DECISIONS: 'Decisions',
57
- ONT_CONDUCT: 'Conduct',
57
+ ONT_OWNERSHIP: 'Ownership', ONT_CONDUCT: 'Conduct',
58
58
  };
59
59
 
60
60
  /**