@polderlabs/bizar-omp 0.7.0 → 0.7.1

package/docs/development/ci-release-implementation-guide.md

@@ -0,0 +1,1259 @@
+# BizarHarness-OMP CI, Contribution, and Release Architecture
+
+> **Current implementation (2026-09-23):** `.github/workflows/ci.yml` is a
+> phased pipeline with generated runtime matrices, one validated package
+> artifact, native OMP qualification, a stable required-check fan-in, and
+> separate npm Trusted Publishing and GitHub Packages publish jobs. Runtime
+> policy is in `.github/ci-policy.json`; package and OMP values come from
+> `package.json` and `src/omp/compatibility.ts`. The historical migration
+> analysis below records earlier source observations; where it describes a
+> prior workflow shape, the current workflow and `CONTRIBUTING.md` take
+> precedence.
+
+Target repository: `PolderLabs/BizarHarness-OMP`
+Inspected main commit: `064578c3ea60d5b9ec891610ee08b09d92c908fc`
+Package at inspected HEAD: `@polderlabs/bizar-omp` with `package.json` version `0.7.0`
+Upstream reference: `can1357/oh-my-pi` at `0f9139f546e1dcb0e63ce35f1236509c4cca66c1`
+Research date: 2026-09-22
+
+# Migration status
+
+> **Status (2026-09-22):** This plan has been implemented in PR #78 (`ci+release: unified pipeline, local orchestrator, contract tests`). `.github/workflows/immutable-tag.yml` and `.github/workflows/release.yml` are removed. `.github/workflows/ci.yml` is the unified pipeline (verify / package-contract / bun-compatibility / release). The local orchestrator is `scripts/release.mjs` (with `scripts/release-lib.mjs`). Preflight is `scripts/verify-release-state.mjs --strict-network`. The release-receipt generator is `scripts/create-release-receipt.mjs`. The OMP compatibility updater (`scripts/update-omp-compatibility.mjs`) no longer mutates the Bizar package version. The contributor runbook lives in `docs/development/contributing-and-releasing.md`. The remainder of this document is kept as the source of truth for the architecture; if implementation diverges, the implementation wins and this document is updated in a follow-up.
+## Verification status of this plan
+
+
+Evidence labels follow the OMP native-development guidance:
+
+- **SOURCE-OBSERVED:** BizarHarness-OMP repository state at `064578c3ea60d5b9ec891610ee08b09d92c908fc`, including package metadata, release workflows, compatibility automation, and release scripts.
+- **SOURCE-OBSERVED:** current oh-my-pi main at `0f9139f546e1dcb0e63ce35f1236509c4cca66c1`. The release-control files used by this design (`.github/workflows/ci.yml`, `scripts/release.ts`, `CONTRIBUTING.md`, and `.github/PULL_REQUEST_TEMPLATE.md`) are unchanged in substance from the previously inspected `6cb51f9...` snapshot.
+- **DOCUMENTED:** npm Trusted Publishing currently requires npm CLI `>=11.5.1`, Node `>=22.14.0`, a supported cloud-hosted runner, and `id-token: write`; private source repositories can use OIDC publishing but do not receive npm provenance attestations. Existing Trusted Publisher connections cannot be edited in place.
+- **DOCUMENTED:** GitHub Actions workflow-level `concurrency.cancel-in-progress` may be an expression; this supports the release-safe per-SHA pattern used by OMP.
+- **UNKNOWN:** whether `@polderlabs/bizar-omp@0.7.0` is already published. Registry access was unavailable in the audit environment, so Phase 0 must query npm before changing the current version state.
+- **PROPOSED:** the Bizar-specific unified workflow graph, qualification matrix, release receipt, and agent authority rules below.
+
+No unexecuted release or CI path is labeled TESTED in this document. The migration is complete only after the acceptance cases in section 25 are actually executed.
+
+## 1. Goal
+
+BizarHarness-OMP should adopt the release architecture used by oh-my-pi without copying OMP's platform-binary complexity.
+
+The target model is:
+
+1. Contributor PRs change code, tests, docs, and the `[Unreleased]` changelog only.
+2. PR CI validates the contribution. A PR never publishes and never bumps the package version.
+3. Merged changes accumulate on `main`, which remains releasable.
+4. A maintainer manually decides when to release and which SemVer impact applies.
+5. A local release script prepares one version-bump commit and one matching `vX.Y.Z` tag.
+6. The release script pushes `main` and the tag atomically.
+7. The ordinary `CI` workflow detects that its `main` HEAD is tagged and turns the same CI run into the release run.
+8. Validation and release-artifact preparation run in parallel where useful.
+9. Publication is held behind one release validation gate.
+10. CI publishes the exact validated npm artifact through npm trusted publishing, verifies the registry artifact, and then creates the GitHub Release with checksums and a release receipt.
+
+The key rule is:
+
+> A merged PR is not a release. A release is an explicit maintainer action against a green, releasable `main`.
+
+## 2. What exists now
+
+The repository already has useful pieces and should preserve them:
+
+- `.github/workflows/ci.yml`
+  - Node 22/24 matrix.
+  - package/security/document verification.
+  - Bun compatibility.
+  - packed installation verification against OMP 18.2.8.
+- `.github/workflows/release.yml`
+  - npm trusted publishing via GitHub OIDC.
+  - tag/version verification.
+  - native OMP installation verification.
+  - registry visibility wait.
+  - registry plugin-install verification.
+  - GitHub Release creation.
+- `.github/workflows/immutable-tag.yml`
+  - verifies that a tag points at a commit with a successful `CI` run.
+- `.github/workflows/omp-compatibility.yml`
+  - daily OMP release detection.
+  - immutable OMP tag resolution.
+  - npm integrity capture.
+  - packed OMP qualification.
+  - automated compatibility PR creation.
+- `scripts/publish-release.mjs`
+  - idempotent registry lookup.
+  - local-vs-registry content comparison.
+  - safe handling when a version already exists.
+- `scripts/verify-release.mjs`
+  - tag/package version check.
+- `scripts/verify-omp-install.mjs`
+  - packed plugin installation and native discovery qualification.
+- `scripts/verify-omp-plugin-install.mjs`
+  - post-publication registry install and OMP doctor qualification.
+- `scripts/check-secrets.mjs`
+  - repository secret canaries.
+- `docs/compatibility/baseline.json`
+  - explicit Bizar/OMP qualification fingerprint.
+- `docs/releases/`
+  - release notes and release policy.
+- `CONTRIBUTING.md`
+  - branch naming and local verification guidance.
+
+These are good building blocks. The migration should consolidate them rather than replacing them with a generic release framework such as semantic-release or Changesets.
+
+## 3. Current problems to correct first
+
+### 3.1 Version metadata is currently inconsistent
+
+At inspected HEAD:
+
+- `package.json`: `0.7.0`.
+- `package-lock.json` root: `0.6.8`.
+- `package-lock.json` `packages[""]`: `0.6.8`.
+- `docs/compatibility/baseline.json` package version: `0.6.8`.
+
+`package.json` was bumped in commit `064578c3...`, but the other release metadata was not updated.
+
+This already conflicts with `verify:docs`, which requires the baseline package version to match `package.json`.
+
+Before introducing the new release system, reconcile this state. If `0.7.0` has not actually been published, restore the repository to the last published version and let the new release script create `0.7.0` later. If `0.7.0` has been published, synchronize every release metadata file to the exact published version and artifact.
+
+Do not guess publication state from `package.json` alone.
+
+### 3.2 The lockfile has evidence of unsafe version editing
+
+The current lockfile contains transitive entries whose `version` field is `0.6.7` while their `resolved` URL names a completely different dependency version. That is not a valid release-management strategy.
+
+The new release code MUST NOT regex-replace arbitrary `"version"` fields in `package-lock.json`.
+
+Required rule:
+
+1. Never regex-rewrite `package-lock.json`.
+2. For normal version bumps, use npm itself:
+   `npm version <target> --no-git-tag-version --ignore-scripts`.
+   npm documents that `npm version` updates both `package.json` and `package-lock.json`; disabling Git tagging leaves commit/tag ownership with `scripts/release.mjs`.
+3. Verify both root lockfile version fields match `package.json`.
+4. Run `npm ci` from the updated lock before release.
+
+The currently corrupted lockfile is a separate migration repair. Rebuild it with npm in an isolated branch/worktree, inspect every dependency-tree change, and do not accept accidental dependency upgrades as release bookkeeping. If a clean regeneration changes resolved dependency versions, treat those as dependency changes requiring normal review and validation.
+
+### 3.3 Bizar has no `[Unreleased]` contribution buffer
+
+Current `CHANGELOG.md` starts directly with released version sections. This forces release metadata to be created during feature/release commits rather than allowing normal PRs to accumulate releasable change descriptions.
+
+Add at the top:
+
+```md
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Security
+
+### Compatibility
+```
+
+Empty subsections may be omitted. The release script promotes non-empty `[Unreleased]` content into the version being released and recreates an empty `[Unreleased]` section.
+
+### 3.4 Release state is split across three workflows
+
+Today:
+
+```text
+CI
+  -> tag pushed
+     -> immutable-tag.yml
+        -> release.yml
+           -> npm/GitHub release
+```
+
+The desired OMP model is:
+
+```text
+one main push CI run
+  -> detect release tag on HEAD
+  -> run normal validation
+  -> prepare release artifact in parallel
+  -> release_gate
+  -> npm publish
+  -> registry verification
+  -> GitHub Release
+```
+
+Once the new workflow is proven, remove `.github/workflows/immutable-tag.yml` and `.github/workflows/release.yml`. Their responsibilities move into `.github/workflows/ci.yml`.
+
+### 3.5 `make verify` and documentation disagree
+
+`CONTRIBUTING.md` says the local gate includes packed-artifact checks. Current `Makefile` `verify` does not execute `pack:check` or native OMP qualification.
+
+Create one canonical command and make every document call the same command.
+
+Recommended:
+
+```json
+{
+  "scripts": {
+    "check": "npm run typecheck && npm test && npm run verify:package && npm run verify:docs && npm run verify:security && npm run pack:check",
+    "check:full": "npm run check && npm run verify:omp"
+  }
+}
+```
+
+Then:
+
+```make
+verify:
+\tnpm run check
+
+verify-full:
+\tnpm run check:full
+```
+
+`check` is the normal contributor gate. `check:full` is the OMP-sensitive/release qualification gate when a compatible OMP host is available.
+
+## 4. Proposed repository structure
+
+Add or change these files:
+
+```text
+BizarHarness-OMP/
+├── AGENTS.md                                  NEW - coding-agent authority guide
+├── CONTRIBUTING.md                            UPDATE - human contribution/release policy
+├── CHANGELOG.md                               UPDATE - [Unreleased] workflow
+├── Makefile                                   UPDATE - canonical check commands
+├── package.json                               UPDATE - check/release scripts
+├── package-lock.json                          REGENERATE, never regex-edit
+│
+├── .github/
+│   ├── PULL_REQUEST_TEMPLATE.md               NEW
+│   ├── dependabot.yml                         KEEP
+│   └── workflows/
+│       ├── ci.yml                             REWRITE/EXPAND; CI + release
+│       ├── omp-compatibility.yml              KEEP, MODIFY behavior
+│       ├── immutable-tag.yml                  REMOVE after migration
+│       └── release.yml                        REMOVE after migration
+│
+├── scripts/
+│   ├── release.mjs                            NEW - local maintainer orchestrator
+│   ├── release-lib.mjs                        NEW - pure/testable release helpers
+│   ├── verify-release-state.mjs               NEW - metadata/tag consistency gate
+│   ├── create-release-receipt.mjs             NEW - immutable release receipt
+│   ├── publish-release.mjs                    KEEP, adapt to CI artifact path/channel
+│   ├── verify-release.mjs                     REPLACE or fold into release-state verifier
+│   ├── verify-package.mjs                     KEEP
+│   ├── verify-omp-install.mjs                 KEEP
+│   ├── verify-omp-plugin-install.mjs          KEEP
+│   ├── update-omp-compatibility.mjs           MODIFY - never bump Bizar version
+│   └── check-secrets.mjs                      KEEP
+│
+├── tests/
+│   ├── release.test.ts                        NEW
+│   ├── workflow-contract.test.ts              NEW
+│   └── ...                                    EXISTING
+│
+└── docs/
+    ├── development/
+    │   └── contributing-and-releasing.md      NEW - detailed policy/runbook
+    ├── compatibility/
+    │   └── baseline.json                      KEEP; release script owns package.version
+    └── releases/
+        ├── native-stable.md                    KEEP; release script updates stable pointer
+        └── X.Y.Z.md                            GENERATED/FINALIZED by release process
+```
+
+## 5. Contribution model
+
+### 5.1 Normal contributor PR
+
+A normal PR MUST NOT:
+
+- change `package.json` version;
+- change package-lock root version manually;
+- create a `v*` tag;
+- call `npm publish`;
+- create a GitHub Release;
+- finalize a release date/version in `CHANGELOG.md`;
+- change `docs/releases/native-stable.md` to a not-yet-released version.
+
+A normal PR SHOULD:
+
+- contain one logical change;
+- include tests for changed behavior;
+- include direct/manual verification for user-visible behavior;
+- update documentation where behavior changed;
+- add a concise entry under `CHANGELOG.md -> [Unreleased]` when user-facing;
+- identify release impact in the PR as `patch`, `minor`, `breaking`, or `none` without changing the actual version.
+
+For external contributions, use OMP's useful attribution convention after a PR number exists:
+
+```md
+- Fix session reconnect after a detached host exits (#123 by @contributor).
+```
+
+For internal work linked to an issue:
+
+```md
+- Fix session reconnect after a detached host exits (#123).
+```
+
+### 5.2 Major changes
+
+Adopt the same conceptual split as upstream OMP:
+
+- Small bug fixes, docs, narrow improvements: PR directly.
+- New subsystems, broad architecture changes, security model changes, cross-cutting OMP contract changes, new runtime dependencies, or major UI redesign: discuss/approve scope before implementation.
+
+The Bizar-specific agent guide should make this a hard instruction for coding agents: do not expand a narrowly scoped task into architecture work merely because the agent sees an opportunity.
+
+### 5.3 Merge does not publish
+
+Merging a PR only updates `main` and `[Unreleased]`.
+
+```text
+PR #101 fix -> merge
+PR #102 feature -> merge
+PR #103 docs -> merge
+PR #104 OMP compatibility -> merge
+
+main remains at the currently released package version
+[Unreleased] accumulates the changes
+
+maintainer later chooses release boundary
+```
+
+This is a major change from the current habit of mixing version changes with feature/release PRs.
+
+## 6. Release decision policy
+
+The maintainer decides when to release. CI does not infer a release from Conventional Commits and does not auto-publish after merges.
+
+A stable release is appropriate when:
+
+1. `main` contains a coherent set of changes worth shipping.
+2. `[Unreleased]` accurately describes user-visible changes.
+3. Required docs and compatibility metadata are current.
+4. The normal CI state is green or the maintainer has intentionally authorized a documented emergency path.
+5. No known release-blocking audit finding remains open.
+6. The qualified OMP target still matches the package's claims.
+
+Recommended Bizar SemVer policy while version is `<1.0.0`:
+
+- `patch`: fixes, docs, compatibility qualification, and backward-compatible refinements.
+- `minor`: substantial backward-compatible features OR intentionally breaking pre-1.0 changes.
+- `major`: `1.0.0` and later major compatibility boundaries.
+
+After `1.0.0`, use standard SemVer:
+
+- patch = backward-compatible fixes;
+- minor = backward-compatible features;
+- major = breaking public contract.
+
+Agents may recommend release impact in a PR, but the maintainer owns the final version decision.
+
+## 7. Local release orchestrator
+
+Create `scripts/release.mjs`, with pure helpers in `scripts/release-lib.mjs` so version/changelog logic is unit tested.
+
+Required stable commands:
+
+```sh
+npm run release -- patch
+npm run release -- minor
+npm run release -- major
+npm run release -- 0.8.0
+npm run release -- watch
+```
+
+Do not advertise `canary` until it is implemented and tested end to end. If canary support is added later, it must use a prerelease version, publish with npm dist-tag `canary`, mark the GitHub Release as a prerelease, and MUST NOT promote `[Unreleased]` or update the stable-release pointer.
+
+### 7.1 Preflight
+
+The script MUST fail before making changes unless all are true:
+
+- current branch is `main`;
+- working tree is clean;
+- local `main` equals `origin/main` after `git fetch origin main --tags`;
+- repository contains no conflicting local release tag;
+- package metadata is coherent before bump;
+- current package version equals the last stable released version expected by repository policy;
+- `[Unreleased]` exists;
+- the selected next version is greater than the previous stable tag;
+- `gh` is authenticated if CI watching is requested.
+
+Never print npm/GitHub credentials.
+
+### 7.2 Version mutation
+
+The release script owns these version-dependent files:
+
+- `package.json` version.
+- `package-lock.json` root version, via npm regeneration only.
+- `docs/compatibility/baseline.json -> package.version`.
+- README current package pin if that pin remains in README.
+- `CHANGELOG.md` promotion of `[Unreleased]`.
+- `docs/releases/<version>.md`.
+- `docs/releases/native-stable.md` for stable releases.
+
+Do NOT let contributor PRs edit these fields as release bookkeeping.
+
+Recommended mutation order:
+
+1. Run `npm version <target> --no-git-tag-version --ignore-scripts` so npm updates `package.json` and the root lockfile version metadata together without creating a commit or tag.
+2. Assert that the dependency graph in `package-lock.json` did not change except where separately authorized; a release bump must not smuggle dependency upgrades.
+3. Update baseline `package.version`.
+4. Promote changelog:
+
+Before:
+
+```md
+## [Unreleased]
+
+### Fixed
+- Fix X.
+```
+
+After:
+
+```md
+## [Unreleased]
+
+## [0.7.1] - 2026-09-22
+
+### Fixed
+- Fix X.
+```
+
+5. Generate/finalize `docs/releases/0.7.1.md` from the promoted changelog and release metadata.
+6. Update the stable release pointer.
+7. Run release-state verification.
+
+### 7.3 Local checks
+
+Before the release commit/tag exists:
+
+```sh
+npm ci
+npm run check
+npm run verify:release-state
+```
+
+When an OMP runtime is locally available, also run:
+
+```sh
+npm run verify:omp
+```
+
+The final authoritative OMP matrix still runs in GitHub Actions. A missing local OMP runtime is not a pass; report it as not run.
+
+### 7.4 Release commit and tag
+
+Use one exact commit-subject convention because CI concurrency uses it to protect release runs from cancellation:
+
+```text
+chore: bump version to 0.7.1
+```
+
+Create:
+
+```text
+v0.7.1
+```
+
+Push branch and tag atomically, using the release commit SHA as the tag source:
+
+```sh
+git push --atomic origin \
+  refs/heads/main:refs/heads/main \
+  <release-sha>:refs/tags/v0.7.1
+```
+
+Do not make `ci.yml` trigger on tags. The authoritative release run is the `main` push run. That run discovers the tag on its HEAD.
+
+This follows upstream OMP's current architecture and avoids two independent branch/tag CI runs racing each other.
+
+### 7.5 Watch CI
+
+Port the useful behavior from OMP's `scripts/release.ts`:
+
+- query `gh run list --commit <sha>`;
+- wait for the `CI` run to appear;
+- inspect in-progress jobs;
+- fail early when a job fails;
+- show a short tail from failed job logs;
+- exit success only when the authoritative release CI run passes.
+
+The release script MUST NOT call `npm publish` or `gh release create` locally during a normal release.
+
+## 8. Unified `.github/workflows/ci.yml`
+
+The workflow should handle three modes:
+
+```text
+PR                -> validate only
+ordinary main     -> validate only
+release main HEAD -> validate + publish
+```
+
+### 8.1 Triggers
+
+Recommended:
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+```
+
+Do not add `push.tags`. The release script pushes tag + main atomically and the main run detects the tag.
+
+Avoid narrow path filters unless every release-sensitive path is comprehensively included. OMP explicitly learned that omitted lockfile/root paths can allow untested releases. Bizar is small enough that always running CI is safer and simpler.
+
+### 8.2 Concurrency
+
+Use OMP's release-safe pattern.
+
+Conceptually:
+
+```yaml
+concurrency:
+  group: >-
+    ${{ github.workflow }}-${{
+      (startsWith(github.event.head_commit.message, 'chore: bump version to ')
+       || startsWith(github.ref, 'refs/tags/v')
+       || github.event_name == 'workflow_dispatch')
+      && format('release-{0}', github.sha)
+      || github.ref
+    }}
+  cancel-in-progress: >-
+    ${{ !(startsWith(github.event.head_commit.message, 'chore: bump version to ')
+       || startsWith(github.ref, 'refs/tags/v')
+       || github.event_name == 'workflow_dispatch') }}
+```
+
+Reason:
+
+- normal PR/main churn cancels stale work;
+- a later main push can never cancel an in-progress release publication;
+- release runs are isolated by SHA.
+
+### 8.3 Global permissions
+
+Keep the workflow default minimal:
+
+```yaml
+permissions:
+  contents: read
+```
+
+Only the npm publication job receives `id-token: write`.
+Only the GitHub Release job receives `contents: write`.
+
+Do not grant publishing permissions globally or to PR jobs.
+
+## 9. Release metadata job
+
+Add first job:
+
+```text
+release_metadata
+  name: Resolve release metadata
+```
+
+Responsibilities:
+
+1. checkout with tags available when running on `main`;
+2. find `v*` tag pointing at HEAD;
+3. reject multiple release tags on HEAD;
+4. validate tag version against `package.json`;
+5. determine release channel (stable initially; canary only after optional canary support is implemented);
+6. output:
+   - `is-release`;
+   - `release-tag`;
+   - `version`;
+   - `channel`.
+
+The job should use `scripts/verify-release-state.mjs` rather than duplicating all rules in shell.
+
+A normal PR/main run returns `is-release=false` and continues as normal CI.
+
+## 10. Validation job graph
+
+Bizar does not need OMP's Rust/native binary fanout. A targeted graph is:
+
+```text
+                         release_metadata
+                              |
+          +-------------------+--------------------+
+          |                   |                    |
+     node_matrix        package_contract       bun_compat
+          |                   |                    |
+          +-------------------+--------------------+
+                              |
+                     omp_qualification
+                              |
+                         release_gate
+                              |
+                     publish_npm
+                              |
+                    verify_registry
+                              |
+                    github_release
+```
+
+Release artifact preparation can start as soon as `package_contract` passes and run in parallel with OMP qualification:
+
+```text
+package_contract -> release_artifact -----+
+                                           |
+omp_qualification + other CI -> release_gate
+                                           |
+                              publish exact artifact
+```
+
+### 10.1 `node_matrix`
+
+Keep Node 22 and 24 because the package claims Node >=22.
+
+Recommended matrix work:
+
+```sh
+npm ci
+npm test
+```
+
+Run typecheck/build once in package-contract to avoid unnecessary duplicate work, unless Node-specific type/build differences are intentionally being tested.
+
+### 10.2 `package_contract`
+
+Run on Node 24:
+
+```sh
+npm ci
+npm run typecheck
+npm run build
+npm run verify:package
+npm run verify:docs
+npm run verify:security
+npm run pack:check
+npm run verify:release-state
+```
+
+This is the main deterministic package gate.
+
+### 10.3 `bun_compatibility`
+
+Keep Bun 1.3.14 qualification because the package explicitly supports it:
+
+```sh
+npm ci
+bun run typecheck
+bun run test
+```
+
+This should not be responsible for installing OMP. Keep runtime compatibility and OMP qualification separate so failures are diagnosable.
+
+### 10.4 `omp_qualification`
+
+This is Bizar's most important product-specific gate.
+
+At minimum on every PR/main run, qualify:
+
+- current supported OMP, presently 18.2.8;
+- previous supported OMP, presently 18.2.7, if the repository continues to claim it as regression-qualified.
+
+For a stable release, run the complete set that the package claims is qualified, or narrow the public claim to the versions actually tested.
+
+Current code claims:
+
+```text
+18.2.4
+18.2.5
+18.2.6
+18.2.7
+18.2.8
+```
+
+If all five remain in `QUALIFIED_OMP_VERSIONS`, a stable release should have an auditable qualification policy for all five. A practical compromise is:
+
+- PR/main: latest + N-1;
+- release: full qualified matrix;
+- scheduled compatibility watch: prospective next OMP version.
+
+Do not hard-code that matrix in workflow YAML. Add a small script such as `scripts/print-omp-matrix.mjs` that derives the selected matrix from the canonical compatibility source (`src/omp/compatibility.ts` or a single structured compatibility manifest). An `omp_matrix` job emits JSON and `omp_qualification` consumes it with `fromJSON`. This prevents routine OMP-compatibility PRs from modifying security-sensitive workflow files.
+
+Run packed installation against each selected version:
+
+```sh
+bun install --cwd "$RUNNER_TEMP/omp-host" "@oh-my-pi/pi-coding-agent@$OMP_VERSION"
+BIZAR_OMP_PACKAGE_ROOT=... BIZAR_OMP_BIN=... npm run verify:omp
+```
+
+Do not claim a compatibility version solely because it remains in an array.
+
+### 10.5 `release_artifact`
+
+Run only when `release_metadata.is-release == true`.
+
+Build and pack exactly once:
+
+```sh
+npm ci
+npm run build
+node scripts/verify-package.mjs
+npm pack --ignore-scripts --json
+```
+
+Generate:
+
+- `polderlabs-bizar-omp-X.Y.Z.tgz`;
+- a tarball SHA-256 record;
+- `release-receipt.partial.json` with commit/tree/version/toolchain/OMP target.
+
+Upload these as a short-retention Actions artifact.
+
+The publish job must download this exact tarball. Do not rebuild/repack after the release gate. Final `release-receipt.json` and `SHA256SUMS.txt` are produced only after registry verification so the receipt can contain the observed npm integrity and post-publish verification result.
+
+## 11. Release validation gate
+
+Add:
+
+```text
+release_gate
+  name: Release validation gate
+```
+
+It only runs for release HEADs and only succeeds when every required validation job succeeded.
+
+For Bizar, require at least:
+
+- Node matrix success;
+- package contract success;
+- Bun compatibility success;
+- release OMP qualification matrix success;
+- release artifact success;
+- workflow contract/security checks success.
+
+The gate itself should be trivial after dependencies are green, for example:
+
+```sh
+npm run verify:release-state
+```
+
+followed by a clear `release validation green` message.
+
+This is the single publish admission point. Do not make downstream publish jobs each reinvent their own definition of green CI.
+
+## 12. npm publication
+
+Keep npm trusted publishing. It is better than a long-lived `NPM_TOKEN`.
+
+Current npm documentation requires npm CLI `>=11.5.1`, Node `>=22.14.0`, a supported cloud-hosted runner, and `id-token: write`. Use GitHub-hosted Ubuntu with Node 24 and pin npm to an explicitly supported 11.x version used by the workflow.
+
+Because BizarHarness-OMP is a private GitHub repository, npm provenance attestations are not available even though OIDC trusted publishing works. Keep this distinction explicit and set `NPM_CONFIG_PROVENANCE=false` in the publish job.
+
+### Critical migration action
+
+The existing npm trusted publisher is documented as pointing at `release.yml`.
+
+After publication moves into `ci.yml`, update npm package settings:
+
+```text
+Provider: GitHub Actions
+Organization: PolderLabs
+Repository: BizarHarness-OMP
+Workflow filename: ci.yml
+Allowed action: npm publish
+```
+
+npm's current trusted-publisher configuration cannot be edited in place; delete/recreate the publisher entry if necessary.
+
+Do this before removing `release.yml` or the first new release will fail OIDC authorization.
+
+### Publish job
+
+```text
+publish_npm
+  needs: [release_metadata, release_gate, release_artifact]
+```
+
+Permissions:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+```
+
+Steps:
+
+1. download the exact tarball artifact;
+2. install Node 24 and an explicitly pinned npm 11.x version `>=11.5.1`; disable package-manager caching for this publication job;
+3. verify the downloaded tarball SHA-256 against the release-artifact metadata;
+4. run `scripts/publish-release.mjs --tarball <path> --tag latest` (adapt the script to accept an explicit artifact path and dist-tag rather than relying on cwd/implicit `latest`);
+5. keep the `npm publish` command directly in `ci.yml` rather than hiding it behind a reusable workflow unless the npm Trusted Publisher is intentionally configured for that calling workflow;
+6. if optional canary support is later added, use `--tag canary`.
+
+Prefer removing `NPM_TOKEN` fallback from the normal path once trusted publishing is confirmed. A long-lived token should not silently mask an OIDC configuration error.
+
+## 13. Verify the published registry artifact
+
+Preserve and strengthen the existing post-publish behavior.
+
+`verify_registry` should:
+
+1. wait for `@polderlabs/bizar-omp@X.Y.Z` to become visible;
+2. retrieve its registry integrity;
+3. compare unpacked published file contents/modes with the CI tarball, reusing `publish-release.mjs` logic where practical;
+4. create a fresh OMP host;
+5. run `npm run verify:omp:registry` against the exact published version;
+6. fail the release chain if plugin install/discovery/doctor fails.
+
+This is the Bizar equivalent of OMP downloading and smoke-testing an actual published binary.
+
+## 14. GitHub Release
+
+For Bizar, create the GitHub Release after npm registry verification. This is intentionally slightly different from OMP because Bizar's primary deliverable is the npm package, not standalone platform binaries.
+
+Before creating the GitHub Release:
+
+1. finalize `release-receipt.json` with observed registry integrity, registry verification result, qualification matrix outcomes, and CI run identity;
+2. generate the final `SHA256SUMS.txt` over the exact npm `.tgz` and `release-receipt.json`;
+3. verify those digests locally in the release job.
+
+Attach:
+
+- the exact npm `.tgz` artifact;
+- `release-receipt.json`;
+- the final `SHA256SUMS.txt`.
+
+Generate release text from:
+
+1. the promoted changelog section;
+2. `docs/releases/X.Y.Z.md`;
+3. GitHub's generated PR/contributor notes as supplemental information.
+
+Do not let GitHub-generated notes become the only release description; Bizar's compatibility/qualification boundary is important and should be explicit.
+
+## 15. Release receipt
+
+Create `scripts/create-release-receipt.mjs` and make every release produce a machine-readable receipt such as:
+
+```json
+{
+  "schemaVersion": 1,
+  "package": {
+    "name": "@polderlabs/bizar-omp",
+    "version": "0.7.1"
+  },
+  "git": {
+    "commit": "...",
+    "tree": "...",
+    "tag": "v0.7.1"
+  },
+  "artifact": {
+    "filename": "polderlabs-bizar-omp-0.7.1.tgz",
+    "sha256": "...",
+    "npmIntegrity": "sha512-..."
+  },
+  "omp": {
+    "supported": "18.2.8",
+    "commit": "5e0fc867...",
+    "qualification": [
+      {"version": "18.2.7", "status": "passed", "job": "..."},
+      {"version": "18.2.8", "status": "passed", "job": "..."}
+    ]
+  },
+  "runtime": {
+    "node": "24.x",
+    "npm": "11.x",
+    "bun": "1.3.14"
+  },
+  "ci": {
+    "repository": "PolderLabs/BizarHarness-OMP",
+    "runId": "...",
+    "runAttempt": 1
+  }
+}
+```
+
+This directly addresses the repository's earlier audit concern around durable qualification evidence.
+
+## 16. `omp-compatibility.yml` after migration
+
+Keep this workflow separate. It is maintenance automation, not release automation.
+
+The current workflow is conceptually good:
+
+```text
+schedule/manual
+ -> read currently supported OMP
+ -> read latest npm OMP
+ -> resolve immutable Git tag
+ -> obtain npm integrity
+ -> qualify packed Bizar against candidate
+ -> open normal PR
+```
+
+Change one critical behavior: `scripts/update-omp-compatibility.mjs` MUST stop bumping the Bizar package version.
+
+It currently calculates a next Bizar patch version and updates package/release metadata. Under the new model that is wrong.
+
+The compatibility updater should modify only compatibility-relevant development state:
+
+- `src/omp/compatibility.ts`;
+- OMP version/integrity/commit fields in compatibility docs;
+- support matrix;
+- OMP-specific skill fingerprint/reference files;
+- README OMP requirements if necessary;
+- `CHANGELOG.md [Unreleased] -> Compatibility` entry.
+
+It MUST NOT modify:
+
+- `package.json` version;
+- package-lock root version;
+- baseline `package.version`;
+- stable release note pointer;
+- create `docs/releases/X.Y.Z.md`;
+- `.github/workflows/ci.yml` merely to change an OMP version literal.
+
+Also remove broad `replaceAll(currentVersion, targetVersion)` behavior from compatibility maintenance. Historical references and release evidence must not be rewritten accidentally. Update exact structured fields/markers only, and test the resulting diff.
+
+The automated OMP PR then behaves exactly like any other contributor PR. A maintainer later decides whether it ships in a patch/minor release.
+
+## 17. Pull request template
+
+Add `.github/PULL_REQUEST_TEMPLATE.md` adapted from upstream OMP but Bizar-specific:
+
+```md
+## What
+
+<!-- Explain what changed. Human contributors should include at least one sentence in their own words. -->
+
+## Why
+
+<!-- Motivation, issue, audit finding, or approved scope. -->
+
+## Verification
+
+<!-- Exact checks AND the behavior exercised manually/end-to-end. -->
+
+## Release impact
+
+- [ ] none
+- [ ] patch
+- [ ] minor
+- [ ] breaking
+
+## Checklist
+
+- [ ] `npm run check` passes
+- [ ] Changed behavior was exercised directly, not only unit-tested
+- [ ] OMP-sensitive changes ran the required native qualification
+- [ ] `[Unreleased]` changelog updated if user-facing
+- [ ] No package version, release tag, or published-release metadata was changed
+- [ ] No credentials or private runtime state were added
+```
+
+For automated/internal PRs, the "human-written sentence" requirement can be adapted to your organization policy, but the verification and release-impact fields should remain.
+
+## 18. Root `AGENTS.md`
+
+Add the audited root `AGENTS.md` committed alongside this implementation guide. Treat it as the coding-agent authority contract for future work.
+
+The root guide should be short enough that every coding agent can load it, but explicit enough to prevent the recurring failure mode where an agent treats "feature complete" as permission to bump/publish a release.
+
+It must establish:
+
+- normal agents work on branches/PRs;
+- package versions are maintainer/release-script owned;
+- all user-facing work goes to `[Unreleased]`;
+- an agent may recommend release impact but not choose/publish a version autonomously;
+- only an explicit release task may run `scripts/release.mjs`;
+- never call `npm publish`, create/move release tags, or create GitHub Releases manually during ordinary coding work;
+- exact local verification requirements;
+- OMP contract change qualification requirements;
+- release failure recovery rules;
+- no hidden fallback from OIDC to long-lived tokens in the normal release path.
+
+## 19. Workflow contract tests
+
+The repository already learned that workflow names, mutable third-party action tags, and release documentation can drift. Add static tests.
+
+`tests/workflow-contract.test.ts` should assert at minimum:
+
+1. all third-party GitHub Actions are pinned to full commit SHAs, except explicitly allowlisted first-party/local cases if you choose that policy;
+2. `ci.yml` contains `Release validation gate`;
+3. `ci.yml` has no direct tag push trigger;
+4. npm publish job has `id-token: write`;
+5. PR validation jobs do not have `id-token: write` or `contents: write`;
+6. release publication needs the release gate;
+7. no active `release.yml`/`immutable-tag.yml` remains after migration;
+8. OMP compatibility workflow does not mutate package release version;
+9. package version metadata consistency script passes;
+10. documented workflow filename for npm trusted publishing is `ci.yml`.
+
+This should be part of `npm run check`.
+
+## 20. GitHub repository settings
+
+When repository plan/capabilities permit, configure a ruleset for `main`:
+
+- require pull request for ordinary contributors;
+- require current CI checks;
+- require conversation resolution;
+- block force pushes and deletion;
+- allow a small maintainer/release role to bypass specifically for the release script's atomic main+tag push.
+Current repository documentation says branch protection/rulesets are unavailable on the active private-repository plan. Until that changes, describe PR/release discipline as required process, not technically enforced policy.
+
+Do not claim CI blocks direct pushes if GitHub settings do not actually enforce it.
+
+## 21. npm settings migration
+
+Before first release from unified `ci.yml`:
+
+1. Confirm `@polderlabs/bizar-omp` Trusted Publisher currently points at `release.yml`.
+2. Delete/recreate the publisher for `ci.yml` if necessary.
+3. Allow direct `npm publish` for that publisher.
+4. Keep the publishing job on a GitHub-hosted runner.
+5. Do not rely on `npm whoami` to test OIDC; trusted publishing token exchange happens at publish time.
+6. Keep `NPM_CONFIG_PROVENANCE=false` while the source repository is private.
+7. Remove/disable long-lived publish token fallback from the normal CI path once OIDC is proven.
+
+## 22. Failure and recovery policy
+
+Release recovery must distinguish pre-publication from post-publication failure.
+
+### Before npm publication succeeded
+
+If the release CI fails before npm contains the version:
+
+1. fix the defect on the release commit/version;
+2. preserve the exact release commit subject convention;
+3. move/recreate the release tag to the corrected commit only while the version is still unpublished;
+4. push corrected main+tag atomically;
+5. watch CI again.
+
+The release script may provide a `retry`/`watch` mode, but must check the registry first.
+
+### After npm publication succeeded
+
+npm versions are immutable. Never move the same version tag to different contents after npm has published that version.
+
+If a defect is found after publication:
+
+1. leave the published tag/version immutable;
+2. fix on `main`;
+3. add the fix to `[Unreleased]`;
+4. cut a new patch/minor version.
+
+If GitHub Release creation fails after npm publication, rerunning CI may recreate the GitHub Release only if it verifies that the exact npm artifact matches the CI tarball.
+
+## 23. Emergency/manual release path
+
+Keep an emergency path, but make it explicitly exceptional.
+
+A coding agent must never select this path on its own.
+
+An authorized maintainer must explicitly state that GitHub Actions is unavailable and authorize the override.
+
+The manual path must generate the same release receipt and record:
+
+- commit/tree/tag;
+- package tarball SHA-256 and npm integrity;
+- OMP version/commit/integrity;
+- Node/npm/Bun versions;
+- exact verification commands and results;
+- operator identity/authorization;
+- reason CI was unavailable.
+
+Do not describe such a release as CI-green.
+
+## 24. Recommended implementation sequence
+
+### Phase 0 - normalize current state
+
+1. Determine whether `0.7.0` is actually published.
+2. Reconcile `package.json`, package-lock root metadata, and baseline package version.
+3. Regenerate `package-lock.json` with npm and review the transitive-version corrections.
+4. Run `npm ci`, tests, package/docs/security verification.
+5. Commit this as a dedicated metadata/lockfile repair if needed.
+
+Do not build the new release automation on top of incoherent version state.
+
+### Phase 1 - contribution contract
+
+1. Add `[Unreleased]` to `CHANGELOG.md`.
+2. Add root `AGENTS.md` from the provided draft.
+3. Rewrite `CONTRIBUTING.md` around contributor-vs-maintainer responsibilities.
+4. Add `.github/PULL_REQUEST_TEMPLATE.md`.
+5. Add `npm run check` and `check:full`.
+6. Make `Makefile` call the canonical commands.
+
+### Phase 2 - release script
+
+1. Add `release-lib.mjs` pure functions.
+2. Add unit tests.
+3. Add `verify-release-state.mjs`.
+4. Add `release.mjs` preflight/version/changelog/commit/tag/atomic-push/watch flow.
+5. Ensure package-lock is regenerated by npm.
+6. Add release receipt generator.
+
+Do not publish yet. Test the script in dry-run mode and disposable branches/repos first.
+
+### Phase 3 - unified CI
+
+1. Add release_metadata to `ci.yml`.
+2. Separate Node/package/Bun/OMP jobs cleanly.
+3. Add release artifact preparation.
+4. Add release validation gate.
+5. Add npm publish job.
+6. Add registry verification.
+7. Add GitHub Release creation.
+8. Add workflow contract tests.
+9. Keep old release workflows temporarily disabled or on a test branch until the new workflow is proven.
+
+### Phase 4 - OMP compatibility automation
+
+1. Remove Bizar version bumping from `update-omp-compatibility.mjs`.
+2. Remove workflow-YAML version rewriting and broad version-string replacement; update exact compatibility fields only.
+3. Make it write an `[Unreleased]` compatibility entry.
+4. Keep immutable OMP tag+integrity verification.
+5. Keep automated qualification PRs.
+6. Ensure those PRs pass the same contributor CI as all others.
+
+### Phase 5 - credential/settings cutover
+
+1. Change npm Trusted Publisher from `release.yml` to `ci.yml`.
+2. Confirm OIDC with a controlled release (or a canary only after canary semantics are explicitly implemented).
+3. Remove normal-path `NPM_TOKEN` fallback.
+4. Delete/retire `release.yml` and `immutable-tag.yml` only after the unified path succeeds.
+
+### Phase 6 - GitHub governance
+
+1. Configure main ruleset if available.
+2. Mark the stable CI jobs as required.
+3. Give only maintainers/release role bypass for atomic releases.
+4. Keep workflow/security files under maintainer review, optionally via CODEOWNERS once the correct GitHub team/user names are known.
+
+## 25. Acceptance criteria for the migration
+
+Do not call the migration complete until all of the following are demonstrated.
+
+### Contributor path
+
+- A normal PR cannot publish anything.
+- A normal PR leaves package version unchanged.
+- A user-facing PR adds to `[Unreleased]`.
+- Node 22/24, Bun, package/security/docs checks run.
+- OMP-sensitive code is qualified against the declared PR matrix.
+
+### Ordinary main path
+
+- Merge to main runs CI only.
+- No release/tag/npm/GitHub Release is created.
+- Another main push can cancel an obsolete normal main run if desired.
+
+### Release path
+
+- `npm run release -- patch` from clean main creates exactly one version commit and matching tag.
+- main+tag are pushed atomically.
+- only one authoritative CI run handles the release.
+- a later normal main push does not cancel the release run.
+- release artifact builds before/alongside qualification but cannot publish before `release_gate`.
+- npm publication uses OIDC trusted publishing from a GitHub-hosted runner with npm `>=11.5.1` and Node `>=22.14.0`.
+- exact published npm contents match the CI tarball.
+- registry plugin install + OMP doctor pass for the published version.
+- GitHub Release contains the same tarball, checksums, and receipt.
+- rerunning the same release is idempotent when published contents match.
+- a same-version content mismatch fails closed.
+
+### Governance/documentation
+
+- `AGENTS.md`, `CONTRIBUTING.md`, PR template, `docs/releases/npm-publishing.md`, and workflow behavior agree.
+- version metadata cannot drift without CI failing.
+- workflow action pins cannot drift to mutable tags without CI failing.
+- compatibility claims match versions actually tested.
+
+## 26. Important deliberate deviations from upstream OMP
+
+Do not copy these upstream elements into Bizar unless Bizar actually needs them:
+
+- Rust validation.
+- Bazel native addon builds.
+- Linux/macOS/Windows binary build matrices.
+- native leaf npm packages.
+- Homebrew publication.
+- macOS signing/notarization.
+
+Bizar should copy OMP's control architecture, not its product-specific build graph:
+
+```text
+release detection
++ release-safe concurrency
++ one authoritative CI run
++ build/qualification overlap
++ one release gate
++ OIDC publication
++ verification of the actually published artifact
++ atomic version commit/tag push
++ maintainer-owned release decision
+```
+
+That is the part that fits BizarHarness-OMP directly.
+
+## 27. Source references used for this design
+
+BizarHarness-OMP current state:
+
+- `package.json` at `064578c3ea60d5b9ec891610ee08b09d92c908fc`
+- `package-lock.json` at the same commit
+- `.github/workflows/ci.yml`
+- `.github/workflows/release.yml`
+- `.github/workflows/immutable-tag.yml`
+- `.github/workflows/omp-compatibility.yml`
+- `scripts/publish-release.mjs`
+- `scripts/verify-release.mjs`
+- `scripts/update-omp-compatibility.mjs`
+- `scripts/verify-omp-install.mjs`
+- `scripts/verify-omp-plugin-install.mjs`
+- `CONTRIBUTING.md`
+- `CHANGELOG.md`
+- `docs/compatibility/baseline.json`
+- `docs/releases/npm-publishing.md`
+- full-repository audit and closure PR #75
+
+Upstream oh-my-pi reference:
+
+- `can1357/oh-my-pi` `0f9139f546e1dcb0e63ce35f1236509c4cca66c1`
+- `.github/workflows/ci.yml`
+- `scripts/release.ts`
+- `CONTRIBUTING.md`
+- `.github/PULL_REQUEST_TEMPLATE.md`
+- `.omp/commands/release.md`
+
+Upstream OMP's current key mechanics verified in source:
+
+- main-only push CI with tag-on-HEAD release detection;
+- atomic main+tag release push;
+- release-safe per-SHA concurrency;
+- validation fanout plus one `release_gate`;
+- build work overlapping validation;
+- publish jobs gated on release validation;
+- npm OIDC publishing with job-scoped `id-token: write`;
+- post-publication artifact verification;
+- contributor changelog requirements and explicit manual release decision.
+
+Current external documentation checked during the final audit:
+
+- npm Trusted Publishing documentation: workflow filename binding, GitHub-hosted runner requirement, npm `>=11.5.1`, Node `>=22.14.0`, private-repository provenance limitation, and immutable publisher configuration.
+- npm `version` documentation: `npm version` updates `package.json` and `package-lock.json`, while `--no-git-tag-version` suppresses npm-created commits/tags.
+- GitHub Actions workflow syntax: expression-based `concurrency.cancel-in-progress` is supported.