문제: 운영 문서(browser-file-storage-recovery.md 8절)는 "활성화는 페이지의 requestActivation()으로만 일어나므로 새 worker 활성화를 멈추려고 따로 할 일은 없다"고 적는다. 브라우저는 scope의 탭이 모두 닫히면 waiting 워커를 스스로 활성화한다. 운영자가 이 문장을 믿고 결함 있는 waiting 워커를 두면, 탭을 닫았다 연 사용자부터 그 워커를 쓰고 대응(REMOVE_REGISTRATION)이 늦어진다. RED(문서-코드 대조): install은 skipWaiting()을 부르지 않는다 (service-worker-entry.ts). requestActivation()은 src에서 정의 (service-worker-page-controller.ts, contracts/service-worker.ts)만 있고 부르는 곳이 없다. 저장소 e2e 주석(service-worker-update.spec.ts)과 리뷰 실험 8(chromium·webkit)은 탭을 모두 닫으면 B가 활성화되고 reload만으로는 waiting에 남는 것을 보였다. 같은 저장소의 release-cache-rollback.md는 이미 "every tab of the scope closes or a page calls requestActivation()"으로 맞게 적는다. 고른 방법: 문장을 두 활성화 경로(requestActivation 성공, scope의 탭이 모두 닫힘)와 reload만으로는 활성화되지 않는다는 점, 템플릿의 기본 경로, 결함 있는 waiting 워커에 대한 조치(다음 release로 교체 또는 REMOVE_REGISTRATION)로 고친다. 코드는 바꾸지 않는다. 버린 대안: 없음. 리뷰가 문서 정정 하나만 제시했다. 위험·한계: 이번에 브라우저 실험을 다시 하지 않았다. 근거는 표준 SW 수명주기, 저장소 e2e 주석, 리뷰 실험 8이다. firefox는 Playwright에서 페이지가 제어되지 않아 확인 범위 밖이다. 검증: - `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED. - `grep -rln requestActivation src tests` -> src는 정의 2파일뿐. Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 06-02, 7.2절
문서 색인
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/contract-ownership.md,contracts/compatibility.md - 정적 배포와 런타임 설정:
architecture/static-delivery.md - 기능 개발자가 알아야 하는 양:
architecture/capability-consumer-experience.md - 운영·복구:
operations/,runbooks/ - 보안과 공급망:
security/browser-boundary.md,security/supply-chain.md - 디자인 토큰과 수동 접근성 검토:
styling/design-tokens.md,accessibility/manual-checklist.md - 버전별 변경:
../CHANGELOG.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. 목표 설계
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
- 런타임 capability 결정의 정본:
architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md - 상태 원장:
architecture/browser-data-capability-completion-ledger.md - 전체 검토와 로드맵:
architecture/frontend-platform-capability-review.md,architecture/frontend-platform-implementation-roadmap.md - 포트·경계·데이터 흐름:
architecture/frontend-ports-adapters-and-boundaries.md,architecture/typescript-state-and-data-flow.md,architecture/routing-pages-and-patterns.md - API와 서버 상태:
architecture/api-contract-schema-mapper-and-server-state.md,architecture/backend-api-and-server-state-contract.md,architecture/protobuf-browser-transport-and-rest-gateway.md - 브라우저 데이터:
architecture/client-cache-and-storage.md,architecture/browser-file-and-origin-storage.md,architecture/presigned-transfer-and-image-cdn.md,architecture/server-file-capability-infrastructure.md - 실시간:
architecture/realtime-events-web-push-and-bounded-polling.md - 디자인 시스템과 테스트 전략:
styling/design-system-platform.md,testing/frontend-platform-testing-strategy.md - 결정 기록(ADR):
architecture/decisions/VD-*.md
3. 작업 이력·리뷰
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
superpowers/ |
과거 작업 계획과 스펙 |
reviews/ |
리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다 |
../SPEC.md, ../tasks/ |
2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다 |