---
task_id: task-2447
type: context
scope: task
created: 2026-05-04
updated: 2026-05-04
status: in-progress
---

# 맥락 노트: task-2447

**task**: task-2447

---

## 결정 근거

### 결정 1 — `extension-release.yml`을 workspace + InsuRo 양쪽 모두 배치
- 이유: task spec `allowed_resources`가 `/home/jay/workspace/.github/workflows/extension-release.yml`을 명시함. 그러나 `extension/` 디렉토리는 InsuRo 프로젝트(`/home/jay/projects/InsuRo/extension/`)에 있어, workspace 워크플로의 `paths: extension/**` 트리거는 동작 불가.
- 채택: 두 위치 모두에 파일 생성. workspace 버전은 `workflow_dispatch`만 가능하며 (트리거 paths가 매치되지 않음), InsuRo 버전이 실제 push 트리거를 담당.
- forbidden_paths에 InsuRo `.github/workflows/`는 명시되지 않음 → 추가 허용.

### 결정 2 — 기존 endpoint URL `/api/insuro/composite-design/extension-version` 유지
- 이유: 프론트엔드(`CompositeExtensionGuide.tsx`)가 이미 이 URL을 사용 중. 기존 테스트(`test_composite_ingest.py:73-83`)도 이 URL을 검증.
- task spec의 새 URL `/api/extension/latest-version`은 alias로 추가 (응답 schema는 spec에 맞춤: `version`, `download_url`, `released_at`, `release_notes_url`).
- 기존 endpoint도 새 응답 schema와 호환되도록 `latest_version` (legacy) 키 + `version` (신규) 키 모두 포함.

### 결정 3 — 버전 정보 소스: `extension/manifest.json` (서버 fs 직접 읽기)
- 이유: `extension/` 디렉토리는 InsuRo repo에 있고, 백엔드도 같은 repo에서 deploy됨. fs 직접 읽기가 GitHub API 호출보다 빠르고 인증 불필요.
- GitHub release URL은 manifest version으로 구성: `https://github.com/JonghyukJeon/InsuRo/releases/download/extension-v{version}/insuro-helper-{version}.zip`
- 5분 TTL 캐시: manifest mtime을 캐시 키로 활용 (변경 즉시 cache miss).

### 결정 4 — manifest 버전 0.4.0 → 0.4.1 bump (minor patch)
- 이유: 본 task는 sync 메커니즘 인프라 도입. 기능 추가가 아닌 버그 fix(박제) + 인프라. 0.4.1 patch가 적절.
- 0.5.0이었다면 task-2433 콘텐츠 변경을 동반해야 함 (forbidden — content.js 변경 금지).

### 결정 5 — `extension_version_bump.py --check` 모드 동작
- manifest.json version 추출 → popup.html에서 `v\d+\.\d+\.\d+` 패턴 검사 → 발견 시 FAIL (popup.html이 동적 표시로 전환됐는지 확인)
- `extension_version.json` (server config)의 `version`/`latest_version`이 manifest와 일치하는지 검사
- `--check` exit 1 = mismatch, exit 0 = OK
- `--sync` mode: extension_version.json을 manifest 기반으로 자동 갱신 (개발자가 수동 실행)

## 참조 자료

- task 명세: `/home/jay/workspace/memory/tasks/task-2447.md`
- 기존 endpoint: `/home/jay/projects/InsuRo/server/main.py:7912` (`composite_design_extension_version`)
- 기존 테스트: `/home/jay/projects/InsuRo/server/tests/test_composite_ingest.py:73`
- 프론트엔드 호출: `/home/jay/projects/InsuRo/src/pages/CompositeExtensionGuide.tsx:60`
- 정적 config 파일: `/home/jay/projects/InsuRo/server/config/extension_version.json` (현재 v0.1.0 박제)
- 회장 거버넌스: `system_governance_4layer.md`
- 선행 task: task-2423/2429/2433 (content.js mmlfcp fix), task-2440/2445 (ruleset)

## 주의사항

### Forbidden 파일 (절대 금지)
- `extension/content.js`, `background.js`, `inject.js` (task-2433 산출물 keep)
- `scripts/task_scope.py`, `pre_push_guard.py`, `qc_report_guard.py`, `guard.sh`
- `scripts/anu_confirm_bot/main.py`, `git-hooks/pre-push`
- `scripts/gemini_review_gate.py`, `gemini_feedback_loop.py`, `lock_in_verify.py`
- `scripts/auto_merge_controller.py`, `auto_merge_lock.py`
- workspace `.github/workflows/ci.yml`
- `dispatch.py`, `dashboard/**`, `teams/shared/**`, `CLAUDE.md`

### admin bypass 절대 금지
- 본 task PR도 ruleset 통과 후 merge
- 봇 자체 머지 금지 — `manual_after_full_enforcement`
- 회장 게이트키퍼 6 케이스 모두 PASS 시에만 .done.acked

### Sanitize gate
- 외부 AI(Codex) 호출 전 코드/문서에 PII가 없는지 확인. 본 task 코드는 PII 없음 (URL, version 문자열만 다룸).

### Worktree 정책
- InsuRo worktree: `/home/jay/projects/InsuRo/.worktrees/task-2447-dev5` (브랜치: `task/task-2447-dev5`)
- workspace는 worktree 미사용 (task-2439-dev1 브랜치에 진행 중인 dirty state — 본 task와 무관, 격리 필요)
- workspace 파일 수정 시 stash 먼저 또는 직접 main 체크아웃 후 신규 브랜치 사용 — 본 task에서는 workspace 파일 3개만 추가 (수정 0건)이므로 영향 최소

## 발견 이슈

### 이슈 1 — workspace는 다른 task의 dirty state에 있음
- workspace `git status`: branch task-2439-dev1, 수정 5+ 파일 (config/constants.json 등)
- 본 task는 workspace에 신규 파일만 추가 (수정 0건) → 충돌 없음
- 추가하는 파일: `scripts/extension_version_bump.py`, `tests/scripts/test_extension_version_bump.py`, `.github/workflows/extension-release.yml`
- 커밋은 task-2439-dev1 브랜치 수정사항을 건드리지 않도록 명시적 add만 사용