@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/README.md CHANGED
@@ -246,7 +246,7 @@ Agents don't have to wait for someone to type. Schedules and triggers are part o
246
246
  - **A trigger** starts a new agent when an event matches: a GitHub pull request opened, labelled or updated, or an event from a source a capability provides.
247
247
  - **Shared or local.** Kept in the workspace, they are reviewed like everything else and run on the machine they name; or keep them local to one machine. On a server they keep running while your laptop sleeps.
248
248
 
249
- For example, every knowledge harvest pull request can get its own reviewer agent minutes after it opens.
249
+ For example, every knowledge proposal pull request can get its own reviewer agent minutes after it opens.
250
250
 
251
251
  ## OATS Desktop
252
252
 
@@ -574,7 +574,8 @@ One package can carry capabilities meant for **different souls**. oats.okf
574
574
  ships three:
575
575
 
576
576
  - `oats.okf` fills every working soul's knowledge slot;
577
- - `oats.okf-harvest` is composed only into its harvester soul;
577
+ - `oats.okf-harvest` is composed only into its harvester soul, a stub
578
+ since 6.0 that refuses every spawn (kept until 7.0);
578
579
  - `oats.okf-maintenance` is composed only into its maintainer soul.
579
580
 
580
581
  Each is its own manifest with its own skills, inject and commands. One pin
@@ -1587,7 +1588,7 @@ schedule or an operator invokes without knowing the provider.
1587
1588
 
1588
1589
  ```json
1589
1590
  "operations": {
1590
- "harvest": { "kind": "action", "command": "harvest", "context": "home", "description": "Promote this instance's notes" },
1591
+ "checkpoint": { "kind": "action", "command": "checkpoint", "context": "home", "description": "Record this instance's checkpoint" },
1591
1592
  "inspect": { "kind": "view", "command": "inspect", "context": "home", "description": "Show this instance's working knowledge" }
1592
1593
  }
1593
1594
  ```
package/docs/container.md CHANGED
@@ -3,8 +3,10 @@
3
3
  `container/agent/` supplies an agent image and a Compose service for one
4
4
  team's trust group. It runs non-root sshd on port 2222; the operator uses the
5
5
  existing [server route](servers.md) to connect, preview and spawn. The
6
- entrypoint creates private state directories and host keys, then starts
7
- sshd. Deployment setup and seat admission belong to the operator.
6
+ entrypoint creates private state directories and host keys, starts sshd,
7
+ then runs `oats host run`
8
+ ([The kernel's periodic work](#the-kernels-periodic-work)). Deployment setup
9
+ and seat admission belong to the operator.
8
10
 
9
11
  ## Configuration contract
10
12
 
@@ -61,8 +63,10 @@ version and regenerate this directory's lock with
61
63
  `npm install --package-lock-only --ignore-scripts`; review both files. Do not
62
64
  use `--install-oats` or `--install-aw` against a running container.
63
65
 
64
- The committed OATS 0.69.14 pin supports `env: { fromFile: ... }` and the
65
- operator's `oats harness token set` route. Provision the token through the
66
+ The committed OATS 0.69.15 pin has `oats host run`, which the entrypoint
67
+ runs, and `oats schedule host install --register-only`. It supports
68
+ `env: { fromFile: ... }` and the operator's `oats harness token set` route.
69
+ Provision the token through the
66
70
  [harness credential route](servers.md#harness-credentials) and collect live
67
71
  acceptance evidence before claiming the two-seat inference milestone.
68
72
 
@@ -122,7 +126,10 @@ Supply these plain variables to the bundle's env file:
122
126
  The bundle owns the network, resolver, forwarder, firewall and their bypass
123
127
  checks. The agent service publishes no ports and sets no DNS or extra-hosts
124
128
  override. It joins only the named external `agents` network. Its restart
125
- policy is `unless-stopped`; security flags are fixed in the service file.
129
+ policy is `unless-stopped`, its stop grace period is 45 seconds and its
130
+ healthcheck reads sshd's port
131
+ ([The kernel's periodic work](#the-kernels-periodic-work)); security flags
132
+ are fixed in the service file.
126
133
 
127
134
  ```sh
128
135
  docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
@@ -157,7 +164,15 @@ oats server connect team-agent --ssh <ssh-alias> --dir /state/deploy \
157
164
  ```
158
165
 
159
166
  Use public HTTPS package pins unless a separate reviewed credential route
160
- is provisioned. Verify `server connect` reports ready. The operator places
167
+ is provisioned. Verify `server connect` reports ready. Then register the
168
+ deployment for the schedule tick `oats host run` runs in the container
169
+ ([The kernel's periodic work](#the-kernels-periodic-work)):
170
+
171
+ ```sh
172
+ oats schedule host install --register-only --server team-agent
173
+ ```
174
+
175
+ The operator places
161
176
  two independently admitted ordinary-member identities at
162
177
  `/state/seats/<alias>/.aw`; each spawn selects one:
163
178
 
@@ -188,46 +203,77 @@ or narrow its authority. Never share the mount across trust groups.
188
203
 
189
204
  ## The kernel's periodic work
190
205
 
191
- The image's entrypoint starts sshd and nothing else. A container has no
192
- launchd and no systemd user manager, so in it nothing resumes the sessions
193
- that were lost when it last stopped, nothing runs the schedule tick, and
194
- nothing stops the agents in order when the runtime stops it: they are killed
195
- with the container and read `lost`.
196
-
197
- `oats host run`
198
- ([desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)) is the
199
- kernel command that does those three things in one foreground process. The
200
- image's pinned OATS does not have it, and the image does not run it. An operator can run it by hand in a
201
- container whose OATS has it, and the entrypoint of a derived image can end
202
- in it. What such an entrypoint has to respect:
203
-
204
- - **`oats host run` is the process the runtime's signal must reach and
205
- wait for.** Under `tini -g` that is tini's direct child: start sshd in the
206
- background, then `exec oats host run`. `tini -g` signals its child's
207
- process group; the OATS tmux server and the harnesses under it are in
208
- sessions of their own, outside that group, so they run until `oats host
209
- run` stops them. Measured with tini 0.19.0 and tmux 3.3a.
210
- - **The runtime's stop timeout must be longer than the stop.** On SIGTERM
211
- `oats host run` waits for a tick that is running, lists the instances and
212
- gives each harness `--stop-grace` seconds (default 20). Docker's default
213
- stop timeout is 10 seconds.
214
- - **It does not supervise sshd.** If sshd ends while it runs, the agents and
215
- the tick go on and the operator's route is gone.
216
- - **The tmux server a resume starts gets its environment**, its `PATH`
217
- included.
218
-
219
- It ticks the deployments the container's host schedule registry lists. To
220
- register one where no timer can be installed:
206
+ A container has no launchd and no systemd user manager, so no timer runs
207
+ the kernel's periodic work in it. The image's entrypoint does: it starts
208
+ sshd in the background and then runs `oats host run`
209
+ ([desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)), one
210
+ foreground process that lasts as long as the container.
211
+
212
+ - **At start** it runs the resume sweep once, so the sessions that were lost
213
+ when the container last stopped are started again
214
+ ([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown)).
215
+ Then, at second 0 of every minute, it runs the schedule tick for the
216
+ deployments the container's host schedule registry lists and lists the
217
+ instances. With no deployment registered it ticks nothing and says so.
218
+ - **On the runtime's SIGTERM** (`docker stop`, `docker restart`, a Compose
219
+ `down` or a recreate) it starts no further minute, waits for a tick that
220
+ is running, and stops every running agent side by side: SIGTERM to the
221
+ harness and a wait of 20 seconds, never escalated. Each home's stop record
222
+ says it was stopped with the host, so the home reads `lost` and the next
223
+ start's sweep resumes it. Then it exits 0 and the container ends.
224
+ - **Its progress** is one line per event on standard error, beside sshd's
225
+ log, in `docker logs`.
226
+
227
+ What the image's files fix for that:
228
+
229
+ - **`oats host run` is tini's direct child**, the process the runtime's
230
+ signal reaches and the container waits for: the entrypoint's last line is
231
+ `exec oats host run`, after sshd is started in the background. `tini -g`
232
+ signals its child's process group; the OATS tmux server and the harnesses
233
+ under it are in sessions of their own, outside that group, so they run
234
+ until `oats host run` stops them. Measured in `oats-agent:o1-local` with
235
+ tini 0.19.0 and tmux 3.3a: on `docker stop` both members of the group
236
+ received the TERM, and two seconds later the tmux server and its pane were
237
+ alive and the pane had received nothing.
238
+ - **`stop_grace_period: 45s`** in the Compose service. Docker's default is
239
+ 10 seconds, shorter than the 20 seconds each harness is given; a container
240
+ killed at the timeout leaves agents that were not stopped in order. A
241
+ platform that does not read the Compose file needs the same stop timeout
242
+ in its container spec.
243
+ - **A healthcheck on sshd.** `oats host run` does not supervise sshd: if
244
+ sshd ends, the agents and the tick go on and the operator's route is gone.
245
+ The service's healthcheck opens `127.0.0.1:2222` every 30 seconds (5
246
+ second timeout, 3 retries, 10 second start period), so the container then
247
+ reads `unhealthy`. Docker does not restart a container for being
248
+ unhealthy. Read it and restart the container; the stop is the ordered one
249
+ above, and the next start resumes the agents:
250
+
251
+ ```sh
252
+ docker inspect --format '{{.State.Health.Status}}' "oats-agent-${TEAM}"
253
+ docker restart "oats-agent-${TEAM}"
254
+ ```
255
+
256
+ - **The tmux server a resume starts gets the entrypoint's environment**, its
257
+ `PATH` and the nss_wrapper mapping included.
258
+
259
+ `oats host run` refuses to start while another one holds the container's
260
+ lock (`E_HOST_RUN_BUSY`); the container then exits 1 and the restart policy
261
+ starts it again. A lock left by an earlier run of the container is taken
262
+ over.
263
+
264
+ The schedule tick covers only registered deployments. Register the
265
+ deployment once, after `server connect`
266
+ ([OATS over SSH](#oats-over-ssh)):
221
267
 
222
268
  ```sh
223
- oats schedule host install --register-only --dir /state/deploy
269
+ oats schedule host install --register-only --server team-agent
224
270
  ```
225
271
 
226
- ([schedules.md](schedules.md#without-a-host-timer)). Plain `host install`
227
- fails in a container after registering, since there is no systemd user
228
- manager. Over the route (`--server team-agent`) the option is refused
229
- (`E_REMOTE_INCOMPATIBLE`, nothing sent) unless the container's OATS
230
- advertises `schedule-host-register-only`; the image's pin does not.
272
+ or, in the container, `oats schedule host install --register-only --dir
273
+ /state/deploy` ([schedules.md](schedules.md#without-a-host-timer)). Plain
274
+ `host install` fails in a container after registering, since there is no
275
+ systemd user manager. The registry is in `/state/home`, so it persists
276
+ across container runs.
231
277
 
232
278
  ## Acceptance and evidence
233
279
 
@@ -261,7 +307,9 @@ variables. It resolves `AGENT_IMAGE` independently and requires that image's
261
307
  ID, reference and start command, and its complete environment (printing only
262
308
  names of differing variables). Other comparisons include supplementary
263
309
  groups, namespace overrides, sysctls, published ports, resolver overrides
264
- and the single network/address. The OCI runtime must match the daemon's
310
+ and the single network/address. The stop timeout must be 45 seconds and the
311
+ healthcheck the service file's, so a container made before either was set
312
+ is refused until it is recreated. The OCI runtime must match the daemon's
265
313
  independently read default; shared memory stays at Docker's 64 MiB default,
266
314
  the OOM killer stays enabled, and device cgroup rules stay empty. The total
267
315
  memory-plus-swap setting is absent or Docker's default of twice the memory
@@ -285,7 +333,8 @@ checks. Record target evidence separately from local evidence. Container
285
333
  startup and a local preview do not establish two running agents.
286
334
 
287
335
  `test/agent-container.test.mjs` pins the image, Compose and SSH security
288
- settings and rejects weakened inspect fixtures. The SSH guard requires flat
336
+ settings and the entrypoint's last two lines, and rejects weakened inspect
337
+ fixtures. The SSH guard requires flat
289
338
  `Keyword value` lines and refuses duplicate keywords, `Match`/`Include`,
290
339
  equals-delimited keywords and quoted keywords. Follow the repository's
291
340
  local check limits; full suites run in CI.
package/docs/desktop.md CHANGED
@@ -735,7 +735,7 @@ deployment. Details are in
735
735
 
736
736
  Open **Automations › Schedules** in the selected workspace (the sidebar's
737
737
  **Automations**, or ⌘3 / Ctrl+3) to launch a new agent on a cron,
738
- wake an existing agent with a message, or harvest its knowledge. **Schedule…**
738
+ wake an existing agent with a message, or run a provider operation on it. **Schedule…**
739
739
  on a Soul roster card preselects that soul. Choose the task or message, repeat
740
740
  pattern and time zone; new agent jobs also offer harness, model, permissions
741
741
  and session backend. The list shows the next run, last observed outcome and
@@ -1096,7 +1096,7 @@ their name. It is decorative: the name beside it is authoritative. The letters
1096
1096
  come from the name without its package qualifier (what follows the last `/`
1097
1097
  or `--`), and from three words or more without its first (a namespace word like
1098
1098
  `oats`): the initials of the first two words, or a one-word name's first two
1099
- letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-harvester` KH and
1099
+ letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-maintainer` KM and
1100
1100
  `oats.aweb` OA. Two names can share a mark (`oats-expert` and
1101
1101
  `oats-operator-expert` are both OE); the name and the colour tell them apart.
1102
1102
 
@@ -1122,7 +1122,7 @@ unknown or unreported harness shows "?". Sources and licences are in
1122
1122
  stop, retire or start as a process in its own session.
1123
1123
  - Task text for spawns travels via an owner-only (0600) tempfile, never
1124
1124
  argv. A local start or restart launches only in the server-verified
1125
- instance home. A provider operation on an instance (its harvest included)
1125
+ instance home. A provider operation on an instance
1126
1126
  is addressed with `--home` to a home the server's roster reports, and one
1127
1127
  on a soul to a soul and agents root the server lists, never a path the
1128
1128
  caller names.
@@ -84,7 +84,7 @@ and the rules its tests pin.
84
84
  | `injects/` | the kernel and work-mode instruction blocks composed into every instance |
85
85
  | `skills/` | bootstrap skills shipped with the kernel |
86
86
  | `capabilities/` | this repository's own member capabilities, discovered at the member's latest state: `oats-desktop-ui`, `oats-workspace-experts`, and the copy of the engineering template (`oats-dispatcher`, `oats-engineering-expert`, `oats-developer`, `oats-build`, `oats-code-review`, `oats-maintainer`, `oats-landing-rules`; the release it came from in `TEMPLATE-RELEASE`, its MIT notice in `TEMPLATE-LICENSE`, the notices of the sources its build skills adapt in `THIRD-PARTY-NOTICES.md`) that the framework's own souls compose |
87
- | `mirrors/` | generated byte mirrors of the official packages' capabilities (for example `oats-okf*`, checked by `scripts/check-okf-mirror.mjs`): release-lane and test material, kept out of `capabilities/` so member discovery does not list them a second time; not shipped in the npm package |
87
+ | `mirrors/` | copies of the official packages' capabilities at their pinned tags: release-lane and test material, kept out of `capabilities/` so member discovery does not list them a second time; not shipped in the npm package. The three OKF mirrors (`oats-okf*`) are generated by `scripts/check-okf-mirror.mjs` and checked byte for byte against `scripts/okf-source-inventory.json`; the other seven (`oats-aweb`, `oats-aweb-tasks`, `oats-folio`, `oats-library`, `oats-jira`, `oats-linear`, `oats-authoring`) are copied from their tags by hand and checked for their version only, until every mirror has that check (oats-project/oats#1848) |
88
88
  | `oats-package/` | the `oats.framework` package |
89
89
  | `souls/` | this repository's own souls (a workspace member) |
90
90
  | `docs/` | the reference pages, schemas, design records and release notes |
@@ -40,8 +40,8 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.8.0
44
- oats.aweb: v1.37.0
43
+ oats.okf: v6.0.2
44
+ oats.aweb: v1.39.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -86,13 +86,14 @@ operations in full.
86
86
  | `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
87
87
 
88
88
  - **`oats.okf`** consults the soul's external OKF bases, keeps instance
89
- knowledge, and teaches the harvest duty in its IMPORTANT inject block and
89
+ knowledge, and teaches the duty to propose in its IMPORTANT inject block and
90
90
  compulsory `okf-propose` skill, not the task briefing. Eligible instances
91
- propose durable claims at finished tasks or PR hand-overs by directly
92
- spawning `oats.okf/knowledge-harvester`. The
93
- soul-only `knowledge: { harvest: off }` forbids harvest while retaining
94
- consultation. No host switch or automatic transcript/retire capture remains;
95
- `knowledge-maintainer` reviews the resulting Git PRs.
91
+ propose durable claims at their knowledge checkpoints (a finished task, a PR
92
+ handed over) themselves, with `oats okf propose`, as one pull request each;
93
+ no worker is spawned. The soul-only `knowledge: { harvest: off }` gives no
94
+ duty to propose while retaining consultation. No host switch or automatic
95
+ transcript/retire capture remains; `knowledge-maintainer` reviews the
96
+ resulting Git PRs.
96
97
  - **`oats.aweb-tasks`** (in the `oats.aweb` package from 1.31.0) fills the
97
98
  tasks slot with aweb tasks, acting as the instance's own `oats.aweb`
98
99
  identity in its default team. **An existing workspace opts in** by pinning
@@ -37,7 +37,7 @@ A lesson is kept when both answers are yes:
37
37
  ## How learning flows
38
38
 
39
39
  1. **Instances work and capture evidence.** Each one keeps notes on what it decided and discovered.
40
- 2. **An independent harvester judges what is worth keeping,** at set moments such as a pull request handed over or a task finished.
40
+ 2. **Each instance proposes what is worth keeping,** at set moments such as a pull request handed over or a task finished, judging its own notes against the knowledge base's bar.
41
41
  3. **The proposal is validated and delivered** through the knowledge base's acceptance process. For a Git-backed knowledge base that is a pull request, reviewed by a knowledge maintainer agent or a person.
42
42
  4. **Future instances consult the accepted result.**
43
43
 
@@ -68,5 +68,5 @@ A knowledge capability can organise knowledge per soul, per topic or per project
68
68
 
69
69
  ## Learn more
70
70
 
71
- - [Knowledge, instances and evolving expertise](knowledge-theory.md): the full model, including long-running instances, harvesting, maintenance, hand-offs and cloning.
71
+ - [Knowledge, instances and evolving expertise](knowledge-theory.md): the full model, including long-running instances, proposing knowledge, maintenance, hand-offs and cloning.
72
72
  - [Knowledge operations](knowledge.md): how the knowledge capability is set up and run.
@@ -64,7 +64,7 @@ The reference model accepts:
64
64
  - **Review and process patterns:** verified judgment that code alone does not communicate.
65
65
  - **Maintained slow state:** a dated interpretation of an area that orients future work.
66
66
 
67
- Human-accepted decisions pass the promotion bar by construction: preserve their meaning, scope and acceptance evidence rather than having a harvester re-judge the person. Confidentiality, provenance and duplication checks still apply.
67
+ Human-accepted decisions pass the promotion bar by construction: preserve their meaning, scope and acceptance evidence rather than having anyone re-judge the person. Confidentiality, provenance and duplication checks still apply.
68
68
 
69
69
  ### Keep the larger picture, not a second issue tracker
70
70
 
@@ -84,7 +84,7 @@ It needs a clear scope, a responsible maintenance process, an as-of date and an
84
84
  | Current investigation, provisional reasoning and next action | Instance context and state |
85
85
  | Raw records and notes awaiting judgment | Evidence, not accepted knowledge |
86
86
 
87
- A bare sequence of commands belongs in a skill; if an insight already has an authoritative home, point to it. Exclude secrets, improperly disclosed private material, personal data about people outside the team (clients, correspondents, any other third party), wholesale copies of third-party messages, tool noise and ordinary task residue; for the full rule and what enforces it, see [What a harvest leaves out](knowledge.md#what-a-harvest-leaves-out). If code, a test or a clearer contract can eliminate a recurring problem, fix it instead of writing it down.
87
+ A bare sequence of commands belongs in a skill; if an insight already has an authoritative home, point to it. Exclude secrets, improperly disclosed private material, personal data about people outside the team (clients, correspondents, any other third party), wholesale copies of third-party messages, tool noise and ordinary task residue; for the full rule and what enforces it, see [What a proposal leaves out](knowledge.md#what-a-proposal-leaves-out). If code, a test or a clearer contract can eliminate a recurring problem, fix it instead of writing it down.
88
88
 
89
89
  "Invariant across incarnations" means useful beyond its author, not true forever. Date and scope contingent claims, and supersede changed decisions explicitly rather than leaving contradictory truths or erasing their history.
90
90
 
@@ -102,12 +102,12 @@ A team's chosen knowledge base
102
102
  The layout is illustrative, not a kernel schema.
103
103
 
104
104
  - Instances of a soul consult its accepted expertise and relevant shared material.
105
- - Their harvests have explicit destinations; task context is not published wholesale.
105
+ - Their proposals have explicit destinations; task context is not published wholesale.
106
106
  - A claim has one canonical home; other readers use references rather than copies.
107
107
  - A public soul's publisher does not become the default recipient of an adopter's private learning.
108
108
  - Knowledge identity and lifetime do not depend on one instance or on a changeable display name.
109
109
 
110
- In the reference model, **owns is harvest routing**, not authorship, an access right or a duty to keep the base honest. **Reads is context selection**, not an access list; repository or service access still governs what can be read. Centralization simplifies where a harvest goes; it does not remove the need for judgment, deduplication, freshness or acceptance.
110
+ In the reference model, **owns is proposal routing**, not authorship, an access right or a duty to keep the base honest. **Reads is context selection**, not an access list; repository or service access still governs what can be read. Centralization simplifies where a proposal goes; it does not remove the need for judgment, deduplication, freshness or acceptance.
111
111
 
112
112
  ## Per-soul knowledge can evolve
113
113
 
@@ -146,22 +146,22 @@ A kernel decision may first land with the overall expert because that instance i
146
146
 
147
147
  > Would we deliberately want future instances to start with this narrower charter, skill set and reading context?
148
148
 
149
- A busy two weeks or a large set of notes is not enough; widening or keeping the existing soul may be right. Harvesters supply evidence and maintenance can propose changes, but a person accepts structural change: souls do not split themselves. Drafting a new soul is a skill used in a maintenance proposal, not a separate agent's job.
149
+ A busy two weeks or a large set of notes is not enough; widening or keeping the existing soul may be right. Proposals supply evidence and maintenance can propose changes, but a person accepts structural change: souls do not split themselves. Drafting a new soul is a skill used in a maintenance proposal, not a separate agent's job.
150
150
 
151
151
  ### Maintenance is a responsibility, not a compulsory background agent
152
152
 
153
153
  | Responsibility | Focus |
154
154
  |---|---|
155
- | Harvesting | What an instance's evidence contributes to accepted knowledge |
155
+ | Proposing | What an instance's evidence contributes to accepted knowledge |
156
156
  | Maintenance | Consistency, freshness, structure, ownership and declarations across the base |
157
157
 
158
- In the default capability, the `knowledge-harvester` package soul harvests and the `knowledge-maintainer` package soul maintains a base by reviewing the harvester's proposals. A human can perform maintenance instead; automation is optional, not a prerequisite for per-soul knowledge. A maintainer never silently accepts its own structural proposal or supersedes a human-accepted decision.
158
+ In the default capability, each working instance with a duty to propose proposes its own knowledge, and the `knowledge-maintainer` package soul maintains a base by reviewing those proposals. A human can perform maintenance instead; automation is optional, not a prerequisite for per-soul knowledge. A maintainer never silently accepts its own structural proposal or supersedes a human-accepted decision.
159
159
 
160
160
  Evidence of what instances actually used, such as their purpose, skills and knowledge consulted, can inform these proposals. It is operational evidence, not knowledge or a copy of private transcripts.
161
161
 
162
162
  ### Changing structure must preserve running work
163
163
 
164
- A knowledge move or soul split must account for references, pending harvests and existing instances:
164
+ A knowledge move or soul split must account for references, pending proposals and existing instances:
165
165
 
166
166
  - Update ownership and reading declarations in the same reviewed change.
167
167
  - Preserve a single canonical home and the provenance of claims.
@@ -210,27 +210,29 @@ The kernel supplies the common boundary; it must not hide one mandatory knowledg
210
210
  | Source, soul and instance identity | Knowledge organization and destination semantics |
211
211
  | Configuration resolution and declared requirements | Storage, retrieval and reading context |
212
212
  | Selected resources, exactly locked | Capture conventions and evidence selection |
213
- | Lifecycle and invocation context, and provenance | Judgment, harvesting and maintenance where used |
213
+ | Lifecycle and invocation context, and provenance | Judgment, proposing and maintenance where used |
214
214
  | Safe helper and job execution when required | Proposals, delivery, acceptance and recovery policies |
215
215
  | Resource integrity and truthful outcomes | Its complete runtime instructions, skills and tools |
216
216
 
217
- A knowledge capability is more than a storage adapter under a kernel-owned judge. The kernel does not require OKF, a node taxonomy, particular memory filenames, Git publication, a harvester or a maintainer. Alternative models must not weaken framework safety, repository governance, secret handling or declared authority, and a capability rejects incompatible requirements rather than quietly substituting another provider or destination. Messaging and tasks follow the same principle: common contracts, independently chosen implementations.
217
+ A knowledge capability is more than a storage adapter under a kernel-owned judge. The kernel does not require OKF, a node taxonomy, particular memory filenames, Git publication, a proposal flow or a maintainer. Alternative models must not weaken framework safety, repository governance, secret handling or declared authority, and a capability rejects incompatible requirements rather than quietly substituting another provider or destination. Messaging and tasks follow the same principle: common contracts, independently chosen implementations.
218
218
 
219
219
  ## How the default OKF capability works
220
220
 
221
- `oats.okf` keeps accepted expertise as Markdown concepts with metadata, indexes and history in external knowledge bases. Its runtime owns bindings, consultation, evidence custody, harvest execution and delivery.
221
+ `oats.okf` keeps accepted expertise as Markdown concepts with metadata, indexes and history in external knowledge bases. Its runtime owns bindings, consultation, the checks on a proposal and its delivery.
222
222
 
223
223
  1. A working instance consults the accepted state of its soul's bases remotely with `oats okf bases`, `index`, `cat`, `ls`, `links` and `search`; no knowledge is copied into its home. It captures observations in its own instance knowledge without self-censoring against the promotion bar.
224
- 2. A `knowledge-harvester` instance receives frozen evidence with provenance. It does not borrow the source's worktree or identity, and the source may already be retired.
225
- 3. The harvester judges additions, merges, supersessions and exclusions by the reference doctrine and delivers only through the capability: a pull request on a Git base.
224
+ 2. At each knowledge checkpoint, an instance with a duty to propose judges its own durable, non-duplicate claims (additions, merges, supersessions and exclusions) by the reference doctrine, and proposes them with `oats okf propose`. No worker is spawned and nobody waits for the proposal.
225
+ 3. The capability checks the proposal's ownership, scope and screening before anything leaves the host, and delivers it only as a pull request on a Git base, with its provenance.
226
226
  4. A `knowledge-maintainer` instance reviews that pull request and merges, amends, requests changes, closes, or escalates to a human.
227
227
  5. Accepted learning becomes available to later consultation; it is not automatically in every instance's active context.
228
228
 
229
+ The reference doctrine's independent harvester ([judgment](knowledge-reference/harvester.md)) remains a pattern a capability may choose. `oats.okf` 6 chose differently: the instance proposes its own claims, and the maintainer's review of each pull request is where independence lives.
230
+
229
231
  Directory bases use their own recoverable publication mechanism. Receipts state what actually happened: capture, judgment, delivery and acceptance are different facts, and directory publication does not prove human review. The [operational guide](knowledge.md) describes commands and constraints.
230
232
 
231
233
  ## Reusing working understanding: context handoffs and cloning
232
234
 
233
- Harvesting preserves individual lessons, not the combined working picture that makes a long-running instance effective. A handoff or clone carries selected references, verified observations and labeled provisional reasoning; that is not a knowledge store, and copying it promotes nothing.
235
+ Proposing knowledge preserves individual lessons, not the combined working picture that makes a long-running instance effective. A handoff or clone carries selected references, verified observations and labeled provisional reasoning; that is not a knowledge store, and copying it promotes nothing.
234
236
 
235
237
  Cloning exists as the official `oats.cloning` package ([souls and instances](souls-and-instances.md#cloning-an-instance)). A clone is a new instance of the source's soul with its own identity, credentials and ownership. What it carries is a curated brief written by a short-lived cloner for the new goal: what was re-verified, with its evidence; decisions and their reasons; working understanding marked provisional; open threads and who owns them; and where to look, with transcript turn ids as citations. The cloner leaves secrets out of the brief, a pattern-based redaction pass catches the common forms that slip through, and the brief is attached to the clone as a 0600 file, never placed in its task text. A clone does not carry the raw transcript, the source's `notes/`, the content of its work tree or its uncommitted changes (a worktree clone starts from the source's committed branch, the soul's default or a requested ref), or its commitments: those stay with the source unless the brief says they were handed over. Inherited material is not new evidence; the clone records it in its own notes only after re-verifying it.
236
238
 
@@ -238,7 +240,7 @@ Cloning exists as the official `oats.cloning` package ([souls and instances](sou
238
240
 
239
241
  The model's settled positions are those above: short- and long-running instances are both legitimate; the default is centralized, per-soul knowledge open to reviewed structural evolution; capabilities own their model and runtime behavior; the doctrine preserves expertise, not code descriptions or task residue; and structural change preserves provenance and running work. These are not CLI flags or configuration schemas.
240
242
 
241
- The default OKF capability implements consultation, capture, independent harvest and maintainer review; it does not provide automatic per-soul provisioning, a co-located profile, automatic speciation, redirects or context cloning. Context cloning is a separate package, `oats.cloning`, not part of the knowledge capability. Proving the kernel's flexibility needs a genuinely different organization and learning model, not only Git and directory storage within OKF. Updating this document does not migrate existing deployments.
243
+ The default OKF capability implements consultation, capture, the instance's own proposal and maintainer review; it does not provide automatic per-soul provisioning, a co-located profile, automatic speciation, redirects or context cloning. Context cloning is a separate package, `oats.cloning`, not part of the knowledge capability. Proving the kernel's flexibility needs a genuinely different organization and learning model, not only Git and directory storage within OKF. Updating this document does not migrate existing deployments.
242
244
 
243
245
  ## Related documentation
244
246