docs: 문서 체계 후속으로 VD 보완 표시와 낡은 서술을 고친다 #20

Merged
donghyeon.kang merged 5 commits from donghyeon.kang/claude/fe-b-docs-followup AGit into main 2026-11-12 01:43:20 +00:00
15 changed files with 98 additions and 57 deletions
+1 -1
View File
@@ -251,7 +251,7 @@
},
{
"name": "adapters-do-not-know-other-concrete-adapters",
"comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.",
"comment": "docs/architecture/layers.md, section \"adapter kernel\": a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.",
"severity": "error",
"from": {
"path": "^src/adapters/([^/]+)/"
+5 -1
View File
@@ -43,7 +43,7 @@
## 미출시 — `48c7695b` → 정리 단계
2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지), 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`), 4단계에 남은 R2·R5 검사(브랜치 `chore/layout-rules-r2-r5`, `3f64c689`부터 브랜치 끝까지)를 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다.
2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지), 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`), 4단계에 남은 R2·R5 검사(브랜치 `chore/layout-rules-r2-r5`, `3f64c689`부터 브랜치 끝까지), 문서 체계 후속(브랜치 `claude/fe-b-docs-followup`, `8acf07c2`부터 브랜치 끝까지)을 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다.
### 먼저 할 일 (BREAKING)
@@ -123,6 +123,10 @@
- 문서 검사는 라우트별 수동 접근성 기록(`docs/accessibility/route-reviews/`)을 문서로 보지 않는다. 정해진 영어 키 형식의 게이트 입력이다 (`e9e98b8a`).
- `SPEC.md`의 공통 완료 기준은 하네스 범위가 `docs/work/improve.md` 5절로 옮겼다. 이 범위가 먼저 만든 사본 `docs/manual/reference/done-criteria.md`는 지웠다(`ee5e19f4`에서 만들고 뒤 커밋에서 지움).
- 설정 파일의 설명 칸(recipe 카탈로그, runbook 등록, 규모 상한, 짝 백엔드 pin의 `fact`, secret scan 허용 이유)을 한국어로 옮겼다. 키와 값의 모양은 그대로다 (`309631e4`).
- 결정 뒤 본문을 제자리에서 고친 VD-09·11·13의 상태를 「채택(보완)」으로 올리고, 맨 아래 「보완」 절에 고친 날짜와 커밋을 적었다. 본문은 그대로다 (`8acf07c2`).
- 번역할 때 남겨 둔 낡은 서술 일곱 곳을 코드·설정에 맞췄다: 계약 파일 수는 `src/contracts/`를 가리키고, Local Draft는 테스트 fixture라고 쓰고, 초기 JS 파일 수의 기준은 feature가 없는 빌드다. `.dependency-cruiser.json` 주석은 절 이름을 쓰고, runbook 문서 제목은 `runbooks.json` title과 같다. zod advisory 행의 잰 버전을 밝히고, runbook record 고정 경로 문단의 두 문장을 제자리로 옮겼다 (`374af986`).
- `drill:runbook`의 복구 확인 항목 이름이 `runbooks.json`의 `recoveryEvidence`와 같다. `record.json`의 `assertion` 값이 한국어가 되고, `tests/unit/runbook-drill.test.ts`가 이름과 순서를 대조한다. 자기 `recoveryEvidence`를 고쳤으면 drill 이름도 같이 고친다 (`6571d8cb`).
- `config/ci/ungated-scripts.json`의 `reason`을 한국어로 옮겼다 (`b824195c`).
### 알려진 제한
+18 -18
View File
@@ -3,75 +3,75 @@
"entries": [
{
"script": "check:backend-contract-drift",
"reason": "1103/12-06, 1105/07-01. Compares the paired backend checkout (--backend, or beside the main checkout) with config/contracts/backend-contract-pin.json: the copied table excerpt and the answer table against the pinned document, and the document between the pin and the backend's HEAD. CI checks out this repository alone, so a gate has no backend to read; with no checkout the script exits 2 (not compared), never 0. The gated half is tests/unit/backend-contract-pin.test.ts (test:unit), which holds the Envelope table to the answer table and the answer table to the excerpt. Run this after pulling the backend and before moving the pin (docs/manual/01-add-a-feature.md)."
"reason": "1103/12-06, 1105/07-01. 짝 백엔드 checkout(--backend, 없으면 메인 checkout 옆)을 config/contracts/backend-contract-pin.json과 비교한다. 옮겨 둔 표 발췌와 답 표를 pin한 문서와 대조하고, pin과 백엔드 HEAD 사이에 문서가 바뀌었는지 본다. CI는 이 repo만 checkout하므로 게이트에는 읽을 백엔드가 없다. checkout이 없으면 이 script는 0이 아니라 2(비교하지 못함)로 끝난다. 게이트가 도는 쪽은 tests/unit/backend-contract-pin.test.ts(test:unit)이고, Envelope 표를 답 표에, 답 표를 발췌에 맞춰 본다. 백엔드를 pull한 뒤와 pin을 옮기기 전에 돌린다(docs/manual/01-add-a-feature.md)."
},
{
"script": "check:feature-index",
"reason": "Local check that the generated indexes (src/.generated/, not committed) are current, and the first step of verify:extreme-scale (scripts/verify-extreme-scale.ts), itself a local run. A gate gains nothing from it: every gate script regenerates the indexes first (generate-product-feature-index.ts)."
"reason": "커밋하지 않는 생성 색인(src/.generated/)이 최신인지 보는 로컬 검사이고, 그 자체가 로컬 실행인 verify:extreme-scale(scripts/verify-extreme-scale.ts)의 첫 단계다. 게이트에 넣어도 얻는 것이 없다. 모든 게이트 script가 먼저 색인을 다시 만든다(generate-product-feature-index.ts)."
},
{
"script": "check:http-scenario-evidence",
"reason": "Run by scripts/run-http-scenario-evidence.ts, which is test:http-scenario-evidence in FE-GATE-007; that runner calls it by name after the scenario catalog."
"reason": "scripts/run-http-scenario-evidence.ts가 돌린다. 이 runner는 FE-GATE-007의 test:http-scenario-evidence이고, scenario catalog 다음에 이 script를 이름으로 부른다."
},
{
"script": "check:http-scenario-evidence:fixture",
"reason": "Negative fixture run by scripts/run-http-scenario-evidence.ts (test:http-scenario-evidence, FE-GATE-007), which requires it to fail with TEST-EVIDENCE-EXECUTION-ID-MISSING."
"reason": "scripts/run-http-scenario-evidence.ts(test:http-scenario-evidence, FE-GATE-007)가 돌리는 음성 fixture다. 그 runner는 이 script가 TEST-EVIDENCE-EXECUTION-ID-MISSING으로 실패해야 통과로 본다."
},
{
"script": "check:remediation-ledger",
"reason": "Checks the prose ledger of the 2026-08-14 adapter re-review (docs/operations/adapter-remediation-ledger.md) against test-file markers and the file-transfer bundle budget. It is a history record run by hand, not a current contract: it fails when a product removes the optional file-transfer recipe or when a test split moves a marked test to another file, and neither should block a merge. Run it after moving those tests or changing that budget, and point the ledger rows at the new files."
"reason": "2026-08-14 adapter 재검토의 문장 원장(docs/operations/adapter-remediation-ledger.md)을 테스트 파일 표식과 file-transfer 번들 예산에 대조한다. 지금 계약이 아니라 손으로 돌리는 이력 기록이다. 제품이 선택 recipe인 file-transfer를 지우거나 테스트를 나누다 표식이 있는 테스트가 다른 파일로 옮겨 가면 실패하는데, 둘 다 merge를 막을 일이 아니다. 그런 테스트를 옮기거나 그 예산을 바꾼 뒤에 돌리고, 원장 행이 새 파일을 가리키게 고친다."
},
{
"script": "check:scale:baseline",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
"reason": "CI 밖의 scale 단계다(scripts/scale/run-scale-profile.ts). baseline-regression을 포함하는데, 이 검사는 config/scale/benchmark-baseline.json을 기록한 CPU 모델에서만 시간을 비교하고 다른 곳에서는 incomplete로 보고한다(리뷰 11-03). 그 기계에서 돌린다. CPU와 상관없는 pr 단계는 FE-GATE-005에서 돈다."
},
{
"script": "check:scale:main",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
"reason": "CI 밖의 scale 단계다(scripts/scale/run-scale-profile.ts). baseline-regression을 포함하는데, 이 검사는 config/scale/benchmark-baseline.json을 기록한 CPU 모델에서만 시간을 비교하고 다른 곳에서는 incomplete로 보고한다(리뷰 11-03). 그 기계에서 돌린다. CPU와 상관없는 pr 단계는 FE-GATE-005에서 돈다."
},
{
"script": "check:scale:nightly",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
"reason": "CI 밖의 scale 단계다(scripts/scale/run-scale-profile.ts). baseline-regression을 포함하는데, 이 검사는 config/scale/benchmark-baseline.json을 기록한 CPU 모델에서만 시간을 비교하고 다른 곳에서는 incomplete로 보고한다(리뷰 11-03). 그 기계에서 돌린다. CPU와 상관없는 pr 단계는 FE-GATE-005에서 돈다."
},
{
"script": "check:scale:release",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
"reason": "CI 밖의 scale 단계다(scripts/scale/run-scale-profile.ts). baseline-regression을 포함하는데, 이 검사는 config/scale/benchmark-baseline.json을 기록한 CPU 모델에서만 시간을 비교하고 다른 곳에서는 incomplete로 보고한다(리뷰 11-03). 그 기계에서 돌린다. CPU와 상관없는 pr 단계는 FE-GATE-005에서 돈다."
},
{
"script": "check:test-evidence",
"reason": "Local all-in-one run. CI splits it: check:test-evidence:browser (--skip-scenario-executions) in FE-GATE-008 after the browser suites, and the scenario part through test:http-scenario-evidence in FE-GATE-007."
"reason": "한 번에 모두 보는 로컬 실행이다. CI는 이것을 나눈다. FE-GATE-008이 브라우저 suite 뒤에 check:test-evidence:browser(--skip-scenario-executions)를 돌리고, scenario 부분은 FE-GATE-007의 test:http-scenario-evidence가 맡는다."
},
{
"script": "check:test-evidence:source",
"reason": "--source-only is a subset of check:test-evidence:browser (FE-GATE-008), for a quick local run without browser results."
"reason": "--source-only는 check:test-evidence:browser(FE-GATE-008)의 일부다. 브라우저 결과 없이 로컬에서 빨리 돌릴 때 쓴다."
},
{
"script": "drill:runbooks",
"reason": "Local shortcut for all five drills. CI runs each drill as its own production gate (FE-GATE-021 to FE-GATE-025) through drill:runbook."
"reason": "다섯 drill을 한 번에 돌리는 로컬 단축 명령이다. CI는 drill마다 drill:runbook으로 따로 production 게이트(FE-GATE-021~FE-GATE-025)를 돌린다."
},
{
"script": "test:all",
"reason": "Local aggregate of suites the gates run one by one (FE-GATE-004 to FE-GATE-007). The removal checks in FE-GATE-020 run it inside their fixtures through scripts/lib/removal-fixture.ts, not through the package script graph."
"reason": "게이트가 하나씩 돌리는 suite(FE-GATE-004~FE-GATE-007)를 묶은 로컬 명령이다. FE-GATE-020의 제거 검사는 package script 그래프가 아니라 scripts/lib/removal-fixture.ts를 거쳐 자기 fixture 안에서 이것을 돌린다."
},
{
"script": "test:e2e:dev",
"reason": "Runs tests/e2e against the Vite dev server (playwright.dev.config.ts) for local debugging. FE-GATE-008 runs the same specs against the production build (test:e2e)."
"reason": "로컬 디버깅용으로 tests/e2e를 Vite 개발 서버(playwright.dev.config.ts)에 돌린다. FE-GATE-008은 같은 spec을 production 빌드에 돌린다(test:e2e)."
},
{
"script": "test:extreme-scale:focused",
"reason": "Part of verify:extreme-scale. All its paths run in FE-GATE-005 except tests/scale/global-local-independence.test.ts, which belongs to the main scale tier (see config/ci/ungated-tests.json)."
"reason": "verify:extreme-scale의 일부다. 경로는 모두 FE-GATE-005에서 돈다. 예외는 main scale 단계에 속하는 tests/scale/global-local-independence.test.ts다(config/ci/ungated-tests.json 참고)."
},
{
"script": "test:visual:update",
"reason": "Rewrites the visual snapshots; it is an update command, not a check. FE-GATE-008 runs test:visual."
"reason": "visual snapshot을 다시 쓰는 갱신 명령이지 검사가 아니다. FE-GATE-008은 test:visual을 돌린다."
},
{
"script": "verify:extreme-scale",
"reason": "Local aggregate of 24 scripts (scripts/verify-extreme-scale.ts). Its CPU-independent parts run in gates; the main, nightly and release scale tiers need the baseline CPU (see check:scale:main)."
"reason": "package script 여러 개를 차례로 돌리는 로컬 묶음이다. 목록은 scripts/verify-extreme-scale.ts의 EXTREME_SCALE_GATES다. CPU와 상관없는 부분은 게이트에서 돌고, main·nightly·release scale 단계는 기준 CPU가 필요하다(check:scale:main 참고)."
},
{
"script": "verify:promotion",
"reason": "Re-verifies a promotion bundle archived by an earlier run (13-04, --archived) with provider trust keys and EXPECTED_PROMOTION_* inputs of that run. In CI the promotion job verifies the same bundle through scripts/stage-verified-promotion.ts before it uploads it."
"reason": "앞선 run이 보관한 promotion bundle(13-04, --archived)을 그 run의 provider 신뢰 key와 EXPECTED_PROMOTION_* 입력으로 다시 검증한다. CI에서는 promotion job이 같은 bundle을 올리기 전에 scripts/stage-verified-promotion.ts로 검증한다."
}
]
}
+8 -1
View File
@@ -1,7 +1,7 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 상태: 채택(보완)
- 작성일: 2026-07-26
- 요약: lockfile 전체에서 의존성 목록·라이선스·SBOM·출처 증명을 만들고, 외부 취약점 보고와 서명된 증거가 없으면 승격(promotion)을 실패로 둔다는 결정이다.
- 현재 정본: `docs/security/supply-chain.md`
@@ -120,3 +120,10 @@ attestation transparency/retention과 비밀 관리를 결정해야 한다.
`FAIL_UNVERIFIED`로 돌아간다. local inventory, lock integrity, license, SBOM,
secret, reproducibility와 actual diff gate는 유지한다. scanner 장애를 이유로
promotion을 PASS로 변경하지 않는다.
## 보완
> 머리 블록은 2026-11-08에, 이 절은 2026-11-12에 더했다. 아래 고침은 기록 규칙(2026-11-08)이 생기기 전에 본문을 제자리에서 고친 것이다. 그래서 위 본문은 결정한 때의 원문이 아니라 마지막 고침 뒤의 내용이다. 처음 커밋한 본문은 `git show 8b4f875c:docs/architecture/decisions/VD-09-supply-chain-evidence.md`로 본다.
- 2026-07-30 (`6c52cdb9`): 「실행 경계와 증적」 절의 generator·coherence·secret scan·reproducibility 스크립트 경로를 `.mjs`에서 `.ts`로 바꿨다.
- 2026-08-02 (`92e5cace`): 결정 6~11번, 「실행 경계와 증적」 도식, 「검증」 절, 「Rollback」 절을 고쳤다. 외부 provider 입력을 `immutable_build` archive 하나와 provider job 둘, Ed25519 서명 검증으로 바꿨고, 결정 항목이 10개에서 11개가 됐다.
@@ -1,7 +1,7 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 상태: 채택(보완)
- 작성일: 2026-07-27
- 요약: File·Blob·파일 선택기·IndexedDB·OPFS·Cache Storage를 기존 `StoragePort`와 섞지 않는 별도 경계로 두고, reference runtime은 제품에 조립하지 않은 채 둔다는 결정이다.
- 현재 정본: `src/adapters/browser-files/`, `src/adapters/storage/`, `config/recipes/frontend-capability-recipes.json`
@@ -277,3 +277,9 @@ test, build와 optional catalog가 유지되는지 검증한다.
schema downgrade, blanket `deleteDatabase()`, `caches.keys()` 전체 삭제와 사용자
filename 기반 OPFS 삭제는 rollback 수단으로 금지한다.
## 보완
> 머리 블록은 2026-11-08에, 이 절은 2026-11-12에 더했다. 아래 고침은 기록 규칙(2026-11-08)이 생기기 전에 본문을 제자리에서 고친 것이다. 그래서 위 본문은 결정한 때의 원문이 아니라 마지막 고침 뒤의 내용이다. 처음 커밋한 본문은 `git show 6c52cdb9:docs/architecture/decisions/VD-11-browser-file-and-origin-storage.md`로 본다.
- 2026-09-18 (`ec7f20e2`): 「계약과 증적」 절 끝의 문단 하나를 두 문단으로 바꿨다. engine마다 14개, 모두 42개라는 browser source suite case 수와 WebKit native library 부재 서술을 지우고, `verify:browser-capability-evidence`가 Chromium artifact에서 기준 testcase 묶음을 잡고 Firefox·WebKit이 같은 묶음을 실패 없이 돌렸는지 검사한다는 규칙과, engine별 capability 차이를 skip 이유로 쓰지 않는다는 규칙을 넣었다.
@@ -1,7 +1,7 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 상태: 채택(보완)
- 작성일: 2026-07-28
- 요약: server state cache, Web Storage, IndexedDB 영속화, 탭 간 무효화를 한 추상으로 합치지 않고 scope와 영속화 경계를 따로 정한다는 결정이다.
- 현재 정본: `src/adapters/query-cache/`, `src/adapters/cross-context-invalidation/`, `src/contracts/storage-keys.ts`
@@ -889,3 +889,9 @@ source, deterministic test, native evidence와 composition inventory로 증명
이 비용은 cache hit, durable restore, cross-tab hint와 server truth를 하나의
“cached” 상태로 잘못 합치지 않기 위한 의도적인 비용이다.
## 보완
> 머리 블록은 2026-11-08에, 이 절은 2026-11-12에 더했다. 아래 고침은 기록 규칙(2026-11-08)이 생기기 전에 본문을 제자리에서 고친 것이다. 그래서 위 본문은 결정한 때의 원문이 아니라 마지막 고침 뒤의 내용이다. 처음 커밋한 본문은 `git show 6c52cdb9:docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md`로 본다.
- 2026-11-06 (`02a761f0`): 2절 상태 표의 registered Web Storage 행과 7절 한도 표 아래 문단에서 `COLOR_SCHEME`·`CHUNK_RELOAD_GUARD` 두 key 이름을 지우고, 행 목록의 정본이 `src/contracts/storage-keys.ts`의 `STORAGE_REGISTRY`라고 가리키게 했다.
@@ -111,14 +111,15 @@ Local Draft 소비자가 아직 `src/features/` 아래 있을 때 잰 값(09-12)
- 내구성, 스케줄링, 관측
이 복잡함은 feature가 아니라 조립·플랫폼 경계에 둔다.
Local Draft 세로 slice는 이제 두 번째 구체 소비자다.
Local Draft 세로 slice는 이 repository port를 feature 모양으로 쓰는 구체 소비자다.
다만 제품 feature가 아니라 테스트 fixture(`tests/fixtures/indexeddb-consumer`)다.
이 소비자는 안정된 연결 지점(seam)이 타입이 있는 repository provider와,
feature가 소유한 repository 식별자라는 것을 확인한다.
dataset 범위, 보존, 마이그레이션, codec, 수명 주기 권한 설정을 만능
`create...Repository<T>` factory 하나로 안전하게 합칠 수 있다는 것은 보여 주지 **않는다**.
그래서 편의 프로필은 IndexedDB를 쓰는 다른 제품 feature가 같은 인프라 정책을 되풀이한 뒤에만 들인다.
두 feature가 같은 repository port를 쓴다는 이유만으로 들이지 않는다.
그래서 편의 프로필은 IndexedDB를 쓰는 제품 feature가 생기고, 그 feature들이 같은 인프라 정책을 되풀이한 뒤에만 들인다.
여러 소비자가 같은 repository port를 쓴다는 이유만으로 들이지 않는다.
## 소비자 품질 검토 체크리스트
+2 -2
View File
@@ -39,7 +39,7 @@ bootstrap, presentation, application 모듈을 import하지 못하게 막는다.
## 감사 결과
2026년 9월 아키텍처 리뷰를 계기로 계약 파일 39개 전체의 import 그래프를 감사했다.
2026년 9월 아키텍처 리뷰를 계기로 그때 `src/contracts`에 있던 계약 파일 전체의 import 그래프를 감사했다. 지금 파일 목록은 `src/contracts/`가 정본이다.
### capability 소유 계약을 옮김
@@ -112,4 +112,4 @@ runtime에 설치됐다는 사실을 message 소유로 보지 않는다.
- 같은 정의가 필요한 빌드·release·runtime wire 기준이 없다.
- 정의를 그 owner로 옮겨도 안쪽 방향 의존성 규칙을 어기지 않는다.
39라는 숫자를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.
계약 파일 수를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.
+1 -1
View File
@@ -44,7 +44,7 @@ rollback은 이전 불변 release의 HTML·asset·config·API·manifest 묶음
미리 불러온다(preload). 몇 개까지 허용할지는 `config/performance/budgets.json`의
`initialJsFiles`가 정한다. 지금 개수는
`config/scale/feature-shape-ceilings.json`의 `initialJavascript.files`이고, 이
값은 예시 feature를 기준으로 한다. HTTP/1.1에서는 host마다 연결이 여섯 개라
값은 feature가 없는 지금 템플릿 빌드에서 잰 것이다. HTTP/1.1에서는 host마다 연결이 여섯 개라
파일이 줄을 선다. 그래서 Fast 3G에서 첫 화면이 초기 chunk를 묶었을 때보다 약
1초 늦게 떴다(2026-11-03). HTTP/2에서는 차이가 100 ms 미만이었다. 그래서
템플릿은 chunk를 나눈 채로 둔다. HTTP/1.1로만 서빙할 수 있는 제품은
+5 -5
View File
@@ -333,7 +333,9 @@ release 증거는 다음 release 승격까지, drill 증거는 다음 production
증거는 집계까지 보관한다.
runbook job은 고정 경로 `artifacts/runbooks/<runbook-id>/record.json`에 쓴다. 바뀌는
release identity는 record 안에 저장한다.
release identity는 record 안에 저장한다. 그래서 게이트 증거를 찾는 일이 `RELEASE_ID`의
slash나 그 밖의 provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자
자기 run 범위에 남는다.
runbook drill(`drill:runbook`, FE-GATE-021..025)은 판정마다 `PASS`, `FAIL`,
`UNVERIFIED` 중 하나로 기록한다(`scripts/drill-runbook.ts`, record schema는
@@ -411,9 +413,7 @@ drill은 `FAIL`(exit 1)이다. 그렇지 않고 `UNVERIFIED`가 하나라도 있
production 단계는 닫히지 않는다. 의도한 결과다. 로컬 drill은 승격한 release를 rollback할
수 있다는 것을 보여 줄 수 없다. FE-GATE-016(`rollback-drill`)은 FE-GATE-025와 같은
FE-RB-005 drill을 돌렸으므로 폐기했다(`scripts/contracts/ci-gates.ts`의
`RETIRED_GATE_IDS`). 이렇게 하면 게이트 증거를 찾는 일이 `RELEASE_ID`의 slash나 그 밖의
provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자 자기 run 범위에
남는다.
`RETIRED_GATE_IDS`).
브라우저를 쓰는 merge 게이트는 버전을 고정한 Chromium, Firefox, WebKit 엔진을 설치해
실행한다. 그래서 route 동작, reflow, 기본 dialog 동작, theme 유지, 자동 접근성 검사는
@@ -522,7 +522,7 @@ nanoid, source-map-js)은 선언한 범위 안에서 업데이트해서 없어
| Advisory | 패키지 | 고친 버전 | 아직 업데이트하지 않은 이유 |
|---|---|---|---|
| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 4.6.7은 초기 JavaScript를 gzip으로 약 7 KB 늘려 번들 예산을 넘는다. 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) |
| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 고친 버전 이상으로 올리면 초기 JavaScript가 gzip으로 약 7 KB 늘어 번들 예산을 넘는다(2026-11-04에 4.6.7로 잰 값). 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) |
| GHSA-qwww-vcr4-c8h2 (high) | `react-router`, `react-router-dom`을 거쳐 들어옴(production. 지금 버전은 `pnpm-lock.yaml`) | 7.18.2 | 같은 evidence 규칙을 따른다. 이 advisory는 RSC 모드에 관한 것이다. browser router를 쓰는 이 SPA는 RSC 모드를 쓰지 않는다(리뷰 추정, 확인하지 않음). 7.18.5는 초기 JavaScript를 약 470 B 늘린다 |
두 provider role은 서로 다른 key ID뿐 아니라 canonical DER-SPKI public-key bytes도
+1 -1
View File
@@ -1,4 +1,4 @@
# FE-RB-001 — 부트 설정 실패
# FE-RB-001 — boot 설정 실패
`BOOT_CONFIG_FAILURE`가 나고, 한 번만 허용된 재요청(refetch)도 실패하면 이
runbook을 시작한다. 제품 route를 mount하지 않고 안전한 지원 화면(support
+1 -1
View File
@@ -1,4 +1,4 @@
# FE-RB-002 — chunk 또는 배포 불일치
# FE-RB-002 — chunk·manifest·배포 불일치
`CHUNK_LOAD_FAILURE`, `RELEASE_MANIFEST_FAILURE`, `DEPLOY_MISMATCH` 중 하나가
나면 시작한다. 저장하지 않은 상태(dirty state)를 잃을 수 있으면 경고한다.
+1 -1
View File
@@ -1,4 +1,4 @@
# FE-RB-003 — 백엔드 API 품질 저하
# FE-RB-003 — 백엔드 API 저하
다음 중 하나면 시작한다. 더 재시도하지 않는(terminal) 네트워크·시간 초과·5xx
실패가 최근 5분 이동 구간(rolling)의 기준치를 넘는다. 또는 `SCHEMA_MISMATCH`가
+24 -20
View File
@@ -32,6 +32,10 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
// it on the local build. What needs a browser boot, live traffic or the hosting
// provider is UNVERIFIED, and so is every drill whose runbook needs provider
// verification: a local drill never claims the release can be recovered.
//
// Each recovery assertion is named after one of the runbook's recoveryEvidence
// items in config/runbooks/runbooks.json, word for word and in its order
// (tests/unit/runbook-drill.test.ts), so the record names what the runbook lists.
type RecoveryAssertion = Readonly<{
assertion: string;
@@ -181,14 +185,14 @@ async function drillBoot(): Promise<DrillResult> {
triggerAsserted: verdict(!invalid.success),
containmentAsserted: verdict(!invalid.success),
recoveryAssertions: [
notObserved("clean-session boot", "a browser boot of the promoted release"),
notObserved("product root mount", "a browser boot of the promoted release"),
notObserved("깨끗한 세션에서 boot", "a browser boot of the promoted release"),
notObserved("제품 root mount", "a browser boot of the promoted release"),
assertion(
"config validation",
"config 검증",
"invalid fixture rejected, valid fixture accepted",
verdict(!invalid.success && recovered.success),
),
notObserved("no repeated boot error", "boot telemetry from the promoted release"),
notObserved("boot 오류 반복 없음", "boot telemetry from the promoted release"),
],
// The runbook's negative fixture injects a mount failure after a valid
// config; that needs a mounted app, which a Node drill does not have.
@@ -233,13 +237,13 @@ async function drillChunkMismatch(context: DrillContext): Promise<DrillResult> {
),
recoveryAssertions: [
assertion(
"entry and lazy assets reachable",
"entry asset과 lazy asset에 접근 가능",
"every Vite manifest file exists in the local dist",
verdict(await builtAssetsPresent(context.root)),
),
assertion("release tuple coherent", "build/config/manifest tuple", verdict(coherence.compatible)),
assertion("second reload blocked", "reload guard decision", verdict(second.action === "support")),
notObserved("critical route smoke", "a browser smoke against the hosted release"),
assertion("release tuple 일치", "build/config/manifest tuple", verdict(coherence.compatible)),
assertion("두 번째 reload 차단", "reload guard decision", verdict(second.action === "support")),
notObserved("핵심 route smoke 시험", "a browser smoke against the hosted release"),
],
negativeFixtureFailedAsExpected: verdict(second.action !== "reload-once"),
providerVerificationRequired: true,
@@ -338,11 +342,11 @@ async function drillApiDegradation(): Promise<DrillResult> {
triggerAsserted: "UNVERIFIED",
containmentAsserted: verdict(!unkeyedRetry && safeRetry),
recoveryAssertions: [
notObserved("terminal failure rate at baseline", "API failure telemetry from the promoted release"),
assertion("no retry amplification", "unkeyed retry policy", verdict(!unkeyedRetry)),
notObserved("critical read/write smoke", "a read and a write against the live API"),
notObserved("최종(terminal) 실패율이 기준선 수준", "API failure telemetry from the promoted release"),
assertion("재시도 증폭 없음", "unkeyed retry policy", verdict(!unkeyedRetry)),
notObserved("핵심 읽기/쓰기 smoke 시험", "a read and a write against the live API"),
assertion(
"schema fixtures",
"스키마 fixture",
"schema mismatch is not retryable",
verdict(!schemaRetry),
),
@@ -384,10 +388,10 @@ async function drillTelemetry(): Promise<DrillResult> {
triggerAsserted: verdict(adapter.droppedCount() === 1),
containmentAsserted: verdict(adapter.pendingCount() === 0),
recoveryAssertions: [
assertion("product flow unaffected", "adapter flush resolves despite the sink failure", verdict(flushResolved)),
assertion("delivery self-check", "sink failure counted", verdict(adapter.droppedCount() === 1)),
assertion("queue drained within bound", "pending queue count", verdict(adapter.pendingCount() === 0)),
assertion("forbidden attributes absent", "default-deny projection", verdict(redacted)),
assertion("제품 흐름 영향 없음", "adapter flush resolves despite the sink failure", verdict(flushResolved)),
assertion("전송 자체 점검", "sink failure counted", verdict(adapter.droppedCount() === 1)),
assertion("queue가 상한 안에서 비워짐", "pending queue count", verdict(adapter.pendingCount() === 0)),
assertion("금지 속성 없음", "default-deny projection", verdict(redacted)),
],
negativeFixtureFailedAsExpected: verdict(redacted),
providerVerificationRequired: true,
@@ -421,14 +425,14 @@ async function drillRollback(context: DrillContext): Promise<DrillResult> {
triggerAsserted: "UNVERIFIED",
containmentAsserted: verdict(coherent.compatible && assetsPresent),
recoveryAssertions: [
assertion("compatibility gate", "typed version comparison", verdict(coherent.compatible)),
assertion("호환성 gate", "typed version comparison", verdict(coherent.compatible)),
assertion(
"release coherence gate",
"release 일관성 gate",
"build/config/manifest tuple and every Vite manifest file in the local dist",
verdict(coherent.compatible && assetsPresent),
),
notObserved("critical smoke", "a browser smoke after the provider switches to the prior release"),
assertion("release ID in timeline", "drill record releaseId", verdict(Boolean(release.releaseId))),
notObserved("핵심 smoke 시험", "a browser smoke after the provider switches to the prior release"),
assertion("장애 타임라인에 release ID 기록", "drill record releaseId", verdict(Boolean(release.releaseId))),
],
negativeFixtureFailedAsExpected: verdict(!mixed.compatible),
providerVerificationRequired: true,
+13
View File
@@ -103,6 +103,19 @@ describe("runbook drill verdicts", () => {
expect(record.recoveryAssertions.some(({ result }) => result === "FAIL")).toBe(false);
});
// A drill's recovery assertions are the runbook's recoveryEvidence items, named
// as config/runbooks/runbooks.json names them and in its order, so the record
// and the UNVERIFIED line name the same checks the runbook lists.
it.each(RUNBOOK_IDS)("%s names its recovery assertions after the runbook's recoveryEvidence", async (runbookId) => {
const document = JSON.parse(await readFile("config/runbooks/runbooks.json", "utf8")) as {
runbooks: Record<string, { recoveryEvidence: string[] }>;
};
const record = await runRunbookDrill(runbookId, { releaseRoot: await builtDist(), contractPackages });
expect(record.recoveryAssertions.map(({ assertion }) => assertion)).toEqual(
document.runbooks[runbookId]?.recoveryEvidence,
);
});
it.each(["FE-RB-002", "FE-RB-005"] as const)(
"%s fails when the build lost its JavaScript assets",
async (runbookId) => {