Commit Graph
23 Commits
Author SHA1 Message Date
DongHyeonka 06ffafa25e 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
2026-11-12 23:36:14 +09:00
DongHyeonka e9e98b8aa7 Merge branch 'main' into claude/fe-b-docs-korean-645f55
정리 3·4단계 PR #14와 CI 재편 PR #16(main 38c0dc7d)을 받는다. 충돌은 아홉
파일이다. 이 브랜치가 한국어로 다시 쓴 문서에 두 PR이 영어 판에서 바꾼
것을 한국어로 넣었다.
- a11y 기록 경로 `artifacts/tests/a11y-manual/` → `docs/accessibility/route-reviews/`:
  README, docs/README.md, manual-checklist, starter-experience,
  ci-quality-gates. 문서 검사의 `NOT_DOCUMENT`도 새 경로로 바꿨다(정해진 영어
  키 형식의 게이트 입력이라 문서로 보지 않는다)
- ci-quality-gates.md: merge 단계 job 셋, 지운 CI 계약 기준선, main 단계
  FE-GATE-029의 `check:ci:gating`
- adapter 재검토 원장: 합친 음성 fixture script
- README 프로젝트 구조: `schemas/`는 `config/schemas/`로, `artifacts/`는
  `.gitkeep`만 추적, 최상위 항목 등록부 `config/repository-layout.json`
- verify-documentation-readiness.ts: #14의 배치 규칙 검사(R6·R7)와 이 브랜치의
  문서 체계 검사를 둘 다 둔다. R7의 「현재 문서」는 #14의 폴더 목록(옛
  `docs/superpowers/` 포함) 대신 문서 검사의 `checkedForDrift`로 고른다
- deletable-history-documents 시험: #14의 등록부 기반 경로와 이 브랜치의
  검사기 예외를 같이 둔다
- CHANGELOG: 범위 문장과 표 행을 둘 다 둔다
- 루트 등록부에서 SPEC.md 항목을 뺀다(그 항목이 「문서 체계 작업이 이력 폴더로
  옮기고 이 항목을 뺀다」고 적었다)
- #14가 옛 `docs/testing/frontend-platform-testing-strategy.md`를 고친 것이
  이름 바뀜을 따라 기록(docs/design/…)에 들어와서, 기록은 옮길 때의 글로 되돌렸다
2026-11-12 04:53:06 +09:00
DongHyeonka af10cae9a6 docs(architecture): 현재 계약 문서와 매뉴얼의 영어 부분을 한국어로 옮긴다
문제: docs/architecture의 현재 계약 문서 가운데 scale-architecture.md,
starter-experience.md, capability-consumer-experience.md,
contract-ownership.md, static-delivery.md, review-evidence.md는 본문이
영어이고, backend-api-and-server-state-contract.md와
optional-adapter-recipes.md에는 영어 문단이 남아 있다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. 백틱 안, 링크 대상, 절 번호(코드
주석이 `scale-architecture.md §N`으로 인용한다), 표 구조, 코드 블록은
그대로 둔다. 문서를 읽는 테스트와 절 이름을 인용한 곳을 같은 변경에서
고친다.
- tests/unit/feature-tracked-files.test.ts: starter-experience.md 표를
  자르는 시작·끝 문장과 표 행마다 찾는 낱말(`병합 충돌`)
- 「Ownership declarations」「Adding a feature」를 인용한 주석
  (create-feature.ts, generate-product-feature-index.ts, app-module.ts)과
  docs/manual의 절 이름 인용
- optional-adapter-recipes.md의 recipe 개수 복사를 카탈로그를 가리키게
  바꾼다(number 검사)

위험: create-feature.ts 417줄은 생성하는 context-module.ts의 JSDoc이라
새로 만드는 기능의 주석 글자가 바뀐다. 그 글자를 비교하는 테스트는 없다.
review-evidence.md는 산문만 옮겼고 해시·점수 칸은 그대로다.

검증: 백틱 span·링크 대상·코드 블록·번호 제목을 옮기기 전과 python으로
비교해 같다. 문서 검사의 language 줄이 이 문서들에서 0이 되어 예외
목록에서 지웠다.
2026-11-08 21:57:47 +09:00
donghyeon.kang 79dc945a67 refactor(layout): 루트 경로 목록을 등록부 하나에서 고르고 schemas/를 옮긴다
루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
  들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
  `scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
  집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
  같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
  공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
  추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
  문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
  스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
  `config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
  `.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
  복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
  `tests/fixtures/hosting/response-headers.json`.

버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.

위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).

검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
2026-11-08 17:41:07 +09:00
donghyeon.kang bf485f449a refactor(typecheck): 음성 타입 fixture 23개를 실행기 하나로 돈다
음성 타입 fixture마다 옵션이 같은 tsconfig 하나, package script 하나,
게이트 명령 하나가 있었다(23벌). 옵션은 모두 같고 파일 하나만 달라서
fixture를 더할 때마다 세 곳을 같이 고쳤다. `tsconfig.recipes.json`도
`tsconfig.test.json`과 lib가 같고 types만 하나 적었다.
`tsconfig.web-worker.json`은 `files: []`로 0파일을 검사하고 통과했다
(2026-09-25 리뷰가 기록, FE-GATE-003이 통과로 보였다).

고른 방법(design-docs repo-structure/04-frontend-layout.md 5.3절 (가),
소유자 승인 2026-11-07):
- fixture 첫 줄에 기대(`// expect: TS2322`, `// expect: pass`)를 쓰고
  `scripts/check-type-fixtures.ts`가 fixture마다 `.tmp/type-fixtures/`에
  한 파일 tsconfig를 써서 tsc를 돈다. 판정은 run-ci-gate.ts가 명령마다
  하던 것과 같다(exit 1과 `error TS<code>:`). 결과를 fixture별로 출력한다.
  기대 줄이 없는 fixture와 fixture 0개는 실패한다.
- recipes는 `tsconfig.test.json` include로 옮긴다.
- web-worker tsconfig와 script는 지운다(결정 D4). Worker를 들일 때 더하는
  단계는 매뉴얼 03에 쓴다(뒤 커밋).
- `scripts/check-typecheck-inputs.ts`를 `check:types` 끝에 둔다. package
  script가 tsc에 넘기는 tsconfig마다 이 repo 파일이 1개 이상인지 본다.
  `files: []` tsconfig가 통과로 보이던 구멍을 막는다(R8).

버린 것: TypeScript API로 한 프로세스에서 돌리는 방법. 이 repo의
TypeScript 7.0(네이티브판)은 JS API를 싣지 않는다. 위반마다
`@ts-expect-error`를 쓰는 방법(5.3절 (나))은 오류 코드 고정을 잃는다.

위험: recipe가 이제 `vite/client` 타입이 있는 프로그램에서 검사된다.
recipe가 `import.meta.env`를 쓰면 전에는 실패했고 이제는 통과한다
(복사한 제품도 Vite라 가치가 작다, 설계 5.1절). CI 계약 기준선을 다시
받았다(명령 99 → 76).

검증(desktop): `check:types:fixtures` 23개 PASS, 각 fixture의 기대 코드가
출력에 그대로 나온다. `TelemetryPort.emit` 인자를 `string`으로 넓히는
변이(2026-09-25 리뷰 07-05)에서 `invalid-diagnostics-port.ts`가 TS2578로
FAIL, 실행기 rc=1. 되돌린 뒤 작업 트리 0줄. `check:types` rc=0
(Typecheck inputs: app 379, node 312, service-worker 22, test 915).

Refs: design-docs repo-structure/04-frontend-layout.md 5.3·9.2·9.3절, README.md 3.4절 D4
2026-11-08 17:40:12 +09:00
DongHyeonka e632b230e3 docs: 옮긴 문서를 가리키는 링크와 경로를 새 위치로 고친다
문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는
상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을
가리킨다.

고른 방법: 기계적으로 바꾼다.
- 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고,
  대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다.
  옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은
  링크 대상뿐이다(백엔드 1단계와 같은 예외).
- 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`,
  `docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과
  CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와
  review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토
  작업 공간의 출처 표시라 그대로 둔다.

위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는
없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다.

검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록,
CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시
쓴다) 밖에서 0건.
2026-11-08 17:25:41 +09:00
DongHyeonka fdc1db9471 feat(bootstrap): 제품이 SW blockers·observe를 composeProduct로 넘긴다
문제: SW를 켜는 선택은 제품 소유 `product-capabilities.ts`로 옮겼다
(1103/09-05 일부). 그런데 저장하지 않은 편집이 있는 탭의 활성화 거절
(`blockers`)과 page controller 관측(`observe`)은 템플릿 소유
`src/bootstrap/create-runtime-composition.ts`를 고쳐야 이어진다(매뉴얼 03
"SW 켜기", 레시피 "Service Worker를 켤 때 확인할 것" 2·3). 그 파일을 고친
제품은 템플릿 동기화마다 충돌한다.

고른 방법: 기존 제품 확장 지점에 선택 칸 하나를 더한다.
`ProductComposition.serviceWorker?: { blockers?, observe? }`
(`product-composition-contract.ts`). `createRuntimeAdapters`가 `composeProduct`
결과의 이 칸을 bundle에 `productServiceWorker`로 싣고, 템플릿 조립
(`create-runtime-composition.ts`)이 telemetry와 같은 방식으로 받아
`createOptionalRuntimeHost`에 넘긴다. blockers 목록은 한 번 복사한다. 던지는
blocker는 page controller가 이미 막는 쪽으로 본다. page controller는
`observe`의 throw를 잡지 않으므로, 제품 sink가 던져도 worker 흐름이 바뀌지
않게 조립에서 감쌌다. 매뉴얼 03과 레시피 2·3을 새 자리로 고쳤다.
버린 대안:
- `product-composition.ts`에 새 export(`composeProductServiceWorker`)를 요구.
  이미 그 파일을 가진 다운스트림이 동기화하면 import가 깨진다. 선택 칸은
  기존 `composeProduct`를 그대로 둔다.
- `composeProduct`를 조립에서 한 번 더 부르기. capability와 credential이 두
  벌 생긴다.

위험·한계: 일부만 닫는다. 남은 것:
- 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을
  제품 소유 자리가 없다(레시피 4·5, 0925/06-05).
- realtime·Web Worker·오프라인 명령은 여전히 조립이 거절한다
  (`optional-runtime-host.ts`, 그 런타임이 템플릿에 없다).
`product-composition.ts`(제품 소유, 출하 상태 빈 값)는 고치지 않았다. 칸이
선택이라 기존 제품 파일과 1105/09-01의 타입 검사 탐침 내용이 그대로
통과한다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts tests/component/runtime-composition-service-worker-telemetry.test.ts
- RED: "passes the product's blockers and observer to the page controller"가
  옛 조립에서 observe 기록이 비어 실패한다.
- 함께: check:types, lint, check:architecture, verify:documentation

Refs: 1103/09-05
2026-11-05 22:19:06 +09:00
DongHyeonka 1c7c614b47 fix(service-worker): 사전 캐시를 Vite assets 폴더의 해시 파일로 제한한다
문제: 사전 캐시 수집기(`collectStaticAssets`)는 dist 전체를 돌고 파일
이름만 해시 정규식으로 본다. `public/` 파일은 이름 그대로 dist 루트에
복사되는데, `apple-touch-icon.png`, `android-chrome-192x192.png`,
`safari-pinned-tab.svg`는 정규식에 걸려 immutable 자산으로 들어간다(리뷰
06-R1). 제품이 같은 이름으로 아이콘을 바꾸고 CDN이 옛 바이트를 주면 새
릴리스 install이 INTEGRITY_MISMATCH로 통째로 거절된다. 이전 릴리스
fallback, 호스팅 정책 `/assets/*`, MIME probe, 레시피 문서는 모두
`assets/`만 가정한다.

고른 방법: 리뷰 06-01의 (a). 계약 모듈에 `BUILD_ASSET_DIRECTORY =
"assets/"` 하나를 두고, 수집기는 그 아래 파일만 받는다. 워커 fallback
(`service-worker-static-assets.ts`)과 probe(`hosting-probe.ts`)도 같은
상수를 읽는다. `build.assetsDir`를 바꿀 때(0925/06-08) 이 상수 한 곳만
고치면 된다. 수집기의 `.vite/` 제외는 새 조건이 덮으므로 지웠다. 레시피
문서에 루트 파일이 빠진다는 문장을 더했다.
버린 대안:
- 정규식을 Vite 해시 형식(8자 고정)으로 좁히기. 우연히 맞는 이름이 남는다.
- 문서만 고치기. 아이콘 문제가 그대로다.

위험·한계: 루트에 해시 이름 파일을 일부러 두는 제품은 그 파일이 사전
캐시에서 빠진다. Vite는 그런 파일을 만들지 않는다. 상수는 vite 설정에서
읽지 않는다. `build.assetsDir`를 바꾸는 제품은 상수도 같이 바꿔야 한다
(0925/06-08은 그대로 남는다).

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/service-worker-web-push-remediation.test.ts tests/unit/service-worker-runtime.test.ts tests/unit/hosting-probe.test.ts tests/unit/service-worker-build-output.test.ts
- RED: "precaches only the assets directory, not public files at the dist
  root"가 옛 수집기에서 루트 아이콘 세 개를 받아 실패한다.

Refs: 1105/06-01
2026-11-05 22:08:50 +09:00
DongHyeonka c17b3a05d6 chore(review): 1103 세션 owner 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-03 09-11

# Conflicts:
#	docs/manual/02-decision-tables.md
2026-11-04 21:40:51 +09:00
DongHyeonka b029dcc00a chore(review): 1103 앱 코어·폼 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-01 09-02 09-05 09-07~09-10 08-02~08-04
2026-11-04 21:17:43 +09:00
DongHyeonka f3fd10f17c docs(manual): 짝 백엔드에 처음 붙이기 절을 더한다
문제: 제품이 짝 백엔드에 처음 붙을 때 볼 문서가 없다. owner 작성자는
SessionGateway 주석, subject·scope fence 규칙, R-3.2, recover 규약을
여러 파일에서 모아야 하고, 백엔드가 무엇을 주고 무엇을 안 주는지(realm의
브라우저 client, 로그인·로그아웃·세션 엔드포인트)는 백엔드 코드를 읽어야
안다.

고른 방법: docs/manual/04-paired-backend-session.md를 새로 둔다.
- 두 모드 비교표와 근거 위치(백엔드 bbe944bd의 SecurityConfig,
  security.yml, application-local.yml, realm JSON).
- 공통 준비: AUTH_MODE external, 백엔드 local CORS 출처
  http://localhost:3000에 맞춘 dev 포트, owner context 필드, recipe는
  복사(import 금지).
- jwt: 흐름도, realm에 더할 public client JSON(audience mapper 포함),
  제품 설정 키 OIDC_ISSUER·OIDC_CLIENT_ID, product-composition 예시,
  하지 않는 것(새로고침 로그아웃, ID token 서명, id_token_hint).
- redis-session: 흐름도, 제품이 더할 엔드포인트 셋과 CSRF 토큰 읽기,
  프로필을 product-contracts.ts에 옮겨 적는 이유, 예시, 같은 host 조건.
- 상태 전이 표, 확인 방법(실제 백엔드 e2e는 아직 없음), 증상별 원인.
매뉴얼 README·02 §5, starter-experience·foundation·optional-adapter-
recipes에는 위치만 가리키는 줄을 더했다. 백엔드 표는 복사하지 않고 위치만
적었다(매뉴얼 README 규칙).

위험·한계: 백엔드 설정이 바뀌면 이 문서가 낡는다. 기준 커밋을 문서
첫머리에 적었다. Keycloak client JSON은 실제 Keycloak에 넣어 보지 않았다.

검증: verify:documentation PASS_SCOPED(새 문서와 고친 문서 모두 경로·
명령·게이트 ID 누락 0).

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
2026-11-04 20:51:51 +09:00
DongHyeonka c3aa5eba35 docs(recipes): Service Worker 레시피가 오프라인 셸을 약속하지 않게 한다
문제
catalog의 service-worker-pwa trigger는 "a measured offline-shell
requirement"를 설치 조건으로 적고 failureKinds에 offline-fallback이
있다. 레시피 표도 "install/offline shell"이다. 그러나 reference 워커는
navigation을 NETWORK_ONLY로 두고, 사전 캐시에 index.html을 넣지 않으며,
설계는 cached index.html fallback을 금지한다(closed deep design 18.8).
catalog를 보고 온 제품은 템플릿 파일을 고쳐야 한다는 것을 뒤늦게
알고, 이후 동기화마다 같은 파일에서 충돌한다(0929 리뷰의 memento 사례).

고른 방법
- 0929/06-03 최소 방향대로 주장을 설계에 맞춘다. trigger에서 오프라인
  셸을 빼고 "navigation network-only, offline shell 없음, 별도 제품
  capability"를 적는다. failureKinds의 offline-fallback을
  offline-navigation-network-error로 바꾼다.
- 레시피 3절 표를 고치고, 같은 절에 졸업 경로(넘겨받는 파일 넷, 다시
  증명할 e2e 단언과 성질, 동기화 충돌)를 적는다.
- 버린 대안: 선택 handler로 오프라인 셸 확장 지점을 만들기. 설계가
  금지한 동작이고 재검토 조건(제품 요구)이 아직 없다.

위험·한계
- catalog 문구만 바뀐다. 오프라인 셸을 켜는 확장 지점은 여전히 없다.

검증
- json-schema 테스트 6건 통과, check:remediation-ledger·
  check:optional-recipe-fixtures PASS, verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-03
2026-11-04 20:35:38 +09:00
DongHyeonka 2963c6f42c fix(features): 선택 런타임(SW 등) 선택을 제품 소유 파일로 옮긴다 (1103/09-05)
문제
Service Worker를 켜는 유일한 방법은 src/features/installed-runtime-capabilities.ts의
SERVICE_WORKER 상수를 바꾸는 것이었다. 그 파일에는 "Product-owned." 표시가
없고, 매뉴얼 03 D절은 src/features/installed-*.ts를 고치지 말라고 한다.
매뉴얼대로 하면 SW를 켤 수 없고, 켜면 동기화마다 템플릿 파일을 손으로
병합한다. 템플릿 상태 설명과 제품 선택 상수가 한 블록에 섞여 있었다(1101/09-05).

고른 방법
리뷰의 최소 방향을 따른다.
- 선택 상수 넷(REALTIME, WEB_WORKERS, SERVICE_WORKER, OFFLINE_COMMANDS)을 제품
  소유 src/features/product-capabilities.ts의
  PRODUCT_RUNTIME_CAPABILITY_SELECTION으로 옮긴다. 09-02에서 만든 같은 새 제품
  소유 파일이다. product-contracts.ts에 넣지 않은 이유: 계약 층(src/contracts)이
  아니라 기능 카탈로그 옆의 선택이고, 템플릿은 복사 뒤 기존 제품 소유 파일에
  칸을 더하지 않는다.
- installed-runtime-capabilities.ts는 템플릿 소유로 남고 그 선택을 검사
  (validateRealtimeContributions, validateWebWorkerContributions)하고 투영만
  한다. §3.5 설명과 템플릿 상태 설명은 여기에 남는다.
- 매뉴얼 03 C절에 "SW 켜기"를 넣었다. 조립 거절 메시지, e2e SW 빌드 도우미의
  편집 대상(premise 1), 레시피·운영 문서, dependency-cruiser 주석의 경로를
  새 파일로 바꿨다.
- 09-02 typecheck 테스트는 이제 출하된 product-capabilities.ts에 타입만 채우고
  (선택은 유지), 복사 목록은 REMOVAL_FIXTURE_COPY_TARGETS 하나를 쓴다.

위험·한계
- 리뷰가 함께 제안한 composeProduct의 SW 연결 칸(blockers, observe)은 만들지
  않았다. 그 연결은 여전히 템플릿 파일 create-runtime-composition.ts를 고쳐야
  한다. 매뉴얼 "SW 켜기"에 적었다.
- 템플릿 안의 선택을 이미 바꾼 다운스트림은 값을 새 파일로 옮겨야 한다.

검증
- RED: tests/unit/product-runtime-capability-selection.test.ts 3건(선택이 제품
  소유 파일에만 있음, 제품 SW 선택 투영, 잘못된 선택은 여전히 검사)이 수정 전
  실패.
- 그 테스트, service-worker-build-output, optional-runtime-host,
  runtime-composition-service-worker-telemetry, product-features,
  product-extension-typecheck, runtime-adapters 통과.
- check:types, check:architecture, eslint, verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-05
2026-11-04 20:35:11 +09:00
DongHyeonka 5b2106df25 docs(realtime): realtime 레지스트리 세 바인딩의 출처를 레시피에 적는다
문제
realtime 레지스트리는 schemaCodecs·mappers·apiOperations 세 바인딩을
받아 event type과 checkpoint를 대조한다. V2 삭제(12f3bb7)로 기능의
runtimeSchemas·mappers 칸이 사라져 지금 출처가 있는 것은
apiOperations뿐이다. 레시피는 "제품 feature는 이 runtime에
schema/codec/query … 주입"이라고만 적어 조합자가 codec·mapper를 어디서
만드는지 알 수 없다.

고른 방법
- 리뷰의 최소 방향대로 레시피 Realtime 절에 세 바인딩의 출처를 적는다.
  apiOperations는 loadInstalledFeatureRuntimeRegistries().apiOperations,
  schemaCodecs는 V3 events[].payloadValidator·checkpoint outputValidator를
  runtimeSchemaCodecFromValidator + composeRuntimeSchemaCodecs로,
  mappers는 조합 코드의 BoundaryMapper + composeBoundaryMapperRegistry다.
  등록 때 맞아야 하는 id(payloadSchemaId = validator schemaId =
  mapper inputSchemaId)도 적었다(realtime-streams.ts 등록 검사).
- 버린 대안: 지금 기능 모듈에 realtimeMappers 칸을 더하거나 V3 events에서
  event type을 뽑기. 공개 계약이 바뀌고, 04-02의 push 경로(STOMP hint면
  delta mapper가 필요 없을 수 있음)를 고른 뒤 정하는 것이 맞다.

위험·한계
- 코드 변경이 없다. 같은 이벤트를 V3 events와 realtime 등록 두 곳에
  적는 중복은 문서 규칙으로만 막는다.

검증
- verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-06
2026-11-04 20:30:22 +09:00
DongHyeonka 615da352b9 docs(realtime): 짝 백엔드 실시간 출구와 프론트 transport 대응표를 적는다
문제
짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개,
Map<String,String> 투영, 재전송 없음)과 raw WebSocket 라이브러리 API,
NDJSON·JSON text sequence writer다. 프론트 SSE 어댑터는
text/event-stream과 REALTIME_EVENT_V1 envelope을, WebSocket 어댑터는
subprotocol "realtime.v1"을 요구한다. 어느 repo에도 이 불일치와 지금
되는 경로가 적혀 있지 않아, 채택자가 두 repo를 다 읽어야 안다.

고른 방법
- 리뷰의 최소 방향을 프론트 repo 안에서 따른다. 설계 문서에 0.1절을
  두고 transport별 대응표(지금 연결되나·이유), push가 필요할 때의 세
  길, 재검토 조건을 적는다. 레시피 Realtime 절과 매뉴얼 03 C절에서 한
  줄로 링크한다.
- 다시 확인한 백엔드 사실(읽기만): 아키텍처 테스트가 MVC SseEmitter를
  금지한다(ForbiddenApiArchitectureTest NO_SSE_EMITTER, 결정 D3).
  StreamMediaType.SSE는 OpenAPI 생성기만 쓴다. subprotocol 협상 코드는
  없다. 그래서 첫째 길을 SSE가 아니라 realtime.v1 WebSocket handler로
  적었다.
- 지금 되는 경로(bounded polling)는 사실로 적고, push 경로는 고르지
  않았다. 제품 결정이다.
- 버린 대안: desktop-server-git/design-docs/에 쓰기. 이 브랜치 밖이라
  함께 합쳐지지 않는다. 필요하면 그쪽에서 이 절을 링크한다.

위험·한계
- 백엔드 사실은 지금 백엔드 HEAD(70fb80bf)를 읽은 것이다. 백엔드가
  바뀌면 표가 낡는다. 재검토 조건에 적었다.
- 실제 연결은 실행하지 않았다(리뷰와 같음).

검증
- verify:documentation PASS_SCOPED. documentation-readiness·
  changelog-review-ids 테스트 15건 통과.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-02
2026-11-04 20:29:32 +09:00
DongHyeonka 313f9bac3e chore(recipes): 레시피 예산을 측정값 + 3%로 정하고 규칙을 적는다 (0929/05-04)
문제: 레시피 번들 예산을 수정마다 100 B씩 올려 왔다. 한도가 늘 직전
측정값이라 예산 초과가 "왜 커졌나"를 묻는 신호가 되지 못했다. 이번 수정
묶음 뒤 offline-indexeddb(37,327 > 36,900)와 realtime(40,902 > 40,900)이
넘었고, file-transfer는 여유가 47 B였다. remediation ledger는 예전 값
56,100을 적지 않아 check:remediation-ledger가 실패하고 있었다.

방법: 리뷰 결정(README 14절 0929/05-04)대로, 측정값 + 3%를 100 B 단위로
올린 값으로 한 번 정한다. 그 뒤 3% 안의 증가는 예산을 고치지 않고, 넘는
증가는 커밋 본문에 이유를 쓰고 같은 규칙으로 다시 정한다.
- file-transfer 56,053 → 57,800, offline-indexeddb 37,327 → 38,500,
  realtime 40,902 → 42,200, service-worker-pwa 9,716 → 10,100
- 규칙·이유·측정 표는 optional-adapter-recipes.md의 예산 절에 둔다.
  JSON은 주석을 받지 않아서다.
- realtime 문서 두 곳은 숫자 대신 정본 위치를 가리킨다. VD-10은 결정
  기록이라 그대로 둔다.
버린 대안: 수정마다 100 B 인상(지금 방식), 레시피 예산에서 kernel 제외
(kernel 증가를 놓친다).

위험: 3% 여유 안에서는 회귀가 조용히 쌓인다. 예산 값을 표와 JSON 두
곳에 적으므로, 다음 인상 때 표도 같이 고쳐야 한다(ledger는
check:remediation-ledger가 file-transfer 값을 대조한다).

검증: check:optional-recipes:source PASS(4 budgets), verify:documentation
PASS_SCOPED, check:remediation-ledger의 예산 실패 사라짐(TR-02~04 기존
3건은 그대로, 게이트 밖).
2026-11-03 07:00:41 +09:00
DongHyeonka e1a458081d refactor(recipes)!: runtime이 있는 port는 src port를 다시 내보낸다 (0929/05-03)
문제: `recipes/frontend-capabilities/`가 `src/application/ports/`와
같은 이름의 타입 34개를 따로 정의한다(`DurableObjectStorePort`,
`FilePickerPort`, `StorageDurabilityPort`, `TransferProgress`,
`PublicCacheInspection` 등). 7월 이후 runtime port가 바뀌어도(0929
05-01~05-14) recipe 복사본은 한 번도 따라오지 않았다. catalog는 이
복사본을 구현한 fake를 runtime의 fake로 안내해서, 그 fake로 쓴 테스트는
runtime에 없는 resume·quarantine을 전제했다.

고른 방법 (리뷰의 (c)):
- runtime이 있는 port와 그 표면의 타입은 recipe 정의를 지우고
  `src/application/ports`의 것을 같은 이름으로 다시 내보낸다. 옛 recipe
  port에만 쓰이던 `DurableObjectDataClass`, `DurableObjectIntegrity`,
  `DurableObjectRead`, `ObjectStoreRecoverySummary`도 지운다. src에 없는
  `DurableObjectId`·`ObjectGeneration` 브랜드와 `as*` 헬퍼는 남긴다(src
  port가 그대로 받는다).
- fake는 src port를 `implements`한다.
  - 파일 picker·content·preview·download fake와 storage durability fake:
    결과를 `BrowserDataResult`(`error`, 닫힌 코드, operation)로 바꿨다.
    `PROVIDER_UNAVAILABLE`은 src 코드 `UNAVAILABLE`이 된다.
  - `MemoryDurableObjectStore`: src OPFS port에 맞춰 다시 썼다. 생성자는
    scope·storagePolicy·maxObjectBytes를 받는다. 멈춘 put의 행은
    reconcile이 rollback만 한다(resume·quarantine 없음, runtime과 같다).
    LOGOUT·ACCOUNT_DELETION만 지원하고 나머지 reason은 `UNSUPPORTED`다.
  - 고칠 수 없는 fake: `MemoryStructuredOfflineStore`는
    `IndexedDbRepositoryPort`와 설계가 달라(배치 commit·idempotency 대
    CAS·lifecycle batch) catalog offline-indexeddb 행의 fake 칸에서 뺐다.
    recipe 전용 `StructuredOfflineStore`의 fake로는 남는다.
- recipe 전용 port 두 곳:
  - `PublicResponseCacheAdmin.inspect`는 runtime의 `PublicCacheInspection`
    모양으로 보고한다. `MemoryPublicResponseCache`가 그 모양을 만든다.
  - `FileTransferPort`(runtime 없음)의 progress는 `FileTransferProgress`로
    나눴다. `TransferProgress`라는 이름은 recipe barrel에서 src 타입으로
    계속 나간다. 일반 recipe인 `contracts.ts`가 선택형 runtime port를
    import하지 않게 하려는 것이다.
- 다시 갈라지지 않게 `optional-capability-contracts.test.ts`에 검사를
  더했다. recipes/가 src/application/ports/에 있는 이름으로 타입을
  정의하면 실패한다(다시 내보내기는 허용).
- runtime 제거 fixture(`test-browser-file-storage-runtime-removal.ts`)는
  이 runtime의 port를 다시 내보내는 recipe 두 파일과 그 테스트를 함께
  지우고, recipe barrel에서 두 export 줄을 먼저 뺀다.
버린 대안: 현상 유지(변경 누락 계속), 이름만 바꿔 `*Sketch`로 표시(중복
유지비가 남음), 두 벌을 비교하는 타입 테스트(두 벌을 계속 유지).

위험·한계:
- recipe에서 위 타입·fake를 쓰던 다운스트림은 컴파일 오류로 드러난다
  (조용히 깨지지 않는다). 같은 이름 타입의 모양, `MemoryDurableObjectStore`
  생성자·메서드, 파일 fake의 실패 결과(`failure` → `error`), 지운 타입
  4개가 바뀌었다. 두 제품 repo의 사용 여부는 확인하지 않았다.
- `MemoryDurableObjectStore`의 integrity digest는 runtime의 tree digest가
  아니다(주석에 적음). worker·Web Lock·authority·GC는 흉내내지 않는다.
- `test:browser-file-storage-removal`은 pnpm이 필요해 돌리지 못했다.
  barrel 줄 제거와 경로 추가는 코드로만 확인했다.

검증:
- RED: 새 검사를 수정 전 recipe 소스로 돌리면 실패한다.
  `expected [ 'LocalFileRef', …(33) ] to deeply equal []` (34개).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes
  tests/contract` 180 files 2,548건 통과. `tsc` app·recipes·test·node
  통과, 바꾼 파일 eslint 통과, `check-registries` PASS(재승인 불필요),
  `verify-documentation-readiness` PASS_SCOPED.
  `check-optional-recipes`(source)는 0929/05-01의 offline-indexeddb 예산
  초과(37,327 > 36,900)만 실패하고 catalog·source 검사는 통과했다.
  이 커밋은 그 번들 크기를 바꾸지 않는다(recipes/는 sourceRoots 밖).

BREAKING CHANGE: recipes/frontend-capabilities의 browser-file·OPFS·
storage durability·public cache 타입 중 src/application/ports와 이름이
같은 것은 이제 그 src 타입이다. file·durability·OPFS fake는 src port를
구현하고 BrowserDataResult를 돌려준다(`result.failure.code` →
`result.error.code`). `MemoryDurableObjectStore`는 `{ scope, storagePolicy,
maxObjectBytes }`로 만든다. `FileTransferPort`의 progress 타입은
`FileTransferProgress`다. `DurableObjectDataClass`·`DurableObjectIntegrity`
·`DurableObjectRead`·`ObjectStoreRecoverySummary`는 없어졌다.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-03
2026-11-03 01:23:05 +09:00
DongHyeonka 37e5f9d682 test(e2e): SW spec이 이미 켠 worker와 생성된 사전 캐시 목록을 쓴다 (0929/11-03)
SW e2e는 템플릿의 `= null;` 줄만 바꿔 worker를 켰다. 제품이 이미 ACTIVE로
켠 트리에서는 2건이 실패하고 4건이 실행되지 않았다. 사전 캐시 목록도
템플릿 기준으로 고정돼 있어 해시 파일을 더하면 2건이 실패했다.

선택을 지금 값과 상관없이 고치되, 이미 ACTIVE면 제품의 handler를 그대로
두는 `turnOnServiceWorker` 하나로 모았다. 빌드가 만든 사전 캐시 목록을
`precached`로 돌려주고 spec이 그 목록과 비교한다. 같은 문제를 고친
0929/06-04(`96a4f68`)의 `selectActiveServiceWorker`는 ACTIVE 선택을
템플릿 값으로 덮어써 제품 handler가 빠지므로 이 함수로 바꿨고, 실패한
준비 단계에서 임시 복사본을 지우는 처리는 유지했다(두 브랜치 병합 때
오케스트레이터가 충돌을 풀었다).

위험: 테스트 도우미만 바뀐다. 0929/06-04 단위 테스트의 기대값이 "ACTIVE
선택도 템플릿 값으로 덮어쓴다"에서 "ACTIVE 선택은 그대로 둔다"로 바뀐다.
검증: ACTIVE 선택과 해시 파일 추가 트리 모두 6 passed(에이전트).
병합 뒤 service-worker-build-output 단위 테스트 5/5, SW e2e chromium·webkit
12/12, tsc(test), eslint 통과.
2026-11-01 23:20:28 +09:00
donghyeon-kaandClaude Opus 5.5 51685503d0 test(bootstrap): pin the composition's telemetry wiring for a failed Service Worker start (06-05)
Only the optional host was tested, so removing the composition line that hands
it the telemetry port kept every test green. The real composition with an
ACTIVE selection and a failing first install now must emit one event, and the
recipe doc names what the template still leaves unwired.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 14:05:59 +09:00
DongHyeonkaandClaude Opus 5.5 cd47516592 fix(bootstrap): report a Service Worker that did not start through telemetry (06-05)
An ACTIVE worker whose install failed left a trace only in health(), which
nothing reads. The optional host now emits service-worker.start.failed on the
application telemetry port, and the recipe doc lists what else to wire.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:26:54 +09:00
DongHyeonkaandClaude Opus 5.5 8a0e5f55bb test(security): smoke the build under the production CSP (13-08)
The declared CSP was never applied in a browser. A Playwright spec now serves
the build with config/hosting/security-headers.json and fails on any
securitypolicyviolation. It found one: zod's Function('') probe, listed in the
spec as a known violation until zod is configured jitless before first use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:10:59 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00
donghyeon-ka 6c73b845bd feat: add optional frontend adapter recipes 2026-07-26 17:57:04 +09:00