/release

name: release
description: Release for this repo — CalVer tag + narrative prepend.
allowed-tools: Read, Write, Edit, Bash(gh *), Bash(git *), AskUserQuestion

Release (project-local)

Creates a CalVer tagged release with a hand-written narrative prepended to the body CI generates via `scripts/package.js`. Overrides the global `/release` skill for this repo.

Purpose

• Push CalVer tag → CI (`release.yml`) runs `scripts/package.js` to build ZIPs + produce `dist/release-notes.md`, then `gh release create --draft --notes-file` attaches it
• Prepend a hand-written narrative block to the script-generated body so the release surfaces "why this release matters" before the commit list
• Leave publish (draft → published) to the user for manual review

Preconditions

• Working tree clean, on `main` (or user-specified branch)
• `gh` authenticated with push access to the target remote (fork or upstream)
• Node 22+ on PATH (packaging requires `zlib.crc32`)

Flow

Phase 1: Tag decision

• Previous tag: `git describe --tags --abbrev=0` (excludes drafts, gives last tagged commit)
• Today: derive `YYYY.MM.DD` from current date
• Candidate tag: `v{YYYY.MM.DD}`, or `v{YYYY.MM.DD}.{N+1}` if same-day tag exists
• If latest tag is already today's and is Draft (not published), ask whether to re-tag (delete + recreate) or increment `.N`

Phase 2: Tag push

• `git tag <tag>`
• `git push origin <tag>` → triggers `release.yml`

Phase 3: Wait for CI draft

• Poll `gh run list --workflow=release.yml --limit 1 --json status,conclusion,databaseId` every 5s, max 12 attempts (60s total)
• When `status=completed` and `conclusion=success`, fetch draft: `gh release view <tag> --json body,url`
• If still `in_progress` after 60s: surface run URL and ask user whether to keep waiting
• If CI fails: surface logs via `gh run view <id> --log-failed`, do not proceed to Phase 4. Remediation: fix the cause and retag with `.N` increment, or clean up the pushed tag with `git push origin :refs/tags/<tag>` before retrying

Phase 4: Narrative drafting

Analyze commits since previous tag — each line is one merged PR; read a PR's own commits with `git log <merge>^1..<merge>^2` when its detail is needed:

git log --oneline --first-parent <prev-tag>..HEAD

Select 3-4 highest-impact changes. Prioritize:

• New skills or protocols (`feat:` with new `SKILL.md`)
• Architectural principles (`rules/`, `CLAUDE.md`, axiom tier changes)
• User-facing behavior changes
• Cross-cutting refactors that affect multiple protocols

Deprioritize:

• Single-PR review-round commits, CI test count bumps, version bumps without content
• Commits whose only effect is subsumed by a broader commit in the same range

**Theme axis enumeration** (conditional on commit set complexity):

When the commit set admits multiple plausible theme axes — distinct ways to group the same commits under different unifying frames — enumerate ALL axes before drafting. Trigger: no single dominant change carries the release on its own; 5+ semantically distinct change clusters in the commit range is a heuristic signal of this condition, not the trigger by itself.

For each candidate axis, present as a numbered list (text output, not a gate option set — the user's response is free-form selection, supplement, or a new axis):

• **Theme line**: the unifying frame the axis would emphasize
• **Foregrounds**: which commits become the narrative centerpiece
• **Backgrounds**: which commits become accompanying detail
• **Trade-off signal**: structural strength (faithful to commit shape) vs. interpretive weight (post-hoc grouping)

Include a brief epistemic observation on which axes preserve the commit set's actual shape vs. which apply heavier grouping. When the commit set admits a single dominant theme — one frame is uniquely the best fit and other framings would feel like post-hoc reframing — skip axis enumeration and proceed directly to drafting.

After enumeration, draft narrative using the axis the agent judges best-fit; the gate at Phase 5 lets the user pick a different axis if preferred.

Draft narrative using this template (Korean, matching repo's PR body convention):

> **Background**
>
> {experiential / contextual narrative — the lived origin and why this release matters; 1-3 paragraphs. Background IS pure context — the theme sentence belongs in the 무엇이 새로운가요? section below.}
>
> ---
>
> **무엇이 새로운가요?**
>
> 이번 릴리스의 핵심은 **{theme}** — {one sentence summarizing the release}.
>
> - {emoji} **`/command`** 또는 **{feature name}** — {user-facing narrative, 1-2 sentences}
> - {emoji} **...** — ...
> - {emoji} **...** — ...
> - {emoji} **...** — ...
>
> ---

{script-generated body, with its leading `# Epistemic Protocols vX` H1 line removed so it starts at `## Highlights`}

The narrative splits into two blockquoted sections, matching the repo's prior-release convention:

• **Background** — pure experiential/contextual narrative (the lived origin). The label is English `**Background**`, an exception to the Korean-narrative convention kept for visual continuity across releases. The change-section label `**무엇이 새로운가요?**` stays Korean.
• **무엇이 새로운가요?** — leads with the theme sentence (`이번 릴리스의 핵심은 **{theme}** — ...`), then the change bullets.

Both sections, and the close before the script body, are bounded by in-blockquote dividers (`> ---`). Each `> ---` must be preceded by a blank `>` line: in CommonMark a `---` placed flush against paragraph text parses as a setext H2 underline, which would render the preceding line as a heading instead of a divider — the blank `>` line keeps it a thematic break.

The script body's leading `# Epistemic Protocols vX` H1 is stripped: the GitHub release title already renders the version, so a body H1 would surface a duplicate title. After stripping, the body begins at `## Highlights`.

Emoji selection is descriptive: choose an emoji whose visual semantic matches the change class. The same change class may take different