@awebai/oats 0.24.13 → 0.25.1

package/docs/conventions.md

@@ -31,43 +31,70 @@ instance/.claude/skills -> ../.agents/skills
 
 Spawn copies kernel + soul-private + active capability skills into real
 instance-local directories there. Directory symlinks are not used because
-harness recursive discovery may not descend through them. Packages retain
-skills in their own artifact; activation selects them for materialization. Config-level `.agents/skills` is not an OATS capability source
+harness recursive discovery may not descend through them. Under the workspace
+model (0.25) every capability is copied whole into
+`instance/.oats/modules/<capability>/` and its skills into
+`instance/.agents/skills/<capability>/<skill>/`; nothing is installed at a
+config level. Config-level `.agents/skills` is not an OATS capability source
 or an ambient runtime discovery root.
 
-Pi starts spawned sessions with ambient skill and context discovery disabled
-and the one instance path explicit; its globally configured extensions remain
-enabled. Claude runs provider-native: it reads the instance's `.claude/skills`
-and `CLAUDE.md` symlinks, and the operator's own user and project
-configuration — skills, plugins, settings — stays in effect. Neither runtime
-gets a redirected config home. `composition.materialized.runtimePosture` in
-`instance.json` records what each instance actually exposes.
-`oats-getting-started` is the sole pre-workspace ambient bootstrap.
-
-Duplicate skill directory names are errors unless config's `skill-overrides`
-selects a source.
+Harnesses start normally (workspace-model decision 13, and the behaviour of
+every launch a 0.25 kernel performs, classic homes included): Pi starts with
+cwd = the instance home, the composed `AGENTS.md` appended to its system
+prompt, and its own skill, context and extension discovery intact — the
+instance's copied skills are found because they sit under cwd; machine-level
+and repo-level skills resolve exactly as without OATS. *(0.24 kernels started
+Pi with ambient skill and context discovery disabled and the one instance path
+explicit; that exclusion is gone.)* Claude runs provider-native: it reads the
+instance's `.claude/skills` and `CLAUDE.md` symlinks, and the operator's own
+user and project configuration — skills, plugins, settings — stays in effect.
+Neither runtime gets a redirected config home.
+`composition.materialized.runtimePosture` in `instance.json` records what each
+instance actually exposes. `oats-getting-started` is the sole pre-workspace
+ambient bootstrap.
+
+Duplicate skill directory names within the OATS-composed set are errors
+(`E_SKILL_DUPLICATE`, naming both capabilities) unless the classic config's
+`skill-overrides` selects a source; between a composed skill and an ambient
+repo/machine skill the harness's own precedence decides (decision 16).
 
 ## Package locations
 
+**Workspace model (0.25, current):** nothing is installed. A capability lives
+where its owner keeps it and is copied whole into each instance at spawn:
+
+```text
+<member repo>/capabilities/<name>/oats.json           # member-tier capability, latest state (membership is the trust)
+<package repo>/oats-package/oats-package.json         # package-tier: versioned via oats-workspace.yaml packages:
+<deployment>/oats-lock.json                           # lockfileVersion 3: package commit, integrity, per-version approval
+<instance>/.oats/modules/<capability>/                # the copy this instance runs
+```
+
+**Classic 0.24 layout** (still launched by the 0.24 kernel; a 0.25 kernel
+reads none of it as configuration — see [rebuild-to-v2.md](rebuild-to-v2.md)):
+
 ```text
 <package>/capabilities/<name>/oats.json                 # the official marketplace (install source, not ambient)
 <level>/.agents/capabilities/installed/<name>/oats.json # acquired (gitignored, restorable)
 <level>/.agents/capabilities/owned/<name>/oats.json     # authored at this scope (source; committed where the scope is a repo)
-<level>/oats-lock.json                                  # external source/integrity/trust
+<level>/oats-lock.json                                  # lockfileVersion 2: external source/integrity/trust
 ```
 
 ## Quick map
 
-| Thing | Canonical location |
-|---|---|
-| Config | `<level>/oats-config.yaml` |
-| Acquisition lock | `<level>/oats-lock.json` |
-| Soul operating doc | `soul/AGENTS.md` |
-| Soul Claude view | `soul/CLAUDE.md -> AGENTS.md` |
-| Soul-private skills | `soul/skills/` |
-| Instance operating doc | `instance/AGENTS.md` (generated) |
-| Instance skill set | `instance/.agents/skills/` |
-| Instance metadata | `instance/instance.json` |
+| Thing | Canonical location (0.25 workspace model) | 0.24 classic |
+|---|---|---|
+| Shared declaration | `oats-workspace.yaml` in the host repo; `oats-membership.yaml` in every member | `oats-config.yaml` chain, `oats.yaml` |
+| Per-machine config | `<deployment>/oats-local.yaml` (uncommitted) | `oats-config.yaml` `settings:` |
+| Acquisition lock | `<deployment>/oats-lock.json` (v3) | `<level>/oats-lock.json` (v2) |
+| Soul source | `<member repo>/souls/<name>/` | `agents/<name>/soul/` |
+| Soul operating doc | `souls/<name>/AGENTS.md` | `soul/AGENTS.md` |
+| Soul Claude view | `souls/<name>/CLAUDE.md -> AGENTS.md` | `soul/CLAUDE.md -> AGENTS.md` |
+| Soul-private skills | `souls/<name>/skills/` | `soul/skills/` |
+| Instance operating doc | `instance/AGENTS.md` (generated) | same |
+| Instance skill set | `instance/.agents/skills/` | same |
+| Instance modules | `instance/.oats/modules/<capability>/` | `.agents/capabilities/installed/` (shared) |
+| Instance metadata | `instance/instance.json` (`modules{}`, `providers{}`, `workspace{}`) | `instance/instance.json` |
 
 Symlinks prevent compatibility paths from drifting. Generated regular files
 separate canonical portable identity from scope-dependent runtime policy.

package/docs/design/2026-09-16-fresh-operator-walkthrough.md

@@ -1,5 +1,7 @@
 # Fresh operator walkthrough: working preparation versus pending launch
 
+> **Superseded (2026-09-23).** The acceptance driver and helper this walkthrough runs (`test/portable-onboarding-public.acceptance.mjs`, `test/helpers/portable-onboarding-consumer.mjs`) were deleted with the workspace model v2; the 0.25 operator path is `oats onboard` → `oats sync` → `oats spawn` (`docs/first-team.md`). Read [2026-09-23-simplified-workspace-model.md](2026-09-23-simplified-workspace-model.md) (worked example) and [2026-09-23-workspace-module-contracts.md](2026-09-23-workspace-module-contracts.md) (normative) instead; kept as history.
+
 ## Scope of this evidence
 
 This is a **source-level integration walkthrough**, not a claim about an installed
@@ -20,24 +22,27 @@ backlink; inspection/preparation never adopts or contacts that workspace.
 
 ## Reproduce the pinned public consumer
 
-From the framework worktree, with the existing locked root dependencies installed
-and both exact core commits available in the local Git object database:
+**No longer runnable.** The acceptance driver and its helper were deleted with
+the workspace model v2; the command below fails with `Could not find
+'test/portable-onboarding-public.acceptance.mjs'`. The equivalent 0.25 evidence
+is the CLI suite over the Northwind fixture (`test/onboard.test.mjs`,
+`test/spawn-standalone.test.mjs`, `test/fixtures/northwind/build.mjs`).
 
-```bash
-node --test --test-timeout=60000 test/portable-onboarding-public.acceptance.mjs
+```text
+# historical (deleted): node --test --test-timeout=60000 test/portable-onboarding-public.acceptance.mjs
 ```
 
-This explicit acceptance driver is separate from the default `*.test.mjs` suite:
+This explicit acceptance driver was separate from the default `*.test.mjs` suite:
 a shallow checkout or source tarball need not contain a historical cross-branch
-commit. An explicit run **fails** if the pin or matching dependency lock is absent;
-it never silently skips, fetches a moving branch, substitutes current core or
-strips unsupported request fields.
-
-`test/helpers/portable-onboarding-consumer.mjs` archives committed core objects
-into owned ignored `stage/onboarding-consumer-*` scratch and verifies the pin and
-held-patch exclusion. It links only this worktree's dependencies after comparing
-the complete npm lock. No working files from another agent are loaded and no Git
-worktree/branch is added, reset or merged. Only the fixture's scratch is removed
+commit. An explicit run **failed** if the pin or matching dependency lock was absent;
+it never silently skipped, fetched a moving branch, substituted current core or
+stripped unsupported request fields.
+
+`test/helpers/portable-onboarding-consumer.mjs` (deleted) archived committed core objects
+into owned ignored `stage/onboarding-consumer-*` scratch and verified the pin and
+held-patch exclusion. It linked only this worktree's dependencies after comparing
+the complete npm lock. No working files from another agent were loaded and no Git
+worktree/branch was added, reset or merged. Only the fixture's scratch was removed
 on completion.
 
 The test runs real native Git observations with isolated host configuration and

package/docs/design/2026-09-16-portable-migration-evidence.md

@@ -1,5 +1,7 @@
 # Portable migration evidence reader and planner
 
+> **Superseded (2026-09-23).** The modules this note describes (`lib/portable-migration-evidence.mjs`, `lib/portable-migration.mjs`, `lib/portable-migration-store.mjs`, `lib/portable-migration-artifacts.mjs`, `lib/legacy-lock-codec.mjs`) were deleted with the workspace model v2 — there is no migration (decision 5/15: a 0.24 lock is `E_LOCK_SCHEMA`, not evidence). Read [2026-09-23-simplified-workspace-model.md](2026-09-23-simplified-workspace-model.md) (worked example) and [2026-09-23-workspace-module-contracts.md](2026-09-23-workspace-module-contracts.md) (normative) instead; kept as history.
+
 16 September 2026. This is the first read-only implementation slice of the
 Portable Souls consumer migration. The retention contract and the fifteen
 binding decisions in `2026-09-15-portable-souls-handoff.md` remain authoritative.

package/docs/design/2026-09-16-portable-onboarding.md

@@ -1,5 +1,7 @@
 # Portable fresh onboarding and source discovery
 
+> **Superseded (2026-09-23).** The 0.24 onboarding facade this note describes (`lib/portable-onboarding-acceptance.mjs`, `test/portable-onboarding-public.acceptance.mjs`, source editions, exports) was deleted with the workspace model v2; the 0.25 bootstrap is `oats onboard [<dir>] --workspace <ref>` (contract §6, `docs/desktop-cli-api.md`). Read [2026-09-23-simplified-workspace-model.md](2026-09-23-simplified-workspace-model.md) (worked example) and [2026-09-23-workspace-module-contracts.md](2026-09-23-workspace-module-contracts.md) (normative) instead; kept as history.
+
 16 September 2026. This module supports a controlled fresh setup path while
 historical in-place migration is deferred. It does not alter the Portable Souls
 architecture or weaken the existing partial/unknown evidence safeguards.
@@ -109,7 +111,7 @@ onboarding CLI is still separate integration work.
 
 ## Fresh acceptance driver
 
-`lib/portable-onboarding-acceptance.mjs` keeps acceptance above the same facade:
+`lib/portable-onboarding-acceptance.mjs` (deleted with v2) kept acceptance above the same facade:
 
 - `compareFreshSourceAcceptance({organization,standalone})` accepts only issued,
   ready inspections and proves qualified identity, exact commit, export and
@@ -147,7 +149,7 @@ the helper does not claim CLI router availability.
 
 ## Pinned real public consumer
 
-`test/portable-onboarding-public.acceptance.mjs` additionally executes the real
+`test/portable-onboarding-public.acceptance.mjs` (deleted with v2) additionally executed the real
 public preparation/approval/retained-inspection APIs archived from exact core
 `c5c6a3c9171e424a36a1bdbf3932b9319a3c6c72`, without merging its branch. It uses
 isolated local Git transport, temporary deployments and a declared inert fixture

package/docs/design/2026-09-20-redesign-program-board.md

@@ -2,7 +2,7 @@
 
 **Purpose:** the one accurate view of every work stream in the redesign, what is on main, what is in flight, who owns it, and what blocks it. Lead: `oats-expert` (redesign lead). Updated whenever anything merges, is returned, or reality changes. Older per-lane boards are superseded by this file.
 
-**Last update:** 2026-09-22 23:45Z · v0.24.12 published · **slice 8 approved** (no polling; command-running GET `/api/schedules` to be REMOVED; remote history unsupported; captured edit = honest limitation; transcript = provenance only, read-only transcript verb = K12 Decision later) · **K8b PR95 → main `ee60d1e2`** (`schedule-read-2` / `scheduleHistoryApi 3`: runId by time, bounded fd state reads + 1 MiB budget, per-job isolation, scope/id echo, `session` provenance replaces `transcript`) · 12 receipts to engineer · engineer wiring 8 → then rest of frame 10 · open: K11, K12 transcript, attach-knowledge, auto-PR, branch enumeration
+**Last update:** 2026-09-23 17:40Z · **Workspace model v2 phases A–C ON MAIN (`59ae22df`, PR99) → **`v0.25.0` PUBLISHED** (bump `dc333e4e`)** · Phase D next (framework repos as the first workspace; six expert souls; `oats.core`/`oats.setup` rewrite) · ⏸ parity pipeline still paused except 10B-0 (→ 0.24.14 when the engineer hands off; note: 0.24.14 must be cut from the 0.24 line, not main).
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/design/2026-09-20-workspace-and-portable-adoption-plan.md

@@ -4,6 +4,8 @@
 
 **Status:** Phase1 implementation authorised by the human, using the existing developers under lead supervision/review. The workspace home is confirmed as `oats`; `oats-dev` remains development capabilities. This does not claim completed conversion or authorise unspecified new contracts, credential operations or live deployment mutations.
 
+> **2026-09-23 — direction change, read first.** Phases 1–3 delivered as written (workspace on Git, five souls + central knowledge, all contract-bearing Desktop parity slices, releases 0.24.7–0.24.13). Reviewing the result, the human judged the *declaration model* itself too heavy and, in one sitting, accepted a simplified **workspace model v2**: one workspace per org; reciprocal membership as the only gate and as the trust decision; a soul says `from:` (member repo | `here` | `package`) — a location, never a version; packages are the only versioned thing; **nothing is installed** — every capability is copied whole into the instance at spawn; discovery over Git remotes; teams as labels; harnesses start normally. Record: `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`; worked example: [2026-09-23-simplified-workspace-model.md](2026-09-23-simplified-workspace-model.md). **Consequences for this plan:** P1.3's `oats.yaml` export indexes and P1.4's `oats-config.yaml` activation are superseded (→ `oats-membership.yaml`, derived activation); D1/D4 stand (`oats.core` becomes `from: package` by default; the catalog stays as discovery); D2's "explicit `oats.core` on every soul" is met by the workspace default; D3 gains the `<name>-workspace/` convention and clone-then-spawn. **No migration** — clean v2, the framework's own repos are the first workspace. A Phase 4 implementation plan is proposed to the human before any `lib/`/`bin/` change; the Desktop parity pipeline is paused meanwhile except for the in-flight 10B-0 security fix.
+
 ## Goal and order
 
 1. Put OATS development onto the Git-workspace and Portable Souls architecture: a real shared workspace definition, qualified repository exports, by-reference sources and usable local deployments.