geneseed 5.3.1 → 5.4.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 (161) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +21 -18
  3. package/SHIPPED.md +7 -7
  4. package/adapters/opencode/README.md +3 -2
  5. package/adapters/opencode/plugins/geneseed-context.js +6 -0
  6. package/adapters/opencode/plugins/geneseed-guard.js +5 -3
  7. package/bin/geneseed-cli.mjs +7 -0
  8. package/bin/geneseed-hook.mjs +3 -3
  9. package/docs/PRD.md +1 -1
  10. package/docs/README.md +1 -0
  11. package/docs/concepts/agents.md +1 -1
  12. package/docs/concepts/collaboration.md +2 -2
  13. package/docs/concepts/enforcement-table.md +5 -2
  14. package/docs/concepts/exclusions.md +16 -2
  15. package/docs/concepts/footprint.md +1 -1
  16. package/docs/concepts/foreman-mode.md +1 -1
  17. package/docs/concepts/hook-gates.md +3 -3
  18. package/docs/concepts/hooks.md +4 -3
  19. package/docs/concepts/host-matrix.md +2 -2
  20. package/docs/concepts/kits.md +12 -2
  21. package/docs/concepts/loop-bricks.md +3 -3
  22. package/docs/concepts/loops.md +6 -4
  23. package/docs/concepts/ownership.md +1 -1
  24. package/docs/concepts/rules.md +2 -2
  25. package/docs/concepts/skills.md +1 -1
  26. package/docs/extending.md +63 -28
  27. package/docs/guides/auto-merge.md +100 -0
  28. package/docs/guides/choose-your-setup.md +1 -1
  29. package/docs/guides/headless.md +1 -1
  30. package/docs/guides/install-clone.md +1 -1
  31. package/docs/guides/install.md +1 -1
  32. package/docs/guides/loop-finish.md +3 -3
  33. package/docs/guides/loop-running.md +4 -4
  34. package/docs/guides/project-context.md +1 -1
  35. package/docs/guides/run-a-factory.md +2 -2
  36. package/docs/guides/setup-doctrines.md +2 -2
  37. package/docs/guides/setup-footprint.md +1 -1
  38. package/docs/guides/uninstall.md +3 -3
  39. package/docs/guides/upgrade.md +1 -1
  40. package/docs/guides/worktree.md +1 -1
  41. package/docs/reference/environment.md +4 -2
  42. package/docs/reference/plugin-activity.md +1 -1
  43. package/docs/reference/plugin-guard.md +1 -1
  44. package/docs/reference/plugin-learn.md +1 -1
  45. package/docs/reference/plugin-workflow.md +1 -1
  46. package/docs/reference/troubleshoot-doctor.md +1 -1
  47. package/docs/reference/troubleshoot-hooks.md +2 -2
  48. package/docs/reference/troubleshoot-install.md +3 -3
  49. package/docs/reference/troubleshoot-tools.md +1 -1
  50. package/docs/token-footprint.md +2 -2
  51. package/docs/understand/enforced-vs-asked.md +1 -1
  52. package/docs/understand/machine-claude.md +2 -2
  53. package/docs/understand/on-your-machine.md +1 -1
  54. package/docs/web-ui.md +5 -5
  55. package/harness.config.json +1 -1
  56. package/js/README.md +2 -1
  57. package/js/build/args.mjs +12 -1
  58. package/js/build/driver.mjs +33 -6
  59. package/js/build/emit-claude.mjs +8 -4
  60. package/js/build/emit-opencode.mjs +13 -9
  61. package/js/build/generate.mjs +10 -156
  62. package/js/build/profile.mjs +318 -0
  63. package/js/build/render.mjs +81 -3
  64. package/js/build/retired-skills.mjs +60 -13
  65. package/js/build/source.mjs +15 -1
  66. package/js/build/stubs.mjs +4 -1
  67. package/js/cli-table.json +48 -3
  68. package/js/hosts/hooks-done.mjs +345 -55
  69. package/js/hosts/hooks-learn.mjs +4 -3
  70. package/js/hosts/hooks-prims.mjs +5 -3
  71. package/js/hosts/hooks.mjs +153 -6
  72. package/js/hosts/installs.mjs +19 -1
  73. package/js/hosts/native.mjs +19 -2
  74. package/js/hosts/settings.mjs +29 -3
  75. package/js/inspect/checks-constitution.mjs +32 -0
  76. package/js/inspect/diff.mjs +21 -3
  77. package/js/inspect/inventory.mjs +1 -1
  78. package/js/maintain/setup.mjs +5 -1
  79. package/js/maintain/update.mjs +4 -2
  80. package/js/web/actions.mjs +16 -3
  81. package/js/web/api.mjs +7 -2
  82. package/package.json +1 -1
  83. package/registry.json +14 -0
  84. package/src/AGENT.md.tmpl +15 -17
  85. package/src/bricks/pr-open.md +3 -2
  86. package/src/doctrines/ops.md +2 -2
  87. package/src/doctrines/process.md +40 -36
  88. package/src/factories/analysis-to-build.json +1 -1
  89. package/src/factories/bug-report-to-fix.json +1 -1
  90. package/src/factories/issue-to-pr.json +1 -1
  91. package/src/kits/terminal-tools/rules.md +10 -0
  92. package/src/kits/terminal-tools.json +13 -0
  93. package/src/licenses/herdr.txt +201 -0
  94. package/src/modes/foreman.md +6 -3
  95. package/src/skills/_self-improvement.md +9 -7
  96. package/src/skills/commit.md +17 -17
  97. package/src/skills/debug/ci.md +1 -1
  98. package/src/skills/dependencies.md +3 -3
  99. package/src/skills/document-project.md +3 -2
  100. package/src/skills/factory.md +13 -4
  101. package/src/skills/geneseed.md +4 -2
  102. package/src/skills/git-history.md +5 -7
  103. package/src/skills/herdr.md +135 -0
  104. package/src/skills/loop.md +3 -2
  105. package/src/skills/opencode-cli.md +84 -0
  106. package/src/skills/pipeline.md +1 -1
  107. package/src/skills/release.md +5 -8
  108. package/src/skills/review-response.md +4 -2
  109. package/src/skills/rule.md +27 -1
  110. package/src/skills/ship.md +54 -7
  111. package/src/skills/worktree.md +2 -2
  112. package/src/upstreams.json +7 -0
  113. package/themes/_TEMPLATE.json +2 -0
  114. package/themes/biker.json +2 -0
  115. package/themes/commentator.json +2 -0
  116. package/themes/cyberpunk.json +2 -0
  117. package/themes/gamer.json +2 -0
  118. package/themes/imperial.json +2 -0
  119. package/themes/joker.json +2 -0
  120. package/themes/marvin.json +2 -0
  121. package/themes/mean.json +2 -0
  122. package/themes/military.json +2 -0
  123. package/themes/neutral.json +2 -0
  124. package/themes/pirate.json +2 -0
  125. package/themes/sports.json +2 -0
  126. package/themes/verstappen.json +2 -0
  127. package/themes/wizard.json +2 -0
  128. package/web/dist/assets/Activity-D2kOc3yi.js +1 -0
  129. package/web/dist/assets/ActivityDetail-By3xOr21.js +1 -0
  130. package/web/dist/assets/{Bonsai-BBl4XXqs.js → Bonsai-CBWDTBA4.js} +1 -1
  131. package/web/dist/assets/{CopyButton-Beven8yn.js → CopyButton-BVbpriMB.js} +1 -1
  132. package/web/dist/assets/Dashboard-CIJLPHM9.js +2 -0
  133. package/web/dist/assets/Docs-CiRRIELs.js +5 -0
  134. package/web/dist/assets/Factories-DhyK0O8d.js +1 -0
  135. package/web/dist/assets/{GreenhouseView-Bce212qd.js → GreenhouseView-DW3PgTPy.js} +1 -1
  136. package/web/dist/assets/Installs-B6nlo-Ly.js +3 -0
  137. package/web/dist/assets/{JournalView-CV4omyww.js → JournalView-O65qEWfp.js} +1 -1
  138. package/web/dist/assets/Kits-C5U-yT6Z.js +1 -0
  139. package/web/dist/assets/Laws-CuTw_XNf.js +4 -0
  140. package/web/dist/assets/{LibRows-Dag1s0ZX.js → LibRows-D6-CVa3K.js} +1 -1
  141. package/web/dist/assets/Library-CzPlerd6.js +3 -0
  142. package/web/dist/assets/Loops-CqNF_-nS.js +2 -0
  143. package/web/dist/assets/{OperatorHudView-JmYY1pBR.js → OperatorHudView-BNr8K5qj.js} +1 -1
  144. package/web/dist/assets/Personal-DeDb9e8O.js +2 -0
  145. package/web/dist/assets/Settings-B8MPN_AD.js +1 -0
  146. package/web/dist/assets/{Tabs-8zsyEPSK.js → Tabs-DJzAez4h.js} +1 -1
  147. package/web/dist/assets/index-BL3P-9Rg.js +6 -0
  148. package/web/dist/index.html +1 -1
  149. package/web/dist/assets/Activity-WQ3ykgxU.js +0 -1
  150. package/web/dist/assets/ActivityDetail-7rt04SkS.js +0 -1
  151. package/web/dist/assets/Dashboard-BgLArtgu.js +0 -2
  152. package/web/dist/assets/Docs-B5aHp86J.js +0 -5
  153. package/web/dist/assets/Factories-BjqzXAw8.js +0 -1
  154. package/web/dist/assets/Installs-B1OsrHXF.js +0 -3
  155. package/web/dist/assets/Kits-CW1e7xNa.js +0 -1
  156. package/web/dist/assets/Laws-1Ckf1lbs.js +0 -4
  157. package/web/dist/assets/Library-B3FuFLel.js +0 -3
  158. package/web/dist/assets/Loops-CwqgnLNw.js +0 -2
  159. package/web/dist/assets/Personal-DKLgLa7Z.js +0 -2
  160. package/web/dist/assets/Settings-BwErnh-R.js +0 -1
  161. package/web/dist/assets/index-Ce6qF2nG.js +0 -6
package/src/AGENT.md.tmpl CHANGED
@@ -24,19 +24,17 @@ Tool-agnostic: where the host has no sub-agents, each {{AGENT}} below is a
24
24
  <!-- LEAN:end -->
25
25
 
26
26
  <!-- LEAN:begin -->
27
- **Readiness sigil — required.** Before your first reply, complete the startup
28
- ritual: read this file and its {{LAWS}}, then **load the project context**
29
- (**Session start**, below). Only then emit your first reply, which MUST begin with the
30
- exact line below, before any other text. Do not paraphrase it and do not skip it —
31
- a first reply that omits the sigil signals the harness was not read, and emitting
32
- it certifies you have loaded the {{LAWS}} *and* the project context. **{{SKILLS}}
33
- first:** when a request matches a {{SKILL}}, invoke it as your first tool
34
- call — before loading context or touching files.
27
+ **Readiness sigil.** Before your first reply, read this file and its {{LAWS}}, then
28
+ load the project context (**Session start**, below). Begin that reply with the line
29
+ below, as written, before any other text. The user reads it as the sign that you
30
+ loaded the {{LAWS}} and the project context; a first reply without it tells them the
31
+ harness was not read. **{{SKILLS}} first:** when a request matches a {{SKILL}}, invoke
32
+ it as your first tool call, before you load context or touch files.
35
33
  <!-- LEAN:else -->
36
- **Readiness sigil — required.** Your first reply MUST begin with the exact line below,
37
- verbatim — it certifies you have read this file and its {{LAWS}} and loaded `context.json`
38
- and its `eager` entries (§9). **{{SKILLS}} first:** when the request matches a {{SKILL}}, invoke
39
- it as your very first tool call — before loading context, reading files, or searching.
34
+ **Readiness sigil.** Before your first reply, read this file and its {{LAWS}} and load
35
+ `context.json` and its `eager` entries (§9); begin that reply with the line below, as
36
+ written. **{{SKILLS}} first:** when the request matches a {{SKILL}}, invoke it as your first
37
+ tool call, before you load context, read files or search.
40
38
  <!-- LEAN:end -->
41
39
 
42
40
  > {{LOADED_SIGIL}}
@@ -205,7 +203,7 @@ decompose it into independent subtasks, route each to the single owning {{AGENT}
205
203
  above, and converge the results yourself. Every handoff carries an **envelope** —
206
204
  the subtask goal, the inputs the {{AGENT}} needs, and its output contract — and the
207
205
  constraints travel with it: dispatched {{AGENTS}} commit only in their own worktree, never
208
- push, and never merge outside their own branch ({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented
206
+ push, and never merge outside their own branch, so the push stays with you ({{DOCTRINE:consent-before-push}}), and an unfulfilled contract returns as a stated gap, never invented
209
207
  content. Where the host exposes a `workflow` tool, prefer the saved `dispatch`
210
208
  workflow ([workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md)); where it does not, run
211
209
  the same shape model-driven via the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md).
@@ -217,7 +215,7 @@ dispatched alone; the [council {{SKILL}}]({{DIR_SKILLS}}/council.md) convenes th
217
215
  subset that productively clashes on a given motion.
218
216
  <!-- LEAN:else -->
219
217
  Dispatched {{AGENTS}} commit only in their worktree, never push, never merge outside
220
- their own branch ({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented content. A
218
+ their own branch, so the push stays with you ({{DOCTRINE:consent-before-push}}), and an unfulfilled contract returns as a stated gap, never invented content. A
221
219
  multi-part goal goes through the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md)
222
220
  (or the [workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md) where the host has a workflow tool);
223
221
  the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/council.md).
@@ -359,7 +357,7 @@ tool you build for yourself — belongs in `{{DIR_NOTEBOOK}}/`, never in the hos
359
357
  tree. `NOTEBOOK.md`, a session file, recalls what you keep here; keep the space referable across sessions — the seeded index
360
358
  is one way; replace it with whatever scheme serves you better. When a note
361
359
  hardens into a durable fact worth recalling verbatim, write it to {{MEMORY}}
362
- (§5, {{DOCTRINE:persist-insight}}). Keep the two stores distinct by *role*, not just by
360
+ in §5 ({{DOCTRINE:persist-insight}}). Keep the two stores distinct by *role*, not just by
363
361
  format: {{MEMORY}} holds durable insight for future sessions, the {{NOTEBOOK}}
364
362
  holds your working artifacts. The one fixed law: `{{DIR_NOTEBOOK}}/` is **personal and
365
363
  git-ignored** — never committed or shared, and the `.gitignore` that guarantees
@@ -457,7 +455,7 @@ new note linked in. Cross-project facts go here via the
457
455
  *{{EPI_CONTEXT}}*
458
456
 
459
457
  <!-- LEAN:begin -->
460
- **Load `context.json` before your first reply — this is not a suggestion.** The
458
+ Load `context.json` before your first reply. The
461
459
  harness carries no project-specific knowledge; this manifest is how the project hands
462
460
  you its own: the repo's own (`context.json` or `.harness/context.json` at its root),
463
461
  else `{{AT_HARNESS}}context.json`. The hook injects its `eager` entries (**Session
@@ -475,7 +473,7 @@ comment carries its schema and setup notes.
475
473
  **Reviewing code** — with any review command, built-in or not — first apply the nearest
476
474
  `REVIEW.md` above each changed file. It overrides the review defaults, never a {{LAW}}.
477
475
  <!-- LEAN:else -->
478
- **Load `context.json` before your first reply — not deferrable.** The repo's own
476
+ Load `context.json` before your first reply. The repo's own
479
477
  (`context.json` or `.harness/context.json` at its root), else `{{AT_HARNESS}}context.json`,
480
478
  is how the project hands you its own knowledge; the hook injects its `eager` entries
481
479
  (**Session start**). `"eager"` entries are read now and are
@@ -5,8 +5,9 @@ effect: read
5
5
  skill: ship
6
6
  outcomes: pass, fail
7
7
  ---
8
- Follow the `ship` skill's pull-request path only: never merge, never enable auto-merge, never
9
- push to any branch but this worktree's own. First look for a PR already open on this branch
8
+ Follow the `ship` skill's pull-request path only: never merge, never enable auto-merge here (the
9
+ `factory` skill's close step arms it, only as the user's standing rule allows), never push to any
10
+ branch but this worktree's own. First look for a PR already open on this branch
10
11
  (`gh pr view --json url,state` or `glab mr view`): after a rework lap it exists, and this stage
11
12
  only pushes the new commits to it.
12
13
 
@@ -65,8 +65,8 @@ form is reconciled — not the principal file alone, but the imports, hooks,
65
65
  indices, cross-links, ignore-rules, and peer configs that point to it. A dangling
66
66
  reference left behind breaks downstream in silence, long after the deed seemed
67
67
  done. Before declaring a teardown complete, hunt each integration point and sever
68
- or rewire it ({{DOCTRINE:search-before-creating}} finds what already exists; this finishes what you
69
- remove). Total teardown, or none.
68
+ or rewire it. A search first finds what already exists ({{DOCTRINE:search-before-creating}}); this
69
+ finishes what you remove. Total teardown, or none.
70
70
  <!-- LEAN:else -->
71
71
  A delete, a rename, or a move is finished only when every reference to the old form is
72
72
  reconciled — imports, hooks, indices, cross-links, ignore-rules, peer configs. Before
@@ -28,8 +28,8 @@ context window and lets the user correct course before effort is spent. When a
28
28
  session ends mid-task, persist it to {{MEMORY}} ({{DOCTRINE:persist-insight}}), open
29
29
  blockers and irreversible changes included. Surface the concrete diff or dry-run
30
30
  output of a consequential change before applying it. Before a risky step, lay down a
31
- recovery point — a stash, a branch, a worktree, a copy — never an unconsented commit
32
- ({{DOCTRINE:consent-before-push}}). On a long task, re-read the worklog and re-verify ground
31
+ recovery point — a stash, a branch, a worktree, a copy — never a commit on the main
32
+ branch ({{DOCTRINE:consent-before-push}}). On a long task, re-read the worklog and re-verify ground
33
33
  truth rather than trust stale mid-context memory. Trivial edits need no plan.
34
34
  <!-- LEAN:else -->
35
35
  For any non-trivial task, write a short numbered plan before executing, keep a running
@@ -37,7 +37,7 @@ worklog. One line:
37
37
  `Done: 1-2. Current: 3 (tests). Next: 4. Blockers: none. Irreversible: none.`
38
38
  When a session ends mid-task, persist it to {{MEMORY}} ({{DOCTRINE:persist-insight}}) with open
39
39
  blockers and irreversibles. Show the diff or dry-run before a consequential change. Before
40
- a risky step, lay down a recovery point — stash or branch — never an unconsented commit
40
+ a risky step, lay down a recovery point — stash or branch — never a commit on main
41
41
  ({{DOCTRINE:consent-before-push}}). Trivial edits need no plan.
42
42
  <!-- LEAN:end -->
43
43
 
@@ -84,41 +84,45 @@ the stale page and fix it in the same change ({{DOCTRINE:documentation-in-step}}
84
84
  <!-- LEAN:end -->
85
85
 
86
86
  ### {{DOCTRINE:consent-before-push}} Consent Before Push
87
- <!-- note: summary: Every commit and push needs explicit, repeated consent. -->
87
+ <!-- note: summary: Main changes only through a green PR; your own branch is free. -->
88
88
  <!-- LEAN:begin -->
89
- Recording and sharing code is consented, never unilateral. **Every** `git commit`
90
- and `git push` needs the user's **explicit acceptance**, on every branch, every
91
- time — a personal feature branch included. A one-time approval is not standing
92
- consent. Consent may cover a **named batch**: "commit as you go on this branch"
93
- stands for commits on that branch until the session ends or the scope changes; a
94
- new session, a new branch, or a widened scope re-asks. Push earns no such default
95
- and stays per-ask unless granted in the same named form. A launched loop's batch
96
- covers commit and push on its own `loop/*` branch; merging that branch into a
97
- shared one never is. A dispatched worker, crew or slice (a Foreman worker, a pipeline
98
- crew, a parallel-agents slice) holds a batch that covers commit, and merge of its own
99
- sub-workers, in its own worktree, off any shared branch; it never pushes. Outside a
100
- batch, before each commit, present in order (1) a plain-language
101
- summary of what changed and why and (2) the exact commit message you intend to use,
102
- then wait. Never push on your own initiative.
103
- On a **shared branch** — `main`, `master`, `develop`, `development`, a
104
- `release`/`hotfix` branch, or anything that is not a dedicated feature branch —
105
- the same gate applies with extra care; when unsure, treat the branch as shared.
106
- Never force-push, hard-reset, or rebase a shared branch: undo a published mistake
107
- with a new revert commit, not a history rewrite — the rare legitimate rewrite goes
108
- through the git-history {{SKILL}} behind a backup. The host gates commit and push at
109
- the tool boundary too, so this consent cannot be lost to a sticky allowlist.
89
+ A push onto the main branch needs consent, and the pull request is that consent. The
90
+ main branch is `main`, `master`, the remote's default branch, or, from a linked
91
+ worktree, the branch the main checkout holds; when unsure whether a branch is one of them
92
+ — a remote with no default recorded, or no remote at all — treat it as main. It
93
+ changes only through a pull request whose required checks are green: never commit on
94
+ it, push to it, or merge into it directly, and never merge a pull request whose
95
+ checks are red, pending or absent. A green pull request is merged on the user's
96
+ acceptance of that merge, or under their standing auto-merge rule (the ship {{SKILL}}
97
+ says when it arms). Where the
98
+ repository has no remote, no CI or no branch protection, a change to the main branch
99
+ needs the user's explicit acceptance of that change. Any other branch you work on is
100
+ your own: commit as the work advances and push it with a plain push, without asking.
101
+ Each commit still holds one intent ({{LAW:one-intent-one-act}}) and passes the commit
102
+ {{SKILL}}'s checks; a forced push asks, even on your own branch. A tag, a release or a
103
+ publish faces outward and asks ({{LAW:deletion-is-deliberate}}). A dispatched worker,
104
+ crew or slice commits, and merges its own sub-workers, only in its own worktree, and
105
+ never pushes: the session that dispatched it pushes the branch and opens the pull
106
+ request. Never force-push,
107
+ hard-reset, or rebase the main branch: undo a published mistake with a revert commit;
108
+ the rare legitimate rewrite goes through the git-history {{SKILL}} behind a backup,
109
+ with the user's acceptance. The host gates commits and pushes onto the main branch at
110
+ the tool boundary, so this consent cannot be lost to a sticky allowlist. (On OpenCode,
111
+ whose permission rules cannot see the branch, every commit and push asks.){{STRICT_CONSENT}}
110
112
  <!-- LEAN:else -->
111
- Recording and sharing code is consented, never unilateral: **every** `git commit` and
112
- `git push` needs **explicit acceptance**, every branch, every time — a personal feature
113
- branch included; one-time approval is not standing consent. A named batch ("commit as
114
- you go") stands until the session ends or scope changes; push earns no default. Never
115
- push on your own initiative. A launched loop's batch covers commit and push on its own
116
- `loop/*` branch only; merging it never. A dispatched worker, crew or slice's covers commit
117
- and merge in its own worktree, off any shared branch, never pushed. Outside a batch, show
118
- the plain summary and the exact commit message before each, then wait. Shared branches — `main`, `master`, `develop`, `development`,
119
- `release`/`hotfix`, any unsure — take the same gate. Never force-push, hard-reset, or
120
- rebase one: undo with a revert commit (git-history {{SKILL}} for a legitimate rewrite).
121
- The host gates both at the tool boundary.
113
+ A push onto the main branch needs consent; the pull request is that consent. Main is
114
+ `main`, `master`, the remote's default, or, from a linked worktree, the main checkout's
115
+ branch; unsure (no remote, or no default recorded), treat it as main. It changes only
116
+ through a pull request with green checks: never commit, push or merge directly onto it,
117
+ never merge a red, pending or unchecked one; a green one on the user's yes or their
118
+ standing auto-merge rule (ship {{SKILL}}). With no remote, CI or protection, a change to
119
+ main needs explicit acceptance.
120
+ Your own branch: commit and plain-push freely; a forced push asks. Tags, releases and
121
+ publishes ask ({{LAW:deletion-is-deliberate}}). A dispatched worker, crew or slice commits
122
+ and merges only in its own worktree, never pushes. Never force-push, hard-reset or
123
+ rebase main: revert instead (git-history {{SKILL}}, with acceptance, for a real rewrite).
124
+ The host gates both at the tool boundary (on OpenCode, which cannot see the branch, every
125
+ commit and push asks).{{STRICT_CONSENT}}
122
126
  <!-- LEAN:end -->
123
127
 
124
128
  ### {{DOCTRINE:bound-the-loop}} Bound the Loop
@@ -3,7 +3,7 @@
3
3
  "description": "Turn an analysis (a document, pasted text or a request) into a spec whose task list you approve, build each task in turn with the feature loop in one worktree, run the base branch's checks and a review panel, play the holdout scenarios it never saw, then open one pull request and wait for green CI; a failed check, review or scenario, or red CI, sends the work back to the loop as one more task, twice at most each. At the end it asks you once whether to merge.",
4
4
  "category": "development",
5
5
  "rules": [
6
- "Never merge or enable auto-merge without the user's yes, asked once at the end of the run.",
6
+ "Never merge without the user's yes, asked once at the end of the run; enable auto-merge only as the user's standing auto-merge rule allows.",
7
7
  "Push only this worktree's own branch."
8
8
  ],
9
9
  "stages": ["intake", "spec", "holdout-write", "loop:feature", "checks", "review-panel", "holdout", "pr-open", "merge-gate", "retro"],
@@ -3,7 +3,7 @@
3
3
  "description": "Take one bug report, fix it with the bugfix loop, run the base branch's checks and a review panel, play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed check, review or scenario, or red CI, sends the fix back to the loop, twice at most each. At the end it asks you once whether to merge.",
4
4
  "category": "development",
5
5
  "rules": [
6
- "Never merge or enable auto-merge without the user's yes, asked once at the end of the run.",
6
+ "Never merge without the user's yes, asked once at the end of the run; enable auto-merge only as the user's standing auto-merge rule allows.",
7
7
  "Push only this worktree's own branch."
8
8
  ],
9
9
  "stages": ["intake", "holdout-write", "loop:bugfix", "checks", "review-panel", "holdout", "pr-open", "merge-gate", "retro"],
@@ -3,7 +3,7 @@
3
3
  "description": "Take one issue, let triage pick the lane that fits (the bugfix, feature, deps-upgrade or refactor loop, or a docs-only update), run the base branch's checks and a review panel, play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed check, review or scenario, or red CI, sends the work back to that lane, twice at most each. At the end it asks you once whether to merge.",
4
4
  "category": "development",
5
5
  "rules": [
6
- "Never merge or enable auto-merge without the user's yes, asked once at the end of the run.",
6
+ "Never merge without the user's yes, asked once at the end of the run; enable auto-merge only as the user's standing auto-merge rule allows.",
7
7
  "Push only this worktree's own branch."
8
8
  ],
9
9
  "stages": [
@@ -0,0 +1,10 @@
1
+ ### Terminal tools kit
2
+
3
+ Applies when the agent drives a terminal program through that program's own CLI: Herdr, or OpenCode V2.
4
+
5
+ - Gate on the environment first: Herdr only inside a Herdr pane (`HERDR_ENV=1`), OpenCode only when `opencode --version` reports a 2.x. If the gate fails, say so and stop.
6
+ - Read before acting: list the live state (panes, agents, sessions, service status) and take every id from a command's output, never from an example or an earlier listing.
7
+ - Close what you opened, and only that. Never close, kill or delete a pane, agent, session or workspace you did not create, unless the user asks.
8
+ - Never stop, restart or reconfigure the user's server or background service (`herdr server stop`, `opencode service stop|restart|set|unset`) unless the user asks.
9
+ - No credentials: login, account switches and SSH or OAuth prompts are the user's to complete. Never print, export or import stored credentials: no `opencode auth export|import`, no `opencode service get password|env` and no bare `service get`, which prints the env too.
10
+ - Approval dialogs belong to the user: never answer another agent's permission prompt, and never pass a flag that auto-approves permissions unless the user asks for it.
@@ -0,0 +1,13 @@
1
+ {
2
+ "description": "Terminal programs the agent drives through their own CLI: Herdr panes and agents from inside a Herdr pane, and OpenCode V2 from another session.",
3
+ "skills": ["herdr", "opencode-cli"],
4
+ "agents": [],
5
+ "rules": "kits/terminal-tools/rules.md",
6
+ "rulesWordBudget": 300,
7
+ "catalogue": {
8
+ "skills": [
9
+ "| [herdr]({{DIR_SKILLS}}/herdr.md) | the user names Herdr and the session runs in a Herdr pane (`HERDR_ENV=1`): inspect or control its workspaces, tabs, panes, commands or another agent |",
10
+ "| [opencode-cli]({{DIR_SKILLS}}/opencode-cli.md) | driving OpenCode V2 from another session through its CLI: a headless `opencode run`, its sessions, the background service, MCP servers, plugins, models, stats, debug |"
11
+ ]
12
+ }
13
+ }
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -16,7 +16,10 @@ task that would block it to one background task worker, and keeps answering the
16
16
  - **One worker per task.** Dispatch one developer {{AGENT}} in the background, in its own
17
17
  worktree (without worktrees: one tree, one worker at a time). The brief carries the task as the user stated it, BASE, the write set, the
18
18
  proof commands, and the rule that it commits only in its own worktree, never pushes, and
19
- never merges outside its own branch; without a worktree, it never commits. The worker explores, implements and tests in its own context, loading {{SKILLS}}
19
+ never merges outside its own branch; without a worktree, it never commits. It also says
20
+ to run each command from the worktree as working directory or with absolute paths
21
+ (`git -C`, `npm --prefix`), never opening with `cd <worktree> &&`: the host asks the user
22
+ to approve that form. The worker explores, implements and tests in its own context, loading {{SKILLS}}
20
23
  as it needs them; after two repair rounds on its own red tests it returns red with its
21
24
  findings ({{DOCTRINE:bound-the-loop}}). Check its write set against every task in flight
22
25
  ({{DOCTRINE:one-writer-per-file}}).
@@ -47,8 +50,8 @@ task that would block it to one background task worker, and keeps answering the
47
50
  worker serves one task and retires when that task is merged or dropped.
48
51
  - **Merge on proof you re-ran.** A worker hands back its branch, its local commits and any
49
52
  uncommitted work, with raw test + lint output. The parent re-runs those commands itself —
50
- a worker's log is the worker's account, not the state — shows the user the diff from BASE
51
- and the green output, and commits and merges only once the user accepts
53
+ a worker's log is the worker's account, not the state — merges the branch into its own,
54
+ and lands it on the main branch only through a pull request with green checks
52
55
  ({{DOCTRINE:consent-before-push}}). Surface completions, failures and merges as they
53
56
  happen; watch workers as the pipeline {{SKILL}}'s step 2 watches a crew.
54
57
  - **Crews are opt-in.** Run the `pipeline` {{SKILL}} only when the user asks for a
@@ -13,8 +13,9 @@ Close each run with one beat of reflection on the {{SKILL}} itself:
13
13
  `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what you expected> (<date>)`.
14
14
  `situation:` bounds where the correction holds; `seen:` is the evidence it is
15
15
  later judged by; `general` marks one that would fix other {{SKILLS}} too. Never
16
- edit this file: it is a rendered copy, a rebuild overwrites it, and the doctor
17
- reports the edit as drift. `geneseed diff` carries the notes back to the source;
16
+ edit this file: it is a rendered copy, a rebuild overwrites it. A bundled script
17
+ that is broken is the one exception: fix it in place, and tell the user which
18
+ file you changed. `geneseed diff` carries the notes back to the source;
18
19
  folding a note into the source is the user's call, through the skill-forge
19
20
  {{SKILL}} ({{LAW:one-intent-one-act}}).
20
21
  - Keep the notes sharp: amend or delete a line before adding one — a line with no
@@ -31,9 +32,10 @@ One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or
31
32
  wrong trigger is a flaw in this file — write the exact correction on your own, with no
32
33
  prompt, into `{{PATH_NOTES}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
33
34
  name) as `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened vs expected> (<date>)`,
34
- never into this rendered file, which a rebuild overwrites. Folding a note into the
35
- source is the user's call ({{LAW:one-intent-one-act}}). Read that notes
36
- file before the first step when it exists; it wins where it disagrees. Keep it short.
37
- A lesson that is not about this file goes to {{MEMORY}} only if it clears
38
- {{DOCTRINE:persist-insight}}'s bar. Nothing learned — move on.
35
+ never into this rendered file, which a rebuild overwrites. A bundled script that is
36
+ broken is the one exception: fix it in place, and tell the user which file you
37
+ changed. Folding a note into the source is the user's call ({{LAW:one-intent-one-act}}).
38
+ Read that notes file before the first step when it exists; it wins where it disagrees.
39
+ Keep it short. A lesson that is not about this file goes to {{MEMORY}} only if it
40
+ clears {{DOCTRINE:persist-insight}}'s bar. Nothing learned — move on.
39
41
  <!-- LEAN:end -->
@@ -19,25 +19,25 @@
19
19
  repo has no discernible convention, default to **Conventional Commits**:
20
20
  `type(scope): subject` (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`…),
21
21
  with a `!` before the colon or a `BREAKING CHANGE:` footer for a breaking change.
22
- 5. **Get explicit consent before committing ({{DOCTRINE:consent-before-push}}).** On *every*
23
- branch — feature branches included — first show the user a plain-language summary of
24
- the change *and* the exact commit message, then wait for explicit acceptance before
25
- committing. For a non-trivial change, offer the `explain-changes` skill's visual
26
- walkthrough before asking — an offer, never a condition of the commit. A previous
27
- approval is not standing consent; ask again each commit, unless a batch that
28
- {{DOCTRINE:consent-before-push}} names covers it: a named batch, a launched loop on its
29
- own `loop/*` branch, or a dispatched worker, crew or slice (a Foreman worker, a
30
- pipeline crew, a parallel-agents slice) in its own worktree, off any shared branch —
31
- which commits there without asking, since it cannot reach the user, and never pushes. On a *shared branch*
32
- (`main`, `master`, `develop`/`development`, a release/hotfix branch, or any branch
33
- that is not a dedicated feature branch) apply the same gate with extra care.
34
- 6. Push only when the user has explicitly approved *that push* ({{DOCTRINE:consent-before-push}} / {{LAW:deletion-is-deliberate}})
35
- — never push on your own initiative, on any branch, and never treat one approval as
36
- consent for the next.
22
+ 5. **Commit on your own branch; never on the main branch ({{DOCTRINE:consent-before-push}}).**
23
+ On your own branch, commit without asking once steps 1–4 hold. The main branch
24
+ (`main`, `master`, the remote's default, and from a linked worktree the main checkout's branch) takes no direct
25
+ commit: move the work to a branch first and land it through a pull request. Where the
26
+ repository has no remote or no CI, a commit on the main branch needs explicit
27
+ acceptance: show a plain-language summary and the exact message, then wait. For a
28
+ non-trivial change, offer the `explain-changes` skill's visual walkthrough — an
29
+ offer, never a condition. A dispatched worker, crew or slice commits only in its own
30
+ worktree.
31
+ 6. Push your own branch with a plain push when the work is ready for review; a forced
32
+ push asks, and a push onto the main branch asks ({{DOCTRINE:consent-before-push}} /
33
+ {{LAW:deletion-is-deliberate}}). A dispatched worker, crew or slice never pushes. If the
34
+ branch's PR has auto-merge armed, disarm it before the push (`gh pr merge <pr> --disable-auto`;
35
+ GitLab: `glab api --method POST projects/:id/merge_requests/<iid>/cancel_merge_when_pipeline_succeeds`):
36
+ an armed PR would merge the new head unreviewed. Re-arm only through the [ship {{SKILL}}](ship.md).
37
37
 
38
38
  ## Done when
39
39
  - The commit contains only the intended change and the working tree is clean of it,
40
- and every commit and push went out only with the user's explicit, per-action consent
41
- or inside a batch that covers it.
40
+ and nothing was committed or pushed onto the main branch without a green pull
41
+ request or the user's explicit acceptance.
42
42
 
43
43
  <!-- INCLUDE: skills/_self-improvement.md -->
@@ -5,7 +5,7 @@ Needs the CI log: the host's CI tool, `gh run view --log-failed` or equivalent,
5
5
  2. **Classify before touching anything.** First diff against the last green run: commit range, lockfile, runner image, toolchain. Then name the class: a *real failure* (code or test wrong), an *environment difference* (a version, path, line endings, missing binary, a test skipped locally but not in CI), an *infra flake* (network, runner, cache, timeout), or a *gate on the report itself* (a coverage or count threshold, a lint the local hook skips).
6
6
  3. **Reproduce under CI's own conditions** — the workflow's script, flags and a matching toolchain. Green locally and red in CI has not reproduced yet: close the gap (the env var, `--frozen-lockfile`, the reporter, the binary not on PATH) until it fails the same way. Never retry a run blindly. CI logs are shared: probe a secret's presence, never its value (`[ -n "$TOKEN" ] && echo set || echo unset`).
7
7
  4. **Fix at the cause** through steps 2–6 of the debug procedure. For an environment difference, make the *repo* deterministic (pin, normalise, declare) rather than CI more permissive. A flake is fixed at its source — the race, the timeout, the unpinned resource — or quarantined *with an issue and an owner*, never silently skipped ({{LAW:cure-the-cause}}). A sleep that guesses at timing becomes a wait on the actual condition with a bounded timeout; a fixed delay that remains says why ({{DOCTRINE:honest-tests}}). A fix to CI config itself is its own commit ({{LAW:one-intent-one-act}}), noted in the PR.
8
- 5. **Prove it the way CI will:** run CI's command locally once more and read the output, push with the user's per-push consent ({{DOCTRINE:consent-before-push}}), and watch the re-run to green; the gate that reported it verifies the fix. Report what failed, its class, what changed, and the green run.
8
+ 5. **Prove it the way CI will:** run CI's command locally once more and read the output, push the fix to its own branch ({{DOCTRINE:consent-before-push}}), and watch the re-run to green; the gate that reported it verifies the fix. Report what failed, its class, what changed, and the green run.
9
9
 
10
10
  ## Done when
11
11
  - The debug {{SKILL}}'s own Done-when holds, and the run was reproduced under CI's conditions and the same CI run was re-run and read green — no retry-until-green, no test quietly skipped.
@@ -37,9 +37,9 @@ code needs to move onto a new API, framework, or language version.
37
37
  Nothing is upgraded by the audit itself.
38
38
  7. **Before executing any bump, read the upstream migration guide and changelog first**
39
39
  ({{DOCTRINE:read-the-docs-first}}); list the breaking changes that actually touch this
40
- codebase. Work on a dedicated branch, never directly on a shared one, so a failed migration
41
- rolls back cleanly ({{DOCTRINE:consent-before-push}} applies its shared-branch care to
42
- anything that does land there).
40
+ codebase. Work on a dedicated branch, never directly on the main branch, so a failed
41
+ migration rolls back cleanly; it reaches main only through a green pull request
42
+ ({{DOCTRINE:consent-before-push}}).
43
43
  8. **Execute one change at a time** — one dependency, or one breaking change — never batching
44
44
  unrelated bumps into a single step ({{LAW:one-intent-one-act}}). Run the project's checks
45
45
  after *each* step: a green suite between steps is what lets you bisect a later failure to