문제: 설계 13.1은 IDLE_TIMEOUT을 "heartbeat/byte deadline 초과 -> close + bounded reconnect" 한 뜻으로만 적는다. 코드는 같은 kind를 내부 task 마감에도 쓴다. stream coordinator는 effect·recovery·close drain 마감을 IDLE_TIMEOUT/APPLY·RECOVER·CLOSE(retryable false)로, handoff coordinator는 quiescence·checkpoint·close 마감을 IDLE_TIMEOUT/RECOVER·CLOSE(기본값 retryable)로 보고한다. 13.1만 보고 조합 코드를 쓰면 내부 마감도 재연결 대상으로 읽는다. RED(문서-코드 대조): 13.1 행은 transport 뜻 하나. 코드에서 IDLE_TIMEOUT을 만드는 곳은 transport 3곳(SSE RECEIVE, WS RECEIVE· SUBSCRIBE)과 내부 task 7곳(stream-coordinator.ts 3곳, live-poll-handoff-coordinator.ts 4곳). stream coordinator close() 주석은 "IDLE_TIMEOUT이면 아직 DRAINING"을 공개 계약으로 적는다. 고른 방법: 리뷰의 (b). 13.1 IDLE_TIMEOUT 행을 코드에 맞춰 두 뜻, operation으로 구분하는 법, 각 경우의 recovery, 관측에서 구분되지 않는다는 한계를 적는다. 코드는 바꾸지 않는다. 버린 대안: (a) stream coordinator의 마감을 APPLY_FAILED· PROVIDER_UNAVAILABLE로 바꾸기. 리뷰는 코드 3곳으로 봤지만 같은 관례가 handoff coordinator 4곳에도 있고, stream coordinator close()의 IDLE_TIMEOUT은 주석에 적힌 공개 계약이다. 바꾸려면 두 coordinator의 마감 어휘를 함께 정해야 하므로 별도 결정으로 남긴다. 위험·한계: - 리뷰 완료 기준 중 "effect 마감과 전송 idle을 관측에서 구분"은 충족하지 못했다. reconnect 관측(RUN_ENDED)에 operation이 없다. (a) 또는 관측에 operation 추가가 필요하다. - handoff 마감 결과가 retryable true(kind 기본값)이고 stream coordinator는 false인 차이는 문서에 적기만 했다. 검증: - `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED. - 코드 변경 없음. 테스트 미실행(해당 없음). Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-02, 6.3절
문서 색인
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/ 밖에 그대로 둔다 |