diff --git a/.github/PULL_REQUEST_TEMPLATE/promotion.md b/.github/PULL_REQUEST_TEMPLATE/promotion.md
index 9d488e9c..eec969d6 100644
--- a/.github/PULL_REQUEST_TEMPLATE/promotion.md
+++ b/.github/PULL_REQUEST_TEMPLATE/promotion.md
@@ -31,9 +31,10 @@ The `Promotion gate` check directly depends on every constituent below and fails
 | Exact-candidate clean install and startup | `Clean install and startup` | Pending |
 | Real objects install, update, unload, delete | `Real objects install, update, unload, delete` | Pending |
 | Aggregate | `Promotion gate` | Pending |
+| Semantic version and notes | `Release plan` | Pending |
 
 - [ ] The candidate SHA has not changed since every required check completed.
-- [ ] The `Guard main branch source` and `Promotion gate` required contexts pass.
+- [ ] The `Guard main branch source`, `Promotion gate`, and `Release plan` required contexts pass.
 - [ ] The complete file and commit compare contains only reviewed work.
 - [ ] PR conversations, review summaries, and all review threads have been read; actionable findings are addressed and required code-owner approvals exist.
 
@@ -47,6 +48,10 @@ List each unresolved issue and its disposition. Write `None` only after checking
 
 Summarize behavioral changes. If no migration is required, state why.
 
+### Release plan
+
+Review the `Release Plan` workflow comment. Confirm the proposed semantic tag and deterministic notes describe the complete candidate, or confirm that the workflow reports a no-op. If the version is wrong, change the Conventional Commit history on `next` through a reviewed pull request before merging this promotion.
+
 ### Public-contract follow-ups
 
 Link documentation and consumer follow-ups identified by the public-contract impact check. Write `None` only with a rationale.
@@ -102,4 +107,4 @@ Never force-push either persistent branch. Roll back with a reviewed revert comm
 
 ## Stable consumption boundary
 
-Merging this promotion updates the Git-consumed stable `main` ref. It does not create a semantic tag or GitHub release. Any later tag is a separately approved action with its own release notes and exact-ref validation.
+Merging this promotion updates the Git-consumed stable `main` ref and authorizes the reviewed release plan. When releasable commits exist, publication waits until every required workflow succeeds on the exact merge SHA, then creates the annotated tag and GitHub release automatically. A no-op plan creates neither. The signed manual tag path remains available for recovery.
diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml
new file mode 100644
index 00000000..fbc034d9
--- /dev/null
+++ b/.github/workflows/benchmark.yml
@@ -0,0 +1,100 @@
+---
+name: Benchmark
+
+# Non-blocking performance evidence (#553): every pull request into next is
+# measured against its base, and the promotion pull request into main is
+# measured against main. A regression above the thresholds is flagged in the
+# job summary and the artifact; it never fails the job (ADR-0009: observed,
+# not gated). Hosted runners vary, so compare only within one run, where the
+# A/A control row shows the noise floor.
+
+on:
+  pull_request:
+    branches: [next, main]
+    paths:
+      - "zi.zsh"
+      - "lib/**"
+      - "benchmarks/**"
+      - "tests/fixtures/package-manifests/**"
+      - ".github/workflows/benchmark.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  compare:
+    name: Candidate versus baseline
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Check out candidate
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # A fork's head commit does not exist in this repository, so name the
+          # head repository explicitly; the checkout is read-only either way.
+          repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          path: candidate
+          persist-credentials: false
+
+      - name: Check out baseline
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.base.sha || github.sha }}
+          path: baseline
+          persist-credentials: false
+
+      - name: Install Zsh and jq
+        run: sudo apt-get update && sudo apt-get install -yq zsh jq
+
+      - name: Measure baseline, candidate, and an A/A control
+        shell: bash
+        run: |
+          set -uo pipefail
+          # One invocation measures all three variants: within each round
+          # they run in a rotating order, with alternate cycles reversed, so
+          # every variant takes every position and drift on the runner is not
+          # correlated with a variant. The control is the baseline measured a
+          # second time. run.zsh exits 1 when a workload fails functionally,
+          # after writing every report, so that status is accepted here and
+          # the comparison step renders and returns it; usage and dependency
+          # errors (2) still fail this step. The step runs under the errexit
+          # that `shell: bash` inherits, so the status is captured on the
+          # command's own failure branch, which errexit does not act on.
+          status=0
+          zsh candidate/benchmarks/run.zsh \
+            --variant baseline=baseline --variant candidate=candidate --variant control=baseline \
+            --output-dir results || status=$?
+          if [[ "$status" -gt 1 ]]; then exit "$status"; fi
+
+      - name: Compare and publish the summary
+        shell: bash
+        run: |
+          set -euo pipefail
+          status=0
+          zsh candidate/benchmarks/compare.zsh --baseline results/baseline.json --candidate results/candidate.json \
+            --control results/control.json --output benchmark-comparison.json --markdown benchmark-comparison.md || status=$?
+          cat benchmark-comparison.md >> "$GITHUB_STEP_SUMMARY"
+          flagged="$(jq -r '.flagged | join(", ")' benchmark-comparison.json)"
+          if [[ -n "$flagged" ]]; then
+            echo "::notice title=Benchmark flag::Cases above the regression thresholds, for review: ${flagged}"
+          fi
+          # A functional failure means a workload no longer runs; that is a
+          # defect, not a timing question, and it fails the job.
+          exit "$status"
+
+      - name: Upload benchmark evidence
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: benchmark-${{ github.event.pull_request.head.sha || github.sha }}
+          path: |
+            results/
+            benchmark-comparison.json
+            benchmark-comparison.md
+          retention-days: 90
diff --git a/.github/workflows/promotion-readiness.yml b/.github/workflows/promotion-readiness.yml
index a824616d..5e725af1 100644
--- a/.github/workflows/promotion-readiness.yml
+++ b/.github/workflows/promotion-readiness.yml
@@ -23,8 +23,8 @@ jobs:
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
-      - name: Install Zsh and archive tools
-        run: sudo apt-get update && sudo apt-get install -yq zsh zip unzip
+      - name: Install Zsh, jq, and archive tools
+        run: sudo apt-get update && sudo apt-get install -yq zsh jq zip unzip
 
       - name: Check and compile Zsh sources
         shell: bash
@@ -68,9 +68,18 @@ jobs:
         if: ${{ hashFiles('tests/snippet-directory-mirror.zsh') != '' }}
         run: zsh -f tests/snippet-directory-mirror.zsh
 
+      - name: Test release planning
+        run: zsh -f tests/release-plan.zsh
+
+      - name: Test promotion release verification
+        run: zsh -f tests/promotion-release-verification.zsh
+
+      - name: Test idempotent promotion publication
+        run: zsh -f tests/promotion-release-publication.zsh
+
   zd:
     name: ZD integration
-    uses: z-shell/zd/.github/workflows/test-native.yml@01c3477e48c0c31bb7225986bb1bac4270e151ff # z-shell/zd#121
+    uses: z-shell/zd/.github/workflows/test-native.yml@5d160597c909a23f03b7a07ff9d43793a106f3e8 # z-shell/zd#123
     with:
       zi_repo: ${{ github.event.pull_request.head.repo.full_name }}
       zi_ref: ${{ github.event.pull_request.head.sha }}
diff --git a/.github/workflows/release-plan.yml b/.github/workflows/release-plan.yml
new file mode 100644
index 00000000..23c87a17
--- /dev/null
+++ b/.github/workflows/release-plan.yml
@@ -0,0 +1,75 @@
+---
+name: Release Plan
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, reopened, synchronize, ready_for_review]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  plan:
+    name: Release plan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the candidate
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+
+      - name: Install Zsh
+        run: sudo apt-get update && sudo apt-get install -yq zsh
+
+      - name: Compute release plan
+        id: release
+        if: "${{ github.event_name == 'workflow_dispatch' || (github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.head.ref == 'next') }}"
+        env:
+          RELEASE_NOTES_FILE: ${{ runner.temp }}/release-notes.md
+          RELEASE_PLAN_OUTPUT: ${{ runner.temp }}/release-plan.env
+          RELEASE_PLAN_BODY: ${{ runner.temp }}/release-plan.md
+        run: |
+          zsh -f scripts/release-plan.zsh HEAD > "$RELEASE_PLAN_BODY"
+          cat "$RELEASE_PLAN_BODY" >> "$GITHUB_STEP_SUMMARY"
+          cat "$RELEASE_PLAN_OUTPUT" >> "$GITHUB_OUTPUT"
+
+      - name: Record non-promotion result
+        if: "${{ github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.event.pull_request.head.ref != 'next') }}"
+        run: echo 'This pull request is not an internal next-to-main promotion; automatic publication does not apply.' >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Update promotion pull request
+        if: "${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.head.ref == 'next' }}"
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          RELEASE_PLAN_BODY: ${{ runner.temp }}/release-plan.md
+        run: |
+          set -euo pipefail
+          marker='<!-- zi-release-plan -->'
+          body="${RUNNER_TEMP}/release-plan-comment.md"
+          {
+            echo "$marker"
+            cat "$RELEASE_PLAN_BODY"
+            echo
+            echo '_Merging this reviewed promotion authorizes publication after every required workflow succeeds on the exact merge SHA._'
+          } > "$body"
+          comment_id="$(gh api --paginate \
+            "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" \
+            --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | contains(\"${marker}\"))) | .id" | head -n 1)"
+          if [[ -n "$comment_id" ]]; then
+            gh api --method PATCH "repos/${GITHUB_REPOSITORY}/issues/comments/${comment_id}" \
+              -F body=@"$body" >/dev/null
+          else
+            gh api --method POST "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" \
+              -F body=@"$body" >/dev/null
+          fi
diff --git a/.github/workflows/release-prepare.yml b/.github/workflows/release-prepare.yml
deleted file mode 100644
index cd15c777..00000000
--- a/.github/workflows/release-prepare.yml
+++ /dev/null
@@ -1,21 +0,0 @@
----
-name: Release Prepare
-
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: read
-  issues: write
-  models: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  propose:
-    uses: z-shell/.github/.github/workflows/release-prepare.yml@6f3d88335ca0ae77b795ec2883b4402b51f15c6a # main
-    with:
-      signed_tag: true
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b4ca3044..4e34b01c 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -4,20 +4,24 @@ name: Release
 on:
   push:
     tags: ["v*.*.*"]
+  workflow_run:
+    workflows: [Zsh, ZD Integration, CodeQL, Trunk Code Quality]
+    types: [completed]
 
-permissions:
-  actions: read
-  contents: write
+permissions: {}
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: release-${{ github.event.workflow_run.head_sha || github.ref_name }}
   cancel-in-progress: false
 
 jobs:
-  publish:
-    name: Verify and publish
-    if: github.repository == 'z-shell/zi'
+  manual:
+    name: Verify and publish recovery tag
+    if: github.event_name == 'push' && github.repository == 'z-shell/zi'
     runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: write
     steps:
       - name: Check out the tagged commit
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -49,3 +53,55 @@ jobs:
             --title "Zi $TAG" \
             --generate-notes \
             --latest
+
+  automatic:
+    name: Publish reviewed promotion
+    if: "${{ github.event_name == 'workflow_run' && github.repository == 'z-shell/zi' && github.event.workflow_run.head_branch == 'main' }}"
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: write
+      pull-requests: read
+    steps:
+      - name: Check out the trusted main branch
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: refs/heads/main
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Install Zsh
+        run: sudo apt-get update && sudo apt-get install -yq zsh
+
+      - name: Verify promotion and exact-SHA validation
+        id: verify
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PROMOTION_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: zsh -f scripts/verify-promotion-release.zsh
+
+      - name: Compute the authorized release plan
+        id: plan
+        if: steps.verify.outputs.ready == 'true'
+        env:
+          RELEASE_NOTES_FILE: ${{ runner.temp }}/release-notes.md
+          RELEASE_TARGET: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          RELEASE_PLAN_OUTPUT="$GITHUB_OUTPUT" \
+            zsh -f scripts/release-plan.zsh \
+              "$RELEASE_TARGET" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Record no-op promotion
+        if: steps.verify.outputs.ready == 'true' && steps.plan.outputs.release != 'true'
+        run: echo 'The reviewed promotion contains no releasable Conventional Commits; no tag or release was created.' >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Create annotated tag and release
+        if: steps.verify.outputs.ready == 'true' && steps.plan.outputs.release == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_NOTES_FILE: ${{ runner.temp }}/release-notes.md
+          RELEASE_TAG: ${{ steps.plan.outputs.tag }}
+          RELEASE_TARGET: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          zsh -f scripts/publish-promotion-release.zsh >> "$GITHUB_STEP_SUMMARY"
+          echo "Authorized by reviewed promotion #${{ steps.verify.outputs.promotion_pr }}." >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/zd-integration.yml b/.github/workflows/zd-integration.yml
index 0b9f6d72..ddcf725f 100644
--- a/.github/workflows/zd-integration.yml
+++ b/.github/workflows/zd-integration.yml
@@ -4,10 +4,6 @@ name: ZD Integration
 on:
   push:
     branches: [main, next]
-    paths:
-      - ".github/workflows/zd-integration.yml"
-      - "zi.zsh"
-      - "lib/**"
   pull_request:
     paths:
       - ".github/workflows/zd-integration.yml"
@@ -24,7 +20,7 @@ permissions:
 
 jobs:
   zd-test:
-    uses: z-shell/zd/.github/workflows/test-native.yml@01c3477e48c0c31bb7225986bb1bac4270e151ff # z-shell/zd#121
+    uses: z-shell/zd/.github/workflows/test-native.yml@5d160597c909a23f03b7a07ff9d43793a106f3e8 # z-shell/zd#123
     with:
       zi_repo: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
       zi_ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
diff --git a/.github/workflows/zsh-n.yml b/.github/workflows/zsh-n.yml
index d21eaa1f..63c3294e 100644
--- a/.github/workflows/zsh-n.yml
+++ b/.github/workflows/zsh-n.yml
@@ -6,58 +6,21 @@ on:
     branches:
       - main
       - next
-    paths:
-      - "zi.zsh"
-      - "lib/**"
-      - "contracts/package-manifest-v1.json"
-      - "scripts/validate-package-manifest.py"
-      - "tests/**"
-      - ".github/workflows/*.yml"
-      - "tests/annex-unregister.zsh"
-      - "tests/atinit-deferred-marker.zsh"
-      - "tests/ci-registration.zsh"
-      - "tests/archive-extraction.zsh"
-      - "tests/completion-refresh.zsh"
-      - "tests/disk-ice-resolution.zsh"
-      - "tests/home-preparation.zsh"
-      - "tests/hook-ownership.zsh"
-      - "tests/ice-tokenizer.zsh"
-      - "tests/load-object-status.zsh"
-      - "tests/message-formatting.zsh"
-      - "tests/package-manifest-contract.zsh"
-      - "tests/package-manifest-fixtures.zsh"
-      - "tests/fixtures/package-manifests/**"
-      - "scripts/refresh-package-manifests.zsh"
-      - "tests/package-manifest-parsing.zsh"
-      - "tests/path-resolution.zsh"
-      - "tests/parallel-update.zsh"
-      - "tests/plugin-autoload-fpath-scope.zsh"
-      - "tests/plugin-autoload-ice.zsh"
-      - "tests/nested-load-state.zsh"
-      - "tests/pack-service-first-install.zsh"
-      - "tests/plugin-autoload-ownership.zsh"
-      - "tests/plugin-standard-callbacks.zsh"
-      - "tests/release-tag-verification.zsh"
-      - "tests/scheduler-idle.zsh"
-      - "tests/fixtures/plugin-standard-callbacks/**"
-      - "tests/self-update-reload.zsh"
-      - "tests/snippet-directory-mirror.zsh"
-      - "tests/snippet-update-status.zsh"
-      - "tests/source-hygiene.zsh"
-      - "tests/subst-nesting.zsh"
-      - "tests/unload-hook-dispatch.zsh"
-      - "tests/unload-ownership-contracts.zsh"
-      - "tests/version-reporting.zsh"
   pull_request:
     paths:
       - "zi.zsh"
       - "lib/**"
       - "contracts/package-manifest-v1.json"
       - "scripts/validate-package-manifest.py"
+      - "scripts/release-plan.zsh"
+      - "scripts/verify-promotion-release.zsh"
+      - "scripts/publish-promotion-release.zsh"
       - "tests/**"
       - ".github/workflows/*.yml"
       - "tests/annex-unregister.zsh"
       - "tests/atinit-deferred-marker.zsh"
+      - "tests/benchmark-harness.zsh"
+      - "benchmarks/**"
       - "tests/ci-registration.zsh"
       - "tests/archive-extraction.zsh"
       - "tests/completion-refresh.zsh"
@@ -204,6 +167,50 @@ jobs:
       - name: Test release tag verification
         run: zsh -f tests/release-tag-verification.zsh
 
+  release-plan:
+    name: Release Plan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install Zsh
+        run: sudo apt update && sudo apt-get install -yq zsh
+      - name: Test release planning
+        run: zsh -f tests/release-plan.zsh
+
+  promotion-release-verification:
+    name: Promotion Release Verification
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install Zsh and jq
+        run: sudo apt update && sudo apt-get install -yq zsh jq
+      - name: Test promotion release verification
+        run: zsh -f tests/promotion-release-verification.zsh
+
+  promotion-release-publication:
+    name: Promotion Release Publication
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install Zsh
+        run: sudo apt update && sudo apt-get install -yq zsh
+      - name: Test idempotent promotion publication
+        run: zsh -f tests/promotion-release-publication.zsh
+
+  benchmark-harness:
+    name: Benchmark Harness
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install Zsh and jq
+        run: sudo apt update && sudo apt-get install -yq zsh jq
+      - name: Test the benchmark runner and comparer
+        run: zsh -f tests/benchmark-harness.zsh
+
   version-reporting:
     name: Version reporting
     runs-on: ubuntu-latest
diff --git a/AGENTS.md b/AGENTS.md
index 5f78ff70..6f94dfd1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,6 +14,7 @@ Zi is the canonical Zsh plugin manager for the organization. Changes can affect
 - A successful promotion needs no routine back-merge. Merge a `main` hotfix forward into `next` before ordinary development continues.
 - `hotfix-*` branches may target `main` directly.
 - Keep `delete_branch_on_merge` disabled because `next` is persistent.
+- A pull request merged into `next` leaves its issue open: GitHub closes issues only from the default branch. Link the issue for the Development sidebar (a closing keyword, or `addCloseIssueReferences` when the link is missing) and close the accumulated issues by hand when `next` is promoted to `main`; do not close them early.
 
 ## Before merging
 
diff --git a/benchmarks/README.md b/benchmarks/README.md
new file mode 100644
index 00000000..744d13c0
--- /dev/null
+++ b/benchmarks/README.md
@@ -0,0 +1,40 @@
+# Zi benchmarks
+
+Deterministic, network-free measurements of the paths a user pays for on every shell start: sourcing `zi.zsh`, loading plugins, queueing turbo tasks, parsing ices, reading package manifests, and unloading. The suite exists to make a performance change visible in the pull request that causes it (#553); it does not gate merges (ADR-0009: coverage and performance are observed, not gated).
+
+## Cases
+
+| Case | Measured region |
+| --- | --- |
+| `source-fresh-home` | `source zi.zsh` in a home no sample has used before (directories are created, nothing is cached) |
+| `source-reused-home` | `source zi.zsh` in the variant's home kept from the previous sample (prepared directories and completion state persist) |
+| `light-load-10` | `zi light` of ten fixture plugins |
+| `load-10` | `zi load` (tracked) of ten fixture plugins |
+| `turbo-10` | ten `wait'0'` tasks queued, then `@zi-scheduler burst` |
+| `ice-200` | 200 `zi ice` calls carrying 13 ices each |
+| `manifest-21` | the 21 vendored package manifests through `.zi-read-package-manifest` |
+| `unload-10` | `zi unload` of ten tracked plugins |
+
+Each sample starts a fresh `zsh -f` with an isolated home and reports floating-point `SECONDS` elapsed milliseconds of the measured region only; the timer needs no module, so the source cases include the `zsh/datetime` load that `zi.zsh` performs. All variants of one invocation are measured together: within a round they run in a rotating order, and alternate rotation cycles run reversed, so every variant takes every position equally often and runner drift is not correlated with a variant; cases rotate the same way across rounds. Zi does not compile itself on source, so the two source cases differ by persisted home state, not by bytecode. Every run also records health data that costs nothing extra: function and parameter counts after source and after loading, `.zwc` presence, `zsh -n` and `zcompile` durations, and the line counts of the hot files.
+
+## Run it
+
+```sh
+zsh benchmarks/run.zsh --variant baseline=../zi-at-main --variant candidate=. \
+  --variant control=../zi-at-main --output-dir results
+zsh benchmarks/compare.zsh --baseline results/baseline.json --candidate results/candidate.json \
+  --control results/control.json --output comparison.json --markdown comparison.md
+```
+
+Defaults are 5 warmups and 30 samples; `--case NAME` selects a subset, and `source-reused-home` needs at least one warmup so that its first measured sample times a home a previous sample has sourced. `run.zsh` writes one JSON report per variant and exits 1, after writing every report, when a workload fails functionally. `compare.zsh` reports median, p95, min and the sample count per variant, the median and p95 deltas, and an A/A control column from the second baseline measurement so the noise floor is visible next to the real comparison; a control measured under other settings (Zsh version, architecture, sample or warmup count) is rejected. A failed sample records the child's last diagnostic line, or what its exit status means when it wrote nothing. A case whose median regresses over 10% or whose p95 regresses over 15% is flagged for review; flags never fail, and they are null when the two reports are not comparable (different Zsh version, architecture, sample or warmup count). A functional failure on either side invalidates that case and exits 1, because timing a broken behaviour is meaningless. A case a checkout cannot run because it predates the API the case exercises is a different thing: `case.zsh` exits 6, `run.zsh` records the case as `unsupported` for that variant with the reason and still exits 0, and `compare.zsh` renders the row without a delta. A baseline without the API (or both sides without it) is unsupported, not failed, and does not exit 1; a candidate without an API its baseline has is recorded as a failure, because that is a removal. The manifest case is named for its inventory: `run.zsh` pins the 21 repository names and requires `tests/fixtures/package-manifests/repositories.txt` to list exactly them with a snapshot each, and each sample re-asserts the count; replacing one repository with another is rejected even though the count is unchanged. A changed inventory is a different workload and needs a renamed or versioned case and an updated pinned list, not a drifting number or a silently swapped set. Snapshot contents are not pinned, so refreshing a vendored manifest verbatim keeps the inventory.
+
+## Read results carefully
+
+- Hosted runners differ in hardware and load. Compare only within one run, and only when `comparable` is true (same Zsh version, architecture, and sample count).
+- The fixture plugins are tiny; the cases isolate Zi's own overhead, not a real configuration's plugin bodies.
+- `source-reused-home` is the everyday startup cost; `source-fresh-home` adds the first-run directory preparation.
+- `tests/benchmark-harness.zsh` proves the runner and comparer: shape, A/A, a synthetic 30% regression flagged, a functional failure invalidated, a control-only failure rendered, a repeated `--case` rejected, a checkout without the manifest reader reported unsupported (and a candidate that lost it reported as a failure), a failed postcondition recorded with a one-line reason, a swapped manifest inventory rejected, a pattern given as `--case` rejected as a usage error, a pipe inside a reason kept in one cell, a failed health probe recorded as null counts beside the measured cases, an incompatible control rejected, an integral sample recorded as a number, and six cells in every table row.
+
+## Where it runs
+
+`.github/workflows/benchmark.yml` compares every pull request into `next` with its base and the promotion pull request into `main` with `main`, writes the table to the job summary, and keeps the JSON and Markdown as an artifact for 90 days. Per-release results are committed by a maintainer under `benchmarks/results/<tag>-<os>-<arch>/` (zpmod's naming) after a release, never by automation.
diff --git a/benchmarks/case.zsh b/benchmarks/case.zsh
new file mode 100644
index 00000000..babc78a4
--- /dev/null
+++ b/benchmarks/case.zsh
@@ -0,0 +1,99 @@
+#!/usr/bin/env zsh
+# -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
+# vim: ft=zsh sw=2 ts=2 et
+#
+# case.zsh -- one benchmark sample, run by run.zsh in a fresh `zsh -f`.
+# Reads BENCH_CHECKOUT, BENCH_FIXTURES, BENCH_MANIFESTS and BENCH_CASE from the
+# environment and prints the elapsed milliseconds of the measured region.
+# The measured region excludes process start and setup, which is why every
+# case sets up in the same process it measures in. The timer is floating-point
+# SECONDS, which needs no module: zi.zsh loads zsh/datetime when sourced, so a
+# timer built on that module would pay for the load before the source cases
+# start measuring.
+#
+# Exit 6 means the checkout lacks the API the case exercises; run.zsh records
+# that as unsupported for the variant, not as a failure. Every other non-zero
+# status is a failure of the workload.
+
+emulate -R zsh
+setopt extended_glob
+
+typeset -gAH ZI
+ZI[BIN_DIR]=$BENCH_CHECKOUT
+typeset -F 6 SECONDS
+typeset -F6 t0 t1
+zle() { return 1; }
+start() { t0=$SECONDS; }
+mark()  { t1=$SECONDS; }
+# Always three decimals: arithmetic substitution prints an integral float as
+# "250." with no digits after the point, which run.zsh rejects as a sample and
+# which is not a JSON number.
+elapsed() { printf '%.3f\n' $(( (t1 - t0) * 1000 )); }
+stop()  { mark; elapsed; }
+load_zi() { builtin source "$BENCH_CHECKOUT/zi.zsh" || exit 3; .zi-prepare-home || exit 3; }
+plugins() { local i; for i in {1..10}; do print -r -- "$BENCH_FIXTURES/plugins/p$i"; done; }
+# Every fixture plugin defines a function, an alias, and a global parameter.
+# All thirty artifacts prove that every plugin ran, and that an unload
+# removed every kind of state it owns; checking one kind, or only the last
+# plugin, would accept a partial workload or a partial cleanup.
+all_loaded() {
+  local i
+  for i in {1..10}; do
+    (( $+functions[p${i}_fn] && $+aliases[p${i}_alias] && $+parameters[P${i}_PARAM] )) || return 1
+  done
+  return 0
+}
+none_loaded() {
+  local i
+  for i in {1..10}; do
+    (( $+functions[p${i}_fn] || $+aliases[p${i}_alias] || $+parameters[P${i}_PARAM] )) && return 1
+  done
+  return 0
+}
+
+case $BENCH_CASE in
+  source-fresh-home|source-reused-home)
+    # Zi does not compile itself on source; the difference between these two
+    # is the persisted home state (prepared directories, completion dump)
+    # that the reused home carries over from the previous sample.
+    # zi.zsh does not propagate a failed .zi-prepare-home, so a successful
+    # source can leave the home unprepared; only a ready home is timed.
+    start; builtin source "$BENCH_CHECKOUT/zi.zsh" || exit 3; mark
+    [[ -n ${ZI[HOME_READY]} ]] || exit 4
+    elapsed ;;
+  light-load-10)
+    load_zi; start; for p in $(plugins); do zi light %"$p" || exit 3; done; stop
+    all_loaded || exit 4 ;;
+  load-10)
+    load_zi; start; for p in $(plugins); do zi load %"$p" || exit 3; done; stop
+    all_loaded || exit 4 ;;
+  turbo-10)
+    load_zi; start; for p in $(plugins); do zi wait'0' lucid for %"$p" || exit 3; done; @zi-scheduler burst || exit 3; stop
+    all_loaded || exit 4 ;;
+  ice-200)
+    load_zi; start; for i in {1..200}; do zi ice wait'1' lucid depth'1' atinit'true' atload'true' pick'x' as'program' from'gh-r' mv'a -> b' id-as'x' compile'y' nocompile blockf || exit 3; done; stop ;;
+  manifest-21)
+    load_zi; builtin source "$BENCH_CHECKOUT/lib/zsh/install.zsh" || exit 3
+    # A checkout that predates the manifest reader cannot run this workload.
+    # That is a capability of the checkout, not a defect in it: exit 6 tells
+    # run.zsh to record the case as unsupported for this variant instead of
+    # failed, and compare.zsh decides whether the asymmetry matters.
+    (( $+functions[.zi-read-package-manifest] )) || { print -u2 -r -- "checkout does not define .zi-read-package-manifest"; exit 6 }
+    local -a files; files=( $BENCH_MANIFESTS/*.json(N) )
+    # Exactly the declared inventory, or the timing is not comparable (#555).
+    (( $#files == ${BENCH_MANIFEST_COUNT:-0} )) || exit 5
+    start; for f in $files; do local -A info ices; local -a names; .zi-read-package-manifest "$(<$f)" default info names ices || exit 4; unset info ices names; done; stop ;;
+  unload-10)
+    load_zi; for p in $(plugins); do zi load %"$p" || exit 3; done
+    all_loaded || exit 4
+    start; for p in $(plugins); do zi unload %"$p" -q || exit 3; done; stop
+    none_loaded || exit 4 ;;
+  symbols)
+    # Same setup as a measured case: a failed home preparation exits 3, so
+    # run.zsh records null counts instead of counts from a half-prepared home.
+    load_zi
+    integer f1=$#functions p1=$#parameters
+    for p in $(plugins); do zi load %"$p" || exit 3; done
+    print -r -- "$f1 $p1 $#functions $#parameters" ;;
+  *) exit 2 ;;
+esac
diff --git a/benchmarks/compare.zsh b/benchmarks/compare.zsh
new file mode 100644
index 00000000..7a880628
--- /dev/null
+++ b/benchmarks/compare.zsh
@@ -0,0 +1,136 @@
+#!/usr/bin/env zsh
+# -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
+# vim: ft=zsh sw=2 ts=2 et
+#
+# compare.zsh -- join two run.zsh reports into a baseline-versus-candidate
+# report, flag regressions above the thresholds, and render Markdown.
+#
+# Timing never fails the comparison: a flag marks a case for review, which is
+# the organization's stance for hosted-runner evidence (observed, not gated).
+# A functional failure on either side does invalidate that case.
+#
+# A case a checkout cannot run because it lacks the API the case exercises is
+# reported by run.zsh as unsupported for that variant. A baseline without the
+# API is expected when the candidate adds it, so that row is unsupported, not
+# failed, and does not exit 1. A candidate without an API the baseline has is
+# a removal, and that row is a failure.
+#
+# Usage:
+#   zsh benchmarks/compare.zsh --baseline FILE --candidate FILE --output FILE
+#                              [--markdown FILE] [--control FILE]
+#                              [--median-threshold PERCENT] [--p95-threshold PERCENT]
+#
+# --control is a second run of the baseline (an A/A sample) whose deltas show
+# the noise floor next to the real comparison.
+#
+# Exit codes:
+#   0  comparison written (flags, if any, are in the report)
+#   1  a case failed functionally on either side
+#   2  usage or dependency error
+
+emulate -LR zsh
+setopt extended_glob pipe_fail no_unset
+
+typeset baseline='' candidate='' control='' output='' markdown=''
+typeset -F1 median_threshold=10 p95_threshold=15
+die() { print -u2 -r -- "compare.zsh: $1"; exit ${2:-2}; }
+while (( $# )); do
+  case "$1" in
+    --baseline)  [[ -n ${2-} ]] || die "--baseline needs a value"; baseline=$2; shift 2 ;;
+    --candidate) [[ -n ${2-} ]] || die "--candidate needs a value"; candidate=$2; shift 2 ;;
+    --control)   [[ -n ${2-} ]] || die "--control needs a value"; control=$2; shift 2 ;;
+    --output)    [[ -n ${2-} ]] || die "--output needs a value"; output=$2; shift 2 ;;
+    --markdown)  [[ -n ${2-} ]] || die "--markdown needs a value"; markdown=$2; shift 2 ;;
+    --median-threshold) [[ ${2-} == <->(.<->|) ]] || die "--median-threshold needs a number"; median_threshold=$2; shift 2 ;;
+    --p95-threshold)    [[ ${2-} == <->(.<->|) ]] || die "--p95-threshold needs a number"; p95_threshold=$2; shift 2 ;;
+    --help|-h) print -r -- "usage: ${0:t} --baseline FILE --candidate FILE --output FILE [--markdown FILE] [--control FILE]"; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+[[ -r $baseline && -r $candidate && -n $output ]] || die "--baseline, --candidate and --output are required"
+(( $+commands[jq] )) || die "required command not found: jq"
+
+# The three reports must describe the same case set, or a missing case would
+# be silently dropped (candidate-only) or fail deep inside jq (baseline-only).
+typeset -a case_sets
+case_sets=( "$(jq -c '.cases | keys' "$baseline")" "$(jq -c '.cases | keys' "$candidate")" )
+[[ -n $control ]] && case_sets+=( "$(jq -c '.cases | keys' "$control")" )
+[[ ${#${(u)case_sets}} -eq 1 ]] || die "the reports do not cover the same cases: ${(j: versus :)case_sets}"
+
+# The control is the baseline measured again, so it must come from the same
+# source revision and the same settings; the control rows reuse the
+# baseline-versus-candidate comparability and would otherwise show another
+# revision, or an incompatible run, as the noise floor.
+if [[ -n $control ]]; then
+  typeset baseline_identity control_identity
+  baseline_identity=$(jq -c '[.source_revision, .environment.zsh_version, .environment.architecture, .workload.samples, .workload.warmups]' "$baseline")
+  control_identity=$(jq -c '[.source_revision, .environment.zsh_version, .environment.architecture, .workload.samples, .workload.warmups]' "$control")
+  [[ $baseline_identity == "$control_identity" ]] || die "the control is not a second run of the baseline (source revision, Zsh version, architecture, samples, warmups): ${baseline_identity} versus ${control_identity}"
+fi
+
+# jq does the arithmetic so the report is one deterministic document.
+typeset -a control_args
+[[ -n $control ]] && control_args=( --slurpfile control "$control" ) || control_args=( --argjson control '[null]' )
+jq -n --slurpfile b "$baseline" --slurpfile c "$candidate" "${control_args[@]}" \
+   --argjson mt "$median_threshold" --argjson pt "$p95_threshold" '
+  def pct(a; b): if a == null or b == null or b == 0 then null else ((a - b) * 100 / b) end;
+  ($b[0]) as $B | ($c[0]) as $C | ($control[0]) as $K |
+  ($B.environment.zsh_version == $C.environment.zsh_version
+   and $B.environment.architecture == $C.environment.architecture
+   and $B.workload.samples == $C.workload.samples
+   and $B.workload.warmups == $C.workload.warmups) as $comparable |
+  # Flags are meaningful only between comparable reports; otherwise every
+  # flag is null and the summary says why.
+  def row(base; cand):
+    # A baseline that lacks the API is unsupported (with or without the
+    # candidate); a candidate that lacks an API the baseline runs is a removal
+    # and therefore a failure. A candidate failure always stays a failure.
+    if (base.unsupported? // null) != null and (cand.failure? // null) == null then
+      {unsupported: {baseline: base.unsupported, candidate: (cand.unsupported? // null)}}
+    elif (cand.unsupported? // null) != null then
+      {failure: {baseline: (base.failure? // null), candidate: ("removed: " + cand.unsupported)}}
+    elif (base.failure? // null) != null or (cand.failure? // null) != null then
+      {failure: {baseline: (base.failure? // null), candidate: (cand.failure? // null)}}
+    else
+      {results: {baseline: base, candidate: cand},
+       change: {median_delta_ms: (cand.median - base.median), median_delta_percent: pct(cand.median; base.median),
+                p95_delta_ms: (cand.p95 - base.p95), p95_delta_percent: pct(cand.p95; base.p95)}}
+      | .flag = (if $comparable then ((.change.median_delta_percent > $mt) or (.change.p95_delta_percent > $pt)) else null end)
+    end;
+  {schema_version: 1,
+   captured_at: (now | todate),
+   thresholds: {median_percent: $mt, p95_percent: $pt, policy: "flag for review, never fail on timing; flags are null when the reports are not comparable"},
+   baseline: {label: $B.label, source_revision: $B.source_revision, environment: $B.environment, workload: $B.workload},
+   candidate: {label: $C.label, source_revision: $C.source_revision, environment: $C.environment, workload: $C.workload},
+   comparable: $comparable,
+   health: {baseline: $B.health, candidate: $C.health},
+   cases: ($B.cases | keys | map(. as $k | {($k): row($B.cases[$k]; $C.cases[$k])}) | add),
+   control: (if $K == null then null else ($B.cases | keys | map(. as $k | {($k): row($B.cases[$k]; $K.cases[$k])}) | add) end)}
+  | .flagged = [.cases | to_entries[] | select(.value.flag == true) | .key]
+  | .unsupported = [.cases | to_entries[] | select(.value.unsupported != null) | .key]
+  | .failed = ([.cases | to_entries[] | select(.value.failure != null) | .key]
+               + (if .control == null then [] else [.control | to_entries[] | select(.value.failure != null) | .key] end) | unique)
+' > "$output" || die "could not build the comparison" 1
+jq -e . "$output" >/dev/null || die "comparison is not valid JSON" 1
+
+if [[ -n $markdown ]]; then
+  {
+    print -r -- "## Zi benchmark: candidate versus baseline"
+    print
+    print -r -- "Baseline \`$(jq -r .baseline.source_revision "$output" | cut -c1-7)\` ($(jq -r .baseline.label "$output")) versus candidate \`$(jq -r .candidate.source_revision "$output" | cut -c1-7)\` ($(jq -r .candidate.label "$output")); $(jq -r .baseline.workload.samples "$output") samples after $(jq -r .baseline.workload.warmups "$output") warmups; $(jq -r .candidate.environment.zsh_version "$output") on $(jq -r .candidate.environment.cpu "$output"). Comparable: $(jq -r .comparable "$output"). Flags mark a median regression over $(jq -r .thresholds.median_percent "$output")% or a p95 regression over $(jq -r .thresholds.p95_percent "$output")%; they never fail the job.$( [[ $(jq -r .comparable "$output") == true ]] || print -n " The reports are not comparable (Zsh version, architecture, sample or warmup counts differ), so no case is flagged." )"
+    print
+    print -r -- "| Case | Baseline median / p95 ms | Candidate median / p95 ms | Median delta | p95 delta | A/A control median delta |"
+    print -r -- "| --- | --- | --- | --- | --- | --- |"
+    # A reason is child output and may contain a pipe; escaped, it stays in
+    # its own cell instead of splitting the row.
+    jq -r 'def cell: tojson | gsub("\\|"; "\\|"); .cases | to_entries[] | . as $e | if .value.failure then "| \(.key) | failure | failure | \(.value.failure | cell) | | " elif .value.unsupported then "| \(.key) | unsupported | \(if .value.unsupported.candidate != null then "unsupported" else "not compared" end) | \(.value.unsupported.baseline | cell) | | " else "| \(.key)\(if .value.flag then " (flag)" else "" end) | \(.value.results.baseline.median) / \(.value.results.baseline.p95) | \(.value.results.candidate.median) / \(.value.results.candidate.p95) | \(.value.change.median_delta_percent | . * 10 | round / 10)% | \(.value.change.p95_delta_percent | . * 10 | round / 10)% | " end' "$output" | while IFS= read -r line; do
+      case_name=${${line#| }%% *}
+      ctrl=$(jq -r --arg k "$case_name" '.control[$k] | if . == null then "n/a" elif .failure != null then "failure: \(.failure.candidate // .failure.baseline | gsub("\\|"; "\\|"))" elif .unsupported != null then "unsupported" elif (.change.median_delta_percent | type) == "number" then (.change.median_delta_percent * 10 | round / 10 | tostring) + "%" else "n/a" end' "$output")
+      print -r -- "${line}${ctrl} |"
+    done
+    print
+    print -r -- "Health (baseline to candidate): functions after source $(jq -r .health.baseline.functions_after_source "$output") to $(jq -r .health.candidate.functions_after_source "$output"), parameters $(jq -r .health.baseline.parameters_after_source "$output") to $(jq -r .health.candidate.parameters_after_source "$output"), zi.zsh $(jq -r '.health.baseline["lines:zi.zsh"]' "$output") to $(jq -r '.health.candidate["lines:zi.zsh"]' "$output") lines, zcompile $(jq -r '.health.baseline["zcompile_ms:zi.zsh"] | . * 10 | round / 10' "$output") to $(jq -r '.health.candidate["zcompile_ms:zi.zsh"] | . * 10 | round / 10' "$output") ms."
+  } > "$markdown"
+fi
+print -r -- "wrote $output: $(jq -r '.flagged | length' "$output") flagged, $(jq -r '.failed | length' "$output") failed, $(jq -r '.unsupported | length' "$output") unsupported"
+(( $(jq -r '.failed | length' "$output") == 0 ))
diff --git a/benchmarks/fixtures/plugins/p1/p1.plugin.zsh b/benchmarks/fixtures/plugins/p1/p1.plugin.zsh
new file mode 100644
index 00000000..297cd16b
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p1/p1.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 1: one function, one alias, one parameter.
+p1_fn() { :; }
+alias p1_alias=true
+typeset -g P1_PARAM=1
diff --git a/benchmarks/fixtures/plugins/p10/p10.plugin.zsh b/benchmarks/fixtures/plugins/p10/p10.plugin.zsh
new file mode 100644
index 00000000..cb6adb7a
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p10/p10.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 10: one function, one alias, one parameter.
+p10_fn() { :; }
+alias p10_alias=true
+typeset -g P10_PARAM=1
diff --git a/benchmarks/fixtures/plugins/p2/p2.plugin.zsh b/benchmarks/fixtures/plugins/p2/p2.plugin.zsh
new file mode 100644
index 00000000..5910c48e
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p2/p2.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 2: one function, one alias, one parameter.
+p2_fn() { :; }
+alias p2_alias=true
+typeset -g P2_PARAM=1
diff --git a/benchmarks/fixtures/plugins/p3/p3.plugin.zsh b/benchmarks/fixtures/plugins/p3/p3.plugin.zsh
new file mode 100644
index 00000000..a5d90912
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p3/p3.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 3: one function, one alias, one parameter.
+p3_fn() { :; }
+alias p3_alias=true
+typeset -g P3_PARAM=1
diff --git a/benchmarks/fixtures/plugins/p4/p4.plugin.zsh b/benchmarks/fixtures/plugins/p4/p4.plugin.zsh
new file mode 100644
index 00000000..beb76c68
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p4/p4.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 4: one function, one alias, one parameter.
+p4_fn() { :; }
+alias p4_alias=true
+typeset -g P4_PARAM=1
diff --git a/benchmarks/fixtures/plugins/p5/p5.plugin.zsh b/benchmarks/fixtures/plugins/p5/p5.plugin.zsh
new file mode 100644
index 00000000..952d4b61
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p5/p5.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 5: one function, one alias, one parameter.
+p5_fn() { :; }
+alias p5_alias=true
+typeset -g P5_PARAM=1
diff --git a/benchmarks/fixtures/plugins/p6/p6.plugin.zsh b/benchmarks/fixtures/plugins/p6/p6.plugin.zsh
new file mode 100644
index 00000000..55207e5f
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p6/p6.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 6: one function, one alias, one parameter.
+p6_fn() { :; }
+alias p6_alias=true
+typeset -g P6_PARAM=1
diff --git a/benchmarks/fixtures/plugins/p7/p7.plugin.zsh b/benchmarks/fixtures/plugins/p7/p7.plugin.zsh
new file mode 100644
index 00000000..abf514ca
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p7/p7.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 7: one function, one alias, one parameter.
+p7_fn() { :; }
+alias p7_alias=true
+typeset -g P7_PARAM=1
diff --git a/benchmarks/fixtures/plugins/p8/p8.plugin.zsh b/benchmarks/fixtures/plugins/p8/p8.plugin.zsh
new file mode 100644
index 00000000..c9fe76a7
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p8/p8.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 8: one function, one alias, one parameter.
+p8_fn() { :; }
+alias p8_alias=true
+typeset -g P8_PARAM=1
diff --git a/benchmarks/fixtures/plugins/p9/p9.plugin.zsh b/benchmarks/fixtures/plugins/p9/p9.plugin.zsh
new file mode 100644
index 00000000..a4a232d0
--- /dev/null
+++ b/benchmarks/fixtures/plugins/p9/p9.plugin.zsh
@@ -0,0 +1,4 @@
+# Deterministic benchmark fixture plugin 9: one function, one alias, one parameter.
+p9_fn() { :; }
+alias p9_alias=true
+typeset -g P9_PARAM=1
diff --git a/benchmarks/run.zsh b/benchmarks/run.zsh
new file mode 100644
index 00000000..696cd0df
--- /dev/null
+++ b/benchmarks/run.zsh
@@ -0,0 +1,297 @@
+#!/usr/bin/env zsh
+# -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
+# vim: ft=zsh sw=2 ts=2 et
+#
+# run.zsh -- measure Zi checkouts on deterministic, network-free workloads.
+#
+# Every sample starts a fresh `zsh -f` with an isolated home, so nothing leaks
+# between samples or variants. Several variants (for example baseline,
+# candidate, and a second baseline as the A/A control) are measured in the
+# same invocation: within a round the variants run in a rotating order, with
+# alternate rotation cycles reversed, so every variant takes every position
+# equally often and runner load, cache, and thermal drift are not correlated
+# with a variant. Cases rotate the same way across rounds. Output is one JSON
+# document per variant; compare.zsh joins two of them.
+#
+# Usage:
+#   zsh benchmarks/run.zsh --variant LABEL=DIR [--variant LABEL=DIR]... --output-dir DIR
+#                          [--warmups N] [--samples N] [--case NAME]...
+#
+# Requires: zsh with zsh/datetime, jq.
+#
+# Exit codes:
+#   0  every case produced the requested samples, or a variant reported a case
+#      unsupported because its checkout lacks the API the case exercises (the
+#      report records that per case; compare.zsh decides whether it matters)
+#   1  a case failed functionally (its samples are discarded and the report
+#      records the failure; timing of a broken behaviour is meaningless)
+#   2  usage or dependency error
+
+emulate -LR zsh
+setopt extended_glob pipe_fail no_unset
+
+typeset output_dir=''
+integer warmups=5 samples=30
+typeset -a wanted labels
+typeset -A dirs
+typeset -a all_cases
+all_cases=( source-fresh-home source-reused-home light-load-10 load-10 turbo-10 ice-200 manifest-21 unload-10 )
+
+usage() { print -r -- "usage: ${0:t} --variant LABEL=DIR [--variant LABEL=DIR]... --output-dir DIR [--warmups N] [--samples N] [--case NAME]..."; }
+die() { print -u2 -r -- "run.zsh: $1"; exit ${2:-2}; }
+
+while (( $# )); do
+  case "$1" in
+    --variant)
+      [[ ${2-} == ?*=?* ]] || die "--variant needs LABEL=DIR"
+      [[ ${2%%=*} == [[:alnum:]_-]## ]] || die "variant label must be alphanumeric: ${2%%=*}"
+      (( ${+dirs[${2%%=*}]} )) && die "duplicate variant label: ${2%%=*}"
+      labels+=( "${2%%=*}" ); dirs[${2%%=*}]=${${2#*=}:A}; shift 2 ;;
+    --output-dir) [[ -n ${2-} ]] || die "--output-dir needs a value"; output_dir=$2; shift 2 ;;
+    --warmups)  [[ ${2-} == <-> ]] || die "--warmups needs an integer"; warmups=$2; shift 2 ;;
+    --samples)  [[ ${2-} == <-> && ${2-} -ge 2 ]] || die "--samples needs an integer of at least 2"; samples=$2; shift 2 ;;
+    --case)     [[ -n ${2-} ]] || die "--case needs a value"; wanted+=( "$2" ); shift 2 ;;
+    --help|-h)  usage; exit 0 ;;
+    *) usage >&2; die "unknown argument: $1" ;;
+  esac
+done
+(( $#labels )) || die "at least one --variant LABEL=DIR is required"
+typeset label
+for label in "${labels[@]}"; do [[ -r ${dirs[$label]}/zi.zsh ]] || die "variant ${label}: no zi.zsh under ${dirs[$label]}"; done
+[[ -n $output_dir ]] || die "--output-dir is required"
+command mkdir -p -- "$output_dir" || die "could not create $output_dir"
+(( $+commands[jq] )) || die "required command not found: jq"
+zmodload zsh/datetime || die "zsh/datetime is required"
+
+typeset -a cases
+if (( $#wanted )); then
+  # (Ie) matches the requested name literally: a pattern such as source-*
+  # is not a case name and must be a usage error here, not a workload failure
+  # in case.zsh.
+  for c in "${wanted[@]}"; do (( ${all_cases[(Ie)$c]} )) || die "unknown case: $c"; done
+  # A repeated selection would run the case twice per round and write the
+  # same report key twice, so the sample count would no longer be the truth.
+  typeset -a seen
+  for c in "${wanted[@]}"; do
+    (( ${seen[(Ie)$c]} )) && die "--case $c given more than once"
+    seen+=( "$c" )
+  done
+  cases=( "${wanted[@]}" )
+else
+  cases=( "${all_cases[@]}" )
+fi
+# The reused-home case times a home the previous sample sourced. Without a
+# warmup its first measured sample would be a fresh-home timing mixed into the
+# reused-home statistics; other cases are indifferent to zero warmups.
+(( warmups >= 1 || ${cases[(Ie)source-reused-home]} == 0 )) || die "source-reused-home needs at least one warmup: its first sample would time a home no sample has sourced"
+
+typeset here=${0:A:h} fixtures=${0:A:h}/fixtures manifests=${0:A:h:h}/tests/fixtures/package-manifests
+[[ -d $manifests ]] || die "vendored manifests not found at $manifests"
+# The manifest workload is only comparable to earlier results when it reads
+# exactly the inventory the case was named for: the 21 repositories pinned
+# below, each with its snapshot, and no unlisted snapshot. The names are
+# pinned, not only the count, because replacing one repository with another
+# keeps the count and still changes the workload. A different inventory is a
+# different workload: rename or version the case and its baseline, and update
+# this list with it, instead of letting the contents drift under one name.
+# Snapshot contents are not pinned; refreshing a vendored manifest verbatim
+# keeps the inventory.
+typeset -a manifest_inventory
+manifest_inventory=( any-gem any-node apr asciidoctor brew-completions dircolors-material doctoc ecs-cli firefox-dev fzf fzy github-issues github-issues-srv ls_colors nb pyenv remark subversion system-completions zsh zsh-bin )
+typeset -a manifest_listed manifest_files unpinned unlisted
+typeset manifest_name
+while IFS= read -r manifest_name; do
+  [[ -n $manifest_name ]] && manifest_listed+=( "$manifest_name" )
+done < "$manifests/repositories.txt" || die "could not read $manifests/repositories.txt"
+# (Ie) matches the name literally; a repository name is data, not a pattern.
+for manifest_name in "${manifest_listed[@]}"; do
+  (( ${manifest_inventory[(Ie)$manifest_name]} )) || unpinned+=( "$manifest_name" )
+done
+for manifest_name in "${manifest_inventory[@]}"; do
+  (( ${manifest_listed[(Ie)$manifest_name]} )) || unlisted+=( "$manifest_name" )
+done
+[[ $#unpinned -eq 0 && $#unlisted -eq 0 && ${(j:,:)${(o)manifest_listed}} == ${(j:,:)${(o)manifest_inventory}} ]] ||
+  die "manifest-21 is pinned to a fixed inventory and repositories.txt differs (listed but not pinned: ${(j:, :)unpinned:-none}; pinned but not listed: ${(j:, :)unlisted:-none}). A changed inventory is a different workload: rename or version the case and update the pinned list in run.zsh with it."
+manifest_files=( "$manifests"/*.json(N) )
+for manifest_name in "${manifest_inventory[@]}"; do
+  [[ -r $manifests/$manifest_name.json ]] || die "repositories.txt lists $manifest_name but $manifest_name.json is missing"
+done
+for manifest_name in "${manifest_files[@]}"; do
+  (( ${manifest_inventory[(Ie)${manifest_name:t:r}]} )) || die "${manifest_name:t} is not listed in repositories.txt"
+done
+integer manifest_count=$#manifest_inventory
+
+typeset work
+work=$(command mktemp -d "${TMPDIR:-/tmp}/zi-benchmark.XXXXXXXX") || die "could not create a work directory"
+trap 'command rm -rf -- "$work"' EXIT INT TERM
+# The reused-home case keeps one home per variant across samples; every
+# other case gets a fresh one.
+for label in "${labels[@]}"; do command mkdir -p -- "$work/reused-$label"; done
+
+# reason <status> <stderr-file>: the child's last stderr line, or what its exit
+# status means when it wrote nothing. case.zsh exits 3 when setup or load
+# fails, 4 when the workload ran but left the wrong state, and 5 when the
+# manifest inventory did not match the declared count; a bare "exit 4:" in
+# a report would say nothing about the failed workload.
+reason() {
+  local line
+  line=$(command tail -n 1 -- "$2" 2>/dev/null)
+  if [[ -n $line ]]; then print -r -- "$line"; return; fi
+  case $1 in
+    2) print -r -- "unknown case or missing dependency" ;;
+    3) print -r -- "setup or load failed" ;;
+    4) print -r -- "postcondition failed: the workload did not leave the expected state" ;;
+    5) print -r -- "manifest inventory did not match the declared count" ;;
+    *) print -r -- "no diagnostic" ;;
+  esac
+}
+
+# one_sample <variant> <case>: prints elapsed milliseconds, "fail <reason>", or
+# "unsupported <reason>" when the checkout lacks the API the case exercises
+# (case.zsh exit 6).
+one_sample() {
+  local label=$1 case=$2 home out rc
+  if [[ $case == source-reused-home ]]; then home=$work/reused-$label; else home=$(command mktemp -d "$work/s.XXXXXXXX"); fi
+  command mkdir -p -- "$home"
+  out=$(env -i PATH="$PATH" HOME="$home" ZDOTDIR="$home" TMPDIR="$work" \
+    XDG_DATA_HOME="$home/data" XDG_CACHE_HOME="$home/cache" XDG_CONFIG_HOME="$home/config" \
+    BENCH_CHECKOUT="${dirs[$label]}" BENCH_FIXTURES="$fixtures" BENCH_MANIFESTS="$manifests" \
+    BENCH_MANIFEST_COUNT="$manifest_count" BENCH_CASE="$case" \
+    zsh -f "$here/case.zsh" 2>"$home/stderr"); rc=$?
+  # Only a successful sample reports its timing. A case prints the elapsed
+  # time before checking its postcondition, so on failure stdout can hold a
+  # number that must not reach the report as the start of the reason.
+  if (( rc == 6 )); then
+    print -r -- "unsupported $(command tail -n 1 -- "$home/stderr" 2>/dev/null)"
+  elif (( rc != 0 )); then
+    print -r -- "fail exit ${rc}: $(reason "$rc" "$home/stderr")"
+  else
+    print -r -- "${out##*$'\n'}"
+  fi
+  [[ $case == source-reused-home ]] || command rm -rf -- "$home"
+}
+
+# collected[label/case], failed[label/case] and unsupported[label/case]
+typeset -A collected failed unsupported
+integer round total=$(( warmups + samples ))
+typeset -a order variant_order
+typeset case value
+# Balanced rotation: round r starts the case list one position later than
+# round r-1, so over one cycle of $#cases rounds every case occupies every
+# position; every second cycle runs in reverse direction as well. Variants
+# rotate the same way. A plain reversal every round is not enough for three
+# variants: the middle one would be measured second in every round and take
+# every first-position warm-up effect for granted.
+integer shift_by
+for (( round = 1; round <= total; round++ )); do
+  shift_by=$(( (round - 1) % $#cases ))
+  order=( "${cases[@][shift_by+1,-1]}" "${cases[@][1,shift_by]}" )
+  (( ((round - 1) / $#cases) % 2 )) && order=( "${(Oa)order[@]}" )
+  shift_by=$(( (round - 1) % $#labels ))
+  variant_order=( "${labels[@][shift_by+1,-1]}" "${labels[@][1,shift_by]}" )
+  (( ((round - 1) / $#labels) % 2 )) && variant_order=( "${(Oa)variant_order[@]}" )
+  for case in "${order[@]}"; do
+    for label in "${variant_order[@]}"; do
+      (( ${+failed[$label/$case]} || ${+unsupported[$label/$case]} )) && continue
+      value=$(one_sample "$label" "$case") || value="fail exit $?"
+      # An unsupported case is settled on its first sample for that variant and
+      # is not retried; it is not a failure and does not count toward exit 1.
+      if [[ $value == unsupported* ]]; then unsupported[$label/$case]=${value#unsupported }; continue; fi
+      if [[ $value != <->(.<->|)  ]]; then failed[$label/$case]=${value#fail }; continue; fi
+      (( round > warmups )) && collected[$label/$case]+="${value} "
+    done
+  done
+done
+
+# Health data that costs nothing extra: sizes, compile durations, symbol
+# deltas, measured once per variant outside the sampled rounds.
+health_json() {  # health_json <label>
+  local checkout=${dirs[$1]} f
+  local -A health
+  local -F3 t0 t1
+  integer lines
+  for f in zi.zsh lib/zsh/install.zsh lib/zsh/autoload.zsh lib/zsh/side.zsh lib/zsh/additional.zsh; do
+    lines=$(wc -l < "$checkout/$f"); health[lines:$f]=$lines
+  done
+  t0=$EPOCHREALTIME; zsh -f -n "$checkout/zi.zsh"; t1=$EPOCHREALTIME; health[zsh_n_ms:zi.zsh]=$(( (t1 - t0) * 1000 ))
+  local scratch; scratch=$(command mktemp -d "$work/c.XXXXXXXX")
+  # The copy is setup; only the compilation is timed.
+  command cp -- "$checkout/zi.zsh" "$scratch/zi.zsh"
+  t0=$EPOCHREALTIME; ( cd "$scratch" && zsh -fc 'zcompile zi.zsh' ); t1=$EPOCHREALTIME; health[zcompile_ms:zi.zsh]=$(( (t1 - t0) * 1000 ))
+  command rm -rf -- "$scratch"
+  local -a shipped_zwc; shipped_zwc=( "$checkout"/**/*.zwc(N) )
+  health[zwc_shipped]=$(( $#shipped_zwc > 0 ))
+  local symbols counts home=$work/reused-$1
+  integer probe_status=0
+  symbols=$(env -i PATH="$PATH" HOME="$home" ZDOTDIR="$home" TMPDIR="$work" XDG_DATA_HOME="$home/data" XDG_CACHE_HOME="$home/cache" XDG_CONFIG_HOME="$home/config" \
+    BENCH_CHECKOUT="$checkout" BENCH_FIXTURES="$fixtures" BENCH_MANIFESTS="$manifests" BENCH_MANIFEST_COUNT="$manifest_count" BENCH_CASE=symbols zsh -f "$here/case.zsh" 2>/dev/null) || probe_status=$?
+  # Only a probe that exited 0 and ended with four counts is trusted. A load
+  # failure can print a diagnostic to stdout, and that text must not be
+  # interpolated into the report as JSON; the counts are null instead, so the
+  # case results and failures collected earlier are still published.
+  counts=${symbols##*$'\n'}
+  if (( probe_status == 0 )) && [[ $counts == <->' '<->' '<->' '<-> ]]; then
+    health[functions_after_source]=${${(s: :)counts}[1]}
+    health[parameters_after_source]=${${(s: :)counts}[2]}
+    health[functions_after_load_10]=${${(s: :)counts}[3]}
+    health[parameters_after_load_10]=${${(s: :)counts}[4]}
+  else
+    health[functions_after_source]=null
+    health[parameters_after_source]=null
+    health[functions_after_load_10]=null
+    health[parameters_after_load_10]=null
+  fi
+  local -a hk; hk=( ${(ok)health} ); integer i
+  print -r -- '{'
+  for (( i = 1; i <= $#hk; i++ )); do print -r -- "    $(jq -Rn --arg k "${hk[i]}" '$k'): ${health[${hk[i]}]}$( (( i < $#hk )) && print , )"; done
+  print -r -- '  }'
+}
+
+# Statistics per case: median, p95, min, count, plus the raw samples.
+stats_json() {  # stats_json <space separated samples>
+  local -a a; a=( ${(n)=1} )
+  local -i k=$#a
+  (( k )) || { print -r -- 'null'; return }
+  local -F3 med p95
+  (( k % 2 )) && med=${a[(k+1)/2]} || med=$(( (a[k/2] + a[k/2+1]) / 2.0 ))
+  p95=${a[$(( (k * 95 + 99) / 100 ))]}
+  print -r -- "{\"median\":${med},\"p95\":${p95},\"min\":${a[1]},\"count\":${k},\"samples\":[${(j:,:)a}]}"
+}
+
+typeset zsh_version cpu captured
+zsh_version=$(zsh --version)
+cpu=$(sed -n 's/^model name[[:space:]]*:[[:space:]]*//p' /proc/cpuinfo 2>/dev/null | head -n 1)
+captured=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+integer failures=0 i
+typeset revision output
+for label in "${labels[@]}"; do
+  output=$output_dir/$label.json
+  revision=$(git -C "${dirs[$label]}" rev-parse HEAD 2>/dev/null || print unknown)
+  {
+    print -r -- '{'
+    print -r -- "  \"schema_version\": 1,"
+    print -r -- "  \"captured_at\": \"$captured\","
+    print -r -- "  \"label\": $(jq -Rn --arg v "$label" '$v'),"
+    print -r -- "  \"source_revision\": \"$revision\","
+    print -r -- "  \"environment\": {\"os\": \"$(uname -s)\", \"architecture\": \"$(uname -m)\", \"zsh_version\": $(jq -Rn --arg v "$zsh_version" '$v'), \"cpu\": $(jq -Rn --arg v "${cpu:-unknown}" '$v'), \"runner_image\": $(jq -Rn --arg v "${ImageOS:-}${ImageVersion:+ $ImageVersion}" '$v')},"
+    print -r -- "  \"workload\": {\"warmups\": $warmups, \"samples\": $samples, \"variants\": $(print -r -- "${(j:,:)labels}" | jq -Rc 'split(",")'), \"timer\": \"zsh floating-point SECONDS elapsed milliseconds inside the sampled process\", \"order\": \"within a round the variant list starts one position later than in the previous round, every variant taking every position per cycle, and alternate cycles run reversed; the case list rotates the same way across rounds\"},"
+    print -r -- "  \"health\": $(health_json "$label"),"
+    print -r -- "  \"cases\": {"
+    for (( i = 1; i <= $#cases; i++ )); do
+      case=${cases[i]}
+      if (( ${+unsupported[$label/$case]} )); then
+        print -r -- "    \"$case\": {\"unsupported\": $(jq -Rn --arg v "${unsupported[$label/$case]}" '$v')}$( (( i < $#cases )) && print , )"
+      elif (( ${+failed[$label/$case]} )); then
+        failures+=1
+        print -r -- "    \"$case\": {\"failure\": $(jq -Rn --arg v "${failed[$label/$case]}" '$v')}$( (( i < $#cases )) && print , )"
+      else
+        print -r -- "    \"$case\": $(stats_json "${collected[$label/$case]}")$( (( i < $#cases )) && print , )"
+      fi
+    done
+    print -r -- "  }"
+    print -r -- '}'
+  } > "$output"
+  jq -e . "$output" >/dev/null || die "generated $output is not valid JSON" 1
+  print -r -- "wrote $output: ${#cases} cases"
+done
+(( failures == 0 )) || { print -u2 -r -- "run.zsh: $failures failed case(s); see the failure fields"; exit 1 }
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index d43fe263..b453cd79 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -49,25 +49,16 @@ Repository rules intentionally omit linear-history requirements on both persiste
 
 ## Releases
 
-A promotion to `main` publishes nothing. It updates the Git-consumed stable ref and stops there.
+A same-repository `next` to `main` promotion is the normal publication authorization. Reviewers see the deterministic version and release-note plan on the promotion pull request before deciding whether to merge.
 
-**A signed annotated tag is the sole publication authorization.** Nothing else creates a release: not a merge, not a green pipeline, not the automated proposal.
-
-1. After a promotion reaches `main`, `Release Prepare` opens or updates a proposal issue with the next semantic version computed from Conventional Commits and a draft changelog. It never creates a tag.
-2. A maintainer reviews the proposed version, adjusts it if the computed bump does not describe the change, and pushes a signed annotated tag:
-
-   ```text
-   git switch main && git pull --ff-only
-   git tag -s vX.Y.Z -F <notes-file>
-   git push origin vX.Y.Z
-   ```
-
-3. `scripts/verify-release-tag.zsh` rejects the tag unless every one of the following holds: it matches `vX.Y.Z`, it is annotated rather than lightweight, GitHub reports its signature as verified, its target is the current `origin/main`, and the `Zsh`, `ZD Integration`, `CodeQL` and `Trunk Code Quality` workflows all succeeded on that exact commit.
-4. Only then is a GitHub release published, idempotently, with generated notes.
+1. `Release Plan` computes the next semantic version from Conventional Commits since the latest `vX.Y.Z` tag. A breaking change produces a major bump, `feat` produces a minor bump, and `fix` or `perf` produces a patch bump. A promotion with none of those commits is an explicit no-op.
+2. Merging the reviewed promotion authorizes publication of that displayed plan. The merge still updates the Git-consumed stable `main` ref immediately.
+3. The automatic publisher proves that the exact merge commit came from the reviewed same-repository `next` pull request and is still current `main`. It waits for `Zsh`, `ZD Integration`, `CodeQL`, and `Trunk Code Quality` to succeed on that exact SHA.
+4. The publisher creates an annotated tag and the GitHub release in one idempotent workflow. It fails closed if `main` moves, the promotion identity cannot be proven, validation fails, or the proposed tag already targets another commit.
 
 The repository stores no version file. `ZI[VERSION]` is derived at runtime from `git describe --tags --exact-match`, so the tag is the version and there is nothing to keep in step with it.
 
-Closing a proposal issue without tagging skips that release; the next promotion opens a new proposal.
+The signed manual-tag flow remains available for recovery or exceptional publication. A maintainer may push a signed annotated `vX.Y.Z` tag to the exact current `main`; `scripts/verify-release-tag.zsh` then requires a valid GitHub signature, the exact target, and the same four successful workflows before it creates the release. No personal signing key is stored in Actions.
 
 ## What not to add
 
diff --git a/scripts/publish-promotion-release.zsh b/scripts/publish-promotion-release.zsh
new file mode 100644
index 00000000..6aecfc78
--- /dev/null
+++ b/scripts/publish-promotion-release.zsh
@@ -0,0 +1,56 @@
+#!/usr/bin/env zsh
+
+emulate -L zsh
+setopt err_return no_unset pipe_fail
+
+fail() {
+  print -u2 -r -- "promotion release publication: $*"
+  return 1
+}
+
+repository=${GITHUB_REPOSITORY:-}
+tag=${RELEASE_TAG:-}
+target=${RELEASE_TARGET:-}
+notes_file=${RELEASE_NOTES_FILE:-}
+
+[[ $repository == z-shell/zi ]] || fail "unexpected repository: ${repository:-unset}"
+[[ $tag =~ '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$' ]] ||
+  fail "tag must match vX.Y.Z: ${tag:-unset}"
+[[ $target =~ '^[0-9a-f]{40}$' ]] || fail "invalid release target: ${target:-unset}"
+[[ -r $notes_file ]] || fail "release notes are not readable: ${notes_file:-unset}"
+
+git fetch --quiet --force --no-tags origin \
+  refs/heads/main:refs/remotes/origin/main ||
+  fail 'could not fetch origin/main'
+current_main=$(git rev-parse refs/remotes/origin/main) || fail 'could not resolve origin/main'
+[[ $current_main == $target ]] ||
+  fail "main moved from $target to $current_main before publication"
+
+if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null 2>&1; then
+  git fetch --quiet --force origin "refs/tags/${tag}:refs/tags/${tag}" ||
+    fail "could not fetch existing tag: $tag"
+  existing_target=$(git rev-parse "refs/tags/${tag}^{}") ||
+    fail "could not resolve existing tag: $tag"
+  [[ $existing_target == $target ]] ||
+    fail "$tag already targets $existing_target, not $target"
+  [[ $(git cat-file -t "refs/tags/${tag}") == tag ]] ||
+    fail "$tag exists but is not annotated"
+else
+  git config user.name 'github-actions[bot]'
+  git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+  git tag -a "$tag" "$target" -F "$notes_file" || fail "could not create tag: $tag"
+  git push origin "refs/tags/${tag}" || fail "could not push tag: $tag"
+fi
+
+if gh release view "$tag" --repo "$repository" >/dev/null 2>&1; then
+  print -r -- "Release $tag already exists at $target."
+  return 0
+fi
+
+gh release create "$tag" \
+  --repo "$repository" \
+  --verify-tag \
+  --title "Zi $tag" \
+  --notes-file "$notes_file" \
+  --latest || fail "could not create release: $tag"
+print -r -- "Published $tag at $target."
diff --git a/scripts/release-plan.zsh b/scripts/release-plan.zsh
new file mode 100644
index 00000000..d3ea3111
--- /dev/null
+++ b/scripts/release-plan.zsh
@@ -0,0 +1,153 @@
+#!/usr/bin/env zsh
+
+emulate -L zsh
+setopt err_return no_unset pipe_fail extended_glob
+
+fail() {
+  print -u2 -r -- "release plan: $*"
+  return 1
+}
+
+target=${1:-HEAD}
+output=${RELEASE_PLAN_OUTPUT:-}
+notes_file=${RELEASE_NOTES_FILE:-}
+
+target=$(git rev-parse --verify "${target}^{commit}") ||
+  fail "could not resolve target commit: ${1:-HEAD}"
+
+typeset previous_tag=''
+typeset candidate
+for candidate in ${(f)"$(git tag --list 'v[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname)"}; do
+  if [[ $candidate =~ '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$' ]]; then
+    previous_tag=$candidate
+    break
+  fi
+done
+
+typeset range=$target
+if [[ -n $previous_tag ]]; then
+  tag_target=$(git rev-parse "${previous_tag}^{}") ||
+    fail "could not resolve previous tag: $previous_tag"
+  base_commit=$tag_target
+  if ! git merge-base --is-ancestor "$base_commit" "$target"; then
+    typeset -a tag_parents
+    tag_parents=( ${(s: :)"$(git rev-list --parents -n 1 "$tag_target")"} )
+    (( $#tag_parents == 3 )) ||
+      fail "$previous_tag is not an ancestor or a promotion merge"
+    base_commit=${tag_parents[3]}
+    git merge-base --is-ancestor "$base_commit" "$target" ||
+      fail "$previous_tag does not describe this promotion lineage"
+  fi
+  range="${base_commit}..${target}"
+fi
+
+typeset -a records breaking features fixes performance other
+records=( ${(f)"$(git log --no-merges --format='%H%x09%s' "$range")"} )
+
+typeset bump=0 record sha subject body short
+for record in "${records[@]}"; do
+  sha=${record%%$'\t'*}
+  subject=${record#*$'\t'}
+  short=${sha[1,7]}
+  body=$(git show -s --format='%B' "$sha") || fail "could not read commit $sha"
+
+  if print -r -- "$subject" | grep -qE '^[a-z]+(\([^)]*\))?!:' ||
+      print -r -- "$body" | grep -qE '^BREAKING[ -]CHANGE:'; then
+    (( bump < 3 )) && bump=3
+    breaking+=( "- ${subject} (${short})" )
+  elif print -r -- "$subject" | grep -qE '^feat(\([^)]*\))?:'; then
+    (( bump < 2 )) && bump=2
+    features+=( "- ${subject} (${short})" )
+  elif print -r -- "$subject" | grep -qE '^fix(\([^)]*\))?:'; then
+    (( bump < 1 )) && bump=1
+    fixes+=( "- ${subject} (${short})" )
+  elif print -r -- "$subject" | grep -qE '^perf(\([^)]*\))?:'; then
+    (( bump < 1 )) && bump=1
+    performance+=( "- ${subject} (${short})" )
+  else
+    other+=( "- ${subject} (${short})" )
+  fi
+done
+
+typeset release=false version='' tag=''
+if (( bump > 0 )); then
+  release=true
+  if [[ -z $previous_tag ]]; then
+    version=0.1.0
+  else
+    typeset base=${previous_tag#v}
+    typeset -a parts
+    parts=( ${(s:.:)base} )
+    (( $#parts == 3 )) || fail "invalid previous semantic tag: $previous_tag"
+    case $bump in
+      3) version="$(( parts[1] + 1 )).0.0" ;;
+      2) version="${parts[1]}.$(( parts[2] + 1 )).0" ;;
+      1) version="${parts[1]}.${parts[2]}.$(( parts[3] + 1 ))" ;;
+    esac
+  fi
+  tag="v${version}"
+fi
+
+if [[ -n $output ]]; then
+  {
+    print -r -- "release=${release}"
+    print -r -- "previous_tag=${previous_tag}"
+    print -r -- "version=${version}"
+    print -r -- "tag=${tag}"
+    print -r -- "target=${target}"
+  } >| "$output" || fail "could not write plan output: $output"
+fi
+
+if [[ $release == false ]]; then
+  print -r -- '## Release plan'
+  print
+  print -r -- "No semantic release is proposed. The commits since ${previous_tag:-repository start} contain no feature, fix, performance, or breaking Conventional Commit."
+  return 0
+fi
+
+typeset generated_notes
+generated_notes=$(mktemp "${TMPDIR:-/tmp}/zi-release-notes.XXXXXXXX") ||
+  fail 'could not create a notes file'
+trap 'rm -f -- "$generated_notes"' EXIT HUP INT TERM
+
+{
+  print -r -- "## Changes since ${previous_tag:-repository start}"
+  if (( $#breaking )); then
+    print
+    print -r -- '### Breaking changes'
+    print -rl -- "${breaking[@]}"
+  fi
+  if (( $#features )); then
+    print
+    print -r -- '### Features'
+    print -rl -- "${features[@]}"
+  fi
+  if (( $#fixes )); then
+    print
+    print -r -- '### Fixes'
+    print -rl -- "${fixes[@]}"
+  fi
+  if (( $#performance )); then
+    print
+    print -r -- '### Performance'
+    print -rl -- "${performance[@]}"
+  fi
+  if (( $#other )); then
+    print
+    print -r -- '### Other'
+    print -rl -- "${other[@]}"
+  fi
+} >| "$generated_notes" || fail 'could not render release notes'
+
+if [[ -n $notes_file ]]; then
+  command cp -- "$generated_notes" "$notes_file" ||
+    fail "could not write release notes: $notes_file"
+fi
+
+print -r -- '## Release plan'
+print
+print -r -- "- Proposed tag: \`${tag}\`"
+print -r -- "- Previous tag: \`${previous_tag:-none}\`"
+print -r -- "- Candidate commit: \`${target}\`"
+print
+command cat -- "$generated_notes"
diff --git a/scripts/verify-promotion-release.zsh b/scripts/verify-promotion-release.zsh
new file mode 100644
index 00000000..96de41ed
--- /dev/null
+++ b/scripts/verify-promotion-release.zsh
@@ -0,0 +1,85 @@
+#!/usr/bin/env zsh
+
+emulate -L zsh
+setopt err_return no_unset pipe_fail
+
+fail() {
+  print -u2 -r -- "promotion release verification: $*"
+  return 1
+}
+
+emit() {
+  [[ -z ${GITHUB_OUTPUT:-} ]] || print -r -- "$1=$2" >> "$GITHUB_OUTPUT"
+}
+
+repository=${GITHUB_REPOSITORY:-}
+target=${PROMOTION_SHA:-}
+
+emit ready false
+[[ $repository == z-shell/zi ]] || fail "unexpected repository: ${repository:-unset}"
+[[ $target =~ '^[0-9a-f]{40}$' ]] || fail "invalid promotion SHA: ${target:-unset}"
+
+git fetch --quiet --force --no-tags origin \
+  refs/heads/main:refs/remotes/origin/main ||
+  fail 'could not fetch origin/main'
+
+main=$(git rev-parse refs/remotes/origin/main) || fail 'could not resolve origin/main'
+[[ $target == $main ]] || fail 'promotion SHA is not the current origin/main'
+
+typeset -a parents
+parents=( ${(s: :)"$(git rev-list --parents -n 1 "$target")"} )
+(( $#parents == 3 )) || fail 'promotion commit must have exactly two parents'
+
+pulls_json=$(gh api -H 'Accept: application/vnd.github+json' \
+  "repos/${repository}/commits/${target}/pulls") ||
+  fail 'could not read pull requests for the promotion commit'
+
+promotion=$(jq -c --arg repository "$repository" --arg target "$target" \
+  '[.[] | select(
+    .merged_at != null and
+    .merge_commit_sha == $target and
+    .base.ref == "main" and
+    .head.ref == "next" and
+    .head.repo.full_name == $repository
+  )] | first // empty' <<<"$pulls_json") || fail 'could not inspect promotion pull request'
+[[ -n $promotion ]] || fail 'commit is not a merged next-to-main promotion'
+
+promotion_pr=$(jq -r '.number' <<<"$promotion")
+promotion_head=$(jq -r '.head.sha' <<<"$promotion")
+[[ ${parents[3]} == $promotion_head ]] ||
+  fail 'promotion second parent does not match the reviewed next head'
+
+runs_json=$(gh api --method GET "repos/${repository}/actions/runs" \
+  -f branch=main -f head_sha="$target" -f per_page=100) ||
+  fail 'could not read workflow runs'
+
+typeset workflow run run_status run_conclusion
+for workflow in Zsh 'ZD Integration' CodeQL 'Trunk Code Quality'; do
+  run=$(jq -c --arg name "$workflow" --arg target "$target" \
+    '[.workflow_runs[] | select(
+      .name == $name and
+      .head_branch == "main" and
+      .head_sha == $target
+    )] | sort_by(.id) | last // empty' <<<"$runs_json") ||
+    fail "could not inspect required workflow: $workflow"
+
+  if [[ -z $run ]]; then
+    print -r -- "Waiting for required workflow: $workflow"
+    emit promotion_pr "$promotion_pr"
+    return 0
+  fi
+
+  run_status=$(jq -r '.status' <<<"$run")
+  run_conclusion=$(jq -r '.conclusion // ""' <<<"$run")
+  if [[ $run_status != completed ]]; then
+    print -r -- "Waiting for required workflow: $workflow ($run_status)"
+    emit promotion_pr "$promotion_pr"
+    return 0
+  fi
+  [[ $run_conclusion == success ]] ||
+    fail "required workflow did not succeed: $workflow ($run_conclusion)"
+done
+
+emit promotion_pr "$promotion_pr"
+emit ready true
+print -r -- "Promotion #${promotion_pr} and required workflows verified at ${target}."
diff --git a/tests/benchmark-harness.zsh b/tests/benchmark-harness.zsh
new file mode 100644
index 00000000..7c1df5f6
--- /dev/null
+++ b/tests/benchmark-harness.zsh
@@ -0,0 +1,228 @@
+#!/usr/bin/env zsh
+# -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
+# vim: ft=zsh sw=2 ts=2 et
+#
+# The benchmark runner and comparer are themselves tested: a tiny-count run
+# must produce every case with valid statistics, an A/A comparison must flag
+# nothing, a synthetically slowed candidate must be flagged without failing,
+# a functional failure must invalidate its case, a checkout that lacks the API
+# a case exercises must be reported unsupported rather than failed unless it
+# is the candidate that lost the API, and a swapped manifest inventory must be
+# rejected by name (#553).
+
+builtin emulate -R zsh
+setopt pipe_fail extended_glob
+
+fail() {
+  builtin print -u2 -r -- "not ok - $1"
+  exit 1
+}
+
+(( $+commands[jq] )) || fail "missing test dependency: jq"
+typeset project_root="${ZI_TEST_CHECKOUT:-${0:A:h:h}}"
+typeset temp_root
+temp_root="$(command mktemp -d "${TMPDIR:-/tmp}/zi-benchmark-harness.XXXXXXXX")" || fail "create temporary directory"
+trap 'command rm -rf -- "$temp_root"' EXIT INT TERM
+
+zsh "${project_root}/benchmarks/run.zsh" --variant a="$project_root" --variant b="$project_root" \
+  --output-dir "$temp_root/run" --warmups 1 --samples 2 >/dev/null || fail "runner failed on the checkout"
+[[ -s $temp_root/run/a.json && -s $temp_root/run/b.json ]] || fail "one report per variant expected"
+command cp -- "$temp_root/run/a.json" "$temp_root/a.json"
+zsh "${project_root}/benchmarks/run.zsh" --variant c="$project_root" --output-dir "$temp_root/subset" \
+  --warmups 1 --samples 2 --case source-reused-home --case light-load-10 >/dev/null || fail "runner failed with a case subset"
+command cp -- "$temp_root/subset/c.json" "$temp_root/b.json"
+zsh "${project_root}/benchmarks/run.zsh" --variant a="$project_root" --variant a="$project_root" --output-dir "$temp_root/dup" >/dev/null 2>&1 &&
+  fail "duplicate variant labels must be rejected"
+zsh "${project_root}/benchmarks/run.zsh" --variant c="$project_root" --output-dir "$temp_root/dup-case" \
+  --case ice-200 --case ice-200 >/dev/null 2>&1 && fail "a repeated --case must be rejected"
+zsh "${project_root}/benchmarks/run.zsh" --variant c="$project_root" --output-dir "$temp_root/glob-case" \
+  --case 'source-*' >/dev/null 2>"$temp_root/glob-case.err" && fail "a pattern is not a case name and must be rejected"
+grep -q 'unknown case: source-\*' "$temp_root/glob-case.err" || fail "a pattern --case must be a usage error, not a workload failure"
+zsh "${project_root}/benchmarks/run.zsh" --variant c="$project_root" --output-dir "$temp_root/zero-warm" \
+  --warmups 0 --samples 2 --case source-reused-home >/dev/null 2>"$temp_root/zero-warm.err" && fail "zero warmups with source-reused-home must be rejected"
+grep -q 'at least one warmup' "$temp_root/zero-warm.err" || fail "the zero-warmup rejection must say why"
+zsh "${project_root}/benchmarks/run.zsh" --variant c="$project_root" --output-dir "$temp_root/zero-warm-ok" \
+  --warmups 0 --samples 2 --case ice-200 >/dev/null 2>&1 || fail "zero warmups must stay valid for cases that do not reuse a home"
+
+# Every row of the Markdown case table has six cells, whatever the row's
+# outcome. An escaped pipe is content, not a cell boundary, so it is removed
+# before counting.
+table_rows_ok() { grep '^|' "$1" | sed 's/\\|//g' | awk -F'|' 'NF != 8 { bad = 1 } END { exit bad }'; }
+
+# copy_suite <dir>: a private copy of the runner, its fixtures, and the
+# vendored manifests, so a test can alter one of them without touching the
+# checkout; run.zsh resolves both from its own location.
+copy_suite() {
+  command mkdir -p -- "$1/tests/fixtures" || fail "create a suite copy under $1"
+  command cp -R -- "$project_root/benchmarks" "$1/benchmarks" || fail "copy the benchmark scripts"
+  command cp -R -- "$project_root/tests/fixtures/package-manifests" "$1/tests/fixtures/package-manifests" || fail "copy the vendored manifests"
+}
+
+integer cases
+cases=$(jq -r '.cases | length' "$temp_root/a.json") || fail "a.json is not valid JSON"
+(( cases == 8 )) || fail "expected 8 cases, got ${cases}"
+jq -e '.cases | to_entries | all(.value.count == 2 and (.value.median | type) == "number" and (.value.p95 | type) == "number" and (.value.samples | length) == 2)' "$temp_root/a.json" >/dev/null ||
+  fail "every case must carry two samples with numeric median and p95"
+jq -e '.health | (.functions_after_source > 0) and (.parameters_after_source > 0) and (."lines:zi.zsh" > 1000) and (."zcompile_ms:zi.zsh" > 0)' "$temp_root/a.json" >/dev/null ||
+  fail "health data missing or implausible"
+jq -e '.cases | keys == ["light-load-10", "source-reused-home"]' "$temp_root/b.json" >/dev/null || fail "--case did not select the subset"
+jq -e '.workload.variants == ["a", "b"]' "$temp_root/a.json" >/dev/null || fail "the report must list the variants measured together"
+
+# A sample is printed with exactly three decimals whatever its value: an
+# integral float would otherwise print as "250.", which is neither a sample
+# the runner accepts nor a JSON number. The copy pins the timer to an exact
+# quarter second so the arithmetic result is integral.
+copy_suite "$temp_root/integral"
+command sed 's/^start() { t0=\$SECONDS; }$/start() { t0=1.000000; }/; s/^mark()  { t1=\$SECONDS; }$/mark()  { t1=1.250000; }/' "$project_root/benchmarks/case.zsh" > "$temp_root/integral/benchmarks/case.zsh" || fail "pin the timer in the copy"
+grep -q '^mark()  { t1=1.250000; }$' "$temp_root/integral/benchmarks/case.zsh" || fail "the copy must pin the timer"
+zsh "$temp_root/integral/benchmarks/run.zsh" --variant a="$project_root" --output-dir "$temp_root/integral-run" \
+  --warmups 1 --samples 2 --case ice-200 >/dev/null 2>&1 || fail "an integral sample must be accepted"
+jq -e '.cases["ice-200"].samples == [250, 250] and .cases["ice-200"].median == 250' "$temp_root/integral-run/a.json" >/dev/null ||
+  fail "an integral sample must be recorded as the number 250"
+
+# A/A: comparing a run with itself flags nothing and fails nothing.
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/a.json" --candidate "$temp_root/a.json" \
+  --control "$temp_root/a.json" --output "$temp_root/aa.json" --markdown "$temp_root/aa.md" >/dev/null || fail "A/A comparison failed"
+jq -e '.flagged == [] and .failed == [] and .comparable == true' "$temp_root/aa.json" >/dev/null || fail "A/A comparison must flag and fail nothing"
+[[ -s $temp_root/aa.md ]] && grep -q '^| source-fresh-home ' "$temp_root/aa.md" || fail "Markdown rendering missing the case table"
+table_rows_ok "$temp_root/aa.md" || fail "the A/A Markdown table rows must have six cells"
+
+# Sensitivity: a candidate 30% slower on one case is flagged, never failed.
+jq '.cases["ice-200"].median *= 1.3 | .cases["ice-200"].p95 *= 1.3' "$temp_root/a.json" > "$temp_root/slow.json"
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/a.json" --candidate "$temp_root/slow.json" \
+  --output "$temp_root/slow-cmp.json" >/dev/null || fail "a flagged comparison must still exit 0"
+jq -e '.flagged == ["ice-200"] and .failed == [] and .cases["ice-200"].flag == true' "$temp_root/slow-cmp.json" >/dev/null ||
+  fail "a 30% regression must be flagged on exactly that case"
+
+# Reports that are not comparable carry null flags, even with a large delta.
+jq '.workload.warmups += 1 | .cases["ice-200"].median *= 1.3 | .cases["ice-200"].p95 *= 1.3' "$temp_root/a.json" > "$temp_root/other.json"
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/a.json" --candidate "$temp_root/other.json" \
+  --output "$temp_root/other-cmp.json" --markdown "$temp_root/other.md" >/dev/null || fail "an incomparable comparison must still exit 0"
+jq -e '.comparable == false and .flagged == [] and .cases["ice-200"].flag == null' "$temp_root/other-cmp.json" >/dev/null ||
+  fail "incomparable reports must not flag"
+grep -q "not comparable" "$temp_root/other.md" || fail "Markdown must say why nothing is flagged"
+
+# Reports with different case sets are rejected up front, not deep inside jq.
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/a.json" --candidate "$temp_root/b.json" \
+  --output "$temp_root/mismatch.json" >/dev/null 2>"$temp_root/mismatch.err" && fail "different case sets must be rejected"
+grep -q "do not cover the same cases" "$temp_root/mismatch.err" || fail "the case-set mismatch must be named"
+
+# A failure that appears only in the A/A control is still a failure.
+jq '.cases["unload-10"] = {"failure": "exit 4: control-only"}' "$temp_root/a.json" > "$temp_root/ctl-broken.json"
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/a.json" --candidate "$temp_root/a.json" \
+  --control "$temp_root/ctl-broken.json" --output "$temp_root/ctl-cmp.json" --markdown "$temp_root/ctl.md" >/dev/null 2>&1 && fail "a control-only failure must exit 1"
+jq -e '.failed == ["unload-10"]' "$temp_root/ctl-cmp.json" >/dev/null || fail "the control-only failure must be listed in failed"
+grep -q '^| unload-10 .*| failure: exit 4: control-only |$' "$temp_root/ctl.md" || fail "the control failure must be rendered in its Markdown cell, not n/a"
+table_rows_ok "$temp_root/ctl.md" || fail "a control failure must not misalign the Markdown table"
+
+# A control measured under other settings, or from another revision, is
+# rejected up front rather than rendered as the noise floor.
+jq '.workload.warmups += 1' "$temp_root/a.json" > "$temp_root/ctl-other.json"
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/a.json" --candidate "$temp_root/a.json" \
+  --control "$temp_root/ctl-other.json" --output "$temp_root/ctl-other-cmp.json" >/dev/null 2>"$temp_root/ctl-other.err" && fail "an incompatible control must be rejected"
+grep -q "control is not a second run of the baseline" "$temp_root/ctl-other.err" || fail "the incompatible control must be named"
+[[ ! -e $temp_root/ctl-other-cmp.json ]] || fail "an incompatible control must not produce a comparison"
+jq '.source_revision = "0000000000000000000000000000000000000000"' "$temp_root/a.json" > "$temp_root/ctl-rev.json"
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/a.json" --candidate "$temp_root/a.json" \
+  --control "$temp_root/ctl-rev.json" --output "$temp_root/ctl-rev-cmp.json" >/dev/null 2>"$temp_root/ctl-rev.err" && fail "a control from another revision must be rejected"
+grep -q "control is not a second run of the baseline" "$temp_root/ctl-rev.err" || fail "the other-revision control must be named"
+
+# Functional failure on either side invalidates the case and exits 1.
+jq '.cases["unload-10"] = {"failure": "exit 4: synthetic"}' "$temp_root/a.json" > "$temp_root/broken.json"
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/a.json" --candidate "$temp_root/broken.json" \
+  --output "$temp_root/broken-cmp.json" --markdown "$temp_root/broken.md" >/dev/null 2>&1 && fail "a functional failure must exit 1"
+jq -e '.failed == ["unload-10"] and (.cases["unload-10"].failure.candidate | test("synthetic"))' "$temp_root/broken-cmp.json" >/dev/null ||
+  fail "the failed case must be recorded with its reason"
+grep -q '^| unload-10 | failure | failure | .*synthetic' "$temp_root/broken.md" || fail "the failed case must be rendered as a failure row"
+table_rows_ok "$temp_root/broken.md" || fail "a failure row must not misalign the Markdown table"
+
+# A reason that contains a pipe stays in one cell, in the case row and in the
+# control column alike.
+jq '.cases["unload-10"] = {"failure": "exit 4: a | b"}' "$temp_root/a.json" > "$temp_root/piped.json"
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/a.json" --candidate "$temp_root/piped.json" \
+  --control "$temp_root/piped.json" --output "$temp_root/piped-cmp.json" --markdown "$temp_root/piped.md" >/dev/null 2>&1 && fail "a piped failure reason must still exit 1"
+grep -q '^| unload-10 | failure | failure | .*a \\| b.* | | failure: exit 4: a \\| b |$' "$temp_root/piped.md" || fail "a pipe inside a reason must be escaped in both columns"
+table_rows_ok "$temp_root/piped.md" || fail "a pipe inside a reason must not split the Markdown row"
+
+# A health probe that fails or prints something other than four counts yields
+# null counts and a report that is still valid JSON, so the case results are
+# published. The copy makes the symbols probe print a diagnostic and exit 3.
+copy_suite "$temp_root/probe"
+command sed 's/^    print -r -- "\$f1 \$p1 \$#functions \$#parameters" ;;$/    print -r -- "zi: cannot load"; exit 3 ;;/' "$project_root/benchmarks/case.zsh" > "$temp_root/probe/benchmarks/case.zsh" || fail "break the symbols probe in the copy"
+grep -q 'cannot load' "$temp_root/probe/benchmarks/case.zsh" || fail "the copy must break the symbols probe"
+zsh "$temp_root/probe/benchmarks/run.zsh" --variant a="$project_root" --output-dir "$temp_root/probe-run" \
+  --warmups 1 --samples 2 --case ice-200 >/dev/null 2>&1 || fail "a failed health probe must not fail the run"
+jq -e '.health.functions_after_source == null and .health.parameters_after_load_10 == null and .cases["ice-200"].count == 2' "$temp_root/probe-run/a.json" >/dev/null ||
+  fail "a failed health probe must record null counts beside the measured cases"
+
+# A home that fails to prepare must not yield counts either: the copy makes
+# load_zi's preparation step fail, which the symbols probe shares with the
+# measured cases, and source-fresh-home does not use load_zi.
+copy_suite "$temp_root/prep"
+command sed 's/^load_zi() { builtin source "\$BENCH_CHECKOUT\/zi.zsh" || exit 3; \.zi-prepare-home || exit 3; }$/load_zi() { builtin source "$BENCH_CHECKOUT\/zi.zsh" || exit 3; false || exit 3; }/' "$project_root/benchmarks/case.zsh" > "$temp_root/prep/benchmarks/case.zsh" || fail "break home preparation in the copy"
+grep -q '^load_zi() .*false || exit 3; }$' "$temp_root/prep/benchmarks/case.zsh" || fail "the copy must fail home preparation"
+zsh "$temp_root/prep/benchmarks/run.zsh" --variant a="$project_root" --output-dir "$temp_root/prep-run" \
+  --warmups 1 --samples 2 --case source-fresh-home >/dev/null 2>&1 || fail "a failed preparation in the probe must not fail the run"
+jq -e '.health.functions_after_source == null and .cases["source-fresh-home"].count == 2' "$temp_root/prep-run/a.json" >/dev/null ||
+  fail "a probe whose home preparation fails must record null counts"
+
+# A checkout that lacks the API a case exercises reports that case as
+# unsupported, not failed, and the other cases still run. The copy below is
+# this checkout with the manifest reader's definition renamed away, which is
+# what a baseline older than the reader looks like to the runner.
+command mkdir -p -- "$temp_root/old/lib/zsh" || fail "create the old checkout copy"
+command cp -R -- "$project_root/zi.zsh" "$project_root/lib" "$temp_root/old/" || fail "copy the checkout"
+command sed 's/^\.zi-read-package-manifest() {/.zi-read-package-manifest-absent() {/' "$project_root/lib/zsh/install.zsh" > "$temp_root/old/lib/zsh/install.zsh" || fail "rename the reader in the copy"
+grep -q '^\.zi-read-package-manifest-absent() {' "$temp_root/old/lib/zsh/install.zsh" || fail "the copy must lack the reader definition"
+zsh "${project_root}/benchmarks/run.zsh" --variant old="$temp_root/old" --variant new="$project_root" \
+  --output-dir "$temp_root/unsup" --warmups 1 --samples 2 --case manifest-21 --case ice-200 >/dev/null || fail "an unsupported case must not fail the runner"
+jq -e '.cases["manifest-21"].unsupported | type == "string" and test("zi-read-package-manifest")' "$temp_root/unsup/old.json" >/dev/null ||
+  fail "the old checkout must report manifest-21 unsupported with the reason"
+jq -e '.cases["ice-200"].count == 2' "$temp_root/unsup/old.json" >/dev/null || fail "an unsupported case must not stop the other cases"
+jq -e '.cases["manifest-21"].count == 2 and .cases["ice-200"].count == 2' "$temp_root/unsup/new.json" >/dev/null || fail "the checkout with the reader must still measure manifest-21"
+
+# Baseline without the API, candidate with it: unsupported, never failed.
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/unsup/old.json" --candidate "$temp_root/unsup/new.json" \
+  --control "$temp_root/unsup/old.json" --output "$temp_root/unsup-cmp.json" --markdown "$temp_root/unsup.md" >/dev/null || fail "a baseline without the API must not fail the comparison"
+jq -e '.unsupported == ["manifest-21"] and .failed == [] and .flagged == [] and .cases["manifest-21"].unsupported.candidate == null and .cases["ice-200"].flag != null' "$temp_root/unsup-cmp.json" >/dev/null ||
+  fail "a baseline without the API must be listed as unsupported and nothing else"
+grep -q '^| manifest-21 | unsupported | not compared | .*zi-read-package-manifest.* | | unsupported |$' "$temp_root/unsup.md" || fail "the unsupported case must be rendered with its reason and control state"
+table_rows_ok "$temp_root/unsup.md" || fail "an unsupported row must not misalign the Markdown table"
+
+# Both sides without the API: still unsupported, still exit 0.
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/unsup/old.json" --candidate "$temp_root/unsup/old.json" \
+  --output "$temp_root/both-cmp.json" --markdown "$temp_root/both.md" >/dev/null || fail "two checkouts without the API must not fail the comparison"
+jq -e '.unsupported == ["manifest-21"] and .failed == [] and (.cases["manifest-21"].unsupported.candidate | type) == "string"' "$temp_root/both-cmp.json" >/dev/null ||
+  fail "both sides unsupported must be recorded on both sides"
+grep -q '^| manifest-21 | unsupported | unsupported | ' "$temp_root/both.md" || fail "both sides unsupported must be rendered on both sides"
+
+# Candidate without an API the baseline has: that is a removal, and it fails.
+zsh "${project_root}/benchmarks/compare.zsh" --baseline "$temp_root/unsup/new.json" --candidate "$temp_root/unsup/old.json" \
+  --output "$temp_root/removed-cmp.json" --markdown "$temp_root/removed.md" >/dev/null 2>&1 && fail "a candidate that lost an API must exit 1"
+jq -e '.failed == ["manifest-21"] and .unsupported == [] and (.cases["manifest-21"].failure.candidate | test("^removed: "))' "$temp_root/removed-cmp.json" >/dev/null ||
+  fail "a candidate that lost an API must be recorded as a removal failure"
+grep -q '^| manifest-21 | failure | failure | .*removed' "$temp_root/removed.md" || fail "the removal must be rendered as a failure row"
+
+# A case that prints its timing and then fails its postcondition must report
+# a one-line reason, not a reason that starts with the discarded timing. The
+# copy makes unload-10 exit 4 right after it prints.
+copy_suite "$temp_root/post"
+command sed 's/^    none_loaded || exit 4 ;;$/    exit 4 ;;/' "$project_root/benchmarks/case.zsh" > "$temp_root/post/benchmarks/case.zsh" || fail "break the unload-10 postcondition in the copy"
+grep -q '^    exit 4 ;;$' "$temp_root/post/benchmarks/case.zsh" || fail "the copy must fail the unload-10 postcondition"
+zsh "$temp_root/post/benchmarks/run.zsh" --variant a="$project_root" --output-dir "$temp_root/post-run" \
+  --warmups 1 --samples 2 --case unload-10 >/dev/null 2>&1 && fail "a failed postcondition must exit 1"
+jq -e '.cases["unload-10"].failure | type == "string" and startswith("exit 4: postcondition failed") and (contains("\n") | not)' "$temp_root/post-run/a.json" >/dev/null ||
+  fail "a failed postcondition that wrote nothing must record a one-line reason that says what exit 4 means"
+
+# The manifest inventory is pinned by name: swapping one repository for
+# another keeps the count at 21 and is still rejected before any sample runs.
+copy_suite "$temp_root/swap"
+command mv -- "$temp_root/swap/tests/fixtures/package-manifests/zsh-bin.json" "$temp_root/swap/tests/fixtures/package-manifests/zsh-bin-other.json" || fail "rename a snapshot"
+command sed 's/^zsh-bin$/zsh-bin-other/' "$project_root/tests/fixtures/package-manifests/repositories.txt" > "$temp_root/swap/tests/fixtures/package-manifests/repositories.txt" || fail "swap a listed repository"
+zsh "$temp_root/swap/benchmarks/run.zsh" --variant a="$project_root" --output-dir "$temp_root/swap-run" \
+  --warmups 1 --samples 2 --case ice-200 >/dev/null 2>"$temp_root/swap.err" && fail "a swapped manifest inventory must be rejected"
+grep -q 'pinned' "$temp_root/swap.err" && grep -q 'not pinned: zsh-bin-other' "$temp_root/swap.err" && grep -q 'not listed: zsh-bin' "$temp_root/swap.err" ||
+  fail "the rejection must name the unpinned and the missing repository"
+[[ ! -e $temp_root/swap-run/a.json ]] || fail "a rejected inventory must not produce a report"
+
+builtin print -r -- "ok - benchmark runner and comparer produce, flag, invalidate, and mark unsupported as designed"
diff --git a/tests/ci-registration.zsh b/tests/ci-registration.zsh
index 5d35f259..bbc02175 100644
--- a/tests/ci-registration.zsh
+++ b/tests/ci-registration.zsh
@@ -37,6 +37,9 @@ promotion_set=(
   archive-extraction.zsh
   completion-refresh.zsh
   snippet-directory-mirror.zsh
+  release-plan.zsh
+  promotion-release-verification.zsh
+  promotion-release-publication.zsh
 )
 
 # A test is invoked only by an executable `run:` step. The scanner reads the
diff --git a/tests/disk-ice-resolution.zsh b/tests/disk-ice-resolution.zsh
index 76b93441..2ce46733 100755
--- a/tests/disk-ice-resolution.zsh
+++ b/tests/disk-ice-resolution.zsh
@@ -129,7 +129,14 @@ load_ices collide-id snippet || die "typed collision: non-zero return"
 assert_equal "${ICE[atload]}" COLLIDE_SNIPPET "typed collision resolves to the snippet"
 assert_equal "$captured" "" "typed collision reports nothing"
 
-# 7. An empty plugin metadata directory is a leftover, not an object. It must
+# 7. A caller that knows the object is a snippet must not fall back to the plugin
+#    root when only the plugin has disk ices.
+write_ices "$(plugin_dir plugin-only-id)" 'atload=PLUGIN_ONLY'
+load_ices plugin-only-id snippet && die "snippet caller fell back to plugin root"
+assert_equal "${#ICE}" 0 "snippet caller leaves ICE empty on missing snippet ices"
+assert_equal "$captured" "" "snippet caller with missing snippet ices reports nothing"
+
+# 8. An empty plugin metadata directory is a leftover, not an object. It must
 #    not shadow the snippet, and it is not a collision.
 write_ices "$(snippet_dir leftover-id)" 'atload=LEFTOVER_SNIPPET' 'as=command'
 command mkdir -p -- "$(plugin_dir leftover-id)" || die "create leftover"
@@ -138,10 +145,10 @@ assert_equal "${ICE[atload]}" LEFTOVER_SNIPPET "leftover does not shadow the sni
 assert_equal "${ICE[as]}" command "leftover: snippet ices are complete"
 assert_equal "$captured" "" "leftover is not reported as a collision"
 
-# 8. An ID present in neither root fails.
+# 9. An ID present in neither root fails.
 load_ices absent-id && die "absent ID: reported success"
 
-# 9. Resolution runs with the user's shell options. The root probe must not
+# 10. Resolution runs with the user's shell options. The root probe must not
 #    depend on any of them.
 () {
   builtin setopt local_options sh_glob no_bare_glob_qual no_extended_glob no_null_glob
diff --git a/tests/promotion-release-publication.zsh b/tests/promotion-release-publication.zsh
new file mode 100644
index 00000000..ab2264a4
--- /dev/null
+++ b/tests/promotion-release-publication.zsh
@@ -0,0 +1,85 @@
+#!/usr/bin/env zsh
+
+emulate -L zsh
+setopt err_exit no_unset pipe_fail
+
+root=${0:A:h:h}
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/zi-promotion-publish-test.XXXXXX")
+trap 'rm -rf -- "$tmp"' EXIT HUP INT TERM
+
+typeset -a content_writers
+content_writers=( ${(f)"$(grep -l '^[[:space:]]*contents:[[:space:]]*write' "$root"/.github/workflows/*.yml || true)"} )
+(( $#content_writers == 1 ))
+[[ ${content_writers[1]:t} == release.yml ]]
+grep -q 'workflow_run:' "$root/.github/workflows/release.yml"
+! grep -q 'pull_request_target:' "$root/.github/workflows/release.yml"
+grep -q 'ref: refs/heads/main' "$root/.github/workflows/release.yml"
+! grep -q 'ref:.*github.event.workflow_run.head_sha' "$root/.github/workflows/release.yml"
+
+git init --bare "$tmp/origin.git" >/dev/null
+git clone "$tmp/origin.git" "$tmp/repository" >/dev/null 2>&1
+git -C "$tmp/repository" config user.email release-test@example.invalid
+git -C "$tmp/repository" config user.name 'Release Test'
+print base > "$tmp/repository/file"
+git -C "$tmp/repository" add file
+git -C "$tmp/repository" commit -m 'chore: base' >/dev/null
+print release >> "$tmp/repository/file"
+git -C "$tmp/repository" commit -am 'fix: candidate' >/dev/null
+git -C "$tmp/repository" branch -M main
+git -C "$tmp/repository" push -u origin main >/dev/null 2>&1
+target=$(git -C "$tmp/repository" rev-parse HEAD)
+print notes > "$tmp/notes.md"
+
+mkdir "$tmp/bin"
+cat > "$tmp/bin/gh" <<'FAKE_GH'
+#!/usr/bin/env zsh
+state=${FAKE_RELEASE_STATE:?}
+if [[ $1 == release && $2 == view ]]; then
+  [[ -e $state ]]
+  exit $?
+fi
+if [[ $1 == release && $2 == create ]]; then
+  [[ ! -e $state ]] || exit 1
+  print -r -- "$3" > "$state"
+  exit 0
+fi
+exit 2
+FAKE_GH
+chmod +x "$tmp/bin/gh"
+
+publish() {
+  (
+    cd "$tmp/repository"
+    PATH="$tmp/bin:$PATH" \
+      GITHUB_REPOSITORY=z-shell/zi \
+      RELEASE_TAG=v1.0.0 \
+      RELEASE_TARGET=$target \
+      RELEASE_NOTES_FILE=$tmp/notes.md \
+      FAKE_RELEASE_STATE=$tmp/release-state \
+      zsh -f "$root/scripts/publish-promotion-release.zsh"
+  )
+}
+
+publish >/dev/null
+[[ $(git --git-dir="$tmp/origin.git" cat-file -t refs/tags/v1.0.0) == tag ]]
+[[ $(git --git-dir="$tmp/origin.git" rev-parse 'refs/tags/v1.0.0^{}') == $target ]]
+[[ $(<"$tmp/release-state") == v1.0.0 ]]
+
+first_tag=$(git --git-dir="$tmp/origin.git" rev-parse refs/tags/v1.0.0)
+publish >/dev/null
+[[ $(git --git-dir="$tmp/origin.git" rev-parse refs/tags/v1.0.0) == $first_tag ]]
+
+git -C "$tmp/repository" tag -a v1.0.1 -m v1.0.1 "${target}^"
+git -C "$tmp/repository" push origin refs/tags/v1.0.1 >/dev/null 2>&1
+(
+  cd "$tmp/repository"
+  PATH="$tmp/bin:$PATH" \
+    GITHUB_REPOSITORY=z-shell/zi \
+    RELEASE_TAG=v1.0.1 \
+    RELEASE_TARGET=$target \
+    RELEASE_NOTES_FILE=$tmp/notes.md \
+    FAKE_RELEASE_STATE=$tmp/other-release-state \
+    zsh -f "$root/scripts/publish-promotion-release.zsh"
+) >/dev/null 2>&1 && { print -u2 -- 'expected conflicting tag target to fail'; exit 1; }
+
+print 'promotion release publication tests passed'
diff --git a/tests/promotion-release-verification.zsh b/tests/promotion-release-verification.zsh
new file mode 100644
index 00000000..74e3dff3
--- /dev/null
+++ b/tests/promotion-release-verification.zsh
@@ -0,0 +1,110 @@
+#!/usr/bin/env zsh
+
+emulate -L zsh
+setopt err_exit no_unset pipe_fail
+
+root=${0:A:h:h}
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/zi-promotion-release-test.XXXXXX")
+trap 'rm -rf -- "$tmp"' EXIT HUP INT TERM
+
+git init --bare "$tmp/origin.git" >/dev/null
+git clone "$tmp/origin.git" "$tmp/repository" >/dev/null 2>&1
+git -C "$tmp/repository" config user.email release-test@example.invalid
+git -C "$tmp/repository" config user.name 'Release Test'
+print base > "$tmp/repository/file"
+git -C "$tmp/repository" add file
+git -C "$tmp/repository" commit -m 'chore: base' >/dev/null
+git -C "$tmp/repository" branch -M main
+git -C "$tmp/repository" push -u origin main >/dev/null 2>&1
+base=$(git -C "$tmp/repository" rev-parse HEAD)
+
+git -C "$tmp/repository" switch -c next >/dev/null 2>&1
+print feature >> "$tmp/repository/file"
+git -C "$tmp/repository" commit -am 'fix: release candidate' >/dev/null
+head=$(git -C "$tmp/repository" rev-parse HEAD)
+git -C "$tmp/repository" push -u origin next >/dev/null 2>&1
+git -C "$tmp/repository" switch main >/dev/null 2>&1
+git -C "$tmp/repository" merge --no-ff next -m 'chore: promote next to main' >/dev/null
+target=$(git -C "$tmp/repository" rev-parse HEAD)
+git -C "$tmp/repository" push origin main >/dev/null 2>&1
+
+mkdir "$tmp/bin"
+cat > "$tmp/bin/gh" <<'FAKE_GH'
+#!/usr/bin/env zsh
+if [[ $* == *'/commits/'*'/pulls'* ]]; then
+  if [[ ${FAKE_PR_MODE:-valid} == missing ]]; then
+    print -r -- '[]'
+    exit 0
+  fi
+  source=${FAKE_PR_SOURCE:-next}
+  print -r -- "[{\"number\":600,\"merged_at\":\"2026-09-20T00:00:00Z\",\"merge_commit_sha\":\"${FAKE_TARGET}\",\"base\":{\"ref\":\"main\"},\"head\":{\"ref\":\"${source}\",\"sha\":\"${FAKE_HEAD}\",\"repo\":{\"full_name\":\"z-shell/zi\"}}}]"
+  exit 0
+fi
+
+mode=${FAKE_WORKFLOW_MODE:-success}
+names=( Zsh 'ZD Integration' CodeQL 'Trunk Code Quality' )
+print -n -r -- '{"workflow_runs":['
+separator=''
+id=10
+for name in "${names[@]}"; do
+  [[ $mode == missing && $name == 'ZD Integration' ]] && continue
+  run_status=completed
+  run_conclusion=success
+  [[ $mode == pending && $name == CodeQL ]] && { run_status=in_progress; run_conclusion=''; }
+  [[ $mode == failure && $name == 'Trunk Code Quality' ]] && run_conclusion=failure
+  print -n -r -- "${separator}{\"id\":${id},\"name\":\"${name}\",\"head_branch\":\"main\",\"head_sha\":\"${FAKE_TARGET}\",\"status\":\"${run_status}\",\"conclusion\":\"${run_conclusion}\"}"
+  separator=,
+  (( id += 1 ))
+done
+print -r -- ']}'
+FAKE_GH
+chmod +x "$tmp/bin/gh"
+
+run_verifier() {
+  local mode=${1:-success} source=${2:-next} pr_mode=${3:-valid}
+  local output=$tmp/output
+  : > "$output"
+  (
+    cd "$tmp/repository"
+    PATH="$tmp/bin:$PATH" \
+      GITHUB_OUTPUT=$output \
+      GITHUB_REPOSITORY=z-shell/zi \
+      PROMOTION_SHA=$target \
+      FAKE_TARGET=$target \
+      FAKE_HEAD=$head \
+      FAKE_WORKFLOW_MODE=$mode \
+      FAKE_PR_SOURCE=$source \
+      FAKE_PR_MODE=$pr_mode \
+      zsh -f "$root/scripts/verify-promotion-release.zsh"
+  )
+}
+
+expect_fail() {
+  if run_verifier "$@" >/dev/null 2>&1; then
+    print -u2 -- "expected promotion verification to fail: $*"
+    return 1
+  fi
+}
+
+expect_fail success feature valid
+expect_fail success next missing
+expect_fail failure next valid
+run_verifier missing >/dev/null
+grep -q '^ready=false$' "$tmp/output"
+run_verifier pending >/dev/null
+grep -q '^ready=false$' "$tmp/output"
+run_verifier success >/dev/null
+grep -q '^ready=true$' "$tmp/output"
+grep -q '^promotion_pr=600$' "$tmp/output"
+
+print moved >> "$tmp/repository/file"
+git -C "$tmp/repository" commit -am 'chore: move main' >/dev/null
+git -C "$tmp/repository" push origin main >/dev/null 2>&1
+expect_fail success next valid
+
+GITHUB_REPOSITORY=other/repo PROMOTION_SHA=$target \
+  PATH="$tmp/bin:$PATH" zsh -f "$root/scripts/verify-promotion-release.zsh" \
+  >/dev/null 2>&1 && { print -u2 -- 'expected repository mismatch to fail'; exit 1; }
+
+[[ $(git -C "$tmp/repository" rev-parse "${target}^1") == $base ]]
+print 'promotion release verification tests passed'
diff --git a/tests/release-plan.zsh b/tests/release-plan.zsh
new file mode 100644
index 00000000..33118cae
--- /dev/null
+++ b/tests/release-plan.zsh
@@ -0,0 +1,71 @@
+#!/usr/bin/env zsh
+
+emulate -L zsh
+setopt err_exit no_unset pipe_fail
+
+root=${0:A:h:h}
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/zi-release-plan-test.XXXXXX")
+trap 'rm -rf -- "$tmp"' EXIT HUP INT TERM
+
+git init "$tmp/repository" >/dev/null
+git -C "$tmp/repository" config user.email release-test@example.invalid
+git -C "$tmp/repository" config user.name 'Release Test'
+print initial > "$tmp/repository/file"
+git -C "$tmp/repository" add file
+git -C "$tmp/repository" commit -m 'chore: initial commit' >/dev/null
+git -C "$tmp/repository" tag -a v1.2.3 -m v1.2.3
+
+run_plan() {
+  local output=$tmp/output notes=$tmp/notes body=$tmp/body
+  (
+    cd "$tmp/repository"
+    RELEASE_PLAN_OUTPUT=$output RELEASE_NOTES_FILE=$notes \
+      zsh -f "$root/scripts/release-plan.zsh" HEAD > "$body"
+  )
+}
+
+value() {
+  sed -n "s/^$1=//p" "$tmp/output"
+}
+
+commit() {
+  print -r -- "$1" >> "$tmp/repository/file"
+  git -C "$tmp/repository" commit -am "$2" >/dev/null
+}
+
+commit docs 'docs: explain releases'
+run_plan
+[[ $(value release) == false && -z $(value tag) ]]
+
+commit fix 'fix(load): preserve explicit disk ices'
+run_plan
+[[ $(value release) == true && $(value tag) == v1.2.4 ]]
+grep -q '^### Fixes$' "$tmp/notes"
+grep -q 'fix(load): preserve explicit disk ices' "$tmp/notes"
+
+commit feature 'feat: add a compatible command'
+run_plan
+[[ $(value tag) == v1.3.0 ]]
+grep -q '^### Features$' "$tmp/notes"
+
+commit breaking $'feat!: replace command output\n\nBREAKING CHANGE: callers must migrate'
+run_plan
+[[ $(value tag) == v2.0.0 ]]
+grep -q '^### Breaking changes$' "$tmp/notes"
+grep -q 'Candidate commit' "$tmp/body"
+
+git -C "$tmp/repository" branch previous-next HEAD
+git -C "$tmp/repository" switch -c stable v1.2.3 >/dev/null 2>&1
+git -C "$tmp/repository" merge --no-ff previous-next -m 'chore: promotion merge' >/dev/null
+git -C "$tmp/repository" tag -a v2.0.0 -m v2.0.0
+git -C "$tmp/repository" switch -C next previous-next >/dev/null 2>&1
+commit post-release-fix 'fix: change after a promotion tag'
+run_plan
+[[ $(value previous_tag) == v2.0.0 && $(value tag) == v2.0.1 ]]
+grep -q 'fix: change after a promotion tag' "$tmp/notes"
+if grep -q 'docs: explain releases' "$tmp/notes"; then
+  print -u2 -- 'release notes crossed the previous promotion boundary'
+  exit 1
+fi
+
+print 'release plan tests passed'
diff --git a/zi.zsh b/zi.zsh
index 6f132a27..d209cf50 100644
--- a/zi.zsh
+++ b/zi.zsh
@@ -2540,7 +2540,8 @@ return retval
   }
   (( ___has_plugin || ___has_snippet )) || return 1
   if [[ $___type == snippet ]] {
-    (( ___has_snippet )) && ___path="$___snippet_path" || ___path="$___plugin_path"
+    (( ___has_snippet )) || return 1
+    ___path="$___snippet_path"
   } else {
     if (( ___has_plugin && ___has_snippet )) && \
       [[ ${ZI[MUTE_WARNINGS]} != (1|true|on|yes) ]] {