@awebai/oats 0.23.0 → 0.23.1

package/docs/packages.md

@@ -391,12 +391,14 @@ for it.
 ### Catalog shape
 
 The official catalog is data (`package-catalog.json`, or the file named by
-`OATS_PACKAGE_CATALOG`):
+`OATS_PACKAGE_CATALOG`). The v0.23.1 integration selects these already-published
+sources; installing a kernel does not advance existing package locks:
 
 ```json
 {
   "packages": {
-    "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v1.4.1", "path": "oats-package" },
+    "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v2.0.0", "path": "oats-package" },
+    "oats.knowledge-theory": { "url": "https://github.com/awebai/oats.git", "ref": "v0.23.0", "path": "oats-package" },
     "oats.dev": { "url": "https://github.com/awebai/oats-dev.git", "ref": "v1.0.0", "path": "oats-package" }
   },
   "capabilities": { "oats.review": "oats.dev" }
@@ -412,6 +414,28 @@ Existing v1 locks and artifacts remain supported until you run guided migration.
 reads; identity mappings need no entry. An alias value may also be spelled
 `{ "package": "<id>" }`.
 
+### OKF v2 and optional theory distribution
+
+The standalone OKF package exports only `oats-package/capabilities/oats-okf/`.
+Use its catalog Git payload after [release gates](release-notes/v0.23.1.md) pass.
+The framework's bundled npm mirror is not a self-contained distribution:
+npm drops the source worker soul's `CLAUDE.md -> AGENTS.md`. It must not be
+advertised as a complete local package or repaired after acquisition to evade
+integrity checks. Git transport preserves the canonical source alias.
+
+The optional `oats.knowledge-theory` package is a separate Git payload in this
+repository's `oats-package/`, excluded from the kernel npm tarball. The catalog
+entry selects published framework v0.23.0, which contains package 1.0.0.
+The source reference patch 1.0.1 is separately available through an explicit
+v0.23.1 Git source after that framework tag is published. It supplies an authoring skill and
+`knowledge-theory-expert`, not a default knowledge-layer binding, runtime judge
+or OKF dependency. Acquiring it does not activate it.
+
+Updating OKF v1 to v2 is a breaking capability change. Preserve existing
+knowledge and source state/cursors, explicitly bind/provision external owners,
+accept provider delivery and perform deliberate cutover. Kernel package/lock
+migration does none of this. See [knowledge migration](knowledge-migration.md).
+
 ## Doctor
 
 `oats doctor` reports, in addition to its capability diagnostics:

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

@@ -0,0 +1,97 @@
+# OATS v0.23.1 — external OKF v2 integration
+
+This patch integrates the published **oats.okf 2.0.0** Git package, tagged at
+`4b6d861ce44e5662303e150cc85095d0eb00d7e7`, following the published OATS 0.23.0
+prerequisite. The checked-in mirror records verified remote tag/object and
+payload provenance. Updating OATS alone does not change existing exact locks,
+activate capabilities, migrate knowledge or install a host timer.
+
+## External OKF v2 integration
+
+The framework mirror follows the standalone package's **only exported
+capability**, `oats-package/capabilities/oats-okf/`. OATS >=0.23.0 supplies the
+generic directory-work and public capture/recall/CLI boundaries; OKF uses no
+private kernel imports. V0.23.1 prepares the framework catalog for OKF 2.0.0,
+without changing an existing deployment's exact lock or activation.
+
+This is a **breaking capability upgrade**, independently versioned from the
+framework patch:
+
+- Explicit absolute `bindings-file` settings, external Git/directory bases,
+  `soul/okf.json` owner declarations and accepted `okf-base.json` node metadata.
+- Index-first immutable reader views, with an instructional no-write boundary,
+  not an OS sandbox or new ACL. `owns` routes responsibility and `reads` selects
+  starting context; every configured base remains discoverable/readable.
+- Durable per-source notes **and full record windows**, frozen destinations,
+  independent directory workers and source jobs that survive home retirement.
+  Final capture must certify custody before the source home can disappear.
+- Git delivery is PR-only, with verified native commit/push/PR receipts and
+  separate merge-visible acceptance. Plain-directory delivery uses cooperative
+  locks, baseline comparison, a recoverable publication journal and validated
+  receipts, without Git/gh. Multi-base delivery is not a distributed transaction.
+- Working agents capture; service workers judge. No automatic edits to soul
+  skills, direct accepted-base edits by readers or attached source-branch
+  promotion commits.
+
+## Inspection and complete pipe output
+
+The v2 inspection surface restores labeled live `STATE.md`, `log.md` and sorted
+Markdown notes alongside durable processing receipts. Home-pointer and instance
+identity checks prevent a retired, missing, reused or unverified home from
+supplying another source's live documents. `liveMemory` reports availability,
+reason and observation time; durable bindings, registered view receipts and
+scheduler diagnostics remain available independently.
+
+Inspection keeps its explicit **256 KiB per-document preview**, with
+`truncated`/original `bytes` metadata. The complete JSON envelope drains stdout,
+including large documents and receipts. Provider `read` returns full Markdown;
+record transport retains full returned evidence, not an inspection preview.
+Descriptor-selected `read`/`refresh` always writes new immutable views under
+source state, never the invoking repository or a deleted/replacement home.
+
+Regression qualification must retain behavioral coverage, including large
+piped documents, live identity failures, durable inspection after disappearance,
+external view placement and full native record backlog. Scaffold tests establish
+layout/custody, not that a model learned.
+
+## Git distribution, not an npm payload shortcut
+
+Users acquire `oats.okf` through the catalog's exact Git payload and explicitly
+review/trust executable surfaces. The npm bundled mirror is **not a
+self-contained Git distribution**: npm omits the worker soul's tracked
+`CLAUDE.md -> AGENTS.md` symlink. Do not synthesize source aliases, weaken
+integrity rules or advertise copying that mirror as a complete package.
+
+The optional `oats.knowledge-theory` catalog entry uses the already published
+**v0.23.0** source (package 1.0.0), avoiding a forward reference to an unpublished
+tag. The current Git source additionally contains the 1.0.1 authoring-reference
+patch, available through an explicit v0.23.1 Git source after publication.
+Its payload stays in the repository's `oats-package/` Git subtree,
+not the kernel npm tarball. It exports authoring resources and
+`knowledge-theory-expert`, without a knowledge-layer binding, mandatory runtime
+injection or OKF dependency. Canonical references and copied local curriculum
+must stay synchronized. Acquisition alone activates nothing.
+
+## Migration and verification
+
+Follow [the v1 preservation and cutover guide](../knowledge-migration.md):
+inventory active writers, preserve legacy knowledge/state/cursors, provision
+empty owned nodes, stage and deliver through the provider, confirm acceptance,
+then deliberately cut over owner declarations and existing sources. Old
+watermarks are evidence, not v2 processing proof. No automatic migration deletes
+legacy material or leaves a knowledge symlink in the soul.
+
+Qualification includes the standalone suite against the actual published
+minimum kernel, strict byte/mode/symlink mirror verification, framework regression
+and installed-tarball Git acquisition probes. Iterative independent review
+covered custody, interrupted publication, source retirement and rejected-PR
+recovery. Separate real Pi learning after source/transcript deletion and actual
+GitHub PR merge/reconciliation/fresh-view acceptance were verified; scripted
+transport and model-learning evidence are kept distinct.
+
+The normal tag-driven release still gates npm publication on all tests and
+Desktop build/smoke legs. Live deployment and explicit knowledge cutover remain
+separate operations, not side effects of package acquisition.
+
+See [knowledge runtime documentation](../knowledge.md) for settings, lifecycle,
+commands, custody and recovery boundaries.

package/docs/schedules.md

@@ -44,9 +44,10 @@ and no queue.
 - **command** `{id, enabled, cron, tz, kind: "command", cwd, argv}` — runs
   an oats-only argv (`argv[0]` is `oats`, no shell) in `cwd`, which must be
   inside the workspace. The runner parses the command's envelope and tracks
-  any instance it names, so `["oats", "okf", "harvest"]` run in a source
-  instance's home is followed until the harvester it spawned is gone.
-  Command return is not task completion.
+  any instance it names. A provider can return an independent worker launched
+  from durable context; the job follows that worker until its home is gone.
+  Command return is not task completion. Avoid binding durable work to a
+  disposable source-home cwd; see [OKF v2 source jobs](#okf-v2-source-jobs).
 - **wake** `{id, enabled, cron, tz, kind: "wake", home, message}` — every
   due minute inspects the instance at `home` through its session receipts.
   Running: `message` is delivered once with `session input`. Not running
@@ -150,3 +151,41 @@ saves a wake job `wake-<instance>` bound to the new home after the spawn
 succeeded. If the spawn succeeds but the save fails, the spawn result still
 carries the full instance receipt, plus `wakeScheduleError` and a warning;
 the instance is neither hidden nor spawned again.
+
+## OKF v2 source jobs
+
+The [prepared OKF v2 runtime](knowledge.md) registers **one command job per
+source**, not a fleet sweep or a home-bound operation job. It runs from stable
+deployment context with argv equivalent to:
+
+```text
+oats okf run-source --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
+```
+
+The descriptor and captured evidence live outside the disposable source.
+Registration (including explicit harvest after source migration) idempotently
+creates/verifies the definition; setup failures are reported for retry. A
+pre-existing disabled job is not silently re-enabled. Command execution clears
+invoking-instance identity and still passes normal capability activation/trust
+gates after source retirement.
+
+No timer is installed by registering a source or its job. An operator can
+inspect or explicitly install one from deployment context:
+
+```bash
+oats okf inspect --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
+oats okf setup --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
+# Explicit host change; never part of a scaffold-only test:
+oats okf setup --source /absolute/state/sources/UUID/source.json --install-host --soul domain-expert --json
+# Definition-only disable; does not stop a worker or reconcile an executing job:
+oats okf setup --source /absolute/state/sources/UUID/source.json --disable --soul domain-expert --json
+```
+
+Retirement captures/enqueues final evidence and does not synchronously remove
+its job under the scheduler's host lock or wait for a model/GitHub. A drained
+retired source returns empty; disable its job explicitly when appropriate.
+Source no-launch guards prevent automatic model starts, and final capture of
+a no-launch source disables its automatic processing. `inspect` distinguishes
+job definition from actual timer activity; an absent or inactive timer is not
+reported as enabled automation. The scheduler's launch/liveness receipts do not
+replace OKF's processing, delivery and merge-visible acceptance receipts.

package/docs/souls-and-instances.md

@@ -14,7 +14,7 @@ A soul is durable and committed. It is the part you review, improve, and keep.
   AGENTS.md            # canonical operating doc
   CLAUDE.md → AGENTS.md
   skills/              # skills specific to this expert
-  knowledge/           # optional, created by the knowledge integration
+  okf.json             # OKF v2 owner/owns/reads declaration, when selected
 ```
 
 `soul.yaml` keys:
@@ -31,15 +31,16 @@ A soul is durable and committed. It is the part you review, improve, and keep.
 | `launch-config` | Optional default launch configuration for new instances (a name declared under `launch-configs:` in the scope's config; see docs/design/launch-configurations.md). `oats spawn --launch-config <name|none>` overrides it; `oats soul set --launch-config <name>` / `--no-launch-config` edit it. |
 
 A soul is model-agnostic as an artifact. Its files are plain operating docs,
-skills, and knowledge. `model` is only the default choice for new instances,
-not part of the expert's identity.
+skills and capability-owned declarations. `model` is only the default choice
+for new instances, not part of the expert's identity.
 
 A soul never runs by itself. It is incarnated as an instance. Editing a soul
 is a code change.
 
-Today the core soul artifacts are `AGENTS.md`, `skills/`, and any knowledge
-bundle the knowledge integration creates. Future integrations may add other
-expert-specific artifacts, such as Claude Code-like rule files or
+Core soul artifacts are `AGENTS.md` and `skills/`, plus any declarations the
+selected knowledge integration needs. OKF v2 stores knowledge externally, not
+in a soul bundle; see [knowledge](knowledge.md) for its prepared version scope.
+Future integrations may add expert-specific artifacts such as rule files or
 runtime-specific guidance, while keeping `AGENTS.md` canonical.
 
 ## Instance anatomy
@@ -73,13 +74,14 @@ collide because they are local runtime state, not shared soul state.
   STATE.md, log.md, notes/         # optional, from the knowledge integration
 ```
 
-Why some knowledge belongs in the soul (incarnation-invariant) and some in
-the instance (this task, this branch, now) — regardless of which integration
-or format you use — is covered in [knowledge theory](knowledge-theory.md).
+Why durable expertise must be incarnation-invariant while task state is local
+to this branch and moment is covered in [knowledge theory](knowledge-theory.md).
+This distinction does not require knowledge bytes to live in the soul.
 
-The kernel does not define memory files. If the config resolves `knowledge:
-okf`, the okf integration creates `STATE.md`, `log.md`, and `notes/`. If the
-config resolves `knowledge: none`, those files do not exist.
+The kernel does not define memory files. With `oats.okf` selected under
+`capabilities.layers.knowledge`, v2 creates `STATE.md`, `log.md`, `notes/` and an
+immutable external-knowledge snapshot. `knowledge: none` creates none of these;
+it does not erase pre-existing memory.
 
 ## Lifecycle
 
@@ -94,7 +96,10 @@ own home and tools.
 
 Examples of spawn hooks:
 
-- `oats-okf` creates episodic memory files.
+- `oats.okf` v2 requires explicit bindings and owner declarations, validates
+  accepted bases, creates episodic files and an immutable reader view, and
+  registers a durable source plus its per-source schedule definition. Missing
+  knowledge is an error, not permission to bootstrap an empty substitute.
 - `oats-aweb` mints a messaging identity.
 
 ### Work
@@ -103,29 +108,26 @@ The instance works in `./work`. With oats-okf it also keeps `STATE.md` current,
 appends milestones to `log.md`, and captures non-obvious insights in
 `notes/`.
 
-After committing with pending notes, the instance runs `oats okf harvest`
-(its okf briefing says so). oats-okf spawns a memory-harvest agent attached to
-the same work tree. The harvester promotes, merges, or drops notes, commits a
-`memory-harvest:` change, deletes processed notes, and retires itself. This is
-how long-lived instances feed their souls while still alive.
-
-Instances that write few notes still feed their souls. With no notes pending,
-`oats okf harvest` asks the turn record for the instance's own captured
-sessions (the transcripts whose working directory is the instance home), and
-spawns the harvester on the turns captured since the last harvest, bounded by
-exact turn ids. The harvester extracts candidates from them, judges each under
-the same promotion bar as a note, and once its judgement is complete writes the
-watermark `.okf-harvest-record.json` in the instance home, whether or not it
-promoted anything; only a failed harvest leaves the watermark alone, so the same
-window is read again. `oats okf harvest --from-record` consults the record even
-when notes are pending. Windows are sized to one tool-output read (60 turns
-or 96 KB of JSON by default; okf settings `record-window-turns` and
-`record-window-bytes`), so a long backlog drains over several harvests, each
-advancing the watermark only over what was read; the package prepares the next
-watermark as `.okf-harvest-record.next.json` and the harvester's delivery is
-one rename, so an abandoned harvest leaves that file beside the current one.
-oats.okf 1.5.0 requires kernel 0.22.2 (the `capture --home` and `recall --json`
-surfaces); the compatibility floor refuses to activate it on an older kernel.
+It reads accepted external knowledge through `./knowledge/view.json` and
+`./knowledge/bases/<alias>/`, index-first. It never writes accepted knowledge;
+this is instruction, not an OS sandbox. `oats okf read`/`refresh` obtains a new
+accepted view while old snapshots remain stable. Git PRs are unread as accepted
+knowledge until their merge is visible; pending directory publication blocks
+fresh reads rather than exposing partial bytes.
+
+An independent worker judges durable **notes and full record windows**, not only
+notes or a watermark left in the live home. V2 working-agent instructions do not
+require after-commit harvesting. Each source has a command job rooted in durable
+deployment context; the operator may also request `oats okf harvest`. Timer
+installation is explicit, and no-launch sources cannot schedule model launches.
+
+Workers use their own `work: directory`, never the source branch or an attached
+worktree. Validated Git output goes through real PR delivery; non-Git output
+uses recoverable directory publication. Workers leave live notes and soul skills
+untouched. Captured, processed, delivered and accepted are distinct receipts;
+spawning a worker is not successful learning. See [knowledge](knowledge.md) for
+inspection, completion and recovery, and [migration](knowledge-migration.md) for
+preserving v1 bundles and source cursors before owner/source cutover.
 
 ### Spawning and coordinating with other agents
 
@@ -171,8 +173,11 @@ task layer can provide shared work state while messaging provides conversation.
 ### Retire
 
 Retirement runs active capability retire hooks in reverse spawn order before the home disappears. The aweb
-integration self-deletes the instance identity here. For oats-okf, retirement
-is a knowledge no-op because harvest already happens after commits.
+integration self-deletes the instance identity here. OKF v2 performs final
+notes-and-record capture into durable external custody. An incomplete or
+uncertified capture retains the home for retry. Successful retirement enqueues
+evidence but never waits for a model or GitHub: independent processing and
+source-targeted inspection continue after the home disappears.
 
 `oats retire <instance> --self` lets an instance retire itself when the human
 or briefing says it is done. A live runtime cannot give a stable final
@@ -206,7 +211,8 @@ instructions state first (`injects/instance-boundary.md`):
   extent the mode below permits.
 - The home's `soul` link is to be treated as read-only: writes through it bypass
   the branch and review path. Durable soul edits go through tracked paths under
-  `work/`, or through the harvester when the soul lives outside the repo.
+  `work/` under the applicable review rules. OKF v2 harvest edits external
+  owned knowledge, not canonical soul files or skills.
 
 Agents move between the two as the task needs; the boundary is what each
 directory is for, not a place to settle in.
@@ -247,8 +253,7 @@ Rules:
 `work/` points at **another instance's work tree** — same branch, same
 uncommitted state. Spawning attached requires `workDir` (the owning
 instance's `<home>/work`); it is usually a spawn-time choice for service
-agents (the memory-harvest agent uses it so its promotion commit lands on
-the source instance's branch), but a soul whose role is always-attached
+agents such as reviewers, but a soul whose role is always-attached
 service work may declare it as identity too.
 
 Attached agents are guests: never switch branches or rewrite history, touch
@@ -289,10 +294,10 @@ Rules:
 - Read freely across member repos; **never edit or commit inside them** —
   route changes to the owning repo's agents or the human.
 - No git state operations in any member repo.
-- The one exception is the soul's own home repo: knowledge promotion writes
-  there via the knowledge layer's harvest, **as a PR on a branch**, never a
-  direct push (the OKF integration does this automatically for
-  workspace-mode instances).
+- Knowledge promotion follows the selected capability's custody protocol,
+  never direct edits through the workspace view. In OKF v2 an independent
+  worker publishes external knowledge through PRs for every Git base,
+  irrespective of the source's work mode or the soul's repository.
 
 Spawning workspace mode requires a declared boundary (a `team:` block or a
 workspace-scope config); the instance records no branch — the workspace is
@@ -370,8 +375,8 @@ Default layout:
 ```
 
 `local-agents/` sits BESIDE `agents/` at the scope level and holds **full local
-souls**: complete souls (memory, skills, knowledge, instances) that are not
-committed to the repo. `oats create <name> --local` creates one — the directory
+souls**: complete definitions with instructions, skills, capability declarations
+and instances, not committed to the repo. `oats create <name> --local` creates one — the directory
 is created on first use, and when the scope is a git repo the kernel adds
 `local-agents/` to its `.gitignore` automatically. A scope with only
 `local-agents/` is fully operable: people can use OATS with local agents alone.
@@ -382,7 +387,9 @@ for compatibility.
 Instances of a local soul receive a `local-soul` briefing: work and commits
 are normal, but soul updates are plain file edits (nothing to commit), and
 durability is the machine's — promote the soul to `agents/` when it starts to
-matter beyond one machine.
+matter beyond one machine. That concerns soul artifacts, not a knowledge
+provider's custody: a local soul using OKF v2 still reads external bases and
+uses PR-only delivery for any Git base.
 
 Alternative agents-root layouts are planned but not built. Today the default
 layout is the only implemented layout.

package/package-catalog.json

@@ -2,7 +2,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v1.6.1",
+      "ref": "v2.0.0",
       "path": "oats-package"
     },
     "oats.aweb": {
@@ -29,6 +29,11 @@
       "url": "https://github.com/awebai/oats-dev.git",
       "ref": "v1.0.0",
       "path": "oats-package"
+    },
+    "oats.knowledge-theory": {
+      "url": "https://github.com/awebai/oats.git",
+      "ref": "v0.23.0",
+      "path": "oats-package"
     }
   },
   "capabilities": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/capabilities/oats-okf/lib/harvest-branch.mjs

@@ -1,43 +0,0 @@
-// A workspace-mode harvest delivers its promotion as a PR from a branch named
-// memory-harvest/<slug> in the soul's repository. After that PR merges, the
-// local branch may still exist and the next harvest's spawn would refuse it.
-// A branch fully merged into the base is stale and is deleted before the
-// spawn; an unmerged one is the previous harvester's unfinished work and the
-// harvest refuses with the exact remedy instead of touching it.
-import { execFileSync } from "node:child_process";
-
-/** Single-quote shell escaping for the operator remedy: the repo path may hold spaces or shell metacharacters. */
-export function shellQuote(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'"; }
-
-function git(repo, args) {
-  return execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
-}
-
-/** The repository's base branch: origin/HEAD's target when known, else main, else master. */
-export function baseBranchOf(repo) {
-  try { const ref = git(repo, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]); if (ref) return ref.replace(/^refs\/remotes\//, ""); } catch { /* no origin/HEAD */ }
-  for (const b of ["origin/main", "main", "origin/master", "master"]) {
-    try { git(repo, ["rev-parse", "--verify", "--quiet", b]); return b; } catch { /* next */ }
-  }
-  return undefined;
-}
-
-/** Returns { action: "absent" | "deleted", base } or throws E_HARVEST_BRANCH_EXISTS. */
-export function reclaimHarvestBranch(repo, branch) {
-  try { git(repo, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]); }
-  catch { return { action: "absent" }; }
-  const base = baseBranchOf(repo);
-  let merged = false;
-  if (base) { try { git(repo, ["merge-base", "--is-ancestor", branch, base]); merged = true; } catch { merged = false; } }
-  if (!merged) {
-    const err = new Error(`branch ${branch} already exists in ${repo} and is not merged into ${base || "any base branch"}: a previous harvest's promotion is unfinished — review and merge or delete it (git -C ${shellQuote(repo)} branch -D ${shellQuote(branch)}) before harvesting again`);
-    err.code = "E_HARVEST_BRANCH_EXISTS";
-    throw err;
-  }
-  // -D, not -d: the merge check above is against the BASE (origin/main when
-  // present). `branch -d` re-checks against the branch's upstream or the
-  // current HEAD instead, so with the soul's local main behind origin/main a
-  // branch fully merged upstream would still be refused as "not fully merged".
-  git(repo, ["branch", "-D", branch]);
-  return { action: "deleted", base };
-}