@awebai/oats 0.69.14 → 0.69.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +79 -18
  3. package/docs/capabilities.md +57 -14
  4. package/docs/container.md +111 -17
  5. package/docs/desktop-cli-api.md +215 -19
  6. package/docs/desktop.md +3 -3
  7. package/docs/execution-targets.md +15 -3
  8. package/docs/first-team.md +4 -3
  9. package/docs/implementation.md +19 -9
  10. package/docs/integrations.md +9 -8
  11. package/docs/knowledge-and-learning.md +2 -2
  12. package/docs/knowledge-theory.md +17 -15
  13. package/docs/knowledge.md +202 -179
  14. package/docs/official-catalog.md +4 -4
  15. package/docs/packages.md +13 -13
  16. package/docs/release-notes/v0.69.15.md +444 -0
  17. package/docs/release-notes/v0.69.16.md +169 -0
  18. package/docs/schedules.md +168 -34
  19. package/docs/servers.md +64 -3
  20. package/docs/souls-and-instances.md +100 -19
  21. package/docs/upgrading.md +26 -6
  22. package/docs/workspaces.md +2 -2
  23. package/lib/claim.mjs +2 -3
  24. package/lib/command-flags.mjs +4 -2
  25. package/lib/core.mjs +215 -72
  26. package/lib/dir-lock.mjs +17 -0
  27. package/lib/errors.mjs +2 -1
  28. package/lib/host-run.mjs +218 -0
  29. package/lib/host-stop-child.mjs +21 -0
  30. package/lib/instance-git.mjs +32 -6
  31. package/lib/instance-lifecycle.mjs +4 -3
  32. package/lib/instance-listing.mjs +35 -6
  33. package/lib/kernel-features.mjs +4 -1
  34. package/lib/read-call.mjs +1 -1
  35. package/lib/remote.mjs +17 -14
  36. package/lib/schedule.mjs +237 -20
  37. package/lib/servers.mjs +83 -5
  38. package/lib/session-end.mjs +28 -8
  39. package/lib/session-resume.mjs +10 -18
  40. package/lib/session-seen.mjs +4 -64
  41. package/lib/status-words.mjs +11 -4
  42. package/lib/system-tools.mjs +1 -36
  43. package/lib/worktree-hooks.mjs +6 -175
  44. package/lib/worktree.mjs +19 -10
  45. package/package-catalog.json +3 -3
  46. package/package.json +4 -1
  47. package/packages/record/README.md +56 -21
  48. package/packages/record/docs/capture-service.md +8 -5
  49. package/packages/record/docs/turn-record-sot.md +9 -0
  50. package/packages/record/lib/capture-health.mjs +6 -4
  51. package/packages/record/lib/capture-lock.mjs +31 -27
  52. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  53. package/packages/record/lib/capture-scratch.mjs +2 -1
  54. package/packages/record/lib/derived-state.mjs +4 -2
  55. package/packages/record/lib/index-db.mjs +4 -2
  56. package/packages/record/lib/lock-holder.mjs +21 -0
  57. package/packages/record/lib/private-files.mjs +18 -0
  58. package/packages/record/lib/process-identity.mjs +310 -0
  59. package/packages/record/lib/store.mjs +31 -25
  60. package/skills/oats-getting-started/SKILL.md +9 -6
@@ -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.1
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