@awebai/oats 0.69.12 → 0.69.14
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/README.md +216 -178
- package/bin/oats.mjs +176 -184
- package/docs/capabilities.md +4 -1
- package/docs/configuration.md +63 -5
- package/docs/container.md +246 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +376 -37
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +69 -6
- package/docs/implementation.md +86 -29
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/schedules.md +26 -3
- package/docs/servers.md +181 -5
- package/docs/souls-and-instances.md +140 -11
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +24 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +21 -5
- package/lib/command-flags.mjs +238 -0
- package/lib/core.mjs +791 -563
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +126 -31
- package/lib/errors.mjs +1 -1
- package/lib/harness-token.mjs +110 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +138 -13
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-listing.mjs +80 -38
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +3 -0
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +119 -27
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +2 -1
- package/lib/servers.mjs +78 -23
- package/lib/session-resume.mjs +68 -53
- package/lib/session-seen.mjs +54 -5
- package/lib/start-env.mjs +13 -7
- package/lib/system-tools.mjs +1 -1
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree.mjs +56 -7
- package/package-catalog.json +1 -1
- package/package.json +2 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +92 -25
- package/lib/tmux-config.mjs +0 -35
|
@@ -0,0 +1,767 @@
|
|
|
1
|
+
# OATS 0.69.13
|
|
2
|
+
|
|
3
|
+
0.69.13 lets a container deployment pass launch secrets through a private
|
|
4
|
+
file instead of the terminal's command line (`{ fromFile }`), provision a
|
|
5
|
+
harness's login token over the operator's SSH route, and manage it with
|
|
6
|
+
`oats harness token`; the repository ships a locked-down team agent
|
|
7
|
+
container image. OATS's own workspace gets its new roster of souls and
|
|
8
|
+
drops its `oats.engineering` pin for member copies of the engineering
|
|
9
|
+
coordination template; the official catalog lists the coordination
|
|
10
|
+
templates and moves to `oats.framework` 1.23.0, which adds
|
|
11
|
+
`oats.coordination-setup`. `oats sync` refuses a package pinned under
|
|
12
|
+
another package's id, a spawn checks the package tree against the lock,
|
|
13
|
+
locks are judged by their holder's identity, commands refuse unknown flags,
|
|
14
|
+
and doctor reports half-finished retirements and stale `souls.disabled`
|
|
15
|
+
entries.
|
|
16
|
+
|
|
17
|
+
## Upgrade
|
|
18
|
+
|
|
19
|
+
- **Either order of the Desktop and the CLI works.**
|
|
20
|
+
[Upgrading](../upgrading.md) installs the Desktop first, and a host that
|
|
21
|
+
installed the CLI first is fine too: the 0.69.13 Desktop accepts OATS CLIs
|
|
22
|
+
`>=0.26.0 <0.70.0`, as the 0.69.12 and 0.69.11 Desktops do.
|
|
23
|
+
- **Package moves:** the official catalog pins oats.framework 1.23.0 (from
|
|
24
|
+
1.22.1). It keeps its OATS floor; the lines in its skills that need this
|
|
25
|
+
release say "from OATS 0.69.13". oats.okf stays 5.8.0 and oats.aweb
|
|
26
|
+
1.37.0.
|
|
27
|
+
|
|
28
|
+
- **A home left half-retired now makes `oats doctor` report a
|
|
29
|
+
`retire-incomplete` problem** (oats-project/oats#1747). That covers a
|
|
30
|
+
quarantined home, and a self-retire that failed or was interrupted. Each
|
|
31
|
+
problem names the command that finishes the retirement and the capability
|
|
32
|
+
whose retire hook failed last. Doctor's exit status does not change: it
|
|
33
|
+
exits 0 with problems, as before. A deployment with no open retirement sees
|
|
34
|
+
no change.
|
|
35
|
+
|
|
36
|
+
- **`oats sync` and `oats sync --plan` now refuse a package whose
|
|
37
|
+
`oats-package.json` names another package than the `packages:` key it is
|
|
38
|
+
pinned under** (oats-project/oats#1759). The refusal is
|
|
39
|
+
`E_PACKAGE_INTEGRITY` with `why: "package-id"`. Its message names both ids
|
|
40
|
+
and the line to write in place of the key, then `oats sync`. A refused sync
|
|
41
|
+
writes nothing, and a lock that already holds such an entry is refused at
|
|
42
|
+
the next sync. Existing homes, and spawns from the current lock, keep
|
|
43
|
+
working until the line is fixed. Every version in the official catalog
|
|
44
|
+
names its own id. Before upgrading, check each `git:` pin in `packages:` on
|
|
45
|
+
the version you are leaving: the repository's `oats-package.json` at that
|
|
46
|
+
ref must say `"package": "<the key>"`
|
|
47
|
+
([`oats sync`](../packages.md#oats-sync--the-one-command-for-the-common-path)).
|
|
48
|
+
|
|
49
|
+
- **After upgrading, remove a sweep lock directory the earlier OATS left.**
|
|
50
|
+
A directory at `~/.oats/session-resume/lock` is the earlier OATS's lock.
|
|
51
|
+
This OATS never judges or removes it: `oats session resume` refuses it
|
|
52
|
+
with `E_RESUME_LOCK_STUCK`, and no sweep starts anything on the machine
|
|
53
|
+
until you remove the directory by hand, once no earlier `oats` is running
|
|
54
|
+
there. `oats doctor` reports it. An earlier OATS on the same machine takes
|
|
55
|
+
the new lock over once it is a minute old, also from a sweep that still
|
|
56
|
+
runs, so run one OATS version per machine.
|
|
57
|
+
|
|
58
|
+
- **After upgrading, remove a start lock directory an earlier OATS left.**
|
|
59
|
+
An earlier OATS made the directory `<home>/.oats-start.lock` for each
|
|
60
|
+
session start and could leave it behind when the start was killed. This
|
|
61
|
+
OATS makes nothing there: `oats session start` and `restart` refuse a
|
|
62
|
+
home with that directory with the new code `E_SESSION_START_LOCK_STUCK`,
|
|
63
|
+
naming it, and never remove it; `oats instance upgrade` refuses it too,
|
|
64
|
+
naming it. Remove the directory once no earlier `oats` is running on the
|
|
65
|
+
machine. The resume sweep reports such a home as a refused start
|
|
66
|
+
(`start-refused`, with the code) instead of skipping it as one where a
|
|
67
|
+
start is running. The Desktop and `oats tui` show it as a start that
|
|
68
|
+
started nothing, with a sentence that says to remove the lock its message
|
|
69
|
+
names once no earlier OATS is running, since waiting will not clear it.
|
|
70
|
+
|
|
71
|
+
- **Earlier OATS versions on the same machine still judge a cache write lock
|
|
72
|
+
by its pid alone.** A cache that an earlier `oats` also writes keeps that
|
|
73
|
+
behaviour for the locks it meets: it waits for a lock whose pid another
|
|
74
|
+
process holds, and so does this OATS for a lock the earlier one wrote,
|
|
75
|
+
whose record names no boot or start time. Run one OATS version per
|
|
76
|
+
machine to have every cache write lock judged by its holder's identity.
|
|
77
|
+
|
|
78
|
+
- **A deployment of OATS's own workspace takes four hand steps, in this order.** Names written for the package's reviewer, `oats.engineering/code-reviewer`, now name the workspace's `code-reviewer` soul.
|
|
79
|
+
1. **`souls.launch`.** Remove the old key:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
oats soul launch remove oats.engineering/code-reviewer
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The soul's own launch, pi with `github-copilot/gpt-6.1-sol`, then applies, unless the machine has a `souls.launch."*"` entry: that one wins over the soul's own launch, for the reviewer as for every soul without an entry of its own. Check what the reviewer will run on with `oats spawn code-reviewer --preview`. That preview, like every spawn that names no launch, of a soul with no `souls.launch` entry of its own, is refused while `souls.launch` holds any other key that names no soul: remove or re-point each such key first. A reviewer runs on a model family other than its developers'. Where the `"*"` entry, or any other choice, would put it on theirs, give the reviewer its own key: `oats soul launch set code-reviewer --harness <harness> --model <model>` (or `--launch-config <name>`).
|
|
86
|
+
|
|
87
|
+
Left in place, the old key stops spawns. `oats doctor` shows `E_LAUNCH_PREFERENCE_UNMATCHED: oats-local.yaml souls.launch names "oats.engineering/code-reviewer" (nearest: code-reviewer)`. Its fix line pins a soul first, then removes the key; here removing the key is enough. Every spawn that names no launch, of a soul with no `souls.launch` entry of its own, is refused with that code, and nothing is created or started. A spawn that names its launch (`--harness` or `--launch-config`) still runs.
|
|
88
|
+
2. **`souls.disabled`.** No command writes it. In `oats-local.yaml`, change `oats.engineering/code-reviewer` to `code-reviewer`. A stale entry **fails open**: it disables nothing, so the renamed `code-reviewer` spawns again on that machine, and the spawn doesn't refuse. `oats doctor` reports the stale entry (`disabled-soul-unmatched`).
|
|
89
|
+
3. **Team patterns.** They are the workspace's `souls:`, and OATS's has only `"*"`, which covers `code-reviewer`. Nothing to change. `oats soul teams code-reviewer` shows the `oats` team, from `"*"`.
|
|
90
|
+
4. **Schedules and triggers.** Find any that spawns the old soul with `oats schedule list` and `oats trigger list`. `oats schedule test <id>` reports `soul oats.engineering/code-reviewer does NOT resolve (E_SOUL_UNKNOWN)`, and the job spawns nothing; `oats trigger test <id>` checks its soul the same way. Change each to `code-reviewer`:
|
|
91
|
+
- a host schedule: `oats schedule update <id> --file <spec.json>`, with `"agent": "code-reviewer"`;
|
|
92
|
+
- a local trigger: `oats trigger remove <id>`, then `oats trigger add --file <trigger.json>`, with `"soul": "code-reviewer"` in its `spawn`;
|
|
93
|
+
- a workspace schedule or trigger: in its file in Git.
|
|
94
|
+
|
|
95
|
+
A new schedule that names the old soul is refused when it is added.
|
|
96
|
+
|
|
97
|
+
Then run `oats doctor`, after this or any soul rename or removal, and fix what it reports: a stale `souls.launch` key and a stale `souls.disabled` entry each show there.
|
|
98
|
+
- **Running instances keep their copies.** An instance spawned before this change, the package's `code-reviewer` included, keeps v1.18.0's modules until it is retired and respawned. A respawn picks up the member copies.
|
|
99
|
+
|
|
100
|
+
- **A deployment of OATS's own workspace moves onto the new souls, by hand.**
|
|
101
|
+
|
|
102
|
+
1. **Respawn the live homes onto the new souls,** once each has finished or handed off its effort (`oats status` lists them). For each home of `oats-expert`, the area experts, `oats-kernel-developer` or `oats-integrations-developer`:
|
|
103
|
+
```bash
|
|
104
|
+
oats retire <name> --plan
|
|
105
|
+
oats retire <name>
|
|
106
|
+
```
|
|
107
|
+
New work starts on the successors, `oats-engineering-expert` and `oats-developer` (from your dispatcher, below). A home of `oats-engineering-expert`, `oats-developer` or `oats-desktop-developer` spawned before this change takes the new texts the same way: retire it once its work is done, and spawn a fresh one for the next effort.
|
|
108
|
+
2. **Start the dispatcher,** one standing instance for each person who wants one:
|
|
109
|
+
```bash
|
|
110
|
+
oats spawn dispatcher --name <person>-dispatcher --task-file <who it serves.md>
|
|
111
|
+
```
|
|
112
|
+
It starts a fresh expert of the right soul per effort, introduces its lead and steps aside.
|
|
113
|
+
|
|
114
|
+
## Added
|
|
115
|
+
|
|
116
|
+
- **`oats doctor` and `oats doctor --json` list each retirement left open**
|
|
117
|
+
as a `retire-incomplete` problem in `problems[]`, `{code, message,
|
|
118
|
+
remedy}` (oats-project/oats#1747). The remedy is `oats retire <name> --home
|
|
119
|
+
<home>`, shell-quoted, and names the capability whose retire hook failed
|
|
120
|
+
last. A retire that is running, or whose state cannot be read, is not
|
|
121
|
+
listed. Neither is a spawn in progress, or an outcome whose home is gone,
|
|
122
|
+
which `oats status` still lists
|
|
123
|
+
([doctor `problems[]`](../desktop-cli-api.md)).
|
|
124
|
+
|
|
125
|
+
- **A retire hook's warnings stay readable after the retire, as `retire-warning`
|
|
126
|
+
events** (oats-project/oats#1749). A retire hook can succeed and still name
|
|
127
|
+
an action someone must take. Until now that warning was only in the retire's
|
|
128
|
+
answer, and was lost once the caller moved on.
|
|
129
|
+
- Each warning of the retire hooks is now one `retire-warning` row, `data:
|
|
130
|
+
{message}`, in the instance's workspace log. `oats instance events
|
|
131
|
+
<instance> --json` reads it after the home is gone.
|
|
132
|
+
- The rows are written as soon as the hooks return. A retire that then
|
|
133
|
+
refuses or ends quarantined keeps them, and each retry of the hooks adds
|
|
134
|
+
its own.
|
|
135
|
+
- A retire whose hooks warn nothing writes none. The retire's answer and the
|
|
136
|
+
`retired` event are unchanged. Older clients read the new kind as an
|
|
137
|
+
unknown kind
|
|
138
|
+
([Events](../desktop-cli-api.md#events)).
|
|
139
|
+
|
|
140
|
+
- Launch configuration environment values accept `{ fromFile: /absolute/path }`.
|
|
141
|
+
Each start reads a regular UTF-8 file on its execution host and removes one
|
|
142
|
+
trailing line ending, preserving a UTF-8 BOM. Invalid UTF-8, missing,
|
|
143
|
+
unreadable, NUL-containing or nonregular files
|
|
144
|
+
refuse with `E_LAUNCH_ENV_MISSING` and a provisioning remedy. Preview, list
|
|
145
|
+
and recipes contain references only; resume checks compare keyed digests.
|
|
146
|
+
- Both `fromEnv` and `fromFile` values now reach the pane through a private
|
|
147
|
+
per-start file, removed by the launcher before the harness runs. This removes
|
|
148
|
+
the existing `fromEnv` exposure in tmux process arguments. A subsequent start
|
|
149
|
+
removes abandoned handoff files, including when it needs no references.
|
|
150
|
+
- `fromFile` is for credential values. Directory selectors require a literal
|
|
151
|
+
or `{ fromEnv: NAME }`; validation names the selector and remedy.
|
|
152
|
+
- With references, the private handoff runs the pane wrapper through `/bin/sh`.
|
|
153
|
+
Harness arguments already pass through the native recorder's POSIX shell;
|
|
154
|
+
capability launch contributions are parsed arguments, not shell programs.
|
|
155
|
+
- File sources are capped at 64 KiB, including a final newline, with bounded
|
|
156
|
+
reads. Refusals name the file and the missing, type, permission, encoding, NUL
|
|
157
|
+
or size problem while keeping `E_LAUNCH_ENV_MISSING`.
|
|
158
|
+
|
|
159
|
+
- Claude starts check the effective configuration directory for a `/login`
|
|
160
|
+
credential. When OATS also sets `CLAUDE_CODE_OAUTH_TOKEN` (literal, `fromEnv`,
|
|
161
|
+
`fromFile` or a launch hook), the start refuses with
|
|
162
|
+
`E_CLAUDE_LOGIN_CREDENTIAL`, naming the exact credential file and
|
|
163
|
+
`oats harness token set claude`. Without an OATS-set token, a personal
|
|
164
|
+
`/login` credential is allowed silently. Remove the `/login` credential before
|
|
165
|
+
starting on the token route. Inherited pane tokens do not trigger refusal.
|
|
166
|
+
- Spawn preview and apply check the predictable launch configuration before
|
|
167
|
+
creating a home, worktree or identity.
|
|
168
|
+
Hook-supplied selectors and tokens are checked once their environment is
|
|
169
|
+
known, and the actual pane is checked again before dispatch.
|
|
170
|
+
- The final credential check follows the harness selected for this start,
|
|
171
|
+
including a switch between Claude and another harness. Hook-supplied
|
|
172
|
+
directory selectors are covered at preview, spawn and start.
|
|
173
|
+
|
|
174
|
+
- `oats server add` and `oats server connect` accept `--operator-ssh <alias>`.
|
|
175
|
+
The optional operator route follows the same validation rules as `sshHost`
|
|
176
|
+
and appears as `operatorSshHost` in `server list` and connect's registration.
|
|
177
|
+
It lives in `~/.oats/server-operator-routes.json`, under the same servers
|
|
178
|
+
lock, so `servers.json` stays readable by older kernels, including Desktop's
|
|
179
|
+
bundled kernel. Older kernels never read the separate file.
|
|
180
|
+
- `--replace` keeps the operator route unless `--operator-ssh` sets it again
|
|
181
|
+
or `--no-operator-ssh` clears it. `server remove` deletes its route too.
|
|
182
|
+
Existing commands and saved instance targets keep using the agent's SSH alias.
|
|
183
|
+
- A fresh registration never inherits an orphan operator route left by an
|
|
184
|
+
older kernel's remove. On an unchanged agent target, an operator-only update
|
|
185
|
+
preserves `servers.json` bytes; an answered `--replace` can still refresh a
|
|
186
|
+
stale workspace key without a false concurrency warning.
|
|
187
|
+
|
|
188
|
+
- `oats harness token set|status|remove <harness> --server <id>` uses the
|
|
189
|
+
separate operator SSH route and forced-command credential receiver.
|
|
190
|
+
`set --stdin` supports Claude setup-tokens and Codex, pi and opencode
|
|
191
|
+
API keys, without credential arguments, output or client files. A missing
|
|
192
|
+
operator route refuses; it never falls back to the agent route or reuses
|
|
193
|
+
its authenticated connection. Malformed or oversized replies fail closed,
|
|
194
|
+
and remote refusal text is escaped for terminal output.
|
|
195
|
+
Unknown server ids refuse before SSH, including when an orphan operator route exists.
|
|
196
|
+
- The npm package includes `share/oats-login-receive`; see
|
|
197
|
+
[receiver installation](../servers.md#install-the-credential-receiver)
|
|
198
|
+
for Python 3, the root-owned configuration and the restricted SSH key.
|
|
199
|
+
- Rotation lists sessions of the same harness started before or during the
|
|
200
|
+
receiver's reported replacement second;
|
|
201
|
+
they pick up the new value at their next start. Nothing restarts
|
|
202
|
+
automatically. A roster failure after installation is a warning, not a
|
|
203
|
+
failed install. Claude interactive capture is unavailable, and refreshing
|
|
204
|
+
browser sign-ins do not fit the read-only credential model.
|
|
205
|
+
|
|
206
|
+
- **`E_RESUME_LOCK_STUCK`: a sweep lock that needs a person has its own
|
|
207
|
+
code, and `oats doctor` reports it.** `oats session resume` answers it,
|
|
208
|
+
never `E_RESUME_BUSY`, when the lock cannot be taken and no sweep is known
|
|
209
|
+
to run: a record that cannot be read, a holder that cannot be told to be
|
|
210
|
+
running or gone, a gone holder's record that cannot be taken over, or the
|
|
211
|
+
earlier OATS's lock directory. The message says which it found and what
|
|
212
|
+
to do about it, and `error.details` is `{lock, found}`. `oats doctor`
|
|
213
|
+
lists the same states as a `resume-lock-stuck` problem, reading the lock
|
|
214
|
+
without taking it
|
|
215
|
+
([The machine sweep](../desktop-cli-api.md#the-machine-sweep-oats-session-resume)).
|
|
216
|
+
|
|
217
|
+
- **The setup expert now knows how an organisation's agents should work together.** A new capability in oats.framework, `oats.coordination-setup`, holds OATS's coordination practices (`/coordination-best-practices`) and four skills for shaping them to one organisation:
|
|
218
|
+
- `/adapt-to-the-organisation` runs at onboarding.
|
|
219
|
+
- `/design-the-roster` proposes the souls: an expert per way of working with areas as its knowledge nodes, developer souls by environment, reviewers, maintainers when a lane needs one, a dispatcher per person who wants one, and retire rules.
|
|
220
|
+
- `/set-landing-rules` writes, per lane, who merges on which agreement, who gives the green light to open a PR, and a merge path every lead can reach.
|
|
221
|
+
- `/review-the-setup` proposes the smallest change when a signal says the setup no longer fits.
|
|
222
|
+
|
|
223
|
+
The package soul `oats-setup-expert` composes it. Another soul uses it by naming `oats.coordination-setup: { from: package }`.
|
|
224
|
+
|
|
225
|
+
- Desktop logs one startup disposition for a launch carrying `--instance`,
|
|
226
|
+
including why no selection request could be sent. Linux output capture is
|
|
227
|
+
documented in [Desktop troubleshooting](../desktop.md#troubleshooting).
|
|
228
|
+
|
|
229
|
+
- **OATS's souls are split by way of working, not by area.** OATS's workspace gains a front door, two experts and one developer:
|
|
230
|
+
- **`dispatcher`**: each person's front door, from the engineering template (template-v2.1.0). It starts a fresh expert of the right soul per effort, introduces its lead and steps aside. Start one standing instance for each person who wants one: `oats spawn dispatcher --name <person>-dispatcher --task-file <who it serves.md>`.
|
|
231
|
+
- **`oats-engineering-expert`** (succeeding `oats-expert`): every engineering effort, in every area (the kernel and the CLI, the Terminal UI, the Desktop, the provider packages, operating a deployment, the docs). It shares `oats-expert`'s knowledge owner and node, `oats/oats-expert`, and reads each area's node per task. Until the knowledge base is organised by subject, an area lesson goes into its own node, with its area named in the concept.
|
|
232
|
+
- **`oats-product-expert`** (succeeding `market-research-expert`): vision, direction, users and positioning, research and trials, the README and the concept pages. It writes a brief and hands it to an engineering expert at an exact version. It shares `market-research-expert`'s knowledge owner and node, `oats/market-research-expert`, and names each direction decision for the maintainer's node in its hand-back.
|
|
233
|
+
- **`oats-developer`** (succeeding `oats-kernel-developer` and `oats-integrations-developer`): the kernel and the CLI, the Terminal UI, the provider package repositories and the docs. `oats-desktop-developer` keeps the Desktop.
|
|
234
|
+
|
|
235
|
+
- A reviewable agent container image, Compose service and Docker acceptance
|
|
236
|
+
script with pinned CLIs, arbitrary non-root UID support, read-only root,
|
|
237
|
+
SSH public-key access and explicit isolation evidence. See the
|
|
238
|
+
[container contract](../container.md) for mounts, deployment and the
|
|
239
|
+
prerequisites for live two-seat authentication.
|
|
240
|
+
|
|
241
|
+
## Changed
|
|
242
|
+
|
|
243
|
+
- **The getting-started skill sets npm's per-user folder and its PATH line in two commands** (oats-project/oats#1665). Step 2 named npm's per-user prefix in its text beside the PATH line's command, without saying to keep them apart, and an agent ran both as one command. Claude Code's auto mode refused it as persistence, even though the person's yes named both changes. Each is now its own command, under the name step 1's list gives it. Step 8 also says that the warning from Git older than 2.45 about whole-tree fetches is expected and harmless, in its once-per-command form and in the older once-per-repository form, and that Git 2.45 or later removes it.
|
|
244
|
+
|
|
245
|
+
- **Joining an existing workspace takes one paste.** With oats.aweb 1.36.0 or later and aw 1.36.53 or later, the getting-started skill has the joiner paste only the invite token: `oats aweb setup --soul S --invite-stdin --name A` reads the team and the service from the invite and refuses one that doesn't fit before redeeming it. The teammate no longer passes a service URL. Older versions keep the labelled form with `--join` and `--service` ([awebai/oats-aweb#56](https://github.com/awebai/oats-aweb/issues/56)).
|
|
246
|
+
|
|
247
|
+
- **A self-retire retries a cleanup that retire hooks alone left incomplete**
|
|
248
|
+
(oats-project/oats#1747). When the completion of `oats retire --self` ends
|
|
249
|
+
with the home quarantined, owing retire hooks and nothing else, it runs the
|
|
250
|
+
retire again up to three times: about 1, 5 and 15 minutes after each
|
|
251
|
+
failed attempt.
|
|
252
|
+
- A retry whose hooks pass removes the home and leaves nothing behind.
|
|
253
|
+
- After the last failed attempt the outcome is as before, plus `attempts`.
|
|
254
|
+
The marker, the quarantine and the one `retire-refused` event stay.
|
|
255
|
+
- Every attempt records its own `retired` event with its hooks.
|
|
256
|
+
- A quarantine that also owes Git steps, directory preservation or an
|
|
257
|
+
orphaned work directory is not retried.
|
|
258
|
+
- While the completion waits, `oats status` reads the retire as `running`.
|
|
259
|
+
Another retire of the home is refused with `E_LIFECYCLE_BUSY`, for up to
|
|
260
|
+
about 21 minutes after a hook failure. The refusal names the next attempt
|
|
261
|
+
and the earliest time the last one starts.
|
|
262
|
+
- Plain retires are unchanged
|
|
263
|
+
([Self-retire](../souls-and-instances.md#self-retire-hook-retry)).
|
|
264
|
+
|
|
265
|
+
- **A `launch-warning` or `retire-warning` row stores its message made safe
|
|
266
|
+
and bounded** (oats-project/oats#1749). Control, bidi and hidden characters
|
|
267
|
+
are replaced with U+FFFD, and the text is cut to 2048 UTF-16 code units
|
|
268
|
+
ending in `…`. A warning that is not a string is stored as its JSON. The row
|
|
269
|
+
shape is unchanged, and the answers' `warnings` keep each warning as it was said
|
|
270
|
+
([Events](../desktop-cli-api.md#events)).
|
|
271
|
+
|
|
272
|
+
- **A `souls:` pattern that matches no soul now warns `team-soul-unknown`**
|
|
273
|
+
(oats-project/oats#1759). A `<prefix>/*` key in `oats-workspace.yaml`
|
|
274
|
+
`souls:` whose prefix is no member or package with souls here (a typo, or a
|
|
275
|
+
package that was renamed or dropped) was ignored without a word; exact keys
|
|
276
|
+
already got the warning.
|
|
277
|
+
- It shows where an exact key's warning shows: `oats teams` and readiness
|
|
278
|
+
(`checks.configured`, not required), with the same code, `severity`,
|
|
279
|
+
`key` and `at`. Its message says the pattern matches no soul.
|
|
280
|
+
- The fix: correct the prefix to a member's or package's name (`oats souls`
|
|
281
|
+
lists them), or remove the key. A pattern that matches at least one soul,
|
|
282
|
+
and `"*"`, stay silent. Exact keys' message and fix are unchanged
|
|
283
|
+
([Workspaces](../workspaces.md), [Team readiness items](../desktop-cli-api.md#team-readiness-items)).
|
|
284
|
+
|
|
285
|
+
- **After a pin is removed or renamed, run `oats doctor`.** `/oats-package-pins` ("Change a pin") and [packages](../packages.md) now say: after removing or renaming a pin, or any soul it provided, run `oats doctor` on each deployment and fix what it reports, and check `souls.disabled` by hand. A `souls.disabled` entry that names a soul that no longer exists fails open: it disables nothing, so the soul it was meant to keep off spawns again under its new name.
|
|
286
|
+
|
|
287
|
+
- **A session start makes no `.oats-start.lock` directory.** Two starts of
|
|
288
|
+
one home already excluded each other through the home's lifecycle claim
|
|
289
|
+
(#1602); the start lock directory was a second guard that a killed start
|
|
290
|
+
left behind, after which every start of the home answered
|
|
291
|
+
`E_SESSION_START_BUSY` until it was removed by hand. A start now only
|
|
292
|
+
reads that path: a package upgrade that has not finished is refused as
|
|
293
|
+
before, naming its same-key retry
|
|
294
|
+
([Desktop CLI API](../desktop-cli-api.md)).
|
|
295
|
+
|
|
296
|
+
- **"CI green" in OATS's landing rules no longer holds with every check red.** The rules defined it as every check the forge requires at a head having succeeded. OATS's repositories require no check on their default branches, so that definition was empty. CI green at a head now means at least one check ran there, every check the forge requires is among them, and every check that ran succeeded: none failing, none pending. A head where no check ran isn't green. That holds with or without required checks, and a check that ran without being required can't fail on a green head either. Every skill that reads "CI green" (a developer's "Ready", a maintainer's read and merge, a release's source) takes it from the landing rules, so they change with it. A running instance takes the change up as the landing rules say a change reaches one: whoever lands it tells each standing instance and each open effort's lead, at its commit, and each records it in its state file. A respawn picks it up too.
|
|
297
|
+
|
|
298
|
+
- **The setup expert's coordination practices follow the templates' v3 way of working** (`oats.coordination-setup`, in `oats.framework`), at the engineering template's template-v3.0.1 and the research template's template-v2.0.0. `/coordination-best-practices` now teaches what an organisation's copy of a template will say:
|
|
299
|
+
- **The lead decides who builds each spec,** and builds it itself by default; a developer earns its place by context, parallel work or specialisation, and a large feature always goes to developers. In research, the lead decides who researches each angle the same way, a question with several angles always goes to researchers, and a fresh verifier checks every claim, the lead's own included.
|
|
300
|
+
- **A lead's children are helpers, each with one closed task** (a probe, a spec or a scoped piece), with their bounds and what they send back. Another area's step stays in the effort, never a second lead; a related effort's lead is the first lead's sibling, and the person is told its name. Every child is spawned `--same-work`.
|
|
301
|
+
- **Whoever builds a change runs its review loop,** and nothing lands without a fresh review: a one-line docs fix skips the local loop, not the review. The reviewer's severity decides whether the same reviewer re-reads a fix or a fresh one does, and a verdict that doesn't say what it checked is not a review. A lead starts a missing maintainer without asking, and tells the person what it is.
|
|
302
|
+
- **Every role's briefing says, in capitals, to keep loading its skills** as the work goes on; the setup expert's coordination briefing says the same.
|
|
303
|
+
- `/set-landing-rules` writes those rules as the default (who builds, when a review carries to a new head, the one-line docs fix, the green light for a lead's own change); `/design-the-roster` gives developers, reviewers, maintainers and the retire rules the same wording and names the research souls; `/adapt-to-the-organisation` names the research template for work that ends in a report and checks the copied role skills agree on who builds; `/review-the-setup` gains two signals, a lead that sends every small change to a developer or builds a large feature alone, and verdicts that don't say what they checked.
|
|
304
|
+
|
|
305
|
+
- **Onboarding adapts the coordination template with these practices.** `/oats-tailor-workspace` shapes a workspace's coordination template with `/adapt-to-the-organisation`: the roster of souls (`/design-the-roster`), the landing rules (`/set-landing-rules`) and, with several people, the ownership record. The capability notes the template version it started from.
|
|
306
|
+
|
|
307
|
+
- **Onboarding starts coordination from OATS's template repositories.** Coordination ships as templates, not packages. `/adapt-to-the-organisation` and `/oats-tailor-workspace` now start each group from the closest template repository at its latest `template-v*` tag and follow its `ADAPTING.md` in order: they check for capability ids the workspace already has before copying (a pin of the frozen `oats.engineering` moves by the template CHANGELOG's "From v1.18.0"; an earlier copy is upgraded in place), keep the template's `LICENSE` and `THIRD-PARTY-NOTICES.md`, keep an adapt marker only for a point that waits on a person, and record the release in each copied capability's description and in `capabilities/TEMPLATE-RELEASE`. The first template is `oats-project/oats-engineering-coordination`, at `template-v2.1.0`. The skills name it directly, so they find it on every kernel `oats.framework` admits; from this kernel release, `docs/official-catalog.md` lists the templates under "Coordination templates". `/review-the-setup` ports a later release from that record.
|
|
308
|
+
- **The package `oats.engineering` is frozen at v1.18.0.** Existing pins keep resolving through its catalog entry and aliases; its repository gets no further releases, and the engineering template lives in its own repository.
|
|
309
|
+
- **The coordination practices say which children are OATS instances.** `/coordination-best-practices` now sends proper work (an investigation or test the plan rests on, a review, work that needs a soul's knowledge or an environment) to OATS children, and allows the harness's own subagents (in Claude Code, pi or Codex) for small tasks that directly help the lead, when the person asks, or in a multi-agent workflow mode such as Claude Code's ultracode. A child that checks work runs on a different model from the agent whose work it checks, and the developer, not the expert, launches its fresh reviewer for each round. `/design-the-roster` gives the reviewer soul a launch on a model from a family different from the developers', `/oats-tailor-workspace` gives that soul its own launch entry where the machine's `souls.launch."*"` would replace its model on the same harness, and checks its effective model's family in its preview, and `/set-landing-rules` lets a lane exempt a lead's one-line docs fix or a maintainer's release prep from the review loop, never where every commit must pass a review round.
|
|
310
|
+
- **Probes test theories and approaches.** `/coordination-best-practices` adds testing a theory on small, concrete cases to a probe's questions. Where a plan can go more than one way, the lead probes the competing approaches in parallel and compares them on evidence, records every approach tried, and has a claim the plan rests on checked by another probe with fresh context, never by the probe that made it.
|
|
311
|
+
|
|
312
|
+
- A Desktop launch with `--dir <deployment> --instance <name>` opens the named
|
|
313
|
+
running local instance's terminal tab in the main area, through the same
|
|
314
|
+
viewer path as a roster click. Keyboard focus stays on the roster row;
|
|
315
|
+
the launch sends no input and starts nothing. Stopped, unknown, held,
|
|
316
|
+
unavailable or stale rows stay selected only, without a Start dialog.
|
|
317
|
+
A row first seen stopped during the 30-second pending window does not open
|
|
318
|
+
when it later starts. Your selection, typing or pointer press cancels a
|
|
319
|
+
pending request; a later launch replaces it.
|
|
320
|
+
|
|
321
|
+
- **`oats.framework` 1.23.0 adds `oats.coordination-setup` 1.0.0 and carries the coordination texts.** The new capability gives the setup expert OATS's coordination practices and how to shape them to one organisation: the roster of souls, the landing rules and when to revisit them. Its entries in these notes describe it. `oats.onboarding` 1.3.0's `/oats-tailor-workspace` starts coordination from OATS's template repositories. `oats.setup` 2.14.0's `/oats-package-pins` says to run doctor after a pin change, check `souls.disabled` by hand and check a reviewer soul's model. Its `/oats-teams` names the `<prefix>/*` pattern warning, and its `/oats-setup-model` names the new capability. `oats.core` 2.12.2's `/oats-souls` uses the new roster's names in its examples, and `oats.support` 1.0.2's `support-handoff` works without `/support-maintainer`. The lines that need this release say so: the catalog's "Coordination templates" section, the pattern warning and doctor's `souls.disabled` report are from OATS 0.69.13. No other command they name needs a newer OATS than each capability already admits.
|
|
322
|
+
|
|
323
|
+
- **OATS's workspace stops pinning `oats.engineering`.** Its souls already compose the `oats` repository's copy of the engineering template, and the template's `code-reviewer` soul joins them in `souls/`. Each of the ids the package shared with the copy (`oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer`) now has one source here, the member copy, so `oats capabilities show <id>` needs no `--member` or `--package`. The package is frozen, not retired: its catalog entry and its four aliases stay, so another workspace's pin keeps resolving ([official catalog](../official-catalog.md#coordination-templates)). No kernel or oats.framework release is needed.
|
|
324
|
+
|
|
325
|
+
- **`oats-expert`, `market-research-expert`, `oats-kernel-developer` and `oats-integrations-developer` are deprecated.** Each still resolves and composes as before, and its description says it is deprecated. New work spawns its successor:
|
|
326
|
+
|
|
327
|
+
| Deprecated soul | Successor |
|
|
328
|
+
|---|---|
|
|
329
|
+
| `oats-expert` | `oats-engineering-expert` |
|
|
330
|
+
| `market-research-expert` | `oats-product-expert` |
|
|
331
|
+
| `oats-kernel-developer` | `oats-developer` |
|
|
332
|
+
| `oats-integrations-developer` | `oats-developer` |
|
|
333
|
+
|
|
334
|
+
- **Nothing to change in a deployment now.** `souls.launch`, `souls.disabled`, team patterns, schedules and triggers that name a deprecated soul keep working. The souls' removal comes later, in a change of its own, with the steps it takes.
|
|
335
|
+
- **Two souls share each of two knowledge owners:** `oats-expert` and `oats-engineering-expert` own `oats/oats-expert`, and `market-research-expert` and `oats-product-expert` own `oats/market-research-expert`. Homes of either soul spawn, read and harvest into that node. No node changes owner.
|
|
336
|
+
- **A new home of a deprecated soul gets the current texts of the capabilities it shares with the new souls.** A new `oats-expert` home's coordinate-developers skill and surfaces table name `oats-developer` and `oats-engineering-expert`, so it launches `oats-developer`, not `oats-kernel-developer`. A running home keeps the texts it was spawned with.
|
|
337
|
+
- **Unchanged:** `oats-maintainer`, `oats-setup-admin`, `oats-desktop-developer` and `oats-public-expert`, whose texts now name the new souls. The area experts (`oats-kernel-expert`, `oats-desktop-expert`, `integrations-expert`, `oats-operator-expert`) stay and still own their knowledge nodes, but no text routes new work to them: the dispatcher and the surfaces table of `oats.workspace-experts` (1.2.0) name `oats-engineering-expert` for every engineering surface.
|
|
338
|
+
- The landing rules' "A PR with no lead here" says the person brings it to their dispatcher, as the template does.
|
|
339
|
+
- **oats.framework's texts name the new souls:** the setup inject sends framework questions to `oats-engineering-expert`, and the `oats-souls` naming examples use the current souls. They reach a deployment with the next oats.framework release.
|
|
340
|
+
|
|
341
|
+
- **OATS's own souls now compose OATS's copy of the engineering template, not the `oats.engineering` package.** The `oats` repository holds the template's capabilities at template-v3.0.0 (oats-project/oats-engineering-coordination, commit fa871ed0; its move from template-v2.1.0 is its own entry), adapted to OATS, in `capabilities/oats-<name>/` ([workspaces](../workspaces.md#member-tier-vs-package-tier-the-non-collapse-rule)). The experts, the developers and the maintainer (integrations-expert, oats-desktop-developer, oats-desktop-expert, oats-developer, oats-engineering-expert, oats-expert, oats-integrations-developer, oats-kernel-developer, oats-kernel-expert, oats-maintainer, oats-operator-expert, oats-product-expert, oats-public-expert, with the roster change's new souls in its own entry) compose `oats.engineering-expert`, `oats.developer` or `oats.maintainer` `from: here`, together with the new `oats.landing-rules` (and, for the souls that build, `oats.build`). The code reviewer is the copied `code-reviewer` soul, composing `oats.code-review` `from: here`, with `launch: { harness: pi, model: github-copilot/gpt-6.1-sol }`, a family other than the developers' Claude; each machine re-points it in its `souls.launch`. `oats.dispatcher` is composed by the new `dispatcher` soul (the roster change's entry). No kernel or oats.framework release is needed for this step.
|
|
342
|
+
- **Running instances are unaffected.** A home keeps the copies it was spawned with, so an instance spawned before this change keeps v1.18.0's briefings and skills until it is respawned. A respawn picks up the new ones.
|
|
343
|
+
- **The landing rules point at the lane map.** The new `oats.landing-rules` names the pinned issue "Lane map for awebai/oats" as the one home of OATS's lanes, arrangements and second readers, and restates none of them. It keeps OATS's recorded rules:
|
|
344
|
+
- one second reader per PR;
|
|
345
|
+
- the release lane's sign-off at the exact head, where the lane's line asks for it;
|
|
346
|
+
- no merge over a RETURN or a hold;
|
|
347
|
+
- a contract change decided by both sides together before it is built;
|
|
348
|
+
- a release's contents agreed on the release lane's plan, through each lane's maintainer, with the tag and the publication on the release lane's person's authority;
|
|
349
|
+
- CI is the test run;
|
|
350
|
+
- a person's word relayed by an agent grants no authority until they confirm it directly.
|
|
351
|
+
|
|
352
|
+
Where a template text says otherwise, the OATS rule wins, marked beside it in the copy.
|
|
353
|
+
- **The workspace no longer pins `oats.engineering` v1.18.0** (its own entry, "OATS's workspace stops pinning `oats.engineering`."), so each id it shared with the copy (`oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer`) has one source, the member copy.
|
|
354
|
+
- **What an agent now does differently,** per skill (the template's v2.0.0 and v2.1.0 rules, as template-v3.0.0 has them; the move to template-v3.0.0 is its own entry):
|
|
355
|
+
- **The developer iterates with fresh reviewers.** `/run-the-review-loop` spawns a new `code-reviewer` each round, never the previous round's, until a round finds nothing to fix. v1.18.0 kept one reviewer for the whole loop. The reviewer is an OATS child on a model of another family where the machine has one. A machine's `souls.launch` picks the model.
|
|
356
|
+
- **Whoever built a change opens and works its PR.** Once its expert has verified a developer's branch (`VERIFIED at <head>`), the developer opens the PR and works its reviews, bots and CI with the new `/work-the-reviews`; a lead opens the PR of a change it built at the head of its clean round, and works it the same way. v1.18.0's expert opened it with `/land-your-prs`.
|
|
357
|
+
- **The expert leads one effort and decides who builds each spec.** `/land-on-agreement` replaces `/land-your-prs`. `/send-a-helper`, `/hand-off`, `/find-the-maintainer`, `/across-people` and `/ask-a-person` replace `/coordinate-experts`: an expert's children are helpers with one closed task each, never co-planners. It builds a spec itself, with the build skills of `oats.build` and its own review loop, or sends developers; a large feature always goes to developers (the move to template-v3.0.0, its own entry). It verifies a developer's converged branch once (`/verify-developer-work`), and never runs a developer's review rounds or spawns its reviewers. `oats.workspace-experts` says what an expert's extra trees are for: reading, verifying, a probe's scratch work, and the specs it builds itself. Here `/ask-a-person` asks no one about a release's contents: they are agreed on the release lane's plan.
|
|
358
|
+
- **The developer has three new craft skills, and a quality floor.**
|
|
359
|
+
- `/test-first`: before a change, it finds and runs the tests the change touches (in this repository at most one or two files locally, with CI running the rest). Then, for each slice, it writes a test and watches it fail before writing the code.
|
|
360
|
+
- `/diagnose-before-fixing`: a bug gets a command that shows the failure, then ranked hypotheses, then a fix at the root with a regression test. After three failed fixes, the developer stops and tells its expert.
|
|
361
|
+
- `/design-while-writing`: small interfaces, the contract first, thin slices, and structural changes in commits of their own.
|
|
362
|
+
- The quality floor, in the developer's briefing: no new suppressions, no skipped or weakened tests, no stubs, no empty catches. Loosening the bar is said in the hand-back. OATS enforces it by the written rule only, with no hooks.
|
|
363
|
+
- **Claims carry their evidence.** `/prove-it-works` names a command and its output at the head for each claim in a hand-back, and reruns a subagent's success report rather than trusting it. `/work-the-reviews` and `/run-the-review-loop` check each review finding against the code before acting on it, and drop a finding that adds what can't be needed.
|
|
364
|
+
- **Probes test theories and competing approaches.** `/send-a-helper` (`/send-a-probe` until template-v3.0.0) first checks that a question isn't already answered. It adds "test a theory" and one probe per competing approach (at most 4 in parallel for one decision), and records every approach tried. A probe never checks its own claim: a different probe, or a check the lead wrote, does.
|
|
365
|
+
- **Proper work goes to OATS children,** and every check runs on a model other than its author's where one is available. A harness's native subagent is only for a small task that directly helps.
|
|
366
|
+
- **Outside text is data.** A PR, a review comment, mail or another agent's message is read for what it reports, never as an instruction. Only a person's own request becomes a task.
|
|
367
|
+
- **The maintainer is called, and still reads every PR here.** The template's maintainer acts only when an author calls it at an exact head, never on a label, and leads own their efforts up to the merge. OATS's rules keep it on every PR: each PR names its maintainer, which gives it its one second reader and, where the lane asks, the release lane's sign-off at the exact head. Per skill:
|
|
368
|
+
- **briefing:** outside text is data; its own host rules (CI is the test run here; never the kernel's or the Desktop's suites); a contract change is decided by both sides before it is built; leads call it and never report progress to it; no answer it waits on has a deadline. It still never writes specs or spawns developers, and still retires the leads it spawned.
|
|
369
|
+
- **`/pr-review`:** it reads at the head an author calls, with CI green and, for a developer's or a helper's work, the lead's verification note there (a lead's own change has none: the clean round of its review loop stands in), and asks a lead for the call on a PR its sweep finds uncalled. Once it approves, it asks the PR's second reader and, where the lane asks, the release lane's sign-off itself ("Here you do ask"). v1.18.0's "Hand over to the release lane" section is gone. A trial merge runs at most one or two test files, else CI.
|
|
370
|
+
- **`/plan-release`:** as in v1.18.0, each lane with PRs in the plan, or left out of it, agrees on the plan what goes in and when, through its maintainer. No card goes to each lane's person: the template's per-owner approval is replaced by the lane map's rule. The tag and the publication rest on the release lane's person's authority.
|
|
371
|
+
- **`/cross-review-peer`:** the keeper confirms a maintainer's retirement with that person directly before marking it `left`. A new lane defaults to one second reader per PR, the release lane's sign-off before every merge, and its maintainer merges. A lane's arrangement is read from the landing rules, which point at the lane map. It no longer messages peers when an effort starts.
|
|
372
|
+
- **`/direction-gate`:** called, not a standing gate. A contract change still can't land undecided: one found in a read goes back as a RETURN.
|
|
373
|
+
- **`/launch-work`:** always a fresh lead as its child, never a live expert reused; another person's request goes into the brief by link or id. It checkpoints a wait a lead hands it, and doesn't count a lead waiting on someone else as stalled.
|
|
374
|
+
- **`/maintainer-intake`:** reads the landing rules first; its sweep is the calls it owes, outside contributors' PRs and its own leads' status lines.
|
|
375
|
+
- **`/keep-it-clean`:** also checks the docs and notes of what merged in its sweep, and asks a stale PR's author or lead about it.
|
|
376
|
+
- **`/ship-release`:** publishes on the release lane's person's authority, on the plan the lanes agreed, and hands a release-workflow fix to a lead.
|
|
377
|
+
- **`/support-maintainer`:** removed; OATS runs no support desk.
|
|
378
|
+
- **The support desk's hand-off brief works with or without `/support-maintainer`.** In oats.support's `/support-handoff`, a maintainer the desk spawns loads `/support-maintainer` where its briefing has it. Otherwise it works the tickets as the hand-off gives them: it triages each one and routes it to one expert lead. OATS's maintainer copy has no `/support-maintainer`.
|
|
379
|
+
- **Old → new skills,** from `oats.engineering` v1.18.0 to OATS's copy:
|
|
380
|
+
|
|
381
|
+
| v1.18.0 | OATS's copy (template-v3.0.0) |
|
|
382
|
+
|---|---|
|
|
383
|
+
| `/land-your-prs` (expert) | `/land-on-agreement`; whoever built the change opens and works the PR (`/work-the-reviews`) |
|
|
384
|
+
| `/coordinate-experts` (expert) | `/send-a-helper`, `/hand-off`, `/find-the-maintainer`, `/across-people`, `/ask-a-person` |
|
|
385
|
+
| `/plan-and-spec`, `/coordinate-developers`, `/verify-developer-work` (expert) | the same names, the template's text |
|
|
386
|
+
| (expert, new) | `/findings-and-blocks` |
|
|
387
|
+
| `/understand-the-spec`, `/execution-strategy`, `/worktrees`, `/run-the-review-loop`, `/maintain-dev-docs` (developer) | the same names, the template's text; all but `/understand-the-spec` now in `oats.build` |
|
|
388
|
+
| (developer, new) | `/prove-it-works`, `/work-the-reviews`, `/test-first`, `/diagnose-before-fixing`, `/design-while-writing`, in `oats.build` |
|
|
389
|
+
| `/pr-review`, `/direction-gate`, `/launch-work`, `/cross-review-peer`, `/plan-release`, `/ship-release`, `/keep-it-clean`, `/maintainer-intake` (maintainer) | the same names; what changes is listed per skill above |
|
|
390
|
+
| `/support-maintainer` (maintainer) | removed |
|
|
391
|
+
| (dispatcher, new; the `dispatcher` soul composes it) | `/dispatch` |
|
|
392
|
+
| `/adversarial-review`, `/security-review`, `/simplification-review`, `/review-dev-docs` (code review) | the same names, the template's text |
|
|
393
|
+
|
|
394
|
+
- **OATS's copy of the engineering template moves to template-v3.0.1** (oats-project/oats-engineering-coordination, commit 0e880322), a patch: a fix a maintainer finds goes to a lead, which decides who builds it, in the landing rules and in the maintainer's `/pr-review`, `/cross-review-peer`, `/plan-release` and `/ship-release`. OATS's copy already said so, marked as its own rule; the marks come out, since the text now matches the template. The maintainer soul's text says the lead expert decides who builds each spec.
|
|
395
|
+
|
|
396
|
+
- **OATS's copy of the engineering template moves to template-v3.0.0** (oats-project/oats-engineering-coordination, commit fa871ed0), from template-v2.1.0, taking in template-v2.2.0 on the way. The ids stay, one is added (`oats.build`), and OATS's own rules still win where they differ, marked in the copy: the lane map, one second reader per PR, the release lane's sign-off where a lane asks, the lane's maintainer merges, CI is the test run, and no text names a harness or a model.
|
|
397
|
+
- **The lead decides who builds each spec,** and builds it itself by default. It sends developers where one protects its context, builds in parallel, or specialises in a lane of its own (the Desktop's display, say). A large feature, more than one surface or sustained building and testing, always goes to developers. Whoever builds a change runs the review loop, a fresh `code-reviewer` each round, and the lead is never its own reviewer. It still verifies a developer's converged branch once and never runs a developer's rounds.
|
|
398
|
+
- **Nothing lands without a fresh review,** a one-line docs fix included: the fix skips the local loop, not the review. A lead's own PR carries no `VERIFIED` note, since nobody verifies their own work: the clean round of its review loop stands in for it, in the landing rules and in the maintainer's `/pr-review` and `/cross-review-peer`.
|
|
399
|
+
- **A new capability, `oats.build`,** holds the nine build skills, moved out of `oats.developer`: `/execution-strategy`, `/worktrees`, `/test-first`, `/diagnose-before-fixing`, `/design-while-writing`, `/prove-it-works`, `/run-the-review-loop`, `/work-the-reviews` and `/maintain-dev-docs`. `oats.developer` keeps `/understand-the-spec`. Ten souls compose it:
|
|
400
|
+
- the developers, `oats-developer`, `oats-desktop-developer`, `oats-kernel-developer` and `oats-integrations-developer`, whose skill lists are unchanged;
|
|
401
|
+
- the engineering experts that build their own specs, `oats-engineering-expert`, `oats-expert`, `oats-kernel-expert`, `oats-desktop-expert`, `integrations-expert` and `oats-operator-expert`, which gain those nine skills.
|
|
402
|
+
|
|
403
|
+
`oats-product-expert` and `oats-public-expert` don't: each builds nothing, and its own text says so.
|
|
404
|
+
- **Three of the moved skills change** (the other six are unchanged): `/execution-strategy` works in one context by default and splits only by context, never by kind of work, so a change and its tests stay with one agent; `/run-the-review-loop` sends a fix to a minor back to the same reviewer as a delta, and a fix to a blocker or a major to a fresh one; `/work-the-reviews` reviews each new head of a PR as its findings' severity says.
|
|
405
|
+
- **`/send-a-probe` is now `/send-a-helper`.** A lead's children are helpers, each with one closed task: a question (a probe), a spec (a developer), or a scoped piece of its effort that needs another soul (a scoped helper hands its clean round back, and opens no PR until the lead has verified it). A helper is started for one of four reasons: to split context, to test a theory or an approach before the plan rests on it, to bring a specialist, or to work in parallel. Another area's step of an effort stays in that effort, never a second lead.
|
|
406
|
+
- **Briefs are closed and verdicts are checked.** A helper's brief gives its bounds and what it sends back, in order. A reviewer's report lists what it checked, and a round counts as clean only with that list.
|
|
407
|
+
- **A related effort's lead is a sibling** (`--relation sibling`), which outlives the first lead's retire, and the person is told its exact name. Every recipe that starts a child carries `--same-work`, which records that the child does its parent's work and shares no work tree.
|
|
408
|
+
- **A lead with no maintainer for its lane starts one itself,** without asking, and tells its person in two or three plain sentences what a maintainer is, what it is for, and its name.
|
|
409
|
+
- **Every role's briefing opens with a line to keep loading the skill for each step,** each time the step comes round, not once at the start. A lead's briefing also carries the quality floor and the host rules (CI is the test run here; never the kernel's or the Desktop's suites locally) for the specs it builds.
|
|
410
|
+
- **`oats.workspace-experts` 1.3.0:** an expert's own worktrees are also for the specs it builds itself; a large feature goes to developers.
|
|
411
|
+
- **Running homes keep the texts they were spawned with** until they are respawned. A home of an expert soul spawned before this change builds nothing, as before.
|
|
412
|
+
|
|
413
|
+
- **An older Git is reported once per command, not once per repository.** On
|
|
414
|
+
a Git older than 2.45, every cache a command started, or rebuilt from a
|
|
415
|
+
partial cache, printed its own `oats: warning: git <version> cannot keep a
|
|
416
|
+
partial cache (it needs 2.45); OATS fetches whole trees from <url>`, so an
|
|
417
|
+
`oats onboard` on a fresh host opened on a run of identical warnings. A
|
|
418
|
+
command now prints one line, however many repositories it fetches:
|
|
419
|
+
`oats: warning: git <version> cannot keep a partial cache (it needs 2.45), so OATS fetches whole trees instead; a git of 2.45 or later removes this notice`.
|
|
420
|
+
The fallback is unchanged: each cache still fetches whole trees and records
|
|
421
|
+
`oats.fetch = full`. The notice for a server that does not serve partial
|
|
422
|
+
fetches and the stale-lock notice are unchanged
|
|
423
|
+
([Workspaces](../workspaces.md)).
|
|
424
|
+
|
|
425
|
+
- **The README says plainly how to onboard.** The top of the README gives the one sentence to tell your coding agent. Start here lists what you need (macOS or Linux, Claude Code, Codex or pi, and a GitHub account), what the agent does, about how long it takes, and how to join a teammate's workspace instead. The getting-started skill's download URL is now `raw.githubusercontent.com/oats-project/oats/...`; the old `awebai/oats` URL still redirects.
|
|
426
|
+
|
|
427
|
+
- **A reviewer soul keeps its own model under the machine's default launch.** A `souls.launch."*"` entry replaces a soul's model as well as its harness, and the per-soul rule gave a soul its own entry only when its harness differed, so a reviewer soul declaring the developers' harness with another model ran on the developers' model. `/oats-package-pins` (after a sync that adds a package soul) and the getting-started skill (step 8, "Record the harness for every soul") now give such a reviewer its own entry with its model, and check that its `oats spawn --preview --json` shows a `launch.effective` model from a family other than the developers'. With no such model on the machine, the person is told. `/oats-tailor-workspace` carries the same rule for the souls it adds.
|
|
428
|
+
|
|
429
|
+
## Fixed
|
|
430
|
+
|
|
431
|
+
- **A home whose package is gone is pointed at a respawn, for every package**
|
|
432
|
+
(oats-project/oats#1759, items 2 and 3). A workspace that stops declaring a
|
|
433
|
+
package leaves the homes composed from it on their recorded copies, and only
|
|
434
|
+
a respawn moves them.
|
|
435
|
+
- `oats readiness --home` no longer only tells such a home to declare the
|
|
436
|
+
package again. Readiness cannot tell a deliberate drop from an accidental
|
|
437
|
+
unpin or a pending sync, so the `package <package>/<soul>` item's remedy
|
|
438
|
+
names both, the respawn first: if the workspace dropped the package on
|
|
439
|
+
purpose, spawn a new instance from a soul the workspace offers, then retire
|
|
440
|
+
this one; otherwise declare it in `packages:` and `oats sync`. Readiness
|
|
441
|
+
of a soul (`--soul`) still names declaring the package and `oats sync`
|
|
442
|
+
([`oats readiness`](../desktop-cli-api.md#oats-readiness)).
|
|
443
|
+
- `oats session start` and `restart` add one warning for package modules an
|
|
444
|
+
upgrade cannot move, because their package is no longer locked or no
|
|
445
|
+
longer provides the capability, naming each and the respawn. Before, only
|
|
446
|
+
modules behind the lock got a hint. `drift` is unchanged: it lists the
|
|
447
|
+
modules an upgrade moves in place
|
|
448
|
+
([Start and restart](../desktop-cli-api.md#start-and-restart)).
|
|
449
|
+
|
|
450
|
+
- **A package pinned under another package's id is no longer locked
|
|
451
|
+
silently** (oats-project/oats#1759). A pin such as `acme.tools: v2.0.0`,
|
|
452
|
+
whose release's manifest names `acme.tools-next`, was locked under
|
|
453
|
+
`acme.tools`, and its souls were named `acme.tools/<soul>`. `sync` now
|
|
454
|
+
refuses it, and names the line to write under `acme.tools-next`: that id
|
|
455
|
+
at the same version when the catalog lists it, else
|
|
456
|
+
`git:<the catalog's repository for acme.tools>@<the resolved tag>`.
|
|
457
|
+
|
|
458
|
+
- **`oats doctor` reports a `souls.disabled` entry that names no soul**
|
|
459
|
+
(oats-project/oats#1772). Spawn matches each entry of `oats-local.yaml`
|
|
460
|
+
`souls.disabled` by its exact name. An entry whose soul was renamed or moved
|
|
461
|
+
(a removed package pin, for example) therefore keeps nothing off this
|
|
462
|
+
machine, and nothing said so. Such an entry fails open: the soul it was
|
|
463
|
+
meant to keep off becomes spawnable again under its new name. A stale
|
|
464
|
+
`souls.launch` key, by contrast, fails closed. Run `oats doctor` after any
|
|
465
|
+
rename or removal.
|
|
466
|
+
- Doctor adds one `disabled-soul-unmatched` problem per such entry, with
|
|
467
|
+
the nearest souls the workspace offers and the hand edit that fixes it:
|
|
468
|
+
replace the entry with the soul it was meant for, or remove it.
|
|
469
|
+
- An entry doctor could not check against this machine's last read, or a
|
|
470
|
+
cache that cannot answer, is a `disabled-soul-unchecked:` information
|
|
471
|
+
line, by the same rules as the `souls.launch` check.
|
|
472
|
+
- Doctor still exits 0. Spawn, `oats souls`, readiness and inspect are
|
|
473
|
+
unchanged
|
|
474
|
+
([Launch preferences](../desktop-cli-api.md#launch-preferences),
|
|
475
|
+
[`souls.disabled`](../configuration.md)).
|
|
476
|
+
|
|
477
|
+
- **`oats worktree add --repo <name>` no longer tells the operator to repoint a
|
|
478
|
+
good clone** (oats-project/oats#1781). A name that isn't a repository key,
|
|
479
|
+
such as a member's name (`--repo oats`) or `--repo awebai/oats`, names no
|
|
480
|
+
member and matches no remote. The refusal still ended with a Git command
|
|
481
|
+
built from that name, `git -C <clone> remote set-url origin
|
|
482
|
+
https://oats.git`, and pasting it pointed a correct clone at a URL that
|
|
483
|
+
doesn't exist.
|
|
484
|
+
- When the clone at the name's convention path has a remote of that name,
|
|
485
|
+
the refusal names the key to pass, `--repo github.com/awebai/oats`, and
|
|
486
|
+
the clone's path as the other spelling that works.
|
|
487
|
+
- Otherwise it says to pass a member's key (`<host>/<org>/<repo>`) or a
|
|
488
|
+
clone path. It never suggests a Git command or a `clones:` entry for such
|
|
489
|
+
a name.
|
|
490
|
+
- The refusals keep their codes and `details`: `E_CLONE_MISMATCH` when a
|
|
491
|
+
clone is at the convention path, `E_CLONE_MISSING` when there is none.
|
|
492
|
+
A well-formed key and spawn's `--repo` are unchanged
|
|
493
|
+
([Extra trees](../souls-and-instances.md#extra-trees)).
|
|
494
|
+
|
|
495
|
+
- **`oats retire` refuses a flag it does not read** (oats-project/oats#1790). `oats retire <instance>
|
|
496
|
+
--keep-dirs`, a typo for `--keep-dir`, was accepted, the flag was ignored,
|
|
497
|
+
and the instance's home was removed.
|
|
498
|
+
- A flag retire does not define, or an argument after the instance, is
|
|
499
|
+
refused with `E_BAD_ARGS` before anything happens: before `--plan`
|
|
500
|
+
answers, a child is stopped, a hook runs, or a `--server` retire is sent
|
|
501
|
+
to its host. The message names the flag (`oats retire: unknown flag
|
|
502
|
+
--keep-dirs`) and prints the usage; under `--json` the envelope carries
|
|
503
|
+
`error.details.flag` or `error.details.argument`.
|
|
504
|
+
- The flags retire reads are `--plan`, `--plan-revision`,
|
|
505
|
+
`--idempotency-key`, `--home`, `--dir`, `--server`, `--self`,
|
|
506
|
+
`--discard-worktree`, `--keep-dir`, `--force` and `--json`
|
|
507
|
+
([Retire](../souls-and-instances.md#retire)). A script that passes
|
|
508
|
+
`oats retire` any other flag, such as `--agents-root`, which retire never
|
|
509
|
+
read, gets the refusal: remove the flag.
|
|
510
|
+
|
|
511
|
+
- **Inside a container, `oats session resume` counts a boot per run of the
|
|
512
|
+
container** (oats-project/oats#1792). A container shares its host's kernel, so the kernel's boot id,
|
|
513
|
+
which the sweep read as the boot, stayed the same when the container was
|
|
514
|
+
stopped and started, although every session in it was gone. With
|
|
515
|
+
`~/.oats` on a volume, the third restart of a container within one host
|
|
516
|
+
uptime used up the 3 sweep starts a home has per boot, and the sweep then
|
|
517
|
+
answered `keeps-getting-lost` for sessions lost with the container; a
|
|
518
|
+
session lost with a container that stayed down for a day or more was
|
|
519
|
+
answered `not-seen-recently`, since the 24-hour clause of one boot applied
|
|
520
|
+
across the restart. The boot in a container is the kernel's boot id
|
|
521
|
+
together with the start time of the container's PID 1 (`/proc/1/stat`),
|
|
522
|
+
which is the same all through one run and another in the next. OATS takes
|
|
523
|
+
itself to be in a container when `/.dockerenv` or `/run/.containerenv`
|
|
524
|
+
exists or `KUBERNETES_SERVICE_HOST` is set. On a Linux host and on macOS
|
|
525
|
+
the boot is what it was, and the sweep's records stay valid; in a container
|
|
526
|
+
the first sweep after the upgrade starts a new count
|
|
527
|
+
([Execution targets](../execution-targets.md#the-sweep)).
|
|
528
|
+
|
|
529
|
+
- **A lock left by a command that was killed no longer stops the commands
|
|
530
|
+
after it.** The locks of the host scheduler (`~/.oats/schedules/host.lock`,
|
|
531
|
+
`registry.lock`, a deployment's `scope.lock`), of the server registry
|
|
532
|
+
(`~/.oats/servers.lock`), of this computer's deployments list
|
|
533
|
+
(`~/.oats/config/deployments.lock`) and of a deployment's `oats-local.yaml`
|
|
534
|
+
(`.agents/locks/local.lock`) were directories that nothing but their holder
|
|
535
|
+
removed: a tick or a command killed with SIGKILL, by the out-of-memory
|
|
536
|
+
killer or by a reboot left its lock behind, and every later command
|
|
537
|
+
answered `E_SCHEDULER_BUSY` (or `E_SERVERS_BUSY`, `E_DEPLOYMENTS_BUSY`,
|
|
538
|
+
`E_LOCAL_BUSY`) until someone deleted the directory by hand, so the
|
|
539
|
+
per-minute scheduler stopped for good after one killed tick. Each lock is
|
|
540
|
+
now a file that names its holder by pid and start time, and the next command
|
|
541
|
+
takes over a lock whose holder is gone. A holder that is still running is
|
|
542
|
+
never taken over. A SIGINT or SIGTERM that arrives inside a locked section
|
|
543
|
+
waits for it: the section completes, the lock is released, and the signal
|
|
544
|
+
then ends the command (it was lost before, and the command ran on). Three cases still need the operator, and the message says
|
|
545
|
+
which it found and names the path: a lock file whose record is unreadable
|
|
546
|
+
(remove the file), a holder that cannot be told to be running or gone
|
|
547
|
+
(check that pid by hand, then remove the file), and a lock directory written
|
|
548
|
+
by an earlier kernel, which is never removed for you (remove the directory
|
|
549
|
+
once no older oats is running) ([Schedules](../schedules.md#files)).
|
|
550
|
+
|
|
551
|
+
- **`oats instance git` and `oats instance diff` run no filter driver the
|
|
552
|
+
work tree's repository configures.** A repository's own configuration,
|
|
553
|
+
which an agent working in the tree can write, can define
|
|
554
|
+
`filter.<name>.clean` or `filter.<name>.process` and select it with a
|
|
555
|
+
`filter` attribute (`.gitattributes`, or `info/attributes` in the Git
|
|
556
|
+
directory). Git runs such a command during a `git status` or a `git diff`,
|
|
557
|
+
as whoever runs it. Every Git command of the observation that reads a
|
|
558
|
+
work-tree file is preceded by a read of the configuration
|
|
559
|
+
(`git config --list`, which runs nothing), and each filter driver it
|
|
560
|
+
defines is overridden to no command.
|
|
561
|
+
- The observation of a repository with no filter driver is unchanged.
|
|
562
|
+
- A file a filter applies to (a Git LFS file, for one) is compared as its
|
|
563
|
+
bytes are in the work tree: rewritten, it reads as `changed` even when
|
|
564
|
+
its filtered form is what is stored, and its diff is the stored form
|
|
565
|
+
against the work tree's bytes. The observation says so in a note.
|
|
566
|
+
- A driver whose name cannot be passed on Git's command line (it holds `=`
|
|
567
|
+
or is not UTF-8) refuses the read with `E_GIT_FAILED`.
|
|
568
|
+
- Not covered: a driver written between that read and the Git command, and
|
|
569
|
+
a filter that a submodule's own configuration defines, which matters
|
|
570
|
+
where the agent and the reader of its worktree are separate system users
|
|
571
|
+
([Git and diff](../desktop-cli-api.md#git-and-diff)).
|
|
572
|
+
|
|
573
|
+
- **A spawn refuses a package whose content is not what the lock records.**
|
|
574
|
+
`oats-lock.json` pins each package to a `commit` and to the `integrity` of
|
|
575
|
+
its tree, but a spawn compared neither with what it copied. A lock whose
|
|
576
|
+
commit and integrity disagreed (a hand edit, a bad merge), or a package
|
|
577
|
+
copy that changed in this computer's remote cache, spawned without a word.
|
|
578
|
+
- `oats spawn`, and `oats spawn --preview`, now digest the tree of every
|
|
579
|
+
package the soul composes a capability from, at the locked commit, and
|
|
580
|
+
refuse a mismatch with `E_PACKAGE_INTEGRITY` before anything is written:
|
|
581
|
+
no soul copy, no worktree, no instance home. The message names the
|
|
582
|
+
package, the commit, the lock's digest and the one computed, and
|
|
583
|
+
`details` is `{package, version, commit, expected, actual}`.
|
|
584
|
+
- The digest is taken once per package version on a computer. A tree that
|
|
585
|
+
matched is recorded under the remote cache (`.verified/`), with the state
|
|
586
|
+
of the cached repository it was read from, and a later spawn digests
|
|
587
|
+
again only when a file of that repository was added, removed, replaced or
|
|
588
|
+
rewritten since. The records are the kernel's own and safe to delete.
|
|
589
|
+
- `oats instance upgrade` already made this comparison for the packages it
|
|
590
|
+
moves a module to. Its refusal now carries the same message, and its
|
|
591
|
+
`details` gain `version` and `commit` beside `package`, `expected` and
|
|
592
|
+
`actual`
|
|
593
|
+
([The integrity check at spawn](../packages.md#the-integrity-check-at-spawn)).
|
|
594
|
+
|
|
595
|
+
- **`oats retire` and `oats worktree remove` run no filter driver the
|
|
596
|
+
repository configures.** A repository's own configuration, which an agent
|
|
597
|
+
working in the tree can write, can define `filter.<name>.clean` or
|
|
598
|
+
`filter.<name>.process` and select it with a `filter` attribute
|
|
599
|
+
(`.gitattributes`, or `info/attributes` in the Git directory). Git runs
|
|
600
|
+
such a command during a `git status`, as whoever runs it, and a retire and
|
|
601
|
+
a removal both ask for one: a retire of the worktree, of a repository
|
|
602
|
+
under it and of its recovery copy (and a spawn, for the baseline a retire
|
|
603
|
+
compares with); a removal for its own status, inside `git worktree remove`
|
|
604
|
+
and when it compares an unregistered tree's surviving files. Each of
|
|
605
|
+
those commands is preceded by a read of the configuration
|
|
606
|
+
(`git config --list`, which runs nothing), and each filter driver it
|
|
607
|
+
defines is overridden to no command, as `oats instance git` does it.
|
|
608
|
+
- A retire or a removal in a repository with no filter driver of its own
|
|
609
|
+
is unchanged. A driver that the operator's global or system
|
|
610
|
+
configuration defines runs with the operator's command, also when the
|
|
611
|
+
repository defines one of the same name (`git lfs install --local`):
|
|
612
|
+
the repository's values for that name are replaced by the operator's.
|
|
613
|
+
- A file a repository's filter applies to is compared as its bytes are in
|
|
614
|
+
the work tree. A clean filter could make a rewritten file read as
|
|
615
|
+
unchanged: `oats retire --discard-worktree` then removed the worktree
|
|
616
|
+
with that file in it and wrote no recovery, and `oats worktree remove`
|
|
617
|
+
removed the tree. Such a file is uncommitted work: the retire copies it
|
|
618
|
+
to the recovery, and the removal refuses with `E_WORKTREE_DIRTY`. A
|
|
619
|
+
file whose size and times are the ones the index recorded still reads
|
|
620
|
+
as unchanged.
|
|
621
|
+
- A driver whose name cannot be passed on Git's command line (it holds `=`
|
|
622
|
+
or is not UTF-8) is refused before Git runs. A retire answers
|
|
623
|
+
`E_WORK_INSPECTION_FAILED` before its hooks, with `--discard-worktree`
|
|
624
|
+
and `--force` too; a spawn into a worktree of that repository is
|
|
625
|
+
refused and rolled back; a removal answers
|
|
626
|
+
`E_WORK_PRESERVATION_FAILED` with the tree and its record kept.
|
|
627
|
+
- A retire that copies a worktree compares the copy's status with the
|
|
628
|
+
worktree's, and the copy has none of the repository's configuration.
|
|
629
|
+
For a file a repository's filter applies to, the two can disagree, and
|
|
630
|
+
the retire then refuses with `E_WORK_PRESERVATION_FAILED` and removes
|
|
631
|
+
nothing. That is so only for a driver the repository alone defines,
|
|
632
|
+
and was so before (an untouched file whose stored form is the filtered
|
|
633
|
+
one).
|
|
634
|
+
- Not covered: a driver written between that read and the Git command,
|
|
635
|
+
and a filter that a submodule's own configuration defines, which matters
|
|
636
|
+
where the agent and whoever retires or removes its worktree are separate
|
|
637
|
+
system users
|
|
638
|
+
([Filter drivers](../souls-and-instances.md#retire-filter-drivers)).
|
|
639
|
+
|
|
640
|
+
- **`oats session resume` takes over the lock of a sweep that is gone at
|
|
641
|
+
once, and never mistakes another process for it.** The sweep's lock
|
|
642
|
+
(`~/.oats/session-resume/lock`) named its holder by pid alone within one
|
|
643
|
+
boot: when a sweep was killed and its pid went to another process, every
|
|
644
|
+
later sweep answered `E_RESUME_BUSY` until that process ended, and a sweep
|
|
645
|
+
killed just as it took the lock stopped the others for a minute. The lock
|
|
646
|
+
is now a file that names its holder by pid, start time and boot, as the
|
|
647
|
+
kernel's other locks do: the next sweep takes over a lock whose holder
|
|
648
|
+
exited, was killed (a container's stop included) or took it in another
|
|
649
|
+
boot, with no wait. A sweep that is still running is never taken over, and
|
|
650
|
+
a second sweep answers `E_RESUME_BUSY` as before
|
|
651
|
+
([Execution targets](../execution-targets.md#the-sweep)).
|
|
652
|
+
|
|
653
|
+
- **The commands that change state refuse a flag they do not define**
|
|
654
|
+
(oats-project/oats#1791). `oats instance stop`, `oats instance upgrade`,
|
|
655
|
+
`oats worktree add` and `remove`, `oats session start` and `restart`,
|
|
656
|
+
`oats schedule remove`, `run`, `enable`, `disable`, `reconcile` and
|
|
657
|
+
`host uninstall`, `oats trigger remove`, `enable` and `disable`, `oats
|
|
658
|
+
server remove` and `forget`, `oats package add` and `remove`, `oats
|
|
659
|
+
launch-config set` and `remove`, and `oats automations refresh` read the
|
|
660
|
+
flags they knew and ignored every other one, so a typo of a protective
|
|
661
|
+
flag did the unprotected thing: `oats instance stop <instance> --apply
|
|
662
|
+
... --no-recursve` also stopped the recorded children, and `oats instance
|
|
663
|
+
upgrade <instance> --undoo --plan` planned the forward upgrade.
|
|
664
|
+
- Each of them now refuses, with `E_BAD_ARGS` and before anything
|
|
665
|
+
happens (before a plan is read, a file is written, a session is stopped
|
|
666
|
+
or started, and before a `--server` command is sent to its host), a
|
|
667
|
+
flag it does not define, a value given with `=` to one of its switches
|
|
668
|
+
(`--undo=yes`), and an argument after the last one it takes. The message
|
|
669
|
+
names the flag and the command and prints the command's usage
|
|
670
|
+
(`oats instance stop: unknown flag --no-recursve`); under `--json` the
|
|
671
|
+
envelope carries `error.details.flag` or `error.details.argument`.
|
|
672
|
+
`oats retire` refuses the same way, with the same words as before.
|
|
673
|
+
- A script that passes one of these commands a flag it never defined gets
|
|
674
|
+
the refusal where the flag was ignored: remove the flag. Among them:
|
|
675
|
+
`--dir` on `oats session start` and `restart` (they take `--home`),
|
|
676
|
+
`--stop-grace` on `oats session start` (it is `restart`'s), and
|
|
677
|
+
`--server` on `oats trigger remove`, `enable` and `disable`, which have
|
|
678
|
+
no route and changed the trigger on this machine. The flags each command
|
|
679
|
+
defines are listed in
|
|
680
|
+
[The flags a command defines](../desktop-cli-api.md#command-flags).
|
|
681
|
+
- The refusals some of these commands made of one flag in their own words
|
|
682
|
+
(`--server` on `oats instance upgrade`; `--server`, `--dir` and `--home`
|
|
683
|
+
on `oats worktree`; `--home` and `--soul` on `oats launch-config set`
|
|
684
|
+
and `remove`; `--resume` on `oats session restart`) keep their words,
|
|
685
|
+
carry `error.details.flag`, and now also come before a `--server`
|
|
686
|
+
command is sent. `oats worktree remove` given `--branch`, `--base`,
|
|
687
|
+
`--repo` or `--preview` answers `unknown flag` with its usage.
|
|
688
|
+
- `oats retire --json <instance> ...`, with `--json` before the
|
|
689
|
+
instance, answers its refusal as one envelope.
|
|
690
|
+
- `oats retire --json` with no instance answers `E_USAGE` with the usage
|
|
691
|
+
line as one envelope, as a missing argument of other commands does; it
|
|
692
|
+
printed the usage on stderr and no envelope. Without `--json` it prints
|
|
693
|
+
the usage line, as before.
|
|
694
|
+
- A command of the table given `--server` and missing its argument (`oats
|
|
695
|
+
retire --server build` with no instance, `oats schedule remove --server
|
|
696
|
+
build` with no id) answers `E_USAGE` with its usage line on this
|
|
697
|
+
machine and sends nothing; it was sent to the host.
|
|
698
|
+
- `E_USAGE` is one of the codes `oats retire` and `oats instance stop`
|
|
699
|
+
answer only before any effect
|
|
700
|
+
([the table](../desktop-cli-api.md#before-effect-codes)): a client may
|
|
701
|
+
read it as "refused, nothing happened". The Desktop does: a stop or a
|
|
702
|
+
retire it applies that answers `E_USAGE` shows as refused, "Invalid
|
|
703
|
+
lifecycle request.", with the usage line in Details, where it showed an
|
|
704
|
+
unknown outcome with no description.
|
|
705
|
+
|
|
706
|
+
- **A cache write lock whose holder is gone no longer stops writes to the
|
|
707
|
+
cache when its pid belongs to another process.** The cross-process write
|
|
708
|
+
lock of a remote cache repo (`<cache>/.locks/<repo>.lock`) named its holder
|
|
709
|
+
by pid alone: when the holder died and its pid went to another process
|
|
710
|
+
(after a reboot pids start low again), every write to that cache waited
|
|
711
|
+
out the whole deadline and was refused with `E_REMOTE_UNREADABLE`
|
|
712
|
+
(`reason: "cache"`) until that process ended, which could take days. The
|
|
713
|
+
lock's record also names the boot it was taken in and its holder's start
|
|
714
|
+
time, as the kernel's other locks do, and a lock taken in another boot, or
|
|
715
|
+
whose pid runs with another start, is reclaimed at once. A holder that is
|
|
716
|
+
still running is never taken over. The refusal for a lock that is held
|
|
717
|
+
says to check whether the named pid is an oats process, and that once no
|
|
718
|
+
oats process holds it, the lock file it names is safe to remove
|
|
719
|
+
([Implementation](../implementation.md)).
|
|
720
|
+
|
|
721
|
+
- **`oats-getting-started` installs the Desktop again after the repository moved to `oats-project`.** After the transfer, `gh attestation verify <file> --repo awebai/oats` resolves to `oats-project/oats`. The attestations of releases up to 0.69.12 stayed with the `awebai` organisation, so the verify got `HTTP 404`, step 3 never printed `VERIFIED`, and no new onboarding installed the Desktop. Step 3 now downloads from `oats-project/oats` and verifies with `--repo oats-project/oats`. For versions up to 0.69.12 only, it falls back to `--owner awebai`. Each form accepts only its own repository's release workflow, run for the release's tag (`--signer-workflow`, `--source-ref`). The two forms are grouped, so a failed download or checksum still never prints `VERIFIED`. The checksum now also fails when `SHA256SUMS.txt` has no line for the file: on macOS, `sha256sum` passes empty or malformed input ([The Desktop](../desktop.md)).
|
|
722
|
+
|
|
723
|
+
- **The Desktop explains a refused sync's `E_PACKAGE_INTEGRITY` for what it
|
|
724
|
+
is** (oats-project/oats#1765). The sync sheet said every such refusal meant
|
|
725
|
+
a moved tag or a branch, including a lock whose capabilities or souls were
|
|
726
|
+
edited and a package whose manifest names another id. It now reads the
|
|
727
|
+
kernel's `why`: a branch pin says to pin a tag or a full commit; a
|
|
728
|
+
manifest naming another id says to change the pin as Details says; an
|
|
729
|
+
edited lock says to remove that package's entry from the lock file. A moved
|
|
730
|
+
tag, or a case this Desktop doesn't know, gets the general meaning: the
|
|
731
|
+
package doesn't match what the workspace file or the lock records for it.
|
|
732
|
+
The kernel's message stays under Details
|
|
733
|
+
([`oats sync`](../desktop-cli-api.md#oats-sync)).
|
|
734
|
+
|
|
735
|
+
- **On macOS, the boot id is read with the system's `sysctl`, whatever the
|
|
736
|
+
caller's `PATH`** (oats-project/oats#1821). It was read with the first `sysctl` on `PATH`, so under a
|
|
737
|
+
`PATH` without `/usr/sbin` (a scheduled job, a reduced environment) it read
|
|
738
|
+
none. The boot rule was then off without a word: the resume sweep's count
|
|
739
|
+
of starts per boot and its lock, and the cache write lock's holder check,
|
|
740
|
+
judged by process alone, and a lock taken before a reboot could be held by
|
|
741
|
+
a pid the new boot reused. The system directories the kernel runs its tools
|
|
742
|
+
from are `/usr/bin`, `/bin`, `/usr/sbin` and `/sbin`, in that order.
|
|
743
|
+
|
|
744
|
+
## Removed
|
|
745
|
+
|
|
746
|
+
- **The `mirrors/` copies of `oats.engineering` v1.18.0** (`oats-engineering-expert`, `oats-developer`, `oats-code-review`, `oats-maintainer`). The repository mirrors only the packages its workspace pins, as it already does for `oats.cloning`. The checks that read them now read the member copy, or check that the frozen catalog entry stays.
|
|
747
|
+
|
|
748
|
+
## Documentation
|
|
749
|
+
|
|
750
|
+
- **The official catalog page says how `from: package` finds its package**
|
|
751
|
+
(oats-project/oats#1759). It said a capability id selects its package
|
|
752
|
+
through the catalog's aliases. It resolves through the workspace's lock, to
|
|
753
|
+
the one locked package that lists the capability; two such packages are
|
|
754
|
+
refused with `E_PACKAGE_MISSING`. The catalog's `capabilities` map is read
|
|
755
|
+
only to pick a standalone deployment's package
|
|
756
|
+
([Official catalog](../official-catalog.md)).
|
|
757
|
+
|
|
758
|
+
- **A new README.** It says what OATS is and the way of thinking it asks for: kinds of agent, each with its own home, `AGENTS.md`, skills and knowledge. It covers the building blocks, how an instance's `AGENTS.md` is composed, capabilities, why souls are valuable, and what OATS gives people and organisations, ahead of the reference material.
|
|
759
|
+
- **[Knowledge and learning](../knowledge-and-learning.md)**, a new page: what agents keep and where, how souls divide the knowledge base, how learning flows by reviewed pull request, and the `oats.okf` default.
|
|
760
|
+
|
|
761
|
+
- **The catalog lists the research template.** [Coordination templates](../official-catalog.md#coordination-templates) adds `oats-project/oats-research-coordination` at `template-v2.0.0`, for work that ends in a finding or a report: a dispatcher, a research lead for each question that researches a single small angle itself or sends a researcher for each, and a verifier briefed to disprove, which checks the lead's own claims too. A report lands when the person who asked accepts it. The engineering template's row names its latest release, `template-v3.0.1`. The section now says there is one template for each way of working. The onboarding skills still name the engineering template directly.
|
|
762
|
+
|
|
763
|
+
- **The research template's row names `template-v2.0.0`.** [Coordination templates](../official-catalog.md#coordination-templates) lists `oats-project/oats-research-coordination` at its latest release, `template-v2.0.0`, in which the research lead researches a single small angle itself. A copy of a template-v1.x release moves by the template's `CHANGELOG.md`, which starts with renaming `/send-a-probe` to `/send-a-helper`.
|
|
764
|
+
|
|
765
|
+
- **The catalog lists the scientific research template.** [Coordination templates](../official-catalog.md#coordination-templates) adds `oats-project/oats-scientific-research-coordination` at `template-v2.0.0`, for studies that end in claims a person is accountable for: a dispatcher, a study lead for each study, an analyst for each arm of a locked protocol, fresh study reviewers for the methods, an independent check, leakage and citations, and a record steward that locks protocols and keeps the study records. A claim lands when the scientist accepts it; one that leaves the group needs a check that isn't LLM judgement. The onboarding skills still name the engineering template directly.
|
|
766
|
+
|
|
767
|
+
- **The scientific research template's row names `template-v2.0.0`.** [Coordination templates](../official-catalog.md#coordination-templates) lists `oats-project/oats-scientific-research-coordination` at its latest release, `template-v2.0.0`, in which the study lead's children are helpers with closed briefs, every study reviewer's verdict says what it checked, and an analyst still runs every arm. A copy of a template-v1.x release moves by the template's `CHANGELOG.md`, which starts with renaming `/send-a-probe` to `/send-a-helper`.
|