geneseed 4.26.0 → 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.
- package/CHANGELOG.md +28 -0
- package/DESIGN.md +6 -5
- package/README.md +10 -6
- package/SHIPPED.md +4 -3
- package/adapters/bob/README.md +1 -1
- package/adapters/claude-code/README.md +5 -1
- package/adapters/claude-code/skills/geneseed/SKILL.md +2 -2
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +1 -1
- package/adapters/opencode/README.md +5 -2
- package/adapters/opencode/plugins/geneseed-guard.js +79 -4
- package/bin/geneseed-hook.mjs +9 -3
- package/docs/concepts/enforcement-table.md +12 -0
- package/docs/concepts/exclusions.md +15 -1
- package/docs/concepts/hook-gates.md +1 -1
- package/docs/concepts/hooks.md +2 -1
- package/docs/concepts/ownership.md +79 -0
- package/docs/concepts/rules.md +1 -1
- package/docs/guides/set-up-ownership.md +77 -0
- package/docs/reference/glossary.md +1 -1
- package/docs/reference/plugin-guard.md +1 -0
- package/docs/reference/troubleshoot-doctor.md +2 -2
- package/docs/understand/enforced-vs-asked.md +3 -2
- package/docs/understand/machine-bob.md +1 -1
- package/docs/understand/machine-claude.md +1 -1
- package/docs/understand/machine-opencode.md +1 -1
- package/docs/web-ui.md +6 -4
- package/harness.config.json +1 -1
- package/js/README.md +1 -0
- package/js/build/render.mjs +1 -1
- package/js/build/source.mjs +5 -1
- package/js/cli-table.json +46 -1
- package/js/hosts/hooks.mjs +45 -5
- package/js/hosts/ownership-gate.mjs +105 -0
- package/js/hosts/settings.mjs +8 -3
- package/js/inspect/cost.mjs +1 -1
- package/js/inspect/inventory.mjs +1 -1
- package/js/inspect/status.mjs +1 -1
- package/package.json +1 -1
- package/registry.json +7 -0
- package/src/AGENT.md.tmpl +5 -0
- package/src/agents/developer.md +7 -1
- package/src/modes/foreman.md +4 -1
- package/src/ontology/universal.md +19 -0
- package/src/skills/_checkpoints.md +15 -0
- package/src/skills/develop.md +4 -0
- package/src/skills/document-project.md +2 -1
- package/src/skills/learn-mode.md +13 -17
- package/src/skills/ownership.md +139 -0
- package/src/skills/pipeline.md +1 -1
- package/themes/README.md +2 -2
- package/themes/_TEMPLATE.json +1 -0
- package/themes/biker.json +1 -0
- package/themes/commentator.json +1 -0
- package/themes/cyberpunk.json +1 -0
- package/themes/gamer.json +1 -0
- package/themes/imperial.json +1 -0
- package/themes/joker.json +1 -0
- package/themes/marvin.json +1 -0
- package/themes/mean.json +1 -0
- package/themes/military.json +1 -0
- package/themes/neutral.json +1 -0
- package/themes/pirate.json +1 -0
- package/themes/sports.json +1 -0
- package/themes/verstappen.json +1 -0
- package/themes/wizard.json +1 -0
- package/web/dist/assets/Activity-DfETiyWm.js +1 -0
- package/web/dist/assets/{ActivityDetail-BIxt9mAe.js → ActivityDetail-CnP3GPAN.js} +1 -1
- package/web/dist/assets/{CopyButton-DmXwAzBl.js → CopyButton-CRAUXSG7.js} +1 -1
- package/web/dist/assets/{Dashboard-BsevsUea.js → Dashboard-CaqOqtkG.js} +2 -2
- package/web/dist/assets/{Docs-BkipFlm8.js → Docs-BFxyAVdN.js} +1 -1
- package/web/dist/assets/{GreenhouseView-BJmyqf49.js → GreenhouseView-19roNb5W.js} +1 -1
- package/web/dist/assets/{Installs-CICECChj.js → Installs-BSoQN7w7.js} +1 -1
- package/web/dist/assets/{JournalView-BOyq2Abk.js → JournalView-BgU2ybaq.js} +1 -1
- package/web/dist/assets/{KitApply-BRSZjM_N.js → KitApply-Ckc0P5kt.js} +1 -1
- package/web/dist/assets/{Kits-DPGxX2Vv.js → Kits-BZqWGWMu.js} +1 -1
- package/web/dist/assets/{Laws-CY0hBpkK.js → Laws-CnUWiNIx.js} +1 -1
- package/web/dist/assets/{Library-PzXbaBWz.js → Library-rYO8owx_.js} +1 -1
- package/web/dist/assets/{Loops-DflSj8Pz.js → Loops-CljFhhQV.js} +1 -1
- package/web/dist/assets/{OperatorHudView-CjJlJqGm.js → OperatorHudView-xs7SCwCe.js} +1 -1
- package/web/dist/assets/{Personal-CC7cLkTe.js → Personal-CMPwtl36.js} +1 -1
- package/web/dist/assets/{Tabs-DCzA2Eop.js → Tabs-CEfSUVQp.js} +1 -1
- package/web/dist/assets/{index-xjpstIKL.js → index-FLVXXvV3.js} +2 -2
- package/web/dist/index.html +1 -1
- package/web/dist/assets/Activity-Dq8_Xhxu.js +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,34 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [4.27.0] — 2026-10-27
|
|
12
|
+
|
|
13
|
+
Minor: ownership — the developer decides each part of production code, at a granularity the team sets in the root `AGENTS.md`; a Credo section, the ownership skill, and a first-write gate that is on by default (see the ⚠️ entry). Re-emit every install with `geneseed rebuild-all` to get the new Credo section, the skill, the `develop`/`developer`/Foreman changes and the OpenCode guard.
|
|
14
|
+
|
|
15
|
+
- ⚠️ **Behaviour change on update: the ownership first-write gate.** In an application repo (a
|
|
16
|
+
git root holding `package.json`, `pom.xml`, `build.gradle*`, `pyproject.toml`, `go.mod`,
|
|
17
|
+
`Cargo.toml`, `*.csproj`, `composer.json` or `Gemfile`) whose root `AGENTS.md` has no
|
|
18
|
+
`## Ownership` section, the first Write, Edit or NotebookEdit of each session is now refused
|
|
19
|
+
once, with a reason that tells the agent to propose the ownership setup to the developer.
|
|
20
|
+
The next write passes. Claude Code, OpenClaude and Bob get the hook with the update itself (`git pull` or the npm package), with no re-emit
|
|
21
|
+
(Claude and OpenClaude: `permissionDecision: "deny"`, which shows the reason to the model;
|
|
22
|
+
Bob: exit 2). OpenCode V1
|
|
23
|
+
and V2 get it with the guard plugin on the next emit. Run `geneseed rebuild-all` straight
|
|
24
|
+
after updating: the refusal points at the ownership skill, which only a re-emit installs.
|
|
25
|
+
Shell writes are not gated, nor sub-agent writes on Claude Code, OpenClaude and OpenCode. To opt out: per repo, add `## Ownership` with `mode: off` to the root `AGENTS.md`;
|
|
26
|
+
per install, rebuild with `--no-ownership-gate`; per session, answer "proceed without".
|
|
27
|
+
See [Ownership](docs/concepts/ownership.md).
|
|
28
|
+
|
|
29
|
+
### Changed
|
|
30
|
+
- **Activity opens on the Garden.** The live sessions show as bonsai by default; the `List | Garden` switch shows the cards, and the list is kept in the link as `v=list`. An older link carrying `v=garden` still opens the Garden.
|
|
31
|
+
- **The Credo gains an Ownership section, and learn-mode may propose.** A fifth always-on section, between Decisions and Conduct: the code belongs to whoever will answer for it, and work is handed over only when the developer can say what changed, where and why. learn-mode may now propose a solution, but never applies one it has not explained.
|
|
32
|
+
- **learn-mode's checkpoint rules move into a shared include.** The state-file, `Pending`, cadence and "no code without an answer" rules now live in `skills/_checkpoints.md`, which learn-mode includes and the ownership Rite shares. learn-mode keeps every rule it had; they now read as one "Checkpoint rules" section.
|
|
33
|
+
- **develop, the developer Adept and Foreman honour ownership.** In an ownership repo, develop runs each slice through the ownership checkpoints (unless learn-mode is active); Foreman delegates only once the plan is approved inline, and its brief carries the approved decisions; the developer writes only what those decisions cover, returns `blocked: decision needed` on any other choice, and hands back the diff for final review.
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
- **The ownership Rite.** In an application whose root `AGENTS.md` has a `## Ownership` section with `mode: on`, the developer decides each part at the granularity the team sets (`feature`, `file` or `function`); interfaces and sensitive zones are always a checkpoint. Routine steps are announced, not asked, and the native diff is the approval. Its setup extracts the conventions, asks about five questions and writes the section. One line in `AGENT.md` points to it; learn-mode still comes first.
|
|
37
|
+
- **Ownership docs.** A concept page ([Ownership](docs/concepts/ownership.md)): the section format, granularity, the first-write gate, the opt-outs and how it differs from learn-mode; a guide ([Set up ownership](docs/guides/set-up-ownership.md)); and the gate in every page that lists the hook gates.
|
|
38
|
+
|
|
11
39
|
## [4.26.0] — 2026-10-26
|
|
12
40
|
|
|
13
41
|
Minor: Activity's Garden — every live session as a pixel bonsai, fed by richer activity snapshots on every host (where files are, who changed them, sub-agents, turns, context, compactions), plus OpenCode files and the host filter fixed.
|
package/DESIGN.md
CHANGED
|
@@ -31,8 +31,8 @@ vault or a specific tool's hooks.
|
|
|
31
31
|
3. **Theme is voice + vocabulary; the scaffolding is theme-independent.** A single
|
|
32
32
|
neutral source renders to any theme via token substitution, split into two classes:
|
|
33
33
|
- **Structure** (always plain English, every theme, every emit) — the section
|
|
34
|
-
*layout*, the harness name (`HARNESS`), the law *numbers*, the
|
|
35
|
-
names (`ONT_TELOS`, `ONT_EVIDENCE`, `ONT_DECISIONS`, `ONT_CONDUCT`), a few rare
|
|
34
|
+
*layout*, the harness name (`HARNESS`), the law *numbers*, the five ontology section
|
|
35
|
+
names (`ONT_TELOS`, `ONT_EVIDENCE`, `ONT_DECISIONS`, `ONT_OWNERSHIP`, `ONT_CONDUCT`), a few rare
|
|
36
36
|
technical nouns (`Context`, `Scripts`, `Charter`), and the folder names (`laws/`,
|
|
37
37
|
`ontology/`, `doctrines/`, `agents/`, `skills/`, `memory/`, `notebook/` via `DIR_*`).
|
|
38
38
|
These live in the `STRUCTURE` map in `js/build/render.mjs` and are laid on top of every
|
|
@@ -92,10 +92,11 @@ vault or a specific tool's hooks.
|
|
|
92
92
|
the rules that matter. The governance surface is split into three tiers, each answering
|
|
93
93
|
a different question:
|
|
94
94
|
|
|
95
|
-
- **Ontology** (`src/ontology/universal.md`) — *who is deciding*.
|
|
95
|
+
- **Ontology** (`src/ontology/universal.md`) — *who is deciding*. Five sections of
|
|
96
96
|
flowing prose: **Telos** (what the agent is for, and the Pact it works under),
|
|
97
97
|
**Evidence** (how a claim is graded by how it was obtained), **Decisions** (classify
|
|
98
|
-
and tier by reversibility; show the real forks), **
|
|
98
|
+
and tier by reversibility; show the real forks), **Ownership** (the code belongs to
|
|
99
|
+
whoever answers for it; hand work over only once it is understood), **Conduct** (answer what was asked,
|
|
99
100
|
once). It absorbed the Pact, which is now stated *inside* Telos rather than standing
|
|
100
101
|
as a peer of the rules.
|
|
101
102
|
- **Invariants** (`src/laws/universal.md`) — *what is never traded*. Nine Rules, `I`..`IX`,
|
|
@@ -187,7 +188,7 @@ theme file defines a `DIR_*` key, so `laws/` is `laws/` in all fourteen voices.
|
|
|
187
188
|
| Component | Source | `Harness/` output | Purpose |
|
|
188
189
|
| --- | --- | --- | --- |
|
|
189
190
|
| Entrypoint | `src/AGENT.md.tmpl` | `AGENT.md` | what the tool reads; inlines the constitution, links the rest |
|
|
190
|
-
| Ontology | `src/ontology/` | `ontology/` | the mind the rules govern — Telos, Evidence, Decisions, Conduct; always on, never toggleable |
|
|
191
|
+
| Ontology | `src/ontology/` | `ontology/` | the mind the rules govern — Telos, Evidence, Decisions, Ownership, Conduct; always on, never toggleable |
|
|
191
192
|
| Governance | `src/laws/` | `laws/` | the nine universal invariants; always on, never toggleable |
|
|
192
193
|
| Doctrines | `src/doctrines/` | `doctrines/` | the four practice packs — the one build-time axis that changes *which rules ship*; the whole catalogue is written to disk either way |
|
|
193
194
|
| Delegation | `src/agents/` | `agents/` | capability specialists with output contracts |
|
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
[](package.json)
|
|
12
12
|
[](package.json)
|
|
13
13
|
[](themes/)
|
|
14
|
-
[](src/skills/)
|
|
15
15
|
[](src/agents/)
|
|
16
16
|
[](src/doctrines/)
|
|
17
17
|
[](adapters/opencode/plugins/)
|
|
@@ -62,7 +62,7 @@ The lineage is also why an **imperial** theme ships alongside the neutral one: i
|
|
|
62
62
|
|
|
63
63
|
### How it works
|
|
64
64
|
|
|
65
|
-
One canonical source in `src/` renders, via a tiny zero-dependency generator (`geneseed-build`), into a ready-to-use bundle. **A theme controls only *voice*** — how the AI responds and how the prose inside the docs reads (tagline, greeting, descriptions). **Structure is theme-independent**: section names (Rules, Agents, Skills, Memory…), folder names (`laws/`, `ontology/`, `doctrines/`, `agents/`, `skills/`, `memory/`, `notebook/`) and the
|
|
65
|
+
One canonical source in `src/` renders, via a tiny zero-dependency generator (`geneseed-build`), into a ready-to-use bundle. **A theme controls only *voice*** — how the AI responds and how the prose inside the docs reads (tagline, greeting, descriptions). **Structure is theme-independent**: section names (Rules, Agents, Skills, Memory…), folder names (`laws/`, `ontology/`, `doctrines/`, `agents/`, `skills/`, `memory/`, `notebook/`) and the five ontology section headings (Telos, Evidence, Decisions, Ownership, Conduct) are always plain English, so the scaffolding stays tool-friendly while the flavour lives in the words.
|
|
66
66
|
|
|
67
67
|
```bash
|
|
68
68
|
geneseed-build # default theme (neutral)
|
|
@@ -175,17 +175,21 @@ The harness ships as a small set of layers, and the web console's rail is the sa
|
|
|
175
175
|
|
|
176
176
|
| Layer | What it is |
|
|
177
177
|
| --- | --- |
|
|
178
|
-
| **🧭 Ethos** (`ontology/`) | the mind the rules govern, in
|
|
178
|
+
| **🧭 Ethos** (`ontology/`) | the mind the rules govern, in five prose sections — **Telos** (the Pact: three ranked laws — protect the user, serve their intent, keep your own honesty), **Evidence** (every claim graded by how it was obtained), **Decisions** (classify and tier by reversibility, show the real forks), **Ownership** (the code belongs to whoever answers for it; hand work over only once it is understood), **Conduct** (answer what was asked, once). Always in force, never toggleable |
|
|
179
179
|
| **🛡️ Rules** (`laws/`) | 9 universal laws — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-asserting, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, cure-the-cause, echo-the-intent. Each rule has a permanent id; its number is only its position, and the harness cites rules by name |
|
|
180
180
|
| **📐 Doctrines** (`doctrines/`) | practice packs, chosen per install at build time: **craft** (how code is written), **rigor** (how work is proven), **ops** (how the machine is operated), **process** (how a task is run), **comms** (how answers are presented). A doctrine rule may tighten a Rule, never repeal one, and the user's own `user-rules.md` outranks it. Pick with `geneseed-build --doctrines craft,rigor` (or `none`), a single rule with `--exclude-rules "process 7"`, in the setup wizard, or through the switches on the console's Constitution page; all five pack files ship on disk either way, so a citation into a pack you left out still resolves |
|
|
181
181
|
| **🤖 Agents** (20) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `performance`, `explorer`, `researcher`, `developer`, `memory-curator` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
|
|
182
|
-
| **🛠 Skills** (
|
|
182
|
+
| **🛠 Skills** (48) | repeatable workflows: brainstorm · plan · **codebase-design** · **wayfinder** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno** · geneseed-code-review · **fresh-eyes** · **security-audit** · **dependencies** · **review-response** · commit · **ship** · **release** · **git-history** · document-project · **frontend-design** · **deck** · **prose** · **ingest** · **research** · **teach** · **quiz** · **learn-mode** · **ownership** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **skill-forge** · **pipeline** · **loop** · **brick-forge** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
|
|
183
183
|
| **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
|
|
184
184
|
| **🧠 Memory** (`memory/`) | one-fact-per-file durable knowledge, indexed by `MEMORY.md` (git-ignored, personal) |
|
|
185
185
|
| **📓 Notebook** (`notebook/`) | the agent's sovereign space — any medium (code, tools, data, notes), self-ruled via a seed-once charter, always git-ignored; only its `.gitignore` is build-asserted |
|
|
186
186
|
| **🌐 Wiki** (`geneseed-wiki.jsonc`) | your own machine-wide knowledge base — typically an Obsidian vault — declared once per machine: entry notes load eager/lazy, the agent reads and **writes** it under the vault's own conventions, with an inbox fallback and guard-enforced protected folders |
|
|
187
187
|
| **🧭 Context** | the project's own docs — auto-discovered on OpenCode, or via a `context.json` manifest |
|
|
188
188
|
|
|
189
|
+
### 🧑💻 Ownership of production code
|
|
190
|
+
|
|
191
|
+
In an application built for production, the developer stays the owner of the code. A committed `## Ownership` section in the repo's root `AGENTS.md` sets how closely the team steers — per feature, per file or per function — and names the sensitive zones; the agent then proposes, explains the complex parts and writes only what the developer approved, while interfaces and sensitive zones are always a checkpoint. Before the first write in an application repo with no such section, a hook stops the agent once so it proposes the setup. Opt a repo out with `mode: off`, an install with `--no-ownership-gate`, or a session by answering "proceed without"; learn-mode, when a developer turns it on, always drives the workflow (the hook still stops the first write once). See [Ownership](docs/concepts/ownership.md) and [Set up ownership](docs/guides/set-up-ownership.md).
|
|
192
|
+
|
|
189
193
|
### 🤝 What the harness asks of you
|
|
190
194
|
|
|
191
195
|
The Pact in the Ethos is mutual. The agent's side is written into every install. Yours is not enforced — it is what keeps the pact honest, and only you can give it:
|
|
@@ -278,7 +282,7 @@ Geneseed/
|
|
|
278
282
|
├── harness.config.json default theme + metadata (the one owner of the version)
|
|
279
283
|
├── src/ canonical source — edit here
|
|
280
284
|
│ ├── AGENT.md.tmpl the entrypoint, rendered to AGENT.md
|
|
281
|
-
│ ├── ontology/ how the agent thinks — Telos, Evidence, Decisions, Conduct
|
|
285
|
+
│ ├── ontology/ how the agent thinks — Telos, Evidence, Decisions, Ownership, Conduct
|
|
282
286
|
│ ├── laws/ the universal invariants
|
|
283
287
|
│ ├── doctrines/ the five practice packs (craft, rigor, ops, process, comms)
|
|
284
288
|
│ ├── postures/ the relationship register, inlined into AGENT.md
|
|
@@ -377,7 +381,7 @@ Some skills and agents are adapted from other open-source skill collections, und
|
|
|
377
381
|
- `mattpocock-skills-frozen` — [mattpocock/skills](https://github.com/mattpocock/skills) by Matt Pocock (MIT), pinned at 391a2701, the last commit carrying `resolving-merge-conflicts` (deleted upstream since): the merge-conflict step of git-history, from a skill upstream has since deleted, so the weekly drift check skips it.
|
|
378
382
|
- `mattpocock-skills-2509` — [mattpocock/skills](https://github.com/mattpocock/skills) by Matt Pocock (MIT), a second key for the same repo, at the same pin as `mattpocock-skills` today (5beb35b0): the PR body of ship and the guardrail clause of rule.
|
|
379
383
|
- `superpowers` — [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (MIT): the core of debug, the size step and builder check of brainstorm, the plan rules of plan, the reviewer brief behind geneseed-code-review and the reviewer agent, the review-handling steps of review-response, and the ruling format of pipeline and parallel-agents.
|
|
380
|
-
- `vibe-wise` — [nykooi1/vibe-wise](https://github.com/nykooi1/vibe-wise) by Noah Kim (MIT): the state file, levels and checkpoints of learn-mode.
|
|
384
|
+
- `vibe-wise` — [nykooi1/vibe-wise](https://github.com/nykooi1/vibe-wise) by Noah Kim (MIT): the state file, levels and checkpoints of learn-mode, and the checkpoint rules ownership shares.
|
|
381
385
|
- `piomin-spring-boot` — [piomin/claude-ai-spring-boot](https://github.com/piomin/claude-ai-spring-boot) by Piotr Mińkowski (Apache-2.0): the Spring Boot kit's skills and agents, rewritten and condensed for Boot 4.
|
|
382
386
|
- `everything-claude-code` — [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT): the React kit's skills and agents, rewritten and condensed for Vite and Jest.
|
|
383
387
|
|
package/SHIPPED.md
CHANGED
|
@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
|
|
|
20
20
|
> **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
|
|
21
21
|
> human-readable label only. The canonical identity of an installed harness is the
|
|
22
22
|
> **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
|
|
23
|
-
> string. Current label: **4.
|
|
23
|
+
> string. Current label: **4.27.0**.
|
|
24
24
|
|
|
25
25
|
## Capabilities
|
|
26
26
|
|
|
@@ -29,8 +29,8 @@ Every row below is present in the tree today; "Spec" names the design record.
|
|
|
29
29
|
| Capability | What it is | Spec |
|
|
30
30
|
| --- | --- | --- |
|
|
31
31
|
| **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
|
|
32
|
-
| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 20 agents,
|
|
33
|
-
| **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Conduct — the Pact absorbed into Telos), the nine always-on **Invariants**, and five toggleable **Doctrine** packs (craft, rigor, ops, process, comms) addressed `<pack> <n>`. Every rule carries a permanent id; its number is its position, computed at render time, and a citation renders as the rule's principle name. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates rule ids (declared, unique, never a retired one), the per-rule Principle column, every `{{LAW:<id>}}` / `{{DOCTRINE:<id>}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | `2026-08-19-three-tier-constitution-design` |
|
|
32
|
+
| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 20 agents, 48 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
|
|
33
|
+
| **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Ownership, Conduct — the Pact absorbed into Telos), the nine always-on **Invariants**, and five toggleable **Doctrine** packs (craft, rigor, ops, process, comms) addressed `<pack> <n>`. Every rule carries a permanent id; its number is its position, computed at render time, and a citation renders as the rule's principle name. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates rule ids (declared, unique, never a retired one), the per-rule Principle column, every `{{LAW:<id>}}` / `{{DOCTRINE:<id>}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | `2026-08-19-three-tier-constitution-design` |
|
|
34
34
|
| **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | `2026-06-07-theme-aware-doctor-diff` |
|
|
35
35
|
| **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | `2026-06-12-improvements-export` |
|
|
36
36
|
| **`status` / `version`** | Headless dashboard + fingerprint verdict (no TUI needed) | `2026-06-07-status-command` · `2026-06-07-version-and-uninstall` |
|
|
@@ -42,6 +42,7 @@ Every row below is present in the tree today; "Spec" names the design record.
|
|
|
42
42
|
| **Per-agent memory** | Each capability agent keeps durable lessons in `memory/agents/<name>.md`: read at dispatch, written back mechanically by `learn` on session/subagent end (OpenCode plugin + Claude `SubagentStop`; Bob has no subagent event); `learn --consolidate` rebuilds the index | `2026-07-04-orchestration-memory-upgrade` |
|
|
43
43
|
| **Wiki integration** | Machine-wide knowledge base (`geneseed-wiki.jsonc`): eager/lazy loading, conventions, protected folders enforced at the tool boundary | `2026-06-11-wiki-knowledge-base` |
|
|
44
44
|
| **Collaboration layer** | Negotiated postures (peer/mentor/expert/assistant/artisan, chosen at setup, inlined in AGENT.md), the bidirectional Pact, epistemically-typed memory (`force:` + Bridge rule), and a seed-once `PROFILE.md` identity with a web editor tab and a `profile` skill that interviews the user to draft it | `2026-07-12-collaboration-layer` |
|
|
45
|
+
| **Ownership** | The developer keeps ownership of production code: a Credo section (the code belongs to whoever answers for it), the `ownership` skill (setup from the code and a short interview, `feature`/`file`/`function` granularity, interfaces and sensitive zones always a checkpoint, announce-don't-ask), a `## Ownership` section in the committed root `AGENTS.md` (`mode: on\|off`), and a first-write gate on every host that stops the session's first write once in an application repo without one. learn-mode always comes first; `develop`, the `developer` agent and Foreman hold the checkpoints. Off per repo (`mode: off`), per install (`--no-ownership-gate`), per session ("proceed without") | `2026-10-26-ownership` |
|
|
45
46
|
| **Rule front door** | Both durable stores enter through the `rule` skill's fork (*standing rule, or fact to remember?* — always asked, never inferred): the memory branch elicits the binding `force` and shows the file before writing, the rule branch pressure-tests by reformulation and a mandatory counter-example. Doctrine process 1 carries the norm on every host; a `rule-gate` PreToolUse hook (Claude, Bob) and a `geneseed-guard` speed bump (OpenCode) hold it at the tool boundary | `2026-07-30-rule-front-door` |
|
|
46
47
|
| **Entity registry** | `registry.json` records a lifecycle status, version, owner and add-date for every agent and skill in the tree (maintainer-side — never rendered into a bundle, so it costs no session context). `doctor` gates it against `src/` in both directions, sweeps everything that ships for credentials, and holds each vendored skill folder to an immutable upstream commit. The status surfaces as a badge in the web catalog, shown only where it deviates from `approved` | `2026-07-31-entity-registry` |
|
|
47
48
|
| **Node runtime + npm package** | The whole harness runs from Node: every command `js/cli-table.json` declares, all five hook verbs, every web-console endpoint (the OS-native folder picker excepted, and declined on purpose) and both generators. Every commit runs the unit suite, `doctor --all` across every theme × host × footprint, and the generator's two self-comparisons, on Linux and Windows both; the frozen emit/cli/web recordings that also gated it retired on 2026-08-17 (see the 2.0.0 entry in [CHANGELOG.md](CHANGELOG.md)). It ships as the zero-dependency `geneseed` package (`geneseed`, `geneseed-hook`, `geneseed-build`), so `npx geneseed setup` needs no clone and nothing else installed; `geneseed migrate` moves an existing checkout install across. Node is the only runtime it asks for: the `token-report` skill's own script is `token_report.mjs`, gated over seeded transcripts for all four hosts, and `daydream` calls `node -e` | `2026-08-06-npx-distribution` |
|
package/adapters/bob/README.md
CHANGED
|
@@ -104,7 +104,7 @@ What the global emit writes into `~/.bob/settings/settings.json`:
|
|
|
104
104
|
| event | verb | how the verdict travels |
|
|
105
105
|
| --- | --- | --- |
|
|
106
106
|
| `SessionStart` | `context --host bob` | plain stdout, as on Claude |
|
|
107
|
-
| `PreToolUse` | `tool-gate --host bob` — one group, no matcher | Laws I/IV, rigor-5 and ops-2: **exit 2**, reason on stderr — it says no chat confirmation lifts the block, since Bob has no ask tier; process 1/5: a stderr line, exit 0 |
|
|
107
|
+
| `PreToolUse` | `tool-gate --host bob` — one group, no matcher | Laws I/IV, rigor-5 and ops-2: **exit 2**, reason on stderr — it says no chat confirmation lifts the block, since Bob has no ask tier; process 1/5: a stderr line, exit 0; the ownership gate (the session's first write in an application repo with no `## Ownership` section in its root `AGENTS.md`): **exit 2 once**, the same write then passes — off with `--no-ownership-gate` or `mode: off` |
|
|
108
108
|
| `Stop` | `learn` | never a verdict |
|
|
109
109
|
| `UserPromptSubmit` | `activity --host bob` | never a verdict; records the turn for the web console's Activity view |
|
|
110
110
|
|
|
@@ -40,7 +40,11 @@ absolute-path hooks instead — `geneseed setup` does that for you.) It:
|
|
|
40
40
|
- on **PreToolUse** (matcher `Write|Edit|NotebookEdit`), runs
|
|
41
41
|
`geneseed-hook rule-gate` — refuses a write that would put a credential into a tracked
|
|
42
42
|
file, and asks first on the first write to `user-rules.md` or a memory file (whether
|
|
43
|
-
something you want kept is a rule or a fact is your call).
|
|
43
|
+
something you want kept is a rule or a fact is your call). In an application repo (a git
|
|
44
|
+
root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section, it also
|
|
45
|
+
denies the session's first write once, with a reason addressed to the agent: propose the
|
|
46
|
+
ownership setup, or proceed without; the next write passes, and sub-agents defer. Off per repo
|
|
47
|
+
with `mode: off` in that section, per install with `--no-ownership-gate`. Ordinary edits pass.
|
|
44
48
|
(`MultiEdit` is not a Claude Code tool and is not in the matcher; the gate reads
|
|
45
49
|
`edits[].new_string` as a cheap guard regardless.)
|
|
46
50
|
- on **SessionStart**, every source (`startup`, `resume`, `clear`, `compact`, `fork`), runs
|
|
@@ -21,7 +21,7 @@ If none resolve, the user does not have Geneseed deployed here — say so and st
|
|
|
21
21
|
|
|
22
22
|
A live harness root contains: `AGENT.md`, `ontology/universal.md`, `laws/universal.md`, `doctrines/<pack>.md`, `agents/<name>.md`, `skills/<name>/SKILL.md`, `memory/MEMORY.md`, `notebook/NOTEBOOK.md`, `themes/`, and (on OpenCode) `plugins/`, `workflows/`, `opencode.jsonc`, `geneseed-wiki.jsonc`.
|
|
23
23
|
|
|
24
|
-
The constitution is **three tiers**: an always-on **Ontology** (
|
|
24
|
+
The constitution is **three tiers**: an always-on **Ontology** (five prose sections — Telos, Evidence, Decisions, Ownership, Conduct), nine always-on **Rules** numbered I–IX, and the **Doctrines** — practice packs (`craft`, `rigor`, `ops`, `process`, `comms`) chosen per install at build time. `AGENT.md` carries all three inline (whole at the `full` footprint, heading-plus-first-line at `lean`), *and* the complete text ships as files beside it. All five pack files ship even when a pack was not built in, so a citation into an inactive pack still resolves on disk — which is why a question about a rule is answered from the tier file, never only from `AGENT.md`.
|
|
25
25
|
|
|
26
26
|
## Read-only verbs (safe, no confirmation needed)
|
|
27
27
|
|
|
@@ -34,7 +34,7 @@ The constitution is **three tiers**: an always-on **Ontology** (four prose secti
|
|
|
34
34
|
- **Read a specific piece** — read the file directly:
|
|
35
35
|
- Agent by name: `<harness>/agents/<name>.md`
|
|
36
36
|
- Skill by name: `<harness>/skills/<name>/SKILL.md`
|
|
37
|
-
- Ontology section by name: `<harness>/ontology/universal.md` — `#### Telos` / `Evidence` / `Decisions` / `Conduct` (theme-independent names)
|
|
37
|
+
- Ontology section by name: `<harness>/ontology/universal.md` — `#### Telos` / `Evidence` / `Decisions` / `Ownership` / `Conduct` (theme-independent names)
|
|
38
38
|
- Rule by numeral I–IX: `<harness>/laws/universal.md` — heading `### <Rule-noun> <ROMAN> — <title>`
|
|
39
39
|
- Doctrine rule by pack and number: `<harness>/doctrines/<pack>.md` — heading `### <Doctrine-noun> <pack> <n> — <title>`
|
|
40
40
|
- Memory fact: `<harness>/memory/<file>.md`; index at `MEMORY.md`
|
|
@@ -127,7 +127,7 @@ to native **skills**, not slash commands (same `SKILL.md` shape as Claude Code).
|
|
|
127
127
|
| plugin on `experimental.session.compacting` | **context plugin** — re-pushes the `eager` docs so they survive compaction |
|
|
128
128
|
| plugin on `session.idle` | **learn plugin** — distils memory into `memory/` (debounced to fire once, at session end) |
|
|
129
129
|
| plugin on `experimental.chat.messages.transform` (V1) | **context plugin** — also adds the done gate's reminder when a check in `.geneseed/done-checks.txt` has not passed since the last edit (Verify Before Asserting); OpenCode 2 turns are not judged |
|
|
130
|
-
| plugin on `tool.execute.before` | **guard plugin** — blocks secret-file writes and credential-shaped write content (Sealed Secrets), writes to a protected check or the done list (External Gate), catastrophic shell and every other real data loss, judged against the repository's state (Deletion Is Deliberate), a recursive whole-filesystem scan (Commands Must Return), the first rule-store write (Persist Insight)
|
|
130
|
+
| plugin on `tool.execute.before` | **guard plugin** — blocks secret-file writes and credential-shaped write content (Sealed Secrets), writes to a protected check or the done list (External Gate), catastrophic shell and every other real data loss, judged against the repository's state (Deletion Is Deliberate), a recursive whole-filesystem scan (Commands Must Return), the first rule-store write (Persist Insight), protected wiki folders, and the session's first write in an application repo with no `## Ownership` section in its root `AGENTS.md` (the ownership gate, once; a child session defers; off with `--no-ownership-gate`); logs each block to the gate ledger and counts skill/subagent use (`GENESEED_GUARD=off\|warn`) |
|
|
131
131
|
| plugin registering a custom tool | **workflow plugin** — the `workflow` tool runs saved orchestration scripts from `workflows/` |
|
|
132
132
|
| `context.json` / `.harness/` (manifest) | *optional* override when discovery doesn't fit |
|
|
133
133
|
|
|
@@ -386,10 +386,13 @@ behaviour** — nothing changes the machine's current agent/model unless you opt
|
|
|
386
386
|
the safety Laws at the tool boundary: **blocks** writes to private-key/credential
|
|
387
387
|
files (Sealed Secrets), catastrophic shell like `rm -rf /` and every command that would really lose data, judged
|
|
388
388
|
against the repository's state (Deletion Is Deliberate), and any mutation under
|
|
389
|
-
a declared wiki's `protected` folders (AGENT.md §8, from `geneseed-wiki.jsonc`); **
|
|
389
|
+
a declared wiki's `protected` folders (AGENT.md §8, from `geneseed-wiki.jsonc`); **refuses
|
|
390
|
+
once** the session's first write in an application repo whose root `AGENTS.md` has no
|
|
391
|
+
`## Ownership` section (the ownership gate; a child session defers; off with `mode: off` in
|
|
392
|
+
that section or an install built `--no-ownership-gate`); **warns** on
|
|
390
393
|
`.env` writes. `GENESEED_GUARD=off` disables it, `=warn` downgrades
|
|
391
394
|
blocks to warnings. Every **block** appends one line to the install's
|
|
392
|
-
`notebook/gates.jsonl` (rule `law-1` / `law-4` / `process-1` / `wiki`, a timestamp,
|
|
395
|
+
`notebook/gates.jsonl` (rule `law-1` / `law-4` / `process-1` / `wiki` / `ownership`, a timestamp,
|
|
393
396
|
never the path or command) — the same ledger the Claude-family hooks write, so
|
|
394
397
|
`geneseed status` counts what the boundary caught on every host. Warnings are not
|
|
395
398
|
recorded.
|
|
@@ -13,10 +13,12 @@
|
|
|
13
13
|
// memory file — that choice belongs to the user, via the rule skill.
|
|
14
14
|
// - Wiki (AGENT.md §8): block mutations under a declared wiki's `protected`
|
|
15
15
|
// folders — the user's knowledge base sets its own no-go zones in geneseed-wiki.jsonc.
|
|
16
|
+
// - Ownership: in an application repo whose root AGENTS.md has no `## Ownership` section,
|
|
17
|
+
// refuse the session's first write once, so the agent proposes the setup first.
|
|
16
18
|
// High-confidence patterns only, so legitimate work is never caught. Borderline cases
|
|
17
19
|
// (.env edits) are WARNED, not blocked. Every block is recorded in the gate
|
|
18
20
|
// ledger (`<cfg>/notebook/gates.jsonl`) under the hook's rule key (`law-1`, `rigor-5`,
|
|
19
|
-
// `law-4`, `ops-2`, `process-1`, `wiki`); every skill or subagent call, blocked or not, is
|
|
21
|
+
// `law-4`, `ops-2`, `process-1`, `wiki`, `ownership`); every skill or subagent call, blocked or not, is
|
|
20
22
|
// counted in `<cfg>/notebook/usage.jsonl` when that `notebook/` exists and `.usage-off` does not.
|
|
21
23
|
//
|
|
22
24
|
// GENESEED_GUARD=off disable entirely.
|
|
@@ -152,6 +154,8 @@ const CARRIER_TEXT = carrierText()
|
|
|
152
154
|
const gateOff = (marker) => new RegExp(`^${marker}:[ \\t]*off[ \\t]*\\r?$`, "m").test(CARRIER_TEXT)
|
|
153
155
|
const DELETION_GATE_OFF = gateOff("Deletion gate")
|
|
154
156
|
const SECRETS_GATE_OFF = gateOff("Secrets gate")
|
|
157
|
+
// `--no-ownership-gate` (ruling D25): the ownership first-write gate below stands down.
|
|
158
|
+
const OWNERSHIP_GATE_OFF = gateOff("Ownership gate")
|
|
155
159
|
|
|
156
160
|
// OpenCode 1.x paints a plugin's stderr over its TUI input box (in red); its own log API
|
|
157
161
|
// writes to the log file instead. The V1 entry sets LOG_CLIENT; V2 and tests have no
|
|
@@ -1347,6 +1351,54 @@ function protectedIn(target) {
|
|
|
1347
1351
|
}
|
|
1348
1352
|
}
|
|
1349
1353
|
|
|
1354
|
+
// ---- the ownership first-write gate --------------------------------------------
|
|
1355
|
+
// Twin of js/hosts/ownership-gate.mjs's `ownershipBlock` — keep in step (same manifests, same
|
|
1356
|
+
// managed-block strip, same section match, same reason). In an application repo (a git root
|
|
1357
|
+
// holding a build manifest) whose root AGENTS.md has no `## Ownership` section outside the
|
|
1358
|
+
// Geneseed block, the first write of a session is refused once, so the agent proposes the setup
|
|
1359
|
+
// to the developer; the session and root are recorded BEFORE the refusal, so the next write
|
|
1360
|
+
// passes. The marker is this module Set: the plugin lives as long as the OpenCode process.
|
|
1361
|
+
const OWNERSHIP_SEEN = new Set()
|
|
1362
|
+
const OWNERSHIP_MANIFESTS = new Set(["package.json", "pom.xml", "pyproject.toml", "go.mod", "Cargo.toml",
|
|
1363
|
+
"composer.json", "Gemfile"])
|
|
1364
|
+
const isManifest = (n) => OWNERSHIP_MANIFESTS.has(n) || n.startsWith("build.gradle") || n.endsWith(".csproj")
|
|
1365
|
+
const MANAGED_BLOCK_RE = /<!-- BEGIN GENESEED -->[\s\S]*?<!-- END GENESEED -->/g
|
|
1366
|
+
const OWNERSHIP_SECTION_RE = /^## Ownership[ \t]*\r?$/m
|
|
1367
|
+
const OWNERSHIP_TAIL = "Opt out per repo: `## Ownership` with `mode: off` in the root `AGENTS.md`; per " +
|
|
1368
|
+
"install: rebuild with `--no-ownership-gate`. Offer the full documentation " +
|
|
1369
|
+
"(`/document-project`) as yes / later. Stop and ask the developer now; re-issue the write only " +
|
|
1370
|
+
"after they answer. This gate fires once per session and repo."
|
|
1371
|
+
const OWNERSHIP_REASON_NONE = "Geneseed (Ownership) — this application has no `AGENTS.md` with " +
|
|
1372
|
+
"`## Ownership`. Before writing, propose to the developer: set it up (ownership skill), or " +
|
|
1373
|
+
`proceed without for this session. ${OWNERSHIP_TAIL}`
|
|
1374
|
+
const OWNERSHIP_REASON_NO_SECTION = "Geneseed (Ownership) — this application's `AGENTS.md` has no " +
|
|
1375
|
+
"`## Ownership` section. Before writing, ask the developer: add the Ownership section " +
|
|
1376
|
+
`(ownership skill), or proceed without for this session? ${OWNERSHIP_TAIL}`
|
|
1377
|
+
// The reason to refuse this write, or null. `p` is absolute. Never throws.
|
|
1378
|
+
function ownershipBlock(p, sessionID) {
|
|
1379
|
+
try {
|
|
1380
|
+
if (typeof sessionID !== "string" || !sessionID) return null
|
|
1381
|
+
const root = gitRootOf(path.dirname(p))
|
|
1382
|
+
if (!root || !readdirSync(root).some(isManifest)) return null
|
|
1383
|
+
const rel = nocase(path.relative(root, p).replace(/\\/g, "/"))
|
|
1384
|
+
if (rel === nocase("AGENTS.md") || rel.startsWith(nocase(".geneseed/"))) return null
|
|
1385
|
+
// The install's own bookkeeping (memory/, notebook/ beside plugins/, or $GENESEED_HARNESS)
|
|
1386
|
+
// never spends the block — the hook twin's `installRoot`.
|
|
1387
|
+
for (const home of [path.dirname(PLUGIN_DIR), process.env.GENESEED_HARNESS].filter(Boolean)) {
|
|
1388
|
+
const inside = path.relative(path.resolve(home), p)
|
|
1389
|
+
if (!inside.startsWith("..") && !path.isAbsolute(inside)) return null
|
|
1390
|
+
}
|
|
1391
|
+
let text = null
|
|
1392
|
+
try { text = readFileSync(path.join(root, "AGENTS.md"), "utf8") } catch { /* none: gate */ }
|
|
1393
|
+
const own = text === null ? "" : text.replace(MANAGED_BLOCK_RE, "")
|
|
1394
|
+
if (OWNERSHIP_SECTION_RE.test(own)) return null
|
|
1395
|
+
const key = `${sessionID}|${nocase(root)}`
|
|
1396
|
+
if (OWNERSHIP_SEEN.has(key)) return null
|
|
1397
|
+
OWNERSHIP_SEEN.add(key)
|
|
1398
|
+
return own.trim() ? OWNERSHIP_REASON_NO_SECTION : OWNERSHIP_REASON_NONE
|
|
1399
|
+
} catch { return null }
|
|
1400
|
+
}
|
|
1401
|
+
|
|
1350
1402
|
// Mutation-class tools for the wiki check — wider than WRITE_TOOLS because moving,
|
|
1351
1403
|
// renaming, or deleting a protected note is as destructive as overwriting it. Same
|
|
1352
1404
|
// substring stance: over-matching the class is harmless (see WRITE_TOOLS note).
|
|
@@ -1386,6 +1438,17 @@ export const GeneseedGuard = async (ctx) => {
|
|
|
1386
1438
|
if (ctx?.client) LOG_CLIENT = ctx.client
|
|
1387
1439
|
// The session's working directory, the same resolution the context plugin uses.
|
|
1388
1440
|
const root = () => ctx?.worktree || ctx?.directory || process.cwd()
|
|
1441
|
+
// Whether a session has a parent (a subagent's child session). V2 hands in `sessionMeta`
|
|
1442
|
+
// (`ctx.session.get`); V1 asks its client. Read only on the rare would-block path; a failed
|
|
1443
|
+
// lookup reads as a top-level session.
|
|
1444
|
+
const isChildSession = async (sid) => {
|
|
1445
|
+
try {
|
|
1446
|
+
const info = ctx?.sessionMeta ? await ctx.sessionMeta(sid)
|
|
1447
|
+
: await ctx?.client?.session?.get?.({ path: { id: sid } })
|
|
1448
|
+
const meta = info?.data ?? info
|
|
1449
|
+
return Boolean(meta?.parentID ?? meta?.parentId)
|
|
1450
|
+
} catch { return false }
|
|
1451
|
+
}
|
|
1389
1452
|
return {
|
|
1390
1453
|
"tool.execute.before": async (input, output) => {
|
|
1391
1454
|
// Bypass before counting, the order Claude's toolGate keeps: an excluded repo is
|
|
@@ -1398,11 +1461,13 @@ export const GeneseedGuard = async (ctx) => {
|
|
|
1398
1461
|
const args = output?.args || input?.args || {}
|
|
1399
1462
|
// `rule` is the ledger key, spelled as js/hosts/hooks.mjs spells it (`law-1`,
|
|
1400
1463
|
// `law-4`, `process-1`) plus `wiki`, so status counts one vocabulary across hosts.
|
|
1401
|
-
|
|
1464
|
+
// `tail: false` for the ownership gate: its reason names its own ways out, and the next
|
|
1465
|
+
// write passes anyway, so pointing at GENESEED_GUARD=off would only invite disabling it.
|
|
1466
|
+
const deny = async (why, rule, tail = true) => {
|
|
1402
1467
|
if (WARN_ONLY) { log(`WARN (would block): ${why}`); return false }
|
|
1403
1468
|
log(`BLOCKED: ${why}`)
|
|
1404
1469
|
await ledger(rule)
|
|
1405
|
-
throw new Error(`[geneseed-guard] blocked: ${why} — set GENESEED_GUARD=off to allow`)
|
|
1470
|
+
throw new Error(`[geneseed-guard] blocked: ${why}${tail ? " — set GENESEED_GUARD=off to allow" : ""}`)
|
|
1406
1471
|
}
|
|
1407
1472
|
try {
|
|
1408
1473
|
// `apply_patch`'s own tool resolves every marker path against `instance.directory`
|
|
@@ -1443,6 +1508,14 @@ export const GeneseedGuard = async (ctx) => {
|
|
|
1443
1508
|
return
|
|
1444
1509
|
}
|
|
1445
1510
|
}
|
|
1511
|
+
// The ownership first-write gate, last, as in js/hosts/hooks.mjs's ruleDecide. A child
|
|
1512
|
+
// session is a subagent (ruling D29): it cannot ask the user, so it never spends a block.
|
|
1513
|
+
if (!OWNERSHIP_GATE_OFF) {
|
|
1514
|
+
for (const p of paths) {
|
|
1515
|
+
const why = ownershipBlock(path.resolve(cwd, p), input?.sessionID)
|
|
1516
|
+
if (why && !(await isChildSession(input.sessionID))) { await deny(why, "ownership", false); return }
|
|
1517
|
+
}
|
|
1518
|
+
}
|
|
1446
1519
|
}
|
|
1447
1520
|
if (hasAny(tool, WIKI_MUTATE_TOOLS)) {
|
|
1448
1521
|
for (const p of pickPath(args, cwd)) {
|
|
@@ -1499,10 +1572,12 @@ export const GeneseedGuard = async (ctx) => {
|
|
|
1499
1572
|
async function setupV2(ctx) {
|
|
1500
1573
|
const hooks = await GeneseedGuard({
|
|
1501
1574
|
worktree: ctx?.location?.project?.directory, directory: ctx?.location?.directory,
|
|
1575
|
+
sessionMeta: (sessionID) => ctx.session.get({ sessionID }),
|
|
1502
1576
|
})
|
|
1503
1577
|
await ctx.tool.hook("execute.before", async (event) => {
|
|
1504
1578
|
try {
|
|
1505
|
-
|
|
1579
|
+
// `sessionID` rides on every V2 execute.before event (@opencode/plugin 2.1.4 `ToolHooks`).
|
|
1580
|
+
await hooks["tool.execute.before"]({ tool: event.tool, sessionID: event.sessionID }, { args: event.input })
|
|
1506
1581
|
} catch (err) {
|
|
1507
1582
|
const why = String(err?.message || "")
|
|
1508
1583
|
if (!why.startsWith("[geneseed-guard]")) return
|
package/bin/geneseed-hook.mjs
CHANGED
|
@@ -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,
|
|
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: {
|
|
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'),
|
|
@@ -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.
|
|
@@ -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, 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
42
|
- `UserPromptSubmit` → `geneseed-hook activity`, which records the turn for the Activity view.
|
|
43
43
|
|
package/docs/concepts/hooks.md
CHANGED
|
@@ -18,7 +18,7 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
|
|
|
18
18
|
| --- | --- | --- | --- | --- |
|
|
19
19
|
| `SessionStart` | `startup`, `resume`, `clear`, `compact`, `fork` | `geneseed-hook context` | injects your harness files and the repo's docs, or re-injects them after a resume, a fork, or an auto-compaction summarised them away | no |
|
|
20
20
|
| `PreToolUse` | `Bash`, `PowerShell` | `geneseed-hook git-gate` | asks before a command that would really lose data, and before a recursive scan of a whole filesystem; asks before every commit and push | the commit/push question only |
|
|
21
|
-
| `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your rules 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` |
|
|
@@ -62,6 +62,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
|
|
|
62
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
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.
|
|
64
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)).
|
|
65
66
|
- Ordinary edits pass untouched.
|
|
66
67
|
|
|
67
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)).
|
|
@@ -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.
|