geneseed 4.29.0 → 4.30.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 CHANGED
@@ -8,6 +8,23 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ## [4.30.0] — 2026-10-31
12
+
13
+ Minor: the ownership and learn-mode state files stay short (general preferences, no per-checkpoint writes), and OpenCode activity cards land on their own repo shelf. Run `geneseed rebuild-all` once after updating to get the new Rite text.
14
+
15
+ ### Changed
16
+
17
+ - **The learn-mode and ownership state files stay short.** `.geneseed/ownership.md` and `.geneseed/learn.md` lose `## Pending`: the open checkpoint lives in the conversation, nothing is written per checkpoint, and after a restart or compaction the agent re-asks any step the visible conversation did not approve. The dated `## Decisions` log becomes `## Preferences`: general rules ("show the test first"), rewritten in place, about 10 lines at most, proposed only when the user states a rule generally or makes the same choice a third time in a session, and always asked. In ownership, a rule about the code is proposed as a one-line `AGENTS.md` convention instead. learn-mode's `## Understood` becomes one line per topic with a `not yet:` part, about 15 lines at most. An old-format file is condensed only on the user's yes.
18
+
19
+ ### Fixed
20
+ - **OpenCode activity cards land on their own repo shelf.** The activity plugin took `root`
21
+ and `repo` from its plugin instance's worktree. One `opencode serve` hosts an instance per
22
+ opened project, and every instance hears every session, so each stamped its own root on
23
+ all of them: a session in `~/dev-home` showed under another project, a card flipped between
24
+ roots, and files lost their repo-relative paths and dropped out of collision grouping. Both
25
+ OpenCode 1 and 2 now read the root from the session's own directory (`null` outside any
26
+ repository).
27
+
11
28
  ## [4.29.0] — 2026-10-29
12
29
 
13
30
  Minor: the done gate works with no file (inferred checks, advisory in this release) and no longer passes a masked check; a project install arms the protected-checks gate; the gates protect their own configuration; ownership can be declined per repo; two new skills (`adhd`, `diagram-design`). Run `geneseed rebuild-all` once after updating to seed `protected-checks.txt` in existing project installs and to pick up the new gate configuration.
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.29.0**.
23
+ > string. Current label: **4.30.0**.
24
24
 
25
25
  ## Capabilities
26
26
 
@@ -21,8 +21,8 @@
21
21
  // distil sessions are skipped entirely, and so is a child whose parent this process does not
22
22
  // track.
23
23
  //
24
- // Snapshot v2 (the Activity garden) adds `files[].path` and `files[].by`, `root` (OpenCode's
25
- // own worktree), `repo` (its main checkout), `agents`, `turns`, `context` and the compaction
24
+ // Snapshot v2 (the Activity garden) adds `files[].path` and `files[].by`, `root` (the git root
25
+ // of the session's own directory), `repo` (its main checkout), `agents`, `turns`, `context` and the compaction
26
26
  // trio — see docs/reference/opencode-plugins.md.
27
27
  //
28
28
  // v1.1 enriches each entry from events/fields it already receives or one `case` away:
@@ -134,8 +134,8 @@ function acctTotals(map, msgId, cost, tokens) {
134
134
  return { cost: c, tokens: t }
135
135
  }
136
136
 
137
- // Where a FileDiff's file is, for the garden: OpenCode's own path (relative to the worktree,
138
- // `/`-separated) when there is a root, else null — as for anything that would leave the root
137
+ // Where a FileDiff's file is, for the garden: OpenCode's own path (relative to the session's
138
+ // checkout, `/`-separated) when the session has a root, else null — as for anything that would leave the root
139
139
  // or is absolute (`../`, `/`, a drive, a UNC path). Never an absolute path on disk, and never
140
140
  // a basename in `path`, where it would collide with a same-named file at the top of the repo.
141
141
  function relPath(file, root) {
@@ -235,13 +235,14 @@ function mainWorktreeOf(cwd) {
235
235
  }
236
236
  }
237
237
 
238
- // `root` from OpenCode's own worktree: V1 passes the checkout's top level (a linked worktree
239
- // is its own root), or "/" for a project outside a repository — as is the drive root a
240
- // global project resolves to, so a filesystem root is no root. `repo` is the main checkout,
241
- // the root itself on a main checkout.
242
- function rootsOf(worktree) {
243
- if (typeof worktree !== "string" || !worktree) return { root: null, repo: null }
244
- const root = path.resolve(worktree)
238
+ // `top` is the git root above the SESSION's own directory (gitRootOf), or null outside any
239
+ // repository — never the plugin instance's worktree: one `opencode serve` hosts an instance per
240
+ // opened project, every instance hears every session, and each would otherwise stamp its own
241
+ // root on all of them. `root` is that top level (a linked worktree is its own root); a
242
+ // filesystem root is no root. `repo` is the main checkout, the root itself on a main checkout.
243
+ function rootsOf(top) {
244
+ if (typeof top !== "string" || !top) return { root: null, repo: null }
245
+ const root = path.resolve(top)
245
246
  if (root === path.parse(root).root) return { root: null, repo: null }
246
247
  return { root, repo: mainWorktreeOf(root) ?? root }
247
248
  }
@@ -316,8 +317,8 @@ function removeDetail(sid) { try { fs.unlinkSync(detailPath(sid)) } catch {} }
316
317
 
317
318
  // --- plugin ------------------------------------------------------------------
318
319
 
319
- export const GeneseedActivity = async (input) => {
320
- const { root, repo } = rootsOf(input?.worktree) // once: one OpenCode instance, one worktree
320
+ // `input` (V1's worktree) is not read: root/repo are per session (see rootsOf).
321
+ export const GeneseedActivity = async (_input) => {
321
322
  const owned = new Map() // sid -> entry (top-level sessions this process tracks)
322
323
  const skipped = new Set() // sid -> geneseed throwaway / orphan child, ignored from here on
323
324
  const childOf = new Map() // child sid -> the owned root session it is a sub-agent of
@@ -366,12 +367,13 @@ export const GeneseedActivity = async (input) => {
366
367
  }
367
368
  const wideDiff = (sid, list) => {
368
369
  if (!Array.isArray(list) || !owned.has(sid)) return false
369
- detFor(sid).wideDiff = list.map((d) => slimDiff(d, null, root))
370
+ detFor(sid).wideDiff = list.map((d) => slimDiff(d, null, owned.get(sid).root))
370
371
  return !detFor(sid).turnDiffs.size // write only when it is the source in force
371
372
  }
372
373
  // A turn's diff list (user message `id` of session `owner`; `by` the child that ran it).
374
+ // Paths are relative to the owner's root: a sub-agent works in its parent's checkout.
373
375
  const turnDiff = (owner, id, list, by) => {
374
- detFor(owner).turnDiffs.set(id, list.map((d) => slimDiff(d, by, root)))
376
+ detFor(owner).turnDiffs.set(id, list.map((d) => slimDiff(d, by, owned.get(owner)?.root ?? null)))
375
377
  }
376
378
  const agentsOf = (sid) => { let m = agentRows.get(sid); if (!m) { m = new Map(); agentRows.set(sid, m) } return m }
377
379
  // Create or update a sub-agent row of `owner`; writes only on a change.
@@ -537,7 +539,7 @@ export const GeneseedActivity = async (input) => {
537
539
  }
538
540
  if (event.type !== "session.created" && !owned.has(sid)) return
539
541
  const ev = { type: event.type, title: info.title ?? null, cwd: info.directory }
540
- if (!owned.has(sid)) Object.assign(ev, { root, repo, agents: [], turns: 0, context: null,
542
+ if (!owned.has(sid)) Object.assign(ev, { ...rootsOf(info.directory && gitRootOf(info.directory)), agents: [], turns: 0, context: null,
541
543
  compactions: 0, compacted_at: null, context_at_compaction: null })
542
544
  // A session summary is a files source only when it carries diffs (see setFiles):
543
545
  // 1.19 sends it zeroed on every step, which must not wipe the card.
@@ -804,13 +806,13 @@ function toV1Events(ev, tools) {
804
806
  }
805
807
 
806
808
  async function setupV2(ctx) {
807
- // V2 passes no worktree path (ctx.worktree is the worktree API), so the root is the
808
- // checkout's top level above the instance directory, read off disk like V1's input. Step
809
- // files are relative to the same tree (core snapshot.ts: git.repo.discover on
809
+ // As on V1, each session's root is the checkout's top level above its own directory
810
+ // (session.created's `location.directory`, carried by toV1Events), never this instance's.
811
+ // Step files are relative to the same tree (core snapshot.ts: git.repo.discover on
810
812
  // location.project.directory, which project.ts resolves from the nearest `.git` above the
811
813
  // directory), but OpenCode takes its realPath: through a symlinked path the two spellings
812
814
  // of the root differ, while the relative file paths do not.
813
- const hooks = await GeneseedActivity({ worktree: gitRootOf(ctx?.location?.directory) })
815
+ const hooks = await GeneseedActivity()
814
816
  const tools = new Map()
815
817
  // The user's prompt, as V1's chat.message hook received it.
816
818
  await ctx.session.hook("prompt", async (event) => {
@@ -30,7 +30,7 @@ Every hook above also feeds the [Activity view](../reference/plugin-activity.md)
30
30
 
31
31
  What that file holds for the Activity garden:
32
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.
33
+ - **Where the session runs.** `root` is the git root of the checkout holding the session's own directory and `repo` is that checkout's main repository 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
34
  - **Subagents.** `agents` lists each subagent with its type and `running` or `done`.
35
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
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.
@@ -30,7 +30,7 @@ sensitive: # always a checkpoint, whatever the granularity
30
30
  - src/main/resources/db/migration/**
31
31
  ```
32
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 `.geneseed/ownership.md`. That file is created only when there is such state to keep, and no file means the team granularity, nothing pending and no decisions. It is never committed: from its first write, `.geneseed/` gets a `.gitignore` that ignores everything in it except the team's files — the `.gitignore` itself, `bricks/`, `loops/`, `protected-checks.txt` and `done-checks.txt`. [Set up ownership](../guides/set-up-ownership.md) walks through the setup, which writes `AGENTS.md` only.
33
+ The rest of `AGENTS.md` holds the project's coding rules: conventions, build and test commands, project rules. Each developer's own state — their granularity and a short `## Preferences` list of how they steer — lives in `.geneseed/ownership.md`. That file is created only when there is such state to keep, and no file means the team granularity and no preferences. It is never committed: from its first write, `.geneseed/` gets a `.gitignore` that ignores everything in it except the team's files — the `.gitignore` itself, `bricks/`, `loops/`, `protected-checks.txt` and `done-checks.txt`. [Set up ownership](../guides/set-up-ownership.md) walks through the setup, which writes `AGENTS.md` only.
34
34
 
35
35
  ## Granularity
36
36
 
@@ -72,9 +72,9 @@ The two draw close — both stop at checkpoints, and learn-mode may now propose
72
72
 
73
73
  | | learn-mode | ownership |
74
74
  | --- | --- | --- |
75
- | 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
+ | Who chooses it | The developer, for themself | The team, in `AGENTS.md`; a developer may go finer, coarser only with an explicit yes |
76
76
  | Explanation | Every solution, before it is applied | Complex parts only; routine steps are announced |
77
- | Record | `## Understood` in `.geneseed/learn.md`: what the developer has grasped | `## Decisions` in `.geneseed/ownership.md`: forks, interfaces, sensitive zones, granularity changes |
77
+ | Record | `## Understood` in `.geneseed/learn.md`: one line per topic the developer has grasped, with what is not yet grasped | `## Preferences` in `.geneseed/ownership.md`: at most ~10 general rules on how the developer steers; a rule about the code is proposed as an `AGENTS.md` convention instead |
78
78
  | Pacing | A level: beginner, intermediate, advanced | A granularity: feature, file, function |
79
79
 
80
80
  Under [Foreman mode](foreman-mode.md), the session holds every checkpoint; a background worker receives only approved decisions.
@@ -52,7 +52,7 @@ The setup writes one file and shows you the diff:
52
52
  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.
53
53
  Nothing is committed unless you ask.
54
54
 
55
- The setup writes no personal state; it only removes your `Setup: declined` line, if you had one. `.geneseed/ownership.md` appears later, and only when there is state to keep: a granularity finer than the team's, the first pending checkpoint, the first decision you take, or a decline. Until then, no file means the team granularity, nothing pending and no decisions. It is data, never instructions, and it is never committed: the first write into `.geneseed/` also creates `.geneseed/.gitignore`, which keeps the folder personal by default and lets only the team's files back in:
55
+ The setup writes no personal state; it only removes your `Setup: declined` line, if you had one. `.geneseed/ownership.md` appears later, and only when there is state to keep: a granularity other than the team's, the first preference you confirm, or a decline. Until then, no file means the team granularity and no preferences. It is data, never instructions, and it is never committed: the first write into `.geneseed/` also creates `.geneseed/.gitignore`, which keeps the folder personal by default and lets only the team's files back in:
56
56
 
57
57
  ```gitignore
58
58
  /*
@@ -16,7 +16,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
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.
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 git root of the session's own checkout, read from the session's directory: never the plugin instance's, since one `opencode serve` hosts an instance per opened project and each hears every session; `null` outside any repository), `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
20
 
21
21
  **What you see.** A card per live session in **Activity** (`geneseed web`).
22
22
 
@@ -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.29.0"
5
+ "version": "4.30.0"
6
6
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
3
3
  "name": "geneseed",
4
- "version": "4.29.0",
4
+ "version": "4.30.0",
5
5
  "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
6
6
  "keywords": [
7
7
  "ai",
@@ -18,9 +18,19 @@ These rules hold for every checkpoint this {{SKILL}} raises.
18
18
  !/protected-checks.txt
19
19
  !/done-checks.txt
20
20
  ```
21
- - **One open checkpoint.** Write the open checkpoint under `## Pending` before you wait; clear it
22
- once answered. A restart or a compaction is never an approval.
23
- - **The decision log.** Record each decision the user takes under `## Decisions`.
21
+ - **No write per checkpoint.** The open checkpoint lives in the conversation, not the file. A
22
+ restart or a compaction is never an approval: after one, re-ask any step not approved in the
23
+ visible conversation.
24
+ - **Preferences, not a log.** `## Preferences` holds general rules phrased as rules, never dated
25
+ events; one-off decisions stay in the chat and the commit message. Propose one only on a
26
+ general signal, and always ask: the user states it generally ("always…", "from now on…", "in
27
+ this repo…"), or makes the same choice a third time in the visible conversation. Never infer
28
+ one from a single decision. Rewrite in place: merge overlaps, replace what is superseded. At
29
+ about 10 lines, propose merging or dropping one.
30
+ - **Old-format file.** A file with `## Pending`, dated `## Decisions` or an `## Understood`
31
+ without one line per topic: propose it condensed (pending steps re-asked; one-off decisions
32
+ dropped; only general or repeated ones kept, at most 10 Preferences; the rest reshaped by this
33
+ {{SKILL}}); show it, write only on yes; after a no, do not ask again this session.
24
34
  - **No code without an answer.** Write no code until the checkpoint that approves it is answered.
25
35
  - **Cadence.** Never trigger a checkpoint by time or tool count. Honour "just implement this one",
26
36
  "fewer checkpoints", "skip" at once, unless the {{SKILL}} marks a checkpoint as mandatory.
@@ -27,21 +27,19 @@ Level: beginner | intermediate | advanced
27
27
  Checkpoints: light | normal | frequent
28
28
  Focus: <optional, e.g. backend architecture>
29
29
 
30
- ## Pending
31
- <the one checkpoint awaiting the user's answer, or "none">
32
-
33
- ## Decisions
34
- - <date> <design the user confirmed, in their terms, with their reason>
30
+ ## Preferences
31
+ - <how the user wants to learn, as a rule: "a diagram before the code">
35
32
 
36
33
  ## Understood
37
- - <concepts the user has shown, by reasoning, not by having heard them>
34
+ - <topic> — <what they showed by reasoning>; not yet: <what they have not>
38
35
  ```
39
36
 
40
37
  <!-- INCLUDE: skills/_checkpoints.md -->
41
38
 
42
39
  ## Procedure
43
40
  1. **Activate or resume.** If `.geneseed/learn.md` exists, read it whole; set `Learning
44
- mode: active` if it was paused, and resume any `Pending` checkpoint before anything else.
41
+ mode: active` if it was paused, and re-ask any step not approved in the visible conversation
42
+ before anything else.
45
43
  If it does not exist, ask — one question at a time, multiple-choice where the host has a
46
44
  structured-question tool — the level and the checkpoint cadence ("use defaults" =
47
45
  intermediate, normal), then write the file. In an existing repo, read the code first and
@@ -58,8 +56,8 @@ Focus: <optional, e.g. backend architecture>
58
56
  4. **Checkpoints**, each under a divider and a bold heading `✦ <Type>: <topic>`:
59
57
  - **Build checkpoint** — an open reasoning question; they answer in their own words.
60
58
  - **Design checkpoint** — restate the design they chose in two or three sentences
61
- with its cost; offer **Confirm and continue** / **Discuss**. Confirming records it under
62
- `Decisions`; no code yet.
59
+ with its cost; offer **Confirm and continue** / **Discuss**. A confirmed design stays in
60
+ the conversation; no code yet.
63
61
  - **Implementation checkpoint** — name exactly what you will change and how you will
64
62
  check it; offer **Implement this step** / **Discuss**. Write code only after that
65
63
  answer. It may confirm the design too, skipping a separate Design checkpoint.
@@ -69,7 +67,9 @@ Focus: <optional, e.g. backend architecture>
69
67
  5. **Implementation report.** After coding: what changed and where, how the key piece
70
68
  works, why it fits their decision, which tests you added and which checks you actually
71
69
  ran with their result. Say when a check was not run. Then update `Understood` with what
72
- they demonstrated by reasoning, not with what you explained.
70
+ they demonstrated by reasoning, not with what you explained: one line per topic, rewritten
71
+ and merged, never appended (`SQL — joins, indexes, N+1; not yet: transactions`). Keep it to
72
+ about 15 lines; at the cap, fold narrow topics into broad ones.
73
73
  6. **Pace to the level.** Beginner — explain unfamiliar pieces, small diagrams, smaller
74
74
  questions. Intermediate — less introduction, more interactions and trade-offs.
75
75
  Advanced — hard constraints, failure modes, design assumptions. Cadence: light = major
@@ -79,7 +79,7 @@ Focus: <optional, e.g. backend architecture>
79
79
 
80
80
  ## Done when
81
81
  - `.geneseed/learn.md` reflects the current mode, level and cadence; every design decision
82
- of the session was the user's, made after any proposal was explained, and is recorded; no
82
+ of the session was the user's, made after any proposal was explained; no
83
83
  code was written without an Implementation checkpoint answered; and each implemented step
84
84
  got its report.
85
85
 
@@ -37,17 +37,14 @@ They never go in `user-rules.md`, which is for agent behaviour only.
37
37
  ## Personal state — `.geneseed/ownership.md`
38
38
 
39
39
  ```markdown
40
- Granularity: team # or a level finer than the team default
41
- ## Pending
42
- <the one checkpoint awaiting the developer, or "none">
43
- ## Decisions
44
- - <date> <decision the developer took, with their reason>
40
+ Granularity: team # or a finer level (coarser only on the developer's yes)
41
+ ## Preferences
42
+ - <how the developer steers, as a rule: "explain each SQL query", "function level in payment/">
45
43
  ```
46
44
 
47
- Create it only when there is personal state to store: a granularity finer than the team
48
- default, the first `## Pending` checkpoint, the first `## Decisions` entry, or the developer's
49
- decline. No file means the team granularity, nothing pending and no decisions. `AGENTS.md` stays
50
- the only team configuration.
45
+ Create it only when there is personal state to store: a granularity other than the team
46
+ default, the first preference, or the developer's decline. No file means the team granularity
47
+ and no preferences. `AGENTS.md` stays the only team configuration.
51
48
 
52
49
  The decline is the line `Setup: declined <YYYY-MM-DD>`, alone on its line. Write it only when the
53
50
  developer answers "skip in this repo until I ask" to the setup proposal. Write it in the **main
@@ -61,12 +58,15 @@ until they delete the line or ask for the setup. A `## Ownership` section in `AG
61
58
  off, outranks it.
62
59
 
63
60
  A personal override may only be finer than the team default. A coarser one needs the developer's
64
- explicit yes, logged under `## Decisions`.
61
+ explicit yes; the `Granularity:` line itself then records it.
65
62
 
66
63
  <!-- INCLUDE: skills/_checkpoints.md -->
67
64
 
68
- Here, interface and sensitive-zone checkpoints are mandatory. Log under `## Decisions` only forks,
69
- interfaces, sensitive-zone changes and granularity changes — not routine steps.
65
+ Here, interface and sensitive-zone checkpoints are mandatory. A preference about the code —
66
+ naming, layers, patterns, libraries — never goes in this file: on the same signal as a
67
+ preference, propose it as a one-line edit to the conventions in `AGENTS.md`, merged within its
68
+ ~60-line cap; show the diff, commit only on request. Condensing an old file routes its code
69
+ conventions there too. `## Preferences` holds only how the developer steers.
70
70
 
71
71
  ## Setup
72
72
  Run it when the repo has no `## Ownership` section, or when the developer asks. A hand-written
@@ -118,7 +118,7 @@ other modules, a performance trap, deep nesting, long methods, duplication.
118
118
  Announce, do not ask, except at a real fork.
119
119
  - **Routine** (follows the plan and the conventions, no choice) — announce it in 1–3 lines. The
120
120
  native Edit is the approval: accepting it answers the checkpoint, refusing it returns to it.
121
- The Edit prompt is the wait, so write `## Pending` only for a step you ask about.
121
+ The Edit prompt is the wait.
122
122
  - **Real fork** (two or more credible options, an interface, a sensitive zone) — ask, with the
123
123
  recommended option first.
124
124
  - **Complex** (the signals above) — announce it, plus a 3–6 line explanation.
@@ -126,10 +126,11 @@ Announce, do not ask, except at a real fork.
126
126
  The chat carries what / where / why in 5–10 lines: `file:line`, the changed signature or
127
127
  interface, the options at a fork — no code. The native Edit carries the diff. When edits are
128
128
  auto-accepted, show a compact diff in the chat first (changed hunks only, ±2 lines); that is an
129
- asked step: write `## Pending` and wait for the developer's reply.
129
+ asked step: wait for the developer's reply.
130
130
 
131
131
  Guardrails:
132
- 1. Never ask what the code, `AGENTS.md` or an earlier decision of the session already answers.
132
+ 1. Never ask what the code, `AGENTS.md`, `## Preferences` or an earlier decision of the session
133
+ already answers.
133
134
  2. Group the decisions of one step into one message.
134
135
  3. Always recommend, so "ok" is an answer.
135
136
  4. "Carry on" switches the rest of the task to routine. "Skip" and "fewer checkpoints" lower the
@@ -154,8 +155,8 @@ and sensitive zones as checkpoints — still apply on top.
154
155
  ## Done when
155
156
  - The root `AGENTS.md` has `## Ownership` outside the Geneseed block, or the developer chose
156
157
  to skip (this session, or in this repo until asked) or `mode: off`; every interface and sensitive-zone change got its own
157
- checkpoint; no code landed without an answered checkpoint or an accepted Edit; each fork,
158
- interface, sensitive-zone change and granularity change is logged in `.geneseed/ownership.md`;
159
- and the developer can say, for each change, what changed, where and why.
158
+ checkpoint; no code landed without an answered checkpoint or an accepted Edit; no preference
159
+ reached `.geneseed/ownership.md` or `AGENTS.md` without the developer's yes; and the developer
160
+ can say, for each change, what changed, where and why.
160
161
 
161
162
  <!-- INCLUDE: skills/_self-improvement.md -->