@awebai/oats 0.27.1 → 0.28.0

package/docs/desktop-cli-api.md

@@ -54,6 +54,18 @@ something to say. The one warning so far is `deprecated-runtime-name` (see
 --json`, whose document is not an envelope, carries the same `warnings` beside
 its `problems`. In text mode the warning is one `oats: warning: …` line on stderr.
 
+## Flags
+
+A kernel command reads `--flag=value` exactly as `--flag value`, with the
+same validation (0.27.3+; before, the inline form was silently ignored, so
+`--harness=claude` spawned the default harness). The value is everything after
+the first `=`. An empty `--flag=` is `E_BAD_ARGS` ("`--flag=` needs a value"),
+and so is a value on a switch: `--yolo=false` is refused and never turns
+yolo on. A capability command's own flags belong to its provider. They are
+forwarded exactly as typed; the kernel reads only its dispatch flag (`--soul`)
+in either form. There is no feature string: a caller that must work with
+older kernels uses the spaced form.
+
 ## The harness rename (feature `harness`, OATS 0.27.0)
 
 What starts an instance (pi, claude or codex) is its **harness**. 0.27.0 renames
@@ -667,7 +679,7 @@ unchecked, echoed a stored `definition.id` without checking it, and named a
 ```
 
 **Exact shapes (API 3):**
-- `schedule list --json` → `result = {scope, scheduleApi: 2, scheduleHistoryApi: 3, integrity, schedules: Entry[], scheduler}`.
+- `schedule list --json` → `result = {scope, scheduleApi: 2, scheduleHistoryApi: 3, integrity, schedules: Entry[], triggers: {count, command: "oats trigger list"}, scheduler}` (`triggers`, 0.28.0: the trigger definitions this listing leaves out).
 - `schedule show <id> --json` → `result = {schedule: Entry}` (one level of nesting; `integrity` is NOT on `show` — it is a scope fact reported by `list`).
 - `Entry` (readable) = definition fields (`id, kind, home, message|operation, cron, enabled, …`) + `{scope, scheduleApi: 2, scheduleHistoryApi: 3, executionStatus, nextRun: ISO|null, lastRun: Run|null, history, recentRuns: Run[], running: boolean, attempt?, pendingWake?}`.
 - `Entry` (unreadable, `list` only) = `{id, scope, scheduleApi: 2, scheduleHistoryApi: 3, unreadable: {code, message}, history: {status: "corrupt", stored: null, truncated: false}, recentRuns: []}` — no definition fields.
@@ -953,6 +965,12 @@ location. The receipt says so:
   discarding the worktree (a checked-out branch cannot be deleted).
 - A failed move keeps the home and refuses `E_WORK_PRESERVATION_FAILED` —
   nothing is lost; retry or pass `--discard-worktree`.
+- When a recovery's Git status disagrees with the source's (0.27.2),
+  `E_WORK_PRESERVATION_FAILED` carries `details: {home, statusDisagreement:
+  {repo, rows: [{path, source, recovery}], total}}`. `repo` is `.` or a nested
+  repository's path. `source`/`recovery` are the porcelain `XY` codes, or
+  `null` where that side has no row. `rows` holds the first 10 paths, sorted,
+  and `total` counts all of them. The message names the same rows.
 - Non-worktree modes report `retention: null`. Quarantine/rollback paths keep
   their removal semantics.
 - A recovery (`workRecovery`, `workRecoveries[]`) is `{path, classes, bytes,
@@ -1109,8 +1127,8 @@ gate that on the absence of `packages-no-approval`.
              "souls":["tools-expert"],"capabilities":["acme-tools-dev"],"publishes":{"package":"acme.tools","version":"0.4.0"}},
             {"key":"github.com/acme/billing","name":"billing","commit":"<oid>","confirmed":false,"status":"no-backlink","detail":"github.com/acme/billing@… has no oats-membership.yaml","team":null,
              "souls":[],"capabilities":[],"publishes":null}],
- "packages":[{"id":"oats.okf","version":"2.1.3","source":"catalog:oats.okf","commit":"<oid>","integrity":"sha256-…","capabilities":["oats.okf"]},
-             {"id":"acme.tools","version":"0.4.0","source":"git:github.com/acme/tools@v0.4.0","commit":"<oid>","integrity":"sha256-…","capabilities":["acme-deploy","acme-lint"]}],
+ "packages":[{"id":"oats.okf","version":"2.1.3","source":"catalog:oats.okf","commit":"<oid>","integrity":"sha256-…","capabilities":["oats.okf"],"souls":[]},
+             {"id":"acme.tools","version":"0.4.0","source":"git:github.com/acme/tools@v0.4.0","commit":"<oid>","integrity":"sha256-…","capabilities":["acme-deploy","acme-lint"],"souls":["release-reviewer"]}],
  "changes":[{"id":"acme.tools","from":null,"to":"0.4.0","commit":"<oid>"}],
  "problems":[]}
 ```
@@ -1119,6 +1137,8 @@ gate that on the absence of `packages-no-approval`.
   `backlink-elsewhere` | `cannot-read`; `detail` explains an unconfirmed row.
   `publishes` reports a member's `oats-package/` (informational — its
   capabilities are **not** in `capabilities[]`; the non-collapse rule).
+- `packages[].souls` (feature `package-souls`, 0.28.0): the names of the
+  package souls the lock records for that package (`[]` when none).
 - `changes[]`: `from` = previously locked version or `null`; `to` = `null` when
   the package was dropped from `packages:` and from the lock.
 - `problems[]`: `{ code, path, message, repoKey? }` — per-item discovery
@@ -1201,10 +1221,23 @@ or `"unassigned"`.
  "souls":[
    {"name":"release-manager","origin":"member github.com/acme/agents @ 3f2a9c1e","kind":"member","repoKey":"github.com/acme/agents","commit":"<oid>",
     "team":"engineering","private":false,"path":"souls/release-manager","work":"worktree","description":"Cuts, verifies and announces releases."},
-   {"name":"security-reviewer","origin":"external github.com/oss-collective/experts @ 9c4e1f2a","kind":"external",…}],
+   {"name":"security-reviewer","origin":"external github.com/oss-collective/experts @ 9c4e1f2a","kind":"external",…},
+   {"name":"release-reviewer","qualifiedName":"acme.tools/release-reviewer","origin":"package acme.tools v0.4.0","kind":"package","package":"acme.tools","version":"0.4.0",
+    "repoKey":"github.com/acme/tools","commit":"<oid>","team":"engineering","labels":["engineering"],"private":false,"path":"oats-package/souls/release-reviewer","work":"directory","description":"…"}],
  "problems":[]}
 ```
 
+**Package souls** (feature `package-souls`, 0.28.0): a row with `kind:
+"package"` is a soul a locked package ships (listed only while the workspace
+declares the package). It carries `package`, `version` and `qualifiedName`
+(`<package>/<soul>`); spawn it by `qualifiedName` (the bare `name` works when
+it is unique). The Souls page shows it as "from package <id> <version>".
+Its instances home under `agents/<package>--<soul>/` (`.` in the package id
+becomes `-`), and that directory is the agent `name` in `oats status --json`
+(`agents[].name`, e.g. `oats-okf--knowledge-maintainer`). A
+problem about a package soul carries `package` (and `repoKey: null`); its
+`path` is `package:<id>:<path in the repo>`.
+
 Package capabilities of declared-but-unsynced packages are absent until `sync`.
 (`oats souls --json` keeps `soulsApi: 1` in 0.26.0: its shape is unchanged.
 The probe's `soulsApi` is **2** because it tracks the `oats inspect --json`
@@ -1255,9 +1288,13 @@ between preview and apply is `E_DECISION_STALE`):
   key**: legal only at the top level of the workspace file's `messaging:`;
   anywhere else in any payload layer (soul, `oats-local.yaml` `settings`,
   `--provider`, at any depth) it is `E_WORKSPACE_SCHEMA { reason: "reserved-key", path, key }`.
-- Soul lookup: `E_SOUL_UNKNOWN { name, members[] }` (not among confirmed
-  members or externals), `E_SOUL_AMBIGUOUS { name, repos[] }` (name it
-  `<repo>/<soul>`). Resolution errors keep their codes (`E_NOT_A_MEMBER`,
+- Soul lookup: `E_SOUL_UNKNOWN { name, members[], packages[] }` (not among
+  confirmed members, externals or package souls), `E_SOUL_AMBIGUOUS { name,
+  repos[], qualified[] }` (name one of `qualified`: `<member>/<soul>` or
+  `<package>/<soul>`), `E_SOUL_DISABLED { name, qualifiedName, entry }` (the
+  soul is in `oats-local.yaml` `souls.disabled`). A package soul whose fetched
+  content does not match the lock is `E_PACKAGE_INTEGRITY { why:
+  "soul-digest", package, soul, locked, observed }`. Resolution errors keep their codes (`E_NOT_A_MEMBER`,
   `E_MEMBERSHIP_UNCONFIRMED { repoKey, reason }`, `E_CAPABILITY_MISSING { hint? }`,
   `E_CAPABILITY_PRIVATE`, `E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY { why: "capabilities", listed, locked }`,
   `E_SLOT_CONFLICT { slot, modules[], reason? }`, `E_SKILL_DUPLICATE { name, modules[] }`,
@@ -1280,6 +1317,7 @@ Written by materialization inside the spawn transaction; read back by
  "providers":{"acme-release-tooling":{},"oats.okf":{"owns":"release-manager","reads":["platform-engineer"],"state-dir":"/Users/ana/.oats/okf"}},
  "workspace":{"key":"github.com/acme/agents","name":"acme","deployment":"/Users/ana/acme-workspace","commit":"<oid>","resolution":"<24 hex>","standalone":false,
               "soul":{"repoKey":"github.com/acme/agents","commit":"<oid>","team":"engineering"}},
+ "…":"a package soul's workspace.soul also records package: {id, version, commit, digest, path}, and its id is package:<id>#<soul>",
  "capabilities":[{"id":"oats.okf","capability":"oats.okf","origin":"package:oats.okf@2.1.3","…":"one row per module"}]}
 ```
 
@@ -1335,6 +1373,60 @@ top-level `workspace` reachability field:
   `oats-local.yaml` has no `workspace` field and `modules` as recorded.
 - Text mode prints `modules: <cap> from <member|package …> @ <7-char>` lines
   for non-current modules (`--verbose` for all).
+- `instances[].soul` is the soul source's drift: `{ repoKey, commit, current,
+  status, reason? }`. For a **package soul** (feature `package-souls`) it also
+  carries `package`, `version` and `currentVersion`; `moved` means the package
+  pin moved (another version/commit is locked now), `missing` has `reason`
+  `package-absent` (no longer locked or declared) or `soul-absent` (the locked
+  package no longer ships it). Text: `soul: <name> from package <id> v<version>
+  @ <7-char>  [package moved since (now v<version> @ <7-char>)]`.
+
+### Triggers (feature `triggers`, OATS 0.28.0) — `oats trigger … --json` → `triggerApi: 1`
+
+Event-driven spawns of a deployment ([schedules.md#triggers](schedules.md#triggers)).
+Definitions live in `oats-schedules.json` (`kind: "trigger"`); `oats schedule list`
+does not show them.
+
+```json
+{"triggerApi":1,"scope":"/abs/deployment","triggers":[
+  {"id":"okf-harvest-review","enabled":true,"kind":"trigger",
+   "on":{"source":"github.pull_request","repo":"github.com/acme/knowledge","events":["opened","reopened","ready_for_review"],"labels":["okf-harvest"],"base":"main","poll":"2m"},
+   "spawn":{"soul":"oats.okf/knowledge-maintainer","purpose":"review-pr-{number}","task":"…","teams":["okf"],"harness":"claude","model":"opus"},
+   "concurrency":{"max":2,"perKey":1},"template":{"package":"oats.okf","version":"4.0.0","commit":"<oid>","template":"harvest-review"},
+   "triggerApi":1,"scope":"/abs/deployment","createdAt":"<iso>","updatedAt":"<iso>"}]}
+```
+
+- `list` → the document above; `show <id>`, `add`, `enable`, `disable` →
+  `{ trigger }` (one row); a stored definition that no longer validates carries
+  `invalid: { code, message }`. `remove <id>` → `{ removed, live: [instance] }`.
+- `status [<id>]` → `{ triggerApi, scope, triggers: [{ id, enabled, repo, soul,
+  lastPoll: { at, ok, prs, matching } | { at, ok: false, error } | null,
+  nextPollAt, pending: [{ key, event, number, url, observedAt }], fired: [{ key,
+  at, instance, home, event, number }] (newest 50), firedTotal, live: [{
+  instance, home, repo, number, event }], lastError: { at, code, message, key? } | null }] }`.
+- `test <id>` → `{ triggerApi, id, ok, gh: { ok, account, credentialSource:
+  "keyring" | "config" | "env:<VAR>" | "unknown" | null, reachesHostTimer:
+  boolean | null, note, detail }, repo: { key,
+  readable, fullName, permissions: { push, maintain, admin }, canMerge } |
+  { key, readable: false, error }, soul: { resolves, name, agent, messaging } |
+  { resolves: false, name, error }, teams: { requested, undeclared | null,
+  messaging }, wouldFire: [{ key, event, number, url, held? }], pollError?, problems:
+  [string], warnings: [string], spawned: false }`. It writes nothing. `ok`
+  counts `problems` only; a credential the host timer cannot reach
+  (`reachesHostTimer: false`) is a warning.
+- `oats schedule list --json` gains `triggers: { count, command: "oats trigger
+  list" }`: the triggers it does not list.
+- The tick's `considered[]` gains trigger rows `{ workspace, trigger, action,
+  … }` with `action` `not-due`, `poll-failed`, `polled` (`prs`, `matching`;
+  nothing to fire), `held`, `fired` (`key`,
+  `instance`, `home`), `spawn-failed` (`key`, `code`, `error`), `would-fire`
+  (`--dry-run`) or `invalid`.
+- A triggered instance's `instance.json.trigger` is `{ id, key, source, repo,
+  number, url, event, headSha, observedAt, eventFile }`; the event file is
+  `OATS_TRIGGER_EVENT_FILE`.
+- Errors: `E_TRIGGER_INVALID { field }`, `E_TRIGGER_EXISTS`,
+  `E_TRIGGER_UNKNOWN`, `E_BAD_ARGS` (`missing` / `parameters` for a template),
+  `E_PACKAGE_MISSING`, `E_PACKAGE_MANIFEST`, `E_LOCAL_MISSING`.
 
 ### Eligible teams (feature `teams`, OATS 0.26.0)
 

package/docs/oats-local.schema.json

@@ -69,9 +69,10 @@
       "additionalProperties": false,
       "properties": {
         "disabled": {
+          "description": "Souls not run on this machine (a spawn is E_SOUL_DISABLED): a bare soul name disables every soul of that name; a qualified name disables one — <package>/<soul> for a package soul, <member name>/<soul> for a member's.",
           "type": "array",
           "uniqueItems": true,
-          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+          "items": { "type": "string", "pattern": "^(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*$" }
         }
       }
     }

package/docs/oats-package.schema.json

@@ -53,6 +53,45 @@
       },
       "uniqueItems": true
     },
+    "souls": {
+      "description": "Package souls (OATS 0.28.0): package-relative soul directories, each an ordinary soul (soul.yaml + AGENTS.md, optional skills/). A soul's name is its directory's. They are versioned and locked with the package (oats-lock.json records each soul's name, path and digest), listed with their package origin, and spawned by the qualified name <package>/<soul> (or the bare name when unique). `from: here` in a package soul is its own package at the locked commit.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[^/].*$",
+        "not": {
+          "pattern": "(^|/)\\.\\.(/|$)"
+        }
+      },
+      "uniqueItems": true
+    },
+    "triggers": {
+      "description": "Trigger templates (OATS 0.28.0): `oats trigger add --from <package>:<id> [--set <name>=<value>]…` instantiates one from the locked package. Each file is { parameters: { <name>: { path, required?, default?, description? } }, definition: { …a trigger definition… } }; see docs/schedules.md#triggers.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "file"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9._-]*$"
+          },
+          "file": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^/].*$",
+            "not": {
+              "pattern": "(^|/)\\.\\.(/|$)"
+            }
+          }
+        }
+      }
+    },
     "configTemplates": {
       "description": "Named config TEMPLATES: complete reference oats-config.yaml files of the classic line, whose adoption verb is removed under the workspace model. A template is a recommended starting point that becomes ordinary local policy on adoption — adopters may change every copied setting, and package updates never rewrite an adopted config. Templates must stay portable: no secret, credential, account, machine path or provider-local ID. Installation applies none of them. This is the canonical spelling; a manifest may not carry both this and the legacy `configs`.",
       "type": "object",

package/docs/packages.md

@@ -27,7 +27,9 @@ A Git repository **contains** a package at `oats-package/`:
 ```
 
 `oats-package.json` must declare `package` and `capabilities` (a list of
-directories relative to the package root, each holding an `oats.json`). A
+directories relative to the package root, each holding an `oats.json`). It may
+also declare `souls` (0.28.0): soul directories the package ships, see
+[Package souls](#package-souls). A
 directory entry need not equal the capability's name
 (`capabilities/oats-okf` → capability `oats.okf`). A package declaring one
 capability name twice, a listed directory without a manifest, or a manifest
@@ -73,7 +75,7 @@ members:
   - git:github.com/acme/platform
 packages:
   oats.framework: v1.1.3
-  oats.okf: v2.1.5
+  oats.okf: v3.0.0
   oats.aweb: v1.14.2
 teams:
   global: { description: Org-wide }
@@ -172,7 +174,8 @@ same workspace commit hold identical locks.
       "version": "0.4.0",
       "commit": "47f4b81660e4cc9701d373088de52462762585a3",
       "integrity": "sha256-4cd126a7…",
-      "capabilities": ["acme-deploy", "acme-lint"]
+      "capabilities": ["acme-deploy", "acme-lint"],
+      "souls": [{ "name": "release-reviewer", "path": "souls/release-reviewer", "digest": "sha256-9a0f…" }]
     }
   }
 }
@@ -187,6 +190,7 @@ same workspace commit hold identical locks.
 | `commit` | full 40-hex OID the version resolved to |
 | `integrity` | `sha256-<hex>` content digest of the package tree at `path` |
 | `capabilities` | the capability names the package provides (sorted) — what `from: package` looks up |
+| `souls` | the package souls (0.28.0), sorted by name: `name`, `path` (inside the package) and `digest` (`sha256-<hex>` of the soul directory); absent when the package ships none |
 
 A capability provided by **two** locked packages is ambiguous and fails
 closed (`E_PACKAGE_MISSING { ambiguous: [ids] }`): keep one of them in
@@ -220,6 +224,66 @@ against what the fetch reported; skills are copied to
 `packages:` and syncing affects **only new spawns**; `oats status` shows a
 running instance's package module as `moved` once the lock points elsewhere.
 
+## Package souls
+
+A package may ship **souls** as well as capabilities (0.28.0). One pin in
+`packages:` then versions both: nothing drifts, unlike an `external:` soul's
+commit pin.
+
+```
+oats-package/
+├── oats-package.json      # { …, "capabilities": ["capabilities/acme-review"], "souls": ["souls/release-reviewer"] }
+├── capabilities/acme-review/oats.json
+└── souls/release-reviewer/
+    ├── soul.yaml          # an ordinary soul: name = the directory's name
+    ├── AGENTS.md
+    └── skills/…
+```
+
+- **Locked.** `oats sync` records each soul's `name`, `path` and `digest` in
+  the lock entry. A soul without `soul.yaml` or `AGENTS.md`, or whose
+  directory is not a soul name, is `E_PACKAGE_MANIFEST`. On a later sync at
+  the same version the souls must still match (`E_PACKAGE_INTEGRITY { why:
+  "souls" }`); a lock written before 0.28.0 has its `souls` filled in.
+- **Listed.** `oats souls` lists a package soul with `kind: "package"`,
+  `package`, `version`, `qualifiedName` and `origin: "package <id>
+  v<version>"`; `oats sync` / `oats workspace status` list each package's
+  `souls`. Only packages the workspace still declares are listed.
+- **Named.** The qualified name is `<package>/<soul>` (`oats.okf/knowledge-maintainer`).
+  A bare name works when it is unique across member, external and package
+  souls; otherwise `E_SOUL_AMBIGUOUS` names each qualified form
+  (`details.qualified`). A member soul's qualified form is `<member name>/<soul>`.
+- **Resolved** like any soul: the workspace and team defaults apply, `off` and
+  `<slot>: none` work, every `team:` label must be declared (`E_TEAM_UNKNOWN`
+  in discovery), and `from: here` means **this package** at the locked commit
+  (a capability it does not provide is `E_CAPABILITY_MISSING`).
+- **Spawned** at the locked commit: the soul is fetched into the per-commit
+  soul cache and its digest must equal the lock's (`E_PACKAGE_INTEGRITY
+  { why: "soul-digest" }`). A package soul homes in its own agent directory,
+  `agents/<package>--<soul>/` (the package id with `.` as `-`:
+  `agents/oats-okf--knowledge-maintainer/`), which is also its agent name
+  (`OATS_AGENT`, the `oats status` row); its instances are named from it
+  (`oats-okf-knowledge-maintainer-<purpose>`). A soul name never holds `--`,
+  so a member soul of the same bare name keeps its own `agents/<soul>/`.
+  Two packages whose ids sanitise alike (`a.b`, `a-b`) and that ship a
+  same-named soul would share a directory: both are listed with an
+  `E_SOUL_AMBIGUOUS` problem, and spawning either is `E_SOUL_AMBIGUOUS
+  { agentDir, qualified }` — keep one of the packages.
+  `instance.json.workspace.soul` records `name`, `qualifiedName`, `package:
+  { id, version, commit, digest, path }` and the soul id `package:<id>#<soul>`;
+  in `oats status` the soul is `moved` once the package pin moves.
+- **Disabled** by `oats-local.yaml` `souls.disabled` by its qualified or bare
+  name (`E_SOUL_DISABLED` at spawn).
+- **Trusted** as the package's capabilities are: declaring the package is the
+  trust decision.
+
+## Trigger templates
+
+A package may also ship **trigger templates** (0.28.0): `triggers: [{ id,
+file }]` in `oats-package.json`, each file `{ parameters, definition }`.
+`oats trigger add --from <package>:<id> --set <name>=<value>` instantiates one
+at the locked commit; see [schedules.md#triggers](schedules.md#triggers).
+
 ## Compatibility floors
 
 A soul may state floors on package versions — constraints, not sources:

package/docs/release-notes/v0.27.2.md

@@ -0,0 +1,51 @@
+# OATS 0.27.2
+
+## Fixed
+
+- **Retiring a worktree instance whose repository excludes paths locally.**
+  Retire refused with `E_WORK_PRESERVATION_FAILED` ("recovered Git
+  index/status disagreed with the source") when the repository ignored a path
+  only through its local rules: the common Git directory's `info/exclude`, or
+  a `core.excludesFile` set in the repository's config. The recovery clone had
+  neither, so such a path was ignored (`!!`) in the source but untracked, or
+  absent for an empty directory, in the clone. Preservation runs before the
+  retire hooks and `--force` does not bypass it, so the instance could not be
+  retired and its identities were never revoked. The recovery now carries
+  those patterns into its own `.git/info/exclude` (nested repositories too),
+  and `recovery.json` lists them under `excludes`
+  (`[{ repo, kind, path }]`).
+  When a recovery's status still disagrees, the refusal now **names the
+  differing rows** from both sides, for example
+  `.scratch/ (source !!, recovery absent)`: the first 10, then
+  `; and N more`. Under `--json` they are in
+  `details.statusDisagreement` (`{repo, rows: [{path, source, recovery}],
+  total}`; see [desktop-cli-api.md](../desktop-cli-api.md)).
+  **On an older kernel:** remove the disposable paths that
+  `git -C <home>/work status --porcelain --ignored=matching` lists as `!!`
+  before retiring.
+
+- **Retiring a worktree instance whose repository changes how status reads
+  its files.** The recovery clone probed its own settings and lacked the
+  common Git directory's `info/attributes`. A repository with, for example,
+  `core.fileMode=false` and a mode-only change was clean in the source but
+  ` M` in the clone, so retire refused. The recovery now takes the source's
+  `core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`,
+  `core.symlinks`, `core.autocrlf` and `core.eol` (set, or unset where the
+  source leaves them unset) and its `info/attributes`, nested repositories
+  included. `recovery.json` lists them under `statusConfig`
+  (`[{ repo, kind: "config", key, value } | { repo, kind: "info/attributes", path }]`).
+
+## Known limitations
+
+- The bundled oats.okf is still 2.1.5 (its harvest answers one `deprecated-runtime-name` warning per spawn; harmless). oats.okf 2.1.6 follows in a later patch.
+
+- **A `core.attributesFile` or filter driver set in the repository's own
+  config is not carried** into a recovery. Merging its patterns would change
+  their precedence, and a pointer would tie the recovery to a host file. Such
+  a repository can still make retire refuse, and the refusal names the rows.
+  Workaround: commit or restore the files it re-reads before retiring.
+
+## Documentation
+
+- `oats retire --force` does **not** skip work preservation
+  ([souls-and-instances.md](../souls-and-instances.md#retire)).

package/docs/release-notes/v0.28.0.md

@@ -0,0 +1,144 @@
+# OATS 0.28.0
+
+Package souls, triggers, okf 3.0.0 remote knowledge consult, and the Workspace v4 Desktop.
+
+## Added
+
+- **Package souls** (feature `package-souls`). A package may ship souls as
+  well as capabilities: `souls: ["souls/<name>", …]` in
+  `oats-package/oats-package.json`, each an ordinary soul directory
+  (`soul.yaml`, `AGENTS.md`, `skills/`). One pin in the workspace's
+  `packages:` versions both, so a package soul never drifts the way an
+  `external:` commit pin can. See [packages.md](../packages.md#package-souls).
+  - `oats sync` locks each soul's `name`, `path` and `digest` in the package's
+    lock entry and checks them again on the next sync
+    (`E_PACKAGE_INTEGRITY { why: "souls" }`). A soul without `soul.yaml` or
+    `AGENTS.md` is `E_PACKAGE_MANIFEST`. A lock written by an earlier kernel
+    has its `souls` filled in on the next sync.
+  - `oats souls` lists them with `kind: "package"`, `package`, `version` and
+    `qualifiedName`; `oats sync` and `oats workspace status` list each
+    package's `souls`.
+  - Spawn one by its qualified name `<package>/<soul>`
+    (`oats spawn oats.okf/knowledge-maintainer`), or by its bare name when that
+    is unique. A bare name shared by several souls is `E_SOUL_AMBIGUOUS`, which
+    now names each qualified form (`details.qualified`); a member soul's is
+    `<member name>/<soul>`.
+  - A package soul resolves like any soul: workspace and team defaults apply,
+    `off` and `<slot>: none` work, its `team:` labels must be declared, and
+    `from: here` means its own package at the locked commit.
+  - The spawn fetches the soul at the locked commit and verifies it against the
+    lock's digest (`E_PACKAGE_INTEGRITY { why: "soul-digest" }`). It homes in
+    its own agent directory `agents/<package>--<soul>/`
+    (`agents/oats-okf--knowledge-maintainer/`), its agent name in `oats status`
+    and `OATS_AGENT`, so a member soul of the same bare name never shares its
+    directory or roster row. `instance.json.workspace.soul` records `name`,
+    `qualifiedName` and `package: { id, version, commit, digest, path }`, and
+    the soul id is `package:<id>#<soul>`. `oats status` shows the soul as
+    `moved` once the package pin moves. Two packages whose ids differ only by
+    `.` and `-` (`a.b`, `a-b`) and that ship a same-named soul would share an
+    agent directory: that is an `E_SOUL_AMBIGUOUS` problem in `oats sync` and
+    `oats souls`, and neither spawns.
+
+- **Triggers** (feature `triggers`): event-driven spawns. A trigger says
+  "when a GitHub pull request event matches, spawn a new instance of this soul
+  with this task, in these teams". It is stored beside the schedules
+  (`kind: "trigger"` in `oats-schedules.json`) and evaluated by the same host
+  tick; there is no daemon or webhook. See
+  [schedules.md#triggers](../schedules.md#triggers).
+  - The source `github.pull_request` is polled with the host's `gh` at the
+    trigger's `poll` interval (at least 1m). Events: `opened`, `reopened`,
+    `ready_for_review`, `labeled`, `synchronize`, filtered by `labels` and
+    `base`.
+  - Each event fires once: its key is recorded only after a successful spawn,
+    so a failed spawn is retried on the next poll. Delivery is at least once: a
+    tick that dies between the spawn and recording its key spawns the event
+    again (held while the first instance is live, under the default `perKey: 1`). `concurrency.max` and
+    `perKey` bound the live instances of the trigger and of one PR.
+  - The purpose and task are templated from `{repo} {number} {url} {event}
+    {headSha} {trigger}` only; a PR's title and body never reach the task.
+    `spawn.teams` becomes the messaging capability's `join=`. The instance gets
+    the event as `OATS_TRIGGER_EVENT_FILE` (`<home>/.oats/trigger-event.json`)
+    and records `instance.json.trigger`.
+  - `oats trigger add (--file | --from <package>:<template> --set …) | list |
+    show | enable | disable | remove | test | status`, all with `--json`.
+    `oats trigger test` checks gh auth and where its credential comes from
+    (warning when the host timer cannot reach it, such as a shell-only
+    `GH_TOKEN`), the repository and your push/maintain/admin permissions on it,
+    the soul, the teams, and what would fire now, and spawns nothing.
+    `oats schedule list` counts the triggers it does not list.
+  - A package may ship trigger templates (`triggers: [{ id, file }]` in
+    `oats-package.json`).
+  - `oats spawn --trigger-event <file>` is how a trigger hands the event to the
+    spawn.
+
+## Fixed
+
+- **`--flag=value` is read.** Every kernel command ignored the inline form
+  silently: `oats spawn dev --harness=claude` spawned the default harness,
+  and `--name=x`, `--runtime=x`, `--dir=x` and `--server=x` were dropped the
+  same way. A kernel command now reads `--flag=value` exactly as
+  `--flag value`, with the same validation. The value is everything after the
+  first `=`. Two inline forms are refused with `E_BAD_ARGS`: an empty
+  `--flag=`, and a value on a switch. `--yolo=false` is refused and never
+  turns yolo on. A capability command's own flags are its provider's: they
+  are forwarded exactly as typed, and the kernel reads only its dispatch flag
+  (`--soul`) in either form. `oats capture`, `recall` and `setup` parse their
+  own arguments, as before. See
+  [desktop-cli-api.md § Flags](../desktop-cli-api.md#flags).
+  **On an older kernel:** use the spaced form.
+
+- **`oats-local.yaml` `souls.disabled` is enforced at spawn.** It was documented
+  as "not run on this machine", but only counted souls in the `oats sync`
+  report. A listed soul is now refused with `E_SOUL_DISABLED { name,
+  qualifiedName, entry }`. An entry is a bare name (every soul of that name) or
+  a qualified name (`oats.okf/knowledge-harvester`, `<member>/<soul>`).
+
+## oats.okf 3.0.0 (catalog pin and bundled mirror)
+
+The official catalog now pins `oats.okf` to `v3.0.0` (tag object `ad2349c7`,
+commit `76f7ccdb`). The copy bundled in this package is its byte mirror. The
+package declares `oats >=0.26.0`.
+
+- **Knowledge is consulted remotely.** An instance reads its soul's knowledge
+  at the accepted state through new commands: `oats okf bases`, `index`,
+  `cat --base <alias> <path>`, `ls`, `links` and `search`. A Git base is served
+  from one host-wide partial clone per base, and a read refetches the accepted
+  branch once the cached commit is older than the `consult-max-age` setting
+  (seconds; default 300; `0` refetches on every read). `--fresh` always
+  refetches. If the fetch fails, the read is served from the cache, with
+  `stale: true` and the reason in its receipt.
+  A directory base is read in place. The new `okf-consultation` skill and the
+  okf injection teach instances to run `oats okf index` at the start of every
+  task.
+- **BREAKING: no `./knowledge/` in homes.** A spawn records the accepted
+  resolution and materializes no `./knowledge/` directory or view. Anything
+  that read `<home>/knowledge/bases/<alias>/…` reads
+  `oats okf cat --base <alias> <path>` instead.
+- **BREAKING: `oats okf refresh` is `E_REMOVED`.** There are no per-instance
+  views to refresh.
+- **`oats okf read --path` still works** in 3.0.0, as an alias of `cat`.
+- **Older homes:** a `./knowledge/` a 2.x spawn left in a home is not touched.
+  3.0.0 ignores it, and `oats okf inspect` reports it as
+  `legacy-local-view`.
+- The memory-harvest worker soul no longer ships a `CLAUDE.md -> AGENTS.md`
+  symlink (npm drops symlinks, and the kernel composes each home's
+  `CLAUDE.md`). The mirror check (`scripts/check-okf-mirror.mjs`) no longer
+  requires one; any symlink a future release ships is mirrored and verified
+  as before.
+
+## Desktop
+
+- **Workspace v4 redesign** (#206): the Workspace area (Setup, Souls, Capabilities, the soul and capability pages) is rebuilt to the Workspace v4 design. Facts the kernel does not report yet are left out rather than guessed; the Setup screen no longer names kernel files.
+- **Soul team labels** reach the Souls grid (#208).
+
+## Tests and CI
+
+- A home's resolved view (`resolvedFromHome`) carrying the slot rows its
+  spawn recorded (`layers`, since 0.26.0 layers-from) is now pinned. Before,
+  no test caught reverting it to `{}`.
+- CI runs the suite in six parallel shards (`node --test --test-shard`), plus a gate job with the old check name. Main runs no longer cancel each other.
+
+## Upgrading
+
+- **okf 3.0.0 is breaking for anything that read `<home>/knowledge/`.** Use `oats okf cat`. Existing homes keep their old view, unused.
+- **Package souls and triggers are additive.** Nothing changes until a package declares `souls:`/`triggers:`, or you add a trigger.