clean-architecture-frontend-template/docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md

# memento-frontend를 이 템플릿에서 파생시키기 — 설계서

- 작성일: 2026-09-20
- 대상 레포 (둘)
  - 템플릿: `/home/donghyeon/workspace/desktop-server-git/clean-architecture-frontend-template` (`develop`, 기준 커밋 `ec7f20e`)
  - 파생: `/home/donghyeon/workspace/desktop-server-git/memento-frontend` (`main`, 기준 커밋 `b35e17c`)
- 원격: 둘 다 같은 Gitea (`https://git.learn.hyeonworks.com/donghyeon.kang/...`)
- 이 문서는 설계만 한다. 소스 수정·빌드·테스트 실행 없음.

---

## 0. 요약 (먼저 읽을 것)

| 항목 | 판정 |
|---|---|
| 반영 방식 | **upstream 추적 부트스트랩**. 템플릿 히스토리를 memento에 머지하고 `upstream` 원격으로 남겨 계속 받아온다 |
| 추적 브랜치 | `upstream/main`. 그러려면 템플릿의 `main`을 먼저 `develop` 지점까지 올려야 한다 |
| `develop` → `main` | **fast-forward**. `main`은 `Initial commit` 1개뿐이고 `develop`의 조상이라 머지 커밋이 안 생긴다 |
| memento 초기 상태 | 템플릿 그대로 유지 + 식별자만 리브랜딩. `reference-feature`와 `/examples/*`는 **남긴다** |
| 템플릿 선수정 | builder/verifier ID를 `package.json`의 `name`에서 파생. 템플릿 자신의 산출물 문자열은 **불변** |
| 템플릿에 memento 흔적 | **없다.** 템플릿에 "memento"라는 문자열은 들어가지 않는다 |
| 최대 위험 | `pnpm install` 후 게이트가 memento에서도 통과하는지. 특히 `verify:release` 계열이 새 `name`으로 재계산된 ID를 일관되게 쓰는지 |

실행 순서는 되돌리기 어려운 것이 뒤에 오도록 잡았다: 템플릿 수정 → 게이트 → push → memento 머지 → 리브랜딩 → 게이트.

---

## 1. 확정된 결정 (사용자 승인 완료)

1. **반영 = upstream 추적 부트스트랩.** 1회성 스냅샷 복사안과 "동기화 스크립트만 만들기"안은 기각.
   근거: 템플릿이 계속 개선되는 레포이므로, 파생 시점에 끊기면 개선분을 수동 diff로 옮겨야 한다.
2. **추적 대상은 `upstream/main`.** (`develop`이 아니다.)
   따라서 템플릿의 `main`을 `develop` 지점까지 올리는 것이 선행 작업이다.
3. **memento 초기 상태는 "템플릿 그대로 + 리브랜딩만".**
   `reference-feature`와 `/examples/*`를 남긴다. 근거: (a) 살아있는 참조 구현이 남아 팀이 패턴을 보고 따라갈 수 있다, (b) 삭제하면 `INVENTORY.md`·테스트 레지스트리·e2e·a11y까지 연쇄로 손봐야 한다, (c) 삭제한 파일은 upstream 머지마다 충돌한다.
4. **builder/verifier ID는 템플릿 쪽에서 `package.json`의 `name` 파생으로 바꾼다.**
   memento에서 문자열만 교체하는 안은 기각. 근거: 그 경우 4개 파일이 영구 충돌 후보가 된다.
5. **앱 표시 이름은 `Memento`.** ko/en 카탈로그 모두 동일 표기.
6. **템플릿 `main`의 origin push 승인됨.**

---

## 2. Part A — 템플릿 선수정: 프로젝트 이름 파생

### A.1 문제

레포 이름이 4개 파일에 하드코딩되어 있다.

| 파일 | 줄 | 값 |
|---|---|---|
| `scripts/lib/provider-evidence.ts` | 12–13 | `PROMOTION_VERIFIER_ID = "clean-architecture-frontend-template/promotion-verifier"` |
| `scripts/lib/local-release-evidence.ts` | 306–307 | `LOCAL_EVIDENCE_VERIFIER_ID = "clean-architecture-frontend-template/local-evidence-verifier"` |
| `scripts/generate-supply-chain.ts` | 273 | `builder: { id: "local:clean-architecture-frontend-template" }` |
| `tests/unit/security-followup-fixture.ts` | 38, 183, 499 | 위 두 ID의 리터럴 복사본 |

파생 프로젝트는 이 4개 파일을 고쳐야 하고, 그 순간 4개 파일 모두가 upstream 머지의 영구 충돌 지점이 된다.

### A.2 해법: `scripts/lib/supply-chain.ts`에 `PROJECT_NAME`을 둔다

새 파일을 만들지 않는 것이 핵심이다. `scripts/lib/supply-chain.ts`는

- 세 소비자가 **이미 전부 임포트**하고 있고
  (`provider-evidence.ts:5-8`, `local-release-evidence.ts:70`, `generate-supply-chain.ts:26`)
- `LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS`(`scripts/lib/release-candidate.ts:38-58`)에 **이미 등재**되어 있다.

새 파일을 만들면 이렇게 된다:

- `tests/unit/security-followup.test.ts:79-92`가 `local-release-evidence.ts`의 모든 상대 `.ts` import를
  뽑아 `LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS`의 부분집합인지 검사한다. 새 파일을 임포트하면 **이 테스트가 깨진다.**
- 목록을 늘리면 `release-candidate.ts:71`을 통해 릴리스 증적의 대상 파일 집합이 함께 바뀐다.

`supply-chain.ts`는 이미 임포트되어 있고 이미 목록에 있으므로 둘 다 발생하지 않는다.

### A.3 변경 내용

`scripts/lib/supply-chain.ts`에 추가:

- 리포지토리 루트의 `package.json`에서 `name`을 읽어 `PROJECT_NAME`으로 노출한다.
- 읽기는 모듈 로드 시점 1회. `node:fs`의 `readFileSync`를 쓴다
  (선례: `scripts/check-adapter-inventory.ts`). 기존 `export const` 소비자들이
  동기 상수를 기대하므로 비동기 `readFile`로는 시그니처가 바뀐다.
- 루트 해석은 `new URL("../../package.json", import.meta.url)` 로 고정한다. 레포의
  기존 관용구가 이것이다(`scripts/run-vitest.ts:26`, `scripts/check-architecture.ts:74`).
  `import.meta.dirname`은 이 레포에서 쓰인 적이 없으므로 도입하지 않는다.
  `process.cwd()`에 의존하면 다른 디렉터리에서 스크립트를 호출했을 때 값이 달라진다.
- `name`이 없거나 빈 문자열이면 **던진다**. 조용한 폴백은 증적(provenance)에
  잘못된 identity를 박아 넣는다.

파생 상수:

| 상수 | 정의 | 템플릿에서의 값 |
|---|---|---|
| `PROMOTION_VERIFIER_ID` | `` `${PROJECT_NAME}/promotion-verifier` `` | `clean-architecture-frontend-template/promotion-verifier` |
| `LOCAL_EVIDENCE_VERIFIER_ID` | `` `${PROJECT_NAME}/local-evidence-verifier` `` | `clean-architecture-frontend-template/local-evidence-verifier` |
| supply-chain builder id | `` `local:${PROJECT_NAME}` `` | `local:clean-architecture-frontend-template` |

**템플릿의 `package.json` name은 안 바꾼다.** 따라서 세 값 모두 현재와 문자 단위로 동일하다.
이 변경은 템플릿의 산출물을 바꾸지 않는다. 바뀌는 것은 값의 출처뿐이다.

### A.4 테스트 픽스처

`tests/unit/security-followup-fixture.ts`의 리터럴 3곳(38, 183, 499)을 위 상수 import로 교체한다.

**조사 결과 부정 케이스는 없다.** 세 곳 모두 `status: "PASS"` 픽스처이고, 의도적으로 틀린
verifier ID를 넣어 거부를 확인하는 테스트는 `tests/` 어디에도 없다. 따라서 세 곳 전부
상수로 바꿔도 테스트가 무력화되지 않는다.

참고로 불일치를 거부하는 코드는 `scripts/lib/exact-promotion-bundle.ts:93`과
`scripts/lib/local-release-evidence.ts:785`다. 나중에 부정 케이스를 추가한다면
그쪽은 의도적으로 **틀린 리터럴**을 써야 한다. 상수를 쓰면 자기 자신과 비교하게 된다.

### A.5 Part A 완료 조건

```bash
corepack pnpm lint
corepack pnpm check:types
corepack pnpm test:all
corepack pnpm build
corepack pnpm verify:release
```

추가로, 이 변경이 산출물을 안 바꿨다는 것을 확인한다: 변경 전후로
`artifacts/release/provenance.json`의 `predicate.runDetails.builder.id`가 동일해야 한다.

---

## 3. Part B — 템플릿 `develop` → `main`

현재 상태:

```
main    91ae42a Initial commit          (커밋 1개)
develop ec7f20e refactor: 프론트엔드 리펙토링 (커밋 234개)
```

`main`은 `develop`의 조상이다(`git merge-base --is-ancestor main develop` 통과). 따라서:

```bash
git checkout main
git merge --ff-only develop
git push origin main
```

`--ff-only`를 쓰는 이유: `main`이 고유 커밋을 하나도 갖고 있지 않아 `--no-ff` 머지 커밋은
아무 정보도 담지 못한다. `--ff-only`는 "조상이 아니면 실패"라는 안전장치 역할도 한다.

Part A의 커밋이 `develop`에 먼저 올라가야 하므로 **Part A → Part B 순서를 지킨다.**
(Part A가 `develop`에 커밋되어도 `main`은 여전히 조상이므로 ff는 유지된다.)

---

## 4. Part C — memento-frontend 부트스트랩

현재 상태: `main`에 커밋 2개 (`bce7c4c Initial commit`, `b35e17c README.md 업데이트`), 파일은 `README.md` 하나.

```bash
cd /home/donghyeon/workspace/desktop-server-git/memento-frontend
git remote add upstream https://git.learn.hyeonworks.com/donghyeon.kang/clean-architecture-frontend-template
git fetch upstream
git merge upstream/main --allow-unrelated-histories
```

- `--allow-unrelated-histories`가 필요한 이유: 두 레포는 공통 조상이 없다.
- 예상 충돌: **`README.md` 1건**(양쪽에 존재하는 유일한 경로). 템플릿 쪽을 채택한 뒤 Part D에서 교체한다.
- 결과: memento의 커밋 2개가 first-parent 선상에 보존되고, 템플릿 234개가 머지로 들어온다.

이후 동기화:

```bash
git fetch upstream && git merge upstream/main
```

---

## 5. Part D — 리브랜딩

### D.1 바꾸는 곳

| 파일 | 위치 | 현재 | 변경 후 |
|---|---|---|---|
| `package.json` | `name` | `clean-architecture-frontend-template` | `memento-frontend` |
| `index.html` | 7 | `Clean Architecture Frontend` | `Memento` |
| `src/presentation/i18n/catalog.ts` | 6, 165 (`common.appName`) | `Frontend Skeleton` | `Memento` |
| `src/presentation/i18n/catalog.ts` | 44, 203 (`route.APP_HOME.title`) | `Clean Architecture Frontend` | `Memento` |
| `src/presentation/pages/home-page.tsx` | 43 | `Clean Architecture Frontend` | `Memento` |
| `src/contracts/storage-keys.ts` | 1 (`APP_NAMESPACE`) | `ca-frontend` | `memento` |
| `README.md` | 전체 | 템플릿 설명 | memento 설명 + upstream 동기화 절차 |

`package.json`의 `name` 변경은 Part A 덕분에 자동으로 verifier/builder ID까지 memento 값으로 전파된다.

`APP_NAMESPACE` 변경 시 주의: 이 값은 `storage-keys.ts:140`에서 `${APP_NAMESPACE}:${scope}:v${schemaVersion}:${name}` 형태로 브라우저 저장소 키를 만든다. 템플릿이 이미 쓰던 키가 남아 있는 브라우저에서는 기존 데이터가 고아가 된다. 신규 프로젝트라 실제 영향은 없지만, 키 형식을 검사하는 테스트가 있으면 같이 갱신해야 한다.

### D.2 바꾸지 않는 곳 (의도적)

- **`docs/superpowers/specs/*`, `docs/reviews/*`, `docs/architecture/*` 안의 템플릿 이름**
  이들은 템플릿에서 실제로 일어난 작업의 기록이다. 이름을 바꾸면 기록이 거짓이 되고,
  upstream 머지 충돌만 늘어난다. (해당 파일 7개)
- **`config/runtime/*.json`의 `API_BASE_URL`**
  `memento-backend`가 아직 빈 레포라 넣을 값이 없다. `http://localhost:8080/` 유지.
- **`public/config.json`의 `FEATURE_OVERRIDES["reference-feature"]`**
  결정 3에 따라 `reference-feature`를 남기므로 그대로 둔다.

### D.3 memento `README.md`

최소한 다음을 담는다. memento의 도메인이 아직 정해지지 않았으므로 제품 설명은 쓰지 않는다.

1. 이 레포가 `clean-architecture-frontend-template`에서 파생되었다는 사실
2. upstream 동기화 절차 (`git fetch upstream && git merge upstream/main`)
3. 로컬 실행 절차 (템플릿 README에서 승계)
4. 리브랜딩된 지점 목록 — 다음 사람이 upstream 충돌을 만났을 때 볼 곳

---

## 6. 검증

memento-frontend에서, Part D 완료 후:

```bash
corepack pnpm install --frozen-lockfile
corepack pnpm lint
corepack pnpm check:types
corepack pnpm check:architecture
corepack pnpm check:adapter-inventory
corepack pnpm test:all
corepack pnpm build
corepack pnpm verify:release
```

`verify:release`를 포함하는 이유: Part A가 손댄 경로가 정확히 이 게이트의 대상이고,
`package.json`의 `name`이 바뀐 상태에서 ID 파생이 일관되게 동작하는지는 여기서만 드러난다.

`.nvmrc`의 Node 24.14.0과 Corepack이 필요하다.

---

## 7. 비범위 (이번에 하지 않는 것)

- memento의 도메인 기능 설계·구현. 이번 작업의 산출물은 "빌드되고 게이트를 통과하는 빈 스캐폴드"까지다.
- `memento-backend` 연동. 해당 레포도 아직 비어 있다.
- `reference-feature` 제거. 결정 3에 따라 남긴다. 나중에 제거할 때는 별도 작업으로 다룬다.
- `.gitea/workflows/quality-gates.yml`의 CI 활성화 검증. 파일은 그대로 넘어가지만 Gitea Actions 러너 설정은 이 작업 범위 밖이다.
- 템플릿의 `develop` 브랜치 정리나 `refactor/platform-consumer-migration` 브랜치 처리.

---

## 8. 리스크

| 리스크 | 영향 | 완화 |
|---|---|---|
| Part A에서 `readFileSync` 경로가 호출 컨텍스트에 따라 달라짐 | 증적에 잘못된 identity | `new URL(..., import.meta.url)` 기준 고정, `process.cwd()` 사용 금지 |
| Part A가 `local-release-evidence.ts`에 새 import를 추가함 | `security-followup.test.ts:79-92` 실패 | 이미 임포트 중인 `supply-chain.ts`만 쓴다. 새 파일을 만들지 않는다 |
| memento에서 `pnpm install` 후 게이트 실패 | 부트스트랩 미완 | Part B push 전에 템플릿에서 전 게이트를 먼저 통과시킨다 |
| `--allow-unrelated-histories` 머지에서 예상 밖 충돌 | 수작업 증가 | 충돌 파일이 `README.md` 외에 나오면 중단하고 보고 |
| `main` ff 머지 실패 | Part B 중단 | `--ff-only`가 알아서 실패시킨다. 그 경우 `main`에 예상 못한 커밋이 생긴 것이므로 재조사 |

---

## 9. 실행 순서 (되돌리기 어려운 것이 뒤)

1. Part A — 템플릿 `develop`에서 ID 파생으로 변경, 게이트 통과, 커밋
2. Part B — `develop` → `main` ff 머지, `origin/main` push  ← 첫 외부 반영
3. Part C — memento에 `upstream` 추가, `upstream/main` 머지, `README.md` 충돌 해소
4. Part D — 리브랜딩
5. 검증 — memento에서 전 게이트 실행
6. memento 커밋 (push 여부는 별도 확인)