[iflov]

PR #2 리뷰에서 머지를 막지 않아 후속으로 미뤘던 항목들을 처리했다.

1. CI에 Compose 게이트 추가

AGENTS.md의 Required validation에 docker compose config --quiet가 있으나 CI의 validate job은
pnpm build에서 끝나, 문서화된 불변식이 지속 검증되지 않았다.

.env 없이 실행한다. 스캐폴드는 클론한 사람이 .env를 만들기 전에도 compose 파일 자체가 유효해야
하므로 "기본값만으로 성립한다"가 더 강한 불변식이고, .env.example과의 정합성은 이미
check:scaffold가 검사하는 영역이다.

stderr가 비어 있지 않으면 실패로 승격한다. 측정해보니 docker compose config --quiet는 기본값
없는 미정의 변수를 실패로 처리하지 않는다.

기본값 없는 미정의 변수     → exit 0 (warning만)
.env로 채움                 → exit 0
${VAR:?msg} 미정의          → exit 1
YAML/스키마 오류            → exit 1

승격하지 않으면 이 게이트는 사실상 YAML 문법 검사에 그친다. 스캐폴드에서 실제로 위험한 실패는
compose 변수가 조용히 빈 문자열이 되는 것이다. 파생 프로젝트가 '${GRAFANA_HOST_PORT}:3000'처럼
기본값을 빠뜨리면 CI는 통과하고 나중에 docker compose up이 알아보기 힘든 에러로 죽는다.

경고 문구는 docker 버전에 따라 달라질 수 있어 문구 매칭이 아니라 stderr 비어있음으로 판정한다.

mutation 확인 — LOKI_HOST_PORT:-3100에서 기본값을 제거:

정상      stderr empty → PASS
mutation  time=... level=warning msg="The \"LOKI_HOST_PORT\" variable is not set..." → exit 1

받아들이는 위험: 미래 docker 버전이 저장소와 무관한 경고를 내면 CI가 빨개진다. 그때 경고 원인을
없애거나 범위를 좁히면 된다. 현재 stderr는 비어 있어 이 정책의 비용은 0이다.

2. workflow 중복 실행 정리

on:
  pull_request:
  push:
    branches: [main]

브랜치 필터가 없어 PR 브랜치의 push가 push와 pull_request 두 run을 만들고 있었다. 이제 PR
브랜치는 pull_request 한 번, main은 push 한 번이다.

되돌리기 쉽도록 별도 커밋(50c5634)으로 분리했다. 모든 브랜치 push 검증이 필요하면 그 커밋만
되돌리면 된다.

3. typescript-eslint 8.57.0 → 8.68.0

8.57.0의 peer는 >=4.8.4 <6.0.0이라 현재 TypeScript 6.0.3이 지원 범위 밖이었다. 8.68.0은
<6.1.0으로 넓어져 지원한다. pnpm의 minimum release age 예외 없이 그대로 올라갔다.

8.68.0이 불필요한 타입 단언 두 곳을 새로 탐지했다.

src/infra/queue/background-jobs.service.spec.ts
  11:15  error  This assertion is unnecessary...  @typescript-eslint/no-unnecessary-type-assertion
  44:17  error  This assertion is unnecessary...

테스트 타입을 느슨하게 바꾸지 않고 불필요한 as never만 제거했다.

검증

pnpm install --frozen-lockfile   OK
pnpm check:scaffold              OK
pnpm check:observability         OK
pnpm lint                        OK
pnpm typecheck                   OK
pnpm test                        OK  35 files / 306 tests
DB_PORT=15432 pnpm test:e2e      OK   2 files /  20 tests  (실 PostgreSQL)
pnpm build                       OK
docker compose config            OK  (stderr empty)

이번 범위에서 뺀 것

MikroORM/Prisma profile의 materialize + typecheck 검증은 별도 후속으로 남긴다. Drizzle은 PR #2에서
확인됐다. 이 PR의 변경과는 독립적이다.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H9e5FGopAgR7Ah5VK6Wisb