@awebai/oats 0.22.0 → 0.22.1

package/docs/migration-from-oas.md

@@ -1,122 +1,86 @@
 # Migrating from OAS to OATS
 
-Status: **the migration path exists in the kernel** — `oats migrate
---from-oas`, one transactional conversion per scope (plan steps 1–3 below,
-all landed 2026-08-21). What remains is distribution: end users get the
-command with the v0.22.0 release (steps 4–6). This document keeps the facts
-in one place; the work is tracked as epic `aweb-abfy` in this team's aw
-tasks. Audited 2026-08-21 against a live OAS deployment
-(`@oas-framework/oas@0.20.0-aweb.1`).
-
-OATS was published as **OAS** (`@oas-framework/oas`, `@oas-framework/pi`)
-until the 2026-08-13 rename (commit `fa1e646`), which was a deliberate
-clean break: no compatibility shims, and no code in this repo recognizes
-`oas-*` names.
-
-## Do not migrate by hand yet
-
-The dangerous property of the original state was that it failed **quietly**:
-
-- On a scope with `oas-config.yaml`/`oas-lock.json`, `oats status` works
-  (the `agents/` layout is unchanged) — everything looks healthy.
-- But `oats doctor` finds no config, all layers are unresolved, and a spawn
-  produces instances **without the knowledge (`oas.okf`) and messaging
-  (`oas.aweb`) injections**. The compounding-memory and team-comms value
-  disappears with no error.
-- `oats migrate --official --dry-run` on such a scope reported "nothing to
-  migrate" and exited 0 — false success.
-
-Since plan step 1 landed (below), the silence is closed: `oats doctor` names
-an un-migrated OAS scope with the remedy, and every `oats migrate` form —
-plain or guided, dry run or apply — exits nonzero when `oas-config.yaml` /
-`oas-lock.json` are visible from the scope (detection is by name only; the
-kernel never parses OAS files).
-
-## Migrating: `oats migrate --from-oas`
+OATS is the successor to OAS. **OATS 0.22.0 was published on 2026-09-03**:
+the kernel, Pi adapter, and Desktop assets are available. The published
+kernel acquired the official OKF, aweb, authoring, and development packages
+from its catalog during the 2026-09-05 qualification. You no longer need a
+framework checkout to migrate.
+
+Use the migration command rather than renaming files by hand. The OATS
+kernel does not read `oas-*` configuration names or `oas.*` capability IDs.
+An unchanged agent-directory layout can make an old scope look familiar
+while its knowledge and messaging configuration remains unmigrated.
+
+## Upgrade one scope
+
+Finish or preserve active work before changing a daily-use deployment.
+Install OATS alongside the old CLI, then inspect the plan for the exact
+scope you intend to convert:
+
+```bash
+npm install -g @awebai/oats@latest
+pi install npm:@awebai/oats-pi@latest
+oats migrate --from-oas --dry-run --dir /path/to/scope
+```
+
+Read any held or unmapped package rows before applying. A dry run reports
+what can be converted; it is not a guarantee that every historical package
+version has a supported replacement. When the plan is correct:
 
 ```bash
-oats migrate --from-oas --dry-run --dir <scope>   # full per-scope plan, touches nothing
-oats migrate --from-oas --dir <scope>             # convert this scope
-oats migrate --from-oas --recursive --dir <root>  # every visible OAS scope
+oats migrate --from-oas --dir /path/to/scope
+oats doctor --dir /path/to/scope
 ```
 
-One transaction per scope, two phases under one journal:
-
-1. **Rename phase** — `oas-config.yaml` → `oats-config.yaml` (line
-   transform: the `oas:` defaults key becomes `oats:` and capability ids
-   with catalog renames become their successors; comments and every other
-   byte survive), `oas-lock.json` → `oats-lock.json` verbatim, `oas.json` →
-   `oats.json` inside each installed capability dir, and
-   `.oas-scaffold-owners.json` → `.oats-scaffold-owners.json` in `agents/`
-   and `local-agents/` souls with owner ids mapped to their successors.
-2. **Chained guided conversion** — the existing v1→v2 official migration
-   runs on the renamed lock; the catalog's renaming aliases map each
-   `oas.*` entry onto the `oats.*` package that replaces it, re-acquiring
-   the artifacts (stale v1 integrity is resolved by re-acquisition, never
-   recomputed) and cleaning the superseded `oas`-named artifact dirs.
-
-Any failure in either phase restores the scope's original OAS-named bytes.
-A second run finds nothing and exits 0. Executable trust is re-earned after
-conversion (`oats trust` commands are printed), and comments inside your
-config that mention `oas` paths are left untouched — comments are yours.
-
-## The four breaks
-
-1. **File names.** The kernel reads only `oats-config.yaml`
-   (`lib/core.mjs:326`) and `oats-lock.json` (`lib/core.mjs:643`). OAS
-   scopes have `oas-config.yaml`, `oas-lock.json`, `oas.json` inside each
-   installed capability dir, and `.oas-scaffold-owners.json` in souls.
-2. **The config key.** The schema (`docs/oats-config.schema.json`,
-   `additionalProperties: false`) accepts an `oats:` defaults block and
-   rejects the `oas:` block an OAS config carries — renaming the file is
-   not enough.
-3. **Capability ids.** `oas.okf` / `oas.aweb` appear in the config, the
-   lock, and the `.agents/capabilities/installed/<id>/` directory names.
-4. **No catalog aliases.** `package-catalog.json` maps only `oats.*` ids;
-   a hand-renamed lock naming `marketplace:oas.okf` resolves to
-   `available: false` and the guided migration **holds the whole scope**
-   (`lib/core.mjs:3251-3262`, `:1416`).
-
-## Why an OAS user cannot even find OATS
-
-- `@awebai/oats` and `@awebai/oats-pi` are **not yet published**. The
-  v0.22.0 release notes exist and the three manifests are aligned; what
-  remains is the tag and the publish (`.github/workflows/release.yml`, or
-  the runnerless lane in `scripts/release-lane.mjs`).
-- `@oas-framework/oas` is still live on npm (0.21.2 as of 2026-09-03) and
-  **not deprecated**, so the old CLI's `oas update` (which checks that
-  package) never learns OATS exists.
-- The old OAS desktop probes for `@oas-framework/oas`; the new desktop
-  requires `@awebai/oats >=0.22.0 <0.23.0` — old app and new CLI are
-  mutually invisible, so desktop must ship in the same release.
-
-## The plan (epic `aweb-abfy`)
-
-1. **Done.** `oats migrate` / `oats doctor` detect an OAS scope and fail
-   **loud** with the exact remedy (never exit 0 on "nothing to migrate" when
-   `oas-*` siblings exist). `detectOasScopes` in `lib/core.mjs`,
-   `discoverOasScopes` in `lib/packages.mjs`, wired in `bin/oats.mjs`;
-   tests in `test/oas-scope-detection.test.mjs`.
-2. **Done.** Catalog aliases `oas.*` → `oats.*` so legacy locks map instead
-   of holding — as *renaming* aliases (`{ "package": "oats.okf",
-   "capability": "oats.okf" }`), because the replacement packages export the
-   successor ids, never the legacy ones. All seven 0.20 ids are mapped in
-   `package-catalog.json`.
-3. **Done.** `oats migrate --from-oas`: one transactional command covering
-   all four breaks (section above), fixture built from the real deployment
-   shape, idempotent, byte-identical rollback on failure, with a migrated
-   scope reaching green `oats doctor` and spawns composing the knowledge and
-   messaging injections again (`test/from-oas-migration.test.mjs`).
-4. v0.22.0 release: notes and version alignment are **done**; remaining are
-   the tag, npm publish of `@awebai/oats` + `@awebai/oats-pi`, and the
-   desktop GitHub Release.
-5. `npm deprecate` the `@oas-framework/*` packages with a pointer here.
-6. Close the `oats-okf` / `oats-aweb` publication gates so migrated scopes
-   can restore their capabilities under the new ids.
-
-Until 4–6 are done, OAS users (this includes real daily users) should stay
-on `@oas-framework/oas` — it keeps working and loses nothing by
-waiting. The conversion command exists, but until the v0.22.0 release it is
-only reachable from a repo checkout, and until the satellite publication
-gates close the catalog's package refs are not a supported acquisition
-source for migrated scopes.
+Run the exact `oats trust <capability> --dir <scope>` commands printed by
+migration for the executable capabilities you approve. Trust does not
+transfer automatically. Verify the team ID and messaging membership with
+`oats aweb setup --dir /path/to/scope`, then exercise a real task, harvest,
+and retirement as described in [Run your first team](first-team.md).
+
+For a multi-repository deployment, start with one scope. The explicit
+`--recursive --dir /path/to/workspace` form converts every discovered OAS
+scope, with a separate transaction for each; it is not one transaction for
+the whole workspace.
+
+If you use Desktop, install [OATS Desktop](desktop.md) too. The old OAS
+Desktop discovers the old package name and cannot operate the new CLI.
+OATS Desktop 0.22.0 accepts kernel versions `>=0.22.0 <0.23.0`.
+
+## What the command converts
+
+One transaction covers two phases within a scope:
+
+1. Rename `oas-config.yaml` and `oas-lock.json` to their `oats-` names;
+   convert the `oas:` defaults key and catalog-mapped capability IDs;
+   rename installed `oas.json` manifests and soul scaffold-owner files.
+2. Convert the old lock to official package lockfile version 2, acquiring
+   the replacement artifacts and removing superseded installed directories.
+
+The catalog includes aliases for the seven OAS 0.20 capability IDs, mapping
+`oas.*` names to the corresponding `oats.*` packages and capabilities.
+Aliases guide migration; they are not runtime compatibility shims.
+Comments and unrelated configuration text are preserved, including old
+names in comments. Those comments can be updated separately.
+
+A failure in either phase restores that scope's original OAS bytes. A
+second successful run finds nothing to convert. `oats doctor` and migration
+commands identify visible OAS-named scopes and give a remedy rather than
+silently declaring an unmigrated deployment ready.
+
+## Compatibility and remaining transition work
+
+The migration fixtures were built from an OAS 0.20.x deployment. OAS
+0.21.x uses the same file names and configuration keys, but may lock package
+versions outside the OATS catalog's mapped line. Inspect the dry run before
+converting those scopes; do not replace an unmapped version by guessing.
+
+The old `@oas-framework/*` packages have not been deprecated as part of
+this rollout. Their update checks therefore do not announce the OATS
+rename; deprecation belongs to their maintainer. An existing OAS deployment
+can keep running until its own migration plan is ready. This is no longer a
+requirement to wait for OATS publication.
+
+See the [0.22.0 release notes](release-notes/v0.22.0.md) for the rename,
+package versions, and compatibility changes, and the
+[first-team qualification](first-team-demo.md) for current operating evidence.

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

@@ -0,0 +1,106 @@
+# OATS v0.22.1
+
+A bounded reliability release, made from the first day of operating OATS on
+its own repository from the published 0.22.0 artifacts. Every item below was
+either reproduced during that run or found by the independent review that
+preceded it, plus the golden fixtures that guard the kernel's outputs and a
+release-workflow correction (a release with nothing to bump finishes rather
+than fails). The Desktop compatibility band (`>=0.22.0 <0.23.0`) already
+covers this kernel; no Desktop rebuild is needed.
+
+## Fixes
+
+- **`oats create` in a fresh scope no longer crashes.** After `oats init`,
+  the first `oats create` died with a raw stack trace because it demanded the
+  `agents/` directory that only `create` itself populates. It now bootstraps
+  the roster root at the enclosing repository, reports that once (and as
+  `agentsRoot` in `--json`), and the 0.22.0 workaround `mkdir agents` is no
+  longer needed.
+- **Spawn preflights executables and compensates every post-hook failure.**
+  A missing runtime binary or tmux was detected only after the home, worktree,
+  branch, and required capability hooks (an aweb identity) had been created,
+  and those throws bypassed compensation, leaving a branch, a worktree, and
+  remote state with no `instance.json` and no quarantine. The runtime binary,
+  tmux (when launching), and the task input are now checked before any
+  mutation, and one compensation path owns every failure after the spawn
+  hooks: retire hooks run once, Git topology is removed and verified, a
+  window that may have been created is stopped and verified before
+  credentials are touched, and unresolvable cleanup retains the home with
+  its receipt for a retryable `oats retire`. Six fault-injection tests cover
+  the paths.
+- **The turn record's stream lock is ownership-safe and bounded.** A late
+  contender could judge a live holder's lock stale by age and enter the same
+  critical section, and the old holder then unlinked whatever lock was in
+  place. The lock now carries an owner token; staleness is proven from the
+  holder's liveness, with age only as the fallback for a foreign-host or
+  tokenless lock; release removes only a lock the releaser owns; and every
+  failed acquire iteration passes one deadline check, so an unreadable lock
+  or a lock that cannot be removed fails with the underlying code and path
+  instead of spinning forever. Known limit, documented: a pid reused after a
+  reboot makes an abandoned lock read as held until an operator removes it.
+- **README claims match the implementation.** Native captured turns are
+  content-addressed, not signed; projected aweb mail and chat keep their
+  original signatures; capture covers Claude Code, Pi, and Codex transcripts
+  plus aw client logs on machines where `oats setup` ran, subject to the
+  ignore list. The contracts document and the turn-record specification say
+  the same.
+- **Bundled capabilities match their published tags.** The copies of the
+  official packages bundled under `capabilities/` claimed the published
+  version numbers but differed from the published payloads; the bundled
+  `oats.okf` still imported kernel internals and shipped an older harvester
+  layout. All six are now byte-identical to the tagged payloads (`oats.okf`
+  1.4.1, `oats.aweb` 1.8.0, `oats.jira` 1.0.0, `oats.linear` 1.0.0,
+  `oats.authoring` 1.0.0, `oats.review` 1.2.0 from `oats.dev` 1.0.0). Two
+  new tests guard it: no file under `capabilities/` may name kernel internals
+  or shell out to `oats root`, and every bundled manifest must carry the
+  version the catalog pins. The clean-room smoke asserts the same pin before
+  wrapping the bundled package, so it now proves the released package and
+  kernel combination. The bundled `oats.linear` README and test moved with
+  their package.
+
+## Documentation
+
+- **Run your first OATS team** (`docs/first-team.md`) is the tested path from
+  install to a real task, harvest, retirement, and a successor, with the
+  caveats the run met: the harvester runs in Pi even for Claude Code workers,
+  a Claude Code spawn needs two interactive confirmations today, and a
+  messaging layer entry that excludes a soul must state `global: true`.
+- **First-team example** (`docs/first-team-demo.md`) records what actually
+  happened on 2026-09-05: two workers, two promotions, one successor that
+  read its predecessor's promoted lesson.
+- **Migration from OAS** is rewritten from shipped state: the packages are
+  published, the seven catalog aliases exist, and the OAS npm deprecation
+  remains with its maintainer.
+- `docs/layers.md` is now the OATS contracts and `docs/integrations.md` the
+  binding guide; `docs/2026-09-03-architecture-proposal.md` records the
+  component model and the migration plan agreed with the framework's author.
+
+## Known operating limits and issues, not fixed here
+
+- The qualified `oats.okf` 1.4.1 configuration runs its harvester in Pi, so
+  a Pi-runnable model is required even for Claude Code workers.
+- A Claude Code worker's first launch can stop on Claude's folder-trust
+  prompt and on the aweb channel plugin's development-channels
+  confirmation; attach to the tmux session and answer them. A created
+  window is not evidence that the agent has started.
+- Retiring an instance reports its aweb identity deleted while the server
+  keeps the alias (aweb-aaum.6). Local cleanup is complete; the name cannot
+  be reused until an administrator removes the alias. Use a fresh
+  `--purpose` for successors.
+- The OKF harvester's default model assumes the `github-copilot` provider;
+  set `harvest-model` under the knowledge layer settings to a model your Pi
+  can run. A package change is proposed.
+- `oats spawn` resolves the roster root from the working directory, so from
+  a workspace root pass `--dir <repo>` even though `oats status --team`
+  lists the souls.
+- `oats status` lists the retirement-baselines directory as a phantom
+  instance, retire leaves that baseline file behind, and `oats retire --json`
+  prints a bare object rather than the schema-v1 envelope. Tracked; each
+  changes a golden fixture deliberately.
+
+## Install
+
+```bash
+npm install -g @awebai/oats@0.22.1
+pi install npm:@awebai/oats-pi@0.22.1
+```