@qvac/core 0.2.1 → 0.3.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 (278) hide show
  1. package/.claude/skills/compaction/SKILL.md +15 -6
  2. package/.claude/skills/js-house-style/SKILL.md +1 -0
  3. package/.claude/skills/pr-create/SKILL.md +66 -3
  4. package/.claude/skills/pr-review/SKILL.md +252 -40
  5. package/.claude/skills/release/SKILL.md +122 -0
  6. package/CLAUDE.md +8 -5
  7. package/README.md +3 -1
  8. package/dist-lib/client.js +1 -1
  9. package/dist-lib/index.js +8 -8
  10. package/dist-lib/lib/api/agents.d.ts +1 -1
  11. package/dist-lib/lib/api/agents.js +10 -10
  12. package/dist-lib/lib/api/app-config.js +1 -1
  13. package/dist-lib/lib/api/approval-rules.js +9 -5
  14. package/dist-lib/lib/api/attachments.js +25 -3
  15. package/dist-lib/lib/api/chat-groups.d.ts +1 -1
  16. package/dist-lib/lib/api/chat-groups.js +5 -4
  17. package/dist-lib/lib/api/chat.js +10 -10
  18. package/dist-lib/lib/api/chunks.d.ts +1 -1
  19. package/dist-lib/lib/api/chunks.js +11 -21
  20. package/dist-lib/lib/api/config.js +1 -1
  21. package/dist-lib/lib/api/current-mesh.d.ts +16 -1
  22. package/dist-lib/lib/api/current-mesh.js +18 -0
  23. package/dist-lib/lib/api/custom-models.js +2 -2
  24. package/dist-lib/lib/api/devices.d.ts +1 -1
  25. package/dist-lib/lib/api/devices.js +12 -9
  26. package/dist-lib/lib/api/diagnostics.js +1 -1
  27. package/dist-lib/lib/api/effective-ctx-size.js +1 -1
  28. package/dist-lib/lib/api/execution.js +4 -4
  29. package/dist-lib/lib/api/files.js +2 -2
  30. package/dist-lib/lib/api/index.d.ts +1 -0
  31. package/dist-lib/lib/api/index.js +34 -34
  32. package/dist-lib/lib/api/instrument.js +1 -1
  33. package/dist-lib/lib/api/knowledge.js +13 -9
  34. package/dist-lib/lib/api/logs.js +1 -1
  35. package/dist-lib/lib/api/members.d.ts +4 -1
  36. package/dist-lib/lib/api/members.js +87 -18
  37. package/dist-lib/lib/api/mesh.d.ts +13 -3
  38. package/dist-lib/lib/api/mesh.js +25 -2
  39. package/dist-lib/lib/api/model-download.js +1 -1
  40. package/dist-lib/lib/api/network.js +1 -1
  41. package/dist-lib/lib/api/notifications.js +3 -3
  42. package/dist-lib/lib/api/rag.js +7 -7
  43. package/dist-lib/lib/api/sync.d.ts +1 -1
  44. package/dist-lib/lib/api/sync.js +3 -2
  45. package/dist-lib/lib/api/tool-activity.js +5 -5
  46. package/dist-lib/lib/api/tool-configs.js +5 -5
  47. package/dist-lib/lib/api/watchable.d.ts +6 -1
  48. package/dist-lib/lib/api/watchable.js +14 -3
  49. package/dist-lib/lib/assistant/fetch-body.d.ts +5 -0
  50. package/dist-lib/lib/assistant/fetch-body.js +36 -0
  51. package/dist-lib/lib/assistant/harness.d.ts +225 -0
  52. package/dist-lib/lib/assistant/harness.js +154 -0
  53. package/dist-lib/lib/assistant/history.d.ts +31 -0
  54. package/dist-lib/lib/assistant/history.js +226 -0
  55. package/dist-lib/lib/assistant/message.d.ts +45 -0
  56. package/dist-lib/lib/assistant/message.js +47 -0
  57. package/dist-lib/lib/assistant/skill-encode.d.ts +21 -0
  58. package/dist-lib/lib/assistant/skill-encode.js +71 -0
  59. package/dist-lib/lib/assistant-client.js +2 -2
  60. package/dist-lib/lib/assistant-tree.js +10 -4
  61. package/dist-lib/lib/assistant.d.ts +28 -292
  62. package/dist-lib/lib/assistant.js +284 -716
  63. package/dist-lib/lib/audio-format.js +2 -2
  64. package/dist-lib/lib/client.js +2 -2
  65. package/dist-lib/lib/collabora/convert.js +1 -1
  66. package/dist-lib/lib/collabora/entry.js +1 -1
  67. package/dist-lib/lib/collabora/worker.js +1 -1
  68. package/dist-lib/lib/compaction.d.ts +1 -2
  69. package/dist-lib/lib/compaction.js +8 -6
  70. package/dist-lib/lib/constants.js +1 -1
  71. package/dist-lib/lib/core/account-recovery.d.ts +19 -0
  72. package/dist-lib/lib/core/account-recovery.js +50 -0
  73. package/dist-lib/lib/core/agent.js +8 -4
  74. package/dist-lib/lib/core/app-build.d.ts +1 -1
  75. package/dist-lib/lib/core/approval-rules.d.ts +1 -0
  76. package/dist-lib/lib/core/approval-rules.js +3 -1
  77. package/dist-lib/lib/core/archived-mesh.d.ts +25 -0
  78. package/dist-lib/lib/core/archived-mesh.js +162 -0
  79. package/dist-lib/lib/core/chat-activity.js +1 -1
  80. package/dist-lib/lib/core/chat-group.d.ts +1 -0
  81. package/dist-lib/lib/core/chat-group.js +24 -4
  82. package/dist-lib/lib/core/chat-search.js +2 -2
  83. package/dist-lib/lib/core/chat.js +5 -5
  84. package/dist-lib/lib/core/chunk.d.ts +2 -1
  85. package/dist-lib/lib/core/chunk.js +31 -4
  86. package/dist-lib/lib/core/contract/agents.js +1 -1
  87. package/dist-lib/lib/core/contract/approval-rules.js +6 -4
  88. package/dist-lib/lib/core/contract/attestations.js +1 -1
  89. package/dist-lib/lib/core/contract/chat-group.js +1 -1
  90. package/dist-lib/lib/core/contract/chat.js +1 -1
  91. package/dist-lib/lib/core/contract/chunks.js +2 -2
  92. package/dist-lib/lib/core/contract/compute.d.ts +11 -0
  93. package/dist-lib/lib/core/contract/compute.js +45 -0
  94. package/dist-lib/lib/core/contract/devices.js +19 -5
  95. package/dist-lib/lib/core/contract/index.d.ts +3 -1
  96. package/dist-lib/lib/core/contract/index.js +19 -16
  97. package/dist-lib/lib/core/contract/indexing.js +2 -2
  98. package/dist-lib/lib/core/contract/joined-meshes.js +1 -1
  99. package/dist-lib/lib/core/contract/knowledge.js +2 -2
  100. package/dist-lib/lib/core/contract/members.js +2 -2
  101. package/dist-lib/lib/core/contract/seal.d.ts +2 -0
  102. package/dist-lib/lib/core/contract/seal.js +8 -0
  103. package/dist-lib/lib/core/contract/seed-defaults.js +1 -1
  104. package/dist-lib/lib/core/contract/tool-activity.js +1 -1
  105. package/dist-lib/lib/core/contract/tool-configs.js +3 -3
  106. package/dist-lib/lib/core/contract/writers.js +66 -42
  107. package/dist-lib/lib/core/departures.js +1 -1
  108. package/dist-lib/lib/core/device-invites.js +1 -1
  109. package/dist-lib/lib/core/document-attachment.js +2 -2
  110. package/dist-lib/lib/core/files/attachments.js +3 -3
  111. package/dist-lib/lib/core/files/index.d.ts +2 -2
  112. package/dist-lib/lib/core/files/index.js +19 -19
  113. package/dist-lib/lib/core/files/knowledge.js +3 -3
  114. package/dist-lib/lib/core/files/preview/image.js +1 -1
  115. package/dist-lib/lib/core/files/preview/index.js +6 -6
  116. package/dist-lib/lib/core/files/processing/claims.js +1 -1
  117. package/dist-lib/lib/core/files/processing/document.js +5 -5
  118. package/dist-lib/lib/core/files/processing/index.js +8 -8
  119. package/dist-lib/lib/core/files/processing/ownership.js +1 -1
  120. package/dist-lib/lib/core/files/processing/protocol.js +3 -3
  121. package/dist-lib/lib/core/files/processing/source.js +1 -1
  122. package/dist-lib/lib/core/files/rag/artifact/codec.js +1 -1
  123. package/dist-lib/lib/core/files/rag/artifact/id.js +1 -1
  124. package/dist-lib/lib/core/files/rag/artifact/types.d.ts +4 -4
  125. package/dist-lib/lib/core/files/rag/build.js +2 -2
  126. package/dist-lib/lib/core/files/rag/chunk/chunking.js +2 -2
  127. package/dist-lib/lib/core/files/rag/document-types.d.ts +3 -3
  128. package/dist-lib/lib/core/files/rag/extract/document-types.d.ts +9 -9
  129. package/dist-lib/lib/core/files/rag/extract/extract.js +7 -7
  130. package/dist-lib/lib/core/files/rag/extract/html-text.js +1 -1
  131. package/dist-lib/lib/core/files/rag/extract/office-collabora.js +2 -2
  132. package/dist-lib/lib/core/files/rag/extract/pdf-platform.js +1 -1
  133. package/dist-lib/lib/core/files/rag/extract/pdf-text.js +1 -1
  134. package/dist-lib/lib/core/files/rag/extract/text-decoding.js +1 -1
  135. package/dist-lib/lib/core/files/rag/extract/types.d.ts +2 -2
  136. package/dist-lib/lib/core/files/rag/index.js +22 -22
  137. package/dist-lib/lib/core/files/rag/load.js +5 -5
  138. package/dist-lib/lib/core/files/rag/policy.js +2 -2
  139. package/dist-lib/lib/core/files/rag/produce.js +5 -5
  140. package/dist-lib/lib/core/files/rag/retrieval/coverage.js +2 -2
  141. package/dist-lib/lib/core/files/rag/retrieval/diversity.js +1 -1
  142. package/dist-lib/lib/core/files/rag/retrieval/floor.js +2 -2
  143. package/dist-lib/lib/core/files/rag/retrieval/format.js +1 -1
  144. package/dist-lib/lib/core/files/rag/retrieval/full-text.js +18 -11
  145. package/dist-lib/lib/core/files/rag/retrieval/knowledge.js +5 -5
  146. package/dist-lib/lib/core/files/rag/retrieval/scoring.js +2 -2
  147. package/dist-lib/lib/core/files/rag/retrieval/search.js +4 -4
  148. package/dist-lib/lib/core/files/rag/retrieval/selection.js +2 -2
  149. package/dist-lib/lib/core/files/rag/retrieval/sources.js +2 -2
  150. package/dist-lib/lib/core/files/rag/retrieval/terms.js +1 -1
  151. package/dist-lib/lib/core/files/rag/retrieval/web-sources.js +1 -1
  152. package/dist-lib/lib/core/files/records/chunks.js +1 -1
  153. package/dist-lib/lib/core/files/records/index.js +8 -8
  154. package/dist-lib/lib/core/files/records/knowledge.js +2 -2
  155. package/dist-lib/lib/core/files/records/output.js +1 -1
  156. package/dist-lib/lib/core/files/records/reclaim.js +5 -5
  157. package/dist-lib/lib/core/files/records/routing.js +7 -7
  158. package/dist-lib/lib/core/files/store/blob.js +2 -2
  159. package/dist-lib/lib/core/files/store/index.js +7 -7
  160. package/dist-lib/lib/core/files/store/reference.js +2 -2
  161. package/dist-lib/lib/core/files/store/server.js +1 -1
  162. package/dist-lib/lib/core/files/store/sweep.js +1 -1
  163. package/dist-lib/lib/core/files/upload-input.js +2 -2
  164. package/dist-lib/lib/core/files/upload.d.ts +1 -1
  165. package/dist-lib/lib/core/files/upload.js +6 -6
  166. package/dist-lib/lib/core/harness-loan.d.ts +29 -0
  167. package/dist-lib/lib/core/harness-loan.js +187 -0
  168. package/dist-lib/lib/core/helpers/index.d.ts +2 -1
  169. package/dist-lib/lib/core/helpers/index.js +4 -4
  170. package/dist-lib/lib/core/hosted-agents.js +2 -2
  171. package/dist-lib/lib/core/identity.d.ts +2 -0
  172. package/dist-lib/lib/core/identity.js +4 -2
  173. package/dist-lib/lib/core/invite.d.ts +1 -0
  174. package/dist-lib/lib/core/invite.js +4 -2
  175. package/dist-lib/lib/core/local/index.d.ts +12 -3
  176. package/dist-lib/lib/core/local/index.js +81 -16
  177. package/dist-lib/lib/core/membership.d.ts +3 -0
  178. package/dist-lib/lib/core/membership.js +15 -1
  179. package/dist-lib/lib/core/mesh-seed-handoff.js +1 -1
  180. package/dist-lib/lib/core/mesh.d.ts +9 -3
  181. package/dist-lib/lib/core/mesh.js +41 -26
  182. package/dist-lib/lib/core/migrations/agent-catalog.js +1 -1
  183. package/dist-lib/lib/core/migrations/index.js +5 -3
  184. package/dist-lib/lib/core/migrations/membership.js +2 -2
  185. package/dist-lib/lib/core/migrations/seal.d.ts +3 -0
  186. package/dist-lib/lib/core/migrations/seal.js +30 -0
  187. package/dist-lib/lib/core/next-frame.js +1 -1
  188. package/dist-lib/lib/core/notification.js +1 -1
  189. package/dist-lib/lib/core/ota-config.js +1 -1
  190. package/dist-lib/lib/core/secret-handoff.js +1 -1
  191. package/dist-lib/lib/core/send.js +3 -3
  192. package/dist-lib/lib/core/skill-overlay-handoff.js +1 -1
  193. package/dist-lib/lib/core/skill-overlay-receiver.js +2 -2
  194. package/dist-lib/lib/core/skill-secrets.js +3 -3
  195. package/dist-lib/lib/core/sync/devices.js +1 -1
  196. package/dist-lib/lib/core/sync/index.js +8 -5
  197. package/dist-lib/lib/core/sync-status.js +1 -1
  198. package/dist-lib/lib/core/system-info.js +1 -1
  199. package/dist-lib/lib/core/tool-activity.js +2 -2
  200. package/dist-lib/lib/core/tool-configs.js +2 -2
  201. package/dist-lib/lib/core.d.ts +42 -3
  202. package/dist-lib/lib/core.js +543 -100
  203. package/dist-lib/lib/credential-pusher.js +4 -4
  204. package/dist-lib/lib/deadline.js +1 -1
  205. package/dist-lib/lib/fs-drive-bridge.js +5 -3
  206. package/dist-lib/lib/integrations/index.js +3 -3
  207. package/dist-lib/lib/integrations/oauth-providers.js +1 -1
  208. package/dist-lib/lib/integrations/setup-routes.d.ts +5 -5
  209. package/dist-lib/lib/integrations/setup-routes.js +3 -3
  210. package/dist-lib/lib/knowledge-search.js +1 -1
  211. package/dist-lib/lib/log.js +3 -3
  212. package/dist-lib/lib/mesh-scoped-engine.d.ts +3 -0
  213. package/dist-lib/lib/mesh-scoped-engine.js +101 -0
  214. package/dist-lib/lib/model-context.d.ts +2 -2
  215. package/dist-lib/lib/model-context.js +1 -1
  216. package/dist-lib/lib/model-download.d.ts +2 -0
  217. package/dist-lib/lib/model-download.js +26 -11
  218. package/dist-lib/lib/oauth/asana.js +3 -3
  219. package/dist-lib/lib/oauth/browser-connect.js +1 -1
  220. package/dist-lib/lib/oauth/client.js +2 -2
  221. package/dist-lib/lib/oauth/common.d.ts +1 -1
  222. package/dist-lib/lib/oauth/common.js +1 -1
  223. package/dist-lib/lib/oauth/flow-core.js +3 -3
  224. package/dist-lib/lib/oauth/flow.js +2 -2
  225. package/dist-lib/lib/oauth/google.js +4 -4
  226. package/dist-lib/lib/oauth/host.js +3 -3
  227. package/dist-lib/lib/oauth/keys.js +1 -0
  228. package/dist-lib/lib/oauth/loopback.js +1 -1
  229. package/dist-lib/lib/oauth/notion.js +3 -3
  230. package/dist-lib/lib/oauth/providers.js +1 -1
  231. package/dist-lib/lib/oauth/resolve.js +1 -1
  232. package/dist-lib/lib/oauth/spotify.js +4 -3
  233. package/dist-lib/lib/oauth/token-exchange.js +1 -1
  234. package/dist-lib/lib/oauth/verify.d.ts +8 -0
  235. package/dist-lib/lib/oauth/verify.js +58 -0
  236. package/dist-lib/lib/oauth.client.js +2 -2
  237. package/dist-lib/lib/oauth.d.ts +1 -0
  238. package/dist-lib/lib/oauth.js +13 -12
  239. package/dist-lib/lib/run-notices.d.ts +7 -7
  240. package/dist-lib/lib/run-transcript.js +1 -1
  241. package/dist-lib/schema/build.js +12 -6
  242. package/dist-lib/schema/content.d.ts +11 -11
  243. package/dist-lib/schema/engine.js +193 -30
  244. package/dist-lib/schema/field-order.js +2 -2
  245. package/dist-lib/schema/local.js +18 -4
  246. package/dist-lib/schema/qvac.d.ts +3 -0
  247. package/dist-lib/schema/qvac.js +22 -6
  248. package/dist-lib/spec/bind.js +41 -0
  249. package/dist-lib/spec/calls.js +12 -0
  250. package/dist-lib/spec/capabilities.d.ts +36 -12
  251. package/dist-lib/spec/hrpc/hrpc.json +161 -5
  252. package/dist-lib/spec/hrpc/index.js +154 -9
  253. package/dist-lib/spec/hrpc/messages.js +549 -129
  254. package/dist-lib/spec/hyperschema/index.js +549 -129
  255. package/dist-lib/spec/hyperschema/schema.json +370 -40
  256. package/dist-lib/spec/hyperschema/types.d.ts +85 -1
  257. package/dist-lib/spec/local/hyperdb/db.json +15 -0
  258. package/dist-lib/spec/local/hyperdb/index.js +70 -1
  259. package/dist-lib/spec/local/hyperdb/messages.js +300 -117
  260. package/dist-lib/spec/local/hyperschema/index.js +97 -4
  261. package/dist-lib/spec/local/hyperschema/schema.json +58 -1
  262. package/dist-lib/spec/local/hyperschema/types.d.ts +14 -0
  263. package/dist-lib/spec/mesh/hyperdb/messages.js +393 -288
  264. package/dist-lib/spec/mesh/hyperdispatch/dispatch.json +6 -0
  265. package/dist-lib/spec/mesh/hyperdispatch/index.js +18 -1
  266. package/dist-lib/spec/mesh/hyperdispatch/messages.js +176 -85
  267. package/dist-lib/spec/mesh/hyperschema/index.js +176 -85
  268. package/dist-lib/spec/mesh/hyperschema/schema.json +71 -21
  269. package/dist-lib/spec/mesh/hyperschema/types.d.ts +14 -1
  270. package/package.json +14 -8
  271. package/tui/README.md +7 -0
  272. package/tui/app.mjs +633 -55
  273. package/tui/lib/busy-words.mjs +57 -5
  274. package/tui/lib/export.mjs +1 -0
  275. package/tui/lib/render.mjs +25 -2
  276. package/tui/lib/selection.mjs +16 -0
  277. package/tui/lib/usage.mjs +54 -0
  278. package/tui/main.mjs +5 -2
@@ -74,12 +74,21 @@ What makes the fold legal under the rule above:
74
74
  cannot answer the question instead of summarizing it, and cannot pollute the
75
75
  chat's own cache file.
76
76
 
77
- Triggers: proactively before a run on the previous round's numbers, at the end of
78
- a run that filled the window itself, and reactively once the harness overflow
79
- ladder is exhausted. All three announce a `compacting` phase, which clients must
80
- exempt from any restart rule that discards a streamed answer on a non-terminal
81
- status. Clearing the phase stays conditional — only the before-run fold does it,
82
- because its run carries on.
77
+ Triggers: proactively before a run on the previous round's numbers, and
78
+ reactively once the harness overflow ladder is exhausted. Never at the end of a
79
+ run on its own numbers — that path existed and was removed (see the decision
80
+ record): the turn that fills the window ends cleanly, publishes its full reading,
81
+ and the next message folds first, keeping itself verbatim. The proactive share is
82
+ tiered by window — 75% under 12k, 82% under 16k, 85% under 32k, 90% under 64k,
83
+ 95% from there — because the band has to hold a whole thinking turn and
84
+ `cacheTokens` reports a turn with its thinking stripped. Both folds announce a
85
+ `compacting` phase. The before-run fold announces before anything streamed and
86
+ clears the phase, because its run carries on; the overflow fold can land behind
87
+ a partial answer, since a mid-stream overflow is not retried, and its failed
88
+ status closes the phase. That announcement is not an attempt start in
89
+ `historyFromChunks` — reading it as one drops the streamed answer from every
90
+ later prompt — and clients exempt it from their restart rule for the same
91
+ reason.
83
92
 
84
93
  After the fact the fold is visible from its chunk (`thread.compactionMarkers`,
85
94
  anchored before the user message the fold precedes). Only the device that ran the
@@ -446,6 +446,7 @@ We do **not** program defensively. We don't litter methods with arg-type checks,
446
446
  somePromise().catch(safetyCatch)
447
447
  ```
448
448
  - **Never swallow silently.** If you catch and ignore an _operational_ error, leave a comment on why it's safe.
449
+ - **A swallow that keeps the rejection is `.catch(noop)`**, never `.catch(() => null)` or another inline closure fabricating a value the caller does not read. Define `noop` once at the foot of the file. This is about not inventing a value — it says nothing about _whether_ to swallow, which is the `safety-catch` question above.
449
450
 
450
451
  The line to hold: **caller bug → let it crash. Runtime condition → handle it on the resource.** Don't blur the two by defending against the first.
451
452
 
@@ -61,6 +61,46 @@ Optional, and taken from what the diff actually touches — `lib`, `tui`, `schem
61
61
  A scope that restates the type (`fix(fix)`) or names the whole repo adds
62
62
  nothing; leave it off.
63
63
 
64
+ ## Examples
65
+
66
+ `examples/` is where a consumer meets this library: `mesh-peer.mjs` stands a
67
+ Core and a Client up from nothing, `mesh-lab.mjs` drives scenarios against it.
68
+ They are read before `lib/` is.
69
+
70
+ **A PR that adds public API ships an example with it.** Public API means a new
71
+ entry in `package.json#exports`, a new export from `index.ts` or `client.ts`,
72
+ or a new capability that reaches the `Client` surface through `schema/`. Extend
73
+ an existing script or add one, whichever shows the capability in the fewest
74
+ lines someone can actually run.
75
+
76
+ An example is a runnable `.mjs` under `examples/` that imports the package the
77
+ way a consumer does. Give it a `package.json#scripts` entry when it is a
78
+ scenario run by name, and name it in the PR body.
79
+
80
+ Nothing else needs one — an internal module, a `tui/` command, a refactor, a
81
+ fix. Do not pad `examples/` to clear a checklist: one script a reader can run
82
+ beats three that restate the types.
83
+
84
+ ## API docs
85
+
86
+ `docs/api/` carries one file per api module: every route's signature, its input
87
+ fields with what each is for, the mesh scope its handler honours, and a
88
+ changelog.
89
+
90
+ **A PR that changes a route's behaviour updates that route's file in the same
91
+ commit**, including its `### [Unreleased]` entry under the Keep a Changelog
92
+ heading it fits — `Fixed` for a defect, `Changed` for a contract that moved,
93
+ `Added` for a new route. The entry says what a caller has to do differently, not
94
+ what the diff did.
95
+
96
+ This is not optional documentation. The scope line is the only place that records
97
+ whether a handler honours `meshId`, and the changelog is what a consumer reads
98
+ to decide whether an upgrade touches them. A route whose behaviour moved and
99
+ whose file did not is a review finding.
100
+
101
+ Nothing else triggers it. An internal refactor behind an unchanged route, a
102
+ `tui/` change, a test — no doc change, no finding.
103
+
64
104
  ## Decision records
65
105
 
66
106
  `docs/decisions/` holds the durable, non-obvious choices — why a boundary is
@@ -148,6 +188,28 @@ For a **breaking change**, say so in the body under its own `## Breaking`
148
188
  heading, with the migration a consumer has to perform. Published package —
149
189
  this is the only warning they get.
150
190
 
191
+ ### Length, and the shape it has to hold
192
+
193
+ Twenty lines. The bodies in this log run 17–28 (`#134`, `#133`, `#130`), and a
194
+ reviewer reads the diff, not the description.
195
+
196
+ - **Use the template's headings and only those.** Delete what does not apply;
197
+ do not invent `## How I decided`, `## What is unresolved`, `## Is this a
198
+ contract change`. A point that needs its own heading is usually a point that
199
+ belongs in the commit message.
200
+ - **Never hard-wrap.** GitHub renders a single newline as a line break in PR
201
+ bodies, so text wrapped at 80 columns displays as a narrow ragged column
202
+ instead of filling the width. One bullet is one line, however long.
203
+ - **No process narrative.** "Checked rather than assumed", "found by
204
+ intersecting two facts", "I have not established" — how you arrived at the
205
+ change is not what a reviewer needs. State what is true.
206
+ - **No open-question lists.** A body that ends in four things somebody should
207
+ think about is a change that was not finished. Decide them, or say plainly in
208
+ one line what is deliberately left and why.
209
+ - **Depth goes in the commit message.** It is the durable record and it is where
210
+ a rejected alternative, a subtle invariant or a caveat belongs. The body is
211
+ the summary a reviewer reads first, not the second copy.
212
+
151
213
  ## Before opening
152
214
 
153
215
  1. Check the branch is not `main` and the name is neutral.
@@ -155,11 +217,12 @@ this is the only warning they get.
155
217
  each one is a change you would defend on its own. A trail of `wip`,
156
218
  `fixup` or `address review` commits is not history; reshape it before
157
219
  opening.
158
- 3. `bun run lint` and ``bun run test` (node, bare and addon lanes)` pass locally. CI runs the same lanes; a
220
+ 3. New public API? `examples/` shows it, and the body names the script.
221
+ 4. `bun run lint` and ``bun run test` (node, bare and addon lanes)` pass locally. CI runs the same lanes; a
159
222
  red PR wastes a reviewer's round trip.
160
- 4. Rebase on `main` rather than merging it in. A merge commit in the branch
223
+ 5. Rebase on `main` rather than merging it in. A merge commit in the branch
161
224
  makes the diff unreadable.
162
- 5. Open as a **draft** unless you are asking for review right now.
225
+ 6. Open as a **draft** unless you are asking for review right now.
163
226
 
164
227
  ```bash
165
228
  gh pr create --repo tetherto/qvac-core --draft --title "type(scope): subject" --body-file <path>
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: pr-review
3
- description: Deep-dive review of a pull request in @qvac/core, or of local uncommitted/branch changes when invoked with `local`. Checks CI, the commit type and title, code quality against the house style, contract and API mismatches, and missing tests. In PR mode it creates PENDING inline comments only after the user confirms them, and never submits the review event. In local mode it prints findings in chat and posts nothing. Use when reviewing a PR, given a PR link, or asked to review the working tree or current branch.
3
+ description: Deep-dive review of a pull request in @qvac/core, or of local uncommitted/branch changes when invoked with `local`. Checks CI and the base branch, the commit type and title, correctness and state/derived-data bugs, contract and API mismatches, security, code quality against the house style, and missing tests. In PR mode it creates PENDING inline comments only after the user confirms them, and never submits the review event. In local mode it prints findings in chat and posts nothing. Use when reviewing a PR, given a PR link, or asked to review the working tree or current branch.
4
4
  ---
5
5
 
6
6
  # PR review
@@ -41,14 +41,18 @@ PR mode:
41
41
 
42
42
  ```bash
43
43
  gh pr view <num> --repo tetherto/qvac-core \
44
- --json title,body,author,headRefName,headRefOid,baseRefName,files,additions,deletions,state,isDraft,mergeable
44
+ --json title,body,author,headRefName,headRefOid,baseRefName,files,additions,deletions,state,isDraft,mergeable,statusCheckRollup \
45
+ > /tmp/pr-<num>.json
45
46
  gh pr diff <num> --repo tetherto/qvac-core --patch > /tmp/pr-<num>.patch
46
47
  ```
47
48
 
48
- Read the patch from the file with Read/Grep rather than re-running `gh` — it is
49
- the same bytes every time and the file is greppable.
49
+ Two calls, then read both files with Read/Grep rather than re-running `gh` — it
50
+ is the same bytes every time and the files are greppable. `statusCheckRollup`
51
+ already carries every check, so **do not run `gh pr checks`**; it buys nothing
52
+ the JSON does not have.
50
53
 
51
- Local mode:
54
+ Local mode. The default scope is everything uncommitted — staged, unstaged and
55
+ untracked:
52
56
 
53
57
  ```bash
54
58
  git diff --staged > /tmp/local-staged.patch
@@ -57,8 +61,17 @@ git status --porcelain=v1
57
61
  git ls-files --others --exclude-standard # untracked, easy to miss
58
62
  ```
59
63
 
60
- For a branch rather than a working tree: `git diff main...HEAD` (three dots —
61
- the merge base, not the tip).
64
+ Scope overrides, when the user asks for one: `--staged` is `git diff --staged`
65
+ alone, `--unstaged` is `git diff` plus untracked, and `--branch [<base>]` is
66
+ `git diff <base>...HEAD` (three dots — the merge base, not the tip), with
67
+ `<base>` defaulting to `main`.
68
+
69
+ Untracked files are reviewed as wholly new content: read them from the working
70
+ tree, they appear in no patch.
71
+
72
+ **If the requested scope is empty, say so and stop.** An empty `--staged` is
73
+ not an invitation to review something else, and it is certainly not an
74
+ invitation to invent findings.
62
75
 
63
76
  ## CI
64
77
 
@@ -78,8 +91,10 @@ local `bun run test` does not:
78
91
  A PR that touches `schema/` and leaves `spec/` stale is the most common red
79
92
  here, and it looks nothing like a test failure.
80
93
 
94
+ Read the result from `statusCheckRollup` in `/tmp/pr-<num>.json`, and pull logs
95
+ only for a job that actually failed:
96
+
81
97
  ```bash
82
- gh pr checks <num> --repo tetherto/qvac-core
83
98
  gh run view --repo tetherto/qvac-core --log-failed --job <id> > /tmp/pr-<num>-<id>.log
84
99
  ```
85
100
 
@@ -87,6 +102,18 @@ A red `Integrate` is a blocking finding on its own. Read the failing job's log
87
102
  before writing a single line of review — half of what looks like a design
88
103
  problem is a lint rule.
89
104
 
105
+ ### Base branch
106
+
107
+ `baseRefName` is in the JSON you already fetched. Per CLAUDE.md a PR targets
108
+ `main`; the one exception is a stacked PR, which branches from the PR below it
109
+ and targets that branch.
110
+
111
+ So a base other than `main` is only a finding when the PR is **not** part of a
112
+ stack — check whether the base branch is itself an open PR before raising it.
113
+ If it is, the stack is correct and there is nothing to say. If it is not, that
114
+ is a `[P2]`: the diff will contain the base branch's commits and the PR cannot
115
+ merge as it stands.
116
+
90
117
  ## What to check, in order
91
118
 
92
119
  Stop at the first tier that produces findings worth the author's time; a review
@@ -97,7 +124,38 @@ end to end, including the error path. Look for: a promise not awaited, a
97
124
  listener never removed, a resource opened on one path and closed on another, an
98
125
  error swallowed into a default.
99
126
 
100
- **2. Contract and API.** This is a published package, so an exported signature
127
+ A **regression** belongs here too: a change that reads as additive but alters
128
+ what existing callers get — a signature widened, a default flipped, a branch
129
+ removed, a return value that is semantically different at the same type.
130
+
131
+ **2. State and derived data.** The class of bug a linter cannot see and a diff
132
+ skim misses. Walk any new stateful or arithmetic code against these four.
133
+
134
+ - **Two sources of truth.** The same value in two fields, or the same
135
+ expression computed twice, in one payload. Before writing the comment, read
136
+ the type declaration **and** the consumer: if the fields have distinct
137
+ documented meanings (per-item vs aggregate, raw vs normalised) and a reader
138
+ prefers one, this is a value written to the wrong channel — a contract
139
+ violation — not duplication. Say that, and cite the contract. Only call it
140
+ duplication when nothing distinguishes the fields. The two look identical in
141
+ a diff and have opposite fixes: one keeps both fields and moves a value, the
142
+ other deletes a field. Backwards, and you send the author to delete a channel
143
+ something depends on. `[P2]` either way.
144
+ - **Incremental accumulation.** A running total or offset advanced inside a
145
+ loop, where computing the whole table once would be correct by construction.
146
+ `[P2]` when a later edit could desynchronise it — and the fix shrinks the
147
+ code.
148
+ - **Closure over mutated state.** A callback capturing a variable a later step
149
+ reassigns, especially across an `await`. `[P1]` if a late or reordered
150
+ invocation yields a wrong value; say so plainly, because it will not
151
+ reproduce locally.
152
+ - **Laundered values.** `?? 0`, `|| 0`, `Math.max(x, 0)` turning an impossible
153
+ input into a plausible number instead of letting it fail. `[P2]` unless the
154
+ clamp buys a stated presentational guarantee. Watch an optional `uint` in
155
+ `schema/`: it decodes to `0`, not `null`, so `??` never sees the absent
156
+ value.
157
+
158
+ **3. Contract and API.** This is a published package, so an exported signature
101
159
  is a promise to a consumer.
102
160
 
103
161
  - Anything added to or changed in the export map, `index.ts`, `types/`, or
@@ -106,28 +164,61 @@ is a promise to a consumer.
106
164
  baseline regenerated (`bun run build:schema`) rather than hand-edited?
107
165
  - Does the change match its own type declarations, and do callers in this repo
108
166
  still typecheck?
167
+ - A route whose behaviour moved: is `docs/api/<module>.md` updated with it — the
168
+ scope line if the mesh handling changed, and an entry under `### [Unreleased]`?
169
+ That file is where a consumer looks before upgrading, so a stale one is a `[P2]`.
170
+ A refactor behind an unchanged route needs nothing.
109
171
 
110
- **3. House style.** Run the changed files against **js-house-style** — that
111
- document, not your own taste. Layering, composition on primitives, module size
112
- and shape, no defensive programming, comment density.
172
+ **4. House style.** Load **js-house-style** and run the changed files against
173
+ it — that document, not your own taste or your memory of it. Layering,
174
+ composition on primitives, module size and shape, no defensive programming,
175
+ comment density. A style point the document does not back is not a finding.
113
176
 
114
- **4. Tests.** A behaviour change with no test is a finding. Name the missing
177
+ **5. Tests.** A behaviour change with no test is a finding. Name the missing
115
178
  case rather than asking for "more tests": the tests live under `test/`, run on
116
179
  both the node and bare lanes, and a fix without a regression guard will come
117
180
  back.
118
181
 
119
- **5. Commit type and title.** Per **pr-create**: is this really a `fix` (a
182
+ **6. Examples.** This is a library, and `examples/` is where a consumer learns
183
+ its surface — `mesh-peer.mjs` for standing up a Core and a Client,
184
+ `mesh-lab.mjs` for scenarios on top. New public API with nothing in `examples/`
185
+ is a finding: `[P2]` for a new entry in `package.json#exports` or a new export
186
+ from `index.ts` / `client.ts`, `[P3]` for a capability folded into an area an
187
+ existing script already covers. Name the script that should have changed and
188
+ the one thing it should show; anchor the comment on the new export line, since
189
+ the absence itself has no line.
190
+
191
+ Nothing else triggers this. An internal module, a `tui/` command, a refactor, a
192
+ fix, a test — no example, no finding. Do not ask for an example because a diff
193
+ is large.
194
+
195
+ **7. Commit type and title.** Per **pr-create**: is this really a `fix` (a
120
196
  defect a consumer of a released version could hit), or is it `chore` on code
121
197
  that never shipped? Is the title imperative and specific? Does the branch name
122
198
  avoid `codex` / `cursor` / `claude`?
123
199
 
124
- **6. Scope.** Does the PR do one thing? A behaviour change mixed with an
200
+ **8. Scope.** Does the PR do one thing? A behaviour change mixed with an
125
201
  unrelated rename is two PRs — say so, and say which commit to split out.
126
202
 
127
- **7. Decision records.** Does the change contradict something in
128
- `docs/decisions/`? If it does, the record is updated or superseded in the same
129
- PR, not left to rot. Does it settle something non-obvious with no record at all?
130
- Say which, and what the record would have to state.
203
+ **9. Security.** Not a sweep of the file — only what this diff introduces. A
204
+ secret or key material in code, a log line or an error message; a peer-supplied
205
+ value trusted without validation at a trust boundary; unsafe deserialization of
206
+ anything off the wire; crypto used in a way the primitive does not promise
207
+ (a reused nonce, a comparison that is not constant-time, a key derived from
208
+ something predictable); a new dependency pulled in for something small.
209
+
210
+ This is a P2P library, so "the input came from another device" is the normal
211
+ case, not the exceptional one. Where it matters, `[P1]`.
212
+
213
+ **10. Decision records.** Only when the diff **contradicts** a record in
214
+ `docs/decisions/` that you have actually read — then the record is updated or
215
+ superseded in the same PR rather than left to rot, and that is a `[P2]`.
216
+
217
+ A missing record is not a finding. Do not open `docs/decisions/INDEX.md`
218
+ looking for something to say, do not ask for an ADR because a change "feels
219
+ architectural", and never make "no decision record" the only thing a review
220
+ found. If you genuinely think a lasting choice went unrecorded, say it once in
221
+ the chat overview as a question, never inline.
131
222
 
132
223
  ### Do not over-engineer the review
133
224
 
@@ -155,17 +246,38 @@ corner nobody chose.
155
246
  Each finding: the file and line, what breaks, and the concrete scenario that
156
247
  breaks it. No finding without a failure mode you can state.
157
248
 
158
- Drop anything you cannot defend as changing the code, the reviewer's decision,
159
- or a consumer's experience. Style opinions the house style does not back are
160
- noise. Say so plainly when the diff is clean: "no `[P1]` or `[P2]`
161
- findings" is a complete review.
162
-
163
249
  Lead with the findings, ordered by severity.
164
250
 
251
+ ### Only raise what is worth the author's time
252
+
253
+ A review is not required to produce findings. **"Nothing to flag — the diff is
254
+ clean" is a complete, successful review**, and a good PR reviewed honestly is
255
+ the expected outcome most of the time. Never go hunting for something to say
256
+ because the output looks empty; an invented finding costs the author more than
257
+ a silent review ever could.
258
+
259
+ Every finding passes this bar before it is written down:
260
+
261
+ - You can name **what breaks**, and the concrete path that reaches it.
262
+ - Acting on it **changes the code, the reviewer's decision, or a consumer's
263
+ experience**.
264
+ - It is backed by the house style or a real contract, not your taste.
265
+
266
+ Drop everything else. Not "mention it as a `[P3]`" — **drop it**. A finding you
267
+ cannot defend at `[P2]` is not thereby a `[P3]`; it is noise wearing a smaller
268
+ tag. `[P3]` is for a real, small, correct observation, not a holding pen for
269
+ weak `[P1]`/`[P2]`s.
270
+
271
+ The failure mode this repo has actually seen: a clean PR comes back with four
272
+ `[P3]`s about naming, a speculative race nobody can reach, and a request for a
273
+ decision record. That review is worse than no review — it trains the author to
274
+ skim the next one, and the real finding gets skimmed with it.
275
+
165
276
  ### Severity tags
166
277
 
167
- Tag every finding `[P1]`, `[P2]` or `[P3]`. Use the tag, not a word, so two
168
- reviews of the same repo rank things the same way.
278
+ Tag every finding `[P1]`, `[P2]` or `[P3]` **in the chat overview**, using the
279
+ tag rather than a word, so two reviews of the same repo rank things the same
280
+ way. The tag never appears on the PR — see "Comment style".
169
281
 
170
282
  - `[P1]` — almost-certain bug, data corruption, security issue, CI breaker, or a
171
283
  break of behaviour a consumer relies on. In the overview, and **proposed inline
@@ -182,35 +294,135 @@ nits inline teaches the author to skim the next one.
182
294
 
183
295
  **Severity is what the code does today, not what it might do.** A finding whose
184
296
  only support is a scenario nobody has hit is not a `[P2]`: either find the path
185
- that reaches it, or drop it. Zero findings is a legitimate result.
297
+ that reaches it, or drop it — do not park it at `[P3]` instead. Zero findings is
298
+ a legitimate result.
186
299
 
187
300
  If the user says this is a re-review, say explicitly which earlier concerns are
188
301
  resolved and which still stand.
189
302
 
303
+ ### The overview
304
+
305
+ The user's checkout is usually on a different branch or commit than the PR, so
306
+ a bare line number is worth nothing to them. Every `[P1]` and `[P2]` in the
307
+ overview therefore carries two things: a **3–8 line excerpt read at the head
308
+ SHA**, and a **link to that line on the PR**.
309
+
310
+ The excerpt comes from
311
+ `gh api -H "Accept: application/vnd.github.raw" repos/tetherto/qvac-core/contents/<path>?ref=<headRefOid>`,
312
+ never from the local tree. The link is the file-diff anchor:
313
+
314
+ `https://github.com/tetherto/qvac-core/pull/<num>/files#diff-<sha256(path)>R<line>`
315
+
316
+ ```bash
317
+ printf '%s' 'lib/chat/compact.js' | shasum -a 256 | awk '{print $1}'
318
+ ```
319
+
320
+ If the anchor will not compute, fall back to
321
+ `https://github.com/tetherto/qvac-core/blob/<headRefOid>/<path>#L<line>`.
322
+
323
+ ````markdown
324
+ ## PR #<num> — review overview
325
+
326
+ <one line: what this PR does>
327
+
328
+ ### CI / base
329
+
330
+ <one line; omit entirely when both are clean>
331
+
332
+ ### Findings
333
+
334
+ - **[P1]** <short title> — [`<path>:<line>`](link)
335
+
336
+ <one sentence, plus the repro when there is one>
337
+
338
+ ```js
339
+ <3-8 line excerpt at the head SHA>
340
+ ```
341
+
342
+ - **[P3]** <short title> — [`<path>:<line>`](link) — <one sentence, no excerpt>
343
+
344
+ ### Re-review delta
345
+
346
+ <only when the user said this is a re-review>
347
+
348
+ - Resolved: <…>
349
+ - Still open: <…>
350
+ ````
351
+
352
+ One sentence per finding here; the inline comment carries the reasoning. A
353
+ clean review is this same block with `Findings` reading "nothing to flag".
354
+
355
+ Local mode uses the same shape, headed `## Local review — <scope>`, with plain
356
+ `path:line` instead of links and the excerpt read from the working tree.
357
+
358
+ ## Comment style
359
+
360
+ Write like a colleague leaving a note, not a static analyser filing a report.
361
+ If a human reviewer would not say it out loud, do not write it.
362
+
363
+ - **Brief.** A few lines, one point per comment. If it takes three paragraphs
364
+ to justify, it probably is not a finding.
365
+ - **Ask, don't lecture.** "Can this reuse the existing helper?" beats a
366
+ paragraph on why the new one duplicates knowledge the store already owns.
367
+ - **Link what you refer to.** An existing function, type or rule you want
368
+ reused gets a line link — `[name](<url>#L120)`. A reference the author has to
369
+ hunt for is one they skip.
370
+ - **Show the change in code.** A short before/after, or a `suggestion` block
371
+ whenever the fix is mechanical enough to apply as-is.
372
+ - **Never put a severity marker in a comment body.** No `[P1]`/`[P2]`/`[P3]`,
373
+ no "blocker", no "nit:". Severity is how _you_ decided what to raise; it
374
+ lives in the chat overview and nowhere else. On the PR it reads as grading
375
+ the author and it ages badly once the code moves. If something is minor, say
376
+ it in plain words — "not urgent", "while you're in there".
377
+ - One concrete repro line for a `[P1]`/`[P2]` when one exists. Not a test plan.
378
+ - No praise padding, no "LGTM but…", no restating what the diff does.
379
+ - **Sign off every comment with 🤖 on its own last line**, so it is
380
+ unmistakable that the review came from an AI. Every inline comment, no
381
+ exceptions — the emoji alone, nothing else on the line.
382
+
190
383
  ## Posting (PR mode only)
191
384
 
192
- 1. Print every proposed comment in chat first: file, line, severity, body.
193
- The default set is the `[P1]` and `[P2]` findings; name any `[P3]` you are
194
- holding back so the user can pull it in.
385
+ 1. Print every proposed comment in chat first, as it will be posted: file,
386
+ line, then the verbatim body. Carry the severity in the chat line **outside**
387
+ the body. The default set is the `[P1]` and `[P2]` findings; name any `[P3]`
388
+ you are holding back so the user can pull it in. If there is nothing at
389
+ `[P1]`/`[P2]`, say so and stop — never assemble a payload out of `[P3]`s to
390
+ have something to post.
195
391
  2. Ask the user to confirm the exact set. Wait for a clear yes.
196
- 3. Create the review as **PENDING**, with no event:
392
+ 3. Write `/tmp/pr-<num>-review.json` from the confirmed set **only**. If the
393
+ confirmed set is empty, stop — never post an empty review.
394
+ 4. Pre-flight, before the POST:
395
+ - The comment count matches the confirmed set **exactly**. If it does not,
396
+ stop and reconcile; do not post the larger set and mention it after.
397
+ - Every `line` is a **post-PR line** — the `+` side of the patch, as
398
+ numbered in the file at the head SHA. A line the patch does not touch is a
399
+ `422` that rejects the whole review, so anchor to a touched line or move
400
+ the point to the chat overview.
401
+ - Every body ends with a `🤖` line, and none contains `[P1]`, `[P2]`, `[P3]`,
402
+ "nit" or "blocker". Fix the bodies yourself; do not ask the user.
403
+ - Show the bodies as **rendered Markdown**, one per `file:line`, never raw
404
+ JSON — the user is approving what the author will read.
405
+ 5. Create the review as **PENDING**, with no event:
197
406
 
198
407
  ```bash
199
408
  gh api repos/tetherto/qvac-core/pulls/<num>/reviews \
200
- --method POST --input /tmp/review.json
409
+ --method POST --input /tmp/pr-<num>-review.json
201
410
  ```
202
411
 
203
- where `review.json` has `commit_id` (the `headRefOid` you fetched) and a
204
- `comments` array of `{path, line, side, body}`, and **no `event` field**. A body
205
- with `event` submits the review; leaving it out is what makes it pending.
412
+ where the payload has `commit_id` (the `headRefOid` you fetched) and a
413
+ `comments` array of `{path, line, side, body}`, and **no `event` field**. A
414
+ payload with `event` submits the review; leaving it out is what makes it
415
+ pending. No top-level `body` either, unless the user asks for one — the inline
416
+ comments are the review.
206
417
 
207
- 4. Hand the user the link and stop:
208
- `https://github.com/tetherto/qvac-core/pull/<num>#pullrequestreview-<id>`
418
+ If the user edits the selection after the preview, rewrite the file before
419
+ running the command.
209
420
 
210
- If a line is not in the diff, GitHub rejects the comment. Anchor to a line the
211
- patch actually touches, or raise it in the chat overview instead.
421
+ 6. Hand the user the link and stop:
422
+ `https://github.com/tetherto/qvac-core/pull/<num>#pullrequestreview-<id>`
212
423
 
213
424
  ## Sibling skills
214
425
 
215
426
  - Writing the PR being reviewed → **pr-create**.
216
- - The rules tier 3 reviews against → **js-house-style**.
427
+ - The rules tier 4 reviews against → **js-house-style**. Load it; do not review
428
+ from memory of it.
@@ -0,0 +1,122 @@
1
+ ---
2
+ name: release
3
+ description: Cut a release of @qvac/core — pick the version from what landed, bump package.json on a release/x.y.z branch, and roll the api changelogs from Unreleased to the dated version. Use when asked to release, cut a version, publish, or bump the version.
4
+ ---
5
+
6
+ # Release
7
+
8
+ A release here is small and shaped by convention, and both halves matter: the
9
+ version bump, and rolling `docs/api/` from `[Unreleased]` to a dated heading.
10
+ Nothing else rides along.
11
+
12
+ ## What publishes
13
+
14
+ `.github/workflows/publish.yml` triggers on `push: tags: v*`. **The tag is the
15
+ release.** It is created on the merge commit after the PR lands, never on the
16
+ branch — a tag pushed from the branch publishes unreviewed code.
17
+
18
+ So this skill takes you to a merged PR. Tagging is the step after, and it is the
19
+ user's to take unless they ask otherwise.
20
+
21
+ ## 1. Choose the version, then ask
22
+
23
+ Read what has landed since the last tag:
24
+
25
+ ```bash
26
+ git describe --tags --abbrev=0
27
+ git log --format='%s' "$(git describe --tags --abbrev=0)"..main
28
+ ```
29
+
30
+ Classify by conventional-commit type, and remember this package is pre-1.0:
31
+
32
+ | What landed | Bump |
33
+ | -------------------------------------------- | ------- |
34
+ | A breaking change (`!`, or a removed export) | `minor` |
35
+ | `feat` | `minor` |
36
+ | `fix`, `perf`, `refactor`, `chore`, `docs` | `patch` |
37
+
38
+ While the major is `0`, a breaking change is a **minor** bump, not a major one —
39
+ `0.1.7 → 0.2.0` in this repo's history is exactly that. Reserve `major` for
40
+ declaring the API stable, which is a decision, not a consequence of a diff.
41
+
42
+ **Always suggest a version and always ask.** State the bump, the resulting
43
+ version, and the one or two commits that drove it, then wait for a clear answer.
44
+ The log is a signal, not the decision — a `feat` that nobody can reach yet is a
45
+ patch, and a `fix` that changes a contract is not.
46
+
47
+ ## 2. Branch
48
+
49
+ ```bash
50
+ git checkout main && git pull
51
+ git checkout -b release/0.2.3
52
+ ```
53
+
54
+ The branch is named for the version it carries.
55
+
56
+ ## 3. Bump
57
+
58
+ ```bash
59
+ npm version 0.2.3 --no-git-tag-version
60
+ ```
61
+
62
+ `--no-git-tag-version` is not optional: `npm version` tags by default, and a tag
63
+ on this branch publishes before review.
64
+
65
+ Then check what moved:
66
+
67
+ ```bash
68
+ git status --porcelain
69
+ ```
70
+
71
+ **Only `package.json` may change.** `package-lock.json` has been stale since
72
+ `0.1.4` and every release since has left it alone; if npm touches it, revert it
73
+ rather than bringing unrelated churn into a release PR. Same for `bun.lock`.
74
+
75
+ ## 4. Roll the api changelogs
76
+
77
+ Every file in `docs/api/` ends with a changelog in
78
+ [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) form. For each file:
79
+
80
+ - A `### [Unreleased]` with entries under it becomes `### [0.2.3] - 2026-09-21`,
81
+ dated today. Leave the entries as they are — they were written by whoever made
82
+ the change and say what a caller has to do differently.
83
+ - A `### [Unreleased]` reading "No behaviour changes since …" is **not** rolled.
84
+ That module did not change; giving it a dated heading would claim it did.
85
+ Update its sentence to name the new version instead.
86
+ - Every file's `Latest release: **0.2.2**` line becomes the new version.
87
+
88
+ The next behaviour change adds `### [Unreleased]` back above the dated heading.
89
+ Do not leave an empty one behind.
90
+
91
+ ## 5. Commit and open
92
+
93
+ The commit message and the PR title are **the version alone**:
94
+
95
+ ```
96
+ 0.2.3
97
+ ```
98
+
99
+ No type, no scope, no body. That is how every release in this log reads
100
+ (`0.2.2 (#131)`, `0.2.1 (#78)`), and it is what makes them findable.
101
+
102
+ A release PR carries the bump and the changelog roll and nothing else. Do not
103
+ fold a fix into it, and do not fold a bump into a feature PR.
104
+
105
+ Open it against `main`, not as a draft — there is nothing to iterate on.
106
+
107
+ ## 6. After it merges
108
+
109
+ Tag the merge commit and push the tag; that is what publishes:
110
+
111
+ ```bash
112
+ git checkout main && git pull
113
+ git tag v0.2.3 && git push origin v0.2.3
114
+ ```
115
+
116
+ Confirm with the user before pushing a tag. It is the one irreversible step —
117
+ npm does not let a version be republished.
118
+
119
+ ## Sibling skills
120
+
121
+ - Writing any other PR → **pr-create**, which also covers why release PRs are
122
+ titled by version alone.