@awebai/oats 0.27.2 → 0.29.0

package/capabilities/oats-okf-maintenance/skills/okf-authoring/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: okf-authoring
+description: >-
+  Open Knowledge Format (OKF) authoring craft for knowledge-operations souls:
+  how to write, edit, move and validate concepts in an OKF bundle (markdown
+  concepts with YAML frontmatter, per Google Cloud's OKF v0.1 spec), keep
+  index.md and log.md honest, supersede instead of silently rewriting, and run
+  the bundled validator. Use when staging or amending concepts in a knowledge
+  base, fixing index/log entries, reviewing a knowledge PR's Markdown, or when
+  asked to validate a bundle. Promotion judgment (what belongs in a base) is
+  the knowledge-theory skill.
+---
+
+# OKF craft — author, maintain, consume
+
+An OKF **bundle** is a directory tree of markdown files. Each non-reserved `.md`
+file is **one concept**; links between files form the knowledge graph. No
+database, no SDK — plain git-versionable text. Spec: OKF v0.1 (Google Cloud).
+An external base is one bundle and link namespace. Owned nodes are
+nonoverlapping subdirectories, not separate root-link namespaces. Instance
+`notes/` files are task-local concepts; no knowledge lives in the soul.
+
+## The format in one screen
+
+- **Concept = one file.** Concept ID = path minus `.md`. Small and specific
+  beats long and general — split rather than grow.
+- **Frontmatter** (`---` delimited): only **`type`** is required (short,
+  freeform — the spec ships no vocabulary. Fleet core: `Lesson`, `Decision`,
+  `Playbook`, `Reference`; souls also grow role-specific types like
+  `Area Guide` or `Roadmap` — see the knowledge-theory skill for routing).
+  Recommended,
+  in order: `title`, `description` (ONE sentence — it's what index listings
+  and skimming agents see), `resource` (URI, only if a real asset backs the
+  concept), `tags` (YAML list), `timestamp` (ISO date of last meaningful change).
+- **Links** are ordinary markdown, keep the `.md`, prefer bundle-root-absolute:
+  `[clearing playbook](/node/playbooks/clearing-fields.md)`. Links are untyped
+  directed edges; the surrounding prose carries the relationship's meaning.
+- **Reserved files** at any level: `index.md` (navigation) and `log.md`
+  (history). They carry **no `type`**; only the bundle-root `index.md` may
+  have frontmatter, and only `okf_version: "0.1"`.
+- **Conventional headings** when applicable: `# Schema`, `# Examples`,
+  `# Citations` (numbered external sources backing claims).
+
+## Honesty rules (non-negotiable)
+
+- **Never invent** a `resource`, `timestamp`, or `description` — leave a field
+  out rather than guess it.
+- Every claim you write down should be something you verified or observed;
+  cite sources under `# Citations` when the claim came from outside.
+- Never create a link to a concept you didn't create or verify exists —
+  except deliberate not-yet-written knowledge, which is allowed by spec but
+  should be rare and intentional.
+- **Supersede, don't silently rewrite.** When a concept's meaning changes,
+  update it AND log the change; when it's wrong, correct it and say so in
+  log.md (`**Fix**: …`). History must stay reconstructible.
+
+## Maintaining a bundle
+
+**Adding a concept:**
+1. Write the file in the right section dir with valid frontmatter.
+2. Link it to/from related concepts (edit those files' bodies).
+3. Add a line to the section's `index.md`: `* [Title](file.md) - description`.
+4. Append to the bundle's `log.md` (see conventions below).
+
+**Renaming/moving a concept:** update **every inbound link** — search the
+whole bundle for the old path (`grep -rn "old-name.md" <bundle>`) — EXCEPT
+links inside historical `log.md` entries: never rewrite log history; dangling
+links there are expected.
+
+**Removing:** delete the file, remove its index.md line, fix inbound links,
+log a `**Removal**` or `**Deprecation**` entry saying why.
+
+**log.md conventions** (newest first, `## YYYY-MM-DD` headings):
+`* **Creation|Update|Removal|Fix|Deprecation|Harvest|Triage**: prose with
+[links](/path.md).` One line per event; the bold word makes logs greppable.
+
+**index.md discipline:** every concept reachable from an index; descriptions
+in listings match the concept's frontmatter `description`. Indexes are
+navigation, not content — keep them to listings.
+
+## Consuming a bundle (answering from knowledge)
+
+1. **Index-first, always.** Start at the root `index.md`; follow only links
+   relevant to the question. Never bulk-read a bundle — progressive
+   disclosure is the point of the format.
+2. Frontmatter (`type`, `tags`, `description`) is the quick filter layer;
+   open bodies only for concepts that survive the filter.
+3. `log.md` answers "what changed recently" — check it when freshness matters.
+4. Cite concepts by path when reporting answers.
+5. Tolerate imperfect concepts: unknown types and stale links are
+   never a reason to reject or ignore a bundle — that permissiveness is spec.
+
+## Validating
+
+Run the bundled validator (node, no deps) after non-trivial maintenance:
+
+```bash
+node <skill-dir>/scripts/okf-validate.mjs <bundle-dir>            # conformance
+node <skill-dir>/scripts/okf-validate.mjs <bundle-dir> --strict   # + producer lints
+```
+
+- **Conformance errors** (must fix): unparseable/missing frontmatter, missing
+  or empty `type`, reserved files carrying a `type`.
+- **Producer lints** (`--strict`, should fix in bundles you produce): broken
+  intra-bundle links (log.md exempt), links missing `.md`, concepts
+  unreachable from any index.md, missing `title`/`description`.
+
+Lints in a bundle you're *consuming* are noise — read on regardless.
+
+## Portable source and store declarations
+
+When the portable binding interface is active (planned OATS >=0.24.0; not yet a
+published provider baseline), treat the source declaration as policy and the
+captured ProviderBinding as execution authority:
+
+- In `oats.okf.locations@1`, `fixed` is source-owned, `default` is rebindable,
+  and `inherit` requires an external binding such as `write.default`.
+- Qualify every read and owned node by its declared store. A read grants no
+  write authority. Never infer the sole readable store as a destination.
+- Workspace store envelopes put concrete provider choices under
+  `payload.bindings`. Workspace, adoption, and operator values remain separate
+  inputs to the shared resolver; OKF does not select their precedence.
+- Durable placement is explicit selected settings: physical absolute
+  `bindings-file` and `state-dir`, plus selected `harvest-runtime`, optional
+  `harvest-model` and optional `git-timeout` (seconds for remote Git
+  operations, default 600). Never derive state from an instance home.
+- Provider codecs run only after exact retained executable approval. Their
+  populated binding is not proof of readiness, enrollment, credentials, privacy
+  or publication authority. Respect typed non-ready results.
+- Captured source descriptors freeze binding/runtime/source identity. Later
+  reads and workers use those bytes after source/config deletion. Never replace
+  them with today's soul, workspace, settings or bindings file.
+- `responsibleHuman: null` means messaging was explicitly disabled. Missing is
+  unknown, not disabled.
+- New captured source schedules are definition v2 with `capture`, explicit
+  deployment/resolution selectors and saved `--json`; they do not use `--soul`.
+- Captured `setup`, `init`, `migrate`, and `unlock` are deliberate refusals.
+  Provisioning/migration remains a separate explicit operator path.
+
+The broker-owned `binding-normalize`, `binding-bind`, and `binding-check`
+manifest commands are not manual recipes. Do not invoke them from a working
+agent or copy transient `OATS_BINDING_FILE`/`OATS_SOURCE_RECEIPT_FILE` paths.
+Those private mode-0600 files exist only for one synchronous captured invocation.
+
+## External bases and native tools
+
+A harvester stages writes with native file tools only under the roots listed
+in work/staging.json. A maintainer amends a PR branch in its own checkout.
+Either way, validate the WHOLE base, not an isolated node: absolute Markdown
+links can cross node boundaries. The harvester's completion command validates
+again and refuses any errors or producer warnings.

package/capabilities/oats-okf-maintenance/skills/okf-authoring/scripts/okf-validate.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * okf-validate.mjs — OKF v0.1 bundle validator (no dependencies).
+ *
+ * Usage: node okf-validate.mjs <bundle-dir> [--strict] [--json]
+ *
+ * Conformance (errors): frontmatter parses; non-empty `type` on concepts;
+ * reserved files (index.md, log.md) carry no `type`.
+ * Producer lints (--strict, warnings): broken intra-bundle links (log.md exempt),
+ * links missing .md, concepts unreachable from any index.md, missing title/description.
+ * Exit: 0 conformant, 1 errors (or warnings with --strict), 2 usage.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve, dirname, posix } from "node:path";
+
+const args = process.argv.slice(2);
+const strict = args.includes("--strict");
+const asJson = args.includes("--json");
+const dir = args.find((a) => !a.startsWith("--"));
+if (!dir || !existsSync(dir)) { console.error("usage: okf-validate.mjs <bundle-dir> [--strict] [--json]"); process.exit(2); }
+const root = resolve(dir);
+
+const files = [];
+(function walk(d) {
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    if (e.name.startsWith(".")) continue;
+    const p = join(d, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (e.name.endsWith(".md")) files.push(p);
+  }
+})(root);
+
+const errors = [], warnings = [];
+const rel = (p) => relative(root, p).split("\\").join("/");
+const isReserved = (p) => ["index.md", "log.md"].includes(posix.basename(rel(p)));
+
+function parseFrontmatter(text) {
+  if (!text.startsWith("---")) return { present: false };
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+  if (!m) return { present: true, parsed: false };
+  const meta = {};
+  for (const line of m[1].split("\n")) {
+    if (/^\s*#/.test(line) || !line.trim()) continue;
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (kv) meta[kv[1]] = kv[2].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "").trim();
+    else if (!/^\s+/.test(line)) return { present: true, parsed: false };
+  }
+  return { present: true, parsed: true, meta, body: text.slice(m[0].length) };
+}
+
+const concepts = new Map(); // rel path -> { meta, body }
+for (const f of files) {
+  const r = rel(f);
+  const text = readFileSync(f, "utf8");
+  const fm = parseFrontmatter(text);
+  if (isReserved(f)) {
+    if (fm.present && fm.parsed && fm.meta.type) errors.push(`${r}: reserved file must not carry a 'type'`);
+    if (fm.present && fm.parsed && posix.basename(r) === "index.md" && r !== "index.md") {
+      const keys = Object.keys(fm.meta);
+      if (keys.some((k) => k !== "okf_version")) warnings.push(`${r}: only the bundle-root index.md may carry frontmatter`);
+    }
+    concepts.set(r, { reserved: true, body: fm.parsed ? fm.body : text });
+    continue;
+  }
+  if (!fm.present) { errors.push(`${r}: missing YAML frontmatter`); continue; }
+  if (!fm.parsed) { errors.push(`${r}: unparseable YAML frontmatter`); continue; }
+  if (!fm.meta.type) errors.push(`${r}: missing or empty required field 'type'`);
+  if (strict) {
+    if (!fm.meta.title) warnings.push(`${r}: missing recommended field 'title'`);
+    if (!fm.meta.description) warnings.push(`${r}: missing recommended field 'description'`);
+  }
+  concepts.set(r, { meta: fm.meta, body: fm.body });
+}
+
+if (strict) {
+  // Link checks (log.md bodies exempt) + reachability from index files.
+  const reachable = new Set();
+  const linkRe = /\[[^\]]*\]\(([^)\s]+)\)/g;
+  const resolveLink = (fromRel, target) => {
+    if (/^[a-z]+:\/\//i.test(target) || target.startsWith("mailto:")) return null; // external
+    const clean = target.split("#")[0];
+    if (!clean) return null;
+    const abs = clean.startsWith("/")
+      ? posix.normalize(clean.slice(1))
+      : posix.normalize(posix.join(posix.dirname(fromRel), clean));
+    return abs;
+  };
+  for (const [r, c] of concepts) {
+    const body = c.body ?? "";
+    const fromLog = posix.basename(r) === "log.md";
+    for (const m of body.matchAll(linkRe)) {
+      const t = resolveLink(r, m[1]);
+      if (t === null) continue;
+      const isDir = t.endsWith("/") || concepts.has(posix.join(t, "index.md")) || existsSync(join(root, t)) && statSync(join(root, t)).isDirectory?.();
+      if (posix.basename(r) === "index.md" || !fromLog) {
+        if (!t.endsWith(".md") && !isDir) { if (!fromLog) warnings.push(`${r}: link missing .md extension: ${m[1]}`); continue; }
+      }
+      if (fromLog) continue; // history exempt from broken-link lint
+      if (t.endsWith(".md") && !concepts.has(t)) warnings.push(`${r}: broken link: ${m[1]}`);
+      if (posix.basename(r) === "index.md" && t.endsWith(".md") && concepts.has(t)) reachable.add(t);
+      if (posix.basename(r) === "index.md" && isDir) reachable.add(posix.join(t.replace(/\/$/, ""), "index.md"));
+    }
+  }
+  // Reachability: walk index closure (an index that lists a subdir makes that subdir's index reachable).
+  for (const [r, c] of concepts) {
+    if (c.reserved || reachable.has(r)) continue;
+    // root-level concepts listed in root index handled above; report the rest
+    const anyIndex = [...concepts.keys()].some((k) => posix.basename(k) === "index.md");
+    if (anyIndex) warnings.push(`${r}: unreachable from any index.md`);
+  }
+}
+
+const conceptCount = [...concepts.values()].filter((c) => !c.reserved).length;
+if (asJson) {
+  console.log(JSON.stringify({ bundle: root, concepts: conceptCount, errors, warnings, conformant: errors.length === 0 }, null, 2));
+} else {
+  console.log(`OKF validate — ${root}`);
+  console.log(`  ${conceptCount} concept(s), ${errors.length} error(s), ${warnings.length} warning(s)`);
+  for (const e of errors) console.log(`  ERROR ${e}`);
+  for (const w of warnings) console.log(`  warn  ${w}`);
+  console.log(errors.length === 0 ? (strict && warnings.length ? "PASS (with lints)" : "PASS — conformant") : "FAIL — nonconformant");
+}
+process.exit(errors.length > 0 ? 1 : strict && warnings.length > 0 && process.env.OKF_STRICT_EXIT ? 1 : 0);

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.",

package/docs/design/2026-09-24-phase-d-plan.md

@@ -35,6 +35,17 @@ pushes. Agreed by both on 2026-09-24:
   published skills); merges into the other's lane; reverts, force-anything,
   branch or tag deletion. A blocking intent unanswered for about 45 minutes goes
   to the human, never to action.
+- **Amendment (the human, 2026-09-26 ~14:00Z): "do the merge then fix if something broke".**
+  - A PR the lead has reviewed and approved is **merged immediately** by the lead (`gh pr merge --squash --match-head-commit <approved oid>`), without waiting for PR CI. CI runs on main after the merge.
+  - A red main is fixed forward at once, by the author or the lead, before anything else merges.
+  - **Tags still wait for main CI green on their exact SHA** (a tag never moves).
+  - Developers run only the affected suites locally (the nested globs included). The full glob and `smoke:tarball` run in CI, sharded ×6.
+  - The watcher no longer relays merges.
+- **Amendment (the human, 2026-09-26 ~13:10Z): "lets approve and tag ourselves all of these PRs".**
+  - With the co-lead unresponsive since ~10:30Z, the lead's review + green CI is the full Class B gate, in BOTH lanes: merges, okf/aweb tags, catalog pins, releases.
+  - Every such act is logged, with its head/tag oid, in a running account mailed to the co-lead for after-the-fact review.
+  - The co-lead's objections then go to the human, and a revert follows only on the human's word.
+  - This ends when the co-lead resumes and the lead records that here.
 - Every PR is reviewed by the co-lead who did not author it (a helper's PR is
   reviewed by its own lead, inside that lead's lane). A disagreement not settled
   in two mails goes to the human. Standing rules unchanged: PR CI is the full