@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 +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/release-notes/v0.69.17.md +49 -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 +19 -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/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
|
|
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
|
|
package/docs/capabilities.md
CHANGED
|
@@ -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
|
-
"
|
|
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,
|
|
7
|
-
|
|
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.
|
|
65
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
container
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
-
|
|
215
|
-
the
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
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 --
|
|
269
|
+
oats schedule host install --register-only --server team-agent
|
|
224
270
|
```
|
|
225
271
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
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
|
|
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
|
|
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
|
|
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-
|
|
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
|
|
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.
|
package/docs/implementation.md
CHANGED
|
@@ -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/` |
|
|
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 |
|
package/docs/integrations.md
CHANGED
|
@@ -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:
|
|
44
|
-
oats.aweb: v1.
|
|
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
|
|
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
|
|
92
|
-
|
|
93
|
-
soul-only `knowledge: { harvest: off }`
|
|
94
|
-
consultation. No host switch or automatic
|
|
95
|
-
`knowledge-maintainer` reviews the
|
|
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. **
|
|
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,
|
|
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.
|
package/docs/knowledge-theory.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
|
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,
|
|
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
|
|
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,
|
|
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
|
|
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,
|
|
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.
|
|
225
|
-
3. The
|
|
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
|
-
|
|
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,
|
|
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
|
|