geneseed 5.3.1 → 5.5.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 (248) hide show
  1. package/CHANGELOG.md +102 -0
  2. package/README.md +51 -18
  3. package/SHIPPED.md +7 -7
  4. package/adapters/bob/README.md +12 -1
  5. package/adapters/opencode/README.md +5 -3
  6. package/adapters/opencode/plugins/geneseed-context.js +77 -10
  7. package/adapters/opencode/plugins/geneseed-guard.js +106 -22
  8. package/adapters/opencode/plugins/geneseed-learn.js +641 -6
  9. package/bin/geneseed-cli.mjs +10 -0
  10. package/bin/geneseed-hook.mjs +5 -4
  11. package/docs/PRD.md +1 -1
  12. package/docs/README.md +1 -0
  13. package/docs/concepts/agents.md +14 -2
  14. package/docs/concepts/collaboration.md +2 -2
  15. package/docs/concepts/enforcement-table.md +5 -2
  16. package/docs/concepts/exclusions.md +16 -2
  17. package/docs/concepts/footprint.md +1 -1
  18. package/docs/concepts/foreman-mode.md +23 -4
  19. package/docs/concepts/hook-gates.md +4 -4
  20. package/docs/concepts/hooks.md +25 -7
  21. package/docs/concepts/host-matrix.md +4 -4
  22. package/docs/concepts/hosts.md +1 -1
  23. package/docs/concepts/kits.md +12 -2
  24. package/docs/concepts/loop-bricks.md +3 -3
  25. package/docs/concepts/loops.md +6 -4
  26. package/docs/concepts/ownership.md +1 -1
  27. package/docs/concepts/rules.md +2 -2
  28. package/docs/concepts/shared-tier.md +1 -1
  29. package/docs/concepts/skills.md +21 -1
  30. package/docs/concepts/themes.md +1 -1
  31. package/docs/extending.md +73 -29
  32. package/docs/guides/auto-merge.md +100 -0
  33. package/docs/guides/choose-your-setup.md +1 -1
  34. package/docs/guides/headless.md +1 -1
  35. package/docs/guides/install-clone.md +19 -1
  36. package/docs/guides/install-scripted.md +8 -2
  37. package/docs/guides/install.md +20 -2
  38. package/docs/guides/loop-finish.md +3 -3
  39. package/docs/guides/loop-running.md +4 -4
  40. package/docs/guides/project-context.md +1 -1
  41. package/docs/guides/run-a-factory.md +2 -2
  42. package/docs/guides/setup-doctrines.md +2 -2
  43. package/docs/guides/setup-footprint.md +1 -1
  44. package/docs/guides/uninstall.md +3 -3
  45. package/docs/guides/upgrade.md +2 -2
  46. package/docs/guides/worktree.md +1 -1
  47. package/docs/reference/env-context.md +1 -1
  48. package/docs/reference/environment.md +4 -2
  49. package/docs/reference/plugin-activity.md +1 -1
  50. package/docs/reference/plugin-guard.md +1 -1
  51. package/docs/reference/plugin-learn.md +5 -1
  52. package/docs/reference/plugin-workflow.md +1 -1
  53. package/docs/reference/profiles.md +142 -0
  54. package/docs/reference/troubleshoot-doctor.md +1 -1
  55. package/docs/reference/troubleshoot-hooks.md +2 -2
  56. package/docs/reference/troubleshoot-install.md +3 -3
  57. package/docs/reference/troubleshoot-tools.md +1 -1
  58. package/docs/token-footprint.md +11 -6
  59. package/docs/understand/design-choices-engineering.md +1 -1
  60. package/docs/understand/enforced-vs-asked.md +1 -1
  61. package/docs/understand/machine-claude.md +2 -2
  62. package/docs/understand/on-your-machine.md +1 -1
  63. package/docs/web-ui.md +8 -6
  64. package/harness.config.json +1 -1
  65. package/js/README.md +11 -3
  66. package/js/build/args.mjs +16 -4
  67. package/js/build/catalog.mjs +11 -1
  68. package/js/build/driver.mjs +74 -16
  69. package/js/build/emit-claude.mjs +32 -5
  70. package/js/build/emit-opencode.mjs +16 -9
  71. package/js/build/export.mjs +1 -1
  72. package/js/build/generate.mjs +12 -157
  73. package/js/build/notes-migrate.mjs +99 -0
  74. package/js/build/profile.mjs +326 -0
  75. package/js/build/render.mjs +110 -8
  76. package/js/build/retired-skills.mjs +60 -13
  77. package/js/build/source.mjs +100 -3
  78. package/js/build/stubs.mjs +4 -1
  79. package/js/cli-table.json +212 -7
  80. package/js/hosts/agent-runs.mjs +205 -0
  81. package/js/hosts/done-checks.mjs +3 -1
  82. package/js/hosts/hooks-done.mjs +428 -63
  83. package/js/hosts/hooks-learn.mjs +89 -3
  84. package/js/hosts/hooks-prims.mjs +44 -4
  85. package/js/hosts/hooks.mjs +159 -9
  86. package/js/hosts/hosts.mjs +10 -0
  87. package/js/hosts/installs.mjs +44 -2
  88. package/js/hosts/link.mjs +45 -10
  89. package/js/hosts/native.mjs +61 -7
  90. package/js/hosts/opencode.mjs +1 -1
  91. package/js/hosts/settings.mjs +101 -3
  92. package/js/hosts/spec-feedback.mjs +538 -0
  93. package/js/hosts/usage.mjs +67 -8
  94. package/js/inspect/agent-scores.mjs +118 -0
  95. package/js/inspect/checks-authoring.mjs +2 -1
  96. package/js/inspect/checks-build.mjs +20 -4
  97. package/js/inspect/checks-constitution.mjs +32 -0
  98. package/js/inspect/checks-repo.mjs +27 -2
  99. package/js/inspect/cost.mjs +6 -5
  100. package/js/inspect/diff.mjs +46 -8
  101. package/js/inspect/doctor.mjs +4 -0
  102. package/js/inspect/inventory.mjs +1 -1
  103. package/js/inspect/status.mjs +3 -1
  104. package/js/inspect/validate.mjs +1 -0
  105. package/js/lib/machine-dir.mjs +8 -0
  106. package/js/lib/paths.mjs +4 -1
  107. package/js/maintain/profile-scope.mjs +145 -0
  108. package/js/maintain/profiles.mjs +486 -0
  109. package/js/maintain/setup.mjs +413 -15
  110. package/js/maintain/uninstall.mjs +4 -1
  111. package/js/maintain/update.mjs +4 -2
  112. package/js/web/actions.mjs +44 -41
  113. package/js/web/api.mjs +13 -3
  114. package/js/web/handler.mjs +8 -0
  115. package/js/web/jobs.mjs +5 -4
  116. package/js/web/profiles-api.mjs +201 -0
  117. package/js/web/routes.mjs +5 -0
  118. package/package.json +2 -1
  119. package/profiles/guillaume-claude-global.json +16 -0
  120. package/profiles/starter.json +14 -0
  121. package/registry.json +14 -0
  122. package/src/AGENT.md.tmpl +16 -18
  123. package/src/agents/_self-improvement.md +15 -7
  124. package/src/agents/_template.md +4 -2
  125. package/src/agents/advocate.md +1 -1
  126. package/src/agents/architect.md +1 -1
  127. package/src/agents/developer.md +10 -3
  128. package/src/agents/devops-engineer.md +1 -1
  129. package/src/agents/docker-expert.md +1 -1
  130. package/src/agents/docs.md +1 -1
  131. package/src/agents/empiricist.md +1 -1
  132. package/src/agents/explorer.md +4 -2
  133. package/src/agents/framer.md +1 -1
  134. package/src/agents/historian.md +1 -1
  135. package/src/agents/kubernetes-specialist.md +1 -1
  136. package/src/agents/memory-curator.md +1 -1
  137. package/src/agents/operator.md +1 -1
  138. package/src/agents/performance.md +1 -1
  139. package/src/agents/pragmatist.md +1 -1
  140. package/src/agents/react-engineer.md +1 -1
  141. package/src/agents/react-reviewer.md +1 -1
  142. package/src/agents/researcher.md +1 -1
  143. package/src/agents/reviewer.md +10 -3
  144. package/src/agents/security.md +1 -1
  145. package/src/agents/skeptic.md +1 -1
  146. package/src/agents/spring-boot-engineer.md +1 -1
  147. package/src/agents/spring-reviewer.md +1 -1
  148. package/src/agents/spring-security.md +1 -1
  149. package/src/agents/steward.md +1 -1
  150. package/src/agents/tester.md +4 -2
  151. package/src/agents/user-advocate.md +1 -1
  152. package/src/agents/visionary.md +1 -1
  153. package/src/bricks/pr-open.md +3 -2
  154. package/src/doctrines/ops.md +2 -2
  155. package/src/doctrines/process.md +40 -36
  156. package/src/factories/analysis-to-build.json +1 -1
  157. package/src/factories/bug-report-to-fix.json +1 -1
  158. package/src/factories/issue-to-pr.json +1 -1
  159. package/src/kits/terminal-tools/rules.md +10 -0
  160. package/src/kits/terminal-tools.json +13 -0
  161. package/src/licenses/herdr.txt +201 -0
  162. package/src/memory/README.md +12 -2
  163. package/src/modes/foreman.md +25 -9
  164. package/src/skill-descriptions.json +63 -0
  165. package/src/skills/_self-improvement.md +42 -24
  166. package/src/skills/_template.md +3 -1
  167. package/src/skills/brainstorm.md +35 -22
  168. package/src/skills/commit.md +17 -17
  169. package/src/skills/daydream/VENDOR.md +6 -0
  170. package/src/skills/debug/ci.md +1 -1
  171. package/src/skills/dependencies.md +3 -3
  172. package/src/skills/diagram-design/VENDOR.md +4 -0
  173. package/src/skills/document-project.md +3 -2
  174. package/src/skills/explain-changes/VENDOR.md +5 -1
  175. package/src/skills/factory.md +13 -4
  176. package/src/skills/geneseed.md +4 -2
  177. package/src/skills/git-history.md +5 -7
  178. package/src/skills/herdr.md +135 -0
  179. package/src/skills/loop.md +3 -2
  180. package/src/skills/opencode-cli.md +84 -0
  181. package/src/skills/parallel-agents.md +11 -0
  182. package/src/skills/pipeline.md +3 -3
  183. package/src/skills/plan.md +5 -4
  184. package/src/skills/react-view-transitions/VENDOR.md +7 -1
  185. package/src/skills/release.md +11 -9
  186. package/src/skills/review-response.md +4 -2
  187. package/src/skills/rule/approve.md +2 -1
  188. package/src/skills/rule.md +27 -1
  189. package/src/skills/ship.md +54 -7
  190. package/src/skills/skill-forge.md +5 -3
  191. package/src/skills/token-report/VENDOR.md +5 -1
  192. package/src/skills/worktree.md +2 -2
  193. package/src/upstreams.json +9 -2
  194. package/themes/README.md +3 -1
  195. package/themes/_TEMPLATE.json +2 -0
  196. package/themes/biker.json +2 -0
  197. package/themes/commentator.json +2 -0
  198. package/themes/cyberpunk.json +2 -0
  199. package/themes/gamer.json +2 -0
  200. package/themes/imperial.json +2 -0
  201. package/themes/joker.json +2 -0
  202. package/themes/marvin.json +2 -0
  203. package/themes/mean.json +2 -0
  204. package/themes/military.json +2 -0
  205. package/themes/neutral.json +2 -0
  206. package/themes/pirate.json +2 -0
  207. package/themes/sports.json +2 -0
  208. package/themes/verstappen.json +2 -0
  209. package/themes/wizard.json +2 -0
  210. package/web/dist/assets/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
  211. package/web/dist/assets/Activity-LKsDzsnK.js +1 -0
  212. package/web/dist/assets/ActivityDetail-DhwTfPm6.js +1 -0
  213. package/web/dist/assets/{Bonsai-BBl4XXqs.js → Bonsai-CePMLrpr.js} +1 -1
  214. package/web/dist/assets/{CopyButton-Beven8yn.js → CopyButton-CuoaJ6k7.js} +1 -1
  215. package/web/dist/assets/Dashboard-D1VKuvLe.js +2 -0
  216. package/web/dist/assets/Docs-CUrHJKaU.js +5 -0
  217. package/web/dist/assets/Factories-Ci1XfmSy.js +1 -0
  218. package/web/dist/assets/{GreenhouseView-Bce212qd.js → GreenhouseView-CNfH2lPK.js} +1 -1
  219. package/web/dist/assets/Installs-ZHQZM1iS.js +3 -0
  220. package/web/dist/assets/{JournalView-CV4omyww.js → JournalView-CMsWahkS.js} +1 -1
  221. package/web/dist/assets/Kits-CkliyK0n.js +1 -0
  222. package/web/dist/assets/Laws-hh4O3HZ4.js +4 -0
  223. package/web/dist/assets/{LibRows-Dag1s0ZX.js → LibRows-Brv0Hmkr.js} +1 -1
  224. package/web/dist/assets/Library-BYmiLjJr.js +3 -0
  225. package/web/dist/assets/Loops-ytm-xJ68.js +2 -0
  226. package/web/dist/assets/{OperatorHudView-JmYY1pBR.js → OperatorHudView-KaqCx_HP.js} +1 -1
  227. package/web/dist/assets/Personal-CmcnRKYE.js +2 -0
  228. package/web/dist/assets/Settings-tUrpdOfq.js +1 -0
  229. package/web/dist/assets/{Tabs-8zsyEPSK.js → Tabs-CD7etcGD.js} +1 -1
  230. package/web/dist/assets/api-CZ-x0iWG.js +1 -0
  231. package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
  232. package/web/dist/assets/{index-CRWqKxfY.css → index-Ba_Kg3Af.css} +1 -1
  233. package/web/dist/assets/index-COKbhFNo.js +6 -0
  234. package/web/dist/index.html +3 -3
  235. package/web/dist/assets/Activity-WQ3ykgxU.js +0 -1
  236. package/web/dist/assets/ActivityDetail-7rt04SkS.js +0 -1
  237. package/web/dist/assets/Dashboard-BgLArtgu.js +0 -2
  238. package/web/dist/assets/Docs-B5aHp86J.js +0 -5
  239. package/web/dist/assets/Factories-BjqzXAw8.js +0 -1
  240. package/web/dist/assets/Installs-B1OsrHXF.js +0 -3
  241. package/web/dist/assets/Kits-CW1e7xNa.js +0 -1
  242. package/web/dist/assets/Laws-1Ckf1lbs.js +0 -4
  243. package/web/dist/assets/Library-B3FuFLel.js +0 -3
  244. package/web/dist/assets/Loops-CwqgnLNw.js +0 -2
  245. package/web/dist/assets/Personal-DKLgLa7Z.js +0 -2
  246. package/web/dist/assets/Settings-BwErnh-R.js +0 -1
  247. package/web/dist/assets/api-DLDVY3K-.js +0 -1
  248. 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).
@@ -300,7 +298,7 @@ inventory — that list is the catalogue and it is authoritative, as is its
300
298
  procedure is in [`{{DIR_SKILLS}}/`]({{DIR_SKILLS}}/) and the host loads it on
301
299
  demand.
302
300
  <!-- CATALOG:end -->
303
- {{EXCLUDED_SKILLS_LINE}}{{KITS_LINE}}{{SHARED_TIER_LINE}}
301
+ {{EXCLUDED_SKILLS_LINE}}{{KITS_LINE}}{{SHARED_TIER_LINE}}{{CONTEXT_WINDOW_LINE}}
304
302
  When a task repeats and no {{SKILL}} covers it, forge one through the
305
303
  [skill-forge]({{DIR_SKILLS}}/skill-forge.md) {{SKILL}}: copy
306
304
  [`{{DIR_SKILLS}}/_template.md`]({{DIR_SKILLS}}/_template.md), keep it to one coherent
@@ -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
@@ -3,10 +3,18 @@
3
3
  If this spec misled you — an input you needed but were not given, a boundary
4
4
  that proved wrong, a step you could not execute — end your report with one line:
5
5
  `spec-feedback: [agent|general] <the one-line fix> [— situation: <when it applies>] — seen:
6
- <what happened, against what this spec led you to expect>`. `general` marks a fix other
7
- {{AGENTS}} need too. Omit the line when there is no friction. The caller weighs the
8
- feedback and writes a real flaw, dated, into `{{PATH_NOTES}}/agent-notes/<name>.md` on
9
- its own, with no prompt — never into this rendered file, which a rebuild overwrites —
10
- and hands those notes to every later dispatch of this {{AGENT}}. Folding a note into the
11
- source is the user's call, after the skill-forge {{SKILL}}'s probe. It records the feedback to {{MEMORY}} only if it clears
12
- {{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
6
+ <what happened, against what this spec led you to expect>`. Ask one question first: is it true
7
+ in any repo, or only here? Any repo: `[agent]`, or `[general]` for a fix other {{AGENTS}} need
8
+ too. Only here: `[agent:project]`, or `[general:project]`. Omit the line when there is no
9
+ friction. When the run ends, the harness hook copies each line, dated, into the machine notes
10
+ `{{PATH_NOTES}}/agent-notes/<name>.md` (a `general` line into `agent-notes/_general.md` there),
11
+ or a `project` line into `{{PATH_PROJECT_NOTES}}/agent-notes/` at the project root, the same two
12
+ files (in a linked worktree, the main checkout's) — no model call, and never into this rendered file, which
13
+ a rebuild overwrites. Step 0 reads those notes at every later dispatch of this {{AGENT}}, machine
14
+ first; the project notes win where they disagree. When a step-0 read is refused, or the brief
15
+ forbids that path, skip it, say so in one line of the report, and go on. The caller writes no
16
+ note itself, except on a host with no subagent-finished hook (Bob), where it copies the line
17
+ into the machine or the project file, in the same form. The caller
18
+ weighs the line, and folding a note into the source is the user's call, after the
19
+ skill-forge {{SKILL}}'s probe. The caller records the feedback to {{MEMORY}} only if it
20
+ clears {{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
@@ -42,8 +42,10 @@
42
42
  write-capable {{AGENT}}'s spec must not contain it, or its emit is locked down.
43
43
 
44
44
  ## Procedure
45
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists in the harness, read it first —
46
- it holds your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
45
+ 0. Read first, each if it exists — your durable lessons from prior dispatches
46
+ ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback
47
+ notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`,
48
+ then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
47
49
  1. Step-by-step method this {{AGENT}} follows.
48
50
 
49
51
  ## Output contract
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to ground the case in the real artifact. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
21
21
  1. Read the motion and the artifact so the case is concrete, not abstract ({{DOCTRINE:read-the-docs-first}}).
22
22
  2. Steelman the proposal: make its strongest case — the upside, the opportunity, the cost of *not* acting ({{ONTOLOGY}}: {{ONT_CONDUCT}}).
23
23
  3. Name the single objection the proposal must survive, and answer it; concede only what is genuinely indefensible.
@@ -22,7 +22,7 @@
22
22
  <!-- bash: allow -->
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Establish the current state: data shapes, module boundaries, existing patterns.
27
27
  2. Propose 2–3 approaches with trade-offs; recommend one with reasoning.
28
28
  3. Break the chosen approach into isolated units, each with one purpose and a
@@ -22,16 +22,20 @@
22
22
  decisions the developer approved, carried in the brief.
23
23
 
24
24
  ## Allowed tools
25
- - **Read + write to the assigned worktree.** May run the project's own build/lint
26
- commands to self-check before handing off.
25
+ - **Read + write to the assigned worktree.** May run the project's own build, lint and
26
+ test commands to self-check before handing off; installs dependencies (`npm ci` and
27
+ alike) only when the brief allows it.
27
28
  <!-- bash: allow -->
29
+ - In an isolated worktree, run one plain command per call: `git -C <worktree>`, never
30
+ `cd <worktree> &&`, no heredocs. Change files with the edit and write tools; a `\u`
31
+ escape in source stays an escape — check it in the diff.
28
32
  - Commits only in its own worktree, never pushes, and never merges outside its own branch
29
33
  ({{DOCTRINE:consent-before-push}}); into that branch it merges only the branches of
30
34
  sub-workers it started. The parent re-runs the proof and merges beyond it once the user
31
35
  accepts.
32
36
 
33
37
  ## Procedure
34
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
38
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
35
39
  1. Implement the smallest change that satisfies the scoped task ({{DOCTRINE:smallest-viable-diff}}) —
36
40
  in the assigned worktree only, never touching the parent's own tree. In ownership mode,
37
41
  write only what the approved decisions cover; on a choice none of them covers, stop and
@@ -61,6 +65,9 @@ in your own context, and after two repair rounds on your own red tests return re
61
65
  findings ({{DOCTRINE:bound-the-loop}}). As a lead, hold every member's result before you end. Report `T<n> · <task> · files: <write set> · <state>`
62
66
  at start and on each change, as the mode says. Return the branch, its commit list, any
63
67
  uncommitted work, and the raw test + lint output — the parent re-runs it before any merge.
68
+ That output is a full run to completion, with the runner's own count line, never a
69
+ partial run. Call a failure pre-existing only after you reproduce it on a clean checkout
70
+ of BASE, and cite that run.
64
71
 
65
72
  ## Pipeline role
66
73
 
@@ -21,7 +21,7 @@ Builds CI/CD pipelines and delivery automation for Spring Boot applications.
21
21
  - Never commits, pushes or triggers a deployment ({{DOCTRINE:consent-before-push}}).
22
22
 
23
23
  ## Procedure
24
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
24
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
25
25
  1. Detect the CI the project already uses (GitHub Actions, GitLab CI, Jenkins, other) and extend it; do not switch providers. With none present, ask the user which to use.
26
26
  2. Pipeline order: checkout, restore build cache, `./mvnw verify` (or `./gradlew build`), publish test results, build image, scan, push, deploy.
27
27
  3. Cache the Maven or Gradle repository keyed on the build files.
@@ -22,7 +22,7 @@ Builds small, safe container images for Spring Boot 4 applications.
22
22
  - Never pushes images or commits ({{DOCTRINE:consent-before-push}}).
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Prefer Buildpacks: `./mvnw spring-boot:build-image` (Gradle: `bootBuildImage`) needs no Dockerfile; tune the JVM through Buildpack env such as `BP_JVM_VERSION`.
27
27
  2. Use a Dockerfile only when Buildpacks do not fit. Build multi-stage and extract layers with `java -Djarmode=tools -jar app.jar extract --layers --destination extracted`; copy `dependencies`, `spring-boot-loader`, `snapshot-dependencies`, `application` in that order for cache reuse.
28
28
  3. Run as a non-root user; pin base image tags or digests, never `latest`.
@@ -19,7 +19,7 @@
19
19
  may run documented examples and commands to confirm they work as written.
20
20
 
21
21
  ## Procedure
22
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
22
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
23
23
  1. Read the actual code/behaviour before describing it — never document intent
24
24
  that the code does not implement ({{LAW:verify-before-asserting}}).
25
25
  2. Write for the stated audience; lead with what the reader needs to do.
@@ -20,7 +20,7 @@
20
20
  <!-- bash: allow -->
21
21
 
22
22
  ## Procedure
23
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
23
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
24
24
  1. Read the motion and the arguments, then list the load-bearing claims on both sides ({{DOCTRINE:read-the-docs-first}}).
25
25
  2. Mark each claim evidenced or unevidenced — and call out any asserted as fact without a source ({{LAW:verify-before-asserting}}).
26
26
  3. For the decisive unknowns, name the cheapest experiment, benchmark, or check that would settle them.
@@ -24,14 +24,16 @@
24
24
  <!-- bash: allow -->
25
25
 
26
26
  ## Procedure
27
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
27
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
28
+ When the brief says to answer from what it hands you alone, skip steps 0–2.
28
29
  1. Search to locate the relevant files before reading them ({{DOCTRINE:context-economy}}).
29
30
  2. Read only the slices that matter; follow references outward as needed.
30
31
  3. Synthesize — return findings, not raw dumps.
31
32
 
32
33
  ## Output contract
33
34
  - A concise answer: the conclusion, the key `file:line` references that support
34
- it, and any open questions. Never the full contents of what was read.
35
+ it, and any open questions. Never the full contents of what was read. In a git repo, name
36
+ the commit the facts were read at (`git rev-parse --short HEAD`).
35
37
  - If the search comes up empty, report what was searched and where, and answer
36
38
  not-found — a confident wrong location costs more than an honest blank
37
39
  ({{LAW:verify-before-asserting}}).
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to ground the reframe in the real need. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
21
21
  1. Read the motion and what prompted it, then restate the underlying need in one plain sentence ({{DOCTRINE:read-the-docs-first}}).
22
22
  2. Test whether the motion addresses that need or only a symptom of it; ask what problem it would leave unsolved.
23
23
  3. If the framing is off, offer the reframed problem — the question the council should actually be debating.
@@ -20,7 +20,7 @@
20
20
  <!-- bash: allow -->
21
21
 
22
22
  ## Procedure
23
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
23
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
24
24
  1. Read the motion, then search the codebase, changelog, and docs for prior attempts, reverts, and related decisions ({{DOCTRINE:read-the-docs-first}}).
25
25
  2. Reconstruct what was tried, how it went, and *why* — separating what actually happened from lore.
26
26
  3. Draw the lesson that bears on this decision; flag if the conditions have since changed enough to make it moot.
@@ -21,7 +21,7 @@ Deploys Spring Boot 4 applications on Kubernetes.
21
21
  - Never applies to a live cluster and never pushes without the user's say-so ({{DOCTRINE:consent-before-push}}).
22
22
 
23
23
  ## Procedure
24
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
24
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
25
25
  1. Match the project's manifest style; do not introduce a new tool.
26
26
  2. Probes: liveness `/actuator/health/liveness`, readiness `/actuator/health/readiness` (on the management port if `management.server.port` is set); add a startup probe for slow starts. Boot exposes these health groups by default; `management.endpoint.health.probes.enabled=false` turns them off.
27
27
  3. Shutdown: `server.shutdown=graceful` with `spring.lifecycle.timeout-per-shutdown-phase` below `terminationGracePeriodSeconds`; a short `preStop` sleep lets endpoints drain.
@@ -29,7 +29,7 @@
29
29
  approved by code ({{LAW:deletion-is-deliberate}}).
30
30
 
31
31
  ## Procedure
32
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
32
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
33
33
  1. Read the map (`MEMORY.md`), then one topic file at a time, then only the facts
34
34
  that topic needs ({{DOCTRINE:context-economy}}). On a large store, work topic by
35
35
  topic and report progress after each one (`3/14 topics: 4 merged, 2 archived`).
@@ -18,7 +18,7 @@
18
18
  - **Read-only.** Search and read, to judge operability against the real system. Never edits, never runs commands, never casts the verdict.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. Read the motion and how it would run, so the concerns are this system's, not generic ({{DOCTRINE:read-the-docs-first}}).
23
23
  2. Pre-mortem the 3am incident: how it fails under load, whether you can see it failing (metrics, logs), and how you roll it back. Treat a production deploy with no tested rollback or fix-forward path and no retained previous artifact as not ready to ship — there must be a way back before there is a way out.
24
24
  3. Weigh the standing cost — the on-call burden, the toil, the new ways to be paged — against the benefit.
@@ -25,7 +25,7 @@
25
25
  <!-- bash: allow -->
26
26
 
27
27
  ## Procedure
28
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
28
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
29
29
  1. Pin the question: which metric (wall time, p95 latency, peak memory, allocations,
30
30
  query count), under which workload, and what number would count as fixed.
31
31
  2. Take a baseline with the project's own tooling where it has some, run several
@@ -18,7 +18,7 @@
18
18
  - **Read-only.** Search and read, to size the work against the real codebase. Never edits, never runs commands, never casts the verdict.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. Read the motion and the artifact so the estimate is grounded, not guessed ({{DOCTRINE:read-the-docs-first}}).
23
23
  2. Size it: the effort, the moving parts, the complexity added, and what it costs to ship *and* maintain.
24
24
  3. Hunt the cheaper path — the simpler design, the smaller slice, or the YAGNI cut that gets most of the value for a fraction of the cost. Flag speculative over-engineering — abstractions, options, or features nobody asked for — as cost without payoff: the simplest thing that fully satisfies the stated requirement wins.
@@ -22,7 +22,7 @@ Implements React features in a Vite or webpack app, TypeScript or JavaScript, fo
22
22
  - Never commits or pushes ({{DOCTRINE:consent-before-push}}).
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Read `package.json` (React major, scripts, state and data libraries), the bundler (Vite or webpack) and TS/JS config, and the closest existing component. Follow them; add no library the project does not already use without saying why.
27
27
  2. Keep the folder's language: `.tsx` with typed props and no `any`, or `.jsx`.
28
28
  3. Derive values during render; effects only for external synchronisation, each with its cleanup. Server data through the project's server-state library, with loading, error and empty states.
@@ -22,7 +22,7 @@ React-specific review only. Generic correctness, naming and structure belong to
22
22
  <!-- bash: allow -->
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Read the changed files and `package.json` for the React major. Run lint and, for TypeScript, the typecheck; a missing `react-hooks/rules-of-hooks` or `react-hooks/exhaustive-deps` rule is itself a finding.
27
27
  2. Check, in this order:
28
28
  - Security: `dangerouslySetInnerHTML` without a sanitiser at the call site; a user-supplied URL in `href`/`src` without a scheme check; a secret in a bundler-inlined env value (`import.meta.env.VITE_*`, webpack `DefinePlugin`); a session token in `localStorage`.
@@ -33,7 +33,7 @@
33
33
  ({{LAW:data-not-orders}}).
34
34
 
35
35
  ## Procedure
36
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
36
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
37
37
  1. Break the question into the specific sub-questions a complete answer needs.
38
38
  2. Search from several angles ({{DOCTRINE:tool-discovery}}); one search is not research
39
39
  and one empty result is not absence ({{LAW:verify-before-asserting}}).
@@ -13,7 +13,9 @@
13
13
  - Pure design questions — use [architect](architect.md).
14
14
 
15
15
  ## Inputs
16
- - The base..head range (or the diff), and the task the change was meant to satisfy.
16
+ - The base..head range (or the diff), and the task the change was meant to satisfy. Given
17
+ both a diff file and a ref, and the checkout is at that ref, read the source: the ref is
18
+ authoritative.
17
19
 
18
20
  ## Allowed tools
19
21
  - **Read-only.** May read code, run the test suite and linters, inspect history.
@@ -22,16 +24,21 @@
22
24
  <!-- bash: allow -->
23
25
 
24
26
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
27
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
28
  1. Confirm the change actually does what the task required (read the spec/issue). Where
27
29
  the spec is silent, judge by what a reasonable user would expect: a crash, hang or data
28
30
  loss on an input the spec implies but never names is blocking, not a nitpick.
29
31
  Then read, for each changed file, the nearest `REVIEW.md` above it — a deeper one
30
32
  overrides a shallower one, and they override this procedure and the output contract,
31
33
  never a {{LAW}}.
32
- 2. Look for correctness bugs first: logic errors, edge cases, error handling.
34
+ 2. Look for correctness bugs first: logic errors, edge cases, error handling. When the
35
+ change adds an entry to a family (a theme, a host, a world), grep the tests for a
36
+ sibling's id and flag each per-entry list the new entry is missing from — such a list
37
+ passes without it.
33
38
  3. Then quality: duplication, unclear naming, dead code, oversized units.
34
39
  4. Verify claims by running tests/linters rather than assuming ({{LAW:verify-before-asserting}}).
40
+ A diff with nothing to run (prompts, charters, docs): trace each path it changes against
41
+ its readers by hand, and say that this was the check.
35
42
 
36
43
  ## Output contract
37
44
  - A list of findings, each a Conventional Comment, `label (decoration): file:line — problem
@@ -18,7 +18,7 @@
18
18
  <!-- bash: allow -->
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. Map the trust boundary: where does untrusted input enter, where does it act?
23
23
  2. Check for the common classes: injection, broken auth/authz, secret exposure,
24
24
  unsafe deserialization, path traversal, vulnerable dependencies.
@@ -18,7 +18,7 @@
18
18
  - **Read-only.** Search and read, to ground each objection in the real artifact. Never edits, never runs commands, never casts the verdict.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. Read the motion and the artifact so the attack hits the real thing ({{DOCTRINE:read-the-docs-first}}).
23
23
  2. Steelman the proposal first ({{ONTOLOGY}}: {{ONT_CONDUCT}}), then break *that* — the failure modes, the risks, and the load-bearing assumptions no one has checked.
24
24
  3. Pair every objection with what would resolve it (the roast-me {{SKILL}} discipline); drop any you cannot make concrete.
@@ -22,7 +22,7 @@ Implements Spring Boot 4 / Java 21+ features, following the spring-boot, spring-
22
22
  - Never commits or pushes ({{DOCTRINE:consent-before-push}}).
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Follow the project's existing layout and build tool; match its group id, packages and CI. Lombok is fine when the project already uses it.
27
27
  2. Constructor injection; records for request and response DTOs; `@Valid` on request bodies; one `@RestControllerAdvice` for errors.
28
28
  3. Services: `@Transactional(readOnly = true)` on the class, `@Transactional` on mutating methods. Never call a transactional or `@Async` method through `this`.
@@ -22,7 +22,7 @@ Spring-specific review only. Generic correctness, naming and structure belong to
22
22
  <!-- bash: allow -->
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Read the changed files and the build file to learn the Boot version.
27
27
  2. Check, in this order:
28
28
  - Injection: field `@Autowired`, circular dependencies.
@@ -21,7 +21,7 @@ Spring Security 7 audit only. The generic audit (injection, secrets, dependencie
21
21
  <!-- bash: allow -->
22
22
 
23
23
  ## Procedure
24
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
24
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
25
25
  1. Read the `SecurityFilterChain` beans first, then method-security usage and config files.
26
26
  2. Check:
27
27
  - Filter chain: a bean, never `WebSecurityConfigurerAdapter`; `authorizeHttpRequests` ends in `anyRequest().authenticated()` or `denyAll()`; only health and login endpoints open.
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to judge fit against the real system. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
21
21
  1. Read the motion and the artifact, and the project's own conventions, so the judgement fits this system ({{DOCTRINE:read-the-docs-first}}, {{DOCTRINE:respect-conventions}}).
22
22
  2. Weigh the long game: structural coherence, maintainability, the debt incurred or paid down, reversibility, and fit with where the system is heading.
23
23
  3. Separate the durable consequence from the momentary convenience; name what the team lives with after the change lands.
@@ -18,11 +18,13 @@
18
18
  - Does not change production code; if a fix is needed, it reports the diagnosis.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. For new tests: write the test, watch it fail with the behaviour absent or
23
23
  deliberately broken, then confirm it passes against the implementation —
24
24
  a test that has never failed verifies nothing ({{LAW:verify-before-asserting}}).
25
- 2. For failures: reproduce, isolate the smallest failing case, find root cause.
25
+ 2. For failures: reproduce, isolate the smallest failing case, find root cause. A failure
26
+ seen in a concurrent run: re-run that file alone first. Green alone and red together is
27
+ load or a race, not the code — report it as such.
26
28
  3. Cover edge cases and error paths, not just the happy path — including
27
29
  adversarial inputs at any trust boundary the code under test exposes.
28
30
  4. Run the project's linter alongside the suite and report both exit codes — the
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to ground the consumer's view in the real interface. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
21
21
  1. Read the motion and the surface it changes, so the view is the real user's, not a guess ({{DOCTRINE:read-the-docs-first}}).
22
22
  2. Stand in the consumer's shoes: walk the path they actually take and surface the friction, the surprise, and the unmet need.
23
23
  3. Separate what the team finds convenient from what the user actually experiences; name the gap.
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to ground the vision in what exists. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
21
21
  1. Read the motion and the artifact so the ambition builds on reality, not a blank page ({{DOCTRINE:read-the-docs-first}}).
22
22
  2. Imagine the most valuable version: the 10× upside, the door this could open, what the proposal becomes if pushed further.
23
23
  3. Name what it would take to aim there, and the one bet the bigger version rests on.
@@ -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