Release

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:

git log --oneline <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 emoji across releases — match the release's framing, not a fixed table.