문제 기능 패키지의 classifyProblem이 throw하거나 집합 밖 값을 돌려주면 classifyProblemEffect는 MAYBE_APPLIED + contractRuntimeFailure: true를 돌려준다. 주석과 설계서(closed-deep-design.md:650)는 이것을 "contract runtime failure로 기록한다"고 적지만, 실행기는 .effect만 쓰고 플래그를 버린다. 그래서 분류기가 throw한 409와 분류기가 정말 MAYBE_APPLIED라고 답한 409의 관측 기록·진단이 요청 id 말고 똑같다. 또 이 안전 기본값을 NOT_APPLIED로 바꿔도(변이 M5) 영역 테스트가 하나도 실패하지 않는다. 고른 방법 - HttpExecutionObservation에 선택 필드 diagnosticReason을 더한다. 타입은 닫힌 집합 HttpDiagnosticReason이고 지금 값은 CLASSIFIER_FAILED 하나다. 문제 응답 admission이 명령의 contractRuntimeFailure를 이 값으로 바꾸고, finish()가 관측 기록에 싣는다. - 조립 지점의 projector는 이 값을 diagnostics에만 reason으로 더한다 (reason은 이미 허용 목록의 taxonomy 키). telemetry 속성은 그대로다. - 효과는 계속 MAYBE_APPLIED다. 재시도 판단에 쓰는 certainty는 건드리지 않았다. 버린 대안 - 리뷰 문서 문구대로 terminalReason을 CLASSIFIER_FAILED로 바꾸기: terminalReason은 "sink로 나가지 않는 내부 라벨"(VD-07 5-1)이고, 문제 응답에서는 certainty 값이 그대로 terminalReason이 되며 재시도 차단 조건(certainty !== "MAYBE_APPLIED")에도 쓰인다. 값을 바꾸면 그 이중 차단이 하나로 줄고, projector가 문자열을 걸러 내야 한다. 별도 닫힌 타입 필드가 의도가 더 잘 보인다. - 플래그와 주석 문장을 지우기(리뷰의 두 번째 안): 운영자가 "결과 불명"이 분류기 결함 때문인지 구분할 수단이 계속 없다. 위험·한계 - classifyStatus(401·403·429) 분류기의 throw는 지금처럼 MAYBE_APPLIED만 내고 reason을 남기지 않는다. 그 함수는 기록을 주장하지 않아 이번 범위에서 뺐다. - 공개 타입은 추가만 했다(관측 선택 필드 1개, 배럴 type export 1개). - VD-07 5-1에 reason 전달 규칙을 적었다. 검증 - RED(수정 전): tests/integration/http-execution-v3-observability.test.ts "keeps MAYBE_APPLIED and records a failed problem classifier in diagnostics only (03-05)" 실패. 기대 reason "CLASSIFIER_FAILED", 실제 undefined. - GREEN: 같은 파일 7/7 통과. 변이 M5(catch를 NOT_APPLIED로)를 다시 넣으면 이 테스트가 실패하는 것을 확인하고 원복했다. - 회귀: run-vitest tests/integration tests/features/reference-feature tests/unit/http-execution-v3.test.ts 30 files / 302 tests 통과. tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory PASS. - 미실행: check:architecture(pnpm 스크립트 필요). Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
문서 색인
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/ 밖에 그대로 둔다 |