@awebai/oats 0.69.15 → 0.69.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/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 5.8.0** (OATS **>=0.69.2**). Provider implementation and
9
+ This is the operator guide for **oats.okf 6.0.2** (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
- | Harvester home: `harvest-source/` | Private source evidence captured at spawn, not accepted knowledge. |
19
- | Bindings file and `stateDir` | Host base locations and consultation/binding state, not a harvest queue. |
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: v5.8.0
31
+ oats.okf: v6.0.2
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. From 5.6.0 it requires OATS >=0.69.2: its
54
- `knowledge-harvester` and `knowledge-maintainer` souls say `background: true`,
55
- which an older kernel refuses. Upgrade OATS first, then the package.
56
-
57
- **Upgrade:** pin `oats.okf: v5.8.0` and run `oats sync`. Only new spawns get
58
- the capability-owned harvest duty, skill and spawn-recorded policy. Existing
59
- homes keep their copied provider even after a session restart; from 5.4.0, a
60
- stopped 5.x home can move with `oats instance upgrade` (OATS 0.68.0 and
61
- later), and a home spawned under 4.x is refused with the remedy to retire and
62
- respawn it. Deployments whose briefings never mentioned harvesting now get
63
- knowledge proposals at the harvest checkpoints; souls not ready for this must
64
- declare `knowledge: { harvest: off }`. Consultation and instance-memory upkeep
65
- remain. From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the
66
- checkpoint line in `log.md`, drops the available-memory gate, and has the
67
- proposer name each harvester (`--name`, below). 5.5.0 adds the incarnation to
68
- the proposal's `Source:` line (below): a harvester on 5.4.0 or older refuses
69
- that line, so run `oats sync` to 5.5.0 or later before instances on 5.5.0
70
- propose. 5.6.0 lists new harvesters and knowledge maintainers under the
71
- clients' Background section; existing ones do not move. 5.7.0 stops parking
72
- harvest PRs under `okf-needs-human` (step 4 of [the flow](#the-flow)); PRs an
73
- older maintainer parked are re-reviewed by the steps in okf's CHANGELOG.
74
- 5.8.0 screens what harvest and maintenance publish (the outgoing history,
75
- paths, blobs and text) before any push, comment or merge, and reports only
76
- the location, line and rule; a harvest PR behind the accepted tip is
77
- rewritten onto it for a fresh exact-head verdict, never merged on an
78
- approximate squash. Structural validation is unchanged. A harvester or
79
- knowledge maintainer spawned after the sync uses it; existing homes keep
80
- their copy until respawned or upgraded.
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.2/CHANGELOG.md).
60
+
61
+ **Upgrade to 6.0:** pin `oats.okf: v6.0.2` 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.2/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. Harvest
110
- proposals use same-repository GitHub PRs through ordinary `git` and `gh`.
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 automatic
116
- harvest publication**. The 5.0 harvester reports directory harvest as
117
- unsupported and names the Git/PR remedy.
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 no longer schedules harvest.
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 four host settings:
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. The harvester has no provider
139
- runtime/model switch or PR-wait deadline; it uses ordinary kernel/harness
140
- selection and retires after successful handoff or nothing promotable. A
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 harvest switch
194
+ ## The soul's opt-out
162
195
 
163
- **There is no host harvest switch in 5.0.** The sole remaining choice is the
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 harvest
171
- duty. The shared IMPORTANT block and compulsory skill pointer still ship,
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, the harvester's required spawn hook refuses that soul's
174
- material. Absence gives the normal proposal flow.
175
- A soul's `harvest: on` is not a replacement switch. Host cleanup never
176
- changes the soul declaration. `knowledge: none` removes the layer entirely.
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 eligible
186
- checkpoint harvesting a duty; reading **okf-propose** is compulsory.
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 harvest, and `unknown` or an error means stop and report, never
190
- infer permission or edit the record. Working instances never write
191
- accepted knowledge themselves.
192
- 2. **Propose at each harvest checkpoint.** The checkpoints are a PR handed
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 and
204
- harvester or with `nothing to propose` and the reason.
205
-
206
- Write a short self-contained `proposals/<YYYY-MM-DD>-<slug>.md` in instance
207
- home: What (one claim per concept), Why, Evidence (observations, dates,
208
- limits and accepted concepts cited), and optional `## Backing notes` with
209
- one `- notes/<file>.md` entry per note. It has exactly one line
210
- `Source: instance <name>, home <path>, soul <name>, incarnation <createdAt>`
211
- naming the actual source, with `createdAt` copied from its `instance.json`:
212
- a pointer to verify rather than authority. Claim only for owned
213
- nodes; a lesson for a node the soul only reads is named in one line in its
214
- hand-back for that node's owner.
215
-
216
- **Before spawning:** one harvester at a time per instance. Do not spawn
217
- another while `oats status` still lists the last one: keep the proposal
218
- pending in STATE.md and log.md, add the next checkpoint's claims to it,
219
- and launch it at that checkpoint once the last harvester is gone. Never
220
- poll, sleep or stop other instances to make room. (5.3.0 removed the
221
- 5.2.x available-memory gate.)
222
-
223
- **The proposer names its harvester.** For each new proposal,
224
- **okf-propose** prints a fresh name: up to 21 characters of the source
225
- instance's name, a dash, a random UUID without dashes, and `-harvester`,
226
- 64 characters at most (the kernel's and aweb's alias limit). The proposer
227
- records it with the proposal in log.md before the preview, checks that
228
- `oats status` doesn't list it, and uses it unchanged in both the preview and
229
- the apply. Never leave the name to the kernel's numbered default: a retired
230
- harvester's messaging alias can stay occupied with no instance listed, and
231
- a numbered name can land on it.
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-harvester --name <harvester-name> --task-file <proposal> --relation unrelated
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. Before oats.okf 5.7.0 the maintainer labels a PR
294
- that would supersede one `okf-needs-human` and leaves it to a human. From
295
- 5.7.0 the review never parks a PR: such a supersession merges only with the
296
- human's acceptance cited (checked when the record is on GitHub, otherwise
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 universal kernel harvester. Both package role souls have
303
- `knowledge: none`; working souls now also receive the curated theory skill.
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 5.0.
302
+ is historical 4.x context, not instructions for operating 6.0.
306
303
 
307
- ### What a harvest leaves out
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, the
312
- harvester when it edits and when it reads its diff, and the maintainer's
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. Source capture copies evidence but does not
324
- judge its content. The first publication reviewer other than the harvester
325
- reads the already-pushed pull request. Source capture/provenance checks and
326
- the soul's opt-out are enforced in code; neither is a privacy guarantee.
327
- The opt-out ([The harvest switch](#the-harvest-switch)) is per soul and covers
328
- that soul's own proposals, not what its instances write to other seats. A
329
- soul whose work is reading third-party correspondence should opt out.
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:harvest-review` in a workspace trigger file, or
335
- `oats trigger add --from oats.okf:harvest-review --set repo=github.com/<owner>/<repo>`.
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 harvest jobs or host-timer installation steps in
340
- this provider. See [Knowledge harvest and review](schedules.md#knowledge-harvest-and-review),
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 source TASK brief contains harvest or proposal direction.
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 harvest duty
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"`. It reads only home-local spawn state,
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: the harvester
403
- still independently checks its recorded source's opt-out.
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 replacement completion/settlement engine. Existing 4.x private
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
@@ -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.23.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` | `v5.8.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.37.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
12
+ | `oats.framework` | `oats-framework/v1.24.1` (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.2` | `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: v5.8.0`); `oats sync` resolves it through the
67
+ `packages:` map (`oats.okf: v6.0.2`); `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