Release Checklist

---
name: release-checklist
description: Use when preparing to version, tag, publish, or recover a GitHub release whose CI and shipped artifacts must be proven.
compatibility: Windows 10/11; PowerShell 5.1 and Python 3; gh CLI authenticated.
metadata:
  version: 1.1.0
  updated: '2026-09-03'
  library: overseer-skyrim-agent-skills
  error_registry_revision: 4.3.0
---

# Release checklist

Run in order. Every item is mandatory — the ones that look redundant are the
ones that previously shipped broken releases. Nothing below depends on memory:
each step reads the repo's actual files.

## Default flow

Sync the live install through the ownership-aware installer (for skills only:
`powershell -NoProfile -ExecutionPolicy Bypass -File INSTALL-AIO.ps1 -SkillsOnly -SkipNativePlugins -SkipStarterSettings -SkipPreamble -SkipCleanup`).
Use the selected providers; preserve local override hashes and native-owned skills.
Sync the local bundle, then commit -> push -> converge CI
on the exact pushed SHA -> tag -> publish -> verify the shipped bytes (steps
5-7). A step that requires an application to be closed - Hermes profile
migration, an installer that rewrites provider config - is user-run by design:
print the exact command, say why it cannot run here, and never report it as
applied from inside the running app.

## 0. Prove the public surface

- Edited the pack's own preamble text (`3-PREAMBLES/SOUL.md`, `0-UNRESTRAINT-PACKS/AIO-INSTRUCTION.md`)?
  Copy the outgoing text into `3-PREAMBLES/history/` before committing - installed machines strip archived
  text exactly, so the edit converges them instead of stacking a second block.

For new repositories, also apply `github-fleet-maintenance`'s repository completion contract: real CI, applicable security settings, CodeQL/scanning and Dependabot must be verified separately from files merely existing. Resolve publication authorization from the current request and earlier approvals; prepare the release fully before asking if approval is still missing.

Before versioning, make the repository understandable and credible without requiring the user to open the source tree:

- one sentence saying what it does and who it is for;
- a real final-state hero screenshot or short demo near the top when the product has a visual surface;
- a small feature list, quick start, supported platform/requirements, and an honest current-status note;
- a compact gallery for distinct workflows, with alt text and captions that explain what each image proves;
- verification/test commands and results kept separate from unperformed runtime tests;
- authors, data/assets, licences, permissions, and source provenance; and
- no stale screenshots, placeholders, private paths, tokens, personal data, or claims unsupported by the shipped artifact;
- public copy stays true across releases: no version numbers, dates or counts on platform-locked pages (Nexus, Steam, itch, forums) - the version lives in the platform's version field and the changelog, and agent-editable surfaces are the only place per-release facts may be scattered. See `public-copy-durability`.

Inspect the rendered README/release page and the actual image pixels with `visual-verification`. A file existing is not visual proof.
If no real final-state screenshot is available, say so and provide a capture plan instead of inventing one.

## 1. Read the CI workflow before touching anything

    cat .github/workflows/*.yml

List every job and every command it runs. CI checks things the local gate does
NOT — treat the workflow as the contract. Common CI-only traps:

- A version-consistency script (`.github/scripts/check_versions.py`) that
  requires a **dated changelog file** per version (e.g.
  `docs/history/V7.X.Y-CHANGELOG.md`) in addition to the inline `CHANGELOG.md`.
- A manifest verifier (`.github/scripts/verify_manifest.py`) that hashes every
  tracked file — adding/removing/renaming a file without regenerating
  `MANIFEST.json` fails it.

## 2. Bump the version in EVERY place CI checks

    grep -rn '<old-version>' --include='*.md' --include='*.txt' \
      --include='*.ps1' --include='*.json' --include='*.toml' --include='*.py' .

Then read `check_versions.py` (if present) and satisfy its exact file list —
it names files a blind grep can miss (AIO banner vs state, CATALOG, dated
changelog). Create the dated changelog for the new version even if the entry
is three lines; its absence is the #1 CI failure.

## 3. Regenerate integrity manifests

If the repo has `MANIFEST.json` + a generator (`TOOLS/generate_manifest.py`):

    python TOOLS/generate_manifest.py .
    python .github/scripts/verify_manifest.py   # expect 0 missing / 0 mismatch

Regenerate after ANY file add/remove/rename, not just content edits. Run the
verifier — a manifest that "looks fine" but was never verified is not proof.

## 4. Run the local gate

    powershell -NoProfile -ExecutionPolicy Bypass -File TESTS/Test-Pack.ps1

A local PASS is necessary but NOT sufficient — see step 5.

## 5. Push, then converge CI for the exact pushed commit

**REQUIRED SUB-SKILL:** Use `ci-convergence`.

Record the exact pushed SHA and keep it as the release identity:

    SHA=$(git rev-parse HEAD)
    git push origin HEAD

Do not use "latest on main" as a proxy. Query workflow/check state for that
**exact pushed SHA**. GitHub CLI examples:

    gh run list --commit "$SHA" --json databaseId,headSha,status,conclusion,workflowName
    gh run watch <run-id> --exit-status
    gh api repos/{owner}/{repo}/commits/$SHA/check-runs

Wait through queued/in-progress states. Every required check must reach a
terminal successful/skipped state according to branch policy. If any required
check fails, inspect its job/log, fix the root cause, commit and push a NEW SHA,
and restart this section from that new SHA. Never tag, build a release, or end
the release task while the chosen SHA is pending or red.

## 6. Tag and build artifacts from the GREEN commit

    git tag -a vX.Y.Z -m '<summary>'
    git push origin vX.Y.Z
    powershell -NoProfile -ExecutionPolicy Bypass -File TOOLS/Build-Release.ps1

Build zips AFTER the fix. Artifacts built from a red commit stay broken even
if the tag is later moved.

## 7. Publish, then verify what actually shipped

    gh release create vX.Y.Z --title '...' --notes '...' <zip>... 
    gh release view vX.Y.Z --json tagName,targetCommitish,assets

Confirm the tag resolves to the exact green SHA from step 5 and EVERY asset name is present. Re-check the required checks for that SHA. A release is not done until the shipped assets and exact commit are both proven.

Download every published asset into a fresh temporary directory. Require it to exist and be nonempty, then compare its size and SHA-256 with the verified local build and checksum record. Two missing or empty values must never count as a match. A source-code ZIP generated by GitHub is not a substitute for a promised usable installer or binary.

## 8. If a release already shipped red (recovery)

1. Fix the cause, push, get CI green.
2. Prefer a new patch version that preserves the old release and shared tag.
3. Build and publish the new version when authorized; verify as in step 7.
4. Deleting a published release or rewriting its tag requires explicit authorization; ordinary maintenance does not authorize either.

## Why these exist (evidence)

- v7.7.13/7.7.14 CI failed: version bump missed the dated changelog file that
  `check_versions.py` requires. Local pack gate passed; CI did not.
- The release zips were built from the red commit and had to be deleted and
  rebuilt after the tag was force-moved to green.
- SkyrimForge v5.1.7: manifest hashed CRLF working-tree bytes while CI
  verifies LF — same class of failure (CI-only trap), same fix discipline.