docs: 살아 있는 문서의 낡은 문장을 지금 코드와 정본에 맞춘다

2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는
문서가 지금 코드와 다른 말을 한다.

- 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로
  가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/,
  패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06).
- 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다.
  optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리
  블록이 옮긴 곳을 가리킨다(1112/09-02).
- 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로
  가리킨다(1112/08-17).
- 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007),
  drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는
  꼬리 문장(1112/02-08).
- 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop
  verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다
  (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은
  verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07).
- create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자
  (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15).
- secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장
  (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫
  (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조
  (1106/14-02).

고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다.
버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다).

위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제
docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드
예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture
규칙과 부딪쳐 결정 대기로 남긴다.

검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과
FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다.

Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04,
 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15,
 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02,
 0929/14-03, 0929/13-10, 1106/14-02
This commit is contained in:
DongHyeonka
2026-11-12 23:36:14 +09:00
parent c0ddc0328e
commit 06ffafa25e
29 changed files with 142 additions and 80 deletions
+2 -2
View File
@@ -19,5 +19,5 @@ paths:
- 기준선 기록(초기 JS, 기능 모양)은 손으로 고치지 않는다. 측정 스크립트를 `--initial-baseline --write`로 돌린 결과를 같은 변경에 넣는다.
- workflow는 생성기로 만든다. `.gitea/workflows/`만 손으로 고치지 않는다(`check:ci`가 대조한다).
- 새 검사에는 통과 fixture와 거절 fixture를 함께 둔다. 실패 메시지는 넘은 항목·잰 값·고칠 파일을 말한다. 사전 점검은 본 단계와 같은 방법으로 한 번 실행해 본다.
- 바꾼 뒤 desktop에서 `scripts/verify.sh merge`. stage·게이트 목록이 바뀌어도 `scripts/verify.sh`는 계약 파일에서 읽어 따라간다.
- 편집 훅(N6)이 이 파일들의 편집을 알린다. 알림은 막지 않는다. 의도한 변경이면 커밋 본문에 이유와 결정 출처를 적는다.
- 바꾼 뒤 desktop에서 `scripts/verify.sh merge`. 검사 script나 그 fixture를 바꿨으면 `scripts/verify.sh gate FE-GATE-029`도 돌린다(검사기 자기 시험은 main 단계다). stage·게이트 목록이 바뀌어도 `scripts/verify.sh`는 계약 파일에서 읽어 따라간다.
- 편집 훅(N6)이 예산·기준선·ungated 목록·시험 설정·스냅숏의 편집을 알린다(목록은 `scripts/hooks/README.md`). 이 규칙의 다른 파일(`config/ci/gates.json`, workflow, 검사 script)은 알리지 않는다. 알림은 막지 않는다. 의도한 변경이면 커밋 본문에 이유와 결정 출처를 적는다.
+1 -1
View File
@@ -22,4 +22,4 @@ paths:
## 돌리는 법
- 노트북에서는 돌리지 않는다. 한 파일도 desktop에서: `scripts/verify.sh script test:unit`, 또는 `ssh desktop`으로 `node scripts/run-vitest.ts run <file>`(이 runner가 생성물을 먼저 만든다. `pnpm exec vitest run <file>`은 import 오류로 실패한다).
- 노트북에서는 돌리지 않는다. 한 파일도 desktop에서 `scripts/verify.sh exec -- node scripts/run-vitest.ts run <file>`로 돌린다(이 runner가 생성물을 먼저 만든다. `pnpm exec vitest run <file>`은 import 오류로 실패한다). 실행 위치의 정본은 `docs/work/operate.md` 4.1절이다.
+1 -1
View File
@@ -7,5 +7,5 @@
`claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git --scope project`
`claude plugin install harness@claude-harness --scope project`
- 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트(읽기 전용)는 `.claude/agents/`다.
- 분야 지식은 `fe-*` 스킬 9개(`paths`가 걸려 그 분야 파일을 만질 때 목록에 뜬다)이고, 분야 판정은 서브에이전트 `reviewer`에 그 스킬을 렌즈로 준다. 여러 분야면 플러그인 `lead`. 명단은 `docs/work/experts.md`다.
- 분야 지식은 `fe-*` 스킬(`paths`가 걸려 그 분야 파일을 만질 때 목록에 뜬다)이고, 분야 판정은 서브에이전트 `reviewer`에 그 스킬을 렌즈로 준다. 여러 분야면 플러그인 `lead`. 명단은 `docs/work/experts.md`다.
- 리뷰 기준은 `docs/work/reference/review-criteria.md`, 절차는 `docs/work/improve.md` 4.1절이다. 세션 규칙은 `docs/work/delegate.md` 4.3절이다. 보고 칸은 `docs/work/README.md` 6절, 말투와 길이는 소유자 전역 설정을 따른다.
+5 -4
View File
@@ -218,7 +218,7 @@ export CI=true VITE_COMMIT_SHA="$(git rev-parse HEAD)" VITE_BUILD_ID=local-ci-1
```
- 기계가 읽는 증거는 `artifacts/` 아래에 쓴다. 생성된 증거는 git이 무시하고, `.gitkeep` 파일이 폴더 구조를 지킨다.
- 한 checkout에서는 게이트를 하나씩 돌린다. 게이트와 증거 검사가 고정된 `dist/`·`artifacts/` 경로를 읽는다. Playwright 실행 둘은 각자 `TEST_RUN_ID`를 주면 한 checkout을 같이 쓸 수 있다. 그 빌드·결과·보고서는 `.tmp/runs/<id>/` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록은 설계서 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 13.6절에 있다.
- 한 checkout에서는 게이트를 하나씩 돌린다. 게이트와 증거 검사가 고정된 `dist/`·`artifacts/` 경로를 읽는다. Playwright 실행 둘은 각자 `TEST_RUN_ID`를 주면 한 checkout을 같이 쓸 수 있다. 그 빌드·결과·보고서는 `.tmp/runs/<id>/` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록의 정본은 `scripts/lib/run-isolation.ts`(`TEST_RUN_ID_VARIABLE`, `TEST_PORT_VARIABLES`)다.
외부 증거가 필요한 게이트:
@@ -274,11 +274,12 @@ git merge --no-ff template/<range branch> # shared history
git merge-recursive <range base> -- HEAD template/<range branch> # no shared history
```
- 동기화한 기준점은 프로젝트가 적어 두는 곳에 둔다: `.template-origin`, 또는 자기 잠금 파일(tech-log는 `template.lock.json`의 `sourceRevision`). 범위를 다 받으면 그 끝으로 옮긴다.
- 동기화한 기준점은 받은 범위의 끝 커밋(템플릿 커밋 해시) 하나다. 프로젝트가 적어 두는 곳에 둔다: `.template-origin`, 또는 자기 잠금 파일(tech-log는 `template.lock.json`의 `sourceRevision`). 범위를 다 받고 아래 게이트가 통과하면 그 끝으로 옮긴다.
- 충돌을 풀 때 어느 파일이 제품 몫인지는 [매뉴얼 03 문서](docs/manual/03-outside-feature-folder.md)의 C절(조건이 맞을 때만 사람이 고친다)과 D절(고치지 않는다)이 정본이다. D절의 파일은 템플릿 쪽을 받는다.
- 파일이 너무 옮겨졌거나 갈라져서 깨끗하게 고를 수 없으면 diff로 읽고 손으로 적용한다: `git diff <commit>^ <commit> -- <paths from CHANGELOG>`.
- 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, **[계약]** 행이 말하는 백엔드·배포 변경을 하고, 태그까지 따라잡았으면 `.template-origin`을 고친다. 받은 수정은 `git revert`로 되돌린다.
- 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, **[계약]** 행이 말하는 백엔드·배포 변경을 하고, 위 기준점을 받은 범위의 끝으로 옮긴다. 받은 수정은 `git revert`로 되돌린다.
결함: 바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함이다. 그 커밋과 재현 방법을 템플릿 repo에 알린다. 템플릿 관리자가 분류하고 CHANGELOG 항목과 함께 수정을 낸다. 프로젝트의 변경이 있어야 재현되는 문제는 프로젝트의 몫이고, 템플릿 수정을 자기 사본에 적용하는 것도 프로젝트의 일이다.
결함: 바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함이다. 템플릿이 주는 선택 기능(opt-in recipe·adapter, `create:feature`가 만든 기능)을 문서대로 켜거나 더한 것만 다르고 재현되는 것도 템플릿 결함이다. 그 커밋, 켠 선택 기능, 재현 방법을 템플릿 repo에 알린다. 템플릿 관리자가 분류하고 CHANGELOG 항목과 함께 수정을 낸다. 프로젝트의 변경이 있어야 재현되는 문제는 프로젝트의 몫이고, 템플릿 수정을 자기 사본에 적용하는 것도 프로젝트의 일이다.
## 규칙과 기여
+1 -1
View File
@@ -12,7 +12,7 @@
"sets": {
"fixture-copy": "제거·생성 drill과 사본 시험이 복사하는 것(scripts/lib/removal-fixture.ts)",
"fixture-documents": "기능을 더하거나 지우는 drill이 문서까지 맞는지 보려고 더 복사하는 문서(scripts/lib/removal-fixture.ts)",
"secret-scan": "비밀값 검사와 공급망 목록의 범위. config/security/secret-scan-policy.json의 trackedRoots가 이 집합과 같아야 한다",
"secret-scan": "비밀값 검사가 꼭 있어야 한다고 보는 루트. config/security/secret-scan-policy.json의 trackedRoots가 이 집합과 같아야 한다. 검사와 공급망 목록 자체는 추적되는 파일 전부와 dist, artifacts/release를 본다(scripts/lib/repository-file-inventory.ts)",
"history-free": "이력 문서를 읽으면 안 되는 코드(tests/unit/deletable-history-documents.test.ts)",
"scale-source": "규모 증거에서 '지금 코드'를 정하는 입력(scripts/verify-extreme-scale.ts)",
"vite-build": "vite build가 읽는 입력(scripts/lib/vite-build-inputs.ts)",
@@ -1,11 +1,11 @@
# Backend API와 Server State handoff contract
> **정본 안내 (non-authoritative for runtime capability decisions)**
> **정본 안내**
>
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
> Service Worker, offline command와 Background Sync의 구현 결정은
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
> 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.
> Service Worker, offline command와 Background Sync의 지금 구현은
> [프론트엔드 애플리케이션 기반](frontend-application-foundation.md)과 `src/bootstrap/`이 정본이다.
> 설계 배경(기록)은 [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)다(1112/02-06).
- 상태: frontend handoff 설계는 승인됨, backend 구현·증거는 대기 중. 단 4.1·6·6.1절(Envelope 읽기, effect 판정, 쓰기 전 거절 표)은 지금 실행 규칙이다(`COMPOSED`, `src/adapters/http/backend-envelope.ts`)
@@ -20,7 +20,7 @@ feature가 소유한 경계 코드와 application 코드는 다음 네 파일이
- `adapters/<base>-http-gateway.ts`
- `adapters/create-<base>-feature-input.ts`
이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 14-07).
이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 0925/14-07).
생성한 feature에서 이 네 파일에 `wc -l`을 돌려 잰다.
중요한 경계 지표는 단순 합계가 아니다. 이 파일들이 플랫폼에 대해 무엇을 알아야 하는지다.
+4 -4
View File
@@ -103,7 +103,7 @@ adapter가 presentation까지 들어온다.
행이 규칙을 맞게 설명하는지는 보지 않는다.
모든 예외는 규칙 자체(`.dependency-cruiser.json`)에 적는다. 예외 경로는
`pathNot`에, 이유·owner·다시 볼 조건은 `comment`에 적는다(리뷰 12-07).
`pathNot`에, 이유·owner·다시 볼 조건은 `comment`에 적는다(리뷰 0925/12-07).
kernel 말고 예외는 다음과 같다:
- 지금 설치된 registry를 읽는 범용 presentation 모듈
@@ -144,7 +144,7 @@ kernel 말고 예외는 다음과 같다:
경계다.
규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계
`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서
import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture).
import하면 실패한다(리뷰 0925/12-07, `dependency-graph/barrel` fixture).
`service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에
들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지
@@ -165,7 +165,7 @@ output 경계를 구현한다.
`check:architecture`는 TypeScript를 이해하는 아래 그래프를 출력한다. 규칙은
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser를 돌리지는 않는다.
dependency-cruiser는 TypeScript 7을 파싱하지 못해 모듈을 하나도 검사하지
못했다(리뷰 12-05):
못했다(리뷰 0925/12-05):
```json
{
@@ -186,7 +186,7 @@ dependency-cruiser는 TypeScript 7을 파싱하지 못해 모듈을 하나도
그래프는 TypeScript와 TSX를 읽는다. static, dynamic, type, CommonJS, JSDoc
import 참조를 모두 포함한다. `import.meta.glob`은 파싱 실패로 처리한다.
모듈 이름을 적지 않고 모듈을 불러오므로 어떤 간선 규칙도 그 모듈을 볼 수
없기 때문이다(리뷰 12-06). 그래프는 `.dependency-cruiser.json`의 경로 규칙을
없기 때문이다(리뷰 0925/12-06). 그래프는 `.dependency-cruiser.json`의 경로 규칙을
적용한다. 로컬 소스 import에는 TypeScript 확장자를 명시하도록 요구한다. 다음
중 하나라도 있으면 통과시키지 않고 실패한다(fail closed): JavaScript 계열
소스·specifier, 지원하지 않는 규칙 모양, 해석되지 않은 import, 파싱 실패,
+73 -7
View File
@@ -201,7 +201,7 @@ Web Push를 함께 설치하지 않는다.
9. runtime config schema, 의존성 inventory/승인, SBOM, bundle budget,
browser support와 runbook을 갱신한다.
운영 CSP(`config/hosting/security-headers.json`)도 여기서 넓힌다. 기본 CSP는
아래 기능을 막는다(리뷰 13-08).
아래 기능을 막는다(리뷰 0925/13-08).
- 다른 origin의 realtime: `connect-src`에 `wss://<realtime origin>`을 더한다.
`https:`는 `wss:`를 허용하지 않는다(CSP3 scheme 비교).
- 파일 preview(`src/adapters/browser-files/object-url-lease.ts`의 object URL):
@@ -229,14 +229,80 @@ Web Push를 함께 설치하지 않는다.
복구한다.
- Web Push permission은 user action에서만 요청하고 subscription endpoint/key와
payload를 storage, URL, telemetry나 application state에 노출하지 않는다.
- detailed status, target contract와 구현 work package는
[Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)을
따른다. 현재 concrete runtime과 product selection은 없다.
- 설계 배경(기록)은
[Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)이다.
현재 concrete runtime과 product selection은 없다.
- 짝 백엔드 템플릿의 실시간 출구(STOMP-over-SockJS, NDJSON)와 이 repo의 SSE·
`realtime.v1` WebSocket 어댑터는 그대로 연결되지 않는다. 지금 두 템플릿만으로
되는 경로는 bounded polling이다. 대응표와 push를 고를 때의 세 길은 설계 문서
[0.1절](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md#01-짝-백엔드-템플릿과의-대응-110304-02)에
있다(1103/04-02).
되는 경로는 bounded polling이다. 대응표와 push를 고를 때의 세 길은 아래
「짝 백엔드 실시간 출구와의 대응」이다(1103/04-02).
- bounded polling의 `execute`가 실행기 결과를 poll attempt 결과로 바꾸는 표는 아래
「poll attempt 결과 대응」이다(1106/04-02).
#### 짝 백엔드 실시간 출구와의 대응
2026-11-08에 설계서가 기록(`docs/design/`)으로 옮겨진 뒤에도 지금 규칙인 표라 여기로 옮겼다(1112/09-02).
결론: 짝 백엔드(`clean-architecture-backend-template`)의 실시간 출구와 이
repo의 SSE·WebSocket 어댑터는 **지금 그대로 연결되는 조합이 없다.** 지금 두
템플릿만으로 되는 경로는 bounded polling 하나다. push가 필요하면 한쪽에 새 코드를
써야 하고, 어느 쪽을 쓸지는 제품이 정한다.
```text
프론트 SSE 어댑터 → Accept: text/event-stream, REALTIME_EVENT_V1 envelope
프론트 WS 어댑터 → subprotocol 정확히 "realtime.v1", REALTIME_EVENT_V1 envelope
짝 백엔드 STOMP 채널 → SockJS /ws, /topic 구독 1개, Map<String,String> 투영, 재전송 없음
짝 백엔드 스트리밍 → NDJSON, JSON text sequence(RFC 7464). SSE writer는 없다
```
| 프론트 transport | 짝 백엔드 출구 | 지금 연결되나 | 이유 |
| --- | --- | --- | --- |
| SSE (`fetch-sse-connection.ts`) | 없음 | 아니오 | 백엔드에 SSE writer가 없다(`StreamMediaType.SSE`는 OpenAPI 생성기만 쓴다). 아키텍처 테스트가 MVC `SseEmitter`를 금지한다(`ForbiddenApiArchitectureTest` `NO_SSE_EMITTER`, 백엔드 결정 D3). 스트리밍 writer는 NDJSON·JSON text sequence뿐이다(`clean-architecture-backend-template/src/adapter/inbound/web-advanced/README.md`) |
| WebSocket (`websocket-connection.ts`) | STOMP-over-SockJS 채널 | 아니오 | 프론트는 협상된 subprotocol이 정확히 `realtime.v1`이어야 연다(`websocket-protocol.ts`). 백엔드에는 subprotocol 협상 코드가 없다. STOMP frame은 `REALTIME_EVENT_V1` envelope(streamEpoch, sequence, eventId, scopeBinding)이 아니다 |
| WebSocket | raw WebSocket 라이브러리 API(`servlet/`) | 아니오(새 코드 필요) | 서비스 어댑터가 handler를 직접 조립한다. `realtime.v1` 협상과 envelope을 구현한 예시는 없다 |
| bounded polling (`bounded-poll-coordinator.ts`) | REST GET + Envelope | **예** | V3 실행기가 짝 백엔드 Envelope을 읽는다. poll 전용 operation의 `retryBudget`을 0으로 둔다(설계서 9.2절) |
push가 필요할 때 고를 길(제품 결정, 리뷰 1103/04-02 결정의 근거):
1. **백엔드에 `realtime.v1` WebSocket handler를 쓴다.** 프론트 어댑터를 그대로
쓰고 `CURSOR` 복구까지 갈 수 있다. 백엔드에 sequence·replay 저장소(outbox)가
필요하다. SSE는 백엔드 결정 D3을 먼저 바꿔야 하므로 이 표에서는 WebSocket을
먼저 적는다.
2. **프론트에 STOMP transport를 쓴다.** 백엔드는 그대로다. STOMP frame에는
sequence·epoch가 없어 stream coordinator의 gap·cursor 기능을 못 쓴다. frame을
query 무효화 hint로만 쓰고 데이터는 snapshot(REST GET)으로 다시 읽는다
(`INVALIDATION_HINT` + `SNAPSHOT_ONLY`). simple broker는 재전송이 없으므로
연결이 끊긴 동안의 변경은 재연결 뒤 snapshot으로만 회복한다.
3. **push 없이 bounded polling만 쓴다.** 두 repo 모두 새 코드가 없다. freshness는
poll 주기(최소 5초)로 정해진다.
다시 볼 때: 백엔드에 `realtime.v1` handler나 SSE writer가 생기거나, 프론트에 STOMP
transport가 생기면 이 표를 고친다. 백엔드 쪽 정본은
`clean-architecture-backend-template/src/adapter/inbound/websocket/README.md`다.
#### poll attempt 결과 대응
`execute`는 실행기 결과를 아래 표대로 poll attempt 결과로 바꾼다(1106/04-02).
poll이 재시도하는 kind는 `retryable: true`인 `CONNECT_TIMEOUT`·`RATE_LIMITED`·
`PROVIDER_UNAVAILABLE`뿐이고, `retryAfterMs`는 뒤 둘만 읽는다.
| V3 결과 `kind` | poll attempt 결과 |
| --- | --- |
| `SUCCESS` | `ok: true`, `kind: "VALUE"`, `value`, terminal 판정에 쓸 `state`. 결과에 본문 크기가 없으므로 `responseBytes`는 `0`을 둔다. 본문 상한은 실행기가 `frontend.responseByteLimit`으로 지킨다(넘으면 `CONTRACT_VIOLATION`). 그래서 poll descriptor의 `responseByteLimit`을 lease `maxResponseBytes` 이하로 둔다 |
| `PROBLEM` | `metadata.status`가 5xx·`408`·`425`이면 `PROVIDER_UNAVAILABLE`, `retryable: true`, `retryAfterMs`는 `metadata.retryAfterMs`. 그 밖의 status는 다시 보내도 같은 답이라 `PROTOCOL_MISMATCH`, `retryable: false`. 설계서 9.4절의 reset 계약이 있는 `409`·`410`만 `CURSOR_EXPIRED`, `retryable: false` |
| `UNAUTHENTICATED` | `AUTH_REQUIRED`, `retryable: false`. lease가 끝나고, session owner가 회복한 뒤 새 lease를 연다(설계서 9.3절) |
| `FORBIDDEN` | `FORBIDDEN`, `retryable: false` |
| `RATE_LIMITED` | `RATE_LIMITED`, `retryable: true`, `retryAfterMs`는 결과의 `retryAfterMs` |
| `CONTRACT_VIOLATION` | `metadata.status`가 5xx·`408`·`425`이면 쓸 수 있는 problem 본문 없이 온 서버 장애라 `PROBLEM`의 장애 행과 같다. 그 밖(입력 거절 `INPUT_INVALID`, 응답 schema·크기 위반)은 `PROTOCOL_MISMATCH`, `retryable: false` |
| `TRANSPORT_FAILURE` | `failure.kind`가 `TIMEOUT`이면 `CONNECT_TIMEOUT`, `retryable: true`. `ABORTED_BY_CALLER`면 `ABORTED`, `ABORTED_BY_SCOPE`면 `SCOPE_FENCED`, 둘 다 `retryable: false`. 나머지(`NETWORK_FAILURE` 등)는 `PROVIDER_UNAVAILABLE`, `retryable: true`. 실행기가 끝낸 transport 실패의 `failure.retryable`은 모두 `false`라 옮기지 않는다 |
| `CANCELLED` | `ABORTED`, `retryable: false` |
| `AUTH_INTEGRATION_FAILURE` | `reason`이 `CREDENTIAL_OWNER_UNAVAILABLE`이면 `PROVIDER_UNAVAILABLE`, `retryable: true`. 그 밖은 구성 결함이라 `PROTOCOL_MISMATCH`, `retryable: false`. 어느 쪽도 로그아웃 경로로 보내지 않는다 |
실패 결과의 `operation`은 모두 `"POLL"`이다. `retryAfterMs`는 값이 있을 때만
칸을 둔다. 값이 `undefined`인 칸은 모양이 틀린 결과라 lease가 `PROTOCOL_MISMATCH`로
끝난다. lease 상태 검사가 결과 해석보다 먼저라, 그사이 hidden·offline·scope
변경·close가 있었으면 표와 상관없이 그 kind로 끝난다. 이 표를 따르는 조합 예는
`tests/unit/realtime/bounded-poll-coordinator.test.ts`의 `pollAttemptResult`다.
- realtime 레지스트리(`createRealtimePolicyRegistry`)가 받는 세 바인딩의 출처
(1103/04-06). 기능 모듈에는 codec·mapper를 낼 칸이 없으므로 조합 코드가 모은다.
- `apiOperations`: `loadInstalledFeatureRuntimeRegistries().apiOperations`
+3 -2
View File
@@ -80,8 +80,9 @@ TypeScript로 쓴 owner는 `ExternalSessionOwner`에 맞춰 더는 컴파일되
## 스타터 확장
새 플랫폼 작업은 따로 노는 라우트 규칙이나 데이터 로딩 규칙을 하나 더 만들지 않는다.
대신 [라우팅, 페이지 템플릿, 재사용 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)과
[TypeScript, 상태, 데이터 흐름 목표](../design/2026-07-26-typescript-state-and-data-flow-design.md)를 따른다.
대신 지금 규칙인 [기능 매뉴얼의 패턴 표](../manual/reference/patterns.md)와 [계층 규칙](layers.md)을 따른다.
설계 배경(기록)은 [라우팅, 페이지 템플릿, 재사용 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)과
[TypeScript, 상태, 데이터 흐름 목표](../design/2026-07-26-typescript-state-and-data-flow-design.md)다.
### 스타터 화면 바꾸기
+5 -5
View File
@@ -1,11 +1,11 @@
# 정적 자산과 runtime 설정 전달
> **정본 안내 (runtime capability 결정의 정본이 아니다)**
> **정본 안내**
>
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
> Service Worker, offline command와 Background Sync의 구현 결정은
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
> 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.
> Service Worker, offline command와 Background Sync의 지금 구현은
> [프론트엔드 애플리케이션 기반](frontend-application-foundation.md)과 `src/bootstrap/`이 정본이다.
> 설계 배경(기록)은 [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)다(1112/02-06).
이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다.
@@ -34,7 +34,7 @@ smoke 단계는 프로젝트의 provider adapter가 맡는다. 그 adapter가 `p
`production_gate` 사이의 `deployment` job을 채운다. adapter가 promotion된
release를 배포하고 나면, FE-GATE-019가 실제 응답 header를 검사하고 host가 그
release를 서빙하는지 확인한다. 그 자리가 비어 있는 동안 FE-GATE-019는
`UNVERIFIED`다(리뷰 13-05, 1101/13-01,
`UNVERIFIED`다(리뷰 0925/13-05, 1101/13-01,
[`release-cache-rollback.md`](../operations/release-cache-rollback.md)).
rollback은 이전 불변 release의 HTML·asset·config·API·manifest 묶음이 서로
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-07-30
- 요약: SSE·WebSocket·Web Push·제한된 Polling을 도입할 때의 선택 기준, 포트 경계, 이벤트 계약, 재연결·복구와 승격 조건을 정한 설계다.
- 현재 정본: `src/adapters/realtime/`, `src/adapters/web-push/`
- 현재 정본: `src/adapters/realtime/`, `src/adapters/web-push/`, `docs/architecture/optional-adapter-recipes.md` 「짝 백엔드 실시간 출구와의 대응」·「poll attempt 결과 대응」(0.1절과 9.2절의 표)
<!-- 머리 블록 끝 -->
# Realtime events, Web Push, and bounded polling
+2 -2
View File
@@ -429,7 +429,7 @@ projectRequest: (input) => Object.freeze({
- `context-routes.ts`: context가 적재하는 라우트 목록. 생성된 판은 계약의 라우트를 그대로 옮긴다.
- `presentation/<base>-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다.
- 문구 `route.<ROUTE_ID>.title`, `route.<ROUTE_ID>.navigation` (ko-KR, en-US). 화면의 문서 제목과 메뉴 이름은 이 문구다.
- 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정(`scripts/test-performance.ts`, 플랫폼 라우트만)이 읽는다. 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다.
- 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정이 읽는다: 공개 기능 라우트 중 `navigationLabel`이 있는 첫 라우트를 재고(`scripts/lib/lab-performance.ts` `labFeatureRoute`), 그 링크와 제목을 그 값으로 찾는다(`scripts/test-performance.ts`). 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다.
- 기능 폴더 밖: `docs/accessibility/route-reviews/<ROUTE_ID>.md`(pending 기록). 생성 명령이 만든다.
① **정할 것**
@@ -814,4 +814,4 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature
- 브라우저 테스트(`playwright test`)를 한 checkout에서 둘 이상 동시에 돌릴 때는 실행마다 다른 `TEST_RUN_ID`를 준다. 예: `TEST_RUN_ID=a corepack pnpm exec playwright test`. 그 실행의 빌드·결과·report는 `.tmp/runs/<id>/` 아래에 생긴다.
- 서버 포트는 run ID가 없어도 빈 포트를 고른다. 같은 기계의 두 worktree도 부딪히지 않는다. 고정하려면 `TEST_E2E_PORT` 같은 포트 변수를 준다.
- `ci:gate`에는 `TEST_RUN_ID`를 주지 않는다. 주면 증거가 기본 경로에 생기지 않아 게이트가 `command-generated evidence was not freshly produced`로 실패한다.
- 변수 표와 한계는 [테스트 전략 13.6절](../design/2026-07-26-frontend-platform-testing-strategy-design.md)에 있다(1105/12-04).
- 변수 목록의 정본은 `scripts/lib/run-isolation.ts`(`TEST_RUN_ID_VARIABLE`, `TEST_PORT_VARIABLES`)다. 설계 배경(기록)은 [테스트 전략 13.6절](../design/2026-07-26-frontend-platform-testing-strategy-design.md)이다(1105/12-04).
+1 -1
View File
@@ -122,7 +122,7 @@ release admission refused for staging:
- `label`은 `browser-files` 같은 소문자 kebab-case 토큰으로 쓴다. 다른 형식이면 조립이 `TypeError`로 멈춘다.
- `close`가 던지면 scope가 `FAILED`에 머물고 모든 서버 요청이 `SCOPE_FENCED`로 막힌다. 진단 `cache.operation.failed`에 `reason: PARTICIPANT_FAILED`와 `scope_participant: <label>`이 남으니 그 기록으로 원인 closer를 찾는다.
- 템플릿 파일 `src/bootstrap/runtime-adapters.ts`는 고치지 않는다.
- 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·`realtime.v1` WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: [realtime 설계 0.1절](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md#01-짝-백엔드-템플릿과의-대응-110304-02).
- 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·`realtime.v1` WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: [optional adapter recipe 「짝 백엔드 실시간 출구와의 대응」](../architecture/optional-adapter-recipes.md#짝-백엔드-실시간-출구와의-대응).
- `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때.
- 템플릿 파일 `src/contracts/rest-profiles.ts`는 고치지 않는다.
- 설정 키 이름에 `TOKEN`·`COOKIE`·`SECRET`·`PASSWORD` 같은 조각(`src/contracts/env.ts`의 `FORBIDDEN_CONFIG_NAME_FRAGMENTS`, 대소문자 무관)을 넣지 않는다. 부팅이 `CONFIG_SECRET_NAME_REJECTED`로 멈추고, 오류 화면의 "잘못된 설정 키"에 그 키 이름(값은 아님. 중첩 키는 `CAPABILITY_OVERRIDES.AUTH_TOKEN`처럼 경로)이 나온다. `test:unit`의 `env-registry-coverage`가 먼저 `Forbidden client configuration key: <키>`로 실패한다.
+1 -1
View File
@@ -3,7 +3,7 @@
이 폴더는 이 템플릿으로 만든 프로젝트에 **새 기능 하나를 추가하는 절차**를 적는다.
기능 하나는 화면(라우트와 페이지)과 그 화면이 쓰는 API 호출을 함께 뜻한다.
시작은 `corepack pnpm create:feature <id>`다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다(브라우저 게이트는 드릴 밖, `docs/manual/reference/create-feature.md`).
시작은 `corepack pnpm create:feature <id>`다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다. 명령이 출력하는 `Next:`의 초기 JS 기록 다시 쓰기까지 해야 통과한다(브라우저 게이트는 드릴 밖, `docs/manual/reference/create-feature.md`).
그 뒤 이 매뉴얼의 단계대로 뼈대를 실제 기능으로 바꾼다.
## 누가 읽는가
+6 -1
View File
@@ -1,6 +1,6 @@
# create:feature 참조
모든 merge 게이트를 통과하는 가장 작은 기능을 만드는 명령이다. 정본은 `scripts/create-feature.ts`이고, `--with-create`가 더하는 부분은 `scripts/create-feature-write-slice.ts`다.
모든 merge 게이트를 통과하는 가장 작은 기능을 만드는 명령이다. 출력의 `Next:` 3(초기 JS 기록 다시 쓰기)까지 하면 통과한다. 정본은 `scripts/create-feature.ts`이고, `--with-create`가 더하는 부분은 `scripts/create-feature-write-slice.ts`다.
`test:feature-scaffold`가 생성한 기능으로 `config/ci/gates.json`의 merge 단계 명령을 돌려 확인한다. 브라우저 게이트(FE-GATE-008·009의 브라우저 명령)와 `test:system`은 빼고 돈다. 뺀 명령과 이유는 `scripts/lib/feature-scaffold-drill.ts`에 있다.
템플릿 문자열이 두 파일 안에 있고, 다른 기능을 import하지 않는다. 그래서 기능이 하나도 없는 템플릿에서도 동작한다.
@@ -122,6 +122,8 @@ Next:
1. Before a release, have a person review and sign docs/accessibility/route-reviews/<ROUTE_ID>.md (FE-GATE-028). ...
2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage ...
The feature's own tests: node scripts/run-vitest.ts run tests/features/<id> ...
3. The initial JavaScript changes. Rewrite config/scale/feature-shape-ceilings.json with node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write ...
public/release-manifest.json (the dev server's manifest) now names the feature's contract package; ...
The registry baseline does not change: ...
```
@@ -142,8 +144,11 @@ rm -r src/features/<id> tests/features/<id> docs/accessibility/route-reviews/<RO
rm -r src/contexts/<base>-context # 새 context를 만들었을 때만
corepack pnpm generate:feature-index
node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의 계약 패키지를 뺀다
node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write # 초기 JS 기록을 다시 쓴다
```
기능을 만든 뒤 오래 썼으면 지울 것이 더 있다. 목록은 [03 문서의 "기능을 지울 때"](../03-outside-feature-folder.md#기능을-지울-때)다.
생성 명령은 `public/release-manifest.json`(dev server가 내주는 manifest)의 `contractSet`에 기능의 계약 패키지를 더한다. 기능과 함께 커밋한다. 낡으면 `tests/unit/dev-release-manifest.test.ts`가 다시 쓰는 명령을 말하며 실패하고, `corepack pnpm dev`는 `CONTRACT_SET_PACKAGE_MISSING`·`CONTRACT_SET_PACKAGE_UNEXPECTED`로 부팅하지 못한다.
## 이 명령을 지키는 검사
+7 -21
View File
@@ -36,7 +36,7 @@ package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경
닿는 스크립트를 이 목록에 남겨 두면 실패한다. 두 목록에 남은 항목과 이유는 각
파일에 있다.
규모 테스트는 이렇게 나뉜다(리뷰 11-03, `scripts/scale/run-scale-profile.ts`).
규모 테스트는 이렇게 나뉜다(리뷰 0925/11-03, `scripts/scale/run-scale-profile.ts`).
- `check:scale:pr`은 merge gate `FE-GATE-005`에서 돈다. 개수·상한·증가 모양만
검사하므로 CPU가 달라도 결과가 같다. S0~S2 조합 증가 검사가 여기 있다. S0/S1만
@@ -55,7 +55,7 @@ package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경
|---|---|---|---|
| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가(`changeId`, 그 변경 뒤 값 `after`(삭제는 생략, 값은 JSON 그대로이고 키·원시값 배열 순서는 상관없다), `versionBump`·`migration`·`compatibilityWindow`·`rollback`·`owner`). 같은 칸을 다시 바꾸면 `after`가 달라 새 항목이 필요하다. 지금 diff의 breaking 변경과 changeId가 맞지 않는 항목이 있으면 게이트가 그 항목을 나열하며 실패한다. `update:registry-baseline`은 새 기준선이 설명하는 항목을 모두 지운다(지운 항목은 git 이력에 남는다) | `scripts/check-registries.ts`의 baseline 비교 |
| 커버리지 모듈 수 하한 | `config/testing/risk-coverage.json`의 `repositoryBaseline` | 직접 수정. 지운 production 모듈 수만큼 줄인다(`scripts/test-sample-removal.ts`가 같은 계산을 한다) | `scripts/lib/risk-coverage.ts` "repository module baseline" |
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 실패하는 검사는 없다. 남은 키는 아무것도 끄지 않고, `check:release-admission`(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES.<id> … the override does nothing`을, 부팅이 진단 `feature.override.unknown`(warn)을 남긴다(리뷰 09-09) |
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 실패하는 검사는 없다. 남은 키는 아무것도 끄지 않고, `check:release-admission`(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES.<id> … the override does nothing`을, 부팅이 진단 `feature.override.unknown`(warn)을 남긴다(리뷰 0925/09-09) |
| 의존성 목록 | `config/security/dependency-baseline.json`, `dependency-baseline.approval.json` | `update:dependency-baseline` (`DEPENDENCY_BASELINE_OWNER`·`_REASON` 필수) | `scripts/generate-supply-chain.ts` |
계약을 불러올 때, runner가 실행 callback에 들어가기 전에 등록된 명령 항목을 모두
@@ -87,7 +87,7 @@ token으로 나눈 명령이 npm을 부르면 대소문자와 상관없이 `npm_
callback에 들어가기 전에 물려받은 환경 변수에서도 같은 이름을 검사한다. 그래서 그 이름은
자식 게이트 process에 닿지 못한다.
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 12-10에서 줄일 수
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 0925/12-10에서 줄일 수
있는지 확인했고 남겼다. workflow 설치의 `--ignore-scripts`와
`pnpm-workspace.yaml`의 `allowBuilds`로는 막히지 않는 위험이 있기 때문이다.
첫째, 게이트 명령이 직접 설치를 돈다(`verify:lockfile`, 제거 fixture).
@@ -108,29 +108,15 @@ MERGE_READY
DOCUMENTATION_READY (off-chain)
```
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위는 좁다
(`scripts/verify-documentation-readiness.ts`).
- 설치된 라우트마다 수동 접근성 기록 `docs/accessibility/route-reviews/<ROUTE_ID>.md`가
있는지. 없으면 route ID를 적고 실패한다
- README가 빌드와 승인 단계가 읽는 환경 변수를 모두 적는지
- 입구 문서가 실제 `src` 최상위 폴더와 `.dependency-cruiser.json` 규칙 이름을
적는지
- `docs/README.md` 1절의 현재 계약 문서에 적힌 repo 경로·링크·package script·
FE-GATE ID가 실제로 있는지. 짝 백엔드 경로는 옆 checkout의 작업 트리가 아니라
`config/contracts/backend-contract-pin.json`이 고정한 커밋에서 찾고, 그 커밋을
읽을 수 없으면 확인하지 못한 것으로 남긴다
- 2026-07-18 diagram 리뷰 기록의 두 사본(`docs/architecture/review-ledger.json`,
`review-evidence.md`)이 같은 해시·점수를 담는지. 원본 diagram은 repo 밖에
있으므로 이 항목은 구조가 바뀌어도 통과한다
문서의 다른 내용(수치, 목록, 설명)이 코드와 맞는지는 검사하지 않는다(리뷰 14-07).
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위와 방법은 `docs/README.md` 5절과
`docs/work/reference/gates.md` 「문서 검사」가 정본이다(코드는 `scripts/verify-documentation-readiness.ts`,
`scripts/lib/docs-system.ts`). 여기에 목록을 다시 적지 않는다(1112/08-07).
`check:architecture`는 Babel parser/Node resolver 기반 `staticImportGraph`를
`artifacts/quality/dependency-report.json`에 기록한다. 규칙은
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser는 실행하지 않는다.
dependency-cruiser 18은 TypeScript 7을 해석하지 못해 0개 모듈을 검사하고
통과했다(리뷰 12-05). TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
통과했다(리뷰 0925/12-05). TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
로컬 source import에는 실제 TypeScript 확장자를 요구한다. 실행 source나 로컬
specifier에 `.js/.jsx/.mjs/.cjs`가 있거나 unresolved dependency, parse failure,
error-severity layer violation, cycle 또는 지원하지 않는 architecture rule
+1 -1
View File
@@ -101,7 +101,7 @@
예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다.
lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build를
`vite preview --strictPort`로 띄워 잰다(리뷰 11-07).
`vite preview --strictPort`로 띄워 잰다(리뷰 0925/11-07).
- 포트는 `LAB_PERFORMANCE_PORT`(기본 4173)다. 서버를 띄우기 전에 그 포트가
이미 응답하면 실패하고, 응답하는 `/release-manifest.json`의 build·release가
+2 -2
View File
@@ -12,7 +12,7 @@
확인한다.
승격(promotion)한 release를 나중에 배포하거나 그 release로 롤백하기 전에는 승격
묶음(`promotion` job이 올린 파일 다섯 개)을 archived 모드로 다시 검증한다(리뷰 13-04).
묶음(`promotion` job이 올린 파일 다섯 개)을 archived 모드로 다시 검증한다(리뷰 0925/13-04).
provider evidence는 발급 두 시간 뒤 만료된다. 그래서 일반 모드는 그보다 먼저 승격한
release를 모두 거절한다. archived 모드도 서명, digest, 정확한 다섯 member를 검사한다.
다만 신선도는 release에 기록된 승격 시각으로 판단한다
@@ -56,7 +56,7 @@ HTML, JSON config/manifest, hashed JavaScript의 MIME type도 선언한 허용
`HOSTING_BASE_URL`이 없으면 `corepack pnpm verify:hosting-headers`는 선언한 헤더를
결정적(deterministic) fixture와 비교한다. 이것은 선언끼리 서로 맞는다는 것만 보여 준다.
그래서 결과는 `PASS`가 아니라 `UNVERIFIED`(exit 3)다
(리뷰 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). 통과할 수 있는 것은
(리뷰 0925/13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). 통과할 수 있는 것은
`mode: "live"`뿐이다. live 대상은 loopback이 아닌 정식(canonical) HTTPS 루트 URL이어야
한다. 필요한 surface마다 그 origin을 벗어나지 않고 HTTP 200을 돌려줘야 한다. 그래야 그
surface의 캐시, content-type, 보안 헤더를 배포 증거로 셀 수 있다. probe가 요청하는
+2 -2
View File
@@ -4,7 +4,7 @@
>
> GOV-01. 이 표는 손으로 센 숫자가 아니라 `corepack pnpm check:adapter-inventory`가 `git ls-files src/adapters`와 정확히 대조하는 목록이다.
>
> `rg --files src/adapters | sort` 결과 119개를 하나씩 고정한 coverage ledger다. 책임·의존성·finding·유지/변경 판정은 연결된 상세 리뷰의 파일별 표를 따른다.
> `rg --files src/adapters | sort` 결과를 하나씩 고정한 coverage ledger다(개수는 아래 합계 줄). 책임·의존성·finding·유지/변경 판정은 연결된 상세 리뷰의 파일별 표를 따른다.
| # | full path | 상세 리뷰 |
| ---: | --- | --- |
@@ -152,5 +152,5 @@
| 142 | `src/adapters/AGENTS.md` | 계층 규칙 문서(코드 아님, 리뷰 대상 아님) |
| 143 | `src/adapters/CLAUDE.md` | 위 문서를 가져오는 한 줄(`@AGENTS.md`) |
합계: **143/143**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
합계: **143/143**. 새 adapter 파일이 추가되면 이 ledger를 같은 변경에서 갱신한다. 연결된 상세 리뷰는 그 리뷰 때의 기록이라 고치지 않는다. 상세 리뷰에 없는 파일은 그 행의 상세 리뷰 칸에 가장 가까운 묶음을 적는다.
+1 -1
View File
@@ -9,7 +9,7 @@ production source map.
뺀다. production 코드와 빌드된 asset은 이 기준선에서도 동작해야 한다.
`tests/e2e/production-csp.spec.ts`(`test:e2e`의 일부, FE-GATE-008)는 이 header로
빌드를 서빙한다. 그리고 `securitypolicyviolation` 이벤트나 console 오류가 나면
실패한다(리뷰 13-08). zod는 첫 object schema에서 `Function("")`을 시험 삼아
실패한다(리뷰 0925/13-08). zod는 첫 object schema에서 `Function("")`을 시험 삼아
실행한다. 그러면 정책이 부트할 때마다 이것을 위반으로 보고한다.
`src/contracts/zod.ts`는 `jitless`를 켜서 이 시험을 건너뛴다. schema를 만드는
모든 모듈은 `z`를 그 파일에서 import한다. 그래서 bundler가 chunk를 어떤 순서로
+5 -4
View File
@@ -21,8 +21,9 @@
- 새 직접 production 의존성에 대한 독립 리뷰
- CycloneDX 1.6 SBOM, 그리고 inventory와의 component·edge 일치
- source·lock·SBOM·dist를 묶은 local provenance 문서(statement)
- secret scan. 대상은 source, 선택해서 켜는(opt-in) recipe, script, 테스트,
추적되는 config/schema, public 폴더, 빌드된 asset, 생성된 release metadata다
- secret scan. 대상은 추적되는 파일 전부(`git ls-files`, 문서와 `.env.example` 포함)와
빌드된 `dist`, 생성된 `artifacts/release`다(`scripts/lib/repository-file-inventory.ts`).
정책의 `trackedRoots`는 대상을 좁히지 않는다. 비어 있으면 안 되는 루트 목록이다
- 두 번 빌드해 비교하는 `SOURCE_DATE_EPOCH` 재현성 검사
기준 명령은 다음과 같다.
@@ -41,7 +42,7 @@ corepack pnpm check:supply-chain:fixtures
## 무엇을 증명하고 무엇을 증명하지 않는가
리뷰 13-12. 산출물마다 증명 범위가 다르다. 아래 "증명하지 못하는 것"을 증명된
리뷰 0925/13-12. 산출물마다 증명 범위가 다르다. 아래 "증명하지 못하는 것"을 증명된
것으로 읽지 않는다.
| 산출물 | 증명하는 것 | 증명하지 못하는 것 |
@@ -64,7 +65,7 @@ corepack pnpm check:supply-chain:fixtures
## 최소 구성과 전체 구성
리뷰 13-13. 승격 단계까지 쓰려면 이 문서 아래의 runner 조건(bwrap, prlimit,
리뷰 0925/13-13. 승격 단계까지 쓰려면 이 문서 아래의 runner 조건(bwrap, prlimit,
systemd-run, systemd user manager 254 이상, cgroup v2 위임)과 오프라인 데이터로
Ed25519 서명 보고서를 내는 provider 두 개가 필요하다. 이 repo는 그 환경에서
workflow 전체를 한 번도 돌리지 않았다. 그래서 두 구성을 나눠 적는다.
+1 -1
View File
@@ -70,6 +70,6 @@
## 8. 이 폴더를 고칠 때
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 15줄, 폴더 지역 규칙(`src/**/AGENTS.md`, 옆에 `@AGENTS.md` 한 줄 `CLAUDE.md`) 200줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
- 분량 상한이 있다: 지도(루트 `AGENTS.md`), 루트 `CLAUDE.md`, 폴더 지역 규칙(`src/**/AGENTS.md`, 옆에 `@AGENTS.md` 한 줄 `CLAUDE.md`), 이 README, playbook, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나). 줄 수의 정본은 `scripts/check-work-docs.py`의 상수이고, 넘으면 그 검사가 상한과 함께 알린다. `reference/`는 상한이 없다.
- 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서도 같다. `reference/decisions.md`·`reference/defect-patterns.md`와 리뷰 문서는 ID를 둔다.
- 고친 뒤 `scripts/verify.sh docs`(노트북)와 desktop `scripts/verify.sh script verify:documentation`이 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
+1 -1
View File
@@ -77,7 +77,7 @@
### 4.4 수정 라운드와 묶음
- 통합 브랜치 `fix/maturity-review-<YYYY-MM-DD>`(리뷰 날짜)를 만들고, 영역별 수정은 각자 worktree의 브랜치에서 한다. 다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다. CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다.
- 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 커밋 전 게이트를 돌린다. 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 적는다. 합친 트리에서 merge 단계를 돌리고 회차별 결과를 표로 남긴다.
- 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 커밋 전 게이트를 돌린다. 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 적는다. 합친 트리에서 merge 단계를 돌리고 회차별 결과를 표로 남긴다. 통합에서 커밋을 다시 지었으면(fixup 접기, rebase) 커밋 본문과 CHANGELOG가 적은 해시를 `git merge-base --is-ancestor <해시> <브랜치 끝>`으로 하나씩 대조하고, 결과를 PR 본문 「검증」에 적는다. 리뷰 라운드가 아닌 정리·기능 통합도 같다.
- 큰 라운드는 작은 PR로 나눈다. 자기완결적인 변경 하나에 PR 하나(대략 100줄, 1,000줄이면 너무 크다). 리팩터링과 동작 변경은 PR을 나눈다. 병합은 소유자가 한다. 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다(발견 수가 줄어드는지 볼 수 없다).
### 4.5 멈춤 기준 — 이 repo는 하나다
+1 -1
View File
@@ -94,7 +94,7 @@
## 9. 자주 하는 실수
- 노트북 checkout에서 한 파일 테스트쯤은 괜찮다고 돌린다. 한 파일도 desktop에서 `scripts/verify.sh script`나 `ssh desktop`으로 돌린다.
- 노트북 checkout에서 한 파일 테스트쯤은 괜찮다고 돌린다. 한 파일도 desktop에서 `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`로 돌린다(4.1절).
- 한 테스트 파일을 `pnpm exec vitest run <file>`로 돌려 생성물이 없어 실패한다. `node scripts/run-vitest.ts run <file>`을 쓴다.
- 캐시된 산출물(`dist/`, `artifacts/`)이 남은 checkout에서 돌려 다른 실행의 결과를 읽는다. `scripts/verify.sh`의 새 worktree를 쓴다.
- 게이트 로그 대신 `ci:gate`의 마지막 줄만 옮긴다. `gate-artifacts/FE-GATE-0NN.txt`에서 숫자를 옮긴다.
+4 -3
View File
@@ -49,9 +49,10 @@ scripts/verify.sh <단계> [대상…] [--on here|<호스트>] [--log <이름>]
| 브랜치를 합칠 때마다 | 커밋 전 8개. 합친 뒤에만 생긴 실패는 기록한다 |
| merge 가능이라고 말하기 전 | `scripts/verify.sh merge`(3절) |
| 리뷰 시작 | `scripts/verify.sh merge`와 `scripts/verify.sh documentation`(FE-GATE-017) |
| 라우트 로딩·청크·초기 화면을 바꿀 때 | merge에 더해 `check:bundle`(FE-GATE-012)과 lab 게이트 `test:performance`(FE-GATE-026) |
| 라우트 로딩·청크·초기 화면을 바꿀 때 | merge 단계(`check:bundle`의 FE-GATE-012 포함)에 더해 lab 게이트 `test:performance`(FE-GATE-026) |
| 공급망·release 경로를 바꿀 때 | `scripts/verify.sh release` |
| 작업 매뉴얼·훅을 바꿀 때 | 노트북 `scripts/verify.sh docs`, `scripts/verify.sh hooks` |
| 작업 매뉴얼·훅을 바꿀 때 | 노트북 `scripts/verify.sh docs`, `scripts/verify.sh hooks`. 문서(작업 매뉴얼, `.claude/` 아래 문서, `AGENTS.md`·`CLAUDE.md` 포함)를 바꿨으면 desktop `scripts/verify.sh script verify:documentation`도 |
| 검사 script·그 fixture를 바꿀 때 | merge에 더해 `scripts/verify.sh gate FE-GATE-029`(검사기 자기 시험은 main 단계에 있다) |
release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않은 일이 있다. 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
@@ -103,7 +104,7 @@ release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회
`verify:documentation`(FE-GATE-017, documentation 단계)이 문서를 검사하는 범위와 방법의 정본은 `scripts/verify-documentation-readiness.ts`, `scripts/lib/docs-system.ts`와 `docs/README.md` 5절이다.
- **범위:** 살아 있는 문서 전부(루트 `AGENTS.md`·`README.md`, `docs/` 아래 기록 밖 문서, `src/`의 `AGENTS.md`·모듈 README, `.claude/` 아래 문서). 기록(`docs/design/`, `docs/history/`, `docs/adr/`)은 머리 블록만 본다.
- **범위:** 살아 있는 문서 전부(루트 `AGENTS.md`·`README.md`, `docs/` 아래 기록 밖 문서, `src/`의 `AGENTS.md`·모듈 README, `.claude/` 아래 문서). 기록(`docs/design/`, `docs/history/`)은 머리 블록만 보고, 결정 기록(`docs/adr/`)은 본문의 언어·문체도 본다.
- **보는 것:** 언어(한국어인가), 문체(「~한다」), 숫자 복사, 기록의 머리 블록, 문서 지도와 루트 README 필수 절. 그리고 백틱 안의 repo 경로(`:줄` 꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크, `corepack pnpm <script>`와 백틱 안 `<prefix>:<name>` 꼴의 package script, `FE-GATE-0NN` ID가 실제로 있는가. 설명·수치가 코드와 맞는지는 보지 않는다.
- **예외:** git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트 `README.md`의 지워도 되는 파일 표)은 없어도 된다.
- **짝 백엔드 경로:** `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다. 옆 checkout이 없거나 그 커밋이 없으면 실패가 아니라 "확인 못 함"으로 남긴다.
+2 -2
View File
@@ -21,7 +21,7 @@ src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
| 규칙 예외의 이유·담당·재검토 조건 | 그 규칙의 `comment` | 사람이 본다 |
| adapter 그룹의 공개 경계 | 규칙 `adapter-groups-are-reached-through-their-barrel` | `check:architecture`, 고정 fixture `tests/fixtures/architecture/dependency-graph/barrel` |
| adapter 파일 목록 | `docs/reviews/adapters/INVENTORY.md` | `check:adapter-inventory`(FE-GATE-010) |
| 공유 타입·프리미티브를 어디에 둘지 | `docs/architecture/contract-ownership.md` 「Decision rule」 | 사람이 본다 |
| 공유 타입·프리미티브를 어디에 둘지 | `docs/architecture/contract-ownership.md` 「판단 규칙」 | 사람이 본다 |
| 기능 폴더의 모양 | `docs/manual/01-add-a-feature.md`, `create:feature`가 만드는 파일 | FE-GATE-020의 `test:feature-scaffold` |
| 재시도 의미, 결과 불명, 인증, 업로드의 판단 기준 | `docs/manual/02-decision-tables.md` | 사람이 본다 |
| 오류·재시도·실패 경계·trace 모델 | `docs/architecture/scale-architecture.md`(코드 주석의 `scale-architecture.md §N`) | 사람이 본다 |
@@ -84,7 +84,7 @@ src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
- **repo 안:** 스키마 메타, 레지스트리 행, 허용 키 목록, 빌드 입력 목록, 저장 키를 원본(zod 스키마, descriptor, registry)에서 뽑는다. 손으로 다시 적어야 하면 원본과 대조하는 테스트를 같이 둔다. 두 검사기가 같은 산출물을 다른 키 목록으로 읽어 merge 게이트가 항상 실패한 일이 있다(결함 패턴 S1).
- **이미 갈라진 복사본은 하나로 합친다.** 갈라진 recipe port는 지우고 `src` port를 다시 내보낸다.
- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 옮길 때는 백엔드 문서만 보지 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 일이 있다. 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 테스트로 묶는다. pin과 drift 검사는 아직 계약 문서 글자만 비교하고, 답 표 JSON과 생성기 사실은 대조 밖이다(결함 패턴 S2).
- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 옮길 때는 백엔드 문서만 보지 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 일이 있다. 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 테스트로 묶는다. drift 검사(`check:backend-contract-drift`)는 계약 문서 글자, 답 표 JSON(pin 사본과), 생성기 원본 파일이 pin 뒤에 바뀌었는지를 본다. 옮긴 사실의 내용 자체는 대조하지 않는다(결함 패턴 S2).
- 짝 백엔드 repo는 읽기만 한다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다.
## 9. 코드 기준 — 지우거나 바꿀 때
@@ -117,7 +117,8 @@ export type BoundedPollCoordinatorDependencies<
* (the V3 executor returns a rejected fetch as NETWORK_FAILURE). A throw,
* like a result of the wrong shape, ends the lease with PROTOCOL_MISMATCH
* and is not retried: it is a composition defect, not a server outage.
* Design 9.2 maps each V3 executor outcome to a result.
* docs/architecture/optional-adapter-recipes.md 「poll attempt 결과 대응」
* maps each V3 executor outcome to a result.
*/
execute(input: Readonly<{
operationId: string;
+2 -2
View File
@@ -1,6 +1,6 @@
# AGENTS.md — `src/contracts` (공유 어휘와 레지스트리)
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「Decision rule」이다.
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「판단 규칙」이다.
## 지킬 것
@@ -13,5 +13,5 @@
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:registries`(FE-GATE-010 안), `test:runtime-schema`(FE-GATE-004)
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-007)
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-005의 `tests/unit/backend-contract-pin.test.ts`·`backend-contract-pin-document.test.ts`, FE-GATE-007의 `tests/integration/fileserver-upload.test.ts`)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/runtime-schema`, `tests/unit`에 둔다(`.claude/rules/tests.md`).