문제
- "CI and evidence"의 로컬 merge 게이트 반복문이 13개이고 FE-GATE-012가 없다.
f41e3d5가 번들 예산 게이트를 merge 단계로 옮겨 gates.json의 merge 단계는
14개다. "Updating a copied project"가 이 반복문을 가리키므로, 동기화한
제품은 번들 예산을 건너뛴다.
- 배포 슬롯을 채우는 곳이 config/ci/product-gates.json으로 바뀌었고(12-07),
FE-GATE-019는 HTTP/2·entry 압축이 없는 호스트도 실패시킨다(13-02).
README는 둘 다 말하지 않는다.
- CHANGELOG 미출시 절이 동기화 단위 순 요약이 됐는데(14-01 D5 (b)), 업데이트
절은 그 절을 어떻게 받는지 말하지 않는다.
고른 방법
문장 셋만 고친다. 반복문에 012를 넣고 개수를 14로, 제품 merge 검사
(PRODUCT-GATE-NNN)는 workflow의 product_merge_gate job이 돈다고 적었다.
업데이트 절에는 미출시 절을 범위째 받고 "먼저 할 일"부터 하라는 한 문장을
더했다. cherry-pick 절차는 그대로 둔다(한 수정을 받을 때는 여전히 맞다).
위험·한계
- README의 다른 절(0929/14-02의 범위 동기화 절차 전체)은 다시 쓰지 않았다.
검증
- verify:documentation PASS_SCOPED, documentation-readiness 테스트 통과.
- config/ci/gates.json merge 단계 gateIds 14개와 반복문을 대조했다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-01
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-07
문제: README 빌드 변수 표는 VITE_BUILD_ID 기본값을 local-build로만
적었다. staging·production 빌드는 이 값이 없으면 멈추는데
(scripts/generate-runtime-config.ts, src/contracts/env.ts 주석), 그 조건이
표에 없었다(0929/13-09, 세 라운드 남음).
고른 방법: 표의 기본값 칸에 local·development는 local-build, staging·
production은 없으면 빌드 실패라고 적는다.
위험·한계: 문서만 바꾼다.
검증: verify:documentation PASS_SCOPED(이 표를 읽는 검사 포함).
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 0929/13-09
문제
README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서
10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고,
verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서
참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거
드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint·
check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다.
고른 방법
- 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로
적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로
적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다.
- 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지
복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint,
verify:documentation, check:i18n, check:design-system을 돈다
(FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다.
- 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2
(c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울
수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다.
위험·한계
- 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지
않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다.
- 드릴 시간이 lint·문서 검사 두 번만큼 는다.
- 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).
검증
- 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad
sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤
PASS_SCOPED.
- 저장소에서 verify:documentation PASS_SCOPED,
documentation-readiness 14건 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
문제
src/features/<dir>/NOT_INSTALLED 표시는 "기능이 아닌 샘플 폴더"라는 뜻인데,
같은 단어가 런타임 상태 "선언됐지만 빌드·FEATURE_OVERRIDES가 뺀 기능"으로도
쓰였다(product-features.ts). 생성기는 feature-module.ts를 못 읽을 때만 표시를
찾았으므로, 샘플을 졸업시키며 표시를 지우지 않으면 표시가 "설치 안 됨"이라고
말하는 채로 조용히 설치됐다.
고른 방법
- 표시 이름을 NOT_A_FEATURE로 바꾼다(local-draft-feature 파일 이름 변경).
런타임 상태 NOT_INSTALLED는 그대로 둔다.
- 생성기가 표시와 feature-module.ts가 함께 있으면 둘 중 무엇을 지울지 적고
실패한다.
- 옛 이름 표시는 받지 않는다. 받으면 같은 다의가 남는다. 옛 표시만 있는
폴더는 "has no feature-module.ts; … mark the directory with NOT_A_FEATURE"로
실패해 새 이름을 알려 준다.
README 상태 표, starter-experience, 매뉴얼 errors·patterns 표를 맞췄다.
위험·한계
다운스트림이 자기 폴더에 NOT_INSTALLED 표시를 두었다면 생성 단계가 실패한다.
파일 이름만 바꾸면 된다.
검증
- RED: 생성기 테스트 3건(새 이름 허용, 옛 이름 거절, 동시 존재 거절)이
수정 전 실패.
- generate-product-feature-index.test.ts 17건 통과. generate:feature-index
통과. verify:documentation PASS_SCOPED. eslint, tsc(node·test) 통과.
BREAKING CHANGE: src/features/<dir>/NOT_INSTALLED 표시 파일은 더 이상
인식되지 않는다. 같은 자리에 NOT_A_FEATURE라는 이름으로 옮긴다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-09
문제: docs/manual/을 더했지만 입구 문서(README.md, docs/README.md)가
링크하지 않아 찾을 수 없고, verify:documentation도 매뉴얼을 검사하지
않았다.
방법: docs/README.md 1절의 세부 규칙 목록에 manual/과 manual/reference/를
링크한다. 1절에서 링크한 문서는 verify:documentation(FE-GATE-017)이 경로·
script·게이트 ID 실재를 검사한다. 루트 README의 Documentation 절에는
create:feature에서 시작하는 안내 한 줄을 둔다.
버린 대안: 입구 문서 표에 매뉴얼을 더하기 — 표는 계약을 정하는 문서
목록이고 매뉴얼은 그 계약을 쓰는 절차라 세부 목록에 둔다.
검증: verify-documentation-readiness PASS_SCOPED. documentReferences에
매뉴얼 8개 파일이 모두 들어가고 빠진 경로·script·게이트 ID 0.
문서 관련 단위 테스트 3파일 17건 통과.
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N"
처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4).
가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에
있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지
못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다:
docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로,
docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와
docs/superpowers/plans의 계획으로.
고른 방법:
- 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞
커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절
번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다.
- tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 +
"§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에
.dependency-cruiser.json을 넣는다.
- README "Files you can delete after copying"에서 INVENTORY.md 한 파일
대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과
ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다.
INVENTORY의 행 구조는 바꾸지 않는다.
- 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은
링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다.
버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도
상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기
목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시
다른 이력을 가리키면 남길 목록이 계속 커진다.
위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는
주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다.
src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼
이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미
docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의
이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다.
check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던
실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가
바뀐다.
검증:
- RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed).
- GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를
src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림.
- 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0).
- 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크
148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계
참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서
verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트
2 passed.
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- node scripts/check-adapter-inventory.ts: PASS
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts:
50 passed. tests/architecture: 39 passed.
- npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과.
.dependency-cruiser.json JSON 파싱 통과.
- 미실행: check:architecture(pnpm 필요).
문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고
소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조,
그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다.
diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다.
README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다.
design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과
check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가
어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를
설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를
모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를
고쳐야 한다(다운스트림 동기화 충돌 지점).
고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3.
- route ID 나열을 지운다. verify:documentation은 설치된 라우트마다
artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route
ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치
(ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로
starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을
가리키게 바꾼다.
- docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다.
문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는
작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo
기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서
읽는다), README "Files you can delete after copying"의 이력 중 지워진
것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한
FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를
적는 문서라 뺀다.
- compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에
3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트
경로를 현재 위치로 고치고 그 사실을 머리에 적는다.
- diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고
ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다.
- documentation-review.json에 documentReferences를 더한다. routeScope는
모양을 유지하고 기록 폴더 한 항목으로 쓴다.
버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를
고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어
주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 —
artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git
check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다.
위험·한계:
- 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운
링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든
경로, 심볼 이름이 맞는지는 보지 않는다.
- script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로
시작하는 "`접두:이름`"만 본다.
- 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재
계약 문서(README, compatibility.md, starter-experience.md,
manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운
복사본은 그대로 통과한다.
- 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도
본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다.
- CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다.
검증:
- RED: 새 테스트를 기준(61baf96) 스크립트에 돌리면 14개 중 9개 실패.
기록 파일을 지워도 통과했고, README·체크리스트에서 route ID를 지우면
"failed: route scope"로 실패했고, 경로·script·게이트 ID 변이는 모두
통과했다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 14개 통과. 고치기 전 문서에
돌리면 ledger의 옮겨진 테스트 경로 두 개를 잡았다.
- 변이: src/contracts/routes.ts에 라우트를 하나 더하면 README·체크리스트를
고치지 않아도 "artifacts/tests/a11y-manual/ has no record for route IDs:
EXAMPLES_DRIFT"로만 실패하고, 기록 파일을 더하면 통과했다(되돌림).
- 회귀: tests/unit 전체(fixture-node-modules 제외) 173파일 2505개 통과.
deletable-history-documents 통과. tsc(node, test) 통과. 바꾼 ts 파일
eslint 통과. check-ci-contract, generate-artifact-schemas --check,
generate-ci-workflow --check, check-adapter-inventory 통과.
check-remediation-ledger는 기준 커밋과 같은 4건으로 실패(게이트 밖,
이번 변경과 무관).
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
문제
production_gate는 promotion 직후 같은 run에서 시작하고 그 사이에 배포 job이
없다. CI 계약이 job 9개·그래프·env를 정확히 고정해 배포 job을 넣을 자리도
없다. live probe는 헤더만 보고 배포된 release가 승격 후보인지 확인하지
않는다. FE-GATE-019의 명령은 [build, verify-hosting-headers]라서 local
프로필로 다시 빌드한 dist를 검사한다. 그래서 FE-GATE-019 PASS는 "지금 떠
있는 release(대개 이전 것)의 헤더가 맞다"는 거짓 PASS다.
고른 방법 (리뷰 대안 (c), (1)~(3))
(1) live probe가 배포된 release-manifest.json의 buildId·releaseId를 후보와
비교한다. 다르거나 읽을 수 없으면 FAIL(releaseManifest build-id·
release-id). 후보는 검사하는 dist의 release-manifest.json이다.
(2) FE-GATE-019에서 build를 뺀다. verify-hosting-headers가
`--release-root .release/promoted-release`를 받아 후보 dist를 본다.
계약의 13-03 규칙(drill만 --release-root 필수)을 production_gate의 모든
게이트 명령으로 넓혔다. 플래그 없이 돌리면 local dist를 본다.
(3) promotion과 production_gate 사이에 `deployment` job(kind deployment)을
선언한다. 기본은 빈 슬롯이다: deploy 단계 하나가 deployed=false를 job
output으로 낸다. production_gate는 RELEASE_DEPLOYED로 받고, 비어 있으면
FE-GATE-019가 호스트를 probe하지 않고 UNVERIFIED(exit 3)로 끝난다.
프로젝트는 gates.json의 deployment job을 채운다. 계약이 허용하는 것:
checkout·setup-node·frozen-install·download·extract와 마지막 deploy 하나
(`script`는 package 스크립트, 존재·스크립트 그래프 검사를 gate 명령과
같이 받는다). env는 immutable_build의 CANDIDATE_ARCHIVE_SHA256과
vars.*·secrets.*만. 게이트를 소유하지 않아 채워도 계약 기준선이 안
바뀐다.
- ci-contract 보고서 jobCount 9→10, 계약 기준선 commandReferences
103→102(update-ci-contract-baseline, owner frontend-platform).
- verify-hosting-headers가 live가 아닌 모드에서 baseUrl을 null로 적는다.
스키마가 live에만 baseUrl을 허용해서, 비어 있는 슬롯과 기존 invalid-live
(예: http:// URL)는 산출물 쓰기에서 ZodError로 죽었다. 이제 기록을 남기고
각각 UNVERIFIED·FAIL로 끝난다.
버린 대안
- (b) (1)(2)만: 거짓 PASS는 사라지지만 배포 자리가 없어 운영 단계가 항상
FAIL이 된다.
- (d) production_gate를 별도 workflow로 분리: Gitea에서 run 사이 artifact
전달이 검증되지 않았다.
- 슬롯이 비었는지를 HOSTING_BASE_URL 유무로 판단: 변수만 있고 배포가 없으면
이전 release를 probe해 FAIL이 된다. 슬롯이 직접 보고하게 했다.
위험·한계
- Gitea runner가 꺼져 있어 workflow를 실제로 돌리지 않았다. job outputs와
`$GITHUB_OUTPUT`는 immutable_build가 이미 쓰는 방식과 같다.
- 실제 HTTPS 호스트에 이전 release를 띄워 probe하지 않았다. 불일치 판정은
fetcher를 주입한 단위 테스트로만 확인했다.
- 채운 슬롯의 secrets는 그 job의 모든 단계(checkout, download action 포함)
env에 보인다. 프로젝트가 고르는 값이다.
- FE-GATE-019를 수동으로 돌리는 운영자(provider 없는 최소 구성)는 후보
archive를 .release/promoted-release에 풀어야 한다. drill과 같은 전제다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
7 failed / 19 passed(후보 인자 없음, verify가 dist ENOENT로 산출물 없음).
tests/unit/ci-workflow-generation.test.ts 8 failed / 415 passed
("expected [ 'build', 'verify:hosting-headers' ] to deeply equal ...",
"expected -1 to be 6", deployment job 없음)
- GREEN: hosting-probe 26 passed, ci-workflow-generation 423 passed
(스냅샷 1개 갱신)
- check:ci 하위 명령 직접 실행: generate-artifact-schemas --check PASS,
check-ci-contract.ts PASS, generate-ci-workflow --check PASS
- 슬롯을 채운 실험(체크아웃→다운로드→extract→deploy:release, vars·secrets
env, package 스크립트 추가) 뒤 같은 세 명령 PASS. package 스크립트를 빼면
"CI gate contract missing package scripts: deploy:release"로 실패. 실험
뒤 원복
- 관련 테스트 16파일 596 passed(ci-workflow-generation, hosting-probe,
service-worker-build-output, deployment-admission, ungated-*,
supply-chain, removal-fixture, task3-selective-integration,
documentation-readiness, tests/release, tests/platform/release)
- tsc(node, test, app) 0, eslint 바뀐 파일 0,
verify-documentation-readiness PASS_SCOPED
- 미실행: tests/system/ci-runner(pnpm 실행), check:architecture(pnpm)
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-01
문제
staging·production 프로필은 `https://api.example.com/`,
`https://telemetry.example.com/v1/events`를 싣고 텔레메트리를 켠다.
공개 대상 승인(FE-GATE-027)은 https와 비공개 호스트만 보므로 프로필을
고치지 않은 production 빌드가 `production ADMITTED`로 통과한다. 모든 API
호출이 실패하고 이벤트는 프로젝트가 소유하지 않은 도메인으로 간다.
CI 계약은 immutable_build의 env를 APP_PROFILE·RELEASE_TARGET로 고정해
RUNTIME_*를 넘길 수 없는데, README 변수 표는 이를 적지 않고 운영 예시는
`api.example.com`을 그대로 쓴다.
고른 방법
- publicEndpointViolations에 예약 이름 거절을 더한다. RFC 2606·6761의
`example.com`·`example.net`·`example.org`와 그 하위, `.example`,
`.invalid`, `.test`. 비공개 호스트와 겹치면 비공개 사유 하나만 낸다.
- README 운영 예시의 URL을 `<your-api-origin>/` 같은 빈칸으로 바꾼다.
- README 변수 표와 본문에 CI에서 endpoint를 바꾸는 방법은 프로필 파일을
커밋하는 것 하나라고 적는다.
- 테스트 fixture의 공개 endpoint를 예약되지 않은 이름으로 바꾸고, 프로필을
고치지 않은 빌드는 두 위반, endpoint를 준 빌드는 승인되는 것을 고정한다.
버린 대안
- 프로필 기본값을 비워 스키마가 빌드를 막게 하기: 더 확실하지만 프로필이
예시로 읽히지 않고 네 프로필을 같이 바꿔야 한다. 리뷰 대안 비교에서 승인
규칙 한 곳이 더 작다고 봤다.
- 리뷰 13-02 (3)의 괄호("13-01 배포 슬롯에 RUNTIME_* 허용 목록")는 하지
않았다. RUNTIME_*는 빌드 때 쓰이는 값이고, 슬롯은 승격 뒤 배포 job이라
거기서 넘겨도 이미 만든 후보에 닿지 않는다.
위험·한계
- 템플릿을 그대로 쓰는 프로젝트(이 repo 포함)가 APP_PROFILE=production으로
immutable_build를 돌리면 FE-GATE-027이 새로 실패한다(의도).
- `*.test` 같은 이름을 실제 운영 endpoint로 쓰는 프로젝트는 없다고 본다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts
2 failed / 22 passed. "refuses names reserved for examples and tests"
(`expected [] to deeply equal [...]`), "refuses a public build from the
unedited profile on both endpoints"(`staging: expected [] to deeply equal
[ 'API_BASE_URL', 'TELEMETRY_ENDPOINT' ]`)
- GREEN: 같은 파일 24 passed. feature-override-diagnostics,
documentation-readiness 포함 29 passed
- 실험 E-A 재실행: APP_PROFILE=production VITE_BUILD_ID=rel-prod-a
RELEASE_ID=rel-a 빌드 뒤 RELEASE_TARGET=production 승인 rc=1,
API_BASE_URL·TELEMETRY_ENDPOINT 두 위반으로 거절
- tsc(app, test) 0, eslint 바뀐 파일 0, verify-documentation-readiness
PASS_SCOPED
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-02
문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(7a70cea)의 문서에 돌리면 FAIL_UNVERIFIED
(failed: source structure). layers.md는 규칙 25개가 없고, 네 문서
모두 9개 폴더를 설명하지 않는다고 나온다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 6개 통과. 새 변이 3개:
규칙 이름 하나를 바꾸면, README에 `src/domain`을 넣으면, overview의
platform 설명을 바꾸면 각각 실패하고 원인 문서와 이름을 적는다.
- 회귀: tests/unit 전체(fixture-node-modules 제외, pnpm 설치를 띄운다)
173파일 2494개 통과. ci-artifact-contract의 "semantically invalid"
16개 통과. tsc(node, test) 통과, 바꾼 ts 파일 eslint 통과.
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-03
PRODUCT.md가 "예제 기능과 라우트는 지울 수 있고, 예제 화면에만 있는
디자인은 남지 않는다"고 적었다. 실제 제거 드릴(test:sample-removal)은
참조 기능만 지운다. 예제 라우트 4개와 홈은 기본 구성이라 남는다. 이
주장을 믿고 예제 화면에 디자인을 넣으면 제품 빌드에 그대로 남는다.
PRODUCT.md를 드릴 범위대로 고쳤다. 접근성 수동 검토의 근거를 지워도
되는 SPEC.md에서 docs/accessibility/manual-checklist.md로 바꿨다.
README의 "복사 뒤 지워도 되는 파일" 표에 PRODUCT.md를 CLAUDE.md처럼
"제품 것으로 바꾼다"로 넣었다. 예제 화면을 지울 수 있게 만드는 일은
별도 선택이라 하지 않았다(0929/14-03).
위험: 문서만 바뀐다.
검증: deletable-history-documents 테스트 통과, verify:documentation
PASS_SCOPED.
The growth test read docs/reviews/, which the removal fixtures do not copy and
README lets a project delete, so three removal checks failed with ENOENT. The
rationale now lives in config/scale/feature-shape-ceilings.json and a guard
test keeps code from reading the deletable history documents.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The gate count and the reference-feature LOC table were hand-typed and
drifted from the code, so they are removed; the LOC table now names the
files and the command that measures them. .env.example pointed to
layers.md for runtime profiles, which never described them; it now points
to the README section that does. ci-quality-gates.md lists the three
things DOCUMENTATION_READY checks, so the gate name is not read as a
general documentation-accuracy guarantee. The route list (③) and the
README config location (④) were already fixed by 14-03 and 13-15.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Current contracts, target designs and work history shared one tree with no
index. docs/README.md sorts them, names the files gates read, and marks the
history folders; README lists what a copy can delete. SPEC.md and tasks/ stay
in place because this round still uses them (D-16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
What is default, optional, experimental or unsupported (SSR among them) was
spread over the recipe catalog and the capability ledger, each with its own
status words. README now has one tier table, a map from every status word to
a tier, and the browser versions the build targets and the tests run on.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A copy had no way to learn that a fix shipped or which files to take. The
CHANGELOG marks security and contract changes with their paths; README says
where to record the origin commit, how to cherry-pick or diff a fix and who
classifies a template defect. The v0.2.0 tag is added after integration.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
public/config.json is the copy dev serves and nothing compared it with
config/runtime/local.json. A unit test now requires it to equal what a local
build writes, and sample removal drops the feature override from it too.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The unit test read README.md, which removal fixtures do not copy, so
test:sample-removal failed. verify:documentation now requires README to name
every build and deploy variable the generator and admission read.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README said runtime settings live in public/config.json, which the build
replaces with config/runtime/<profile>.json, and named none of APP_PROFILE,
RUNTIME_*, VITE_BUILD_ID, RELEASE_ID or RELEASE_TARGET. A unit test now
requires README to name every variable the generator and admission read.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
FE-GATE-019 ran before the release existed and passed by comparing the declared
headers with a copy of themselves. The fixture result is now UNVERIFIED, the
gate runs in the production stage after deployment, and the live probe
requests the entry script the served index.html names (D-14).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Drills held constant true verdicts and read public/ placeholders, so they
passed with no build or with JS assets deleted. They now check the local dist,
mark boot, live traffic and provider steps UNVERIFIED (exit 3), and FE-GATE-016
is retired because it repeated FE-GATE-025's FE-RB-005 drill.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The signed review is per release candidate, so the merge gate could never pass.
FE-GATE-009 now checks only the record format; the checked-in records are
source-controlled evidence, not command output.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The push trigger listed only develop, while main is the integration
branch. README now says the host may not run Actions and gives the local
loop over the 13 merge gates. Enabling Actions and required checks on the
host stays with the repository owner (U-1).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Three boundaries the layer contract declares had no executable rule behind
them, so the code drifted across all three while every gate stayed green.
`src/contracts` reached back up into `src/application` for the shared `Result`
carrier and the compatibility predicate. Neither package owned the shared
vocabulary and the dependency pointed both ways. Both now live in contracts —
the lower package — and application re-exports them, so no caller moves.
A concrete adapter was not supposed to depend on another concrete adapter, but
only adapter-to-presentation was enforced, and `diagnostics` imported a guard
out of `telemetry`. The guard belongs to neither, so it moved to the adapter
kernel. Stating the rule needed the checker to resolve `$1` in a `to` pattern
against the importing module's own directory; the alternative is one rule per
adapter group, which silently stops covering a group the moment one is added.
Product assembly leaks out of bootstrap: generic presentation reads the
installed-feature registries. That is a real refactor, so the rule freezes the
exact set of modules doing it today rather than pretending it is fixed — a new
edge fails. The two remaining open edges are named in the config, not silent.
Each rule was verified by introducing the violation it forbids and confirming
the gate rejects it.
The documentation drifted the same way. README and the manual accessibility
checklist both said six routes while ten were registered, which left the
platform overview and three reference-resource screens outside the declared
manual review scope without anyone deciding they should be. The scope is now
derived from the route registry by `verify:documentation`, so the sentence
cannot outlive the registry again. The review ledger also named a canonical
path that does not exist in this tree; it is upstream provenance, and it now
says so instead of looking like a broken repository reference.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>