Commit Graph
25 Commits
Author SHA1 Message Date
DongHyeonka a37ebba39c fix(architecture): 기능 안 계층 밖 폴더가 src/adapters에 닿으면 막는다
문제
feature-and-app-roots-do-not-reach-adapters는 기능 루트 파일
(src/features/*.ts, src/features/<id>/*.ts), src/contexts, src/apps만 본다.
그래프는 간선 하나씩 검사하므로, 기능 안에 계층이 아닌 폴더(support/ 등)를
만들어 그 파일이 http adapter 배럴을 import하고 기능 presentation이 그 파일을
import하면 presentation이 구체 adapter에 닿는다. 1105 리뷰 12-R3 변이에서
check:architecture와 ESLint가 둘 다 통과했다.

고른 방법
- 규칙의 from을 "src/features 아래 모든 파일, 기능의 adapters/ 폴더 밖"으로
  바꾼다(`^src/(features/|contexts/|apps/)`, pathNot
  `^src/features/([^/]+/adapters/|feature-adapter-contribution\.ts$)`). 규칙
  주석이 이미 "기능 안에서는 adapters/ 폴더만 src/adapters에 닿는다"고 적고
  있었고, 그 문장을 경로로 옮긴 것이다. 파일 단위 예외는 기존 하나
  (feature-adapter-contribution.ts, type only) 그대로고 새로 더하지 않았다.
- domain·application·presentation은 자기 규칙이 이미 src/adapters를 막는다.
  이제 그 파일들이 src/adapters를 import하면 이 규칙도 같이 걸린다(위반 두 줄).
  더 엄격해질 뿐 허용이 바뀌지는 않는다.
- 지금 src/features에서 src/adapters를 import하는 곳은 reference-feature의
  adapters/ 두 파일과 feature-adapter-contribution.ts뿐이라 새 위반은 없다.
  create:feature가 만드는 adapter import도 adapters/ 안이다.
- 그래프 회귀 fixture에 support/ 재수출(거절), 그것을 읽는 presentation,
  기능 adapters/ import(허용)를 더하고 check:architecture에 두 단언을 더했다.
  규칙 경로를 check:architecture와 같은 방식으로 읽는 vitest 테스트를 더했다.
- layers.md 표와 매뉴얼 01의 설명을 고쳤다.
- 버린 대안: 계층 밖 폴더 자체를 금지(폴더 이름 목록 검사). 제품이 contracts/
  같은 다른 이름을 쓰면 계속 목록을 고쳐야 한다. 규칙마다 support/ 패턴 추가:
  다음 폴더 이름에서 같은 틈이 난다.

위험·한계
- 다운스트림이 기능 안 adapters/ 밖에서 src/adapters를 import하고 있었다면 이제
  check:architecture가 실패한다. 그 파일을 adapters/로 옮기면 된다.
- ESLint는 여전히 간선 하나만 보므로 이 경로를 잡지 않는다. 그래프가 잡는다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/architecture/feature-adapter-reach.test.ts, corepack pnpm
  check:architecture(그래프 fixture 단언 2개 추가 PASS, 저장소 위반 0 기대).
- RED 기대: "rejects a concrete adapter import from a feature folder that is not
  a layer", "leaves a feature's adapters folder and the type-only contribution
  file to reach adapters"(support/adapters/ 경로 단언).

Refs: 0929/12-03
2026-11-05 22:41: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 05958bbdb6 feat(recipes): 짝 백엔드 두 인증 모드의 세션 owner recipe를 더한다
문제: AUTH_MODE external은 제품이 owner 8개 메서드를 직접 써야 하는데,
짝 백엔드(JWT·Keycloak 또는 Redis session)에 맞는 owner가 src·recipes
어디에도 없다. 쿠키 owner 모양은 테스트 파일 안 스케치뿐이다. 그래서
제품마다 첫 연동 전에 토큰 획득·갱신·subject·상태 전이·401 처리를
처음부터 쓴다.

짝 백엔드(bbe944bd)에서 확인한 계약:
- jwt 모드(기본): OAuth2 resource server. iss = APP_SECURITY_JWT_ISSUER
  (local http://localhost:8081/realms/ca-skeleton), aud 필수. CSRF·세션
  없음. 그러나 realm에는 서비스용 confidential client(ca-skeleton-api,
  standard flow 꺼짐)만 있고 브라우저용 public client가 없다.
- redis-session 모드: CA_SESSION httpOnly 쿠키, CookieCsrfTokenRepository
  (XSRF-TOKEN 쿠키, X-XSRF-TOKEN 헤더, plain handler). 로그인·로그아웃·
  세션 조회·CSRF 발급 엔드포인트는 운영 코드에 없다(테스트 픽스처만).

고른 방법: recipes/session-owners/에 둘을 둔다. 제품은 src/bootstrap/로
복사해 composeProductSessionOwner에서 돌려준다.
- oidc-pkce-session-owner.ts: authorization code + PKCE S256, WebCrypto와
  context fetch만 쓴다(라이브러리 없음). 토큰은 메모리에만, sessionStorage
  에는 10분짜리 거래(verifier·state·nonce·returnTo)만 두고 콜백이 먼저
  지운다. 콜백 URL에서 code를 네트워크 호출 전에 지운다. state·RFC 9207
  iss·nonce·aud·azp·exp·sub를 검사하고, 갱신 때 sub가 바뀌면 로그아웃.
  bearer는 apiOrigins에만 보낸다. 만료 30초 전 갱신은 한 번만 하고 상태
  알림이 없다. 401이면 refresh token으로 한 번 복구하고, 그 토큰도 401이면
  로그아웃. 설정이 틀리면 integration-failed로 닫는다.
- cookie-session-owner.ts: 세션 조회·로그아웃 URL과 로그인 시작을 기본값
  없이 받는다(백엔드에 없는 엔드포인트를 지어내지 않는다). 200+subject →
  authenticated, 401 → unauthenticated, 그 밖은 reject(상태 유지).
  SESSION_COOKIE_READ/WRITE 프로필과 XSRF-TOKEN → x-xsrf-token provider.
  쿠키가 없으면 쓰기는 UNAVAILABLE로 아무것도 보내지 않는다.
- 두 owner 모두 SessionState·recover 전이 계약을 따른다.
- PRODUCTION_IMPORTS_RECIPE 검사를 recipes/session-owners에도 건다.
  recipe는 복사하지 import하지 않는다(초기 번들 밖).
버린 대안: src에 기본 owner 내장(IdP 결합이 템플릿 본체에 들어간다),
OIDC 라이브러리 의존(fetch·WebCrypto로 충분), 매뉴얼만(같은 실수 반복).

위험·한계: 실제 Keycloak·Redis session 백엔드에 붙여 보지 않았다. ID
token 서명은 검사하지 않는다(토큰 엔드포인트 직접 응답, OIDC Core
3.1.3.7 (6)); access token 서명은 백엔드가 본다. 새로고침하면 메모리
토큰이 사라져 다시 로그인한다(Keycloak SSO면 비밀번호 없이 돌아온다).
쿠키 모드는 페이지와 API가 같은 host여야 XSRF-TOKEN을 읽는다.

검증: tests/recipes 3파일 52건(구현 전 모듈 없음으로 실패 확인).
변이 15개(state·origin·401 한 번·nonce·iss·URL 정리·갱신 sub·TTL,
CSRF 헤더·401·로그아웃 실패·notify·단일 조회·subject 상한·credentials)
모두 실패로 잡힘. runtime 조립 테스트 4건이 실제 createRuntimeAdapters로
EXTERNAL_BEARER bearer, 401 뒤 갱신, 쿠키 쓰기의 x-xsrf-token을 확인.
check:optional-recipe-fixtures(regex 변경 없이는 실패 확인),
check:optional-recipes:source, check:types, eslint 통과. 두 recipe의
minify+gzip 크기 3.8 kB, 1.1 kB.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
2026-11-04 20:47:24 +09:00
DongHyeonka 64f19ac665 fix(architecture): zod 하위 경로 import도 src/contracts/zod.ts를 거치게 한다
문제
zod-is-reached-through-contracts-zod 규칙의 to.path가 ^zod$다. src 파일이
"zod/v4"를 import하면 check:architecture가 rc=0으로 통과한다(실험 Z1). 그
모듈은 src/contracts/zod.ts의 jitless 설정보다 먼저 스키마를 만들 수 있고,
그러면 운영 CSP가 zod의 Function 탐침을 부팅마다 보고한다(F-7).

고른 방법
to.path를 ^zod(/|$)로 넓힌다. 그래프 fixture에 "zod/v4"를 import하는 파일과
그것이 거절되는지 보는 회귀 검사를 더했다. layers.md 규칙 표도 고쳤다.

버린 대안
- eslint no-restricted-imports에 zod 패턴 추가: 같은 규칙을 두 도구에
  둔다. 경계 규칙은 dependency-cruiser가 정본이다.

위험·한계
- src 안에 zod 하위 경로 import는 지금 없다(grep). 다운스트림이 쓰고
  있으면 check:architecture가 실패한다. src/contracts/zod.ts의 z로 바꾼다.

검증
- 수정 뒤: 참조 기능 스키마 파일 import를 "zod/v4"로 바꾸면
  "Architecture violation [zod-is-reached-through-contracts-zod]: ... ->
  zod/v4"로 실패, "zod"도 실패.
- 규칙을 ^zod$로 되돌리면 새 회귀 검사 "zod subpath import outside
  src/contracts/zod.ts is rejected"가 실패한다.
- check:architecture(29 regression checks PASS), check:types, eslint,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-06
2026-11-04 20:38:14 +09:00
DongHyeonka 048f490ada refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.

고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
  resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
  스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
  parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
  parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
  지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
  legacy-http-credential-authority, bounded-json-compatibility,
  request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
  지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
  boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
  계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
  422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
  비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
  보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
  1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
  risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
  경로를 V3 파일로 바꿨다.

버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
  곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.

위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
  CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
  자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
  재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
  커밋에서 지우지 않았다. 다음 커밋이 지운다.

검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
  check:adapter-inventory(140 files), check:diagnostics, check:registries,
  check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
  test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).

BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
2026-11-03 21:12:34 +09:00
DongHyeonka 6255f05b3c fix(i18n): 타입 fixture 주석이 샘플 경로를 적지 않게 한다 (0929/08-03)
문제: ff33d58이 tests/fixtures/typecheck/invalid-message-params.ts 주석에
샘플 기능 테스트 경로를 적었다. 샘플 제거 드릴의 잔여물 검사가 이 문자열을
샘플이 남은 흔적으로 보고 test:sample-removal이 실패했다.

방법: 주석에서 경로를 빼고 "샘플 기능의 자기 테스트"로 적었다. 잔여물 검사
정규식을 넓히거나 이 파일을 예외로 두는 방법은 버렸다. 검사가 약해진다.

검증: 같은 정규식으로 파일을 검사해 0건. test:sample-removal은 다음 게이트
실행에서 다시 돌린다.
2026-11-03 01:34:32 +09:00
DongHyeonka 498ae87554 test(evidence): HTTP 시나리오와 타입 음성 fixture를 테스트 계약으로 옮긴다 (0929/10-02)
문제: 샘플 제거 절차(scripts/test-sample-removal.ts)의 SAMPLE_EXTRAS가
플랫폼 검사도 함께 지운다. HTTP 실패 시나리오 카탈로그(57개)와 tests/mocks,
test:http-scenario-evidence(FE-GATE-007), 기능 API 타입 음성 fixture 8개와
check:types:fixture:* 8개(FE-GATE-003)가 참조 기능 계약을 import해서
샘플 소유로 묶여 있었다. 드릴은 플랫폼 경로 4개만 확인하므로 통과하고,
제품은 가드레일이 줄었다는 것을 모른다.

방법: 카탈로그와 handler를 tests/helpers/external-contract-fixture.ts의
테스트 계약(TEST_LIST/DETAIL, 명령)으로 옮겼다. 바이트 상한·명령 여부·성공
status는 계약에서 읽는다. 명령은 효과를 분류하는 패키지처럼
TEST_CLASSIFIED_CREATE_HTTP_CONTRACT를 더해 기존 기대값(401/403/429·422·
409 CONFLICT는 NOT_APPLIED, 409 IN_FLIGHT·404·503은 MAYBE_APPLIED)을
그대로 지킨다. TEST_CREATE_HTTP_CONTRACT의 분류기는 실행기 테스트가
"분류기 없음"을 확인하는 데 쓰므로 바꾸지 않았다. 문제 스키마에 선택
code만 더했다.
타입 fixture는 fixture tsconfig만 컴파일하는 fixture-feature-contract.ts의
테스트 기능(operation ID를 literal로 좁힌 테스트 계약, "fixture-feature"
입력 등록)을 쓴다. 등록 augmentation이 app·test 프로그램에 들어가지 않는다.
참조 기능 전용 handler(성공 응답만 쓰였다)는 tests/features/reference-feature
로 옮겼다. test-evidence.json의 owner는 platform이다. SAMPLE_EXTRAS에서
이 경로·스크립트를 빼고, 드릴의 플랫폼 보존 확인 목록에 16개 경로를 더했다.
샘플이 증거 정책을 갖지 않으므로 "등록 안 됨" 오류 검사는 지웠다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
검사는 계속 사라진다.

위험: fixture 스크립트 이름(check:types:fixture:reference-operation)과
파일 이름은 그대로라 이름이 내용(TEST_GET_ENTITY)과 다르다. CI 스크립트·
gates·워크플로 스냅샷을 함께 바꿔야 해서 미뤘다. 드릴의 제외 목록에 있는
tests/unit/http-scenario-evidence.test.ts는 그대로 뒀다.
test:sample-removal 자체는 pnpm이 필요해 돌리지 않았다.

검증: RED는 기준 복사본에 드릴의 삭제 목록을 적용했다. 카탈로그 테스트·
tests/mocks·타입 fixture 16파일이 지워지고 CI 스크립트 9개가 빠지는데 보존
확인은 4/4로 통과한다. GREEN은 같은 적용 뒤 보존 확인 16/16, 잔여 이름은
드릴이 빼는 removal-fixture.test.ts 하나, 타입 fixture 8개가 기존과 같은
진단(TS2345·2741·2353·2322·2345·2322·2322·2339) 1건씩으로 실패, 카탈로그
57/57 실행·check-test-evidence --scenario-only PASS, tests/component와
카탈로그 36파일 226개 통과, tsc -p tsconfig.test.json 통과. worktree에서는
테스트 계약 사용 파일·참조 기능·카탈로그 59파일 535개, scale session 2파일
통과, 음성 fixture의 양성 대조 컴파일 통과, tsc test·node 통과,
check-ci-contract PASS, 바꾼 파일 eslint 통과.
2026-11-03 01:18:36 +09:00
DongHyeonka e8d7fb427f fix(registry): 기능 라우트를 추가해도 governance를 고치지 않게 한다 (0929/07-03)
문제
FE-REG-ROUTE governance가 paramsSchema·searchSchema·loadingSurface를 참조
기능 값까지 적은 닫힌 목록으로 둔다. 기능이 자기 search 스키마나 자기
로딩 화면 이름을 가진 라우트를 더하면 check:registries가 "has unknown
value"로 실패하고, 템플릿 소유 파일인 registry-governance.json을 고쳐야
한다. 목록은 contract 일부라 고치면 breaking 증거나 재승인도 필요하다.
두 다운스트림 모두 여기서 충돌했다. 스키마 id는 이미 references가
FE-REG-SCHEMA와 대조하므로 목록은 같은 사실의 세 번째 사본이고,
loadingSurface는 data-surface 속성 말고 읽는 코드가 없다. 문서는
"governance file do not change"라고 적지만 그 약속을 고정하는 테스트는
라우트 없는 기능만 넣었다.

고른 방법 (2026-11-03 결정, 리뷰 (B))
- paramsSchema·searchSchema를 FE-REG-ROUTE allowedValues에서 뺐다.
  references 검사는 그대로라 등록되지 않은 스키마 id는 계속 실패한다.
- loadingSurface는 목록 대신 이름 형식만 본다. governance에 선언형 키
  fieldPatterns(필드 → 고정된 정규식)를 더하고 check-registries가 문자열
  값을 대조한다. FE-REG-ROUTE는 kebab-case
  ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$를 쓴다. fieldPatterns는 선언한
  레지스트리에서만 contract 스냅샷에 들어가므로 다른 레지스트리의
  contract는 바뀌지 않고, 정규식을 바꾸면 contract 변경(breaking)으로
  잡힌다.
- second-api-feature-registries 테스트의 두 번째 기능에 자기 search 스키마
  (SecondItemListQuery)와 전용 loading surface(second-item-list)를 가진
  라우트를 넣었다. 저장소 사본에 기능 디렉터리와 context만 더하고
  check-registries가 PASS인지 본다. 지시의 two-feature-install-typecheck는
  app 타입 검사만 돌려 governance를 보지 않으므로, check-registries를 돌리는
  이 테스트를 확장했다.
- 라우트 fixture(check:routes:fixture)의 governance도 같은 모양으로 바꾸고,
  형식에 맞지 않는 이름("Unknown loading")이 거절되는 단위 테스트를 더했다.
- starter-experience.md가 이 테스트를 가리키고, 라우트의 스키마·로딩 화면이
  governance 수정 없이 들어가는 이유를 적는다.
- 두 contract 변경(allowedValues 축소, fieldPatterns 추가)은 breaking이다.
  이 커밋에서는 증거 2건으로 게이트를 통과시키고, 기준선 재승인은 이번
  작업 묶음 끝에서 한 번에 한다.

이유: 기능 하나를 추가할 때 템플릿 파일을 고치게 만드는 지점이다. 두
다운스트림 모두에서 충돌했다.

버린 대안
- 문서만 "allowlist를 고치고 증거를 쓴다"로 정정: 기능마다 비용이
  반복된다.
- 기능 계약이 자기 allowlist 값을 기여하는 확장 메커니즘: 등록 규약이
  하나 더 생긴다.

위험·한계
- loadingSurface 오타는 이제 형식만 맞으면 통과한다. 이 값은 로딩
  요소의 data-surface 속성일 뿐이라 동작이 바뀌지 않는다. loadingSurface가
  로딩 컴포넌트 선택 같은 실행 의미를 갖게 되면 닫힌 목록을 다시 둔다.
- errorSurface·access는 라우터가 의미로 읽으므로 닫힌 목록을 유지한다.
  기능이 새 errorSurface를 쓰려면 지금처럼 governance를 고친다.
- 다운스트림은 다음 동기화에서 자기가 이 목록에 더한 값을 지운다.
  CHANGELOG [계약] 행이 필요하다.

검증
- RED(수정 전): 확장한 second-api-feature-registries 테스트가
  "FE-REG-ROUTE.SECOND_ITEM_LIST.searchSchema has unknown value
  SecondItemListQuery", "...loadingSurface has unknown value
  second-item-list"로 실패. 새 형식 테스트는 수정 전 checker로
  "expected [] to deeply equal [ Array(1) ]"로 실패.
- GREEN: 두 테스트 통과. 증거 없이 check-registries는 "breaking change
  missing evidence" 2건(allowedValues contract-field-changed,
  fieldPatterns contract-field-added)으로 실패, 증거를 넣은 뒤
  "11 registries PASS".
- 회귀: registry-compatibility·registry-governance·second-api-feature-
  registries·release-artifacts·two-feature-install-typecheck 57/57.
  compatibility fixtures 11 PASS. check:routes:fixture는 기대대로
  "duplicates routeId=DUPLICATE"로 실패. verify-documentation-readiness
  PASS_SCOPED. tsc node·test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요).

Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
2026-11-03 00:55:33 +09:00
DongHyeonka 855d22ac1b fix(i18n): 화면 문구 literal 검사를 ESLint 선택자로 옮긴다 (0929/08-02)
문제: `check:i18n`은 화면 파일 전체에 `/[가-힣]/`를 돌린다. 한국어 주석
한 줄에 실패하고, 영어 JSX 문구와 영어 접근성 이름은 통과한다. 샘플
화면에도 영어 literal이 이미 있었다(목록 h1 "Reference feature",
`limit {n}`, 목록 aria-label, 상세 "DetailPage"·"Resource ID"·"Created",
폼·상태 eyebrow). ko-KR 사용자에게 영어 문구와 스크린리더 이름이 섞인다.

고른 방법: (B) 문구 literal 검사를 ESLint `no-restricted-syntax` 선택자로
옮긴다(`eslint.config.ts`의 `screenTextSelectors`).
- 대상: 글자(`\p{L}`)가 든 `JSXText`, 표시·접근성 속성(`aria-label`,
  `aria-description`, `aria-roledescription`, `aria-valuetext`,
  `aria-placeholder`, `title`, `placeholder`, `alt`, `label`)의 문자열
  literal, 그리고 `{"..."}` 형태의 같은 literal. 주석은 AST에 없어 빠진다.
  구두점·숫자만 있는 문구는 통과한다.
- 범위(4.3절 "화면 코드"): 지난 `check:i18n`과 같은 폴더다. 공통 UI
  폴더와 `src/features/*/presentation`. 컴포넌트 갤러리
  `src/presentation/examples`는 지금처럼 뺀다. stories(`*.stories.tsx`)는
  workshop 코드라 뺀다. 테스트는 이 폴더 밖이라 대상이 아니다.
- 이 항목은 일반 `no-restricted-syntax` 목록을 대체하므로 FE-OC-019
  선택자(raw HTML, script 생성)를 함께 싣는다.
- `check:i18n`에는 catalog parity와 raw backend 메시지 검사만 남긴다.
  raw HTML은 원래 전역 FE-OC-019 ESLint 규칙이 거절한다.
- `check:i18n:fixture`는 ESLint Node API로 같은 규칙을 fixture 트리에도
  돌린다. forbidden 파일은 하나하나 거절돼야 하고(아니면 종료 코드 2),
  새 `tests/fixtures/i18n/allowed` 트리(한국어 주석, 구두점, catalog
  문구)는 통과해야 한다(거절되면 종료 코드 2). 게이트 기대값(종료 1,
  "I18n contract failed:")은 그대로다.
- fixture 추가: allowed `korean-comment.tsx`, forbidden
  `english-jsx-text.tsx`, `english-accessible-name.tsx`.
- 샘플의 영어 literal 11곳을 catalog로 옮겼다. 새 키 10개
  (`reference.list.title`·`filterLimit`·`filterTags`·`resources`,
  `reference.detail.eyebrow`·`titlePending`·`resourceId`·`createdAt`,
  `reference.form.eyebrow`, `reference.status.eyebrow`). en-US 값은
  예전 영어 문구 그대로라 en-US 화면은 바뀌지 않는다. ko-KR 화면은 한국어가
  된다.

버린 대안:
- (A) 현 상태: 두 제품이 각각 막히거나 스크립트를 고쳤다.
- (C) "행동·상태 문구"만 정규식으로 고르는 제품 정책: 한국어 문장 목록에
  기대 영어를 못 잡고, 템플릿 기본값으로 쓰기에 제품 특화다.
ESLint 설정은 제품이 자기 규칙으로 덮어쓸 수 있는 자리다(한 locale 제품,
고유명사 허용).

위험·한계:
- 식 안에서 만든 문구는 보지 못한다. template literal, 삼항식, 객체
  prop(`heading.title` 같은 것)이 그렇다. 샘플의 이런 문구는 손으로
  옮겼고, `reference-page.test.tsx`가 ko-KR main 영역을 catalog·데이터
  밖 라틴 문자로 검사해 그 빈 곳을 샘플에서만 막는다.
- 고유명사·브랜드 이름도 걸린다. 제품이 선택자를 덮어쓰거나 그 줄에
  `eslint-disable-next-line`을 쓴다.
- ko-KR route 제목(`route.REFERENCE_RESOURCE_*`)은 catalog 안의 영어라
  그대로 뒀다(라우트 제목 정리는 0929/08-06 몫).
- `tests/e2e/reference-form.spec.ts`의 ko-KR 목록 h1 기대값을 "참조
  기능"으로 바꿨다. e2e는 이 worktree에서 돌리지 않았다(webServer가
  pnpm build를 부른다).
- 시각 골든(`tests/visual`)은 /examples/ui·states·platform만 찍는다.
  샘플 화면과 nav 문구는 바뀌지 않아 골든 영향이 없다고 본다(미실행).

검증:
- RED(수정 전):
  - E1 한글 주석 변이: `node scripts/check-i18n.ts` -> "hardcoded common
    user-facing locale literal in .../reference-resource-status-page.tsx",
    exit 1
  - E1b 영어 JSX 문구 변이: `check-i18n.ts` PASS exit 0, `eslint` exit 0
  - `check-i18n.ts --fixture` -> "I18n fixture was not rejected:
    english-accessible-name.tsx, english-jsx-text.tsx", exit 2
  - 새 ko-KR main 테스트: "limit 5 · tags ..." 가 남아 실패
- GREEN(수정 후):
  - E1 변이: `check-i18n.ts` PASS, `eslint` exit 0
  - E1b 변이: `eslint` -> 42:13 no-restricted-syntax, exit 1
  - `check-i18n.ts` PASS(224 keys), `--fixture` -> forbidden 7개 모두
    거절, "I18n contract failed:", exit 1. allowed에 영어 문구를 넣으면
    "I18n allowed fixture was rejected", exit 2
  - ko-KR main 테스트 통과
- `npx eslint src scripts tests recipes .storybook ... --max-warnings=0`
  통과, app·test·node 타입 검사 통과
- vitest: tests/unit + tests/component 209 files 2725 tests,
  tests/features 등 25 files 141 tests 통과
- `check-registries.ts` PASS, `check-ci-contract.ts` PASS,
  `verify-documentation-readiness.ts` PASS_SCOPED

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-02, 4.3
2026-11-03 00:54:18 +09:00
DongHyeonka ff33d58e95 feat(i18n): 문구 보간 파라미터를 catalog의 {이름}에서 만든다 (0929/08-03)
문제: 보간 파라미터 타입이 플랫폼 파일의 닫힌 목록 `MessageParameters`에만
있다. 목록에 없는 기능 키는 `[parameters?: never]`가 된다. 그래서
`formatMessage("ko-KR", "reference.list.resultCount")`는 타입 검사를
통과하고 실행하면 대체 문구를 돌려주며, `{ count: 1 }`을 넣으면 TS2345로
거절된다. 샘플은 타입 없는 `resolveMessage`로 우회했고, tech-log는 템플릿
파일에 키 11개를 넣었다.

고른 방법: (B) catalog가 `as const`이므로 ko-KR 문자열 literal의
`{이름}`에서 `MessageArguments<Key>`를 만든다. 값 타입은
`string | number`다. 값 타입을 좁히고 싶은 키만 `MessageParameters`로
덮어쓴다. 덮어쓰기는 catalog 파라미터와 교집합이라 좁히기만 한다. 덮어쓴
항목이 catalog 문자열과 어긋나도 catalog의 자리표시자는 계속 필수다.
`ParameterlessMessageKey`도 "자리표시자가 없는 키"로 같은 규칙에서
만든다. 기존 덮어쓰기 8개는 값 타입을 좁히므로 그대로 둔다.
새 개념이 없고, 기능이 템플릿 파일을 고치지 않는다.

버린 대안: (C) 기능 모듈이 파라미터 타입을 따로 선언하고 설치 조립이
교집합을 만든다. 값 타입을 정확히 쓸 수 있지만 catalog와 선언을 따로
맞춰야 한다.

위험·한계:
- 값 타입이 `string | number`로 넓다. 좁히려면 `MessageParameters`에
  덮어쓴다.
- 자리표시자는 ko-KR 문자열에서 읽는다. 다른 locale과의 일치는
  `tests/unit/i18n-contract.test.ts`의 parity 검사가 지킨다.
- ICU 복수형·select처럼 `{이름}`으로 표현하지 못하는 문구는 다루지
  않는다(VD-06 재검토 조건).
- 타입 검사 비용(`tsc -p tsconfig.app.json --extendedDiagnostics`):
  Types 287,440 -> 289,911(+0.9%), Instantiations 721,217 -> 748,663
  (+3.8%). 실행 시간은 load average 9~21에서 전·후 모두 1.0~2.6초로
  흔들려 차이를 구분할 수 없었다.
- 기능 키 검사(`tests/features/reference-feature/feature-module.test.ts`)는
  샘플과 함께 지워지도록 샘플 테스트 폴더에 두었다. 플랫폼 fixture는
  샘플 키에 기대지 않는다.

검증:
- RED: `npx tsc -p tsconfig.test.json --noEmit`
  feature-module.test.ts(23,5): error TS2578: Unused '@ts-expect-error'
  feature-module.test.ts(26,60): error TS2345: Argument of type
  '{ count: number; }' is not assignable to parameter of type 'undefined'.
- GREEN: 같은 명령 오류 0. app·node·recipes 타입 검사 통과.
- `check:types:fixture:i18n-params` fixture: 기존 3줄은 TS2554/TS2345로
  계속 실패하고, 더한 덮어쓰기 좁힘 줄은 TS2322로 실패한다.
- vitest: tests/features/reference-feature, i18n-contract,
  locale-platform 19 files 97 tests 통과.
- 샘플 목록 화면이 타입 있는 `message()`로 결과 수를 그린다.

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-03
2026-11-03 00:54:18 +09:00
DongHyeonka 82c9e594ff fix(registry): 선언된 null 전환과 허용값 추가를 breaking으로 막지 않는다 (0929/07-02)
문제
레지스트리 호환성 분류기(scripts/lib/registry-compatibility.ts)는 값의 JS
타입이 다르면 breakingFields를 보기 전에 field-type-changed(breaking)로
판정한다. null과 문자열은 타입이 달라서, governance가 string|null로
선언하고 breaking 필드에서 뺀 필드(navigationLabel, navigationOrder, API
timeoutMs, 저장 ttl, ENV defaultValue)를 null <-> 값으로 바꾸기만 해도
breaking 증거를 요구한다. contract의 allowedValues에 값을 더하는 것도
어떤 변경이든 breaking이다. 그래서 증거 5필드에 쓸 내용이 없는 변경에
"마이그레이션·롤백"을 지어 쓰게 된다. 템플릿 자신도 VITE_BUILD_ID
defaultValue null -> "local-build"에 "the value itself did not change"라고
적은 breaking 증거를 남겼다.

고른 방법 (리뷰 최소 개선 B)
- 행 필드: 한쪽이 null이고 두 값이 모두 그 필드의 선언 타입
  (contract.fieldTypes, 예 string|null)에 맞으면 타입 변경이 아니라
  field-changed로 보고 breakingFields로 등급을 정한다. 선언이 없거나
  선언 밖 값이면 지금처럼 field-type-changed(breaking)다.
- contract allowedValues: 필드 집합이 같고 필드마다 이전 허용값을 모두
  포함하면 allowed-values-extended(additive)다. 값 하나라도 빠지거나,
  새 필드를 제한하거나, 제한을 없애면 지금처럼 breaking이다. 나머지
  contract 변경도 그대로 breaking이다.
- 선언 타입 판정은 check-registries.ts에 있던 runtimeType·
  matchesDeclaredType을 lib로 옮겨 검사기와 분류기가 같은 함수를 쓴다.
- semantic-diff.json fixture에 nullable-field-cleared(behavior-change),
  registry-contract-extension(additive)을 더하고 artifact id 목록에도
  넣었다.

버린 대안
- 현 상태 + "이런 변경은 재승인하라"는 문서: 재승인이 증거를 대신하는
  길을 더 넓힌다(0929/07-04).
- nullable 필드 판단 전체를 breakingFields로 옮기기(리뷰 C): 다른
  레지스트리 영향을 다시 봐야 하는 넓은 변경이다.
- 제한 해제(allowedValues에서 필드 키 삭제)를 additive로 보기: 리뷰
  기준("이전 값을 모두 포함")에 맞지 않고 판단이 하나 더 필요해 보수적으로
  breaking에 남겼다.

위험·한계
- fail-closed 범위가 줄어든다. 선언 타입 안의 null 전환이 의미("기능
  꺼짐")를 갖는 필드는 breakingFields에 넣어야 breaking으로 남는다.
  paramsSchema·searchSchema는 이미 breakingFields라 그대로 breaking이다.
- 현재 기준선 diff에서 VITE_BUILD_ID defaultValue가 breaking에서
  behavior-change로 바뀐다. registry-change-evidence.json의 해당 증거 행
  (field-type-changed)은 이제 어떤 변경과도 맞지 않는다. 오래된 증거 정리는
  0929/07-01 범위라 이번에는 지우지 않았다.
- 다운스트림의 같은 종류 증거 행도 쓰이지 않게 된다. 게이트 판정이
  바뀌는 변경이라 다음 릴리스 CHANGELOG에 [계약] 행이 필요하다(이번
  라운드는 CHANGELOG 미출시 절이 없어 적지 않았다).
- fieldTypes 키가 점 경로(a.b)인 필드는 행의 최상위 필드 이름과 맞지 않아
  계속 breaking으로 남는다.

검증
- RED(분류기 수정 전): registry-compatibility.test.ts 새 사례 5건 실패
  (null 전환 3건이 breaking/field-type-changed, nullable breaking 필드의
  kind, allowlist 확장 breaking). check-registry-compatibility-fixtures:
  nullable-field-cleared actual breaking, registry-contract-extension
  actual breaking.
- GREEN: registry-compatibility·registry-governance·release-artifacts·
  second-api-feature-registries 49/49 통과. compatibility fixtures 11 PASS.
  check-registries "11 registries PASS"(남은 breaking은
  REFERENCE_RESOURCE_DETAIL.path 하나, 증거 있음).
  ci-artifact-contract "semantic validator" 사례 통과.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm). tests/system 나머지(provider guardian
  exit=126 환경 문제로 이 변경과 무관하게 실패).

Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
donghyeon-kaandClaude Opus 5.5 4805e56ab1 Merge lane/J: test system (10-02, 10-04~10-07, 11-04~11-08, F-2, F-4, F-12, 00-03)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:28:55 +09:00
donghyeon-ka 2b2cabb7f2 Merge lane/H: presentation (07-01, 08-02, 08-04, 08-05, 08-07~08-13, 11-02, F-10)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	config/contracts/registry-change-evidence.json
2026-09-27 13:19:31 +09:00
donghyeon-kaandClaude Opus 5.5 9dc95ca066 fix(contracts): set zod jitless before any schema is built so the production csp sees no eval (F-7, 13-08)
zod probed Function("") on its first object schema, which the production CSP
(no unsafe-eval) reported on every boot. Schema code now imports z from
src/contracts/zod.ts, enforced by a dependency-cruiser rule, and the CSP smoke
drops its init-script workaround.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 12:58:57 +09:00
DongHyeonkaandClaude Opus 5.5 7870c48b5f test(evidence): forbid focused tests and expired quarantines (11-08)
Only the capabilities config set forbidOnly, so a committed test.only ran one
e2e, visual or storybook test and passed. The skip check accepted any
quarantine marker without comparing its expiry date to today.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 01:01:49 +09:00
DongHyeonkaandClaude Opus 5.5 d68e25a2ad test(coverage): ratchet live retry, contract bridge and IndexedDB modules (10-04)
The policy guarded legacy retry-policy.ts but not the live V3 retry and
contract path rules, and the strategy doc claimed 19 modules at 90% targets.
The doc now states the enforced ratchet. The below-threshold fixture used the
pre-counter summary shape and failed with a TypeError instead of the
'Risk coverage failed:' diagnostic the negative gate expects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:28:02 +09:00
DongHyeonkaandClaude Opus 5.5 710436bc2e fix(ci): pin each diagnostics fixture violation with its own ts-expect-error (07-05)
The gate only matched one diagnostic string, so widening the telemetry event
name or the diagnostic level still counted as the expected failure. Each
violation now has its own directive and the fixture must compile cleanly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:22:08 +09:00
DongHyeonkaandClaude Opus 5.5 411619c543 fix(i18n): move sample screen copy into catalogs and widen check:i18n (08-04)
The reference feature and home page rendered Korean literals, so en-US
still showed Korean. check:i18n now scans pages and every feature
presentation folder, and its fixture fails unless every fixture is rejected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:09:07 +09:00
DongHyeonkaandClaude Opus 5.5 4add908c65 docs(architecture): state that the storage sub-barrels are removed with the whole bundle (12-07)
The barrel rule and layers.md said storage/indexeddb and storage/opfs are each
removable on their own. The removal drill deletes the whole browser-file-storage
bundle together; the sub-barrels exist so the Web Storage barrel survives it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:11:59 +09:00
DongHyeonkaandClaude Opus 5.5 e070efa6b5 fix(architecture): narrow boundary exceptions and give each a reason and owner (12-07)
Every adapter group's second-level index.ts counted as a public barrel although
only storage/indexeddb and storage/opfs need one. layers.md called the
cross-context-invalidation kernel edge frozen while any adapter could use it.
Exceptions now name the exempt path, reason, owner and revisit condition.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:43:41 +09:00
DongHyeonkaandClaude Opus 5.5 7bbe48277c fix(architecture): refuse import.meta.glob in the import graph (12-06)
A glob loaded adapter modules without naming one, so the graph, ESLint and the
type check all passed it. It is now a parse failure like a non-literal import().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:40:00 +09:00
DongHyeonkaandClaude Opus 5.5 7f2a1607f3 refactor(architecture): move regex import rules into the import graph (12-10, 12-08)
Icon vendor, design-system deep import and realtime composition were regular
expressions beside graph rules, and the regex missed relative deep imports
inside presentation. They are graph rules with fixtures now, with the
components/ui facades and page-templates named. package-script-graph.ts stays;
the reason is recorded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:33:14 +09:00
DongHyeonkaandClaude Opus 5.5 f8b6a3613c fix(architecture): reject adapter re-exports through feature roots, contexts and apps (12-03)
The graph checks one edge at a time, so presentation reached a concrete adapter
through a re-export in a feature root file or a context with every rule passing.
Those modules may no longer import src/adapters, and presentation may no longer
import apps or contexts (app-router.tsx is the named exception).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:26:27 +09:00
DongHyeonkaandClaude Opus 5.5 1e93d30d1f refactor(platform): drop the .tsx re-export, move CI-only policies, derive message locales (Q-6.9-12)
- Delete src/features/reference-feature/presentation/reference-feature-runtime.tsx:
  it only re-exported the same-named .ts and nothing imported it by the
  .tsx path.
- Move promotion-readiness.ts and performance-budgets.ts from
  src/application/policies to scripts/lib: only scripts and their unit
  tests import them. Imports updated in 5 scripts and 2 tests.
  config/testing/risk-coverage.json lists only src modules, so their two
  criticalModules/highRiskPaths entries are removed; the synthetic
  14-file summary fixture now names two other existing src modules.
- installed-feature-messages.ts composes one catalog per locale the
  installed features declare (composeInstalledMessageCatalogs) instead
  of a fixed ko-KR/en-US list that silently dropped other catalogs. The
  exported type still maps each declared locale to its exact key set.

Verified: tests/unit/installed-feature-messages.test.ts (ko-KR/en-US
content pinned first; derived-locale and duplicate-key cases RED before);
app typecheck also passes with a zero-feature generated index; all gates
PASS; check:ci PASS; check-bundle resolves the moved module (stops later
on the absent artifacts/performance/bundle.json).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:58:35 +09:00
donghyeon-ka 6f6c48ebb7 refactor: 도메인이 100개 1000개씩 늘어나도 유지보수 쉬운 구조로 변경 2026-09-24 00:42:21 +09:00