@awebai/oats 0.69.22 → 0.69.23
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/bin/oats.mjs +131 -23
- package/docs/capabilities.md +12 -2
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +878 -0
- package/docs/design/README.md +3 -0
- package/docs/desktop-cli-api.md +416 -72
- package/docs/desktop.md +60 -17
- package/docs/implementation.md +1 -1
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +117 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +51 -22
- package/docs/tui.md +4 -3
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +2 -2
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +39 -2
- package/lib/core.mjs +25 -14
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-lifecycle.mjs +19 -15
- package/lib/instance-listing.mjs +18 -10
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +4 -1
- package/lib/servers.mjs +123 -13
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/deployment-data.mjs +4 -2
- package/packages/client/deployment-panel.mjs +2 -1
- package/packages/client/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +4 -3
- package/packages/client/workspace-cli.mjs +13 -2
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
package/docs/desktop.md
CHANGED
|
@@ -1054,6 +1054,24 @@ starts, ends or its text changes, never as the age ticks over. In a split,
|
|
|
1054
1054
|
each group's row follows its own tab. The row goes as soon as the wait ends,
|
|
1055
1055
|
and it never shows for a stopped instance or a roster that is out of date.
|
|
1056
1056
|
|
|
1057
|
+
## An agent's mail
|
|
1058
|
+
|
|
1059
|
+
**Alt+M** (⌥⌘M on macOS), the palette's **Agent: mail** or **Mail** in
|
|
1060
|
+
Details' Messaging & Teams section opens the agent's own mail, received and
|
|
1061
|
+
sent, newest first, in a read-only sheet from the right. Each message says who
|
|
1062
|
+
it is from or to, its team when the agent is in more than one, its subject and
|
|
1063
|
+
its body as plain text attributed to its sender, and whether it was encrypted,
|
|
1064
|
+
is not read by the agent yet, is high priority, or its sender is not verified.
|
|
1065
|
+
**r** reads it again and **Older mail** reads further back; Esc closes it.
|
|
1066
|
+
|
|
1067
|
+
Reading it never acknowledges anything or marks anything read: the Desktop
|
|
1068
|
+
runs only the messaging layer's `messaging:mail` operation, when the sheet
|
|
1069
|
+
opens or you ask it to read again, never on its own. Nothing else on the screen
|
|
1070
|
+
says anything about an agent's mail. An agent whose messaging layer predates
|
|
1071
|
+
the operation says so, with what to do: stop it and upgrade it (`oats instance
|
|
1072
|
+
upgrade`), or start a new agent of its soul. The details are in
|
|
1073
|
+
[packages/desktop/docs/desktop-mail-sheet.md](../packages/desktop/docs/desktop-mail-sheet.md).
|
|
1074
|
+
|
|
1057
1075
|
## Copy from a terminal
|
|
1058
1076
|
|
|
1059
1077
|
Drag over an agent's output to select it, as in any terminal. The selection
|
|
@@ -1113,12 +1131,43 @@ error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
|
|
|
1113
1131
|
|
|
1114
1132
|
The sidebar lists a workspace's instances as a tree: a child sits one step
|
|
1115
1133
|
right of its parent, and related instances are grouped together, with a little
|
|
1116
|
-
space before the next group. The
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1134
|
+
space before the next group. The indent and that space show the tree.
|
|
1135
|
+
|
|
1136
|
+
The sidebar draws a line only for related work: an instance its host reports
|
|
1137
|
+
doing work related to its parent's, or to a sibling's. No flag, no line, on
|
|
1138
|
+
every host. Where it draws one, it looks as it did before the Desktop's
|
|
1139
|
+
redesign:
|
|
1140
|
+
|
|
1141
|
+
- **A solid line** joins a parent to a child whose work is related to its
|
|
1142
|
+
parent's: the parent's line leaves its dot and ends in a rounded elbow at
|
|
1143
|
+
the child's. Any other child keeps its indent with no line, and its
|
|
1144
|
+
parent's line doesn't reach it.
|
|
1145
|
+
- **A dotted line** joins the dots of two top-level instances of one group
|
|
1146
|
+
when the one linked as a sibling of the other reports related work. The
|
|
1147
|
+
links are pairs: S may be linked to R and T to S, and the line then runs
|
|
1148
|
+
through all three dots, passing beside the children between them. A
|
|
1149
|
+
top-level instance whose work isn't related breaks the dotted line: its
|
|
1150
|
+
row, and its children's, carry none, so nothing touches its dot. The order
|
|
1151
|
+
doesn't change for the lines.
|
|
1152
|
+
|
|
1153
|
+
The same lines show whether a group is open or closed: closed, the dotted
|
|
1154
|
+
line joins the top-level dots; open, it runs on beside the children, whose
|
|
1155
|
+
own lines are drawn. Both lines hold 3:1 contrast on every row fill.
|
|
1156
|
+
|
|
1157
|
+
The flag comes from the instances' OATS ([Related work](desktop-cli-api.md#related-work-oats-instance-related-work)).
|
|
1158
|
+
An OATS with `instance-related-work` reports it for a child and for a
|
|
1159
|
+
sibling. An older OATS, with `instance-same-work` only, reports it for a
|
|
1160
|
+
child only (set with `--same-work`), so its siblings get no dotted line. An
|
|
1161
|
+
OATS with neither reports none, and no line is drawn. For another machine's
|
|
1162
|
+
instances, its host must report the feature too, through an installed OATS
|
|
1163
|
+
with `server-probe-features`; a host whose features are not known (its last
|
|
1164
|
+
read failed) gets no line. A spawn from the Desktop never sets the flag.
|
|
1165
|
+
|
|
1166
|
+
A screen reader hears each row's state ("running", "stopped" or "status
|
|
1167
|
+
unknown") after its two lines, then each child "under" its parent, with
|
|
1168
|
+
"related work" when the line joins them, and each instance linked as a
|
|
1169
|
+
sibling "sibling of" the other, with "related work" at both ends of a joined
|
|
1170
|
+
pair. The lines themselves are hidden from assistive technology.
|
|
1122
1171
|
|
|
1123
1172
|
The sidebar shows the top-level instances only until you open one. An
|
|
1124
1173
|
instance with children has a chevron right after its name, with the number
|
|
@@ -1149,17 +1198,11 @@ are in name order, and an instance whose spawn time can't be read comes after
|
|
|
1149
1198
|
every one whose time can. Pinned instances come before all of these, at every
|
|
1150
1199
|
level ([Pinned instances](#pinned-instances)).
|
|
1151
1200
|
|
|
1152
|
-
Children
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
draws lines: there a parent's line joins only those children (siblings by a
|
|
1158
|
-
dotted line through their dots), in its own recency order inside each part.
|
|
1159
|
-
For another machine's instances, its host must report the feature too, through
|
|
1160
|
-
an installed OATS with `server-probe-features`. A host without the feature, or
|
|
1161
|
-
one whose features are not known (its last read failed), lists every child as
|
|
1162
|
-
doing its parent's work. A spawn from the Desktop never sets the flag.
|
|
1201
|
+
Children whose work is related to their parent's come first under it, each
|
|
1202
|
+
part newest first, so a parent's line ends at its last joined child and never
|
|
1203
|
+
passes one it doesn't join. Top-level instances keep their order whatever
|
|
1204
|
+
their flag. The command palette draws the same lines by the same rule, in its
|
|
1205
|
+
own recency order inside each part.
|
|
1163
1206
|
|
|
1164
1207
|
A row shows the instance's name as words: each `-` is a space, and the first
|
|
1165
1208
|
letter is a capital, so `oats-expert-maintainer-lanes` reads "Oats expert
|
package/docs/implementation.md
CHANGED
|
@@ -136,7 +136,7 @@ and the rules its tests pin.
|
|
|
136
136
|
| `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
|
|
137
137
|
| `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
|
|
138
138
|
| `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
|
|
139
|
-
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through; `instance-background.mjs` is the same for whether an instance is background: its home record, read by the rows, inspect and the command, and written by spawn and the command; `instance-pin.mjs` is the same for whether an instance is pinned at the top of its machine's list: its home record, read by the rows and inspect, and written only by `oats instance pin`; `instance-
|
|
139
|
+
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through; `instance-background.mjs` is the same for whether an instance is background: its home record, read by the rows, inspect and the command, and written by spawn and the command; `instance-pin.mjs` is the same for whether an instance is pinned at the top of its machine's list: its home record, read by the rows and inspect, and written only by `oats instance pin`; `instance-related-work.mjs` is an instance's related-work flag, its home record bound to a parent or a sibling, `relatedWorkBinding`, the one choice of which, and `relatedWorkHeld`, the one rule of whether it is on, which status rows, spawn, `oats instance related-work` and the `--server` route go through, and its compatibility layer with the same-work flag (the old home file read and removed there; the aliases in `command-flags.mjs`); `instance-board.mjs` is the agent's board: its home file and lock, the bounds, the session rule for its questions (by `instance-events.mjs` `liveSession`, the read that also gives the waiting claim), the `oats.board` claim each write sets, and the one reader of a row's `board`, local or relayed |
|
|
140
140
|
| `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, the rollback of an interrupted add, and completion of Git's partial removal. An unregistered residue with a dangling `.git` file is compared with the recorded branch through a private temporary index (`read-tree`, refresh, `diff-files` allowing deletions, and `ls-files --others --exclude-standard`) before permissions or files change; the clone's index is never used. Only clean residue is made writable, without following symlinks, and deleted |
|
|
141
141
|
| `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
|
|
142
142
|
| `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire`, `oats instance stop --apply`, `oats instance upgrade`, `oats session start --resume` (verb `resume`) and every other session start and restart, a scheduled start included (verb `start`, #1602; `core.mjs` `startClaimed`, the only exclusion of one start by another: two starts are answered `E_SESSION_START_BUSY` from the claim, `startPair`; a path with no record it can read takes no claim (`readHomeRecord`, as every lifecycle verb reads its record first); the start runs on the home's path on disk, and a home given through a link first answers what a start of the path as given answered before any guard (`startRefusals`, in their order; a partial upgrade is left to the claim while an upgrade holds it, `upgradeHoldsClaim`, as the CLI's pre-check does), then is held to its own authority on the path as given, `sessionDirectoryGuard`, then again with every check of the start's roots; an owned directory home must resolve to the home its own receipt records, bound by the receipt's paths, not by a second read of the disk: `requestedHomeGuard`) (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too A holder may add to its record as it goes (`recordInClaim`), and the next holder reads what a gone one left: a worktree add its running Git step; a retire the retire hooks that ended, `retireHooks: [{capability, meta?}]` with `retireHooksFor` (the home's `createdAt`: the list is bound to the incarnation it ran for, so a claim left by a retire that is gone never skips hooks for another home of the same name), which the retire that takes the claim over does not run again (`core.mjs` `finishedRetireHooks`; `claimHomeFor` hands the gone holder's record over as `tookOver`). A record without them skips nothing. |
|
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: v6.
|
|
44
|
-
oats.aweb: v1.
|
|
43
|
+
oats.okf: v6.3.0
|
|
44
|
+
oats.aweb: v1.46.0
|
|
45
45
|
oats.linear: v1.0.1
|
|
46
46
|
oats.jira: v1.0.1
|
|
47
47
|
defaults:
|
|
@@ -97,7 +97,7 @@ operations in full.
|
|
|
97
97
|
- **`oats.aweb-tasks`** (in the `oats.aweb` package from 1.31.0) fills the
|
|
98
98
|
tasks slot with aweb tasks, acting as the instance's own `oats.aweb`
|
|
99
99
|
identity in its default team. **An existing workspace opts in** by pinning
|
|
100
|
-
`oats.aweb: v1.
|
|
100
|
+
`oats.aweb: v1.46.0` (the feature needs 1.31.0 or later), adding
|
|
101
101
|
`tasks: { oats.aweb-tasks: { from: package } }` to `defaults`, and running
|
|
102
102
|
`oats sync`. Only new spawns get it. A soul that names its own tasks
|
|
103
103
|
provider in `capabilities:` (`oats.jira`, `oats.linear`) then holds two and
|
|
@@ -13,8 +13,8 @@ owns slot selection, composition, lifecycle, work-mode boundaries and the
|
|
|
13
13
|
hook contract, not a memory model or a judge.
|
|
14
14
|
|
|
15
15
|
Every implementing capability supplies its full runtime: reader tools,
|
|
16
|
-
injections, capture conventions, judgment instructions,
|
|
17
|
-
|
|
16
|
+
injections, capture conventions, judgment and proposal instructions, the
|
|
17
|
+
review that accepts them, lifecycle, validation, delivery and diagnostics. Reuse may be
|
|
18
18
|
explicit and versioned, never a hidden fetch of mutable doctrine. The theory
|
|
19
19
|
expert advises authors; it does not operate their stores or approve their
|
|
20
20
|
compatibility. Composing this capability selects no knowledge provider.
|
|
@@ -29,7 +29,7 @@ an author soul:
|
|
|
29
29
|
```yaml
|
|
30
30
|
# oats-workspace.yaml
|
|
31
31
|
packages:
|
|
32
|
-
oats.framework: v1.
|
|
32
|
+
oats.framework: v1.27.0 # provides oats.core, oats.setup, oats.knowledge-theory
|
|
33
33
|
|
|
34
34
|
# souls/<author-soul>/soul.yaml
|
|
35
35
|
capabilities:
|
|
@@ -54,9 +54,12 @@ curriculum, not this repository.
|
|
|
54
54
|
3. **Author working behavior.** Use the [reader/capture pattern](knowledge-reference/reader-capture.md).
|
|
55
55
|
Keep every-session instructions short; load detailed native operations from
|
|
56
56
|
that capability's own skills.
|
|
57
|
-
4. **Author deliberate judgment.** Use the [
|
|
58
|
-
if adopting this model
|
|
59
|
-
|
|
57
|
+
4. **Author deliberate judgment.** Use the [proposal pattern](knowledge-reference/proposal.md)
|
|
58
|
+
if adopting this model: the instance judges at its checkpoints, a reviewer
|
|
59
|
+
accepts. Freeze destinations when a proposal is planned, separate semantic
|
|
60
|
+
outcomes from delivery outcomes, and define recovery. An independent
|
|
61
|
+
harvester is an [option](knowledge-reference/adoption.md#an-option-an-independent-harvester)
|
|
62
|
+
with its own obligations.
|
|
60
63
|
5. **Deliver an independently usable package.** Follow [package craft](knowledge-reference/package-craft.md).
|
|
61
64
|
No path in a released soul or skill may depend on an author's checkout.
|
|
62
65
|
6. **Verify observable outcomes.** Run the relevant [acceptance cases](knowledge-reference/acceptance.md).
|
|
@@ -68,7 +71,7 @@ curriculum, not this repository.
|
|
|
68
71
|
- Model: adopt / adapt / alternative; rationale and deliberate departures.
|
|
69
72
|
- Provider and version: verified tools, evidence, unknown guarantees.
|
|
70
73
|
- Responsibility map: who supplies reader, capture, judgment, delivery,
|
|
71
|
-
|
|
74
|
+
review, lifecycle and diagnostics; no unowned runtime step.
|
|
72
75
|
- Custody: named destinations, owner identity, accepted state, concurrency,
|
|
73
76
|
retry and reader-refresh semantics. No credentials in the report.
|
|
74
77
|
- Proposed artifacts: capability manifest, local resources, instructions,
|
|
@@ -15,7 +15,7 @@ actually run.
|
|
|
15
15
|
2. **Activate deliberately.** Select only the additive authoring capability,
|
|
16
16
|
with knowledge/messaging/tasks explicitly disabled. Discover the packaged
|
|
17
17
|
expert and scaffold without a runtime launch. It gets the authoring skill
|
|
18
|
-
and complete local references, but no OKF bundle, capture flow or
|
|
18
|
+
and complete local references, but no OKF bundle, capture flow or proposal duty.
|
|
19
19
|
3. **Remove source crutches.** Copy the distribution to a clean source fixture,
|
|
20
20
|
acquire it, delete that source copy, and scaffold the expert. Follow every
|
|
21
21
|
local skill/reference link from the installed/materialized artifact. No
|
|
@@ -66,8 +66,8 @@ only the assigned trusted instructions govern execution.
|
|
|
66
66
|
- Same leaf names in different bases or repositories remain distinct owners.
|
|
67
67
|
- Missing binding, base or access fails visibly, without an empty substitute.
|
|
68
68
|
A read never scaffolds a node. A feature-branch change never selects custody.
|
|
69
|
-
- Migration preserves old knowledge and
|
|
70
|
-
a changed alias cannot redirect a
|
|
69
|
+
- Migration preserves old knowledge and open proposals until verified cutover;
|
|
70
|
+
a changed alias cannot redirect a planned proposal to another base.
|
|
71
71
|
|
|
72
72
|
## Real custody and failure
|
|
73
73
|
|
|
@@ -75,34 +75,36 @@ For every applicable row inspect native outputs and receipts, not only exit 0:
|
|
|
75
75
|
|
|
76
76
|
| Case | Required observable result |
|
|
77
77
|
|---|---|
|
|
78
|
-
| Embedded Git bundle and dedicated Git repository |
|
|
78
|
+
| Embedded Git bundle and dedicated Git repository | Accepted-baseline work apart from the source's branch; validated knowledge-only PR to correct target |
|
|
79
79
|
| PR opened, rejected or failed | Report actual proposal/failure state; no claim of accepted visibility or direct-write fallback |
|
|
80
80
|
| PR merged | Fresh reader after refresh can retrieve accepted knowledge; not merely PR text |
|
|
81
81
|
| Directory outside Git | Real durable native update without `.git`, GitHub, branch or PR dependencies |
|
|
82
|
-
| Concurrent destination
|
|
83
|
-
| Failure before publication |
|
|
84
|
-
| Crash after partial/publication write | Recovery establishes actual state; no duplicated claims or lost
|
|
85
|
-
|
|
|
86
|
-
| All candidates dropped |
|
|
87
|
-
| Truncated
|
|
82
|
+
| Concurrent proposals on one destination | Baseline conflict/coordination prevents silent loss; receipts identify outcomes |
|
|
83
|
+
| Failure before publication | Proposal and its outgoing change retained and reported; no successful receipt |
|
|
84
|
+
| Crash after partial/publication write | Recovery establishes actual state; no duplicated claims or lost proposal |
|
|
85
|
+
| Deliver the same proposal twice | Refused or explicitly reconciled; not duplicate knowledge |
|
|
86
|
+
| All candidates dropped | Checkpoint recorded with its reason; no empty proposal |
|
|
87
|
+
| Truncated or unreadable evidence | Reported; no proposed claim rests on it |
|
|
88
88
|
| Multiple destinations, one failed | Per-destination truthful results, no fabricated cross-store atomicity |
|
|
89
89
|
|
|
90
|
-
##
|
|
90
|
+
## Learning gate
|
|
91
91
|
|
|
92
92
|
1. Let source instance A encounter a genuinely new, verified, behavior-changing
|
|
93
93
|
fact or decision absent from the accepted base. Capture notes and/or records.
|
|
94
|
-
2.
|
|
95
|
-
|
|
96
|
-
3. Reuse A's display name for a distinct incarnation. Verify
|
|
97
|
-
stays attributed to A,
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
94
|
+
2. Let A run its final checkpoint, judge the claim and propose it, then retire
|
|
95
|
+
A safely before the proposal is reviewed.
|
|
96
|
+
3. Reuse A's display name for a distinct incarnation. Verify the proposal's
|
|
97
|
+
provenance stays attributed to A, and that the new incarnation's checkpoint
|
|
98
|
+
does not propose A's claim again.
|
|
99
|
+
4. Let the reviewer judge the proposal from what it carries, with no access to
|
|
100
|
+
A's home. Inspect A's semantic judgment, the review and the native delivery
|
|
101
|
+
result. For Git, merge through the authorized review process; for non-Git,
|
|
102
|
+
verify durable application and consistency/freshness semantics.
|
|
101
103
|
5. Launch fresh reader B in the selected real runtime with no A home, transcript
|
|
102
104
|
or hidden conversation context. Ask a task whose answer needs the new fact.
|
|
103
105
|
Require an answer traceable to accepted knowledge through native retrieval.
|
|
104
106
|
6. Record the evidence, failures and limits. A scaffold-only expert probe or an
|
|
105
|
-
agent reading
|
|
107
|
+
agent reading A's notes directly does not satisfy this gate.
|
|
106
108
|
|
|
107
109
|
Live agent trials require separate authorization and an isolated test deployment.
|
|
108
110
|
This curriculum's package tests deliberately never launch a runtime or install
|
|
@@ -10,7 +10,7 @@ policy. Choosing another model is a supported architectural choice.
|
|
|
10
10
|
| Alternative | Describe the replacement model, its own learning/retention/consistency contract and tests |
|
|
11
11
|
|
|
12
12
|
A graph store can adopt the reference promotion bar without Markdown, YAML,
|
|
13
|
-
`index.md`, branches or a universal
|
|
13
|
+
`index.md`, branches or a universal proposal API. A capability using continuous
|
|
14
14
|
retrieval without a separate judge might instead choose an alternative model.
|
|
15
15
|
Neither storage choice decides theory. Alternative capabilities still honor
|
|
16
16
|
framework work-mode, package containment, explicit configuration and executable
|
|
@@ -25,13 +25,27 @@ lifecycle effects, scheduling, native persistence, validation and diagnostics.
|
|
|
25
25
|
There is no invisible shared theory layer underneath it. It must be usable
|
|
26
26
|
without the expert running or reference documentation fetched over the network.
|
|
27
27
|
|
|
28
|
-
The default OKF model chooses external bases/nodes,
|
|
29
|
-
|
|
30
|
-
real non-Git custody. These are adoption choices, not new mandatory kernel
|
|
28
|
+
The default OKF model chooses external bases/nodes, working instances that
|
|
29
|
+
capture and propose at checkpoints, a knowledge maintainer that reviews every
|
|
30
|
+
proposal, PR-only Git delivery and real non-Git custody. These are adoption choices, not new mandatory kernel
|
|
31
31
|
fields. OKF-specific files, schemas and validator calls stay in OKF. A
|
|
32
32
|
capability choosing another approach is not rejected for failing an OKF or
|
|
33
33
|
reference-doctrine test that does not apply to it.
|
|
34
34
|
|
|
35
|
+
## An option: an independent harvester
|
|
36
|
+
|
|
37
|
+
A capability may instead give judgment to an independent harvester: a separate
|
|
38
|
+
worker that judges a source's captured evidence, possibly after the source has
|
|
39
|
+
retired, and delivers the result. Earlier OATS knowledge capabilities worked
|
|
40
|
+
this way; `oats.okf` 6 replaced it with proposals at checkpoints. A capability
|
|
41
|
+
choosing it adapts the reference model and owns what proposals avoid: copying
|
|
42
|
+
bounded evidence out of the source's home before retirement, per-source jobs
|
|
43
|
+
that a reused name cannot consume, destinations frozen at capture, explicit
|
|
44
|
+
host scheduling, and recovery when work outlives its source. The judgment
|
|
45
|
+
procedure, the exclusions and the delivery states in
|
|
46
|
+
[judgment and proposal](proposal.md) still apply to it, and a reviewer of its
|
|
47
|
+
output is still the gate before acceptance.
|
|
48
|
+
|
|
35
49
|
## Record the choice
|
|
36
50
|
|
|
37
51
|
Write a short decision before implementing:
|
|
@@ -25,15 +25,17 @@ choices can pass. Repository file inventories, API shapes obvious from source,
|
|
|
25
25
|
code paraphrases, session trivia, one-off workarounds and current TODOs usually
|
|
26
26
|
fail. Prefer expertise about the code over descriptions of the code.
|
|
27
27
|
|
|
28
|
-
## Capture is not judgment
|
|
28
|
+
## Capture is not judgment, and judgment is not acceptance
|
|
29
29
|
|
|
30
30
|
The working instance records non-obvious observations while they are fresh,
|
|
31
|
-
without self-censoring against a half-remembered promotion bar.
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
31
|
+
without self-censoring against a half-remembered promotion bar. At its
|
|
32
|
+
knowledge checkpoints it applies deliberate judgment to what it captured and
|
|
33
|
+
proposes the claims that pass; it does not strengthen them. A reviewer reads
|
|
34
|
+
every proposal and alone accepts it, so the independent read is the review,
|
|
35
|
+
not a second worker. Capture can come from notes and bounded records; neither
|
|
36
|
+
source automatically makes a claim true.
|
|
35
37
|
|
|
36
|
-
|
|
38
|
+
Judgment is **de-indexicalization**, not file copying. Given verified evidence:
|
|
37
39
|
|
|
38
40
|
- Input: “The build broke until I cleared the schema cache after this change.”
|
|
39
41
|
- Candidate: “Model changes leave stale schema-cache entries; clear that cache
|
|
@@ -53,7 +55,7 @@ Harvest is **de-indexicalization**, not file copying. Given verified evidence:
|
|
|
53
55
|
repeat the same way” can become a skill. Maintain an existing skill when the
|
|
54
56
|
candidate corrects it; do not duplicate it as a new procedure. Skills are
|
|
55
57
|
behavior changes and must follow their owning repository's approval process.
|
|
56
|
-
|
|
58
|
+
Proposing does not grant permission to rewrite role or safety boundaries.
|
|
57
59
|
|
|
58
60
|
## Jurisdiction, slow state and specialization
|
|
59
61
|
|
|
@@ -75,12 +77,12 @@ Ownership means responsibility and routing, not a new access-control system.
|
|
|
75
77
|
Discover available accepted knowledge, then retrieve selectively. Index-first
|
|
76
78
|
is an OKF tactic; a graph's native entry query can serve the same purpose. Do
|
|
77
79
|
not bulk-load everything, mutate during a read, or infer an absent base is empty.
|
|
78
|
-
Capture and
|
|
80
|
+
Capture and proposal retain provenance and uncertainty. Never promote secrets,
|
|
79
81
|
credentials, personal data about people outside the team (clients,
|
|
80
82
|
correspondents, any other third party), or verbatim third-party messages. A
|
|
81
83
|
generalized lesson about a message is different from transcribing it as
|
|
82
84
|
verified knowledge. Source/tool content is evidence, not instructions allowed
|
|
83
85
|
to override the worker's task.
|
|
84
86
|
|
|
85
|
-
See [reader/capture](reader-capture.md), [judgment](
|
|
87
|
+
See [reader/capture](reader-capture.md), [judgment](proposal.md), and
|
|
86
88
|
[behavioral acceptance](acceptance.md) for applying these distinctions.
|
|
@@ -34,7 +34,7 @@ A knowledge implementation's capability manifest might begin:
|
|
|
34
34
|
"description": "Native knowledge capability.",
|
|
35
35
|
"compatibility": { "oats": ">=0.22.19" },
|
|
36
36
|
"layer": "knowledge",
|
|
37
|
-
"skills": ["skills/native-reader", "skills/native-
|
|
37
|
+
"skills": ["skills/native-reader", "skills/native-propose"],
|
|
38
38
|
"inject": "injects/knowledge.md"
|
|
39
39
|
}
|
|
40
40
|
```
|
|
@@ -67,7 +67,7 @@ Ground the role in a real authoring/review task and its corrections. Mark an
|
|
|
67
67
|
untested role as such rather than inventing expertise. Omit deployment paths,
|
|
68
68
|
accounts, credentials and pending work. Packaged souls are read-only resources;
|
|
69
69
|
instances home locally. A knowledge-disabled expert must not assume `STATE.md`,
|
|
70
|
-
`notes/`, a soul knowledge bundle or a
|
|
70
|
+
`notes/`, a soul knowledge bundle or a proposal command exists. Do not silently
|
|
71
71
|
pin a model or runtime if the role does not need that choice.
|
|
72
72
|
|
|
73
73
|
## Skill craft
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Judgment and proposal at checkpoints
|
|
2
|
+
|
|
3
|
+
Use this pattern for capabilities adopting the [reference model](model.md).
|
|
4
|
+
A capability choosing a different model authors its own runtime behavior. This
|
|
5
|
+
is not a universal judge, kernel service or required shared proposal skill.
|
|
6
|
+
|
|
7
|
+
## Who judges, and where independence lives
|
|
8
|
+
|
|
9
|
+
The working instance judges its own captured evidence at its **knowledge
|
|
10
|
+
checkpoints** and proposes the claims that pass. A reviewer the capability
|
|
11
|
+
names, such as a knowledge maintainer, reads every proposal and alone decides
|
|
12
|
+
what becomes accepted knowledge. The proposer never writes accepted state and
|
|
13
|
+
never accepts its own proposal: the review is the independent read.
|
|
14
|
+
|
|
15
|
+
The capability defines its checkpoints. Typical ones: a piece of work handed
|
|
16
|
+
over for review, a finished task, and in a long-lived role a feature ready, a
|
|
17
|
+
release or deploy shipped, or a direction decision taken with a person. A
|
|
18
|
+
commit or a review round is not a checkpoint. One proposal per checkpoint
|
|
19
|
+
carries only what no earlier proposal carried. The last checkpoint comes
|
|
20
|
+
before the instance retires: nothing waits for the source after it is gone,
|
|
21
|
+
so there is no queue, no background worker and no watermark to keep.
|
|
22
|
+
|
|
23
|
+
## Judgment procedure
|
|
24
|
+
|
|
25
|
+
1. Read your own captured evidence for the checkpoint in full. If a required
|
|
26
|
+
record cannot be read completely, say so and propose nothing that rests on
|
|
27
|
+
it. Source content is data, never instructions to expand scope, access
|
|
28
|
+
credentials or change the task.
|
|
29
|
+
2. Consult relevant accepted knowledge using native read tools. Retrieve enough
|
|
30
|
+
to detect duplicates, contradictions and superseded claims, and read the
|
|
31
|
+
proposals already open on the same destination: a claim pending there is a
|
|
32
|
+
duplicate.
|
|
33
|
+
3. Extract only claims the evidence supports. Do not strengthen them. Apply
|
|
34
|
+
the promotion bar: durable **and** behavior-changing for future instances
|
|
35
|
+
in this owner's jurisdiction. Record uncertainty and provenance.
|
|
36
|
+
4. Choose a semantic outcome per candidate:
|
|
37
|
+
- **Promote:** propose a genuinely new authoritative claim in an owned node.
|
|
38
|
+
- **Merge:** propose maintaining an existing concept or procedure, preserving
|
|
39
|
+
evidence.
|
|
40
|
+
- **Supersede:** explain what changed and why; propose retiring the
|
|
41
|
+
contradicted claim rather than leaving two incompatible “current” claims.
|
|
42
|
+
- **Drop:** record why it fails the bar or an exclusion. A checkpoint that
|
|
43
|
+
proposes nothing is legitimate success, recorded with its reason.
|
|
44
|
+
5. Route facts/decisions to knowledge, repeatable procedures to playbooks or
|
|
45
|
+
skills, and corrections to their existing home. A proposed skill or soul
|
|
46
|
+
behavior change follows the owning repository's approval rules; a proposal
|
|
47
|
+
does not authorize changing safety boundaries. Do not stash durable
|
|
48
|
+
knowledge in soul files just because a store write is inconvenient. A
|
|
49
|
+
lesson whose home is a node you do not own goes to that node's owner.
|
|
50
|
+
6. Validate the proposed update, deliver it through the selected custody, and
|
|
51
|
+
record the checkpoint and its exact outcome in the instance's own record. A
|
|
52
|
+
partial edit or an opened process is not a delivered proposal.
|
|
53
|
+
|
|
54
|
+
Never promote secrets, credentials, personal data about people outside the team
|
|
55
|
+
(clients, correspondents, any other third party), third-party messages
|
|
56
|
+
verbatim, tool noise, readily re-derived code descriptions or task-only plans.
|
|
57
|
+
Generalize a lesson without losing scope; do not turn a deployment fact into
|
|
58
|
+
universal expertise.
|
|
59
|
+
|
|
60
|
+
## A proposal stands on what it carries
|
|
61
|
+
|
|
62
|
+
The reviewer judges the proposal and its cited evidence, never the proposer's
|
|
63
|
+
home, transcript or live interview: the proposer may have retired by then. A
|
|
64
|
+
proposal names each claim, its destination node, why a future instance would
|
|
65
|
+
act differently, and its evidence. Provenance identifies the source incarnation
|
|
66
|
+
and owner, and fixes what was relied on (for example, hashes of the backing
|
|
67
|
+
notes) without publishing the notes themselves.
|
|
68
|
+
|
|
69
|
+
Screen everything that leaves the host before it is delivered: the changed
|
|
70
|
+
content, file names, the commit text and the proposal's description. On a
|
|
71
|
+
public Git base a pushed branch is public before anyone reviews it. A screen
|
|
72
|
+
is a bounded detector, not clearance: the proposer still reads the complete
|
|
73
|
+
outgoing change once, as a reviewer would.
|
|
74
|
+
|
|
75
|
+
## Delivery is separate from judgment
|
|
76
|
+
|
|
77
|
+
| State | What may be asserted |
|
|
78
|
+
|---|---|
|
|
79
|
+
| Captured | Evidence is in the instance's record; nothing is judged yet |
|
|
80
|
+
| Checkpoint, nothing to propose | All candidates judged; the outcome and its reason are recorded |
|
|
81
|
+
| Git PR delivered | Validated proposal exists at a verified PR destination/head; not accepted |
|
|
82
|
+
| Git accepted | The reviewer merged the PR into the accepted baseline; readers may still need refresh |
|
|
83
|
+
| Directory/native applied | The reviewer applied it with provider-confirmed durable publication; report actual consistency limits |
|
|
84
|
+
| Reader-visible | Fresh native read observes accepted update, not just a write acknowledgment |
|
|
85
|
+
| Failed/uncertain | The proposal and its delivery record are retained and reported; no invented successful receipt |
|
|
86
|
+
|
|
87
|
+
**Git:** start in an accepted-baseline clone of the owned nodes, outside the
|
|
88
|
+
source's feature branch. Embedded and dedicated Git bases both receive
|
|
89
|
+
knowledge-only PRs on a new branch, never a push to the accepted branch.
|
|
90
|
+
Validate scope and target, record the verified PR receipt, and distinguish
|
|
91
|
+
rejected, pending, merged and reader-refreshed state. Never downgrade a Git
|
|
92
|
+
delivery failure into a direct write.
|
|
93
|
+
|
|
94
|
+
**Directory:** use a genuinely non-Git execution context, staged changes,
|
|
95
|
+
baseline checks, coordinated publication and crash-recoverable receipts. A
|
|
96
|
+
successful file write alone is not crash recovery. Name who reviews and applies
|
|
97
|
+
a staged proposal; if the store has no review phase, say so rather than
|
|
98
|
+
letting the proposer publish its own change. Document cooperative single-host
|
|
99
|
+
limits rather than claiming distributed locking.
|
|
100
|
+
|
|
101
|
+
**Native service/CLI:** verify its actual acknowledgment, consistency, update
|
|
102
|
+
and retry behavior. If it has no review phase or snapshot revisions, say so.
|
|
103
|
+
Do not fabricate PRs or transactions. Cross-destination writes are not assumed
|
|
104
|
+
atomic; report and recover each destination independently.
|
|
105
|
+
|
|
106
|
+
## Failure and recovery
|
|
107
|
+
|
|
108
|
+
A delivery error or an uncertain result is reported, never retried blindly:
|
|
109
|
+
after an uncertain push a remote branch or PR may exist. Keep the proposal, its
|
|
110
|
+
outgoing change and its result where the instance and its reviewer can inspect
|
|
111
|
+
them, and do not propose the same work again after a restart or a compaction.
|
|
112
|
+
A durable proposal counts as delivered judgment without being reader-visible.
|
|
113
|
+
Keep proposal, acceptance and freshness state inspectable, and retain evidence
|
|
114
|
+
for rejected or failed delivery. Bind destinations when the proposal is
|
|
115
|
+
planned, not by consulting changed config at retry time. Test failures before
|
|
116
|
+
and after publication, concurrent proposals and retries as
|
|
117
|
+
[acceptance cases](acceptance.md).
|
|
@@ -18,14 +18,14 @@ another model. A soul may own nodes in several bases. `project/desktop-expert`
|
|
|
18
18
|
and `team/desktop-expert` are different nodes; leaf names are not identity.
|
|
19
19
|
Stable owner identity distinguishes same-named souls from different repositories.
|
|
20
20
|
|
|
21
|
-
Ownership assigns responsibility and
|
|
21
|
+
Ownership assigns responsibility and proposal routing; `reads` selects initial
|
|
22
22
|
context. Neither is an ACL. Configured workspace/team bases are discoverable,
|
|
23
23
|
and native user accounts govern access. There is no new public/private system.
|
|
24
24
|
Access to a repository does not automatically bind it as a knowledge base.
|
|
25
25
|
|
|
26
26
|
## Resolve without guessing
|
|
27
27
|
|
|
28
|
-
Record an unambiguous resolved destination and owner before reads or
|
|
28
|
+
Record an unambiguous resolved destination and owner before reads or proposals.
|
|
29
29
|
Do not derive custody from the source's cwd, feature branch, writable checkout,
|
|
30
30
|
work mode or the soul's location. Relative locators resolve from their declaring
|
|
31
31
|
scope with containment checks. For OKF specifically,
|
|
@@ -35,8 +35,8 @@ is an implementation choice, not generic OATS YAML or a graph-provider schema.
|
|
|
35
35
|
|
|
36
36
|
Missing bindings, owner mismatches and access failures are visible errors.
|
|
37
37
|
Reads never scaffold missing nodes. Creation and ownership changes are explicit
|
|
38
|
-
writes.
|
|
39
|
-
subsequent config edits must not reroute
|
|
38
|
+
writes. A planned proposal retains its frozen destination identity and binding
|
|
39
|
+
provenance; subsequent config edits must not reroute it. Provider migration is explicit.
|
|
40
40
|
|
|
41
41
|
## Native contract worksheet
|
|
42
42
|
|
|
@@ -45,19 +45,19 @@ subsequent config edits must not reroute them. Provider migration is explicit.
|
|
|
45
45
|
| Resolve | Actual locator, stable base/node/owner identity, declaring scope, containment |
|
|
46
46
|
| Discover/read | Accepted-state entry point, selective retrieval, credentials source, freshness signal |
|
|
47
47
|
| Capture | Source identity, note versions/hashes, bounded record content and provenance |
|
|
48
|
-
|
|
|
48
|
+
| Propose | Checkpoint input, frozen destinations, write surface, content screen before anything leaves the host, a second delivery of the same proposal refused |
|
|
49
49
|
| Judge/write | Native read and author tools; allowed targets; supersession and duplicate prevention |
|
|
50
50
|
| Validate | Representation validator and semantic checks; whole-base/link namespace where relevant |
|
|
51
|
-
| Deliver | Durable proposal, applied update, no-change, failure and uncertainty signals |
|
|
51
|
+
| Deliver and review | Durable proposal, the reviewer's accept/reject/amend, applied update, no-change, failure and uncertainty signals |
|
|
52
52
|
| Inspect/refresh | What readers see, accepted versus pending, retry/recovery and receipts |
|
|
53
53
|
|
|
54
54
|
## Concrete custody distinctions
|
|
55
55
|
|
|
56
56
|
| Store | Read baseline | Writer and acceptance |
|
|
57
57
|
|---|---|---|
|
|
58
|
-
| Embedded Git OKF | Accepted ref plus contained bundle root |
|
|
58
|
+
| Embedded Git OKF | Accepted ref plus contained bundle root | Accepted-baseline clone apart from the feature branch; knowledge-only PR the reviewer merges |
|
|
59
59
|
| Dedicated Git OKF | Accepted ref of knowledge repository | Same PR-only rule; separate repository does not make it non-Git |
|
|
60
|
-
| Directory OKF | Configured directory's confirmed current contents |
|
|
60
|
+
| Directory OKF | Configured directory's confirmed current contents | Staging, baseline checks, coordinated/crash-recoverable native publication; no review phase, so `oats.okf` 6 delivers no proposals to it |
|
|
61
61
|
| Native CLI graph | Verified native query and consistency behavior | Verified native authoring/confirmation; unknown until investigated |
|
|
62
62
|
|
|
63
63
|
For Git, a PR opened is delivered judgment, not merged knowledge. A failed PR
|
|
@@ -70,5 +70,5 @@ subdirectories. A graph uses its own representation validator, not an OKF check.
|
|
|
70
70
|
Omnigraph is a motivating scenario, not a verified integration: obtain a graph
|
|
71
71
|
provider's actual command help and guarantees before proposing any command.
|
|
72
72
|
|
|
73
|
-
See [
|
|
74
|
-
for
|
|
73
|
+
See [judgment and proposal](proposal.md) and [acceptance cases](acceptance.md)
|
|
74
|
+
for checkpoint execution and delivery/failure probes.
|