# Release checklist (Bare operating system)

Run these steps before tagging or publishing a Pear bundle so the kernel, seeder mirror, and docs stay aligned.

**Docs:** [documentation home](README.md) · [contributing to docs](CONTRIBUTING-DOCS.md) · [deployment / OTA notes](deployment/OTA_AND_BUNDLES.md).

1. **`npm ci`** at the repository root (clean install).
2. **`npm test`** at the root (includes full **`pretest`** gates plus workspace tests).
3. **`npm run test:bare`** at the root (Bare-runtime protocol + booter + seeder lane).
4. **`node scripts/verify-kernel-seeder-parity.mjs`** (kernel and seeder mirror must match).
5. **`node scripts/verify-init-bundle-recipe.mjs`** and **`node scripts/gen-require-initjs-sha256.mjs`** (init bundle recipe + digest fixture).
6. **`node scripts/verify-ctx-api-feature-bits.mjs`** and **`node scripts/verify-compat-matrix.mjs`** (contract/doc version gates).
7. **`npm run audit:placeholder-baseline`** (refresh and review **`docs/audit/placeholder-baseline-scan.json`**).
8. **Holepunch alignment checks:** run **`node scripts/report-holepunch-lockfile-drift.mjs`**, **`node scripts/report-holepunch-runtime-compat.mjs`**, **`node scripts/gen-holepunch-catalog-tiers.mjs`**, and **`node scripts/verify-holepunch-clone-drift.mjs`**.
9. **`node scripts/verify-personal-drive-path-policy.mjs`** and **`node scripts/verify-ctx-client-helper-sync.mjs`**.
10. **Corestore snapshot workflow drill (operator lane):**
   - quiesce writers (or pause replication),
   - capture a Corestore snapshot with your host tooling,
   - export non-secret summary JSON to **`BARE_OS_CORESTORE_SNAPSHOT_JSON`** and (optionally) **`BARE_OS_CORESTORE_SNAPSHOT_WORKFLOW_JSON`**,
   - verify **`/proc/bare_os/snapshot_hints.json`** and **`/proc/bare_os/replication`** surface the same workflow metadata.
   - optional mirror-drive experiment helper: run **`node scripts/mirror-drive-experiment.mjs --source-key <64hex> --mirror-key <64hex> --aux 1`** and apply emitted env hints before launching booter/seeder.
11. **Shell conformance and flake evidence (required for shell-touching releases):**
   - run **`npm run test -w bare-os-booter`** and **`npm run test:shell-bracket -w bare-os-booter`**,
   - run **`npm run test:shell-fast`** and **`npm run report:shell-reliability`** for fast-lane + machine-readable failure-mode output,
   - run **`npm run verify:reliability-gates`** and **`npm run test:flake-repeat`** (repeat-run must stay green without retries),
   - confirm no retry-dependent shell test behavior in two consecutive clean runs,
   - verify shell docs changed in lockstep when semantics changed (**`docs/reference/shell-grammar.md`**, **`shell-unsupported-behavior.md`**, **`shell-troubleshooting.md`**, **`posix-issue7-traceability.md`**),
   - optional: run **`npm run verify:shell-roadmap`** and review **[`docs/data/shell-roadmap-features.json`](../docs/data/shell-roadmap-features.json)** for phase status.
12. **Zero-trust hard gates (required for trust-surface releases):**
   - run **`npm run verify:zero-trust-gates`**,
   - run **`npm run test -w bare-os-booter`** with **`BARE_OS_ZERO_TRUST_PROFILE=strict`** in at least one clean lane,
   - verify no release config sets **`BARE_OS_PEER_ALLOW_ALL=1`** without explicit break-glass expiry notes,
   - verify signer trust enforcement is on for capability-protected paths (**`BARE_OS_PATH_CAPABILITY_REQUIRE_TRUSTED_SIGNER=1`**).

When **`COREUTILS_COMMANDS`** in **`packages/bare-os-coreutils/lib/commands.mjs`** changes length, update the **Tier-1 count** prose in root **`README.md`**, **`kernel/README.md`**, **`docs/reference/environment-and-posix-appendix.md`**, **`docs/audit/PLACEHOLDER_BASELINE.md`**, and **`packages/bare-os-coreutils/README.md`** to match — **`scripts/verify-doc-tier1-count.mjs`** (part of **`pretest`**) fails otherwise.

Optional: **`npm run release-checklist`** runs **`scripts/release-checklist.mjs`** for automated JSON checks when configured.

**Quarterly:** compare Holepunch dependency pins in **`packages/bare-os-booter/package.json`** (and optional **`optionalDependencies`**) against your local mirror under **`pearcli/holepunch-repos/holepunchto_repos`** (or upstream tags). Note API or semver changes before bulk upgrades. When **`docs/audit/bundle-health.json`** changes by more than a few percent for any bundle, record a one-line reason in **`packages/bare-os-bare-libs/README.md`** (bundle health log) and shrink **`docs/audit/bundle-marker-allowlist.json`** / **`bundle-throw-allowlist.json`** when upstream clears markers.

**Holepunch clone inventory:** run **`node scripts/sync-holepunch-clones.mjs`** on a machine with local org clones to refresh **`docs/audit/holepunch-clone-sync-report.json`** and the NDJSON stream **`docs/audit/holepunch-clone-sync-summary.ndjson`** (one JSON object per manifest package row; safe to commit empty rows when clones are absent).

**Optional strict clone lag gate:** **[`docs/audit/holepunch-freshness-gate.json`](audit/holepunch-freshness-gate.json)** defaults to **`enabled: false`**. Release trains that maintain local mirrors may set **`enabled: true`**, run **`git fetch origin main`** in listed repos, and use **`BARE_OS_HOLEPUNCH_FRESHNESS_STRICT=1`** in CI so **`verify-holepunch-clone-freshness.mjs`** fails when clones exceed **`maxCommitsBehind`**.