@awebai/oats 0.28.0 → 0.29.1

package/capabilities/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: okf-trigger-setup
+description: >-
+  Set up and verify the OKF harvest-review trigger, which spawns a knowledge
+  maintainer for each harvest PR: declare it as a workspace automation
+  (`oats-triggers/okf-harvest-review.yaml` in a member repo, `from:
+  oats.okf:harvest-review`, with `runsOn` naming the one host and `owner` the
+  GitHub account that can merge on the knowledge-base repo), or locally with
+  `oats trigger add` for a machine-private setup. Covers the okf team, the
+  self-approval limit and `oats trigger test`. Use when setting up knowledge
+  operations, when harvest PRs are not being reviewed, when moving the
+  reviewer to another host, or when asked whether a host may run the
+  maintainer.
+---
+
+# Setting up the harvest-review trigger
+
+The trigger makes a harvest PR get reviewed: when a PR labelled `okf-harvest`
+opens on the knowledge-base (KB) repository, the host tick spawns a new
+`oats.okf/knowledge-maintainer` in the `okf` team to review it. It runs on one
+machine, acting as one GitHub account, and that account must be able to
+**merge** on the KB repository.
+
+## 1. Choose the host and the account
+
+- **The account (`owner`)** must be able to merge on the KB repository (push,
+  maintain or admin). Check from the host:
+  `gh api repos/<owner>/<repo> --jq .permissions`.
+- **The host (`runsOn`)** is the one machine that runs the trigger, named by
+  its `oats-local.yaml` `host: { name: <slug> }`, and logged in with `gh` as
+  that account.
+- **The harvest switch is independent**: a review host need not harvest (its
+  `harvest` setting can stay `off`), and a harvesting host need not review.
+
+## 2. The self-approval limit
+
+GitHub forbids approving your own account's PR. If the harvester's host and
+the reviewer's account are the same GitHub account, then either:
+- the KB repository's `main` must not require approving reviews (merge
+  permission is enough; the maintainer records its verdict as a PR comment,
+  not an approval), or
+- the trigger's `owner` is a separate reviewer account or machine user.
+
+Say which one applies when you report the setup.
+
+## 3. The okf team
+
+The package souls carry `team: okf`. The workspace must declare it, with its
+messaging mapping. Messaging is aweb (`oats.aweb`, the workspace default);
+it needs oats.aweb 1.15.0 or later, which honours the `join=okf` the
+harvester spawn and the trigger's `teams: [okf]` pass:
+
+```yaml
+# oats-workspace.yaml
+teams:
+  okf: { description: Knowledge operations }
+defaults:
+  messaging: { oats.aweb: { from: package } }
+messaging:
+  byTeam:
+    okf: { team: aweb:<your-org>.okf }
+```
+
+Another messaging provider works the same way if it honours `join`.
+
+Without it, the souls list with `E_TEAM_UNKNOWN`, and the harvester and the
+maintainer cannot message each other.
+
+## 4. Declare it in the workspace (the default)
+
+A team relies on the review, so declare it in Git, in a member repository (the
+workspace's host repo), in its `oats-triggers/` folder:
+
+```yaml
+# <member>/oats-triggers/okf-harvest-review.yaml
+kind: oats-trigger
+schemaVersion: 1
+description: Review every OKF harvest PR on the knowledge base
+from: oats.okf:harvest-review
+set: { repo: github.com/<owner>/<kb-repo> }     # optional: base, harness, model
+runsOn: <host.name of the one machine>
+owner: github.com/<the merge-capable account>
+```
+
+- `kind: oats-trigger` and `schemaVersion: 1` make the file self-describing; a
+  wrong kind is `E_AUTOMATION_SCHEMA`.
+- The id is `id:` if present, else the filename stem (`okf-harvest-review`).
+  Two files with the same id in one member are `E_AUTOMATION_DUPLICATE`.
+- A file named `*.oats-trigger.yaml` anywhere in the member works too (never
+  under `oats-package/`, `.git/` or `node_modules/`); `oats-triggers/` is the
+  canonical place.
+
+Or let the CLI write it: `oats trigger add --from oats.okf:harvest-review
+--set repo=github.com/<owner>/<kb-repo> --workspace <member>` (it prints the
+file when that repository is not the current checkout). Commit and merge it
+like any other change.
+
+A host runs it only when **both** its `host.name` equals `runsOn` **and** its
+`gh` account equals `owner`. Everywhere else it is listed with the reason:
+`assigned-elsewhere`, `owner-mismatch` or `host-unnamed`. That keeps exactly
+one machine on it, and the operator's consent explicit. A host can opt out
+without a commit: `automations.disabled: [<member>/okf-harvest-review]` in its
+`oats-local.yaml`. Changes reach the host within about ten minutes (after
+`oats sync`, or the tick's refresh).
+
+## 5. Or add it locally (machine-private)
+
+For a personal or experimental setup, add it to this deployment only. It runs
+on this host with this host's `gh`, with no `runsOn` or `owner`:
+
+```sh
+oats trigger add --from oats.okf:harvest-review --set repo=github.com/<owner>/<kb-repo>
+#   optional: --set base=main --set harness=claude --set model=opus --id okf-harvest-review
+```
+
+Never run the same review from two places: one workspace declaration, or one
+local trigger on one host.
+
+## 6. Test it on the host that runs it
+
+```sh
+oats trigger test <member>/okf-harvest-review   # or: oats trigger test okf-harvest-review (local)
+oats schedule host install                      # the host timer, if the test says it is missing
+oats trigger status
+```
+
+- `oats trigger test` checks gh auth and where its credential comes from, the
+  repository and your merge permissions, the soul, its messaging capability,
+  the okf team, the host/owner match, and what would fire now. It spawns
+  nothing. It must pass before you report the setup done; fix what it names.
+- **Credentials reach the tick through the host timer, not your shell.** A
+  `GH_TOKEN` exported in your shell does not reach it; `gh auth login` with the
+  keyring or config file does.
+- Pause with `oats trigger disable <id>`; `remove` leaves running maintainers
+  alone.
+
+## 7. Labels
+
+Harvest PRs carry `okf-harvest` (the harvester's completion creates the label
+if the repository lacks it). The maintainer adds `okf-needs-human` when a PR
+would supersede a human-accepted decision. To pre-create both:
+
+```sh
+gh label create okf-harvest --repo <owner>/<repo> --force --color 0E8A16 --description "OKF harvest PR (oats.okf)"
+gh label create okf-needs-human --repo <owner>/<repo> --force --color D93F0B --description "OKF: needs a human decision"
+```

package/capabilities/oats-review/injects/review.md

@@ -11,8 +11,9 @@ oats spawn reviewer --work attached --work-dir "$PWD/work" \
   --task "Review commit <sha> on branch <branch>. Report to <your-instance> per your operating loop."
 ```
 
-- `--purpose "<short-sha>"` gives the reviewer a unique, commit-relevant
-  instance name (`reviewer-<short-sha>`); attached mode shares your work tree
+- `reviewer` is the oats.dev package's soul (`oats.dev/reviewer`).
+  `--purpose "<short-sha>"` gives it a unique, commit-relevant instance name
+  (`oats-dev-reviewer-<short-sha>`); attached mode shares your work tree
   and automatically makes the reviewer your child (attached agents are always
   children of the work-tree owner — no relation flags needed or allowed).
 - The reviewer reviews **that commit's diff only** and reports its verdict

package/capabilities/oats-review/oats.json

@@ -1,11 +1,10 @@
 {
   "capability": "oats.review",
   "private": true,
-  "version": "1.2.1",
-  "compatibility": { "oats": ">=0.26.0" },
-  "description": "Post-commit review discipline: a fresh reviewer agent (defined by this capability) reviews each new commit's diff, reports its verdict to its spawner over the deployment's messaging layer (or in its transcript when there is none), and retires — plus the shared developer delivery discipline.",
+  "version": "1.3.0",
+  "compatibility": { "oats": ">=0.28.0" },
+  "description": "Post-commit review discipline: a fresh reviewer (this package's soul `reviewer`) reviews each new commit's diff, reports its verdict to its spawner over the deployment's messaging layer (or in its transcript when there is none), and retires — plus the shared developer delivery discipline and the reviewer's code-review and security-review skills.",
   "requires": [],
-  "agents": ["agents/reviewer"],
   "skills": ["skills/code-review", "skills/security-review"],
   "inject": "injects/review.md"
 }

package/docs/capabilities.md

@@ -72,7 +72,7 @@ A self-contained package has an `oats.json`:
 - `compatibility.oats` is the kernel range the capability runs on. The kernel
   refuses to compose a capability whose range does not admit it
   (`E_CAPABILITY_INCOMPATIBLE`, naming capability, range and kernel) wherever a
-  soul or capability agent resolves (spawn, `spawn --preview`, `inspect
+  soul resolves (spawn, `spawn --preview`, `inspect
   --soul`, operator commands). `oats inspect` shows each module's
   `compatibility: { ok, range, kernel }`; a home whose spawned module no longer
   admits the running kernel reports a `capability-incompatible` problem.
@@ -302,6 +302,19 @@ workspace's decision to trust it. A soul names a package capability with
 packages is in [packages.md](packages.md). There is no installed
 copy at a deployment and no `oats install`/`trust`/`update`/`remove`.
 
+One package can carry capabilities meant for **different souls**. oats.okf
+4.0.0 ships three:
+
+- `oats.okf` fills every working soul's knowledge slot;
+- `oats.okf-harvest` is composed only into its harvester soul;
+- `oats.okf-maintenance` is composed only into its maintainer soul.
+
+Each is its own manifest with its own skills, inject and commands. One pin
+versions all three, together with the package's souls
+([knowledge.md](knowledge.md#who-gets-which-okf-skills)). Split a package this
+way when roles need different instructions: a soul composes only the
+capability it names, so no role carries another's procedure.
+
 ## Member capabilities
 
 A capability at `<member repo>/capabilities/<name>/oats.json` is discoverable
@@ -314,13 +327,24 @@ listed (`private: true`, marked "(repo-owned)"), but usable only from its own
 repo (`E_CAPABILITY_PRIVATE` elsewhere). A member's `oats-package/` is **not** a member capability: it is
 reported as `publishes` and consumed only as a package.
 
-## Capability-defined agents
+## Agents a capability needs
+
+A capability declares no agents: `agents:` in a manifest was **removed in
+0.29.0**. Resolution refuses a module that still declares it with
+`E_CAPABILITY_AGENTS_REMOVED { capability, agents }` (spawn, `spawn --preview`,
+`inspect --soul`, operator commands). Ship the agent as a soul instead:
+
+- a **package soul**: `souls/<name>/` beside the package's capabilities, listed
+  in `oats-package.json` `souls:`, spawned as `oats spawn <package>/<name>`
+  (or the bare name when unique), reading the package's capabilities with
+  `from: here` ([packages.md](packages.md#package-souls)). The post-commit
+  `reviewer` is one: oats.dev 1.1.0's `oats.dev/reviewer`, beside `oats.review`;
+- or a **member soul**: `souls/<name>/` in a member repository, using a
+  member capability `from: here`.
 
-A manifest may declare `agents: ["agents/<name>"]` — package-relative soul
-directories (`soul.yaml` + `AGENTS.md` directly inside). *(Open thread: under
-the workspace model these are re-based on member souls — a package repo's
-expert soul is an ordinary `souls/<name>-expert/` in the member; the classic
-lookup still exists for 0.24 layouts.)*
+A home an earlier kernel spawned from a manifest `agents:` soul (its agent
+directory holds only `instances/`) is still listed by `oats status`, may anchor
+a `--parent`, and retires; nothing creates one any more.
 
 ## Commands and hooks
 
@@ -335,7 +359,14 @@ existing manifests load, and change nothing.
 
 Hooks receive `OATS_EVENT`, `OATS_CAPABILITY`, `OATS_LAYER`, `OATS_INSTANCE`,
 `OATS_HOME`, `OATS_AGENT`, `OATS_SOUL`, `OATS_CONTEXT`, `OATS_WORKSPACE`,
-`OATS_ROOT`, `OATS_LEVEL`, `OATS_SETTINGS`, and `OATS_META`. A final JSON line may
+`OATS_ROOT`, `OATS_LEVEL`, `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, and
+`OATS_META`. `OATS_SETTINGS_ORIGINS` (0.29.0) says where each leaf of
+`OATS_SETTINGS` came from: a JSON object from a JSON pointer to `{ kind, at }`,
+`kind` being `manifest-default`, `workspace`, `soul`, `host`, `spawn` or
+`anchor` (the last layer that set it), e.g.
+`{"/harvest":{"kind":"soul","at":"soul.yaml#/knowledge"}}`. A provider tells a
+soul-set value from a host-set one there, and never reads `soul.yaml` for it.
+A home spawned before 0.29.0 recorded none: `{}`. A final JSON line may
 return `meta`, `brief`, `warning`, or harness-specific `launch` arguments. A
 **spawn hook only** may also return an `env` object for the launched process;
 returning `env` from retire or soul-scaffold is an explicit contract error.
@@ -482,7 +513,8 @@ passed as arguments; no shell is involved.
 - Every ambient `OATS_*`, `OAS_*` and `PI_*` variable is removed. Other
   variables pass through.
 - The kernel sets:
-  - `OATS_CAPABILITY` and `OATS_SETTINGS` (the payload as JSON);
+  - `OATS_CAPABILITY`, `OATS_SETTINGS` (the payload as JSON) and
+    `OATS_SETTINGS_ORIGINS` (where each leaf came from, as hooks get it);
   - `OATS_CLI_BIN`;
   - `OATS_WORKSPACE` (the deployment);
   - the team variables `OATS_TEAM_ID` (the messaging payload's `team`: the

package/docs/capability-manifest.schema.json

@@ -262,13 +262,6 @@
       },
       "additionalProperties": false
     },
-    "agents": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Package-relative soul directories (soul.yaml + AGENTS.md) \u2014 capability-defined agents; they resolve where the capability is active, souls stay read-only in the package, instances home under <deployment>/agents/<agent>/instances/."
-    },
     "settings": {
       "type": "object",
       "description": "Declared capability settings: name to { default, values?, description }. Documentation for the values a soul, oats-local.yaml or `oats spawn --provider` supplies; undeclared settings are still accepted.",