Commit Graph
716 Commits
Author SHA1 Message Date
DongHyeonka aff267db76 fix(scripts): 기능 제거 드릴의 src 잔여물 검사가 이름 단위로 찾는다
문제: 제거 드릴(`test:sample-removal -- --feature=<id>`)의 잔여물 검사는
`src`의 경로와 본문을 대소문자 무시 부분 문자열로 찾는다. 그래서 합법
ID `product-feature`를 지우면 템플릿 파일 열 개(`product-features.ts`,
`product-features-port.ts`와 그것을 가져오는 파일들)와 템플릿 시험 이름
여섯(`product-feature-switch.test.tsx` 등)이 잔여물로 잡혀 드릴이
실패한다. 매뉴얼 예시 ID `invoice-feature`는 걸리지 않아 남아 있었다.

고른 방법: spec 본문에 이미 쓰는 규칙에 맞춘다. 본문은 이름 단위
(대소문자 구분, 앞뒤에 `[A-Za-z0-9_-]` 없음), 경로는 세그먼트가 이름과
같거나 그 첫 `.` 앞부분이 같을 때만 센다. `src/.generated/`는 기능 목록에서
다시 만드는 파생물이라 뺀다.
- 버린 대안: 「파일 이름이 ID로 시작」. 템플릿의 `product-feature-*` 시험
  이름이 그대로 걸린다.

위험·한계: 한 단어 ID(`search` 등)는 템플릿 본문에 보통 낱말로 있어 여전히
잡힐 수 있다. 본문 규칙으로는 자료와 참조를 가릴 수 없다(spec은 한 단어
이름을 아예 보지 않는다).

검증(desktop): 구현을 main으로 되돌린 상태에서 새 시험 2개 실패(RED),
고친 뒤 feature-residue·feature-removal-argument 11개 통과, eslint·
check:types rc=0. 로그 /tmp/claude-gates/w2fe2-res1/.

Refs: 1105/16-04
2026-11-13 04:57:04 +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 c6d7f43ab9 perf(e2e): fixture build를 브라우저 project마다가 아니라 run에 한 번 만든다
문제: fixture spec 여섯(old-tab-chunk-recovery, generated-feature,
preload-use, boot-module-failure, service-worker-update·recovery)이
beforeAll에서 저장소를 복사해 vite build를 동기로 돈다. chromium·
firefox·webkit project가 그 hook을 따로 돌아, e2e 한 번에 같은 build를
세 번(약 9 build × 3) 만든다. 그 build는 옆 worker의 브라우저와 CPU를
다툰다. FE-GATE-008이 가끔 떨어진 firefox 시험(runner run 127,
desktop p5·fea-v8: `old-tab-chunk-recovery`·`app-shell`·`accessibility`의
첫 goto 뒤 요소 없음)은 이 build가 도는 구간과 겹쳤다. 다만 아래
6회 실행에서 고치기 전·후 모두 재현되지 않아, 이것이 원인이라고는
확정하지 못했다.

고른 방법: e2e 설정의 global setup이 run마다 공유 폴더를 만들고
(`SHARED_FIXTURE_BUILD_ROOT`), `prepareFixtureBuilds`와
`prepareServiceWorkerBuilds`가 key마다 처음 닿은 worker만 build한다.
나머지 worker는 그 결과를 기다려 쓴다(`mkdir` 잠금, 결과 JSON을
rename으로 공개, 실패는 `.failed`로 전한다). 같은 key를 다른 정의로
부르면 거절한다. build는 엔진과 무관하고 시험이 build 폴더에 쓰는
곳은 없다(edit는 build 전에만 돈다). global teardown이 폴더를 지운다.
- old-tab spec은 edit 안에서 정하던 기능 목록을 build 뒤에 root에서도
  읽는다. 다른 project의 build를 쓴 worker는 edit를 돌지 않는다.
- 공유 폴더가 없으면(Vitest 시험, 다른 Playwright 설정) 예전처럼
  호출마다 자기 사본을 만든다.
- 버린 대안: expect timeout 늘리기·worker 줄이기(규칙 밖), fixture
  spec을 한 브라우저만 돌리기(브라우저별 계약이 줄어든다).

위험·한계: build를 기다리는 worker는 자기 hook timeout(180~300초)
안에서 기다린다. build한 worker가 죽으면 기다리는 쪽은 그 timeout으로
실패한다. 2026-11-01 리뷰의 R-1(두 helper 중복 정리)은 하지 않았다.

검증(desktop, `taskset -c 0-5` + worker 6으로 runner 모양, 같은 세션에서
고치기 전·후 번갈아 3회): e2e 전체 벽시계 172/150/141 → 123/141/113초
(중앙값 150 → 123초), 6회 모두 183개 통과. 공유 시험 6개 통과,
check:types·eslint rc=0. 로그 /tmp/claude-gates/w2fe2-e2eab/,
w2fe2-shared1/.
2026-11-12 23:19:43 +09:00
DongHyeonka 0c3c9d3351 fix(coverage): 위험 커버리지가 "use strict" 밖의 지시문을 문장으로 센다
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-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (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-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 / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / checker self-tests (pull_request) Canceled after 0s
문제: 0bb1f0af에서 모듈을 Babel AST로 읽게 바꾼 뒤, 파일 맨 위의
지시문(`"use client";`)을 세지 않는다. Babel은 지시문을
`program.directives`에 두고 `body`에 넣지 않는다(ESTree 변환은 body에
넣었다). V8 coverage는 `"use client"`를 문장 1개로 세고 `"use strict"`는
세지 않는다(desktop에서 실제 V8 실행으로 확인). 그래서 지시문과 타입만
있는 모듈이 counterless로 분류되고 coverage에는 문장이 잡혀, 파생
프로젝트에서 risk-coverage가 거짓으로 실패한다. 지금 `src/`에는
지시문이 없어 375개 대조에서 보이지 않았다. 새 눈 리뷰(fe-testing
렌즈)가 찾았다.

고른 방법: `"use strict"`가 아닌 지시문이 있으면 counter-bearing이다.
check:v8-coverage-counter-semantics의 fixture에 지시문 모듈 둘
(`use client`는 counter-bearing, `use strict`는 counterless)을 더해,
분류기가 기대는 V8 동작을 실제 실행으로 고정한다. risk-coverage 시험도
같은 두 모듈을 분류한다.

위험·한계: 예전 분류(ESTree)는 `"use strict"`만 있는 모듈을
counter-bearing으로 봤다. 이제 V8과 같이 counterless다.

검증(desktop): risk-coverage·risk-coverage-files·counter-semantics 시험
통과, check:v8-coverage-counter-semantics PASS(2 counter-bearing,
8 counterless), check:types·eslint rc=0. 변이: 지시문 규칙을 빼면
「matches the observed V8 counterless …」가 `directive-use-client.ts`를
counterless로 받아 실패. 로그 /tmp/claude-gates/w2fe2-dir1·2·4/.

Fixes: 0bb1f0afc0 ("perf(coverage): 위험 커버리지 모듈 목록을 Babel 파서와 동기 fs로 만든다")
2026-11-12 22:45:48 +09:00
DongHyeonka 37a850040d test(http): deadline 분류 시험이 대기 지점에서 가짜 시계로 deadline을 낸다
문제: 「times out at the <phase> wait when the deadline fires」가 실제
시계로 30ms deadline을 잡는다. 전송 실패(transport backoff)나 503
(retry backoff)을 처리하는 시점에 이미 30ms가 지났으면 실행기는
backoff할 시간이 없다고 보고 그 실패로 끝낸다(`remaining() > 0`이
거짓). 그래서 기대한 TIMEOUT 대신 NETWORK_FAILURE·503 결과가 나온다.
desktop 부하 31에서 한 번 떨어졌다(PR #19 W2-FE 기록 F).

고른 방법: deadline 경우만 가짜 시계(`vi.useFakeTimers`)로 돌고, 그
대기에 닿은 것을 확인한 뒤 30ms를 진행한다. 시험이 보려는 것(대기
중에 deadline이 나면 DEADLINE·TIMEOUT)을 그대로 보고 기계 속도에는
기대지 않는다. 두 backoff 단계는 답하기 전에 실제 시간 40ms를 멈춘다
(`Atomics.wait`). 실제 시계로 되돌리면 이 시험이 매번 실패한다.
- 버린 대안: deadline을 늘리기. 경쟁이 남고 규칙 밖이다.
- 버린 대안: `vi.waitFor`로 기다리기. 가짜 시계에서는 확인할 때마다
  시계를 진행해 대기에 닿기 전에 deadline이 날 수 있다.

위험·한계: 실행기 동작은 바꾸지 않았다. deadline이 이미 지난 뒤
도착한 전송 실패를 NETWORK_FAILURE로 보고하는 것이 맞는지는 이
커밋이 정하지 않는다.

검증(desktop): 시험 파일 72개 3회 연속 통과. 변이: 가짜 시계를 빼고
실제 30ms deadline에 같은 40ms 멈춤을 두면 transport backoff·retry
backoff 둘이 매번 실패(나머지 넷 통과). eslint·check:types rc=0.
로그 /tmp/claude-gates/w2fe2-http1·2/.
2026-11-12 22:26:17 +09:00
DongHyeonka 198e9856f6 test(schemas): 스키마 생성 시험이 fsync 없는 writer로 임시 폴더에 쓴다
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 / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / checker self-tests (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-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (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
문제: json-schema 시험 「generates deterministic … detects drift」가
임시 폴더에 스키마 넷을 쓸 때 파일과 폴더를 fsync한다. 이 시험의
대부분이 fsync이고, 디스크가 바쁘면 시간이 크게 뛴다(desktop
89~1,075ms, CPU를 제한한 coverage 측정에서 7.4초). 이 시험은 생성한
바이트와 drift 판정을 보고, 내구성은 validated-json-artifact 시험이
본다. 기본 timeout 10초 아래라 자기 timeout도 없다.

고른 방법: `generateArtifactSchemas`가 writer를 받는다(기본은 지금의
`writeValidatedJsonArtifact`). 시험은 같은 검증·원자적 rename writer를
`createValidatedJsonArtifactWriter`로 만들고 sync만 뺀다.
- 버린 대안: 시험에 timeout 선언. 시간을 줄이지 않고 흔들림을 덮는다.

위험·한계: 생성 명령과 check:artifact-schemas의 쓰기는 그대로다.

검증(desktop, 고치기 전·후 번갈아 3회, 부하 11~16): 89/1,075/98 →
36/48/35ms. coverage + CPU 소모 12개에서도 208~519 → 73~151ms. 시험
통과, check:artifact-schemas rc=0, check:types·eslint rc=0. 로그
/tmp/claude-gates/w2fe2-slow2·6/.
2026-11-12 22:17:32 +09:00
DongHyeonka 543518ad2a fix(coverage): coverage 대상 패턴을 저장소 루트에 고정한다
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-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (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-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 / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / checker self-tests (pull_request) Canceled after 0s
문제: vitest는 coverage include·exclude를 모듈의 절대 경로에 picomatch
`contains: true`로 맞춘다. 그래서 `src/**/*.{ts,tsx}`가 경로 어디에서나
맞는다. checkout이 이름이 `src`로 끝나는 폴더(`~/work/app-src/`)에
있으면 `vite.config.ts`·`scripts/**` 같은 루트 파일이 coverage에 들어가
risk-coverage가 저장소 목록 밖의 행으로 실패한다(tech-log 동기화 때
desktop에서 본 일). CI 경로에는 `src`가 없어 runner에서는 안 보였다.

고른 방법: `scripts/lib/coverage-scope.ts`의 `rootAnchoredGlobs`가
패턴 앞에 루트를 붙인다. 루트는 vitest의 glob 라이브러리(tinyglobby
0.2)가 cwd를 escape하는 식 그대로 escape해, 괄호 같은 glob 문자가 든
루트도 자기 자신에만 맞고 안 불린 파일 glob도 `src/...`로 풀린다.
`vitest.config.ts`와 `check:v8-coverage-counter-semantics`의 자식
설정이 이 함수를 쓴다.
- 막는 시험: counter-semantics 검사가 fixture를
  `checkout (copy)-src/` 아래로 복사하고, fixture 시험이 `src/` 밖
  모듈(`outside-src.ts`)도 불러온다. 고정이 빠지면 그 모듈이 행으로
  들어와 행 집합 검사가 실패한다. 이 검사는 test:coverage 첫 단계에서
  이미 자식 vitest를 띄우므로 프로세스가 늘지 않는다. 단위 시험은
  repo 설정의 모든 패턴이 루트로 시작하는지와 escape를 본다.
- 버린 대안: picomatch로 vitest의 판정을 흉내 내는 단위 시험. 직접
  의존성이 아니고, vitest가 옵션을 바꾸면 거짓 통과한다.

위험·한계: Windows 루트는 `/`로 바꾼 뒤 같은 식으로 escape한다.
올바른 Windows 경로에서는 tinyglobby의 Windows escape와 결과가 같다고
보았지만 Windows에서 돌려 보지는 않았다.

검증(desktop): coverage-scope·v8-coverage-counter-semantics 시험 통과,
check:v8-coverage-counter-semantics rc=0. 변이: 자식 설정을 예전
`["src/**/*.ts"]`로 되돌리면 같은 검사가 `additional: outside-src.ts`로
rc=1. check:types·eslint rc=0. 로그 /tmp/claude-gates/w2fe2-cov1/.
2026-11-12 22:03:08 +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 f90ffb6c9a fix(tests): provider 기준 사본이 .claude 아래 추적 파일을 함께 복사한다
문제: tests/system의 provider 기준 사본은 `.git`을 함께 복사하면서
`.claude` 폴더를 통째로 뺀다(노트북 checkout의 `.claude/worktrees/`를
피하려고). 2026-11-08 하네스가 `.claude/` 아래에 agents·rules·skills를
추적 파일로 더한 뒤로, 사본의 `git ls-files`가 그 파일을 말하는데 디스크에
없어 공급망 생성이 `ENOENT ... .claude/agents/arch-reviewer.md`로 멈춘다.
FE-GATE-013이 어디서도 끝까지 돈 적이 없어(runner는 사전 점검, desktop은
userns에서 멈춤) 드러나지 않았다. 시스템 컨테이너에서 처음 끝까지 돌자
provider 시험 18개가 이것으로 실패했다.

고른 방법: 빼는 것을 저장소 루트 기준 경로로 바꾸고 `.claude` 대신
`.claude/worktrees`만 뺀다. `.git`을 복사하지 않는 다른 빌드 사본
(e2e fixture-builds·service-worker-builds, run-output-root-build)은
그대로 둔다.

위험·한계: 다른 checkout을 품는 새 폴더가 생기면 이 목록에 더해야 한다.

검증: desktop 묶음(w2fe-p4)에서 scripts/verify.sh gate FE-GATE-013.
2026-11-12 19:51:54 +09:00
DongHyeonka 35b60a049a fix(tests): 드릴 경로 시험이 선택 recipe를 지운 사본에서도 통과한다
문제: b4210753이 더한 removal-drill-test-paths 시험과 고친
feature-scaffold-drill 시험이 test:recipes가 있다고 가정한다. FE-GATE-020의
optional-recipe-removal 드릴은 recipe를 지운 사본에서 test:all을 돌고,
그 사본의 package.json에는 test:recipes가 없어 두 시험이 실패한다
(desktop merge 단계, 2d3e5889).

고른 방법: 드릴 코드(scripts/test-sample-removal.ts)처럼 사본의
package.json에 남은 suite만 「coverage 밖」으로 본다. scaffold 드릴 시험의
기대 목록에서는 test:recipes를 뺀다(그 드릴의 다른 기대처럼 사본에 늘
있는 명령만 둔다).

위험·한계: test:recipes가 없는 사본에서는 「coverage 밖 suite」 시험이
아무것도 보지 않는다. 그 사본은 그 경로 자체가 없다.

검증: desktop 묶음(w2fe-p4)의 test:optional-recipe-removal과 merge 단계.
2026-11-12 19:51:54 +09:00
DongHyeonka db4c632d53 test(archive): 다른 시험이 쓰는 중인 임시 파일은 사본에 복사하지 않는다
tests/integration/security-followup-archive.test.ts는 후보 빌드에 쓸
증거를 얻으려고 checkout의 artifacts/를 통째로 사본에 복사한다. 같은
integration 실행에서 tests/integration/http-scenario-catalog.test.ts가
artifacts/tests/http-scenario-executions.json을 임시 파일에 쓰고
rename한다. 복사가 목록을 읽은 뒤 그 임시 파일이 rename되면 ENOENT로
실패한다. desktop FE-GATE-007(2026-11-12, load 9)에서 났다.

복사 filter가 원자적 쓰기의 임시 파일(.<이름>.<무작위>.tmp)을 건너뛴다.
그런 파일은 쓰는 중이라 증거가 아니다. fs.cp는 filter를 stat보다 먼저
부르므로, 건너뛴 파일은 사라져도 오류가 없다.

버린 것:
- 필요한 증거 경로만 복사: 공급망 생성이 추적 파일(artifacts의 .gitkeep
  포함)을 모두 lstat하고 build가 읽는 증거가 여러 곳이라, 목록을 따로
  관리해야 한다.
- 두 시험을 같이 돌지 않게 하기: integration 층 전체를 직렬로 돌려야 한다.

위험: 임시 파일이 아닌 파일을 다른 시험이 지우는 경합은 남는다. 지금
artifacts/ 아래에서 그렇게 하는 시험은 찾지 못했다.

검증(desktop):
- 다른 프로세스가 artifacts/tests에 임시 파일 10개를 계속 만들고
  rename하는 동안 이 시험을 돌렸다. main 6b4f703c는 3회 중 2회가 같은
  ENOENT(.tmp)로 실패했고, 이 커밋은 3회 모두 통과했다.
- test:unit, check:types, check:ci, lint, verify:documentation.
2026-11-12 11:43:08 +09:00
DongHyeonka 77c01b03c1 test(guardian): lease가 시험 대상이 아니면 시험 timeout만큼 준다
tests/integration/provider-guardian-transaction.test.ts가 부하 때 lease
만료로 실패한다. guardian이 스스로 SIGKILL한 것이다. desktop 기록 둘:
- FE-GATE-007: 「still publishes near the lease deadline」
- FE-GATE-020 drill: 「owns raw and sealed publication through the
  authenticated client lease」
FE-B 실행에서도 load 28에 같은 실패가 2건 났다. 다시 돌리면 통과한다.

원인은 두 가지다.
- startProviderGuardian은 guardian을 띄우자마자 절대 deadline
  (Date.now() + leaseMs)을 찍는다. 그래서 client 경로 시험의 2~3초
  lease가 node 시작 시간까지 낸다. 부하 때 시작에는 상한이 없다.
- 직접 프로토콜 시험은 guardian이 load를 마친 뒤 가드를 보낸다
  (c8620042). 그래도 가드 → READY 처리는 실제 시계로 돈다. desktop에서
  CPU 25%로 제한하면 이 구간이 17ms에서 334ms로 늘어나, 350ms lease로
  만료를 보는 시험의 여유가 거의 없다.

lease가 시험 대상인지로 나눠 고쳤다.
- lease가 대상이 아닌 15곳(client 경로 10, 직접 경로 5)은
  LEASE_NOT_UNDER_TEST_MS다. 값은 시험 timeout과 같아서, lease가 시험보다
  먼저 끝날 수 없다. guardian이 멈추면 시험 timeout이 잡는다.
- lease 만료를 보는 시험은 350ms → 2초다. 가드 → READY의 CPU 25% 최대
  334ms의 여섯 배다.
- near-deadline 시험은 client 경로에서 직접 프로토콜로 옮겼다.
  - deadline이 guardian load 뒤에 시작해서 시작 시간이 빠진다.
  - sendGuard가 보낸 deadline을 돌려준다.
  - 시험은 lease 4초의 마지막 2초 안에 publish·commit을 보내고, 그
    구간에 있었는지 단언한다.
  - 2초는 publish·commit의 CPU 25% 최대 104ms의 약 스무 배다.
  - client의 publish·commit은 「owns raw and sealed publication」이 그대로
    본다.

버린 것:
- guardian에 가짜 시계 주입: 운영 스크립트에 시험용 훅을 넣어야 한다
  (c8620042와 같은 이유).
- client가 guardian load 뒤에 deadline을 찍게 바꾸기: 운영 프로토콜에
  준비 신호를 더해야 한다. 이 PR 범위를 넘는다.
- 모든 lease를 늘리기: 만료와 near-deadline 시험은 lease가 대상이라
  늘리면 보는 것이 흐려진다.

위험:
- 시험이 실패하면 guardian이 lease 끝까지(최대 30초) 남을 수 있다.
  전에는 2~3초였다.
- near-deadline 시험에는 실제 시계 구간이 남는다. publish·commit이 2초를
  넘으면 실패한다. 잰 최대의 약 스무 배다.
- 운영 client가 lease에 node 시작 시간을 포함하는 것은 그대로다. 운영
  lease는 분 단위라 시험만큼 빠듯하지 않다.

검증(desktop):
- 이 파일을 10회 돌려 22개 모두 통과했다(load 3~4).
- CPU 20% 제한에서 main d2239c67은 5회 모두 1~6개 실패했다. 원인은 가드
  처리 중 deadline 지남(126), READY·PUBLISHED 대기 시간 초과, EPIPE였다.
  같은 조건에서 이 커밋은 5회 모두 통과했다.
- 시험 timeout은 잰 최대로 고쳤다. near-deadline 3.2초, 만료 2.1초.
- 첫 최종 실행에서 FE-GATE-007이 near-deadline 시험의 「마지막 2초 안」
  단언으로 실패했다(남은 2,001ms). 타이머가 Date.now()보다 1ms 일찍 깼다.
  목표 시각에 닿을 때까지 다시 기다리게 고쳤다. 고친 뒤 이
  파일을 30회(load 3.6~21), CPU 20% 제한으로 5회 돌려 모두 통과했다.
2026-11-12 11:23:04 +09:00
DongHyeonka 91962e24e3 test(setup): 자식 프로세스를 띄우는 시험이 잰 시간으로 timeout을 정한다
자식 프로세스를 띄우는 Vitest 시험 91개(24파일)가 기본 timeout 10초에
기대고 있었다. 셋은 FE-GATE-013에서만 도는 tests/system 시험이다.
기본값은 프로세스 안에서 도는 시험에 맞춘 값이다. 부하가 높은
desktop에서는 자식 프로세스 시험이 평소보다 크게 느려진다.
FE-GATE-020 drill 사본에서 평소 0.4~1.2초인 문서 시험이 10.6초 걸려
실패했다(2026-11-12). 가장 위험한 것은 tests/architecture/app-build-input
.test.ts로, desktop에서 이미 5.7초까지 걸렸다.

무엇을 고칠지는 desktop 계측으로 정했다.
- test:coverage 묶음(maxWorkers=4)과 test:unit을 세 번씩 돌렸다. 시험마다
  띄운 자식 프로세스는 child_process 함수를 감싸 기록했고, 소요 시간은
  JSON reporter로 받았다.
- 시험마다 실제 timeout은 task.timeout으로 기록했다.
- 자식 프로세스를 띄우는 시험 140개 중 88개가 기본값이었다. tests/system은
  그 묶음에 없어서, 아래 검사가 잡은 셋을 따로 세 번 쟀다.

고친 것:
- tests/helpers/child-process-timeout.ts의 childProcessTimeout(<잰 최대
  ms>)는 그 15배를 30초 단위로 올린 값이다. 15배는 위 0.7초 → 10.6초에서
  왔다. 시험마다 자기가 잰 최대값을 인자로 적어 근거가 호출 자리에 남는다.
- describe 안의 기본값 시험이 모두 자식 프로세스를 띄우면 describe에,
  일부만 띄우면 그 시험에 준다. 프로세스 안에서 도는 시험의 hang을 늦게
  잡지 않으려는 것이다.
- tests/setup.ts가 child_process 함수를 감싼다. 기본 timeout인 시험이
  자식 프로세스를 띄우면 그 호출에서 실패시키고, helper 이름을 알린다.
  helper나 시험이 import한 스크립트가 띄워도 잡는다. util.promisify가
  읽는 속성은 원래 함수에서 옮긴다.
- docs/work/reference/testing.md 2절에 값 정하는 법과 이 검사를 적었다.

버린 것:
- 전역 testTimeout 올리기: 프로세스 안 시험의 hang을 늦게 잡는다.
- 시험마다 손으로 정한 숫자: 근거가 남지 않고, 이미 있는 값도
  60_000·120_000처럼 근거가 없었다.
- 자식 프로세스를 띄우지 않게 바꾸기: 검사 스크립트를 CLI 그대로 시험하는
  것이 이 시험들의 목적이라 범위가 커진다.
- 파일에 timeout 선언이 있는지만 보는 정적 검사: helper가 띄우는 경우와
  같은 파일의 다른 시험을 놓친다.

위험:
- hook(beforeAll 등)에서 띄우는 프로세스는 검사하지 않는다. 계측에서
  hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다.
- 같은 파일 안에서 it.concurrent로 도는 시험이 섞이면 어느 시험의
  timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다.
- 다운스트림 시험이 기본값으로 자식 프로세스를 띄우면 test:unit 등이
  실패한다. 메시지가 helper를 알린다.

검증(desktop):
- 다섯 검사(test:unit·check:types·check:ci·lint·verify:documentation)
  rc=0.
- 자식 프로세스를 띄우는 시험 파일 40개와 tests/scale: rc=0, 검사 위반 0.
- tests/system: 115개 중 18개 실패. 모두 bwrap 호스트 제약이고 검사
  위반은 0이다.
- 변이: 검사를 끄면 tests/unit/child-process-timeout.test.ts가 실패한다.
  tracked-artifacts describe의 timeout을 지우면 그 시험이 검사 메시지로
  실패한다.
- 재현: CPU 10% 제한에서 app-build-input·registry-governance·hosting-probe
  ·design-system-rules를 돌렸다. main 650d22fa는 11개가 10초 timeout으로
  실패했다. 이 커밋은 71개 모두 통과했고, 가장 긴 시험은 17.7초였다.
2026-11-12 11:22:59 +09:00
DongHyeonka 6571d8cb9d fix(runbook): drill 복구 항목 이름을 runbooks.json과 같게 한다
문제: scripts/drill-runbook.ts의 복구 확인 항목 이름은 영어 리터럴이고,
config/runbooks/runbooks.json의 recoveryEvidence는 2026-11-08에 한국어로
옮겼다. 둘을 비교하는 곳이 없어 record.json과 UNVERIFIED 줄이 runbook에
없는 이름을 쓴다. 앞으로 한쪽만 고쳐도 아무 신호가 없다.

고른 방법: 다섯 drill의 항목 이름 20개를 recoveryEvidence 문자열로 바꾸고,
이름과 순서가 recoveryEvidence와 같은지 보는 시험을 runbook-drill.test.ts에
더한다. 판정 근거 문구(evidence)와 오류 메시지는 영어 그대로다.
버린 대안: drill이 recoveryEvidence를 위치로 읽어 이름을 붙이는 방법은
코드에서 항목과 판정의 짝이 보이지 않고, 설정 순서를 바꾸면 조용히
어긋난다.

위험: artifacts/runbooks/<id>/record.json의 assertion 값이 한국어가 된다.
record schema는 빈 문자열만 막으니 통과하지만, 그 값을 영어로 읽는 바깥
도구가 있으면 바꿔야 한다. 이 repo에는 없다.

검증: desktop에서 node scripts/run-vitest.ts run tests/unit/runbook-drill.test.ts
— 고치기 전 새 시험 5개 실패(RED), 고친 뒤 runbook-drill 14개·
runbook-contract 2개 통과(GREEN).
2026-11-12 09:40:51 +09:00
DongHyeonka 2d3e58895f chore(merge): 문서 체계 PR #15가 들어간 main을 받는다 2026-11-12 07:02:05 +09:00
DongHyeonka f5344f2166 Merge branch 'main' into chore/layout-rules-r2-r5
main이 PR #15(문서 체계)를 받아 db6a6eb6이 됐다. CHANGELOG 정리 단계
절 머리의 범위 문장이 충돌했고, 문서 체계 단계와 이 브랜치의 범위를 둘
다 남겼다. 나머지 파일은 자동으로 합쳐졌다. PR #15가 더한
tests/unit/docs-system.test.ts의 가상 저장소 목록은 앞 커밋
R2 예외로 적었다.
2026-11-12 07:00:43 +09:00
DongHyeonka b96f3b4564 test(layout): R2가 메모리 안 가상 저장소 목록은 이유와 함께 건너뛴다
main이 받은 PR #15의 tests/unit/docs-system.test.ts는 문서 검사기 시험을
위해 메모리 안에 가상 저장소를 만든다. 그 knownPaths 배열(docs,
docs/architecture, docs/architecture/layers.md, src, src/platform)을 R2
검사가 루트 경로 목록으로 잡아, main을 이 브랜치에 합치면 test:unit이
실패한다. 이 목록은 실제 루트 항목을 옮겨도 바뀌지 않으니 등록부 집합으로
고를 것이 아니다.

R2 시험에 MADE_UP_REPOSITORY_LISTS를 두고 파일·목록·이유를 적는다.
- 그 파일의 그 목록만 건너뛰고, 같은 파일의 다른 목록은 그대로 본다.
- 적힌 목록이 그 파일에 더 없으면 실패한다. 그래서 낡은 예외가 뒤에 새
  목록을 덮지 못한다. 제거 drill 사본처럼 그 파일이 검사 대상에 없으면
  보지 않는다.
- 이 커밋에는 아직 그 파일이 없다. 다음 merge 커밋이 main을 합쳐도 모든
  커밋이 시험을 통과하도록 merge 앞에 둔다.
매뉴얼 03 E절 R2 칸과 CHANGELOG 먼저 할 일 15에 이 예외를 적는다.

버린 것:
- docs-system 시험의 배열을 둘로 나누기: 검사를 피하려고 코드 모양을
  바꾸는 것이다.
- 가상 경로를 다른 이름으로 바꾸기: 문서 검사기가 docs/ 경로를 규칙으로
  보므로 시험의 뜻이 바뀐다.
- 집합을 고르게 하기: 가상 저장소가 실제 저장소 배치에 묶인다.

위험: 다운스트림이 같은 꼴의 fixture를 두면 이 목록에 적어야 한다.

검증(desktop): 이 커밋과 다음 merge 커밋에서 test:unit, check:types,
check:ci, lint, verify:documentation. merge 커밋에서 변이 셋을 넣었다. 예외를
지우면 R2 시험이 docs-system 목록을 대며 실패한다. 목록 내용을 바꾸면
바뀐 목록을 대며 실패한다. 목록이 파일에서 없어지면 낡은 예외로 실패한다.
2026-11-12 07:00:43 +09:00
DongHyeonka ceaf21ea84 fix(test): provider fixture가 추적되는 .claude 파일도 복사한다
FE-GATE-013의 system 시험 tests/system/ci-runner/ci-artifact-contract.test.ts
에서 verified promotion finalizer 시험 18개가 desktop에서 실패한다. 오류는
`ENOENT … .claude/agents/arch-reviewer.md`다. 기준 fixture는 checkout을
.git째 복사하면서 .claude를 통째로 건너뛴다. 하네스 PR #13 뒤로 .claude/에
추적 파일이 11개 있다. 공급망 생성(scripts/lib/repository-file-inventory.ts)
은 추적 파일마다 lstat하므로, 빠진 파일에서 후보 빌드가 멈춘다. main
38c0dc7d에서도 같다. runner에서는 이 시험이 bwrap 없음으로 돌지 못해 드러나지
않았다.

.claude 대신 다른 worktree가 들어 있는 .claude/worktrees만 건너뛴다.
- 등록부의 provider-fixture-skip 집합은 .claude 항목의 setPaths로 그 경로를
  고른다.
- 복사 filter는 첫 경로 조각이 아니라 경로 앞부분으로 비교한다.

버린 것:
- inventory가 .claude를 건너뛰게 하기: 실제 후보 빌드의 inventory까지 추적
  파일을 빠뜨린다.
- fixture의 git index에서 .claude 파일을 지우기: fixture가 실제 checkout과
  달라진다.

위험: runner에서는 FE-GATE-013이 여전히 bwrap 없음으로 실패해, 이 수정은
desktop에서만 확인된다. 사본에 .claude/ 11파일이 더 들어간다.

검증(desktop): 이 시험 파일 전체를 main 38c0dc7d와 이 커밋에서 돌렸다.
- main: 18개 ENOENT 실패, 36개 건너뜀(기준 fixture 빌드 실패).
- 이 커밋: finalizer 18개 통과, ENOENT 0. 남은 18개 실패는 모두
  provider sandbox의 `bwrap: loopback: Failed RTM_NEWADDR`(desktop 비특권
  network namespace 제약)다.
- test:unit, check:types, check:ci, lint, verify:documentation.
2026-11-12 05:01:27 +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 1f57c38e40 test(layout): R5를 게이트 대상의 소유자를 따라가는 검사로 바꾼다
R5 검사는 샘플의 기능 ID와 라우트 경로가 goto 문자열, 증거 경로,
규모 기록 본문에 들어 있는지 찾았다. 조립한 경로, 여러 줄 goto,
origin을 붙인 template 문자열, import로 샘플을 쓰는 spec은 놓쳤다.

이제 대상마다 소유자를 따라간다.
- visual·e2e goto 경로 → 라우트 표(ROUTE_REGISTRY)의 라우트와 기능.
  선언된 경로가 없으면 catch-all.
- workshop story id → title이 그 id를 만드는 stories 파일.
- spec의 import → 불러오는 파일을 끝까지. src/.generated/에서 멈춘다.
- gates.json의 라우트 기록 → 라우트. 라우트 표에 없으면 실패.
- 게이트 명령 → package script 그래프로 닿는 script, 경로 인자,
  --feature 인자.
- config/scale/feature-shape-growth.json의 sourceFeature → 기능.

실제 저장소로 돈 결과가 비지 않는지, 샘플이 플랫폼 화면·디자인
시스템·메시지 카탈로그를 소유했다면 실제 spec·게이트에서 무엇이
걸리는지, 합성 샘플로 각 경로가 잡히는지를 시험한다.

검증(desktop): test:unit, check:types, check:ci, lint, verify:documentation.
2026-11-12 01:17:55 +09:00
DongHyeonka 3f64c68991 refactor(layout): 남은 루트 경로 목록도 등록부 집합에서 고른다
정리 4단계의 R2 검사는 등록부를 쓰는 7곳만 봤다. 그 밖에 루트 이름을
담은 목록이 코드 15파일에 19개 따로 있어, 루트 항목 하나를 옮기면
여전히 여러 곳을 같이 고쳐야 했다.

- 등록부에 집합 12개를 더했다. 사본 복사에서 건너뛰는 항목 셋
  (checkout·provider·공급망 fixture), fixture 코드 범위, pnpm 매니페스트,
  Playwright 설정, visual 증거, 문서 입력, 에이전트 하네스, tsconfig
  묶음 셋. 각 집합 설명에 읽는 파일을 적었다.
- 사본이 건너뛰는 node_modules·dist·.tmp 같은 추적 안 하는 항목은
  종류 untracked(optional)로 적는다. 추적 파일이 있으면 시험이 실패한다.
- 19개 목록이 모두 집합을 고른다. 집합의 원소는 전과 같아 동작은
  바뀌지 않는다.
- R2 시험이 추적되는 코드 파일 전체를 본다. 루트 항목(이나 그 안
  경로)만 담은 문자열 배열에 추적되는 루트 이름이 둘 이상이면 실패.
  인자 목록은 `--` 뒤만 본다. main의 옛 목록 18개를 이 검사가 잡는
  것을 확인했다.
- 집합마다 selectRepositoryPaths·selectRepositoryEntries로 고르는 코드가
  있는지 본다. 문서를 복사하지 않는 제거 drill(FE-GATE-020)은 문서
  시험(REMOVAL_FIXTURE_DOCUMENT_TESTS)을 지우는데, 집합 셋
  (agent-harness·documentation-inputs·feature-typecheck)은 그 시험만
  읽는다. 시험이 이 셋을 적어 두고, 문서 시험이 지워진 사본에서만 셋이
  비는 것을 허용한다. 셋이 바뀌면 전체 checkout에서 실패한다.
- 파서가 kinds·sets 설명과 코드의 목록이 같은지 본다.
- .gitignore 주석이 a11y 기록을 아직 artifacts/ 아래라고 적던 것을
  고쳤다(정리 3단계에서 docs/로 옮김).

검증(desktop): test:unit, check:types, check:ci, lint, verify:documentation.
repository-layout 시험을 문서 없는 제거 사본과 feature-scaffold 사본에서도
돌렸고, 집합 하나의 읽는 곳을 지우면 두 곳 모두 실패한다.
2026-11-12 01:17:55 +09:00
DongHyeonka 1f09c1cc88 perf(tests): vitest setup이 DOM이 있는 파일에만 Testing Library를 불러온다
문제: tests/setup.ts는 모든 시험 파일에 @testing-library/jest-dom과
@testing-library/react(그리고 react-dom)를 불러온다. tests/unit 215개
파일 중 DOM(jsdom)을 쓰는 것은 3개뿐인데, Node 환경 파일마다 이 import가
돈다. runner의 test:unit에서 setup이 누적 124~165초로, 시험 본문 다음으로
크다(run 80·81).

고른 방법: setup 파일이 `document`가 있을 때만 두 모듈을 불러오고
configure를 건다. afterEach 하나에서 cleanup → 실제 timer 복원 순서를
그대로 지킨다. 버린 대안: vitest projects로 node·jsdom 설정을 나누기.
같은 효과에 설정·명령 변경이 커서 뒤로 미뤘다.

위험·한계: Node 환경 파일에서 jest-dom matcher를 쓰면 이제 실패한다. 그런
파일은 없다(아래 검증의 unit·component 전부 통과로 확인).

검증: desktop 묶음(w2fe-p2) A·B 단계 — unit·component 전·후 각 2회.
2026-11-12 00:05:25 +09:00
DongHyeonka 92abfd2089 ci(gates): 브라우저 job을 Playwright 이미지에서 돌린다
문제: merge / browser tests job은 `playwright install --with-deps`로
매번 apt 276개(180MB)와 브라우저 넷(전체 Chrome 포함), 글꼴 220MB를
받는다. runner에서 job마다 198~242초, 약 900MB다(run 56·80·81).
run 54에서는 이 단계 중 desktop 루트가 90%까지 차 Gitea가 내려갔다.

고른 방법: browser-install 단계에 `image`를 두고, 생성기가 그 job의
container로 그린다. 값은 @playwright/test와 같은 버전의 Playwright 공식
이미지 digest(mcr.microsoft.com/playwright:v1.62.0-noble@sha256:baed…)다.
그 이미지에는 1.62의 브라우저와 OS 라이브러리가 들어 있다. 단계는 visual
골든의 글꼴만 apt로 설치한다(이미지에 패키지 목록이 없어 apt-get update
먼저). job env의 CI_RUNNER_IMAGE를 그 이미지로 적어, 빌드가 기록하는
runner 이미지가 실제와 맞는다.
- 계약: image는 Playwright 레지스트리의 noble 태그 + digest만 받고,
  gate-sequence job에만 둔다(matrix의 비브라우저 lane까지 그 이미지로
  돌지 않게). tests/unit/ci-browser-image.test.ts가 태그 버전 =
  package.json @playwright/test 버전을 지킨다.
- release_gate(lab-performance)는 그대로 둔다(release 단계, 범위 밖).
- 버린 대안: runner 이미지 위에 브라우저를 구운 자체 이미지(레지스트리
  쓰기 토큰과 빌드 경로가 필요), 브라우저 폴더 캐시(apt 의존성 100초가
  남는다).

위험·한계: 이미지의 OS 라이브러리 판이 runner 이미지와 조금 다를 수
있어 visual 골든(maxDiffPixels 50)이 바뀔 수 있다. runner 실행으로 확인한다.
이미지(압축 947MB)를 runner의 dind가 한 번 받는다. Playwright를 올릴 때
이미지 digest도 같이 바꿔야 한다(위 시험이 막는다).

검증(desktop): generate:ci-workflow 뒤 check:ci PASS, ci-workflow-generation
·ci-browser-image 시험 통과(스냅샷 1개 갱신), check:types·eslint rc=0.
runner 실행은 PR에서.
2026-11-12 00:04:19 +09:00
DongHyeonka 1d3eb901d2 ci(gates): FE-GATE-013을 일회용 systemd 컨테이너 안에서 돌린다
문제: FE-GATE-013의 test:system은 provider sandbox를 실제로 띄운다.
systemd user manager(systemd-run --user --scope)와 cgroup v2 위임,
bubblewrap(--unshare-net 등)이 필요하다. runner의 job 컨테이너는
entrypoint가 sleep이라 systemd가 없고 bwrap도 없어 사전 점검에서 실패한다
(run 56·80·81). desktop 호스트는 다 있지만 Ubuntu 24.04의
apparmor_restrict_unprivileged_userns=1이 비특권 bwrap을 막는다.
그래서 이 게이트는 runner와 desktop 어디서도 초록인 적이 없다.

고른 방법(소유자 결정 2026-11-11 5절 e: 조건이 되는 실행 환경을 찾는다):
- config/ci/system-container.Dockerfile: Ubuntu 24.04(digest 고정) +
  systemd PID 1 + root linger + bubblewrap 등 hostRequirements의 도구.
- scripts/run-in-system-container.sh: 이미지(Dockerfile 해시 태그)가 없으면
  만들고, privileged·자체 cgroup namespace로 띄워 systemd와 root user
  manager를 기다린 뒤, 작업 트리·git 이력·호출한 쪽의 node와 corepack을
  복사해 명령을 root로 돌리고 artifacts/를 되가져온 다음 지운다. root는
  호스트의 userns 제한을 받지 않는다.
- gates.json 게이트 필드 hostEnvironment: "system-container"(FE-GATE-013).
  생성기는 그 게이트의 run 줄에 래퍼를 붙이고, 실행 검사
  (workflowGateExecutionFailures)는 계약이 정한 접두어로 돈 줄만 센다.
  scripts/verify.sh gate·parts·stage도 같은 래퍼로 돌린다.
- CI에서는 runner의 Docker proxy로 안쪽 dind daemon을 쓴다(platform-core
  gitea-runner README가 「남은 위험」으로 적은 길: proxy가 privileged
  컨테이너를 막지 않는다).
- 버린 대안: 전용 VM runner(문서 조건을 그대로 만족하지만 platform-core
  변경과 VM 자원·runner 등록이 필요), 호스트 AppArmor profile(호스트
  userns 제한을 푸는 보안 설정 변경, 소유자 sudo).

위험·한계:
- root로 돌아 「비특권 runner에서 bwrap userns」 조건 자체는 증명하지
  않는다. release 단계 provider job 둘은 아직 job 컨테이너에서 돈다(범위
  밖, 같은 래퍼나 VM runner가 필요).
- runner가 rootless dind로 바뀌면 privileged 컨테이너를 못 띄워 깨진다.
- 래퍼 준비(이미지 확인·기동·복사)에 desktop에서 50~60초가 든다.

검증(desktop): 래퍼로 check-system-test-prerequisites → PASS(root),
tests/system/ci-runner/provider-process-group.test.ts 1개 통과.
python3 -m unittest scripts.tests.test_verify 통과, check:ci PASS(게이트 28),
ci-workflow-generation 시험 통과. 게이트 전체(test:system 116개 포함)는 이
브랜치 끝의 merge 단계에서 돈다.
2026-11-12 00:04:05 +09:00
DongHyeonka b4210753f0 perf(scripts): FE-GATE-020 드릴이 같은 시험 파일을 한 복사본에서 두 번 돌지 않는다
문제: FE-GATE-020이 desktop merge 단계 27.4분 중 17.2분이다. 그 안에서
같은 시험 파일이 한 복사본에서 두 번 돈다.
- feature-scaffold 드릴은 merge 단계 명령을 차례로 돌며 test:runtime-schema
  ·test:unit·test:contract·test:component·test:integration을 돌고, 바로
  FE-GATE-005의 test:coverage가 같은 경로를 다시 돈다(약 80초).
- feature-removal 확인은 test:all을 돈 뒤 test:coverage를 돈다. test:all의
  경로는 tests/recipes 말고 모두 coverage 안에 있다(약 110초).

고른 방법:
- scaffold 드릴 제외 목록에 다섯 suite를 넣는다. 그 복사본의 merge 단계에
  test:coverage가 있을 때만 뺀다. 없으면 plain으로 다시 돈다.
- feature-removal은 test:coverage 다음에 coverage 밖에 남는 suite
  (REMOVAL_DRILL_SUITES_OUTSIDE_COVERAGE = test:recipes)만 돈다.
- tests/unit/removal-drill-test-paths.test.ts가 경로를 package.json에서
  읽어 「뺀 suite의 경로 ⊆ coverage 경로」, 「test:all 경로 ⊆ coverage +
  남긴 suite」, coverage가 없으면 다시 도는 것을 지킨다.
- 버린 대안: FE-GATE-005 자체의 plain test:unit·test:contract를 빼고
  coverage 실행에서 junit을 나누기. 그 script가 어느 게이트에서도 안 돌게
  되어 ungated 목록을 늘려야 한다(게이트 기준을 낮추는 일).

위험·한계: plain 실행만의 차이(coverage 계측 없음, worker 수 기본값,
tests/platform을 test:platform처럼 파일 차례로 도는 것)는 드릴에서 더
보지 않는다. merge 단계의 FE-GATE-005가 coverage로 같은 파일을 병렬로
돌고 있어 그 모양이 이미 게이트다. 선택 기능 제거 드릴 셋의 test:all은
그대로다(그 드릴은 coverage를 돌지 않는다).

검증(desktop, 38c0dc7d 위): removal-drill-test-paths·feature-scaffold-drill
·example-feature-rules·test-all-paths·fixture-node-modules 20개 통과,
check:types·eslint rc=0. 변이 두 개(남긴 suite 목록 비우기, test:unit에
tests/recipes 더하기)에서 각각 해당 시험이 실패.
2026-11-11 23:46:41 +09:00
DongHyeonka ddfcb6f6b1 fix(tests): pnpm이 CI로 보지 않는 설치를 CI=false로 만든다
문제: fixture-node-modules 시험의 F-4는 「개발자 PC에서 설치한
node_modules를 CI=true인 fixture가 다시 설치한다」는 위험을 재현하려고
설치 env에서 CI만 지운다. pnpm은 CI 말고도 GITEA_ACTIONS·
GITHUB_ACTIONS 같은 벤더 변수로 CI를 알아챈다. 그래서 Gitea runner
job에서는 두 설치가 같은 설정이 되어 재설치가 일어나지 않고, 시험이
changed=false로 실패한다. FE-GATE-005와 복사본 안에서 같은 시험을 도는
FE-GATE-020이 runner에서만 빨갛다(run 56·80·81).

고른 방법: 설치 env에 CI=false를 준다. pnpm(ci-info)은 CI가
"false"이면 다른 변수를 보지 않는다. 벤더 변수 목록을 지우는 방법은
버렸다. 목록이 pnpm 버전마다 다르고 새 runner가 나오면 다시 깨진다.

위험·한계: pnpm이 CI=false를 무시하게 바뀌면 다시 실패한다. 그때는
runner에서 같은 모양으로 드러난다.

검증(desktop, 38c0dc7d):
- 수정 전, GITEA_ACTIONS=true GITHUB_ACTIONS=true CI=true: rc=1
- 수정 뒤, 같은 env: rc=0 / CI=true만: rc=0 / CI 없음: rc=0
2026-11-11 23:32:38 +09:00
DongHyeonka 7b09c215f0 test(docs): verify:documentation을 띄우는 시험에 넉넉한 시간을 준다
문제: tests/unit/documentation-readiness.test.ts의 사례마다
verify:documentation을 새 프로세스로 띄운다. 이 브랜치에서 그 검사가 살아
있는 문서 전부를 읽게 돼 한 번 도는 시간이 늘었고, 부하가 큰 desktop(load
25)에서 FE-GATE-020의 기능 생성 드릴이 사본 안에서 이 파일을 돌릴 때 세
사례가 기본 시간 10초를 넘겨 실패했다. 같은 사례는 부하가 낮을 때 1~8초다.

고른 방법: 이 파일의 사례에 저장소 관례대로 시간 한도 60초를 준다
(`VERIFY_TIMEOUT`). 그리고 livingDocuments가 문서 내용을 읽지 않고 경로만
고르게 해 한 번 도는 일을 줄인다. 버린 안: vitest 전역 testTimeout을
올리는 것(다른 시험의 멈춤을 늦게 알게 된다).

위험: 진짜로 멈춘 검사를 60초 뒤에야 알게 된다.

검증: desktop에서 이 파일과 FE-GATE-005·FE-GATE-020을 다시 돌린다.
2026-11-11 23:25:51 +09:00
DongHyeonka 743f6fcc68 fix(docs): 문서 경로 검사가 줄임표 「…」를 자리표시자로 본다
문제: 하네스 PR #13이 더한 scripts/hooks/README.md는 `node scripts/…`처럼
줄임표 「…」(U+2026)로 「아무 스크립트」를 적는다. 참조 검사가 살아 있는
문서 전부로 넓어지자 verify:documentation이 `scripts/…`를 없는 경로로
잡아 실패한다. 경로 검사는 `...`만 자리표시자로 알고 「…」는 몰랐다.
같은 repo의 문서 검사(scripts/lib/docs-system.ts의 PLACEHOLDER)는 이미
「…」를 자리표시자로 본다.

고른 방법: verify-documentation-readiness.ts의 경로 후보 거르기에 「…」를
더해 두 검사를 맞춘다. 버린 안: 하네스 문서의 표기를 바꾸는 것(같은 표기를
다른 문서도 쓸 수 있고, 검사 둘이 다르게 판정하는 것이 원인이다).

위험: 「…」가 든 진짜 경로는 검사에서 빠진다. 파일 이름에 「…」를 쓰는
일은 없다고 본다.

검증: documentation-readiness 시험의 자리표시자 사례에 `node scripts/…`를
더했다. 고치기 전 코드에서는 그 사례가 실패하고 고친 뒤 통과한다(desktop).
2026-11-11 21:17:48 +09:00
DongHyeonka 5757742ed0 docs(work): 하네스 문서를 새 문서 위치와 검사 범위에 맞춘다
문제: 하네스 PR #13이 더한 작업 매뉴얼·규칙은 이 브랜치가 바꾼 문서
체계의 옛 모습을 적는다.
- 옛 경로: `docs/architecture/decisions/`, `docs/superpowers/`, 루트
  `SPEC.md`, 목표 설계였던 `docs/testing/frontend-platform-testing-strategy.md`
- 옛 검사 범위: 「docs/README.md 1절이 링크한 문서, 폴더 링크는 바로 아래
  .md만」. 지금 verify:documentation은 살아 있는 문서 전부를 보고 언어·
  문체·숫자·머리 블록도 본다
- 옛 docs/README.md 절(1절 묶음 / 2절 목표 설계 / 3절 작업 이력)과 README
  절 이름(「Support scope」, 「Updating a copied project」)
- #13의 template-contract-documents 시험은 README 지워도 되는 표를
  `docs/superpowers/` 행으로 찾는데, 그 행은 이제 없다

고른 방법: 그 줄만 새 위치·새 절 이름·새 범위로 고친다(.claude/rules/docs.md,
docs/work의 docs-writing·operate·research-design·reference 다섯,
docs/problem-statement.md). 시험은 `docs/history/` 행으로 표를 찾는다.
docs/work/evidence.md는 백엔드처럼 매뉴얼 규칙의 근거 기록이라 고치지 않고
`HISTORY_HOLDERS`에 넣어 참조·숫자 검사에서 뺀다.

위험: 하네스 문서의 다른 문장은 건드리지 않았다. 하네스 세션이 쓴 뜻을
바꾸지 않으려는 것이다.

검증: 문서 검사 여섯이 0건, `git grep -n -E 'docs/superpowers|architecture/decisions'`가
기록·CHANGELOG·출처 표시 밖에서 0건.
2026-11-11 20:55:32 +09:00
DongHyeonka fb446e471e Merge branch 'main' into claude/fe-b-docs-korean-645f55
하네스 PR #13(main d1b9c087)을 받는다. 충돌은 README.md와 docs/README.md
둘이다. 이 브랜치가 두 파일을 한국어로 다시 썼고, #13이 영어 판에
AGENTS.md·docs/work/·docs/ledger/를 가리키는 줄과 지워도 되는 표 행을 더했다.
이 브랜치 판을 바탕으로 #13이 더한 것을 한국어로 넣었다.
- README: 최상위 표에 AGENTS.md·.claude/, 문서 지도에 AGENTS.md·docs/work/·
  docs/vision.md·docs/problem-statement.md·docs/ledger/, 지워도 되는 표에서
  CLAUDE.md를 빼고 docs/ledger/estimates.jsonl을 더함, 새 서비스로 시작하기와
  규칙과 기여의 CLAUDE.md 줄을 AGENTS.md 기준으로
- docs/README.md: 1절 「처음 읽을 문서」에 ../AGENTS.md·work/·work/reference/
  링크(#13의 template-contract-documents 시험이 본다), 지도에 work/·ledger/
  행, 폴더 밖 문서에 AGENTS.md·vision.md·problem-statement.md, 2절 살아 있는
  문서 목록
2026-11-11 20:55:11 +09:00
donghyeon.kang 9676101a4d chore(merge): main을 받은 정리 3단계 브랜치를 받는다
PR #16은 PR #14(chore/layout-3-merge) 위에 쌓았다. #14가 하네스 PR #13이
들어간 main을 합친 커밋(568f3328)을 받는다. 충돌은 없었다.
2026-11-11 20:29:19 +09:00
donghyeon.kang 568f332892 chore(merge): 하네스 PR #13이 들어간 main을 받는다
frontend-quality-gates / FE-GATE-001 / manifest-lockfile (pull_request) Successful in 1m20s
frontend-quality-gates / FE-GATE-002 / lint (pull_request) Successful in 1m13s
frontend-quality-gates / FE-GATE-003 / typecheck (pull_request) Successful in 1m2s
frontend-quality-gates / FE-GATE-004 / runtime-schema (pull_request) Successful in 1m4s
frontend-quality-gates / FE-GATE-005 / unit (pull_request) Failing after 2m13s
frontend-quality-gates / FE-GATE-006 / component (pull_request) Successful in 1m12s
frontend-quality-gates / FE-GATE-007 / integration (pull_request) Successful in 1m17s
frontend-quality-gates / FE-GATE-010 / architecture (pull_request) Successful in 1m38s
frontend-quality-gates / FE-GATE-011 / build (pull_request) Successful in 57s
frontend-quality-gates / FE-GATE-012 / bundle (pull_request) Successful in 53s
frontend-quality-gates / FE-GATE-013 / security (pull_request) Failing after 36s
frontend-quality-gates / FE-GATE-020 / removability (pull_request) Failing after 12m49s
frontend-quality-gates / FE-GATE-008 / e2e (pull_request) Successful in 9m9s
frontend-quality-gates / FE-GATE-009 / accessibility (pull_request) Failing after 6m43s
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-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
main(d1b9c087)에 하네스 PR #13이 들어가 루트에 `AGENTS.md`, `.claude/`,
`.gitattributes`가 생겼다. 이 브랜치는 그 셋을 루트 등록부에 optional로
미리 적어 두었다.

충돌 둘을 풀었다.
- `scripts/lib/removal-fixture.ts`: main은 문서 복사 목록에 `AGENTS.md`를
  더했고 이 브랜치는 그 목록을 등록부의 `fixture-documents` 집합으로
  바꿨다. 등록부의 `AGENTS.md` 항목에 그 집합을 적었다.
- `tests/unit/template-feature-removal-documents.test.ts`: main은 문서
  목록에 `AGENTS.md`와 옛 a11y 기록 폴더를 더했다. a11y 기록은 이
  브랜치에서 `docs/`로 옮겼으므로 `AGENTS.md`만 남겼다.

등록부의 `AGENTS.md`·`.claude`·`.gitattributes`는 이제 추적되는 항목이라
optional을 빼고 역할을 실제 내용으로 고쳤다. 추적되는 루트 항목과
등록부 항목이 서로 남는 것 없이 같다.

검증(desktop): 커밋별 5검사와 merge 게이트 14개, verify:documentation.
2026-11-11 20:29:01 +09:00
DongHyeonka af10cae9a6 docs(architecture): 현재 계약 문서와 매뉴얼의 영어 부분을 한국어로 옮긴다
문제: docs/architecture의 현재 계약 문서 가운데 scale-architecture.md,
starter-experience.md, capability-consumer-experience.md,
contract-ownership.md, static-delivery.md, review-evidence.md는 본문이
영어이고, backend-api-and-server-state-contract.md와
optional-adapter-recipes.md에는 영어 문단이 남아 있다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. 백틱 안, 링크 대상, 절 번호(코드
주석이 `scale-architecture.md §N`으로 인용한다), 표 구조, 코드 블록은
그대로 둔다. 문서를 읽는 테스트와 절 이름을 인용한 곳을 같은 변경에서
고친다.
- tests/unit/feature-tracked-files.test.ts: starter-experience.md 표를
  자르는 시작·끝 문장과 표 행마다 찾는 낱말(`병합 충돌`)
- 「Ownership declarations」「Adding a feature」를 인용한 주석
  (create-feature.ts, generate-product-feature-index.ts, app-module.ts)과
  docs/manual의 절 이름 인용
- optional-adapter-recipes.md의 recipe 개수 복사를 카탈로그를 가리키게
  바꾼다(number 검사)

위험: create-feature.ts 417줄은 생성하는 context-module.ts의 JSDoc이라
새로 만드는 기능의 주석 글자가 바뀐다. 그 글자를 비교하는 테스트는 없다.
review-evidence.md는 산문만 옮겼고 해시·점수 칸은 그대로다.

검증: 백틱 span·링크 대상·코드 블록·번호 제목을 옮기기 전과 python으로
비교해 같다. 문서 검사의 language 줄이 이 문서들에서 0이 되어 예외
목록에서 지웠다.
2026-11-08 21:57:47 +09:00
DongHyeonka 7a9aefdf25 feat(docs): 문서 체계 검사를 verify:documentation에 더하고 입구 문서를 고친다
문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와
입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는
문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를
보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한
문서의 경로만 본다.

고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number,
map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨
scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이
부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는
문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation
단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의
documentation-readiness 시험이 이 repo를 그대로 두고
verify:documentation을 한 번 돌린다.
- 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리
  3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다.
- 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와
  도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는
  이미 TS에 있다.
- 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다
  FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤
  번역 커밋들이 지운다.
- docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·
  검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수
  절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와
  글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다.
- README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는
  테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록
  폴더 이름을 적지만 지운 사본에서도 통과하므로
  deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를
  테스트와 검사기 시험에 적었다).

위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때
verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다.
review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자
검사에서 뺐다(HISTORY_HOLDERS).

검증: tests/unit/docs-system.test.ts(조건마다 실패 입력),
documentation-readiness·template-feature-removal-documents·
deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
2026-11-08 21:57:39 +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
DongHyeonka 4a21bc79a1 fix(test): 새 템플릿 계약 시험이 지워도 되는 폴더 이름을 코드에 쓰지 않는다
template-contract-documents.test.ts가 README 표를 찾으려고
docs/superpowers 경로를 문자열로 적었다. deletable-history-documents.
test.ts는 코드·테스트가 지워도 되는 문서를 가리키면 실패하므로,
desktop merge 단계의 FE-GATE-005에서 이 두 줄로 실패했다.

경로를 조각으로 이어 만든다(그 시험 자신과 같은 방법). 시험이 보는
것은 그대로다.

검증: desktop FE-GATE-005(트리 ada4015c)의 실패 줄이 이 파일 15·35줄
이었다. 고친 뒤 결과는 PR 전 merge 단계에서 본다.
2026-11-08 17:53:36 +09:00
donghyeon.kang e902e657d1 test(layout): 저장소 배치 규칙 R3~R9를 검사로 두고 매뉴얼에 적는다
소유자가 2026-11-07에 지적한 것(매뉴얼이 생긴 뒤에도 남은 샘플, 역할이
겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)은 매뉴얼과 리뷰가
먼저 잡아야 했다. 지금은 그 규칙이 글로도 검사로도 없다. 그래서 같은
지적이 다시 나와도 게이트가 모른다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 11절, 기계
검사가 「예」인 규칙을 표의 게이트 칸대로):
- R4·R5 `tests/unit/example-feature-rules.test.ts`(FE-GATE-005): 샘플
  목록은 FE-GATE-020의 `test:sample-removal`(인자 없이, 빌드와 test:all
  포함)이 증명한다. 목록 샘플의 기능 ID·라우트가 visual·e2e의 `goto`,
  gates.json 산출물 경로, `config/scale/`에 나오면 실패한다. 템플릿
  목록은 비어 있어 가짜 샘플로 판정 함수를 시험한다.
- R6·R7(문서) `verify:documentation`(FE-GATE-017): `docs/manual/`이 목록
  샘플 경로를 가리키면, 현재 문서에 ```nginx```·```hcl``` 블록이나
  `kind: Deployment` 같은 매니페스트 줄이 있으면 실패한다. 이력 폴더는
  보지 않는다. 산출물 `documentation-review.json`에
  `layoutRuleViolations`를 더했다.
- R7(파일)·R9 `tests/unit/repository-layout.test.ts`(FE-GATE-005):
  nginx·Terraform·Helm·Kustomize 파일과 Kubernetes 매니페스트 YAML이
  추적되면 실패. 옵션이 같은 tsconfig 쌍이 있으면 실패.
- R3은 `tests/unit/tracked-artifacts.test.ts`, R8은 앞 커밋의
  `check-typecheck-inputs.ts`·`check-type-fixtures.ts`가 맡는다. R10의
  기계 몫(루트 *.md 등록)은 R1이다.
- 매뉴얼 03에 E절(R1~R10 규칙과 검사, 루트 항목을 더하는 순서)과 C절
  「Web Worker를 들일 때 tsconfig 더하기」(결정 D4)를 더했다.

위험: R5는 문자열 검색이라 샘플 ID를 다르게 쓴 대상(예: 라우트 경로를
조립하는 spec)은 놓친다. R7 문서 검사는 코드 블록 언어 태그와 매니페스트
줄로만 본다. R13(리뷰 가이드)은 design-docs 몫이라 넣지 않았다.

검증(desktop): 이 커밋에서 test:unit, check:types, check:ci, lint,
verify:documentation, check:architecture를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 11절, README.md 3.4절
2026-11-08 17:41:27 +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 98f5c6e73e docs(docs): AGENTS.md와 docs/work를 문서 검사에 넣고 템플릿 계약으로 둔다
README의 지워도 되는 파일 표가 루트 CLAUDE.md를 "템플릿 repo 자신의
리뷰 지시, 자기 것으로 바꿔라"로 분류했다. 소유자 결정(2026-11-07 Q4)은
루트 지침을 템플릿 계약으로 정했다. 그리고 AGENTS.md와 docs/work/는
verify:documentation 범위 밖이라 그 안의 경로·script·게이트 ID가 틀려도
아무 검사도 알리지 않는다.

- README: 문서 절에 AGENTS.md와 docs/work/ 포인터를 더하고, 지워도 되는
  표에서 CLAUDE.md 행을 빼고 docs/ledger/estimates.jsonl("줄을 비운다")을
  넣는다.
- docs/README.md 1절: ../AGENTS.md, work/, work/reference/를 링크한다.
- tests/unit/template-contract-documents.test.ts: 지워도 되는 표에
  AGENTS.md·CLAUDE.md·.claude·docs/work가 없고, 1절이 셋을 링크하는지
  본다. 표는 제목이 아니라 docs/superpowers/ 행으로 찾아 제목을 옮겨도
  돈다. 문서를 읽으니 REMOVAL_FIXTURE_DOCUMENT_TESTS에 올렸다.
- deletable-history-documents.test.ts: CLAUDE.md 패턴을 뺀다(이제 지워도
  되는 문서가 아니다).
- 제거 드릴의 문서 사본(REMOVAL_FIXTURE_DOCUMENT_TARGETS)과
  template-feature-removal-documents.test.ts의 사본에 AGENTS.md를 더한다.
  사본 안에서 검사기를 돌리므로, 1절이 링크한 AGENTS.md가 없으면
  FE-GATE-020과 그 단위 시험이 실패한다.

버린 대안: AGENTS.md를 링크하지 않고 백틱으로만 적기. 검사가 빠진다.

위험·한계: 문서 체계 세션이 README를 한국어로 옮기면 표 제목이 바뀐다.
새 시험은 행으로 찾지만, verify-documentation-readiness.ts의 지운 이력
목록은 영어 제목을 읽으니 그 세션이 같이 고친다.

검증: 새 시험은 README·docs/README.md를 고치기 전 트리에서 둘 다
실패했고(desktop test:unit), 고친 뒤 통과한다. verify:documentation과
merge 단계는 PR 전 합친 트리에서 돌린다.

Refs: design-docs harness/01-harness-design.md 4.4절·13절 Q4
2026-11-08 17:27:39 +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 4917222049 test(removal): 제거 사본에서도 남는 명령으로 CI 계약 정리를 시험한다
removal-fixture.test.ts는 선택 recipe 제거 사본 안에서도 돈다. 정리 대상으로 고른
test:recipes가 그 사본에는 이미 없어 FE-GATE-020이 실패했다. 어느 제거 사본에도
남는 test:integration과 그 산출물로 바꿨다.
2026-11-08 14:37:41 +09:00
DongHyeonka e47a0ab23d fix(ci): 라우트 수와 상관없이 라우트 런타임 음성 fixture 진단을 고정한다
샘플 라우트를 지워 라우트가 3개가 되자 FE-GATE-003의 route-runtime 음성 fixture가
TS2740 대신 TS2739를 내 기대 진단과 어긋났다. tsc는 빠진 키가 많으면 TS2740,
적으면 TS2739를 낸다. fixture가 정확히 한 라우트만 빼도록 바꿔 어느 라우트 수에서나
TS2741이 나오게 하고 기대 진단을 맞췄다.
2026-11-08 14:37:40 +09:00
DongHyeonka 9c87cc4d22 chore(scale): 샘플 없는 템플릿에서 성장 기준선을 다시 잰다
config/scale/feature-shape-growth.json은 참조 기능 사본으로 잰 값이고,
기준 근거(feature-shape-ceilings.json의 axes)도 그 수치를 쓴다. 앞
커밋들이 측정 대상을 생성 기능으로 바꾸고 샘플을 지웠다.

샘플을 지운 트리(8c4b09b7, 수정 파일 없음)에서 node
scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100
--repeats=2 --write로 다시 쟀다. 기능당 tsc instantiation 약 10.1만,
tsc 메모리 약 31MB, 지연 JS 약 6.7KB와 9파일, 라우트 3개다. axes의
문장을 이 값과 firstFeatureGzipBytes에 맞췄다. 기준선 시험이 측정
대상(sourceFeature)도 본다.

위험: 시간 값은 desktop(i5-10400F, 부하 기록 포함)의 것이다. 400개 이상은
재지 않았다(D-18 선택).

검증(desktop): 같은 크기의 두 반복에서 컴파일러 수치가 같다.
tests/unit/feature-shape-growth.test.ts 통과.
2026-11-08 14:07:58 +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 b2042de9be test(scale): 규모 측정을 참조 기능 대신 생성 기능 사본으로 잰다
규모 측정(S4 3.1절 S-6)은 참조 기능을 복사해 이름을 바꿔 잰다.

create:feature의 planFeature로 사본마다 --with-create --keyed 기능
파일을 만든다(자기 계약 패키지와 topic, context당 200개). 초기 JS
기록에 firstFeatureGzipBytes를 더하고, context 비용은 둘째 기능을 새
context에 둘 때와 같은 context에 둘 때의 차이로 잰다. 옛 정의는 기능이
없는 템플릿에서 첫 기능의 공용 코드까지 context 비용으로 세어 5,788B로
상한 512B를 넘었다. 몇 바이트짜리 비용에는 기록 허용치 하한 16B를
둔다(빌드 ID에 따라 gzip이 1~2B 흔들린다). 이 트리(샘플이 아직 있는
상태)의 기록: 204,266B, 27파일, 첫 기능 797B, 기능 521B, context 12B.

위험: 성장 기준선(0·25·100개)은 샘플을 지운 트리에서 뒤 커밋이 다시
잰다. 이 커밋의 기준선 파일은 아직 참조 사본으로 잰 값이다.

검증(desktop): feature-shape-growth 등 4파일 57 passed, test:unit 통과.
2026-11-08 14:07:53 +09:00
DongHyeonka 794a51a37d test(e2e): 참조 기능 대신 생성 기능을 넣은 빌드로 기능 경로를 확인한다
참조 기능 e2e 3개가 "기능 하나가 실제 브라우저에서 라우트·폼·
저장까지 된다"를 맡는다. 청크 복구, 부트 실패, preload 시험도 설치된
기능에 기댄다.

S4 9.1절 (가)대로 한다. scripts/lib/generated-feature.ts가 저장소
사본에 create:feature order-feature --with-create --keyed를 만들고,
spec은 그 사본의 빌드를 띄워 돈다. 참조 e2e의 검사(로그인, 목록, 폼
검증·이탈 확인·320px, en-US, 저장과 멱등 키, 429 뒤 다시 시도, 결과
불명과 같은 키 재전송, 키보드 포커스, 상태별 axe)를 생성 기능에
옮겼다. 오래된 탭의 청크 복구는 생성 기능 목록 라우트를, 부트 실패는
생성 기능을 넣은 사본을, preload 시험은 생성 기능 실행부 청크를 쓴다.

위험: 생성 기능의 동작만 본다. 제품 기능은 자기 spec이 필요하다.
사본 빌드가 spec과 브라우저마다 돈다(빌드 1초 안팎).

검증(desktop): 샘플을 지운 최종 트리에서 test:e2e 183 passed,
test:a11y 통과.
2026-11-08 14:07:53 +09:00
DongHyeonka 01cac930e0 docs(manual): 샘플 대신 생성 기능 경로와 시험하는 코드 조각을 예제로 둔다
매뉴얼 예제 칸 14곳(S4 3.3절)과 산문 30여 곳이 참조 기능을
가리킨다. problem details(Envelope가 아닌 백엔드) 응답 매핑의 예는
참조 기능에만 있다.

생성기 출력이 그 모양을 만들면 그 경로로 바꿨다. 없으면 매뉴얼 안
코드 조각으로 썼다: problem details의 분류와 매핑(02 결정표 4절,
소유자 결정 D1), 도메인 모델, 검색값 스키마와 hook, 실패 행동 hook,
403 페이지 시험. 조각마다 manual-code-block 표식에 둘 경로를 적는다.
tests/unit/manual-code-blocks.test.ts가 저장소 사본에 create:feature
invoice-feature --with-create를 만들고 조각을 그 경로에 그대로 넣어
tsc(app, test), eslint, check:architecture, 그 기능 폴더의 vitest를
돈다. 조각의 동작은 tests/fixtures/manual-code-blocks/가 본다.

위험: 403 조각은 본문 없는 403으로 답한다. 공유 시나리오
forbidden-403(JSON 본문)은 jsdom + MSW에서 실행기의 본문 cancel이
끝나지 않아 화면이 로딩에 머물렀다. 실행기는 고치지 않았다. 사본에
이미 invoice-feature가 있는 프로젝트에서는 이 시험이 생성 단계에서
실패한다.

검증(desktop): test:unit 213 files 3096 passed(이 커밋까지),
verify:documentation PASS_SCOPED, lint 통과.
2026-11-08 13:51:55 +09:00