@awebai/oats 0.29.4 → 0.30.1

package/docs/packages.md

@@ -1,10 +1,11 @@
-# Packages — the versioned tier
+# Packages: the versioned tier
 
 A **package** is a place to fetch capabilities from *with a version attached*.
 It is one of the two kinds of capability source in the
 [workspace model](workspaces.md); the other — a member repo — is never
 versioned. Nothing is installed: a package is resolved to an exact commit by
-`oats sync`, recorded in `oats-lock.json`, and **copied whole into each instance at spawn** (`<home>/.oats/modules/<cap>/`).
+`oats sync`, recorded in `oats-lock.json`, and **copied whole into each
+instance at spawn** (`<home>/.oats/modules/<cap>/`).
 
 Ground truth: [`oats-package.schema.json`](oats-package.schema.json) (the
 package manifest), the [lock v3 format](#lock-v3) below (`validateLock` in
@@ -28,7 +29,7 @@ A Git repository **contains** a package at `oats-package/`:
 
 `oats-package.json` must declare `package` and `capabilities` (a list of
 directories relative to the package root, each holding an `oats.json`). It may
-also declare `souls` (0.28.0): soul directories the package ships, see
+also declare `souls`: soul directories the package ships, see
 [Package souls](#package-souls). A
 directory entry need not equal the capability's name
 (`capabilities/oats-okf` → capability `oats.okf`). A package declaring one
@@ -36,22 +37,21 @@ capability name twice, a listed directory without a manifest, or a manifest
 without `capability` is `E_PACKAGE_MANIFEST`. Catalog entries may name another
 `path` than `oats-package`; a `git:` ref always reads `oats-package/`.
 
-## Declaring packages — two forms, in one place
+## Declaring packages
 
 The workspace file's `packages:` map is the **only** list of versions in the
 whole organisation:
 
 ```yaml
 packages:
-  oats.framework: v1.1.3                              # bare version → the official catalog
-  oats.okf: v2.1.3
+  oats.okf: v4.0.5                                    # bare version → the official catalog
   acme.tools: git:github.com/acme/tools@v0.4.0        # direct ref: git:<repo>@<tag or full OID>
 ```
 
-- **Bare version** (`v2.1.3`, `2.1.3`, `1.0.0-rc.1`): the id is looked up in
+- **Bare version** (`v4.0.5`, `4.0.5`, `1.0.0-rc.1`): the id is looked up in
   the official catalog — `package-catalog.json` in the `oats` repo, or the file
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
-  convention (`v2.1.3` or `oats-framework/v1.1.3`) and the payload path. An id
+  convention (`v4.0.5` or `oats-framework/v1.4.0`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
   a package outside the catalog"). The catalog is the reviewed official list
   ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,12 +74,11 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.3.2
-  oats.okf: v4.0.1
-  oats.aweb: v1.16.0
+  oats.framework: v1.4.0
+  oats.okf: v4.0.5
+  oats.aweb: v1.17.1
 teams:
-  global: { description: Org-wide }
-  engineering: { description: Platform }
+  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
 defaults:
   capabilities: { oats.core: { from: package } }
   knowledge: { oats.okf: { from: package } }
@@ -105,11 +104,11 @@ decision recorded in the lock.
 ```
 $ oats sync
 workspace  acme  (github.com/acme/agents @ 3f2a9c1e)
-members    agents ✓↔ (@ 3f2a9c1e)   platform ✓↔ (@ 77c0a1b2)   tools ✓↔ (@ 47f4b816)   billing ✗ (no-backlink)
-packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.framework 1.1.3 ✓ (@ 9c3e27aa)   oats.okf 2.1.3 ✓ (@ b2e16f2e)
+members    agents ✓↔ (@ 3f2a9c1e)   platform ✓↔ (@ 77c0a1b2)   billing ✗ (no-backlink)
+packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.0.5 ✓ (@ 26d8216f)
 changed    acme.tools  — → 0.4.0 (@ 47f4b816)
-souls      7 discovered (6 members, 1 external, 0 disabled here) · 0 private capabilities
-teams      engineering 4 souls, 3 capabilities · global 2 souls, 2 capabilities · unassigned 1 soul
+souls      9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
+teams      platform (shared) · this deployment's: oats teams
 
 lock       oats-lock.json
 ```
@@ -127,16 +126,15 @@ lock       oats-lock.json
 4. writes `oats-lock.json` and reports the diff. Entries dropped from
    `packages:` are dropped from the lock.
 
-There is **no approval step** (human decision, 2026-09-24): declaring a package
-in the workspace's `packages:` is the trust decision, so `sync` asks nothing,
-exits `0` on success, and `--approve` is `E_BAD_ARGS`. `--json` emits the
+Declaring a package in the workspace's `packages:` is the trust decision
+([Trust](#trust)): `sync` asks nothing and exits `0` on success. `--json` emits the
 `syncApi: 1` envelope documented in
 [desktop-cli-api.md](desktop-cli-api.md#workspace-model-workspaceapi-2).
 
 ## `oats package add | remove`
 
 ```bash
-oats package add oats.aweb v1.11.2                         # a catalog version
+oats package add oats.aweb v1.17.1                         # a catalog version
 oats package add acme.tools git:github.com/acme/tools@v0.4.0
 oats package remove acme.tools
 ```
@@ -144,8 +142,8 @@ oats package remove acme.tools
 Both edit `packages:` in `oats-workspace.yaml` **when the file is tracked by
 the Git checkout the command runs in** (the workspace host repo); the edit is
 validated against the full workspace schema before it is written, and the
-receipt tells you to commit and `oats sync`. Anywhere else — a deployment folder,
-a member clone — the command prints the line to add (`--json`: `edited: false`,
+receipt tells you to commit and `oats sync`. Anywhere else (a deployment folder,
+a member clone) the command prints the line to add (`--json`: `edited: false`,
 `line`) because the workspace file is shared through Git, not through this
 machine. Nothing network-bound happens in `package add`; `sync` resolves.
 
@@ -162,10 +160,10 @@ same workspace commit hold identical locks.
       "source": "catalog:oats.okf",
       "url": "https://github.com/awebai/oats-okf.git",
       "path": "oats-package",
-      "version": "2.1.3",
-      "commit": "b2e16f2ea1555be519db76fda30cd0bea06f8609",
-      "integrity": "sha256-1c34dbe9c1cc3826dbe6ecbafbd9a1e189ed36a74bfb2ba8fb6f46a382e95c2d",
-      "capabilities": ["oats.okf"]
+      "version": "4.0.5",
+      "commit": "26d8216f8ce986cad1ffa7a8291b4a4978510ee2",
+      "integrity": "sha256-…",
+      "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
     },
     "acme.tools": {
       "source": "git:github.com/acme/tools@v0.4.0",
@@ -183,31 +181,26 @@ same workspace commit hold identical locks.
 
 | field | meaning |
 |---|---|
-| `source` | `catalog:<id>` or `git:<repo key>@<ref>` — how the workspace asked for it |
+| `source` | `catalog:<id>` or `git:<repo key>@<ref>`: how the workspace asked for it |
 | `url` | the repo url the package was read from; travels in the lock so spawn needs no catalog |
 | `path` | the package root inside the repo |
 | `version` | the version string without a leading `v` (a `git:…@<OID>` pin records the OID) |
 | `commit` | full 40-hex OID the version resolved to |
 | `integrity` | `sha256-<hex>` content digest of the package tree at `path` |
-| `capabilities` | the capability names the package provides (sorted) — what `from: package` looks up |
-| `souls` | the package souls (0.28.0), sorted by name: `name`, `path` (inside the package) and `digest` (`sha256-<hex>` of the soul directory); absent when the package ships none |
+| `capabilities` | the capability names the package provides (sorted): what `from: package` looks up |
+| `souls` | the package souls, sorted by name: `name`, `path` (inside the package) and `digest` (`sha256-<hex>` of the soul directory); absent when the package ships none |
 
 A capability provided by **two** locked packages is ambiguous and fails
 closed (`E_PACKAGE_MISSING { ambiguous: [ids] }`): keep one of them in
-`packages:`. A lock that is not v3 (a 0.24 lock, an unreadable file) is
-`E_LOCK_SCHEMA`; it is never auto-repaired — delete it and `oats sync`. A v3
-lock written before 0.26.0 may carry an `approved` record per entry: it is read
-with the field ignored, and the next write drops it. The reverse does not hold:
-a kernel before 0.26.0 refuses a lock 0.26.0 wrote (`E_LOCK_SCHEMA "approved:
-must be null or { executables, at }"`) — keep every kernel that reads one
-deployment on 0.26.0 or later. Agents never hand-edit the lock.
+`packages:`. A lock that is not v3, or cannot be read, is `E_LOCK_SCHEMA`; it
+is never repaired automatically: delete it and `oats sync`. Agents never
+hand-edit the lock.
 
 ## Trust
 
 Member capabilities are trusted by membership; **a package is trusted by its
-declaration in the workspace's `packages:`** (human decision, 2026-09-24) —
-people install a package only when they trust it, so there is no second,
-per-version approval step. The lock is reproducibility, not approval: it pins
+declaration in the workspace's `packages:`**. People declare a package only
+when they trust it, so there is no second, per-version approval step. The lock is reproducibility, not approval: it pins
 the exact commit and the content integrity, a moved tag or drifted content is
 `E_PACKAGE_INTEGRITY`, and at spawn the lock's capability list must match what
 the package declares at the locked commit (`E_PACKAGE_INTEGRITY { why:
@@ -226,7 +219,7 @@ running instance's package module as `moved` once the lock points elsewhere.
 
 ## Package souls
 
-A package may ship **souls** as well as capabilities (0.28.0). One pin in
+A package may ship **souls** as well as capabilities. One pin in
 `packages:` then versions both: nothing drifts, unlike an `external:` soul's
 commit pin.
 
@@ -244,7 +237,7 @@ oats-package/
   the lock entry. A soul without `soul.yaml` or `AGENTS.md`, or whose
   directory is not a soul name, is `E_PACKAGE_MANIFEST`. On a later sync at
   the same version the souls must still match (`E_PACKAGE_INTEGRITY { why:
-  "souls" }`); a lock written before 0.28.0 has its `souls` filled in.
+  "souls" }`).
 - **Listed.** `oats souls` lists a package soul with `kind: "package"`,
   `package`, `version`, `qualifiedName` and `origin: "package <id>
   v<version>"`; `oats sync` / `oats workspace status` list each package's
@@ -253,9 +246,9 @@ oats-package/
   A bare name works when it is unique across member, external and package
   souls; otherwise `E_SOUL_AMBIGUOUS` names each qualified form
   (`details.qualified`). A member soul's qualified form is `<member name>/<soul>`.
-- **Resolved** like any soul: the workspace and team defaults apply, `off` and
-  `<slot>: none` work, every `team:` label must be declared (`E_TEAM_UNKNOWN`
-  in discovery), and `from: here` means **this package** at the locked commit
+- **Resolved** like any soul: the workspace defaults apply, `off` and
+  `<slot>: none` work, its teams here are keyed `<package>/<soul>` in
+  `oats-local.yaml` `souls.teams`, and `from: here` means **this package** at the locked commit
   (a capability it does not provide is `E_CAPABILITY_MISSING`).
 - **Spawned** at the locked commit: the soul is fetched into the per-commit
   soul cache and its digest must equal the lock's (`E_PACKAGE_INTEGRITY
@@ -285,7 +278,7 @@ oats-package/
 
 ## Trigger templates
 
-A package may also ship **trigger templates** (0.28.0): `triggers: [{ id,
+A package may also ship **trigger templates**: `triggers: [{ id,
 file }]` in `oats-package.json`, each file `{ parameters, definition }`.
 `oats trigger add --from <package>:<id> --set <name>=<value>` instantiates one
 at the locked commit; see [schedules.md#triggers](schedules.md#triggers).
@@ -296,7 +289,7 @@ A soul may state floors on package versions — constraints, not sources:
 
 ```yaml
 compatibility:
-  oats.okf: ">=2.1"
+  oats.okf: ">=4.0"
 ```
 
 Checked at resolution against the locked version (`E_COMPATIBILITY`,
@@ -338,23 +331,12 @@ A soul that names one of the package's capabilities with
 {
   "policy": "docs/official-catalog.md",
   "packages": {
-    "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v2.1.3", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.1.3", "path": "oats-package" }
+    "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.0.5", "path": "oats-package" },
+    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.0", "path": "oats-package" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.3.2`
-resolves to tag `oats-framework/v1.3.2`. Resolving through the catalog never
-advances a lock by itself — `oats sync` does, and
-says so.
-
-## Removed verbs
-
-`oats install`, `restore`, `init`, `use`, `trust`, `list`, `catalog`, `remove`,
-`migrate`, `config` are gone; each answers `E_UNKNOWN_COMMAND` naming its
-replacement (`details.removed` / `details.replacement` in `--json`). There is
-no installed-capability directory, no config template adoption, no host
-requirement installer. A manifest's `requires` still describes what must exist
-on the host (harness packages are verified at spawn; host commands are the
-operator's to install).
+`ref` carries the tag convention: a workspace's `oats.framework: v1.4.0`
+resolves to tag `oats-framework/v1.4.0`. Resolving through the catalog never
+advances a lock by itself: `oats sync` does, and says so.

package/docs/plans/0.30-close-out.md

@@ -0,0 +1,83 @@
+# OATS 0.30 close-out: the shared plan
+
+The single source of truth for the rest of 0.30, owned by BOTH leads (oats-expert-knowledge-reworks
+and oats-expert-antares, succeeded by oats-expert-steward; Juan asked for joint work on 2026-09-28). Whoever changes the state updates
+this file.
+
+## Rules
+- One driver per item; the other lead reviews every PR in it.
+- Every developer brief is cc'd to the other lead. No objection within the hour and it stands.
+- Idle agent sessions don't wake on mail: nudge them by tmux when they stall.
+
+## Items
+
+| # | Item | Driver | Developer | State |
+|---|---|---|---|---|
+| 1 | oats.aweb 1.17.1: a newcomer's first `--join` (service source, resume, `--name`); `--soul` on operator commands; the `aweb-team-leave-failed` event | Antares | Antares' aweb developer | TAGGED v1.17.1 → 9254e385 (tag object 899408a6); reviewed by the lead; proven in the final rehearsal |
+| 2 | oats.okf 4.0.4: answer the kernel's documented readiness request, from the real host settings; recaptured with the real package | Antares | Antares' okf developer | TAGGED v4.0.4 → a4ccca02 (tag object e1c3827f); rehearsal case 10 PASS 5/5 with the kernel #298 fix |
+| 3 | Kernel: `session start`/`restart` return, print and record the launch hooks' warnings | lead | cli-dev-okf-ops | MERGED #295 → 2049adda |
+| 4 | Desktop #292: `launch-changed` decoding scoped to its code; `at: null`; real captures incl. `default-team-changed` | lead | ux-designer-desktop-redesign | MERGED #292 → 39a03379 |
+| 5 | The 0.30.0 release PR (brief below) | lead | cli-dev-v2-native | briefed |
+| 6 | Full rehearsal re-run on the final heads (all cases, incl. 5 and 10); close-out; retire case 9; the 0.30 runbook for Juan and Pepe | Antares | — | DONE on the final heads (main kernel stamped 0.30.0 + aweb v1.17.1 + okf v4.0.4): all cases PASS (1–8, 10, onboarding (a)–(e) + resume, the BYOT leave/retire owner commands actually run → revoked, 22 clean retires). Known: 8 (E_SPAWN_FAILED), the BYOT membership limit. Runbook for Juan and Pepe: next |
+| 7a | automations.trust (#300, ACKed a0562b9f) + the Desktop grouping of `untrusted` with owner-mismatch (not here, with the remedy; a real-capture test): the Desktop PR merges BEFORE #300. Both land before the tag, or both go to 0.30.1 together | lead | cli-dev-okf-ops + ux-designer-desktop-redesign | routed |
+| 7 | Tag v0.30.0 after green main CI on the exact release SHA | Antares | — | DONE: v0.30.0 + oats-framework/v1.4.0 on dec58082 (main CI green on it); published @awebai/oats 0.30.0 (shasum 2e370157) + @awebai/oats-pi 0.30.0, latest; a clean-room onboard with the published package locks framework 1.4.0, aweb 1.17.1, okf 4.0.4, engineering 1.1.0 |
+
+**Sequence:** 1–4 in parallel → 6 on the final heads → 5 with the final pins → 7.
+
+## The release PR (item 5)
+1. Version 0.30.0 in EVERY package that carries it (root, pi, desktop).
+2. The `oats.core` / `oats.setup` compat floors AND the check-knowledge-theory floor at `>=0.30.0`,
+   in the same commit as the bump.
+3. The framework v1.4.0 pins (the tag is cut at release).
+4. The oats.aweb 1.17.1 and oats.okf 4.0.4 mirrors (trees == the tags) and pins. Until those tags
+   exist, use placeholders; the PR stays a draft.
+5. Re-pin the REAL bundled binding-check test to 1.17.1's actual answer (no hand-written payload).
+6. The Desktop's supported band: `<0.31`.
+7. Release notes:
+   - the team model v2 migration and the flag day, with every setup step as
+     `oats aweb setup --soul <soul>`;
+   - the teams you control (BYOT) line: a lost team is left automatically on hosted teams; on a team
+     you control, the leave is reported with an `aweb-team-leave-failed` event, and the owner
+     removes the member;
+   - launch preferences (soul `launch:`, `souls.launch`, the frozen record, `--reselect-launch`);
+   - automations.trust, if it merged in time: a behaviour change for hosts that ran automations;
+   - fixed: second-team joins usable, okf readiness answered, launch warnings shown;
+   - the 0.29.4 catalog note (`OATS_PACKAGE_CATALOG`).
+   - **Known in 0.30.0** (so nobody is surprised): with no teams configured, spawn refuses through
+     the provider (`E_SPAWN_FAILED`), not `E_TEAM_UNCONFIGURED`; capability operator commands run
+     from a deployment need `--soul <soul>`; retire of homes whose session is gone (if it misses the
+     tag). Each is fixed in 0.30.1.
+8. A check of the PACKED tarball: its `package-catalog.json` carries oats.engineering 1.1.0,
+   oats.aweb 1.17.1 and oats.okf 4.0.4.
+
+## Released (2026-09-29)
+**OATS 0.30.0** on npm (`@awebai/oats` and `@awebai/oats-pi`, latest), from `dec58082` (#297).
+Tags `v0.30.0` and `oats-framework/v1.4.0` are both on that SHA. Pins: oats.aweb 1.17.1,
+oats.okf 4.0.4, oats.engineering 1.1.0, framework 1.4.0. A clean-room `oats onboard` against the
+published package locks all of them without a catalog override.
+
+Found by the rehearsals, and fixed before the tag:
+- joined teams unusable against real aw;
+- okf readiness always `unknown`;
+- `oats aweb setup` from a deployment;
+- launch-hook warnings dropped;
+- `readiness --soul` with no soul copy;
+- a newcomer's first `--join`;
+- a stale `settings.team` orphaning identities on retire;
+- a BYOT retire with no owner command.
+
+## After the tag
+- **Flag day:** the oats.engineering release with the souls' `launch:` (experts on Claude Code +
+  Opus 5.5; `code-reviewer` on Codex + Astra; compat `>=0.30.0`), and committing the shared team id.
+- **0.30.1:**
+  - the kernel items that miss the tag: retire of homes whose session is gone, automations.trust;
+  - deployment-scope capability commands without `--soul`;
+  - the case-8 pre-check (`E_TEAM_UNCONFIGURED`).
+  - the kernel refuses an unrecognised spawn argument (a bare `join=oats` without
+    `--provider oats.aweb` was silently ignored, so the spawn joined nothing).
+  - a launch (spawn, `session start`, `session restart`) puts the spawning kernel's bin directory
+    FIRST on the instance's PATH and records it in the launch recipe, so plain `oats` inside an
+    instance is the kernel that made it (two kernels side by side: a 0.30 home ran the global 0.24.6
+    and `oats aweb` was `E_UNKNOWN_COMMAND`; the injected instructions tell agents to run plain `oats`).
+- **Parked:** item L (`git rm agents/`, cli-dev-v2-native). It needs the GitHub `workflow` token
+  scope from the human on the lead's machine.

package/docs/release-lane.md

@@ -9,6 +9,9 @@ The policy it satisfies: no release capability may permanently depend on
 GitHub or GitHub Actions. Registry publish works on its own; tags and hosted
 release assets can follow later.
 
+The last two sections cover the post-publish Desktop check and mirroring a
+released `oats.okf`.
+
 ## When to use it
 
 - **Runner outage.** GitHub Actions is down, queued, or a runner image has
@@ -130,3 +133,82 @@ contract; `test/release-lane.test.mjs` covers the lane's gates and phase
 logic against fixtures, with `npm` stubbed. The two can run in either order:
 a lane release followed by a workflow run, or a broken workflow run finished
 by the lane, and neither republishes what the other already did.
+
+## Desktop release verification
+
+Installer CI gates what headless runners can prove reliably for every
+published platform/architecture: electron-builder completes, the expected
+DMG/ZIP/AppImage/DEB artifacts exist, both packaged macOS `.app` bundles
+pass strict deep codesign verification of their complete ad-hoc signatures
+(`codesign --verify --deep --strict`), node-pty's packaged `spawn-helper` is
+executable, and node-pty loads and spawns under the packaged Electron ABI.
+The macOS x64 leg cross-builds on macos-14 and installs Rosetta 2 so that its
+x64 Electron + node-pty ABI probe really executes; a wrong-architecture
+native module fails that leg.
+
+CI does **not** gate the packaged GUI launch: ad-hoc-signed, non-notarized
+Electron apps do not
+have a reliable interactive windowserver in headless CI. Post-publish launch
+acceptance is therefore owned by the operator/maintainer, using the actual
+released installers (not a source checkout):
+
+1. Verify the asset checksum/attestation, install it outside the source tree,
+   and on macOS use right-click → **Open** for the Gatekeeper step (ad-hoc
+   signatures carry no identified-developer identity).
+2. Launch OATS Desktop and open a real deployment; verify roster, brain and
+   Markdown reads.
+3. Attach an existing tmux terminal, confirm input/output, and close the tab
+   (the durable tmux window must survive).
+4. Verify the released global CLI is detected and Spawn is enabled; hide or
+   mismatch the CLI and confirm reads/terminal still work while Spawn disables
+   with recovery guidance.
+5. Repeat per published architecture where hardware is available. In
+   particular, launch-check macOS x64 on an Intel Mac if one is available;
+   CI's Rosetta ABI probe is the native-module proof, while this is the actual
+   shipped-installer/user-launch proof.
+
+Record the installed version, platform/architecture and outcome in the
+release verification notes. This post-publish check is acceptance — it does
+not weaken the pre-publish build/inventory/ABI gates.
+
+## Mirroring a released `oats.okf`
+
+The standalone `awebai/oats-okf` repository is authoritative. This repository
+carries a generated mirror of its capabilities under `mirrors/oats-okf*/`
+and the inventory `scripts/okf-source-inventory.json`; neither is edited by
+hand. The inventory records each capability at its path inside the package
+(`capabilities/oats-okf`, what the tag attests) and, in `mirrorPaths`, where
+this repository keeps it. The mirror is not under `capabilities/`: this
+repository is a workspace member, and member discovery would list it as a
+latest-state member capability beside the package. After an okf release is
+tagged:
+
+1. Check out the release in a clean clone of `awebai/oats-okf` at the tagged
+   commit, with the tag present locally and `origin` pointing at the official
+   repository.
+2. From this repository:
+
+   ```bash
+   node scripts/check-okf-mirror.mjs --finalize --source <clone> \
+     --final-tag v<version> --final-commit <full merged commit id>
+   node scripts/check-okf-mirror.mjs --verify
+   node scripts/check-okf-mirror.mjs --verify-source --source <clone>
+   ```
+
+3. Pin the same version in `package-catalog.json` and `oats-workspace.yaml`,
+   update the version literals the tests and smoke script carry, and review
+   the diff as one PR.
+
+`--finalize` stamps `release.status: published` only when every check passes:
+the tag is exactly `v<package version>` and resolves to the given commit; the
+source tree is clean, with no masked index entries; the exported files, modes
+and symlink targets equal the raw objects at that commit; `origin` is the
+official repository, and a fresh `ls-remote` advertises the same tag object
+and commit. A failed check leaves the mirror and inventory untouched.
+
+`--verify` needs no network: it checks the checked-in mirror against the
+inventory (file set, bytes, modes, symlinks, wrapper hashes). `--verify-source`
+re-checks a published inventory against the source and its origin; it attests
+what the remote advertised when queried, so released tags must never move.
+`--generate --source <clone>` captures a working tree for development and
+always records `release.status: pending`.

package/docs/release-notes/oats-framework-v1.1.3.md

@@ -1,11 +1,13 @@
 # oats.framework 1.1.3 · aweb 1.11.2 — helper composition for every edition
 
-Packaging fix found by the independent second operator on the 0.24.4 wave: behind the operator's `responsibleHuman` requirement, preparation refused with `needs-configuration: new helper injection requires an explicit capability policy`. `oats.okf` had adopted the helper-injection contract (`omit`); its siblings **`oats.core`** and **`oats.aweb`** shipped an `inject` without a `helperInjection` policy, so no edition's OKF harvest helper could compose and **no edition could publish a resolution**. Both remaining blockers were packaging, not operator input.
+Packaging fix: `oats.core` and `oats.aweb` shipped an `inject` without a
+`helperInjection` policy, so preparation refused with `needs-configuration: new
+helper injection requires an explicit capability policy`, no edition's OKF
+harvest helper could compose, and no edition could publish a resolution.
 
-- **`oats.core` 1.0.1** (in oats.framework 1.1.3): `helperInjection: {version: 1, mode: inherit}` — a helper is still an OATS instance and keeps the "you run on OATS" briefing.
-- **aweb 1.11.2**: `helperInjection: {version: 1, mode: omit}` — a harvest helper has no messaging identity. Manifest-only; code identical to 1.11.0.
-- **Release check**: `test/release-packaging.test.mjs` now asserts every framework-shipped capability with an `inject` declares a `helperInjection` policy; the theory-package check pins core's `inherit`. The framework's own packages must pass the contracts the kernel imposes.
-- Catalog: `oats.aweb` → `v1.11.2`, `oats.framework` → `oats-framework/v1.1.3`; six editions and workspace imports repinned.
-- Still open (kernel, 0.25 unless a 0.24.5 is cut): this early refusal is a bare top-level error with no `details`/attribution — it must route through the same problem shape as every other preparation problem. Also noted: `responsibleHuman` is a captured accountability claim the code validates only by shape.
-
-Decision: `agents/oats-expert/soul/knowledge/decisions/helper-injection-policy-on-every-injecting-capability.md`.
+- **`oats.core` 1.0.1** (in oats.framework 1.1.3): `helperInjection: {version:
+  1, mode: inherit}`; a helper keeps the "you run on OATS" briefing.
+- **aweb 1.11.2**: `helperInjection: {version: 1, mode: omit}`; a harvest
+  helper has no messaging identity. Manifest-only.
+- Catalog: `oats.aweb` → `v1.11.2`, `oats.framework` →
+  `oats-framework/v1.1.3`; six editions and workspace imports repinned.