@awebai/oats 0.48.0 → 0.50.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +326 -28
- package/docs/capabilities.md +425 -8
- package/docs/capability-manifest.schema.json +60 -5
- package/docs/configuration.md +103 -0
- package/docs/desktop-cli-api.md +542 -47
- package/docs/desktop.md +85 -5
- package/docs/execution-targets.md +50 -9
- package/docs/implementation.md +74 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +289 -53
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +450 -60
- package/docs/workspaces.md +3 -3
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +18 -2
- package/lib/core.mjs +1374 -394
- package/lib/instance-events.mjs +9 -10
- package/lib/instance-git.mjs +19 -10
- package/lib/instance-inspect.mjs +58 -18
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/refused-text.mjs +17 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +9 -2
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +705 -108
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
package/docs/knowledge.md
CHANGED
|
@@ -2,65 +2,63 @@
|
|
|
2
2
|
|
|
3
3
|
The **knowledge slot** gives a working soul durable, reviewed expertise:
|
|
4
4
|
decisions and their rationale, rejected alternatives, discovered limits. The
|
|
5
|
-
kernel owns
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
kernel owns slot selection, composition and command dispatch; the capability
|
|
6
|
+
owns its knowledge format, instructions and promotion procedure. The model is
|
|
7
|
+
in [Knowledge, instances and evolving expertise](knowledge-theory.md).
|
|
8
8
|
|
|
9
|
-
This
|
|
10
|
-
|
|
11
|
-
[oats-okf README](https://github.com/awebai/oats-okf).
|
|
9
|
+
This is the operator guide for **oats.okf 5.0**. Provider implementation and
|
|
10
|
+
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
12
11
|
|
|
13
12
|
| Surface | What it holds |
|
|
14
13
|
|---|---|
|
|
15
|
-
| Accepted
|
|
16
|
-
| `souls/<name>/okf.json` | The
|
|
17
|
-
| Instance home: `STATE.md`, `log.md`, `notes/` |
|
|
18
|
-
|
|
|
14
|
+
| Accepted Git or directory bases | Soul knowledge: OKF concepts in owned nodes. |
|
|
15
|
+
| `souls/<name>/okf.json` | The soul's stable owner and owned/read nodes. |
|
|
16
|
+
| Instance home: `STATE.md`, `log.md`, `notes/` | The instance's working knowledge. |
|
|
17
|
+
| Bindings file and `stateDir` | Host base locations and consultation/binding state, not a harvest queue. |
|
|
19
18
|
|
|
20
19
|
## Setup
|
|
21
20
|
|
|
22
21
|
### Pin and select the package
|
|
23
22
|
|
|
24
|
-
The workspace pins the package and fills the slot for every soul by default:
|
|
25
|
-
|
|
26
23
|
```yaml
|
|
27
24
|
# oats-workspace.yaml (excerpt)
|
|
28
25
|
packages:
|
|
29
|
-
oats.okf:
|
|
26
|
+
oats.okf: v5.0.0
|
|
30
27
|
defaults:
|
|
31
28
|
knowledge: { oats.okf: { from: package } }
|
|
32
29
|
stores:
|
|
33
30
|
org: git:github.com/acme/knowledge
|
|
34
31
|
```
|
|
35
32
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
- `stores:` names the workspace's knowledge repositories; the kernel validates
|
|
40
|
-
them as repo refs. oats.okf does not read `stores:`: the bindings file says
|
|
41
|
-
where each base lives.
|
|
33
|
+
`oats sync` locks the package. `oats spawn <soul> --preview --json` shows the
|
|
34
|
+
resolved module and merged settings. Membership in the package's repository
|
|
35
|
+
does not supply the package capability: the workspace pin does.
|
|
42
36
|
|
|
43
|
-
|
|
37
|
+
A soul without knowledge says `knowledge: none`. `stores:` names workspace
|
|
38
|
+
repositories; oats.okf reads its **bindings file**, not that block, to locate
|
|
39
|
+
bases. Each deployment supplies host paths, for example:
|
|
44
40
|
|
|
45
41
|
```yaml
|
|
46
|
-
# oats-local.yaml (excerpt)
|
|
42
|
+
# oats-local.yaml (excerpt; replace the example paths)
|
|
47
43
|
settings:
|
|
48
44
|
oats.okf:
|
|
49
|
-
bindings-file: /
|
|
50
|
-
state-dir: /
|
|
45
|
+
bindings-file: /absolute/okf/bindings.json
|
|
46
|
+
state-dir: /absolute/okf/state
|
|
51
47
|
```
|
|
52
48
|
|
|
49
|
+
Upgrading an existing deployment requires the ordered
|
|
50
|
+
[5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
|
|
51
|
+
just editing a version line.
|
|
52
|
+
|
|
53
53
|
### Bindings document
|
|
54
54
|
|
|
55
|
-
Capability-owned JSON at an absolute path; relative paths inside
|
|
56
|
-
from
|
|
55
|
+
Capability-owned JSON at an absolute path; relative paths inside resolve
|
|
56
|
+
from the document's directory:
|
|
57
57
|
|
|
58
58
|
```json
|
|
59
59
|
{
|
|
60
60
|
"version": 1,
|
|
61
|
-
"stateDir": "
|
|
62
|
-
"cron": "*/15 * * * *",
|
|
63
|
-
"tz": "UTC",
|
|
61
|
+
"stateDir": "./state",
|
|
64
62
|
"bases": {
|
|
65
63
|
"project": {
|
|
66
64
|
"id": "project-knowledge",
|
|
@@ -75,236 +73,208 @@ from its own directory:
|
|
|
75
73
|
}
|
|
76
74
|
```
|
|
77
75
|
|
|
78
|
-
-
|
|
79
|
-
`okf.json
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
-
|
|
89
|
-
|
|
90
|
-
-
|
|
91
|
-
|
|
76
|
+
- The alias (`project`) is local to the bindings and is named by souls'
|
|
77
|
+
`okf.json`. Its `id` must match `okf-base.json` at the base root or reading
|
|
78
|
+
that base fails with `E_BASE`.
|
|
79
|
+
- Git bases may use HTTPS, SSH or a durable local repository; `root: "."`
|
|
80
|
+
means the whole repository. Embedded credentials are refused. Harvest
|
|
81
|
+
proposals use same-repository GitHub PRs through ordinary `git` and `gh`.
|
|
82
|
+
- Directory bases need no Git and must not sit inside a Git worktree. They
|
|
83
|
+
support consultation and explicit provisioning/migration, **not automatic
|
|
84
|
+
harvest publication**. The 5.0 harvester reports directory harvest as
|
|
85
|
+
unsupported and names the Git/PR remedy.
|
|
86
|
+
- Paths are physical and nonoverlapping: state is outside every base and
|
|
87
|
+
instance home; the bindings document is outside state and bases.
|
|
88
|
+
- `cron` and `tz` are removed: the provider no longer schedules harvest.
|
|
89
|
+
- A bad configured base blocks a knowledge-slot spawn; the error names the
|
|
90
|
+
alias. Spawning never bootstraps an empty accepted base as a fallback.
|
|
92
91
|
|
|
93
92
|
### Settings
|
|
94
93
|
|
|
95
|
-
|
|
94
|
+
The knowledge capability declares four host settings:
|
|
96
95
|
|
|
97
96
|
| Setting | Default | Meaning |
|
|
98
97
|
|---|---|---|
|
|
99
|
-
| `bindings-file` |
|
|
100
|
-
| `state-dir` |
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
`harvest-runtime` or the harvest opt-out.
|
|
98
|
+
| `bindings-file` | required | Absolute path to the bindings document. |
|
|
99
|
+
| `state-dir` | required by portable binding preparation | Absolute host-owned state location, never derived from an instance home. |
|
|
100
|
+
| `git-timeout` | `600` | Seconds allowed for a remote Git operation. |
|
|
101
|
+
| `consult-max-age` | `300` | Maximum cached accepted-commit age before refetch; `0` always refetches. |
|
|
102
|
+
|
|
103
|
+
Host `harvest`, `harvest-runtime` and `harvest-model` are removed, including
|
|
104
|
+
explicit `harvest: off`. A 4.x **recorded manifest default** is ignored by
|
|
105
|
+
5.0 readers as nobody's decision, not reinterpreted as an opt-out. Explicit
|
|
106
|
+
removed keys still refuse and name the fix. The harvester has no provider
|
|
107
|
+
runtime/model switch or PR-wait deadline; it uses ordinary kernel/harness
|
|
108
|
+
selection and retires after its handoff.
|
|
111
109
|
|
|
112
110
|
## The soul's okf.json
|
|
113
111
|
|
|
114
|
-
|
|
112
|
+
Every working soul using oats.okf has `okf.json` beside `soul.yaml`:
|
|
115
113
|
|
|
116
114
|
```json
|
|
117
115
|
{ "version": 1, "owner": "domain-expert", "owns": ["project/expert"], "reads": ["project/steward", "team/operations"] }
|
|
118
116
|
```
|
|
119
117
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
- A missing `okf.json`, base metadata or index fails the spawn; nothing is
|
|
126
|
-
bootstrapped empty. A legacy `soul/knowledge/` fails it with a migration
|
|
127
|
-
diagnostic.
|
|
118
|
+
`owner` is the stable owner ID named by the base metadata. `owns` lists
|
|
119
|
+
`alias/node` proposal destinations; `reads` is the starting consultation
|
|
120
|
+
context. Neither is an access-control list: every configured base is
|
|
121
|
+
readable. Missing declarations, base metadata or indexes refuse spawn;
|
|
122
|
+
legacy soul-local knowledge needs explicit migration, never silent copying.
|
|
128
123
|
|
|
129
|
-
`oats okf init`
|
|
130
|
-
|
|
131
|
-
|
|
124
|
+
`oats okf init` provisions a new directory base with `--confirm`, or stages a
|
|
125
|
+
Git base with `--output` for reviewed delivery. Existing knowledge is never
|
|
126
|
+
overwritten by initialization.
|
|
132
127
|
|
|
133
128
|
## The harvest switch
|
|
134
129
|
|
|
135
|
-
|
|
130
|
+
**There is no host harvest switch in 5.0.** The sole remaining choice is the
|
|
131
|
+
soul's opt-out:
|
|
136
132
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
| `soul.yaml` | `knowledge: { harvest: off }` | This soul is never harvested. The opt-out is absolute. |
|
|
141
|
-
|
|
142
|
-
- A soul can only opt out. A soul's `harvest: on` is ignored with a warning,
|
|
143
|
-
and keeps that soul off until the line is removed. An unreadable opt-out
|
|
144
|
-
counts as off.
|
|
145
|
-
- **Off means no capture at all:** no source, custody or schedule, and no
|
|
146
|
-
final capture at retire. A manual `oats okf harvest` answers
|
|
147
|
-
`E_HARVEST_OFF`. Consultation works either way.
|
|
148
|
-
- On applies to new spawns. Off (host or soul) stops capture at a source's
|
|
149
|
-
next scheduled run; evidence already in custody stays.
|
|
150
|
-
- `oats okf setup --harvest on|off` writes the host setting;
|
|
151
|
-
`oats okf harvest-status` reports the effective value, the row that decided
|
|
152
|
-
it and the registered sources.
|
|
133
|
+
```yaml
|
|
134
|
+
knowledge: { harvest: off }
|
|
135
|
+
```
|
|
153
136
|
|
|
154
|
-
|
|
137
|
+
That soul keeps consultation and working-memory guidance, receives no
|
|
138
|
+
checkpoint-harvest directive, and its material is refused by the
|
|
139
|
+
harvester's required spawn hook. Absence gives the normal proposal flow.
|
|
140
|
+
A soul's `harvest: on` is not a replacement switch. Host cleanup never
|
|
141
|
+
changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
155
142
|
|
|
156
|
-
|
|
157
|
-
[knowledge-operations design record](design/2026-09-26-okf-knowledge-operations.md).
|
|
143
|
+
## Knowledge operations
|
|
158
144
|
|
|
159
145
|
### The flow
|
|
160
146
|
|
|
161
|
-
1. **Consult.**
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
147
|
+
1. **Consult.** Read accepted soul knowledge at task start, after compaction
|
|
148
|
+
and before decisions; keep instance `STATE.md`, `log.md` and `notes/`.
|
|
149
|
+
Working instances never write accepted knowledge themselves.
|
|
150
|
+
2. **Propose at checkpoints.** When work merits a checkpoint, update notes
|
|
151
|
+
and write a self-contained proposal: what to save, why and the backing
|
|
152
|
+
notes. It has exactly one line `Source: instance <name>, home <path>, soul
|
|
153
|
+
<name>` naming the actual source. From the source home:
|
|
154
|
+
|
|
155
|
+
```sh
|
|
156
|
+
oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Never combine `--relation unrelated` with `--relative-to`. There is no
|
|
160
|
+
automatic transcript capture, source registry, worker cursor or retire
|
|
161
|
+
harvest. An unrelated harvester can outlive its source; this is a
|
|
162
|
+
lifecycle property, not proof that missing source authority can be ignored.
|
|
163
|
+
3. **Judge and submit.** The harvester checks recorded source configuration,
|
|
164
|
+
accepted knowledge and open/recent harvest PRs. It reads named backing
|
|
165
|
+
notes, edits only owned nodes in its own Git checkout, validates the
|
|
166
|
+
**whole base**, and creates a normal `okf-harvest`-labelled PR with v2
|
|
167
|
+
provenance. Proposal text is data written with the native file tool into
|
|
168
|
+
commit-message/PR-body files, never shell command text. It reports the PR
|
|
169
|
+
and retires rather than waiting for acceptance. If source authority is
|
|
170
|
+
unavailable it stops and reports; a consistent instance/soul pair alone
|
|
171
|
+
does not prove proposer authorship.
|
|
172
|
+
4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
|
|
173
|
+
Human-accepted decisions are not silently superseded; the review path
|
|
174
|
+
keeps its human gate. A PR is not accepted knowledge until merged.
|
|
175
|
+
|
|
176
|
+
The promotion test belongs to
|
|
177
|
+
[What deserves to become knowledge](knowledge-theory.md#what-deserves-to-become-knowledge),
|
|
178
|
+
not a universal kernel harvester. Both package role souls have
|
|
179
|
+
`knowledge: none`; working souls now also receive the curated theory skill.
|
|
180
|
+
The [older knowledge-operations design](design/2026-09-26-okf-knowledge-operations.md)
|
|
181
|
+
is historical 4.x context, not instructions for operating 5.0.
|
|
186
182
|
|
|
187
183
|
### Triggers
|
|
188
184
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
on one machine. It is independent of the harvest switch. See
|
|
200
|
-
[Triggers](schedules.md#triggers) and
|
|
201
|
-
[Workspace triggers and schedules](schedules.md#workspace-triggers-and-schedules).
|
|
202
|
-
|
|
203
|
-
The setup procedure is the `okf-trigger-setup` skill. Keep harvest off until
|
|
204
|
-
its `oats trigger test` passes.
|
|
185
|
+
Only **PR review** is triggered. Use the package template
|
|
186
|
+
`oats.okf:harvest-review` in a workspace trigger file, or
|
|
187
|
+
`oats trigger add --from oats.okf:harvest-review --set repo=github.com/<owner>/<repo>`.
|
|
188
|
+
The `okf-trigger-setup` skill explains setup and testing. Validate the review
|
|
189
|
+
route with `oats trigger test` before relying on automated review.
|
|
190
|
+
|
|
191
|
+
There are no per-source harvest jobs or host-timer installation steps in
|
|
192
|
+
this provider. See [Knowledge harvest and review](schedules.md#knowledge-harvest-and-review),
|
|
193
|
+
[Triggers](schedules.md#triggers) and
|
|
194
|
+
[Workspace triggers and schedules](schedules.md#workspace-triggers-and-schedules).
|
|
205
195
|
|
|
206
196
|
### Who gets which okf skills
|
|
207
197
|
|
|
208
|
-
| Capability | Composed into | Skills |
|
|
209
|
-
|
|
210
|
-
| `oats.okf` |
|
|
211
|
-
| `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` |
|
|
212
|
-
| `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../mirrors/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../mirrors/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) |
|
|
198
|
+
| Capability | Composed into | Skills |
|
|
199
|
+
|---|---|---|
|
|
200
|
+
| `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), `knowledge-theory` |
|
|
201
|
+
| `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` |
|
|
202
|
+
| `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../mirrors/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../mirrors/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) |
|
|
213
203
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
204
|
+
Only the working soul's eligible **spawn brief** gives the proposal-spawn
|
|
205
|
+
command. Shared consultation injects/skills also reach opted-out souls and
|
|
206
|
+
do not unconditionally direct a harvest.
|
|
217
207
|
|
|
218
208
|
## Inspection and operator commands
|
|
219
209
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
the command to that instance home), a capability command runs as the soul
|
|
225
|
-
`--soul <name>` names, or without it as the first soul that provides the
|
|
226
|
-
namespace ([capabilities.md](capabilities.md), `command`). Inside an instance home, a
|
|
227
|
-
`--soul` naming another soul is refused (`E_HOME_MISMATCH`). The kernel resolves the
|
|
228
|
-
soul as a spawn would, fetches its module at the locked commit into
|
|
229
|
-
`<deployment>/.oats/modules/` and runs it with the soul's merged settings
|
|
230
|
-
and `OATS_SOUL`, the soul's source at that commit, with the soul's
|
|
231
|
-
`OATS_AGENT` and `OATS_SOUL_ID` as its hooks get them.
|
|
232
|
-
An unlocked package is `E_PACKAGE_MISSING` until `oats sync`.
|
|
210
|
+
From an instance home, `oats okf …` runs its copied module and recorded
|
|
211
|
+
settings. Pinning a new package does not replace those modules, hooks,
|
|
212
|
+
skills or briefings; even the old home's readiness/binding checks keep its
|
|
213
|
+
old code. Respawn homes that should adopt the new proposal flow.
|
|
233
214
|
|
|
234
|
-
|
|
215
|
+
From the deployment directory (holding `oats-local.yaml`), with neither
|
|
216
|
+
`OATS_INSTANCE_HOME` nor `OATS_HOME` set, pass `--soul <name>` or use the
|
|
217
|
+
first soul providing that namespace. The kernel resolves and runs its
|
|
218
|
+
locked module with the selected soul's merged payload. An in-home command
|
|
219
|
+
cannot select a different soul (`E_HOME_MISMATCH`). An unlocked package is
|
|
220
|
+
`E_PACKAGE_MISSING` until sync. See [capability dispatch](capabilities.md).
|
|
235
221
|
|
|
236
|
-
Consult
|
|
237
|
-
and `--fresh` (refetch the accepted branch now):
|
|
222
|
+
### Consult
|
|
238
223
|
|
|
239
|
-
```
|
|
240
|
-
oats okf bases
|
|
241
|
-
oats okf index [--base ALIAS] [NODE]
|
|
224
|
+
```sh
|
|
225
|
+
oats okf bases
|
|
226
|
+
oats okf index [--base ALIAS] [NODE]
|
|
242
227
|
oats okf cat --base project /expert/decisions/retry-policy.md [--from PATH]
|
|
243
228
|
oats okf ls --base project /expert/lessons
|
|
244
229
|
oats okf links --base project /expert/decisions/retry-policy.md
|
|
245
230
|
oats okf search backoff [--base ALIAS | --all] [--node NODE] [--regex] [--case-sensitive]
|
|
246
231
|
```
|
|
247
232
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
- `okf-consultation` teaches navigation, search and citation.
|
|
233
|
+
Commands accept `--json` and `--fresh`. Run from the home, or select a live
|
|
234
|
+
home with `--home PATH` from an operator scope and the appropriate `--soul`.
|
|
235
|
+
There is no `--source` descriptor path, including after retirement. Paths
|
|
236
|
+
are rooted in the base, never outside it. A failed fetch may serve cached
|
|
237
|
+
accepted bytes marked stale. `read` and `refresh` remain removed: use `cat`
|
|
238
|
+
and `index`. The consultation skill teaches navigation and citation.
|
|
255
239
|
|
|
256
240
|
### Inspect
|
|
257
241
|
|
|
258
|
-
```
|
|
242
|
+
```sh
|
|
243
|
+
oats okf inspect --json
|
|
259
244
|
oats okf inspect --home /absolute/instance-home --soul domain-expert --json
|
|
260
|
-
oats
|
|
261
|
-
oats okf harvest-status --soul domain-expert --json
|
|
245
|
+
oats operation run knowledge:inspect --home /absolute/instance-home --json
|
|
262
246
|
```
|
|
263
247
|
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
declaration, bases and working memory. `oats operation run knowledge:inspect
|
|
270
|
-
--home PATH --json` is the same view through the generic operation interface.
|
|
248
|
+
The view contains the declaration, configured bases and that home's working
|
|
249
|
+
`STATE.md`, `log.md` and Markdown notes. Each document has a 256 KiB preview
|
|
250
|
+
cap (`truncated: true` beyond it), preserving UTF-8 boundaries. It invents
|
|
251
|
+
no capture/processing/acceptance receipts and has no retired-source view.
|
|
252
|
+
`oats okf bases` reports accepted-state freshness and validity separately.
|
|
271
253
|
|
|
272
254
|
### Operator-level commands
|
|
273
255
|
|
|
274
|
-
|
|
256
|
+
From the deployment, with `--soul <name>`:
|
|
275
257
|
|
|
276
258
|
| Command | Purpose |
|
|
277
259
|
|---|---|
|
|
278
|
-
| `setup --
|
|
279
|
-
| `setup --source FILE [--enable \| --disable] [--install-host]` | Verify, toggle or host-install a source's job. |
|
|
280
|
-
| `run-source --source FILE [--manual] [--no-launch]` | Run a source's job by hand; `--no-launch` stops at a scaffold. |
|
|
260
|
+
| `setup --remove-legacy-settings [--plan] [--json]` | Delete only explicit legacy host harvest keys; guard-exempt, plan read-only. |
|
|
281
261
|
| `init --base ALIAS --nodes FILE (--confirm \| --output PATH)` | Provision a directory base or stage a Git proposal. |
|
|
282
|
-
| `migrate …` |
|
|
283
|
-
| `unlock --lock PATH --token TOKEN` | Release
|
|
284
|
-
|
|
285
|
-
From an instance home, `oats okf harvest [--no-launch]` captures now and
|
|
286
|
-
requests a harvester.
|
|
262
|
+
| `migrate …` | Explicitly migrate legacy soul-local knowledge into a base. |
|
|
263
|
+
| `unlock --lock PATH --token TOKEN` | Release the specified dead local process's directory-base lock. |
|
|
287
264
|
|
|
288
265
|
### Completion and recovery
|
|
289
266
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
`retry` never discards an uncertain delivery; `--rejudge` keeps old proposals
|
|
299
|
-
and refreshes only unresolved destinations. After a PR merges, `complete` for
|
|
300
|
-
the run without `--judgment` records acceptance. Never remove a pending
|
|
301
|
-
directory journal to force progress. Exact recovery, adoption and migration
|
|
302
|
-
procedures are in the
|
|
303
|
-
[oats-okf README](https://github.com/awebai/oats-okf#independent-worker-and-completion).
|
|
267
|
+
`harvest`, `run-source`, `complete`, `retry`, `harvest-status`, old source
|
|
268
|
+
selectors and harvest setup switches return actionable removal errors.
|
|
269
|
+
There is no replacement completion/settlement engine. Existing 4.x private
|
|
270
|
+
inputs and open PR obligations must be resolved explicitly under the old
|
|
271
|
+
provider before the pin; they are not deleted or re-imported by 5.0. Follow
|
|
272
|
+
the [ordered cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), including the host cleanup
|
|
273
|
+
**after** 5.0 sync and **before** new spawns.
|
|
304
274
|
|
|
305
275
|
## Without a knowledge capability
|
|
306
276
|
|
|
307
277
|
`knowledge: none`, on a soul or as the workspace default, is valid: no OKF
|
|
308
|
-
state, instructions or
|
|
309
|
-
|
|
278
|
+
state, instructions or source. Another capability may fill the slot with
|
|
279
|
+
its own model ([authoring guide](knowledge-capability-authoring.md)).
|
|
310
280
|
Switching slots migrates and erases nothing.
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.
|
|
13
|
-
| `oats.okf` | `
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.9.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.0.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.24.0` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.9.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
17
|
| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
|
|
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
|
|
|
29
29
|
## Find and use packages
|
|
30
30
|
|
|
31
31
|
- A workspace pins an official package by **bare version** in its
|
|
32
|
-
`packages:` map (`oats.okf:
|
|
32
|
+
`packages:` map (`oats.okf: v5.0.0`); `oats sync` resolves it through the
|
|
33
33
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
34
34
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
35
35
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -44,14 +44,14 @@ whole organisation:
|
|
|
44
44
|
|
|
45
45
|
```yaml
|
|
46
46
|
packages:
|
|
47
|
-
oats.okf:
|
|
47
|
+
oats.okf: v5.0.0 # bare version → the official catalog
|
|
48
48
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
- **Bare version** (`
|
|
51
|
+
- **Bare version** (`v5.0.0`, `5.0.0`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`
|
|
54
|
+
convention (`v5.0.0` or `oats-framework/v1.9.0`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,9 +74,9 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.
|
|
78
|
-
oats.okf:
|
|
79
|
-
oats.aweb: v1.
|
|
77
|
+
oats.framework: v1.9.0
|
|
78
|
+
oats.okf: v5.0.0
|
|
79
|
+
oats.aweb: v1.24.0
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -105,7 +105,7 @@ decision recorded in the lock.
|
|
|
105
105
|
$ oats sync
|
|
106
106
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
107
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.0 ✓ (@ 12db7749)
|
|
109
109
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
110
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
111
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
134
|
## `oats package add | remove`
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.
|
|
137
|
+
oats package add oats.aweb v1.24.0 # a catalog version
|
|
138
138
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
139
|
oats package remove acme.tools
|
|
140
140
|
```
|
|
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
|
|
|
160
160
|
"source": "catalog:oats.okf",
|
|
161
161
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
162
|
"path": "oats-package",
|
|
163
|
-
"version": "
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.0.0",
|
|
164
|
+
"commit": "12db77492d92154099e7f1aad60a98b1d47f6631",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
167
167
|
},
|
|
@@ -290,6 +290,20 @@ overrides it; a workspace trigger made `from:` it shows its file header's
|
|
|
290
290
|
description, else the template's. A kernel before 0.43.0 refuses the key, so
|
|
291
291
|
a package whose template sets it needs `compatibility.oats: ">=0.43.0"`.
|
|
292
292
|
|
|
293
|
+
A template may name a capability's trigger source (feature
|
|
294
|
+
`trigger-sources`): its
|
|
295
|
+
`definition.on` is `{ source: "<capability>:<source>", params?, events,
|
|
296
|
+
poll? }`, and a parameter's `path` may point into `on.params` (for example
|
|
297
|
+
`on.params.prefix`). `add --from` checks what it means against the soul it
|
|
298
|
+
spawns, as for any capability-source trigger
|
|
299
|
+
([schedules.md](schedules.md#capability-sources)). A package does **not**
|
|
300
|
+
raise `compatibility.oats` for such a template: a template is read only by
|
|
301
|
+
`add --from`, so a kernel without feature `trigger-sources` refuses that one
|
|
302
|
+
`add --from` (`E_TRIGGER_INVALID` on `on.source`, or on `on.params` when the
|
|
303
|
+
template sets it), reports a workspace trigger made from it as a problem of
|
|
304
|
+
its snapshot, and uses the package's capabilities and souls as before. A
|
|
305
|
+
floor would refuse them all on every older host.
|
|
306
|
+
|
|
293
307
|
## Compatibility floors
|
|
294
308
|
|
|
295
309
|
A soul may state floors on package versions — constraints, not sources:
|
|
@@ -338,12 +352,12 @@ A soul that names one of the package's capabilities with
|
|
|
338
352
|
{
|
|
339
353
|
"policy": "docs/official-catalog.md",
|
|
340
354
|
"packages": {
|
|
341
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "
|
|
342
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.0", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.0", "path": "oats-package" }
|
|
343
357
|
}
|
|
344
358
|
}
|
|
345
359
|
```
|
|
346
360
|
|
|
347
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
348
|
-
resolves to tag `oats-framework/v1.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.9.0`
|
|
362
|
+
resolves to tag `oats-framework/v1.9.0`. Resolving through the catalog never
|
|
349
363
|
advances a lock by itself: `oats sync` does, and says so.
|