0aada28b91044cac84d6ef2c9d836e0401aa5278
108
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
12f3bb7862 |
refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제 기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행 (defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고, contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게 http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가 없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을 위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석 (resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만 남기고, 레지스트리 기준선 재승인을 승인했다. 고른 방법 - src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다. 조립된 contribution의 descriptor마다 operationId, featureId, method, path, authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope, request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는 같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다. requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다. - FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다. installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고 FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다. - realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과 retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics· replayPolicy 대신). - rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립 때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다. - 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로 바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를 지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다. - create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를 만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다. - 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다 (digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음). - 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다. 버린 대안 - V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은 실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다. - 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary· unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를 쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다. 위험·한계 - BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes 의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다. 옮기는 법은 CHANGELOG에 적는다. - V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF 모드)가 사라졌다. V3 descriptor에는 그 칸이 없다. - BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2 필드를 갖지만 자체 계약이라 바꾸지 않았다. 검증 - check:types, lint, check:architecture, check:registries(11 registries PASS, compatibility=none), check:ci, check:diagnostics, check:adapter-inventory, verify:documentation 통과. - test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함), test:integration 114, test:component 245, test:contract 23, test:runtime-schema 56, tests/features 99 통과. - tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두 번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다. - check:bundle 통과. 초기 JS 201,598 → 200,911 B. - test:feature-scaffold 16개, test:sample-removal 23개 검사 통과. BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다. defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations, validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS, createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles, validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile, loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은 operation을 contract contribution에만 적고, schemas 행을 feature-runtime에 넘긴다. |
||
|
|
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으로 실행한다.
|
||
|
|
7db32e1343 |
fix(http): V3 실행기가 짝 백엔드 Envelope를 operation 단위로 읽는다
문제
create:feature가 만든 기능과 참조 기능이 쓰는 V3 실행기
(http-execution-v3.ts, feature-http-binding.ts)는 성공 본문을 DTO로,
실패 본문을 problem details(최상위 code)로 바로 검증한다. 짝 백엔드는
모든 JSON 응답을 Envelope {success, data|error, meta}로 보내고 null 필드는
키째 뺀다(백엔드 docs/web/http-contract.md 1절). 그래서 생성한 기능은 짝
백엔드의 성공을 SCHEMA_MISMATCH로, 실패를 PROBLEM_SCHEMA_INVALID(쓰기는
결과 불명)로 읽는다. 백엔드 맞추기(969979d~64e98ee)는 V2 클라이언트에만
들어갔다.
고른 방법: (가) V3 실행기에 operation 단위 Envelope 읽기
- V3 descriptor에 선택 필드 responseEnvelope("NONE" | "ENVELOPE_V1")를
둔다. 조립은 이 키를 허용하고 모르는 값을 거부한다. 값이 없으면 지금과
같다.
- ENVELOPE_V1이면 실행기가 바이트 상한·구조 예산을 Envelope 전체에 건 뒤
프레임을 확인한다. outputValidator는 data(키가 없으면 null),
problemValidator는 error를 받는다. 성공 status에 Envelope가 아닌 본문은
새 위반 ENVELOPE_MISMATCH다. 실패 Envelope의 바이트 상한은
min(64 KiB, responseByteLimit)이다.
- V2 client.ts의 멱등성 거절 표·필드 검증 판정·gateway status 규칙을
backend-envelope.ts로 옮기고 V2, V3 실행기, feature binding이 함께
읽는다. 실행기는 그 표의 판정(422·400 거절, 필드 목록 400은 적용 안 됨,
409 IDEMPOTENT_IN_FLIGHT·503 IDEMPOTENCY_UNAVAILABLE은 결과 불명)을
classifyProblem보다 먼저 쓴다. binding은 mapProblem이 답하지 않으면 V2와
같은 kind·code·validationIssues로 읽는다. V2 출력은 바뀌지 않았다.
- create:feature 뼈대: contribution이 ENVELOPE_V1을 선언하고 problem
스키마가 Envelope error(code 필수)다. 백엔드 본문을 그대로 적은
<base>-http-gateway.test.ts를 생성한다.
- MSW createHttpScenarioHandler는 descriptor가 ENVELOPE_V1이면 Envelope로
답한다.
버린 대안
- provider 단위(실행기 전체): V3 실행기는 baseUrl 하나라 앱 전체가 바뀐다.
참조 기능·테스트 계약의 problem details fixture가 모두 깨지고 한 앱이 두
모양의 API를 쓸 수 없다.
- (나) 백엔드 problem+json·DTO 모드: 백엔드 소유자 결정 2(JSON은 모두
Envelope)와 반대이고 백엔드가 두 모양을 계속 유지해야 한다.
- (다) 기능 스키마가 Envelope를 감쌈: 기능마다 null 생략·success 판별·
멱등성 판정을 다시 쓰고, V2 행(data 스키마)과 V3 스키마 ID가 갈라진다.
위험·한계
- HttpContractViolationKind에 ENVELOPE_MISMATCH가 더해졌다. default 없는
exhaustive switch는 분기를 더해야 한다.
- 실행기가 ENVELOPE_V1 operation의 위 판정을 classifyProblem보다 먼저
정한다. 패키지가 409 IDEMPOTENT_IN_FLIGHT를 적용 안 됨이라 해도 결과
불명이다.
- V2와 남은 차이: 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸
KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 같다). 구조
예산은 V3에만 있다.
- 참조 기능은 그대로 DTO·problem details다. tests/e2e/accessibility.spec.ts는
모든 API에 []로 답하므로 생성한 기능 라우트는 오류 화면이 검사된다(e2e는
돌리지 않았다).
- 초기 JS 202,770 → 203,321 B(+551 B, 예산 204,800 B).
검증
- RED: tests/integration/http-execution-v3-envelope.test.ts 19건 중 17건
실패(성공 → SCHEMA_MISMATCH, 실패 → PROBLEM_SCHEMA_INVALID·MAYBE_APPLIED,
조립 → unexpected key: responseEnvelope). 크기 2건은 처음부터 통과(동작
고정).
- GREEN: 같은 파일 25건 통과. 같은 응답을 V2와 V3에 보내 kind·code·
httpStatus·effect·retryAfterMs·validationIssues가 같음을 7가지 응답으로
비교한다.
- check:types, lint, check:architecture, check:adapter-inventory,
check:registries, check:diagnostics, check:i18n, check:ci 통과.
test:unit 2,604, test:component 244, test:integration 200 통과.
tests/features·tests/contract 124건 통과.
test:feature-scaffold 16개 검사 통과(생성한 gateway 테스트 5건,
Envelope로 답하는 목록 화면 테스트 3건 포함).
test:sample-removal 23개 검사 통과.
check:bundle 통과(203,321 / 204,800 B).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
|
||
|
|
b26517e6f2 |
fix(docs): 설계 주석에 문서 이름을 붙이고 지운 뒤 끊기는 링크를 없앤다 (1101/14-01)
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N" 처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4). 가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에 있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지 못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다: docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로, docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와 docs/superpowers/plans의 계획으로. 고른 방법: - 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞 커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절 번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다. - tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 + "§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에 .dependency-cruiser.json을 넣는다. - README "Files you can delete after copying"에서 INVENTORY.md 한 파일 대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과 ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다. INVENTORY의 행 구조는 바꾸지 않는다. - 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은 링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다. 버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도 상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기 목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시 다른 이력을 가리키면 남길 목록이 계속 커진다. 위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는 주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다. src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼 이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미 docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의 이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다. check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던 실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가 바뀐다. 검증: - RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed). - GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를 src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림. - 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0). - 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크 148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계 참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서 verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트 2 passed. - node scripts/verify-documentation-readiness.ts: PASS_SCOPED - node scripts/check-adapter-inventory.ts: PASS - node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts: 50 passed. tests/architecture: 39 passed. - npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과. .dependency-cruiser.json JSON 파싱 통과. - 미실행: check:architecture(pnpm 필요). |
||
|
|
d166aa39a7 |
feat(features): 기능 뼈대를 만드는 create:feature 명령과 드릴을 더한다 (U7)
문제
- 새 기능은 참조 기능을 복사해 이름을 바꾸는 방법뿐이다. 리뷰 16 실험 E
에서 이 방법은 12번 막혔다. 접두어 없는 전역 ID(NoRequest, qinv topic,
navigationOrder)는 치환으로 바뀌지 않고, 토큰 경계 없는 치환은
preference·supportReference를 깨뜨린다. 제품이 참조 기능을 지우면 복사할
원본도 없다.
고른 방법 (결정 D1·D2, 오케스트레이터 결정 2·4)
- scripts/create-feature.ts: pnpm create:feature <id> [--context <ctx>]
[--package @scope/name@x.y.z --digest sha256:… --revision <hex>].
템플릿을 이 파일 안에 두고 참조 기능을 import하지 않는다(D1).
- 뼈대: 파라미터 없는 목록 라우트 1, GET 1(SAFE, EXTERNAL_BEARER),
쿼리 1, topic 1, CollectionPage 1, ko-KR·en-US 문구. domain/ 없음.
검증은 공유 zodValidator, 링크는 route ID와 buildRouteUrl
(<base>-routes.ts). 빈 배열 응답은 공유 빈 상태로 그린다.
- 전역 ID는 모두 기능 접두어를 단다(D2): 스키마·mapper·operation·
contribution·policy·diagnostics·chunk·route·namespace·definitionId·
문구 키·telemetry kind·owner. topic은 qinv. + 무작위 26자(Crockford
base32)이고 설치된 topic과 겹치면 거부한다. navigationOrder는 설치된
최댓값 + 10.
- 패키지 인자가 없으면 결정 2의 자리표시자 상수를 import해 쓰고 경고를
출력한다. 인자가 있으면 external-contract-runtime의 신원 검사
(composeContractContributions)로 형식을 확인한다.
- 거부: kebab이 아닌 id, 기존 기능·context id(디렉터리 이름 포함),
같은 접두어를 쓰는 기존 기능, 이미 있는 <base>-context(--context 안내),
같은 라우트 루트·route ID·경로·chunk·문구 키.
- 폴더 밖은 새 context 선언과 pending a11y 기록만 쓴다. 기존 파일은
덮어쓰지 않고(wx), 쓰기나 직후 생성기 실행이 실패하면 만든 것을 지운다.
- 출력: 만든 파일, a11y 서명(FE-GATE-028), 돌릴 게이트 목록, 기준선
재승인이 필요 없다는 안내, 자리표시자 교체 방법.
- 테스트: tests/unit/create-feature.test.ts(렌더 결과만: 접두어, 샘플
토큰 없음, topic 형식·중복, 순서, 거부, 덮어쓰기·되돌리기).
생성된 기능의 테스트는 input 단위 테스트와 런타임 조립·라우터를 거치는
페이지 테스트다. MSW는 createHttpScenarioHandler(설치 계약)를 쓴다.
- 느린 드릴 test:feature-scaffold: removal-fixture로 만든 복사본(README·
CHANGELOG·docs 포함)에 기능을 만들고 커밋한 뒤 types, lint,
architecture, registries, i18n, design-system, diagnostics,
documentation, unit, component, integration, features, coverage,
check:ci, build를 돌린다. FE-GATE-020에 넣고 gates.json, 계약 기준선,
ci-workflow-generation 테스트의 개수를 맞췄다(workflow는 그대로).
- 결정 4: test:sample-removal이 기능 0개 검사 뒤 같은 복사본에서
create:feature로 기능을 만들고 같은 게이트를 scaffold- 이름으로 다시
돌린다.
- tests/release 고정 manifest가 계약 집합을 빈 배열로 고정해, EXTERNAL_
PACKAGE를 쓰는 첫 기능에서 7건이 release-mismatch로 깨졌다. 16-02가
tests/runtime-schema에 한 것처럼 설치된 집합에서 만든다.
- 버린 대안: 참조 기능 복사+토큰 치환(D1에 어긋나고 전역 ID를 놓친다),
topic을 뼈대에서 빼기(실제 기능이 같은 문제를 다시 만난다), 생성
테스트가 tests/mocks의 bootstrap·server를 쓰기(부팅 문서는 테스트 안의
fetcher가 주고, MSW는 setupServer와 http-scenarios만 쓴다).
위험·한계
- 생성기 파일이 1,408줄이다. 대부분 템플릿 문자열이다.
- context-module.ts는 생성기가 글로 읽는 선언이라 실행되지 않는다(참조
context와 같다). 나머지 생성 모듈은 생성된 테스트가 모두 실행한다
(함수 100%, 문장 100%, 페이지 분기 1개 미실행).
- --context reference-context로 참조 context에 넣으면 참조 기능의
installed-context-routing 테스트(라우트 4개 정확히 일치)가 깨진다.
드릴은 새 context를 쓴다.
- test:feature-scaffold, test:sample-removal, check:architecture는
pnpm이 필요해 worktree에서 돌리지 않았다.
- tests/unit/feature-shape-growth.test.ts는 기준 커밋에서도 1 KiB를 넘어
실패한다(이번 측정 1035·1068). 기능이 하나 더 있으면 통과한다.
검증
- RED: 생성한 기능을 넣고 돌리면 tests/release 7건 실패("expected
{ state: 'release-mismatch' } to match { state: 'booted' }"),
ci-workflow-generation 1건 실패(98 vs 99). 접두어 테스트는 템플릿의
스키마 ID를 "NoRequest"로 바꾼 변이에서 실패한다.
- GREEN(worktree에 order-feature 생성): tsc app·test·node rc=0, 전체
eslint rc=0, check-registries "11 registries PASS; compatibility=
additive"(기준선 재승인 없음), verify-documentation-readiness
PASS_SCOPED, check-i18n PASS, check-design-system·check-diagnostics·
check-adapter-inventory PASS, check-ci-contract·workflow·artifact
schema PASS, 생성 테스트 7/7, run-vitest tests/unit·component·features
238파일 통과, integration·contract·runtime-schema·platform·architecture·
release·scripts 59파일 통과(pnpm을 띄우는 2파일 제외).
- --context reference-context와 --package 변형도 tsc·registries·생성
테스트 통과. 참조 기능을 지운 복사본에서 생성 → tsc app·test, i18n,
생성 테스트·release·router 테스트 통과(결정 4 모의).
- 생성물을 지운 뒤 같은 검사 통과(feature-shape-growth 기존 실패 1건
제외), git status 깨끗.
|
||
|
|
1269992b1a |
fix(release): 공개 대상 승인이 자리표시자 계약 신원을 거절한다 (U7 결정 2)
문제 - 기능 생성 명령(U7)은 계약 패키지 인자가 없으면 자리표시자 신원으로 기능을 만든다. 이 신원은 형식 검사(external-contract-runtime.ts의 패키지 신원 검사)를 모두 통과한다. 계약 집합 검사도 같은 목록을 자기 자신과 비교한다. 그래서 자리표시자를 그대로 둔 빌드가 staging· production 승인까지 통과한다. 고른 방법 (오케스트레이터 결정 2) - 자리표시자를 src/contracts/deployment-admission.ts에 상수로 둔다. digest는 sha256: 뒤에 0 64개, version 0.0.0, revision 0000000이다. 생성 명령이 이 상수를 import해 쓰므로 코드에서 자리표시자임이 보인다. - findAdmissionViolations에 세 번째 인자로 빌드가 컴파일한 계약 패키지 목록을 받는다. 대상이 PUBLIC(staging, production)이면 digest가 자리표시자인 패키지마다 contractPackages.<packageId> 위반을 낸다. BUILD_ID·RELEASE_ID의 PLACEHOLDER_IDENTIFIERS 검사와 같은 꼴이다. - check-release-admission.ts는 EXPECTED_CONTRACT_SET_PACKAGES를 넘긴다. 이미 COMPILED_PRODUCT_FEATURE_IDS를 같은 방식으로 읽는다. - 배포된 config.json의 수정본 검사(--config, 1101/13-05)는 패키지를 보지 않는다. 수정본은 비상 스위치만 바꿀 수 있고, 패키지는 빌드 필드라 빌드 승인 때 이미 검사했다. - APP_PROFILE 테스트의 production 행은 컴파일된 계약 집합에 자리표시자가 있으면 거절(그 이유로만)을, 없으면 승인을 기대한다. 생성 명령으로 기능을 하나 만들면 저장소 자체 빌드가 production 승인을 받지 못하는 것이 의도한 동작이기 때문이다. - 버린 대안: 계약 형식 검사에서 거절하기. 그러면 생성한 기능이 로컬에서 부팅·테스트되지 않는다. dist/release-manifest.json을 읽어 비교하기. 릴리스 일관성 검사가 이미 manifest와 컴파일된 목록이 같은지 보므로 같은 값을 한 번 더 읽고, 이 스크립트를 실행하는 테스트마다 manifest를 써야 한다. 위험·한계 - digest만 본다. version이나 revision만 자리표시자이고 digest는 진짜인 신원은 거절하지 않는다. 결정이 digest 하나를 자리표시자로 정했다. - local·development 대상은 거절하지 않는다. 의도한 동작이다. - 새 코드는 앱 번들에 들어가지 않는다(빌드 후 dist에서 거절 문구와 상수 이름 grep 0건). 앱은 이 모듈에서 isLoopbackHostname만 쓴다. 검증 - RED: 상수만 넣고 거절 전 코드로 새 테스트를 돌리면 실패한다. "staging: expected [] to deeply equal [ Array(1) ]" - RED(수정본·APP_PROFILE): 생성 명령으로 기능 하나를 만든 상태에서 두 테스트가 "contractPackages.@org-contracts/order: pins the placeholder identity ..."로 실패했다. - GREEN: tests/unit/deployment-admission.test.ts 25/25, feature-override-diagnostics.test.ts(스크립트 실행) 통과. 생성한 기능이 있을 때와 없을 때 모두 통과. 생성한 기능이 있을 때 production 대상 스크립트 실행은 rc=1과 위 위반 한 줄을 낸다. - npx tsc app·node·test rc=0, 바꾼 3파일 eslint rc=0. |
||
|
|
3ea7c37ed0 |
fix(registry): 적재에 실패한 레지스트리 source는 그 오류를 함께 적는다
문제: check-registries는 레지스트리 source 모듈의 import 오류를 삼키고 "missing registry source <path>"만 남겼다. 파일은 있는데 그 안의 import가 깨진 경우에도 파일이 없는 것처럼 보였다. 6ea9e4a의 원인(옮긴 export를 예전 경로에서 가져온 fixture)도 이 메시지만으로는 찾을 수 없어 임시 출력을 넣어 찾았다. 방법: source 경로가 있는데 적재가 실패하면 오류 메시지 첫 줄을 실패 문장 뒤에 붙인다. 파일이 없을 때의 문장은 그대로다(release-artifacts·json-schema 테스트가 그 문장을 쓴다). 스택 전체를 붙이는 방법은 버렸다. 산출물 JSON의 failures가 커지고 경로가 실행 환경마다 달라진다. 위험: 다운스트림이 이 실패 문장을 정확히 비교하면 달라진다. 파일이 없는 경우의 문장은 바뀌지 않았다. 검증: tests/unit/registry-governance.test.ts에 "있지만 import가 깨진 source" 테스트를 더했다. 수정 전 실패(1 failed), 수정 뒤 10건 통과. check-registries PASS, eslint, tsc(node) 통과. |
||
|
|
ca161878f2 |
feat(routes): 기능이 홈을 대신하고 context가 자기 레이아웃을 선언한다 (1101/09-03)
문제: 라우터는 모든 context gateway를 `AppShell` 하나 아래에 붙이고 플랫폼
`/`를 index로 둔다. 기능이 `APP_HOME`을 선언하면 `composeUniqueRecord`가
throw한다. 그래서 제품 홈이 기능 화면이거나 화면이 `AppShell`이 아닌 자기
셸을 쓰면 제품이 템플릿 라우터와 조립 카탈로그를 고쳐야 한다. memento는
카탈로그 브리지(`APP_HOME` 허용 목록)와 라우터 브리지(`ownsShell`)를 넣고
동기화마다 병합한다. tech-log는 라우터를 PUBLIC/STUDIO 그룹 라우터로 통째로
바꿔 생성기 설치 경로(context gateway)를 쓰지 못한다.
고른 방법: 리뷰 4.3의 (B). 선언 두 개를 연다.
- 홈 대체: 플랫폼이 기능이 대신할 수 있는 라우트 id를 선언한다
(`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS = ["APP_HOME"]`,
src/contracts/routes.ts). 그 id를 선언한 기능의 정의가 플랫폼 정의를
대신한다. 둘이 선언하면 카탈로그를 읽을 때 두 기능 id를 담아 throw한다
(`withoutTakenOverPlatformRoutes`). 다른 플랫폼 id는 지금처럼 중복 오류다.
라우터는 대체된 라우트를 소유 context와 함께 그 경로에 붙인다.
- context 레이아웃: `BoundedContextRouteModule.loadLayout`(선택). 생성기는
`src/contexts/<context>/context-layout.tsx`가 있으면 그 `CONTEXT_LAYOUT`을
지연 import로 싣는다. 라우터는 그 context를 `AppShell` 형제인 `/` 레이아웃
라우트 아래, 기능의 등록 경로마다 붙인다. 그래서 모르는 URL은 여전히
`AppShell`의 NOT_FOUND로 간다. 선언이 없으면 지금처럼 `AppShell` 아래 루트에
붙는다. 레이아웃 청크 실패는 라우트 청크와 같은 reload-once 복구를 받는다.
- 09-06 불변식을 레이아웃으로 넓힌다. 레이아웃 라우트는 모두 `/`의
형제라서 루트는 레이아웃과 상관없이 그 아래 URL을 가진다. 그래서 기존
루트 검사가 모든 레이아웃에 걸친다. 한 레이아웃 아래 루트 여럿(같은
컴포넌트를 싣는 context들)은 허용한다. 대체된 플랫폼 라우트는 라우터가
경로에 직접 붙이므로 루트 검사에서 뺀다(09-06 재검토 조건).
- tests/unit/product-features.test.ts의 "플랫폼 라우트는 소유자가 없다"
검사가 대체 가능한 id는 건너뛴다. memento가 고쳤던 템플릿 테스트다.
- `ContextRouteModule`에 `featureIds`가 생겨서, `TEMPLATE_APP_MODULE`을
손으로 mock하며 필수 필드 `features`를 빼먹은 두 테스트
(context-route-gateway, context-boundary-diagnostics)에 `features: []`를
넣었다.
버린 대안:
- (A) 현 상태: 제품마다 브리지를 넣고 동기화마다 병합한다.
- (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 tech-log를 담지 못한다.
- 같은 레이아웃을 쓰는 context를 로더 함수로 묶어 레이아웃 라우트 하나에
모으기: 만들었다가 지웠다. React 19는 같은 컴포넌트로 풀린 lazy 타입을 같은
타입으로 맞춰 레이아웃 인스턴스를 그대로 둔다. 묶지 않은 변이로 테스트가
그대로 통과해서 쓸모없는 코드였다.
- `CONTEXT_LAYOUT_ID` 리터럴로 다른 context의 레이아웃을 가리키기: 같은
컴포넌트를 내보내는 파일 두 개로 같은 결과가 나와 선언을 하나 덜 둔다.
- 레이아웃 라우트를 `AppShell`보다 앞에 두기(memento 브리지 순서): 경로가
같으면 기능이 플랫폼 라우트를 조용히 가린다. `AppShell`을 앞에 두어
지금처럼 플랫폼이 이긴다.
위험·한계:
- 레이아웃이 skip link와 `<main id="main-content">` 하나를 그리는 것은
계약(타입 주석, starter-experience.md)과 테스트 fixture로만 지킨다. 실행 중
검사는 없다. 레이아웃 로딩·실패 화면에는 `<main>`이 없다(`AppShell`의
errorElement와 같다).
- 레이아웃 렌더 결함(청크 실패가 아닌 것)은 라우트 errorElement로 가고
진단을 남기지 않는다. `AppShell` 렌더 결함과 같다.
- 홈을 대신한 기능을 실행 중에 끄면 `/`는 비활성 기능 화면이 된다. 빌드에서
빼면(`VITE_PRODUCT_FEATURES`) 플랫폼 홈이 돌아온다.
- tech-log의 PUBLIC 셸 안 NOT_FOUND는 표현하지 않는다. 모르는 URL은
`AppShell`의 NOT_FOUND다. STUDIO의 `/studio/*` 라우트는 STUDIO 레이아웃
아래에서 동작한다. tech-log는 기능 하나를 레이아웃 그룹별 기능 둘(context
둘)로 나눠야 한다.
- 플랫폼 라우트와 기능 라우트의 같은 경로는 여전히 검사하지 않는다(
|
||
|
|
605fd17d9f |
fix(registry): 무효화 그래프에 더하기만 한 변경을 additive로 분류한다 (0929/07-02)
문제 FE-REG-QUERY-INVALIDATION은 무효화 그래프를 행 하나(invalidation-graph)로 투영하고 topics·namespaces·edges를 breakingFields로 둔다. 분류기는 배열에서 빠진 원소가 없으면 field-changed로 보고 breakingFields로 등급을 정한다. 그래서 topic 하나, namespace 하나, edge 하나를 더하기만 해도 breaking 3건이 되고 기준선 재승인이나 breaking 증거가 필요하다. 서버 상태를 쓰는 기능은 모두 topic을 달기 때문에 기능을 하나 추가할 때마다 사람이 재승인해야 한다(1101 리뷰 16 영역 2.1절: P-07-02가 남았고 범위가 더 넓다). 고른 방법 (오케스트레이터 결정 1) - governance의 snapshotProjection.canonicalArrayKeyFields에 있는 필드는 키로 식별되는 원소 집합이다. 이 필드에서 원소가 빠지지 않았으면 set-items-added(additive)로 분류한다. 다른 레지스트리의 "행 추가"와 같은 성격이다. 이전 집합의 원소를 읽던 소비자는 모두 그대로 찾는다. 무효화가 늘어날 뿐이다. - 원소를 빼거나 바꾸면 지금처럼 allowed-value-removed(breaking)다. 이 분기는 새 분기보다 먼저 판정된다. - 0929/07-02( |
||
|
|
5d064b8ace |
test(features): 기능을 더해도 기능 밖 테스트와 시나리오 하네스가 깨지지 않게 한다 (16-02)
문제: 기능 하나를 더하면(리뷰 16 실험 E) 기능 밖 테스트 3개가 깨진다.
① installed-context-routing은 context 목록이 정확히
["reference-context"]이고 첫 context가 참조 context라고 단정한다.
② product-feature-switch는 정렬 첫 기능(INSTALLED_PRODUCT_FEATURE_IDS[0])을
끄고 참조 라우트를 본다. 새 기능이 앞에 정렬되면 깨진다.
③ release-manifest fixture가 contractSet.packages: []로 고정이다.
EXTERNAL_PACKAGE를 쓰는 첫 기능에서 반드시 깨진다.
또 시나리오 하네스의 operation ID 타입이 테스트 계약 3개 리터럴이고
시나리오 응답 함수가 /api/test-entities 핸들러 안에 묶여 있다. 새 기능
테스트가 자기 operation에 실패 시나리오를 쓰려면 카탈로그를 고쳐야 한다
(안 고치면 TS2345, 실행하면 catalog.ts:469 TypeError).
방법: 리뷰의 (b) 최소 개선.
① "목록에 reference-context가 있다"로 바꾸고, 라우트 검사는 id로 찾은
context에서 한다.
② REFERENCE_FEATURE_ID를 쓴다.
③ fixture의 packages와 setDigest를 EXPECTED_CONTRACT_SET_PACKAGES에서
만든다.
하네스: HttpScenarioOperationId를 string으로 넓혔다. 시나리오 사실(명령
여부, 응답 상한, 성공 status)은 httpScenarioOperationFacts가 설치된 V3
descriptor에서 읽는다. 시나리오 응답은 tests/mocks/handlers/
http-scenarios.ts의 createHttpScenarioHandler로 옮겼다. 경로와 method도
descriptor에서 만든다. test-entities 핸들러는 이 함수를 쓰고 카탈로그
확인(assertOperationScenario)을 그대로 거친다. 카탈로그 기대값 57개는
계속 테스트 계약 3개에만 있고, 그 타입도 3개로 둔다. 카탈로그에 없는
operation을 assertOperationScenario에 넘기면 TypeError 대신 그 사실을
말하는 오류가 난다. test-entities 핸들러는 요청의 이름·id를 되돌려 주던
응답을 카탈로그 payload로 고정했다(기대값과 같은 값이다).
새 기능 테스트의 MSW 시나리오: server.use(createHttpScenarioHandler(
<자기 설치 계약>, { scenario: "server-terminal-503", payload }))
버린 대안: (a) 현상 유지는 기능마다 4곳을 고친다. (c) 하네스를 기능별로
나누면 변경이 크고 test-evidence.json의 증거 경로가 바뀐다. 기능
operation을 카탈로그에 더하는 방식은 기능 추가를 공유 파일 수정으로
만든다.
test-evidence.json은 바꾸지 않았다(sourceContracts 토큰이 test-entities.ts에
그대로 있다). 제거 드릴의 플랫폼 보존 목록에 http-scenarios.ts를 더했고,
테스트 전략 문서 11절에 사용법을 적었다.
위험·한계:
- 앱 전체를 렌더하는 테스트에서 response-too-large는 끝나지 않는다.
실행기가 MSW가 넘긴 본문을 cancel하는 promise가 끝나지 않는 기존
제약이다. 카탈로그 통합 테스트는 프록시 fetcher로 우회한다.
- 같은 실험에서 기능 밖 테스트가 더 깨진다. 이 발견 범위 밖이라 두었다.
http-operation-v2-v3-parity는 스키마 ID "NoRequest"를 센티널로 고정한다.
스키마 ID는 전역이라 두 번째 기능은 다른 이름을 써야 하고, 그러면 이
테스트가 깨진다. manual-a11y-evidence·documentation-readiness(라우트별
a11y 기록, 16-01)와 second-api-feature-registries(무효화 그래프 추가가
breaking, 16-01)도 깨진다.
- test:sample-removal, test:http-scenario-evidence는 pnpm이 필요해 돌리지
않았다.
검증:
RED: 참조 기능을 토큰 경계로 order로 바꾼 복사본(order-context,
EXTERNAL_PACKAGE 출처 포함, 커밋 안 함)을 넣고 tests/features
tests/component tests/runtime-schema를 돌렸다. 5파일 8개 실패. 기능 밖은
① 2개(["order-context","reference-context"]), ② 2개(order-feature를 꺼서
참조 링크가 남음), ③ 1개(ReleaseManifestError)다. 나머지 3개는 복사한
테스트다. 하네스 probe는 TS2345 2건, 실행 시 TypeError(catalog.ts:469).
새 통합 테스트는 기준 하네스에서 모듈 없음으로 실패하고, 기준
assertOperationScenario는 미등록 operation에 TypeError를 낸다.
GREEN: 같은 복사본으로 같은 폴더와 카탈로그 통합 테스트를 돌렸다. 78파일
중 실패는 출처를 바꾼 복사본 provenance 1파일뿐이고 ①~③은 통과한다.
order 테스트가 createHttpScenarioHandler(LIST_ORDER_RESOURCES_CONTRACT)로
content-type-mismatch·schema-mismatch·server-terminal-503을 화면에서
확인했다(카탈로그 수정 없음).
복사본을 지운 뒤: tests/features·component·runtime-schema·unit·
integration(security-followup-archive 제외)·contract 250파일 3111개 통과,
카탈로그 57/57, check-test-evidence --scenario-only·--source-only PASS,
tsc app·test·node 통과, verify-documentation-readiness PASS_SCOPED,
check-ci-contract PASS, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-02
|
||
|
|
b4ccadab77 |
feat(design-system): 제품이 싣는 글꼴을 토큰 계약에 선언하게 한다 (1101/12-04)
문제 첫 글꼴 규칙(check:design-system)은 --font-sans의 첫 글꼴이 일반 키워드이거나 검사하는 CSS 안의 @font-face로 실릴 때만 통과시킨다. 글꼴 패키지 import, @import url(…), index.html의 <link>로 싣는 글꼴은 볼 수 없어 실패한다. memento 토큰이 이미 이 규칙에 걸린다. 선언할 곳이 없으니 제품은 템플릿 소유 스크립트를 고치게 된다. 고른 방법 - token-contract.ts에 PRODUCT_LOADED_FONT_FAMILIES(템플릿은 빈 목록)를 둔다. 제품은 토큰 계약 파일에서 자기가 싣는 글꼴 이름을 적는다. - firstFontFamilyFailures가 세 번째 인자로 이 목록을 받아 @font-face로 실은 글꼴과 같이 허용한다. check-design-system.ts가 목록을 넘긴다. - 실패 메시지에 목록 이름을 넣어 어디에 선언하는지 알린다. - docs/styling/design-system-platform.md 4.1절 표의 첫 글꼴 행을 고친다. - 12-04의 (1)~(3)과 (5)는 e714c0d가 했다(deg·음수 색상각, 지원 형식을 적는 포커스 메시지, -apple-system·BlinkMacSystemFont, 규칙 문서). 이 커밋은 (4)만 한다. 버린 대안 - 패키지 import·<link>를 찾아 실제로 싣는지 판정: 진입점·CDN·번들러 설정까지 봐야 해서 규칙이 커진다. - 목록을 design-system/index.ts로도 내보내기: 앱 코드가 쓰지 않는다. 위험·한계 - 검사는 목록을 믿는다. 글꼴이 실제로 실리는지 보지 않는다. 주석과 문서에 "모든 화면이 싣는 글꼴만 적는다"고 적었다. - 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 tests/unit/design-system-rules.test.ts뿐이다. - 새 공개 이름 PRODUCT_LOADED_FONT_FAMILIES가 생긴다. 검증 - RED: 새 테스트 "passes a family the product declares it loads, and only that one"이 실패(expected [ Array(1) ] to deeply equal []). - GREEN: design-system-rules·oklch-contrast·design-system-contract 22/22 통과. - 실제 스크립트 probe: CSS 사본의 --font-sans를 "Pretendard Variable"로 시작하게 하고 node scripts/check-design-system.ts → 빈 목록이면 새 메시지로 실패(exit 1), 목록에 넣으면 PASS(exit 0). 저장소 CSS는 PASS. - tsc(app·node·test), 바꾼 파일 eslint, verify-documentation-readiness PASS_SCOPED. Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04 |
||
|
|
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
|
||
|
|
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 통과. |
||
|
|
16202fd48d |
fix(docs): 현재 계약 문서의 경로·명령·게이트 ID를 검사한다 (14-05)
문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고
소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조,
그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다.
diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다.
README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다.
design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과
check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가
어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를
설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를
모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를
고쳐야 한다(다운스트림 동기화 충돌 지점).
고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3.
- route ID 나열을 지운다. verify:documentation은 설치된 라우트마다
artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route
ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치
(ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로
starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을
가리키게 바꾼다.
- docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다.
문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는
작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo
기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서
읽는다), README "Files you can delete after copying"의 이력 중 지워진
것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한
FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를
적는 문서라 뺀다.
- compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에
3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트
경로를 현재 위치로 고치고 그 사실을 머리에 적는다.
- diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고
ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다.
- documentation-review.json에 documentReferences를 더한다. routeScope는
모양을 유지하고 기록 폴더 한 항목으로 쓴다.
버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를
고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어
주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 —
artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git
check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다.
위험·한계:
- 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운
링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든
경로, 심볼 이름이 맞는지는 보지 않는다.
- script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로
시작하는 "`접두:이름`"만 본다.
- 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재
계약 문서(README, compatibility.md, starter-experience.md,
manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운
복사본은 그대로 통과한다.
- 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도
본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다.
- CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다.
검증:
- RED: 새 테스트를 기준(
|
||
|
|
de379ea78d |
ci(release): FE-GATE-019가 승격 후보를 배포된 release와 대조한다 (1101/13-01)
문제
production_gate는 promotion 직후 같은 run에서 시작하고 그 사이에 배포 job이
없다. CI 계약이 job 9개·그래프·env를 정확히 고정해 배포 job을 넣을 자리도
없다. live probe는 헤더만 보고 배포된 release가 승격 후보인지 확인하지
않는다. FE-GATE-019의 명령은 [build, verify-hosting-headers]라서 local
프로필로 다시 빌드한 dist를 검사한다. 그래서 FE-GATE-019 PASS는 "지금 떠
있는 release(대개 이전 것)의 헤더가 맞다"는 거짓 PASS다.
고른 방법 (리뷰 대안 (c), (1)~(3))
(1) live probe가 배포된 release-manifest.json의 buildId·releaseId를 후보와
비교한다. 다르거나 읽을 수 없으면 FAIL(releaseManifest build-id·
release-id). 후보는 검사하는 dist의 release-manifest.json이다.
(2) FE-GATE-019에서 build를 뺀다. verify-hosting-headers가
`--release-root .release/promoted-release`를 받아 후보 dist를 본다.
계약의 13-03 규칙(drill만 --release-root 필수)을 production_gate의 모든
게이트 명령으로 넓혔다. 플래그 없이 돌리면 local dist를 본다.
(3) promotion과 production_gate 사이에 `deployment` job(kind deployment)을
선언한다. 기본은 빈 슬롯이다: deploy 단계 하나가 deployed=false를 job
output으로 낸다. production_gate는 RELEASE_DEPLOYED로 받고, 비어 있으면
FE-GATE-019가 호스트를 probe하지 않고 UNVERIFIED(exit 3)로 끝난다.
프로젝트는 gates.json의 deployment job을 채운다. 계약이 허용하는 것:
checkout·setup-node·frozen-install·download·extract와 마지막 deploy 하나
(`script`는 package 스크립트, 존재·스크립트 그래프 검사를 gate 명령과
같이 받는다). env는 immutable_build의 CANDIDATE_ARCHIVE_SHA256과
vars.*·secrets.*만. 게이트를 소유하지 않아 채워도 계약 기준선이 안
바뀐다.
- ci-contract 보고서 jobCount 9→10, 계약 기준선 commandReferences
103→102(update-ci-contract-baseline, owner frontend-platform).
- verify-hosting-headers가 live가 아닌 모드에서 baseUrl을 null로 적는다.
스키마가 live에만 baseUrl을 허용해서, 비어 있는 슬롯과 기존 invalid-live
(예: http:// URL)는 산출물 쓰기에서 ZodError로 죽었다. 이제 기록을 남기고
각각 UNVERIFIED·FAIL로 끝난다.
버린 대안
- (b) (1)(2)만: 거짓 PASS는 사라지지만 배포 자리가 없어 운영 단계가 항상
FAIL이 된다.
- (d) production_gate를 별도 workflow로 분리: Gitea에서 run 사이 artifact
전달이 검증되지 않았다.
- 슬롯이 비었는지를 HOSTING_BASE_URL 유무로 판단: 변수만 있고 배포가 없으면
이전 release를 probe해 FAIL이 된다. 슬롯이 직접 보고하게 했다.
위험·한계
- Gitea runner가 꺼져 있어 workflow를 실제로 돌리지 않았다. job outputs와
`$GITHUB_OUTPUT`는 immutable_build가 이미 쓰는 방식과 같다.
- 실제 HTTPS 호스트에 이전 release를 띄워 probe하지 않았다. 불일치 판정은
fetcher를 주입한 단위 테스트로만 확인했다.
- 채운 슬롯의 secrets는 그 job의 모든 단계(checkout, download action 포함)
env에 보인다. 프로젝트가 고르는 값이다.
- FE-GATE-019를 수동으로 돌리는 운영자(provider 없는 최소 구성)는 후보
archive를 .release/promoted-release에 풀어야 한다. drill과 같은 전제다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
7 failed / 19 passed(후보 인자 없음, verify가 dist ENOENT로 산출물 없음).
tests/unit/ci-workflow-generation.test.ts 8 failed / 415 passed
("expected [ 'build', 'verify:hosting-headers' ] to deeply equal ...",
"expected -1 to be 6", deployment job 없음)
- GREEN: hosting-probe 26 passed, ci-workflow-generation 423 passed
(스냅샷 1개 갱신)
- check:ci 하위 명령 직접 실행: generate-artifact-schemas --check PASS,
check-ci-contract.ts PASS, generate-ci-workflow --check PASS
- 슬롯을 채운 실험(체크아웃→다운로드→extract→deploy:release, vars·secrets
env, package 스크립트 추가) 뒤 같은 세 명령 PASS. package 스크립트를 빼면
"CI gate contract missing package scripts: deploy:release"로 실패. 실험
뒤 원복
- 관련 테스트 16파일 596 passed(ci-workflow-generation, hosting-probe,
service-worker-build-output, deployment-admission, ungated-*,
supply-chain, removal-fixture, task3-selective-integration,
documentation-readiness, tests/release, tests/platform/release)
- tsc(node, test, app) 0, eslint 바뀐 파일 0,
verify-documentation-readiness PASS_SCOPED
- 미실행: tests/system/ci-runner(pnpm 실행), check:architecture(pnpm)
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-01
|
||
|
|
6c5818faec |
refactor(contracts): bearer 인증 프로필을 EXTERNAL_BEARER로 바꾼다 (1101/16-03)
문제
유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다.
세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유
파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이
이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류
메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다.
고른 방법 (2026-11-03 결정)
- 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와
V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를
새 이름으로 옮겼다.
- 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고
JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야
하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다.
그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로
해석된다.
- scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는
"REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다.
- 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지,
src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준).
버린 대안
- 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서
바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다.
- 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이
매핑을 알아야 한다. 프로필 항목 하나가 더 작다.
위험·한계
- 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지
않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다.
그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다.
- 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가
보이지 않는다. CHANGELOG로 알린다.
- FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라
behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번
작업 묶음 끝에서 한 번에 한다.
- 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭
항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy
청크라 초기 크기에 영향이 없다.
검증
- RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected
undefined to match object { transport: 'BEARER_HEADER', …(1) }",
"expected [ …(9) ] to deeply equal [ Array(1) ]").
- GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS"
(FE-REG-API authProfileId 3건 behavior-change).
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외:
http-scenario-evidence, ci-workflow-generation, lab-performance,
fixture-node-modules, deployment-admission, security-followup-archive).
tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공.
- 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
|
||
|
|
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
|
||
|
|
4ada84e1ec |
fix(registry): 맞는 변경이 없는 breaking 증거 행을 실패로 막는다 (0929/07-01)
문제
check:registries는 증거 행이 지금 diff의 어느 breaking 변경을 설명하는지
보지 않는다. 증거 파일 17건 중 14건이 지금 diff의 어떤 changeId와도 맞지
않았다(예: FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed,
그 필드는 07-04 이후 없다). update:registry-baseline은 기준선을 새로 찍어도
증거 행을 그대로 두므로 오래된 행이 계속 쌓인다. 5e6be9a가 리뷰 개선
(1)(증거를 값에 묶기)만 했고 (2)·(3)이 남았다.
고른 방법 (2026-11-03 결정)
- (2) validateBreakingEvidence가 지금 diff의 breaking 변경과 changeId가
맞지 않는 증거 행마다 "stale breaking evidence <changeId>: ..."로
실패한다. 메시지에 지울 행과 update:registry-baseline이 지운다는 사실을
적는다. breaking이 아닌 변경(behavior-change 등)과 맞는 행도 오래된
행으로 본다. 증거는 breaking 변경에만 쓰기 때문이다.
- (3) update:registry-baseline이 승인 파일을 쓴 뒤 증거 행을 모두 지우고,
지운 changeId를 출력한다. 새 기준선은 지금 스냅샷이라 증거가 설명하던
변경을 모두 흡수한다. 남은 행은 어떤 변경과도 맞지 않아 (2)에서
실패한다. 이력 파일로 옮기지 않는다. git 이력이 이력이다.
증거 파일은 쓰기 전에 읽어서, 파일이 없으면 아무것도 바꾸지 않고 멈춘다.
- 이번 검사에 걸리는 오래된 14건을 지웠다. 지금 diff와 맞는 3건
(REFERENCE_RESOURCE_DETAIL.path, CACHE_INVALIDATION_PULSE backend·
valueCodec)은 남겼다.
- docs/operations/ci-quality-gates.md 증거 안내에 두 동작을 적었다.
이유: 목록을 출력만 하면 아무도 보지 않는다. 정리가 자동이라 실패해도
고치는 비용이 작다.
버린 대안
- 오래된 행을 목록으로 출력만 하기: 위 이유.
- 지운 행을 이력 파일로 옮기기: 파일이 하나 늘고, git 이력과 같은 사실의
사본이 된다.
위험·한계
- 다운스트림이 이 검사를 동기화하면 자기 증거 파일의 오래된 행 때문에
게이트가 실패한다. 실패 메시지가 행을 나열하므로 지우거나
update:registry-baseline을 한 번 돌리면 된다. CHANGELOG [계약] 행이
필요하다.
- 같은 changeId가 증거 파일에 두 번 있으면 지금처럼 뒤의 행만 쓰고,
앞의 행은 오래된 행으로 걸리지 않는다. 이번 범위 밖이다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 "fails on evidence
rows that explain no breaking change of the current diff"가
"expected [] to deeply equal [ …(2) ]"로 실패. registry-governance.test.ts
새 사례 "deletes the evidence rows the new baseline explains"가
"expected { schemaVersion: 1, changes: [ …(1) ] } to deeply equal
{ schemaVersion: 1, changes: [] }"로 실패.
- GREEN: 두 파일 25/25 통과. 오래된 행을 지우기 전 check-registries가
"stale breaking evidence ..." 14줄로 실패(rc=1), 지운 뒤 "11 registries
PASS"(rc=0).
- 회귀: registry-compatibility·registry-governance·second-api-feature-
registries·release-artifacts 55/55 통과. compatibility fixtures 11 PASS.
verify-documentation-readiness PASS_SCOPED. tsc node·test rc=0, 바꾼
파일 eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요). 제거 드릴은
update:registry-baseline 뒤 check:registries를 돌리므로 (3)이 있어야
통과한다.
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
|
||
|
|
61baf96682 |
fix(docs): 입구 문서를 실제 src 폴더 9개와 규칙 이름에 맞추고 검사한다 (14-03)
문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(
|
||
|
|
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
|
||
|
|
e4ace51099 |
fix(features): 기능이 하나도 없을 때도 타입 검사와 커버리지가 통과하게 한다 (15-01)
문제: 샘플 제거 드릴(test:sample-removal)이 reference feature를 지우면 설치된 기능이 0개가 된다. 15-01 이후 그 상태에서 기능 기여 타입이 never가 되어 installed-feature-adapters.ts와 테스트 2개가 타입 검사에서 실패했다. features.load는 기능 테스트로만 검증되고 있어서, 기능 테스트가 같이 지워지면 create-application.ts 커버리지가 90% 아래로 떨어졌다. 드릴 사본에 README.md·CHANGELOG.md가 없어 문서 테스트 2개도 실패했다. 방법: never일 때도 통과하는 넓은 타입으로 받아서 읽는다(as 단언 없이 대입). features.load는 가짜 로더로 플랫폼 테스트를 추가했다(한 번만 적재, 남의 input 거부, 실패 후 재시도). 문서 테스트 2개는 드릴 제외 목록에 넣었다. 드릴 사본에 문서를 복사하는 안은 버렸다. 기능 제거와 무관한 파일이 사본 목록에 들어간다. 위험: 넓힌 타입은 기여 타입이 바뀌어도 featureId 검사 부분은 잡지 못한다. 그 검사는 실행 시 TypeError로 남아 있다. 검증: tsc -p tsconfig.test.json 통과, check:types 통과, 관련 단위 테스트 20/20 통과. 드릴은 고치기 전 실행에서 coverage PASS를 확인했고 타입 오류 2건이 남아 있었다. 그 2건을 고친 뒤 드릴 전체는 다시 돌리지 않았다. |
||
|
|
9333595ce5 |
fix(scale): 기능 복사본이 외부 패키지를 고정하고 선언하게 한다 (1101/07-04)
문제: 1101/07-04 이후 조립 단계는 reference feature 밖의 TEMPLATE_FIXTURE 기여를 거부한다. 규모 측정 생성기는 reference feature를 그대로 복사하므로 +25/+100 측정이 ContractContributionError로 멈췄고, 기준선 source가 작업 트리 SHA(2be973a)로 남아 있었다. 방법: renameReferenceFeature가 복사본의 source를 EXTERNAL_PACKAGE (@feature-shape/<id>)로 바꾸고, 같은 패키지를 contracts.contractPackages에도 선언한다. 제품 기능이 실제로 거치는 경로와 같다. 조립 검사에 측정용 예외를 두는 안은 버렸다. 측정이 제품과 다른 경로를 재게 된다. 위험: reference feature의 source 블록 형태가 바뀌면 정규식이 맞지 않는다. 그때는 조립이 같은 오류로 실패하므로 조용히 틀린 값을 기록하지 않는다. 검증: node scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100 --repeats=2 --write 성공(초기 JS +0: 203,816 B, +25: 219,508 B, +100: 264,841 B), tests/unit/feature-shape-growth.test.ts 6/6 통과. |
||
|
|
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 통과. |
||
|
|
41e79627d0 |
test(scale): 기능 규모 기준선에 측정한 커밋을 남기고 다시 잰다 (0929/11-05)
문제: config/scale/feature-shape-growth.json에 측정 시각만 있고 어느
코드를 쟀는지가 없다. 기준선이 지금 코드와 맞는지, 다음 측정과 비교할 수
있는지 알 수 없다. 실제로 기준선은 2026-09-27 측정이고, 그 뒤 15-01이
초기 청크 구조를 바꿨다(ceilings.json도 "baseline predates 15-01"이라고
적고 있었다). 기준선 0개 초기 JS 200,001 B, 기능당 2,907 B는 지금 코드와
다르다.
고른 방법:
- 측정 스크립트가 시작할 때 `git rev-parse HEAD`와 추적 파일 변경 목록
(`git status --porcelain --untracked-files=no`)을 읽어 결과의
`source: { commit, modifiedPaths }`에 싣는다. 변경 목록이 비면 커밋만으로
재현된다는 뜻이다. 측정 중 트리가 바뀔 수 있어 시작할 때 읽는다.
- 기준선을 현재 코드로 다시 잰다(--sizes=0,25,100 --repeats=2 --write).
- ceilings.json의 수치를 새 기준선에 맞춘다. 초기 JS 여유는 리뷰 개선안대로
"예산 − 기준선 ÷ 기능당 증가"로 적는다(2,291 B ÷ 약 610 B ≈ 3개).
- 단위 테스트가 기준선에 40자 commit과 modifiedPaths 배열이 있는지 본다.
버린 대안:
- 기준선 커밋이 현재 이력의 조상인지 테스트로 확인: 이력 없이 3-way로
이식하는 다운스트림(tech-log)에서는 템플릿 커밋이 없어 항상 실패한다.
- dirty 트리면 --write를 거절: 이 커밋처럼 측정 스크립트와 기준선을 한
커밋에 넣을 수 없게 된다. 대신 변경 경로를 그대로 기록한다.
위험·한계:
- 기록된 커밋은 2be973a(이 브랜치의 직전 커밋)이고 modifiedPaths는 측정
스크립트와 그 테스트 2개다. 측정 대상(src, vite 설정)은 그 커밋과 같다.
이 브랜치를 rebase하면 기록된 SHA가 이력에서 사라진다. 그때는 다시 재야
한다.
- 시간 값은 호스트 부하(loadavg 27~29)에 따라 흔들린다. 바이트와
instantiation 수만 비교 대상이다.
- 15-01 커밋 본문의 202,361 B와 이번 0개 측정 202,509 B는 148 B 다르다.
원인은 확인하지 않았다. ceilings.json은 기준선 수치 하나로 통일했다.
검증:
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
-t 'commits a baseline' — "expected undefined to deeply equal { commit:
StringMatching…" 실패.
- 측정(flock): 0개 202,509 B·720,060 inst, 25개 218,010 B, 100개
263,119 B·12,399,171 inst, 반복 2회 바이트·inst 동일. 기능당 초기 JS
약 610 B, lazy 약 8.3 KB·8파일, inst 약 117k, tsc 메모리 약 36 MB,
route 4개.
- 재현: 같은 트리에서 --sizes=0,25 --repeats=1을 다시 돌려 0개 202,509 B,
25개 218,010 B로 같음.
- GREEN: feature-shape-growth.test.ts 5 passed(빌드 측정 테스트 포함).
- tsc(node·test), eslint(바꾼 2파일), verify-documentation-readiness
PASS_SCOPED.
Refs: docs/reviews/2026-09-29-maturity-review/11-tests-browser-release-scale.md 11-05
|
||
|
|
95e7d1107c |
test(vitest): skip·todo·only가 남은 실행을 실패시킨다 (10-04)
문제: Vitest는 skip·todo 테스트를 통과로 센다. `it.skip`이나
`it.todo`가 든 파일은 CI=true에서도 종료 코드 0으로 끝난다.
`context.skip()`도 같다. `.only`는 Vitest 기본값 때문에 CI에서만 막히고,
로컬에서는 같은 파일의 나머지 테스트를 조용히 건너뛴다.
check:test-evidence의 소스 검사가 quarantine 주석 없는 `.skip(`·`.only(`
글자를 잡지만, `it.todo`, `context.skip()`, `skipIf`는 보지 못한다.
고른 방법:
- vitest.config.ts에 allowOnly: false를 둬 `.only`를 어디서나 막는다.
- scripts/lib/no-skipped-tests-reporter.ts reporter가 실행 끝에
state가 skipped인 테스트를 찾으면 이름을 출력하고 exitCode를 1로 둔다.
-t, 태그 필터, file:line처럼 호출자가 일부러 좁힌 실행은 예외다.
게이트는 실행을 좁히지 않는다.
- reporter는 scripts/run-vitest.ts가 붙인다. CLI --reporter는 config의
reporters를 대체하므로 config에 두면 package script에서 빠진다.
run-vitest.ts는 package script와 scale tier가 모두 거치는 입구다.
호출자가 reporter를 하나도 주지 않으면 default를 함께 붙인다.
버린 대안:
- 리뷰 최소 개선안의 junit `skipped > 0` 검사: Vitest junit은 mode가
skip·todo인 테스트만 <skipped/>로 적고 `context.skip()`은 통과처럼
적는다. junit을 쓰지 않는 실행(scale tier, http-scenario-catalog,
로컬 단일 파일)은 아예 보지 못한다.
- tests/setup.ts의 afterAll 검사: 모든 테스트가 skip인 파일은 hook이
돌지 않아 잡지 못한다.
- eslint-plugin-vitest no-disabled-tests: 새 의존성이 생기고
`context.skip()`을 못 잡는다.
위험·한계:
- run-vitest.ts를 거치지 않는 직접 `vitest` 실행에는 reporter가 붙지
않는다. allowOnly는 config라서 그때도 적용된다.
- 호출자가 reporter를 주지 않으면 default reporter를 고정해서 붙인다.
Vitest가 AI 에이전트 환경에서 고르는 agent reporter 대신 default가
나온다.
- 본문 없는 `describe.todo`처럼 테스트가 없는 묶음은 세지 않는다.
- check:test-evidence는 quarantine 주석이 있는 `.skip(`을 허용하지만
이 reporter는 Vitest에서 그것도 실패시킨다. 지금 quarantine은
Playwright spec에만 있어 충돌하는 테스트는 없다. 전략 문서 16.5절에
"quarantine은 Vitest 테스트를 통과시키지 않는다"고 적었다. Vitest에도
quarantine이 필요해지면 허용 목록을 따로 둬야 한다.
- 지금 저장소의 Vitest 테스트에는 skip·todo·only가 없다.
검증:
- RED(P-B 재현, run-vitest.ts로 skip+todo, only, context.skip() 파일을
CI 없음/CI=true로): 수정 전 6경우 중 5경우 exit 0("1 passed | 1
skipped | 1 todo"). only+CI=true만 exit 1.
- 새 tests/unit/no-skipped-tests-reporter.test.ts는 수정 전 "Cannot find
module ../../scripts/lib/no-skipped-tests-reporter.ts"로 실패.
- GREEN: 같은 6경우 모두 exit 1. skip·todo·context.skip()은 "N test(s)
did not run" 목록, only는 "Unexpected .only modifier". junit reporter를
준 실행도 exit 1. -t로 좁힌 실행과 file:line 실행은 exit 0. 새 테스트
11 passed.
- 빠른 계층 전체(unit·component·integration·contract·runtime-schema·
platform·architecture·features·release·scripts·recipes, pnpm 설치를
하는 fixture-node-modules.test.ts 제외, maxWorkers 4): 3,228 passed,
1 failed. 실패는 provider-guardian-transaction의 fs.watch ENOSPC(호스트
inotify 한도)이고 reporter 없이 vitest를 직접 돌려도 같다. skip 목록
출력은 없었다.
- tsc -p tsconfig.node.json, tsconfig.test.json, eslint(바꾼 4파일),
check-ci-contract, generate-ci-workflow --check,
verify-documentation-readiness(PASS_SCOPED) 통과.
Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-04
|
||
|
|
85d55e0cd3 |
fix(service-worker): 사전 캐시와 설정 URL이 router base path를 따른다 (0929/06-02)
문제: SW 자산 생성기(scripts/generate-service-worker-assets.ts)가 사전
캐시 URL을 `/${relative}`로 만들어 VITE_ROUTER_BASE_PATH를 무시했다.
워커는 root-relative URL을 scope 기준으로 풀지만 base가 사라지므로
/app/ 배포에서 install이 /assets/...를 요청해 404를 받고, 워커가
설치되지 않았다. 같은 빌드의 SW 설정도 runtime config URL 기본값을
"/config.json"으로 고정해, 페이지가 쓰는 /app/config.json을 워커가
network-only로 알아보지 못했다. 앱 빌드·runtime config·06-08
fallback은 이미 base를 따르는데 이 두 곳만 빠져 있었다.
고른 방법: 리뷰가 적은 최소 방향. collectStaticAssets에 basePath
인자(기본 "/")를 더하고, 생성기 main과 SW Vite 설정이 페이지와 같은
getBuildConfig(src/contracts/env.ts)로 base와 runtime config URL을
계산한다. 결과 URL은 그대로 root-relative라 isCanonicalStaticAssetUrl
검사를 통과한다. base가 "/"이면 manifest와 digest가 전과 같다.
버린 대안: 워커가 manifest URL을 scope 상대로 풀게 바꾸기. 계약 차이는
없지만 워커 코드와 manifest 계약(root-relative)을 함께 바꿔야 해서
생성기 수정보다 크다.
위험·한계:
- base마다 manifest digest가 달라진다(의도된 결과).
- VITE_RUNTIME_CONFIG_URL이 빈 문자열이면 이제 base 기본값을 쓴다.
페이지(getBuildConfig)와 같은 규칙이다.
- 리뷰 완료 기준의 "e2e 도우미를 base 옵션으로 돌린 첫 설치가
RELOAD_TO_ENABLE"은 하지 않았다. e2e 도우미에 base 옵션과 /app/
서빙이 필요하고, 실제 브라우저 install은 이번에 확인하지 않았다.
검증:
- RED: collectStaticAssets 단위 테스트(basePath "/app/")가 수정 전
`/assets/index-abcdefgh.js`를 받아 실패(1 failed | 9 passed).
service-worker-build-output.test.ts의 새 테스트(SW ACTIVE·
production·/app/ 실제 빌드)가 생성기만 되돌리면 URL 목록에서,
SW 설정만 되돌리면 `Received: "/config.json"`으로 각각 실패.
- GREEN: 두 테스트 통과. `node scripts/run-vitest.ts run
tests/unit/service-worker tests/unit/sub-path-deployment.test.ts
tests/unit/hosting-probe.test.ts tests/unit/web-push` -> 12파일
171건 통과(빌드 테스트는 flock 안에서).
- `npx tsc` node·test·app·service-worker -> 오류 0.
- `npx eslint <바꾼 파일 4개> --max-warnings=0` -> 통과.
- `node scripts/check-adapter-inventory.ts` -> PASS.
- 미실행: SW e2e(Playwright).
Refs: docs/reviews/2026-09-29-maturity-review/06-adapters-service-worker-push.md 06-02, docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2.1절
|
||
|
|
e0c2a91d47 |
test(setup): npx vitest가 npm scope 환경변수 없이 시작한다 (1101/15-05)
문제 `npx vitest run tests/unit/ci-workflow-generation.test.ts`는 79건이 "CI runner npm scope environment invalid"로 실패한다(415건 중). npx와 npm을 거친 IDE 실행기는 npm_config_prefix·_userconfig·_globalconfig를 넣는다. CI 게이트 preflight(withCiGatePreflight)는 실제 runner에서 이 변수들을 거절하는데(옳은 동작), 테스트가 그 preflight를 프로세스 안에서 부르거나 자식으로 띄우면서 실행기의 process.env를 그대로 물려받는다. scripts/run-vitest.ts만 그중 일부를 지워서 pnpm 경로만 통과한다. 원인은 timeout이 아니라 이 환경변수다. 고른 방법 - vitest.config.ts가 NODE_ENV를 고정하는 자리에서 npm scope 변수를 지운다. config는 worker를 띄우기 전에 메인 프로세스에서 평가되므로 worker와 그 자식 프로세스 모두 깨끗한 환경으로 시작한다. 어느 실행기로 돌리든, 어느 테스트 파일이든 한 곳에서 막는다. - 지울 이름은 preflight가 쓰는 것과 같은 판정 (package-script-graph.ts의 isNpmScopeEnvironmentName, 기존 private 함수를 export)으로 고른다. 목록이 둘로 갈라지지 않는다. - ci-workflow-generation.test.ts에 "테스트 프로세스에 npm scope 변수가 없다"는 테스트를 더했다. 버린 대안 - 해당 테스트 파일의 beforeEach/afterEach에서 지우고 되돌리기(리뷰의 최소 방향 1): 같은 preflight를 띄우는 다른 파일이 생기면 다시 깨진다. - 실행 함수가 환경을 인자로 받게 하기: 자식 프로세스는 여전히 process.env를 물려받아 실패한다. - run-vitest.ts의 하드코딩 목록 정리: 이번 수정으로 필요 없어지지만, product index 생성 자식에도 쓰이고 동작이 같아 건드리지 않았다. 위험·한계 - 실제 게이트 실행기의 npm scope 거절은 그대로다. 테스트 안에서 일부러 변수를 넣는 기존 테스트 3건도 그대로 통과한다. - tests/unit 밖(component, integration 등)은 npx로 돌려 보지 않았다. 검증 - RED: npx vitest run tests/unit/ci-workflow-generation.test.ts -t "npm-launched runner" 실패 "expected [ 'npm_config_userconfig', …(2) ] to deeply equal []". 수정 전 같은 파일 79 failed / 336 passed - GREEN: npx vitest run tests/unit/ci-workflow-generation.test.ts 416 passed - npx vitest run tests/unit: 171파일 2,401 passed - tsc(node, test), eslint 바뀐 파일 통과 Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-05 |
||
|
|
f13ed7bea7 |
fix(docs): verify:documentation이 실패한 검사와 고칠 파일을 적는다 (1101/14-06)
문제 verify-documentation-readiness.ts는 실패 원인과 상관없이 마지막에 "FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)"를 적는다. stderr에 따로 적는 것은 README 빌드 변수 누락뿐이다. 기능을 더해 route가 늘었는데 README나 접근성 체크리스트에 route ID를 안 적으면, 개발자는 diagram 리뷰 기록을 먼저 의심하고 산출물 JSON을 열어야 원인을 안다. 고른 방법 - 검사 네 개(route scope, runtime variables, review report digest, diagram reviews)의 실패를 failedChecks로 모으고 passed는 그것이 비었는지로 정한다. 판정 조건은 그대로다. - 실패하면 검사마다 고칠 곳을 stderr에 적는다. route scope는 문서별로 빠진 route ID, diagram review는 어느 diagram이 증거 문서에 PASS로 없는지. - 마지막 줄은 "FAIL_UNVERIFIED (failed: <검사 이름들>)"이다. 판정 토큰은 그대로 둬서 이 줄을 읽는 쪽이 바뀌지 않는다. 버린 대안 - route ID 누락만 따로 적기(리뷰의 최소 방향): 다음에 다른 검사가 실패해도 같은 엉뚱한 문구가 나온다. 검사 네 개 모두 같은 방식으로 적어도 몇 줄이다. 위험·한계 - diagram review 실패는 어느 하위 조건(경로·digest·점수)인지까지는 적지 않는다. 산출물 JSON의 results에 그대로 있다. 검증 - RED: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts 2 failed. README에서 `EXAMPLES_PLATFORM`을 지운 사본에서 stderr가 "Documentation readiness: FAIL_UNVERIF…"뿐이라 "README.md does not name route IDs: EXAMPLES_PLATFORM"이 없다. 두 검사 실패 때도 실패 이름이 없다 - GREEN: 같은 파일 3 passed(원본 사본 PASS, route 하나 누락, route+변수 누락) - 실제 repo에서 verify-documentation-readiness PASS_SCOPED - eslint, tsc(node, test), check-ci-contract PASS Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-06 |
||
|
|
b3af26fc0e |
fix(release): 배포된 config.json 사본을 바꾸기 전에 검사한다 (1101/13-05)
문제 .env.example과 운영 문서는 runtime config를 재빌드 없이 바꿀 수 있다고 적는다(SERVICE_WORKER DISABLED, FEATURE_OVERRIDES). 그런데 고친 문서를 검사할 명령이 없다. check:release-admission은 dist/config.json만 읽고, build:profile은 BUILD_ID를 덮어 다시 만든다. 브라우저는 부팅 때 문서를 스키마로 검사하고 BUILD_ID를 HTML과 맞춰 보므로, 오타 하나나 BUILD_ID 변경 하나가 모든 사용자의 BOOT_CONFIG_FAILURE가 된다. FE-RB-001은 세 줄이고 고치는 방법이 없다. 고른 방법 - check-release-admission.ts가 `--config <고친 사본> --original <배포된 원본>`을 받는다. 사본에 기존 검사(스키마, 대상 규칙)를 그대로 돌리고, 원본과 비교해 CAPABILITY_OVERRIDES·FEATURE_OVERRIDES 밖의 필드가 하나라도 바뀌면 거절한다. BUILD_ID·RELEASE_ID 유지는 이 규칙에 들어 있다. `--original` 없이 `--config`만 주면 거절한다(비교 대상 없이 통과시키지 않는다). - 사본 검사는 artifacts/release/deployment-admission.json을 쓰지 않는다. 그 파일은 빌드의 승인 증거(CI artifact)이고 운영자의 사본은 빌드가 아니다. - FE-RB-001에 네 단계(사본 두 개 받기·고치기 → 검사 → 같은 파일시스템에서 rename으로 교체, 되돌리기도 같은 방법 → 깨끗한 세션 부팅 확인)를 적고, release-cache-rollback.md와 browser-file-storage-recovery.md의 스위치 설명이 그 절차를 가리킨다. .env.example 문장을 "비상 스위치만 재빌드 없이 바꾼다"로 좁혔다. - pnpm이 `--`를 넘겨도 되도록 맨 앞 `--`를 버린다. 버린 대안 - `--build-id <id>`로 BUILD_ID만 대조: API_BASE_URL·RELEASE_MANIFEST_URL처럼 빌드가 정한 다른 필드를 바꿔도 통과한다. 원본 전체 비교가 같은 비용으로 더 좁다. - release-manifest.json에서 build id를 읽기: 운영자가 받을 파일이 하나 더 늘고, 여전히 BUILD_ID만 본다. - 비상 스위치도 빌드로만 바꾸기: 장애 대응 시간이 빌드·승격 시간만큼 늘어 스위치의 목적이 사라진다(리뷰 대안 비교). 위험·한계 - 원본과 사본의 중첩 객체 비교는 JSON.stringify라 키 순서만 달라도 "바뀜"으로 거절한다(닫힌 쪽으로 실패). - 실제 서버에서 사본을 바꿔 부팅해 보지 않았다. 바뀐 문서가 release 기록(checksums.txt, 승격 archive)과 달라지는 점은 런북에 적기만 했다. 검증 - RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts 새 6건 실패. 모두 "release admission refused: dist/config.json is unreadable"(--config를 무시하고 dist를 읽음) - GREEN: 같은 파일 22 passed. 스위치만 바꾼 사본 ADMITTED·기록 없음, SERVICE_WORKER "DISABLE" 오타·BUILD_ID/RELEASE_ID/API_BASE_URL 변경· --original 누락은 exit 1 - runbook-contract, runbook-drill, feature-override-diagnostics 포함 35 passed - 실제 local 빌드에서 인자 없는 기존 경로 ADMITTED(기록 작성), `-- --config dist/config.json --original public/config.json` ADMITTED - tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness PASS_SCOPED Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-05 |
||
|
|
629c8f045e |
fix(hosting): 호스팅 검사가 SPA fallback과 SW 스크립트 헤더를 본다 (1101/13-04)
문제
라우터는 browser history를 쓴다. 호스트가 앱 경로에 index.html을 주지
않으면 `/`는 열리고 새로고침·북마크·공유 링크만 404가 된다. 호스팅 계약
(config/hosting/cache-policy.json)에 앱 경로 표면이 없고, live probe는
`/`, config, manifest, entry script만 요청해서 FE-GATE-019가 그대로
PASS한다. 운영 문서가 no-cache로 서빙하라는 service-worker.js도 선언과
검사에 없다. e2e는 fallback을 기본으로 하는 vite preview라 드러나지 않는다.
고른 방법
- cache-policy.json에 표면 두 개를 더한다.
- appRoute: 빌드에 파일이 없는 경로 `/__probe/deep-link`. index와 같은
Cache-Control, content-type, 보안 헤더를 요구한다.
- serviceWorker: `/service-worker.js`, no-cache, JS MIME.
`requiredWhen: "service-worker-shipped"`로 워커를 싣는 빌드
(ACTIVE, REMOVE_REGISTRATION)에서만 요구한다. 이 판정은
checkPublicServiceWorkers와 같은 함수(shipsServiceWorker)를 쓴다.
- live probe를 scripts/lib/hosting-probe.ts의 probeLiveRelease로 옮겨
fetcher를 주입해 단위 테스트한다. 요청 경로는 정책의 path에서 읽는다.
appRoute는 200이어야 하고, 응답이 index.html과 같은 entry script를
가리켜야 한다. 그래서 404와, 200으로 답하는 다른 페이지(soft 404)를
모두 FAIL로 잡는다.
- release-cache-rollback.md에 fallback 규칙과 desktop 서버용 nginx 예시를
적는다. 예시는 손으로 썼고, 빠진 hashed asset은 index.html이 아니라
404여야 한다는 점(구 탭 재적재, FE-RB-002)과 add_header 상속 함정을
적었다.
버린 대안
- createHashRouter로 바꿔 fallback 자체를 없애기: URL과 기존 경로 계약·
테스트가 모두 바뀐다(리뷰 대안 비교에서 기각).
- 정책 이름(serviceWorker)으로 스크립트가 조건을 아는 방식: 정책 파일만
읽는 운영자가 항상 필요한 표면으로 오해한다. 조건을 JSON에 적었다.
- 리다이렉트 뒤 최종 경로까지 비교: 이번 완료 기준(404 FAIL) 밖이라 넣지
않았다.
위험·한계
- nginx 예시는 이 머신에 nginx가 없어 실행하지 않았다. CI도 돌리지 않는다.
호스트가 실제로 무엇을 주는지는 live probe가 확인한다.
- 이미 배포한 호스트에 fallback이나 SW 헤더가 없으면 FE-GATE-019가 새로
실패한다(의도).
- 앱 base path가 `/`가 아닌 배포는 기존 probe와 같이 다루지 않는다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
5 failed. "expected undefined to match object { cacheControl:
'no-cache', …}"(정책에 appRoute·serviceWorker 없음),
"probeLiveRelease is not a function"
- GREEN: 같은 파일 22 passed. fallback 없는 호스트에서
["appRoute http-status", "appRoute entry-script"]가 실패로 나온다
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
tests/platform/release tests/release tests/unit/ci-workflow-generation.test.ts:
483 passed
- build-frontend.ts 뒤 verify-hosting-headers.ts(fixture): UNVERIFIED rc=3,
결과 36건(appRoute 8건 포함), SW null이라 serviceWorker 헤더 검사는 건너뜀
- tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness
PASS_SCOPED, check-ci-contract PASS
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-04
|
||
|
|
5e6be9a92f |
fix(registry): breaking 증거를 그 증거가 설명하는 값에 묶는다 (0929/07-01)
문제
breaking 증거 조회 키는 registryId:row:field:kind뿐이고, 증거 검사는
5필드가 비었는지만 본다. 값은 diff에 있지만 증거와 비교하지 않는다. 그래서
한 번 증거를 쓴 row·field는 다음 변경도 새 증거 없이 통과한다. 실험 X3:
REFERENCE_RESOURCE_DETAIL.path를 08-13 증거가 설명하는
/examples/reference-resources/items/:resourceId가 아닌
.../entries/:resourceId로 바꿔도 check-registries가 "11 registries
PASS"였다. 공개 URL·API 경로·저장 키 같은 breaking 변경이 이행·롤백
계획 없이 지나간다.
고른 방법 (리뷰 최소 개선 (1))
- 값이 있는 breaking 변경(change.after가 있음)은 증거 행에 after가 있어야
하고, canonical JSON이 diff의 after와 같아야 한다. 없으면 "evidence
needs after", 다르면 "evidence explains after=..., the change is
after=..."로 실패한다. 키 순서·원시값 배열 순서는 기존 canonical 규칙
그대로라 차이로 보지 않는다.
- 삭제(row·registry·field 삭제)는 설명할 값이 없어 after를 요구하지 않는다.
- 현재 diff와 맞는 템플릿 증거 1건(REFERENCE_RESOURCE_DETAIL.path)에
after를 더했다. ci-quality-gates.md의 증거 안내에 after를 적었다.
- 완전한 증거를 만드는 테스트 두 곳(registry-compatibility,
registry-governance tamper 사례)에 after를 넣었다.
버린 대안
- after를 선택 필드로 두기: 없는 행은 지금처럼 모든 다음 변경을 통과시켜
X3이 그대로 남는다.
- 증거 키에 값 해시를 넣기(changeId 형식 변경): 기존 changeId 문법과
출력이 바뀌고 사람이 읽을 수 없다.
- 리뷰 (2) 현재 diff와 맞지 않는 증거 행 실패 또는 목록 출력, (3)
update:registry-baseline의 증거 정리: 실패로 할지 출력으로 할지, 오래된
14건을 지울지 이력 파일로 옮길지가 감사 기록을 다루는 결정이라 이번에
하지 않았다.
위험·한계
- 증거 파일 형식이 바뀐다. 다운스트림이 이 검사를 동기화하면 아직 diff에
남은 breaking 변경의 증거 행마다 after를 넣어야 게이트가 통과한다.
다음 릴리스 CHANGELOG [계약] 행이 필요하다(미출시 절이 없어 적지
않았다).
- 오래된 증거 행(현재 diff와 무관한 14건, 0929/07-02 수정으로 쓰이지 않게
된 VITE_BUILD_ID 포함)은 그대로 남는다. 위 (2)·(3)이 남은 일이다.
- 값이 큰 contract 필드(allowedValues 전체 등)의 증거는 그 값을 통째로
적어야 한다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 2건 실패
("rejects evidence written for another value", "requires the explained
value": expected [] to deeply equal [...]). X3 변이로 check-registries
"11 registries PASS".
- GREEN: 같은 X3 변이에서 check-registries 실패("evidence explains
after=\"/examples/reference-resources/items/:resourceId\", the change is
after=\"/examples/reference-resources/entries/:resourceId\""), 변이 없이
"11 registries PASS". registry-compatibility·registry-governance·
release-artifacts·second-api-feature-registries 53/53 통과.
compatibility fixtures 11 PASS. verify-documentation-readiness
PASS_SCOPED.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm), test:sample-removal(pnpm).
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
|
||
|
|
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
|
||
|
|
98b9682241 |
chore(scripts): 쓰지 않는 npm script 4개를 지우고 scan:도 게이트 검사한다 (12-05)
문제
package.json에 어디서도 부르지 않는 script 4개가 있다.
- scan:security:fixture: FE-GATE-013은 이것 대신 check:security:fixtures를
돈다. supply-chain.test.ts는 "게이트에 없어야 한다"고 단언하는데 script는
남아 있다. 게이트 밖 script 검사는 check|verify|test|drill|review만 봐서
scan:을 놓쳤다.
- build:profile: 이름과 달리 generate-runtime-config.ts만 돈다.
- generate:contract-set: 참조 0건.
- build:app-only: vite build와 매니페스트만 만든다. build-frontend.ts의
계약 세트·런타임 설정·Service Worker 단계가 빠진 dist가 나온다. 참조는
product-index-entrypoints 테스트의 진입점 목록 하나다.
참조 확인(새 기준
|
||
|
|
e714c0d770 |
fix(design-system): 디자인 검사가 deg 색상각과 시스템 글꼴 이름을 받는다 (12-04)
문제
디자인 규칙이 올바른 CSS를 거부한다. 포커스 대비 규칙의 parseOklch는
색상각 단위 deg와 음수 색상각을 읽지 못해 oklch(52% 0.15 230deg)를 실패로
센다(B13). 첫 글꼴 규칙은 -apple-system, BlinkMacSystemFont로 시작하는
시스템 글꼴 스택을 실패로 센다(B6). color-mix()·알파 표면(B10, B11)은
"--color-focus or X is not a plain oklch() value"로 실패해서 어느 토큰이
무슨 값인지, 무엇이면 되는지 알 수 없다. 네 규칙의 설명은 코드 주석에만
있다.
고른 방법
- parseOklch가 색상각에 deg와 음수를 받는다. 알파는 계속 받지 않는다.
- oklch-contrast.ts에 resolveValue(var() 사슬 끝 값)를 두고 resolveColor가
그것을 쓴다. 포커스 규칙은 계산할 수 없는 토큰마다 "<테마> <토큰> is
<값>; contrast needs an opaque oklch(L C H), hue in degrees with or
without deg"를 낸다. 포커스 색 자체를 못 읽으면 표면 8개 대신 한 줄이다.
- 첫 글꼴 허용 목록에 -apple-system, BlinkMacSystemFont를 더한다.
- docs/styling/design-system-platform.md 4.1절에 규칙 4개, 지원 형식,
검사 위치를 표 하나로 적는다.
버린 대안
- color-mix()·알파 표면을 배경 위에 섞어 계산: 무엇이 아래에 그려지는지
규칙이 모른다. 추측하지 않고 실패하는 기존 원칙을 유지하고 메시지로
해결 형식을 알린다(리뷰 대안 비교와 같다).
- 리뷰 개선 (4) token-contract.ts에 "제품이 싣는 글꼴" 목록: 공개 계약에
새 이름을 넣는 설계 선택이고 완료 기준에 없다. 문서 표에 "아직 선언할
곳이 없어 실패한다"로 적었다.
- rad·grad·turn 단위: 쓰는 곳이 없다. 넣지 않은 단위는 메시지가 알려 준다.
위험·한계
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 이 테스트 파일뿐이다.
- 패키지·<link>로 싣는 글꼴, 12-03의 검사 위치 밖 CSS는 그대로다.
- 화면 변화 없음. CSS를 바꾸지 않았다.
검증
- RED(수정 전): design-system-rules·oklch-contrast 테스트 19개 중 4개
실패. "reads a hue written with deg" expected [ …(8) ] to deeply equal [],
"names the value it cannot compute …" 메시지 불일치, "-apple-system"
expected [ Array(1) ] to deeply equal [], parseOklch("…230deg") expected
null.
- GREEN: 같은 두 파일과 design-system-contract 21/21 통과. 실제 스크립트
probe: 포커스를 oklch(52% 0.15 230deg)로 → PASS(B13). surface-muted를
oklch(0.97 0 0 / 0.9)로 → "light --color-surface-muted is oklch(0.97 0 0
/ 0.9); contrast needs …"로 실패(B11). 저장소 CSS는 PASS.
- tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint, verify-
documentation-readiness PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
|
||
|
|
3c175a5429 |
fix(provider): guardian이 실패하면 stdin을 기다리지 않고 끝난다 (G-1)
문제
guardian은 fd 0을 fs.createReadStream으로 읽는다. 이 스트림은 libuv
스레드 풀의 스레드 하나를 read(2)에 세워 둔다. process.exit()는 종료
전에 스레드 풀을 join하므로, 그 read가 돌아올 때까지(부모가 stdin을
닫을 때까지) 끝나지 않는다. 그래서 가드를 거부하거나 link가 실패하면
failClosed가 진단을 바로 쓰고도 프로세스는 남는다. 클라이언트는 stdin을
연 채 READY를 기다리므로 거부가 즉시 오지 않고 고정 5초 뒤 "READY timed
out"으로 끝난다. 같은 종류 guardian 두 개 테스트의 패자가 이 경로다.
탐침: 같은 종료 코드를 fs 스트림은 stdin을 닫은 2,008ms에, net 소켓은
228ms에 냈다(200ms 뒤 exit 호출).
고른 방법
- liveness 입력을 process.stdin으로 바꾼다. pipe면 Node가 이벤트 루프로
읽는 net.Socket을 만든다. 스레드 풀 read가 없어 exit가 바로 끝난다.
data/end/error 처리, removeAllListeners·destroy, closeSync(0)는 그대로다
(libuv는 fd 0~2를 destroy에서 닫지 않는다).
- 동시 guardian 테스트에 붙였던 PROCESS_HEAVY_TIMEOUT_MS와 그 주석을
뺀다. 패자가 link 실패 즉시 끝나 테스트가 5.14초에서 0.16~0.54초가 됐다.
버린 대안
- provider-scope-wrapper.ts처럼 new Socket({ fd: 0 }): fd 0이 pipe가
아니면 생성자가 throw한다. guardian은 그 시점에 이미 private alias를
묶었고 failClosed는 liveness가 있어야 돈다. process.stdin은 pipe에서는
같은 Socket이고, 그 밖의 fd에서는 throw 대신 end/error로 기존 실패
경로(125)를 탄다.
- 실패 때 SIGKILL로 자신을 죽이기: 종료 코드 124~126 계약이 사라진다.
위험·한계
- pipe인 fd 0에 O_NONBLOCK이 걸린다. 읽기 끝은 guardian만 가진다
(클라이언트는 stdio "pipe"로 띄운다).
- lease 마감 경로는 원래 SIGKILL을 쓰므로 바뀌지 않는다.
검증
- RED(수정 전): 새 테스트 "exits on a rejected guard while the parent
still holds its input open"이 "rejected-guard guardian exit timed out"
(5,122ms)으로 실패. 다른 nonce의 가드를 보내 시계와 무관하게 거부시킨다.
- GREEN: tests/integration/provider-guardian-transaction.test.ts 22/22
통과, 3회 반복 통과(새 테스트 65~333ms). tests/unit/task3-selective-
integration 7/7. tsc(tsconfig.node, tsconfig.test) 통과, 바꾼 파일
eslint 통과.
- 미실행: tests/system/ci-runner/ci-artifact-contract.test.ts의 provider
체인 테스트. fixture가 corepack pnpm으로 빌드해서 이 worktree에서는
돌리지 않았다.
Refs: commit
|
||
|
|
298201f3ee |
perf(features)!: 기능 실행부를 초기 청크에서 떼어 라우트 진입 때 적재한다 (15-01)
문제 초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의 feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper 포함), HTTP 계약 contribution, application input 팩토리, route codec까지 모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서 예산을 넘었다. 고른 방법 - 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime 계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼 contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API 계약, adapter contribution, contract contribution)는 feature-runtime.ts로 옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의 route handle에 실어 route와 함께 적재한다. - 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route 모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에 화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route 모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은 적재하지 않는다. - 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다 (installed-contract-contributions.ts). 선언하지 않은 contract package를 적재하면 거절한다. - 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는 installed-feature-runtime-registries.ts의 async 함수로, Node·테스트· registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로 둔다. src에서 후자를 import하면 새 아키텍처 규칙 boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은 route 로더에서 async 함수를 불러 결과를 prop으로 받는다. - vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy 청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면 기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는 플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져 템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을, feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다. render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03: 애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다). 버린 대안 - 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는 lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라 버렸다. - 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를 공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다. - 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당 -60 B 수준이라 그룹 없이 목표에 못 미쳤다. - 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만 i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다. - boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두 초기로 세어 218,303 B가 됐다. 위험·한계 - FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로 실행부를 옮겨야 한다(BREAKING CHANGE). - 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라 그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트· 테스트)로 옮겨 간다. - 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼 구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가 재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다. - 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가 비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿 총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다. - config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직 installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인 때 고친다. check-registries는 통과한다. - 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의 98.8%다. 수치 (vite build, classifyViteJavascript + gzipSync 기본 수준) - 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B - 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741) - 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648) - 참조 복사본 +5: 205,629 B - lazy JS: 23,516 B -> 28,204 B 검증 - RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts "adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or equal to 1024 - GREEN: 같은 테스트 통과(+741 B) - node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과 - node scripts/run-vitest.ts run tests/component tests/features tests/integration tests/contract tests/runtime-schema tests/architecture tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출): 109파일 787 통과 - npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과 - npx eslint 바뀐 파일 통과 - check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이 boot.tsx의 import를 거절하는 것 확인 - check-adapter-inventory, check-registries, verify-documentation-readiness, check-ci-contract: PASS - e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트): 55 통과 - storybook build 성공 - 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026), pnpm 경로의 check:bundle, test:system BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages, loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약 (apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로 만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle codecs로 옮긴다. contracts에는 contractPackages를 추가한다. Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01, 16-structure-patterns.md 9절 |
||
|
|
f41e3d5e32 |
ci(gates): 번들 예산 검사를 merge 단계에서 돌린다 (15-01)
FE-GATE-012(build, check-bundle, check-app-build-input-bundle, check-optional-recipes)는 release 단계에만 있어 tag push나 수동 release 실행에서만 돈다. 초기 JS를 예산보다 크게 만드는 PR도 merge 게이트를 통과하고, 몇 PR 뒤 release가 실패한다. 어느 PR이 얼마나 늘렸는지는 그때 이력을 거꾸로 따라가 찾아야 한다. FE-GATE-012를 merge stage와 merge_gate job으로 옮긴다. release_gate는 merge_gate를 needs로 두므로 tag 실행에서도 그대로 돈다. promotion 공식 (MERGE_READY)과 CI 계약 검사의 job 소유 표를 같이 바꾸고, workflow는 생성기(node scripts/generate-ci-workflow.ts)로 다시 만든다. 버린 대안: - check-bundle만 FE-GATE-011(build)에 붙인다(리뷰의 최소안). 같은 검사가 두 게이트에 갈라지고, release에 남은 FE-GATE-012와 중복해서 돈다. - FE-GATE-012를 merge와 release 둘 다에 둔다. 계약이 게이트당 job 하나를 강제한다(multiply owned gate). - lab 게이트(FE-GATE-026)도 merge로 옮긴다. PR마다 브라우저 설치와 5회 측정이 붙고, 부하에 따라 판정이 뒤집힌 기록(0929/11-04)이 있다. release에 남긴다. 위험·한계: - merge 실행이 build 1회와 공급망 생성, 번들 계산만큼 길어진다. - 실제 CI 러너에서는 돌려 보지 않았다(Actions 꺼짐). 검증: - node scripts/check-ci-contract.ts: 27 gates PASS - node scripts/generate-ci-workflow.ts --check: PASS - node scripts/generate-artifact-schemas.ts --check: PASS - node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts tests/unit/promotion-readiness.test.ts: 423 통과(workflow 스냅샷 1건 갱신) Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01 |
||
|
|
0536891c05 |
feat(provider): 실행 단계가 자기 PID와 argv를 실행 기록에 남긴다 (11-01)
문제: tests/system의 cgroup 테스트는 provider 실행 중 /proc을 5 ms마다 표본으로 읽어 어떤 프로세스가 어떤 argv로 돌았는지 판정한다. systemd-run --scope는 scope로 옮긴 뒤 같은 PID에서 sh 게이트와 scope wrapper로 exec하고, 갓 fork된 자식은 exec 전까지 부모 argv를 보인다. 표본은 PID마다 처음 본 argv만 남겨 이 짧은 단계를 자주 놓친다. 운영 코드에는 테스트가 결정적으로 읽을 실행 증거가 없다. 고른 방법: scripts/lib/provider-process-trace.ts를 추가한다. PROVIDER_PROCESS_TRACE_PATH가 있을 때만 각 단계가 JSON 한 줄을 덧붙인다. - 자기 기록: supervisor와 scope wrapper가 /proc/self/cmdline과 /proc/self/cgroup을 남긴다(커널이 본 값). - 자식 기록: supervisor가 systemd-run, guardian client가 guardian, wrapper가 bwrap을 spawn에 넘긴 argv 배열 그대로 남긴다. spawn과 기록이 같은 배열을 쓴다. - 필드는 role, pid, ppid, argv, (자기 기록만) cgroup. 환경변수는 담지 않는다. credential과 provider 명령이 지나가는 곳이기 때문이다. - systemd-run 환경은 허용 목록으로 다시 만들어지므로 providerProcessTraceEnvironment()로 기록 경로만 넘긴다. bwrap은 --clearenv라 sandbox 안의 provider는 경로를 받지 않는다. guardian은 빈 환경을 그대로 두고 client가 spawn 지점에서 기록한다. 테스트용 opt-in으로 두고 운영 감사 증거로 쓰지 않는다. 운영에서 켜면 argv가 두 번째로 남는 곳이 생긴다. 나중에 credential이나 provider 명령이 argv에 들어가는 회귀가 생기면, 지금은 /proc에 잠깐 보이는 값이 파일로 남아 CI 산출물이 될 수 있다. 감사 증거로 쓰려면 봉인 보고서와 같은 경로 안전·크기 상한·스키마·보존 정책이 필요하고 이번 범위가 아니다. CI 워크플로는 이 변수를 설정하지 않는다. 버린 대안: - /proc 표본 보강(부모와 같은 argv 무시, PID별 argv 이력 보존): 리뷰 README 13.1에서 시도하고 되돌렸다. 이력 보존은 prlimit -> sh로 바뀌는 PID 이력에 provider 명령이 섞여 "인프라 argv에 명령 없음" 단언의 뜻이 바뀐다. - spawn 직후 /proc/<pid>/cmdline 읽기: libuv는 exec 뒤에 반환하지만 systemd-run은 곧 wrapper로 다시 exec하므로 경쟁이 남는다. - guardian 자기 기록: guardian이 빈 환경으로 뜨는 것이 보장이라 기록 경로를 넘기지 않는다. 위험·한계: - 기록은 각 단계가 스스로 남긴다. 새 spawn 지점이 기록을 빠뜨리면 테스트에서 보이지 않는다. 모듈 주석에 적었다. - 기록 실패는 run 결과를 바꾸지 않고 stderr에 한 줄 남긴다. wrapper의 stderr는 provider 출력으로 버려지므로 빠진 줄은 기록을 읽는 쪽에서 드러난다. - 변수가 없으면 spawn 인자와 환경은 이전과 같다. 검증: - node scripts/run-vitest.ts run tests/unit/provider-process-trace.test.ts 2건 통과. 자식 기록에 env 필드를 넣는 변이를 넣으면 실패한다. - 관련 테스트 6파일 44건 통과(provider-process-trace, task3-selective- integration, provider-output-limiter, security-provider-evidence, provider-guardian-transaction, provider-process-group). - pnpm 없는 하네스(운영 encoder로 systemd-run -> sh -> wrapper -> bwrap -> prlimit -> provider 실행)에서 실행 기록 20회 중 20회 완전. - tsc(tsconfig.node.json, tsconfig.test.json), eslint 통과. |
||
|
|
112c870fe3 |
fix(reference): 처리 중 409를 결과 불명으로 보고 같은 키를 유지한다 (0929/03-01)
문제
참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다
(reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은
멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은
409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고
conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을
지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시
열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번
생긴다(키 [K, K, K']).
고른 방법
분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code
(CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT"
하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의
409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고
있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다.
시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과
"충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다.
버린 대안
- IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속
NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면
같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다.
- 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도
APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가
틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조
변경이다. 이번 범위를 넘어 뺐다.
- 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED
목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이
응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선
요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을
만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다.
위험·한계
- 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state-
contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만
적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로
고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝
백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT
(CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드
템플릿 소유자.
- problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라
Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory).
참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면
referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만
code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다.
- 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다
(reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이
이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다.
"처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다.
- 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드
확인). 동기화 때 같은 수정이 필요하다.
- 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와
run-http-scenario-evidence.ts 출력 문구를 맞췄다.
- 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로
두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다.
검증
- RED(수정 전): reference-production-vertical "keeps the key when the
resend meets the first attempt still in flight" 실패, 키 [K, K, K'].
분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'"
(IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음).
카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치.
- GREEN: 같은 세 파일 23/23 통과.
- 회귀: run-vitest tests/features tests/component tests/contract
tests/integration tests/unit(pnpm을 띄우는 security-followup-archive
제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory
PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을
읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다.
check:ci 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
|
||
|
|
49d8675f97 |
fix(design-system): 컴포넌트 토큰 사용 검사가 이름 전체를 맞춰 본다 (12-01, 12-02)
문제: UI-03 규칙은 source.includes(`var(${token}`)로 독자를 찾는다.
"var(--field-border"가 var(--field-border-invalid) 안에도 있어서, 독자가
0곳이던 --field-border를 통과시켰다. 주석 안의 var(--x)도 독자로 셌다.
그리고 이번 브랜치의 디자인 규칙 4개(포커스 대비, oklab 혼합, 토큰
사용, 첫 글꼴)는 스크립트 본문에 바로 있어서, 규칙을 꺼도 잡는 테스트가
없었다(12-02).
고른 방법:
- 규칙 4개를 scripts/lib/design-system-rules.ts의 순수 함수로 옮긴다.
입력은 CSS 글자와 토큰 맵이고 출력은 실패 메시지다. 메시지 문구와
순서는 그대로다.
- 토큰 독자는 var(--name) 또는 var(--name, ...)처럼 이름 전체가 맞아야
한다. "var"는 대소문자를 무시하고, 사용자 정의 속성 이름은 CSS 규칙
대로 대소문자를 구분한다.
- 토큰 사용 규칙과 oklab 혼합 규칙은 CSS 주석을 지우고 본다(리뷰 probe
B5 우회, B12 오탐).
- oklab 혼합 규칙은 대소문자를 무시한다(B1 `in OKLCH` 우회). CSS
키워드는 대소문자를 구분하지 않는다.
- ui-design-audit.md의 UI-03 행에 다섯 번째 토큰을 적는다.
버린 대안: 12-02가 제안한 --root 인자와 CSS 음성 fixture 폴더. 규칙별
검출을 증명하려면 어차피 실패 메시지를 단언하는 테스트가 필요하고,
순수 함수 단위 테스트가 fixture 파일 없이 같은 것을 증명한다. 게이트의
--fixture 모드와 산출물 스키마는 바꾸지 않았다.
위험·한계:
- 주석 제거는 정규식이라 따옴표 문자열 안의 "/*"를 주석 시작으로
본다. 지금 CSS에는 없다.
- 12-03의 나머지 우회(그라디언트, TSX 인라인, base.css 재정의,
outline-offset 0, feature CSS)와 12-04의 오탐(-apple-system, deg,
알파, color-mix 표면)은 그대로다. 포커스·글꼴 규칙은 주석을 지우지
않는다.
- 게이트의 check:design-system:fixture는 여전히 TSX fixture 두 개만으로
"기대 실패"를 채운다. CSS 규칙 회귀는 test:unit이 잡는다.
검증:
- RED(규칙을 동작 그대로 옮긴 상태): tests/unit/design-system-rules.test.ts
11개 중 5개 실패. "does not count a longer token that starts with the
same name"이 "expected [] to deeply equal [ Array(1) ]"로 실패했다.
나머지 4개는 대문자 OKLCH, 주석 안 혼합, VAR( --x , ...) 형태, 주석
안 독자.
- 고친 검사를 앞 커밋 전 CSS(
|
||
|
|
c7b9cb8818 |
fix(service-worker): SW 빌드가 public/을 다시 복사하지 않게 한다 (0929/06-01)
문제: SW를 ACTIVE로 켜면 build-frontend 6단계의 SW Vite 빌드가 Vite 기본값대로 public/을 dist에 다시 복사한다. 4단계가 프로필로 만든 dist/config.json이 public/config.json(local, demo 인증, http://localhost:8080/, 루트 release manifest)으로 덮어써진다. 빌드와 verify-release는 통과하고 release admission만 거절한다. 그래서 SW를 켠 제품은 local이 아닌 릴리스를 만들 수 없다. VITE_ROUTER_BASE_PATH를 쓰면 RELEASE_MANIFEST_URL도 base를 잃는다. 고른 방법: vite.service-worker.config.ts에 publicDir: false를 넣는다. dist에는 3단계 앱 빌드가 이미 public/을 복사해 두었고, 워커 번들은 public/ 파일을 쓰지 않는다. 같은 repo의 다른 두 번째 Vite 빌드 (scripts/lib/optional-recipe-bundle.ts)도 같은 설정이다. build-frontend.ts 6단계 주석에 이 조건을 한 줄 적었다. 버린 대안: - build.copyPublicDir: false. 복사만 끄고 public 디렉터리는 계속 설정에 남는다. 워커 빌드는 public/을 쓸 일이 없어 publicDir: false가 의도를 바로 말한다. - 앱 빌드 plugin의 closeBundle에서 워커를 만들기, 또는 Vite build()를 configFile: false로 부르는 스크립트. 둘 다 리뷰 5.2절의 대안이다. two-pass 구조를 바꾸거나 파일이 늘어 이 결함에 비해 범위가 크다. 테스트: tests/unit/service-worker-build-output.test.ts는 임시 복사본에서 SW ACTIVE + APP_PROFILE=production + VITE_ROUTER_BASE_PATH=/app/로 실제 build-frontend.ts를 돌린다. 그리고 dist/config.json이 generateRuntimeConfig("production", env) 결과와 같은지 본다(리뷰의 완료 기준). 설정 객체에서 publicDir === false를 보는 테스트는 수정을 다시 적을 뿐이고, 설정이 5단계 생성물 없이는 로드되지 않아 버렸다. 빌드 1회가 약 2초라 unit 계층에 둔다(build-environment-bundle.test.ts와 같은 방식, docs/testing/taxonomy.md의 짧은 child process 규칙). 복사와 빌드는 e2e 도우미 prepareFixtureBuilds를 재사용하고, 빌드별 env 옵션만 추가했다(기존 호출은 그대로). 이 테스트로 0925/06-10(SW Vite 설정의 dist/config.json 읽기 테스트 없음)도 닫힌다. 위험·한계: 하위 경로에서 사전 캐시 URL이 base를 잃는 문제(0929/06-02)와 워커의 runtime config URL 기본값은 그대로다. 이 테스트는 /app/ 빌드의 설정 문서만 보고 워커 설치는 보지 않는다. Vite 8.1.5 동작 기준이다. check:architecture는 pnpm 스크립트로만 돌아서 실행하지 않았다(src는 바꾸지 않았다). 검증: - RED(수정 전): 새 테스트 실패. APP_ENV local(기대 production), AUTH_MODE demo(기대 external), API_BASE_URL http://localhost:8080/, RELEASE_MANIFEST_URL /release-manifest.json(기대 /app/...) - GREEN: 새 테스트 통과(1.9초) - 수정 전후 production + /app/ 빌드 비교: dist 파일 34개로 같음. 수정 후 RELEASE_TARGET=production check-release-admission ADMITTED, 수정 전 rc 1 - node scripts/run-vitest.ts run tests/unit(pnpm을 띄우는 2파일 제외): 164파일 2343건 통과 - tsc tsconfig.test.json, tsconfig.node.json 통과. 바꾼 4파일 eslint 통과 Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2절, 13-build-release-supply-chain.md 실험 E-B |
||
|
|
8576ce16c7 |
fix(design-system): --font-sans가 실제로 그려지는 글꼴을 가리키게 한다 (UI-05)
토큰이 Inter로 시작했지만 Inter를 불러오는 코드가 없었다. Inter가 없는 기기는 자기 글꼴로 그렸고, Inter에는 한글이 없어 한국어는 처음부터 Inter로 그려지지 않았다. 토큰을 시스템 UI 글꼴과 플랫폼별 한국어 글꼴 목록으로 바꿨다(사용자 결정). 한글 웹폰트 배포는 버렸다. 전송량과 글꼴 파일 관리가 생기고, 중립 템플릿에서는 서비스가 브랜드 글꼴로 바꾸면 되기 때문이다. check:design-system이 첫 글꼴이 기본 키워드도 아니고 @font-face로 싣지도 않으면 실패한다. 위험: OS마다 글꼴 모양이 다르다. 시각 테스트 실행 환경의 글꼴 고정은 아직 남았다(UI-05 후반). 검증: 바꾸기 전 검사가 Inter를 보고했고, 바꾼 뒤 통과했다. |
||
|
|
165ed19968 |
fix(design-system): 컴포넌트 토큰을 복사하지 않고 읽게 한다 (UI-03)
계약에 있는 컴포넌트 토큰 4개를 읽는 스타일이 없었다. 기본 버튼은 bg-action을 직접 썼고, 현재 메뉴는 --navigation-active-background의 계산식을 다시 적었다. 그래서 서비스가 이 토큰으로 브랜드를 바꿔도 화면이 바뀌지 않았다. 기본 버튼과 현재 메뉴가 토큰을 읽게 했다. 변형 버튼은 뒤에 오는 같은 우선순위 규칙이라 그대로 덮어쓴다. check:design-system이 계약의 컴포넌트 토큰을 읽는 스타일이 하나도 없으면 실패한다. 위험: 기본 버튼 배경 지정 방식이 utility에서 토큰으로 바뀐다. 보이는 색은 같다. 검증: 바꾸기 전 검사가 토큰 4개를 보고했고, 바꾼 뒤 통과했다. |
||
|
|
bfa7dd9188 |
fix(design-system): 색 혼합을 oklab으로 해서 무채색이 색상각을 끌어오지 않게 한다 (UI-02)
라이트 테마에서 현재 메뉴 배경이 파랑이 아니라 분홍으로 그려졌다. color-mix(in oklch, action 14%, panel)에서 panel이 oklch(1 0 0)으로 색상각 0을 명시해, 보간된 색상각이 255에서 345로 끌려갔다. 15곳의 혼합을 모두 in oklab으로 바꿨다. oklab에는 보간할 색상각이 없다. 흰색을 oklch(1 0 none)으로 바꾸는 방법은 버렸다. 앞으로 생길 무채색 토큰마다 같은 규칙을 기억해야 하기 때문이다. check:design-system이 oklch·lch·hsl·hwb 혼합을 실패로 처리한다. 위험: 섞인 색이 미세하게 달라진다. 시각 골든을 갱신했다. 검증: 바꾸기 전 검사가 15곳을 보고했고, 바꾼 뒤 통과했다. |
||
|
|
35b183b64f |
fix(design-system): 라이트 포커스 링이 모든 표면에서 3:1을 넘게 한다 (UI-01)
라이트 --color-focus가 흰 패널에서 2.33:1, surface-muted에서 1.95:1로 WCAG 1.4.11 기준(3:1)에 못 미쳤다. 포커스 링은 컨트롤에서 3px 떨어져 그려지므로, 대비를 따질 인접색은 컨트롤 뒤의 표면이다. 라이트 포커스를 oklch(0.52 0.15 230)으로 바꿨다. 가장 낮은 대비가 4.24:1이다. 다크는 그대로다. check:design-system이 두 테마에서 포커스 토큰과 표면 토큰 8종의 대비를 계산하고, 3:1 미만이면 실패한다. 안팎 이중 링은 버렸다. 한 색으로 충분하고 링 모양이 바뀌지 않는다. 위험: 포커스 링 색이 진해져 시각 골든이 바뀐다(별도 커밋에서 갱신). 검증: 토큰을 바꾸기 전 검사가 라이트 표면 8종 모두에서 실패했고, 바꾼 뒤 통과했다. 계산식은 브라우저 실측값 2.33:1과 일치한다 (tests/unit/oklch-contrast.test.ts). |
||
|
|
fa3de53106 |
ci(release): drill the downloaded promoted archive in the production stage (13-03)
FE-GATE-021..025 rebuilt from source and drilled that build, so the drilled bytes were not the promoted release. production_gate now downloads the promoted-release artifact, extracts it against immutable_build's digest and runs each drill with --release-root; the CI contract rejects a rebuild. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
15a946fc46 |
ci(gates): require every verification package script to run in a gate or name why not (12-04)
check-ci-contract only caught test files outside the gates; check:* scripts such as check:request-fanout and check:remediation-ledger ran nowhere. The new check reads config/ci/ungated-scripts.json; three checks are now wired into FE-GATE-010 and FE-GATE-012 and the rest carry a reason. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
70f4ff8717 |
fix(scale): keep the ceiling rationale next to the baseline, not in a review document (11-04, 00-02, 14-05)
The growth test read docs/reviews/, which the removal fixtures do not copy and README lets a project delete, so three removal checks failed with ENOENT. The rationale now lives in config/scale/feature-shape-ceilings.json and a guard test keeps code from reading the deletable history documents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
49413af045 |
fix(types): turn on noUnusedLocals and drop the unused declarations (12-12)
VD-01 decision 3 hands unused diagnostics to tsc and turns off ESLint's no-unused-vars for TS files, but tsconfig.base.json never enabled the tsc check (D-19). The flag found 46 unused imports, types and helpers across 22 files; none of them were read, so removing them changes no behaviour. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
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> |