@awebai/oats 0.69.15 → 0.69.17

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.
package/docs/packages.md CHANGED
@@ -48,14 +48,14 @@ whole organisation:
48
48
 
49
49
  ```yaml
50
50
  packages:
51
- oats.okf: v5.8.0 # bare version → the official catalog
51
+ oats.okf: v6.0.2 # bare version → the official catalog
52
52
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
53
53
  ```
54
54
 
55
55
  - **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
56
56
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
57
57
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
58
- convention (`v5.8.0` or `oats-framework/v1.23.0`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.24.1`) and the payload path. An id
59
59
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
60
60
  a package outside the catalog"). The catalog is the reviewed official list
61
61
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -78,9 +78,9 @@ members:
78
78
  - git:github.com/acme/agents
79
79
  - git:github.com/acme/platform
80
80
  packages:
81
- oats.framework: v1.23.0
82
- oats.okf: v5.8.0
83
- oats.aweb: v1.37.0
81
+ oats.framework: v1.24.1
82
+ oats.okf: v6.0.2
83
+ oats.aweb: v1.39.0
84
84
  teams:
85
85
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
86
86
  defaults:
@@ -109,7 +109,7 @@ decision recorded in the lock.
109
109
  $ oats sync
110
110
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
111
111
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
112
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.8.0 ✓ (@ cfc595a9)
112
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 6.0.2 ✓ (@ 5c3f684c)
113
113
  changed acme.tools — → 0.4.0 (@ 47f4b816)
114
114
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
115
115
  teams platform (shared) · this deployment's: oats teams
@@ -155,7 +155,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
155
155
  ## `oats package add | remove`
156
156
 
157
157
  ```bash
158
- oats package add oats.aweb v1.37.0 # a catalog version
158
+ oats package add oats.aweb v1.39.0 # a catalog version
159
159
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
160
160
  oats package remove acme.tools
161
161
  ```
@@ -181,8 +181,8 @@ same workspace commit hold identical locks.
181
181
  "source": "catalog:oats.okf",
182
182
  "url": "https://github.com/awebai/oats-okf.git",
183
183
  "path": "oats-package",
184
- "version": "5.8.0",
185
- "commit": "56dbc167394bbc13cc900bd8af0c64b74fecae54",
184
+ "version": "6.0.2",
185
+ "commit": "5c3f684c35b2ea9eeec5cdca915b6d845273fb4d",
186
186
  "integrity": "sha256-…",
187
187
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
188
188
  },
@@ -431,12 +431,12 @@ A soul that names one of the package's capabilities with
431
431
  {
432
432
  "policy": "docs/official-catalog.md",
433
433
  "packages": {
434
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.8.0", "path": "oats-package" },
435
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.23.0", "path": "oats-package" }
434
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.0.2", "path": "oats-package" },
435
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.24.1", "path": "oats-package" }
436
436
  }
437
437
  }
438
438
  ```
439
439
 
440
- `ref` carries the tag convention: a workspace's `oats.framework: v1.23.0`
441
- resolves to tag `oats-framework/v1.23.0`. Resolving through the catalog never
440
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.24.1`
441
+ resolves to tag `oats-framework/v1.24.1`. Resolving through the catalog never
442
442
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,169 @@
1
+ # OATS 0.69.16
2
+
3
+ 0.69.16 moves OATS onto oats.okf 6: there is no knowledge harvester any more,
4
+ and an instance proposes what it learned itself, as a pull request the
5
+ knowledge maintainer reviews (`oats okf propose`). The official catalog pins
6
+ oats.okf 6.0.1, oats.aweb 1.39.0 and oats.framework 1.24.0, and OATS's own
7
+ texts, souls and template copy follow. The team agent image now runs
8
+ `oats host run`.
9
+
10
+ ## Upgrade
11
+
12
+ - **Either order of the Desktop and the CLI works.**
13
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
14
+ installed the CLI first is fine too: the 0.69.16 Desktop accepts OATS CLIs
15
+ `>=0.26.0 <0.70.0`, as the 0.69.15 Desktop does.
16
+ - **Package pins:** oats.okf 6.0.1 (from 5.8.0), oats.aweb 1.39.0 (from
17
+ 1.37.0) and oats.framework 1.24.0 (from 1.23.0). A deployment that pins
18
+ them takes the steps below; one that keeps its own pins changes nothing
19
+ until it moves them.
20
+
21
+ - **A deployment that takes oats.okf 6.0.1 does these by hand**, from its
22
+ deployment directory (oats.okf's
23
+ [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.0.1/README.md#upgrading-to-60)
24
+ has each step's commands; [knowledge.md](../knowledge.md#pin-and-select-the-package)
25
+ the summary):
26
+ 1. Delete the harvester's launch preference, if any:
27
+ `oats soul launch remove oats.okf/knowledge-harvester --plan`, then
28
+ without `--plan`.
29
+ 2. Delete every `--provider oats.okf harvest=…` spawn flag from the
30
+ scripts and briefs that spawn instances. Remove a leftover host
31
+ `harvest` key with `oats okf setup --remove-legacy-settings --soul
32
+ <soul>` (`--plan` first).
33
+ 3. Add the `proposal-review` trigger beside `harvest-review`: an existing
34
+ `harvest-review` watches only the 5.x label `okf-harvest`, so it never
35
+ reviews a 6.0 proposal. For a workspace file, copy it under the template
36
+ `oats.okf:proposal-review` and the id `okf-proposal-review`, keeping its
37
+ `set:`, `runsOn` and `owner`. On its review host, if `oats-local.yaml`
38
+ lists named `automations: trust:` entries, add
39
+ `- <member>/okf-proposal-review` beside the old one, then check that
40
+ `oats trigger show <member>/okf-proposal-review --json` answers
41
+ `runsHere: true`. For a local trigger, read its values with `oats
42
+ trigger show <id> --json` and repeat them as `--set` values on `oats
43
+ trigger add --from oats.okf:proposal-review`. Remove `harvest-review`
44
+ (and its trust line) once no 5.x harvester can open an `okf-harvest`
45
+ PR.
46
+ 4. Protect every Git base's accepted branch (pull requests only, merged by
47
+ the knowledge maintainer's account), and give each proposing host's
48
+ account branch-create access on the knowledge repository, never
49
+ accepted-branch push; optionally set `screen-terms-file`
50
+ ([Settings](../knowledge.md#settings)).
51
+ 5. Retire the harvesters `oats status` still lists, once they have handed
52
+ over. A retired source's claims are proposed with the operator form,
53
+ `oats okf propose --home <retirement recovery directory> --soul <soul>`
54
+ (`--plan`, `--check`, `--apply`).
55
+ - **OATS's own workspace** adds `oats-triggers/okf-proposal-review.yaml`
56
+ beside `okf-harvest-review.yaml`. On the host it names, add its trust line
57
+ as in step 3 unless that host trusts `"*"`.
58
+
59
+ - **oats.aweb 1.39.0 tests aw 1.36.56** (from 1.36.53). The floor stays
60
+ aw 1.36.33. `aw-newer-than-tested` now warns only above 1.36.56, and the
61
+ pin it names is `npm i -g @awebai/aw@1.36.56`. Install that version on
62
+ each host where readiness asks for it.
63
+ - **pi homes: remove or filter `@awebai/claude-skills` in the launch's pi
64
+ folder.** From oats.aweb 1.38.0, home readiness warns
65
+ `pi-skills-package-loaded` when that pi folder lists
66
+ `npm:@awebai/claude-skills` without `"skills": []`. Remove the entry, or
67
+ filter it. With @awebai/pi 0.5.0 or later installed there,
68
+ `pi-extension-skills-loaded` no longer asks for the skills filter.
69
+ - **Bringing your own team** (`oats aweb setup --create <label> --namespace
70
+ <domain>`) needs aw 1.36.53 or later, and refuses an older aw before it
71
+ creates anything.
72
+
73
+ - **Rebuild the [team agent image](../container.md) and recreate its
74
+ container.** The image pins OATS 0.69.15 and its entrypoint runs
75
+ `oats host run`; an existing container keeps the old entrypoint, the
76
+ 10-second stop timeout and no healthcheck until it is made again from the
77
+ new image and `container/agent/compose.agent.yaml` (`docker compose ... up
78
+ -d`). `container/agent/accept.sh` refuses a container whose stop timeout
79
+ is not 45 seconds or whose healthcheck is not the service file's.
80
+ - **A platform that does not read the Compose file** gives the container a
81
+ stop timeout of 45 seconds itself: `oats host run` gives each harness 20
82
+ seconds to end, and Docker's default of 10 kills the agents before they
83
+ are stopped in order.
84
+ - **Register the deployment for schedules once**, after `server connect`:
85
+ `oats schedule host install --register-only --server team-agent`. The
86
+ operator's OATS must be 0.69.15 or later for the option.
87
+
88
+ ## Changed
89
+
90
+ - **The official catalog pins oats.okf 6.0.1** (from 5.8.0, crossing 6.0.0),
91
+ and OATS's own workspace takes it. 6.0 removes the knowledge harvester: an
92
+ instance proposes its knowledge by pull request at its checkpoints (`oats
93
+ okf propose`), and the knowledge maintainer reviews it. `oats.okf-harvest`
94
+ and `oats.okf/knowledge-harvester` stay as refusing stubs until 7.0. It
95
+ also reads a bridged knowledge base by subject (`okf.json` version 2, and
96
+ the `subjects`, `subject`, `claims` and `verdicts` verbs); a base that is
97
+ not bridged, and a version-1 soul, are served as before. The generated
98
+ mirror under `mirrors/oats-okf*` is finalized from the v6.0.1 tag
99
+ ([oats.okf's CHANGELOG](https://github.com/oats-project/oats-
100
+ okf/blob/v6.0.1/CHANGELOG.md)).
101
+
102
+ - **OATS's texts follow oats.okf 6: an instance proposes its own knowledge.**
103
+ The docs, the souls and the `oats.framework` skills no longer name a
104
+ harvester to launch, wait for or retire: at each knowledge checkpoint an
105
+ instance with a duty to propose runs `oats okf propose` itself, and the
106
+ knowledge maintainer's review gates the pull request
107
+ ([knowledge.md](../knowledge.md#the-flow),
108
+ [schedules.md](../schedules.md#knowledge-proposal-review)). A finished
109
+ instance's done line is one of "done, proposed: <PR URLs>", "done, nothing
110
+ to propose: <reason>" or "done, no duty to propose"; "done, proposal
111
+ pending: <slug and why>" means it is not finished yet.
112
+
113
+ - **`oats.framework` 1.24.0 carries OATS's texts for oats.okf 6 and the pi
114
+ folder steps for @awebai/pi 0.5.0.**
115
+ - `oats.setup` 2.15.0:
116
+ - `/oats-onboarding`, `/oats-automations` and `/oats-agent-permissions`
117
+ describe oats.okf 6.0.1: an instance proposes its own knowledge with
118
+ `oats okf propose`, the `oats.okf:proposal-review` trigger reviews it,
119
+ and there is no harvester to set up.
120
+ - `/oats-host-delivery`'s pi step asks for the skills filter only below
121
+ @awebai/pi 0.5.0, and keeps @awebai/claude-skills out of OATS pi
122
+ folders.
123
+ - `oats.coordination-setup` 1.0.1's `/coordination-best-practices` says
124
+ knowledge is proposed at checkpoints, not harvested.
125
+
126
+ The commands these name come from oats.okf 6, which the catalog pins. None
127
+ needs a newer OATS than each capability already admits.
128
+
129
+ - **OATS's copy of the engineering template moves to template-v3.0.2**, which
130
+ makes the same change in the coordination skills and injects.
131
+
132
+ - **The official catalog pins oats.aweb 1.39.0** (from 1.37.0, crossing
133
+ 1.38.0), and OATS's own workspace takes it. It brings:
134
+ - from 1.38.0, the pi skills-filter change above;
135
+ - from 1.39.0, a bring-your-own-team create that runs to the end
136
+ (registers the team, publishes and verifies its team-server record, and
137
+ resumes when re-run); a public `aw-compat.json` stating the aw floor and
138
+ the tested aw; and owner-only draft files for mail and chat bodies
139
+ instead of fixed `/tmp` paths.
140
+
141
+ `mirrors/oats-aweb` and `mirrors/oats-aweb-tasks` are copied from the
142
+ v1.39.0 tag
143
+ ([oats.aweb's CHANGELOG](https://github.com/awebai/oats-aweb/blob/v1.39.0/CHANGELOG.md)).
144
+
145
+ - **The team agent image runs the kernel's periodic work.** Its entrypoint
146
+ starts sshd in the background and ends in `exec oats host run`, so that
147
+ command is tini's direct child, the process the runtime's SIGTERM reaches
148
+ and the container waits for. At start it resumes the sessions lost when
149
+ the container last stopped, then runs the schedule tick each minute for
150
+ the registered deployments; on `docker stop` it stops the agents in order
151
+ and the next start resumes them
152
+ ([container.md](../container.md#the-kernels-periodic-work)).
153
+ - The image pins OATS 0.69.15, the first release with `oats host run`.
154
+ - The Compose service sets `stop_grace_period: 45s`.
155
+ - The Compose service has a healthcheck that opens sshd's port,
156
+ `127.0.0.1:2222`, every 30 seconds. `oats host run` does not supervise
157
+ sshd, and Docker does not restart an unhealthy container: when
158
+ `docker inspect --format '{{.State.Health.Status}}'` reads `unhealthy`,
159
+ `docker restart` the container.
160
+ - The acceptance script requires the 45-second stop timeout and that
161
+ healthcheck in the container's inspect evidence.
162
+
163
+ ## Documentation
164
+
165
+ - **The pi skills filter is for @awebai/pi below 0.5.0, and @awebai/claude-skills stays out of OATS pi folders.**
166
+ - **Why:** @awebai/pi 0.5.0 bundles no skills. They now ship on their own in @awebai/claude-skills, which pi would load in every session that uses the folder.
167
+ - **`/oats-host-delivery`** (`oats.framework`): the pi step of channel delivery makes the extension's entry `{"source": "npm:@awebai/pi", "skills": []}` only below 0.5.0.
168
+ - **The getting-started onboarding:** it still sets the filter whatever the version, because it's harmless on 0.5.0.
169
+ - Both now say never to install @awebai/claude-skills in a pi folder that OATS homes use, because a home gets its skills from its capabilities. This matches oats.aweb 1.38.0, whose readiness warns `pi-extension-skills-loaded` only below 0.5.0 and adds `pi-skills-package-loaded`.
@@ -0,0 +1,49 @@
1
+ # OATS 0.69.17
2
+
3
+ 0.69.17 moves OATS's two coordination souls, `oats-engineering-expert` and
4
+ `oats-product-expert`, onto knowledge subjects (`okf.json` version 2). The
5
+ official catalog pins oats.okf 6.0.2 and oats.framework 1.24.1; oats.aweb
6
+ stays at 1.39.0.
7
+
8
+ ## Upgrade
9
+
10
+ - **Either order of the Desktop and the CLI works.**
11
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
12
+ installed the CLI first is fine too: the 0.69.17 Desktop accepts OATS CLIs
13
+ `>=0.26.0 <0.70.0`, as the 0.69.16 Desktop does.
14
+ - **Package pins:** oats.okf 6.0.2 (from 6.0.1) and oats.framework 1.24.1
15
+ (from 1.24.0). Neither asks for a hand step: `oats sync` takes them. A
16
+ deployment that keeps its own pins changes nothing until it moves them.
17
+ - **Respawn an instance of `oats-engineering-expert` or `oats-product-expert`
18
+ once** after `oats sync`. An instance keeps the `okf.json` its spawn
19
+ recorded, so one started before this release still reads and proposes to
20
+ its old node; a new spawn reads the soul's subjects. The soul needs a
21
+ knowledge base bound with the subject layout: on a base that is not
22
+ bridged, its spawn refuses with `E_CONFIG` naming the base
23
+ ([okf.json version 2](../knowledge.md#the-souls-okfjson)).
24
+
25
+ ## Changed
26
+
27
+ - **`oats.framework` 1.24.1: `oats.setup` 2.15.1's `/oats-onboarding` names
28
+ `oats.okf` 6.0.2**, the release the catalog pins, in its knowledge card and
29
+ its workspace example. Nothing else changes, and no capability needs a
30
+ newer OATS.
31
+
32
+ - **The official catalog pins oats.okf 6.0.2** (from 6.0.1), and OATS's own
33
+ workspace takes it. A claim merged into a bridged base without the
34
+ maintainer's id stamp no longer stops version-2 spawns: readers warn
35
+ `W_ID_MISSING`, `oats okf bases` shows it, and writers and strict checks
36
+ still refuse. The generated mirror under `mirrors/oats-okf*` is finalized
37
+ from the v6.0.2 tag
38
+ ([oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.0.2/CHANGELOG.md)).
39
+
40
+ - **`oats-engineering-expert` and `oats-product-expert` read by subject**
41
+ (`okf.json` version 2). The engineering expert's subjects are
42
+ `system/oats-kernel`, `system/oats-desktop`,
43
+ `workstream/provider-integration`, `workstream/operations` and
44
+ `workstream/coordination`; the product expert's are
45
+ `workstream/oats-direction` and `workstream/positioning`. Their spawn brief
46
+ lists those subjects, and their texts say each proposed claim names the
47
+ subjects it is about. Every other soul keeps its version-1 `okf.json`.
48
+ - **`oats.workspace-experts` 1.3.1:** its table of surfaces names, beside each
49
+ knowledge node, the subject that absorbs it ("Knowledge it reads").
package/docs/schedules.md CHANGED
@@ -221,9 +221,9 @@ refuses the key on a trigger.
221
221
  again only at due minutes, so a harness that keeps exiting is not restarted
222
222
  in a loop. Unobservable or still starting: skipped, delivery kept pending.
223
223
  Word wake messages so that receiving one again is harmless.
224
- - **operation** `{…, operation, home}` — runs a provider operation such as
225
- `knowledge:harvest` in the instance at `home` through `oats operation run
226
- <layer>:<name> --home <home>`. The provider is whatever fills that layer
224
+ - **operation** `{…, operation, home}` — runs a provider operation
225
+ (`<layer>:<name>`, one the capability filling that layer declares) in the
226
+ instance at `home` through `oats operation run <layer>:<name> --home <home>`. The provider is whatever fills that layer
227
227
  when the job runs. Tracking is that of a command job.
228
228
 
229
229
  `--wake-every N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07,
@@ -244,11 +244,11 @@ reports `gh.credentialSource` (`keyring`, `config`, `env:<VAR>`) and warns
244
244
  when the timer cannot reach it.
245
245
 
246
246
  ```json
247
- { "id": "okf-harvest-review", "enabled": true, "kind": "trigger",
248
- "description": "Review every harvest PR on the knowledge base",
247
+ { "id": "okf-proposal-review", "enabled": true, "kind": "trigger",
248
+ "description": "Review every knowledge proposal PR on the knowledge base",
249
249
  "on": { "source": "github.pull_request", "repo": "github.com/acme/knowledge",
250
250
  "events": ["opened", "reopened", "ready_for_review"],
251
- "labels": ["okf-harvest"], "base": "main", "poll": "2m" },
251
+ "labels": ["okf-proposal"], "base": "main", "poll": "2m" },
252
252
  "spawn": { "soul": "oats.okf/knowledge-maintainer", "purpose": "review-pr-{number}",
253
253
  "task": "Review knowledge-base PR {repo}#{number}. Load knowledge-review first.",
254
254
  "harness": "claude", "model": "opus" },
@@ -328,7 +328,7 @@ when the timer cannot reach it.
328
328
 
329
329
  ```sh
330
330
  oats trigger add --file trigger.json [--description=<text>] # or:
331
- oats trigger add --from oats.okf:harvest-review --set repo=github.com/acme/knowledge [--id <id>] [--description=<text>]
331
+ oats trigger add --from oats.okf:proposal-review --set repo=github.com/acme/knowledge [--id <id>] [--description=<text>]
332
332
  oats trigger update <id> --description=<text> # the description only; --description= clears it
333
333
  oats trigger list | show <id> | enable <id> | disable <id> | remove <id>
334
334
  oats trigger test <id> # dry run: gh credentials, repo permissions, the soul, what WOULD fire
@@ -576,11 +576,11 @@ with the kind's suffix anywhere in the member (`.yml` works too), for example
576
576
  `oats-package/`, `.git/` and `node_modules/` are never scanned.
577
577
 
578
578
  ```yaml
579
- # <member>/oats-triggers/okf-harvest-review.yaml
579
+ # <member>/oats-triggers/okf-proposal-review.yaml
580
580
  kind: oats-trigger
581
581
  schemaVersion: 1
582
- description: Review every harvest PR on the knowledge base
583
- from: oats.okf:harvest-review # a package template at the locked commit, then its parameters
582
+ description: Review every knowledge proposal PR on the knowledge base
583
+ from: oats.okf:proposal-review # a package template at the locked commit, then its parameters
584
584
  set: { repo: github.com/acme/knowledge }
585
585
  runsOn: kb-bot-server # the host.name that runs it
586
586
  owner: github.com/acme-kb-bot # the GitHub account it acts as
@@ -1122,35 +1122,38 @@ more than that:
1122
1122
  fails, the spawn result still carries the instance receipt, plus
1123
1123
  `wakeScheduleError` and a warning.
1124
1124
 
1125
- ## Knowledge harvest and review
1125
+ ## Knowledge proposal review
1126
1126
 
1127
- **oats.okf 5.x does not schedule harvest jobs.** In 5.2 the capability's
1128
- IMPORTANT inject and compulsory `okf-propose` skill give the duty, not TASK.md.
1129
- A working instance keeps its notes current, checks `oats okf status`, and at
1130
- a finished task or PR hand-over proposes only durable, non-duplicate claims.
1131
- At most one proposal per completed unit of work, one harvester at a time,
1132
- and no spawn under memory pressure or below 8 GB available; otherwise defer
1133
- and hand back the pending claims. Most checkpoints propose nothing. When the
1134
- skill's gates pass, the instance directly spawns the package harvester:
1127
+ **oats.okf 6 schedules no knowledge job.** Its IMPORTANT inject and
1128
+ compulsory `okf-propose` skill give the duty to propose, not TASK.md. At each
1129
+ knowledge checkpoint an instance with that duty proposes its durable,
1130
+ non-duplicate claims itself, from its home, as one pull request on the
1131
+ knowledge base:
1135
1132
 
1136
1133
  ```sh
1137
- oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
1134
+ oats okf propose --plan --slug <slug> # stages the proposal in the home
1135
+ oats okf propose --check --slug <slug> # the diff and its digest
1136
+ oats okf propose --apply --slug <slug> --digest <digest>
1138
1137
  ```
1139
1138
 
1140
- The unrelated harvester can outlive the proposing instance. It checks the
1141
- recorded source and its soul opt-out, accepted knowledge and open/recent
1142
- harvest PRs, then proposes an owned-node change through a normal reviewed
1143
- Git PR. Retirement does not automatically capture or harvest anything.
1144
- There is no host harvest switch, per-source command job, run-source command
1145
- or capture/drain/worker engine. The soul-only `knowledge: { harvest: off }`
1146
- keeps consultation while forbidding harvest of that soul's material.
1139
+ `--apply` pushes a create-only `okf-proposal/<date>-<id>` branch and opens
1140
+ one PR labelled `okf-proposal`; most checkpoints propose nothing. No worker
1141
+ is spawned, nobody waits for the PR, and retirement captures nothing. There
1142
+ is no host switch, per-source job or capture engine. The soul-only
1143
+ `knowledge: { harvest: off }` keeps consultation while giving that soul no
1144
+ duty to propose ([The soul's opt-out](knowledge.md#the-souls-opt-out)).
1147
1145
 
1148
- **Review still uses a trigger.** Each harvest PR can be reviewed by
1146
+ **Review still uses a trigger.** Each proposal PR can be reviewed by
1149
1147
  `oats.okf/knowledge-maintainer`, spawned from the package template
1150
- `oats.okf:harvest-review`: a workspace trigger file or a local
1151
- `oats trigger add --from oats.okf:harvest-review`. This is a PR-review
1152
- trigger, not a harvest scheduler or a kernel PR-opened capture hook.
1153
-
1148
+ `oats.okf:proposal-review`: a workspace trigger file or a local
1149
+ `oats trigger add --from oats.okf:proposal-review`. Through 6.x the template
1150
+ `oats.okf:harvest-review` watches only the 5.x label `okf-harvest`: keep it
1151
+ beside `proposal-review` only while a 5.x harvester may still open such a
1152
+ PR. These are PR-review triggers, not a knowledge scheduler or a kernel
1153
+ PR-opened capture hook.
1154
+
1155
+ A deployment moving from 5.x takes the hand steps in
1156
+ [Pin and select the package](knowledge.md#pin-and-select-the-package).
1154
1157
  Deployments upgrading from 4.x must settle registered sources before
1155
1158
  changing the pin, then use the 5.0 guard-exempt host-key cleanup before new
1156
1159
  spawns. See the [5.0 cutover sequence](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters). Provider
package/docs/servers.md CHANGED
@@ -669,7 +669,10 @@ It relays the host's viewer fact the same way, `probe.sessionViewer`
669
669
  host's viewer takes `C-b [`, or `null` when unknown.
670
670
 
671
671
  **Harvest** runs the knowledge capability's `okf harvest --json` in the
672
- instance's saved home on the server and relays its envelope.
672
+ instance's saved home on the server and relays its envelope. oats.okf 5.0
673
+ and later refuse that command with `E_REMOVED`: an instance proposes its
674
+ knowledge from its own home with `oats okf propose`
675
+ ([the flow](knowledge.md#the-flow)).
673
676
 
674
677
  ## What this machine keeps
675
678
 
@@ -172,7 +172,7 @@ For current settings and the respawn/cleanup sequence, see [knowledge.md](knowle
172
172
  }
173
173
  },
174
174
  "providers": {
175
- "oats.okf": { "bindings-file": "/Users/ana/.oats/okf-bindings.json", "state-dir": "/Users/ana/.oats/okf", "harvest-runtime": "claude" },
175
+ "oats.okf": { "bindings-file": "/Users/ana/.oats/okf-bindings.json", "state-dir": "/Users/ana/.oats/okf" },
176
176
  "acme-release-tooling": {}
177
177
  },
178
178
  "workspace": {
@@ -403,8 +403,7 @@ setting given without `--provider <capability>`). The full DTOs are in
403
403
  Examples of spawn hooks:
404
404
 
405
405
  - `oats.okf` validates the soul's declaration and the bindings, and creates the
406
- instance knowledge files. With harvest on, it also registers a durable source
407
- and its harvest schedule; with harvest off (the default) it registers nothing.
406
+ instance knowledge files. It registers no source, worker or schedule.
408
407
  Missing knowledge configuration is an error, never permission to bootstrap an
409
408
  empty substitute.
410
409
  - `oats.aweb` mints a messaging identity or, with
@@ -419,9 +418,10 @@ current, appends milestones to `log.md`, and captures non-obvious insights in
419
418
 
420
419
  It consults accepted knowledge remotely, at its accepted state, with
421
420
  `oats okf index`, `cat` and `search` (the `okf-consultation` skill), and never
422
- writes accepted knowledge; this is instruction, not an OS sandbox. With harvest
423
- on, an independent harvester judges the instance's notes and session record and
424
- proposes promotions by pull request. See [knowledge](knowledge.md).
421
+ writes accepted knowledge; this is instruction, not an OS sandbox. At each
422
+ knowledge checkpoint, an instance with a duty to propose judges its own notes
423
+ and proposes durable claims as one pull request (`oats okf propose`). See
424
+ [knowledge](knowledge.md).
425
425
 
426
426
  ### Spawning and coordinating with other agents
427
427
 
@@ -528,10 +528,11 @@ says what a clone carries and what it does not.
528
528
  ### Retire
529
529
 
530
530
  Retirement runs active capability retire hooks in reverse spawn order before the home disappears. The aweb
531
- integration deletes the instance identity here. With harvest on, `oats.okf`
532
- takes a final capture of notes and the session record into durable custody; an
533
- incomplete capture keeps the home for a retry. Retirement never waits for a
534
- model or GitHub: processing continues after the home is gone.
531
+ integration deletes the instance identity here. `oats.okf` captures nothing
532
+ at retirement: an instance proposes before it finishes, and for one that
533
+ retired without proposing, the operator proposes from its retirement recovery
534
+ copy ([the flow](knowledge.md#the-flow)). Retirement never waits for a model
535
+ or GitHub.
535
536
 
536
537
  A spawn that is killed after its spawn hooks started and before it wrote the
537
538
  home's record (SIGKILL, a container stop, a dropped connection) leaves a home
@@ -1844,8 +1845,8 @@ after the capability injects (`injects/instance-boundary.md`):
1844
1845
  soul's instructions, and `instance.json` `soulDir` records the (read-only,
1845
1846
  per-commit) soul directory every hook and dispatched command receives as
1846
1847
  `OATS_SOUL`. Durable soul edits go through tracked paths under `work/` under
1847
- the applicable review rules. The knowledge harvester proposes changes to the
1848
- external knowledge base, never to soul files or skills.
1848
+ the applicable review rules. A knowledge proposal changes the external
1849
+ knowledge base, never soul files or skills.
1849
1850
 
1850
1851
  Agents move between the two as the task needs; the boundary is what each
1851
1852
  directory is for, not a place to settle in.
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.15** ([release notes](release-notes/v0.69.15.md)).
10
- The 0.69.15 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.17** ([release notes](release-notes/v0.69.17.md)).
10
+ The 0.69.17 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.69.15,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.17,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.69.15 first
23
- npm install -g @awebai/oats@0.69.15 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.17 first
23
+ npm install -g @awebai/oats@0.69.17 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -204,6 +204,18 @@ of the Desktop and the CLI, and an optional package pin. A change a script
204
204
  must follow is in its release's Upgrade section whether or not it is listed
205
205
  here.
206
206
 
207
+ - **[0.69.17](release-notes/v0.69.17.md#upgrade):** the catalog pins
208
+ oats.okf 6.0.2 and oats.framework 1.24.1; respawn each running
209
+ `oats-engineering-expert` and `oats-product-expert` once after `oats sync`,
210
+ on a knowledge base with the subject layout.
211
+ - **[0.69.16](release-notes/v0.69.16.md#upgrade):** the catalog pins
212
+ oats.okf 6.0.1, oats.aweb 1.39.0 and oats.framework 1.24.0. A deployment
213
+ that takes oats.okf 6 removes the harvester's launch preference and spawn
214
+ flags, adds the `proposal-review` trigger beside `harvest-review`, protects
215
+ each Git base's accepted branch and gives proposing hosts branch-create
216
+ access, and retires its harvesters; aw 1.36.56 is the tested aw; pi homes keep
217
+ @awebai/claude-skills out of their pi folder; the team agent image is
218
+ rebuilt.
207
219
  - **[0.69.15](release-notes/v0.69.15.md#upgrade):** Node 22.5.0 or later
208
220
  before the CLI; on a shared host, `chmod -R go-rwx` each turn-record root;
209
221
  a record root is written from one machine at a time; release a schedule
@@ -294,7 +306,8 @@ here.
294
306
  - **[0.57.0](release-notes/v0.57.0.md#upgrade):** a retire plan taken before
295
307
  the upgrade is refused once (`E_PLAN_STALE`); `oats worktree remove` may
296
308
  refuse with `E_CHILDREN_RUNNING`; with oats.okf 5.2.0, new spawns carry the
297
- harvest duty unless the soul opts out.
309
+ harvest duty unless the soul opts out (oats.okf 6 makes it the duty to
310
+ propose: [knowledge.md](knowledge.md#pin-and-select-the-package)).
298
311
  - **[0.56.0](release-notes/v0.56.0.md#upgrade):** new refusal codes for
299
312
  scripts; `open-workspace` in `tui.json` is `open`; a launch gets only its
300
313
  capabilities' declared environment.
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.23.0 # bare version → resolves through the official catalog
58
- oats.okf: v5.8.0
57
+ oats.framework: v1.24.1 # bare version → resolves through the official catalog
58
+ oats.okf: v6.0.2
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
@@ -3,12 +3,12 @@
3
3
  "packages": {
4
4
  "oats.okf": {
5
5
  "url": "https://github.com/awebai/oats-okf.git",
6
- "ref": "v5.8.0",
6
+ "ref": "v6.0.2",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.37.0",
11
+ "ref": "v1.39.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -48,7 +48,7 @@
48
48
  },
49
49
  "oats.framework": {
50
50
  "url": "https://github.com/awebai/oats.git",
51
- "ref": "oats-framework/v1.23.0",
51
+ "ref": "oats-framework/v1.24.1",
52
52
  "path": "oats-package"
53
53
  }
54
54
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.15",
3
+ "version": "0.69.17",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -533,7 +533,7 @@ installed CLI's catalog:
533
533
  node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
534
534
  ```
535
535
 
536
- It prints the two refs, for example `oats-framework/v1.23.0 v1.37.0`. If the
536
+ It prints the two refs, for example `oats-framework/v1.24.1 v1.39.0`. If the
537
537
  framework's version (after the `/`) is below `1.19.0`, or with aweb
538
538
  `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
539
539
  skill: stop, and tell the person to wait for the next OATS
@@ -544,8 +544,11 @@ wakes an agent when mail arrives (skip this without messaging): Claude
544
544
  `claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
545
545
  pi `pi install npm:@awebai/pi`, then its entry in pi's `settings.json` set
546
546
  to load none of the skills it bundles (pi's extension is installed without
547
- its skills, so it puts none on the computer; each agent gets its own);
548
- Codex nothing (the setup expert sets up its wake). Claude's aweb channel
547
+ its skills, so it puts none on the computer; each agent gets its own;
548
+ from 0.5.0 it bundles none, and the setting is harmless, so set it
549
+ whatever the version). Never install `@awebai/claude-skills` in that pi
550
+ folder: its skills would load in every agent there, and each agent gets
551
+ its own skills from OATS. Codex nothing (the setup expert sets up its wake). Claude's aweb channel
549
552
  plugin still carries one skill of its own, until aweb ships it without
550
553
  (a known gap). The pi entry, which matches `npm:@awebai/pi` alone or with
551
554
  `@` and a version, never another `@awebai/pi-…` package, and prints it so
@@ -765,8 +768,8 @@ name: acme
765
768
  members:
766
769
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
767
770
  packages:
768
- oats.framework: v1.23.0 # the installed CLI's catalog versions (below)
769
- oats.aweb: v1.37.0 # messaging: agent identities, mail and chat
771
+ oats.framework: v1.24.1 # the installed CLI's catalog versions (below)
772
+ oats.aweb: v1.39.0 # messaging: agent identities, mail and chat
770
773
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
771
774
  defaults:
772
775
  capabilities: