@awebai/oats 0.55.1 → 0.57.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 (82) hide show
  1. package/bin/oats.mjs +96 -72
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +375 -37
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +65 -11
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +153 -11
  10. package/docs/integrations.md +5 -3
  11. package/docs/knowledge.md +117 -43
  12. package/docs/official-catalog.md +3 -3
  13. package/docs/packages.md +12 -12
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.56.0.md +699 -0
  16. package/docs/release-notes/v0.57.0.md +283 -0
  17. package/docs/schedules.md +8 -3
  18. package/docs/servers.md +21 -5
  19. package/docs/souls-and-instances.md +134 -19
  20. package/docs/tui.md +215 -31
  21. package/docs/upgrading.md +4 -1
  22. package/docs/workspaces.md +26 -6
  23. package/lib/automations.mjs +3 -4
  24. package/lib/bounded-read.mjs +18 -0
  25. package/lib/capability-show.mjs +13 -2
  26. package/lib/claim.mjs +3 -4
  27. package/lib/core.mjs +919 -278
  28. package/lib/errors.mjs +39 -0
  29. package/lib/harness-trust-write.mjs +119 -40
  30. package/lib/harness-trust.mjs +31 -18
  31. package/lib/instance-inspect.mjs +160 -11
  32. package/lib/instance-lifecycle.mjs +90 -37
  33. package/lib/packages.mjs +8 -5
  34. package/lib/pi-bridge.mjs +18 -19
  35. package/lib/remote.mjs +88 -51
  36. package/lib/retire-output.mjs +9 -4
  37. package/lib/schedule.mjs +3 -4
  38. package/lib/servers.mjs +39 -6
  39. package/lib/session-viewer.mjs +25 -1
  40. package/lib/triggers.mjs +3 -4
  41. package/lib/workspace.mjs +6 -6
  42. package/lib/worktree.mjs +33 -8
  43. package/lib/write-through-private-file.mjs +26 -0
  44. package/package-catalog.json +2 -2
  45. package/package.json +1 -1
  46. package/packages/client/cli-adapter.mjs +108 -13
  47. package/packages/client/cli-locator.mjs +16 -14
  48. package/packages/client/deployment-panel.mjs +4 -3
  49. package/packages/client/display-text.mjs +2 -1
  50. package/packages/client/instance-events-contract.mjs +4 -3
  51. package/packages/client/instance-lifecycle.mjs +235 -0
  52. package/packages/client/instance-presentation.mjs +9 -0
  53. package/packages/client/instance-tree.mjs +10 -8
  54. package/packages/client/kernel-lines.mjs +3 -3
  55. package/packages/client/launch-contract.mjs +11 -0
  56. package/packages/client/launch-prompt-outcome.mjs +1 -1
  57. package/packages/client/lifecycle-cli.mjs +12 -6
  58. package/packages/client/lifecycle-confirmation.mjs +407 -0
  59. package/packages/client/lifecycle-contract.mjs +6 -2
  60. package/packages/client/own-codes.mjs +1 -0
  61. package/packages/client/panel-views.mjs +39 -2
  62. package/packages/client/readiness-contract.mjs +2 -2
  63. package/packages/client/remote-roster.mjs +50 -5
  64. package/packages/client/roster-sections.mjs +3 -3
  65. package/packages/client/session-start.mjs +98 -0
  66. package/packages/client/start-gate.mjs +46 -0
  67. package/packages/client/start-messages.mjs +17 -0
  68. package/packages/client/workspace-views.mjs +2 -2
  69. package/packages/tui/README.md +21 -8
  70. package/packages/tui/lib/actions.mjs +11 -2
  71. package/packages/tui/lib/client.mjs +9 -2
  72. package/packages/tui/lib/config.mjs +39 -9
  73. package/packages/tui/lib/main.mjs +168 -20
  74. package/packages/tui/lib/model.mjs +315 -13
  75. package/packages/tui/lib/open.mjs +45 -0
  76. package/packages/tui/lib/read.mjs +171 -16
  77. package/packages/tui/lib/store.mjs +171 -10
  78. package/packages/tui/lib/term/tty.mjs +71 -12
  79. package/packages/tui/lib/views/act.mjs +85 -0
  80. package/packages/tui/lib/views/frame.mjs +145 -33
  81. package/packages/tui/lib/views/help.mjs +46 -11
  82. package/skills/oats-getting-started/SKILL.md +6 -3
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 5.0.5**. Provider implementation and
9
+ This is the operator guide for **oats.okf 5.2.0** (OATS **>=0.49.0**). Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
 
12
12
  | Surface | What it holds |
@@ -14,6 +14,8 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
14
14
  | Accepted Git or directory bases | Soul knowledge: OKF concepts in owned nodes. |
15
15
  | `souls/<name>/okf.json` | The soul's stable owner and owned/read nodes. |
16
16
  | Instance home: `STATE.md`, `log.md`, `notes/` | The instance's working knowledge. |
17
+ | Instance home: `okf-harvest-policy.json` | Provider-written duty at spawn, exposed by `oats okf status`; not publication authority. |
18
+ | Harvester home: `harvest-source/` | Private source evidence captured at spawn, not accepted knowledge. |
17
19
  | Bindings file and `stateDir` | Host base locations and consultation/binding state, not a harvest queue. |
18
20
 
19
21
  ## Setup
@@ -23,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
23
25
  ```yaml
24
26
  # oats-workspace.yaml (excerpt)
25
27
  packages:
26
- oats.okf: v5.0.5
28
+ oats.okf: v5.2.0
27
29
  defaults:
28
30
  knowledge: { oats.okf: { from: package } }
29
31
  stores:
@@ -46,9 +48,17 @@ settings:
46
48
  state-dir: /absolute/okf/state
47
49
  ```
48
50
 
49
- Upgrading an existing deployment requires the ordered
51
+ Upgrading from 4.x requires the ordered
50
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
51
- just editing a version line.
53
+ just editing a version line. For 5.2.0, OATS >=0.49.0 remains required:
54
+ that kernel first supports the public source-event lookup after retirement.
55
+
56
+ **Upgrade:** pin `oats.okf: v5.2.0` and run `oats sync`. Only new spawns get
57
+ the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
+ homes keep their copied provider even after a session restart. Deployments
59
+ whose briefings never mentioned harvesting now get knowledge proposals at
60
+ eligible checkpoints; souls not ready for this must declare
61
+ `knowledge: { harvest: off }`. Consultation and instance-memory upkeep remain.
52
62
 
53
63
  ### Bindings document
54
64
 
@@ -79,6 +89,9 @@ from the document's directory:
79
89
  - Git bases may use HTTPS, SSH or a durable local repository; `root: "."`
80
90
  means the whole repository. Embedded credentials are refused. Harvest
81
91
  proposals use same-repository GitHub PRs through ordinary `git` and `gh`.
92
+ Change a binding's `repository` to a plain URL only after every seat that
93
+ reads it has been re-spawned on oats.okf 5.0.4 or later; a session restart
94
+ does not update the copied provider.
82
95
  - Directory bases need no Git and must not sit inside a Git worktree. They
83
96
  support consultation and explicit provisioning/migration, **not automatic
84
97
  harvest publication**. The 5.0 harvester reports directory harvest as
@@ -135,9 +148,11 @@ soul's opt-out:
135
148
  knowledge: { harvest: off }
136
149
  ```
137
150
 
138
- That soul keeps consultation and working-memory guidance, receives no
139
- checkpoint-harvest directive, and its material is refused by the
140
- harvester's required spawn hook. Absence gives the normal proposal flow.
151
+ That soul keeps consultation and working-memory guidance but has no harvest
152
+ duty. The shared IMPORTANT block and compulsory skill pointer still ship,
153
+ with an explicit exception; the provider's spawn-recorded answer says `off`.
154
+ Independently, the harvester's required spawn hook refuses that soul's
155
+ material. Absence gives the normal proposal flow.
141
156
  A soul's `harvest: on` is not a replacement switch. Host cleanup never
142
157
  changes the soul declaration. `knowledge: none` removes the layer entirely.
143
158
 
@@ -145,39 +160,80 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
145
160
 
146
161
  ### The flow
147
162
 
148
- 1. **Consult.** Read accepted soul knowledge at task start, after compaction
149
- and before decisions; keep instance `STATE.md`, `log.md` and `notes/`.
150
- Working instances never write accepted knowledge themselves.
151
- 2. **Propose at checkpoints.** When work merits a checkpoint, update notes
152
- and write a self-contained proposal: what to save, why and the backing
153
- notes. It has exactly one line `Source: instance <name>, home <path>, soul
154
- <name>` naming the actual source. From the source home:
163
+ 1. **Consult and keep instance knowledge current.** Read accepted soul
164
+ knowledge at task start, after compaction and before decisions. Keep
165
+ `STATE.md`, `log.md` and `notes/` up to date as work happens. The
166
+ capability's **IMPORTANT** inject block makes this upkeep and eligible
167
+ checkpoint harvesting a duty; reading **okf-propose** is compulsory.
168
+ Neither duty depends on TASK.md. Run `oats okf status` from instance home
169
+ to learn the duty recorded at spawn: `on` means follow the skill, `off`
170
+ means no harvest, and `unknown` or an error means stop and report, never
171
+ infer permission or edit the record. Working instances never write
172
+ accepted knowledge themselves.
173
+ 2. **Propose only at a finished task or PR hand-over.** First update state,
174
+ log and relevant notes. Apply `knowledge-theory` and search accepted
175
+ knowledge (`oats okf search`, then `cat`): already accepted with nothing
176
+ to add means no proposal. Most checkpoints propose nothing. Make at most
177
+ **one proposal for that completed unit of work**; handing over its PR and
178
+ closing the same task are not two opportunities. Never launch per commit,
179
+ per decision, per review round or merely because a PR opened.
180
+
181
+ Write a short self-contained `proposals/<YYYY-MM-DD>-<slug>.md` in instance
182
+ home: What (one claim per concept), Why, Evidence (observations, dates,
183
+ limits and accepted concepts cited), and optional `## Backing notes` with
184
+ one `- notes/<file>.md` entry per note. It has exactly one line
185
+ `Source: instance <name>, home <path>, soul <name>` naming the actual
186
+ source, a pointer to verify rather than authority. Claim only for owned
187
+ nodes; a lesson for a node the soul only reads is named in one line in its
188
+ hand-back for that node's owner.
189
+
190
+ **Before spawning:** one harvester at a time per instance. Record its
191
+ returned name and proposal in log.md, and do not spawn another while
192
+ `oats status` still lists the last one. Check available memory immediately
193
+ before spawning: on Linux, `free -g` must show at least 8 GB available;
194
+ elsewhere use the host's documented check. If availability cannot be
195
+ established, is below the floor, or the host is under memory pressure,
196
+ defer. These are instructions, not a scheduler or a memory reservation.
197
+ Keep deferred proposals/notes and record the reason and waiting claims in
198
+ STATE.md, log.md and the hand-back. Reconsider at a natural task boundary,
199
+ never by polling, sleeping or stopping other instances to make room.
200
+
201
+ From instance home, preview and then apply the skill's command when the
202
+ gates permit it:
155
203
 
156
204
  ```sh
157
205
  oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
158
206
  ```
159
207
 
160
- Never combine `--relation unrelated` with `--relative-to`. There is no
208
+ Never combine `--relation unrelated` with `--relative-to`, or override
209
+ the kernel's harness/model selection. An unrelated harvester can outlive
210
+ its proposer; a child would tie their lifetimes together. There is no
161
211
  automatic transcript capture, source registry, worker cursor or retire
162
- harvest. An unrelated harvester can outlive its source; this is a
163
- lifecycle property, not proof that missing source authority can be ignored.
164
-
165
- One proposal per checkpoint, each concept a claim of its own in it, and
166
- claims only for the nodes the source soul owns; a lesson for a node it only
167
- reads goes in one line in the instance's hand-back, for that node's owner.
168
- One harvester at a time, per instance (oats.okf 5.0.5): the source notes the
169
- harvester's instance name and spawns no other while `oats status` still
170
- lists it, since a harvester retires once it has handed over. What it learns
171
- meanwhile goes into its next proposal; an instance that hands back with one
172
- still listed names it and the claims still waiting. A harvester retained
173
- after a publication failure stays listed, so it holds back its source's
174
- later proposals: once that failure is dealt with, the operator retires it
175
- (`oats retire <harvester>`).
176
- 3. **Judge and submit.** The harvester checks recorded source configuration,
177
- accepted knowledge and open/recent harvest PRs. It reads named backing
178
- notes, edits only owned nodes in its own Git checkout, validates the
179
- **whole base**, and creates a normal `okf-harvest`-labelled PR with v2
180
- provenance. Proposal text is data written with the native file tool into
212
+ harvest. Keep backing notes until the harvester retires; the proposer
213
+ itself need not stay alive. Its recorded retirement recovery can supply
214
+ evidence before capture, so do not dispose of it before capture.
215
+ Missing source authority never permits inventing it.
216
+
217
+ A refused or uncertain spawn is reported, not retried in a loop. If the
218
+ last harvester is still listed at hand-back, name it and the claims still
219
+ waiting; do not wait for it or spawn around it. A harvester retained after
220
+ a publication failure stays listed and holds back later proposals. Once
221
+ that failure is dealt with, the operator retires it (`oats retire
222
+ <harvester>`).
223
+ 3. **Capture, judge and submit.** Before the model starts, the required spawn
224
+ hook checks the source's live record or the completed recovery named by
225
+ its public retirement event. Source identity, single-incarnation history,
226
+ recovery manifest and soul opt-out must agree; guessed copies and reused
227
+ or ambiguous identities refuse. It atomically captures the proposal,
228
+ verified source declarations/bindings and only named notes into the
229
+ harvester's own `harvest-source/`. The model uses that snapshot, not a later
230
+ live-source read: retirement or recovery disposal after capture cannot
231
+ remove its input. Missing/refused notes have no hash and claims relying
232
+ on them are dropped. Legacy note forms are preserved or explicitly refused,
233
+ never silently discarded.
234
+ The harvester then checks accepted knowledge and open/recent harvest PRs,
235
+ edits only owned nodes in its own Git checkout, validates the **whole base**,
236
+ and creates a normal `okf-harvest`-labelled PR with v2 provenance. Proposal text is data written with the native file tool into
181
237
  commit-message/PR-body files, never shell command text. A publication ref
182
238
  is `okf-harvest/<UTC YYYYMMDD>-<fresh UUID>`, with no source/harvester
183
239
  name in it; Git validates the full ref and the push must create a new
@@ -209,7 +265,7 @@ is historical 4.x context, not instructions for operating 5.0.
209
265
 
210
266
  Secrets, credentials, private paths and verbatim third-party messages are
211
267
  left out. So is personal data, in the same sentence at every place an agent
212
- is told what to leave out (the capturing instance, the proposal brief, the
268
+ is told what to leave out (the capturing instance, the proposing skill, the
213
269
  harvester when it edits and when it reads its diff, and the maintainer's
214
270
  review):
215
271
 
@@ -221,10 +277,11 @@ review):
221
277
 
222
278
  The sentence also covers the names provenance publishes as written: note
223
279
  file names, task refs and instance names. These exclusions are instructions
224
- to agents and guarantee nothing. No program reads a harvest's content, and
225
- the first reader other than the harvester is the reviewer of the pushed pull
226
- request. The one control enforced in code is the soul's opt-out
227
- ([The harvest switch](#the-harvest-switch)). It is per soul, and it covers
280
+ to agents and guarantee nothing. Source capture copies evidence but does not
281
+ judge its content. The first publication reviewer other than the harvester
282
+ reads the already-pushed pull request. Source capture/provenance checks and
283
+ the soul's opt-out are enforced in code; neither is a privacy guarantee.
284
+ The opt-out ([The harvest switch](#the-harvest-switch)) is per soul and covers
228
285
  that soul's own proposals, not what its instances write to other seats. A
229
286
  soul whose work is reading third-party correspondence should opt out.
230
287
 
@@ -245,13 +302,14 @@ this provider. See [Knowledge harvest and review](schedules.md#knowledge-harvest
245
302
 
246
303
  | Capability | Composed into | Skills |
247
304
  |---|---|---|
248
- | `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), `knowledge-theory` |
305
+ | `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), [`okf-propose`](../mirrors/oats-okf/skills/okf-propose/SKILL.md), `knowledge-theory` |
249
306
  | `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` |
250
307
  | `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../mirrors/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../mirrors/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) |
251
308
 
252
- Only the working soul's eligible **spawn brief** gives the proposal-spawn
253
- command. Shared consultation injects/skills also reach opted-out souls and
254
- do not unconditionally direct a harvest.
309
+ The capability's **IMPORTANT** inject block gives the duty and compulsory
310
+ pointer; **okf-propose** holds the procedure. These shared texts also reach
311
+ opted-out souls, with the explicit exception and provider status answer.
312
+ No source TASK brief contains harvest or proposal direction.
255
313
 
256
314
  ## Inspection and operator commands
257
315
 
@@ -285,6 +343,22 @@ are rooted in the base, never outside it. A failed fetch may serve cached
285
343
  accepted bytes marked stale. `read` and `refresh` remain removed: use `cat`
286
344
  and `index`. The consultation skill teaches navigation and citation.
287
345
 
346
+ ### Read the harvest duty
347
+
348
+ ```sh
349
+ oats okf status --json
350
+ ```
351
+
352
+ The provider's answer is `result.harvest: "on"` with `reason: "default"`, or
353
+ `"off"` with `reason: "soul-opt-out"`. It reads only home-local spawn state,
354
+ not the network, bases, TASK.md or a soul file. Missing state is `"unknown"`
355
+ with `reason: "spawn-state-missing"`; malformed or linked state refuses.
356
+ Neither unknown nor failure permits a proposal. Report it and respawn with
357
+ the current provider; never hand-create a policy or reinterpret later
358
+ settings as the spawn decision. `--home PATH` selects an explicit home.
359
+ This answer is instruction state, not publication authority: the harvester
360
+ still independently checks its recorded source's opt-out.
361
+
288
362
  ### Inspect
289
363
 
290
364
  ```sh
@@ -9,8 +9,8 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.10.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
12
+ | `oats.framework` | `oats-framework/v1.10.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
29
29
  ## Find and use packages
30
30
 
31
31
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v5.0.5`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.2.0`); `oats sync` resolves it through the
33
33
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
34
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
35
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.0.5 # bare version → the official catalog
47
+ oats.okf: v5.2.0 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v5.0.5`, `5.0.5`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.2.0`, `5.2.0`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.0.5` or `oats-framework/v1.10.0`) and the payload path. An id
54
+ convention (`v5.2.0` or `oats-framework/v1.10.2`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,8 +74,8 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.10.0
78
- oats.okf: v5.0.5
77
+ oats.framework: v1.10.2
78
+ oats.okf: v5.2.0
79
79
  oats.aweb: v1.27.3
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.5 ✓ (@ 73b85020)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.2.0 ✓ (@ 2ac86ccb)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "5.0.5",
164
- "commit": "73b85020e52b8584cb15f153a39712f900e69918",
163
+ "version": "5.2.0",
164
+ "commit": "2ac86ccba6ea3da19acf43274dd6d30ab2037653",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
352
352
  {
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.5", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.0", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.0", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.2", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.10.0`
362
- resolves to tag `oats-framework/v1.10.0`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.10.2`
362
+ resolves to tag `oats-framework/v1.10.2`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -74,7 +74,11 @@ node scripts/release-lane.mjs desktop --tag v0.22.0 --arch x64 # needs Rosett
74
74
  node scripts/release-lane.mjs status --tag v0.22.0
75
75
  ```
76
76
 
77
- On the Linux host, from a checkout of the same commit:
77
+ On the Linux host, from a checkout of the same commit. Besides the build tools,
78
+ the host needs binutils (`readelf` and `ar`) and `tar`. The `desktop` phase's
79
+ `dist:smoke` reads every ELF file of the DEB and the AppImage and checks it
80
+ against the installers' glibc floor (`packages/desktop/scripts/linux-floor.json`).
81
+ No flag skips that check, and it stops naming the tool when one is missing.
78
82
 
79
83
  ```bash
80
84
  node scripts/release-lane.mjs build --tag v0.22.0
@@ -251,6 +255,16 @@ module's number follows the runner that builds it: the symbols it needs at
251
255
  2.34 are the ones a module gets when it is built on a system whose glibc is
252
256
  2.34 or later.
253
257
 
258
+ **The build now holds that number.** `docs/desktop.md` states it (glibc 2.34)
259
+ and `packages/desktop/scripts/linux-floor.json` holds it with libstdc++'s
260
+ `GLIBCXX` and `CXXABI` (`packages/desktop/test/linux-floor.test.mjs` keeps the
261
+ two equal). On the Linux leg of both workflows, `dist:smoke` unpacks the DEB
262
+ and the AppImage (its runtime and the libraries it adds included), reads the
263
+ version-needs table of every ELF file with `readelf -V -W`, and fails naming
264
+ each file that needs a newer version than the floor. A move of the runner, a
265
+ new `node-pty` or a new Electron that raises it is then a pull request that
266
+ changes that file and the page together.
267
+
254
268
  ## Release-notes entries
255
269
 
256
270
  A release ships one notes file, `docs/release-notes/v<version>.md`. Between
@@ -332,6 +346,17 @@ node scripts/assemble-release-notes.mjs --tag v0.54.0
332
346
  file, which `test/release-packaging.test.mjs` requires for the version the
333
347
  manifests carry. The release-prep pull request runs it again for the
334
348
  entries merged since, which go after the earlier ones.
349
+ - **The Upgrade section opens with the order of the Desktop and the CLI.**
350
+ The tag owner writes it in the release-prep pull request, for every
351
+ release, from `ACCEPT_RANGE` in `packages/client/cli-locator.mjs`:
352
+ - when the release moves the range's upper bound (a new minor), the first
353
+ Upgrade line says to install the Desktop first and the CLI second,
354
+ because the previous Desktop refuses this CLI ([Upgrading](upgrading.md));
355
+ - when the range already admits the new version (a patch), it says that
356
+ either order works.
357
+
358
+ No entry file writes this line: only the tag owner knows the release's
359
+ version when the notes are assembled.
335
360
  - **A tag is refused while anything is under `docs/release-notes/next/`:** by
336
361
  the `build-and-test` job of `release.yml` and by `release-lane.mjs build`,
337
362
  each right after its notes-file gate and before anything is built. Each