Task #37: v0.3.0 macOS app fallback and public documentation release

[postmelee]

요약

• 대상 타스크: M030: v0.3.0 macOS app fallback and public documentation release #37 M030 v0.3.0 release preparation
• 왜: PR #44의 macOS app bundle fallback은 backward-compatible capability addition이므로 기존 patch 계획을 minor release로 조정했습니다.
• 무엇: Package/CLI/SDK/app-server version surface를 0.3.0으로 일치시키고 resolver artifact, README sync baseline과 Trusted Publishing release gate를 검증했습니다.
• 리뷰 포인트: Product diff가 version source/test 7개로 제한되는지와 post-merge 별도 release 승인 경계를 확인해 주세요.

변경 내역

• Stage 1 (69f4097): Package, CLI/SDK, declaration과 app-server metadata를 0.3.0으로 일치시켰습니다.
• Stage 2 (89204fa): Full regression, npm artifact와 source/npm README sync baseline을 검증했습니다.
• Stage 3 (fa90bf4): Origin/product diff, strict preflight와 Trusted Publishing 보안 경계를 확정했습니다.

영향 영역

영역	변경	리뷰 포인트
Version surface	0.2.0에서 0.3.0으로 갱신	Package, CLI/SDK/type와 app-server metadata 일치
Release 운영	Post-merge Trusted Publishing runbook 확정	Tag 생성 전 별도 승인, GitHub Release 최종 생성 순서

작업 문서

• 수행 계획서: task_m030_37.md
• 구현 계획서: task_m030_37_impl.md
• 최종 보고서: task_m030_37_report.md

핵심 리뷰 포인트

• Product 변경은 version source/test 7개, 8 insertions/8 deletions뿐이며 PR Task #43: macOS Codex 앱 번들 실행 파일 자동 탐지 #44 resolver와 public docs는 재작성하지 않았습니다.
• Historical benchmark 0.2.0 marker를 유지하고 package artifact만 0.3.0으로 갱신했습니다.
• 이 PR은 release preparation만 수행합니다. Tag, publish workflow, npm 0.3.0과 GitHub Release는 merge 후 별도 승인 대상입니다.

검증

자동 검증

주제	검증 방법	결과	근거
전체 regression	npm test 및 strict preflight	OK	55/55 pass, fail/cancelled/skipped/todo 0
Focused regression	CLI/index/app-server/resolver test	OK	30/30 pass
npm artifact	npm pack --dry-run --json 구조 검사	OK	0.3.0, 18개 파일, 필수 파일 포함, 금지 경로 0
Version/document boundary	Exact literal 및 보호 경로 diff 검사	OK	Version 파일 7개만 변경, historical 0.2.0 유지
Trusted Publishing	Workflow permission/runtime와 sensitive pattern 검사	OK	OIDC 최소 권한, Node 24, token/provenance 비활성화 pattern 0
Strict preflight	npm run release:preflight -- --release-ready	OK	Tag 부재만 expected FAIL, 다른 9개 check 통과

수동/시나리오 검증

시나리오	확인 절차	결과	자료
Release mutation 차단	Local/remote tag, workflow dispatch, npm latest와 GitHub Release 상태 확인	OK	Stage 3 보고서

CI/원격 검증

항목	결과	근거
test	OK	GitHub Actions run, 12s pass
CodeQL actions	OK	CodeQL run, 43s pass
CodeQL JavaScript/TypeScript	OK	CodeQL run, 52s pass
origin/main 포함	OK	PR 게시 직전 behind 0
npm registry baseline	OK	2026-07-13 확인: version/latest 0.2.0
v0.3.0 release state	OK	Local/remote tag, publish dispatch, GitHub Release 모두 0

검증 한계

• Merge 후 main branch CI/CodeQL과 최종 merge SHA는 아직 확인할 수 없습니다.
• 실제 npm Trusted Publisher publish, registry propagation, npx, README, signature/provenance는 merge 후 별도 release 실행 승인 전에는 검증할 수 없습니다.
• 실제 account usage command는 privacy 경계를 위해 release preparation에서 실행하지 않았습니다.

관련 이슈

• 선행 구현: PR #44, Issue #43
• 동시 workflow 변경: PR #40, PR #41

후속 이슈 제안

• 없음. Post-merge release runbook과 Issue 종료는 #37에서 계속 추적합니다.

남은 리스크

• PR Bump actions/setup-node from 4 to 7 #40 또는 #41이 먼저 merge되면 tag 생성 전 main의 실제 publish workflow를 다시 검증해야 합니다.
• Publish 이후 검증 실패 시 0.3.0을 재게시하거나 tag를 이동하지 않고 Issue #37을 열린 상태로 유지해야 합니다.