fix(release): v1.21.1 긴급 업데이트 (#308)

.agents/skills/tablecloth-promote-stable/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: tablecloth-promote-stable
+description: Promote a tested TableCloth develop line to a stable X.Y.0 Retail release on main, including freeze, synchronization, merge, tagging, signing, publishing, and transition checks. Use when ending a Preview cycle.
+---
+
+# TableCloth 정식 버전 승격
+
+검증한 Preview 개발선을 `main`에 병합하고 `vX.Y.0` Retail로 게시합니다.
+
+## 승격 준비
+
+[`docs/BRANCHING.md`](../../../docs/BRANCHING.md), [`docs/RELEASE_CHANNELS.md`](../../../docs/RELEASE_CHANNELS.md), [`docs/RELEASING.md`](../../../docs/RELEASING.md)를 읽습니다. 목표 버전, 마지막 Preview, 미해결 차단 이슈와 릴리스 노트 범위를 확인합니다.
+
+새 기능 병합을 중지하고 최신 `main` 핫픽스를 `develop`에 반영합니다. `Directory.Build.Props`가 목표 `X.Y.0.0`을 유지하는지 확인합니다.
+
+## 최종 검증과 병합
+
+x64와 arm64 CI와 두 테스트 프로젝트를 완료합니다. TableCloth 본체와 그 밖의 호스트 시나리오는 호스트 Windows에서 스모크 테스트하고, Spork 게스트 시나리오만 Windows Sandbox 안에서 확인합니다. TableCloth와 Spork의 주요 실행 경로 및 업데이트 채널 동작을 확인합니다.
+
+검증을 통과하면 Pull Request로 `develop`을 `main`에 병합합니다. 정식 태그는 병합된 `origin/main` HEAD와 정확히 일치해야 합니다. Preview 태그가 가리키던 병합 전 커밋이나 로컬 전용 커밋에 태그하지 않습니다.
+
+## Retail 게시
+
+Retail 태그 Push 뒤 [`build.yml`](../../../.github/workflows/build.yml)의 Draft와 두 아키텍처 산출물을 확인합니다. [`tablecloth-sign-release`](../tablecloth-sign-release/SKILL.md)를 Retail 모드로 수행하고 [`tablecloth-verify-release`](../tablecloth-verify-release/SKILL.md)로 게시 전후 결과를 확인합니다.
+
+릴리스 노트에는 Preview 기간의 주요 기능, 호환성 영향, 알려진 문제와 마이그레이션 사항을 사용자 관점에서 정리합니다. Avalonia와 Native AOT처럼 이전 버전 대비 기반 기술이 바뀌었다면 실행 성능과 이후 플랫폼 확장에 미치는 범위를 함께 설명합니다.
+
+## 승격 이후 상태
+
+Preview 사용자가 Retail로 자동 전환된다고 가정하지 않습니다. 현재 수동 채널 전환 정책을 릴리스 노트와 지원 문서에 반영합니다.
+
+정식 게시와 후속 자동화를 확인한 뒤 다음 Minor 버전 개발 요청이 있으면 [`tablecloth-start-next-version`](../tablecloth-start-next-version/SKILL.md)을 수행합니다. `develop` 삭제나 재생성은 미병합 이력을 확인한 뒤 결정합니다.

.agents/skills/tablecloth-promote-stable/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Promote TableCloth Stable"
+  short_description: "Promote a Preview line to stable Retail"
+  default_prompt: "Use $tablecloth-promote-stable to promote this TableCloth version to Retail."

.agents/skills/tablecloth-release-hotfix/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: tablecloth-release-hotfix
+description: Deliver an urgent TableCloth Retail patch from main and forward-port the fix to develop without changing its next-minor version. Use for backward-compatible X.Y.Z fixes, not feature releases.
+---
+
+# TableCloth Retail 핫픽스
+
+현재 정식 버전의 호환성 문제를 `X.Y.Z` Retail 패치로 게시하고 수정 코드를 다음 Minor 버전에 전파합니다.
+
+## 패치 범위
+
+[`docs/BRANCHING.md`](../../../docs/BRANCHING.md)와 [`docs/RELEASING.md`](../../../docs/RELEASING.md)를 읽습니다. 최신 `origin/main`과 정식 Release를 확인하고 다음 Patch 번호를 선택합니다.
+
+긴급 수정이 새 공개 기능이나 호환되지 않는 변경을 포함하면 핫픽스로 게시하지 않습니다. 다음 Minor 또는 Major 버전 경로로 전환합니다.
+
+## 수정과 버전 커밋
+
+최신 `main`에서 `hotfix/X.Y.Z`를 만듭니다. 실제 수정과 회귀 테스트를 먼저 커밋하고 `Directory.Build.Props`의 Patch 변경을 별도 커밋으로 남깁니다. Revision은 `0`을 유지합니다.
+
+관련 단위 테스트를 실행합니다. TableCloth 본체와 그 밖의 호스트 시나리오는 호스트 Windows에서 스모크 테스트하고, Spork 게스트 시나리오만 Windows Sandbox 안에서 확인합니다. Pull Request를 통해 `main`에 병합하고 새 `origin/main` HEAD에만 Retail 태그를 생성합니다.
+
+## Retail 게시
+
+[`build.yml`](../../../.github/workflows/build.yml)이 생성한 Draft와 x64 및 arm64 `PublishPayload`를 확인합니다. [`tablecloth-sign-release`](../tablecloth-sign-release/SKILL.md)를 Retail 모드로 수행하고 [`tablecloth-verify-release`](../tablecloth-verify-release/SKILL.md)로 게시 전후 상태를 확인합니다.
+
+정식 게시 뒤 WinGet Pull Request와 Discord 공지의 실제 생성 결과를 확인합니다.
+
+## 다음 버전 순방향 전파
+
+`develop`이 존재하면 패치 코드 커밋을 즉시 전파합니다. 버전 변경 커밋은 전파하지 않으며 `develop`의 `X.(Y+1).0`을 유지합니다. 같은 회귀 테스트를 `develop`에서도 실행합니다.
+
+브랜치 정리는 병합, Retail 게시와 순방향 전파를 모두 확인한 뒤 수행합니다. 이전 버전 유지보수 계획이 남아 있으면 관련 브랜치를 보존합니다.

.agents/skills/tablecloth-release-hotfix/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release TableCloth Hotfix"
+  short_description: "Deliver and forward-port a Retail hotfix"
+  default_prompt: "Use $tablecloth-release-hotfix to deliver this TableCloth Retail patch."

.agents/skills/tablecloth-release-preview/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tablecloth-release-preview
+description: Prepare and publish a TableCloth Preview from develop with a strict preview.N tag, native x64 and arm64 CI artifacts, local signing, and prerelease verification. Use for Preview releases, not Retail patches or stable promotion.
+---
+
+# TableCloth Preview 릴리스
+
+`develop`의 다음 Minor 버전을 `vX.Y.0-preview.N` Prerelease로 게시합니다.
+
+## 준비 상태
+
+[`docs/BRANCHING.md`](../../../docs/BRANCHING.md), [`docs/RELEASE_CHANNELS.md`](../../../docs/RELEASE_CHANNELS.md), [`docs/RELEASING.md`](../../../docs/RELEASING.md)를 읽습니다. 다음 조건을 확인합니다.
+
+- 대상 커밋이 `origin/develop` 이력에 포함됨
+- 최신 `main` 핫픽스가 `develop`에 반영됨
+- `Directory.Build.Props`가 목표 버전 코어와 일치함
+- 로컬 빌드와 관련 테스트가 성공함
+- 기존 Preview 태그에서 다음 번호를 계산함
+
+태그는 `^v[0-9]+\.[0-9]+\.[0-9]+-preview\.[1-9][0-9]*$` 형식만 허용합니다. 게시하거나 삭제한 Preview 번호를 재사용하지 않습니다.
+
+## CI Draft 생성
+
+사용자가 Preview 릴리스를 실행하도록 요청했다면 태그를 생성하고 Push합니다. [`preview.yml`](../../../.github/workflows/preview.yml)의 x64와 arm64 Job, Draft Prerelease 생성, 두 `PublishPayload` 아티팩트를 확인합니다.
+
+CI가 실패하면 태그를 이동하지 않습니다. 원인을 새 커밋에서 수정하고 다음 Preview 번호를 사용합니다.
+
+## 서명과 게시
+
+CI Draft가 성공하면 [`tablecloth-sign-release`](../tablecloth-sign-release/SKILL.md)를 읽고 Preview 모드로 수행합니다. `--preview-number`에는 태그의 `N`을 전달합니다.
+
+서명 뒤 [`tablecloth-verify-release`](../tablecloth-verify-release/SKILL.md)를 읽고 Preview 자산, Preview 채널 메타데이터와 Prerelease 상태를 검증합니다. 검증을 통과하고 사용자가 게시까지 요청했다면 Draft를 Prerelease로 게시합니다.
+
+Preview에는 WinGet 제출, Discord 정식 공지, 무설치 고정 URL 별칭을 만들지 않습니다. Preview를 최신 정식 Release로 지정하지 않습니다.
+
+완료 보고에는 태그, Release URL, CI 실행, 서명 검증과 알려진 제한을 포함합니다.

.agents/skills/tablecloth-release-preview/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release TableCloth Preview"
+  short_description: "Build and publish a signed Preview release"
+  default_prompt: "Use $tablecloth-release-preview to publish the next signed TableCloth Preview."

.agents/skills/tablecloth-release/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: tablecloth-release
+description: Orchestrate the TableCloth branch, version, Preview, hotfix, signing, stable promotion, and post-release lifecycle. Use for end-to-end release management requests; use a narrower TableCloth child skill when the request covers only one phase.
+---
+
+# TableCloth 릴리스 오케스트레이션
+
+TableCloth의 다음 버전 개발 시작부터 정식 게시까지 단계별 상태를 관리합니다. 이 스킬은 작업을 직접 포괄하기보다 필요한 하위 스킬을 선택하고 완료 조건을 연결합니다.
+
+## 기준 문서
+
+작업을 시작할 때 다음 문서를 읽습니다.
+
+- [`docs/BRANCHING.md`](../../../docs/BRANCHING.md): 브랜치 역할과 버전 증가 기준
+- [`docs/RELEASE_CHANNELS.md`](../../../docs/RELEASE_CHANNELS.md): Retail과 Preview 채널 계약
+- [`docs/RELEASING.md`](../../../docs/RELEASING.md): CI Draft, SimplySign 서명과 게시 절차
+
+문서와 실제 워크플로가 다르면 `.github/workflows`, `build.cs`, `Directory.Build.Props`의 현재 동작을 확인하고 차이를 보고합니다. 확인하지 않은 문서 설명을 현재 구현으로 단정하지 않습니다.
+
+## 상태 확인
+
+다음 항목으로 현재 릴리스 단계를 판별합니다.
+
+- 현재 브랜치와 작업 트리
+- `origin/main`과 `origin/develop`의 존재 및 선후 관계
+- 최신 정식 태그와 Preview 태그
+- `Directory.Build.Props`의 버전 코어
+- GitHub Release의 Draft, Prerelease와 게시 상태
+- 관련 GitHub Actions 실행 결과
+
+검토나 계획만 요청받았다면 외부 상태를 변경하지 않습니다. 릴리스 실행을 요청받았다면 태그 Push, Draft 생성, 서명 자산 업로드와 게시를 요청 범위에 맞추어 이어갑니다.
+
+## 하위 스킬 선택
+
+선택한 하위 스킬의 `SKILL.md`를 작업 전에 모두 읽습니다.
+
+| 요청 | 하위 스킬 |
+| --- | --- |
+| 다음 Minor 버전 개발 시작 | [`tablecloth-start-next-version`](../tablecloth-start-next-version/SKILL.md) |
+| Preview 생성과 게시 | [`tablecloth-release-preview`](../tablecloth-release-preview/SKILL.md) |
+| 현재 Retail 긴급 패치 | [`tablecloth-release-hotfix`](../tablecloth-release-hotfix/SKILL.md) |
+| Preview의 정식 승격 | [`tablecloth-promote-stable`](../tablecloth-promote-stable/SKILL.md) |
+| CI 산출물의 로컬 서명 | [`tablecloth-sign-release`](../tablecloth-sign-release/SKILL.md) |
+| 게시 전후 검증 | [`tablecloth-verify-release`](../tablecloth-verify-release/SKILL.md) |
+
+Preview 릴리스는 Preview 스킬, 서명 스킬, 검증 스킬 순서로 진행합니다. 핫픽스와 정식 승격도 각 준비 스킬 뒤에 서명과 검증 스킬을 연결합니다.
+
+## 공통 불변 조건
+
+- Retail 태그는 `origin/main` HEAD와 정확히 일치합니다.
+- Preview 태그는 `origin/develop` 이력에 포함됩니다.
+- Preview 태그는 `vX.Y.Z-preview.N` 형식을 사용합니다.
+- `Directory.Build.Props`의 코어 버전과 태그 코어를 일치시킵니다.
+- x64와 arm64 산출물을 모두 확보하고 모든 서명 검증을 통과한 뒤 게시합니다.
+- Retail 핫픽스를 `develop`으로 전파하면서 다음 Minor 버전을 유지합니다.
+- Preview 게시에서는 WinGet과 Discord 자동화를 실행하지 않습니다.
+- Retail 게시에서는 WinGet Pull Request와 Discord 공지의 실제 결과를 각각 확인합니다.
+
+## 중단 조건
+
+서명 실패, 아키텍처 누락, 태그와 브랜치 불일치, 버전 불일치, 부분 업로드가 발견되면 Draft를 유지하고 원인을 보고합니다. 이미 외부에 Push한 태그를 다른 커밋으로 이동하지 않습니다. 게시 권한이 요청에 포함되지 않았다면 서명과 검증 결과까지만 제공합니다.

.agents/skills/tablecloth-release/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TableCloth Release"
+  short_description: "Orchestrate version development and releases"
+  default_prompt: "Use $tablecloth-release to manage this TableCloth release lifecycle."

.agents/skills/tablecloth-sign-release/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: tablecloth-sign-release
+description: Repackage and Authenticode-sign TableCloth and Spork x64 and arm64 CI payloads with the local SimplySign certificate, then replace and verify draft release assets. Use only after a release CI draft succeeds.
+---
+
+# TableCloth 릴리스 산출물 서명
+
+CI가 만든 x64와 arm64 게시 산출물을 로컬 SimplySign 인증서로 전체 서명하고 GitHub Draft 자산을 교체합니다.
+
+## 입력 검증
+
+[`docs/RELEASING.md`](../../../docs/RELEASING.md)의 로컬 서명 절차를 읽습니다. 다음 입력을 확인합니다.
+
+- 대상 태그와 Retail 또는 Preview 구분
+- 성공한 CI 실행과 Draft Release
+- `PublishPayload-x64`와 `PublishPayload-arm64`
+- 태그 코어와 `Directory.Build.Props`의 일치
+- Preview라면 태그에서 추출한 Preview 번호
+- SimplySign 세션과 개인 키를 포함한 로컬 인증서
+
+인증서 개인 키나 PFX를 복사하거나 저장소와 CI에 업로드하지 않습니다. 인증서 주체는 현재 로컬 인증서에서 확인하며 문서에 고정된 이름을 가정하지 않습니다.
+
+## 안전한 작업 디렉터리
+
+`git rev-parse --show-toplevel`로 저장소 루트를 확인합니다. 정리 대상은 해당 루트 아래의 생성물인 `publish`와 `Releases`, 그리고 작업별 임시 아티팩트 디렉터리로 제한합니다. 계산한 경로가 저장소 루트 또는 임시 디렉터리 안에 있는지 확인한 뒤 제거합니다.
+
+두 `PublishPayload`를 내려받아 `publish` 계약에 맞게 합칩니다. TableCloth와 Spork의 x64 및 arm64 폴더가 모두 존재하지 않으면 중단합니다.
+
+## 패키징과 서명
+
+Retail은 `build.cmd --skip-build --sign`을 사용합니다. Preview는 `--preview --preview-number N`을 추가하며 `N`을 태그에서 추출합니다. 수동 기본값에 의존하지 않습니다.
+
+패키징 로그에서 TableCloth와 Spork의 앱 바이너리, `Update.exe`, `Setup.exe` 서명을 확인합니다. 로컬에서 빌드할 수 없는 arm64 Native AOT 코드는 CI 페이로드를 사용하고 x64 호스트에서는 패키징과 서명만 수행합니다.
+
+## 업로드와 검증
+
+자산을 파일별로 `gh release upload --clobber`하여 부분 실패를 식별합니다. 각 파일을 최대 세 번 재시도하고 계속 실패하면 Draft를 유지합니다.
+
+원격 자산 이름과 크기를 로컬 결과와 비교합니다. 모든 `.exe` 자산과 Portable ZIP 내부 앱 바이너리의 Authenticode 상태가 `Valid`인지 확인합니다. 한 항목이라도 누락되거나 서명이 유효하지 않으면 `UNSIGNED` 경고를 제거하거나 Release를 게시하지 않습니다.
+
+완료 보고에는 사용한 CI 실행, 두 아키텍처의 산출물 수, 서명 검증 결과와 업로드 대조 결과를 포함합니다. 인증서의 민감한 정보는 출력하지 않습니다.

.agents/skills/tablecloth-sign-release/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Sign TableCloth Release"
+  short_description: "Sign x64 and arm64 release artifacts"
+  default_prompt: "Use $tablecloth-sign-release to sign and replace the draft assets for this release."

.agents/skills/tablecloth-start-next-version/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: tablecloth-start-next-version
+description: Start development of the next TableCloth minor version on develop, including version selection, branch preparation, version-source updates, and baseline verification. Use when beginning a new minor cycle, not for a patch or an existing Preview release.
+---
+
+# TableCloth 다음 버전 개발 시작
+
+최신 Retail을 기준으로 다음 Minor 버전의 `develop` 브랜치와 버전 코어를 준비합니다.
+
+## 기준 확인
+
+[`docs/BRANCHING.md`](../../../docs/BRANCHING.md)를 읽고 다음 상태를 현재 저장소와 원격에서 확인합니다.
+
+- 최신 게시 Retail 태그와 `origin/main` HEAD
+- 기존 `origin/develop`의 존재와 미병합 커밋
+- `Directory.Build.Props`의 현재 버전
+- 작업 트리와 서브모듈 상태
+
+최신 정식 버전이 `X.Y.Z`라면 기본 다음 버전은 `X.(Y+1).0`입니다. 사용자가 다른 목표 버전을 지정하면 SemVer 증가 방향과 현재 브랜치 정책의 충돌 여부를 먼저 검토합니다.
+
+## 브랜치와 버전 준비
+
+기존 `develop`이 없으면 최신 `origin/main`에서 만듭니다. 기존 브랜치가 있으면 덮어쓰지 않고 `main`과의 선후 관계 및 미병합 작업을 확인합니다.
+
+`Directory.Build.Props`에서 Major, Minor, Patch와 Revision을 목표 버전에 맞춥니다. 다음 Minor 버전은 Patch와 Revision을 `0`으로 둡니다. Preview 접미사는 이 파일에 넣지 않습니다.
+
+버전 변경은 기능 변경과 분리한 커밋으로 남깁니다. 원격 Push나 Pull Request 생성은 사용자가 개발 착수를 실행하도록 요청한 범위에서만 수행합니다.
+
+## 기준선 검증
+
+서브모듈을 초기화한 뒤 저장소의 전체 빌드와 두 테스트 프로젝트를 실행합니다. 기능 변경 전 실행 기준선이 필요하면 TableCloth 본체를 호스트 Windows에서 스모크 테스트합니다. Spork 게스트 시나리오를 검증할 때만 Windows Sandbox 안에서 실행합니다.
+
+완료 보고에는 다음 내용을 포함합니다.
+
+- 목표 버전과 브랜치
+- 버전 변경 커밋
+- 빌드와 테스트 결과
+- 원격 Push 또는 Pull Request 상태
+- 첫 Preview를 만들기 전에 남은 작업

.agents/skills/tablecloth-start-next-version/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Start TableCloth Version"
+  short_description: "Start the next TableCloth minor version"
+  default_prompt: "Use $tablecloth-start-next-version to begin the next TableCloth minor cycle."