문제
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
문제
레지스트리 호환성 분류기(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