geneseed 4.27.1 → 4.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/README.md +7 -4
  3. package/SHIPPED.md +2 -2
  4. package/adapters/bob/README.md +1 -1
  5. package/adapters/claude-code/README.md +4 -2
  6. package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -2
  7. package/adapters/opencode/README.md +18 -2
  8. package/adapters/opencode/plugins/geneseed-context.js +155 -18
  9. package/adapters/opencode/plugins/geneseed-guard.js +59 -8
  10. package/adapters/opencode/plugins/geneseed-workflow.js +27 -8
  11. package/adapters/opencode/workflows/_runtime.js +14 -3
  12. package/docs/concepts/enforcement-table.md +5 -4
  13. package/docs/concepts/exclusions.md +3 -3
  14. package/docs/concepts/hooks.md +11 -3
  15. package/docs/concepts/ownership.md +7 -6
  16. package/docs/concepts/skills.md +1 -0
  17. package/docs/guides/set-up-ownership.md +22 -6
  18. package/docs/reference/environment.md +1 -0
  19. package/docs/reference/plugin-context.md +3 -1
  20. package/docs/reference/plugin-guard.md +1 -1
  21. package/docs/understand/enforced-vs-asked.md +3 -3
  22. package/docs/understand/machine-bob.md +1 -1
  23. package/docs/understand/machine-claude.md +1 -1
  24. package/docs/understand/machine-opencode.md +1 -1
  25. package/harness.config.json +1 -1
  26. package/js/README.md +3 -1
  27. package/js/build/driver.mjs +29 -9
  28. package/js/build/emit-opencode.mjs +12 -10
  29. package/js/build/render.mjs +9 -0
  30. package/js/hosts/done-checks.mjs +134 -0
  31. package/js/hosts/geneseed-dir.mjs +116 -0
  32. package/js/hosts/hooks-context.mjs +19 -0
  33. package/js/hosts/hooks-done.mjs +82 -38
  34. package/js/hosts/hooks-learn.mjs +9 -2
  35. package/js/hosts/hooks-prims.mjs +4 -0
  36. package/js/hosts/hooks.mjs +139 -6
  37. package/js/hosts/hosts.mjs +6 -0
  38. package/js/hosts/native.mjs +1 -1
  39. package/js/hosts/owned.mjs +19 -0
  40. package/js/hosts/ownership-gate.mjs +64 -10
  41. package/js/hosts/settings.mjs +115 -74
  42. package/js/inspect/checks-constitution.mjs +5 -1
  43. package/js/inspect/cost.mjs +1 -1
  44. package/js/inspect/doctor.mjs +2 -1
  45. package/js/inspect/inventory.mjs +1 -1
  46. package/js/inspect/status.mjs +2 -1
  47. package/js/inspect/validate.mjs +2 -1
  48. package/js/lib/json.mjs +70 -0
  49. package/js/maintain/uninstall.mjs +18 -5
  50. package/js/web/gates-api.mjs +2 -2
  51. package/package.json +1 -1
  52. package/registry.json +14 -0
  53. package/src/AGENT.md.tmpl +2 -2
  54. package/src/doctrines/comms.md +9 -2
  55. package/src/licenses/i-have-adhd.txt +21 -0
  56. package/src/skills/_checkpoints.md +15 -2
  57. package/src/skills/adhd.md +40 -0
  58. package/src/skills/diagram-design/LICENSE +21 -0
  59. package/src/skills/diagram-design/SKILL.md +392 -0
  60. package/src/skills/diagram-design/THIRD_PARTY_LICENSES.md +134 -0
  61. package/src/skills/diagram-design/VENDOR.md +81 -0
  62. package/src/skills/diagram-design/assets/example-architecture.html +183 -0
  63. package/src/skills/diagram-design/assets/example-venn.html +110 -0
  64. package/src/skills/diagram-design/assets/template-dark.html +99 -0
  65. package/src/skills/diagram-design/assets/template-full.html +421 -0
  66. package/src/skills/diagram-design/assets/template-motion.html +448 -0
  67. package/src/skills/diagram-design/assets/template-terminal.html +188 -0
  68. package/src/skills/diagram-design/assets/template.html +100 -0
  69. package/src/skills/diagram-design/references/animation.md +135 -0
  70. package/src/skills/diagram-design/references/layout-budget.md +97 -0
  71. package/src/skills/diagram-design/references/onboarding.md +368 -0
  72. package/src/skills/diagram-design/references/output-spec.md +277 -0
  73. package/src/skills/diagram-design/references/primitive-annotation.md +36 -0
  74. package/src/skills/diagram-design/references/primitive-icons.md +782 -0
  75. package/src/skills/diagram-design/references/primitive-sketchy.md +43 -0
  76. package/src/skills/diagram-design/references/primitive-terminal.md +76 -0
  77. package/src/skills/diagram-design/references/primitives-core.md +144 -0
  78. package/src/skills/diagram-design/references/profiles.md +183 -0
  79. package/src/skills/diagram-design/references/semantic-patterns.md +154 -0
  80. package/src/skills/diagram-design/references/style-guide.md +232 -0
  81. package/src/skills/diagram-design/references/type-architecture-delta.md +143 -0
  82. package/src/skills/diagram-design/references/type-architecture.md +117 -0
  83. package/src/skills/diagram-design/references/type-axonometric-plan.md +83 -0
  84. package/src/skills/diagram-design/references/type-bar.md +108 -0
  85. package/src/skills/diagram-design/references/type-data-flow.md +371 -0
  86. package/src/skills/diagram-design/references/type-db-schema.md +48 -0
  87. package/src/skills/diagram-design/references/type-dependency.md +44 -0
  88. package/src/skills/diagram-design/references/type-deployment.md +45 -0
  89. package/src/skills/diagram-design/references/type-dp-integration.md +407 -0
  90. package/src/skills/diagram-design/references/type-dp-security-matrix.md +379 -0
  91. package/src/skills/diagram-design/references/type-er.md +25 -0
  92. package/src/skills/diagram-design/references/type-exploded.md +115 -0
  93. package/src/skills/diagram-design/references/type-fishbone.md +75 -0
  94. package/src/skills/diagram-design/references/type-flowchart.md +23 -0
  95. package/src/skills/diagram-design/references/type-gantt.md +45 -0
  96. package/src/skills/diagram-design/references/type-heatmap.md +80 -0
  97. package/src/skills/diagram-design/references/type-high-level.md +470 -0
  98. package/src/skills/diagram-design/references/type-it-state.md +468 -0
  99. package/src/skills/diagram-design/references/type-journey.md +55 -0
  100. package/src/skills/diagram-design/references/type-kanban.md +49 -0
  101. package/src/skills/diagram-design/references/type-layers.md +26 -0
  102. package/src/skills/diagram-design/references/type-line.md +337 -0
  103. package/src/skills/diagram-design/references/type-loop.md +223 -0
  104. package/src/skills/diagram-design/references/type-medallion.md +356 -0
  105. package/src/skills/diagram-design/references/type-nested.md +22 -0
  106. package/src/skills/diagram-design/references/type-org-chart.md +44 -0
  107. package/src/skills/diagram-design/references/type-polar.md +136 -0
  108. package/src/skills/diagram-design/references/type-process.md +490 -0
  109. package/src/skills/diagram-design/references/type-pyramid.md +33 -0
  110. package/src/skills/diagram-design/references/type-quadrant.md +81 -0
  111. package/src/skills/diagram-design/references/type-radar.md +82 -0
  112. package/src/skills/diagram-design/references/type-sankey.md +75 -0
  113. package/src/skills/diagram-design/references/type-scatter.md +276 -0
  114. package/src/skills/diagram-design/references/type-sequence.md +130 -0
  115. package/src/skills/diagram-design/references/type-service-blueprint.md +103 -0
  116. package/src/skills/diagram-design/references/type-state.md +30 -0
  117. package/src/skills/diagram-design/references/type-story-map.md +46 -0
  118. package/src/skills/diagram-design/references/type-swimlane.md +22 -0
  119. package/src/skills/diagram-design/references/type-timeline.md +20 -0
  120. package/src/skills/diagram-design/references/type-tree.md +24 -0
  121. package/src/skills/diagram-design/references/type-treemap.md +137 -0
  122. package/src/skills/diagram-design/references/type-uml-class.md +65 -0
  123. package/src/skills/diagram-design/references/type-venn.md +26 -0
  124. package/src/skills/diagram-design/references/type-wardley.md +39 -0
  125. package/src/skills/diagram-design/references/type-waterfall.md +75 -0
  126. package/src/skills/document-project.md +4 -1
  127. package/src/skills/ownership.md +26 -4
  128. package/src/upstreams.json +14 -0
  129. package/themes/_TEMPLATE.json +1 -0
  130. package/themes/biker.json +1 -0
  131. package/themes/commentator.json +1 -0
  132. package/themes/cyberpunk.json +1 -0
  133. package/themes/gamer.json +1 -0
  134. package/themes/imperial.json +1 -0
  135. package/themes/joker.json +1 -0
  136. package/themes/marvin.json +1 -0
  137. package/themes/mean.json +1 -0
  138. package/themes/military.json +1 -0
  139. package/themes/neutral.json +1 -0
  140. package/themes/pirate.json +1 -0
  141. package/themes/sports.json +1 -0
  142. package/themes/verstappen.json +1 -0
  143. package/themes/wizard.json +1 -0
@@ -14,7 +14,8 @@
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
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.
17
+ // refuse the session's first write once, so the agent proposes the setup first — unless
18
+ // the developer's personal `.geneseed/ownership.md` holds `Setup: declined <date>`.
18
19
  // High-confidence patterns only, so legitimate work is never caught. Borderline cases
19
20
  // (.env edits) are WARNED, not blocked. Every block is recorded in the gate
20
21
  // ledger (`<cfg>/notebook/gates.jsonl`) under the hook's rule key (`law-1`, `rigor-5`,
@@ -140,11 +141,12 @@ const WARN_ONLY = MODE === "warn"
140
141
  // restart. Anything unreadable or unexpected reads as ARMED. Each stands down only its own check
141
142
  // below (the real-loss check; the Sealed Secrets path block and content scan) — catastrophic
142
143
  // commands, root scans and protected checks still block.
144
+ // Every dir the carrier may come from, in read order; the gate-config check protects AGENT.md in each.
145
+ const CARRIER_DIRS = [...(process.env.GENESEED_HARNESS ? [process.env.GENESEED_HARNESS] : []),
146
+ path.resolve(PLUGIN_DIR, ".."), path.resolve(PLUGIN_DIR, "..", "..")]
143
147
  function carrierText() {
144
148
  try {
145
- const dirs = [path.resolve(PLUGIN_DIR, ".."), path.resolve(PLUGIN_DIR, "..", "..")]
146
- if (process.env.GENESEED_HARNESS) dirs.unshift(process.env.GENESEED_HARNESS)
147
- for (const d of dirs) {
149
+ for (const d of CARRIER_DIRS) {
148
150
  try { return readFileSync(path.join(d, "AGENT.md"), "utf8") } catch { continue }
149
151
  }
150
152
  } catch { /* fall through: armed */ }
@@ -1355,6 +1357,37 @@ function protectedIn(target) {
1355
1357
  }
1356
1358
  }
1357
1359
 
1360
+ // ---- the gates' own configuration (External Gate) ------------------------------
1361
+ // Twin of js/hosts/hooks.mjs's `gateConfig`, MINUS what OpenCode now asks about itself
1362
+ // (tests/plugins/guard.test.mjs pins the difference). A file that turns a gate off is a gate the
1363
+ // agent can switch off. Every host's shared config — `opencode.json(c)`, the hook `settings.json`
1364
+ // files — and this install's own files (its `AGENT.md`, `excludes.json`, manifest,
1365
+ // `plugins/geneseed-*.js`) and the hook shim dir get a native `permission.edit` "ask" written into
1366
+ // opencode.json by the emit (`opencodeEditAsks`, js/hosts/settings.mjs), so the user can approve
1367
+ // the edit: this guard must not deny those, or the ask never shows. What stays a deny here is
1368
+ // Geneseed-only state of the OTHER hosts, which no user edits through OpenCode — their
1369
+ // `excludes.json`, `AGENT.md` and manifests, found by the parent's folder name — and an `AGENT.md`
1370
+ // under `$GENESEED_HARNESS`, a carrier the emit cannot name.
1371
+ const GATE_CONFIG_FILES = ['excludes.json', 'AGENT.md', '.geneseed-manifest.json', '.geneseed-emit'];
1372
+ const GATE_CONFIG_MARKERS = ['.claude', '.openclaude', '.bob'];
1373
+ const GATE_CONFIG_ASK = 'is a gate\'s own configuration (the hook wiring, the exclusion list, a gate switch or the hook shim). Editing it could switch a check off: fix the code, not the gate, unless the user asks for this edit. Stop and ask the user now; never write it another way (for example through a shell command).';
1374
+ function gateConfig(p) {
1375
+ try {
1376
+ const fold = (s) => nocase(path.resolve(s))
1377
+ const cfg = path.dirname(PLUGIN_DIR)
1378
+ const carriers = CARRIER_DIRS.filter((d) => ![fold(cfg), fold(path.dirname(cfg))].includes(fold(d)))
1379
+ .map((d) => fold(path.join(d, "AGENT.md")))
1380
+ for (const target of [path.resolve(p), resolvePath(p)]) {
1381
+ const t = fold(target)
1382
+ if (carriers.includes(t)) return true
1383
+ const dir = path.dirname(target)
1384
+ if (GATE_CONFIG_MARKERS.some((m) => nocase(m) === nocase(path.basename(dir)))
1385
+ && GATE_CONFIG_FILES.some((f) => fold(path.join(dir, f)) === t)) return true
1386
+ }
1387
+ } catch { /* an unresolvable path is no hit, like `protectedIn` */ }
1388
+ return false
1389
+ }
1390
+
1358
1391
  // ---- the ownership first-write gate --------------------------------------------
1359
1392
  // Twin of js/hosts/ownership-gate.mjs's `ownershipBlock` — keep in step (same manifests, same
1360
1393
  // managed-block strip, same section match, same reason). In an application repo (a git root
@@ -1372,12 +1405,20 @@ const OWNERSHIP_TAIL = "Opt out per repo: `## Ownership` with `mode: off` in the
1372
1405
  "install: rebuild with `--no-ownership-gate`. Offer the full documentation " +
1373
1406
  "(`/document-project`) as yes / later. Stop and ask the developer now; re-issue the write only " +
1374
1407
  "after they answer. This gate fires once per session and repo."
1408
+ const OWNERSHIP_SKIP = "skip this session; or skip in this repo until they ask — only on that third answer, " +
1409
+ "write the line `Setup: declined <YYYY-MM-DD>` (today) into `.geneseed/ownership.md` at the " +
1410
+ "MAIN worktree's root (in a linked git worktree, the main checkout's, so it outlives this " +
1411
+ "worktree), which is personal and never committed (if `.geneseed/.gitignore` is absent there, " +
1412
+ "create it first, as the ownership skill's checkpoint rules say)"
1375
1413
  const OWNERSHIP_REASON_NONE = "Geneseed (Ownership) — this application has no `AGENTS.md` with " +
1376
- "`## Ownership`. Before writing, propose to the developer: set it up (ownership skill), or " +
1377
- `proceed without for this session. ${OWNERSHIP_TAIL}`
1414
+ "`## Ownership`. Before writing, propose three answers to the developer: set it up now " +
1415
+ `(ownership skill); ${OWNERSHIP_SKIP}. ${OWNERSHIP_TAIL}`
1378
1416
  const OWNERSHIP_REASON_NO_SECTION = "Geneseed (Ownership) — this application's `AGENTS.md` has no " +
1379
- "`## Ownership` section. Before writing, ask the developer: add the Ownership section " +
1380
- `(ownership skill), or proceed without for this session? ${OWNERSHIP_TAIL}`
1417
+ "`## Ownership` section. Before writing, ask the developer: add the Ownership section now " +
1418
+ `(ownership skill); ${OWNERSHIP_SKIP}? ${OWNERSHIP_TAIL}`
1419
+ // The developer's durable, personal decline (`DECLINED_RE` in the hook twin; geneseed-context.js
1420
+ // carries it too): with no section, this line in `.geneseed/ownership.md` defers the gate.
1421
+ const OWNERSHIP_DECLINED_RE = /^Setup:[ \t]*declined[ \t]+(\d{4}-\d{2}-\d{2})[ \t]*\r?$/m
1381
1422
  // The reason to refuse this write, or null. `p` is absolute. Never throws.
1382
1423
  function ownershipBlock(p, sessionID) {
1383
1424
  try {
@@ -1396,6 +1437,15 @@ function ownershipBlock(p, sessionID) {
1396
1437
  try { text = readFileSync(path.join(root, "AGENTS.md"), "utf8") } catch { /* none: gate */ }
1397
1438
  const own = text === null ? "" : text.replace(MANAGED_BLOCK_RE, "")
1398
1439
  if (OWNERSHIP_SECTION_RE.test(own)) return null
1440
+ let personal = ""
1441
+ // In the MAIN worktree (the hook twin's `mainWorktreeOf(root) ?? root`): the shared `.git`'s
1442
+ // parent, else this root (a main worktree, a submodule, a bare common dir, a bad link).
1443
+ // Sync equivalent of this plugin's async `mainWorktreeOf` and js/hosts/gitref.mjs
1444
+ // `mainWorktreeOf`; the parity table in tests/plugins/ownership_guard.test.mjs pins all three.
1445
+ let home = root
1446
+ try { const c = gitCommonDirOf(root); if (path.basename(c) === ".git") home = path.dirname(c) } catch { /* this root */ }
1447
+ try { personal = readFileSync(path.join(home, ".geneseed", "ownership.md"), "utf8") } catch { /* none: gate */ }
1448
+ if (OWNERSHIP_DECLINED_RE.test(personal.replace(/^\uFEFF/, ""))) return null
1399
1449
  const key = `${sessionID}|${nocase(root)}`
1400
1450
  if (OWNERSHIP_SEEN.has(key)) return null
1401
1451
  OWNERSHIP_SEEN.add(key)
@@ -1491,6 +1541,7 @@ export const GeneseedGuard = async (ctx) => {
1491
1541
  if (SECRET_WARN_RE.some((re) => re.test(p))) log(`WARN: writing ${p} — keep secrets out of tracked files (Sealed Secrets)`)
1492
1542
  const sensor = protectedCheck(p)
1493
1543
  if (sensor) { await deny(`${p} is a protected check (${sensor === DONE_LIST ? "the done gate list itself" : `${sensor}, listed in ${SENSOR_LIST}`}) — a check the agent can edit is not a check (External Gate)`, "rigor-5"); return }
1544
+ if (gateConfig(p)) { await deny(`${p} ${GATE_CONFIG_ASK} (External Gate)`, "rigor-5"); return }
1494
1545
  const store = ruleStoreTarget(p)
1495
1546
  if (store && !RULE_STORE_BUMPED.has(p)) {
1496
1547
  RULE_STORE_BUMPED.add(p)
@@ -11,12 +11,12 @@
11
11
  //
12
12
  // Saved workflows ONLY — no model-authored/eval'd scripts (v1). Synchronous: the tool
13
13
  // blocks until the workflow finishes; a phase-by-phase trace and the full result are
14
- // written to `.geneseed/workflow-runs/<runId>.log`. Every failure is contained and
14
+ // written to `.geneseed/workflow-runs/<runId>.log`, and `.geneseed/` gets a
15
+ // personal-by-default `.gitignore` if it has none. Every failure is contained and
15
16
  // reported, never thrown into the session.
16
17
  //
17
- // One stderr line at load (the banner below — it is how a restart shows the tool
18
- // registered, or warns that it could not); everything else is quiet unless
19
- // GENESEED_DEBUG=1. GENESEED_WORKFLOWS_DIR overrides
18
+ // Quiet unless GENESEED_DEBUG=1 (which adds a load banner on stderr), except a
19
+ // warning that the tool may not register. GENESEED_WORKFLOWS_DIR overrides
20
20
  // where saved workflows are loaded from.
21
21
 
22
22
  import { execFile } from "node:child_process"
@@ -119,11 +119,27 @@ function isolationReport(stats) {
119
119
  return lines.join("\n")
120
120
  }
121
121
 
122
+ // `<repo>/.geneseed/` is personal by default, so its first writer makes it ignore itself, with
123
+ // the team paths (bricks, loops, check lists) allowed back. Anchored `/*`: a bare `*` matches at
124
+ // every depth and would hide `bricks/x.md` even under `!bricks/`. Create-if-absent (`wx`): a
125
+ // user's own edit survives; its failure never costs the trace. The same string lives in
126
+ // `workflows/_runtime.js` (a plugin cannot share a file — V2 loads every .js here as a
127
+ // plugin — and the runtime is imported lazily, from a configurable dir); tests pin both.
128
+ const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/protected-checks.txt\n!/done-checks.txt\n"
129
+ // Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
130
+ // never a user edit, so it is upgraded. Any other content is the user's. Never throws.
131
+ async function writeGitignore(file) {
132
+ try { await fs.writeFile(file, GENESEED_GITIGNORE, { flag: "wx" }) } catch {
133
+ try { if (/^\*(\r?\n)?$/.test(await fs.readFile(file, "utf8"))) await fs.writeFile(file, GENESEED_GITIGNORE) } catch { /* contained */ }
134
+ }
135
+ }
136
+
122
137
  async function writeTrace(rootDir, runId, lines) {
123
138
  if (!rootDir) return "(no trace file — unknown working dir)"
124
139
  try {
125
140
  const dir = path.join(rootDir, ".geneseed", "workflow-runs")
126
141
  await fs.mkdir(dir, { recursive: true })
142
+ await writeGitignore(path.join(rootDir, ".geneseed", ".gitignore"))
127
143
  const file = path.join(dir, `${runId}.log`)
128
144
  await fs.writeFile(file, lines.join("\n") + "\n", "utf8")
129
145
  return file
@@ -197,11 +213,14 @@ const TOOL_DESCRIPTION =
197
213
  const NAME_DESCRIPTION = "saved workflow name; omit to list available"
198
214
  const ARGS_DESCRIPTION = "inputs passed to the workflow script as `args` (object, or a JSON object string)"
199
215
 
200
- // One-line load banner (always on) so a restart visibly confirms the plugin loaded and the
201
- // `workflow` tool is registered. tests/host_canary.mjs reads it as V1's proof of load, so it
202
- // stays on stderr, not `say`: `opencode debug config` never prints a `client.app.log` line. It
203
- // runs once, before the TUI draws, so it does not land in the input box as `say`'s lines did.
216
+ // One-line load banner, GENESEED_DEBUG=1 only: OpenCode 1.19 paints it in red over the input
217
+ // box like any other stderr line (it does not run before the TUI draws). tests/host_canary.mjs
218
+ // sets the flag and reads it as V1's proof of load, so it stays on stderr, not `say`:
219
+ // `opencode debug config` never prints a `client.app.log` line. A warning always goes out,
220
+ // through `say`, so a tool that may not register is never silent.
204
221
  async function loadBanner(warn = "") {
222
+ if (warn) say(`tool 'workflow'${warn}`)
223
+ if (!DEBUG) return
205
224
  try {
206
225
  const names = await listWorkflows()
207
226
  console.error(`[geneseed-workflow] loaded — tool 'workflow' registered, ${names.length} workflow(s) [${names.join(", ") || "none"}] from ${WORKFLOWS_DIR}${warn}`)
@@ -193,8 +193,19 @@ async function runChildSession(client, { prompt, agent, model, title, directory
193
193
  //
194
194
  // Worktrees live under <root>/.geneseed/worktrees/ beside the run traces, NOT in the OS
195
195
  // temp dir: a kept worktree is unmerged work, and temp cleaners delete it. The state dir
196
- // gets a `*` .gitignore of its own (never overwriting one already there), so neither the
197
- // worktrees nor the traces show up as untracked files in the project.
196
+ // gets a .gitignore of its own (never overwriting one already there): personal by default,
197
+ // so neither the worktrees nor the traces show up as untracked files, with the team paths
198
+ // (bricks, loops, check lists) allowed back. Anchored `/*`, because a bare `*` matches at
199
+ // every depth and would hide `bricks/x.md` even under `!bricks/`. Same string as
200
+ // GENESEED_GITIGNORE in plugins/geneseed-workflow.js; both are pinned by tests.
201
+ const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/protected-checks.txt\n!/done-checks.txt\n"
202
+ // Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
203
+ // never a user edit, so it is upgraded. Any other content is the user's. Never throws.
204
+ async function writeGitignore(file) {
205
+ try { await fs.writeFile(file, GENESEED_GITIGNORE, { flag: "wx" }) } catch {
206
+ try { if (/^\*(\r?\n)?$/.test(await fs.readFile(file, "utf8"))) await fs.writeFile(file, GENESEED_GITIGNORE) } catch { /* contained */ }
207
+ }
208
+ }
198
209
  const fullSlug = (t) => String(t).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")
199
210
  const slug = (t) => fullSlug(t).slice(0, 32) || "agent"
200
211
 
@@ -205,7 +216,7 @@ export async function isolate(git, root, name) {
205
216
  const branch = `geneseed-wf/${name}`
206
217
  const state = path.join(root, ".geneseed")
207
218
  await fs.mkdir(path.join(state, "worktrees"), { recursive: true })
208
- await fs.writeFile(path.join(state, ".gitignore"), "*\n", { flag: "wx" }).catch(() => {})
219
+ await writeGitignore(path.join(state, ".gitignore"))
209
220
  const dir = path.join(state, "worktrees", name)
210
221
  await git(["worktree", "add", "-b", branch, dir, base], root)
211
222
  return { dir, branch, base }
@@ -25,8 +25,8 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
25
25
  | `deletion-is-deliberate` | law | ask: git-gate, only on real data loss judged against the repository's state (the list in [Hooks](hooks.md): a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, the reflog pruned, files git cannot restore removed); asks when it cannot verify. Switchable per install with `--no-deletion-gate` (see [Exclusions](exclusions.md)): the real-loss check and the Law IV `permission.bash` keys stand down, everything else in this table stays **+** ask: git-gate, catastrophic shell (`rm -rf` of `/`, a drive root or `~`, `mkfs`, `dd` over a raw disk, `format`, fork bomb), whatever the state and even with the switch off | same as Claude Code | ask: permission prompt (`git reflog expire*`, `git gc --prune*`, a force push or delete of `main`/`master` by name) **+** block: guard plugin (catastrophic shell, the hook's check plus its own stricter text match: `rm -rf` of `/`, a drive root or `~`, fork bomb, `format`, `dd` over a raw disk) **+** block: guard plugin (every other real-loss case, the same state-aware decisions as the hook) | block (exit 2) |
26
26
  | `persist-insight` | process | ask: rule-gate (a write to `user-rules.md` or the memory store) | same as Claude Code | ask once: guard plugin (refuses the *first* write to that path; a re-issued write goes through) | log only (warning, call goes through) |
27
27
  | `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed | log only |
28
- | `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list) | same as Claude Code | block: guard plugin (same list) | block (exit 2) |
29
- | `verify-before-asserting` | law | block at Stop, once per turn: the done gate in `learn` (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Opt-in per project; switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (**unverified live**: a frozen fork, and no check runs a model turn) | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
28
+ | `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list, or to a gate's own configuration: hook settings, `excludes.json`, `AGENT.md` gate markers, the hook shim) | same as Claude Code | ask: OpenCode's own `permission.edit` rules, written by the emit (every `opencode.json(c)`, the hook settings, the install's `AGENT.md`, `excludes.json`, manifest, plugins, the hook shim); block: guard plugin (the protected-checks list, and the other hosts' Geneseed-only files) | block (exit 2), writes only; a hook `settings.json` only when the edit changes Geneseed's own hook entries |
29
+ | `verify-before-asserting` | law | block at Stop, once per turn: the done gate in `learn` (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (**unverified live**: a frozen fork, and no check runs a model turn) | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
30
30
  | `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
31
31
 
32
32
  Bob has no "ask" tier (see [ADR 0007](../adr/0007-gates-fail-closed-per-host-ceiling.md)), so a
@@ -43,7 +43,8 @@ one host can run still ships for every host it can.
43
43
  The [ownership](ownership.md) first-write gate enforces the Credo's Ownership section, not a law
44
44
  or doctrine rule, so it has no id above. In an application repo whose root `AGENTS.md` has no
45
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
46
+ and the next write passes. Off per repo with `mode: off`, for one developer with a personal
47
+ `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`, per install with
47
48
  `--no-ownership-gate` ([Exclusions](exclusions.md)).
48
49
 
49
50
  | Gate | Claude Code | OpenClaude | OpenCode | Bob |
@@ -60,7 +61,7 @@ the OpenCode guard plugin in-process, on one call each must refuse and one it mu
60
61
  Every other rule carries no gate on any host. A human reads them because the model was told to
61
62
  follow them, not because a tool call was ever inspected.
62
63
 
63
- **Laws** — `one-intent-one-act` · `verify-before-asserting` (in a project without a done list) · `surface-failures` ·
64
+ **Laws** — `one-intent-one-act` · `verify-before-asserting` (in a project without a done list, where inferred checks only warn) · `surface-failures` ·
64
65
  `data-not-orders` · `least-privilege` · `cure-the-cause` · `echo-the-intent`.
65
66
 
66
67
  **Doctrine: process** — `plan-before-acting` · `context-economy` · `read-the-docs-first` ·
@@ -101,7 +101,7 @@ The console's Constitution page has a switch on Rule I's and Rule III's rows too
101
101
 
102
102
  What stops, per host:
103
103
  - **`--no-secrets-gate`**: the credential scan of `rule-gate` (Claude Code, OpenClaude) and of `tool-gate` (Bob, which then no longer exits 2 for it), and on OpenCode the guard plugin's *Sealed Secrets* block — both the key/credential file path block and the content scan. *External Gate*, *Persist Insight*, the deletion gate and the root-scan check stay.
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*.
104
+ - **`--no-done-gate`**: the done check `learn` runs on Stop, listed or inferred (Claude Code, OpenClaude; on Bob, the "turn not judged" log line), and on OpenCode the context plugin's reminder (OpenCode 1), its one-line notice (OpenCode 2), and on every host the `Done gate:` line at session start. 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
107
 
@@ -113,8 +113,8 @@ The [ownership](ownership.md) first-write gate is not a Rule's gate: it stops th
113
113
  geneseed build --emit claude-global --no-ownership-gate
114
114
  ```
115
115
 
116
- The install records `Ownership gate: off` beside the other gate markers, written only when off; rebuilds, upgrades and `geneseed status` carry it. The console has 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.
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), on OpenCode the guard plugin's ownership refusal, the setup proposal in the install's `AGENT.md` (the build drops that sentence), and the session-start decline reminder. A repo with `mode: on` still runs the ownership checkpoints, and every other check of those gates stays.
117
117
 
118
- 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.
118
+ Two narrower ways out need no rebuild: `## Ownership` with `mode: off` in a repo's root `AGENTS.md` silences it for that repo and its team; answering "skip in this repo until I ask" writes `Setup: declined <YYYY-MM-DD>` into your personal `.geneseed/ownership.md`, which silences it for you alone in that repo until you delete the line or ask for the setup; and answering "skip this session" lets the session write on.
119
119
 
120
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.
@@ -60,12 +60,20 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
60
60
  **rule-gate.** Runs before every file write.
61
61
  - Content that looks like a credential (a cloud access key, a GitHub or Anthropic token, a Slack token, a private-key block) going into any file other than `.env*` gets a prompt citing *Sealed Secrets*. An install built `--no-secrets-gate` wires the hook with that flag and this check alone stands down ([Exclusions](exclusions.md)).
62
62
  - A write to `user-rules.md`, `MEMORY.md` or a file in the install's `memory/` gets a prompt citing *Persist Insight*: whether something is a standing rule or a fact to remember is your call, settled through the `rule` [skill](skills.md).
63
- - A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). 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.
63
+ - A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). The list is `.geneseed/protected-checks.txt` at the project's git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A project install (any host) seeds it when it is absent, with only the paths that exist there: CI (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`, `.circleci/`), lint, type and test config (`eslint.config.*`, `.eslintrc*`, `biome.json(c)`, `tsconfig.json`, `jest.config.*`, `vitest.config.*`, `pytest.ini`, `ruff.toml`, `.golangci.yml`, `checkstyle.xml`), and the manifests the done gate infers its checks from (`package.json`, `pom.xml`, `build.gradle(.kts)`, `pyproject.toml`, `Cargo.toml`, `go.mod`). It is seeded once and is yours from then on: Geneseed never rewrites it, never deletes it on uninstall, and never touches a list that already exists. To opt out, delete the listed paths (the comments may stay) but keep the file. An existing list, even one holding only comments, is never seeded again; a deleted file is. A global install seeds nothing. Whenever `.geneseed/` exists, the emit also makes sure it holds the personal-by-default `.gitignore`. A check the agent can edit is not a check. The list protects itself. 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
+ - A write to a gate's own configuration gets the same *External Gate* prompt on Claude Code and OpenClaude. These files can switch a gate off:
66
+ - In the install's own dir: `settings.json`, `settings.local.json` and Bob global's `settings/settings.json` (the hook wiring), `excludes.json`, `AGENT.md` (its `… gate: off` markers), `.geneseed-manifest.json` and `.geneseed-emit`.
67
+ - In any project: the same names under a `.claude/`, `.openclaude/`, `.bob/` or `.opencode/` folder (at the git root, in a subpackage, or with no git at all), and any `opencode.json(c)`. A team `settings.json` can set `disableAllHooks`.
68
+ - The machine-wide hook shim in `~/.geneseed/bin/` (or `$GENESEED_HOME/bin/`).
69
+ - On OpenCode, also the install's `opencode.json(c)` and its own `plugins/geneseed-*.js`.
70
+ - **OpenCode** asks with its own prompt. The emit writes `permission.edit` "ask" keys into `opencode.json`: every `opencode.json(c)`, the global `config.json`, the install's `AGENT.md` (where the emit put it), the install dir's `excludes.json`, manifest, `.geneseed-emit` and `plugins/geneseed-*.js`, the `.claude/`, `.openclaude/` and `.bob/` hook settings, and the shim dir. A blanket `"edit": "allow"` becomes `{"*": "allow", …}` with the asks after it. A blanket `"ask"` or `"deny"` already covers them and is left alone; a key you set yourself is kept and named in a warning. The manifest records the keys Geneseed added (`edit_asks`, `edit_shorthand`); a rebuild drops a recorded key it no longer wants, and uninstall takes back the ones still set to `"ask"` and restores your `"allow"`. The guard plugin refuses only the other hosts' Geneseed-only files (`excludes.json`, `AGENT.md`, manifest) and an `AGENT.md` under `$GENESEED_HARNESS`. These rules match by name, not through a link, a project `opencode.json` with its own `"edit": "allow"` replaces a global install's object, and a custom `$GENESEED_HOME` is named by its absolute path, which only OpenCode 2 matches. In OpenCode's built-in plan agent, these files are asked about rather than refused.
71
+ - **Bob** has no prompt, so it blocks, and only writes: a read passes, and so does a write to `opencode.json(c)`, which Bob never reads. A hook `settings.json` (or `settings.local.json`, or global `settings/settings.json`) is blocked only when the write changes Geneseed's own entries (a hook whose command names `geneseed-hook`, with its event and matcher), turns on `disableAllHooks`, or changes a `GENESEED_*`, `*_CONFIG_DIR` or `NODE_OPTIONS` env value. An MCP server or your own hook passes. An edit the hook cannot replay exactly is blocked: a regex, case-folded or line-ranged replace, a search not found exactly once, a diff of more than one block, an unknown write-shaped tool (its name says write, edit, diff, replace or insert; a tool named otherwise is not judged), or a file left unparseable or turned from strict JSON into JSONC. The other files stay blocked.
72
+ Names match exactly, and on Windows without regard to case or slash direction; a link into one of these paths is caught too. To change one of these files, edit it yourself, or approve the prompt. `geneseed` commands (`exclude`, a rebuild) write these files directly and are never asked. Claude Code itself also prompts for writes under `.claude/` in its default and `acceptEdits` modes, but not in `bypassPermissions`, so you can see two prompts there. Only file-write tools are seen, as above.
73
+ - The first write of a session in an application repo (a git root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section is refused once, the **ownership gate**. It is not a prompt for you: the reason goes to the agent, which asks you to set ownership up now, skip this session, or skip in this repo until you ask (on Bob, exit 2, once). The next write passes, a sub-agent never triggers it on Claude Code and OpenClaude, and writes to `AGENTS.md` or `.geneseed/` pass. Off per repo with `mode: off` in that section; for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, which also makes every session start with the line `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it`; per install with `--no-ownership-gate`, which prints no such line ([Ownership](ownership.md), [Exclusions](exclusions.md)).
66
74
  - Ordinary edits pass untouched.
67
75
 
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)).
76
+ **The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**: a turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test`. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. The gate never runs a check itself. It reads the transcript from its end, back only to the prompt that opened the turn, so its cost does not grow with the session. It blocks at most once per turn; the second stop ends the turn and leaves a line in the gate ledger. Only file-write tools count as edits: a shell `sed -i` or redirect is not seen. On OpenCode the gate is a reminder on the next request (OpenCode 1 only), listed or inferred; on Bob, whose Stop carries no transcript, the turn is not judged, and with a listed file a log line says so. An install built `--no-done-gate` wires `learn` with that flag: the check is skipped, learning still runs ([Exclusions](exclusions.md)).
69
77
 
70
78
  **learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries under `memory/`. It is shown the facts already stored, so it updates one with the merged text rather than writing a twin (the old version is kept in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It needs `GENESEED_LLM` set to a model command, for example:
71
79
 
@@ -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 the git-ignored `.geneseed/ownership.md`. [Set up ownership](../guides/set-up-ownership.md) walks through writing both.
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.
34
34
 
35
35
  ## Granularity
36
36
 
@@ -47,8 +47,8 @@ On complex code (business branching, transactions, concurrency, security) the ag
47
47
  On every host, a hook stops the first write in an application that has not decided yet:
48
48
 
49
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.
50
+ - **When.** Its root `AGENTS.md` has no `## Ownership` heading outside Geneseed's managed block, and your personal `.geneseed/ownership.md` holds no `Setup: declined <YYYY-MM-DD>` line. 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 now, skip this session, or skip in this repo until you ask. The next write passes. Writes to `AGENTS.md` and `.geneseed/` themselves always pass.
52
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
53
 
54
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).
@@ -57,11 +57,12 @@ Per host: Claude Code and OpenClaude deny the call with the reason; Bob refuses
57
57
 
58
58
  | Scope | How | Lasts |
59
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 |
60
+ | One session | Answer "skip this session" when the agent asks | This session; it asks again in the next one |
61
+ | One repo, for you | Answer "skip in this repo until I ask": the agent writes `Setup: declined <YYYY-MM-DD>` into your personal `.geneseed/ownership.md` in the main worktree — from a linked git worktree, the main checkout's, so the decline survives each new worktree (Claude Desktop opens one per session) | No expiry: until you delete the line or ask for the setup; never committed, so it never reaches the team. Each session opens with the reminder `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it` |
62
+ | One repo, for the team | `## Ownership` with `mode: off` in the root `AGENTS.md` | Until the line changes; travels with the repo |
62
63
  | One install | Rebuild with `--no-ownership-gate` ([Exclusions](exclusions.md)) | Every rebuild replays it |
63
64
 
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
+ The decline is looked up only in the main worktree; the `## Ownership` section and the manifest are read from the git root you work in. A decline left inside a linked worktree is ignored, and a `.git` file that names no gitdir falls back to the current root. If the host refuses the write to the main checkout (outside the session's working directory, a sandbox, a declined permission prompt), the agent tells you the decline was not saved and why; it never writes it inside the linked worktree instead. A `## Ownership` section, on or off, outranks a personal decline: the line is then ignored and no reminder prints. The per-install switch stops the gate, drops the setup proposal from the install's `AGENT.md`, and prints no decline reminder. A repo with `mode: on` still runs the ownership checkpoints, and the Credo section still binds.
65
66
 
66
67
  ## learn-mode comes first
67
68
 
@@ -36,6 +36,7 @@ A **skill** is a repeatable workflow written as a markdown playbook: when it app
36
36
  | open a pull request, or finish and merge a branch | `ship` |
37
37
  | decide whether something is a standing rule or a fact to remember | `rule` |
38
38
  | be taught a topic, or quizzed on it | `teach`, `quiz` |
39
+ | have every reply lead with the next action and keep the state in view (ADHD mode) | `adhd` |
39
40
 
40
41
  The full list, with each description, is in the catalog.
41
42
 
@@ -6,7 +6,7 @@ kind: "concept"
6
6
  section: "Set up"
7
7
  description: "Give an application repo its `## Ownership` section, so the developer decides each part."
8
8
  ---
9
- This guide gives one application repository its ownership setup: a `## Ownership` section in the committed root `AGENTS.md`, and your personal state file. What ownership is, and how it differs from learn-mode: [Ownership](../concepts/ownership.md).
9
+ This guide gives one application repository its ownership setup: a `## Ownership` section in the committed root `AGENTS.md`. What ownership is, and how it differs from learn-mode: [Ownership](../concepts/ownership.md).
10
10
 
11
11
  You need a Geneseed install on your host (any of Claude Code, OpenClaude, OpenCode or Bob) and a repository with a build manifest at its git root (`package.json`, `pom.xml`, `build.gradle*` and the like).
12
12
 
@@ -14,7 +14,11 @@ You need a Geneseed install on your host (any of Claude Code, OpenClaude, OpenCo
14
14
 
15
15
  Open a session in the repository and ask for it: "set up ownership for this repo". The agent runs the `ownership` skill.
16
16
 
17
- You may not need to ask. In an application with no `## Ownership` section, the first file write of a session is stopped once, and the agent proposes the setup to you. Answer "set it up", or "proceed without" to skip it for this session only.
17
+ You may not need to ask. In an application with no `## Ownership` section, the first file write of a session is stopped once, and the agent proposes the setup to you, with three answers:
18
+
19
+ - **Set it up now.** The steps below.
20
+ - **Skip this session.** Nothing is written; the proposal comes back in the next session.
21
+ - **Skip in this repo until I ask.** For you alone, in this repo only: the agent writes `Setup: declined <date>` into your personal `.geneseed/ownership.md` in the main worktree (from a linked git worktree, the main checkout's), so it holds in every later worktree too. From then on the gate does not stop you and the agent proposes nothing. Each session starts with the reminder `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it`, which the agent repeats once. It has no expiry: delete the line, or ask for the setup (which removes it). A `## Ownership` section in `AGENTS.md`, on or off, outranks it.
18
22
 
19
23
  ## 2. Review the conventions it found
20
24
 
@@ -32,7 +36,7 @@ About five questions, one at a time, each with a recommended answer:
32
36
 
33
37
  ## 4. Check the diff
34
38
 
35
- The setup writes two files and shows you the diff:
39
+ The setup writes one file and shows you the diff:
36
40
 
37
41
  - `AGENTS.md` at the repository root, at most about 60 lines, ending with the section:
38
42
 
@@ -46,10 +50,21 @@ The setup writes two files and shows you the diff:
46
50
  ```
47
51
 
48
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.
49
- - `.geneseed/ownership.md`, your personal state: a finer granularity if you want one, the pending checkpoint, and the decisions you took. It is data, never instructions, and it belongs in `.gitignore` — the agent offers to add `.geneseed/` once.
50
-
51
53
  Nothing is committed unless you ask.
52
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:
56
+
57
+ ```gitignore
58
+ /*
59
+ !/.gitignore
60
+ !/bricks/
61
+ !/loops/
62
+ !/protected-checks.txt
63
+ !/done-checks.txt
64
+ ```
65
+
66
+ The `.gitignore` does not ignore itself, so you can commit it and give the team the same rule. An existing `.geneseed/.gitignore` is never overwritten, and your root `.gitignore` is not touched.
67
+
53
68
  ## 5. Check how diffs reach you
54
69
 
55
70
  Under ownership, the host's own diff prompt is how you approve a routine step. The setup checks the permission mode:
@@ -66,7 +81,8 @@ Commit the root `AGENTS.md` with the repository, so the whole team works under t
66
81
  - **Finer for one task.** Say "go finer here", or "do the rest in one go" to propose a coarser batch.
67
82
  - **The team default.** Edit `granularity:` in `AGENTS.md` and commit it.
68
83
  - **Opt the repo out.** Set `mode: off`. The gate stays quiet, and no checkpoint runs.
69
- - **Opt the whole install out of the gate.** Rebuild with the flag, as [Exclusions](../concepts/exclusions.md) shows:
84
+ - **Skip it for yourself only.** Answer "skip in this repo until I ask" to the proposal, or write `Setup: declined <YYYY-MM-DD>` into `.geneseed/ownership.md` yourself. The team's `AGENTS.md` does not change.
85
+ - **Opt the whole install out of the gate.** Rebuild with the flag, as [Exclusions](../concepts/exclusions.md) shows. The install's `AGENT.md` then carries no ownership proposal either, and no decline reminder prints:
70
86
 
71
87
  ```bash
72
88
  geneseed build --emit claude-global --no-ownership-gate
@@ -31,6 +31,7 @@ Where Geneseed writes an install, and what an upgrade re-renders.
31
31
  | `GENESEED_ROOT` | `geneseed upgrade` | Project root for that bundle (default: the bundle's parent). |
32
32
  | `GENESEED_PRIMARY` | `geneseed build` | `1` also emits the primary orchestrator agent (OpenCode). |
33
33
  | `GENESEED_COMMANDS` | `geneseed build` | `1` also emits the `/slash` command layer (OpenCode). |
34
+ | `GENESEED_NO_SEED` | `geneseed build` | `1` skips seeding `<git root>/.geneseed/protected-checks.txt` on a project emit. For sandbox emits (the golden test matrix); `validate` and `doctor` never seed. |
34
35
 
35
36
  ## OpenCode plugin variables
36
37
 
@@ -17,7 +17,9 @@ One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed
17
17
 
18
18
  **When it runs.** On every request: the context rides invisibly in the request's message list, so it also survives compaction. If your OpenCode build lacks that (experimental) hook, the plugin notices and falls back to one visible message at session start, re-pushed when the session compacts.
19
19
 
20
- **The done gate's reminder.** In a project with `.geneseed/done-checks.txt` (see [Hooks](../concepts/hooks.md)), a request that follows a turn which edited files without every listed check passing since gets one more invisible message naming the checks owed. OpenCode has no turn-end event a plugin can block on, so this is a reminder, not a block. OpenCode 1 only: on OpenCode 2 the turn is not judged, and the plugin logs that once. `GENESEED_CONTEXT_INJECT=off` does not turn it off; removing the file does, and so does an install built `--no-done-gate` (`Done gate: off` in its `AGENT.md`, read once when OpenCode starts), which also silences the OpenCode 2 log line.
20
+ **The done gate's reminder.** The project's checks come from `.geneseed/done-checks.txt`, or, without that file, are inferred from the manifests at the project's git root (see [Hooks](../concepts/hooks.md)). A request that follows a turn which edited files without every check passing since gets one more invisible message naming the checks owed (inferred ones marked advisory). OpenCode has no turn-end event a plugin can block on, so this is a reminder, not a block. OpenCode 1 only: on OpenCode 2 the turn is not judged, and with a listed file the plugin logs that once. The context block also opens with one line naming the checks and their source (`Done gate: …`), ending `(reminder)` for a listed file or `(advisory)` for inferred checks on OpenCode 1, and `(not judged on this host)` on OpenCode 2. `GENESEED_CONTEXT_INJECT=off` does not turn the reminder off; a done list that lists nothing does, and so does an install built `--no-done-gate` (`Done gate: off` in its `AGENT.md`, read once when OpenCode starts), which also silences the OpenCode 2 log line and the context line.
21
+
22
+ **The ownership decline line.** In an application repo whose root `AGENTS.md` has no `## Ownership` section, a `Setup: declined <YYYY-MM-DD>` line in the personal `.geneseed/ownership.md` of the main worktree (the main checkout's, from a linked git worktree) adds one line beside the done line: `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it`. An install built `--no-ownership-gate` (`Ownership gate: off` in its `AGENT.md`, read once when OpenCode starts) prints no such line.
21
23
 
22
24
  **What you see.** Normally nothing — the context is there, but not shown. With the visible fallback, a `PROJECT CONTEXT` block at the top of the session.
23
25
 
@@ -11,7 +11,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
11
11
  **What it does.** Enforces the safety rules at the tool boundary — before a tool call runs, not after. High-confidence patterns only, so legitimate work is not caught.
12
12
 
13
13
  - **Blocks** writes to private-key and credential files and writes whose content carries a credential (*Sealed Secrets*; an install built `--no-secrets-gate` carries `Secrets gate: off` in its `AGENT.md`, read once at load, and both stop blocking), catastrophic shell commands such as deleting the filesystem root and every command that would really lose data — a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, a protected branch force-moved off commits nothing else holds, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, files git cannot restore removed — judged against the repository's state, the same decisions the Claude/Bob hook makes (*Deletion Is Deliberate*; `reflog expire` and `gc --prune` are left to the `permission.bash` ask; an install built `--no-deletion-gate` carries `Deletion gate: off` in its `AGENT.md`, which the plugin reads once at load and then stops blocking real loss — catastrophic commands still block), a recursive scan rooted at a whole filesystem such as `find /` (*Commands Must Return* — search a specific directory instead), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `geneseed-wiki.jsonc`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)).
14
- - **Refuses once** the first write of a session in an application repo (a git root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section, so the agent proposes the [ownership](../concepts/ownership.md) setup first; the next write passes, and a sub-agent's session never triggers it. Off per repo with `mode: off` in that section; an install built `--no-ownership-gate` carries `Ownership gate: off` in its `AGENT.md`, read once at load.
14
+ - **Refuses once** the first write of a session in an application repo (a git root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section, so the agent proposes the [ownership](../concepts/ownership.md) setup first; the next write passes, and a sub-agent's session never triggers it. Off per repo with `mode: off` in that section, or for one developer with a personal `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`; an install built `--no-ownership-gate` carries `Ownership gate: off` in its `AGENT.md`, read once at load.
15
15
  - **Warns** (logged, allowed) on `.env` writes.
16
16
  - **Speed-bumps** the *first* write to `user-rules.md` or a memory file: it is refused once, naming *Persist Insight* — whether something is a standing rule or a fact to remember is your call, settled through the `rule` skill. The re-issued write goes through.
17
17
 
@@ -27,8 +27,8 @@ On Claude Code and OpenClaude the hooks never block silently. They make the host
27
27
  - **A scan of a whole filesystem**: a recursive `find`, `du`, `grep -r`, `rg` or `Get-ChildItem -Recurse` rooted at `/`, `/c` or `C:\`, which in Git Bash walks every drive for hours. Wired in every build.
28
28
  - **Credentials**: a write or edit whose content looks like a real key (AWS, GitHub, Anthropic, Slack, or a private-key block), anywhere except a `.env` file.
29
29
  - **Your rules and memory**: any write by the agent to `user-rules.md` or to the memory store. Whether something is a standing rule or a fact to remember is your call.
30
- - **The first write in an application with no ownership setup**: in a repo with a build manifest whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused once, with the reason sent to the agent rather than to you: it then asks you to set [ownership](../concepts/ownership.md) up or proceed without. Off per repo with `mode: off`, per install with `--no-ownership-gate`.
31
- - **Ending a turn without the proof**: only in a project that lists its checks in `.geneseed/done-checks.txt`. A turn that edited files cannot end until every listed check has passed since the last edit. The agent is stopped once, then the turn may end.
30
+ - **The first write in an application with no ownership setup**: in a repo with a build manifest whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused once, with the reason sent to the agent rather than to you: it then asks you to set [ownership](../concepts/ownership.md) up now, skip this session, or skip in this repo until you ask. Off per repo with `mode: off`, for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, per install with `--no-ownership-gate`.
31
+ - **Ending a turn without the proof**: only in a project that lists its checks in `.geneseed/done-checks.txt`. A turn that edited files cannot end until every listed check has passed since the last edit. The agent is stopped once, then the turn may end. Without that file, Geneseed infers the checks from the project's manifest (`package.json` scripts, Maven, Gradle, `pyproject.toml`, `Cargo.toml`, `go.mod`): you get a warning when a turn ends without them, but the turn is not stopped.
32
32
 
33
33
  If a gate crashes, it asks instead of letting the call through. If it cannot start at all (a deleted or broken shim) or times out, Claude Code blocks the call instead: see [Troubleshoot hooks](../reference/troubleshoot-hooks.md) to recover. Other shell commands go through Claude Code's normal permission flow; an `rm` of files git cannot restore is the real-loss case above.
34
34
 
@@ -41,7 +41,7 @@ If a gate crashes, it asks instead of letting the call through. If it cannot sta
41
41
  On OpenCode, two mechanisms enforce rules:
42
42
 
43
43
  - **OpenCode's own permission prompt**, which Geneseed configures in `opencode.json`. It asks you before `git reflog expire`, `git gc --prune` and a force-push or delete of `main`/`master`, and, when the **process** pack is on, before every commit and push.
44
- - **The guard plugin**, which blocks outright: writes to key and credential files (`id_rsa`, `*.pem`, `.ssh/`, `.npmrc`…), catastrophic commands (`rm -rf /`, `rm -rf ~`, formatting or overwriting a disk), every other real data loss (the same state-aware decisions as the hook), a recursive scan of a whole filesystem (`find /`, `du -sh /`, `Get-ChildItem C:\ -Recurse`), and any change inside a folder your wiki marks `protected`. It also refuses the first write to `user-rules.md` or memory once. Re-issue the write and it goes through. And in an application repo with no `## Ownership` section in its root `AGENTS.md`, it refuses the session's first write once, so the agent proposes the [ownership](../concepts/ownership.md) setup (off with `mode: off` or `--no-ownership-gate`).
44
+ - **The guard plugin**, which blocks outright: writes to key and credential files (`id_rsa`, `*.pem`, `.ssh/`, `.npmrc`…), catastrophic commands (`rm -rf /`, `rm -rf ~`, formatting or overwriting a disk), every other real data loss (the same state-aware decisions as the hook), a recursive scan of a whole filesystem (`find /`, `du -sh /`, `Get-ChildItem C:\ -Recurse`), and any change inside a folder your wiki marks `protected`. It also refuses the first write to `user-rules.md` or memory once. Re-issue the write and it goes through. And in an application repo with no `## Ownership` section in its root `AGENTS.md`, it refuses the session's first write once, so the agent proposes the [ownership](../concepts/ownership.md) setup (off with `mode: off`, a personal `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`, or `--no-ownership-gate`).
45
45
 
46
46
  The guard only warns on `.env` edits. It checks credentials by **file path**, not by content, so a key pasted into an ordinary source file is not caught here. One caveat about the process pack: if your `opencode.json` already has a `git commit*` entry, a rebuild without the pack leaves that entry in place and reports it. Geneseed cannot tell its own entry from one you typed.
47
47
 
@@ -8,7 +8,7 @@ description: "Where an install lands on IBM Bob or as a plain AGENT.md bundle, a
8
8
  ---
9
9
  Bob and the plain bundle carry the same rules, agents and skills as the other hosts. What differs is where they land and how much of it is enforced. The **Kind** words are explained in [What lands on your machine](on-your-machine.md).
10
10
 
11
- **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for the checks that admit no judgement call: credentials, destructive git, and a write under a project's own protected-checks list. The commit/push and memory questions become log lines. One more refusal happens only once: in an application repo whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused so the agent proposes the [ownership](../concepts/ownership.md) setup, and the same write passes after you answer. Turn it off per repo with `mode: off` in that section, or per install with `--no-ownership-gate`.
11
+ **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for the checks that admit no judgement call: credentials, destructive git, and a write under a project's own protected-checks list. The commit/push and memory questions become log lines. One more refusal happens only once: in an application repo whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused so the agent proposes the [ownership](../concepts/ownership.md) setup, and the same write passes after you answer. Turn it off per repo with `mode: off` in that section, for yourself in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, or per install with `--no-ownership-gate`.
12
12
 
13
13
  **Plain bundle.** The `files` target writes `AGENT.md` and the same folders into `./Harness/` for any tool that reads `AGENT.md`. It installs no hooks and no plugins, so nothing in it is enforced.
14
14
 
@@ -16,7 +16,7 @@ What a Claude Code or OpenClaude install writes, piece by piece. The **Kind** wo
16
16
  | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
17
17
  | context hook | At session start, and again after a resume or compaction, puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `geneseed exclude add <folder>` silences every hook in that folder |
18
18
  | git-gate hook | Before each shell command: asks you before any `git commit` or `git push`, and before a command that would really lose data — a force-push to `main`, a `reset --hard` that abandons unpushed commits, `branch -D` of an unpushed branch, an `rm` git cannot undo | enforced | ~14 ms per shell call | The commit/push question goes away if you build without the **process** pack; the destructive-git question has no switch except `geneseed exclude` |
19
- | rule-gate hook | Before each write or edit: asks you when the file would carry a credential-shaped string (outside `.env`), or when the agent writes to `user-rules.md` or memory. In an application repo with no `## Ownership` section in its root `AGENTS.md`, stops the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | ~14 ms per write | `geneseed exclude add <folder>`; the ownership stop alone: `mode: off` in the repo's `## Ownership`, or rebuild with `--no-ownership-gate` |
19
+ | rule-gate hook | Before each write or edit: asks you when the file would carry a credential-shaped string (outside `.env`), or when the agent writes to `user-rules.md` or memory. In an application repo with no `## Ownership` section in its root `AGENTS.md`, stops the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | ~14 ms per write | `geneseed exclude add <folder>`; the ownership stop alone: `mode: off` in the repo's `## Ownership`, `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, or rebuild with `--no-ownership-gate` |
20
20
  | learn hook | When the agent finishes a reply, and before compaction, distils durable facts from the recent conversation into `memory/`. Off until you set `GENESEED_LLM` to a model command such as `claude -p` | automatic | One model call each time it runs, once enabled | Leave `GENESEED_LLM` unset (the default) |
21
21
  | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
22
22
  | `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
@@ -16,7 +16,7 @@ What an OpenCode install writes, piece by piece. The **Kind** words are explaine
16
16
  | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
17
17
  | `opencode.json` entries | `instructions` points OpenCode at `AGENT.md`. `permission.bash` makes OpenCode ask before `git reflog expire`, `git gc --prune` or a force-push or delete of `main`/`master`, and before every commit and push when the **process** pack is on. `permission.skill` denies each user-only skill, so the model never starts it but `/name` still runs it; Geneseed takes back only the denies it wrote | enforced | No tokens | Edit the `permission` block yourself. The commit/push questions follow the **process** pack |
18
18
  | context plugin | Puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `GENESEED_CONTEXT_INJECT=off` |
19
- | guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), every other real data loss judged against the repository's state, a recursive scan of a whole filesystem (`find /`), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours. In an application repo with no `## Ownership` section in its root `AGENTS.md`, refuses the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block; the ownership refusal alone: `mode: off` in the repo's `## Ownership`, or rebuild with `--no-ownership-gate` |
19
+ | guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), every other real data loss judged against the repository's state, a recursive scan of a whole filesystem (`find /`), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours. In an application repo with no `## Ownership` section in its root `AGENTS.md`, refuses the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block; the ownership refusal alone: `mode: off` in the repo's `## Ownership`, `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, or rebuild with `--no-ownership-gate` |
20
20
  | learn plugin | Once a session has been quiet for 60 seconds, distils durable facts into `memory/` with the model the session already uses | automatic | One model call per quiet session | `geneseed exclude add <folder>` silences it in that folder |
21
21
  | activity plugin | Writes one small file per session that the web console's Activity view shows: what the session does now, its sub-agents, the files each of them changed (by path inside the repository), its turns, how full its context is and its compactions | automatic | No tokens | `GENESEED_ACTIVITY=off` |
22
22
  | notify plugin | A desktop notification when a turn took longer than 30 seconds | automatic | No tokens | `GENESEED_NOTIFY=off` |
@@ -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.27.1"
5
+ "version": "4.29.0"
6
6
  }
package/js/README.md CHANGED
@@ -92,12 +92,14 @@ user co-owns, and the hook verbs those emitted configs then run.
92
92
  | `hooks.mjs` | The gate verbs, run on every tool call: `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), plus `ask`/the gate ledger/`guardGate`. `--host` picks the verdict dialect |
93
93
  | `hooks-context.mjs` | The `context` verb — SessionStart: session files plus the repo's context docs |
94
94
  | `ownership-gate.mjs` | The ownership first-write gate, last in `rule-gate`: in an application repo (git root + build manifest) whose root `AGENTS.md` has no `## Ownership` section, denies the session's first write once (a tmpdir marker per session). Builtins + `gitRootOf` only. Twin: the OpenCode guard plugin |
95
- | `hooks-done.mjs` | The done gate (#289): on Stop, inside `learn` and before its spawn, blocks a turn that edited files until `.geneseed/done-checks.txt`'s checks passed after the last edit |
95
+ | `hooks-done.mjs` | The done gate (#289): on Stop, inside `learn` and before its spawn, judges a turn that edited files against the project's checks — blocks until `.geneseed/done-checks.txt`'s checks passed after the last edit; without that file, the inferred checks are advisory (a `systemMessage`, never a block) |
96
+ | `done-checks.mjs` | Where the done gate's checks come from: `.geneseed/done-checks.txt`, else inferred from the git root's manifests (package.json scripts, pom.xml, Gradle, pyproject.toml, Cargo.toml, go.mod), each a group of accepted command forms; plus `doneLine`, the SessionStart line `context` prints. Spawn-free: `context` is in the CLI's closure. Twin: the OpenCode context plugin |
96
97
  | `hooks-learn.mjs` | The `learn` verb — Stop/SubagentStop/PreCompact distiller; the hook path's ONE spawn (`$GENESEED_LLM`) |
97
98
  | `hooks-prims.mjs` | The Python path/text primitives the hook verbs share (`splitLines`, `readStdin`, a never-throwing `isFile`), plus the activity off switch (`activityOn`) and the do-nothing `activity` verb |
98
99
  | `activity.mjs` | The hook-side activity writer and the owner of snapshot liveness: `recordActivity` (one payload into `<root>/activity/`), `readTranscriptDelta`, `sweepActivity` (archive, newest 50, 7 days). Loaded only when tracking is on; never prints |
99
100
  | `usage.mjs` | The usage counter `tool-gate` runs: one `{day, kind, name}` line per Skill or subagent call into `notebook/usage.jsonl`. Hook path: builtins only, silent, never throws |
100
101
  | `memory-files.mjs` | The memory store's file format — `frontmatter`, `MEMORY.md` index writes, agent lessons, consolidate. No spawn: the CLI and web console import it |
102
+ | `geneseed-dir.mjs` | The Node writers into a project's `<git root>/.geneseed/`: the personal-by-default `.gitignore` (`GENESEED_GITIGNORE`, pinned to the two OpenCode copies), and the protected-checks seed every project emit runs (`seedProtectedChecks`: seed once when absent, then the user's — never recorded, rewritten or uninstalled). Never throws, never writes through a link. Spawn-free |
101
103
  | `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `gitCommonDirOf`, `currentBranch`, `protectedBranches`, `stashExists`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate, `loss.mjs` and `js/loop/cli.mjs`'s commit-message writer |
102
104
  | `loss.mjs` | Law IV calibrated to real loss: `lossReason` decides whether a command would really lose data (protected branch, unpushed branch, dirty tree, stash, reflog, files git cannot restore) and fails closed. The gate path's one `git` spawn, reached only after `LOSS_CANDIDATE_RE` matched. Twin: the OpenCode guard plugin |
103
105
  | `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json` (one `loadJsonObject` reader for all of them) and the managed blocks |