@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.
- package/README.md +1 -1
- package/bin/oats.mjs +79 -18
- package/docs/capabilities.md +57 -14
- package/docs/container.md +111 -17
- package/docs/desktop-cli-api.md +215 -19
- package/docs/desktop.md +3 -3
- package/docs/execution-targets.md +15 -3
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +19 -9
- 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.15.md +444 -0
- package/docs/release-notes/v0.69.16.md +169 -0
- package/docs/schedules.md +168 -34
- package/docs/servers.md +64 -3
- package/docs/souls-and-instances.md +100 -19
- package/docs/upgrading.md +26 -6
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +2 -3
- package/lib/command-flags.mjs +4 -2
- package/lib/core.mjs +215 -72
- package/lib/dir-lock.mjs +17 -0
- package/lib/errors.mjs +2 -1
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/instance-git.mjs +32 -6
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +35 -6
- package/lib/kernel-features.mjs +4 -1
- package/lib/read-call.mjs +1 -1
- package/lib/remote.mjs +17 -14
- package/lib/schedule.mjs +237 -20
- package/lib/servers.mjs +83 -5
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +10 -18
- package/lib/session-seen.mjs +4 -64
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +19 -10
- package/package-catalog.json +3 -3
- package/package.json +4 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/skills/oats-getting-started/SKILL.md +9 -6
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.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
|
|
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
|
|