@awebai/oats 0.69.15 → 0.69.16
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 +1 -1
- package/docs/capabilities.md +3 -2
- package/docs/container.md +93 -44
- package/docs/desktop.md +3 -3
- package/docs/implementation.md +1 -1
- package/docs/integrations.md +9 -8
- package/docs/knowledge-and-learning.md +2 -2
- package/docs/knowledge-theory.md +17 -15
- package/docs/knowledge.md +202 -179
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.16.md +169 -0
- package/docs/schedules.md +35 -32
- package/docs/servers.md +4 -1
- package/docs/souls-and-instances.md +13 -12
- package/docs/upgrading.md +14 -6
- package/docs/workspaces.md +2 -2
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +8 -5
package/docs/knowledge.md
CHANGED
|
@@ -6,17 +6,20 @@ kernel owns slot selection, composition and command dispatch; the capability
|
|
|
6
6
|
owns its knowledge format, instructions and promotion procedure. The model is
|
|
7
7
|
in [Knowledge, instances and evolving expertise](knowledge-theory.md).
|
|
8
8
|
|
|
9
|
-
This is the operator guide for **oats.okf
|
|
9
|
+
This is the operator guide for **oats.okf 6.0.1** (OATS **>=0.69.2**). Provider implementation and
|
|
10
10
|
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
11
|
+
In 6.0 there is no knowledge harvester: a working instance proposes its own
|
|
12
|
+
knowledge as a pull request at its checkpoints (`oats okf propose`), and the
|
|
13
|
+
knowledge maintainer gates every merge.
|
|
11
14
|
|
|
12
15
|
| Surface | What it holds |
|
|
13
16
|
|---|---|
|
|
14
17
|
| 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. |
|
|
18
|
+
| `souls/<name>/okf.json` | The soul's stable owner and owned/read nodes (version 1), or the subjects it reads by default (version 2). |
|
|
16
19
|
| Instance home: `STATE.md`, `log.md`, `notes/` | The instance's working knowledge. |
|
|
17
|
-
| Instance home: `okf-harvest-policy.json` | Provider-written duty at spawn, exposed by `oats okf status`; not publication authority. |
|
|
18
|
-
|
|
|
19
|
-
| Bindings file and `stateDir` | Host base locations and consultation/binding state, not a
|
|
20
|
+
| Instance home: `okf-harvest-policy.json` | Provider-written duty to propose, recorded at spawn (the file keeps its 5.x name), exposed by `oats okf status`; not publication authority. |
|
|
21
|
+
| Instance home: `proposals/<date>-<slug>/` | One proposal: clones of the owned bases, `proposal.md`, and once applied its publication record. Not accepted knowledge. |
|
|
22
|
+
| Bindings file and `stateDir` | Host base locations and consultation/binding state, not a proposal queue. |
|
|
20
23
|
|
|
21
24
|
## Setup
|
|
22
25
|
|
|
@@ -25,7 +28,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
25
28
|
```yaml
|
|
26
29
|
# oats-workspace.yaml (excerpt)
|
|
27
30
|
packages:
|
|
28
|
-
oats.okf:
|
|
31
|
+
oats.okf: v6.0.1
|
|
29
32
|
defaults:
|
|
30
33
|
knowledge: { oats.okf: { from: package } }
|
|
31
34
|
stores:
|
|
@@ -50,34 +53,42 @@ settings:
|
|
|
50
53
|
|
|
51
54
|
Upgrading from 4.x requires the ordered
|
|
52
55
|
[5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
|
|
53
|
-
just editing a version line.
|
|
54
|
-
`knowledge-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
56
|
+
just editing a version line. The package requires OATS >=0.69.2: its
|
|
57
|
+
`knowledge-maintainer` soul says `background: true`, which an older kernel
|
|
58
|
+
refuses. Upgrade OATS first, then the package. Each 5.x step is in
|
|
59
|
+
[oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.0.1/CHANGELOG.md).
|
|
60
|
+
|
|
61
|
+
**Upgrade to 6.0:** pin `oats.okf: v6.0.1` and run `oats sync`. Only new
|
|
62
|
+
spawns get `oats okf propose`, the 6.0 `okf-propose` skill and the
|
|
63
|
+
spawn-recorded duty. Existing homes keep their copied provider even after a
|
|
64
|
+
session restart; a stopped 5.x home can move with `oats instance upgrade`
|
|
65
|
+
(OATS 0.68.0 and later), and a home spawned under 4.x is refused with the
|
|
66
|
+
remedy to retire and respawn it. Harvester spawns stop: the stub soul
|
|
67
|
+
`oats.okf/knowledge-harvester`, kept until 7.0, refuses every spawn with
|
|
68
|
+
`E_REMOVED` and the fix. Harvesters already running keep their 5.x modules
|
|
69
|
+
and finish, or a person retires them. Then, by hand, from the deployment
|
|
70
|
+
(oats.okf's [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.0.1/README.md#upgrading-to-60)
|
|
71
|
+
has each step's commands):
|
|
72
|
+
|
|
73
|
+
1. Delete the harvester's launch preference, if any:
|
|
74
|
+
`oats soul launch remove oats.okf/knowledge-harvester --plan`, then
|
|
75
|
+
without `--plan`.
|
|
76
|
+
2. Delete every `--provider oats.okf harvest=…` spawn flag from the scripts
|
|
77
|
+
and briefs that spawn instances; remove a leftover host `harvest` key with
|
|
78
|
+
`oats okf setup --remove-legacy-settings --soul <soul>` (`--plan` first).
|
|
79
|
+
3. Add the `proposal-review` trigger beside `harvest-review`, and remove the
|
|
80
|
+
old one once no 5.x harvester can open an `okf-harvest` PR
|
|
81
|
+
([Triggers](#triggers)).
|
|
82
|
+
4. Protect every Git base's accepted branch (pull requests only, merged by
|
|
83
|
+
the knowledge maintainer's account), and give each proposing host
|
|
84
|
+
branch-create access on the knowledge repository; optionally set
|
|
85
|
+
`screen-terms-file` ([Settings](#settings)).
|
|
86
|
+
5. Retire the harvesters `oats status` still lists, once they have handed
|
|
87
|
+
over; propose a retained one's claims with the operator form of
|
|
88
|
+
`oats okf propose` ([the flow](#the-flow)).
|
|
89
|
+
|
|
90
|
+
Bindings, `okf.json` and `okf-base.json` need no change, and open
|
|
91
|
+
`okf-harvest` PRs stay reviewable.
|
|
81
92
|
|
|
82
93
|
### Bindings document
|
|
83
94
|
|
|
@@ -106,24 +117,29 @@ from the document's directory:
|
|
|
106
117
|
`okf.json`. Its `id` must match `okf-base.json` at the base root or reading
|
|
107
118
|
that base fails with `E_BASE`.
|
|
108
119
|
- Git bases may use HTTPS, SSH or a durable local repository; `root: "."`
|
|
109
|
-
means the whole repository. Embedded credentials are refused.
|
|
110
|
-
|
|
120
|
+
means the whole repository. Embedded credentials are refused. Proposals
|
|
121
|
+
are same-repository GitHub PRs from a new, create-only branch, through
|
|
122
|
+
ordinary `git` and `gh`; there is no fork flow.
|
|
111
123
|
Change a binding's `repository` to a plain URL only after every seat that
|
|
112
124
|
reads it has been re-spawned on oats.okf 5.0.4 or later; a session restart
|
|
113
125
|
does not update the copied provider.
|
|
114
126
|
- Directory bases need no Git and must not sit inside a Git worktree. They
|
|
115
|
-
support consultation and explicit provisioning/migration, **not
|
|
116
|
-
|
|
117
|
-
|
|
127
|
+
support consultation and explicit provisioning/migration, **not
|
|
128
|
+
proposals**: `oats okf propose` skips a directory base and names the remedy
|
|
129
|
+
(convert it to a Git base, or edit it in a reviewed change).
|
|
118
130
|
- Paths are physical and nonoverlapping: state is outside every base and
|
|
119
131
|
instance home; the bindings document is outside state and bases.
|
|
120
|
-
- `cron` and `tz` are removed: the provider
|
|
132
|
+
- `cron` and `tz` are removed: the provider schedules nothing.
|
|
133
|
+
- Protect each Git base's accepted branch so that only a pull request the
|
|
134
|
+
knowledge maintainer merges changes it: the maintainer can gate only what
|
|
135
|
+
cannot bypass it. `oats okf bases` reports `protection: enforced | none |
|
|
136
|
+
unknown` per Git base, read-only.
|
|
121
137
|
- A bad configured base blocks a knowledge-slot spawn; the error names the
|
|
122
138
|
alias. Spawning never bootstraps an empty accepted base as a fallback.
|
|
123
139
|
|
|
124
140
|
### Settings
|
|
125
141
|
|
|
126
|
-
The knowledge capability declares
|
|
142
|
+
The knowledge capability declares five host settings:
|
|
127
143
|
|
|
128
144
|
| Setting | Default | Meaning |
|
|
129
145
|
|---|---|---|
|
|
@@ -131,14 +147,14 @@ The knowledge capability declares four host settings:
|
|
|
131
147
|
| `state-dir` | required by portable binding preparation | Absolute host-owned state location, never derived from an instance home. |
|
|
132
148
|
| `git-timeout` | `600` | Seconds allowed for a remote Git operation. |
|
|
133
149
|
| `consult-max-age` | `300` | Maximum cached accepted-commit age before refetch; `0` always refetches. |
|
|
150
|
+
| `screen-terms-file` | none | Optional (6.0): absolute path of a host file, one term per line; `oats okf propose` refuses outgoing content holding a term (rule `host-term`, by location only). It only adds refusals. |
|
|
134
151
|
|
|
135
152
|
Host `harvest`, `harvest-runtime` and `harvest-model` are removed, including
|
|
136
153
|
explicit `harvest: off`. A 4.x **recorded manifest default** is ignored by
|
|
137
154
|
5.0 readers as nobody's decision, not reinterpreted as an opt-out. Explicit
|
|
138
|
-
removed keys still refuse and name the fix.
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
publication failure retains its live home; see [the flow](#the-flow).
|
|
155
|
+
removed keys still refuse and name the fix. A host or spawn `publish` refuses
|
|
156
|
+
too: only the soul opts out ([The soul's opt-out](#the-souls-opt-out)). There
|
|
157
|
+
is no proposal runtime or model to choose: the instance proposes itself.
|
|
142
158
|
|
|
143
159
|
## The soul's okf.json
|
|
144
160
|
|
|
@@ -154,26 +170,44 @@ context. Neither is an access-control list: every configured base is
|
|
|
154
170
|
readable. Missing declarations, base metadata or indexes refuse spawn;
|
|
155
171
|
legacy soul-local knowledge needs explicit migration, never silent copying.
|
|
156
172
|
|
|
173
|
+
**Version 2 (6.0)** binds a soul to **subjects** on a bridged base, one with
|
|
174
|
+
the subject layout (its `okf-base.json` lists the reserved nodes `claims`,
|
|
175
|
+
`subjects` and `verdicts`):
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{ "version": 2, "subjects": ["system/oats-kernel", "workstream/operations"] }
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Each entry is `<kind>/<slug>`, a subject that exists on a bound base. They
|
|
182
|
+
are the soul's reading defaults, with no owner, `owns` or `reads`: spawn and
|
|
183
|
+
readiness resolve them (`E_CONFIG: unresolved subject: <ref>`; a plain base
|
|
184
|
+
answers `E_CONFIG: base <alias> has no subject layout`), and the spawn brief
|
|
185
|
+
lists one line per subject with its claim counts. Such a soul writes its
|
|
186
|
+
claims under `claims/`, each `about:` one or more subjects. Version 1 keeps
|
|
187
|
+
working on a bridged base. A soul moves to version 2 once its base is
|
|
188
|
+
bridged.
|
|
189
|
+
|
|
157
190
|
`oats okf init` provisions a new directory base with `--confirm`, or stages a
|
|
158
191
|
Git base with `--output` for reviewed delivery. Existing knowledge is never
|
|
159
192
|
overwritten by initialization.
|
|
160
193
|
|
|
161
|
-
## The
|
|
194
|
+
## The soul's opt-out
|
|
162
195
|
|
|
163
|
-
**There is no host
|
|
164
|
-
soul's opt-out:
|
|
196
|
+
**There is no host switch.** The sole choice is the soul's opt-out:
|
|
165
197
|
|
|
166
198
|
```yaml
|
|
167
|
-
knowledge: { harvest: off }
|
|
199
|
+
knowledge: { harvest: off } # from 6.0 also spelled publish: off
|
|
168
200
|
```
|
|
169
201
|
|
|
170
|
-
That soul keeps consultation and working-memory guidance but has no
|
|
171
|
-
|
|
202
|
+
That soul keeps consultation and working-memory guidance but has no duty to
|
|
203
|
+
propose. The shared IMPORTANT block and compulsory skill pointer still ship,
|
|
172
204
|
with an explicit exception; the provider's spawn-recorded answer says `off`.
|
|
173
|
-
Independently,
|
|
174
|
-
|
|
175
|
-
A soul's `harvest: on` is not a replacement switch
|
|
176
|
-
|
|
205
|
+
Independently, `oats okf propose` refuses that soul's homes (`E_OPTED_OUT`),
|
|
206
|
+
also reading the soul's own text. Absence gives the normal proposal flow.
|
|
207
|
+
A soul's `harvest: on` is not a replacement switch, and a soul `publish`
|
|
208
|
+
other than `off`, or a soul `knowledge.propose` key, refuses the spawn
|
|
209
|
+
(`E_CONFIG`). Host cleanup never changes the soul declaration.
|
|
210
|
+
`knowledge: none` removes the layer entirely.
|
|
177
211
|
|
|
178
212
|
## Knowledge operations
|
|
179
213
|
|
|
@@ -182,14 +216,14 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
182
216
|
1. **Consult and keep instance knowledge current.** Read accepted soul
|
|
183
217
|
knowledge at task start, after compaction and before decisions. Keep
|
|
184
218
|
`STATE.md`, `log.md` and `notes/` up to date as work happens. The
|
|
185
|
-
capability's **IMPORTANT** inject block makes this upkeep and
|
|
186
|
-
checkpoint
|
|
219
|
+
capability's **IMPORTANT** inject block makes this upkeep and proposing at
|
|
220
|
+
each knowledge checkpoint a duty; reading **okf-propose** is compulsory.
|
|
187
221
|
Neither duty depends on TASK.md. Run `oats okf status` from instance home
|
|
188
222
|
to learn the duty recorded at spawn: `on` means follow the skill, `off`
|
|
189
|
-
means no
|
|
190
|
-
infer permission or edit the record. Working instances never
|
|
191
|
-
accepted
|
|
192
|
-
2. **Propose at each
|
|
223
|
+
means no proposal, and `unknown` or an error means stop and report, never
|
|
224
|
+
infer permission or edit the record. Working instances never push to an
|
|
225
|
+
accepted branch or merge their own proposals.
|
|
226
|
+
2. **Propose at each knowledge checkpoint.** The checkpoints are a PR handed
|
|
193
227
|
over for review and a finished task. In a long-lived role whose task
|
|
194
228
|
never finishes (a maintainer, an expert holding an area, a support desk),
|
|
195
229
|
they also include a feature ready, a release or deploy shipped, and a
|
|
@@ -200,117 +234,79 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
200
234
|
`knowledge-theory` and search accepted knowledge (`oats okf search`, then
|
|
201
235
|
`cat`): already accepted with nothing to add means no proposal. Make **one
|
|
202
236
|
proposal per checkpoint, carrying only what no earlier proposal carried**,
|
|
203
|
-
and record every checkpoint in `log.md`, either with its proposal
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
`
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
237
|
+
and record every checkpoint in `log.md`, either with its proposal's PR
|
|
238
|
+
URLs or with `nothing to propose` and the reason. Claim only for owned
|
|
239
|
+
nodes (or, for a version-2 soul, in `claims/` on its subjects); a lesson
|
|
240
|
+
for a node the soul only reads is named in one line in its hand-back for
|
|
241
|
+
that node's owner.
|
|
242
|
+
|
|
243
|
+
The instance proposes itself, from its home, in three steps:
|
|
244
|
+
|
|
245
|
+
```sh
|
|
246
|
+
oats okf propose --plan --slug <slug>
|
|
247
|
+
oats okf propose --check --slug <slug>
|
|
248
|
+
oats okf propose --apply --slug <slug> --digest <digest>
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
`--plan` clones every Git base the soul owns, at its accepted branch, into
|
|
252
|
+
`proposals/<date>-<slug>/work/<alias>`, writes the skeleton
|
|
253
|
+
`proposal.md` (What, Why, Evidence, Backing notes), and prints the write
|
|
254
|
+
surface (the owned nodes and the base root `index.md`) and the open
|
|
255
|
+
`okf-proposal` and `okf-harvest` PRs: duplicate candidates. The instance
|
|
256
|
+
writes the concepts in the clone with its own file tools and fills
|
|
257
|
+
`proposal.md`. `--check` validates the proposed tree, checks every path
|
|
258
|
+
against the write surface, hashes the named notes, screens everything
|
|
259
|
+
that would leave the host and prints the complete outgoing diff, the
|
|
260
|
+
commit text, the PR body with its provenance block and a digest; nothing
|
|
261
|
+
remote changes, and the instance reads that diff once as a reviewer would.
|
|
262
|
+
`--apply` with that digest commits, pushes a new
|
|
263
|
+
`okf-proposal/<date>-<uuid>` branch (create-only, never the accepted
|
|
264
|
+
branch), labels it `okf-proposal` and opens one PR per changed base. One
|
|
265
|
+
attempt per proposal: a publication error (`E_BASE_MOVED`,
|
|
266
|
+
`E_PUSH_UNCERTAIN`, `E_GH`, `E_PR_UNCERTAIN`) is reported, never retried,
|
|
267
|
+
and a remote branch or PR may exist after an uncertain one. The instance
|
|
268
|
+
records the PR URLs in `log.md` and goes back to work: it never shepherds
|
|
269
|
+
the PR, and nobody waits for it to merge. oats.okf's README has every
|
|
270
|
+
refusal and its remedy.
|
|
271
|
+
|
|
272
|
+
**The operator form,** for a source that retired without proposing, runs
|
|
273
|
+
the same three steps from the deployment on its retirement recovery:
|
|
274
|
+
`oats okf propose --home <retirement recovery directory> --soul <soul>
|
|
275
|
+
--plan --slug <slug>`, then `--check` and `--apply` with the same `--home`
|
|
276
|
+
and `--soul`. The proposal directory is made in the copied home, and the
|
|
277
|
+
provenance names the form.
|
|
278
|
+
3. **Review.** A separate `oats.okf/knowledge-maintainer` reviews each PR
|
|
279
|
+
and **gates every merge**: it verifies each claim against the evidence it
|
|
280
|
+
cites, judges it by the promotion test, and merges, amends and merges, or
|
|
281
|
+
closes it, with a verdict bound to the exact head. The `proposal-review`
|
|
282
|
+
trigger spawns it ([Triggers](#triggers)); where none is installed, the
|
|
283
|
+
proposer may spawn one, a call and not a station:
|
|
232
284
|
|
|
233
285
|
```sh
|
|
234
|
-
oats spawn oats.okf/knowledge-
|
|
286
|
+
oats spawn oats.okf/knowledge-maintainer --task "Review knowledge-base PR <url> at <head>. Load the knowledge-review skill first." --relation unrelated
|
|
235
287
|
```
|
|
236
288
|
|
|
237
|
-
Never combine `--relation unrelated` with `--relative-to`, or override
|
|
238
|
-
the kernel's harness/model selection. An unrelated harvester can outlive
|
|
239
|
-
its proposer; a child would tie their lifetimes together. There is no
|
|
240
|
-
automatic transcript capture, source registry, worker cursor or retire
|
|
241
|
-
harvest. Keep backing notes until the harvester retires; the proposer
|
|
242
|
-
itself need not stay alive. Its recorded retirement recovery can supply
|
|
243
|
-
evidence before capture, so do not dispose of it before capture.
|
|
244
|
-
Missing source authority never permits inventing it.
|
|
245
|
-
|
|
246
|
-
A refused or uncertain spawn is reported, not retried in a loop. On
|
|
247
|
-
`E_INSTANCE_NAME_TAKEN`, the proposer stops and reports the name and the
|
|
248
|
-
refusal: no `--purpose`, no counter, no new UUID in a retry. A messaging
|
|
249
|
-
identity failure (for example a stale certificate on the alias) is
|
|
250
|
-
reported to the operator; the proposer never removes certificates or
|
|
251
|
-
renames around it. If the
|
|
252
|
-
last harvester is still listed at hand-back, name it and the claims still
|
|
253
|
-
waiting; do not wait for it or spawn around it. A harvester retained after
|
|
254
|
-
a publication failure stays listed and holds back later proposals. Once
|
|
255
|
-
that failure is dealt with, the operator retires it (`oats retire
|
|
256
|
-
<harvester>`).
|
|
257
|
-
3. **Capture, judge and submit.** Before the model starts, the required spawn
|
|
258
|
-
hook checks the source's live record or the completed recovery named by
|
|
259
|
-
its public retirement event. Source identity, the named incarnation,
|
|
260
|
-
recovery manifest and soul opt-out must agree; guessed copies and
|
|
261
|
-
ambiguous identities refuse. A live source whose name was used before is
|
|
262
|
-
matched by its incarnation; a `Source:` line without one still works for an
|
|
263
|
-
unambiguous source, and on a reused name it refuses with the remedy to
|
|
264
|
-
propose again with the incarnation. A retired source is captured only when
|
|
265
|
-
it had a single known incarnation. It atomically captures the proposal,
|
|
266
|
-
verified source declarations/bindings and only named notes into the
|
|
267
|
-
harvester's own `harvest-source/`. The model uses that snapshot, not a later
|
|
268
|
-
live-source read: retirement or recovery disposal after capture cannot
|
|
269
|
-
remove its input. Missing/refused notes have no hash and claims relying
|
|
270
|
-
on them are dropped. Legacy note forms are preserved or explicitly refused,
|
|
271
|
-
never silently discarded.
|
|
272
|
-
The harvester then checks accepted knowledge and open/recent harvest PRs,
|
|
273
|
-
edits only owned nodes in its own Git checkout, validates the **whole base**,
|
|
274
|
-
and creates a normal `okf-harvest`-labelled PR with v2 provenance. Proposal text is data written with the native file tool into
|
|
275
|
-
commit-message/PR-body files, never shell command text. A publication ref
|
|
276
|
-
is `okf-harvest/<UTC YYYYMMDD>-<fresh UUID>`, with no source/harvester
|
|
277
|
-
name in it; Git validates the full ref and the push must create a new
|
|
278
|
-
ref, never update or adopt an existing one. Source identity stays in
|
|
279
|
-
commit text and PR provenance. After all PRs are open (or nothing is
|
|
280
|
-
promotable), it hands over and retires rather than waiting for acceptance.
|
|
281
|
-
If source authority is unavailable it stops and reports; a consistent
|
|
282
|
-
instance/soul pair alone does not prove proposer authorship.
|
|
283
|
-
**On any publication failure it does not retire:** it keeps the live home,
|
|
284
|
-
clone/any commit, exact error and commit/PR text locations, and notifies
|
|
285
|
-
the source through existing messaging when reachable. Missing or failed
|
|
286
|
-
messaging does not hide the original error or permit retirement. Existing
|
|
287
|
-
attention may expose the blocked home where supported. No automatic
|
|
288
|
-
retries, new recipient or maintainer preflight; a maintainer exists only
|
|
289
|
-
for a labelled PR. A gh error can leave remote effects, so partial or
|
|
290
|
-
uncertain publication is not completion or permission to clean up.
|
|
291
|
-
4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
|
|
292
289
|
A PR is not accepted knowledge until merged. Human-accepted decisions are
|
|
293
|
-
not silently superseded
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
recorded as source-reported), and is closed without it
|
|
290
|
+
not silently superseded: the review never parks a PR, and such a
|
|
291
|
+
supersession merges only with the human's acceptance cited (checked when
|
|
292
|
+
the record is on GitHub, otherwise recorded as source-reported), and is
|
|
293
|
+
closed without it
|
|
298
294
|
([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)).
|
|
295
|
+
The maintainer reports to no one: the proposer reads the PR.
|
|
299
296
|
|
|
300
297
|
The promotion test belongs to
|
|
301
298
|
[What deserves to become knowledge](knowledge-theory.md#what-deserves-to-become-knowledge),
|
|
302
|
-
not a
|
|
303
|
-
|
|
299
|
+
not a kernel mechanism. The maintainer soul has `knowledge: none`; working
|
|
300
|
+
souls also receive the curated theory skill.
|
|
304
301
|
The [older knowledge-operations design](design/2026-09-26-okf-knowledge-operations.md)
|
|
305
|
-
is historical 4.x context, not instructions for operating
|
|
302
|
+
is historical 4.x context, not instructions for operating 6.0.
|
|
306
303
|
|
|
307
|
-
### What a
|
|
304
|
+
### What a proposal leaves out
|
|
308
305
|
|
|
309
306
|
Secrets, credentials, private paths and verbatim third-party messages are
|
|
310
307
|
left out. So is personal data, in the same sentence at every place an agent
|
|
311
|
-
is told what to leave out (the capturing instance, the proposing skill
|
|
312
|
-
|
|
313
|
-
review):
|
|
308
|
+
is told what to leave out (the capturing instance, the proposing skill when
|
|
309
|
+
it writes and when it reads its outgoing diff, and the maintainer's review):
|
|
314
310
|
|
|
315
311
|
> Never include personal data about people outside the team (clients,
|
|
316
312
|
> correspondents, any other third party): a name, a contact detail, or
|
|
@@ -320,24 +316,35 @@ review):
|
|
|
320
316
|
|
|
321
317
|
The sentence also covers the names provenance publishes as written: note
|
|
322
318
|
file names, task refs and instance names. These exclusions are instructions
|
|
323
|
-
to agents and guarantee nothing.
|
|
324
|
-
judge its content.
|
|
325
|
-
|
|
326
|
-
the
|
|
327
|
-
The
|
|
328
|
-
|
|
329
|
-
|
|
319
|
+
to agents and guarantee nothing. The propose command hashes the evidence it
|
|
320
|
+
names but does not judge its content. A bounded content screen runs over
|
|
321
|
+
everything that would leave the host before every push, comment and merge,
|
|
322
|
+
and the host's `screen-terms-file` can add terms to it; a clean screen is not
|
|
323
|
+
proof. The proposer reads its outgoing diff before the push; the maintainer,
|
|
324
|
+
the second reader, reads the already-pushed pull request. The write surface,
|
|
325
|
+
the provenance checks and the soul's opt-out are enforced in code; none is a
|
|
326
|
+
privacy guarantee. The opt-out ([The soul's opt-out](#the-souls-opt-out)) is
|
|
327
|
+
per soul and covers that soul's own proposals, not what its instances write
|
|
328
|
+
to other seats. A soul whose work is reading third-party correspondence
|
|
329
|
+
should opt out.
|
|
330
330
|
|
|
331
331
|
### Triggers
|
|
332
332
|
|
|
333
333
|
Only **PR review** is triggered. Use the package template
|
|
334
|
-
`oats.okf:
|
|
335
|
-
|
|
334
|
+
`oats.okf:proposal-review` (label `okf-proposal`) in a workspace trigger
|
|
335
|
+
file, or
|
|
336
|
+
`oats trigger add --from oats.okf:proposal-review --set repo=github.com/<owner>/<repo>`.
|
|
337
|
+
Through 6.x, `oats.okf:harvest-review` watches only the 5.x label
|
|
338
|
+
`okf-harvest`. The kernel requires every label a trigger names, so each
|
|
339
|
+
template watches one: keep `harvest-review` beside `proposal-review` only
|
|
340
|
+
while a 5.x harvester may still open an `okf-harvest` PR, then remove it.
|
|
336
341
|
The `okf-trigger-setup` skill explains setup and testing. Validate the review
|
|
337
|
-
route with `oats trigger test` before relying on automated review.
|
|
342
|
+
route with `oats trigger test` before relying on automated review. Without
|
|
343
|
+
the trigger, proposal PRs wait for a human reviewer or a maintainer the
|
|
344
|
+
proposer spawns.
|
|
338
345
|
|
|
339
|
-
There are no per-source
|
|
340
|
-
|
|
346
|
+
There are no per-source jobs or host-timer installation steps in this
|
|
347
|
+
provider. See [Knowledge proposal review](schedules.md#knowledge-proposal-review),
|
|
341
348
|
[Triggers](schedules.md#triggers) and
|
|
342
349
|
[Workspace triggers and schedules](schedules.md#workspace-triggers-and-schedules).
|
|
343
350
|
|
|
@@ -345,14 +352,16 @@ this provider. See [Knowledge harvest and review](schedules.md#knowledge-harvest
|
|
|
345
352
|
|
|
346
353
|
| Capability | Composed into | Skills |
|
|
347
354
|
|---|---|---|
|
|
348
|
-
| `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), [`okf-propose`](../mirrors/oats-okf/skills/okf-propose/SKILL.md), `knowledge-theory` |
|
|
349
|
-
| `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` |
|
|
355
|
+
| `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), [`okf-propose`](../mirrors/oats-okf/skills/okf-propose/SKILL.md), `knowledge-theory`, `okf-authoring` |
|
|
350
356
|
| `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) |
|
|
351
357
|
|
|
352
358
|
The capability's **IMPORTANT** inject block gives the duty and compulsory
|
|
353
359
|
pointer; **okf-propose** holds the procedure. These shared texts also reach
|
|
354
360
|
opted-out souls, with the explicit exception and provider status answer.
|
|
355
|
-
No
|
|
361
|
+
No TASK brief contains proposal direction. Until 7.0 the package also ships
|
|
362
|
+
`oats.okf-harvest` and the soul `oats.okf/knowledge-harvester` as stubs, with
|
|
363
|
+
no skills or instructions: the soul's required spawn hook refuses every spawn
|
|
364
|
+
with `E_REMOVED`, naming the fix.
|
|
356
365
|
|
|
357
366
|
## Inspection and operator commands
|
|
358
367
|
|
|
@@ -379,6 +388,17 @@ oats okf links --base project /expert/decisions/retry-policy.md
|
|
|
379
388
|
oats okf search backoff [--base ALIAS | --all] [--node NODE] [--regex] [--case-sensitive]
|
|
380
389
|
```
|
|
381
390
|
|
|
391
|
+
On a bridged base, the subject verbs read the committed indexes by subject:
|
|
392
|
+
|
|
393
|
+
```sh
|
|
394
|
+
oats okf subjects [--kind KIND]
|
|
395
|
+
oats okf subject KIND/SLUG
|
|
396
|
+
oats okf claims --about KIND/SLUG [--type TYPE] [--kind KIND]
|
|
397
|
+
oats okf index [KIND/SLUG]
|
|
398
|
+
oats okf verdicts --check CLAIM-FILE
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
A plain base answers them with `E_USAGE: base <alias> has no subject layout`.
|
|
382
402
|
Commands accept `--json` and `--fresh`. Run from the home, or select a live
|
|
383
403
|
home with `--home PATH` from an operator scope and the appropriate `--soul`.
|
|
384
404
|
There is no `--source` descriptor path, including after retirement. Paths
|
|
@@ -386,21 +406,22 @@ are rooted in the base, never outside it. A failed fetch may serve cached
|
|
|
386
406
|
accepted bytes marked stale. `read` and `refresh` remain removed: use `cat`
|
|
387
407
|
and `index`. The consultation skill teaches navigation and citation.
|
|
388
408
|
|
|
389
|
-
### Read the
|
|
409
|
+
### Read the duty to propose
|
|
390
410
|
|
|
391
411
|
```sh
|
|
392
412
|
oats okf status --json
|
|
393
413
|
```
|
|
394
414
|
|
|
395
415
|
The provider's answer is `result.harvest: "on"` with `reason: "default"`, or
|
|
396
|
-
`"off"` with `reason: "soul-opt-out"
|
|
416
|
+
`"off"` with `reason: "soul-opt-out"`; from 6.0 `result.publish` repeats the
|
|
417
|
+
same value under its new name. It reads only home-local spawn state,
|
|
397
418
|
not the network, bases, TASK.md or a soul file. Missing state is `"unknown"`
|
|
398
419
|
with `reason: "spawn-state-missing"`; malformed or linked state refuses.
|
|
399
420
|
Neither unknown nor failure permits a proposal. Report it and respawn with
|
|
400
421
|
the current provider; never hand-create a policy or reinterpret later
|
|
401
422
|
settings as the spawn decision. `--home PATH` selects an explicit home.
|
|
402
|
-
This answer is instruction state, not publication authority:
|
|
403
|
-
|
|
423
|
+
This answer is instruction state, not publication authority: `oats okf
|
|
424
|
+
propose` reads it and refuses `off` and `unknown` homes itself.
|
|
404
425
|
|
|
405
426
|
### Inspect
|
|
406
427
|
|
|
@@ -422,6 +443,7 @@ From the deployment, with `--soul <name>`:
|
|
|
422
443
|
|
|
423
444
|
| Command | Purpose |
|
|
424
445
|
|---|---|
|
|
446
|
+
| `propose --home <recovery> --soul <name> (--plan \| --check \| --apply) --slug <slug>` | Propose for a source that retired without proposing ([the flow](#the-flow)). |
|
|
425
447
|
| `setup --remove-legacy-settings [--plan] [--json]` | Delete only explicit legacy host harvest keys; guard-exempt, plan read-only. |
|
|
426
448
|
| `init --base ALIAS --nodes FILE (--confirm \| --output PATH)` | Provision a directory base or stage a Git proposal. |
|
|
427
449
|
| `migrate …` | Explicitly migrate legacy soul-local knowledge into a base. |
|
|
@@ -430,8 +452,9 @@ From the deployment, with `--soul <name>`:
|
|
|
430
452
|
### Completion and recovery
|
|
431
453
|
|
|
432
454
|
`harvest`, `run-source`, `complete`, `retry`, `harvest-status`, old source
|
|
433
|
-
selectors and harvest setup switches return actionable removal errors
|
|
434
|
-
There is no
|
|
455
|
+
selectors and harvest setup switches return actionable removal errors, as
|
|
456
|
+
does a spawn of the harvester stub. There is no completion/settlement engine:
|
|
457
|
+
a proposal's publication record stays in its proposal directory. Existing 4.x private
|
|
435
458
|
inputs and open PR obligations must be resolved explicitly under the old
|
|
436
459
|
provider before the pin; they are not deleted or re-imported by 5.0. Follow
|
|
437
460
|
the [ordered cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), including the host cleanup
|
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.24.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
|
|
13
|
+
| `oats.okf` | `v6.0.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.39.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
|
|
15
15
|
| `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `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.1.0` | `oats.cloning` | `cloner` |
|
|
@@ -64,7 +64,7 @@ aliases, a later decision once no workspace we know of pins it.
|
|
|
64
64
|
## Find and use packages
|
|
65
65
|
|
|
66
66
|
- A workspace pins an official package by **bare version** in its
|
|
67
|
-
`packages:` map (`oats.okf:
|
|
67
|
+
`packages:` map (`oats.okf: v6.0.1`); `oats sync` resolves it through the
|
|
68
68
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
69
69
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
70
70
|
not join a team or adopt the publisher's workspace. See
|