main(d1b9c087)에 하네스 PR #13이 들어가 루트에 `AGENTS.md`, `.claude/`,
`.gitattributes`가 생겼다. 이 브랜치는 그 셋을 루트 등록부에 optional로
미리 적어 두었다.
충돌 둘을 풀었다.
- `scripts/lib/removal-fixture.ts`: main은 문서 복사 목록에 `AGENTS.md`를
더했고 이 브랜치는 그 목록을 등록부의 `fixture-documents` 집합으로
바꿨다. 등록부의 `AGENTS.md` 항목에 그 집합을 적었다.
- `tests/unit/template-feature-removal-documents.test.ts`: main은 문서
목록에 `AGENTS.md`와 옛 a11y 기록 폴더를 더했다. a11y 기록은 이
브랜치에서 `docs/`로 옮겼으므로 `AGENTS.md`만 남겼다.
등록부의 `AGENTS.md`·`.claude`·`.gitattributes`는 이제 추적되는 항목이라
optional을 빼고 역할을 실제 내용으로 고쳤다. 추적되는 루트 항목과
등록부 항목이 서로 남는 것 없이 같다.
검증(desktop): 커밋별 5검사와 merge 게이트 14개, verify:documentation.
정리 단계 미출시 절에 CI 재편(merge job 셋, main 단계 FE-GATE-029,
계약 기준선 삭제, F3 판정 표)을 더한다. 다운스트림이 할 일 13·14(기준선
파일 삭제, merge job 이름과 필수 검사), 옮긴 뒤 확인 한 줄, 계약 표 두
줄, 알려진 제한 한 줄(Gitea runner 실행 미확인)을 적었다.
위험: 다운스트림에 적용해 보지 않았다.
검증(desktop): changelog-review-ids를 포함한 test:unit.
Refs: design-docs repo-structure/03-ci.md 7.3절
정리 단계 미출시 절에 3단계(합치기)와 4단계(배치 규칙 검사)를
더한다. 다운스트림이 할 일 7~12(음성 타입 fixture 기대 줄, 지운
tsconfig, a11y 기록과 스키마 이동, 루트 등록부, CI 계약 기준선)와 계약
표 세 줄, 알려진 제한 둘(R2가 보는 범위, R5의 문자열 검색)을 적었다.
위험: 다운스트림에 적용해 보지 않았다(절의 알려진 제한과 같다).
검증(desktop): `tests/unit/changelog-review-ids.test.ts`를 포함한
test:unit.
Refs: design-docs repo-structure/04-frontend-layout.md 9.2절
복사한 프로젝트가 이 묶음을 받을 때 할 일(루트 CLAUDE.md를 걸러 내지
않기, .claude/ 무시 규칙, 장부 비우기)과 문서 검사 범위가 넓어진 계약
변경을 적는다. 다른 정리 단계 절과 줄이 겹치지 않게 절을 따로 둔다.
검증: 커밋 칸의 해시는 origin/main 8327e221 위로 rebase한 뒤의 값이다.
정리 1단계(PR #11)와 2단계(샘플 역할 이전과 삭제)가 CHANGELOG에 없다.
다운스트림은 이 절을 보고 샘플 사본 처리와 기준선 재승인을 한다.
미출시 절 「48c7695b → 정리 단계」를 맨 위에 더했다. 「먼저 할 일」에
샘플 사본을 지우거나 자기 기능으로 옮기는 법, 레지스트리·CI 계약
기준선과 초기 JS 기록을 다시 받는 법, NOT_A_FEATURE 폴더 처리를 적고,
보안·계약 변경 표와 알려진 제한을 적었다. 절의 해시는 모두 이 브랜치
조상이다(git merge-base --is-ancestor로 확인).
위험: 두 다운스트림에 시험 병합을 하지 않아 충돌 수를 모른다.
검증: tests/unit/changelog-review-ids.test.ts 통과(desktop test:unit).
문제: 1106 절의 03-01 행, "먼저 할 일" 2단계, 03-03 행, 알려진 제한 03-01
줄은 입력 검증(kind VALIDATION_REJECTED)이 재전송 뒤 결과 불명을 푼다고
적는다. b41990c 뒤에는 짝 백엔드 표의 400 VALIDATION_FAILED와 400
IDEMPOTENCY_KEY_INVALID만 푼다. 6142cc8은 VALIDATION_FAILED가 요청 내용 검사여야
한다는 전제를 계약 문서 6.1절에 적었다.
고른 방법: 그 행들만 고치고 두 커밋 해시를 커밋 칸에 더한다. 참조 기능처럼
problem details를 읽는 기능의 422 입력 검증이 결과 불명으로 남는 것을 알려진
제한 03-01 줄에 적는다.
버린 대안: 수정 커밋에 함께 넣기(그 커밋 자신의 해시를 적을 수 없다).
위험·한계: 문서만 바꾼다. 해시 대조는 머리말의 사람 단계다(1106/14-02).
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1106/03-01 (final review FR-01), 1106/03-01 (final review FR-02)
문제: diff 리뷰 DR-02·DR-04·DR-05 조치(`eb03dab`, `efe11f1`, `95141f1`)가
CHANGELOG 1106 절의 16-01·07-02·11-01 행을 고쳤지만 커밋 칸에 자기 해시를
적지 못했다. 같은 커밋 안에서는 자기 해시를 알 수 없다.
고른 방법: 합친 뒤 세 행의 커밋 칸에 해시를 더한다. 문장은 바꾸지 않는다.
위험·한계: 없다. 세 해시는 `git merge-base --is-ancestor`로 이 브랜치 끝의
조상임을 확인했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
Refs: 1106/16-01 (diff review DR-02), 1106/07-02 (diff review DR-04), 1106/11-01 (diff review DR-05)
문제: 1106 절의 03-01·03-03 행과 "먼저 할 일" 2단계, 알려진 제한은 같은 키
재전송의 쓰기 전 거절을 모두 결과 불명으로 적는다. 80e7f1d 뒤에는 같은 요청이
매번 받는 거절(입력 검증, 400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID)이
결과 불명을 푼다. 08-01 행은 다시 마운트한 폼의 확인이 "지금 값으로 성공을
정한다"고 적지만 145be2d 뒤에는 값을 건드리지 않는다.
고른 방법: 그 행들만 고치고 두 커밋 해시를 커밋 칸과 괄호에 더한다. 기능이
선언한 결정적 거절이 결과 불명으로 남는 것은 알려진 제한 03-01 줄에 적는다.
버린 대안: 각 수정 커밋에 함께 넣기(그 커밋 자신의 해시를 적을 수 없다).
위험·한계: 문서만 바꾼다. 해시 대조는 머리말의 사람 단계다(1106/14-02).
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1106/03-01 (diff review DR-01), 1106/08-01 (diff review DR-03)
문제: 9c4cddc의 report는 "로그인 라우트의 paramsSchema = 한 자원 GET의
입력 스키마"만으로 실패 화면 기록을 기대한다. 그 라우트의 페이지가 그
GET을 실제로 부르는지는 보지 않는다. 손으로 쓴 기능이 하위 항목 작성 폼
(`/things/:thingId/parts/new`)의 paramsSchema로 상세 GET과 같은
ThingParams를 쓰면, spec은 한 자원 응답을 보지 못해 기록을 남기지 않고
report가 `a11y.json not written:`으로 FE-GATE-009를 실패시킨다. 그런데
errors.md는 "spec의 기록 호출을 본다. 기능 파일은 고치지 않는다"고만
안내했다. 이 경우 고칠 곳은 기능의 라우트 스키마 ID다.
고른 방법: 리뷰의 첫 방향. report 판정은 그대로 두고 안내를 고친다.
errors.md 행이 두 원인(spec이 기록을 놓침 / 페이지가 그 GET을 부르지
않음)과 각각 고칠 곳을 적는다. 매뉴얼 01 6단계에 같은 경우와 고치는 법
(그 라우트에 자기 paramsSchema)을 더했다. CHANGELOG 1106 절 11-01 행에
같은 줄을 더했다. report의 실패 문장 끝에도 같은 안내를 붙였다. 판정
조건과 문장 앞부분은 그대로라 단위 테스트의 기대(`stringContaining`)도
그대로다.
버린 대안: spec이 "기대했지만 보지 못함"을 따로 기록하고 report가 그
경우를 다르게 다룬다. report 판정이 바뀌어 이번 범위(문서) 밖이다.
위험·한계: 같은 스키마를 쓰면서 그 GET을 부르지 않는 라우트는 여전히
실패한다. 안내로만 풀린다. 그 라우트에 스키마를 따로 두면 FE-REG-SCHEMA
행과 route codec이 하나씩 는다.
검증: desktop batch에서 확인. 테스트 없음(문서와 실패 문장 끝).
corepack pnpm verify:documentation
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
tests/unit/changelog-review-ids.test.ts
Refs: 1106/11-01 (diff review DR-05)
문제: e7b1b01 뒤 정책 테스트는 HTTP 자리 스키마의 행이
unknownFieldPolicy를 빼면 실패하고, 적으면 탐침 결과와 비교한다. 탐침이
객체에 닿지 못하는 검증기(두 탐침을 모두 루트에서 거절: `responseBody:
"NONE"` 출력의 z.undefined(), 문자열·null 본문)는 결과가 UNREACHED다.
행 타입은 REJECT_UNKNOWN·STRIP_UNKNOWN만 받으므로, 그런 operation은 행을
어떻게 적어도 통과하지 못한다. 칸을 빼면 `row states no
unknownFieldPolicy`, STRIP_UNKNOWN을 적으면 `row STRIP_UNKNOWN, validator
UNREACHED`다. 템플릿에는 그런 operation이 없어 다운스트림에서 난다.
고른 방법: 리뷰의 가장 작은 방향. 탐침 결과가 UNREACHED인 자리는 정책
비교에서만 빼고, direction은 그대로 요구한다. 두 검사를 슬롯·행을 받는
함수(directionProblems, policyProblems)로 꺼내, 설치된 descriptor 검사와
가짜 스키마 검사가 같은 함수를 쓴다. 새 describe가 z.undefined() 같은
NoContent 검증기로 탐침이 UNREACHED인지, 행이 direction을 빼면 실패하는지,
정책을 빼거나 적어도 통과하는지 본다. 매뉴얼 01, errors.md, CHANGELOG
1106 절의 먼저 할 일 1과 07-02 행에 적었다.
검사를 느슨하게 한 것이 아닌 이유: 탐침은 객체가 없는 스키마의 모르는
필드 정책을 판정할 수 없다. 그 자리의 비교는 맞는 답이 없는 질문이었다.
e7b1b01 전에는 칸을 빼면 이 자리 전체를 건너뛰었다. 지금은 direction을
요구하므로 그때보다 넓다. 객체에 닿는 스키마의 정책 비교는 그대로다.
버린 대안: 행 타입에 객체가 아닌 본문용 값을 더한다. src/contracts의
SchemaDefinition 모양, 분류기, 기준선이 함께 바뀐다.
위험·한계: 행이 UNREACHED 스키마에 적은 정책 값은 아무도 검사하지 않는다.
루트에서 이슈 하나로 거절하는 union(zod `invalid_union`, 예:
strict 객체 | null)도 UNREACHED가 되어 정책 비교에서 빠진다(추론, 실행하지
않음). 고친 곳이 테스트 파일 자신이라 RED는 테스트 파일만으로
만들 수 없다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts
Refs: 1106/07-02 (diff review DR-04)
문제: af3344b가 더한 Playwright spec 본문 검색은 대소문자를 무시하고
`_`를 이름 경계로 봤다(`(?<![A-Za-z0-9-])…(?![A-Za-z0-9-])`, `i`).
create:feature는 한 단어 ID(`messages`, `reports`)를 받고 폴더 이름도
ID와 같다. 그래서 `messages` 기능을 지우면 템플릿 자신의
tests/e2e/accessibility.spec.ts(`KO_MESSAGES`)와 scrollbar-gutter
visual spec이 잔여로 잡혀 드릴이 실패한다. `status`·`reports`는 템플릿
spec 여러 개가 평범한 단어로 쓴다. errors.md는 목록에 템플릿 파일이
나오면 템플릿 결함이라 적으므로 제품은 고칠 곳이 없다.
고른 방법: 메인 세션 기준대로 적힌 그대로(대소문자 구분) 찾고, 경계는
식별자 문자 `[A-Za-z0-9_-]`다. 폴더 이름이 ID와 다르면 같은 규칙을 쓴다.
그런데 이 둘만으로는 `status`·`reports`가 0건이 되지 않는다. 템플릿
spec에 `status: 200`, `getByRole("status")`, 테스트 제목의 "reports"가
있다(git grep). `getByRole("status")`는 따옴표 안 한 단어라 따옴표나
문맥 규칙으로도 실제 참조와 구별되지 않는다. 그래서 `-`가 든 이름만 spec
본문에서 찾는다. 한 단어 ID·폴더 이름은 spec 본문 검색에서 빠진다.
검사를 좁히는 변경이지만 이 발견이 바로 그 거짓 양성이다. 거짓 양성은
제거를 막고 고칠 길이 없는 반면, 빠지는 쪽(한 단어 ID만 본문에 적은
spec)은 1106/16-01 전처럼 다음 CI의 브라우저 게이트가 잡는다.
테스트: 템플릿의 spec 파일 전부를 사본에 옮겨 `product-feature`,
`messages`, `status`, `reports`로 돌리면 잔여 0건이다. 적힌 그대로의
ID와 다른 폴더 이름(`invoice-docs`)은 잔여이고, `Invoice-Feature`와
`invoice-feature_v2`는 아니다. 매뉴얼 01 11단계, errors.md, CHANGELOG
1106 절의 16-01 행·확인 2·알려진 제한을 고쳤다.
버린 대안: 따옴표나 `/features/` 문맥만 센다. `getByRole("status")`가
남고, `test.describe("invoice-feature")` 같은 실제 잔여도 문맥에 따라
빠진다. 한 단어 ID를 막는 생성기 규칙은 이 수정 범위 밖이다.
위험·한계: `-`가 든 흔한 이름(예: `read-only`)을 ID로 쓰면 템플릿 spec이
그 이름을 쓸 때 다시 거짓 양성이 난다. 템플릿 spec 0건 테스트는 네
ID만 본다. src 쪽 부분 문자열 검색(1105/16-04)은 그대로다. CHANGELOG
행의 커밋 칸에는 이 커밋 해시를 아직 적지 않았다(같은 커밋에 자기 해시를
적을 수 없다).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
Refs: 1106/16-01 (diff review DR-02)
문제: 2026-11-06 리뷰 조치 27개 커밋(`302d3a5..5cfc3a65`)이 CHANGELOG에
없다. 몇 커밋은 [계약] 행을 CHANGELOG 담당에게 남겼다(13-01 기준선,
02-01 포트 옵션, 03-01 문구 키, 03-03 `resendSafe`, 04-01·04-02, 01-01의
백엔드로 넘김).
고른 방법: 아래 1105 절 위에 새 미출시 절을 둔다. 범위는 `bbde570`(PR B
끝) → 브랜치 `fix/maturity-review-2026-11-06`이다. 이유:
- 머리말 규칙상 절마다 절 머리에 범위를 적고, 그 절의 해시는 모두 그
범위에 있다. 1105 절에 합치면 그 절의 범위(`409d72e` → 11-05-b)와 "해시는
모두 범위 안" 문장이 틀린다.
- 1105 절은 그 범위 끝 `bbde570`의 상태다. 리뷰도 지난 절의 값을 범위 끝
값으로 본다(1106 15 영역의 1103/15-02 판정). 그래서 이 범위가 1105 절의
"지금 값"을 바꾼 것(초기 JS 기록, 6.1절 대조 테스트 파일, 0929/03-03
재전송 조건, 실행 격리)은 새 절에 적고 1105 절은 고치지 않았다.
- 예외는 처음부터 틀린 문장이다. 1105 "먼저 할 일" 1~3단계는 이 라운드의
`2f0f2bb`·`06357e9`이 이미 고쳤고, 새 절 머리에 그 사실을 적었다.
- 1105 절 60행의 `tests/unit/backend-contract-pin.test.ts`는 바꾸지
않았다(지시와 다름). `bbde570`에서는 맞는 이름이다. 새 절 테스트 줄에
6.1절 대조가 `backend-contract-pin-document.test.ts`로 옮겼다고 적었다.
내용은 커밋 본문과 코드에서 옮겼다. 04-02는 [계약] BREAKING으로 적었다.
타입 인자 없이 부르는 호출은 descriptor 타입을 추론해, 입력이 맞지 않거나
`outcome.value`를 겹치지 않는 타입으로 단언한 호출이 `check:types`에서
실패할 수 있다. 두 다운스트림은 이 함수를 부르지 않는다(grep). 커밋은 `!`
없이 들어갔다. "먼저 할 일"은 여섯 단계다: 스키마 행 두 칸(07-02), 문구
키(03-01), 토큰 CSS(08-03), IDEMPOTENT 확인(03-03), CI 기준선(13-01),
poll 타입(04-02). 01-01의 백엔드 요청은 알려진 제한 "백엔드로 넘김"에 둔다.
버린 대안: 1105 절에 합쳐 순 요약으로 다시 쓰기. PR B가 아직 main에 없어
한 동기화 단위로 볼 수도 있지만, 1105 절의 해시 범위와 리뷰가 확인한 75개
해시 대조를 다시 해야 하고, 이미 1105 절을 읽은 다운스트림이 무엇이 바뀌었는지
찾기 어렵다.
위험·한계: 두 다운스트림에 적용해 게이트를 돌려 보지 않았다. 08-03 시각
spec이 제품 셸에서 도는지, 토큰 CSS가 빠졌을 때 가림막이 투명해지는지는
코드를 읽은 판단이다. 이 절의 해시는 이 범위의 커밋 27개와 기준점
`bbde570`, 리뷰 기록 `302d3a5`뿐이다. 1105 절의 해시는 이 범위 밖이라
새 절에 적지 않았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts tests/unit/documentation-readiness.test.ts
노트북에서는 같은 정규식을 grep으로 흉내 내 괄호 안 라운드 없는 ID와
꼴을 벗어난 참조가 0건인 것만 봤다.
Refs: 1106/01-01, 1106/02-01, 1106/03-01, 1106/03-02, 1106/03-03, 1106/04-01, 1106/04-02, 1106/05-01, 1106/06-01, 1106/06-02, 1106/07-01, 1106/07-02, 1106/08-01, 1106/08-02, 1106/08-03, 1106/09-01, 1106/10-01, 1106/11-01, 1106/12-01, 1106/12-02, 1106/13-01, 1106/14-01, 1106/14-02, 1106/15-01, 1106/16-01, 1103/15-02
문제: D7 커밋 `287dc6f` 본문의 "늘어난 곳"이 1105/03-01과 1105/08-03에
적은 해시 둘은 통합에서 다시 짓기 전 해시라 `bbde570`에서 닿지 않는다
(`git merge-base --is-ancestor` rc=1). 같은 변경은 이 이력에서 `5c0b37e`,
`f849d78`이다(`git log --format='%h %s' 409d72e..bbde570`, rc=0). 원격
clone에는 두 객체가 없다. 통합 절차에 CHANGELOG·커밋 본문의 해시를 범위와
대조하는 단계가 없다.
고른 방법: 올린 이력은 고쳐 쓰지 않는다(`287dc6f`을 amend·rebase하지 않음).
1105 README 16.2절 D7 행에 본문의 두 해시가 다시 짓기 전 것이라는 것과 이
이력의 해시를 적는다(지시대로 그 행만). 닿지 않는 해시는 새로 적지 않는다.
적으면 아래 대조에 다시 걸린다. CHANGELOG 머리말의 "그 절의 해시는 모두 그
범위에 있다" 뒤에, 해시를 다시 쓴 뒤 절과 범위 커밋 본문의 해시를
`git merge-base --is-ancestor`로 대조하고 결과를 리뷰 README 조치 절에 적는
한 단계를 둔다(리뷰의 대안 b).
버린 대안: 해시를 대조하는 단위 테스트(대안 c). 싸지 않다.
- 복사한 프로젝트에는 템플릿 이력이 없거나(tech-log는 이력 없이 3-way로
옮긴다) CI checkout이 얕을 수 있어, 테스트가 그때 건너뛰어야 한다. 조건부로
도는 테스트는 이번 라운드 지시가 막는다.
- 커밋 본문은 작업 트리가 아니라 `git log` 범위를 읽어야 하고, 이미 올린
`287dc6f`이 영구히 걸리므로 예외가 필요하다. 예외 추가도 지시가 막는다.
- CHANGELOG에는 다른 repo 해시(`d3810a0` 등)가 섞여 있어 repo 표시 규칙부터
정해야 한다.
위험·한계: 대조는 사람이 하는 단계다. 빼먹으면 같은 일이 다시 난다. 완료
기준 "다음 통합 기록에 그 대조 결과가 있다"는 이번 라운드를 합칠
오케스트레이터가 채운다. 새 clone에서 `git show 287dc6f` 본문의 두 해시는
여전히 열리지 않는다.
검증: 문서만 바꿨다. desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
(새 괄호 `(1106/14-02, 1105 README 16.2)`가 참조 꼴을 지킨다)
git merge-base --is-ancestor 5c0b37ebbde570 && git merge-base --is-ancestor f849d78bbde570
Refs: 1106/14-02
문제: 미출시 절 "먼저 할 일"의 세 설명이 코드와 다운스트림 모양과 다르다.
(1단계) TechLog를 "감싸지 않는 백엔드"라 적는다. TechLog 백엔드는 Envelope로
감싸고 출력 검증기 `envelopeData`가 직접 벗긴다(tech-log
`tech-log-studio-contract-contribution.ts`). 같은 CHANGELOG 아래 절은
"출력은 Envelope 뼈대만 검사"로 적어 두 절이 다르다. "Envelope면
`ENVELOPE_V1`"을 따르면 실행기가 벗긴 `data`를 검증기가 다시 벗기려다 모든
응답이 실패한다. 빠뜨리면 `satisfies`에서 실패한다는 문장도 두 제품처럼
`as`로 단언한 descriptor에는 맞지 않는다.
(2단계) `commandMutationIdentity`가 `requiresIdempotencyKey`를
`retrySemantics === "KEYED"`로 다시 계산한다는 말이 없다
(`src/contracts/server-state.ts`). tech-log 관리 정책은 `true`를 적었고
descriptor는 `NEVER`라 값이 `false`로 바뀌고, 키를 요구하는 제품 가드가
저장마다 던진다. `check:types`는 통과한다.
(3단계) "계약 조립이 거절해 부팅이 멈춘다"고 적는다. 부팅은 빈 기여 목록만
조립하고(`installed-contract-contributions.ts`), 기능의 계약 기여는 그 기능
실행부를 적재할 때 `install`이 조립한다. 앱은 뜨고 그 기능 라우트에 처음
들어갈 때 실패한다.
고른 방법: 세 단계의 문장을 코드에 맞춘다. 1단계는 TechLog가 왜 `NONE`인지와
`ENVELOPE_V1`로 바꿀 때의 결과를 적고, `as` 단언에서는 타입 검사가 잡지 않는다고
덧붙인다. 2단계는 다시 계산하는 규칙, tech-log 관리 쓰기 예, 바꾸기 전에 값을
맞춰 보라는 한 줄을 붙인다. 3단계는 실패 시점과 CI에서 먼저 잡는 검사
(`test:unit`, `check:registries`)를 적고, "옮긴 뒤 확인" 1의 3단계 검사도
같이 고친다. 아래 절의 TechLog 문장은 이미 맞아 그대로 둔다.
위험·한계: `as` 단언이 빠진 `responseEnvelope`를 잡지 않는다는 것과 tech-log
관리 쓰기가 지금 실행기에서 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절된다는 것은
코드를 읽은 추론이고, 문서에도 그렇게 적었다. tech-log sync 브랜치에서
2단계 뒤 관리 저장을 해 보지 않았다.
검증: 문서만 바꿨다. CHANGELOG는 verify:documentation 밖이다. desktop
batch에서 확인.
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
Refs: 1106/14-01
문제: 1103/16-05로 `BoundMutation.operationId`가 brand 타입이 됐고, 그 값은
`commandMutationIdentity`만 만든다. 이 함수는 descriptor 모양
`{ contract: { operationId, method, retrySemantics } }`만 받는다. CHANGELOG
"먼저 할 일" 2단계와 매뉴얼 01 7단계는 descriptor 상수 길만 적는다. V3
descriptor가 없는 쓰기(Fileserver 업로드 client는 `upload(request)`만 있다)와
테스트 fixture는 길이 없어, 따라 하면 `check:types`에서 막힌다. 템플릿은
자기 테스트에 `tests/helpers/mutation-operation-id.ts`를 두었지만 어느 문서도
그 helper를 말하지 않는다. 매뉴얼 01 안에서도 "손으로 적은 ID에 오타가 있으면
저장이 항상 실패한다"(BREAKING 전 동작)와 "문자열로 직접 적으면
`check:types`가 실패한다"가 서로 다르다.
고른 방법: 문서만 고친다(리뷰의 대안 A). descriptor 없는 쓰기는 descriptor
모양 객체를 넘기고, 키가 필요하면 `KEYED`, 아니면 `NEVER`를 적는다고 쓴다.
대조할 descriptor가 없어 그 ID는 intent 이름일 뿐이고 오타를 잡는 검사가
없다는 것도 적는다. 테스트는 `testMutationOperationId`를 쓰고
`requiresIdempotencyKey`는 따로 적는다. 매뉴얼 01의 "저장 때 실패" 문장은
손 객체를 넘긴 경우로 좁히고, "못 잡음" 항목을 descriptor가 있는 쓰기와 없는
쓰기로 나눈다. 버린 대안: 이름 있는 함수(B)나 Fileserver 업로드 descriptor
상수(C)를 공개하기. 공개 API가 늘고 코드 변경이라 이 문서 브랜치의 범위
밖이다. 리뷰도 A를 가장 작은 길로 적었다.
위험·한계: 손 객체가 공식 길이 된다. descriptor 없는 쓰기의 ID 오타는
여전히 아무 검사도 잡지 않는다(문서에 그렇게 적었다). 두 다운스트림의 손
ID 정책 중 몇 개가 이 길로 가야 하는지는 세지 않았다.
검증: 문서만 바꿨다. desktop batch에서 확인.
corepack pnpm verify:documentation (매뉴얼 01이 새로 적은 경로
`tests/helpers/mutation-operation-id.ts`와 script `check:types:test`가 있는지)
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts tests/unit/documentation-readiness.test.ts
Refs: 1106/09-01
문제: 1105 리뷰 README에는 수정 라운드의 기록이 없다. 1103 리뷰는 14절에
방법·결정·통합 문제·발견별 상태를 적었다. 초기 JS 예산 상향(D7)은 결정이라
이유·대안·재검토 조건을 남겨야 한다.
고른 방법: README 16절에 방법, 결정 표(7절 D1~D6의 결과, 새 D7과 그 근거: 커밋별 증가와 올린 뒤
여유), 합칠 때 생긴 문제와 고친 위치, 새 발견 48건·1103 이월 22건·그 밖의
이월 상태, 돌린 검사와 돌리지 않은 것을 적는다. CHANGELOG의 예산 행에 예산
커밋 `287dc6f`를 더한다.
버린 대안: 결정을 `docs/improvement/` 결정 색인에 적기. 그 폴더는 매뉴얼
PR(#6)과 겹쳐 건드리지 않는다.
위험·한계: 해시는 이 브랜치 끝에서 닿는 커밋이다. 브랜치를 다시 쓰면 함께
고쳐야 한다.
검증: desktop batch에서 확인.
옆 백엔드 checkout 없는 verify:documentation
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts tests/unit/documentation-readiness.test.ts tests/unit/deletable-history-documents.test.ts
Refs: 1105/15-02, docs/reviews/2026-11-05-maturity-review/README.md
문제: 1105 PR B의 수정이 템플릿 초기 JS를 1,184 B 늘렸다(202,927 →
204,111 B, 초기 파일 26 → 27개, `0fee3fe`). 예산 204,800 B까지 남은 여유가
689 B로, 기능 하나가 더하는 768 B보다 작다. FE-GATE-020의 생성 기능
드릴이 기능 둘을 더하면 205,463 B가 되어 check:bundle이 "over by 663"으로
실패한다. PR A 끝(`a793b83`)에서는 통과했다.
늘어난 곳(desktop, 2026-11-06, 커밋마다 `--initial-baseline`으로 잼):
- 1105/03-01 `ab0d4a1` +327 B: 조립 때 `refusedBeforeWrite` code 검사
- 1105/08-03 `7ce9bf1` +293 B, 초기 파일 +1: `navigation-policy` 공유 청크
- 1105/02-01 `f738348` +251 B: scope closer 진단
- 계약·앱 코어 브랜치를 합칠 때 +148 B
- 나머지 +165 B: realtime +72 B, 05-01 +46 B, 테스트 +23 B, 03-02 +15 B와
합칠 때의 압축 차
고른 방법: `config/performance/budgets.json`의 `initialJsGzipBytes`를
204,800 → 206,848 B(202 KiB)로 올린다(메인 세션 결정, 2026-11-06). 늘어난
바이트는 비대가 아니라 검사와 진단 코드다. 이유와 재검토 조건을
`docs/operations/performance-evidence.md`에, 계약 행을 CHANGELOG 미출시 절에
적는다. 초기 파일 상한을 26 → 32로 올린 `2fef27d`와 같은 방식이다.
버린 대안: 줄이기. 08-03 청크를 기존 청크 그룹에 넣으면 약 240 B가 돌아올
것으로 본다(추정, 재지 않음). 663 B에는 모자라서 03-01·02-01의 런타임 검사를
빌드 시점으로 옮기는 설계 변경이 더 필요하다. 리뷰 라운드 중간의 설계
변경은 다음 라운드의 숫자를 흐린다.
위험·한계:
- 올린 뒤 여유는 템플릿 그대로 2,737 B(768 B 기능 셋), 드릴이 기능 둘을
더한 뒤 1,385 B다. 기록 대조 허용치 256 B(1105/15-02)는 두 여유보다 작다.
- 재검토 조건: 예산을 다시 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을
정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터
본다. 이 상향은 13-03을 정하지 않는다.
- 기준선 기록(`initialJavascript`)은 앞 커밋 `0fee3fe`이 측정 스크립트
`--initial-baseline --write`로 다시 썼다. 이 커밋은 기록을 바꾸지 않는다.
검증: desktop batch에서 확인.
corepack pnpm ci:gate FE-GATE-020 (CI env)
node scripts/run-vitest.ts run tests/unit/performance-budgets.test.ts tests/unit/check-bundle-output.test.ts tests/unit/feature-shape-growth.test.ts
Refs: 1105/15-02
문제
새 미출시 절(409d72e → fix/maturity-review-2026-11-05)에는 PR A 조치 셋만
있다. PR B(fix/maturity-review-2026-11-05-b)는 그 위에 비병합 커밋 70개를
쌓았고, 그중 `!` 커밋 다섯(1105/03-01, 1105/04-02, 1103/16-01, 1103/16-05,
1103/11-01)은 복사한 프로젝트가 코드를 바꿔야 한다. 커밋 본문이 "CHANGELOG
[계약] 행이 필요하다"고 적은 변경과 결정 대기·백엔드로 넘김·일부 항목도 이
절에 없다. 11-03 절의 알려진 제한 세 줄(기능 라우트 첫 진입, 참조 기능의
responseEnvelope, SW composeProduct 칸)은 PR B가 바꿨다.
고른 방법
- 절 머리의 범위 끝을 fix/maturity-review-2026-11-05-b로 바꾸고, 앞의 세
조치가 PR A(PR #5)에 있다고 한 줄로 적었다. PR A 행은 그대로 두었다.
- 11-03 절과 같은 모양으로 "먼저 할 일(BREAKING)"을 두었다. 옮기는 법 10단계
(responseEnvelope, MutationOperationId, refusedBeforeWrite 플랫폼 code,
poll execute, a11y.json v2, scope participant label, 레시피 복사본,
SW 칸, 제품 게이트의 workflow 재생성, 기능 안 adapters/ 밖 import)와 옮긴
뒤 확인.
- 보안·계약 표에 [계약] 행을 더했다: CI·게이트(13-02, 12-01 기준선,
12-04 TEST_RUN_ID·RUN_OUTPUT_ROOT·TEST_*_PORT, 12-02, 14-01·14-03,
0929/12-03 아키텍처 규칙, a11y.json, lab 예산, 기록 허용 오차, test:all,
제거 드릴 잔여), HTTP·계약, server-state, realtime, bootstrap·세션,
저장소·캐시(scope_participant 진단 키, chunkSweep deprecated,
UNREADABLE·REHYDRATE, AUTH_REDIRECT_TRANSACTION 행), SW·호스팅. `!` 커밋
다섯은 **BREAKING**으로 표시했다. 나머지는 "그 밖의 수정"에 영역별로 적었다.
- 이 절의 알려진 제한에 커밋 본문의 결정 대기·백엔드로 넘김·일부를 한 줄씩
적었다. 기능 라우트 첫 진입 줄은 지금 상태(lab이 EXAMPLES_UI를 500 ms로
잰다, 요청 두 묶음은 남음)로 적었다.
- 11-03 절의 세 줄은 그 범위 끝의 사실로 두고 위 절에서 바뀐 것을 붙였다.
- PR B의 비병합 커밋 70개가 모두 행이나 줄에 해시로 있다. 기준점 409d72e를
빼면 이 절의 해시는 모두 409d72e..이 브랜치 끝에 있다.
위험·한계
- 이 브랜치(fix/r1105-docs-v2) 커밋의 해시도 인용했다. 통합 때 이 브랜치를
다시 쌓으면(fixup 접기 등) 그 해시 11개를 새 값으로 바꿔야 한다.
- 안내를 두 다운스트림 코드에 적용해 보지 않았다. 1105/12-01 기준선 행의
"제품이 기준선을 다시 기록해 두었다면 다시 기록한다"는 67082cc 본문에서
추론한 것이다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1105 PR B (fix/maturity-review-2026-11-05-b)
문제
CHANGELOG 머리는 리뷰 ID를 `MMDD/NN-MM`과 `F-N`으로만 정한다. 본문에는
`1101 README 14.3`, `1103 07 영역 P-07-06`, `백엔드 리뷰 1101/02-01`,
"리뷰 조치 X2"가 섞여 있다. 마지막은 라운드가 없어 어느 리뷰인지 찾을 수
없다. changelog-review-ids 테스트는 `NN-MM`·`F-N`만 본다(1101/14-02 잔여).
고른 방법
- 머리에 세 꼴을 적었다: `MMDD README N.N`(다시 돌린 항목은 뒤에 `X2`),
`MMDD NN 영역 P-NN-NN`, `백엔드 리뷰 MMDD/NN-MM`. 지금 본문의 참조는 이
꼴이다.
- "리뷰 조치 X2"를 `1103 README 14.6 X2`로 고쳤다(2fef27d 등의 Refs가 그
절을 가리킨다).
- 테스트 "cites README sections and other review references with their
round": 괄호 안 토큰 중 README 절·X 번호·P-ID·백엔드 리뷰를 담은 것이 이
꼴과 다르면 실패한다.
- 버린 대안: README 절도 `MMDD/README-14.3` 같은 한 꼴로 바꾸기. 본문 9곳과
커밋 Refs의 쓰임을 함께 바꿔야 해서 얻는 것보다 바꿀 것이 많다.
위험·한계
- 괄호 밖에 적은 참조는 보지 않는다(기존 테스트와 같다).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
RED: 부모 CHANGELOG에서 새 테스트가 ["리뷰 조치 X2"]로 실패한다.
Refs: 1101/14-02
문제
"옮기기 전" 2단계는 "제품이 고친 템플릿 파일을 뽑는다"며 memento 7개,
tech-log 11개를 적는다. 실제로 af3d8e6 뒤 고친 템플릿 src 파일(기능·
context 폴더 밖)은 memento 26개(수정 23, 추가 3), tech-log 40개(수정 38,
추가 2)다(리뷰 영역 14 E-4). 빠진 파일 중 일부는 이 묶음에 옮길 제품 소유
자리가 있고, 일부는 없다. 목록에 없으면 동기화 때 충돌이나 조용한 유지로
드러난다.
고른 방법
- 두 다운스트림(memento d3810a0, tech-log 7a4e201a)에서
`git diff --name-status af3d8e6 HEAD -- src`와 파일별 diff를 읽어(쓰기
없음) 2단계에 세 항목을 더했다.
- 자리가 있는 것: tech-log release-artifacts.ts의 TECH_LOG_*_SOURCE
→ PRODUCT_RUNTIME_CONFIG_FIELDS, memento offset-upload.ts와 HTTP 배럴
export → product-composition 쪽 제품 파일(그 파일은 contracts만
import한다), tech-log 라우팅 파일과 참조 기능 계약의 layoutGroup → 3단계
기능 모듈 길.
- 자리가 아직 없는 것: memento의 if-match 요청 헤더, SW 오프라인 shell과
사전 캐시 확장자, 저장소·OPFS 이름, 앱 이름 문구, 브랜드 토큰·
primitive. tech-log의 AppFailure.detail, BoundMutation.identity,
null을 빈 상태로 보기, 폼, 디자인 시스템, 문구, 전역 스타일 import.
- 템플릿 결함 후보: tech-log application-query.ts의 "마운트한 같은 턴의
저장" 수정. 템플릿은 재현하지 않았다.
- 알려진 제한에 "자리 없는 것은 이 묶음이 옮길 곳을 주지 않는다"를 더했다.
- 버린 대안: 파일마다 옮길 곳을 정하기. 템플릿에 자리를 만들지는 각각
설계 결정이다(결정 대기).
위험·한계
- 일부다. 자리 없는 항목마다 템플릿이 자리를 줄지, 제품 fork로 둘지는
정하지 않았다. 안내를 제품 코드에 적용해 게이트를 돌리지 않았다.
- 분류는 diff를 읽은 판단이다. 파일 안의 모든 변경을 확인하지는 않았다
(예: tech-log 디자인 시스템 primitive 3개는 줄 수만 봤다).
검증
- 문서만. desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1103/14-02, 0929/14-03, 0929/14-06
문제
11-03 절의 realtime BREAKING 행은 "poll은 던지는 execute도 lease 안에서
다시 시도한다"고 적는다. 그 범위 끝(8a44226)에서는 사실이지만, 같은 동기화
때 함께 받는 위 절의 05330e3(1105/04-02)이 던지는 execute를 재시도 없이
PROTOCOL_MISMATCH로 끝내게 바꿨다. 두 절을 함께 받는 제품은 아래 절의
문장대로 재시도를 기대한다. 그 커밋 본문도 이 행이 맞지 않는다고 적는다.
고른 방법
- 아래 절 행은 그 범위 끝의 사실로 두고, 위 절에서 바뀐 것과 새 결과를 한
문장으로 붙였다. 위 절의 BREAKING 행은 PR B 행을 쓸 때 05330e3 본문으로
적는다.
- 버린 대안: 아래 절 문장을 지우기. 그 절은 한 동기화 단위의 순 요약이라
위 절만 받지 않은 프로젝트가 읽을 수 있다.
위험·한계
- 문서만 바꿨다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1105/04-02
문제
미출시 11-03 절(752a61f → fix/maturity-review-2026-11-03)은 머리 규칙이
"최종 상태만 적는다"인데 세 곳이 중간 상태나 틀린 이름을 적는다.
- 초기 JS 파일 상한: BREAKING 7단계와 FE-GATE-012 [계약] 행이 "26개"다.
코드는 32다(config/performance/budgets.json, 2fef27d). 같은 절의 X2 줄은
32라고 적는다. [계약] 행이 인용한 1b8cb12(26으로 올림)는 범위 안에서
2fef27d가 다시 바꾼 중간 상태다.
- 알려진 제한 머리가 "이 절을 쓴 끝 커밋(f887817)"이다. 범위 끝은
8a44226이다.
- "옮긴 뒤 확인" 2단계가 "로컬 merge 게이트 14개 중" 목록에
verify:documentation(FE-GATE-017)과 제품 기능 제거 드릴을 둔다.
FE-GATE-017은 documentation 단계이고(config/ci/gates.json), 제품 기능
드릴은 어느 게이트도 돌리지 않는다(FE-GATE-020은 참조 기능만).
고른 방법
- 두 곳의 상한을 32(템플릿 26 + 기능 여유)로 고치고, [계약] 행 커밋을
1b8cb12 대신 2fef27d로 적었다. 템플릿 자체의 파일 수 26은 따로 적었다.
- 알려진 제한 머리를 범위 끝 8a44226 기준으로 바꿨다. 2026-11-05 리뷰
영역 14가 8a44226에서 그 줄들을 대조했다(낡은 줄은 지난 라운드에 빠짐).
위 절(2026-11-05 조치)이 바꾼 줄은 위 절에 적는다고 밝혔다.
- merge 단계에서 문서 검사를 하는 것은 FE-GATE-005의
documentation-readiness라 test:unit 줄에 넣고, FE-GATE-017과 제품 기능
드릴은 "merge 게이트 밖" 단계로 나눴다.
위험·한계
- 문서만 바꿨다. 1,873 B 여유는 기록 값이다(빌드마다 수십 B 다르다).
- 위 절이 바꾸는 알려진 제한 줄(기능 라우트 첫 진입, SW composeProduct 칸
등)은 위 절 행을 쓸 때 함께 고친다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1103/14-01, 1103/15-02
문제
CHANGELOG "먼저 할 일" 6단계는 예제를 지운 제품(tech-log)에게 예제 기능
폴더와 그 context를 지우라고 한다. 그런데 starter-experience.md가 그 세
폴더를 백틱 경로로 적어서, 지운 사본에서 verify:documentation과
FE-GATE-005의 documentation-readiness "passes the documents as they are"가
"starter-experience.md names paths that do not exist"로 실패한다(리뷰
14-R1). 그 문서가 안내한 드릴(test:sample-removal
--feature=platform-examples-feature)도 같은 문서 검사와, 예제 기능 ID를
적은 tests/unit/hosting-probe.test.ts 때문에 잔여 검사에서 실패한다.
PRODUCT.md는 예제 화면에 제거 드릴이 없다고 적는다. 지운 제품이 템플릿
문서를 고치면 동기화마다 그 줄이 충돌한다.
고른 방법
- 문서 검사는 scripts/lib/removable-template-features.ts의 기능마다, 그
기능이 설치돼 있으면(src/features/<id>/feature-module.ts가 있으면) 그
경로·script를 지금처럼 검사하고, 아니면 그 기능이 가진 경로(기능·테스트
폴더, context, 전용 파일)와 script를 없어도 되는 것으로 본다. 폴더가 아니라
feature-module.ts를 보는 것은 tech-log가 참조 기능 폴더를 계약 파일만 남긴
채 NOT_A_FEATURE로 두기 때문이다(CHANGELOG 옮기는 법 1). 목록에 없는
폴더(오타)는 그대로 실패한다. 지운 기능이 있으면 stdout에 그 ID를 적는다.
- tests/unit/hosting-probe.test.ts의 FEATURE_OVERRIDES 키를 테스트 전용
기능 ID(fixture-feature)로 바꾼다. probe는 키 이름을 보지 않는다.
- 새 테스트 tests/unit/template-feature-removal-documents.test.ts: 저장소
사본에서 기능마다 그 경로를 지우고 색인을 다시 만든 뒤 사본의
verify:documentation이 통과한다. 사본의 코드로 경로를 찾으므로 실제로
지운 상태다. 기능 ID는 목록에서 읽어 테스트에 적지 않는다(제거 드릴의
잔여 검사). 설치된 기능 아래의 없는 경로와 목록에 없는 폴더는 여전히
실패하는 것도 본다. 문서를 읽으므로 REMOVAL_FIXTURE_DOCUMENT_TESTS에
더했다.
- PRODUCT.md, starter-experience.md(지우는 법과 문서 검사 규칙),
docs/README.md 1절 검사 설명, CHANGELOG 6단계(테스트 폴더,
generate:feature-index, 드릴, 두 절을 함께 받을 것)를 고쳤다.
- 버린 대안: (a) 세 경로를 백틱 없이 적기(1103/14-04 방식). 검사가 또
좁아진다(1105/14-03). (b) 모든 src/features/<dir> 아래 경로를 폴더가
없으면 통과시키기. 기능 폴더 이름 오타가 조용히 지나간다. (c)
FE-GATE-020에 예제 기능 드릴을 더하기. job이 약 5분 는다. 문서 쪽은 새
unit 테스트가 merge 단계에서 본다.
위험·한계
- 새 테스트는 저장소 사본을 두 번 만든다(기능마다 cp·색인·검사). test:unit
시간이 몇 초 는다. 드릴이 test:all에서 이 파일을 다시 돈다.
- 예제 기능 드릴 전체(test:all, build 등)는 이 커밋에서 돌리지 않았다.
알려진 남은 실패는 e2e·visual spec이 예제 화면을 여는 것이고 드릴 밖이다.
- RED에서 새 테스트는 앞 커밋의 목록 모듈을 import하므로 그대로 돈다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/template-feature-removal-documents.test.ts
tests/unit/hosting-probe.test.ts tests/unit/removal-fixture.test.ts
tests/unit/documentation-readiness.test.ts, corepack pnpm
verify:documentation, corepack pnpm test:sample-removal --
--feature=platform-examples-feature
Refs: 1105/14-01
CHANGELOG의 미출시 절은 `752a61f` → `fix/maturity-review-2026-11-03`
범위다. 그 범위는 main `409d72e`에 합쳐졌고, 2026-11-05 리뷰의 P1
조치 셋(1105/09-01, 12-01, 13-01)은 어느 절에도 없다. 다운스트림이
FE-GATE-013 러너 요구와 release job의 새 upload를 알 수 없다.
`409d72e` → `fix/maturity-review-2026-11-05` 범위의 새 미출시 절을
위에 두고 세 조치를 적었다. CI 러너 요구와 workflow upload가 바뀌므로
12-01·13-01은 [계약]이다. 기존 절은 지우지 않고 main에 합쳐졌다고만
머리에 적었다. 두 절을 하나로 합칠지는 남은 조치(PR B)의 CHANGELOG
정리에서 정한다.
위험·한계: 문서만 바꿨다.
검증: desktop batch에서 changelog-review-ids, documentation-readiness
테스트.
Refs: 1105/09-01, 1105/12-01, 1105/13-01
문제: ee37dd86(1103/11-10)이 firefox에서 FE-GATE-008을 가끔 떨어뜨리던
capability test의 구조를 고쳤는데 CHANGELOG에 없었다.
방법: 게이트·드릴 행의 11-09 문장 뒤에 이어 적었다.
검증: desktop에서 changelog-review-ids test(README 커밋과 함께).
문제: aad005cb(1103/11-09)이 strict fixture의 WebKit preload 경고 처리와
새 preload 사용 검사를 바꿨는데 CHANGELOG에 없었다. 다운스트림은 build
script를 직접 fulfill하는 test에 `fulfillBuildScript`를 써야 한다.
방법: 게이트·드릴 행의 11-08 문장 뒤에 이어 적었다. FE-GATE-008이 가끔
떨어지던 게이트 문제라 같은 행에 둔다.
검증: desktop에서 tests/unit/changelog-review-ids.test.ts(아래 README
커밋과 함께).
문제: b693600(1103/11-08)이 fixture 빌드·시각 골든 build·dev server를
CI=true와 CI 식별값에서 떼어 놓았는데 CHANGELOG에는 11-07의 vitest·dev
server 조치만 있었다.
방법: 게이트·드릴 행의 11-07 문장 뒤에 11-08을 이어 적었다. 새 행을 만들지
않은 것은 같은 원인(CI env가 로컬 빌드로 샌다)의 두 번째 조치라서다.
검증: tests/unit/changelog-review-ids.test.ts 통과,
verify:documentation PASS_SCOPED(짝 백엔드 checkout 없음).
문제
미출시 절은 "corepack pnpm dev가 설치된 기능의 contract set으로 release
manifest를 낸다"고 적는다. 그 미들웨어는 799ab7f에서 지웠고, 지금은
create:feature와 기능 제거 드릴이 public/release-manifest.json을 다시 쓴다.
고른 방법
- 행을 지금 동작([계약]: 다시 쓰는 명령, 커밋할 것, 낡으면 실패하는 테스트)과
dev server 감시 제외로 고친다.
검증
- changelog-review-ids·documentation-readiness 테스트 20건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 16-09
문제
매뉴얼만으로 기능을 더한 재실험(리뷰 조치 X2)의 막힘 7건과 깨끗한 clone
검증에서 고친 것이 미출시 절에 없다.
고른 방법
- 그 밖의 수정에 한 행으로 적는다(dev release manifest 1103/16-09, 기능 제거
드릴의 초기 JS 재기록 15-02, 파일 상한 32 15-05, 업로드 client 포트
분리 01-01, 타입 검사 탐침 09-02, 시각·storybook 11-07).
검증
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6
문제
af312de(vitest와 dev server Playwright가 CI의 VITE_BUILD_ID·VITE_COMMIT_SHA를
물려받지 않는다)는 CHANGELOG 재작성(44aa44d) 뒤에 들어왔다. 미출시 절
머리의 끝 커밋 설명도 그 뒤의 변경을 말하지 않는다.
고른 방법
- 게이트·드릴 행에 1103/11-07 행을 더한다. 리뷰 README 13절에 발견으로
적는다.
- 머리에 f887817 뒤로 검증 수정과 pin 갱신이 더해졌다고 적는다.
검증
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-07
문제
check:backend-contract-drift가 백엔드 HEAD 45d2a478에서 http-contract.md §2
두 행의 설명 변경을 알린다. IDEMPOTENT_IN_FLIGHT(PostgreSQL 저장소는 409
대신 첫 요청이 끝날 때까지 기다림)와 IDEMPOTENCY_UNAVAILABLE(processing
lease가 시작 전에 끝나 저장소가 시작을 거절함)이다. 같은 커밋이 6.1절이
인용하는 GlobalExceptionHandler와 IdempotencyExecutor도 고쳤다.
고른 방법
- 두 행의 code·status·retryable·재전송 규칙은 같다. 프론트 판정(처리 중
MAYBE_APPLIED·같은 키, UNAVAILABLE 실행 안 됨·같은 키 자동 재전송)은
바꾸지 않는다.
- 6.1절이 인용하는 블록 13개를 두 판에서 대조했다. 내용은 모두 같고
GlobalExceptionHandler 4개, IdempotencyExecutor 1개의 줄 번호만 옮겼다.
인용한 다른 백엔드 파일 15개는 바뀌지 않았다.
- pin, 답 표 JSON, 계약 문서 4.1·6·6.1절, CHANGELOG의 pin 행과 알려진
제한을 같이 고친다.
위험·한계
- PostgreSQL 저장소의 기다림이 프론트 totalDeadline보다 길면 응답 없는
끝(결과 불명, 키 유지)이 된다. 판정은 안전 쪽이다.
- Fileserver 계약(docs/fileserver/http-contract.md)은 bbe944bd 이후 바뀌지
않았다.
검증
- check:backend-contract-drift --backend <백엔드 checkout>: pinned
45d2a478.
- backend-contract-pin·changelog-review-ids 테스트 11건,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06
문제
미출시 절은 fix/ui-design-audit-2026-11-01 한 브랜치의 누적 기록이었다.
- 같은 묶음에 들어온 그 브랜치 뒤 16커밋(ece944dd0414c87d855897c8cb1917fa8d127f45238a09c90e5b7b3e 등)과 2026-11-03 조치 11개 브랜치가 없다.
- V2를 고친 행과 V2를 지운 행이 함께 있고, 알려진 제한 13줄 중 대부분이
이미 고쳐졌다.
- BREAKING 이행 안내가 "memento-web이 V2 API 행을 쓴다"고 적었다. memento-web의
apiOperations는 비어 있고, 실제 작업은 descriptor 29개의 FE-REG-API 행,
스키마 행 43개, zod가 아닌 검증기다. tech-log의 직접 조립 경로는 안내가
없었다.
- 0.2.0의 17d617a 행이 설정 스키마 분류기를 "레지스트리 호환성 분류기"라고
부르고, 그 커밋이 고치지 않은 scripts/check-registries.ts를 적는다.
고른 방법
- 결정 D5 (b): 752a61f → fix/maturity-review-2026-11-03 범위를 한 동기화
단위로 보고 최종 상태만 적는다. 머리에 범위·세 갈래·읽는 법, 이어서
"먼저 할 일 (BREAKING)"을 옮기기 전 / 옮기는 법 / 옮긴 뒤 확인 순서로,
그 뒤 영역별 [보안]·[계약] 표, 그 밖의 수정, f887817에서 사실인 알려진
제한을 둔다. 뒤 커밋이 바꾼 중간 상태 행(V2 Envelope·V2 거절·V2/V3 대조,
REST 보안 프로필 메시지, 초기 청크 16→25개 등)은 최종 행에 합치거나 지웠다.
- 14-02: 두 다운스트림(memento d3810a0, tech-log 7a4e201a)을 읽고 단계마다
실제 모양을 적었다. memento: PRODUCT_LOCAL_CONTRACT 출처, ownsShell·APP_HOME
다리, SW ACTIVE 선택, 손으로 쓴 검증기. tech-log: NOT_INSTALLED 직접 조립과
기능 모듈로 바꾸는 길(fixture-layout-product 모양).
- 리뷰 P-07-07은 경로를 scripts/lib/registry-compatibility.ts로 바꾸라고
했지만, 17d617a가 고친 것은 src/contracts/compatibility.ts(FE-GATE-014)다.
경로를 바꾸면 틀린다. 그래서 이름을 "설정 스키마 호환성 분류기"로,
둘째 경로를 scripts/check-compatibility.ts로 고쳤다.
- 머리 규칙에 미출시 절이 동기화 단위 순 요약이라는 줄을 더했다.
- 버린 대안: 브랜치별 누적 기록을 유지하고 빠진 행만 더하기(14-01 (a)).
다운스트림이 서로 뒤집는 행을 직접 걸러야 한다. 커밋 trailer 검사
(14-01 (c))는 이번에 넣지 않았다.
위험·한계
- 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. memento 숫자는
정적 집계다. 알려진 제한에 적었다.
- 끝 커밋은 f887817 기준이다. 이 브랜치를 합친 뒤 끝이 바뀌어도 해시 규칙
(범위 안)은 그대로다.
- 짝 백엔드가 pin c508b1ba 뒤로 바뀐 것(HEAD 45d2a478, §2 두 행 설명)을
알려진 제한에 적었다. pin은 올리지 않았다.
검증
- 미출시 절의 이 repo 해시 148개: 모두 f887817에서 닿고 752a61f에서 닿지
않는다(merge-base --is-ancestor 스크립트). 나머지는 기준점 2개와 다른
repo 커밋 4개.
- vitest changelog-review-ids, documentation-readiness 20건 통과.
- verify:documentation PASS_SCOPED, check:types, lint 통과.
- 인증 프로필 오타 변이(참조 기능): check:registries가 reason과 함께 실패,
check:types·check:architecture·verify:documentation 통과를 확인했다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-01
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-02
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-07
문제
14.7은 V2 삭제로 "401 뒤 세션 복구 재전송"과 "보낸 KEYED 요청 자동 재시도"가
사라졌다고만 적었다. 사용자가 없어져도 되는지 물었고, V2 보안 프로필 일관성
검사도 같이 사라졌다.
고른 방법
14.7에 세 동작의 판정 표를 적었다. 기준은 설계 정본(2026-07-30 closed deep
design) 8절이다.
- 401 재전송: 없어져도 된다(8.4 FRT-D016 hidden replay 금지). VD-23의 낡은
문장은 리뷰 대상으로 남긴다.
- KEYED 자동 재시도: 정본 8.3이 허용하는 부분(재시도를 허락하는 알려진 응답)만
되살렸다(c05f41a).
- 보안 프로필 검사: 쿠키 인증 쓰기의 CSRF 요구만 보안 불변식이라 되살렸다
(365d8c3).
CHANGELOG에 [보안] 행과 [계약] 행을 더했다.
검증
- verify:documentation PASS_SCOPED, tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
문제
048f490(V2 클라이언트 삭제)과 12f3bb7(V2 API 행 삭제)은 공개 이름을 깨는
변경인데 CHANGELOG 미출시 절에 행이 없고, "먼저 할 일" 절의 기능 모양 옮기기
순서가 아직 apiContract(V2 API 필드 네 개)를 만들라고 적는다. 리뷰 README
14.6의 "V2와 남은 차이"도 V2가 있는 것으로 적는다.
고른 방법
- CHANGELOG: [계약] BREAKING 행 둘(지운 이름, 옮기는 법, memento-web 영향)을
더하고, "먼저 할 일" 1·3번을 schemas 하나로 고쳤다.
- 리뷰 README 14.7: 사용자 지시, 지우기 전·후 도식, 두 커밋이 지운 것과 바꾼
것, 레지스트리 재승인 digest, 초기 JS 변화, 사라진 V2 전용 동작, 남긴
BoundedPollOperationContract, 다운스트림 영향. 14.6의 차이 절에 지금은 없다고
적었다.
위험·한계
- 다운스트림 동기화 방법은 CHANGELOG의 문장뿐이다. memento-web을 직접 옮겨
보지는 않았다.
검증
- verify:documentation PASS_SCOPED.
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
문제
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으로 실행한다.
문제
3261208이 V2·V3의 거절 판정을 계약 문서 6.1절 표로 바꿨다. 매뉴얼 02
4절은 아직 "422 전부와 필드 목록 400은 적용 안 됨, 그 밖은
classifyProblem"으로 적고, 리뷰 README 14.6 판정 표, 14.4의 검증 거절 줄,
CHANGELOG의 7db32e1 행도 같은 옛 규칙을 적는다.
고른 방법
- 매뉴얼 02 4절: 표의 세 code(적용 안 됨)와 그 밖의 400·409·422(결과 불명),
근거가 계약 문서 6.1절이라는 것, 쓰기 전 거절 code를 새로 만들 때 두 곳을
함께 고친다는 것.
- 매뉴얼 01 3단계: 실행기가 정하는 status 범위를 400·409·422와 503으로 적었다.
- 리뷰 README 14.6: 판정 표를 새 표로 바꾸고 처음 규칙을 한 줄로 남겼다.
"6.1 표 반영" 단락에 바뀐 것, 버린 대안, 위험, RED·GREEN, 게이트를 적었다.
14.4 줄에 바뀐 판정을 덧붙였다.
- CHANGELOG: [계약] 행 하나를 더하고 02e35d2·7db32e1 행이 그 행을 가리키게
했다.
위험·한계
- 계약 문서 6.1절은 오케스트레이터 브랜치(ed0e4b1)에만 있다. 이 브랜치의
매뉴얼은 그 절을 가리키지만, 합치기 전에는 그 절이 없다.
- 프론트 계약 문서 4.2절 "422 field validation" 행은 고치지 않았다.
검증
- verify:documentation PASS_SCOPED.
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
문제
매뉴얼 01 3단계, CHANGELOG 미출시 절, 리뷰 README 14.3은 "생성한 기능은
짝 백엔드 응답을 그대로 읽지 못한다, 해결 방법은 정하지 않았다"를 알려진
제한으로 적는다. 7db32e1로 V3가 responseEnvelope: "ENVELOPE_V1"
operation의 Envelope를 읽게 되어 이 문장들이 틀렸다. 매뉴얼 02 4절의 503
흐름도와 계약 문서 4.1절도 "V3는 Envelope 없이 DTO를 검증"으로 적는다.
고른 방법
- 리뷰 README 14.6: 선택지 넷(V3 operation 단위 / provider 단위 / 백엔드
problem+json 모드 / 기능 스키마가 감쌈)의 판정과 이유, V2와 같은 판정
표, 의도한 차이 세 가지, RED→GREEN·게이트 결과, 남은 것. 14.3 행의
처리 칸은 14.6을 가리킨다.
- 매뉴얼 01 3단계: "응답 모양"을 짝 백엔드 Envelope 기준으로 다시 쓰고,
Envelope가 아닌 백엔드에 붙이는 순서(responseEnvelope 줄 삭제, problem
details 스키마)를 따로 적었다. 알려진 제한 문단은 지웠다.
- 매뉴얼 02 4절: 실행기가 먼저 정하는 판정 목록과 바뀐 503 흐름.
- CHANGELOG: [계약] 행 하나, 알려진 제한을 남은 차이(참조 기능 미선언,
V2와의 차이 셋, e2e 접근성 스펙의 [] 본문)로 바꿨다.
- 14.4와 CHANGELOG의 "V3 진단에 problem code가 없다"에 bd83b49가 싣는
범위(멱등성 거절 reason 두 값)와 싣지 않는 것, 그 이유를 적었다.
- 계약 문서 4.1절·compatibility.md: Envelope를 읽는 곳을
backend-envelope.ts로 고쳤다.
버린 대안
- 백엔드에 요청 문서 쓰기: (나)를 고르지 않아 요청할 것이 없다.
위험·한계
- 문서의 게이트 결과는 이 커밋 직전 트리(bd83b49, scaffold·sample-removal은
7db32e1)에서 잰 값이다.
- 백엔드 링크는 두 repo가 나란히 있을 때만 열린다(기존과 같다).
검증
- verify:documentation PASS_SCOPED.
- 게이트 수치는 README 14.6 결과 표에 실행한 커밋과 함께 적었다.
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
문제: 결정 반영 묶음을 다 합친 뒤의 게이트 결과, 매뉴얼만으로 기능을
추가한 재실험 결과, 그 과정에서 찾은 결함이 리뷰 README와 CHANGELOG에
없었다.
방법:
- 리뷰 README 14.3에 세 가지를 더했다.
- create:feature와 참조 기능(V3 실행기)이 짝 백엔드 Envelope 응답을
읽지 못한다(High, P1, 결정 필요라 남김).
- 매뉴얼 재실험 결과: 막힘 5건, 예고된 실패 1건. 막힘은 매뉴얼에 메웠다.
- webkit old-tab-chunk-recovery 간헐 실패.
- 14.5에 7c7ef32 최종 게이트 표를 둔다.
- CHANGELOG 알려진 제한에 Envelope 제한과 webkit 간헐 실패를 더했다.
버린 대안: Envelope 제한을 이번에 고치기. V3 실행기에 Envelope 읽기를
넣을지, 백엔드가 problem+json을 보낼지는 두 repo에 걸친 결정이다.
게다가 백엔드 repo는 사람만 커밋한다.
위험: Envelope 제한이 풀리기 전에는 생성한 기능을 짝 백엔드에 바로 붙일
수 없다. 매뉴얼 01-3단계가 이를 적는다.
검증: tests/unit/changelog-review-ids.test.ts 통과. webkit 반복 실행
10/10 통과(load 16).
문제: 2026-11-03 결정(리뷰 README 14절)에 따라 만든 커밋 40여 개가
CHANGELOG 미출시 절과 리뷰 README에 없었다. 다운스트림은 CHANGELOG의
[계약]·BREAKING 행으로 가져갈 수정을 고른다. CHANGELOG 11행은 0.2.0
해시가 main에서 다를 수 있다고 적었지만 52개 모두 main에서 닿는다.
방법:
- CHANGELOG 보안·계약 표에 BREAKING 2건(1101/08-03, 0929/05-03)과
[계약] 28건을 더했다. file-transfer 예산 행은 새 예산 규칙 행으로 바꿨다.
- 백엔드 리뷰에서 온 ID는 "백엔드 리뷰 1101/02-01"로 적어 이 repo의 같은
번호와 섞이지 않게 했다.
- 알려진 제한에서 풀린 것(registry-baseline source, OPFS 여러 페이지
purge)을 지우고 남은 위험을 더했다.
- 11행 해시 문장을 사실대로 고치고, docs/reviews/를 지운 복사본은 원본
repo에서 ID를 찾는다고 적었다.
- 리뷰 README에 14.2 결과, 14.3 새로 찾은 것, 14.4 남은 문제를 더했다.
위험: 행 수가 많아 다운스트림이 놓칠 수 있다. BREAKING은 표시 열 맨
앞에 둔다.
검증: tests/unit/changelog-review-ids.test.ts 통과(라운드 없는 ID 0).
표의 각 행 열 수를 확인했다(기존 이스케이프 행 1개 제외).
문제: 리뷰 README 13절은 개선 순서 1까지만 적혀 있었다. 밤사이 고친
ID와 커밋, 건너뛴 항목과 이유, 새로 찾은 결함, 예산 여유가 에이전트
보고에만 있었다. CHANGELOG 알려진 제한에는 이미 해결된 두 줄(규모
기준선이 15-01 전 측정, 좁은 화면 골든 미갱신)이 남아 있었고, 규모 근거
문장이 옛 수치를 적고 있었다.
방법: README 13.3~13.8에 개선 순서 2, 영역별 고친 ID와 커밋, 결정이
필요한 건너뛴 항목 20줄, 새 발견(여러 페이지 OPFS purge), 예산 여유,
마지막 게이트를 더했다. 영역 문서는 리뷰 시점 기록이라 고치지 않았다.
CHANGELOG는 해결된 두 줄을 지우고 OPFS purge 제한을 더했다.
feature-shape-ceilings.json의 Initial/Lazy JavaScript 수치를 9333595
측정에 맞췄다.
위험: 13.6의 OPFS purge 결함은 코드로만 확인했다(E2). 실행 재현은 없다.
검증: changelog-review-ids, feature-shape-growth, documentation-readiness,
deletable-history-documents 11/11 통과. verify:documentation PASS_SCOPED.
미출시 절은 13·14·15 묶음을 합칠 때 썼다. 그 뒤 합친 01·02·03·04·06·08·
09·10·11·16 영역 수정이 빠져 있었고, 13-04 행은 worktree 커밋 해시를
가리켰다.
[계약] 행 9개(업로드 Retry-After와 recovery, realtime 배럴 함수, base path,
조립 거절 2종, 전송 전 거절 분류, CI의 skip·todo 실패, 시각 허용치 50 px,
file-transfer 레시피 예산 인상)와 그 밖의 수정 5줄을 더했다. 13-04 해시를
브랜치 커밋으로 고쳤다.
위험: 문서만 바뀐다. file-transfer 예산 인상은 소유자 검토 대상으로 적었다.
검증: 표와 목록의 커밋 해시를 `git log`와 대조했다.
문제
fix/ui-design-audit-2026-11-01 브랜치에는 다운스트림(tech-log, memento)이
따라 고쳐야 하는 변경이 쌓였는데 CHANGELOG에 한 줄도 없다. 특히
298201f(15-01)는 FeatureModule 모양을 바꾸는 BREAKING 변경이라, 커밋
본문의 BREAKING CHANGE 꼬리말만으로는 기존 기능을 어떤 순서로 옮겨야
하는지 알 수 없다. 영역 14는 check:design-system 규칙 추가가 CHANGELOG에
없다고 지적했고, 영역 07 수정(증거 형식, 분류 판정, TEMPLATE_FIXTURE
거부, 폐기 별칭 lint)도 [계약] 행이 필요하다고 각 커밋이 적었다.
고른 방법
- 기존 형식(버전 절 → 보안·계약 표 → 그 밖의 수정 → 알려진 제한)을 따라
"미출시 — 브랜치 fix/ui-design-audit-2026-11-01" 절을 0.2.0 위에 둔다.
버전 번호는 정하지 않았다. 리뷰 ID는 1101/14-02 규칙대로 라운드를
붙였다.
- 15-01은 "먼저 할 일" 절로 따로 뺐다. 298201f 본문과
src/features/reference-feature/의 실제 모양(feature-module.ts,
feature-runtime.ts, context-routes.ts, contracts/reference-api-contract.ts,
installed-contract-contributions.ts, feature-module.ts 타입)을 근거로 아홉
단계를 적었다.
- [계약] 표에 15-01, FE-GATE-012 merge 이동, 0929/03-01·09-01·0929/04-01·
0929/06-01(High), check:design-system 규칙 4개, 시각 테스트 fonts.conf와
runner 글꼴 패키지, 0929/07-01·0929/07-02·07-04·07-01, 05-01, 12-05,
13-04를 넣었다. 경로는 각 커밋의 변경 파일과 대조했다.
- 커밋 해시는 브랜치에 있는 해시다. 영역 07 등 합쳐진 수정은 브랜치의
cherry-pick 해시(5e6be9a 등)를 쓴다.
버린 대안
- 0.3.0 같은 버전 절을 미리 만들기: 버전 번호는 이번 작업에서 정하지
않는다.
- 15-01 이행 순서를 starter-experience.md만 가리키기: 그 문서는 새 기능
추가 순서라, 이미 있는 기능을 옮기는 단계(runtimes 삭제, features.load
호출, fake의 load)가 없다.
위험·한계
- 이 worktree에 없는 커밋(5e6be9a까지 브랜치에 합쳐진 것)은 커밋 본문과
변경 파일 목록으로만 확인했다. 이후 합쳐지는 수정은 이 절에 없다.
- 13-04·13-05·15-02·14-02·14-06·15-05 행의 해시는 이 worktree의 해시라
브랜치에 옮길 때 바뀔 수 있다.
- registry-baseline의 source 경로, feature-shape-growth 기준선, 08-01 서랍
시각 골든은 알려진 제한에 적기만 했다.
검증
- node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
tests/unit/deletable-history-documents.test.ts: 2 passed
- grep -cE '\(([0-9]{2}-[0-9]{2})' CHANGELOG.md → 0, 새 절 본문의 라운드
없는 ID 0
- verify-documentation-readiness PASS_SCOPED
문제
리뷰 라운드마다 발견 ID를 `NN-MM`으로 새로 매긴다. CHANGELOG의
`(14-02)`는 0925 라운드의 "CI 계약 고정"인데, 0929 라운드의 14-02는
"README 업데이트 절차"이고 이번 라운드에도 14-02가 있다. CHANGELOG는
복사한 프로젝트가 변경 근거를 찾는 유일한 링크라 ID가 어느 라운드인지
모르면 다른 결함을 읽게 된다. 리뷰 가이드에 ID 네임스페이스 규칙이 없다.
고른 방법
- CHANGELOG 0.2.0 절의 ID 98개에 `0925/`를 붙였다(`F-N`은 0925
FOLLOW-UP의 ID라 같이 붙였다). 기계적 치환이다: 괄호 안의
`NN-MM`·`F-N`만, 범위(`01-01~01-11`)는 앞에만, 날짜는 건드리지 않는다.
0.1.0 절의 `R-x.y`는 다른 체계라 그대로 둔다.
- CHANGELOG 머리말에 `MMDD/NN-MM` 규칙과 F-N의 뜻을 적었다.
- 리뷰 가이드 36.3 "ID·제목"에 같은 규칙을 넣었다. 라운드 안에서는
`NN-MM`, 밖에서 가리킬 때는 `MMDD/NN-MM`. 기존 코드 주석 약 339곳은
고치지 않고 새로 쓰는 것부터 붙인다(리뷰의 최소 개선 방향 ③).
- tests/unit/changelog-review-ids.test.ts가 CHANGELOG 괄호 안의 라운드
없는 ID를 막는다. 리뷰가 적은 grep 검증을 test:unit 게이트로 옮긴 것이다.
버린 대안
- CHANGELOG 표에 라운드 열 추가: "그 밖의 수정" 목록에는 표가 없어 규칙이
둘이 된다. ID 자체에 붙이는 쪽이 코드 주석·커밋 제목과 같은 형식이다.
- 접두어를 `YYYYMMDD/`로: 이미 브랜치의 커밋과 리뷰 README가
`0929/03-01` 형식을 쓴다. 해가 바뀌어 월일이 겹치면 그때 연도를 붙인다.
위험·한계
- 기존 주석과 0.2.0 커밋 제목은 라운드 없는 ID로 남는다(혼재 기간).
- 테스트는 괄호 안 쉼표 구분 토큰만 본다. 괄호 밖 본문에 쓴 ID는 잡지
않는다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
실패 "expected [ '03-03', '03-01', '08-03', …(95) ] to deeply equal []"
- GREEN: 같은 테스트 통과. 리뷰의 검증 명령
`grep -cE '\(([0-9]{2}-[0-9]{2})' CHANGELOG.md` → 0
- eslint, tsc(test), verify-documentation-readiness PASS_SCOPED,
check-ci-contract PASS(새 테스트 파일이 test:unit 게이트에 들어감)
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-02
The in-progress section is folded into the contract table and the other
fixes list, and a known-limits section records what was not verified
(WebKit on this host) and what stays user-owned.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>