@qvac/core 0.3.0 → 0.3.2

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 (191) hide show
  1. package/dist-lib/lib/api/chat.d.ts +3 -1
  2. package/dist-lib/lib/api/chat.js +6 -2
  3. package/dist-lib/lib/api/index.d.ts +2 -0
  4. package/dist-lib/lib/api/index.js +3 -1
  5. package/dist-lib/lib/api/inference-calls.d.ts +18 -0
  6. package/dist-lib/lib/api/inference-calls.js +15 -0
  7. package/dist-lib/lib/api/rag.js +10 -2
  8. package/dist-lib/lib/assistant/harness.d.ts +1 -0
  9. package/dist-lib/lib/assistant/history.d.ts +10 -1
  10. package/dist-lib/lib/assistant/history.js +36 -1
  11. package/dist-lib/lib/assistant/message.d.ts +2 -0
  12. package/dist-lib/lib/assistant/message.js +11 -0
  13. package/dist-lib/lib/assistant/skill-encode.js +27 -1
  14. package/dist-lib/lib/assistant-tree.d.ts +2 -0
  15. package/dist-lib/lib/assistant-tree.js +11 -2
  16. package/dist-lib/lib/assistant.d.ts +19 -3
  17. package/dist-lib/lib/assistant.js +148 -23
  18. package/dist-lib/lib/core/chunk.js +5 -0
  19. package/dist-lib/lib/core/files/rag/build.d.ts +1 -2
  20. package/dist-lib/lib/core/files/rag/build.js +1 -2
  21. package/dist-lib/lib/core/files/rag/extract/office-collabora.d.ts +1 -1
  22. package/dist-lib/lib/core/files/rag/index.d.ts +4 -24
  23. package/dist-lib/lib/core/files/rag/index.js +3 -17
  24. package/dist-lib/lib/core/files/rag/load.d.ts +1 -2
  25. package/dist-lib/lib/core/files/rag/load.js +1 -2
  26. package/dist-lib/lib/core/files/rag/produce.d.ts +1 -1
  27. package/dist-lib/lib/core/files/rag/produce.js +1 -3
  28. package/dist-lib/lib/core/files/rag/retrieval/full-text.d.ts +1 -1
  29. package/dist-lib/lib/core/files/rag/retrieval/full-text.js +1 -4
  30. package/dist-lib/lib/core/files/rag/similarity.d.ts +5 -0
  31. package/dist-lib/lib/core/files/rag/similarity.js +6 -0
  32. package/dist-lib/lib/core/files/upload.d.ts +1 -1
  33. package/dist-lib/lib/core/inference-calls-handoff.d.ts +20 -0
  34. package/dist-lib/lib/core/inference-calls-handoff.js +37 -0
  35. package/dist-lib/lib/core/inference-calls-receiver.d.ts +14 -0
  36. package/dist-lib/lib/core/inference-calls-receiver.js +39 -0
  37. package/dist-lib/lib/core/notification.js +5 -4
  38. package/dist-lib/lib/core/skill-secrets.js +3 -6
  39. package/dist-lib/lib/core.d.ts +9 -1
  40. package/dist-lib/lib/core.js +129 -13
  41. package/dist-lib/lib/credential-pusher.d.ts +2 -3
  42. package/dist-lib/lib/credential-pusher.js +67 -39
  43. package/dist-lib/lib/inference-calls.d.ts +40 -0
  44. package/dist-lib/lib/inference-calls.js +266 -0
  45. package/dist-lib/lib/integrations/index.d.ts +1 -2
  46. package/dist-lib/lib/integrations/index.js +0 -1
  47. package/dist-lib/lib/integrations/setup-routes.js +0 -15
  48. package/dist-lib/lib/oauth/flow-core.js +1 -1
  49. package/dist-lib/lib/oauth/flow.d.ts +4 -2
  50. package/dist-lib/lib/oauth/flow.js +3 -4
  51. package/dist-lib/lib/oauth/host.d.ts +3 -1
  52. package/dist-lib/lib/oauth/host.js +3 -1
  53. package/dist-lib/lib/oauth/keys.d.ts +21 -20
  54. package/dist-lib/lib/oauth/keys.js +59 -85
  55. package/dist-lib/lib/oauth/loopback.d.ts +2 -2
  56. package/dist-lib/lib/oauth/loopback.js +32 -19
  57. package/dist-lib/lib/oauth/loopback.stub.d.ts +2 -2
  58. package/dist-lib/lib/oauth/loopback.stub.js +2 -2
  59. package/dist-lib/lib/oauth/providers.d.ts +3 -5
  60. package/dist-lib/lib/oauth/providers.js +20 -67
  61. package/dist-lib/lib/oauth/redirect-types.d.ts +1 -0
  62. package/dist-lib/lib/oauth/registry.d.ts +10 -0
  63. package/dist-lib/lib/oauth/registry.js +25 -0
  64. package/dist-lib/lib/oauth/resolve.js +1 -1
  65. package/dist-lib/lib/oauth/token-exchange-core.js +2 -1
  66. package/dist-lib/lib/oauth/types.d.ts +1 -1
  67. package/dist-lib/lib/oauth.client.d.ts +3 -1
  68. package/dist-lib/lib/oauth.client.js +3 -1
  69. package/dist-lib/lib/oauth.d.ts +4 -7
  70. package/dist-lib/lib/oauth.js +4 -7
  71. package/dist-lib/lib/skill-types.d.ts +12 -0
  72. package/dist-lib/schema/content.js +5 -1
  73. package/dist-lib/schema/engine.js +63 -2
  74. package/dist-lib/schema/qvac.js +4 -2
  75. package/dist-lib/spec/bind.js +3 -0
  76. package/dist-lib/spec/calls.js +1 -0
  77. package/dist-lib/spec/capabilities.d.ts +2 -0
  78. package/dist-lib/spec/hrpc/hrpc.json +13 -0
  79. package/dist-lib/spec/hrpc/index.js +15 -3
  80. package/dist-lib/spec/hrpc/messages.js +284 -52
  81. package/dist-lib/spec/hyperschema/index.js +284 -52
  82. package/dist-lib/spec/hyperschema/schema.json +210 -1
  83. package/dist-lib/spec/hyperschema/types.d.ts +51 -1
  84. package/dist-lib/spec/local/hyperdb/messages.js +64 -128
  85. package/dist-lib/spec/local/hyperschema/index.js +32 -64
  86. package/dist-lib/spec/local/hyperschema/schema.json +16 -0
  87. package/dist-lib/spec/mesh/hyperdb/messages.js +176 -311
  88. package/dist-lib/spec/mesh/hyperdispatch/messages.js +132 -236
  89. package/dist-lib/spec/mesh/hyperschema/index.js +132 -236
  90. package/dist-lib/spec/mesh/hyperschema/schema.json +70 -1
  91. package/dist-lib/spec/mesh/hyperschema/types.d.ts +3 -1
  92. package/package.json +15 -18
  93. package/tui/app.mjs +98 -155
  94. package/tui/lib/knowledge-import.mjs +1 -1
  95. package/tui/lib/save-file.mjs +1 -1
  96. package/.claude/skills/asana/SKILL.md +0 -86
  97. package/.claude/skills/compaction/SKILL.md +0 -136
  98. package/.claude/skills/device-mesh-debug/SKILL.md +0 -328
  99. package/.claude/skills/gh-stack/SKILL.md +0 -181
  100. package/.claude/skills/gh-stack/references/commands.md +0 -177
  101. package/.claude/skills/gh-stack/references/stack-design.md +0 -97
  102. package/.claude/skills/gh-stack/references/troubleshooting.md +0 -159
  103. package/.claude/skills/js-house-style/SKILL.md +0 -671
  104. package/.claude/skills/pr-create/SKILL.md +0 -243
  105. package/.claude/skills/pr-review/SKILL.md +0 -428
  106. package/.claude/skills/release/SKILL.md +0 -122
  107. package/CLAUDE.md +0 -48
  108. package/dist-lib/lib/core/files/rag/artifact/codec.d.ts +0 -3
  109. package/dist-lib/lib/core/files/rag/artifact/codec.js +0 -172
  110. package/dist-lib/lib/core/files/rag/artifact/id.d.ts +0 -10
  111. package/dist-lib/lib/core/files/rag/artifact/id.js +0 -39
  112. package/dist-lib/lib/core/files/rag/artifact/types.d.ts +0 -24
  113. package/dist-lib/lib/core/files/rag/artifact/types.js +0 -41
  114. package/dist-lib/lib/core/files/rag/chunk/chunking.d.ts +0 -12
  115. package/dist-lib/lib/core/files/rag/chunk/chunking.js +0 -117
  116. package/dist-lib/lib/core/files/rag/chunk/metadata.d.ts +0 -30
  117. package/dist-lib/lib/core/files/rag/chunk/metadata.js +0 -89
  118. package/dist-lib/lib/core/files/rag/chunk/tokenizer.d.ts +0 -7
  119. package/dist-lib/lib/core/files/rag/chunk/tokenizer.js +0 -18
  120. package/dist-lib/lib/core/files/rag/extract/csv-text.d.ts +0 -1
  121. package/dist-lib/lib/core/files/rag/extract/csv-text.js +0 -117
  122. package/dist-lib/lib/core/files/rag/extract/document-types.d.ts +0 -22
  123. package/dist-lib/lib/core/files/rag/extract/document-types.js +0 -152
  124. package/dist-lib/lib/core/files/rag/extract/extract.d.ts +0 -17
  125. package/dist-lib/lib/core/files/rag/extract/extract.js +0 -81
  126. package/dist-lib/lib/core/files/rag/extract/html-table-text.d.ts +0 -1
  127. package/dist-lib/lib/core/files/rag/extract/html-table-text.js +0 -125
  128. package/dist-lib/lib/core/files/rag/extract/html-text.d.ts +0 -1
  129. package/dist-lib/lib/core/files/rag/extract/html-text.js +0 -132
  130. package/dist-lib/lib/core/files/rag/extract/pdf-platform.d.ts +0 -17
  131. package/dist-lib/lib/core/files/rag/extract/pdf-platform.js +0 -141
  132. package/dist-lib/lib/core/files/rag/extract/pdf-text.d.ts +0 -12
  133. package/dist-lib/lib/core/files/rag/extract/pdf-text.js +0 -43
  134. package/dist-lib/lib/core/files/rag/extract/rtf-text.d.ts +0 -1
  135. package/dist-lib/lib/core/files/rag/extract/rtf-text.js +0 -15
  136. package/dist-lib/lib/core/files/rag/extract/text-decoding.d.ts +0 -1
  137. package/dist-lib/lib/core/files/rag/extract/text-decoding.js +0 -91
  138. package/dist-lib/lib/core/files/rag/extract/types.d.ts +0 -36
  139. package/dist-lib/lib/core/files/rag/extract/types.js +0 -12
  140. package/dist-lib/lib/core/files/rag/extract/utf.d.ts +0 -2
  141. package/dist-lib/lib/core/files/rag/extract/utf.js +0 -18
  142. package/dist-lib/lib/core/files/rag/retrieval/citation-match.d.ts +0 -2
  143. package/dist-lib/lib/core/files/rag/retrieval/citation-match.js +0 -16
  144. package/dist-lib/lib/core/files/rag/retrieval/coverage.d.ts +0 -4
  145. package/dist-lib/lib/core/files/rag/retrieval/coverage.js +0 -48
  146. package/dist-lib/lib/core/files/rag/retrieval/diversity.d.ts +0 -10
  147. package/dist-lib/lib/core/files/rag/retrieval/diversity.js +0 -37
  148. package/dist-lib/lib/core/files/rag/retrieval/floor.d.ts +0 -5
  149. package/dist-lib/lib/core/files/rag/retrieval/floor.js +0 -21
  150. package/dist-lib/lib/core/files/rag/retrieval/format.d.ts +0 -6
  151. package/dist-lib/lib/core/files/rag/retrieval/format.js +0 -21
  152. package/dist-lib/lib/core/files/rag/retrieval/knowledge.d.ts +0 -2
  153. package/dist-lib/lib/core/files/rag/retrieval/knowledge.js +0 -54
  154. package/dist-lib/lib/core/files/rag/retrieval/notices.d.ts +0 -16
  155. package/dist-lib/lib/core/files/rag/retrieval/notices.js +0 -27
  156. package/dist-lib/lib/core/files/rag/retrieval/scoring.d.ts +0 -8
  157. package/dist-lib/lib/core/files/rag/retrieval/scoring.js +0 -82
  158. package/dist-lib/lib/core/files/rag/retrieval/search.d.ts +0 -3
  159. package/dist-lib/lib/core/files/rag/retrieval/search.js +0 -49
  160. package/dist-lib/lib/core/files/rag/retrieval/selection.d.ts +0 -11
  161. package/dist-lib/lib/core/files/rag/retrieval/selection.js +0 -93
  162. package/dist-lib/lib/core/files/rag/retrieval/source-tag-filter.d.ts +0 -6
  163. package/dist-lib/lib/core/files/rag/retrieval/source-tag-filter.js +0 -79
  164. package/dist-lib/lib/core/files/rag/retrieval/sources.d.ts +0 -13
  165. package/dist-lib/lib/core/files/rag/retrieval/sources.js +0 -20
  166. package/dist-lib/lib/core/files/rag/retrieval/target.d.ts +0 -13
  167. package/dist-lib/lib/core/files/rag/retrieval/target.js +0 -89
  168. package/dist-lib/lib/core/files/rag/retrieval/terms.d.ts +0 -8
  169. package/dist-lib/lib/core/files/rag/retrieval/terms.js +0 -70
  170. package/dist-lib/lib/core/files/rag/retrieval/types.d.ts +0 -29
  171. package/dist-lib/lib/core/files/rag/retrieval/types.js +0 -1
  172. package/dist-lib/lib/core/files/rag/retrieval/web-sources.d.ts +0 -8
  173. package/dist-lib/lib/core/files/rag/retrieval/web-sources.js +0 -41
  174. package/dist-lib/lib/core/files/rag/retrieval/whole-document-query.d.ts +0 -1
  175. package/dist-lib/lib/core/files/rag/retrieval/whole-document-query.js +0 -96
  176. package/dist-lib/lib/core/files/rag/vector/memory.d.ts +0 -15
  177. package/dist-lib/lib/core/files/rag/vector/memory.js +0 -135
  178. package/dist-lib/lib/core/files/rag/vector/types.d.ts +0 -28
  179. package/dist-lib/lib/core/files/rag/vector/types.js +0 -1
  180. package/dist-lib/lib/integrations/oauth-providers.d.ts +0 -14
  181. package/dist-lib/lib/integrations/oauth-providers.js +0 -116
  182. package/dist-lib/lib/oauth/asana.d.ts +0 -35
  183. package/dist-lib/lib/oauth/asana.js +0 -71
  184. package/dist-lib/lib/oauth/google.d.ts +0 -37
  185. package/dist-lib/lib/oauth/google.js +0 -77
  186. package/dist-lib/lib/oauth/notion.d.ts +0 -34
  187. package/dist-lib/lib/oauth/notion.js +0 -82
  188. package/dist-lib/lib/oauth/spotify.d.ts +0 -32
  189. package/dist-lib/lib/oauth/spotify.js +0 -74
  190. package/dist-lib/lib/oauth/verify.d.ts +0 -8
  191. package/dist-lib/lib/oauth/verify.js +0 -58
@@ -1,243 +0,0 @@
1
- ---
2
- name: pr-create
3
- description: Write the title, body and commits for a pull request in @qvac/core, and decide the conventional-commit type for a change — `fix` is reserved for user-facing defects in a released version. Use when opening a PR here, splitting work into a stack, or choosing between `fix` and `chore`.
4
- ---
5
-
6
- # PR creation
7
-
8
- `@qvac/core` is a published package. The log is the only durable record of intent,
9
- and for this repo it is also the changelog a consumer reads before upgrading.
10
-
11
- ## Title
12
-
13
- ```
14
- type(scope): subject
15
- ```
16
-
17
- Imperative, lowercase after the colon, no trailing period. Scope optional, and
18
- only when it narrows something real. What and why, not how.
19
-
20
- ```
21
- feat: publish the sidecar entry, so spawning it needs no bundle
22
- fix(publish): repoint dynamic imports at dist-lib too
23
- refactor: own the schema codegen tooling
24
- chore: regenerate the schema
25
- ```
26
-
27
- There is no ticket prefix here, and no title validator in CI. That is not
28
- licence to be loose: nothing will catch a bad title but a reviewer.
29
-
30
- ## Types
31
-
32
- ```
33
- build chore ci docs style refactor perf test fix feat
34
- ```
35
-
36
- **`fix` is reserved for a defect a consumer of a released version could hit.**
37
- It is the line someone reads to decide whether to upgrade, so it claims real
38
- breakage in something already published.
39
-
40
- | The change | Type |
41
- | ----------------------------------------------------------- | -------------------------------------------------- |
42
- | Breaks a consumer on a published version | `fix` |
43
- | Repairs code that has never shipped (same release cycle) | `chore` |
44
- | Repairs the build, the bundle, or what lands in the tarball | `build` or `fix` if a published artifact was wrong |
45
- | Repairs CI, a workflow, an action pin | `ci` |
46
- | Repairs or adds a test | `test` |
47
- | Repairs a lint/type error | `chore` |
48
- | Pure move or rename, no behaviour change | `refactor` |
49
- | New capability, new export, new flag | `feat` |
50
- | README, comments, docs | `docs` |
51
-
52
- When a repair is on unreleased code, check the last release tag: if the bug was
53
- never in a published version, it is `chore`, not `fix`.
54
-
55
- Never relabel a real defect as `chore` to make the log quieter, and never
56
- inflate a cleanup into `fix` to make it look urgent.
57
-
58
- ## Scopes
59
-
60
- Optional, and taken from what the diff actually touches — `lib`, `tui`, `schema`, `spec`, `scripts`, `test`, `ci`, `publish`, or a domain name (`mesh`, `sync`, `assistant`, `storage`).
61
- A scope that restates the type (`fix(fix)`) or names the whole repo adds
62
- nothing; leave it off.
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
-
104
- ## Decision records
105
-
106
- `docs/decisions/` holds the durable, non-obvious choices — why a boundary is
107
- where it is, why an approach was rejected. They are reference for a future
108
- reader, **not rules, and not to be loaded by default**.
109
-
110
- Add one when this PR settles something a later reader would otherwise have to
111
- reverse-engineer from the diff: a runtime or storage boundary, a wire-format or
112
- schema choice, a build or publish constraint, a rejected alternative that will
113
- look obvious later. Do not add one for a bug fix, a rename, or anything the code
114
- already says plainly.
115
-
116
- Copy `docs/decisions/TEMPLATE.md`, give it a `status`, list it once in
117
- `INDEX.md`, and name it in the PR's Decisions section. `node
118
- scripts/docs-audit.cjs` checks all of that, and CI runs it.
119
-
120
- An **active** record may cite only paths that exist here; a path in another
121
- repository is written `@qvac/harness → lib/x.ts` so the audit treats it as
122
- context rather than a local file. A superseded record is exempt — it describes
123
- how things used to be.
124
-
125
- ### One PR, one type
126
-
127
- The commits carry conventional-commit types, so the mix of types _is_ the scope
128
- statement. `feat:`, `fix:` and `chore:` on one branch is not a well-rounded
129
- change, it is three changes sharing a branch, and a reviewer has to hold all
130
- three while judging any one of them.
131
-
132
- List them before writing the body:
133
-
134
- ```bash
135
- git log --format='%s' main..HEAD | grep -oE '^[a-z]+' | sort -u
136
- ```
137
-
138
- - **One type** is the PR's type.
139
- - **A dominant type plus its own tests or docs** (`feat` + `test`, `fix` +
140
- `docs`) is fine; the dominant one wins.
141
- - **Unrelated types** means split the PR, or stack it.
142
-
143
- ## Small PRs, stacked
144
-
145
- A PR is read by a human, so it has to fit in one head. Default to one concern.
146
- When a change decomposes into dependent steps, do not grow one PR to fit them —
147
- stack them, so each step is reviewable alone and lands in order.
148
-
149
- - A large refactor belongs on a `refactor/...` branch with `refactor:` commits.
150
- - **Refactor commits never live inside a non-refactor branch.** A `feat/` branch
151
- that also reshuffles unrelated code is two PRs. Behaviour changes and pure
152
- moves are reviewed differently, and mixing them hides both.
153
- - A pure rename or move lands _before_ the change that depends on it, as its own
154
- commit or its own PR in the stack.
155
-
156
- Branch names must never contain `codex`, `cursor`, or `claude` (case
157
- insensitive). Use a neutral name before committing or pushing.
158
-
159
- ## Body
160
-
161
- `.github/pull_request_template.md` pre-fills the headings. Keep its shape, fill
162
- what applies, and delete the sections that would be empty — an absent section
163
- says more than one saying "n/a". The template's own order is Why, What, Testing,
164
- Decisions; the expanded form below is what each should contain.
165
-
166
- ```markdown
167
- ## What
168
-
169
- One paragraph. The change, in the reviewer's terms.
170
-
171
- ## Why
172
-
173
- The problem this solves, or the decision it implements. Link the issue,
174
- PR, or upstream change that forced it.
175
-
176
- ## How
177
-
178
- Only the parts a reader would not infer from the diff: the seam that moved,
179
- the invariant being preserved, the thing that looks wrong but isn't.
180
-
181
- ## Testing
182
-
183
- What you ran, and what it proved. ``bun run test` (node, bare and addon lanes)` at minimum.
184
- Say plainly when something could not be tested locally and why.
185
- ```
186
-
187
- For a **breaking change**, say so in the body under its own `## Breaking`
188
- heading, with the migration a consumer has to perform. Published package —
189
- this is the only warning they get.
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
-
213
- ## Before opening
214
-
215
- 1. Check the branch is not `main` and the name is neutral.
216
- 2. `git log --oneline main..HEAD` — every commit is a conventional commit, and
217
- each one is a change you would defend on its own. A trail of `wip`,
218
- `fixup` or `address review` commits is not history; reshape it before
219
- opening.
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
222
- red PR wastes a reviewer's round trip.
223
- 5. Rebase on `main` rather than merging it in. A merge commit in the branch
224
- makes the diff unreadable.
225
- 6. Open as a **draft** unless you are asking for review right now.
226
-
227
- ```bash
228
- gh pr create --repo tetherto/qvac-core --draft --title "type(scope): subject" --body-file <path>
229
- ```
230
-
231
- Never push to `main`, never force-push a branch someone else is reviewing, and
232
- never open a PR that carries commits you did not write without saying so.
233
-
234
- ## Version bumps
235
-
236
- Release PRs in this repo are titled by version alone (`0.2.4 (#32)`,
237
- `release/0.1.4 (#40)`). They carry the version bump and nothing else — do not
238
- fold a bump into a feature PR, and do not fold a feature into a bump.
239
-
240
- ## Sibling skills
241
-
242
- - Reviewing a PR or a local diff → **pr-review**.
243
- - How the code itself should be shaped → **js-house-style**.
@@ -1,428 +0,0 @@
1
- ---
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 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
- ---
5
-
6
- # PR review
7
-
8
- Reviews changes in `@qvac/core`. Two modes.
9
-
10
- - **PR mode** (a PR number or URL) — a short overview in chat, then a **pending**
11
- GitHub review of per-file inline comments. The pending review is created only
12
- after the user confirms the exact set of comments. **Never submit the review
13
- event** (`COMMENT`, `REQUEST_CHANGES`, `APPROVE`) — that is the user's call,
14
- from the GitHub UI.
15
- - **Local mode** (`local`, or "review my changes") — the overview in chat only.
16
- Posts nothing, anywhere.
17
-
18
- ## Reviewing is read-only
19
-
20
- This skill never writes to the working tree. Against the user's repo these are
21
- forbidden, whatever the reason:
22
-
23
- - `git switch`, `git checkout`, `git reset`, `git restore`, `git clean`
24
- - `git stash`, in any form
25
- - `git pull`, `git merge`, `git rebase`, `git cherry-pick`
26
- - `gh pr checkout`
27
- - any edit to a file
28
-
29
- Local mode reads the diff with `git diff`, `git status` and `git ls-files`, and
30
- nothing else. If the tree is dirty in a way that makes the diff hard to read, say
31
- so and let the user decide; never tidy it yourself. A review that loses
32
- uncommitted work is worse than no review.
33
-
34
- PR mode needs no checkout at all: `gh pr diff` gives the patch, and
35
- `gh api repos/{owner}/{repo}/contents/{path}?ref={sha}` gives any file at the PR
36
- head.
37
-
38
- ## Gather
39
-
40
- PR mode:
41
-
42
- ```bash
43
- gh pr view <num> --repo tetherto/qvac-core \
44
- --json title,body,author,headRefName,headRefOid,baseRefName,files,additions,deletions,state,isDraft,mergeable,statusCheckRollup \
45
- > /tmp/pr-<num>.json
46
- gh pr diff <num> --repo tetherto/qvac-core --patch > /tmp/pr-<num>.patch
47
- ```
48
-
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.
53
-
54
- Local mode. The default scope is everything uncommitted — staged, unstaged and
55
- untracked:
56
-
57
- ```bash
58
- git diff --staged > /tmp/local-staged.patch
59
- git diff > /tmp/local-unstaged.patch
60
- git status --porcelain=v1
61
- git ls-files --others --exclude-standard # untracked, easy to miss
62
- ```
63
-
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.
75
-
76
- ## CI
77
-
78
- One workflow gates this repo: **Integrate** (`.github/workflows/ci.yml`), a
79
- single `Lint & Tests` job. `publish.yml` runs on release, not on PRs.
80
-
81
- Its steps are each a separate way to fail, and the last three catch what a
82
- local `bun run test` does not:
83
-
84
- | Step | Command | Fails when |
85
- | ------------------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
86
- | Lint | `bun run lint` | prettier, lunte or `tsc --noEmit` |
87
- | Schema is regenerated | `bun run build:schema` | `spec/` is dirty after codegen — someone hand-edited it, or forgot to commit the regeneration |
88
- | Tests | `bun run test` | the node, bare and addon lanes |
89
- | Library surface compiles | `bun run build:lib` | the compiled export surface breaks |
90
-
91
- A PR that touches `schema/` and leaves `spec/` stale is the most common red
92
- here, and it looks nothing like a test failure.
93
-
94
- Read the result from `statusCheckRollup` in `/tmp/pr-<num>.json`, and pull logs
95
- only for a job that actually failed:
96
-
97
- ```bash
98
- gh run view --repo tetherto/qvac-core --log-failed --job <id> > /tmp/pr-<num>-<id>.log
99
- ```
100
-
101
- A red `Integrate` is a blocking finding on its own. Read the failing job's log
102
- before writing a single line of review — half of what looks like a design
103
- problem is a lint rule.
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
-
117
- ## What to check, in order
118
-
119
- Stop at the first tier that produces findings worth the author's time; a review
120
- that lists twelve nits under a broken contract has buried the real thing.
121
-
122
- **1. Correctness.** Does it do what the title claims? Trace the changed path
123
- end to end, including the error path. Look for: a promise not awaited, a
124
- listener never removed, a resource opened on one path and closed on another, an
125
- error swallowed into a default.
126
-
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
159
- is a promise to a consumer.
160
-
161
- - Anything added to or changed in the export map, `index.ts`, `types/`, or
162
- `package.json#exports` — is it intentional, and is it a breaking change?
163
- - `schema/` or `spec/` changes: is the wire format still compatible, and was the
164
- baseline regenerated (`bun run build:schema`) rather than hand-edited?
165
- - Does the change match its own type declarations, and do callers in this repo
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.
171
-
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.
176
-
177
- **5. Tests.** A behaviour change with no test is a finding. Name the missing
178
- case rather than asking for "more tests": the tests live under `test/`, run on
179
- both the node and bare lanes, and a fix without a regression guard will come
180
- back.
181
-
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
196
- defect a consumer of a released version could hit), or is it `chore` on code
197
- that never shipped? Is the title imperative and specific? Does the branch name
198
- avoid `codex` / `cursor` / `claude`?
199
-
200
- **8. Scope.** Does the PR do one thing? A behaviour change mixed with an
201
- unrelated rename is two PRs — say so, and say which commit to split out.
202
-
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.
222
-
223
- ### Do not over-engineer the review
224
-
225
- The most damaging thing a review can do is talk a good PR into a worse one. AI
226
- review skews defensive: a guard here, an abstraction there, a layer to absorb a
227
- hypothetical, each one permanent debt bolted to a problem that never happened.
228
- That runs directly against the house style, which does not program defensively.
229
-
230
- It compounds. Successive reviews each add a layer against a different
231
- speculative case, one review's fix undoes another's, and the code ends up in a
232
- corner nobody chose.
233
-
234
- - **Only raise what is wrong now**, or has a concrete path to being wrong.
235
- "Someone could later..." is not a finding.
236
- - **Never propose a guard, wrapper, fallback or abstraction** whose only job is
237
- to make a hypothetical safe. Let caller bugs crash; that is the contract.
238
- - **Prefer the fix that deletes code.** If your suggestion makes the diff
239
- bigger, be sure it earns it.
240
- - **Simplification is a valid finding; speculative hardening is not.**
241
- - When you cannot tell whether something is real, ask instead of requesting a
242
- change, and be willing to land zero findings.
243
-
244
- ## Write the findings
245
-
246
- Each finding: the file and line, what breaks, and the concrete scenario that
247
- breaks it. No finding without a failure mode you can state.
248
-
249
- Lead with the findings, ordered by severity.
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
-
276
- ### Severity tags
277
-
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".
281
-
282
- - `[P1]` — almost-certain bug, data corruption, security issue, CI breaker, or a
283
- break of behaviour a consumer relies on. In the overview, and **proposed inline
284
- by default**.
285
- - `[P2]` — likely bug, non-obvious caveat, contract or API mismatch, subtle
286
- behaviour change, missing test on a risky path. In the overview, and **proposed
287
- inline by default**.
288
- - `[P3]` — minor: a stale comment or doc, an ergonomic improvement, an optional
289
- cleanup. In the overview when material, and **not proposed inline** unless the
290
- user asks for them.
291
-
292
- **Never silently put a `[P3]` in the inline payload.** A review that posts ten
293
- nits inline teaches the author to skim the next one.
294
-
295
- **Severity is what the code does today, not what it might do.** A finding whose
296
- only support is a scenario nobody has hit is not a `[P2]`: either find the path
297
- that reaches it, or drop it — do not park it at `[P3]` instead. Zero findings is
298
- a legitimate result.
299
-
300
- If the user says this is a re-review, say explicitly which earlier concerns are
301
- resolved and which still stand.
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
-
383
- ## Posting (PR mode only)
384
-
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.
391
- 2. Ask the user to confirm the exact set. Wait for a clear yes.
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:
406
-
407
- ```bash
408
- gh api repos/tetherto/qvac-core/pulls/<num>/reviews \
409
- --method POST --input /tmp/pr-<num>-review.json
410
- ```
411
-
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.
417
-
418
- If the user edits the selection after the preview, rewrite the file before
419
- running the command.
420
-
421
- 6. Hand the user the link and stop:
422
- `https://github.com/tetherto/qvac-core/pull/<num>#pullrequestreview-<id>`
423
-
424
- ## Sibling skills
425
-
426
- - Writing the PR being reviewed → **pr-create**.
427
- - The rules tier 4 reviews against → **js-house-style**. Load it; do not review
428
- from memory of it.