@awebai/oats 0.29.4 → 0.30.0

package/docs/design/2026-09-23-workspace-v2-implementation-plan.md

@@ -1,65 +0,0 @@
-# Phase 4 — implementing workspace model v2: proposal for the human
-
-**Date:** 2026-09-23 · **Status:** PROPOSED — nothing lands before the human approves this plan.
-**Decision:** `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)
-
-## What we are building, in one paragraph
-
-A clean v2 of the kernel's declaration, resolution and launch path: read `oats-workspace.yaml` v2 / `oats-membership.yaml` / `soul.yaml` v2 / `oats-local.yaml` over Git remotes; confirm membership; resolve every capability by `from:`; fetch packages at the locked version with per-version approval in lock v3; copy each capability whole into the instance (`.oats/modules/` + `.agents/skills/`); compose `AGENTS.md`; launch the harness normally. Remove the installed-capability tier, the classic activation config and the v1 declaration readers. No migration. The framework's own repos become the first real v2 workspace and the Desktop follows through new DTOs under new feature names.
-
-## Where the current code is
-
-`lib/` is 82 modules / 21 k lines; `core.mjs` alone is 9.2 k. The v1 declaration/portable path is spread over ~20 modules (`workspace-definition`, `workspace-discovery`, `source-spec`, `portable-*`, `capability-provenance`, `prepared-resources`, `resolution-shape`, `captured-*`, `packages` 1.4 k). Much of that machinery exists to carry per-soul versioned sources, migration evidence and the installed tier — the things v2 removes. The lifecycle core (spawn/retire/session/events/schedule, the Desktop DTOs, `binding` validation, the lock) stays.
-
-**Approach (human, 2026-09-23): the new modules ARE the kernel — no `lib/v2/`, no seam, no flag.** Each phase replaces canonical code on main and deletes what it supersedes; tests are updated to the new truth in the same phase. Desktop contracts that change do so under new feature names; the Desktop follows in W12.
-
-## Work packages
-
-Each is one PR (or two small ones), reviewed by me, on `main`, as canonical code from the first phase (no seam — see the approach above). Order is dependency order; W1–W3 can proceed in parallel lanes. **Status (2026-09-23): W1–W8 and W10 shipped in OATS 0.25.0 (PR99 `59ae22df`); W8's last part — folding the classic no-`oats-local.yaml` spawn path into the one pipeline and deleting the v1 residue — is a follow-up; W9/W9b/W11/W12 are Phases D–F.**
-
-| # | Package | Delivers | Owner | Size |
-|---|---|---|---|---|
-| **W1** | **Schemas + fixtures** | `oats-workspace.schema.json` v2, `oats-membership.schema.json`, `soul.schema.json` v2, `oats-local.schema.json`, lock v3; the Northwind example as a **test fixture workspace** (three teams, five repos as bare local remotes) used by every later package | lead | S |
-| **W2** | **Remote observation** | `lib/remote.mjs`: fetch a file or a tree from a Git remote at default-branch or exact commit, in the operator's access context (git credential helper / `gh` token), with typed `cannot read <url>`; bounded; a content-addressed **fetch cache** under the OS cache dir (invisible plumbing) | lead | M |
-| **W3** | **Membership + discovery** | `lib/workspace.mjs`: read the workspace file; for each member read `oats-membership.yaml`; confirm both halves in one access context (`E_MEMBERSHIP_UNCONFIRMED` naming the missing/unreadable half); enumerate `souls/*/soul.yaml` and `capabilities/*/oats.json`; apply `private`; team labels (`E_TEAM_UNKNOWN`); standalone case | lead | M |
-| **W4** | **Resolution** | `lib/resolve.mjs`: workspace defaults ⊕ `defaults.byTeam` ⊕ soul (`off` removes) → for each `(name, from)`: member lookup or package lookup; slot filling from `layer:` (`E_SLOT_CONFLICT`); produces an immutable **resolution** (the input to preview/apply — reuses `decision.revision`) | lead | M |
-| **W5** | **Packages v2 + lock v3** | `lib/packages.mjs` (rewritten in place): `packages:` → catalog/git ref → commit; integrity; **approval per version** stored in `oats-lock.json` v3 (`approved.executables` digest); `oats package add|remove`; a moved tag fails integrity and re-asks; **delete** `oats install/restore/use/init` and the installed tier | lead | M |
-| **W6** | **Materialization + launch** | `lib/materialize.mjs`: copy each resolved capability whole into `<instance>/.oats/modules/<cap>/`; copy `skills/` into `<instance>/.agents/skills/<cap>/`; compose `AGENTS.md` (soul + injects); record `modules{}` and **`providers{}` (from `spawn --provider <cap> k=v`, the instance-level payload home; merged with soul + `oats-local.yaml` settings before `binding`)** in `instance.json`; keep `CLAUDE.md`/`.claude/skills` aliases; **launch the harness normally** (drop the ambient-skill exclusion; keep model/profile pinning) | lead | M |
-| **W7** | **CLI switch-over** | `oats sync`, `oats spawn` (preview/apply unchanged in shape, now fed by W4/W6), `oats capabilities` / `oats souls` with origin + team, `oats workspace status`; `oats status` shows `modules … @ commit` + `member moved since`; `oats version --json` advertises `workspaceApi: 2` + feature `workspace-v2`; **remove the v1 readers** (`oats.yaml`, per-soul `source:`, `oats-config.yaml` activation) — a v1 file at a v2 path errors naming the schema | lead | M |
-| **W8** | **Delete v1** | Remove `portable-*`, `source-spec`, `capability-provenance` (v1 parts), `prepared-resources`, migration stores/evidence, the installed tier in `packages.mjs`, classic config activation, their tests and docs; `core.mjs` loses everything that only served v1 | lead | L (mostly deletion) |
-| **W9** | **Framework repos as the first workspace (decisions 18–21)** | `oats-workspace.yaml` v2 in `oats` (drop the six imports; `packages:` pins oats.framework/okf/aweb/jira/linear/authoring/dev **as packages**; `teams:` global/engineering; `defaults`); `oats-membership.yaml` in ALL seven repos; the six soul editions rewritten (`oats.okf: {from: package}` etc. even though the repos are members); **a new expert soul in every package repo** — `okf-expert`, `aweb-expert`, `jira-expert`, `linear-expert`, `authoring-expert`, `dev-expert` (v2 `souls/<name>/`, team global, knows and evolves that capability); `package-catalog.json` kept as the official marketplace (bare-version `packages:` entries resolve through it) | lead (member-repo PRs to their owners; the expert souls' AGENTS.md drafted by me, reviewed by the package owner) | L |
-| **W9b** | **`oats.core` and `oats.setup` rewritten for the new architecture (human, 2026-09-23)** | The two official capabilities' skills and injects are rewritten to teach the *new* model, not patched: **`oats.core`** (`oats-operate`, `oats-souls`, the "you run on OATS" inject) — how an agent works inside an instance under this architecture: its home layout (`.oats/modules/`, `.agents/skills/`, `instance.json` modules/providers), the verbs it will actually use (`status`, `spawn --preview/--provider`, `retire`, `session`, `instance events`, `capabilities`, `souls`, `workspace status`), what a workspace/member/package/team is *from the agent's seat*, drift ("member moved since"), how to find and read other souls. **`oats.setup`** (`oats-config`/`oats-packages` → renamed to what they now are: `oats-workspace`, `oats-packages`, `oats-onboarding`) — the whole architecture and its best practices: workspace ↔ repo handshake and why, `oats-workspace.yaml` / `oats-membership.yaml` / `soul.yaml` v2 / `oats-local.yaml` field by field, teams as labels, member-tier vs package-tier and the non-collapse rule, `packages:` + lock v3 + per-version approval, the official catalog vs `git:` refs, `sync`/`package add`, the deployment directory (the operator's; no naming convention) and clone-then-spawn, private items, external souls, the standalone case, provider payload homes (soul/machine/spawn), what is deliberately NOT versioned and why. Every skill is validated against the shipped CLI (`oats <verb> --help` snapshot test) so they cannot drift from the commands. | lead (swarm + review) | M |
-| **W10** | **Docs** | **the rebuild guide (removed in 0.26.0; ships with the schemas; states that 0.24.x keeps spawning 0.24.x deployments)**; `docs/workspaces.md` rewritten around v2; `souls-and-instances.md`, `packages.md`, `configuration.md` (mostly deleted), `first-team.md` → the operator's deployment directory; DTO doc § Workspace v2; release notes | lead | M |
-| **W11** | **Onboarding skill** | `oats-setup-expert` / `oats.setup`: ASK for the deployment directory (an existing folder with the operator's clones is the usual case — no named convention, decision 9), `oats sync`, clone-then-spawn; **the hosting rule for mixed public/private organisations (decision 26): ask up front whether any member is private; if so the workspace file is hosted in a private repo that is NOT a public member (a dedicated private `workspace` repo is the honest shape), public contributors get the standalone case with `oats.core` by default (decision 25); `oats onboard` prints the same rule in its next-steps**; the `oats-operate` skill updated for the new verbs | lead | S |
-| **W12** | **Desktop follow-through** | New kernel DTOs (from W7) consumed the usual way — engineer reads the merged head, files pins, wires: Capabilities/Souls origin + team columns; "installed" removed as a state; spawn preview shows modules (from/commit/hash) + team; Workspaces surface shows membership status | Desktop engineer, after W7 | M |
-
-**Team review (Antares, 2026-09-23) folded in:** rebuild guide (W10), **second review (two aweb teams, stores, soul layout, standalone, public/private hosting → decisions 23–26: `messaging.byTeam`, stores = repo + provider `root`, `souls/` only, `oats.core` standalone default, private host rule taught by onboarding),** `--provider` instance payload (W6/W7), drift display (W7), duplicate-name rule (W6), 0.24.x-keeps-working stated everywhere.
-
-**Not in scope:** K11 (member admission UI/"Join"), K12 (transcript verb), 10B editor/detach — they wait behind this.
-
-## How phases land
-
-Each phase = one developer-swarm workflow (parallel agents, disjoint files, against a written module contract) → one adversarial-review workflow (independent reviewers with different lenses) → fixes → my four-gate review → merge to main. No compatibility flag: when a phase lands, its modules are the kernel and the v1 code they replace is deleted in the same PR, with tests rewritten. Between phases main is always green and always the canonical state.
-
-## Releases
-
-- **0.24.14** — 10A + 10B-0 (already planned; nothing v2). Ships first, independent.
-- **0.25.0** — W1–W8: the new model is the kernel, v1 deleted as each phase landed; `workspaceApi: 2`. Breaking by design (no migration).
-- **0.26.0** — W9 live (framework repos on v2), W11 onboarding, W12 Desktop.
-
-## Risks and how the plan handles them
-
-| Risk | Mitigation |
-|---|---|
-| Remote access context is subtle (SSH vs HTTPS vs `gh` token; private repos) | W2 uses git itself (`git ls-remote`, `git archive`/shallow fetch) with the operator's configured credential helpers — no new credential store; typed `cannot read` never guesses |
-| `core.mjs` entanglement makes W8 risky | W8 is deletion behind a green W7; `rg` proof of zero importers per module before each deletion (the v1-residue table from the Phase C review); CI + the Northwind fixture + Desktop suites are the gate |
-| Package approval UX ("asks once") in non-interactive spawns | `oats sync` is where approval is asked; `spawn` refuses `E_PACKAGE_UNAPPROVED` pointing at `sync` — never prompts mid-spawn |
-| Latest-state members drift between preview and apply | The resolution records the member commit; apply re-observes and refuses `E_DECISION_STALE` if it moved — same mechanism as today's decision revision |
-| Desktop relying on "installed" | Removed as a state in W12; until then the Capabilities view keeps working on 0.24.x DTOs (contracts unchanged) |
-
-## What I need from you
-
-1. **Approve the plan shape** (parallel v2 beside v1, one switch-over release, then delete) or tell me you want in-place.
-2. **Confirm I implement the kernel packages W1–W11 myself**, with the Desktop engineer on W12 after W7 — or whether Juan's side should take lanes (W2 remote observation and W5 packages are the most separable).
-3. **0.25.0 as the breaking release number** — fine?
-4. Anything in W9 you want different for the framework repos (team labels for the six souls: I'd put the five experts under `global`, `oats-setup-expert` under `global`, and any dev capabilities in `oats-dev` under `engineering`).

package/docs/design/2026-09-24-desktop-phase-f-boundary.md

@@ -1,242 +0,0 @@
-# Desktop Phase F — the Desktop is built FOR workspace model v2
-
-> **Vocabulary (2026-09-26):** there is no "personal team". Read it below as **the workspace's default team**. See the AMENDMENT at the top of [the teams contract](2026-09-25-teams-contract.md). This document is a record and keeps its original wording.
-
-**Status**: boundary for the Desktop engineer, issued 2026-09-24 by the lead under
-the human's direction: *"the desktop should not just adapt to the new version,
-it should be natively built for it."* Supersedes the Phase 3 parity plan's
-assumptions about what the Desktop reads; keeps its visual deliverable (the
-redesign frames, excl. 05/06).
-
-**Human's second directive, verbatim intent**: make ultra sure the Desktop is set
-up to work in the new setup — new versions, new CLI, new deployment shape.
-
-## 0. Why this is a rebuild of the model, not a patch
-
-The Desktop today is a 0.24 product that *tolerates* 0.25 kernels: its
-`ACCEPT_RANGE` admits `0.25.x`, so it launches, and the few CLI verbs it drives
-(`version`, `session *`, `spawn`, `retire`, `schedule`, `catalog`) still answer.
-But its **model of a deployment is 0.24's**, reimplemented in
-`packages/desktop/server/deployment.mjs`: it reads `oats-config.yaml`,
-`agents/<name>/soul`, `local-agents/`, and capability manifests from
-`.agents/capabilities/installed/`, and derives the roster itself. None of these
-is how a v2 deployment is shaped:
-
-| 0.24 (what the Desktop reads) | v2 (what a deployment IS) |
-|---|---|
-| `oats-config.yaml` at the repo root | `oats-local.yaml` at the deployment directory → `workspace:` URL |
-| souls at `agents/<name>/soul` | souls at `souls/<name>` **in member repos**, materialised per commit into `agents/<name>/souls/<commit>` |
-| capabilities installed into `.agents/capabilities/installed/` | packages resolved through `oats-workspace.yaml` + the official catalog, locked in `oats-lock.json`, **copied whole into each instance home** (`.oats/modules/<cap>`) |
-| `team:` block | `oats-membership.yaml` `team:` label per member; `messaging.byTeam.<label>` payloads |
-| `oats catalog` DTO | removed; the catalog is `package-catalog.json` resolved by `oats sync` |
-| roster derived by the Desktop | `oats status --json` is the roster (agents, instances, `modules[]` drift, `soul` source drift, `identity`) |
-
-A Desktop that keeps the left column and adds a few right-column fields is the
-"adapt" outcome the human rejected. Phase F replaces the left column.
-
-## 1. The principle: the kernel is the model; the Desktop renders and drives it
-
-- **Read model**: every fact the Desktop shows about a deployment comes from
-  the kernel's JSON surfaces — `oats status --json`, `oats inspect --json`,
-  `oats workspace status --json`, `oats spawn --preview --json`, `oats
-  readiness --json`, `oats version --json`, `oats sync --json`. The Desktop
-  does not parse `oats-config.yaml`, `oats-local.yaml`, `soul.yaml`,
-  manifests or lock files itself. Where a fact is missing from a kernel
-  surface, the fix is a kernel PR (lead's lane), not a Desktop-side parser.
-- **Write model**: every mutation is a kernel verb with `--json`: `sync`,
-  `sync --approve`, `spawn` (preview → `--expect-decision` apply), `retire`,
-  `session start|restart|recompose`, `schedule *`, `onboard`. The Desktop
-  never writes a deployment file.
-- **Version contract**: `oats version --json` `features[]` is the capability
-  probe. The Desktop's `ACCEPT_RANGE` moves to `>=0.25.6 <0.27.0` (the first
-  kernel with `served-identity`), and each feature the UI depends on is gated
-  on its `features[]` name, not on a version number.
-
-## 2. Deliverables (slices; each is one PR against main, each reviewed by the lead)
-
-**F1 — Deployment model on kernel JSON.** Replace
-`server/deployment.mjs`'s own readers with `oats status --json` (+ `oats
-workspace status --json` for the workspace header: name, key, members, packages,
-lock state, `approvalNeeded`). Roster rows carry `modules[]` drift, `soul`
-source (`repo: <member> @ <c7>`, "member moved since"), `identity`. Legacy
-`local-agents/`/`tmp-agents/` paths are dropped. Remove `server/catalog.mjs`'s
-`oats catalog` DTO validation (the verb no longer exists).
-
-**F2 — Workspace onboarding and sync.** A "Open deployment" flow that: detects a
-directory with `oats-local.yaml` (v2), or offers `oats onboard` for one without
-(the kernel asks for the deployment directory and the workspace URL — the
-Desktop collects both, never invents a folder name; decision 9). A "Sync"
-action runs `oats sync --json`; exit 2 with `approvalNeeded[]` renders an
-approval sheet showing each package's `executables` digest and applies with
-`oats sync --approve <id>@<version>` (the version string is what
-`approvalNeeded[].version` reports — for a git-pinned package, the full OID).
-Lock drift and `E_PACKAGE_INTEGRITY` are surfaced verbatim.
-
-**F3 — Spawn dialog on the v2 preview.** The preview already carries
-`modules`, `providers`, `settings.<cap>`, `team`, `resolution`, `decision`.
-Render: which modules the instance will get and from where (package vs member,
-commit); the merged `settings.<cap>` per provider (read-only); **Identity**
-select (local | global) with a Resident field for global, prefilled from
-`settings.<messaging cap>.identity`, forwarded as `--provider <cap>
-identity.mode=… identity.resident=…` (decision 27 — there is no kernel flag);
-`decision.effective.providers` is what the confirm binds. `cli-adapter.mjs`
-`SPAWN_ARG_RULES` gains one `provider` rule (capability id, dotted key, value
-grammar); no identity-named rules. Work mode select includes `workspace`.
-
-**F3 amended by the human (2026-09-24). This supersedes design frame 02 and the
-text above wherever they differ.** The dialog leads with the **instance name**:
-the purpose field becomes a name field that shows `<soul>-<purpose>` live and
-then the kernel's final name from the preview. A no-prefix toggle maps to
-`spawn --name <slug>`, gated on the `spawn-name` feature; `--purpose` stays the
-default. **Runtime and model** are always visible, with their resolved value and
-its source. **Relationship** sits in the main form, shown by default: None /
-Child of / Sibling of / Parent of. There is **no** modules/capabilities list and
-no attach-knowledge / child-spawn / open-PR toggles, because those behaviours
-come from capabilities. There is **no** preview button either. The preview runs
-in the background to fill the real defaults, and apply still binds with
-`--expect-decision` (`E_DECISION_STALE` re-previews). A collapsed section named
-**Developer settings** holds:
-- **work**: base | branch and the worktree path. A `checkout` soul is offered
-  "Use a worktree instead?" (`--work worktree`); the work mode itself comes
-  from the soul's `work:`.
-- harness permissions
-- launch config
-- session backend
-- Run on (the execution server)
-- wake-up
-- messaging identity (`--provider <cap> identity.mode=…`, decision 27)
-
-(Second human redirect, same day: relationship moved into the main form, work
-moved into the collapsed section, and the section was renamed from "Advanced".)
-Every modal gets a darker backdrop.
-
-**F4 — Instance card and roster on v2 facts.** The served-identity line (`acts
-as <address> via grant, expires <t>` / `alias <a> on <team>`); module rows with
-"moved since" markers and a **re-spawn** action (preview → apply, then retire
-the old instance — module homes answer `E_UNSUPPORTED_MODE` to
-`session recompose` by design; an instance never changes under itself); the
-soul-source row; quarantine state from `rollbackIncomplete` with the retry
-action (`oats retire`) and `--force` behind a confirm.
-
-**F5 — Redesign frames** (the original Phase 3 deliverable, excl. 05/06),
-implemented on top of F1–F4 rather than on the 0.24 model.
-
-**F7 — Side panels redesigned, teams everywhere (human, 2026-09-25). This
-supersedes the frames and the text above wherever they differ.** One Desktop PR:
-- **Side panels** in the spawn modal's design language (frame 01a):
-  - an identity header and compact cards;
-  - only useful facts (no "Not reported" rows), and empty sections hidden;
-  - relative dates, and shortened paths with Copy;
-  - errors as one plain sentence, with the code behind Details;
-  - discoverable cross-links between an instance and its soul.
-- **Terminal-side context panel tabs, in order:** Instance · Soul · Git & GitHub.
-- **Teams, per surface** (teams contract `docs/design/2026-09-25-teams-contract.md`):
-  - **Soul** (Workspace inspector): the soul's labels, primary marked, each
-    joinable or "not mapped by this workspace". Read-only, from
-    `inspect --soul` `teams`.
-  - **Instance** (Workspace inspector and the terminal-side Instance tab): the
-    live panel (#178). Personal is always on; joined teams have Leave, and
-    joinable ones have Join.
-  - **Spawn modal, main form** (not Developer settings), a Teams row:
-    - "Personal team — always", fixed;
-    - each joinable label as an unchecked checkbox, sent as
-      `--provider <messaging> join=<a,b>`;
-    - unmapped labels greyed with the reason;
-    - the line "By default it's only in your personal team. Tick the teams it
-      should also join."
-
-    The row is shown iff the preview carries `teams` AND the messaging
-    module's preview row lists `join` in `declares` (feature
-    `settings-declared`; the Desktop gates on declared facts, never on
-    versions).
-  - **Second human redirect (QA, same day):** unmapped labels are not shown
-    anywhere (no greyed rows, no "not mapped" text), and Teams in the spawn
-    modal is one row styled like Relationship.
-
-**F6 — Version and doctor surface.** `oats version --json` and `oats doctor
---json` in an About/Health pane; `ACCEPT_RANGE` and the three pins move to
-`>=0.25.6`; a kernel below the floor is refused with the upgrade command shown.
-
-Order: F1 → F2 → F3 → F4 → F5 → F6, or F1 then F3/F4 in parallel if the engineer
-spawns children (its call; the lead reviews each PR).
-
-## 3. What the engineer must LEARN first (before F1)
-
-Read, in this order, in the checked-out main:
-1. `docs/workspaces.md` — the v2 model end to end (deployment vs workspace,
-   members, packages, payloads, `byTeam`, hosting).
-2. the 0.25 rebuild guide (removed in 0.26.0; `docs/configuration.md` and
-   `oats onboard` now) — how an operator builds a deployment (this is the
-   flow F2 wraps).
-3. `docs/desktop-cli-api.md` — every JSON surface, with examples; note
-   `features[]`, `decision.effective.providers`, `instances[].identity`.
-4. `docs/design/2026-09-23-workspace-module-contracts.md` §0.25.x — what
-   changed per release and why.
-5. `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md` and
-   `…/served-identity-is-a-messaging-layer-fact.md` — the decisions.
-6. `test/fixtures/northwind/build.mjs` — the two-team fixture workspace; run
-   `node --test test/spawn-workspace.test.mjs` once and read what a v2 spawn
-   produces on disk (`.oats/modules/`, `instance.json` `modules`/`providers`/
-   `workspace.soul.id`).
-
-Then build a scratch deployment by hand with the CLI (`oats onboard`, `oats
-sync`, `oats sync --approve`, `oats spawn --preview`, `oats spawn --no-launch`,
-`oats status`, `oats inspect`, `oats retire`) against the Northwind fixture
-remotes, and keep the transcript: F1's tests are written against exactly those
-JSON shapes.
-
-## 3b. Native rework, not a compatibility layer (human, 2026-09-24)
-
-The human's rule, verbatim intent: *"do a native rework — do not keep v1-specific
-things, and no v1 modules calling v2 modules."* Concretely:
-
-- **Remove, do not wrap.** A 0.24 reader (`server/deployment.mjs`'s
-  `oats-config.yaml`/`soul.yaml`/manifest parsing, `local-agents/`,
-  `.agents/capabilities/installed/`, the `oats catalog` DTO) is deleted in the
-  slice that replaces it — never kept behind a flag, a fallback branch, or an
-  "if the kernel is old" path. The Desktop supports one kernel line
-  (`ACCEPT_RANGE` from 0.25.6) and refuses older ones with the upgrade command.
-- **No adapters between generations.** No module whose job is to translate a
-  v1-shaped object into a v2-shaped one or vice versa (no `legacyRosterToV2()`,
-  no `toOldCard()`); the v2 kernel JSON is consumed where it is read and shaped
-  once for rendering. If a v1 module still needs a v2 fact, the v1 module is
-  the thing being replaced — replace it, do not feed it.
-- **Names and types follow v2.** Types, fields and UI labels use the kernel's
-  vocabulary (workspace, member, package, module, deployment, soul source,
-  served identity); 0.24 vocabulary (installed capability, config chain, team
-  block, agents root as identity) leaves the codebase with the code that used
-  it. `git grep` for the old terms is part of each slice's exit check.
-- **Tests follow the same rule.** Fixtures shaped like 0.24 deployments are
-  deleted with the readers; new fixtures are v2 deployments produced by the
-  kernel (Northwind or a hand-built scratch deployment), not hand-written
-  JSON imitating old shapes.
-- **One exception, stated per case.** Where a 0.24 concept has a genuine v2
-  successor with the same meaning and the Desktop code is already correct for
-  it (a terminal broker, a tmux target admission), it stays — the PR names it
-  as "unchanged, v2-agnostic", not as "kept for compatibility".
-
-Exit check for Phase F as a whole: no file under `packages/desktop/` reads a
-deployment file, names a 0.24 concept, or contains a code path that exists
-only for a kernel below the floor.
-
-## 4. Rules that do not change
-
-- `packages/desktop/**` only; kernel gaps go to the lead as a written ask
-  (they become kernel PRs; the engineer never adds a Desktop-side parser to
-  work around one).
-- No native tmux/PTY/Electron execution by the agent; the lead's native gate
-  at review time is the acceptance.
-- Every slice: focused tests + the intended mutants on the new code; the
-  Desktop suite green; one PR per slice against main; lead's pr-review.
-- The design frames are the visual authority; the kernel JSON is the data
-  authority; where a frame shows a 0.24 concept (an "installed capability"
-  list, a `team:` block), the frame is adapted to the v2 concept and the
-  adaptation noted in the PR.
-
-## 5. Acceptance for Phase F as a whole
-
-The lead builds a fresh v2 deployment from the Northwind fixture using ONLY the
-Desktop (open → onboard → sync → approve → spawn with a global identity →
-inspect → retire) on kernel 0.25.6+, and every fact shown matches `oats status
---json` / `oats inspect --json` byte for byte. Nothing in
-`packages/desktop/server` reads a deployment file.

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

@@ -1,305 +0,0 @@
-# Phase D — the OATS project runs on the architecture it offers (plan)
-
-> **Vocabulary (2026-09-26):** there is no "personal team". Read it below as **the workspace's default team**. See the AMENDMENT at the top of [the teams contract](2026-09-25-teams-contract.md). This document is a record and keeps its original wording.
-
-**Status**: plan, 2026-09-24, lead. Decisions 18–22 of the workspace model, the
-five-soul roster and its 2026-09-24 amendment, the human's sequencing
-("knowledge centralisation first"; "do not retire live souls until their
-instances retire"). Mailed to the human and the OSS coordinator before the
-first swarm. Method per standing instruction: write → swarm build →
-adversarial-review swarm → PR → main; releases under delegated authority.
-
-## Co-leads and lanes (human, 2026-09-24)
-
-The human made the two `oats-expert` instances — the redesign lead
-(`oats-expert-knowledge-reworks`) and the maintainer of the second deployment
-(`oats-expert-antares`) — **co-leads with equivalent authority**, who agree on
-pushes. Agreed by both on 2026-09-24:
-
-| Lane | Owner | Status |
-|---|---|---|
-| Desktop Phase F (engineer PRs, native gates) | lead | assigned |
-| Kernel (`lib/`, `bin/`; kernel gaps raised by anyone) | lead | assigned |
-| Releases 0.25.7 and D5 (catalog + 0.26.0) | lead | assigned |
-| oats.aweb 1.13.0 re-land end to end | Antares | assigned |
-| D1 operator node + integrations node | Antares | assigned (draft PR `d1/operator-node` handed over) |
-| aweb and okf package-expert seams | Antares | assigned |
-| D2, D3, D4, desktop + kernel bundle migrations (D1 remainder) | lead, driven by the child instance `oats-expert-phase-d` | assigned (human, 2026-09-24: picked up by the lead's side after all, so as not to wait on the other deployment's human). The lead reviews and merges; Class B items go to Antares for ACK; D3's aweb/okf seams are drafted by the driver and settled with Antares. **Antares is a REQUIRED cross-reviewer** on D4's `oats.setup` rewrite (it must not drift from the operator node) and on D3's `aweb-expert` and `okf-expert` souls (the seams); the rest of the driver's PRs it reads without gating. |
-
-**Push protocol.**
-- **Class A** — notify after, one line: stewardship, docs and knowledge inside
-  one's own lane or node; merging a PR the other co-lead approved in writing;
-  merging one's own lane's PR after the other co-lead's review; the bump PR of
-  an agreed release.
-- **Class B** — `PUSH INTENT: <what> @ <commit/PR>` → `ACK <message-id>` before
-  acting: tags, releases, npm publishes, catalog pins; framework-behaviour
-  changes (kernel semantics, OKF/memory contracts, workspace config semantics,
-  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
-  gate; published tags never move; no destructive git on shared checkouts.
-- `main` on these repositories carries no branch or tag protection: the parity
-  gate and the cross-review are the only things between a merge and `main`.
-
-## Human decision (2026-09-24): no package approval
-
-**Package approval is removed from the kernel and from the Desktop.** People
-install a package only when they trust it. Declaring it in the workspace's
-`packages:` IS the trust decision, so there's no second, per-version approval
-step. This supersedes the "executables approved once per version" rule in
-`docs/workspaces.md` (§ Packages, lock, approval, catalog) and everything built
-on it:
-- `oats sync` exit 2 for pending approvals and `approvalNeeded`
-- `--approve <id>@<version>` and the interactive prompt
-- the lock's `approved` record
-- `E_PACKAGE_UNAPPROVED` at spawn and dispatch
-- the Desktop F2 approval flow (`E_APPROVAL_STALE`)
-- the planned pinned `--approve …=<digest>`
-
-What stays: the lock still pins each package to the exact commit and integrity,
-and restore still refuses drift (`E_PACKAGE_INTEGRITY`). Reproducibility is not
-approval. It's a breaking contract change, so it ships in a minor release, and
-the Desktop requires that kernel.
-
-## Slices, in order
-
-### D1 — Knowledge centralisation (IN PROGRESS)
-
-Goal: every roster soul's knowledge lives in the central base
-`awebai/oats-knowledge` (OKF 2.1.4), one owned node each; the in-repo
-`agents/*/soul/knowledge` bundles stop receiving writes and are decommissioned
-when no live instance links them.
-
-Done: nodes `oats-operator-expert` and `integrations-expert` chartered
-(oats-knowledge PR #3); eight attributed seeds landed in
-`agents/oats-expert/soul/knowledge/inbox` (oats PR #121); the roster amendment
-accepted; the rule "no per-soul knowledge merges" in force.
-
-Work:
-1. **Copy-migrate by judgement** (the 2026-09-21 method: two-part test plus the
-   2026-09-24 recipe refinement; not copying): `agents/oats-expert/soul/knowledge`
-   (~130 files) → node `oats-expert`; `agents/oats-desktop-engineer/soul/knowledge`
-   (~120) → `oats-desktop-expert`; `agents/cli-dev/soul/knowledge` (~155) →
-   `oats-kernel-expert`; `agents/integrations-expert/soul/knowledge` (13) →
-   `integrations-expert`. Others (`dev-coordinator`, `docs-expert`, `ux-designer`,
-   `lead`, `oats-coordinator`) are assessed for the few universal concepts they
-   hold and otherwise not carried. One PR per node on oats-knowledge, reviewed
-   by the lead; the OSS coordinator reviews the operator and integrations PRs.
-2. **Seed the operator node** — attributed to `oats-expert-antares`:
-   MOVE (not copy) from the oats-expert bundle: `lessons/the-aweb-team-root-must-sit-where-the-spawn-hook-looks`,
-   `lessons/okf-state-directory-must-sit-outside-every-work-tree`,
-   `lessons/capability-trust-hash-covers-the-installation-record`,
-   `lessons/a-locally-minted-oats-identity-has-no-cross-team-first-contact-address`,
-   `lessons/stale-checkout-serves-stale-soul`,
-   `playbooks/rebuild-a-deployment-in-scratch-against-local-bare-remotes`;
-   generalise the R1–R10 rebuild findings and the published-combination
-   verifications from `stewardship/delivery-log` (the log keeps the record).
-   From the inbox: `check-the-record-before-redesigning-identity`,
-   `grant-custody-service-and-renewal-belong-on-the-custody-host` (operator
-   half), `the-wake-broker-accepts-a-grant-home`.
-3. **Seed the integrations node** — from the inbox:
-   `a-merged-provider-payload-cannot-enforce-host-only-keys`,
-   `aw-grant-commands-resolve-the-identity-from-cwd-only` (discipline half),
-   `oats-runtime-requirements-for-grant-backed-resident-operation`; from the
-   integrations-expert bundle: `fake-aw-must-model-real-refusals` and the rest
-   of this week's harvested lessons.
-4. **Route the remainder of the inbox**: aweb package expert (D3) gets
-   `aweb-grants-are-team-bound-to-the-custody-identitys-active-team`,
-   `a-grant-signed-send-must-name-the-subject-as-sender` and the aw halves;
-   kernel expert gets `path-keyed-owner-registry-breaks-under-per-commit-soul-copies`.
-5. **Rebind the souls** in `souls/<name>/`: the `knowledge:` grammar there is
-   still 0.24's (`capability` + `source: git:…@v2.1.2#oats-package`); v2 is
-   `capabilities: { oats.okf: { from: package } }` plus `okf.json`
-   (`{ version: 1, owner: <node owner uuid>, owns: ["oats/<node>"], reads: [...] }`)
-   and the store `oats` naming `awebai/oats-knowledge` / `knowledge` / `main`.
-   Add `souls/oats-operator-expert` (rename of `oats-setup-expert`, keeps the
-   `oats.setup` charter) and `souls/integrations-expert`.
-6. **Do NOT delete** `agents/<n>/soul/knowledge` or the legacy souls while a
-   live instance links them (human rule). Record which are live; decommission
-   as they retire; new spawns use `souls/<n>`.
-7. **Release playbook** (`oats-expert` node, stewardship area): landing order
-   for provider PRs (tag → pin on the branch → squash; a bundled provider never
-   lands ahead of its tag), the version literals to bump on a catalog bump,
-   the mirror checker, the bump-PR step. First entries: today's two lessons.
-
-### D2 — The OATS workspace as a v2 workspace (decisions 18, 19, 21)
-
-`oats-workspace.yaml` at the `oats` repo (name `oats`; members = the seven
-framework repos incl. `oats` itself; `packages:` = oats.framework / okf / aweb /
-jira / linear / authoring / dev pinned from the catalog; `defaults.capabilities`
-= `oats.core` from package + knowledge `oats.okf`); `oats-membership.yaml` ×7
-(each package repo is a member AND a package publisher — non-collapse:
-`packages:` resolves it as a package, membership only grants trust and a soul).
-`package-catalog.json` stays the official marketplace (decision 21); the `oats`
-repo keeps `oats-dev` as dev capabilities. A fresh deployment directory (asked
-for, never named by convention — decision 9) is the acceptance: `oats onboard`
-→ `sync` → `approve` → spawn every roster soul `--no-launch`.
-
-### D3 — Souls to `souls/<name>` and the six package-expert souls (decision 20)
-
-Each package repo carries `souls/oats-<pkg>-expert` (oats-okf-expert,
-oats-aweb-expert, oats-jira-expert, oats-linear-expert, oats-authoring-expert,
-oats-dev-expert), the expert in that package, with a node in the central base
-from day one. **Messaging (human, 2026-09-24; supersedes the lead's per-soul rule):**
-`oats.aweb` is the workspace's messaging **default**
-(`defaults.messaging: { oats.aweb: { from: package } }`, oats#140); a soul
-without messaging says `messaging: none`. The human calls it "the most
-important capability, and most workspaces will use it as default", so the
-provider must work well as a default. Open items (oats.aweb unless noted):
-an unconfigured default must not make every soul unspawnable (onboarding sets
-the messaging root before the first spawn, and/or an unconfigured provider
-reports what is missing instead of refusing); error texts and `setup` must stop
-pointing at `oats-config.yaml`; the deployment names its messaging root
-explicitly rather than by search; `aw mail` usable from `work/`; retired aliases
-reusable. Kernel (lead): in v2 the team scope is the deployment directory and
-the team id comes from the messaging payload, not the classic `team:` block.
-#140 merges together with the first answer to the unspawnable-default item.
-**Teams (human, 2026-09-24): seamless by default.** (R1) Every person gets a
-**personal team per workspace**, created on first use with no invite and no
-manual initialisation — two people, or one person on two workspaces, get
-separate teams; stable across one person's machines. (R2) When a soul whose
-`team:` label the workspace maps to a shared team (`messaging.byTeam.<label>.team`)
-is spawned, the instance **joins that team seamlessly**. Authorization for R2
-(what entitles a person to join without an invite) is oats.aweb's design call
-with the aweb project, fail-closed and visible when the entitlement is missing.
-Kernel (lead): pass the soul's team label and the workspace identity so the
-provider derives the personal team deterministically; an unmapped team means
-"personal". The onboarding skill's manual invite-then-join step is the 1.12.0
-path and is rewritten when the provider ships R1/R2.
-**Teams, re-stated as THE priority (human, 2026-09-25; amends R1/R2):**
-"As long as we don't have this working seamlessly, people won't understand
-things." The two most important messaging behaviours, above every other
-messaging item:
-- **(R1) A personal team by default.** A user's agents in a workspace get
-  that person's personal team for the workspace with no setup step. This is
-  the default whenever the workspace maps nothing else.
-- **Defaults and joining (human, later the same day; refines R1/R2′):**
-  - By default an instance is in the person's personal team ONLY, even when
-    its soul names teams.
-  - Joining a wider team is explicit: a spawn choice, or at any point of the
-    instance's life one simple command, run by the human, another agent, or
-    the instance when told to. It covers only the soul's labels the workspace
-    maps.
-  - The Desktop offers these controls.
-  - Personal teams are per WORKSPACE: one personal team spanning several
-    workspaces is wrong, and aweb's per-workspace get-or-create (abjj) is
-    urgent. Nobody uses OATS in production yet, which is what keeps this a
-    fix and not a migration.
-  - Contract: `docs/design/2026-09-25-teams-contract.md`.
-- **(R2′) Wider teams, at spawn AND during an instance's life.** When a soul
-  belongs to one or more wider teams, its instance is also included in each
-  team the soul specifies, both at spawn and at any later point of its life,
-  not only at spawn. The teams are exactly those the workspace defines
-  (`messaging.byTeam` / the workspace's team labels); no team outside the
-  workspace's definition, and none silently missing. R2′ supersedes R2's
-  "is spawned … joins": joining is a lifetime operation, and a soul may name
-  several teams.
-Both are oats.aweb's (Antares) with aweb primitives. **The kernel's share is
-the lead's:**
-- today `soul.team` is ONE label (docs/soul.schema.json), and the messaging
-  payload merges `byTeam[soul.team]` for that one label. "Team/teams" needs a
-  soul to name several team labels, and the payload to carry each mapped
-  team's entry (not one merged view), so the provider can join all of them;
-- the workspace identity and the person's identity reach the provider, so
-  the personal team derives deterministically;
-- a lifecycle entry point for "join now" during an instance's life (for
-  example, a provider operation or hook run against a live home when the
-  workspace's teams or the soul's team labels change at a new commit).
-The contract shape is decided with Antares and recorded as a Decision before
-code. **Human, same day:** the primitives must be seamlessly integrated into
-the aweb messaging capability (acceptance is the oats.aweb experience: no
-manual `aw team …` anywhere we ship, and live instances follow the
-workspace's teams), and kernel changes are in scope, so the provider is not
-bent around today's kernel.
-**Naming (lead, 2026-09-24):** the `oats-` prefix on all six —
-it matches the repository names and the roster's `oats-kernel-`/`oats-desktop-`/
-`oats-operator-expert`, and it keeps instance aliases from colliding with the
-messaging project's own `aweb-expert` soul on a shared team. **Seams named in the
-charters** (roster amendment): `oats-aweb-expert` READS
-`aweb-protocol-expert` in base `aweb-oss-knowledge` (repo
-`github.com/awebai/aweb`, root `knowledge/`, branch `main`, OKF 2.1.x
-descriptor at `knowledge/okf-base.json`; owner `1913b77b-…`) through a
-read-only store reference; `oats-okf-expert` names its seam to the knowledge-theory
-material in `oats-expert`. Whether the aweb bookshelf decisions the program
-rests on are published into that node is the aweb side's call (asked).
-
-### D4 — `oats.core` and `oats.setup` rewritten (decision 22, W9b)
-
-Not patched: written for the v2 world. `oats.core`: home layout, `oats status`
-with modules/soul/identity rows, spawn preview → apply, `sync --approve`, the
-two-directory boundary, what a module is. `oats.setup` (held by
-`oats-operator-expert`): onboarding that ASKS for the deployment directory and
-the workspace URL, the hosting rule (decision 26), the public-member executable
-rule, the rebuild guide as procedure with the operator node as rationale.
-Developer souls in `oats.dev` gain `promotesTo: <node>` (roster amendment);
-the harvester delivers to that node as a PR the owning expert reviews.
-
-**D4 also removes the legacy the v2 model already declared gone** (human,
-2026-09-24; boundary §3b's native-rework rule applied to the repository):
-- **Docs, skills, examples** (driver, in D4): delete what v2 removed rather than
-  rewriting it (e.g. the OAS migration guide, the legacy Desktop succession
-  doc, `oats-config.yaml` examples, the `oats-config` skill); rewrite what
-  survives against `oats-local.yaml` and the workspace file; every remaining
-  mention of `oats-config.yaml` either describes its removal or is gone.
-- **Kernel** (lead, one Class B PR after D2 lands, because the OATS workspace
-  itself stops reading `oats-config.yaml` only once D2 converts it): the
-  `oats-config.yaml` scope chain and its readers, the `local-agents/` and
-  `tmp-agents/` layouts, the OAS-scope probes, the installed-capability tier
-  remnants. Removed, not flagged; the `REMOVED_VERBS` answers stay.
-- **In-repo package copies** (`capabilities/oats-{okf,aweb,jira,linear,authoring}`)
-  are NOT removed in D4: `package.json` ships `capabilities/` as the kernel's
-  bundled providers, pinned by the mirror-parity, release-packaging and
-  clean-room tests. Whether 0.26.0 still bundles them is a release decision
-  for D5 (lead); until then they stay unmarked. `private` becomes a schema key
-  (the kernel already reads it); `oats-review` is marked private.
-- **Legacy souls** (`agents/*` and their knowledge bundles) are NOT part of D4:
-  they go when the live instances linking them retire (human rule).
-
-**Human direction 2026-09-25: runtime → harness** ("throughout the app and cli and everywhere"). It ships in 0.26.0 as one kernel PR after (e):
-- every kernel-owned name is renamed with no alias (`--harness`, `launch-configs.<n>.harness`, `instance.json.harness`, JSON fields, feature `harness`);
-- two released-contract aliases stay: the provider env sets both `OATS_HARNESS` and `OATS_RUNTIME`, and manifests may say `requires[].runtime` or `requires[].harness`;
-- the Desktop switches on the `harness` feature.
-
-**Human direction 2026-09-25 (~17:20Z), amending the above: release 0.26.0 WITHOUT the harness rename; harness ships as a separate, later release.**
-- 0.26.0 ships main as it stands once the in-flight PRs land: (e), K, the teamsOf check, `layers.<layer>.from`, and Desktop F7. It keeps the `runtime` names everywhere.
-- The harness rename (the kernel PR, with the alias addendum: env `OATS_RUNTIME`, stdin `launch.runtime`, manifest `agents[].runtime`/`requires[].runtime`, `spawn --runtime`) ships in the **next minor, 0.27.0**. It is a breaking CLI/JSON change (`--runtime` refused on session/launch-config, `version.runtimes` dropped, launch-configs field renamed), so it isn't a patch. It ships together with the Desktop's switch on feature `harness`, and the Desktop's accepted kernel range widens to include 0.27.
-- Neither the kernel harness PR nor the Desktop switch merges to main before the v0.26.0 tag.
-
-Also: "core capabilities" is the human vocabulary for the knowledge/messaging/tasks capabilities in prose; wire names are unchanged.
-
-### D5 — Catalog update and 0.26.0
-
-Catalog pins for the new package versions; **widen Desktop `ACCEPT_RANGE` and
-the three pins FIRST** (minor bump rule); release notes; tag; the fresh
-deployment from D2 rebuilt on the published artefacts by the OSS coordinator
-(outsider verification) before the program board marks Phase D done.
-
-## Adversarial review (per slice)
-
-Each slice's swarm is followed by a review swarm with the standing lenses
-(direction against the decisions; correctness by reproduction; security —
-trust at acquisition, hoisted paths, hook approval, host-only keys; docs as
-contract — every guide claim has a test), plus two Phase-D-specific ones: **the
-outsider** (can a reader who was not in the room set OATS up from `oats.setup`
-alone?) and **the seam** (does every cross-project read resolve to a real node
-with a real owner?).
-
-## Out of scope
-
-Desktop (Phase F, its own boundary); oats.aweb 1.13.0 re-land (held on the
-aweb release); legacy `~/OATS` deployment cutover (the operator's, on the
-published 0.26.0).