Commit Graph
182 Commits
Author SHA1 Message Date
DongHyeonka f21ea48911 ci(gates): 의존성 캐시를 checkout과 같은 파일시스템의 폴더에 둔다
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m56s
frontend-quality-gates / merge / tests (pull_request) Successful in 15m58s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m15s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / self-tests and removal drills (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
문제: #41의 merge job 캐시는 hit해도 설치가 빨라지지 않았다. PR run
230에서 세 job 모두 복원했지만(222MB, 4.8초) pnpm 설치는 16.9·26.4·22.4초로
캐시 없는 run(13.8~22.8초)과 같았다. `reused 404, downloaded 0` 뒤 node_modules에
넣는 데만 15초 넘게 걸렸다. desktop 재현: 같은 파일시스템 2.1초, tar 왕복 뒤
7.6초, store가 다른 파일시스템이면 58.8초(하드링크 대신 복사). store가 job의
`/tmp`에 있어 checkout과 다른 파일시스템일 가능성이 크다.

고친 것(권하는 안으로 정함, 총괄): merge job의 첫 캐시 단계가
`scripts/ci/dependency-cache-root.sh "$RUNNER_TEMP" "$(dirname "$GITHUB_WORKSPACE")"`
를 돈다. 후보 중 checkout과 `stat -c %d`가 같고 checkout 밖인 첫 폴더를 고르고,
없으면 첫 후보를 쓴다. 고른 폴더, 견준 장치 번호, job 시작 때의 부하를 한
줄로 로그에 남기고, `COREPACK_HOME`·`PNPM_CONFIG_STORE_DIR`·
`PNPM_CONFIG_CACHE_DIR`를 `$GITHUB_ENV`로 넘긴다(job env 고정값을 뺌). 캐시
경로는 그 단계 출력을 쓴다. checkout 안은 후보가 아니다(`git status`, repo
배치 검사, 산출물에 잡히지 않게).

버린 대안: checkout 안 `.tmp` 아래(배치 검사·산출물에 걸림), workspace 부모를
고정 경로로(파일시스템이 같은지 runner마다 다를 수 있다).

위험·한계: 고른 폴더가 run마다 다르면 캐시 항목의 경로가 달라 hit하지 않는다
(같은 runner에서는 같다). 같은 파일시스템이 없으면 지금과 같다. runner에서의
효과는 main 저장 → 다음 PR 복원으로 잰다.

검증(desktop): 새 시험 `tests/unit/dependency-cache-root.test.ts`(가짜
`stat`으로 같은 파일시스템 고르기·checkout 안 제외·대체 경로) 통과, 최대
47ms. 생성 시험은 바꾸기 전 생성기에서 실패(RED), 고친 뒤
ci-workflow-generation·test-timeout-declarations·repository-layout 등 460개
통과. check:ci·check:types·eslint·verify:documentation rc=0.
2026-11-13 14:05:46 +09:00
DongHyeonka 000b5a35be ci(gates): release job이 FE-GATE-028에 릴리스 태그를 넘긴다
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m9s
frontend-quality-gates / merge / tests (pull_request) Successful in 18m3s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 7m39s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / main / self-tests and removal drills (pull_request) Skipped
문제: 서명된 수동 접근성 기록의 「Release ID」를 무엇과 대조할지 정해지지
않았다(round9 1112/05-01, R9-D7). 처음 정한 `--release-root` 안은 성립하지
않는다. FE-GATE-028은 후보를 만드는 `immutable_build`보다 앞의 `release_gate`
에서 돌고, 후보의 `releaseId`는 run마다 다른 env `RELEASE_ID`에서 온다.
r9-fe가 (가) 릴리스 태그로 정했다.

고친 것: `release_gate` job env에 `RELEASE_TAG`(tag run이면 `gitea.ref_name`,
아니면 빈 값)를 두고, FE-GATE-028이 그것을 `requiresEnvironment`로 요구한다.
`run-ci-gate.ts`는 빈 필수 변수를 거절하므로, 브랜치에서 수동으로 돌린
release 단계에서는 028이 `missing required environment: RELEASE_TAG`로
실패한다(fail-closed, 의도한 동작). 계약의 job env 고정과
ci-quality-gates.md를 같이 고친다.

버린 대안: 명령 인자로 후보 root 넘기기(028 시점에 후보가 없음),
releaseId를 tag 기준 결정값으로 바꾸기(빌드 식별 계약 변경), 028을 이전
run의 후보를 받는 흐름으로 옮기기(job 그래프 변경).

위험·한계: 기록의 「Release ID」를 이 태그와 대조하는 일은 검사
(`scripts/verify-a11y-manual.ts`)와 기록 양식 쪽(그룹 A5)이 한다. 이 커밋만
으로는 값을 받기만 한다. 다운스트림이 release 단계를 브랜치에서 수동으로
돌리던 흐름은 028에서 멈춘다.

검증(desktop): 새 시험이 바꾸기 전 gates.json에서 실패(RED), 고친 뒤
ci-workflow-generation 439개 통과. check:ci·check:types·eslint·
verify:documentation rc=0. `ci:gate FE-GATE-028`: `RELEASE_TAG`가 비면
`missing required environment: RELEASE_TAG`로 실패, `v0.0.0`이면 그 줄 없이
검사까지 간다(서명 없는 템플릿 기록이라 지금처럼 incomplete로 실패).

Refs: 1112/05-01
2026-11-13 11:02:51 +09:00
DongHyeonka 7ed0af3d29 ci(gates): merge job 셋이 의존성 캐시에서 설치를 시작하고 main만 저장한다
문제: merge job 셋은 runner의 새 컨테이너에서 매번 Node(GitHub
다운로드), corepack의 pnpm, 패키지 404개를 내려받고, pnpm 11은 lockfile
542개 항목의 공급망 정책을 레지스트리에 물어 검증한다. run 169에서 job마다
setup-node 11~18초, 설치 12~29초였고 설치 시간의 대부분은 정책 검증의
메타데이터 요청이었다(10.1~27.9초). FE-GATE-013의 시스템 컨테이너는 같은
설치를 한 번 더 한다. merge 25분 목표에 0.8분 모자랐다.

고친 것(권하는 안으로 정함 2026-11-13, 총괄):
- job 단계 `dependency-cache`를 더한다. setup-node 앞에서 Node toolcache와
  `/tmp/fe-dependency-cache`(corepack, pnpm store, pnpm 메타데이터 캐시)를
  `.nvmrc`·`pnpm-lock.yaml` 해시 키로 복원한다. main run은 actions/cache로
  복원·저장하고, 그 밖의 ref는 actions/cache/restore로 복원만 한다. pin은
  짝 백엔드의 JDK·Gradle·Trivy 캐시와 같다(v4.3.0).
- 생성기가 그 job에 `COREPACK_HOME`·`PNPM_CONFIG_STORE_DIR`·
  `PNPM_CONFIG_CACHE_DIR`를 주어 job의 모든 pnpm 호출이 같은 곳을 본다.
  frozen install 단계는 그대로이고 캐시와 관계없이 돈다.
- PR run은 main이 저장한 항목을 같은 키로 읽기만 한다. 저장할 수 있는
  actions/cache 단계는 `refs/heads/main` 조건 아래에만 있고, 그 밖의 ref가
  타는 actions/cache/restore에는 저장하는 post 단계가 없다(시험으로 고정).
- 계약: merge job 셋만 이 단계를 가진다(release·promotion·provider·main
  job은 거절, 단계 순서 고정에 반영). 그 env를 job이 따로 묶으면 거절한다.
  키 입력은 `config/repository-layout.json`의 새 집합
  `dependency-cache-key`(`.nvmrc`, `pnpm-lock.yaml`)에서 고른다.
- `scripts/run-in-system-container.sh`가 그 env가 있으면 store와 메타데이터
  캐시를 같은 경로로 컨테이너에 넘긴다. 없으면(desktop) 지금과 같다.
- 결정 색인, ci-quality-gates.md, O1 출처 문구를 총괄이 정한 말로 맞춘다.

버린 대안:
- CI 이미지에 의존성 굽기: 레지스트리 쓰기 토큰이 든다.
- 브랜치 run도 저장하기: 캐시 항목은 다음 run이 믿는 입력이다. pnpm은
  같은 lockfile의 공급망 검증 기록이 캐시에 있으면 다시 검증하지 않으므로,
  브랜치가 쓴 항목이 main의 검증을 건너뛰게 할 수 있다.
- `cache-hit`일 때 설치를 건너뛰기: 결과가 캐시 상태에 달린다.
- apt 글꼴 캐시: 캐시가 없을 때 새 패키지 버전이 깔려 시각 결과가 달라질
  수 있다.

위험·한계:
- PR run은 main이 같은 키(또는 restore-keys로 앞 항목)를 저장한 뒤에야
  hit한다. 이 PR 자신의 run은 비어서 시작한다.
- runner 캐시 저장소(5GB)는 짝 백엔드와 같이 쓴다. 항목 하나는 Node·store·
  메타데이터로 압축 전 약 0.7GB다. lockfile이 바뀔 때마다 새 항목이 생긴다.
- Node toolcache 경로(`/opt/hostedtoolcache`)가 job 이미지와 다르면 그
  부분만 효과가 없고 setup-node가 내려받는다.

검증(desktop):
- 설치 실험(같은 lockfile, 새 폴더): 빈 캐시 13.9·17.2초, 캐시 있음 1.6초,
  store 파일 40개·메타데이터 40개를 망가뜨린 캐시 3.6초(27개만 다시 받음).
  다섯 번 모두 node_modules 트리 해시가 같다. pnpm 11은 대문자
  `PNPM_CONFIG_STORE_DIR`·`PNPM_CONFIG_CACHE_DIR`를 읽는다.
- FE-GATE-013 흐름을 캐시 env로 재현: 빈 캐시 설치 13.7초, 캐시 설치
  2.6초, 시스템 컨테이너 안 설치 1.5초(`Recreating node_modules` 없음, 지금은
  31.3초). 그 실행의 FE-GATE-013은 provider 묶음 시험 하나가 손 timeout
  30초에 걸려 실패했다(캐시와 무관, PR #39가 고치는 문제).
- RED: 계약·생성기를 둔 채 gates.json에서 캐시 단계를 빼면 새 시험 6개
  실패. 키 입력을 코드에 직접 적은 첫 판은 repository-layout R2 시험이
  잡았다. GREEN: repository-layout·ci-workflow-generation 456개 통과,
  check:ci·check:types·eslint rc=0, verify:documentation rc=0, 노트북
  `scripts/verify.sh docs` OK.
2026-11-13 08:26:13 +09:00
DongHyeonka df37a082e0 merge: PR #36을 합친 검사 브랜치에 넣는다 2026-11-13 07:16:02 +09:00
DongHyeonka 9ebd0856a1 fix(ci): provider job에 sandbox runner 요구를 적고 시작 때 namespace를 점검한다
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (pull_request) Canceled after 0s
frontend-quality-gates / merge / static checks (pull_request) Canceled after 0s
frontend-quality-gates / merge / tests (pull_request) Canceled after 0s
frontend-quality-gates / merge / browser tests (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Canceled after 0s
frontend-quality-gates / external-vulnerability-provider (pull_request) Canceled after 0s
frontend-quality-gates / external-provenance-provider (pull_request) Canceled after 0s
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Canceled after 0s
frontend-quality-gates / deploy-promoted-release (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Canceled after 0s
문제: release의 provider job 둘(vulnerability·provenance)은 FE-GATE-013과
같은 provider sandbox(systemd-run scope, bwrap --unshare-pid/ipc/uts/net)를
돈다. 그런데 생성 workflow의 runner 요구 주석은 게이트의
hostRequirements에서 나와 merge_test에만 붙고, provider job에는 없다.
provider 감독 스크립트의 시작 점검도 실행 파일이 있는지만 봐서, 비특권
user namespace를 막는 runner에서는 나중에 bwrap 원문 오류로 끝난다.

고른 방법:
- 계약 job에 선택 칸 `hostRequirements`를 두고 provider job 둘에
  FE-GATE-013과 같은 요구를 적는다. 계약이 provider job의 요구가
  FE-GATE-013과 같은지 보고(갈라지면 거절), provider 밖 job은 이 칸을 못
  쓴다. 생성기가 그 job의 runs-on 옆에 주석을 쓴다.
- `check-system-test-prerequisites.ts`에서 namespace 점검만 함수로 내보내고
  (`findProviderSandboxNamespaceFailure`), `run-and-validate-provider.ts`가
  provider를 띄우기 전에 부른다. 실패하면 test:system 사전 점검과 같은
  문구(제한 이름, bwrap stderr, host 설정, 고치는 법)로 멈춘다.
- 버린 대안: 생성기가 hostEnvironment 게이트의 요구를 provider job에
  저절로 붙이기. 연결이 계약에 보이지 않는다.

위험·한계: provider job은 release 단계라 PR run에서 돌지 않는다. 새
점검은 desktop FE-GATE-013의 provider 시스템 시험(감독 스크립트를 실제로
띄움)으로 본다. 「provider 없이 배포할 때」 문서 절은 소유자 결정이라
이 커밋에 없다.

검증(desktop): 구현을 main으로 되돌리고 새 시험만 둔 상태에서 4개 실패
(RED), 고친 뒤 system-test-prerequisites·ci-workflow-generation 445개 통과,
generate:ci-workflow·스냅샷 갱신, check:ci·check:types·eslint rc=0,
verify:documentation PASS_SCOPED. desktop `scripts/verify.sh gate FE-GATE-013`
rc=0 226초(시스템 컨테이너, system 시험 115개 통과 — provider 감독
스크립트를 실제로 띄워 새 점검을 거친다). 로그 /tmp/claude-gates/w2fe2-prov1/,
w2fe2-prov013/.

Refs: 1101/13-03
2026-11-13 05:02:16 +09:00
DongHyeonka 50d623c40e Merge remote-tracking branch 'origin/main' into fix/r9-living-docs-sync
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Canceled after 0s
frontend-quality-gates / merge / static checks (pull_request) Canceled after 0s
frontend-quality-gates / merge / tests (pull_request) Canceled after 0s
frontend-quality-gates / merge / browser tests (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Canceled after 0s
frontend-quality-gates / external-vulnerability-provider (pull_request) Canceled after 0s
frontend-quality-gates / external-provenance-provider (pull_request) Canceled after 0s
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Canceled after 0s
frontend-quality-gates / deploy-promoted-release (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (pull_request) Canceled after 0s
# Conflicts:
#	AGENTS.md
#	docs/work/reference/decisions.md
2026-11-13 04:30:07 +09:00
DongHyeonka 8de1403b92 ci(gates): 선택 runtime 제거 드릴 셋을 main 단계의 FE-GATE-030으로 옮긴다
문제: runner PR 1회(merge job 셋, capacity 1이라 차례로)가 28.5분이다
(run 151). tests job의 FE-GATE-020이 13분 13초로 가장 크고, 그 안의
선택 runtime 제거 드릴 셋(optional recipe, browser file/storage,
realtime)이 약 7분이다. worker를 늘리지 않는 대책을 다 넣어도 25분
목표에 닿지 않는다.

고른 방법(소유자 결정 p, 2026-11-12): 그 드릴 셋을 새 게이트
FE-GATE-030 `optional-removability`로 떼어 main 단계(`main_gate`,
FE-GATE-029 다음)에서 돌린다. 샘플 제거와 scaffold 드릴은 merge의
FE-GATE-020에 남는다. 짝 백엔드가 무거운 lane을 nightly로 옮긴 것과
같은 모양이다.
- 계약: 정규 게이트 ID를 001..030으로, MAIN_READY를 029·030으로,
  main_gate job의 게이트를 029·030으로 바꾼다. 계약 보고서의 gateCount는
  29(016은 은퇴).
- scaffold 드릴의 제외 목록에서 셋을 뺀다. 이제 merge 명령이 아니라서,
  계약 검사가 「merge 밖 명령을 제외하면 숨긴다」고 거절했다.
- main job 이름을 `main / self-tests and removal drills`로 바꾼다.
- 시험: 020은 merge·merge_test에서 sample·scaffold만, 030은
  main·main_gate에서 셋을 돈다고 단언한다. 승격 공식 시험에 030을 더한다.
- 문서: 결정 색인(decisions.md 2.2), 구조·시험·리뷰 기준·CI 문서,
  fe-structure 스킬의 드릴 명령.

위험·한계: 선택 runtime을 바꾼 PR의 제거 회귀는 병합 뒤 main run에서
본다. main이 빨강이면 다음 PR이 고친다. 그런 PR은
`scripts/verify.sh gate FE-GATE-030`을 직접 돌려야 한다(structure.md
12절에 적음). 파생 프로젝트가 main job 이름을 필수 검사로 걸었으면
이름이 바뀐다.

검증(desktop): generate:ci-workflow, 생성 시험 스냅샷 갱신,
ci-workflow-generation·promotion-readiness·feature-scaffold-drill·
removal-drill-test-paths·example-feature-rules 등 483개 통과,
check:ci(29 gates) rc=0, check:ci:gating rc=0, verify:documentation
PASS_SCOPED, check:types·eslint rc=0. 로그 /tmp/claude-gates/w2fe2-o1b~g/.
2026-11-13 02:03:01 +09:00
DongHyeonka 06ffafa25e docs: 살아 있는 문서의 낡은 문장을 지금 코드와 정본에 맞춘다
2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는
문서가 지금 코드와 다른 말을 한다.

- 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로
  가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/,
  패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06).
- 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다.
  optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리
  블록이 옮긴 곳을 가리킨다(1112/09-02).
- 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로
  가리킨다(1112/08-17).
- 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007),
  drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는
  꼬리 문장(1112/02-08).
- 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop
  verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다
  (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은
  verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07).
- create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자
  (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15).
- secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장
  (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫
  (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조
  (1106/14-02).

고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다.
버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다).

위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제
docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드
예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture
규칙과 부딪쳐 결정 대기로 남긴다.

검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과
FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다.

Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04,
 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15,
 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02,
 0929/14-03, 0929/13-10, 1106/14-02
2026-11-12 23:36:14 +09:00
DongHyeonka 2f5eb2b4a5 ci(workflow): 같은 PR·브랜치의 새 push가 앞 run을 취소한다
문제: runner가 하나(capacity 1)인데 PR에 push할 때마다 run이 하나씩
쌓인다. 낡은 head의 run이 runner를 25분씩 잡아 새 head와 백엔드 run이
뒤로 밀린다.

고른 방법: workflow에 concurrency를 둔다. group은
`frontend-quality-gates-<event>-<ref>-<stage>`다. PR run의 ref는
`refs/pull/<번호>/head`라 PR마다 group 하나, branch push는 branch마다
하나, release tag는 tag마다 하나다. cancel-in-progress는 수동 실행만
거짓이다. Gitea 1.27.0은 group과 cancel-in-progress를 서버에서 식으로
계산하고(`services/actions/concurrency.go`, `inputs` 포함), 같은 group의
앞 run을 대기 중이면 언제나, 실행 중이면 cancel-in-progress가 참일 때
취소한다.
- 수동 실행에 stage를 group에 넣고 취소를 끈 이유: 다음 수동 실행이
  검증과 승격 사이의 release run을 끊지 않게 한다.
- 버린 대안: 백엔드처럼 event·ref만으로 group을 짓기. 프론트는 수동
  실행 하나가 stage 여섯을 받아, 다른 stage의 수동 실행끼리 취소된다.

위험·한계: 실제 취소는 runner에서 push 두 번으로 확인해야 한다(다음
커밋들의 PR run으로 남긴다). 이 커밋 전에 만들어진 대기 run은 group이
없어 취소되지 않는다.

검증(desktop): generate:ci-workflow, ci-workflow-generation 시험 파일
전부 통과(스냅샷 갱신 포함), check:ci-workflow rc=0, check:types rc=0,
eslint rc=0. 로그 /tmp/claude-gates/w2fe2-gen1/, w2fe2-cov1/.
2026-11-12 22:02:56 +09:00
DongHyeonka ba72b86595 chore(merge): FE-GATE-013 판정·시험 timeout PR들이 들어간 main을 받는다
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m7s
frontend-quality-gates / merge / tests (pull_request) Successful in 20m56s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m56s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
main(5250ff95)의 PR #17·#18·#20·#21·#22를 받는다. 충돌 정리:
- tests/setup.ts: main의 자식 프로세스 timeout 감시를 그대로 두고, Testing
  Library는 DOM이 있는 파일에만 불러오는 이 브랜치의 방식을 남긴다.
- tests/system/ci-runner/ci-artifact-contract.test.ts: main이 같은 결함
  (.claude 추적 파일 ENOENT)을 저장소 배치 등록부의 provider-fixture-skip
  집합으로 이미 고쳤다. main 쪽을 받고 이 브랜치의 f90ffb6c 고침은 버린다.
  CHANGELOG의 그 행도 지운다.
- 작업 매뉴얼·스킬(gates.md 3절, operate·improve·new-feature, evidence,
  desktop-gates·fe-testing 스킬): 기본은 시스템 컨테이너 경로, main의 D8
  판정(사전 점검의 userns 제한 하나뿐이고 뒤 명령 모두 rc=0이면 merge
  판정에서 뺀다)은 컨테이너를 띄울 수 없는 호스트에 쓴다.
- 그 호스트에서 D8 절차를 그대로 돌릴 수 있게 scripts/verify.sh에
  VERIFY_HOST_ENVIRONMENT=off(hostEnvironment 게이트를 이 호스트에서 바로
  돈다)를 더하고 원격 실행에도 넘긴다. 시험 하나를 더한다.
- decisions.md는 main 그대로(D8이 2.2절에 있어 이 브랜치의 O-21 행은 겹친다).

검증(노트북): python3 -m unittest discover -s scripts/tests 73개 통과,
scripts/verify.sh docs rc=0. desktop merge 단계는 이 커밋에서 다시 돈다.
2026-11-12 20:00:50 +09:00
DongHyeonka f6e2560e4d docs: FE-GATE-013이 시스템 컨테이너에서 도는 것을 지침과 운영 문서에 적는다
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m49s
frontend-quality-gates / merge / tests (pull_request) Successful in 22m18s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m54s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
문제: 작업 매뉴얼·루트 지침·스킬이 「desktop의 FE-GATE-013은 호스트 제약
실패로 적고 merge 가능 여부는 소유자가 정한다(결정 대기 D8)」라고 적고
있다. 1d3eb901 뒤로 workflow와 scripts/verify.sh는 이 게이트를
scripts/run-in-system-container.sh 안에서 돌리고, 다른 게이트처럼 rc로
센다. CHANGELOG에는 이 브랜치의 변경이 없다.

고른 방법:
- gates.md 3절 문단을 「시스템 컨테이너 안에서 돈다」로 바꾸고, AGENTS.md
  ·improve.md·new-feature.md·operate.md·desktop-gates 스킬의 기록법
  문구를 그 절을 가리키게 고친다.
- decisions.md: 소유자 결정(2026-11-11, design-docs template-program
  README 5절 e)을 2.1절 행으로 더하고 열린 결정 대기 D8을 닫는다.
  evidence.md의 근거 행을 새 규칙 이름과 runner 사건으로 고친다.
- docs/operations/ci-quality-gates.md, docs/testing/taxonomy.md,
  README.md에 컨테이너 경로와 그 한계(root라 비특권 userns 조건은 증명하지
  않음, privileged를 막는 runner에서는 깨짐)를 적는다.
- CHANGELOG 미출시 절에 이 브랜치의 변경을 적는다.

위험·한계: desktop·runner에서 FE-GATE-013이 실제로 초록인지는 이 브랜치
끝의 merge 단계 실행으로 확인한다.

검증: 노트북 scripts/verify.sh docs rc=0. desktop verify:documentation
PASS_SCOPED, 문서를 읽는 시험 넷(changelog-review-ids,
documentation-readiness, template-contract-documents,
deletable-history-documents) 29개 통과.
2026-11-12 19:52:09 +09:00
DongHyeonka 374af98640 docs: 번역하며 찾은 낡은 서술을 코드·설정에 맞춘다
문제: 살아 있는 문서를 옮길 때 뜻을 바꾸지 않는다는 규칙 때문에 남겨
둔 낡은 서술이 있다.
- contract-ownership: 계약 파일 「39개」. 지금 src/contracts의 .ts는 44개다.
- capability-consumer-experience: Local Draft를 「두 번째 구체 소비자」,
  「두 feature」라고 부른다. 지금은 제품 feature가 아니라 테스트 fixture
  (tests/fixtures/indexeddb-consumer)다.
- static-delivery: initialJavascript.files가 「예시 feature 기준」이라고
  한다. feature-shape-ceilings.json은 feature가 없는 지금 템플릿 빌드라고
  적는다.
- .dependency-cruiser.json:254 주석이 번호 없는 layers.md의 「§4」를 가리킨다.
- runbook 문서 제목 셋이 runbooks.json title과 다르다. FE-RB-002는 영어
  원문부터 manifest가 빠져 있었고, 001·003은 번역에서 갈라졌다.
- ci-quality-gates: zod 행의 고친 버전은 4.6.6인데 이유 칸은 4.6.7을 말한다.
  4.6.7은 올렸을 때 잰 버전이다(26ca2fdb 원문 "4.6.7 also adds").
- 같은 문서 FE-GATE-016 문단 끝 두 문장은 원래 runbook record 고정 경로
  문단의 것이다(6c52cdb9 원문). 폐기 문장 뒤로 밀려 뜻이 끊겼다.

고른 방법: 숫자는 옮겨 적지 않고 정본(src/contracts/)을 가리킨다.
Local Draft는 fixture라고 쓰고, 편의 프로필을 들일 조건을 「IndexedDB를
쓰는 제품 feature」로 좁힌다. 절 번호는 절 이름으로, 문서 제목은 등록부
title로 맞춘다. zod는 「고친 버전 이상으로 올리면」으로 쓰고 잰 버전과
날짜를 괄호에 둔다. 두 문장은 원래 문단으로 옮긴다.

위험: zod 7 KB는 다시 재지 않았다(2026-11-04 측정값 그대로).
cruiser 주석은 check:architecture 위반 메시지의 why 줄에 나온다. 이 주석을
비교하는 시험은 없다.

검증: 각 사실을 git ls-files, feature-shape-ceilings.json, runbooks.json,
layers.md 절 제목, 원문 커밋으로 확인했다. 문서 검사와 관련 시험은
desktop에서 돌린다.
2026-11-12 09:40:51 +09:00
DongHyeonka e9e98b8aa7 Merge branch 'main' into claude/fe-b-docs-korean-645f55
정리 3·4단계 PR #14와 CI 재편 PR #16(main 38c0dc7d)을 받는다. 충돌은 아홉
파일이다. 이 브랜치가 한국어로 다시 쓴 문서에 두 PR이 영어 판에서 바꾼
것을 한국어로 넣었다.
- a11y 기록 경로 `artifacts/tests/a11y-manual/` → `docs/accessibility/route-reviews/`:
  README, docs/README.md, manual-checklist, starter-experience,
  ci-quality-gates. 문서 검사의 `NOT_DOCUMENT`도 새 경로로 바꿨다(정해진 영어
  키 형식의 게이트 입력이라 문서로 보지 않는다)
- ci-quality-gates.md: merge 단계 job 셋, 지운 CI 계약 기준선, main 단계
  FE-GATE-029의 `check:ci:gating`
- adapter 재검토 원장: 합친 음성 fixture script
- README 프로젝트 구조: `schemas/`는 `config/schemas/`로, `artifacts/`는
  `.gitkeep`만 추적, 최상위 항목 등록부 `config/repository-layout.json`
- verify-documentation-readiness.ts: #14의 배치 규칙 검사(R6·R7)와 이 브랜치의
  문서 체계 검사를 둘 다 둔다. R7의 「현재 문서」는 #14의 폴더 목록(옛
  `docs/superpowers/` 포함) 대신 문서 검사의 `checkedForDrift`로 고른다
- deletable-history-documents 시험: #14의 등록부 기반 경로와 이 브랜치의
  검사기 예외를 같이 둔다
- CHANGELOG: 범위 문장과 표 행을 둘 다 둔다
- 루트 등록부에서 SPEC.md 항목을 뺀다(그 항목이 「문서 체계 작업이 이력 폴더로
  옮기고 이 항목을 뺀다」고 적었다)
- #14가 옛 `docs/testing/frontend-platform-testing-strategy.md`를 고친 것이
  이름 바뀜을 따라 기록(docs/design/…)에 들어와서, 기록은 옮길 때의 글로 되돌렸다
2026-11-12 04:53:06 +09:00
DongHyeonka 45e8cb774c docs(operations): 운영 문서와 adapter 재검토 처리 원장을 한국어로 옮긴다
문제: docs/operations의 release-cache-rollback.md와
adapter-remediation-ledger.md는 본문이 영어이고, 나머지 복구 문서와
ci-quality-gates.md에도 영어 문단이 남아 있다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. 원장은 check:remediation-ledger가
읽으므로 같은 변경에서 스크립트를 맞춘다.
- `SECTION_HEADING`을 옮긴 절 제목(`## 세 번째 재검토 (2026-08-14)`)으로
- 「모두 닫혔다」를 잡는 `BLANKET_CLOSURE`에 한국어 대안을 더한다. 영어
  대안은 원장이 인용한 옛 문장을 잡도록 그대로 둔다
- 표 구조, id 칸, disposition 칸의 백틱 값, file-transfer 예산 숫자는
  그대로다
- ci-quality-gates.md의 advisory 표가 복사한 zod·react-router 버전을
  `package.json`·`pnpm-lock.yaml`을 가리키게 바꾼다(number 검사)

위험: check:remediation-ledger는 게이트 밖이라 CI가 돌리지 않는다.
desktop에서 손으로 돌려 확인했다.

검증: dispositions.json의 id 25개가 그 절의 행과 맞는지, 예산 숫자가
있는지를 스크립트로 확인했다. 문서 검사의 language·number 줄이 0이 되어
예외 목록에서 지웠다.
2026-11-08 21:57:47 +09:00
donghyeon.kang 3ce77d9e89 docs(ci): check-*.ts를 lint·의존 규칙·시험으로 옮길 수 있는지 판정한다
scripts/check-*.ts 30개(6,351줄)가 게이트 명령의 상당수를 차지한다.
각각을 ESLint 규칙, dependency-cruiser 규칙, vitest 시험으로 옮길 수
있는지 판정 표로 남긴다(design-docs repo-structure/03-ci.md 7.3절 F3).
코드는 바꾸지 않는다.

판정: 시험 8, 일부 이전 9, 스크립트 유지 11, ESLint 규칙 1, 지움 1
(정리 3단계). 위험이 낮고 효과가 큰 후보 5개와, 옮길 때 같이 고칠
증거 계약·drill 목록을 적었다.

위험: 줄 번호는 판정 시점 `ad3a071f` 기준이다. 판정 중에 찾은 가짜 검사
2개(`check-design-system.ts`, `check-diagnostics.ts`의 fixture 표식 검사)는
고치지 않았다.

검증: 문서만. 스크립트를 읽어 판정했고 실행하지 않았다.

Refs: design-docs repo-structure/03-ci.md 7.3절 F3
2026-11-08 21:56:38 +09:00
donghyeon.kang f6b2b96c53 ci(gates): 검사기 자기 시험과 gating 검사를 main 단계로 내리고 계약 기준선을 지운다
merge 단계(=PR)가 변경이 아니라 검사기 자신을 시험하는 명령까지 돈다.
검사기가 나쁜 입력을 거부하는지 보는 `*:fixture` 명령 15개, 모든 시험
파일과 검증 script가 게이트에 걸렸는지 보는 ungated 검사, CI 계약의
개수·해시 기준선(`config/ci/contract-baseline.json`)이다. 기준선은 게이트
명령 하나를 더하거나 빼도 OWNER·REASON을 붙여 다시 받아야 했다.
소유자 결정(2026-09-16)은 개수·배선 검사를 main 단계에 두는 것이다.

고른 방법(design-docs repo-structure/03-ci.md 7.3절 F2, README.md 3.3절,
소유자 승인 2026-11-07):
- 새 게이트 FE-GATE-029 `checker-self-tests`, 새 단계 `main`
  (`MAIN_READY`, 승격을 막지 않는다), 새 job `main_gate`. 브랜치 push와
  `workflow_dispatch`(stage=main)에서만 돈다. PR과 태그에서는 돌지 않는다.
- FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거
  산출물 10개를 FE-GATE-029로 옮긴다.
- `check:ci`의 ungated 검사를 `scripts/check-ci-gating.ts`
  (`check:ci:gating`)로 떼어 FE-GATE-029에 둔다. `check:ci`는 계약·
  workflow 검사만 PR에서 돈다.
- 기준선 파일, `update:ci-contract-baseline`, 그 검사를 지운다(소유자
  결정). 계약 모양은 ci-gates.ts의 의미 검사가 지킨다. 개수를 고정하던
  단위 시험의 개수 단언도 뺐다.

남긴 것: 음성 타입 fixture(`check:types:fixtures`, FE-GATE-003)는
이름이 `*:fixture`여도 merge에 둔다. 검사기가 아니라 src의 포트·계약
타입을 시험한다. `TelemetryPort.emit`을 넓히는 변경을 PR에서 막는다(정리
3단계 9.3절 변이로 확인). merge 단계 명령 참조 64 → 49.

위험: 검사기를 망가뜨린 PR은 merge를 통과하고 main에서 빨개진다. 그
대가로 PR이 검사기 자기 시험을 기다리지 않는다(설계 7.5절의 같은 교환).
FE-GATE-029의 명령이 앞 게이트 산출물 없이 새 checkout에서 도는지는
desktop에서 따로 확인했다(PR 본문).

검증(desktop): check:ci, check:ci:gating, check:types, CI 시험 통과.
merge 단계·FE-GATE-029 실행 결과는 PR 본문에 적는다.

Refs: design-docs repo-structure/03-ci.md 7.3·7.4절, README.md 3.3절
2026-11-08 21:56:37 +09:00
donghyeon.kang 0739f26b80 ci(gates): merge 단계 job 14개를 셋으로 합친다
merge 단계가 게이트마다 job 하나(행렬 14개)라서 PR마다 checkout,
setup-node, `pnpm install`을 14번 하고 브라우저 설치를 2번 한다. Gitea
runner는 소유자 기계 한 대다. 사례(Vite 등)는 설치를 job당 한 번으로
묶는다(design-docs repo-structure/03-ci.md 3.5절).

고른 방법(03-ci.md 7.3절 F1, 소유자 승인 2026-11-07):
- job 종류 `gate-sequence`를 더한다. job 하나가 게이트 여럿을 차례로
  돈다. 게이트마다 `FE-GATE-NNN / <이름>` 단계이고 `if: !cancelled()`라
  앞 게이트가 실패해도 다음 게이트가 돈다(행렬의 fail-fast: false와 같다).
- merge job 셋: `merge_static`(001·002·003·010·011·012, 소스를 읽고
  빌드하는 검사), `merge_test`(004·005·006·007·013·020, 시험),
  `merge_browser`(008·009, 브라우저 설치). release 단계는 셋을 모두
  기다린다. 게이트 id·명령·증거·승격 공식은 그대로다.
- 증거 업로드는 job마다 하나(`merge-static-<run>` 등)다.

버린 것: 행렬을 두고 `pnpm install`만 캐시하는 방법. runner 한 대에서는
job 수만큼 checkout과 준비가 남는다. 게이트를 job 하나에 모두 넣는
방법은 브라우저 설치를 모든 게이트가 기다린다.

위험: 한 job 안의 게이트가 같은 작업 공간을 쓴다. 앞 게이트의 산출물이
뒤 게이트에 남는다. desktop의 merge 단계 실행(게이트를 한 checkout에서
차례로 도는 것)과 같은 조건이라 그 결과로 확인했다. 실제 Gitea runner의
`!cancelled()` 해석은 Actions를 켠 뒤 확인한다.

검증(desktop): check:ci, check:types, CI 시험 4파일 통과. 합치기
전후 merge 단계 게이트별 결과 비교는 PR 본문에 적는다.

Refs: design-docs repo-structure/03-ci.md 3.5·7.3·7.4절, README.md 3.3절
2026-11-08 21:56:28 +09:00
donghyeon.kang 79dc945a67 refactor(layout): 루트 경로 목록을 등록부 하나에서 고르고 schemas/를 옮긴다
루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
  들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
  `scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
  집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
  같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
  공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
  추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
  문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
  스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
  `config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
  `.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
  복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
  `tests/fixtures/hosting/response-headers.json`.

버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.

위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).

검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
2026-11-08 17:41:07 +09:00
donghyeon.kang bf485f449a refactor(typecheck): 음성 타입 fixture 23개를 실행기 하나로 돈다
음성 타입 fixture마다 옵션이 같은 tsconfig 하나, package script 하나,
게이트 명령 하나가 있었다(23벌). 옵션은 모두 같고 파일 하나만 달라서
fixture를 더할 때마다 세 곳을 같이 고쳤다. `tsconfig.recipes.json`도
`tsconfig.test.json`과 lib가 같고 types만 하나 적었다.
`tsconfig.web-worker.json`은 `files: []`로 0파일을 검사하고 통과했다
(2026-09-25 리뷰가 기록, FE-GATE-003이 통과로 보였다).

고른 방법(design-docs repo-structure/04-frontend-layout.md 5.3절 (가),
소유자 승인 2026-11-07):
- fixture 첫 줄에 기대(`// expect: TS2322`, `// expect: pass`)를 쓰고
  `scripts/check-type-fixtures.ts`가 fixture마다 `.tmp/type-fixtures/`에
  한 파일 tsconfig를 써서 tsc를 돈다. 판정은 run-ci-gate.ts가 명령마다
  하던 것과 같다(exit 1과 `error TS<code>:`). 결과를 fixture별로 출력한다.
  기대 줄이 없는 fixture와 fixture 0개는 실패한다.
- recipes는 `tsconfig.test.json` include로 옮긴다.
- web-worker tsconfig와 script는 지운다(결정 D4). Worker를 들일 때 더하는
  단계는 매뉴얼 03에 쓴다(뒤 커밋).
- `scripts/check-typecheck-inputs.ts`를 `check:types` 끝에 둔다. package
  script가 tsc에 넘기는 tsconfig마다 이 repo 파일이 1개 이상인지 본다.
  `files: []` tsconfig가 통과로 보이던 구멍을 막는다(R8).

버린 것: TypeScript API로 한 프로세스에서 돌리는 방법. 이 repo의
TypeScript 7.0(네이티브판)은 JS API를 싣지 않는다. 위반마다
`@ts-expect-error`를 쓰는 방법(5.3절 (나))은 오류 코드 고정을 잃는다.

위험: recipe가 이제 `vite/client` 타입이 있는 프로그램에서 검사된다.
recipe가 `import.meta.env`를 쓰면 전에는 실패했고 이제는 통과한다
(복사한 제품도 Vite라 가치가 작다, 설계 5.1절). CI 계약 기준선을 다시
받았다(명령 99 → 76).

검증(desktop): `check:types:fixtures` 23개 PASS, 각 fixture의 기대 코드가
출력에 그대로 나온다. `TelemetryPort.emit` 인자를 `string`으로 넓히는
변이(2026-09-25 리뷰 07-05)에서 `invalid-diagnostics-port.ts`가 TS2578로
FAIL, 실행기 rc=1. 되돌린 뒤 작업 트리 0줄. `check:types` rc=0
(Typecheck inputs: app 379, node 312, service-worker 22, test 915).

Refs: design-docs repo-structure/04-frontend-layout.md 5.3·9.2·9.3절, README.md 3.4절 D4
2026-11-08 17:40:12 +09:00
DongHyeonka e632b230e3 docs: 옮긴 문서를 가리키는 링크와 경로를 새 위치로 고친다
문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는
상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을
가리킨다.

고른 방법: 기계적으로 바꾼다.
- 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고,
  대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다.
  옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은
  링크 대상뿐이다(백엔드 1단계와 같은 예외).
- 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`,
  `docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과
  CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와
  review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토
  작업 공간의 출처 표시라 그대로 둔다.

위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는
없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다.

검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록,
CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시
쓴다) 밖에서 0건.
2026-11-08 17:25:41 +09:00
DongHyeonka e3c8db48ae chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.

참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.

위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.

검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
2026-11-08 14:07:58 +09:00
DongHyeonka 121e11250a docs(operations): nginx 설정 예시를 지우고 호스트가 지킬 조건만 남긴다
문제: docs/operations/release-cache-rollback.md에 nginx 설정이 통째로
있다(보안 헤더 snippet과 server 블록, 「Example: nginx on a single
server」 절). CI는 그것을 돌리지 않고, 호스트 설정은 개발 repo의 일이
아니다(소유자 2026-11-07). ci-quality-gates.md의 runner 요구 절에도
호스트를 바꾸는 절차(AppArmor profile 본문, sysctl 명령)가 있다.

고른 방법:
- nginx 절을 지우고 같은 문서에 「운영 환경이 지켜야 할 조건」 19개를
  문장으로 쓴다. 조건마다 재는 쪽을 적었다: FE-GATE-019가 잰다(live
  모드, 값은 config/hosting/*.json) / 아무도 재지 않는다. 백엔드와 같은
  절 이름·같은 언어(한국어)다.
- 지운 설정을 한 줄씩 대조했다. snippet 6줄 → 6(값), always → 7;
  listen 443 ssl·server_name·인증서 → 1; http2 → 2; gzip·gzip_types →
  10, gzip_vary → 11; root current와 원자적 symlink 전환 → 17;
  index.html → 3·6; try_files fallback → 4·6; config.json·
  release-manifest.json → 5·6; 공유 /assets/·기간으로 지우기 → 18;
  없는 청크 404 → 12; immutable → 8; service-worker.js → 14·15;
  .map 404 → 16; Cache-Control에 always 없음 → 13; 기본 base path / →
  1; mime.types에 맡긴 Content-Type → 3·5·9·14. 롤백 때 동작은 19.
- static-delivery.md의 "nginx example" 문장은 이 절을 가리키게 고친다.
- ci-quality-gates.md: runner 요구(바이너리, systemd, cgroup, 비특권
  user namespace)는 게이트가 runner에 요구하는 조건이라 남긴다. 고치는
  방법 목록과 AppArmor profile 본문만 지우고 "고치는 방법은
  scripts/check-system-test-prerequisites.ts가 실패할 때 출력한다"로
  바꾼다. 그 스크립트가 같은 세 방법을 출력한다.
버린 대안: nginx 설정을 project-infra나 cicd-platform으로 복사하기.
아무도 시험하지 않는 복사본이 다른 repo에 생긴다(백엔드도 지웠다).

위험·한계: 아무도 재지 않는 부분이 있는 조건이 11개다(7, 8의 나머지 파일,
10의 나머지 청크와 CSS·JSON·SVG, 11, 12, 13, 15, 16의 호스트 쪽, 17의
전환 도중, 18, 19의 호스트 쪽). 지운 nginx 예시도 CI가 돌리지 않았으니
재지 않는 범위는 넓어지지 않았다. AppArmor profile 본문은 이 repo에서
없어진다. 필요하면 runner를 만드는 쪽 인프라 repo가 갖는다.

검증: git grep -n '^```nginx' 0줄. desktop(이 커밋 30a379f 트리, 로그
~/l1-layout-cleanup-logs/): verify:documentation PASS_SCOPED(새 절의
경로·script 이름·FE-GATE ID와 static-delivery.md의 링크 포함),
test:unit 3091 tests 통과.

Refs: design-docs repo-structure/04-frontend-layout.md 4절 I-3·I-4·I-11
2026-11-07 19:02:47 +09:00
DongHyeonka b41990cdd5 fix(query): 재전송 거절의 결과 불명 해제를 짝 백엔드 표 code로만 정한다
문제: 80e7f1d의 isRefusedOnEveryAttempt는 kind가 VALIDATION_REJECTED면 code를
보지 않고 참을 돌려준다. 그 kind는 기능의 mapProblem이 정한다. 생성기는
선언한 <FEATURE>_INVALID를 VALIDATION_REJECTED로 옮기고
(scripts/create-feature-write-slice.ts mapProblem), 참조 기능 gateway는 code와
상관없이 모든 422를 그렇게 옮긴다(reference-http-gateway.ts). 그래서 기능이
선언한 code나 422 IDEMPOTENT_REQUEST_MISMATCH로 끝난 같은 키 재전송이 결과
불명을 푼다. 함수 주석, CHANGELOG, 런북 6.3-4는 이것들이 결과 불명으로
남는다고 적는다. 기존 테스트는 mapProblem 없이 실패를 만들어 이 길을 타지
않았다(최종 리뷰 FR-01).

고른 방법(메인 세션 결정 "D10 보완 2"): 재전송 거절은 짝 백엔드 표의 code일
때만 결과 불명을 푼다. 지금은 400 VALIDATION_FAILED와 400
IDEMPOTENCY_KEY_INVALID다(REFUSALS_OF_EVERY_ATTEMPT, code와 status 함께). kind
줄을 지우고 kind로 입력 검증을 말하던 주석과 런북 6.3-4를 고쳤다. 기능 code는
상태 규칙일 수 있어 mapProblem이 정한 kind를 믿지 않는다. 400
VALIDATION_FAILED는 필드 목록이 있든 없든 전처럼 푼다.
테스트: 훅의 결과 불명 유지 it.each에 mapProblem 모양(VALIDATION_REJECTED +
선언 code, VALIDATION_REJECTED + 422 IDEMPOTENT_REQUEST_MISMATCH) 두 행을 더했다.
참조 페이지에서 422 재전송이 필드 오류와 다시 저장을 보인다던 테스트를, 결과
불명이 남고 확인이 보이는 테스트로 바꿨다. 리뷰가 요청한 대로 다시 마운트한 폼이
다른 값을 보이는 채 재전송해 422 IDEMPOTENT_REQUEST_MISMATCH를 받으면 결과
불명과 확인 버튼이 남는 테스트를 더했다.
버린 대안: kind 줄을 남기고 기능 선언 code만 빼기(실행기는 code가 선언인지
폼과 훅에 알리지 않는다).

위험·한계: 참조 기능처럼 problem details를 읽는 기능의 422 입력 검증은 재전송
뒤 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다. 리뷰 실험 03-R1
X1~X3·X5는 그대로 키가 모두 key-1이어야 한다. CHANGELOG는 다음 커밋이 적는다.

검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx tests/unit/backend-envelope.test.ts,
리뷰 실험 03-R1 패치를 이 커밋에 적용

Refs: 1106/03-01 (final review FR-01)
2026-11-06 08:25:28 +09:00
DongHyeonka 80e7f1d63a fix(query): 같은 요청이 매번 받는 거절로 끝난 재전송은 결과 불명을 푼다
문제: 1106/03-01(2568587)은 결과 불명 요청을 같은 키로 다시 보낸 시도가
NOT_APPLIED·NOT_STARTED로 끝나면 이유와 상관없이 결과 불명과 키를 남긴다.
같은 요청이 매번 받는 거절(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID,
필드 목록이 있는 입력 검증)도 같다. 폼은 필드 오류를 버리고 "잠시 뒤 같은
요청으로 다시 보내 주세요"만 보인다. 저장은 꺼져 있고 다시 보내면 같은 400이
온다. 출구는 사실이 아닌 "변경됨으로 확인"이나 새로고침뿐이다. 815ea58
(1106/03-03)이 같은 길을 IDEMPOTENT 쓰기로 넓혔다(diff 리뷰 DR-01).

고른 방법(메인 세션 결정, D10 보충): 같은 키 재전송은 그 결과가 첫 요청에
무슨 일이 있었는지 보여 줄 때만 결과 불명을 푼다.
- 성공·APPLIED_CONFIRMED: 저장된 답의 재생이다. 지금처럼 푼다.
- 같은 요청이라 첫 요청도 받았을 거절: 푼다. src/contracts/errors.ts에
  isRefusedOnEveryAttempt를 두었다. effect NOT_APPLIED이고, kind
  VALIDATION_REJECTED(필드 목록이 있는 입력 검증)이거나 code·status가
  REFUSALS_OF_EVERY_ATTEMPT(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID)다.
- 그 밖(429, 401, 403, 503 RATE_LIMIT_*, 422 IDEMPOTENT_REQUEST_MISMATCH(키가
  이미 서버에 닿아야 나온다), 기능이 선언한 code(바뀌는 상태의 규칙일 수
  있다), IDEMPOTENT 쓰기의 404·412 같은 다른 code, NOT_STARTED): 지금처럼
  결과 불명과 키를 남긴다. 어느 쪽인지 모르는 code는 남긴다.
훅(resendLeavesUnknown)과 폼(resendLeftUnknown)이 같은 함수를 부른다. 폼은 푼
경우 처음 저장과 같이 보인다(필드 오류, 다시 받는 저장, 고친 값은 새 키).
남긴 경우 결과 불명 화면(확인·다시 보내기)이 그대로라 폼이 영영 막히지
않는다. 표는 backend-envelope.ts REFUSED_BEFORE_WRITE의 부분집합이어야 하고,
표의 나머지 행은 다른 쪽으로 분류된다. backend-envelope 단위 테스트가 둘을
대조해, 표에 새 행이 생기면 이 분류를 정할 때까지 실패한다. presentation은
adapters를 import할 수 없어(.dependency-cruiser.json) 판정을 contracts에 둔다.
버린 대안: 일시 거절(NOT_STARTED, retryable, RATE_LIMITED, RATE_LIMIT_*)만
남기기(diff 리뷰 안). 401·403과 422 IDEMPOTENT_REQUEST_MISMATCH, 기능 선언
code를 풀어 버린다. AppFailure에 새 칸을 더해 실행기가 표시하기(계약 타입과
실행기·바인딩을 함께 바꾼다).

위험·한계: 기능이 선언한 결정적 거절(생성 기능의 400 <FEATURE>_INVALID)은
어느 쪽인지 알 수 없어 결과 불명으로 남는다. 출구는 결과 불명 화면의
확인이다. 필드 목록이 있는 NOT_APPLIED는 기능 선언 code여도 입력 검증으로
본다. 리뷰 실험 03-R1 X1~X3·X5(503·429·NOT_STARTED)는 그대로 키가 모두
key-1이어야 한다. 런북 6.3-4를 고쳤다. CHANGELOG는 다음 커밋이 적는다.

검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/component/form-foundation.test.tsx
tests/features/reference-feature/reference-page.test.tsx
tests/unit/backend-envelope.test.ts, 리뷰 실험 03-R1 패치를 이 커밋에 적용

Refs: 1106/03-01 (diff review DR-01)
2026-11-06 08:00:56 +09:00
DongHyeonka 81ff05efc1 chore(review): 1106 화면·테마 조치 브랜치를 합친다 2026-11-06 07:24:11 +09:00
DongHyeonka 7625dc4548 fix(theme): 열린 modal의 가림막이 스크롤바 자리까지 덮게 한다
문제: :root의 scrollbar-gutter: stable(1105/15-05)은 일반 스크롤바를 쓰는
브라우저에서 문서가 스크롤되지 않아도 오른쪽 15 px를 비워 둔다. 그 자리에는
root의 배경색이 보인다. 고정 위치 상자와 top layer의 ::backdrop은 그 자리
앞에서 끝나서, drawer·modal을 열면 오른쪽 끝에 가림막이 덮지 않은 밝은
세로 띠가 남는다. compact 골든(390 px, drawer 열림)이 가림막이 375 px에서
끝나는 모습을 정답으로 고정했다. header 띠도 같은 자리 앞에서 끝난다.

고른 방법:
- modal이 열린 동안 root 배경색을 가림막을 페이지 바탕 위에 겹친 불투명한
  색으로 바꾼다. primitives.css의 :root:has(.ui-dialog[open])이
  background-color: var(--dialog-backdrop-on-surface)를 쓴다.
- 새 컴포넌트 토큰 셋(component.css). --dialog-backdrop-weight(55%)를
  --dialog-backdrop(::backdrop이 칠하는 반투명 가림막, 값은 전과 같다)과
  --dialog-backdrop-on-surface(color-mix in srgb로 페이지 바탕과 섞은 색)가
  같이 읽는다. 브라우저는 반투명 색을 sRGB에서 겹치므로 두 색이 맞는다.
- body가 페이지 바탕(--color-surface)을 직접 칠한다. 그래서 root 배경은
  스크롤바 자리(와 overscroll)에만 보이고, 열린 modal 아래 페이지가 두 번
  어두워지지 않는다. modal이 없으면 둘이 같은 색이라 화면이 그대로다.
- 검사: tests/visual/scrollbar-gutter.visual.spec.ts. 시각 프로젝트에서
  Chromium을 --hide-scrollbars 없이 띄우고, 스크롤되지 않는 /not-found
  (390x844)에서 스크롤바 자리와 바로 옆 가림막의 평균 픽셀 색을 비교한다.
  닫힘 → drawer 열림 → 다시 닫힘 세 번 본다. 실패 메시지에 root의 계산된
  배경(색·이미지)과 열린 .ui-dialog 수를 적어, 규칙이 안 맞은 것과 맞았는데
  그 자리에 안 그려진 것을 구분한다. 08-R2 probe의 잘못된 단언 둘을
  고쳤다. 자리가 비어 있으면 clientWidth가 창 폭이라 자리 위치는 body의
  오른쪽 끝으로 찾는다. 그 자리의 hit test는 늘 null이라 픽셀을 본다.
  허용 차이 12는 drawer 그림자(70 px blur)가 옆 띠를 약 3단계 어둡게 하는
  몫이다. 덮지 않은 띠는 약 120 차이 난다.
- header 띠는 받아들이고 design-system-platform.md 8.2에 적었다. header
  색으로 칠하려면 root 배경이 셸의 header 높이·색을 알아야 하고, 셸이 없는
  화면에서는 그 띠를 빼야 한다. 완료 기준은 가림막만 요구한다.
버린 대안:
- 첫 시도: :root:has(.ui-dialog:modal)에서 가림막 색 gradient 한 겹을 페이지
  바탕 위에 얹었다. desktop batch에서 그 자리가 페이지 바탕색 그대로였다
  (gutter rgb(248 250 252), 옆 가림막 rgb(122 128 136)). 그 실행만으로는
  규칙이 안 맞았는지(:modal의 :has() 무효화), 이미지 층이 그 자리에 안
  그려졌는지 가를 수 없다. 그래서 둘 다 피한다. 배경색 자체를 바꾸고,
  showModal()이 세우는 [open] 속성으로 고른다. Dialog primitive는 브라우저에서
  늘 showModal()로 열기 때문에 열린 .ui-dialog는 modal이다.
- ::backdrop에 음수 inset(right: -N px): 스크롤바 자리는 viewport의
  padding box 밖이라 고정 위치 상자가 잘린다(스펙 기준, 화면 확인은 안 함).
- scrollbar-gutter를 거두기: 15-05의 첫 화면 shift를 다시 연다.
- modal이 열린 동안 root 배경만 바꾸고 body를 비워 두기: 페이지 전체가
  가림막 아래에서 한 번 더 어두워진다.

위험·한계: :has()를 모르는 브라우저(Firefox 121 미만 등)는 이 규칙을 버리고
전처럼 띠가 남는다. 그 자리 색은 가림막의 blur(2px)를 따르지 않는 평평한
색이다. 오른쪽 drawer(placement="end")는 drawer와 창 끝 사이에 가림막 색 띠가
남는다(템플릿은 쓰지 않음, 미확인). RTL, Firefox, WebKit은 보지 않았다.
문서가 스크롤되면 그 자리의 스크롤바는 전처럼 가림막 밖이다.
--hide-scrollbars로 찍는 compact 골든은 전체 페이지(1377 px)를 찍으므로,
열린 modal 동안 어두워진 root 배경이 창 높이(844 px) 아래의 오른쪽 15 px
띠에도 보인다. 실제 브라우저에서 그 부분은 스크롤바 아래에 있다. compact
골든 1장은 desktop에서 다시 찍었다(test:visual:update). 바뀐 것은 x 375~390
띠가 높이 전체에서 가림막 색이 된 것뿐이다. 나머지 골든 4장은 바뀌지
않았다(body와 root가 같은 색). 레이아웃은 바꾸지 않았다.

검증: desktop batch에서 확인.
corepack pnpm test:visual tests/visual/scrollbar-gutter.visual.spec.ts
corepack pnpm test:visual:update 뒤 corepack pnpm test:visual
node scripts/r5-15-scrollbar.mjs 3 <out.json> (15-R3, 첫 화면 shift 0 유지)

Refs: 1106/08-03
2026-11-06 07:24:02 +09:00
DongHyeonka 68fc796a9e chore(review): 1106 문서·CHANGELOG 조치 브랜치를 합친다 2026-11-06 07:02:34 +09:00
DongHyeonka 90e485f3db chore(review): 1106 release 게이트 조치 브랜치를 합친다 2026-11-06 07:02:34 +09:00
DongHyeonka 6f15ac8f09 chore(review): 1106 Service Worker·호스팅 조치 브랜치를 합친다 2026-11-06 07:02:34 +09:00
DongHyeonka 37f1f87c90 chore(review): 1106 캐시·업로드 조치 브랜치를 합친다 2026-11-06 07:02:34 +09:00
DongHyeonka 815ea58e80 fix(query): IDEMPOTENT 쓰기는 결과 불명 뒤에도 다시 보낼 수 있게 한다
문제: 0929/03-03의 두 가드(재전송 버튼 canResend, 같은 입력 재제출 거절)가
intent의 키 유무로만 가른다. 뮤테이션 정책은 키 여부만 실어서 훅이 NEVER와
IDEMPOTENT를 가를 수 없다. 그래서 IDEMPOTENT 쓰기(손으로 쓴 PUT·DELETE)도
결과 불명 뒤 재전송 버튼이 없고 같은 입력 저장이 UNKNOWN_EFFECT_PENDING으로
거절된다. 출구는 사실을 모르는 "변경됨으로 확인"이나 새로고침뿐이다. 매뉴얼은
IDEMPOTENT를 "여러 번 적용해도 결과가 같다"로 적고, 실행기도 보낸 뒤에
다시 보낸다.

고른 방법(리뷰 03-03 대안 (a)): commandMutationIdentity가 resendSafe
(KEYED 또는 IDEMPOTENT)를 함께 준다. BoundMutation에 선택 칸 resendSafe를
더했다(추가만). 훅은 admission마다 resendable(키가 있거나 정책이
resendSafe)을 적고, 두 가드가 키 대신 그 값을 본다. 칸이 없는 손으로 쓴
정책은 지금처럼 키 유무로 간다. NEVER의 재전송 금지와 같은 입력 거절은
그대로다. 매뉴얼 01·02와 런북 6.3-4에 IDEMPOTENT 행을 적었다.
버린 대안: 문서만 고치기(회복 경로가 그대로 불편하다), IDEMPOTENT에도 키를
붙이기(백엔드가 키를 읽지 않으면 의미가 없고 실행기가
UNEXPECTED_IDEMPOTENCY_KEY로 거절한다).

위험·한계: commandMutationIdentity의 반환 객체에 칸이 하나 늘었다. 그 값을
toEqual로 비교하던 테스트는 칸을 더해야 한다(이 repo는 1곳을 고쳤다).
IDEMPOTENT로 잘못 선언한 쓰기(백엔드가 실제로는 중복을 막지 못함)는 이제
결과 불명 뒤 사용자가 다시 보낼 수 있다. 선언의 정확성은 기능 작성자
몫이다(02 결정표 3절). 템플릿 안에는 IDEMPOTENT 쓰기 소비자가 없다.
CHANGELOG 행은 문서 담당이 적는다.

검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/unit/command-mutation-identity.test.ts

Refs: 1106/03-03
2026-11-06 05:31:30 +09:00
DongHyeonka 25685871f1 fix(query): 쓰기 전에 거절된 같은 키 재전송 뒤에도 결과 불명과 키를 지킨다
문제: KEYED 결과 불명 요청을 같은 키로 다시 보냈는데 그 시도가 쓰기 전
거절(429, 엣지 rate limiter의 503 RATE_LIMIT_*, 401)이나 보내기 전 실패
(NOT_STARTED)로 끝나면, 훅이 그 판정을 논리 요청 전체의 판정으로 써서
결과 불명과 intent를 버린다. 폼은 retry-later가 되고 다음 저장이 새 키로
나간다. 첫 요청이 적용됐으면 같은 항목이 둘 생긴다. 재전송의 NOT_APPLIED는
그 시도만 증명한다. 백엔드 http-contract.md §2와 런북 6.3-4는 결과 불명에
새 키를 금지한다(리뷰 실험 03-R1 X1~X3·X5: keys key-1, key-1, key-2).

고른 방법(결정 D10, 메인 세션, 2026-11-06: 리뷰 03-01 대안 (a)):
- 훅(application-query.ts submit): 결과 불명 intent를 다시 쓴 시도가
  NOT_APPLIED·NOT_STARTED로 끝나면 새 admission을 UNKNOWN으로 되돌리고 그
  intent와 키를 남긴다. 실패는 그대로 돌려준다. Retry-After는 MAYBE_APPLIED와
  같이 다음 재전송의 대기 시각이 된다. 낙관적 층은 rollback 대신
  markUncertain이다(첫 요청이 적용됐을 수 있다). 훅 안의 보내기 전 예외
  (.catch, NOT_STARTED)도 같다. 이 경우 충돌 상태는 세우지 않는다. 화면은
  결과 불명을 먼저 보여야 한다. 처음 보내는 요청의 NOT_APPLIED, 재전송의
  성공·APPLIED_CONFIRMED, scope가 바뀐 경우는 지금처럼 정리한다.
- 폼은 (i)을 골랐다: use-app-form.ts resendUnknown이 그런 결과에서
  unknownSubmissionRef를 지우지 않고 result를 effect-unknown으로 둔다. 문구
  하나("form.resendLater": "잠시 뒤 같은 요청으로 다시 보내 주세요")를
  formErrors에 싣고 feedback으로 포커스를 옮긴다. 이유: 폼은 이미 그 ref로
  저장을 막는다(submitForm). 결과 불명 화면(확인·같은 키로 다시 보내기)이
  그대로 남아 다음 행동이 재전송이다. (ii)는 useAppForm이 코디네이터 상태를
  받는 새 옵션이 필요하다. 폼과 훅을 새로 묶는 일이라 지난 라운드 3.5 (B)로
  미룬 설계 변경이다. 401은 D-2대로 다시 로그인이 먼저다.
버린 대안: 표에서 rate-limit 503을 다시 MAYBE_APPLIED로(429·401·NOT_STARTED가
남고 1105/03-02의 이득을 잃는다), 생성 페이지의 "다시 시도"만 고치기(생성
기능만 덮는다).

위험·한계: 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남는다. 다시
보내기는 Retry-After(상한 5초)를 기다린다. 폼 밖에서 submit을 부른 같은
입력 재저장이 NOT_APPLIED로 끝나면 훅은 키를 지키지만 폼은 retry-later를
보인다. 그때 "다시 시도"도 같은 키로 간다. 새 문구가 초기 JS를 조금
늘린다(check:bundle). CHANGELOG 행은 문서 담당이 적는다.

검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/component/form-foundation.test.tsx, 리뷰 실험 03-R1 패치를 이 커밋에
적용해 X1~X3 keys [key-1,key-1,key-1], X5 세 번째 요청 없음 또는 key-1.

Refs: 1106/03-01
2026-11-06 05:28:30 +09:00
DongHyeonka 43ed03d14f docs(perf): 초기 파일 상한 문장이 템플릿 파일 수를 기록에서 읽게 한다
문제: `docs/operations/performance-evidence.md`의 초기 파일 상한 문장이
"상한은 템플릿 그대로의 수(26)에 6을 더한 32다"라고 적는다. 지금 기록은
27개다(`config/scale/feature-shape-ceilings.json`의 `initialJavascript.files`,
FE-GATE-012 `27 / 32 files`). 기록을 27로 다시 쓴 `0fee3fe`이 이 문장을 고치지
않았다. 1103/15-02의 완료 기준 "문서·JSON에 서로 다른 기준선이 없다"를 다시
어긴다. 같은 문서의 바이트 쪽은 이미 숫자를 적지 않고 기록을 가리킨다.

고른 방법: 지금 수를 지우고, 상한 32가 정할 때 6칸을 더한 값이라는 것만
남긴다. 지금 템플릿 수는 그 기록이 정본이고 남은 칸은 32에서 그 값을 뺀
것이라고 적는다. 바이트 절의 "기준선 숫자는 이 문서에 적지 않는다"와 같은
방식이다. 숫자를 27로 고치는 대안은 버렸다. 다음에 파일이 하나 늘면 같은
식으로 낡는다.

위험·한계: 상한 값 32는 예산 값이라 그대로 적었다. `budgets.json`을 바꾸면
이 문장도 고쳐야 하고, 그것을 보는 검사는 없다. 기록 파일은 참조 기능과 함께
지워질 수 있고, 그때 문서 검사는 이 경로를 요구하지 않는다
(`scripts/lib/removable-template-features.ts`).

검증: 문서만 바꿨다. desktop batch에서 확인.
corepack pnpm verify:documentation
node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/template-feature-removal-documents.test.ts

Refs: 1103/15-02
2026-11-06 05:23:03 +09:00
DongHyeonka 1eaa6447dc docs(perf): 초기 JS 예산 폭의 근거와 되돌림 규칙을 적는다
문제: D7이 초기 JS 예산을 204,800 → 206,848 B로 올렸다(`287dc6f`). 드릴
(FE-GATE-020, 생성 기능 둘)이 넘은 양은 665 B(CI env)인데 2,048 B를 올렸다.
문서는 올린 뒤 여유만 적고 왜 그 폭인지, 언제 다시 내리는지를 적지 않는다.
재검토 조건 "예산을 또 넘을 때"는 이번 상향의 조건과 같아서, 내릴 조건이 없다.
다음 담당자는 예산을 넘었을 때 올릴지 줄일지 문서에서 알 수 없다.

고른 방법: 메인 세션 결정 D9를 따른다. 206,848 B를 그대로 두고
`docs/operations/performance-evidence.md`의 예산 항목에 세 가지를 적는다.
- 폭의 근거: 드릴 측정값 205,465 B(CI env, `bbde570`) + 기능 하나의 상한
  1 KiB = 206,489 B를 KiB 단위로 올림해 202 KiB = 206,848 B. 드릴 위 여유
  1,383 B가 기능 하나와 올림 359 B로 나뉜다. 템플릿 자신의 몫은 이 규칙에 없다.
- 되돌림 규칙: D7의 재검토 조건마다 드릴을 다시 재고, 204,800 B 이하이면 같은
  규칙으로 내린다.
- 사용자가 이 결정을 뒤집을 수 있다.
버린 대안(리뷰 15-01의 대안): 예산을 드릴 + 256 B로 되돌리기(다음 템플릿
변경마다 넘는다), 테스트로 예산 값을 여유 규칙에 묶기(D9가 고르지 않았다).

위험·한계: 규칙은 문서에만 있다. 예산 값을 규칙 밖으로 바꿔도 실패하는
테스트는 없다(리뷰 대안 c는 고르지 않았다). 205,465 B는 2026-11-06의 한 번
측정이고, 다음 측정은 "다시 볼 때"에 한다. 결정 기록 자체는 오케스트레이터가
2026-11-06 리뷰 README에 적는다. 이 문서는 그 파일을 가리킨다.

검증: 문서만 바꿨다. desktop batch에서 확인.
corepack pnpm verify:documentation (새로 적은 경로
`docs/reviews/2026-11-06-maturity-review/README.md`와 FE-GATE-020을 본다)
node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/template-feature-removal-documents.test.ts

Refs: 1106/15-01
2026-11-06 05:22:31 +09:00
DongHyeonka 4cef2a2716 fix(cache-storage): 읽히지 않는 active pointer를 activation 옵션으로 덮어쓴다
문제: control cache의 active pointer entry는 있는데 저장된 본문이 다시
쓰기 전까지 계속 읽히지 않으면(blob 손실 등) Cache Storage 관리가 모두
멈춘다. readActivePointer는 이 실패를 UNAVAILABLE/RETRY(또는
NOT_READABLE/REOPEN)로 돌려주고 CORRUPT_DATA로 보지 않는다. activation은
CORRUPT_DATA 밖의 pointer 실패에서 멈추고, cleanup·inspect·조회도 같은
실패에서 멈춘다. pointer를 쓰는 곳은 activation 하나라서 RETRY를
지켜도 돌아오지 않는다. 돌아오는 길은 adapter 밖에서 control cache를
지우는 것뿐이다. 리뷰 실험 02-R1 X3이 이것을 보였다.

고른 방법: activateRelease에 선택 옵션 replaceUnreadablePointer를 둔다.
true면 이전 pointer를 읽지 못한 이유와 상관없이, 손상 pointer와 같은
0929/02-01 경로로 검증된 후보를 rollback 목록 없이 덮어쓴다. 기본값은
지금처럼 멈춤이라 "일시 오류 하나로 rollback 목록을 잃지 않는다"는
보존 조건이 지켜진다. 포트 주석, 설계 문서 8.3절, 운영 문서에 언제
쓰는지와 rollback 목록을 잃는다는 것을 적었다.
버린 대안: (가) 문서에 "control cache를 지우고 다시 activate"만 적기.
제품이 adapter 밖 코드로 소유 cache 이름을 알고 지워야 하고, 그동안
조회가 pointer 없음으로 바뀐다. (다) 연속 N회 실패를 손상으로 보기.
실패 횟수를 저장해야 하고, 긴 일시 오류에서도 rollback 목록을 잃는다.

위험·한계: 옵션을 켜면 일시 오류에서도 rollback 목록을 잃고, 다음
cleanup이 새 활성 release 밖의 owned release cache를 모두 지운다. 그래서
기본값으로 두지 않았다. 일시와 지속을 가르는 판단은 운영자 몫이다.
포트에 선택 칸이 하나 늘었다. 호출부·구현부 모두 호환이라 breaking이
아니다. CHANGELOG [계약] 행은 CHANGELOG 담당에게 남긴다.
1105/02-02의 남은 부분(release marker 본문이 계속 읽히지 않으면 stage가
marker를 다시 쓰지 않는다)은 이 변경으로 풀리지 않는다. marker는 release
cache 안의 entry라 stage 경로를 바꿔야 한다. 범위 밖으로 둔다.
service-worker-pwa 레시피 번들(여유 306 B)에 수십 B가 더해진다.
실제 브라우저에서 pointer 본문 읽기 실패가 지속되는지는 확인하지
못했다(리뷰 5절 미검증과 같다).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
RED(이 커밋의 테스트 + 부모 src): "replaces a pointer whose body stays
unreadable when the activation asks to (1106/02-01)"가 옵션을 준
activation에서 실패한다. 부모는 옵션을 모르므로 UNAVAILABLE/RETRY를
돌려주고 pointer를 다시 쓰지 않는다. 그 앞의 멈춤 단언(X3와 같은
결과)은 부모에서도 통과한다. 일시 오류 테스트 "still stops activation
when the pointer read fails transiently"는 바뀌지 않았고 통과해야 한다.

Refs: 1106/02-01
2026-11-06 05:21:06 +09:00
DongHyeonka c5ab7a3983 fix(ci): FE-GATE-027이 advisory 검사를 승인보다 먼저 돌린다
FE-GATE-027은 `check:release-admission`을 먼저, `scan:dependency-advisories`
를 뒤에 돈다. `ci:gate`는 처음 실패한 명령에서 멈춘다. 그래서 공개 대상
승인이 거절된 run에는 advisory 기록(`artifacts/security/
dependency-advisories.json`)이 생기지 않는다. 운영 문서는 release
산출물이 결과와 상관없이 이 기록을 싣는다고 적는다.

명령 순서를 scan → 승인으로 바꾼다. scan은 막지 않는 신호라 항상
exit 0이고, 승인 판정과 gate 결과는 그대로다. 문서 두 곳(한국어·영어)에
올라가는 것은 그 run에 생긴 파일이고, 승인이 거절돼도 기록이 있으며,
FE-GATE-015가 실패하면 FE-GATE-027이 돌지 않아 기록이 없다고 적는다.
gate 모양이 바뀌어 계약 기준선의 `gateShapeSha256`을 다시 적었다(owner
DongHyeonka, reason에 1106/13-01, 개수는 그대로). 생성 workflow는 명령
순서를 담지 않아 바뀌지 않는다.
버린 대안: (a) 문서만 고치기 — 거절된 run에서 신호가 한 run 늦는 것이
남는다. (c) scan을 always 단계로 따로 빼기 — 계약 단계와 workflow가
바뀌어 이 결함에 비해 크다.

위험·한계: 승인 전에 pnpm audit이 돌아 거절되는 run이 최대 120초(scan
timeout) 늦게 끝난다. scan이 정책 파일을 못 읽어 죽으면 이제 승인이
돌지 않는다(전에도 gate는 실패했다). FE-GATE-015가 실패한 run에는 여전히
기록이 없다. 실제 runner의 upload가 없는 파일을 건너뛰는지는 미확인이다.
제품이 `config/ci/contract-baseline.json`을 자기 값으로 다시 적어 두었다면
받은 뒤 다시 적어야 한다. 새 digest는 jq로 계산했다. 같은 계산이 바꾸기
전 기준선(7bebafe6…)을 그대로 재현했다.

검증: desktop batch에서 확인.
`node scripts/run-vitest.ts run tests/system/ci-runner/ci-evidence-freshness.test.ts tests/unit/dependency-advisories.test.ts`
— 새 "writes the advisory record when the release admission refuses the
candidate"와 바꾼 "runs before the release admission (FE-GATE-027) ..."가
수정 전 계약에서 실패하고 수정 뒤 통과한다. `check:ci`, 13-R1 C.

Refs: 1106/13-01
2026-11-06 05:18:09 +09:00
DongHyeonka 2a78169c58 fix(hosting): live probe가 redirect된 워커 스크립트를 거절한다
문제
워커를 싣는 빌드에서 live probe는 `/service-worker.js`를 기본 fetcher
`redirect: "follow"`로 받고, 최종 응답의 status와 origin만 본다
(`scripts/lib/hosting-probe.ts` `probeLiveRelease`). 같은 origin 안
redirect 뒤에 200·`no-cache`·JS MIME이 오면 FE-GATE-019가 PASS다.
브라우저는 워커 스크립트를 redirect mode "error"로 받는다(Service
Worker Update 알고리즘). 그런 호스트에서는 첫 등록, update 검사,
`REMOVE_REGISTRATION` kill switch가 모두 실패한다.

고른 방법과 버린 대안
- `serviceWorker` surface에만 `redirect` 행을 더한다.
  `response.redirected`이거나 `opaqueredirect`이면 FAIL이다. 자산
  probe(1105/06-02)와 같은 판정식이라 fetcher가 redirect를 따라가든
  manual이든 잡는다. 3xx 응답은 지금처럼 `http-status` 행이 FAIL로 본다.
- redirect가 없으면 이 행은 PASS로 남는다. 산출물에 이 검사를 했다는
  기록이 된다.
- 버린 대안: 모든 surface에서 redirect를 FAIL로 보기(리뷰 (b)).
  `index`·`appRoute`의 정상 redirect(끝 슬래시 정규화 등)까지 막는다.
  문서에만 적기(리뷰 (c))는 게이트가 그대로 PASS다.
- 운영 문서 두 곳에 "redirect 없이"를 적었다. release-cache-rollback.md의
  live probe 설명과 browser-file-storage-recovery.md의 kill switch
  전제다.

위험·한계
- 워커 스크립트를 redirect하던 호스트는 이제 FE-GATE-019에서 FAIL이다.
  그런 호스트에서는 지금도 워커가 동작하지 않는다.
- 브라우저 거절은 명세와 Chromium 오류 문구에 기댄 것이다. redirect하는
  호스트로 실제 등록을 돌려 보지 않았고, live 모드도 실제 호스트로 돌리지
  않았다(리뷰 §5 미검증 그대로).

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "live hosting probe (1105/06-02) > fails a worker script the host
  answers only after a same-origin redirect"가 실패한다. 옛 probe에는
  redirect 행이 없어 실패 행이 비어 있다.
- 함께: check:types, lint, verify:documentation

Refs: 1106/06-01
2026-11-06 05:17:04 +09:00
DongHyeonka 287dc6fa9b build(perf): 초기 JS 예산을 202 KiB로 올린다
문제: 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
2026-11-06 02:59:03 +09:00
DongHyeonka 1c4e57c0ca docs(operations): 남은 FEATURE_OVERRIDES 키가 경고를 남긴다고 적는다
문제
ci-quality-gates.md의 기준선 표는 지운 기능의 FEATURE_OVERRIDES 키가
"조용히 무시된다"고 적는다. 코드는 그 키를 무시하지만 조용하지 않다.
check:release-admission(FE-GATE-027)이 `release admission warning:
FEATURE_OVERRIDES.<id> … the override does nothing`을 내고
(scripts/check-release-admission.ts), 부팅이 진단 feature.override.unknown
(warn)을 남긴다(src/bootstrap/runtime-adapters.ts). 운영자는 경고를 오류로
오해하거나, 문서대로 아무 신호도 없다고 생각한다(0929/14-05).

고른 방법
- 표의 "검사 위치" 칸을 코드대로 고쳤다: 실패하는 검사는 없고, 두 곳이
  경고를 남긴다.

위험·한계
- 문서만 바꿨다. 경고 문구가 바뀌면 이 칸도 고친다(문서 검사는 문구를
  대조하지 않는다).

검증
- desktop batch에서 확인: corepack pnpm verify:documentation

Refs: 0929/14-05
2026-11-06 02:59:02 +09:00
DongHyeonka 1dda18da30 fix(docs): 참조 기능 경로를 다시 백틱으로 적어 문서 검사가 본다
문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.

고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
  README, starter-experience, static-delivery, compatibility,
  backend-api-and-server-state-contract, manual-checklist,
  adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
  참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
  적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
  1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
  지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
  measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
  안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
  위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
  and scripts only where verify:documentation checks them"을 더했다. 검사기가
  읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
  기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
  같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
  커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
  검사기와 같은 규칙을 두 곳에 두게 된다.

위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
  백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
  아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/template-feature-removal-documents.test.ts
  tests/unit/documentation-readiness.test.ts, corepack pnpm
  verify:documentation, corepack pnpm test:sample-removal

Refs: 1105/14-03
2026-11-06 02:59:02 +09:00
DongHyeonka b8d53c9aae chore(review): 1105 성능·구조 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 둘.
- 1105/12-04(실행 격리 브랜치)는 `vite.config.ts`가
  `scripts/lib/run-isolation.ts`를 가져오게 해, 저장소를 임시 루트에 복사해
  빌드하는 두 목록(`scripts/scale/measure-feature-shape-growth.ts`,
  `tests/unit/product-feature-selection-build.test.ts`)에 그 파일을 더했다.
  1105/15-03(이 브랜치)은 두 목록을 `scripts/lib/vite-build-inputs.ts` 하나로
  옮겼다. 두 파일의 충돌은 15-03 쪽으로 풀고, 옮긴 목록에
  `scripts/lib/run-isolation.ts`를 더한다. 더하지 않으면
  `tests/unit/vite-build-inputs.test.ts`가 그 파일 이름을 대며 실패하고,
  임시 루트 빌드 두 곳이 "Could not resolve './scripts/lib/run-isolation.ts'"로
  실패한다.
- `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 03-01(HTTP 판정
  브랜치)과 16-01(이 브랜치)이 각자 한 줄씩 더했다. 두 줄을 모두 둔다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts

Refs: 1105/12-04, 1105/15-03, 1105/03-01, 1105/16-01
2026-11-06 02:59:02 +09:00
DongHyeonka 703a33559f chore(review): 1105 가드레일·CI 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka 57c34ea626 chore(review): 1105 realtime·Service Worker 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 7af80859e5 chore(review): 1105 브라우저 파일·캐시·저장소 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 19d10538d6 chore(review): 1105 HTTP 판정·폼 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 683ccfb56b fix(query): 키 없는 결과 불명 요청의 같은 입력 재제출을 훅이 막는다
문제
0929/03-03은 화면 버튼 쪽만 고쳐졌다. 남은 길이 둘이다.
- useApplicationMutation의 submit은 같은 canonical input의 결과 불명
  admission을 찾아 그 intent를 그대로 다시 보낸다. 키 없는 intent(NEVER)면
  서버가 가려낼 수 없는 두 번째 요청이다. 막는 곳은 폼(unknownSubmissionRef)과
  두 페이지의 버튼·onSubmit 검사뿐이라, 폼 밖에서 submit을 부르는 화면은 같은
  항목을 둘 만들 수 있다(리뷰 실험 X1: 재전송은 null인데 같은 입력 submit이
  두 번째 POST를 보냈고 keys=[null,null]).
- AsyncSurface는 state.unknownEffectResendable !== false일 때 재전송 버튼을
  그린다. 코디네이터 없이 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을
  그린다(실험 X3).

고른 방법
- submit이 같은 입력의 결과 불명 admission을 찾았는데 그 intent에 키가 없으면
  보내지 않고 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를
  돌려준다. admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다.
  KEYED의 같은 키 재전송, 입력이 바뀐 새 요청은 바뀌지 않는다. LEGACY(테스트
  하네스) 경로는 intent가 없어 replay 자체가 없으므로 영향이 없다.
- AsyncSurface는 unknownEffectResendable === true일 때만 재전송 버튼을 그린다.
  코디네이터의 state는 늘 이 값을 싣는다(canResendUnknownEffect).
- 기존 async-surface 테스트 "renders unknown mutation effects with
  confirm-applied and resend only"는 플래그 없는 상태로 버튼을 기대했다. 이
  수정의 의도대로 isUnknownEffectResendable: true를 입력에 적었다. 단언은 그대로다.
- 런북 6.3-4와 매뉴얼 01에 키 없는 재제출과 손으로 만든 상태를 적었다.

버린 대안
FailureKind에 새 kind를 더한다: 닫힌 레지스트리를 넓히는 계약 변경이다.
"같은 논리 요청이 아직 끝나지 않았다"는 DUPLICATE_IN_FLIGHT(action none)로
충분하다.

위험·한계
- 다운스트림이 AsyncSurface에 손으로 만든 결과 불명 상태와 onResendUnknownEffect를
  넘기던 화면은 재전송 버튼이 사라진다. 코디네이터의 state를 넘기면 그대로다.
- 결과 불명 admission은 메모리에만 있다. 새로고침 뒤 같은 입력은 막지 못한다
  (런북 6.3-7의 한계 그대로).

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx
tests/component/async-surface.test.tsx tests/component/application-query.test.tsx

Refs: 0929/03-03
2026-11-06 02:33:16 +09:00
DongHyeonka 81701add7e feat(perf): lab이 기능 라우트 첫 진입을 재고 500 ms 예산으로 판정한다
문제: lab(FE-GATE-026)은 플랫폼 구성 화면(EXAMPLES_PLATFORM) 하나만 잰다.
이 화면은 기능 코드를 받지 않아 기능을 더해도 수치가 거의 그대로다
(146 → 154 ms). 기능 라우트는 처음 들어갈 때 context 라우트 모듈과 기능
실행부를 받고, 그다음 페이지 청크를 받는 두 번의 요청 묶음을 거친다.
lab 조건에서 EXAMPLES_UI 첫 진입은 중앙값 406 ms(403~410, 리뷰 15-R1)로
대상 화면의 2.7배인데 어느 게이트도 재지 않는다. 다운스트림의 화면은
모두 기능 라우트다.

고른 방법:
- labFeatureRoute(scripts/lib/lab-performance.ts): 설치된 기능이 가진,
  세션 없이 열리는 첫 내비게이션 라우트. 템플릿에서는 EXAMPLES_UI다.
  없으면 null이고 lab은 measured: false로 남기고 판정하지 않는다.
- lab은 run마다 `/`에서 그 라우트의 내비게이션 링크를 눌러 heading까지를
  같은 페이지 시계로 잰다(새 cold context). metrics.featureRouteInteractionMs
  (중앙값), context.sampling.featureRoute(표본, owner)에 남긴다. 기존 대상
  라우트와 그 예산(200 ms)은 그대로라 회귀 비교가 이어진다.
- 예산 config/performance/budgets.json lab.featureRouteInteractionMs = 500 ms.
  측정 406 ms(8a44226, i5-10400F, lab 조건)를 통과시키고, 지금 둘째 요청
  묶음 크기(약 100 ms, 클릭 뒤 98~204 ms)의 왕복이 하나 더 붙으면 넘는다.
  lab 자가 검사 fixture에 feature-route-over-threshold를 더해 이 예산이
  실패할 수 있음을 매번 확인한다.
- 단위 테스트: 라우트 선택 규칙, 설치된 레지스트리에서의 선택, 커밋된
  예산이 406 ms는 통과·516 ms는 실패·null은 판정 제외.
버린 대안:
- 두 요청 묶음을 하나로 줄이기(진입한 URL의 페이지 청크를 context 라우트
  모듈과 같이 받기): 페이지 청크 이름이 context 라우트 모듈 안의 lazy()에만
  있어, 첫 묶음에서 받으려면 초기 청크의 라우트 선언이 페이지 로더를 가져야
  한다. 선언 모양·생성기·초기 JS를 바꾸는 일이라 이 커밋에서 하지 않았다
  (결정 대기, performance-evidence.md에 적음).
- 처음에는 기록만 하기: 기록만 하면 늘어도 아무도 모른다. 측정값이 있으니
  예산을 같이 둔다.
- 라우트별 예산 표: 다운스트림이 채워야 하는 표가 는다.

위험·한계: 예산 여유가 94 ms(23%)라 lab 호스트가 지금보다 20% 이상 느리면
기능 라우트 판정이 흔들릴 수 있다(0929/11-04 lab 부하 가드는 여전히 없음).
FE-GATE-026 시간이 run마다 cold navigation 하나(약 2~3초) 늘어 5회면
+10~15초다. 생성 기능의 목록 라우트는 session-required라 lab 대상이 되지
않는다. 기능 라우트의 heading은 계약 `title`과 같은 글자로 찾는다(대상
라우트와 같은 방식). CHANGELOG의 "기능 라우트 첫 진입은 어느 게이트도
재지 않는다" 제한 문장은 이 커밋에서 고치지 않았다(오케스트레이터 몫).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts
tests/unit/performance-budgets.test.ts
corepack pnpm build && corepack pnpm test:performance -- --runs=5
(featureRoute EXAMPLES_UI 중앙값이 500 ms 안인지, 표본 기록)

Refs: 1105/15-04
2026-11-06 01:23:48 +09:00
DongHyeonka 138c195fcd fix(examples): 릴리스 신원 칸의 자리를 미리 잡고 lab이 대상 화면 직접 진입 CLS를 잰다
문제: 플랫폼 구성 화면(lab 대상)은 getReleaseSummary()가 끝날 때까지
릴리스 신원 칸을 "상태" 한 칸으로 그리고, 끝나면 hint 줄이 있는 네 칸으로
바꾼다. 제목이 보인 뒤 약 30~100 ms에 grid가 hint 한 줄만큼 커져 아래
section이 21 px 내려간다(layout shift 0.00461, 리뷰 15-platform-shift
16회). lab은 `/`에서 클릭으로만 들어가고, 클릭 뒤 500 ms 안의 shift는
hadRecentInput이라 CLS에서 빠지므로 0을 낸다. `/` 밖의 라우트 CLS는 어느
게이트도 보지 않는다.

고른 방법:
- 화면: 요약 전·실패 때도 같은 네 칸(빌드·릴리스·설정 스키마·계약 집합
  다이제스트)을 같은 hint 줄 구성으로 그린다. 값만 "확인하고 있습니다."
  / "확인하지 못했습니다." / "—"다. 상태 문장은 가장 좁은 칸(13rem)에서도
  한 줄이 되게 짧게 했다. dl에 aria-busy를 둔다. 시각 테스트는 이미
  `main [aria-busy='true']`가 0개가 될 때까지 기다리므로, dt만 보고 찍던
  대기가 값이 채워진 뒤로 유지된다.
- lab: run마다 대상 라우트를 새 context에서 직접 열고 heading 뒤 network
  idle까지의 CLS를 잰다(metrics.targetDeepLinkCls, 중앙값,
  context.sampling.targetDeepLink에 표본). evaluateLabBudget가 lab.cls
  임계값으로 판정한다. 클릭 시계(상호작용 중앙값)와 대상 라우트는 그대로다.
- 컴포넌트 테스트: 요약 전과 후의 칸 이름·hint 유무가 같다. 실패 테스트는
  빌드 칸의 값으로 본다. 단위 테스트: 직접 진입 CLS가 임계값을 넘으면
  lab 판정이 실패한다.
버린 대안: 릴리스 요약을 동기로 읽기 — getReleaseSummary()가 비동기
포트 계약이라 포트를 바꿔야 한다. 클릭 run에서 hadRecentInput을 무시 —
CLS 정의와 달라져 field 값과 비교할 수 없다.

위험·한계: lab 시간이 run마다 cold navigation 하나(lab 조건 약 2~3초)
늘어 5회면 +10~15초다. 직접 진입 CLS 예산은 0.1이라 0.0046 같은 작은
shift는 실패시키지 않고 lab.json에 값으로만 남는다. layout shift 0건은
lab 값(0)과 15-platform-shift 방법으로 확인해야 한다. 상태 문구가 바뀌어
"런타임 정보를 확인하고 있습니다." 문장은 이 화면에서 사라졌다(홈 화면
문구는 그대로). lab.json 스키마 문서(config/schemas/lab-performance.schema.json)에
새 칸을 필수로 더했다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/component/starter-platform-overview-page.test.tsx
tests/unit/performance-budgets.test.ts
corepack pnpm build && corepack pnpm test:performance -- --runs=5
(lab.json metrics.targetDeepLinkCls가 0인지)

Refs: 1105/15-01
2026-11-06 01:23:48 +09:00
DongHyeonka e02f252d57 fix(theme): 스크롤바 자리를 첫 화면부터 잡고 lab을 스크롤바와 함께 잰다
문제: 라우트 로딩 화면(280 px)은 720 px 창에 들고 홈 화면(732 px 문서)은
넘친다. 일반(overlay가 아닌) 스크롤바를 쓰는 브라우저에서 홈이 그려지는
프레임에 세로 스크롤바가 생겨 너비가 15 px 줄고 header 오른쪽(세션 영역)이
15 px 밀린다(1280x720·1366x657에서 CLS 0.0002, 리뷰 15-R2 12회). lab과 모든
게이트의 Playwright Chromium은 --hide-scrollbars로 떠서 이 shift를 못 본다.

고른 방법:
- base.css의 :root에 scrollbar-gutter: stable을 둔다. 스크롤바 자리가
  첫 프레임부터 있어 내용이 길어져도 너비가 바뀌지 않는다. overlay
  스크롤바(macOS 기본)는 어느 쪽이든 자리를 쓰지 않는다.
- lab(scripts/test-performance.ts)은 labBrowserLaunchOptions()로
  --hide-scrollbars를 빼고 띄운다. lab.json context.browser에
  scrollbars: "visible"을 남긴다. 이제 lab의 `/` CLS가 같은 회귀를 본다.
- 단위 테스트: 실행 옵션이 --hide-scrollbars를 빼는지, :root에
  scrollbar-gutter: stable이 있는지.
- 시각 골든 5장을 새 gutter에 맞춰 desktop에서 다시 찍는다
  (test:visual:update).
버린 대안: html { overflow-y: scroll } — 짧은 화면에도 빈 스크롤바를
그린다.

위험·한계: 스크롤바 폭만큼 오른쪽 여백이 짧은 화면에서도 늘 생긴다.
--hide-scrollbars로 뜬 Chromium도 gutter 자리를 잡는다. 그래서 시각 골든
5장이 모두 바뀌었다. 바뀐 것은 내용 폭 15 px다(main 1040 → 1025 px).
compact(390 px) 골든은 줄바꿈이 늘어 1297 → 1377 px로 길어졌다. 실제
휴대폰은 overlay 스크롤바라 자리를 쓰지 않으므로, compact 골든은 휴대폰
화면보다 15 px 좁게 그린다. 열린 drawer의 가림막은 gutter를 덮지 않는다
(일반 스크롤바 브라우저에서는 그 자리에 스크롤바가 그려진다). lab의 CLS 예산
0.1은 그대로라 0.0002 shift가 다시 생겨도 lab은 통과한다(값만 남는다).
Firefox·Windows 스크롤바 폭은 재지 않았다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts
corepack pnpm test:visual (부모 d5b6aeba에서 6건 통과, 이 변경은 옛
골든과 5건이 달라 실패, 다시 찍은 골든에서 통과)
corepack pnpm build && corepack pnpm test:performance -- --runs=5

Refs: 1105/15-05
2026-11-06 01:23:48 +09:00
DongHyeonka 46359a1c79 fix(scale): 초기 JS 기록 대조의 합계 허용 오차를 256 B로 둔다
문제: initialJavascriptRecordDrift가 합계를 1%까지 같다고 본다.
202,927 B에서 1%는 2,029 B로, 남은 여유 1,873 B와 기능 하나(768 B)보다
크다. 템플릿 변경이 여유를 다 써도 기록을 다시 쓰지 않은 채 test:unit을
통과하고, 기록을 인용한 문서는 없는 여유를 말한다. 단위 테스트는 1,500 B
차이를 "같음"으로 고정했다.

고른 방법: 합계만 바이트 상한 256 B(INITIAL_JAVASCRIPT_RECORD_TOLERANCE_BYTES)로
바꾼다. build id 차이(기록된 실행 사이 6 B, 48 B)는 넘고 기능 하나보다는
작다. 기능·context 비용(10%)과 파일 수(정확)는 그대로다. 단위 테스트는
48 B·200 B 차이는 통과, 300 B 증가와 1,500 B 차이는 실패로 고정한다.
performance-evidence.md의 "합계 1% 초과" 문장을 고쳤다.
버린 대안: 여유 자체를 기록해 대조 — 예산이 바뀔 때마다 같이 바뀌어
더 쉽게 낡는다.

위험·한계: 초기 JS를 수백 바이트 움직이는 템플릿 변경마다 기록을 다시
써야 한다(의도). CI와 로컬의 build id 차이가 256 B를 넘는 일이 생기면
test:unit이 흔들린다. 지금까지 본 차이는 50 B 안이다. 이 커밋은 기록
숫자를 바꾸지 않는다. 현재 기록과 빌드의 차이는 0 B였다(리뷰 15-lab).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts

Refs: 1105/15-02
2026-11-06 01:23:48 +09:00