Files
clean-architecture-frontend…/docs
DongHyeonka de379ea78d ci(release): FE-GATE-019가 승격 후보를 배포된 release와 대조한다 (1101/13-01)
문제
production_gate는 promotion 직후 같은 run에서 시작하고 그 사이에 배포 job이
없다. CI 계약이 job 9개·그래프·env를 정확히 고정해 배포 job을 넣을 자리도
없다. live probe는 헤더만 보고 배포된 release가 승격 후보인지 확인하지
않는다. FE-GATE-019의 명령은 [build, verify-hosting-headers]라서 local
프로필로 다시 빌드한 dist를 검사한다. 그래서 FE-GATE-019 PASS는 "지금 떠
있는 release(대개 이전 것)의 헤더가 맞다"는 거짓 PASS다.

고른 방법 (리뷰 대안 (c), (1)~(3))
(1) live probe가 배포된 release-manifest.json의 buildId·releaseId를 후보와
    비교한다. 다르거나 읽을 수 없으면 FAIL(releaseManifest build-id·
    release-id). 후보는 검사하는 dist의 release-manifest.json이다.
(2) FE-GATE-019에서 build를 뺀다. verify-hosting-headers가
    `--release-root .release/promoted-release`를 받아 후보 dist를 본다.
    계약의 13-03 규칙(drill만 --release-root 필수)을 production_gate의 모든
    게이트 명령으로 넓혔다. 플래그 없이 돌리면 local dist를 본다.
(3) promotion과 production_gate 사이에 `deployment` job(kind deployment)을
    선언한다. 기본은 빈 슬롯이다: deploy 단계 하나가 deployed=false를 job
    output으로 낸다. production_gate는 RELEASE_DEPLOYED로 받고, 비어 있으면
    FE-GATE-019가 호스트를 probe하지 않고 UNVERIFIED(exit 3)로 끝난다.
    프로젝트는 gates.json의 deployment job을 채운다. 계약이 허용하는 것:
    checkout·setup-node·frozen-install·download·extract와 마지막 deploy 하나
    (`script`는 package 스크립트, 존재·스크립트 그래프 검사를 gate 명령과
    같이 받는다). env는 immutable_build의 CANDIDATE_ARCHIVE_SHA256과
    vars.*·secrets.*만. 게이트를 소유하지 않아 채워도 계약 기준선이 안
    바뀐다.
- ci-contract 보고서 jobCount 9→10, 계약 기준선 commandReferences
  103→102(update-ci-contract-baseline, owner frontend-platform).
- verify-hosting-headers가 live가 아닌 모드에서 baseUrl을 null로 적는다.
  스키마가 live에만 baseUrl을 허용해서, 비어 있는 슬롯과 기존 invalid-live
  (예: http:// URL)는 산출물 쓰기에서 ZodError로 죽었다. 이제 기록을 남기고
  각각 UNVERIFIED·FAIL로 끝난다.

버린 대안
- (b) (1)(2)만: 거짓 PASS는 사라지지만 배포 자리가 없어 운영 단계가 항상
  FAIL이 된다.
- (d) production_gate를 별도 workflow로 분리: Gitea에서 run 사이 artifact
  전달이 검증되지 않았다.
- 슬롯이 비었는지를 HOSTING_BASE_URL 유무로 판단: 변수만 있고 배포가 없으면
  이전 release를 probe해 FAIL이 된다. 슬롯이 직접 보고하게 했다.

위험·한계
- Gitea runner가 꺼져 있어 workflow를 실제로 돌리지 않았다. job outputs와
  `$GITHUB_OUTPUT`는 immutable_build가 이미 쓰는 방식과 같다.
- 실제 HTTPS 호스트에 이전 release를 띄워 probe하지 않았다. 불일치 판정은
  fetcher를 주입한 단위 테스트로만 확인했다.
- 채운 슬롯의 secrets는 그 job의 모든 단계(checkout, download action 포함)
  env에 보인다. 프로젝트가 고르는 값이다.
- FE-GATE-019를 수동으로 돌리는 운영자(provider 없는 최소 구성)는 후보
  archive를 .release/promoted-release에 풀어야 한다. drill과 같은 전제다.

검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
  7 failed / 19 passed(후보 인자 없음, verify가 dist ENOENT로 산출물 없음).
  tests/unit/ci-workflow-generation.test.ts 8 failed / 415 passed
  ("expected [ 'build', 'verify:hosting-headers' ] to deeply equal ...",
  "expected -1 to be 6", deployment job 없음)
- GREEN: hosting-probe 26 passed, ci-workflow-generation 423 passed
  (스냅샷 1개 갱신)
- check:ci 하위 명령 직접 실행: generate-artifact-schemas --check PASS,
  check-ci-contract.ts PASS, generate-ci-workflow --check PASS
- 슬롯을 채운 실험(체크아웃→다운로드→extract→deploy:release, vars·secrets
  env, package 스크립트 추가) 뒤 같은 세 명령 PASS. package 스크립트를 빼면
  "CI gate contract missing package scripts: deploy:release"로 실패. 실험
  뒤 원복
- 관련 테스트 16파일 596 passed(ci-workflow-generation, hosting-probe,
  service-worker-build-output, deployment-admission, ungated-*,
  supply-chain, removal-fixture, task3-selective-integration,
  documentation-readiness, tests/release, tests/platform/release)
- tsc(node, test, app) 0, eslint 바뀐 파일 0,
  verify-documentation-readiness PASS_SCOPED
- 미실행: tests/system/ci-runner(pnpm 실행), check:architecture(pnpm)

Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-01
2026-11-03 00:56:00 +09:00
..

문서 색인

docs/의 문서를 세 묶음으로 나눈다.

1. 현재 계약   지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계   앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력   리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다

문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는 문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로 확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.

README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.

1. 현재 계약

처음 읽을 입구 문서 6개다.

문서 정하는 것
README.md 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
architecture/optional-adapter-recipes.md 선택 기능(recipe)을 넣고 빼는 절차
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

입구 문서가 가리키는 세부 규칙:

게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
architecture/review-ledger.json, architecture/review-evidence.md, accessibility/manual-checklist.md verify:documentation (FE-GATE-017)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)

2. 목표 설계

설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.

3. 작업 이력·리뷰

템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다. 복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의 "Files you can delete after copying" 절에 있다.

경로 내용
superpowers/ 과거 작업 계획과 스펙
reviews/ 리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다
../SPEC.md, ../tasks/ 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다