@awebai/oats 0.29.3 → 0.30.0

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

@@ -1,289 +0,0 @@
-# OATS adoption plan: workspace first, knowledge and experts second
-
-**Date:** 2026-09-20
-
-**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 `the operator's deployment directory` 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.
-2. Centralise the curated knowledge and adopt the five expertise souls on that foundation.
-3. Complete Desktop design/feature parity against the resulting supported flows.
-
-A distribution work package (below, D1–D4) accompanies phase1: the kernel's operational skills become the official capabilities `oats.core` and `oats.setup`, every soul declares `oats.core` explicitly by default, onboarding creates an `oats-setup-expert`, and the official marketplace is the reviewed list in this repository.
-
-The second phase does not run as an unrelated bulk migration while the first is still changing underneath it. Necessary generic knowledge/provider boundary fixes belong in phase1; default OKF behavior and the actual corpus/roster cutover belong in phase2.
-
-## Target arrangement
-
-Approved repository responsibilities following the framework-hosted workspace choice. The two-phase order is unchanged:
-
-| Repository | Role in the new setup |
-|---|---|
-| `oats` | Kernel, adapters, Desktop and portable soul exports through `oats.yaml`; hosts the shared development workspace in `oats-workspace.yaml`; ships the official capabilities `oats.core` and `oats.setup` and the reviewed official package list (`package-catalog.json`) |
-| `oats-dev` | Reusable OATS development capabilities, including selected review skills/behavior; no longer responsible for defining the new workspace through a package template |
-| `oats-okf` | Reference knowledge capability and its complete reading/capture/judgment/delivery behavior |
-| `oats-aweb` | Messaging capability and its provider-owned identity/team/wake behavior |
-| `oats-authoring` | Reusable authoring support |
-| `oats-jira`, `oats-linear` | Optional task capabilities; workspace membership does not activate them |
-| `oats-knowledge` | Curated accepted expertise, not executable soul definitions, working transcripts or a copy of framework documentation |
-
-A workspace is a logical role and does not require a dedicated repository. The human has selected co-hosting in `oats`, preserving `oats-dev`'s capability purpose. Keep the `oats.dev` package where its reusable behavior is useful; separately review compatibility and the legacy template. Preserve published tags/payloads and exact restores. Merely adopting the workspace does not activate every capability.
-
-`oats-workspace.yaml` and `oats.yaml` have separate contracts even when co-located. Admit the framework repository explicitly if it participates as a member, and verify matching reciprocal observations. Importing a public OATS soul or installing the framework must NOT implicitly select or enroll an adopter in the framework's development workspace. A separate workspace repository remains an option if independent permissions or lifecycle become necessary.
-
-The shared workspace is **not a shared live runtime**. Each operator retains local deployment mappings, runtime/authentication, state and explicit approvals. Config and nonsecret lock/template provenance can be Git-shared where supported; credentials and live instance state cannot. Git access, organizational admission, executable approval and messaging enrollment remain distinct.
-
-## Verified starting point
-
-- Kernel/Pi/Desktop0.24.0 and OKF2.1.0 are released. Workspace/source codecs, discovery, retained composition and scoped execution/provider machinery already exist. This is not a kernel rewrite from zero.
-- A read-only September20 inventory found no root `oats-workspace.yaml` in either `oats` or `oats-dev` and no root `oats.yaml` in the framework or the six inspected capability/development repositories. The selected knowledge repository is not yet initialized. These observations must be refreshed against exact heads before editing.
-- The default development package still supplies a legacy config template and `oats.review`; these are capability/template exports, not a Git workspace definition.
-- The checked-in roster remains legacy. A five-role candidate and curated corpus are preserved but not validly published/adopted as the new portable setup.
-- Earlier live native/directory-learning evidence is valuable but does not prove our actual Git workspace, two-operator deployment, private messaging or Git-PR learning cutover.
-- Current source contains the approved forward correction of the accidentally integrated held record patch. Preserve repaired history and its active-content exclusion; do not reopen that incident or repeat closed test matrices.
-
-# Phase 1 — adopt the workspace and Portable Souls architecture
-
-## P1.1 — freeze the repository, source and runtime map
-
-**Owner:** integration lead, with kernel/provider/deployment owners.
-
-Produce one bounded implementation checklist from the actual current code and chosen package revisions:
-
-- Exact workspace repository and intended member repositories; external consumption is not membership.
-- Source/export locations for the necessary transitional roles and the eventual five experts. Recommended reusable soul editions remain in the framework repository, separate from live legacy `agents/` sources.
-- Compatible package/source revisions, required capabilities and operator-selectable bindings.
-- Actual runtime/backend and messaging-delivery profiles to support, including intentional local differences. Do not replace native credentials/profiles or copy one operator's raw configuration to another.
-- Existing support versus declaration/resource drift versus provider work versus genuinely missing kernel/CLI seams. Every missing generic field or authority change gets a concrete proposal; reuse the current parser/resolver/invocation engine.
-
-**Deliverable:** an exact repository/change/owner matrix and a small gap list, not another open-ended architecture investigation.
-
-## P1.2 — author the real workspace
-
-**Owner:** workspace/deployment owner, reviewed by the integration lead.
-
-Add `oats-workspace.yaml` to the confirmed workspace home `oats` using the shipped schema, alongside that repository's separate `oats.yaml` export index:
-
-- Intended members, selected source imports with real reviewed revisions and aliases.
-- Shared defaults bounded by soul requirements, not a new repository-level policy hierarchy.
-- Provider-owned knowledge declarations and team aliases only where meaningful and safe to publish.
-- Explicit discovery/catalog references if needed, not an OATS-hosted registry.
-
-Do not advertise a planned source export or uninitialized knowledge base as usable. Do not commit secrets, private runtime state or machine-specific execution paths into the public workspace. The phase2 knowledge destination can remain deliberately unresolved until it is initialized and approved.
-
-**Deliverable:** validated, reviewable workspace definition and a short explanation of shared versus operator-local choices.
-
-## P1.3 — publish repository indexes and reciprocal admission
-
-**Owner:** each repository/package owner, coordinated by the integration lead.
-
-For every intended member:
-
-- Add `oats.yaml` with the correct workspace backlink and actual exports.
-- Advertise package roots containing real `oats-package.json` files, not arbitrary npm roots.
-- Advertise only source-complete souls with explicit definition paths; imported souls remain references, not adopter-owned copies.
-- Add knowledge exports only when the provider declaration/base actually exists. A metadata-only bootstrap of the knowledge repository must not masquerade as corpus migration or a ready store.
-- Preserve package identities, compatible version floors, immutable releases and old locked revisions.
-
-Coordinate publication of backlinks and workspace admission. One side alone is not membership. Resolve the existing contract's default-branch observations and explicit revisions honestly; do not invent mutually dependent future commit pins or guess `main` when the host's default branch is required.
-
-**Deliverable:** discovery can qualify intended membership and enumerate real exports across repositories without requiring every source checkout to be present locally.
-
-## P1.4 — make the declared setup operational
-
-**Owner:** kernel/lifecycle owner and the owners of the selected capabilities.
-
-This is **adoption and validation first**, not a mandate to write new runtime code. Exercise the already shipped paths with correct declarations and inputs before changing them. A new inspection convenience is not automatically an adoption blocker; preserve it as a separate proposal unless necessity is demonstrated. Provider adaptation must identify the minimum usable completion path, not merely replace one refusal with a later refusal.
-
-Close only demonstrated gaps needed by the chosen workspace/profile:
-
-- Public inspection/preparation, explicit artifact approval, retained resolution, scaffold and native start through supported CLI/API paths.
-- Complete source/skill/capability closure; independent source, deployment and work-target identities.
-- Actual provider bindings, required hooks and their truthful readiness. A parsed team/store declaration is not enrollment or a working provider.
-- Required continuation, capture and applicable wake/retire/recovery behavior for the selected profile. A path that is still unsupported must be named and resolved, not hidden behind successful start-only evidence.
-- Version-correct operational skills and guidance, including known stale claims that public request/context/launch inputs are unavailable.
-- Any minimal Desktop compatibility needed to observe/refuse operations truthfully; full redesign parity is later.
-
-Use an explicitly agreed transitional edition of an existing role for the pilot, not a new fictitious owner or bootstrap host. Retain its actual requirements. Any temporary acceptance store/profile must be explicitly scoped and must not be counted as production knowledge adoption. Do not silently remove messaging, knowledge, plugins or other requirements to make it launch.
-
-New package defaults or executable changes require appropriate release/pinning/approval. Adding metadata does not itself require replacing stable runtime components, but a real runtime change is not deployed merely because it reached main.
-
-**Deliverable:** one reproducible operator path from the shared Git definition to a genuinely usable, retained portable instance under the chosen profile.
-
-## P1.5 — adopt fresh local deployments without disturbing existing work
-
-**Owner:** each local operator; coordinated readiness/evidence review by the integration lead.
-
-- Use a fresh explicit deployment location where existing managed state conflicts. Preserve old configs, locks, knowledge, identities, sessions, worktrees and pending jobs.
-- Map local repositories/work targets deliberately; operators need not have identical directory layouts.
-- Review exact software and restore/acquire through supported tooling. Keep native auth and deliberately chosen model/delivery behavior local.
-- Verify source discovery, reciprocal admission, imported identity, retained composition and actual start/continuation on the approved test host.
-- Check the second operator's declarations/readiness and an actual message/reply through its own identity without requesting model or GUI tests on that machine. Existing legacy connectivity is not automatically new-profile qualification.
-- Exercise relevant source-unavailability/update safeguards using owned test fixtures, never by deleting working source repositories or modifying retained artifacts.
-
-### Phase1 exit gate
-
-The shared workspace and repository declarations are published and discoverable; a fresh deployment can select a real portable source and complete the supported prepare/approve/scaffold/start path with its declared requirements. Required lifecycle/provider limitations are resolved or explicitly constrain the qualified profile. Both operators understand the same shared definition and their own local differences. Old live deployments remain preserved.
-
-**Seven YAML files alone do not satisfy this gate.** Nor does an isolated fixture establish production provider readiness. No claim that the five new knowledge-backed experts are adopted is made yet.
-
-# Distribution — official capabilities and the official marketplace
-
-**Status:** direction accepted by the human on 2026-09-20 (decision `agents/oats-expert/soul/knowledge/decisions/official-capabilities-oats-core-setup-and-marketplace.md`). Runs alongside phase1 once the current lanes' PRs are integrated; it changes how OATS itself is distributed and must be in place before phase2 souls are published, since those souls declare their capabilities explicitly.
-
-Today the skills that teach an agent to operate OATS (`oats`, `oats-config`, `oats-packages`) and the "you run on OATS" injection are ambient kernel content. Under Portable Souls a soul declares its capabilities and their sources, so this knowledge must be packaged as capabilities a soul can declare, remove or replace.
-
-## D1 — package `oats.core` and `oats.setup` from the oats repository
-
-**Owner:** capability/provider owner (packaging), reviewed by the integration lead.
-
-- `oats.core` — day-to-day operation, present on every soul by default: skill `oats-operate` (status, spawn, retire, doctor, lifecycle, instance layout) and skill `oats-souls` (soul discovery, spawn relations/linkage, roster, workspace-member souls), plus the former `injects/oats.md` injection.
-- `oats.setup` — deployment and workspace configuration ("OATS Soul Setup"): the former `oats-config` and `oats-packages` skills, workspace adoption guidance and package acquisition/trust/lock knowledge.
-- Both live under the framework's `oats-package/capabilities/` beside `oats-knowledge-theory`, are exported through the repository package manifest and `oats.yaml`, and are versioned/locked like any package. Content is moved from the existing skills, not re-authored; stale claims are corrected in the move.
-- The `instance-boundary` injection, work-mode briefings and config-declared injections **stay kernel-owned** — they describe the layout the kernel itself creates.
-
-**Deliverable:** two installable capabilities with manifests and focused inventory tests; the kernel unchanged except for registering nothing new.
-
-## D2 — explicit default `oats.core` on every soul; kernel skills de-ambiented
-
-**Owner:** kernel/lifecycle owner.
-
-- Every soul-creation path (CLI, Desktop, setup guidance) writes `requires.capabilities.oats.core` with its source into the soul definition. It is visible in the file and the user can remove it.
-- The kernel does **not** inject `oats.core` when absent; `oats doctor` reports a soul that has neither `oats.core` nor a deliberate opt-out note, as information, not an error.
-- The hard-coded kernel skill list and the `kernel:oats` injection are retired once souls carry `oats.core`. Transition: both coexist for one release, with existing kernel-listed skills marked deprecated in favor of the capability.
-- Existing checked-in souls in this repository are updated to declare `oats.core` explicitly as part of the same change.
-
-**Deliverable:** soul definitions are honest about OATS operational knowledge; no hidden kernel dependency.
-
-## D3 — onboarding creates and instantiates `oats-setup-expert`
-
-**Owner:** kernel/lifecycle owner, with the workspace/source owner for the soul edition.
-
-- Onboarding a new workspace (or a fresh deployment of one) produces a soul `oats-setup-expert` whose definition declares **both** `oats.core` and `oats.setup`, prepares/approves its artifacts under the normal approval bar, and instantiates it.
-- The setup expert then drives adoption: declaring/adopting member repositories, selecting fundamental-layer capabilities, creating further souls (each with explicit `oats.core`), and walking the operator through trust/approval steps. Setup becomes a conversation with a competent soul, not a wall of flags.
-- No new bootstrap authority: prepare/approve/scaffold/start remain the shipped path; onboarding only chooses the first soul and its capabilities. The entry point (CLI verb, Desktop flow, or both) and its relation to the version-scoped `oats init`/`oats use` compatibility path is proposed and reviewed separately; do not document a command before it exists.
-- The soul edition itself is source-complete and exported from the oats repository like the other framework souls.
-
-**Deliverable:** one reproducible path from "empty workspace" to a running `oats-setup-expert` that can configure the rest.
-
-## D4 — the official marketplace is the reviewed list in the oats repository
-
-**Owner:** workspace/source owner (list and docs); Desktop owner for the view in the parity phase.
-
-- `package-catalog.json` in `awebai/oats` (read today by `officialPackageCatalog()`) **is** the official marketplace. Listing = official. Do not build a second registry.
-- Officialness is granted by a reviewed PR to that file — for external packages too. That review is the safety gate: we control what is called official even when we do not host the code. Document the acceptance criteria (source-complete package, pinned immutable ref, payload root, trust posture, maintainer contact).
-- First entries: `oats.core`, `oats.setup`, `oats.okf`, `oats.aweb`, `oats.authoring`, `oats.jira`, `oats.linear`, `oats.dev`, `oats.knowledge-theory` (the fundamentals are already listed; add the two new ones once released).
-- Discovery is universal (CLI and Desktop marketplace view/search present official packages as assignable to a soul); installation still goes through acquisition, lock and per-capability executable trust. Discoverable is not installed; installed is not approved.
-
-**Deliverable:** documented official-list policy and seeded list; Desktop view tracked under phase3 parity.
-
-### Distribution exit gate
-
-A fresh workspace onboarding yields an `oats-setup-expert` whose definition shows `oats.core` and `oats.setup` resolved from the official list; a soul created by that expert shows `oats.core` explicitly and still runs after the user removes it; the kernel ships no ambient operational skill. Framework souls in this repository declare `oats.core`.
-
-# Phase 2 — centralise knowledge and adopt the five expert souls
-
-## P2.1 — align the reference knowledge profile
-
-**Owner:** OKF owner, with kernel review only for demonstrated generic-boundary gaps.
-
-Apply the accepted knowledge model to actual runtime instructions, skills, bindings and behavior:
-
-- Centralised per-soul homes with stable identity and explicit cross-reads.
-- Capability-owned organisation, placement, reading, capture, judgment and delivery—not a kernel-owned mandatory knowledge pipeline.
-- Distinct accepted knowledge, local evidence/working state and immutable execution artifacts.
-- Supported reading/refresh/capture for both short- and long-running instances; no automatic active-context synchronisation or silent curriculum replacement.
-- Independent promotion, reference doctrine and PR-only Git delivery, distinguishing proposal, accepted merge and reader visibility.
-
-Do not implement automatic speciation, redirects, whole-session cloning, a permanent maintenance agent or every alternative provider as prerequisites. Preserve their architectural possibility without claiming them shipped.
-
-## P2.2 — curate and publish the shared knowledge base
-
-**Owner:** knowledge steward, with human publication/visibility decision.
-
-- Confirm public/private visibility and access before publishing corpus or exposing private locators in the workspace.
-- Reuse the existing curation and disposition records. Add a focused freshness pass for subsequent accepted decisions and discoveries; do not redo the entire audit or bulk-copy legacy folders.
-- Preserve useful expertise, rationale, limitations and maintained slow state. Keep formal contracts/code navigation in docs, repeatable procedures in skills, and task residue/transcripts in local evidence.
-- Give each accepted concept one canonical home, valid cross-links and appropriate provenance/freshness.
-- Separate administrative repository/bootstrap scaffolding from corpus acceptance. Deliver the corpus through reviewed changes; ongoing runtime Git learning remains PR-only.
-
-**Deliverable:** a small, current, reviewed knowledge base with an explicit owner/read mapping, not merely a passing validator over relocated text.
-
-## P2.3 — publish and adopt the five expertise souls
-
-**Owner:** soul/source maintainer, reviewed by the integration lead and knowledge steward.
-
-The five permanent expertise roles are:
-
-1. `oats-expert` — overall direction and cross-cutting architectural judgment.
-2. `oats-kernel-expert` — kernel/capability contract rationale and technical expertise.
-3. `oats-desktop-expert` — Desktop/product/interaction expertise.
-4. `market-research-expert` — sourced research and positioning evidence.
-5. `oats-assistant` — user-facing adoption and onboarding help.
-
-Use source-complete portable declarations, canonical `AGENTS.md` and the `CLAUDE.md` alias, reviewed procedures, explicit capability requirements and stable knowledge bindings. Final export paths must be deliberately chosen before pinning imports. New adopters' learning must not silently default to the source publisher's writer.
-
-The optional knowledge-theory authoring expert is not a sixth mandatory runtime role. The public assistant must work through a real supported adoption path, not only as a maintainer-local role. A distinct cold-bootstrap helper protocol, if needed, requires its own scoped decision; do not invent a persistent owner to bypass helper authority.
-
-**Deliverable:** five indexed reusable sources, imported by the workspace at real compatible revisions, with the intended expertise/reading boundaries—not renamed engineer charters.
-
-## P2.4 — demonstrate learning, then switch writers/readers
-
-**Owner:** integration lead and OKF owner, with local operators.
-
-Use a small real end-to-end path:
-
-1. An expert obtains its accepted foundation and relevant cross-role context.
-2. A working instance captures a useful new finding.
-3. An independent worker judges it and delivers a Git PR.
-4. Authorised review/merge accepts it.
-5. A different/fresh instance obtains that accepted learning through the supported reader/refresh path.
-
-Do not seed the conclusion and call that learning. Check representative questions and source/binding correctness for all five roles without running five redundant full matrices.
-
-Then cut over the workspace imports/bindings deliberately. Reconcile or hold outstanding old harvests rather than retarget their frozen destinations; avoid duplicate old/new writers. Do not rename live homes or borrow identities. Keep original knowledge and work recoverable. Retirement/removal of superseded sources is a separately verified cleanup after unfinished work is safe.
-
-### Phase2 exit gate
-
-The five experts run from portable sources in the shared workspace, consult the curated common knowledge, and demonstrate actual reviewed Git learning visible to a subsequent reader. Publication, access, writer ownership and local runtime configuration are known. The old setup is preserved until this is true.
-
-# Execution and review discipline
-
-The initial implementation lanes are deliberately disjoint:
-
-| Lane | Owns | Does not own |
-|---|---|---|
-| Workspace/source declarations | Framework workspace/member indexes, transitional `souls/oats-expert/` edition preserving its existing logical owner, setup guide and metadata tests; other capability repositories' root `oats.yaml` only | Kernel or provider runtime, provider README/tests, framework mirrors, corpus migration |
-| Kernel/onboarding | Public preparation/lifecycle glue, same-repository workspace regression coverage and portable-setup skill | Root workspace/member indexes, soul editions, provider payloads, record optimisation |
-| Capability/provider readiness | Canonical OKF/aweb payloads, manifests, skills/docs/tests and actual profile-readiness facts | Kernel/record, root member indexes, soul editions, framework mirrors/catalog |
-| Integration lead | Scope/interface arbitration, exact review/integration, shared stewardship, release coordination and combined deployment acceptance | Unilateral changes to another operator's credentials, identity or local deployment |
-
-Distribution lanes (D1–D4) map onto the same owners: capability/provider readiness packages the two capabilities (D1); kernel/onboarding owns the explicit default, kernel de-ambienting and the setup-expert onboarding (D2, D3); workspace/source declarations own the official list and its policy docs (D4). They are assigned only after the current phase1 PRs are integrated, to avoid overlapping edits in `lib/core.mjs` and the skills tree.
-
-The phase1 transitional source is an edition of the existing overall expert, not the full five-role rebuild or an invented bootstrap owner. Source publication precedes workspace import pinning to its actual approved revision. An owner reports a precise cross-lane seam rather than patching another lane's files. No new review agents or per-edit permission loops are required for agreed work.
-
-- One redesign lead owns the cross-repository plan, dependency order, scope questions and integration picture. Contributors deliver bounded agreed work and exact diffs/PRs; no wholesale branch merges that import unrelated or held work.
-- Workspace/source metadata and compatibility work can proceed in parallel once their shared identities/contracts are agreed. Provider changes are reviewed against concrete missing seams, not speculative replacement architectures.
-- Local operator approval remains necessary for installation, executable trust, identity/team changes, deployment cutover and disclosure. Lead coordination is not authority over unrelated deployments.
-- Use focused changed-path checks while developing, then one coherent acceptance gate per usable increment. Keep original failed evidence and distinguish author reports, independent checks, installed bytes and real execution.
-- Preserve normal native harness auth and explicit permissions. No implicit credential handling, safety bypasses, source/identity borrowing or model/GUI testing on another operator's machine.
-- Publish updated versions only where code/payload changes require them; never move existing tags. Record delivery and actual adoption separately.
-
-# Decisions to settle at the appropriate boundary
-
-- Workspace home is settled: `oats` hosts it and `oats-dev` remains development capabilities. Phase1 authorises the parallel existing-role edition at `souls/oats-expert/`; preserve its logical owner and settle any remaining source-policy details before publishing. Final five-role publication/cutover remains phase2, not permission to replace the live roster now.
-- Confirm knowledge visibility and public-safe content before phase2 publication; this need not block the phase1 contract inventory.
-- Agree the exact pilot/provider/runtime profile and its supported lifecycle. No hidden fallback to an easier profile.
-- Review any newly identified generic contract or bootstrap authority change explicitly. Existing accepted constraints do not need repeated approval.
-
-# References
-
-- [Portable source/workspace declarations](2026-09-15-portable-declarations.md)
-- [Workspace schema](../oats-workspace.schema.json) and [repository index schema](../oats-member.schema.json)
-- [Fresh onboarding boundary](2026-09-16-portable-onboarding.md) — read historical pending statements with the actual current public routes and release scope
-- [Released0.24 scope](../release-notes/v0.24.0.md)
-- [Canonical knowledge theory](../knowledge-theory.md)
-- [Generic knowledge/capability boundary](2026-09-16-knowledge-capability-contract.md)

package/docs/design/2026-09-20-workspace-onboarding-public.md

@@ -1,207 +0,0 @@
-# Public source inspection for same-repository workspace onboarding
-
-This increment supplies the missing public adapter around the EXISTING portable
-onboarding facade. It does not define another workspace format, parser, resolver,
-registry, identity or permission. Source/member declarations remain separately
-owned; production capability/profile readiness is not established by the fixture.
-
-## Read-only entry
-
-```sh
-oats inspect --request /absolute/inspection.json --json
-# Optional explicit request export (new private file; never overwrite):
-oats inspect --request /absolute/inspection.json --emit-prepare-request /absolute/preparation.json --json
-```
-
-This mode accepts one request file, optional `--emit-prepare-request`, and `--json`.
-The 0.24.4 follow-up also accepts the complete preparation request's `operator`,
-`launch`, `helperLaunches`, `mode`, and `allowLocalPaths` fields. Inspection ignores
-their semantics: it does not validate provider payloads, select a runtime/model,
-execute a codec, or authorize local acquisition. `ignored: [...]` lists only the
-present field NAMES in a stable order; values stay out of the metadata view and
-`omitted.*` remains true. Preparation still validates those fields normally.
-Unknown fields remain errors. Explicit captured selectors
-or current-context flags conflict before file reads; inherited captured environment
-is not new-work input. Other existing inspect modes are unchanged. The shared
-bounded strict JSON request reader feeds the existing inspection validator intact:
-unknown fields are not dropped, and no missing context comes from current config.
-
-The public core export `inspectPortableOnboarding(input, {repositoryOptions}?)`
-owns one transient repository transaction and its guarded cleanup. Its input is
-the existing facade contract:
-
-```json
-{
-  "deployment": "/operator/deployments/example",
-  "workTarget": "/operator/projects/example",
-  "source": "advertised-alias",
-  "origin": {"kind":"operator","document":{"kind":"operator","id":"setup"},"pointer":"/source"},
-  "workspace": {
-    "source": "git:https://example.org/team/framework.git",
-    "origin": {"kind":"operator","document":{"kind":"operator","id":"setup"},"pointer":"/workspace"}
-  },
-  "member": {
-    "source": "git:https://example.org/team/framework.git",
-    "origin": {"kind":"operator","document":{"kind":"operator","id":"setup"},"pointer":"/member"}
-  }
-}
-```
-
-These paths/references are placeholders. Workspace and member may identify the
-SAME repository. They still require explicit workspace admission, a member
-backlink and matching observed commits. Omitted repository revisions observe the
-hosting default branch; they do not guess `main` or create circular future pins.
-
-Independent adoption replaces workspace/member with an explicit source reference
-`{source, soul, revision, alias}` and explicit `standaloneContextKey` (opaque string
-or null). It does not follow the source publisher's workspace backlink or inherit
-its development defaults/teams. A member check is optional; without one, import
-reports `not-requested` membership, never enrollment.
-
-## Metadata is not authority or provider readiness
-
-Normal JSON envelope `result` retains schemaVersion1 and the existing statuses:
-`ready-for-preparation`, `needs-configuration`, `separate-deployment-required`.
-`ok:true` means the observation succeeded, including a truthful hold. Separate
-fields expose source identity/revision/export metadata, deployment/work paths,
-workspace identity/import locators, reciprocal observations, declared teams and
-non-effect claims. Inspection executes no provider, hook, approval or native
-backend and writes no deployment state; repository scratch is transient.
-
-The public projection deliberately does NOT expose `source.reference` as a
-reusable mutation input. Opaque adoption values and provider declaration payloads
-have not been classified by their owner and are omitted. Import summaries expose
-`adoptionPresent`; knowledge export summaries expose contract/version and
-`payloadOmitted`. Top-level `omitted:{providerPayloads:true,adoptionValues:true}`
-states that this is a metadata view, not a lossless request or a safe-payload claim.
-It is not an issued `buildFreshPreparationRequest` witness, even in the same
-process. The opt-in `--emit-prepare-request` route calls that existing builder
-on the real in-process inspection before dropping the private witness. It writes
-only `.preparation` to a new mode-0600 file at an explicit normalized absolute
-path with an existing real parent; existing files/symlinks are refused, never
-overwritten. JSON output names `prepareRequestFile` and records the explicit
-request-file write in `effects`; it does not echo the request contents. The
-export can carry unclassified adoption declarations and must remain private;
-requests must contain nonsecret values or credential references, never secrets.
-A held inspection cannot emit a fresh preparation request. Core callers can
-explicitly request this data via `{includePrepareRequest:true}`; the default
-metadata projection and its omissions are unchanged.
-
-The explicit export preserves authored prepare-only fields privately through the
-existing builder, without interpreting them; it must not silently drop operator
-bindings or launch/helper choices. They remain unvalidated until preparation.
-This does not expose their values in normal metadata or turn ignored values into
-inspection authority.
-
-The file is reusable new-work input, NOT a stored resolution, approval, admission,
-or serialized ready-inspection permission. Preparation performs fresh validation
-and observations, including re-resolving any mutable source selectors. Provider
-configuration still requires explicit operator choices; conversion invents none.
-
-Existing managed deployment state is preserved and reported, not repaired or
-migrated. An absent selected path requires explicit operator provisioning and
-reinspection. Prepare refuses it with typed `needs-configuration` and provisioning
-guidance before fetching or writing managed state, not a raw ENOENT. Inspection's
-`ready` means the path is eligible for fresh setup, not already provisioned.
-The serialized inspection does not lock the filesystem or authorize
-later mutation; preparation retains its own existing validation/custody rules.
-The inspected work target does not become source identity or an implied placement
-choice. Supported captured directory scaffolds own their separate H/work.
-
-## Existing preparation and retained execution
-
-`oats prepare --request` accepts deployment/source/origin, optional `workTarget`,
-workspace/member OR standalone context, operator policy/bindings,
-mode/local-input authorization, launch and helperLaunches. The original minimal
-inspection request (without inspection-only `catalogIndexes`) is also accepted;
-use the converter rather than stripping fields from a metadata/result wrapper.
-Explicit `workTarget` is validated with the same physical existing-directory
-validator as inspection and returned as work-context metadata. It takes precedence
-over any caller assumption about cwd: no cwd/config fallback selects its value.
-Omitting it preserves prior preparation behavior without inventing a placement.
-It does not change source identity, `operator.localBase`, work mode, or captured
-H/work placement. Do not pass an inspection result/catalog wrapper or private
-scratch `directory` to preparation. Exact executable approval is separate. A required provider whose binding
-code is unapproved may return `needs-configuration` with an `approval-required`
-problem and exact artifact-set/capability requests, before any record exists:
-
-```sh
-oats trust <capability> --deployment <D> --artifact-set <returned-id> --json
-oats prepare --request /absolute/preparation.json --json
-oats inspect --deployment <D> --resolution <R> --composition --json
-oats spawn <subject> --deployment <D> --resolution <R> --home <new-H> --no-launch --json
-oats session start --deployment <D> --resolution <R> --home <H> --request /absolute/native.json --json
-```
-
-Each `selections[]` row carries an `artifactSet` id and an `approvalRequired[]`
-array of **capability ids**. Pair them: pass the capability to `trust` and that
-row's artifact-set id to `--artifact-set`. These are not interchangeable ids.
-`trust <capability> --dir <D>` against a v3 deployment now refuses with typed
-`needs-configuration` and exact available-set commands; it never picks or approves
-a set automatically. Classic v1/v2 trust remains the classic route.
-
-Provider preparation problems carry `slot` and `capability`, plus original
-provenance where available. A no-interface provider is identified with kernel-known
-manifest/version facts. Other supported slots still normalize, resolve through
-the same choice engine, and bind if their own choices are resolved; any required
-slot problem still prevents publication. Provider free text is not passed through.
-The 0.24.4 follow-up preserves only exact fixed reasons declared by the selected
-manifest (or its reviewed kernel compatibility list when absent); see the
-[binding wire](2026-09-16-provider-binding-wire.md). Human CLI output also shows a
-problem's existing choice key, without inventing new key/provider semantics.
-Different opaque inputs need not produce different public errors if both fail the
-same provider prerequisite. In particular, missing OKF host runtime settings can
-hold both syntactically valid Git locators; preparation does not test whether a
-remote repository exists. Required readiness checks remain later, with the provider.
-
-### Operator input
-
-When present, `operator` requires both `policy` (object; `{}` is valid) and
-`document` (`{ "kind": "operator", "id": "setup-attempt" }`). Its ONLY optional
-fields are `localBase`, `allowLocalPaths`, `sourceContext`, and `bindings`:
-
-- `policy`: explicit provider/additive selections with their selected sources and
-  settings, using the existing policy grammar. It cannot erase soul requirements.
-- `localBase`: explicit absolute base for relative local policy sources. Work
-  context/cwd is not a substitute.
-- `allowLocalPaths`: explicit boolean authorization for those local policy sources.
-  Top-level local acquisition authorization remains a separate input.
-- `sourceContext`: existing qualified repository anchor for `repo:` policy sources;
-  not a new repository inferred from workTarget.
-- `bindings`: provider-owned map. Kernel preserves it and its document pointers;
-  it does not interpret store names, Git destinations, credentials or private teams.
-
-Selecting an inherited store does not replace required provider runtime settings.
-Use the selected provider's instructions for those settings; kernel must not guess
-host-owned durable paths or copy native authentication.
-
-Repreparation after explicit approval is ordinary continuation in the selected,
-now-managed deployment; do not delete its state to make fresh preflight pass.
-Required hooks still run under their admitted custody with `--no-launch`; a parsed
-binding or team declaration is not proof of an enrolled/ready native provider.
-Native request version1 supplies backend/task/optional stopGraceMs, not a new
-model or current launch selection. Complete OATS home resources remain composed.
-Native auth stays native and permission bypass requires explicit user opt-in.
-
-## Limits and focused evidence
-
-`test/workspace-onboarding-public.test.mjs` uses current public CLI/core, actual
-Git and a bounded local SSH upload-pack fixture, contract-shaped inert provider
-codecs/hooks, and inert native/backend executables. It covers self-membership,
-reciprocal stale observations, independent adoption, non-effect/opaque-output
-boundaries, exact approval, full retained resources, source deletion/current
-config poison, required-provider failure BEFORE native admission/backend effects,
-and original-incarnation native dispatch plus receipt-based stopped observation.
-No production provider/SDK/model/server or host installation is exercised.
-
-Captured input/wake and public captured retirement remain explicit unsupported
-boundaries; a stopped terminal observation is not permission to deliver a captured
-message or retire through legacy fallback. Session-delivered messaging must retain
-its required wake contract; a start-only fixture does not qualify that profile.
-Non-directory placement is not supplied by inspecting a Git work target. These
-limits go to their owners as precise seams, not silent requirement removal.
-
-The user requested removal of `oats-portable-setup` and no new skills in this
-increment. Fresh kernel composition no longer selects that skill; existing
-retained snapshots are unchanged. This document and CLI help describe the public
-adapter, not a replacement skill or a claim of completed workspace deployment.

package/docs/design/2026-09-22-desktop-parity-seams.md

@@ -1,58 +0,0 @@
-# Desktop parity — slice plan and kernel/provider seams (S8)
-
-Status: **proposal accepted for direction** by the lead on 2026-09-22; contracts K1–K8 and P1 are *proposed identifiers*, not shipped CLI grammar. Five policy decisions are routed to the human (below) before their slices start. Author of the plan: the Desktop engineer (`oats-desktop-engineer-1`); this document is the lead's record of it. Scope authority: the human's 2026-09-22 direction — the redesign to the letter, only frames 05 Knowledge and 06 Tasks excluded.
-
-## Slices (each a PR from main; lead reviews and merges)
-
-| Slice | Delivers | Needs |
-|---|---|---|
-| 1a | Compact guides; engine-owned ⌘F / ⌘N; rebind-aware hints | — (PR45) |
-| 1b | Shell 01a/01b: right panel Instance · Git & GitHub · Soul tabs, collapse rail, two editor groups, focus mode; panel state survives repaint | existing tabs/terminal lifecycle |
-| 2a | Worktree branch/ahead/behind/path; changes list; bounded unified diff | **K1** |
-| 2b | PR card: title/#/state/commits/closes; per-job checks bound to head OID; unresolved review threads; Open PR; Send threads | **P1**, **K2** |
-| 2c | Remove / Stop confirmations with worktree/branch/open-PR/child/dirty facts and receipts | **K3** |
-| 3 | 03 Souls + Sources: imported editions + local souls, requirements, provenance, editability | **K4** |
-| 4 | 04 Capabilities: official catalog (`oats catalog --json`, 0.24.6+) + deployment inventory/readiness/used-by; Add capability = exact command | landed catalog + list/inspect + **K5** |
-| 5 | 09 First-run readiness quartet; View policy; Skip/Enrol | **K5** + enrollment decision |
-| 6a | 02 Spawn modal **design parity on existing seams** (human pulled forward 2026-09-22): two-column layout, soul chooser, provider/model dropdowns, launch config restored, opening instruction, readiness from known facts (`unknown` where not), ⌘↵ guards; not-yet-backed fields rendered disabled with "available after <seam>" | existing spawn/launch-config seams |
-| 6b | 02 Spawn fields live: soul chooser, provider/model, launch config (restored), work-area naming/worktree/base+branch, opening instruction, attach knowledge, child spawns, auto-PR, readiness, ⌘↵ | **K6** (+ knowledge-node JSON from the knowledge provider; 05 excluded but attach stays) |
-| 7a | 07 Active overview: counts, relations, activity/waiting-on-you, actions, pan/zoom | **K7** |
-| 7b | 08 Schedules: table/toggles/new/edit, next/last, recent runs, transcript handoff, captured-policy preservation | **K8** |
-| 8 | 10 Components: dropdowns, workspace join/manage, Open in split, Detach to window, Open worktree in editor, actions, toasts, collapsed rail | existing seams + Desktop IPC review for detach/editor |
-
-## Shared JSON rules (accepted)
-
-Envelope `{schemaVersion:1, ok, result|error}` unchanged. Requests address a server-admitted exact target (`{home, server}` / exact source+revision+soul), never a renderer cwd. Results echo target + `contract`, `version`, `observedAt`, opaque `revision`, typed `problems[]`, explicit completeness/truncation. `null` = not known; empty = observed empty only when complete. Per-section availability `available | not-applicable | unavailable | denied | unsupported | error`. No stack traces, auth stderr, tokens or token-bearing URLs in renderer data. Remote paths are provenance, never local authority. Read-only calls never install, trust, enroll, spawn, fetch into the operator's worktree, switch branches or repair config.
-
-
-> **Ownership amendment (2026-09-22, human):** contract-dependent slices are not waits — the team implements the contracts. Kernel seams may be assigned to the Desktop engineer under lead review (the `lib/`/`bin/` lane rule is lifted per assigned seam). Current split (revised 17:10Z): **K1, P1 Decision, K3, K5 → lead** — the engineer's composed instructions forbid kernel edits and a mail cannot recompose them (role change = soul edit + recomposition; spawns blocked by the deployment's pi-profile pin). Engineer: slice 3 now (K4 merged), then 2a after K1. Kernel PRs: full root `npm test` + DTO in `docs/desktop-cli-api.md` in the same PR.
-
-## Seams
-
-- **K1 `oats.instance-git` / `oats.instance-diff`** (kernel): typed per-instance Git state — worktree, head, upstream/merge-base comparison (missing upstream ≠ 0/0), NUL-delimited changes with rename paths and per-file counts; bounded unified diff by opaque file id + observation revision (stale selection refuses, never a different file). Replaces the Desktop-only `instance.git` aggregate whose fallback zeros can masquerade as clean.
-- **P1 `oats.instance-github`** (provider, not kernel): PR summary/checks/reviews through an additive Git/review **capability** with its own credential policy (native custody; Desktop never runs `gh`, reads tokens or opens credential forms). Needs a kernel dispatch contract for additive-capability structured views (today `operation run` accepts only knowledge/messaging/tasks). "No PR" ≠ unavailable ≠ unauthenticated ≠ rate-limited. Checks bind to exact head OID. Review markdown is untrusted text.
-- **K2 review-thread delivery**: explicit, confirmed send of selected threads to the exact home's session input with receipt (`delivered | refused | unknown`); delivered ≠ consumed. Typed producer events for commit / branch-renamed / PR-updated / review-request; **no prose parsing** to infer actions.
-- **K3 lifecycle plan/apply**: read-only plan (runtime activity, children, worktree dirt, branch + open PRs, retention per artefact, per-option allowed/default/reason, warnings, blockers) → apply with plan revision + idempotency key, revalidated under the lifecycle lock; per-target `completed | retained | partial | unknown`. Today there is **no standalone stop**, and retire removes owned worktrees; the design's default Remove retains worktree/branch/PR.
-- **K4 souls/sources enumeration** (✅ MERGED PR52 as additive `inspect --json` `soulsApi:1`, not a new command — see docs/desktop-cli-api.md): qualified list of imported editions + authored local souls with identity/source/revision/requirements/declarations/editability; readiness separate from launchability and adoption; no renderer YAML.
-- **K5 readiness quartet** (✅ MERGED PR63 — `oats readiness`): `installed | trusted | configured | enrolled`, each `pass | fail | unknown | not-applicable` with items (subject, requiredness, reason, producer, evidence, remedy); trust separates artifact approval from `signature {verified|unsigned|unknown|invalid, signer}`; policy view returns **enforced** child-spawn/worktree permissions with origins; native config items report labels/scope state, never secrets; unknown ≠ granted.
-- **K6 spawn preview/apply** (✅ MERGED PR63 — `oats spawn --preview`, `--base`, `--model @native-default`) (add, 2026-09-22 from 6a review: an explicit `model: {kind: "native-default"}` request field — today an omitted model inherits the configured/soul model and there is no force-native override; 6a renders that control disabled until K6): kernel returns suggestions, canonical worktree/home/branch/base OID, resolved knowledge refs, enforced child policy, auto-PR policy, readiness, typed field problems; apply revalidates and captures; no Desktop-derived paths or branches.
-- **K7 activity feed** (✅ MERGED PR64 — `oats instance events`): bounded typed events per instance with provenance; "waiting on you" only from a producer that reports it.
-- **K8 schedule run history** + captured-policy-preserving edit contract; transcript access via the owning CLI/provider.
-
-## Decisions — DECIDED 2026-09-22 (lead, delegated by the human)
-
-Recorded in `agents/oats-expert/soul/knowledge/decisions/desktop-parity-lifecycle-and-policy-decisions.md`: (1) Remove retains worktree/branch/PR by default and re-homes the worktree to the deployment `worktrees/` root before the home is removed; (2) `stop` is a first-class recursive lifecycle route retaining everything for restart; (3) Enrol = workspace member admission with a two-document receipt; "signed by" renders only on a verified Git signature with a named signer; policy rows render enforced policy only; (4) child-spawn permission is enforced by the spawn route (attributed refusal); (5) auto-PR is provider-owned, default off, first pushed commit, draft, human undrafts. Gemini illustrative. The original questions follow for the record.
-
-### Original questions
-
-1. **Remove semantics** (K3, slice 2c): the design's default Remove deletes the instance but *retains* worktree, branch and remote PR; today retirement removes owned worktrees and there is no standalone Stop. Decide: adopt the design's retention default (needs a kernel placement/custody rule for a worktree that outlives its home) or keep current semantics and label the UI accordingly.
-2. **Recursive Stop** (K3): Stop as a first-class lifecycle action (retain home/worktree for restart) including children — new kernel route.
-3. **Enrollment** (K5, slice 5): what "Enrol workspace" *is* (workspace admission? team/machine registration?), its authority and receipt; `oats onboard` is bootstrap, not enrollment. Also what counts as **signature evidence** for "Trusted · signed by …" (catalog URL/hash is not a signer).
-4. **Enforced child-spawn permission** (K6): "Allow child spawns" must be enforced by admitted spawn routes, not advisory — new kernel policy surface.
-5. **Automatic PR** (K6 / P1): trigger (proposed: first non-empty *pushed* commit), draft status, publication consent; provider-owned; default off; never commits/pushes local data on its own.
-
-Also to confirm: prototype "Gemini" runtime is illustrative (not an OATS runtime) unless the human wants kernel work.
-
-## Ownership
-
-Lead: K1, K4, K5 (readiness/policy shape), K6 preview/apply plumbing, K7/K8 projections, dispatch contract for additive-capability views — proposed as Decisions where they change contracts, implemented in small PRs otherwise. P1: **forge connections are ADE/workstation integrations, not capabilities** — **Decision ACCEPTED** (`agents/oats-expert/soul/knowledge/decisions/p1-forge-connection-is-an-ade-integration.md`). Desktop *Connections* surface (GitHub card: status / Connect = `gh auth login --web` in an owned pane / Disconnect), PR card read by the Desktop server via fixed-argv `gh pr view … --json` at the existing guarded boundary, typed states (available / no-pull-request / not-connected / cli-not-installed / unsupported-forge / no-remote / unavailable), remote workspaces refuse; OATS never holds a token. No kernel dispatch contract. Kernel: K1 gains `remote {name,url,host,path}` (lead). Slice **2b** = Connections + PR card (engineer; lead security gate before wiring). Auto-PR: ADE-owned, off, per spawn, after K6. Desktop engineer: all slices, Desktop IPC review items (detach, open-in-editor).