@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.
Files changed (54) hide show
  1. package/bin/oats.mjs +131 -23
  2. package/docs/capabilities.md +12 -2
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +206 -228
  5. package/docs/design/2026-11-19-sandboxes.md +878 -0
  6. package/docs/design/README.md +3 -0
  7. package/docs/desktop-cli-api.md +416 -72
  8. package/docs/desktop.md +60 -17
  9. package/docs/implementation.md +1 -1
  10. package/docs/integrations.md +3 -3
  11. package/docs/knowledge-capability-authoring.md +10 -7
  12. package/docs/knowledge-reference/acceptance.md +21 -19
  13. package/docs/knowledge-reference/adoption.md +18 -4
  14. package/docs/knowledge-reference/model.md +11 -9
  15. package/docs/knowledge-reference/package-craft.md +2 -2
  16. package/docs/knowledge-reference/proposal.md +117 -0
  17. package/docs/knowledge-reference/provider-mapping.md +10 -10
  18. package/docs/knowledge-reference/reader-capture.md +26 -22
  19. package/docs/knowledge-theory.md +1 -1
  20. package/docs/knowledge.md +5 -5
  21. package/docs/official-catalog.md +4 -4
  22. package/docs/packages.md +13 -13
  23. package/docs/release-notes/v0.69.23.md +231 -0
  24. package/docs/servers.md +10 -6
  25. package/docs/souls-and-instances.md +51 -22
  26. package/docs/tui.md +4 -3
  27. package/docs/upgrading.md +12 -5
  28. package/docs/workspaces.md +2 -2
  29. package/lib/argv.mjs +6 -2
  30. package/lib/capability-contract.mjs +2 -2
  31. package/lib/command-flags.mjs +39 -2
  32. package/lib/core.mjs +25 -14
  33. package/lib/instance-board.mjs +337 -0
  34. package/lib/instance-events.mjs +48 -10
  35. package/lib/instance-lifecycle.mjs +19 -15
  36. package/lib/instance-listing.mjs +18 -10
  37. package/lib/instance-related-work.mjs +143 -0
  38. package/lib/kernel-features.mjs +4 -1
  39. package/lib/servers.mjs +123 -13
  40. package/package-catalog.json +3 -3
  41. package/package.json +1 -1
  42. package/packages/client/deployment-data.mjs +4 -2
  43. package/packages/client/deployment-panel.mjs +2 -1
  44. package/packages/client/instance-tree.mjs +34 -4
  45. package/packages/client/keymap.mjs +5 -0
  46. package/packages/client/mail-contract.mjs +130 -0
  47. package/packages/client/panel-views.mjs +7 -7
  48. package/packages/client/related-work.mjs +84 -0
  49. package/packages/client/remote-roster.mjs +4 -3
  50. package/packages/client/workspace-cli.mjs +13 -2
  51. package/skills/oats-getting-started/SKILL.md +11 -8
  52. package/docs/knowledge-reference/harvester.md +0 -109
  53. package/lib/instance-same-work.mjs +0 -67
  54. 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 sidebar draws no lines between them: the
1117
- indent and that space show the tree. A screen reader hears each row's state ("running", "stopped" or "status
1118
- unknown") after its two lines, then each child "under"
1119
- its parent, with "same work" when its host reports it doing its parent's work,
1120
- and each instance linked as a sibling "sibling of" the other, after the row's
1121
- two lines.
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 that do their parent's work come first under it. When the instances'
1153
- OATS has the `instance-same-work` feature, a child the kernel reports as doing
1154
- its parent's work (`sameWork: true` in its row, set with `oats spawn …
1155
- --same-work` or `oats instance same-work <instance> on`) is listed before its
1156
- parent's other children, each part newest first. The command palette still
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
@@ -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-same-work.mjs` is an instance's same-work flag, its home record bound to a parent, and `sameWorkOf`, the one rule of whether it is on, which status rows, spawn and `oats instance same-work` go 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-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. |
@@ -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.2.0
44
- oats.aweb: v1.45.0
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.45.0` (the feature needs 1.31.0 or later), adding
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, a harvester if any,
17
- lifecycle and scheduling, validation, delivery and diagnostics. Reuse may be
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.26.0 # provides oats.core, oats.setup, oats.knowledge-theory
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 [harvester pattern](knowledge-reference/harvester.md)
58
- if adopting this model. Freeze inputs and destinations before execution,
59
- separate semantic outcomes from delivery outcomes, and define recovery.
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
- lifecycle, scheduling and diagnostics; no unowned runtime step.
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 harvester.
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 pending inputs until verified cutover;
70
- a changed alias cannot redirect a frozen job to another base.
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 | Independent accepted-baseline work; validated knowledge-only PR to correct target |
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 writers | Baseline conflict/coordination prevents silent loss; receipts identify outcomes |
83
- | Failure before publication | Preserved input and retryable staged work, no successful applied receipt |
84
- | Crash after partial/publication write | Recovery establishes actual state; no duplicated claims or lost input |
85
- | Retry the same input | Idempotent processing or explicit reconciliation; not duplicate knowledge |
86
- | All candidates dropped | Durable completed-no-change judgment, not an endless pending input |
87
- | Truncated, skipped or held capture/window | Incomplete/pending, never a completed watermark |
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
- ## Source-independent learning gate
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. Preserve bounded evidence and frozen destinations outside A's home/worktree.
95
- Remove A through safe retirement before the independent harvest finishes.
96
- 3. Reuse A's display name for a distinct incarnation. Verify A's pending evidence
97
- stays attributed to A, not consumed by the new incarnation's job.
98
- 4. Run the independent harvest and inspect its semantic judgment and native
99
- delivery result. For Git, merge through the authorized review process; for
100
- non-Git, verify durable application and consistency/freshness semantics.
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 the captured input directly does not satisfy this gate.
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 harvester API. A capability using continuous
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, instructional
29
- read/capture-only workers, independent harvesting, PR-only Git delivery and
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. A separate
32
- harvest applies deliberate judgment. It does not strengthen claims or interview
33
- a source that must remain alive. Capture can come from notes and bounded
34
- records; neither source automatically makes a claim true.
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
- Harvest is **de-indexicalization**, not file copying. Given verified evidence:
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
- Harvesting does not grant permission to rewrite role or safety boundaries.
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 harvest retain provenance and uncertainty. Never promote secrets,
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](harvester.md), and
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-harvest"],
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 harvest command exists. Do not silently
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 harvest routing; `reads` selects initial
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 harvest.
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. Pending inputs retain frozen destination identity and binding provenance;
39
- subsequent config edits must not reroute them. Provider migration is explicit.
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
- | Prepare harvest | Independent worker input, frozen destinations, claim/idempotency key, durable input custody |
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 | Independent accepted-baseline checkout; knowledge-only PR |
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 | Independent staging, baseline checks, coordinated/crash-recoverable native publication |
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 [harvester instructions](harvester.md) and [acceptance cases](acceptance.md)
74
- for source-independent execution and delivery/failure probes.
73
+ See [judgment and proposal](proposal.md) and [acceptance cases](acceptance.md)
74
+ for checkpoint execution and delivery/failure probes.