geneseed 5.0.0 → 5.0.3

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 (138) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/README.md +1 -1
  3. package/SHIPPED.md +1 -1
  4. package/adapters/claude-code/README.md +6 -4
  5. package/adapters/opencode/HOW-OPENCODE-LOADS.md +3 -0
  6. package/adapters/opencode/plugins/geneseed-context.js +13 -2
  7. package/adapters/opencode/plugins/geneseed-guard.js +595 -74
  8. package/adapters/opencode/plugins/geneseed-learn.js +1 -1
  9. package/bin/geneseed-hook.mjs +21 -7
  10. package/docs/PRD.md +1 -1
  11. package/docs/concepts/enforcement-table.md +22 -3
  12. package/docs/concepts/exclusions.md +48 -2
  13. package/docs/concepts/foreman-mode.md +19 -4
  14. package/docs/concepts/hook-gates.md +1 -1
  15. package/docs/concepts/hooks.md +53 -12
  16. package/docs/concepts/host-matrix.md +4 -3
  17. package/docs/concepts/hosts.md +1 -1
  18. package/docs/concepts/kits.md +18 -0
  19. package/docs/concepts/shared-tier.md +5 -5
  20. package/docs/concepts/skills.md +1 -1
  21. package/docs/extending.md +3 -1
  22. package/docs/guides/autostart.md +27 -3
  23. package/docs/guides/choose-your-setup.md +1 -1
  24. package/docs/guides/migrate.md +5 -3
  25. package/docs/guides/uninstall.md +1 -1
  26. package/docs/guides/upgrade-to-5.md +6 -4
  27. package/docs/reference/plugin-context.md +1 -1
  28. package/docs/reference/plugin-guard.md +24 -5
  29. package/docs/reference/troubleshoot-doctor.md +2 -2
  30. package/docs/understand/a-day.md +9 -5
  31. package/docs/web-ui.md +78 -20
  32. package/harness.config.json +1 -1
  33. package/js/README.md +3 -2
  34. package/js/build/emit-claude.mjs +9 -1
  35. package/js/build/emit-opencode.mjs +2 -1
  36. package/js/build/fold.mjs +7 -7
  37. package/js/build/rule-decide.mjs +273 -0
  38. package/js/build/source.mjs +9 -3
  39. package/js/cli-table.json +122 -2
  40. package/js/hosts/geneseed-dir.mjs +1 -1
  41. package/js/hosts/hooks-context.mjs +9 -7
  42. package/js/hosts/hooks-done.mjs +3 -1
  43. package/js/hosts/hooks-learn.mjs +1 -1
  44. package/js/hosts/hooks-prims.mjs +270 -0
  45. package/js/hosts/hooks.mjs +409 -151
  46. package/js/hosts/hosts.mjs +22 -0
  47. package/js/hosts/installs.mjs +13 -9
  48. package/js/hosts/memory-files.mjs +2 -2
  49. package/js/hosts/settings.mjs +123 -23
  50. package/js/hosts/shim.mjs +155 -7
  51. package/js/hosts/store-watch.mjs +41 -14
  52. package/js/inspect/diff.mjs +2 -1
  53. package/js/inspect/inventory.mjs +1 -0
  54. package/js/inspect/registry.mjs +4 -2
  55. package/js/inspect/validate.mjs +1 -1
  56. package/js/lib/paths.mjs +13 -0
  57. package/js/maintain/migrate.mjs +60 -22
  58. package/js/maintain/uninstall.mjs +5 -1
  59. package/js/web/actions.mjs +17 -1
  60. package/js/web/api.mjs +22 -16
  61. package/js/web/handler.mjs +2 -0
  62. package/js/web/routes.mjs +9 -4
  63. package/js/web/update-check.mjs +2 -2
  64. package/js/web/user-files.mjs +38 -11
  65. package/package.json +1 -1
  66. package/registry.json +21 -0
  67. package/src/AGENT.md.tmpl +17 -21
  68. package/src/agents/_self-improvement.md +7 -6
  69. package/src/agents/developer.md +3 -2
  70. package/src/agents/docker-expert.md +1 -0
  71. package/src/agents/memory-curator.md +3 -2
  72. package/src/doctrines/process.md +24 -19
  73. package/src/kits/ci-pipelines/rules.md +10 -0
  74. package/src/kits/ci-pipelines.json +14 -0
  75. package/src/kits/docker/rules.md +11 -0
  76. package/src/kits/docker.json +12 -0
  77. package/src/memory/README.md +5 -4
  78. package/src/modes/foreman.md +23 -10
  79. package/src/notebook/README.md +1 -1
  80. package/src/skills/_self-improvement.md +12 -9
  81. package/src/skills/compose-ops.md +58 -0
  82. package/src/skills/gitlab-ci.md +51 -0
  83. package/src/skills/jenkins-pipeline.md +56 -0
  84. package/src/skills/pipeline.md +2 -2
  85. package/src/skills/rule/approve.md +11 -5
  86. package/src/skills/rule.md +26 -19
  87. package/src/skills/skill-forge.md +24 -6
  88. package/themes/_TEMPLATE.json +5 -2
  89. package/themes/biker.json +5 -2
  90. package/themes/commentator.json +5 -2
  91. package/themes/cyberpunk.json +5 -2
  92. package/themes/gamer.json +5 -2
  93. package/themes/imperial.json +5 -2
  94. package/themes/joker.json +5 -2
  95. package/themes/marvin.json +5 -2
  96. package/themes/mean.json +5 -2
  97. package/themes/military.json +5 -2
  98. package/themes/neutral.json +5 -2
  99. package/themes/pirate.json +5 -2
  100. package/themes/sports.json +5 -2
  101. package/themes/verstappen.json +5 -2
  102. package/themes/wizard.json +5 -2
  103. package/web/dist/assets/Activity-Ck_Xffpo.js +1 -0
  104. package/web/dist/assets/ActivityDetail-CBxVS4mU.js +1 -0
  105. package/web/dist/assets/{Bonsai-B_y20b3i.js → Bonsai-BlOwsvW6.js} +1 -1
  106. package/web/dist/assets/{CopyButton-CHQte7Ap.js → CopyButton-DFMOIGbe.js} +1 -1
  107. package/web/dist/assets/Dashboard-BUdUTjbB.js +2 -0
  108. package/web/dist/assets/{Docs-Dgv_MWfT.js → Docs-D_2Jt6gU.js} +3 -3
  109. package/web/dist/assets/{GreenhouseView-CSzTMSl_.js → GreenhouseView-WalcX5bp.js} +1 -1
  110. package/web/dist/assets/Installs-UGiPDMDt.js +3 -0
  111. package/web/dist/assets/{JournalView-CvRk1-m5.js → JournalView-CZtXQz-v.js} +1 -1
  112. package/web/dist/assets/Kits-XQHsazCN.js +1 -0
  113. package/web/dist/assets/Laws-B6A55S-2.js +4 -0
  114. package/web/dist/assets/Library-D7L0Wdbh.js +3 -0
  115. package/web/dist/assets/Loops-C0loS73u.js +2 -0
  116. package/web/dist/assets/{OperatorHudView-DuGz_sTk.js → OperatorHudView-CeDw5qMB.js} +1 -1
  117. package/web/dist/assets/Personal-PVmGA2-M.js +2 -0
  118. package/web/dist/assets/{RailCats-AW92uhsX.js → RailCats-BGZnJ6fa.js} +1 -1
  119. package/web/dist/assets/Settings-DWuxwh4i.js +1 -0
  120. package/web/dist/assets/Tabs-d2RIRAKT.js +1 -0
  121. package/web/dist/assets/api-BMFDSXoB.js +1 -0
  122. package/web/dist/assets/index-BEI5ugYQ.css +1 -0
  123. package/web/dist/assets/index-BNttaGQb.js +6 -0
  124. package/web/dist/index.html +3 -3
  125. package/web/dist/assets/Activity-D8G4eClY.js +0 -1
  126. package/web/dist/assets/ActivityDetail-BtOBYk3M.js +0 -1
  127. package/web/dist/assets/Dashboard-B8uXeJZ_.js +0 -2
  128. package/web/dist/assets/Installs-BDk9lqBI.js +0 -3
  129. package/web/dist/assets/Kits-CoITzxWM.js +0 -1
  130. package/web/dist/assets/Laws-Ctf5r9rE.js +0 -3
  131. package/web/dist/assets/Library-DNwHYVXt.js +0 -3
  132. package/web/dist/assets/Loops-S85PMQ8m.js +0 -2
  133. package/web/dist/assets/Personal-afJNwvRS.js +0 -2
  134. package/web/dist/assets/Settings-CGDFz-6j.js +0 -1
  135. package/web/dist/assets/Tabs-1qLrnqmn.js +0 -1
  136. package/web/dist/assets/api-C46vAuqp.js +0 -1
  137. package/web/dist/assets/index-COTd4TRZ.js +0 -3
  138. package/web/dist/assets/index-CtorA7uK.css +0 -1
@@ -10,10 +10,11 @@
10
10
  import { createHash } from 'node:crypto';
11
11
  import path from 'node:path';
12
12
 
13
+ import { RETIRED_RULES_FILE, decideItem, decisionState, draftItems, CHOICE_DECISIONS, RULE_DECISIONS } from '../build/rule-decide.mjs';
13
14
  import { PROFILE_STUB } from '../build/stubs.mjs';
14
15
  import { readMaybe } from '../hosts/installs.mjs';
15
16
  import { splitLines } from '../hosts/hooks-prims.mjs';
16
- import { frontmatter, isRuleEdge, parseDraft, parseRules, readFoldState } from '../hosts/memory-files.mjs';
17
+ import { frontmatter, isRuleEdge, parseRules, readFoldState } from '../hosts/memory-files.mjs';
17
18
  import { writeText, isFile, isDir } from '../lib/fs.mjs';
18
19
  import { formatRepr, isTruthy } from '../lib/json.mjs';
19
20
  import { WHITESPACE, codePointLength, stripWhitespace } from '../lib/text.mjs';
@@ -64,22 +65,30 @@ const userDir = (state, tier = tierOf(state)) => tier?.root ?? state.target;
64
65
  const rulesPath = (state, tier) => path.join(userDir(state, tier), RULES_FILE);
65
66
 
66
67
  /**
67
- * The blocks the fold left in `<tier>/user-rules.draft.md`, as `{title, host, body}`, in file
68
- * order (`parseDraft` reads the format). The console only SHOWS them: the rule Rite is the only
69
- * draft writer (C15), so no verb here decides one. A block the ledger already holds as decided is
70
- * left over from a stopped Rite write, so it is not pending; a block with no row, or a ledger that
71
- * does not parse, still shows. Empty for a project install and for a missing draft.
68
+ * The blocks the fold left in `<tier>/user-rules.draft.md`, in file order (`draftItems`). A block
69
+ * the ledger already holds as decided is left over from a stopped write, so it is not pending; a
70
+ * block with no row, or a ledger that does not parse, still shows. Empty for a project install and
71
+ * for a missing draft. `apiRulesDecide` below decides one.
72
72
  */
73
73
  function ruleDrafts(tier) {
74
74
  if (tier === null) return [];
75
75
  let ledger = {};
76
76
  try { ledger = readFoldState(tier).items; } catch { /* shows all */ }
77
77
  const decided = ({ key }) => {
78
- const row = ledger[key];
78
+ const row = Object.hasOwn(ledger, key ?? '') ? ledger[key] : null;
79
79
  return row != null && row.state !== 'pending';
80
80
  };
81
- return parseDraft(readMaybe(tier.draft) ?? '').filter((d) => !decided(d))
82
- .map(({ title, host, body }) => ({ title, host, body }));
81
+ // A bad draft is one row on the page, never a failed page: the rules below it still edit.
82
+ try {
83
+ return draftItems(tier).filter((d) => !decided(d));
84
+ } catch (e) {
85
+ return [{ title: 'The draft could not be read', host: null, body: String(e?.message ?? e), decisions: [] }];
86
+ }
87
+ }
88
+
89
+ /** The fingerprint a decision must send back: `''` where there is no tier, or no draft to read. */
90
+ function draftFingerprint(tier) {
91
+ try { return tier === null ? '' : fingerprint(decisionState(tier)); } catch { return ''; }
83
92
  }
84
93
 
85
94
  /**
@@ -95,7 +104,7 @@ export function apiRules(state) {
95
104
  const drafts = ruleDrafts(tier);
96
105
  if (!isFile(p)) {
97
106
  return { exists: false, path: p, rules: [], warnings: [], fingerprint: '', shared, drafts,
98
- stats: { rules: 0, lines: 0, tokens: 0 } };
107
+ draft_fingerprint: draftFingerprint(tier), stats: { rules: 0, lines: 0, tokens: 0 } };
99
108
  }
100
109
  const text = readMaybe(p) ?? '';
101
110
  const [rules, warnings] = parseRules(text);
@@ -111,6 +120,7 @@ export function apiRules(state) {
111
120
  tokens: tokensOf(stripWhitespace(lines.slice(r.start, r.end).join('\n'))),
112
121
  }));
113
122
  return { exists: true, path: p, rules: out, warnings, fingerprint: fingerprint(text), shared, drafts,
123
+ draft_fingerprint: draftFingerprint(tier),
114
124
  // The whole file, so it holds its header too: more than the rules' own tokens added up.
115
125
  stats: { rules: rules.length, lines: lines.length, tokens: tokensOf(text) } };
116
126
  }
@@ -186,7 +196,6 @@ function ruleId(v) {
186
196
  * mistake; it exists so a retire never loses the text. Like user-rules.md it is the user's: no
187
197
  * install manifest claims it, so no uninstall deletes it.
188
198
  */
189
- const RETIRED_RULES_FILE = 'user-rules-retired.md';
190
199
  const RETIRED_HEADER = '# Retired rules — not in force, never loaded into any session.\n';
191
200
  const isBlank = (line) => !stripWhitespace(line);
192
201
 
@@ -254,6 +263,24 @@ export function apiRulesMutate(state, body) {
254
263
  return { ok: true, op, id: rid, fingerprint: fingerprint(next) };
255
264
  }
256
265
 
266
+ /**
267
+ * One decision on a drafted item (`decideItem`). The fingerprint covers the draft, the shared rules
268
+ * and both files of each `Choose` block, so a click on what the page showed never lands on what an
269
+ * agent session or a fold wrote since: `ok: false`, 409, and the page reloads.
270
+ */
271
+ export function apiRulesDecide(state, body) {
272
+ const decision = bget(body, 'decision');
273
+ if (![...RULE_DECISIONS, ...CHOICE_DECISIONS].includes(decision)) {
274
+ throw new BadRequest(`unknown decision ${formatRepr(decision)}`);
275
+ }
276
+ const tier = tierOf(state);
277
+ if (tier === null) throw new NotFound('shared tier');
278
+ if (!fpMatches(bget(body, 'fingerprint', ''), draftFingerprint(tier))) {
279
+ return { ok: false, error: 'conflict', detail: 'The draft changed since you loaded it.' };
280
+ }
281
+ return decideItem(tier, strOr(bget(body, 'key')), decision);
282
+ }
283
+
257
284
  /**
258
285
  * One memory fact promoted into a trial rule. The provenance line and the month of
259
286
  * probation are the rule this endpoint owns, and both are DATES read from the real clock —
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin`, `exports` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
3
3
  "name": "geneseed",
4
- "version": "5.0.0",
4
+ "version": "5.0.3",
5
5
  "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
6
6
  "keywords": [
7
7
  "ai",
package/registry.json CHANGED
@@ -574,6 +574,27 @@
574
574
  "owner": "Guillaume Lemer",
575
575
  "added": "2026-09-06",
576
576
  "last_verified": "2026-10-13"
577
+ },
578
+ "skills/compose-ops": {
579
+ "status": "experimental",
580
+ "version": "1.0.0",
581
+ "owner": "Guillaume Lemer",
582
+ "added": "2026-11-08",
583
+ "last_verified": ""
584
+ },
585
+ "skills/gitlab-ci": {
586
+ "status": "experimental",
587
+ "version": "1.0.0",
588
+ "owner": "Guillaume Lemer",
589
+ "added": "2026-11-08",
590
+ "last_verified": ""
591
+ },
592
+ "skills/jenkins-pipeline": {
593
+ "status": "experimental",
594
+ "version": "1.0.0",
595
+ "owner": "Guillaume Lemer",
596
+ "added": "2026-11-08",
597
+ "last_verified": ""
577
598
  }
578
599
  }
579
600
  }
package/src/AGENT.md.tmpl CHANGED
@@ -189,19 +189,16 @@ contract you do not already know.
189
189
  <!-- CATALOG:end -->
190
190
 
191
191
  **Rule of delegation:** read-only investigation can be dispatched freely; any
192
- {{AGENT}} that *writes* must return a summary of exactly what it changed. Every
193
- {{AGENT}} spec ends with a **self-improvement loop**: when a report carries a
194
- `spec-feedback:` line, weigh it — record a real flaw (with the user's assent) in
195
- `{{PATH_NOTES}}/agent-notes/<name>.md` and pass it to later dispatches;
196
- {{MEMORY}} gets a record only when it clears {{DOCTRINE:persist-insight}}'s bar.
192
+ {{AGENT}} that *writes* must return a summary of exactly what it changed. Weigh any
193
+ `spec-feedback:` line an {{AGENT}}'s report carries, as its spec's self-improvement loop says.
197
194
 
198
195
  <!-- LEAN:begin -->
199
196
  **Dispatching a multi-part goal.** When a goal spans several capabilities,
200
197
  decompose it into independent subtasks, route each to the single owning {{AGENT}}
201
198
  above, and converge the results yourself. Every handoff carries an **envelope** —
202
199
  the subtask goal, the inputs the {{AGENT}} needs, and its output contract — and the
203
- constraints travel with it: dispatched {{AGENTS}} never commit or push ({{DOCTRINE:consent-before-push}}
204
- stays with you), and an unfulfilled contract returns as a stated gap, never invented
200
+ constraints travel with it: dispatched {{AGENTS}} never push, and commit only in their own
201
+ worktree ({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented
205
202
  content. Where the host exposes a `workflow` tool, prefer the saved `dispatch`
206
203
  workflow ([workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md)); where it does not, run
207
204
  the same shape model-driven via the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md).
@@ -212,8 +209,8 @@ Ten of them — `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`,
212
209
  dispatched alone; the [council {{SKILL}}]({{DIR_SKILLS}}/council.md) convenes the
213
210
  subset that productively clashes on a given motion.
214
211
  <!-- LEAN:else -->
215
- Dispatched {{AGENTS}} never commit or push ({{DOCTRINE:consent-before-push}} stays with
216
- you), and an unfulfilled contract returns as a stated gap, never invented content. A
212
+ Dispatched {{AGENTS}} commit only in their worktree, never push
213
+ ({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented content. A
217
214
  multi-part goal goes through the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md)
218
215
  (or the [workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md) where the host has a workflow tool);
219
216
  the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/council.md).
@@ -311,8 +308,8 @@ the file, or to {{MEMORY}} ({{DOCTRINE:persist-insight}}).
311
308
  Persistent facts live in {{LINK_MEMORY}} — one fact per file, indexed by a
312
309
  local `MEMORY.md`, a session file (**Session start**, above); write a new memory
313
310
  whenever the conversation yields a durable fact, a correction, or a decision worth
314
- keeping — through the [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}, which settles with
315
- the user whether it is a memory or a standing rule before either is written
311
+ keeping — on your own; the user sees each memory later in the web console. A standing
312
+ rule goes to the user, through the [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}
316
313
  ({{DOCTRINE:persist-insight}}). The `{{PATH_MEMORY}}/` directory is **personal and git-ignored** — it is
317
314
  never committed or shared; to share knowledge, put it in code, docs, or the
318
315
  project's `user-rules.md` (§1). When the same feedback lesson keeps recurring,
@@ -325,9 +322,9 @@ the session — memory, notebook, notes, commits, docs — cite a rule by its pr
325
322
  ("Verify Before Asserting"), never its number: numbers are positional. Full convention: [`{{DIR_MEMORY}}/README.md`]({{DIR_MEMORY}}/README.md).
326
323
  <!-- LEAN:else -->
327
324
  Durable facts live in {{LINK_MEMORY}}, one per file, indexed by
328
- `MEMORY.md`, a session file. Write one through the
329
- [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}, which settles with the user whether a
330
- lesson is a memory or a standing rule ({{DOCTRINE:persist-insight}}). The directory is
325
+ `MEMORY.md`, a session file. Write one on your own; the user sees it in the web
326
+ console. A standing rule goes through the
327
+ [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}} ({{DOCTRINE:persist-insight}}). The directory is
331
328
  **personal and git-ignored**; shared knowledge goes in code, docs, or `user-rules.md`
332
329
  (§1). In anything that outlives the session, cite a rule by its principle ("Verify Before
333
330
  Asserting"), never its number — numbers change. Convention, incl. `force`:
@@ -355,8 +352,8 @@ own benefit — a scratch script, an analysis dump, a draft, an experiment, a
355
352
  tool you build for yourself — belongs in `{{DIR_NOTEBOOK}}/`, never in the host
356
353
  tree. `NOTEBOOK.md`, a session file, recalls what you keep here; keep the space referable across sessions — the seeded index
357
354
  is one way; replace it with whatever scheme serves you better. When a note
358
- hardens into a durable fact worth recalling verbatim, propose it for {{MEMORY}}
359
- through the rule {{SKILL}} (§5, {{DOCTRINE:persist-insight}}). Keep the two stores distinct by *role*, not just by
355
+ hardens into a durable fact worth recalling verbatim, write it to {{MEMORY}}
356
+ (§5, {{DOCTRINE:persist-insight}}). Keep the two stores distinct by *role*, not just by
360
357
  format: {{MEMORY}} holds durable insight for future sessions, the {{NOTEBOOK}}
361
358
  holds your working artifacts. The one fixed law: `{{DIR_NOTEBOOK}}/` is **personal and
362
359
  git-ignored** — never committed or shared, and the `.gitignore` that guarantees
@@ -365,8 +362,7 @@ it is not yours to lift.
365
362
  Your own working space, [`{{DIR_NOTEBOOK}}/`]({{DIR_NOTEBOOK}}/): any file you make
366
363
  for your own benefit — scratch code, drafts, datasets, experiments — goes here, never
367
364
  in the host tree, in whatever format serves; its index `NOTEBOOK.md` is a session
368
- file. A note that hardens into a durable fact is proposed for {{MEMORY}} through
369
- the rule {{SKILL}} (§5).
365
+ file. A note that hardens into a durable fact goes to {{MEMORY}} (§5).
370
366
  The charter [`{{DIR_NOTEBOOK}}/README.md`]({{DIR_NOTEBOOK}}/README.md) is yours to
371
367
  rewrite; the one fixed law is that the folder is **personal and git-ignored**, and
372
368
  that `.gitignore` is not yours to lift.
@@ -385,8 +381,8 @@ configs, documents, prior work. All of it is context you may use.
385
381
 
386
382
  After reading this file, take stock of what surrounds it. That non-harness
387
383
  content is knowledge to **read and learn from**, not scaffolding to reorganise.
388
- When you find a durable fact there worth keeping, propose it for {{MEMORY}} through
389
- the rule {{SKILL}} (§5) so it outlives the session.
384
+ When you find a durable fact there worth keeping, write it to {{MEMORY}} (§5) so it
385
+ outlives the session.
390
386
 
391
387
  Because the folder is shared, two cautions hold:
392
388
  - **You do not own it.** Files you did not create are not yours to move, rename,
@@ -400,7 +396,7 @@ scratch scripts, analysis dumps, drafts, experiments — are made in the
400
396
  <!-- LEAN:else -->
401
397
  {{INTRO_WORKSPACE}} Whatever sits beside the harness files — notes, data, configs,
402
398
  prior work — is knowledge to read and learn from, not scaffolding to reorganise;
403
- propose a durable fact from it for {{MEMORY}} through the rule {{SKILL}} (§5). You do not own the folder: files
399
+ write a durable fact from it to {{MEMORY}} (§5). You do not own the folder: files
404
400
  you did not create are not yours to move or delete unless the task requires it
405
401
  ({{LAW:deletion-is-deliberate}}), and a file is verified before it is treated as disposable ({{LAW:verify-before-asserting}}).
406
402
  It receives only the task's deliverables; your working files go in the {{NOTEBOOK}}
@@ -2,10 +2,11 @@
2
2
 
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
- `spec-feedback: [agent|general] <the one-line fix> — seen: <what happened, against
6
- what this spec led you to expect>`. `general` marks a fix other {{AGENTS}} need too.
7
- Omit the line when there is no friction. The caller weighs the feedback and, with the
8
- user's assent, writes a real flaw, dated, into `{{PATH_NOTES}}/agent-notes/<name>.md`
9
- — never into this rendered file, which a rebuild overwrites — and hands those notes
10
- to every later dispatch of this {{AGENT}}. It records the feedback to {{MEMORY}} only if it clears
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
11
12
  {{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
@@ -25,8 +25,9 @@
25
25
  - **Read + write to the assigned worktree.** May run the project's own build/lint
26
26
  commands to self-check before handing off.
27
27
  <!-- bash: allow -->
28
- - Never commits or pushes ({{DOCTRINE:consent-before-push}}) — the parent re-runs the proof and
29
- commits once the user accepts.
28
+ - Never pushes ({{DOCTRINE:consent-before-push}}). It commits and merges only inside its own
29
+ worktree branch, from sub-workers it started; the parent re-runs the proof and merges
30
+ beyond it once the user accepts.
30
31
 
31
32
  ## Procedure
32
33
  0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
@@ -11,6 +11,7 @@ Builds small, safe container images for Spring Boot 4 applications.
11
11
 
12
12
  ## When NOT to dispatch
13
13
  - Cluster manifests — use [kubernetes-specialist](kubernetes-specialist.md). Pipelines — use [devops-engineer](devops-engineer.md).
14
+ - Operating a Compose stack (updates, rollback, limits, logs, networks) — the docker kit's `compose-ops` skill, when that kit is on.
14
15
 
15
16
  ## Inputs
16
17
  - The build tool (Maven or Gradle), the Java version and any registry or base-image policy.
@@ -20,8 +20,9 @@
20
20
 
21
21
  ## Allowed tools
22
22
  - **Read + write to the {{MEMORY}} store only.** May run `geneseed memory` and
23
- `geneseed learn --consolidate`. A write into the store may stop for the user's consent
24
- at the tool boundary, so it batches its edits per topic behind one plan.
23
+ `geneseed learn --consolidate`. A write into the store meets no prompt at the tool boundary
24
+ (memory is written freely), but bulk curation reworks facts the user already keeps, so it still
25
+ shows each topic's plan and applies it with the user's consent.
25
26
  <!-- bash: allow -->
26
27
  - Moves a fact out with `geneseed memory rm <name>`, which archives it — never a raw
27
28
  `mv` or `rm` past that gate. Deletes only with `--purge`, and only what the user
@@ -1,18 +1,20 @@
1
1
  **{{PACK_PROCESS}}** — how a task is run.
2
2
 
3
3
  ### {{DOCTRINE:persist-insight}} Persist Insight
4
- <!-- note: summary: Durable decisions are recorded before the session ends — and rule or memory is the user's call. -->
4
+ <!-- note: summary: Durable insight is recorded before the session ends — memory on your own, a standing rule only with the user. -->
5
5
  <!-- LEAN:begin -->
6
6
  When a session yields a durable decision, correction, non-obvious discovery, or
7
- architectural stance, record it before the session ends — through the rule {{SKILL}},
8
- which settles with the user whether it belongs in {{MEMORY}} or as a standing rule,
9
- never on your own initiative. No valuable insight perishes at session's end, and which
10
- store holds it is the user's call, never yours.
7
+ architectural stance, record it before the session ends. A durable fact goes into
8
+ {{MEMORY}} on your own, with no prompt: the user sees every memory later in the web
9
+ console. A standing rule binds every later session, so it is the user's call: take it to
10
+ them through the rule {{SKILL}}. A memory phrased as an instruction to later sessions
11
+ ("always…", "never…", `force: constraint`) is a standing rule.
11
12
  <!-- LEAN:else -->
12
13
  When a session yields a durable decision, correction, non-obvious discovery, or
13
- architectural stance, record it before it ends — through the rule {{SKILL}}, which settles
14
- with the user whether it belongs in {{MEMORY}} or a standing rule, never on your own
15
- initiative.
14
+ architectural stance, record it before it ends: a durable fact into {{MEMORY}} on your
15
+ own (the user sees it in the web console); a standing rule, which includes
16
+ any instruction to later sessions ("always…", "never…", `force: constraint`), only through
17
+ the rule {{SKILL}}, with the user's consent.
16
18
  <!-- LEAN:end -->
17
19
 
18
20
  ### {{DOCTRINE:plan-before-acting}} Plan Before Acting
@@ -92,9 +94,10 @@ stands for commits on that branch until the session ends or the scope changes; a
92
94
  new session, a new branch, or a widened scope re-asks. Push earns no such default
93
95
  and stays per-ask unless granted in the same named form. A launched loop's batch
94
96
  covers commit and push on its own `loop/*` branch; merging that branch into a
95
- shared one never is. Before each, present in
96
- order (1) a plain-language summary of what changed and why and (2) the exact
97
- commit message you intend to use, then wait. Never push on your own initiative.
97
+ shared one never is. A Foreman worker's batch covers commit and merge in its own
98
+ worktree, off any shared branch. Before each, present in order (1) a plain-language
99
+ summary of what changed and why and (2) the exact commit message you intend to use,
100
+ then wait. Never push on your own initiative.
98
101
  On a **shared branch** — `main`, `master`, `develop`, `development`, a
99
102
  `release`/`hotfix` branch, or anything that is not a dedicated feature branch —
100
103
  the same gate applies with extra care; when unsure, treat the branch as shared.
@@ -104,14 +107,16 @@ through the git-history {{SKILL}} behind a backup. The host gates commit and pus
104
107
  the tool boundary too, so this consent cannot be lost to a sticky allowlist.
105
108
  <!-- LEAN:else -->
106
109
  Recording and sharing code is consented, never unilateral: **every** `git commit` and
107
- `git push` needs **explicit acceptance**, every branch, every time; one-time approval is
108
- not standing consent. A named batch ("commit as you go") stands until the session ends or
109
- scope changes; push earns no default. A launched loop's batch covers commit and push on
110
- its own `loop/*` branch only; merging it never. Show the plain summary and the exact
111
- commit message before each, then wait. Shared branches — `main`, `master`, `develop`,
112
- `development`, `release`/`hotfix`, any unsure — take the same gate. Never force-push,
113
- hard-reset, or rebase one: undo with a revert commit (git-history {{SKILL}} for a
114
- legitimate rewrite). The host gates both at the tool boundary.
110
+ `git push` needs **explicit acceptance**, every branch, every time — a personal feature
111
+ branch included; one-time approval is not standing consent. A named batch ("commit as
112
+ you go") stands until the session ends or scope changes; push earns no default. Never
113
+ push on your own initiative. A launched loop's batch covers commit and push on its own
114
+ `loop/*` branch only; merging it never. A Foreman worker's covers commit and merge in its
115
+ own worktree, off any shared branch. Show the plain summary and the exact commit message
116
+ before each, then wait. Shared branches — `main`, `master`, `develop`, `development`,
117
+ `release`/`hotfix`, any unsure — take the same gate. Never force-push, hard-reset, or
118
+ rebase one: undo with a revert commit (git-history {{SKILL}} for a legitimate rewrite).
119
+ The host gates both at the tool boundary.
115
120
  <!-- LEAN:end -->
116
121
 
117
122
  ### {{DOCTRINE:bound-the-loop}} Bound the Loop
@@ -0,0 +1,10 @@
1
+ ### CI pipelines kit
2
+
3
+ Applies to Jenkins pipelines (declarative `Jenkinsfile`, shared libraries) and GitLab CI (`.gitlab-ci.yml` and its includes). Read the pipeline file and everything it loads before changing it.
4
+
5
+ - One source of truth: the pipeline lives in the repository's pipeline file and the libraries or includes it pins. No job configured by hand in the CI's web UI, no second copy of a step in another file.
6
+ - Secrets come only from the CI's own store (Jenkins credentials, GitLab masked and protected variables). Never in the pipeline file, a commit, a parameter default or the build log.
7
+ - Pin images, tools and shared code: image tags or digests, never `latest`; a fixed tool version; a library or include at a tag, never a moving branch.
8
+ - Fast feedback first: lint and unit tests run early and in parallel; slow stages wait on them.
9
+ - GitLab job conditions use `rules:`; Jenkins logic beyond declarative syntax goes into a tested shared-library step.
10
+ - Lint the pipeline before pushing, then prove the change with a real branch run, read from its log.
@@ -0,0 +1,14 @@
1
+ {
2
+ "description": "CI pipelines on Jenkins (declarative Jenkinsfile, shared libraries) and GitLab CI (.gitlab-ci.yml): job conditions, stage order, reuse, credentials, caching, testing the pipeline itself.",
3
+ "skills": ["jenkins-pipeline", "gitlab-ci"],
4
+ "agents": [],
5
+ "rules": "kits/ci-pipelines/rules.md",
6
+ "rulesWordBudget": 300,
7
+ "banned": ["only:", "except:"],
8
+ "catalogue": {
9
+ "skills": [
10
+ "| [jenkins-pipeline]({{DIR_SKILLS}}/jenkins-pipeline.md) | writing or fixing a declarative Jenkinsfile or a shared library: stages, when, parallel, credentials, CPS and @NonCPS, sandbox approval, JenkinsPipelineUnit tests |",
11
+ "| [gitlab-ci]({{DIR_SKILLS}}/gitlab-ci.md) | writing or fixing .gitlab-ci.yml: rules, needs, include and extends, cache and artifacts, protected and masked variables, environments, CI lint |"
12
+ ]
13
+ }
14
+ }
@@ -0,0 +1,11 @@
1
+ ### Docker kit
2
+
3
+ Applies to Docker images and Compose stacks. Run `docker compose config` and read the merged result before changing a stack.
4
+
5
+ - Pin every image to a version tag or a digest. Never `latest`, never an untagged image.
6
+ - Order startup by health: `depends_on` with `condition: service_healthy` on a real readiness check.
7
+ - State lives in named volumes. Never run `docker compose down -v` or prune volumes on a stack with data without a backup and an explicit go-ahead.
8
+ - No secret in an image layer, a build argument, the Compose file or a committed `.env`; use Compose `secrets:` or the runtime environment from a git-ignored file.
9
+ - Images run as a non-root user, built multi-stage, with a `.dockerignore`.
10
+ - Every long-running service has a restart policy, resource limits and capped logs.
11
+ - Before an update, know the rollback target (the previous tag or digest); confirm the new container is healthy before pruning the old image.
@@ -0,0 +1,12 @@
1
+ {
2
+ "description": "Docker and Compose operations for any stack: health-ordered startup, volumes, pinned images, env and secrets, restart, limits, logging, networks, lean non-root images, safe updates and rollback.",
3
+ "skills": ["compose-ops"],
4
+ "agents": [],
5
+ "rules": "kits/docker/rules.md",
6
+ "rulesWordBudget": 300,
7
+ "catalogue": {
8
+ "skills": [
9
+ "| [compose-ops]({{DIR_SKILLS}}/compose-ops.md) | writing, reviewing or operating a Compose stack or a generic Dockerfile: healthchecks, volumes, image pins, secrets, limits, logs, networks, safe update and rollback |"
10
+ ]
11
+ }
12
+ }
@@ -8,10 +8,11 @@
8
8
 
9
9
  Durable knowledge that must survive across sessions lives here as **one fact per
10
10
  file**. An agent reads `MEMORY.md` (the local index map) at the start of a session,
11
- and opens the topic file a task needs (see *The index* below). A new fact is written through the rule {{SKILL}}, which settles with the user
12
- whether it is a fact for here or a standing rule ({{DOCTRINE:persist-insight}}) — never on the
13
- agent's own initiative. The one automatic writer is the `learn` hook, where the host
14
- runs it: a distiller the user opted into at install, not an agent's judgement call.
11
+ and opens the topic file a task needs (see *The index* below). The agent writes a new fact
12
+ here on its own, with no prompt, following Branch A of the rule {{SKILL}}; the user sees every
13
+ memory afterwards in the web console ({{DOCTRINE:persist-insight}}). A standing rule is different:
14
+ it goes to the user first, through the same {{SKILL}}. The `learn` hook writes here too, where the
15
+ host runs it: a distiller the user opted into at install.
15
16
 
16
17
  This store is for **curated facts**, written for recall. For freeform working space
17
18
  the agent shapes for itself — plans, scratch designs, working theories, with no
@@ -15,12 +15,24 @@ task that would block it to one background task worker, and keeps answering the
15
15
  and the brief carries the approved decisions.
16
16
  - **One worker per task.** Dispatch one developer {{AGENT}} in the background, in its own
17
17
  worktree. The brief carries the task as the user stated it, BASE, the write set, the
18
- proof commands, and the rule that it never commits, pushes or merges. The worker
19
- explores, implements and tests in its own context, loading {{SKILLS}} as it needs them;
20
- after two repair rounds on its own red tests it returns red with its findings
21
- ({{DOCTRINE:bound-the-loop}}). It dispatches no {{AGENTS}}, except a read-only explorer
22
- when its own context would overflow. Check its write set against every task in flight
18
+ proof commands, and the rule that it never pushes and never merges outside its own
19
+ branch. The worker explores, implements and tests in its own context, loading {{SKILLS}}
20
+ as it needs them; after two repair rounds on its own red tests it returns red with its
21
+ findings ({{DOCTRINE:bound-the-loop}}). Check its write set against every task in flight
23
22
  ({{DOCTRINE:one-writer-per-file}}).
23
+ - **A worker may lead, inside its worktree.** It may dispatch read-only helpers (explorer,
24
+ researcher) at any time, and writing sub-workers, each in its own worktree branched from
25
+ its branch. It may commit and merge their branches into its own, locally, and re-runs the
26
+ proof after each merge. Depth stops at main → worker → sub-worker: a sub-worker
27
+ dispatches nothing. Every lead holds every member's result before it ends. The blind
28
+ reviewer stays the parent's.
29
+ - **Status, one line per change.** A worker reports
30
+ `T<n> · <task> · files: <write set> · <state>` at start and on each change: by
31
+ `SendMessage` to the parent on Claude Code (on OpenClaude only in its agent-teams mode);
32
+ elsewhere in its own `{{DIR_NOTEBOOK}}/foreman/<task>.status`, one line it alone writes.
33
+ Read all status files with one command, only before dispatching near the same files and
34
+ when a worker returns, never every turn. On an overlap, one waits or one owns the file;
35
+ record the ruling in the ledger.
24
36
  - **Verify non-trivial diffs blind.** When a worker returns green with a diff that touches
25
37
  two or more files or changes logic, dispatch a reviewer (a tester for test-heavy work)
26
38
  with only the original ask and the diff, never the worker's reasoning. A failing verdict
@@ -36,11 +48,12 @@ task that would block it to one background task worker, and keeps answering the
36
48
  worker serves one task and retires when that task is merged or dropped.
37
49
  - **Isolate.** Each worker works in its own git worktree/branch; falls back to a single
38
50
  tree, one worker at a time, when worktrees are unavailable.
39
- - **Merge on proof you re-ran.** A worker hands back its worktree, uncommitted, with raw
40
- test + lint output. The parent re-runs those commands itself — a worker's log is the
41
- worker's account, not the state — shows the user the diff and the green output, and
42
- commits and merges only once the user accepts ({{DOCTRINE:consent-before-push}}). Commit,
43
- push and merge stay the parent's alone.
51
+ - **Merge on proof you re-ran.** A worker hands back its branch, its local commits and any
52
+ uncommitted work, with raw test + lint output. The parent re-runs those commands itself —
53
+ a worker's log is the worker's account, not the state — shows the user the diff from BASE
54
+ and the green output, and commits and merges only once the user accepts
55
+ ({{DOCTRINE:consent-before-push}}). Push, and every merge beyond a worker's own branch,
56
+ stay the parent's alone.
44
57
  - **Report and watch.** Surface completions, failures, and merges to the user as they
45
58
  happen; a worker that returns no proof, or goes silent, is handled as the pipeline
46
59
  {{SKILL}}'s step 2 says for a crew.
@@ -32,7 +32,7 @@ will, in whatever structure serves you.
32
32
  the host tree. The host tree receives only the
33
33
  deliverables of the task.
34
34
  - **Promote what hardens.** When something here crystallises into a durable
35
- fact worth recalling verbatim, propose it for {{MEMORY}} through the rule {{SKILL}}
35
+ fact worth recalling verbatim, write it to {{MEMORY}}
36
36
  ({{DOCTRINE:persist-insight}}).
37
37
  - **It is not the repo's.** Do not keep here what the repository already
38
38
  records (code, git history, the {{LAWS}}, `user-rules.md`). Keep what is
@@ -9,12 +9,14 @@ write, and no rebuild touches them.
9
9
  Close each run with one beat of reflection on the {{SKILL}} itself:
10
10
  - A step misled, a needed step was missing, or the trigger fired wrongly — that
11
11
  is a flaw in this file. Write the exact correction (trigger, procedure, or
12
- done-when) into the notes file, with the user's assent ({{LAW:one-intent-one-act}}), as one line:
13
- `- [skill|general] <correction> — seen: <what happened, against what you expected> (<date>)`.
14
- `seen:` is the evidence the correction is later judged by; `general` marks one
15
- that would fix other {{SKILLS}} too. Never
12
+ done-when) into the notes file on your own, with no prompt, as one line:
13
+ `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what you expected> (<date>)`.
14
+ `situation:` bounds where the correction holds; `seen:` is the evidence it is
15
+ later judged by; `general` marks one that would fix other {{SKILLS}} too. Never
16
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.
17
+ reports the edit as drift. `geneseed diff` carries the notes back to the source;
18
+ folding a note into the source is the user's call, through the skill-forge
19
+ {{SKILL}} ({{LAW:one-intent-one-act}}).
18
20
  - Keep the notes sharp: amend or delete a line before adding one — a line with no
19
21
  `seen:`, or whose `seen:` no longer happens, goes first — and prune past about
20
22
  twenty lines.
@@ -26,10 +28,11 @@ Close each run with one beat of reflection on the {{SKILL}} itself:
26
28
  runs end here.
27
29
  <!-- LEAN:else -->
28
30
  One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or a
29
- wrong trigger is a flaw in this file — write the exact correction, with the user's
30
- assent ({{LAW:one-intent-one-act}}), into `{{PATH_NOTES}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
31
- name) as `- [skill|general] <correction> — seen: <what happened vs expected> (<date>)`,
32
- never into this rendered file, which a rebuild overwrites. Read that notes
31
+ wrong trigger is a flaw in this file — write the exact correction on your own, with no
32
+ prompt, into `{{PATH_NOTES}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
33
+ 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
33
36
  file before the first step when it exists; it wins where it disagrees. Keep it short.
34
37
  A lesson that is not about this file goes to {{MEMORY}} only if it clears
35
38
  {{DOCTRINE:persist-insight}}'s bar. Nothing learned — move on.
@@ -0,0 +1,58 @@
1
+ # {{SKILL}}: compose-ops
2
+
3
+ > {{DESC_COMPOSE_OPS}}
4
+
5
+ {{CREDIT:everything-claude-code:skills/docker-patterns/SKILL.md}}
6
+
7
+ **Trigger:** writing, reviewing or operating a `compose.yaml` (or `docker-compose.yml`) stack, or a generic Dockerfile for it: startup order, health, volumes, image pins, env and secrets, restart, limits, logs, networks, image size and user, or an update that must be safe to roll back. Stack-agnostic. A Spring Boot service's own image (Buildpacks, layered or native jar) belongs to the spring-boot kit's `docker-expert` agent when that kit is on, and so does that service's local-dev Compose file; this skill owns how every other stack is composed and run.
8
+
9
+ ## Working loop
10
+ 1. Read the Compose file, every `-f` override and `.env` it uses, then the merged result: `docker compose config`. It resolves variables, merges overrides and fails on a bad key.
11
+ 2. Check what runs now before changing it: `docker compose ps`, `docker compose images` (the real tags and digests), `docker compose logs --tail=100 <svc>`.
12
+ 3. Change, `docker compose config` again, then apply and confirm each changed service is `healthy` (or, for a service with no healthcheck, `running` with clean logs).
13
+
14
+ ## Startup order and health
15
+ - `depends_on: { db: { condition: service_healthy } }` waits for the dependency's healthcheck. A bare `depends_on: [db]` waits only for the container to start, not for the database to accept connections.
16
+ - Give every service others depend on a `healthcheck:` that tests readiness: `test: ["CMD", "pg_isready", "-U", "app"]`, with `interval`, `timeout`, `retries` and a `start_period` long enough for a cold start. The command must exist in the image; a missing `curl` makes the check fail forever.
17
+ - `condition: service_completed_successfully` for a one-shot job (a migration) that must finish first.
18
+
19
+ ## Volumes
20
+ | Use | Mount |
21
+ |---|---|
22
+ | Data the service owns (database, uploads) | named volume: `pgdata:/var/lib/postgresql/data`, declared under top-level `volumes:` |
23
+ | Config or source you edit on the host | bind mount, read-only where possible: `./nginx.conf:/etc/nginx/nginx.conf:ro` |
24
+ | Scratch that must not persist | `tmpfs:` |
25
+
26
+ - A named volume survives `down` and keeps Docker-managed permissions; a bind mount takes the host path's owner and breaks a non-root container whose UID does not match.
27
+ - `docker compose down -v` deletes named volumes, which is data loss. Never run it on a stack with state unless deleting the data is the intent and a backup exists.
28
+ - An anonymous volume (a container path with no name) carries over when `up` recreates the container, but is orphaned after `down` then `up`, or with `up -V` (`--renew-anon-volumes`), and its data is no longer mounted; name it.
29
+
30
+ ## Images
31
+ - Pin every `image:` to a version tag (`postgres:16.4`), and to a digest (`postgres:16.4@sha256:...`) where the stack must reproduce exactly. Never `latest` and never no tag: an update must be a change in the file.
32
+ - Your own images: multi-stage builds, so the final stage carries only the runtime and the built output, not compilers or dev dependencies. Start from a slim or distroless base, and add a `.dockerignore` (`.git`, `node_modules`, build output, `.env`).
33
+ - Run as a non-root user: `USER app` in the Dockerfile, or `user: "1000:1000"` in Compose. Add `read_only: true` with a `tmpfs:` for write paths, `cap_drop: [ALL]` and `security_opt: ["no-new-privileges:true"]` where the service allows.
34
+
35
+ ## Env and secrets
36
+ - `.env` holds non-secret settings and the values the file interpolates (`${TAG:?set TAG}` fails loudly when unset). It is git-ignored; commit a `.env.example` with placeholders instead.
37
+ - Secrets go in `secrets:` (a file outside the repository, mounted at `/run/secrets/<name>`), read by images that support `*_FILE` variables (`POSTGRES_PASSWORD_FILE`). An `environment:` secret shows in `docker inspect` and in every child process.
38
+ - Never bake a secret into an image: `ARG`/`ENV` values stay in the layer history. Use `RUN --mount=type=secret,id=...` for a build-time secret.
39
+
40
+ ## Running: restart, limits, logs
41
+ - `restart: unless-stopped` for long-running services; `restart: "no"` for one-shot jobs. A service that crash-loops hides its error behind restarts: read `docker compose logs` before raising retries.
42
+ - Set limits so one service cannot starve the host: `deploy: { resources: { limits: { cpus: "1.0", memory: 512M } } }`, or `mem_limit:` on older engines. A JVM or Node process also needs its heap capped below the limit.
43
+ - Cap logs: `logging: { driver: json-file, options: { max-size: "10m", max-file: "3" } }` (or `local`). The default json-file driver grows until the disk is full.
44
+
45
+ ## Networks
46
+ - Services reach each other by service name on the stack's default network; never hard-code container IPs.
47
+ - Split networks by trust: a `frontend` network for the proxy and the app, a `backend` network with `internal: true` for the database, which then has no route out and no published port.
48
+ - Publish only the ports users reach, bound to an address where possible: `"127.0.0.1:5432:5432"` for a local-only database. A published port bypasses host firewall rules on most Linux setups.
49
+
50
+ ## Safe updates
51
+ 1. Record the current state: the running image digests (`docker compose images`) and the committed Compose file. Back up the named volumes of a stateful service before an update that may migrate its data.
52
+ 2. Change the pinned tag in the file, then `docker compose pull <svc>`.
53
+ 3. `docker compose up -d <svc>` recreates only the services whose image or configuration changed. Add `--wait` (with `--wait-timeout <seconds>`) to block until they are running or healthy; `--wait` only proves health for a service that has a healthcheck, so give one to every service you update.
54
+ 4. Check health and logs. Roll back by restoring the previous tag or digest and running `up -d` again; a data migration the new version ran may not roll back, which is why step 1 takes the backup.
55
+ 5. Prune old images only after the new version has proved itself: `docker image prune -a` deletes every image no container uses, the rollback target included (plain `docker image prune` removes only dangling images).
56
+
57
+ ## Done when
58
+ - `docker compose config` accepts the merged file, every changed service with a healthcheck reports `healthy` and the others are `running` with clean logs, images are pinned, no secret sits in the file, an image or `environment:`, and the rollback target (the previous tag or digest, and a backup for stateful data) is known.