합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나.
- 1105/03-02(HTTP 판정 브랜치)가 §4의 503 `RATE_LIMIT_UNAVAILABLE`·
`RATE_LIMIT_INCOMPATIBLE`을 답 표(`backend-idempotency-answers.json`)에
옮겼다. 1105/07-01(이 브랜치)은 같은 두 code를 pin의 `notCopied`에
두었다. 합친 트리에서 `backend-contract-pin.test.ts`의 "copies the
answers from the backend table rows at the pin"이 "is both copied and
listed in notCopied"로 실패한다.
- pin의 `notCopied`를 비우고, 계약 문서 4.1절의 "지금은 §4의 `RATE_LIMIT_*`
둘"과 "§4 행은 `REQUEST_TIMEOUT` 하나"를 답 표에 맞게 고친다.
- `docs/manual/01-add-a-feature.md` 충돌은 앞 통합(1a4a220c)과 같게
푼다: "5xx 여섯" 줄과 pin·사본·drift 명령 세 줄을 함께 둔다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
Refs: 1105/03-02, 1105/07-01
문제: 다섯 Playwright 설정의 서버 포트가 고정이다(e2e 4173, visual과
capability가 둘 다 4174, storybook 6006, dev 5173). 한 checkout이든 같은
기계의 두 worktree든 두 번째 실행은 `http://127.0.0.1:4173 is already
used`로 시작하지 못한다(00-R1). dev 설정만 `reuseExistingServer: true`라
5173에 다른 checkout·브랜치의 dev 서버가 떠 있으면 말없이 그 서버를
검사한다. vite는 `--strictPort` 없이 떠서, 포트가 그 사이 잡히면 다음
포트로 옮기고 Playwright는 원래 URL의 남의 서버를 검사할 수 있다
(1105/12-04).
고른 방법: 설정마다 `reservePort(TEST_<이름>_PORT)`로 빈 포트를 고른다
(`scripts/lib/run-isolation.ts`). 커널이 port 0에 준 포트를 받고 바로
닫는다. 고른 포트를 그 변수에 써 둔다. Playwright는 worker마다 설정을
다시 평가하고 worker는 runner 환경을 물려받으므로, worker의 평가가 같은
포트를 읽어 `baseURL`이 어디서나 같다. 변수를 미리 주면 그 포트를 쓴다
(디버깅용 고정). vite 서버 넷 모두 `--strictPort`로 띄우고, dev 설정은
`reuseExistingServer: false`로 바꿨다. run ID가 없어도 빈 포트를 쓴다.
두 worktree는 출력 경로가 이미 다르고 포트만 부딪히기 때문이다. 고정
번호를 읽는 곳은 없다. spec은 `baseURL`에서 origin을 얻는다
(`resumable-upload.spec.ts`, `production-csp.spec.ts`).
버린 대안: 포트 범위를 run ID에서 계산하기. 두 checkout이 같은 run ID를
쓰거나 다른 프로그램이 그 포트를 쓰면 다시 부딪힌다. Playwright
`webServer.wait`로 서버가 고른 포트를 stdout에서 읽기: `use.baseURL`은
설정을 읽을 때 정해져서 쓸 수 없다.
위험·한계: 포트를 고른 뒤 서버가 잡기 전에 다른 프로세스가 같은 포트를
잡을 수 있다. 그때는 `--strictPort`/serve-static의 listen 실패나
Playwright의 "already used"로 시작이 실패한다. 남의 서버로 검사가 새지
않는다. 기본 실행의 포트 번호가 매번 달라진다. 고정이 필요하면
`TEST_E2E_PORT=4173`처럼 준다. `test:e2e:dev`는 이제 떠 있는 dev 서버를
쓰지 않고 자기 서버를 띄운다. capability 설정이 없는 사본
(test:browser-file-storage-removal)에서는 그 설정의 포트 테스트를 돌리지 않는다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts
corepack pnpm test:browser-file-storage-removal
Refs: 1105/12-04
문제
create:feature --with-create가 만드는 작성 폼의 feedback은 form.failure와 결과
불명 두 가지뿐이다. 저장 성공은 상세로 이동해서 알리는데, "변경됨으로 확인"은
reconcileUnknownEffect(...).then(form.settleApplied)이고 이동하지 않는다.
settleApplied가 결과를 success로 바꾸고 기본값 resetOnSuccess로 입력을 비우므로,
결과 불명 화면이 사라진 뒤 빈 폼만 남는다. 짝 백엔드 기본(NEVER)에서는 이것이
화면 안의 유일한 행동이다. 사용자는 확인이 받아들여졌는지 모르고, 다시 입력해
저장하면 키 없는 생성이 한 번 더 나간다(실제로 저장됐던 경우 중복). 참조 폼은
같은 경우 "저장했습니다."를 보인다.
고른 방법
확인 뒤 폼을 정리하고(settleApplied, flushSync라 이동 전에 dirty 가드가 풀린다)
목록으로 이동한다. 목록은 항목이 실제로 저장됐는지를 보여 주는 화면이고,
reconcileUnknownEffect가 이미 목록 topic을 무효화한다. 라우터가 목록 제목으로
포커스를 옮기므로 08-01의 포커스 문제도 이 폼에서는 생기지 않는다. 생성 기능
테스트에 "응답을 잃은 생성 → 변경됨으로 확인 → 목록 제목과 항목"을 한 행 더했다
(NEVER·KEYED 공통). 매뉴얼 02의 생성 테스트 행에 적었다.
버린 대안
참조 폼처럼 success 가지에 확인 문구를 둔다: 생성 catalog에 키가 하나 늘고,
항목이 실제로 있는지는 여전히 보이지 않는다.
위험·한계
- 짝 백엔드 생성기에는 목록 GET이 아직 없다(1103/03-07 결정 대기). 실제 짝
백엔드에서는 이동한 목록이 405를 받는다(생성 목록 페이지가 지금 그렇다).
생성 테스트는 MSW로 목록을 답한다.
- 생성 결과 파일은 단위 테스트가 문자열로만 보고, 동작은 test:feature-scaffold
(KEYED, FE-GATE-020)와 test:sample-removal(NEVER)에서 생성한 테스트가 본다.
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/create-feature.test.ts
corepack pnpm test:feature-scaffold
corepack pnpm test:sample-removal
Refs: 1105/08-02
문제
1103/08-02 수정(2d5d41f8)이 저장 버튼을 disabled 대신 pending으로 바꾸면서
버튼은 결과 불명일 때만 꺼진다. 코디네이터가 mutation-pending이어도 이 폼이
저장 중이 아닐 수 있다. 저장 중에 화면을 떠났다가 같은 세션에서 돌아온 경우
(진행 중 시도가 있는 동안 채널이 남는다)와 "변경됨으로 확인"을 처리하는
동안이다. 그때 onSubmit은 아무것도 하지 않고 돌아가고 feedback에도 아무것도
없다. 저장을 눌러도 반응이 없고, 첫 저장이 끝난 뒤에도 그 클릭은 실행되지
않는다(리뷰 08-R1 D). 참조 폼과 생성기 템플릿이 같다.
고른 방법
"코디네이터가 mutation-pending인데 이 폼은 저장 중이 아님"을 otherSaveRunning으로
두고 두 가지를 함께 한다.
- 저장 버튼을 그동안 끈다. 이 폼 자신의 저장 중에는 지금처럼 끄지 않고 busy로
둔다(포커스 유지, 1103/08-02). 그때 포커스는 저장 버튼에 있지 않다(다시
마운트한 폼이거나, 누른 버튼은 "변경됨으로 확인"이다).
- feedback에 코디네이터 상태를 AsyncSurface로 그려 "변경 사항을 저장하고
있습니다."를 보인다. 이 폼의 결과 불명을 확인하는 동안(결과가 effect-unknown)은
그리지 않는다. 확인이 끝나면 곧 결과가 바뀌고, 그 사이에 상태 문구가 하나 더
생기지 않게 한다.
참조 폼 페이지와 create:feature 쓰기 슬라이스 템플릿을 같이 고쳤다.
버린 대안
문구만 보이고 버튼은 켜 둔다(리뷰 문서가 포커스 때문에 권한 쪽): 확인 중에는
문구를 그릴 수 없어(위) 그때 버튼이 다시 무반응이 된다. 끄는 버튼에 포커스가
없으므로 포커스를 잃지 않는다.
위험·한계
- 생성기 쪽은 생성 결과 문자열만 단위 테스트가 본다. 다시 마운트하는 동작은
참조 폼 테스트로만 확인한다. 생성 기능의 기존 테스트는 test:feature-scaffold
(FE-GATE-020)와 test:sample-removal에서 돈다.
- 다른 탭이나 새로고침은 해당 없다(코디네이터는 앱 메모리 안이다).
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/features/reference-feature/reference-page.test.tsx
tests/unit/create-feature.test.ts
Refs: 1105/08-04
문제
commandEffect.refusedBeforeWrite의 조립 검사는 code 문법, 멱등성 접두사,
중복, Envelope 여부만 본다. 계약 문서 6.1절은 BAD_PARAMETER(어느 층이든
IllegalArgumentException), MAPPING_FAILED(멱등성 응답 직렬화는 action 뒤),
DB_* 8개, LOCK_ACQUISITION_TIMEOUT, fileserver code를 "쓰기 뒤 가능"으로
적는다. 이 code를 목록에 적어도 조립이 통과하고, 그 code로 온 400·409·422가
NOT_APPLIED가 된다. 쓰기 뒤에 난 실패를 사용자가 다시 저장하면 새 키나 키
없는 새 요청이 나가 같은 항목이 둘 생길 수 있다(리뷰 실험 X2: 네 code가
조립을 통과하고 모두 NOT_APPLIED).
고른 방법
6.1절의 "쓰기 뒤 가능" 플랫폼 code를 src/contracts/external-contract-runtime.ts에
PLATFORM_CODES_POSSIBLY_AFTER_WRITE로 두고, assertRefusedBeforeWrite가 그
code의 선언을 6.1절을 이유로 거절한다. 실행기의 fail-close(조립 없이 부른
경우)도 같은 목록을 무시한다. 목록을 adapters가 아니라 contracts에 둔 것은
조립 검사가 adapters를 import할 수 없기 때문이다(리뷰 문서의 최소 개선은
backend-envelope.ts에 두라고 했다). backend-contract-pin.test.ts가 계약 문서
6.1절 표의 "쓰기 뒤 가능" 행을 읽어 목록과 양방향으로 대조한다. 참조 도메인
code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 테스트의 예외
목록에 적고 선언할 수 있게 둔다.
버린 대안
- 매뉴얼 문장만 둔다(현상 유지): 폼을 막는 code를 넣고 싶어지는 바로 그
자리에 통제가 없다.
- 업무 code 접두사 규칙(<FEATURE>_로 시작하는 code만 허용): 다운스트림 code
이름을 강제해 과하다.
위험·한계
- 이미 이 code를 적은 다운스트림 계약은 부팅에서 조립이 실패한다. 의도한
실패다.
- 6.1절 표에 플랫폼 code가 더해지면 목록도 같이 고쳐야 한다. 대조 테스트가
알린다. 백엔드가 code를 더한 것은 pin을 올릴 때 6.1절을 다시 읽어야 안다.
- 업무 code를 잘못 선언하는 것은 여전히 막지 못한다(기능 작성자의 판단).
- 대조 테스트는 계약 문서를 읽으므로, 문서를 복사하지 않는 기능 제거
드릴(FE-GATE-020의 optional-recipe·browser-file-storage·realtime)에서는
돌지 않는다. `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에
`tests/unit/backend-contract-pin.test.ts`를 더했다. 저장소 자신의 test:unit은
그대로 돌린다.
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts
tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts
corepack pnpm test:optional-recipe-removal
BREAKING CHANGE: refusedBeforeWrite에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔
플랫폼 code(PLATFORM_CODES_POSSIBLY_AFTER_WRITE)를 적으면
composeContractContributions가 거절한다. 그 code를 목록에서 지운다. 그 code의
실패는 결과 불명으로 남는다.
Refs: 1105/03-01
문제: 빌드는 `dist`, `.generated/frontend-runtime`, `artifacts/release`·
`artifacts/quality`에 고정으로 쓰고, 다섯 Playwright 설정은 결과·report·
JUnit을 `artifacts/tests/<이름>/`에 고정으로 쓴다. 한 checkout에서 두
번째 e2e 실행이 시작하면 빌드 1단계가 첫 실행의 preview가 서빙 중인
`dist`를 지우고, Playwright가 `outputDir`을 비워 첫 실행의 trace를 지운다.
증거 파일도 늦게 끝난 쪽 것으로 섞인다(1105/12-04).
고른 방법: 변수 두 개로 나눈다(`scripts/lib/run-isolation.ts`).
- `TEST_RUN_ID`: Playwright 설정이 읽는다. 값이 있으면 그 실행의 결과·
report·JUnit과 서빙할 빌드를 `.tmp/runs/<id>/` 아래 같은 상대 경로에
둔다. 없으면 지금 경로 그대로라 게이트, CI upload, 증거 검사가 읽는
곳이 바뀌지 않는다.
- `RUN_OUTPUT_ROOT`: 설정이 web server에만 넘긴다. 빌드 단계 전부
(`build-frontend`, contract set, runtime config, SW asset 목록, SW 빌드,
build manifest)와 `vite.config.ts`가 읽어 `dist`·생성 모듈·증거·Vite
캐시를 그 아래에 쓴다. preview는 `--outDir`로 같은 `dist`를 서빙한다.
빌드 코드는 `TEST_RUN_ID`를 읽지 않는다. e2e worker가 저장소 복사본을
빌드할 때(fixture-builds, service-worker-builds) runner 환경을 물려받는데,
그 빌드는 복사본 자기 `dist`에 써야 하기 때문이다.
두 루트는 `.` 또는 `.tmp/` 아래만 받는다. git, Tailwind 소스 스캔(report
안 문자열이 CSS에 들어가지 않게), Vite watcher, vitest, 저장소 복사
helper가 모두 `.tmp`를 건너뛴다. service-worker-builds의 복사 제외 목록에
`.tmp`를 더했다(fixture-builds와 같아짐). build manifest의 경로는 빌드가
쓴 폴더 기준 상대 경로로 둔다.
`vite.config.ts`가 새로 가져오는 `scripts/lib/run-isolation.ts`는 저장소
일부를 임시 루트에 복사해 빌드하는 두 목록(초기 JS 측정
`scripts/scale/measure-feature-shape-growth.ts`,
`tests/unit/product-feature-selection-build.test.ts`)에도 더한다.
Storybook은 run ID가 있으면 `build:storybook`의 두 단계를 다른 `-o`로
돌린다. 같은 단계인지는 단위 테스트가 package script와 대조한다.
버린 대안: 운영 증거 경로(54개 스크립트, `config/ci/gates.json`)까지 run
ID로 옮기기. 게이트와 workflow upload가 고정 경로를 읽으므로 이번 범위
밖이다(아래 한계). 실행마다 저장소를 임시 폴더로 복사하기: 매번 수십
MB 복사와 node_modules 링크가 들고, 개발자가 보는 결과 위치가 사라진다.
위험·한계: 포트는 아직 고정이라 이 커밋만으로는 두 실행이 함께 돌지
못한다(다음 커밋). `ci:gate`와 증거 검사(`check:test-evidence`,
`verify:browser-capability-evidence`)는 기본 경로만 읽는다. run ID를 준
채 게이트를 돌리면 증거가 기본 경로에 새로 생기지 않아 게이트가 "not
freshly produced"로 실패한다(통과로 새지 않는다). Storybook 내부 캐시
(`node_modules/.cache`)는 여전히 공유한다. capability 설정
(`playwright.capabilities.config.ts`)은 test:browser-file-storage-removal이
capability와 함께 지운다. 설정 테스트는 그 파일이 있을 때만 그 설정을 읽고,
경로를 변수로 두어 타입 검사가 그 파일을 요구하지 않는다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts tests/unit/run-output-root-build.test.ts
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts
corepack pnpm test:browser-file-storage-removal
Refs: 1105/12-04
문제
접근성 e2e는 보호 라우트의 목록 조회에 빈 목록을 답한다. 자원 하나를
읽는 상세 라우트(참조 기능의 상세, 생성기 --with-create의 상세)는
일반 답이 없어 실패 화면에서 axe를 돌린다. 그런데
scripts/write-a11y-report.ts는 설치된 라우트 전체를 scope에 넣고
automatedStatus "passed"를 쓴다. 화면 내용은 한 번도 검사하지 않은
라우트가 통과로 보고된다. annotation은 test 결과에만 남는다.
고른 방법과 버린 대안
- scripts/lib/a11y-data-state.ts(새 파일): 라우트 test가 끝날 때
자기 상태를 artifacts/tests/a11y-data-state/<ROUTE_ID>.json에 남긴다.
실패 화면으로만 봤으면 이유를 쓰고, 아니면 지운다. 그래서 라우트마다
마지막 실행이 정한다. 세 엔진이 같은 파일을 쓰므로 임시 파일에 쓰고
rename한다.
- tests/e2e/accessibility.spec.ts: 위 기록을 남긴다(공개 라우트와
데이터 상태로 본 라우트는 지운다).
- a11y.json schemaVersion 2: scope에는 자기 상태로 검사한 라우트만,
notChecked에는 실패 화면으로만 본 라우트와 이유를 넣는다. 둘을
합치면 설치된 라우트 레지스트리와 같아야 한다(schema가 본다).
- 상세 라우트를 실제 데이터 상태로 검사하는 안은 버렸다. 출력
validator에서 유효한 값을 일반적으로 만들 수 없고, 기능마다 견본
응답을 받는 자리를 새로 열어야 한다.
- annotation을 Playwright JSON reporter로 읽는 안은 버렸다. test:a11y
스크립트의 reporter와 산출물 경로를 바꿔야 하고, 경로는 다른 작업
(12-04)이 바꾸는 중이다.
- 매뉴얼(docs/manual/reference/create-feature.md)에 상세 라우트가
notChecked로 적히고 수동 검토가 맡는다고 적는다.
위험·한계
- a11y.json 모양이 바뀐다(schemaVersion 1 → 2, scope 의미, 새 필드).
템플릿 안의 소비자는 ci-artifact-validator 하나이고 같이 바꿨다.
- 템플릿 상태에서도 참조 기능의 상세 라우트가 notChecked로 나온다.
지금까지 실제로 검사하지 않던 것이 드러나는 것이다.
- 기록 디렉터리는 artifacts/tests 아래 고정 경로다. 12-04가 산출물
경로를 실행마다 나누면 이 경로도 따라가야 한다.
- 라우트 test가 돌지 않은 실행에서는 그 라우트의 지난 기록이 남는다.
지난 기록이 "검사 안 함"이면 덜 주장하는 쪽이라 위험하지 않다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
corepack pnpm test:a11y (세 엔진) 뒤 artifacts/tests/a11y.json의
notChecked에 REFERENCE_RESOURCE_DETAIL이 있고 scope에 없어야 한다.
- RED: 부모 커밋에는 scripts/lib/a11y-data-state.ts가 없어 새 unit
test 파일 전체가 실패한다.
Refs: 1103/11-01
BREAKING CHANGE: artifacts/tests/a11y.json이 schemaVersion 2가 된다. scope는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 notChecked 배열에 { routeId, reason }으로 들어간다. scope를 설치된 라우트 전체로 읽던 도구는 scope와 notChecked를 합쳐 읽는다.
문제
feature-and-app-roots-do-not-reach-adapters는 기능 루트 파일
(src/features/*.ts, src/features/<id>/*.ts), src/contexts, src/apps만 본다.
그래프는 간선 하나씩 검사하므로, 기능 안에 계층이 아닌 폴더(support/ 등)를
만들어 그 파일이 http adapter 배럴을 import하고 기능 presentation이 그 파일을
import하면 presentation이 구체 adapter에 닿는다. 1105 리뷰 12-R3 변이에서
check:architecture와 ESLint가 둘 다 통과했다.
고른 방법
- 규칙의 from을 "src/features 아래 모든 파일, 기능의 adapters/ 폴더 밖"으로
바꾼다(`^src/(features/|contexts/|apps/)`, pathNot
`^src/features/([^/]+/adapters/|feature-adapter-contribution\.ts$)`). 규칙
주석이 이미 "기능 안에서는 adapters/ 폴더만 src/adapters에 닿는다"고 적고
있었고, 그 문장을 경로로 옮긴 것이다. 파일 단위 예외는 기존 하나
(feature-adapter-contribution.ts, type only) 그대로고 새로 더하지 않았다.
- domain·application·presentation은 자기 규칙이 이미 src/adapters를 막는다.
이제 그 파일들이 src/adapters를 import하면 이 규칙도 같이 걸린다(위반 두 줄).
더 엄격해질 뿐 허용이 바뀌지는 않는다.
- 지금 src/features에서 src/adapters를 import하는 곳은 reference-feature의
adapters/ 두 파일과 feature-adapter-contribution.ts뿐이라 새 위반은 없다.
create:feature가 만드는 adapter import도 adapters/ 안이다.
- 그래프 회귀 fixture에 support/ 재수출(거절), 그것을 읽는 presentation,
기능 adapters/ import(허용)를 더하고 check:architecture에 두 단언을 더했다.
규칙 경로를 check:architecture와 같은 방식으로 읽는 vitest 테스트를 더했다.
- layers.md 표와 매뉴얼 01의 설명을 고쳤다.
- 버린 대안: 계층 밖 폴더 자체를 금지(폴더 이름 목록 검사). 제품이 contracts/
같은 다른 이름을 쓰면 계속 목록을 고쳐야 한다. 규칙마다 support/ 패턴 추가:
다음 폴더 이름에서 같은 틈이 난다.
위험·한계
- 다운스트림이 기능 안 adapters/ 밖에서 src/adapters를 import하고 있었다면 이제
check:architecture가 실패한다. 그 파일을 adapters/로 옮기면 된다.
- ESLint는 여전히 간선 하나만 보므로 이 경로를 잡지 않는다. 그래프가 잡는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/architecture/feature-adapter-reach.test.ts, corepack pnpm
check:architecture(그래프 fixture 단언 2개 추가 PASS, 저장소 위반 0 기대).
- RED 기대: "rejects a concrete adapter import from a feature folder that is not
a layer", "leaves a feature's adapters folder and the type-only contribution
file to reach adapters"(support/adapters/ 경로 단언).
Refs: 0929/12-03
문제
제품 overlay(config/ci/product-gates.json)의 mergeGates는 product_merge_gate
job으로 렌더링되는데, 다른 job이 이 job을 기다리지 않는다. release_gate는
merge_gate만 기다린다. 그래서 제품 검사(예: 짝 백엔드 계약 검사)가 실패해도
같은 run의 release·immutable_build·promotion·deployment는 그대로 돈다. 브랜치
필수 검사는 PR merge만 막는다. job 그래프는 계약이 고정해서(ci-gates.ts의
expectedJobGraph) 제품이 연결을 더할 방법도 없다.
고른 방법
- overlay에 게이트가 있으면 release_gate의 needs에 product_merge_gate를 더해
렌더링한다(`needs: [merge_gate, product_merge_gate]`). release_gate는 release
단계의 첫 job이고 뒤의 job은 모두 그것을 거쳐 기다린다. 템플릿 게이트가
release를 막는 방식과 같다.
- 연결은 렌더링에서만 더한다. gates.json과 계약 그래프 검사는 그대로라 템플릿
job 그래프와 check:ci의 엄격함은 바뀌지 않는다. 게이트가 없으면 workflow
바이트가 같다(.gitea/workflows/quality-gates.yml 변경 없음).
- workflowGateExecutionFailures(check:ci가 부름)가 제품 게이트가 있는데
release_gate가 product_merge_gate를 기다리지 않는 workflow를 거절한다.
"실행된다"와 "막는다"를 따로 본다.
- 문서(ci-quality-gates.md, README)에 release 단계가 제품 job을 기다린다고
적었다.
- 버린 대안: (a) 문서에만 "막지 않는다"고 적기. 제품이 막을 방법이 계속 없다.
(c) 게이트마다 blocksRelease 칸. 선택권은 주지만 칸이 늘고, 불안정한 제품
검사가 생기기 전에는 필요가 없다. 계약 그래프 검사에 overlay 예외를 넣는 것:
템플릿 계약이 제품 overlay를 알아야 한다.
위험·한계
- 불안정한 제품 게이트는 이제 release도 멈춘다. 그때는 (c)로 간다.
- Gitea가 needs와 기본 success() 조건을 GitHub Actions처럼 처리한다고 본다.
실제 runner에서는 확인하지 못했다(Actions 꺼짐).
- 제품 게이트를 이미 쓰는 다운스트림은 generate:ci-workflow를 다시 돌려야
check:ci를 통과한다(생성 YAML의 release_gate needs 한 줄이 바뀐다).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/product-ci-overlay.test.ts tests/unit/ci-workflow-generation.test.ts,
corepack pnpm check:ci.
- RED 기대: "holds the release stage until the product merge gates pass",
"runs product merge gates in a job of their own, apart from the template gates".
Refs: 1105/13-02
문제
verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의
작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은
옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1,
짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면
pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는
"확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지
않았다.
고른 방법
- 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이
작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서).
- 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의
트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다.
hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다.
- checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신
unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다.
- `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다.
실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다.
- 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만
pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다
`git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다.
위험·한계
- pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부
"not verified"다. 실패하지 않는 대신 확인도 하지 않는다.
- 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터
바꿔야 한다.
- pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다.
- 보고서 schema는 그대로다(unverifiedLinks 주석만 고침).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm
verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED +
not verified 기대).
- RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or
the working tree", "reports the references as not verified when the
checkout does not have the pinned commit", "fails a link out of the
repository into a repository that is not paired".
Refs: 1105/12-02
문제: 짝 백엔드 답 표 JSON(backend-idempotency-answers.json)이 pin한
백엔드 http-contract.md와 같은지 아무 검사도 보지 않는다.
backend-contract-pin.test.ts는 pin과 답 표 두 파일만 읽고, drift
스크립트는 pin과 HEAD 사이에 문서 글자가 바뀌었는지만 본다. 그래서
답 표 status 오타나 옮기지 않은 행(§4 RATE_LIMIT_*)은 어디서도 걸리지
않는다. drift 스크립트는 옆 checkout이 없으면 "skipped"로 rc=0이고
(worktree에서 늘 그렇다), 매뉴얼에는 스크립트가 없다.
고른 방법: 게이트가 백엔드 checkout 없이 볼 수 있게, 백엔드 §2·§4 표의
`|` 줄을 pin 커밋 그대로 config/contracts/backend-http-contract-excerpt.json
에 옮겼다. 읽는 함수는 scripts/lib/backend-contract-excerpt.ts 하나다.
- test:unit(backend-contract-pin.test.ts): 답 표의 행마다 사본의 같은 절에
같은 code·status 행이 있는지, 사본의 행마다 답 표에 있거나 pin의
`notCopied`에 이유와 함께 있는지 본다. `notCopied`에는 RATE_LIMIT_* 둘을
적었다(리뷰가 지적한 sectionsCompared §4의 실제 범위).
- check:backend-contract-drift(게이트 밖): pin 커밋의 문서에서 같은 표를
읽어 사본과 글자 단위로 비교하고, 답 표도 그 표와 비교하고, pin 뒤
HEAD에서 바뀐 사본 표 행을 찍는다. checkout이 없거나 pin 커밋·문서가
없으면 rc=2("not compared")로 끝난다. 기본 경로는 main checkout 옆이라
linked worktree에서도 같은 백엔드를 찾는다. `--write-excerpt`는 pin을
올릴 때 사본을 pin 커밋에서 다시 옮긴다.
- 매뉴얼 01 Envelope 단계와 계약 문서 4.1에 언제 무엇을 돌리는지 적었다.
버린 대안: 백엔드 문서의 digest만 pin에 두는 것. 게이트는 digest로 답
표를 확인할 수 없다. 계약 패키지(리뷰 안 D)는 배포 경로가 아직 없다.
위험·한계: 사본과 백엔드 문서의 일치는 여전히 백엔드 checkout이 있을
때만 drift 스크립트가 본다. 게이트는 답 표와 사본의 일치만 본다. 사본을
손으로 같이 고치면 게이트는 통과한다(drift 스크립트가 잡는다). 답 표의
refusedBeforeWrite·sameKeyResend는 백엔드 문장(클라이언트 행동)을 사람이
읽은 값이라 기계로 대조하지 않는다. 그 문장이 바뀌면 사본 diff와 drift
출력에 보인다. 백엔드 표 형식(머리글 `error.code`·`코드`·`status`)이
바뀌면 파서도 고친다. pin의 comparedOn을 사본을 옮긴 날로 올렸다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
drift 테스트는 가짜 백엔드 git repo로 D6g(pin 뒤 status 변경), 답 표
status 오타, 사본 오타, 옮기지도 적지도 않은 행, checkout 없음,
--write-excerpt를 돈다.
Refs: 1105/07-01
문제: 빌드, dev 서버, 타입 검사, vitest가 모두 시작할 때
`scripts/generate-product-feature-index.ts`로 `src/.generated/*.ts`를
다시 쓴다. 생성기는 `writeFile`로 파일을 제자리에서 비우고 다시 썼다.
한 checkout에서 두 실행이 겹치면, 한쪽이 파일을 비운 순간 다른 쪽의
Vite나 tsc가 빈 파일이나 반쯤 쓴 파일을 읽을 수 있다(1105/12-04의
"한 checkout 두 실행" 중 공유 소스 파일 부분).
고른 방법: 내용이 같으면 쓰지 않는다. 다르면 같은 폴더의 임시 파일에
쓰고 rename으로 바꾼다. 읽는 쪽은 옛 파일이나 새 파일 하나만 본다.
같은 선택(같은 PRODUCT_APP_ID·VITE_PRODUCT_FEATURES)으로 도는 두 실행은
아예 쓰지 않는다.
버린 대안: 실행마다 `src/.generated`를 따로 두기. 앱 소스가 이 경로를
import하므로 경로를 바꾸면 Vite·tsc·ESLint 설정이 모두 따라 바뀐다.
잠금 파일: 겹친 실행을 직렬로 만들 뿐이고, 죽은 프로세스가 잠금을
남긴다.
위험·한계: 선택이 서로 다른 두 실행(예: 한쪽만 VITE_PRODUCT_FEATURES=none)은
여전히 서로의 인덱스를 바꾼다. 그건 실행이 아니라 checkout 상태가 다른
것이라 이 커밋 범위 밖이다. 임시 파일은 `.tmp`로 끝나 tsc·Vite·ESLint
대상이 아니다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/product-feature-index-write.test.ts
Refs: 1105/12-04
문제: ci:gate는 명령 출력을 artifacts/quality/gates/FE-GATE-<NNN>.txt에만
쓰고 콘솔에는 PASS/FAIL 한 줄만 남긴다(scripts/run-ci-gate.ts). release
단계 job immutable_build는 후보 tar만, 그것도 성공했을 때만 올린다. 그래서
실제 run에서 FE-GATE-015·027이 왜 실패했는지와 FE-GATE-027이 쓰는
artifacts/security/dependency-advisories.json(1103/13-03의 신호)이 runner
작업 디렉터리와 함께 사라진다. 다른 gate job은 artifacts/를 if: always()로
올린다.
고른 방법:
- config/ci/gates.json의 immutable_build 마지막에 upload 단계를 더한다.
transfer ID는 immutable-gate-evidence, 이름은
immutable-gate-evidence-<run>-<attempt>, always: true. 대상은
FE-GATE-015·027의 log와 evidence 산출물(gate 순서)과 advisory 기록 7개다.
FE-GATE-015의 verification.json 등은 후보가 만들어지지 않으면 후보 안에도
없으므로 같이 올린다.
- 계약(scripts/contracts/ci-gates.ts)이 이 단계를 고정한다. immutable_build의
단계 목록에 upload 하나가 늘고, 이 upload가 always이고 마지막 단계이며
경로가 "job이 도는 gate의 log·evidence 경로 + advisory 기록"과 같아야
한다. 경로는 계약의 artifact 등록에서 계산하므로 log 경로가 바뀌면 함께
따라온다. advisory 기록은 gate evidence가 아니라(막지 않는 신호) 경로를
scripts/lib/dependency-advisories.ts의 상수로 옮기고 scan 스크립트도 그
상수를 쓴다.
- 후보 archive의 member set, 후보 upload(always 없음), 하위 job의 download는
그대로다. 생성 workflow를 generator 출력과 같게 손으로 고쳤다.
버린 대안:
- immutable_build도 artifacts/ 전체를 올림: 다른 job과 같지만 후보 증거가
두 이름으로 나가 어느 것이 승격 대상인지 흐려진다. 필요한 파일만 고정했다.
- ci:gate가 실패한 명령의 마지막 N줄을 콘솔에 씀(리뷰 대안 c, d의 콘솔
한 줄 포함): 모든 job에 걸리고 provider 출력의 비밀 노출과 로그 상한을
다시 따져야 한다. 담당 지시 범위(업로드) 밖이라 이번에 하지 않았다.
위험·한계:
- checkout·install 단계에서 실패하면 올릴 파일이 없어 이 단계도
if-no-files-found: error로 실패한다. job은 이미 실패한 뒤라 결과는 같다.
merge·release job의 upload도 같은 동작이다.
- 실제 Gitea runner에서 stage=release를 돌려 산출물이 남는지는 확인하지
못했다(runner 없음). 확인한 것은 계약·생성 workflow까지다.
- 콘솔에는 여전히 한 줄만 나온다. 사람이 산출물을 열어야 이유를 본다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
Refs: 1105/13-01, 1103/13-03
문제: 확장자별 MIME probe(1103/06-03)는 install 조건 일부만 옮겼다.
1. install fetch는 `redirect: "error"`라 redirect가 하나라도 있으면
실패한다. probe는 `redirect: "follow"`로 받고 최종 status와 MIME만
본다. 같은 origin 안 redirect 뒤 200을 주는 호스트가 PASS다(리뷰
06-R1). FE-GATE-019가 PASS인데 워커 install은 매번 실패한다.
2. 워커 없는 빌드에서도 돈다. 주석과 문서는 이유를 워커로만 적는다.
3. live 분기의 호출 줄(`verify-hosting-headers.ts`)을 지키는 테스트가
없다. live 모드는 루프백·http를 거절해 저장소 테스트가 들어갈 수
없다. 호출을 지우는 변이가 44건 통과로 살아남았다(06-R2).
고른 방법:
1. 자산 probe 기본 fetcher를 `redirect: "manual"`로 바꾸고,
`response.redirected`이거나 `opaqueredirect`이면 관측 "redirected",
이유 "install fetch가 redirect를 거절"로 FAIL이다. 3xx는 지금처럼
`HTTP 3xx`로 FAIL이다. fetcher가 redirect를 따라가도 `redirected`로
잡으므로 fetcher 방식과 무관하다.
2. 동작은 그대로 두고 의도를 주석과 운영 문서에 적었다. 워커가 없어도
`nosniff` 아래 script·style은 MIME이 틀리면 페이지가 깨지고, 나중에
워커를 켜는 릴리스가 호스팅을 다시 확인하지 않아도 된다. 글꼴·이미지는
페이지에 피해가 없는데 FAIL한다는 것도 적었다. 워커 없는 빌드에서
script·style만 보도록 좁히는 것은 검사를 약하게 하는 정책 결정이라
하지 않았다(결정 대기, 템플릿 소유자).
3. live 분기 전체를 `probeLiveHosting`(release surface +
자산 MIME)으로 빼고 스크립트는 그것만 부른다. 테스트가 fetcher
대역으로 이 함수를 돌려 CSS `text/plain`이 FAIL인지 본다. 자산 probe
호출을 빼면 이 테스트가 실패한다. 스크립트에서 `probeLiveHosting`
호출을 빼면 live 결과가 비어 cache-control 행이 모두 FAIL이라 스스로
드러난다.
버린 대안: 문서에 한계만 적기(리뷰 (b)). 1·3이 그대로다.
위험·한계: 정규 경로 규칙으로 자산을 redirect하는 호스트는 이제
FE-GATE-019에서 FAIL이다. 워커가 없는 제품도 마찬가지다(2의 판단).
실제 호스트로 live 모드를 돌리지는 않았다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "fails an asset the host answers only after a redirect"(옛 probe는
redirect 뒤 200을 PASS), "checks every built asset type besides the
release surfaces"(옛 코드에 `probeLiveHosting`이 없음)가 실패한다.
- 변이(06-R2 대응): `probeLiveHosting`에서 `probeAssetContentTypes` 결과를
빼면 "checks every built asset type ..."가 실패해야 한다.
Refs: 1105/06-02
문제: 응답 DTO를 `.strict()`로 바꾸고 FE-REG-SCHEMA 행의
`unknownFieldPolicy`를 STRIP_UNKNOWN에서 REJECT_UNKNOWN으로 같이 고치면
check:registries가 behavior-change로 통과한다(리뷰 배치 07-R1). 1103/07-03
수정은 행과 검증기를 묶었지만 등급은 그대로였다. 그 뒤 백엔드가 응답에
필드 하나를 더하면 그 API는 SCHEMA_MISMATCH로 실패한다. 같은 경계에서
FE-REG-API는 acceptedStatuses 축소를 breaking으로 본다.
고른 방법: 분류기에 규칙 하나를 더한다. `direction: "RESPONSE"` 행의
`unknownFieldPolicy`가 REJECT_UNKNOWN이 아니던 값에서 REJECT_UNKNOWN으로
바뀌면 kind `response-reader-narrowed`, breaking이다. 반대 방향
(REJECT→STRIP, 읽는 쪽을 넓힘)과 REQUEST 행(프론트가 스스로 채우는 값)은
그대로 behavior-change다. 버린 대안: governance의 FE-REG-SCHEMA
breakingFields에 `unknownFieldPolicy`를 넣는 것(리뷰 안 B). 넓히는 변경까지
증거를 요구하게 되고, governance 계약이 바뀌어 템플릿과 다운스트림 모두
기준선을 다시 승인해야 한다. 이 규칙은 기준선과 governance를 바꾸지 않는다.
리뷰 안 (1)의 fieldTypes 선언도 같은 이유로 하지 않았다.
위험·한계: 규칙은 칸 이름(`unknownFieldPolicy`)과 값 어휘
(src/contracts/schema-registry.ts)에 묶여 있다. 어휘를 바꾸면 이 함수도
고친다. route-params·route-search(REQUEST 방향, URL을 읽는 쪽)를
REJECT_UNKNOWN으로 좁히는 변경은 여전히 behavior-change다. 지금 템플릿
스냅샷은 기준선과 같아 결과는 none 그대로다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/registry-compatibility.test.ts
리뷰 07-R1 패치(응답 DTO `.strict()` + 응답 행 두 개 REJECT_UNKNOWN)를
다시 적용하면 check:registries가 `breaking change missing evidence:
FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy:
response-reader-narrowed`로 실패해야 한다.
Refs: 1105/07-02
문제: 사전 캐시 수집기(`collectStaticAssets`)는 dist 전체를 돌고 파일
이름만 해시 정규식으로 본다. `public/` 파일은 이름 그대로 dist 루트에
복사되는데, `apple-touch-icon.png`, `android-chrome-192x192.png`,
`safari-pinned-tab.svg`는 정규식에 걸려 immutable 자산으로 들어간다(리뷰
06-R1). 제품이 같은 이름으로 아이콘을 바꾸고 CDN이 옛 바이트를 주면 새
릴리스 install이 INTEGRITY_MISMATCH로 통째로 거절된다. 이전 릴리스
fallback, 호스팅 정책 `/assets/*`, MIME probe, 레시피 문서는 모두
`assets/`만 가정한다.
고른 방법: 리뷰 06-01의 (a). 계약 모듈에 `BUILD_ASSET_DIRECTORY =
"assets/"` 하나를 두고, 수집기는 그 아래 파일만 받는다. 워커 fallback
(`service-worker-static-assets.ts`)과 probe(`hosting-probe.ts`)도 같은
상수를 읽는다. `build.assetsDir`를 바꿀 때(0925/06-08) 이 상수 한 곳만
고치면 된다. 수집기의 `.vite/` 제외는 새 조건이 덮으므로 지웠다. 레시피
문서에 루트 파일이 빠진다는 문장을 더했다.
버린 대안:
- 정규식을 Vite 해시 형식(8자 고정)으로 좁히기. 우연히 맞는 이름이 남는다.
- 문서만 고치기. 아이콘 문제가 그대로다.
위험·한계: 루트에 해시 이름 파일을 일부러 두는 제품은 그 파일이 사전
캐시에서 빠진다. Vite는 그런 파일을 만들지 않는다. 상수는 vite 설정에서
읽지 않는다. `build.assetsDir`를 바꾸는 제품은 상수도 같이 바꿔야 한다
(0925/06-08은 그대로 남는다).
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/service-worker-web-push-remediation.test.ts tests/unit/service-worker-runtime.test.ts tests/unit/hosting-probe.test.ts tests/unit/service-worker-build-output.test.ts
- RED: "precaches only the assets directory, not public files at the dist
root"가 옛 수집기에서 루트 아이콘 세 개를 받아 실패한다.
Refs: 1105/06-01
문제
1103 수정이 더한 플랫폼 규칙 테스트 둘이 참조 샘플에 기댄다. 샘플을
지우면 두 테스트가 사라지거나 비어도 test:all과 제거 드릴이 통과한다.
- MAX_RETRY_ATTEMPTS가 실행기에 닿는다: 유일한 테스트가
tests/features/reference-feature/reference-runtime-composition.test.ts
에 있다. createRuntimeAdapters는 설치된 기능의 HTTP로만 실행기에 닿아,
기능이 없으면 시험할 길이 없다. REQUEST_TIMEOUT_MS도 같은 모양이다.
- 복구 중인 세션은 보호 라우트에서 기다린다:
tests/unit/navigation-policy.test.ts는 설치된 보호 라우트를 돌며
단언하는데, 보호 라우트는 모두 샘플 것이라 샘플을 지우면 반복이 0번이다.
고른 방법과 버린 대안
- src/bootstrap/runtime-adapters.ts: 설정 두 값과 auth profile 표로
실행기를 만드는 부분을 createRuntimeContractHttpExecutor로 뺀다.
조립 루트는 이 함수로만 실행기를 만든다. tests/unit/runtime-adapters
.test.ts가 테스트 계약(TEST_LIST, 재시도 예산 2)으로 MAX_RETRY_ATTEMPTS
0·1·2에 1·2·3번 나가는지, REQUEST_TIMEOUT_MS 5가 10초 계약을 5ms에
끊는지 본다. 이 파일은 이미 제거 드릴의 공통 테스트 목록에 있다.
- tests/unit/session-route-access.test.ts(새 파일): component 테스트와
같은 방법으로 생성 index를 mock해 tests/helpers/fixture-feature.tsx를
설치하고, 보호 라우트 FIXTURE_ITEMS에서 네 세션 상태의 결정을 본다.
decideRouteAccess에 라우트 정의를 받는 순수 함수를 따로 두는 안(리뷰
ⓐ)은 버렸다. fixture 기능을 설치하는 방법이 이미 있어서 운영 코드를
바꾸지 않고 실제 getRoute 경로까지 시험할 수 있다.
- scripts/test-sample-removal.ts: 새 파일을 공통 테스트 목록에 넣어,
제거 드릴이 그 파일이 남았는지 본다.
- 매뉴얼에 "샘플을 지우면 다시 고정한다"고만 적는 안(ⓒ)은 사람이
기억해야 해서 버렸다.
위험·한계
- 조립 루트가 이 함수 대신 실행기를 직접 만들도록 바뀌면 새 unit
테스트는 그걸 모른다. 템플릿 상태에서는 참조 기능 테스트가 계속
조립 루트 전체를 지킨다.
- 샘플을 지운 복사본에 변이를 넣어 돌리지는 않았다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/runtime-adapters.test.ts tests/unit/session-route-access.test.ts tests/unit/navigation-policy.test.ts tests/features/reference-feature/reference-runtime-composition.test.ts
- RED: 부모 커밋의 운영 코드에는 createRuntimeContractHttpExecutor가
없어 runtime-adapters.test.ts의 새 4건이 실패한다.
- 변이: 새 함수의 maxRetryAttempts를 상수 2로 바꾸면 "honours
MAX_RETRY_ATTEMPTS 0/1"이, navigation-policy.ts의 recovery-pending
분기를 show-sign-in으로 바꾸면 session-route-access.test.ts의
"answers a recovery-pending session …"이 실패해야 한다.
Refs: 1105/10-01
문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid
--unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가
아니므로 비특권 user namespace가 있어야 한다. 사전 점검
(scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd
bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트
(Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를
낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed
RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간
초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도
없고 운영 원장의 일회성 메모에만 있다.
고른 방법:
- 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한
번 띄운다. 실패하면 "this host does not allow unprivileged user and
network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값,
고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1.
기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다.
- 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고
run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이
갈라지면 점검이 다른 것을 시험하게 된다.
- 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access·
readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다.
- config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다.
gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의
runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로
그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty
규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가
아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선
재기록 불필요).
- 요구 목록 세 곳(docs/operations/ci-quality-gates.md,
docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge
게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를
두었다.
버린 대안:
- namespace가 없으면 provider 테스트를 skip: 거짓 초록이다.
- FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다.
- probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope
안과 밖의 결과가 같았다. 직접 실행이 더 단순하다.
- workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직
없다. 주석이 지금 가능한 가장 작은 표시다.
위험·한계:
- probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른
옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로
실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다.
- 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만
한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서
이유와 함께 실패한다.
- gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과
제품 overlay는 그대로 통과한다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
- desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과
namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지
Refs: 1105/12-01, 1105/11-02
문제: 계약 조립이 실패하면 check:registries 출력에 같은 원인이 두 번
나온다. 1103/09-07 수정이 ContractContributionError의 message 끝에
reason을 붙였고, 1103/14-06 수정이 loadErrorText에서 message 뒤에
"(reason: ...)"를 또 붙였다. 두 수정이 다른 브랜치에서 들어왔다.
기존 테스트는 reason이 message에 없는 가짜 오류로만 시험해 중복을
보지 못했다.
고른 방법: loadErrorText가 message에 reason이 이미 들어 있으면 붙이지
않는다. reason을 message에 싣지 않는 오류(기존 테스트의 가짜 오류)는
지금처럼 "(reason: ...)"가 붙는다. 버린 대안: ContractContributionError
message에서 reason을 다시 빼는 것. message만 찍는 다른 출구(부팅 오류,
테스트 출력)가 원인을 잃는다(1103/09-07이 고친 문제).
위험·한계: message 첫 줄만 보므로 여러 줄 reason은 다시 붙는다. 지금
reason은 한 줄이다. docs/manual/reference/errors.md의 출력 형식 줄을
실제 출력에 맞췄다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/registry-governance.test.ts
새 테스트는 실제 ContractContributionError를 던지는 source로
check:registries를 돌려 원인이 한 번만 나오는지 본다.
Refs: 1105/09-03
문제
README의 로컬 merge 게이트 반복문과 매뉴얼 01, 생성 명령 출력은 CI=true와
CI 빌드 식별값 없이 돌리는 법만 적는다. 그렇게 통과해도 workflow(CI=true)에서
떨어지는 결함 두 건(1103/11-07, 11-08)이 이 차이로 숨었다.
고른 방법
- README 반복문 아래에 workflow와 같은 env 블록(CI=true, VITE_COMMIT_SHA,
VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE digest)과 깨끗한 clone에서 돌리라는
말을 더한다. 테스트가 만드는 로컬 빌드는 이 값과 무관하게 로컬 빌드로
돈다는 것도 적는다.
- 매뉴얼 01 "merge 전에 돌릴 것"과 생성 명령 Next 2번이 그 블록을
가리킨다.
검증
- verify:documentation PASS_SCOPED, tests/unit/create-feature.test.ts 43건.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-08
문제
workflow는 모든 job에 CI=true와 CI 빌드 식별값을 준다. 메인 세션이 깨끗한
clone에서 그 env 그대로(CI=true 포함) merge 단계 14개를 돌리자 FE-GATE-005·
008·020이 실패했다.
- vitest 안의 fixture 빌드(tests/e2e/support/fixture-builds.ts →
build-frontend.ts)가 CI=true를 물려받아 release 빌드처럼 검사된다.
af312de가 vitest에서 VITE_COMMIT_SHA를 지워 "missing required CI build
environment: VITE_COMMIT_SHA"로 멈춘다(service-worker-build-output 7건이
돌지 않음, 제거 드릴 안에서도 같다).
- 시각 골든 build(9bddfa5)가 VITE_COMMIT_SHA="local"을 받는데 CI=true가
40·64자리 hex를 요구해 webServer가 뜨지 않는다.
내 X4가 CI=true 없이 돌아 놓쳤다. 1103/11-07과 같은 원인이다.
고른 방법
- scripts/lib/build-environment.ts에 둘을 둔다.
- localBuildEnvironment(env): spawn하는 로컬 빌드용. CI와 CI 빌드 식별값을
뺀 사본. fixture-builds.ts, service-worker-builds.ts가 쓴다.
- LOCAL_BUILD_IDENTITY: Playwright web server용. Playwright가 env를
process.env 위에 합치므로 CI를 지우지 않고 ""로 덮는다(검사는
CI === "true"일 때만). visual·capabilities·dev 설정이 쓴다.
- assertCiBuildEnvironment의 CI=true 검사는 그대로다. job 자신의 release
빌드(build:release-candidate 등)는 계속 검사된다.
- 버린 대안: 로컬 빌드에 유효한 가짜 커밋 id(0×40)를 주기. CI=true 검사의
다른 칸(CI_RUNNER_IMAGE, SOURCE_DATE_EPOCH)도 함께 맞춰야 하고, 로컬
빌드가 release 빌드인 척한다.
위험·한계
- 로컬 빌드 안에서 CI를 읽어 동작을 바꾸는 코드가 있으면 그 빌드는 이제
CI가 아닌 쪽으로 돈다(지금은 build-environment 검사뿐이다).
검증
- tests/unit/local-build-environment.test.ts 3건: 구현 전 2건 실패(RED),
CI job 자체 검사는 유지.
- CI=true·VITE_COMMIT_SHA·VITE_BUILD_ID=gitea-41-1·RELEASE_ID·
CI_RUNNER_IMAGE·SOURCE_DATE_EPOCH로: service-worker-build-output 7건,
test:visual 6/6, test:unit 2,883, test:component 270, test:integration 189
통과. 수정 전 service-worker-build-output은 7건 미실행.
- check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-08
문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.
고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
같은 조건을 dev만 따로 두게 된다.
위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
test:unit이 그 상태를 이름과 명령으로 알린다.
검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
뒤 깨끗한 clone에서 돈다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
문제
깨끗한 clone의 FE-GATE-008에서 dev server를 쓰는 capability e2e가
"requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로 1~4건씩
떨어졌다(세 번 중 세 번, 부하 9~30). 플러그인(db5728b)이 dev server 시작
때 .generated/frontend-runtime/에 manifest를 쓰는데, polling 감시
(CHOKIDAR_USEPOLLING=1)가 그 새 파일을 서버가 뜬 뒤에 보고 부팅 중인 페이지를
다시 불러오면 진행 중인 manifest 요청이 끊긴다고 본다. 플러그인을 넣기 전
같은 부하의 회차들은 66건 모두 통과했다.
고른 방법
- 자식 프로세스가 manifest를 stdout으로 내고, 플러그인은 그 문자열을
메모리에 두고 낸다. 파일을 쓰지 않으므로 감시가 볼 것이 없다.
devReleaseManifest(source)가 문자열을 돌려준다.
위험·한계
- 원인을 감시 이벤트로 직접 관측하지는 않았다(추론). 수정 뒤 재실행으로
확인한다.
검증
- tests/unit/dev-release-manifest.test.ts 2건, check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 X4
문제
test:feature-scaffold(12-02)는 기능 둘을 생성한 fixture에서 merge 단계
명령을 돈다. 15-02의 test:unit은 초기 JS 기록
(config/scale/feature-shape-ceilings.json)을 빌드와 대조한다. 두 브랜치를
합치자 드릴 안의 test:unit·test:coverage가 "initialJavascript is stale"로
실패해 FE-GATE-020이 떨어진다. 제품은 생성 명령 Next: 3번대로 기록을 다시
쓰지만 드릴은 그 단계를 하지 않았다.
고른 방법
- 생성이 성공하면 fixture를 봉인하기 전에 measure-feature-shape-growth.ts
--initial-baseline --write를 돌린다. 측정 스크립트가 없으면(샘플이 없으면)
건너뛴다. 결과는 별도 검사(initial-javascript-record)로 보고한다.
위험·한계
- 드릴이 빌드 한 번만큼 길어진다.
검증
- check:types, eslint 통과. FE-GATE-020은 깨끗한 clone에서 다시 돈다.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02, 15-performance.md 15-02
문제
c15345c의 플러그인은 apply: "serve"라 Vitest가 Vite를 띄울 때도 돌아,
test:unit마다 자식 프로세스로 manifest를 쓴다. 출력 위치
src/.generated/dev-release-manifest.json에는 자리표시자의 routeChunks(샘플
경로)가 들어 있다. test:sample-removal의 잔여 검사는 src/를 훑으므로
FE-GATE-020이 "fixture-id-residue: src/.generated/dev-release-manifest.json"으로
실패한다.
고른 방법
- 출력을 빌드의 contract set 생성물 옆 .generated/frontend-runtime/로 옮긴다
(무시 대상).
- apply가 serve이면서 VITEST가 없을 때만 돈다. 테스트는 서버에서
manifest를 받지 않는다.
검증
- browser-files capability spec(dev server) chromium 3건 통과, 생성물이 새
위치에 생긴다.
- test:unit 2,880건 통과, 실행 뒤 src/.generated에 manifest가 없다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
c15345c가 vite.config.ts에서 scripts/lib/dev-release-manifest.ts를
import한다. 초기 JS를 재는 measure-feature-shape-growth.ts와
product-feature-selection-build 테스트는 빌드할 복사본에 정해진 파일만
복사하는데(BUILD_INPUTS), 그 목록에 새 파일이 없다. 그래서 복사본의 vite
build가 "Could not resolve './scripts/lib/dev-release-manifest.ts'"로 실패해
test:unit 두 파일과 세 capability 제거 드릴이 떨어졌다. c15345c 뒤에
test:unit 전체를 돌리지 않아 놓쳤다.
고른 방법
- 두 BUILD_INPUTS에 그 파일을 더한다.
- 두 목록이 같은 내용의 사본이다. 하나로 합치는 것은 이 수정의 범위 밖으로
둔다(남은 문제).
검증
- test:unit 193파일 2,880건 통과, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
매뉴얼만으로 기능을 더한 재실험(리뷰 조치 X2)에서 안내가 틀리거나 빠진
곳이 나왔다.
- 생성 명령 출력과 매뉴얼 01이 초기 JS 기록(config/scale/feature-shape-
ceilings.json)을 말하지 않는다. 출력은 "baseline does not change"만 적는다.
- 01·create-feature.md가 "드릴은 check:bundle을 돌리지 않는다"고 적는다.
12-02 뒤로 드릴은 merge 단계 명령으로 check:bundle을 돈다.
- 로컬에서 FE-GATE-013은 VITE_COMMIT_SHA가 40자리 커밋이어야 한다. 실패한
게이트의 로그 위치가 어디에도 없다.
- 01 6단계가 "생성된 판은 파라미터가 없다"고 적지만 --with-create 상세
라우트는 codec을 넘긴다. global-ids.md의 API 경로 예가 옛 생성 경로다.
고른 방법
- 생성 명령 Next에 3번(기록 다시 쓰기)과 로그 위치·FE-GATE-013 조건을
더한다. 매뉴얼 01 "merge 전에 돌릴 것"에 같은 내용과 파일 수 상한을
적는다. 나머지 문장을 지금 동작에 맞춘다.
검증
- tests/unit/create-feature.test.ts 43건, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #2#5#6
문제
config/scale/feature-shape-ceilings.json의 initialJavascript는 지금 설치된
기능으로 만든 빌드를 기록하고, test:unit이 빌드와 대조한다(1103/15-02).
제품이 기능을 더하면 기록을 다시 써야 FE-GATE-005가 통과한다. 그러면
`test:sample-removal -- --feature=<id>`가 그 기능을 지운 fixture에서 반대
이유("record 27, build 26")로 실패한다. 두 게이트를 함께 통과시킬 방법이
없다(리뷰 조치 X2 #2).
고른 방법
- 드릴이 레지스트리 기준선을 다시 찍는 것과 같은 자리에서
measure-feature-shape-growth.ts --initial-baseline --write를 fixture에서
돌린다. 제품이 기능을 지운 뒤 할 일을 드릴이 그대로 한다.
- 샘플 제거는 측정 스크립트를 함께 지우므로 그때는 건너뛴다.
위험·한계
- 측정이 빌드를 하므로 기능 제거 드릴이 1~2분 길어진다.
검증
- eslint 통과. 기능 제거 드릴은 X4 재실행(test:feature-scaffold 안의
feature-removal)에서 확인한다.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, README.md 14.6 X2 #2
문제
`create:feature`가 만든 기능은 계약 패키지(`@org-contracts/<base>`)를
선언한다. dev server는 커밋된 자리표시자 public/release-manifest.json을
그대로 내주는데, 그 contractSet.packages는 고정된 빈 목록이다. 부팅이 이
집합을 설치된 선언과 대조하므로, 기능을 생성한 직후 `corepack pnpm dev`가
CONTRACT_SET_PACKAGE_MISSING으로 "애플리케이션을 시작할 수 없습니다"를
보인다. 같은 이유로 dev server를 쓰는 FE-GATE-008의
test:browser-capabilities가 38건 실패하고("Execution context was
destroyed"), 매뉴얼에는 이 파일을 고치라는 말이 없다. 매뉴얼만으로 기능을
더하는 재실험(리뷰 조치 X2 #3)에서 찾았다.
고른 방법
- dev 전용 Vite 플러그인(scripts/lib/dev-release-manifest.ts)이 dev server를
시작할 때 scripts/write-dev-release-manifest.ts를 자식 프로세스로 돌려
src/.generated/dev-release-manifest.json(무시되는 생성물)을 쓰고,
`/release-manifest.json` 요청에 그것을 낸다. 내용은 자리표시자에
설치된 기능의 contract set(build와 같은 buildContractSet)을 넣은 것이다.
- 자식 프로세스로 돌리는 이유: contract set을 만들려면 설치된 기능 선언을
import해야 하는데, Vite 설정이 그것을 불러오면 안 된다.
- build는 바뀌지 않는다. 빌드 manifest는 generate-build-manifest.ts가 만든다.
- 버린 대안: dev 자리표시자에서 contractSet을 빼기. V2 manifest 스키마가
contractSet을 요구한다. 생성기가 추적 파일(public/release-manifest.json)을
다시 쓰기: 기능 선택이 바뀌는 실행마다 추적 파일이 바뀐다.
위험·한계
- dev server를 켠 뒤 기능을 더하거나 지우면 dev server를 다시 켜야 한다.
- 자리표시자의 routeChunks는 여전히 손으로 둔다(부팅이 dev에서 보지 않는다).
검증
- tests/unit/dev-release-manifest.test.ts 2건(낡은 집합을 설치된 집합으로
바꾼다, 템플릿 그대로면 자리표시자와 같다).
- check:types, lint, check:architecture, check:ci 통과.
- 생성 기능을 더한 깨끗한 clone의 capability 실행은 X4 재실행에서 본다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
09-06의 완료 기준은 짝 백엔드 wire의 KEYED 생성, 400 필드 오류와 함께 409
IDEMPOTENT_IN_FLIGHT를 실행하는 기능 예제다. --with-create --keyed가 만드는
gateway 테스트는 503 IDEMPOTENCY_UNAVAILABLE 재전송만 보고 409 처리 중은 보지
않는다.
고른 방법
KEYED 생성 gateway 테스트에 409 IDEMPOTENT_IN_FLIGHT 사례를 더한다. 결과는
MAYBE_APPLIED이고 code가 그대로이며, 실행기는 스스로 다시 보내지 않는다(같은
키 재전송은 폼이 한다, http-contract.md §2). NEVER 생성은 키가 없어 이 답을
받지 않으므로 더하지 않는다.
위험·한계
- Retry-After 대기는 뮤테이션 조정자 쪽이라 이 gateway 테스트는 보지 않는다.
검증
- keyx-feature --with-create --keyed를 만들어 gateway 테스트 13건 통과, eslint
통과. 생성 기능은 지웠다. tests/unit/create-feature.test.ts 43건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
문제
--with-create(NEVER)와 --with-create --keyed(KEYED)가 만드는 코드는 단위
테스트가 텍스트로만 본다. FE-GATE-020의 두 드릴(test:feature-scaffold,
test:sample-removal)은 기본 기능 하나만 만들어 게이트를 돈다. 그래서 쓰기
slice의 타입·lint·테스트·빌드가 머지 게이트에서 깨져도 모른다(16 5.3절의
"생성 결과를 매번 게이트로 돌린다"는 전제).
고른 방법
- scripts/test-feature-scaffold.ts: 기본 기능(scaffold-feature) 옆에
scaffold-write-feature를 --with-create --keyed로 하나 더 만들고, 둘 다
만들어졌을 때 같은 게이트를 한 번 돈다. 바꾼 것은 WRITE_FEATURE_ID 상수,
create-feature-write 검사 한 개, 게이트 조건(created && createdWrite), 머리
주석이다.
- scripts/test-sample-removal.ts: 참조 기능을 지운 복사본의 create:feature
인자에 --with-create 한 개를 더했다. 쓰기 slice도 샘플에 기대지 않는다는
증거다.
- 세 변형(기본, NEVER, KEYED)이 모두 드릴의 게이트를 지난다.
- reference/create-feature.md의 드릴 설명을 맞췄다.
버린 대안
- 드릴 기능 하나를 --with-create로 바꾸기: 기본 변형이 게이트에서 빠진다.
위험·한계
- test:feature-scaffold는 기능 하나만큼(create:feature 한 번과 그 기능의
테스트) 길어진다. 게이트는 한 번만 돈다.
- 다른 작업(게이트 담당)이 같은 두 파일의 명령 목록을 고칠 수 있다. 내 수정은
위 줄로 좁혔다.
검증
- flock 아래 CHOKIDAR_USEPOLLING=1 corepack pnpm test:feature-scaffold:
rc=0, "feature scaffold: PASS (17 checks)" (생성 2 + 게이트 15), 162초.
- 같은 조건 corepack pnpm test:sample-removal: rc=0, "reference-feature
removal: PASS (23 checks, no fixture IDs)". 참조 기능을 지운 복사본에서
--with-create 기능을 만든 뒤 scaffold-* 게이트 9개가 모두 통과했다. 첫
실행은 tests/unit/create-feature.test.ts에 샘플 ID 문자열이 있어
fixture-id-residue로 실패했고, 그 테스트를 앞 커밋에서 고친 뒤 통과했다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제
- 프론트 create:feature는 GET /api/<base>-items 목록 하나를 만든다. 짝 백엔드
new-feature.sh는 POST /<plural>(201, NOT_IDEMPOTENT)과 GET /<plural>/{id}를
만든다. 경로 규칙도, operation 쌍도 맞지 않는다(03-07).
- 짝 백엔드 모양(Envelope)의 상세 GET·작성 POST·폼·결과 불명 화면 예제는
참조 기능뿐이고, 참조 기능은 problem details 모양이라 옮기면 짝 백엔드에서
쓰이지 않는 분기와 값(400·422 분류, retryBudget 0, Envelope 줄 없음)을
함께 옮긴다(09-06, 16 5.3절).
- 생성된 목록의 "총 N개"는 배열 길이다. 백엔드 meta.page.total을 쓰지
않는다(03-02 수정이 남긴 일).
고른 방법
- 경로: 백엔드 new-feature.sh와 같은 복수형 규칙(backendPathSegment)으로
API_PATH 상수 하나를 둔다. 백엔드 api-base-path는 API_BASE_URL에 붙인다.
- 목록: mapper가 { items, total }을 내고 total은 page?.total ?? 길이다. 빈
목록은 EmptySurface로 같은 빈 상태를 그린다.
- --with-create: 상세 GET, 작성 POST, 상세·작성 라우트와 페이지, 폼 스키마
(이름 100자 = 백엔드 NAME_MAX_LENGTH), 뮤테이션 정책(commandMutationIdentity),
작성 폼 테스트를 만든다. 작성은 백엔드 기본에 맞춰 NEVER(retryBudget 0, 키
없음)다. --keyed는 백엔드 create를 IdempotencyExecutor 뒤에 둔 경우의
KEYED 값(IDEMPOTENCY_REPLAY, retryBudget 1)을 쓴다.
- 작성 descriptor: acceptedStatuses [201], refusedBeforeWrite
["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED(백엔드
보안 필터·@RequiresPermission 프록시·rate-limit interceptor가 use case 전에
거절한다). mapProblem이 <BASE>_INVALID를 이름 칸 오류로 바꾼다.
- 생성 테스트: gateway 테스트가 세 operation의 백엔드 본문(201 Envelope,
404 <BASE>_NOT_FOUND, 400 <BASE>_INVALID → NOT_APPLIED, 응답 유실 →
MAYBE_APPLIED, NEVER는 키 없음·KEYED는 503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키
1회 재전송)을 손으로 적는다. 하네스 재시도 상한은 앱 기본값 2다(16-07 (3)).
작성 폼 테스트는 라우터를 거쳐 201 저장 뒤 상세 열기, 400 거절을 이름 칸에
보이고 저장 버튼이 켜진 채 다시 저장, 응답 유실 뒤 결과 불명(NEVER는 다시
보내기 없음, KEYED는 같은 Idempotency-Key로 다시 보내기)을 본다.
- 페이지 테스트의 앱 조립은 <base>-test-app.tsx 하나로 모은다.
- slice 템플릿은 scripts/create-feature-write-slice.ts에 둔다. 리뷰 5.3절
재검토 조건(템플릿 2,000줄)을 넘지 않게 하고, create-feature.ts의 수정을
필요한 자리로 좁힌다.
- X1: 생성한 context 선언을 임시 폴더에 써서 생성기 선언 읽기로 읽고, 그
모듈을 import해 앱 모듈 조립(라우트 루트 검사)이 기능 라우트를 받는지 보는
단위 테스트를 더한다.
버린 대안
- 작성을 기본 KEYED로: 백엔드 생성 create는 키를 읽지 않아, 같은 키 재전송이
새 항목을 만든다. 안전해 보이는 거짓 보장이다.
- 참조 기능을 Envelope로 옮기기(09-06 (2)): 참조 테스트와 MSW fixture를 다수
바꾸고 problem details 예제가 사라진다.
- 목록 값을 배열로 두고 total을 배열 속성으로 싣기: TanStack 구조 공유가 배열
속성을 버린다.
위험·한계
- 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 GET 페이지 목록을
더하기 전에는 생성 목록이 405를 받는다. descriptor 주석과 매뉴얼에 적었다.
- 생성 기능의 초기 JS: 기본 +647 B, --with-create +964 B(이 브랜치 기준선
203,702 B에서 잰 값, 기능당 1 KiB 안). 기준선의 남은 여유는 1,098 B라
--with-create 기능 하나를 넣으면 134 B가 남는다.
- 두 생성기를 실제로 띄워 붙여 보지는 않았다. 백엔드 템플릿의 응답 본문과
경로를 읽어 생성 테스트에 옮겼다.
검증
- RED: tests/unit/create-feature.test.ts 새 17건 실패 → GREEN 43건 통과.
- 기본·--with-create·--with-create --keyed·--context reference-context
--with-create 네 기능을 만든 상태에서: check:types(app·test·node), lint,
check:registries(additive), check:i18n, check:architecture,
check:design-system, check:diagnostics, verify:documentation 통과. 생성 기능
테스트 77건 통과. 빠른 계층 313파일 3,818건 중 참조 라우팅 테스트 1건만
실패(X1, 다음 커밋).
- 변이: refusedBeforeWrite 삭제 → gateway·폼 테스트 2건 실패. 상세 GET의
responseEnvelope 삭제 → 조립 거절로 테스트와 check:registries 실패. KEYED
retryBudget 0 → 503 재전송 테스트 실패. 정책의 descriptor 상수 오타 → tsc 실패.
- flock 아래 build, check:bundle: 기준 203,702, 기본 기능 204,349, --with-create
기능 204,666 / 204,800 B PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제
<base>-schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이
목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입·
레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과
unknownFieldPolicy는 07-03 수정(5bee9ab)이 검증기와 대조한다. 또 FE-REG-API의
problemSchema는 breaking 칸이지만 FE-REG-SCHEMA를 참조하지 않고, 참조 기능과
생성 뼈대에 실패 본문 스키마 행이 없다(07-01 (d)).
고른 방법
- schema-metadata-policy.test.ts에 boundary 대조를 더한다. 설치된 descriptor의
입력·응답·실패 검증기와 라우트 paramsSchema·searchSchema에서 스키마마다
쓰인 자리를 모으고, 그 조합에서 boundary를 정해 행과 비교한다. 쓰이는데
행이 없는 스키마도 실패한다. direction·unknownFieldPolicy 검사는 실패
검증기까지 넓힌다.
- boundary에 "api-problem"을 더한다(SchemaDefinition, governance
allowedValues). FE-REG-API problemSchema → FE-REG-SCHEMA.schemaId 참조를
governance에 더한다.
- 참조 기능 ReferenceProblem, 생성 뼈대 <Base>Problem, second-api fixture에
실패 본문 행을 더한다.
버린 대안
- 메타 행을 descriptor·라우트에서 투영(16-04 권고 (b)): 메타 파일이 거의
사라지지만 생성 뼈대·참조 기능·레지스트리 원본을 함께 바꾼다. 리뷰가
"빠르게 막으려면 (c) 먼저"라고 적은 대조 테스트를 골랐다.
- owner를 기능 ID에서 검사: 정한 규칙이 없다(참조 기능 owner는
"...-vertical-slice"). 그대로 둔다.
위험·한계
- governance 참조 추가는 FE-REG-API 계약 변경이라 기준선을 다시 찍었다
(REGISTRY_BASELINE_REASON에 1103/16-04). 다른 브랜치 변경(FE-REG-TELEMETRY
optionalAttributes)도 같은 스냅샷에 들어갔다. 오케스트레이터가 통합 뒤 다시
찍는다.
- 다운스트림 기능은 실패 본문 행이 없으면 check:registries가 실패한다.
CHANGELOG에 이행 안내가 필요하다.
- 대조 테스트는 설치된 기능만 본다. 기능을 더한 상태에서 test:unit을 돌릴 때
잡힌다.
검증
- RED: 새 boundary 테스트가 "ReferenceProblem: no FE-REG-SCHEMA row"로 실패.
행을 더한 뒤 통과.
- 변이: ReferenceResourcePayload boundary를 api-request로 바꾸면 "row
api-request, used as api-response"로 실패. 되돌림.
- check:registries 실패(FE-REG-API references 변경) → 기준선 갱신 뒤 PASS
compatibility=none.
- second-api-feature-registries, registry-governance, release-artifacts,
create-feature 테스트 통과. check:types, lint, verify:documentation 통과.
BREAKING CHANGE: FE-REG-API problemSchema가 FE-REG-SCHEMA.schemaId를 참조한다.
설치된 기능의 problemValidator 스키마마다 <base>-schema-metadata.ts에
boundary "api-problem", direction "RESPONSE" 행이 없으면 check:registries가
"FE-REG-API.<operationId>.problemSchema references unknown FE-REG-SCHEMA"로
실패한다. 행을 더하고 레지스트리 기준선을 다시 찍는다.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
문제
QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다.
bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능
작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로
적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②).
고른 방법
세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는
채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다.
매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title·
navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다.
버린 대안
- 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과
다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다.
- 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의
operation ID를 싣는다. 같은 값을 두 번 싣는다.
위험·한계
- 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면
FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와
test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은
파일이라 이번에는 문서로만 적었다.
검증
- RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner·
operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과.
- tests/features/reference-feature, tests/unit/create-feature.test.ts,
scope-fence 129건 통과. check:types(app·node·test), lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.
고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
자기 context platform-examples-context(루트 examples/*)에 산다.
reference-context의 examples/reference-resources/*와 플랫폼 라우트
/examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
(페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
"{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
(product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
"플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
제품이 지우게 둠(동기화 충돌 자리가 남음).
위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
(starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
재지 않는다.
검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
registries, test:all, coverage, test-evidence, ci, home-smoke, build,
route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
architecture 383 통과. check:types, lint, check:architecture,
check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
문제: 의존성 취약점 판정은 운영 승격의 외부 provider에만 있었다. 로컬
supply chain은 스캔하지 않고 provider: UNCONFIGURED를 썼다. 그래서
lockfile이 템플릿 자신의 정책(high 이상 차단, 예외 0건)을 어겨도 merge·
release 단계에서는 아무 신호가 없었고, provider가 없는 복사본은 끝까지
몰랐다. 갱신 자동화도 없었다(짝 백엔드에는 renovate.json이 있다).
고른 방법:
- scan:dependency-advisories(scripts/scan-dependency-advisories.ts)가
pnpm audit --json에 config/security/vulnerability-policy.json과
예외 파일을 적용한다. 판정은 승격이 쓰는 validateVulnerabilityReport를
그대로 쓴다. 결과는 PASS / POLICY_VIOLATION(승격에서 막힐 항목 목록) /
UNVERIFIED(레지스트리에 닿지 못함)이고, 운영·개발 의존성별 개수와 함께
gate 로그와 artifacts/security/dependency-advisories.json에 남는다.
- FE-GATE-027(release-admission, release 단계, 후보 빌드 직후)이 이 명령을
두 번째로 돈다. 명령은 항상 exit 0이다.
- renovate.json을 둔다(보안 업데이트만, 사람이 리뷰·merge).
- 남은 운영 의존성 위반 2건과 올리지 않은 이유, 다시 볼 날짜
(2026-12-04)를 ci-quality-gates.md에 적는다.
버린 대안: merge 차단 audit(코드가 안 바뀌어도 advisory DB 변경으로
merge가 깨진다), 로컬 스캐너를 provider로 내장(서명 주체 분리라는 원래
목적이 사라진다), 새 evidence 산출물·스키마 등록(계약 변경이 커진다.
gate 로그가 이미 release 단계 산출물이다).
위험·한계: 비차단이라 신호를 읽는 사람이 있어야 한다. 네트워크가 없는
runner에서는 UNVERIFIED로 남는다. Renovate runner는 붙어 있지 않아
renovate.json은 아직 동작하지 않는다. 남은 zod·react-router high 2건은
dependency-change-evidence의 reviewer(owner와 다른 사람)와 zod의 번들
예산 결정이 있어야 고칠 수 있다. 계약 기준선(contract-baseline.json)을
명령 100개·참조 104개로 다시 기록했다.
검증: dependency-advisories.test.ts 5건(정책 위반 판정, PASS, 유효한
예외, 보고서 없음 → UNVERIFIED, FE-GATE-027 배선과 exit 0). 상태 판정을
PASS로 고정하는 변이를 넣으면 실패한다. 실제 실행: POLICY_VIOLATION
(운영 high 2, 개발 moderate 2), exit 0. 죽은 프록시로 돌리면 UNVERIFIED,
exit 0. check:ci PASS, CI workflow bytes PASS, ci-workflow-generation·
product-ci-overlay·ungated-scripts·removal-fixture·supply-chain 489건 통과,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-03
문제
e1b4e28 뒤 test:feature-scaffold는 merge 단계 명령을 모두 돈다. 실제 실행
(snapshot b6bfc9b, CI env 없음)에서 검사 75개 중 FE-GATE-013의 두 개만
실패했다. build:release-candidate가 build의 commitSha를 source.revision으로
기록하는데, VITE_COMMIT_SHA가 없으면 commitSha가 "local"이라 schema(40·64자리
16진수)가 거부한다. verify:local-evidence는 그 결과를 읽어 따라 실패했다.
CI workflow는 VITE_COMMIT_SHA를 전체 env로 주므로 CI에서는 나지 않는다.
고른 방법
- VITE_COMMIT_SHA가 비었을 때만 드릴이 fixture의 봉인 commit(git rev-parse
HEAD)을 넣는다. CI 값은 그대로 둔다. test:system의 provider fixture도 같은
방법으로 commit을 준다.
- 버린 대안: build:release-candidate·verify:local-evidence를 제외 목록에
넣기. 생성 기능 파일이 후보의 추적 파일 목록과 공급망 증거에 들어가는지를
보지 못한다.
위험·한계
- 로컬 실행에서 빌드 산출물의 commitSha가 "local" 대신 fixture commit이 된다.
fixture 안에서만이다.
검증
- 수정 전 드릴 실행: create-feature, merge 명령 73개(음성 fixture 포함),
feature-removal 통과. 실패는 위 두 개뿐(866초, load 10~25).
- 수정 뒤 eslint·tsc 통과, feature-scaffold-drill 6건 통과. 드릴 재실행 결과는
이 커밋 메시지에 적지 않았다(공유 잠금).
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
문제
c4d5870 뒤 test:sample-removal이 문서를 복사하고 verify:documentation과 문서
테스트를 돌린다. 실제 드릴 실행(snapshot 0edc3fc)에서 두 가지로 실패했다.
- 드릴은 fixture에서만 tests/unit/ci-workflow-generation.test.ts와
tests/unit/removal-fixture.test.ts를 지운다(전체 저장소를 고정하는 테스트라).
docs/operations/adapter-remediation-ledger.md가 그 두 파일을 백틱 경로로 적어,
fixture의 문서 검사와 문서 테스트 7건이 실패했다. 샘플을 지운 실제 프로젝트는
그 테스트를 지우지 않으므로 이 실패는 fixture에만 있다.
- 잔여 검사가 tests/unit/documentation-readiness.test.ts의 정규식
REFERENCE_RESOURCE_[A-Z]+를 샘플 흔적으로 잡았다. 그 파일은 예전에는 fixture
에서 지워져 검사되지 않았다.
고른 방법
- 원장(기록 문서)의 그 세 곳을 백틱 없는 경로로 바꾼다. 드릴의 fixture 전용
삭제 목록 옆에 "현재 계약 문서는 이 파일들을 백틱 경로로 적지 않는다"를
적었다.
- 정규식을 [A-Z]+_RESOURCE_[A-Z]+로 쓴다. 라우트 ID를 지우는 용도는 같다.
- 버린 대안: 문서 검사에 fixture 전용 예외 경로를 넘기는 환경 변수. 운영
스크립트에 테스트용 입력이 생긴다. fixture 전용 삭제를 그만두기.
ci-workflow-generation 스냅샷은 줄어든 CI 계약과 맞지 않는다.
위험·한계
- 앞으로 현재 계약 문서가 그 두 테스트를 백틱으로 적으면 sample 드릴이 다시
문서 검사에서 실패한다. 실패 메시지가 파일과 경로를 적는다.
검증
- 수정 전 snapshot 0edc3fc의 test:sample-removal exit 1: documentation,
unit-integration, coverage, fixture-id-residue와 scaffold- 세 검사가 이 두
원인으로 실패. lint·check:i18n·check:design-system 등 나머지는 통과.
- 샘플·SAMPLE_EXTRAS·fixture 전용 테스트를 지운 복사본(sim-sample-docs.sh)에서
verify:documentation PASS_SCOPED. 저장소에서 documentation-readiness 19건
통과, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04