---
name: release
metadata:
  version: "0.24.9"
description: Cut a versioned release — stamp the changelog, snapshot the roadmap, tag, create the platform release, publish, and sync. Use when asked to "cut a release", "ship vX.Y.Z", "tag a version", or when an unreleased changelog section is ready to go out.
---

# Release

A release is worklog work: record a release task first (work-track), and the
release leaves frozen artifacts behind — a dated changelog section, a roadmap
snapshot, a tag, and a platform release. No per-system code ships with this
skill; use the platform's own release tooling.

## 1. Preconditions

- Clean working tree on the default branch (or a release-prep branch about
  to merge into it).
- All test suites green locally; CI green on the tip.
- Version lockstep holds: the plugin manifest, `bin/worklog --version`, and
  every plugin skill's frontmatter agree (`tests/test_plugin.py` enforces it).
- The top CHANGELOG section reads `## X.Y.Z — unreleased` and describes what
  actually ships. If it doesn't, fix that first — release notes are written
  as features land, not reconstructed at tag time. When the section is missing
  or thin, `bin/worklog changelog-draft --version X.Y.Z` writes a starting
  draft from git log since the last tag (markdown on stdout, the commits it
  excluded on stderr). It is bullets, not release notes: edit the prose before
  stamping, and read the exclusion list to confirm nothing real was dropped.

## 2. Stamp

- CHANGELOG: change `— unreleased` to `— YYYY-MM-DD` (UTC, release date).
- `bin/worklog roadmap-snapshot --name vX.Y.Z-release` — the frozen picture
  of open work at release time. Snapshots are frozen; never regenerate.
- `bin/worklog ia-index` — sidecars the new snapshot (stamping its
  `release` and supersede chain), refreshes the inventory, and re-renders
  Home/Sidebar/Releases-index + publish manifest so the release is
  navigable. Commit `docs/.index/` with the snapshot.
- `bin/worklog trace-check --strict` — the pre-release evidence gate: every
  closed item must trace to a plan, ticket, and PR. Failures block the
  release; fix the links (`worklog link-pr`, sidecar `relates_to`) or
  consciously report the gaps to the human — never skip silently.
- `bin/worklog doc-verify --strict` — the pre-release citation gate: every
  document's code citations must resolve at the commit that document was
  written against. FABRICATED means wrong even in the tree the author had
  open — a real defect, fix it. DRIFT on a frozen document is expected and
  does not block; drift on `current_design_doc` / `current_code_walkthrough`
  does, because those claim to describe HEAD. `unresolvable` means the
  stamped commit is not in this clone (see ADR-0008) — report it, never
  re-check against HEAD.

## 3. Land it

Commit the stamp + snapshot on a release-prep branch and land it as a PR
(the branch guard hook refuses commits directly on the default branch --
main is pull-only). The release tags the commit that carries the dated
changelog.

## 4. Tag and platform release

- `git tag vX.Y.Z <commit>` on the landed commit; push the tag.
- Create the platform release with the CHANGELOG section as the notes:
  GitHub — `gh release create vX.Y.Z --title "vX.Y.Z" --notes-file <section>`;
  GitLab — `glab release create`; other systems — their CLI or MCP, or
  tag-only when the platform has no release object. Research, don't guess.

## 5. Doc sync — background agents

The moment the tag exists, spawn background subagents — the release NEVER
waits on prose. Read `release.sync_docs` in `.work/config.yml`; each listed
target gets regenerated and republished. Doc commits land on the default
branch AFTER the tag: docs describe the release, the tag does not wait for
them.

- **Agent A — design-docs skill, release mode**: regenerates
  `docs/designs/current_design_doc.md` + `current_code_walkthrough.md`
  against the tagged commit, freezes the dated pair
  (`<DATE>_<vX.Y.Z-release>_*.md`), publishes all four via wiki-publish.
- **Agent B — user-docs refresh**: diffs `vPREV..vX.Y.Z`, updates
  `docs/user_guide/*.md` and `README.md` wherever that diff made them stale
  (only targets named in `release.sync_docs`), then republishes changed wiki
  pages through the ledger.

Agents report when done; their commits reference the release work item.
Removing an entry from `release.sync_docs` opts that doc out — the list is
the contract, not this prose.

## 6. Publish and sync

- wiki-publish: the updated Roadmap and the release snapshot page; link the
  snapshot from Home.
- ticket-sync: close the release work item(s); anything shipped-and-closed
  reconciles with the tracker. Release items are local-only by convention —
  no external ticket is filed for them, so this step is a no-op for the
  release item itself. That's intentional, not a gap: the tag and platform
  release already give the release public visibility; don't file a
  redundant issue just to have something for ticket-sync to close.
- **Re-index after publishing, and commit the result.** Publishing writes the
  page's live wiki location back into the ledger, so the generated inventory
  is stale the moment the last page lands. Run `bin/worklog ia-index` and
  commit `docs/.index/` — the IA gates are hard now, and the next commit fails
  otherwise. One pass is enough: publishing adds only the wiki location to a
  record, which is not part of the render hash, so re-indexing never makes
  another page need republishing.

## 7. After

- `bin/worklog provenance-backfill` — stamps `merged_in` on frozen documents
  that have now landed on the default branch. A document cannot know the
  merge that will carry it, so this is the step that fills it in; run it on
  the post-release branch (this step already lands a commit) and run
  `worklog ia-index` alongside it in the SAME commit, or the freshness gate
  rejects the result. Frozen documents only, by design — a live document has
  been edited since it landed, so the merge that first carried it would name
  a version that no longer exists. Safe to re-run: it skips anything already
  stamped.

The next feature wave opens a new `## X.Y.Z — unreleased` section and bumps
the version lockstep in the same commit that adds the first feature.
Released changelog sections are frozen — corrections go in the next
release's notes, same rule as status reports.