@awebai/oats 0.69.12 → 0.69.15

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.
Files changed (92) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +254 -201
  3. package/docs/capabilities.md +58 -13
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +291 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +590 -55
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +84 -9
  11. package/docs/first-team.md +4 -3
  12. package/docs/implementation.md +99 -32
  13. package/docs/integrations.md +3 -2
  14. package/docs/knowledge-and-learning.md +72 -0
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +39 -5
  17. package/docs/packages.md +93 -14
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.13.md +767 -0
  20. package/docs/release-notes/v0.69.14.md +83 -0
  21. package/docs/release-notes/v0.69.15.md +444 -0
  22. package/docs/schedules.md +159 -5
  23. package/docs/servers.md +241 -7
  24. package/docs/souls-and-instances.md +223 -14
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +36 -5
  27. package/docs/workspaces.md +31 -5
  28. package/lib/claim.mjs +20 -5
  29. package/lib/command-flags.mjs +240 -0
  30. package/lib/core.mjs +1004 -633
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +145 -33
  33. package/lib/errors.mjs +3 -2
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/host-run.mjs +218 -0
  36. package/lib/host-stop-child.mjs +21 -0
  37. package/lib/hot-reads.mjs +4 -3
  38. package/lib/instance-events.mjs +28 -6
  39. package/lib/instance-git.mjs +165 -14
  40. package/lib/instance-inspect.mjs +6 -1
  41. package/lib/instance-lifecycle.mjs +4 -3
  42. package/lib/instance-listing.mjs +114 -43
  43. package/lib/instance-resolution.mjs +56 -3
  44. package/lib/instance-upgrade.mjs +16 -20
  45. package/lib/kernel-features.mjs +4 -1
  46. package/lib/launch-env-exec.sh +7 -0
  47. package/lib/launch-env.mjs +74 -0
  48. package/lib/launch-preference.mjs +19 -12
  49. package/lib/member-clone.mjs +7 -1
  50. package/lib/packages.mjs +74 -2
  51. package/lib/read-call.mjs +4 -1
  52. package/lib/reader.mjs +3 -2
  53. package/lib/refused-text.mjs +3 -2
  54. package/lib/remote.mjs +126 -31
  55. package/lib/retained-after-retire.mjs +2 -7
  56. package/lib/retire-git-forms.mjs +41 -0
  57. package/lib/retire-incomplete.mjs +96 -0
  58. package/lib/schedule.mjs +239 -21
  59. package/lib/servers.mjs +161 -28
  60. package/lib/session-end.mjs +28 -8
  61. package/lib/session-resume.mjs +63 -56
  62. package/lib/session-seen.mjs +3 -14
  63. package/lib/start-env.mjs +13 -7
  64. package/lib/status-words.mjs +11 -4
  65. package/lib/system-tools.mjs +1 -36
  66. package/lib/teams.mjs +11 -4
  67. package/lib/upgrade-state.mjs +13 -2
  68. package/lib/worktree-hooks.mjs +6 -175
  69. package/lib/worktree.mjs +68 -10
  70. package/package-catalog.json +1 -1
  71. package/package.json +5 -1
  72. package/packages/client/instance-lifecycle.mjs +1 -1
  73. package/packages/client/lifecycle-contract.mjs +3 -1
  74. package/packages/client/session-resume-cli.mjs +2 -1
  75. package/packages/client/session-start.mjs +10 -7
  76. package/packages/client/workspace-cli.mjs +5 -1
  77. package/packages/record/README.md +56 -21
  78. package/packages/record/docs/capture-service.md +8 -5
  79. package/packages/record/docs/turn-record-sot.md +9 -0
  80. package/packages/record/lib/capture-health.mjs +6 -4
  81. package/packages/record/lib/capture-lock.mjs +31 -27
  82. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  83. package/packages/record/lib/capture-scratch.mjs +2 -1
  84. package/packages/record/lib/derived-state.mjs +4 -2
  85. package/packages/record/lib/index-db.mjs +4 -2
  86. package/packages/record/lib/lock-holder.mjs +21 -0
  87. package/packages/record/lib/private-files.mjs +18 -0
  88. package/packages/record/lib/process-identity.mjs +310 -0
  89. package/packages/record/lib/store.mjs +31 -25
  90. package/share/oats-login-receive +204 -0
  91. package/skills/oats-getting-started/SKILL.md +93 -26
  92. package/lib/tmux-config.mjs +0 -35
@@ -0,0 +1,72 @@
1
+ # Knowledge and learning
2
+
3
+ How OATS agents keep what they learn, so that every new instance of a soul starts wiser than the last. This page describes our default approach, implemented by the official `oats.okf` knowledge capability. Other knowledge capabilities can adopt it, adapt it or work differently.
4
+
5
+ ## Four kinds of value, four places
6
+
7
+ An experienced agent carries four kinds of value, and each belongs in a different place:
8
+
9
+ - **Reusable procedures and know-how** belong in skills and capabilities. How to run a release is a skill.
10
+ - **Lasting judgment and the larger picture** belong in the knowledge base. Why a release must verify the installed artifact is a lesson.
11
+ - **A detailed understanding of the current problem** belongs in the instance's working context.
12
+ - **Unfinished work and next steps** belong in the instance's own state. Which release check is still running is state.
13
+
14
+ Only the second goes into the knowledge base.
15
+
16
+ ## Keep expertise, not a second description of the code
17
+
18
+ > **Knowledge is what makes an expert an expert in a subject or project. It is not a description of what lives in the code.**
19
+
20
+ A lesson is kept when both answers are yes:
21
+
22
+ 1. Would a future instance of this soul act differently for knowing it?
23
+ 2. Is it something the instance could not learn by simply reading the repository?
24
+
25
+ - **Kept:** decisions and their reasons, rejected alternatives, discoveries, research conclusions, design inspiration, and awareness of the larger situation.
26
+ - **Not kept:** code structure, file maps, ordinary task progress, or anything the repository already makes clear. A second copy of what the code says only grows stale.
27
+
28
+ ## Souls divide the knowledge base
29
+
30
+ - The knowledge base is divided into areas, such as the release process, the kernel or the design system.
31
+ - Each area has exactly one owning soul. Its instances' lessons are proposed to that area, and other souls hand lessons for it to its owner. Keeping the base consistent is maintenance, done by a knowledge maintainer or a person.
32
+ - Other souls read an area when their work touches it, and link to it rather than copying it.
33
+ - So every agent starts with a well-defined context: the area its soul owns, and the few it reads. Every area lives in one place, owned by one kind of agent.
34
+ - Each instance of a soul keeps its own working context and state for its own piece of work.
35
+ - Adopting someone else's published soul does not send your learning back to its publisher.
36
+
37
+ ## How learning flows
38
+
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.
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
+ 4. **Future instances consult the accepted result.**
43
+
44
+ Working instances never rewrite the accepted knowledge base directly. An open pull request is not yet accepted knowledge, and a delivery receipt does not prove that a person approved it or that another instance has read it.
45
+
46
+ ## Our default: oats.okf
47
+
48
+ - It uses **Open Knowledge Format**: readable Markdown concepts with metadata, links and history.
49
+ - A team shares its knowledge bases, one or more, divided among its souls as above.
50
+ - It needs explicit bindings and setup; not every step is automatic.
51
+
52
+ ## Your own way
53
+
54
+ OATS provides the contracts, and the knowledge capability decides how knowledge works. With the right capability you can, for example:
55
+
56
+ - let new instances inherit a soul's accumulated expertise;
57
+ - let instances of one soul develop their own specialisations from a shared foundation;
58
+ - let a long-running instance keep its working understanding across many tasks;
59
+ - turn selected learning into shared knowledge after review.
60
+
61
+ A knowledge capability can organise knowledge per soul, per topic or per project, centrally or next to the soul definitions, as long as it actually supports the arrangement you choose. Messaging and tasks work the same way: OATS provides the contracts, and you choose how your team works through them.
62
+
63
+ ## Expertise can evolve
64
+
65
+ - Souls can widen their scope, hand an area to a better-placed soul, merge, or split into more specialised souls.
66
+ - A deliberate split into new reusable specialisations is called **speciation**. A generalist that keeps handling UX work, for example, can give rise to a dedicated UX expert. The new expert owns the UX area, and the generalist consults it rather than duplicating it.
67
+ - These changes are proposed and reviewed. A busy period or a large pile of notes is not enough on its own, and no agent reshapes its own soul.
68
+
69
+ ## Learn more
70
+
71
+ - [Knowledge, instances and evolving expertise](knowledge-theory.md): the full model, including long-running instances, harvesting, maintenance, hand-offs and cloning.
72
+ - [Knowledge operations](knowledge.md): how the knowledge capability is set up and run.
@@ -73,10 +73,19 @@
73
73
  "additionalProperties": {
74
74
  "oneOf": [
75
75
  { "type": "string" },
76
- { "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } }
76
+ { "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
77
+ { "type": "object", "additionalProperties": false, "required": ["fromFile"], "properties": { "fromFile": { "type": "string", "pattern": "^/[^\\u0000]*$" } } }
77
78
  ]
78
79
  },
79
- "description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops."
80
+ "allOf": [{ "properties": {
81
+ "HOME": { "not": { "type": "object", "required": ["fromFile"] } },
82
+ "PATH": { "not": { "type": "object", "required": ["fromFile"] } },
83
+ "CLAUDE_CONFIG_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
84
+ "CODEX_HOME": { "not": { "type": "object", "required": ["fromFile"] } },
85
+ "PI_CODING_AGENT_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
86
+ "PI_CODING_AGENT_SESSION_DIR": { "not": { "type": "object", "required": ["fromFile"] } }
87
+ } }],
88
+ "description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops. {fromFile: /absolute/path} reads a regular UTF-8 file of at most 64 KiB (source bytes including a final newline) on the execution host at every start, stripping one trailing LF or CRLF. NUL, missing, unreadable or nonregular files refuse with E_LAUNCH_ENV_MISSING. Both reference kinds are redacted and recorded only as keyed digests. fromFile is for credential values; directory selectors require a literal or fromEnv."
80
89
  },
81
90
  "model": { "type": "string", "minLength": 1, "description": "Model for this configuration's harness; overrides the soul default when this configuration is selected." },
82
91
  "yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." },
@@ -9,10 +9,10 @@ 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.22.1` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert`, `oats-setup-expert` |
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
13
  | `oats.okf` | `v5.8.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.37.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
- | `oats.engineering` | `v1.18.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
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` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
@@ -21,12 +21,46 @@ or workspace membership alone does not make a package official.
21
21
  | `oats.machine` | `v0.1.1` | `oats.machine-care` | `steward`, `technician` |
22
22
 
23
23
  Each package lives in its own `awebai/oats-*` repository except
24
- `oats.framework`, whose payload root is `oats-package/` here. A capability id
25
- names the package that supplies it through the catalog's aliases, so
26
- `oats.developer: { from: package }` selects `oats.engineering`. This catalog ships with
24
+ `oats.framework`, whose payload root is `oats-package/` here. A capability
25
+ written `{ from: package }` resolves through the workspace's lock, to the one
26
+ locked package whose capability list holds it: `oats.developer: { from: package }`
27
+ selects `oats.engineering` when that package is pinned and synced. Two locked
28
+ packages providing the same capability are refused with `E_PACKAGE_MISSING`,
29
+ which names both. The catalog's `capabilities` map records which official
30
+ package ships each capability (and a renamed capability's current name:
31
+ `oas.okf` is `oats.okf`); the kernel reads it only to pick a standalone
32
+ deployment's package (the one that ships `oats.core`). This catalog ships with
27
33
  the CLI: an older installed CLI keeps its own copy, and a change here rewrites
28
34
  no lock and adds nothing to an existing workspace.
29
35
 
36
+ ## Coordination templates
37
+
38
+ OATS's coordination ships as templates, not packages: one for each way of
39
+ working, each in its own repository. An installed kernel's
40
+ copy of this catalog carries this section from the next kernel release; the
41
+ onboarding skills name the engineering template directly, so they work on an
42
+ older kernel too. A template is a
43
+ repository that a setup expert copies into a workspace's own capabilities and
44
+ adapts to the organisation by the repository's `ADAPTING.md`
45
+ (`/adapt-to-the-organisation`, in `oats.framework`); nobody pins it. Template
46
+ releases are tagged `template-v<version>`. Each copied capability records the
47
+ release it came from in its description, and the copy records it as a whole in
48
+ `capabilities/TEMPLATE-RELEASE`.
49
+
50
+ | Template | Latest release | Way of working |
51
+ | --- | --- | --- |
52
+ | `oats-project/oats-engineering-coordination` | `template-v3.0.1` | Work that lands as pull requests: a dispatcher, a lead for each effort that builds a change itself or sends developers, whoever builds it iterating with a fresh reviewer each round, and a maintainer where a lane needs one. |
53
+ | `oats-project/oats-research-coordination` | `template-v2.0.0` | Work that ends in a finding or a report: a dispatcher, a research lead for each question that researches a single small angle itself or sends a researcher for each, and a verifier briefed to disprove, which checks the lead's own claims too. A report lands when the person who asked accepts it. |
54
+ | `oats-project/oats-scientific-research-coordination` | `template-v2.0.0` | Studies that end in claims a person is accountable for: a dispatcher, a study lead for each study, an analyst for each arm of a locked protocol, fresh study reviewers for the methods, an independent check, leakage and citations, and a record steward that locks protocols and keeps the study records. A claim lands when the scientist accepts it; one that leaves the group needs a check that isn't LLM judgement. |
55
+
56
+ The package `oats.engineering` is frozen at `v1.18.0`. Its entry and its four
57
+ aliases stay, so existing pins keep resolving, and its repository,
58
+ `oats-project/oats-engineering`, gets no further releases. The engineering
59
+ template that replaces it lives in its own repository, above; a workspace that
60
+ pins the package moves to it by the template's `ADAPTING.md` and the "From
61
+ v1.18.0" steps in its CHANGELOG. Open: retiring the entry and moving the
62
+ aliases, a later decision once no workspace we know of pins it.
63
+
30
64
  ## Find and use packages
31
65
 
32
66
  - A workspace pins an official package by **bare version** in its
package/docs/packages.md CHANGED
@@ -28,7 +28,11 @@ A Git repository **contains** a package at `oats-package/`:
28
28
  ```
29
29
 
30
30
  `oats-package.json` must declare `package` and `capabilities` (a list of
31
- directories relative to the package root, each holding an `oats.json`). It may
31
+ directories relative to the package root, each holding an `oats.json`). The
32
+ `package` must equal the `packages:` key the package is pinned under: a
33
+ package is locked under its own id, and its souls are named after it
34
+ (`<package>/<soul>`). `sync` refuses a pin whose manifest names another id
35
+ (`E_PACKAGE_INTEGRITY { why: "package-id" }`, see [`oats sync`](#oats-sync--the-one-command-for-the-common-path)). It may
32
36
  also declare `souls`: soul directories the package ships, see
33
37
  [Package souls](#package-souls). A
34
38
  directory entry need not equal the capability's name
@@ -51,7 +55,7 @@ packages:
51
55
  - **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
52
56
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
57
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.8.0` or `oats-framework/v1.22.1`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.23.0`) and the payload path. An id
55
59
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
60
  a package outside the catalog"). The catalog is the reviewed official list
57
61
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +78,7 @@ members:
74
78
  - git:github.com/acme/agents
75
79
  - git:github.com/acme/platform
76
80
  packages:
77
- oats.framework: v1.22.1
81
+ oats.framework: v1.23.0
78
82
  oats.okf: v5.8.0
79
83
  oats.aweb: v1.37.0
80
84
  teams:
@@ -117,12 +121,29 @@ lock oats-lock.json
117
121
 
118
122
  1. discovers the workspace over the remotes and confirms every member;
119
123
  2. resolves each `packages:` entry to a commit (`observeRemote`), reads its
120
- manifests, computes the **integrity** (content digest of the package tree)
121
- and records `url`, `path`, `version`, `commit`, `integrity`, `capabilities`;
124
+ manifests, checks that `oats-package.json` names the `packages:` key it is
125
+ pinned under, computes the **integrity** (content digest of the package
126
+ tree) and records `url`, `path`, `version`, `commit`, `integrity`,
127
+ `capabilities`. A manifest naming another package is refused before
128
+ anything is written: `E_PACKAGE_INTEGRITY { why: "package-id", id,
129
+ manifestPackage, commit }`, whose message names the line to write instead:
130
+ - a catalog version whose named package is in the catalog: `<named>: <the
131
+ same version>`;
132
+ - a catalog version whose named package is not: `<named>:
133
+ git:<the catalog entry's repo>@<the resolved tag>` (no line when the
134
+ catalog entry reads another `path` than `oats-package/`, which a `git:`
135
+ pin cannot reach);
136
+ - a `git:` pin: `<named>: <the same git: value>`.
137
+
138
+ The other way out is a version of the key's package whose manifest names
139
+ that key;
122
140
  3. for an entry already locked at the same version/source/path: the commit must
123
141
  be unchanged (else `E_PACKAGE_INTEGRITY` — "the tag moved; a version string
124
- must change when its content does") and the integrity must match
125
- (`E_PACKAGE_INTEGRITY`);
142
+ must change when its content does"), the integrity must match
143
+ (`E_PACKAGE_INTEGRITY`), and the manifest must still name the key
144
+ (`why: "package-id"`, as in step 2: a lock an older kernel wrote under
145
+ another package's id is refused at the next sync; spawns from it keep
146
+ working until then);
126
147
  4. writes `oats-lock.json` and reports the diff. Entries dropped from
127
148
  `packages:` are dropped from the lock.
128
149
 
@@ -202,9 +223,12 @@ Member capabilities are trusted by membership; **a package is trusted by its
202
223
  declaration in the workspace's `packages:`**. People declare a package only
203
224
  when they trust it, so there is no second, per-version approval step. The lock is reproducibility, not approval: it pins
204
225
  the exact commit and the content integrity, a moved tag or drifted content is
205
- `E_PACKAGE_INTEGRITY`, and at spawn the lock's capability list must match what
206
- the package declares at the locked commit (`E_PACKAGE_INTEGRITY { why:
207
- "capabilities" }`).
226
+ `E_PACKAGE_INTEGRITY`, a package pinned under another package's id is
227
+ `E_PACKAGE_INTEGRITY { why: "package-id" }` at sync, and at spawn the lock's
228
+ capability list must match what the package declares at the locked commit
229
+ (`E_PACKAGE_INTEGRITY { why: "capabilities" }`) and the package tree there must
230
+ digest to the lock's `integrity`
231
+ ([The integrity check at spawn](#the-integrity-check-at-spawn)).
208
232
 
209
233
  ## Materialization from a package
210
234
 
@@ -217,6 +241,56 @@ against what the fetch reported; skills are copied to
217
241
  `packages:` and syncing affects **only new spawns**; `oats status` shows a
218
242
  running instance's package module as `moved` once the lock points elsewhere.
219
243
 
244
+ ### The integrity check at spawn
245
+
246
+ A spawn copies a package's capabilities only when the package is the content
247
+ the lock records. For each package the soul composes a capability from, the
248
+ kernel digests the package tree (the lock entry's `path`) at the lock's
249
+ `commit`, as `oats sync` does, and compares the digest with the lock's
250
+ `integrity`.
251
+
252
+ - **When.** After the soul is resolved and before the spawn writes anything:
253
+ no soul copy, no worktree, no instance home. `oats spawn --preview` makes
254
+ the same check. `oats instance upgrade` makes it for each package it moves
255
+ a module to.
256
+ - **The refusal** is `E_PACKAGE_INTEGRITY` with `details: {package, version,
257
+ commit, expected, actual}`: `expected` is the lock's `integrity`, `actual`
258
+ the digest of the tree as this computer reads it. The message names the
259
+ package, the commit and both digests. Two things produce it: a lock whose
260
+ `commit` and `integrity` describe different content (a hand edit, a bad
261
+ merge), which is fixed by restoring the lock; and a copy of the
262
+ package in this computer's remote cache that changed after it was fetched,
263
+ which is fixed by removing the cache (`$OATS_REMOTE_CACHE`, default
264
+ `~/.cache/oats/remotes`).
265
+ - **Once per package version and computer.** A tree that matched is recorded
266
+ under the remote cache, in `.verified/`, one file per (repository key,
267
+ commit, path, integrity). The record also holds the state of the cached
268
+ repository the tree was read from: every file under it, by path, size,
269
+ mode, inode, modification time and status-change time. A later spawn
270
+ believes a record only when each of its fields is the one asked for and the
271
+ cached repository is still in that state, and then digests nothing. Any
272
+ file added, removed, replaced or rewritten there (a later fetch of the same
273
+ repository included) makes the next spawn digest the tree again. Nothing
274
+ is recorded when the cached repository changed while the tree was read (the
275
+ first fetch of the package's files): the next spawn digests it again. With
276
+ a missing or unreadable record the tree is digested, and a cached
277
+ repository that reads objects from outside itself (a symbolic link, an
278
+ alternates file) is digested every time. A record older than 30 days is
279
+ removed when the cache is next pruned. The records are the kernel's own and
280
+ no contract: deleting them only costs the next spawn a digest.
281
+ - **What a record does not see.**
282
+ - A change to the cached repository that leaves every file's size, mode,
283
+ inode and both times as they were. That takes writing to the disk under
284
+ the filesystem, setting the clock back, or, on a filesystem that keeps
285
+ times to the second, rewriting a file in place to the same size within
286
+ the second it was last changed.
287
+ - A record written by whoever changed the cache: both live in the same
288
+ directory, so the cache is as trusted as the account that owns it.
289
+ - What Git reads outside the cached repository: its own configuration and
290
+ environment.
291
+ - A change made between the check and the copy of the modules a moment
292
+ later in the same spawn.
293
+
220
294
  ## Package souls
221
295
 
222
296
  A package may ship **souls** as well as capabilities. One pin in
@@ -273,7 +347,12 @@ oats-package/
273
347
  { id, version, commit, digest, path }` and the soul id `package:<id>#<soul>`;
274
348
  in `oats status` the soul is `moved` once the package pin moves.
275
349
  - **Disabled** by `oats-local.yaml` `souls.disabled` by its qualified or bare
276
- name (`E_SOUL_DISABLED` at spawn).
350
+ name (`E_SOUL_DISABLED` at spawn). An entry is matched by name only, so an
351
+ entry naming a soul that no longer exists fails open: after a pin's removal
352
+ or rename, the soul it was meant to keep off spawns again under its new
353
+ name. After removing or renaming a pin, or a soul it provided, run
354
+ `oats doctor` and fix what it reports, and check `souls.disabled` by hand: an
355
+ older kernel's doctor doesn't report such an entry.
277
356
  - **Trusted** as the package's capabilities are: declaring the package is the
278
357
  trust decision.
279
358
 
@@ -353,11 +432,11 @@ A soul that names one of the package's capabilities with
353
432
  "policy": "docs/official-catalog.md",
354
433
  "packages": {
355
434
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.8.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.22.1", "path": "oats-package" }
435
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.23.0", "path": "oats-package" }
357
436
  }
358
437
  }
359
438
  ```
360
439
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.22.1`
362
- resolves to tag `oats-framework/v1.22.1`. Resolving through the catalog never
440
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.23.0`
441
+ resolves to tag `oats-framework/v1.23.0`. Resolving through the catalog never
363
442
  advances a lock by itself: `oats sync` does, and says so.
@@ -480,7 +480,8 @@ always records `release.status: pending`.
480
480
  ## Releasing `oats.framework`
481
481
 
482
482
  The distribution package in `oats-package/` (`oats.core`, `oats.setup`,
483
- `oats.onboarding`, `oats.support`, `oats.knowledge-theory`) is not published
483
+ `oats.onboarding`, `oats.coordination-setup`, `oats.support`,
484
+ `oats.knowledge-theory`) is not published
484
485
  by `release.yml` or by this lane. A deployment takes it from this repository at the tag
485
486
  `oats-framework/v<version>`, through the catalog ref or its workspace pin. A
486
487
  skill changed under `oats-package/` therefore reaches deployments only when