Commit Graph
165 Commits
Author SHA1 Message Date
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 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 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 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 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 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 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 11530b1adf docs: runbook·보안·스타일·접근성·계약·테스트 문서와 모듈 README를 한국어로 옮긴다
문제: docs/runbooks, docs/security, docs/styling/design-tokens.md,
docs/accessibility, docs/contracts, docs/testing/taxonomy.md와
src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다.
PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code,
기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로
둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장
끝만 바꾼다.

위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임
문체를 더하면 verify:documentation이 실패한다.

검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다.
문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
2026-11-08 21:57:47 +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
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
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 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 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
DongHyeonka c7e80f2f8a test(visual): 갤러리를 Storybook story로 옮기고 골든 대상을 바꾼다
예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리
브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을
지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/
04-frontend-layout.md 9.2절 2단계 (1)).

두 갤러리 화면을 그대로 src/presentation/design-system/
galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는
preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual
설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고
(TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은
scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운
골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의
갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화
상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다.

위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰
변화는 옛 골든처럼 새 골든도 잡지 못한다.

검증(desktop): test:storybook 6 passed, test:visual 7 passed,
playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을
파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px
차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다.
미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface
색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
2026-11-08 13:51:54 +09:00
DongHyeonka 95141f1d85 docs(a11y): 한 자원 GET을 부르지 않는 라우트는 자기 paramsSchema를 둔다고 적는다
문제: 9c4cddc의 report는 "로그인 라우트의 paramsSchema = 한 자원 GET의
입력 스키마"만으로 실패 화면 기록을 기대한다. 그 라우트의 페이지가 그
GET을 실제로 부르는지는 보지 않는다. 손으로 쓴 기능이 하위 항목 작성 폼
(`/things/:thingId/parts/new`)의 paramsSchema로 상세 GET과 같은
ThingParams를 쓰면, spec은 한 자원 응답을 보지 못해 기록을 남기지 않고
report가 `a11y.json not written:`으로 FE-GATE-009를 실패시킨다. 그런데
errors.md는 "spec의 기록 호출을 본다. 기능 파일은 고치지 않는다"고만
안내했다. 이 경우 고칠 곳은 기능의 라우트 스키마 ID다.

고른 방법: 리뷰의 첫 방향. report 판정은 그대로 두고 안내를 고친다.
errors.md 행이 두 원인(spec이 기록을 놓침 / 페이지가 그 GET을 부르지
않음)과 각각 고칠 곳을 적는다. 매뉴얼 01 6단계에 같은 경우와 고치는 법
(그 라우트에 자기 paramsSchema)을 더했다. CHANGELOG 1106 절 11-01 행에
같은 줄을 더했다. report의 실패 문장 끝에도 같은 안내를 붙였다. 판정
조건과 문장 앞부분은 그대로라 단위 테스트의 기대(`stringContaining`)도
그대로다.
버린 대안: spec이 "기대했지만 보지 못함"을 따로 기록하고 report가 그
경우를 다르게 다룬다. report 판정이 바뀌어 이번 범위(문서) 밖이다.

위험·한계: 같은 스키마를 쓰면서 그 GET을 부르지 않는 라우트는 여전히
실패한다. 안내로만 풀린다. 그 라우트에 스키마를 따로 두면 FE-REG-SCHEMA
행과 route codec이 하나씩 는다.

검증: desktop batch에서 확인. 테스트 없음(문서와 실패 문장 끝).
corepack pnpm verify:documentation
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
tests/unit/changelog-review-ids.test.ts

Refs: 1106/11-01 (diff review DR-05)
2026-11-06 07:59:04 +09:00
DongHyeonka eb03dabdfd fix(removal): spec 본문 잔여를 적힌 그대로, -가 든 이름만 찾는다
문제: af3344b가 더한 Playwright spec 본문 검색은 대소문자를 무시하고
`_`를 이름 경계로 봤다(`(?<![A-Za-z0-9-])…(?![A-Za-z0-9-])`, `i`).
create:feature는 한 단어 ID(`messages`, `reports`)를 받고 폴더 이름도
ID와 같다. 그래서 `messages` 기능을 지우면 템플릿 자신의
tests/e2e/accessibility.spec.ts(`KO_MESSAGES`)와 scrollbar-gutter
visual spec이 잔여로 잡혀 드릴이 실패한다. `status`·`reports`는 템플릿
spec 여러 개가 평범한 단어로 쓴다. errors.md는 목록에 템플릿 파일이
나오면 템플릿 결함이라 적으므로 제품은 고칠 곳이 없다.

고른 방법: 메인 세션 기준대로 적힌 그대로(대소문자 구분) 찾고, 경계는
식별자 문자 `[A-Za-z0-9_-]`다. 폴더 이름이 ID와 다르면 같은 규칙을 쓴다.
그런데 이 둘만으로는 `status`·`reports`가 0건이 되지 않는다. 템플릿
spec에 `status: 200`, `getByRole("status")`, 테스트 제목의 "reports"가
있다(git grep). `getByRole("status")`는 따옴표 안 한 단어라 따옴표나
문맥 규칙으로도 실제 참조와 구별되지 않는다. 그래서 `-`가 든 이름만 spec
본문에서 찾는다. 한 단어 ID·폴더 이름은 spec 본문 검색에서 빠진다.
검사를 좁히는 변경이지만 이 발견이 바로 그 거짓 양성이다. 거짓 양성은
제거를 막고 고칠 길이 없는 반면, 빠지는 쪽(한 단어 ID만 본문에 적은
spec)은 1106/16-01 전처럼 다음 CI의 브라우저 게이트가 잡는다.
테스트: 템플릿의 spec 파일 전부를 사본에 옮겨 `product-feature`,
`messages`, `status`, `reports`로 돌리면 잔여 0건이다. 적힌 그대로의
ID와 다른 폴더 이름(`invoice-docs`)은 잔여이고, `Invoice-Feature`와
`invoice-feature_v2`는 아니다. 매뉴얼 01 11단계, errors.md, CHANGELOG
1106 절의 16-01 행·확인 2·알려진 제한을 고쳤다.
버린 대안: 따옴표나 `/features/` 문맥만 센다. `getByRole("status")`가
남고, `test.describe("invoice-feature")` 같은 실제 잔여도 문맥에 따라
빠진다. 한 단어 ID를 막는 생성기 규칙은 이 수정 범위 밖이다.

위험·한계: `-`가 든 흔한 이름(예: `read-only`)을 ID로 쓰면 템플릿 spec이
그 이름을 쓸 때 다시 거짓 양성이 난다. 템플릿 spec 0건 테스트는 네
ID만 본다. src 쪽 부분 문자열 검색(1105/16-04)은 그대로다. CHANGELOG
행의 커밋 칸에는 이 커밋 해시를 아직 적지 않았다(같은 커밋에 자기 해시를
적을 수 없다).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts

Refs: 1106/16-01 (diff review DR-02)
2026-11-06 07:56:30 +09:00
DongHyeonka 0c6548a774 chore(review): 1106 검사 범위 조치 브랜치를 합친다 2026-11-06 07:02:34 +09:00
DongHyeonka 95a090e2d1 chore(review): 1106 테스트 기반 조치 브랜치를 합친다 2026-11-06 07:02:34 +09:00
DongHyeonka 68fde02777 fix(test-run): RUN_OUTPUT_ROOT가 있으면 빌드 뒤 검사가 멈춘다
문제: 1105/12-04 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰는데,
check:bundle의 두 단계(`generate-supply-chain.ts`, `check-bundle.ts`)는 이
변수를 읽지 않고 checkout의 `dist`와 `artifacts/`를 읽는다. 셸에 이 변수를
둔 채 빌드와 check:bundle을 돌리면 예산을 3,504 B 넘는 새 빌드 대신 이전
빌드를 재서 PASS한다(리뷰 12-R2). ci:gate의 신선도 검사도 bundle.json을
check:bundle이 다시 쓰므로 막지 못한다.

고른 방법: `scripts/lib/run-isolation.ts`에 `checkoutBuildReadFailure`를
두고, 두 스크립트가 무엇을 읽기 전에 부른다. 출력 루트가 `.`이 아니면 변수
값과 이유를 적고 exit 1로 멈춘다. `.`(Playwright 설정이 run ID 없이 web
server에 넘기는 값)과 빈 값은 그대로 돈다. 그래서
`RUN_OUTPUT_ROOT=.tmp/x corepack pnpm ci:gate -- FE-GATE-012`도 check-bundle
단계에서 변수 이름을 적고 실패한다.
버린 대안: ci:gate가 시작 전에 거절하기(리뷰 문서 (b)). 12-R2처럼
check:bundle을 직접 돌리는 경우를 막지 못한다. 두 스크립트가 같은 루트를
읽게 하기(c)는 supply-chain 산출물 전부와 CI upload 경로를 함께 옮겨야 한다.

위험·한계:
- FE-GATE-012는 빌드 단계를 끝까지 돈 뒤 check-bundle에서 실패한다. 빌드
  시간만큼 늦게 알린다.
- 같은 모양일 수 있는 `check:app-build-input:bundle`,
  `check:optional-recipes --require-dist`, release candidate 조립은 보지
  않았다. FE-GATE-012에서는 check-bundle이 먼저 실패해 거기까지 가지 않는다.
- 디버깅으로 변수를 둔 사람은 check:bundle 전에 지워야 한다(문서에 적음).
- 이 노트북에서는 실행하지 못했다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/check-bundle-output.test.ts tests/unit/run-isolation.test.ts
리뷰 12-R2 명령(stale-bundle-rc=1, stderr에 RUN_OUTPUT_ROOT), check:types,
lint, verify:documentation, ci:gate FE-GATE-012

Refs: 1106/12-02
2026-11-06 05:35:48 +09:00
DongHyeonka af3344b310 fix(removal): 본문에만 기능 ID를 적은 Playwright spec을 잔여로 센다
문제: 1105/16-04 수정 뒤 제품 기능 제거 드릴의 tests 잔여는 파일
이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일뿐이다. 주석과 매뉴얼
01 11단계는 빠진 경우(본문에만 ID가 있는 테스트)를 test:all이 잡는다고
적었다. 그런데 test:all은 vitest 묶음이고 vitest는 tests의 *.test.ts(x)만
돈다. tests/e2e·visual 등의 *.spec.ts는 test:all도 드릴의 다른 단계도
돌리지 않는다. 그래서 `test.describe("invoice-feature", …)`처럼 본문에만
ID를 담은 spec은 드릴을 통과하고, 다음 CI의 브라우저 게이트에서 지운
라우트를 열다가 실패한다.

고른 방법: 리뷰의 (b). tests 중 vitest가 돌지 않는 Playwright spec
(`*.spec.[cm]?[jt]sx?`)은 본문도 찾는다. 다만 1105/16-04가 없앤 부분
문자열 검색으로 돌아가지 않고, 기능 ID·폴더 이름을 앞뒤가 영문·숫자·`-`가
아닌 한 이름으로만 찾는다. `"invoice-feature"`, `'invoices'`,
`/features/invoices/`는 잔여이고, product-feature를 지울 때
`generate-product-feature-index.ts`·`data-product-feature`·
`product-features`는 잔여가 아니다. vitest 테스트 본문은 그대로 찾지 않는다
(템플릿 테스트가 예시 ID를 데이터로 쓴다). 템플릿 자신의 spec에는
invoice-feature·product-feature·scaffold-feature가 한 이름으로 나오지 않는다
(git grep 0건). 그래서 16-R2(invoice-feature 제거)와 FE-GATE-020
(scaffold-feature)은 그대로 통과해야 한다. 주석, 매뉴얼 01 11단계, errors.md의
판정 문장을 고쳤다.
버린 대안: (a) 문서만 고친다. 빈틈이 남는다. spec 본문을 부분 문자열로
찾는다: 짧은 ID와 템플릿 이름(`generate-product-feature-index`)이 거짓
양성을 다시 낸다. tests의 모든 비-vitest 파일(helpers, mocks, fixtures)을
찾는다: tests/helpers/runtime-capabilities-stub.ts가 주석에
"product-feature"를 한 이름으로 적어 거짓 양성이 된다. spec이 import하는
helper는 spec이 지워지면 아무 데서도 돌지 않아 해가 없다.

위험·한계: route ID나 URL만 적은 spec은 여전히 못 잡는다(03 손 목록).
다운스트림 spec이 무관한 이유로 기능 ID를 한 이름으로 적으면 거짓 양성이
난다. 1105/16-04의 남은 부분(src 경로·본문과 tests 파일 이름의 부분 문자열
검색, dist 빌드 잔여 검사)은 이 변경이 덮지 않아 그대로 두었다. 같은 이름
단위 검색으로 바꾸면 product-feature의 거짓 양성(16-R3, 20파일)은 풀리지만,
폴더 이름에 붙은 식별자(`invoices` → `InvoicesPage`)와
`<id>-helpers.test.ts` 같은 파일 이름을 놓쳐 검사가 좁아진다. 따로 정한다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts
corepack pnpm create:feature invoice-feature에 본문에만 ID를 적은
tests/e2e/checkout.spec.ts를 더한 뒤 corepack pnpm test:sample-removal --
--feature=invoice-feature가 fixture-id-residue로 실패, spec 없이는 통과

Refs: 1106/16-01
2026-11-06 05:32:31 +09:00
DongHyeonka b8535f8ce7 fix(test): 문서를 읽는 테스트만 제거 드릴의 문서 테스트 목록에 둔다
문제: 문서를 복사하지 않는 capability 드릴 셋은 `REMOVAL_FIXTURE_DOCUMENT_TESTS`
의 파일을 통째로 지운다. 문서를 읽는 테스트 하나 때문에
`backend-contract-pin.test.ts`가 목록에 들어가, config와 코드만 보는 나머지
14건(pin 커밋, 답 표 사본, 생성기 사실, Envelope 판정 대조)도 그 드릴에서
돌지 않는다. `feature-tracked-files.test.ts`의 생성기 목록 검사 1건도 같다.
목록을 지키는 검사는 파일 글자에 `README.md|CHANGELOG.md|docs/`가 있는지만
봐서, `backend-contract-pin.test.ts`는 주석 한 줄로 통과했다.

고른 방법(리뷰 문서 ⓐ+ⓑ):
- 6.1 표를 읽는 테스트를 `backend-contract-pin-document.test.ts`로 옮기고
  목록에는 그 파일을 둔다. pin 파일은 목록에서 빠져 모든 드릴에서 돈다.
  새 파일은 pin에서 문서 경로만 읽고, 그 경로가 `docs/` 아래인지 확인한다.
- `feature-tracked-files.test.ts`의 문서와 무관한 1건을
  `feature-tracked-file-rewrites.test.ts`로 옮긴다. 남은 두 건은 모두 문서를
  읽어 그 파일은 목록에 남는다(`create-feature.ts`의 참조도 그대로 맞다).
- 목록 검사는 Babel로 파일을 파싱해 코드의 문자열·템플릿 리터럴에 문서
  경로가 있는지 본다. 주석은 세지 않는다. 주석만 있는 소스를 거절하는지
  자체 테스트를 더했다.
- 6.1 대조를 가리키던 `external-contract-runtime.ts` 주석과 계약 문서 한
  줄을 새 파일 이름으로 고쳤다.
버린 대안: capability 드릴이 계약 문서 하나만 복사하기. 문서 테스트가
늘 때마다 복사 목록이 늘고, 그 드릴이 "문서 없이"를 증명한다는 전제가
흐려진다. 목록 검사만 고치기는 빠지는 범위가 그대로다.

위험·한계:
- 목록 검사는 파일 단위다. 파일 안의 모든 테스트가 문서를 읽는지는 기계로
  보지 않는다. 목록 주석에 규칙을 적었다.
- 검사는 코드에 문서 경로 문자열이 있는지 본다. 그 문자열로 실제로 읽는지는
  보지 않는다.
- 이 노트북에서는 실행하지 못했다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/removal-fixture.test.ts tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-pin-document.test.ts tests/unit/feature-tracked-files.test.ts tests/unit/feature-tracked-file-rewrites.test.ts
check:types, lint, verify:documentation, ci:gate FE-GATE-020(capability
드릴 셋의 unit 실행에 pin 14건이 나오는지)

Refs: 1106/12-01
2026-11-06 05:31:57 +09:00
DongHyeonka 9c4cddc201 fix(a11y): 한 자원을 읽는 라우트가 기록 없이 통과로 세지면 report가 실패한다
문제: a11y.json의 notChecked는 접근성 spec이 남긴 기록만으로 정해졌다.
기록이 없으면 "검사함"이었고, 어느 라우트에 기록이 있어야 하는지는 spec
말고 아무도 몰랐다. 리뷰 11-R2에서 실패 화면 분기의 기록 호출 reason을
null로 바꾸자 라우트 test 10건, write-a11y-report.ts, 증거 schema가 모두
통과하고 a11y.json이 상세 라우트를 scope(통과)에 넣고 notChecked: []를
적었다. 1103/11-01이 고친 거짓 주장이 한 줄로 돌아온다. 같은 실행 뒤 지난
실행의 기록 파일도 디렉터리에 남아 있었다.

고른 방법: 리뷰의 (다)와 기록 초기화.
- scripts/lib/a11y-data-state.ts의 oneResourceReadRoutes가 설치된
  descriptor만으로 "실패 화면으로만 볼 수 있는 라우트"를 찾는다. 로그인이
  필요한 라우트의 paramsSchema가, 경로 파라미터가 있고 빈 목록을 거부하는
  GET의 입력 스키마일 때다. GET 쪽 규칙은
  tests/e2e/support/installed-api-answers.ts가 답하는 규칙과 같다.
  참조 기능 상세와 create:feature --with-create 상세는 GET과 같은
  <Pascal>Params를 쓰므로 이 규칙에 든다.
- write-a11y-report.ts는 그 라우트가 기록(notChecked)에 없으면
  `a11y.json not written:`과 라우트·operation을 찍고 rc=1로 끝난다.
  a11y.json은 쓰지 않는다. test:a11y(FE-GATE-009)가 실패한다.
- accessibility.spec.ts의 라우트 test는 시작할 때 자기 기록을 지운다.
  기록 호출에 닿지 못한 실행이 지난 실행의 기록을 그대로 쓰지 않는다.
  엔진 셋이 같은 파일을 쓰지만 각 엔진은 지운 뒤에만 쓰고, 실행 중에
  기록을 읽는 곳이 없어 순서가 섞여도 결과가 같다.
- 단위 테스트: 가짜 descriptor로 규칙(목록·경로 아래 목록·DELETE·공개
  라우트 제외)과 거절(null 기록은 거절, 기록이 있으면 통과, 기대 밖 기록은
  허용). 참조 기능 테스트가 실제 descriptor에서 REFERENCE_RESOURCE_DETAIL
  하나가 나오는지 본다. 이 줄이 없으면 규칙이 아무것도 찾지 못해도
  모른다. 참조 기능과 함께 지워진다.
- 11-R2 diff는 그대로 적용된다(문맥 줄 유지, 4줄 offset).
버린 대안:
- (나) 두 상태 모두 기록하고 기록 없는 라우트를 실패: 기록 삭제는 잡지만
  reason을 null로 바꾸는 11-R2는 못 잡는다. 실행 경계(TEST_RUN_ID)도
  정해야 한다.
- 증거 schema(release-artifacts.ts)에서 검사: schema 모듈이 기능
  런타임 전체(top-level await)를 불러야 하고, 그 모듈을 쓰는 스크립트가
  많다.
- spec 안에서 기록을 다시 읽어 대조: 같은 test의 두 줄을 서로 대조할
  뿐이고, 시작 시 초기화와 엔진 동시 실행이 겹치면 거짓 실패가 난다.
- 기록 호출의 모양을 바꿔 사실(읽은 operation)을 적고 report가 판정:
  11-R2 변이 자리가 사라져 리뷰 변이로 확인할 수 없다.

위험·한계: 방향은 하나다. 규칙이 찾은 라우트가 기록에 없으면 실패하고,
규칙이 못 찾는 라우트를 spec이 notChecked로 적는 것은 덜 주장하는 쪽이라
받는다. paramsSchema가 GET 입력과 다른 상세 페이지(손으로 쓴 기능)는
규칙이 찾지 못해 기록만으로 정해진다(이전과 같다). 공개 라우트는 spec이
API에 답하지 않으므로 이 규칙 밖이다. write-a11y-report.ts가 기능 런타임
전체를 불러온다(check:registries와 같은 경로). check:types:node가 그
그래프를 node 설정으로 검사한다. 노트북에서 아무것도 실행하지 않았다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
tests/features/reference-feature/reference-contract.test.ts
11-R2 변이와 기록 줄 삭제 변이에서 playwright(chromium, @a11y /) 뒤
node scripts/write-a11y-report.ts rc=1, 변이 없이 rc=0. corepack pnpm
test:a11y

Refs: 1106/11-01
2026-11-06 05:29:21 +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 e6b2a4f6bf fix(manual): 짝 백엔드 OIDC 설정 키 예시의 FE-REG-ENV 행에 defaultValue를 적는다
문제
매뉴얼 04 §3.2의 PRODUCT_ENV_REGISTRY 예시 두 행(OIDC_ISSUER,
OIDC_CLIENT_ID)에 defaultValue가 없다. 행 타입은 defaultValue를 필수 칸으로
가진다(src/contracts/env.ts). 그래서 제품이 그대로 붙이면 check:types:app이
env.ts에서 TS2322로, env-registry-coverage가 `row {"required":false}`로
실패한다(리뷰 14-R3). 매뉴얼 03 C절과 product-contracts.ts 주석은
defaultValue를 쓴다.

고른 방법
- 두 행에 `defaultValue: null`을 더하고(.optional() 키), 행 칸의 규칙을
  예시 아래 한 줄로 적었다.
- 테스트 tests/unit/manual-paired-backend-settings.test.ts: 매뉴얼 §3.2의 ts
  블록을 그대로 저장소 사본의 새 파일로 두고, 사본의 product-contracts.ts가
  제품 자신의 파일(옆에 보존)에 그 키를 더해 내보낸다. 그 사본에서
  tsconfig.app.json 타입 검사와, env-registry-coverage와 같은 행 대조(키가
  없을 때 스키마가 내는 required·defaultValue)를 node로 돌린다. 제품 파일을
  덮어쓰지 않으므로 다운스트림에서도 그대로 돈다(1105/09-01과 같은 방식).
- 문서를 읽는 테스트라 REMOVAL_FIXTURE_DOCUMENT_TESTS에 더했다. 그 목록의
  항목이 문서를 읽는지 보는 removal-fixture.test.ts 정규식에 `docs/`를
  더했다. 문서 대상(REMOVAL_FIXTURE_DOCUMENT_TARGETS)에 docs가 있어 README나
  CHANGELOG를 읽지 않는 문서 테스트도 있을 수 있다. 목록의 뜻은 그대로다.
- 버린 대안: 예시 행을 recipe에서 export하고 recipe 테스트가 그것으로
  조립하기(리뷰 ②). contracts가 recipe를 import할 수 없어 매뉴얼이 다시
  복사를 시킨다. 이번 테스트가 매뉴얼 블록 자체를 지킨다.

위험·한계
- 행 대조는 env-registry-coverage의 schemaDeclaration을 이 테스트 안에 다시
  적었다(사본에서 vitest를 띄우지 않으려고). 규칙이 바뀌면 둘을 함께 고친다.
- §3.3·§4.3의 코드 예시는 여전히 컴파일하지 않는다(recipe를 복사한 뒤의
  모양이라 사본 구성이 더 크다).
- 테스트가 저장소 사본을 만들고 tsc app 프로그램을 돈다. test:unit이 몇 초
  는다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/manual-paired-backend-settings.test.ts
  tests/unit/removal-fixture.test.ts, corepack pnpm verify:documentation

Refs: 1105/14-02
2026-11-06 02:59:02 +09:00
DongHyeonka 332bfee9b8 fix(docs): 지운 템플릿 기능의 경로를 문서 검사가 요구하지 않는다
문제
CHANGELOG "먼저 할 일" 6단계는 예제를 지운 제품(tech-log)에게 예제 기능
폴더와 그 context를 지우라고 한다. 그런데 starter-experience.md가 그 세
폴더를 백틱 경로로 적어서, 지운 사본에서 verify:documentation과
FE-GATE-005의 documentation-readiness "passes the documents as they are"가
"starter-experience.md names paths that do not exist"로 실패한다(리뷰
14-R1). 그 문서가 안내한 드릴(test:sample-removal
--feature=platform-examples-feature)도 같은 문서 검사와, 예제 기능 ID를
적은 tests/unit/hosting-probe.test.ts 때문에 잔여 검사에서 실패한다.
PRODUCT.md는 예제 화면에 제거 드릴이 없다고 적는다. 지운 제품이 템플릿
문서를 고치면 동기화마다 그 줄이 충돌한다.

고른 방법
- 문서 검사는 scripts/lib/removable-template-features.ts의 기능마다, 그
  기능이 설치돼 있으면(src/features/<id>/feature-module.ts가 있으면) 그
  경로·script를 지금처럼 검사하고, 아니면 그 기능이 가진 경로(기능·테스트
  폴더, context, 전용 파일)와 script를 없어도 되는 것으로 본다. 폴더가 아니라
  feature-module.ts를 보는 것은 tech-log가 참조 기능 폴더를 계약 파일만 남긴
  채 NOT_A_FEATURE로 두기 때문이다(CHANGELOG 옮기는 법 1). 목록에 없는
  폴더(오타)는 그대로 실패한다. 지운 기능이 있으면 stdout에 그 ID를 적는다.
- tests/unit/hosting-probe.test.ts의 FEATURE_OVERRIDES 키를 테스트 전용
  기능 ID(fixture-feature)로 바꾼다. probe는 키 이름을 보지 않는다.
- 새 테스트 tests/unit/template-feature-removal-documents.test.ts: 저장소
  사본에서 기능마다 그 경로를 지우고 색인을 다시 만든 뒤 사본의
  verify:documentation이 통과한다. 사본의 코드로 경로를 찾으므로 실제로
  지운 상태다. 기능 ID는 목록에서 읽어 테스트에 적지 않는다(제거 드릴의
  잔여 검사). 설치된 기능 아래의 없는 경로와 목록에 없는 폴더는 여전히
  실패하는 것도 본다. 문서를 읽으므로 REMOVAL_FIXTURE_DOCUMENT_TESTS에
  더했다.
- PRODUCT.md, starter-experience.md(지우는 법과 문서 검사 규칙),
  docs/README.md 1절 검사 설명, CHANGELOG 6단계(테스트 폴더,
  generate:feature-index, 드릴, 두 절을 함께 받을 것)를 고쳤다.
- 버린 대안: (a) 세 경로를 백틱 없이 적기(1103/14-04 방식). 검사가 또
  좁아진다(1105/14-03). (b) 모든 src/features/<dir> 아래 경로를 폴더가
  없으면 통과시키기. 기능 폴더 이름 오타가 조용히 지나간다. (c)
  FE-GATE-020에 예제 기능 드릴을 더하기. job이 약 5분 는다. 문서 쪽은 새
  unit 테스트가 merge 단계에서 본다.

위험·한계
- 새 테스트는 저장소 사본을 두 번 만든다(기능마다 cp·색인·검사). test:unit
  시간이 몇 초 는다. 드릴이 test:all에서 이 파일을 다시 돈다.
- 예제 기능 드릴 전체(test:all, build 등)는 이 커밋에서 돌리지 않았다.
  알려진 남은 실패는 e2e·visual spec이 예제 화면을 여는 것이고 드릴 밖이다.
- RED에서 새 테스트는 앞 커밋의 목록 모듈을 import하므로 그대로 돈다.

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

Refs: 1105/14-01
2026-11-06 02:59:02 +09:00
DongHyeonka 50b631e4cd refactor(removal): 지울 수 있는 템플릿 기능 목록을 한 모듈에 둔다
문제
템플릿은 지울 수 있는 기능을 둘 둔다. 참조 기능(README)과 예제 화면
기능 platform-examples-feature(starter-experience.md, CHANGELOG 6단계)다.
그 기능이 가진 경로는 제거 드릴의 SAMPLE_EXTRAS에만 있다. 그래서 문서
검사가 "이 경로는 지운 템플릿 기능의 것"을 알 길이 없다(1105/14-01,
14-03). 문서 검사가 따로 목록을 가지면 드릴과 갈라진다.

고른 방법
- scripts/lib/removable-template-features.ts에 두 기능을 적는다. 기능
  ID(= src/features·tests/features 폴더 이름), 혼자 속한 context, 폴더 밖
  전용 파일, 전용 package script.
- 드릴은 참조 기능의 전용 파일·script를 이 모듈에서 읽는다. 목록 내용과
  주석은 그대로 옮겼다. 동작은 바뀌지 않는다.
- 예제 기능 항목은 다음 커밋(1105/14-01)의 문서 검사가 읽는다. 드릴은
  예제 기능을 지금처럼 locateFeature로 찾는다.
- 버린 대안: 문서 검사 안에 목록을 따로 두기. 드릴의 SAMPLE_EXTRAS와 두
  벌이 된다.

위험·한계
- 동작 변경은 없다. 드릴 출력과 지우는 경로가 같다.

검증
- desktop batch에서 확인: corepack pnpm check:types, corepack pnpm lint,
  node scripts/run-vitest.ts run tests/unit/feature-removal-argument.test.ts

Refs: 1105/14-01, 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 1a29d4aa85 chore(review): 1105 실행 격리 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka d5a70b4267 chore(review): 1105 테스트 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka 45c9c4dc48 chore(review): 1105 계약·앱 코어 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나.
- 1105/03-02(HTTP 판정 브랜치)가 §4의 503 `RATE_LIMIT_UNAVAILABLE`·
  `RATE_LIMIT_INCOMPATIBLE`을 답 표(`backend-idempotency-answers.json`)에
  옮겼다. 1105/07-01(이 브랜치)은 같은 두 code를 pin의 `notCopied`에
  두었다. 합친 트리에서 `backend-contract-pin.test.ts`의 "copies the
  answers from the backend table rows at the pin"이 "is both copied and
  listed in notCopied"로 실패한다.
- pin의 `notCopied`를 비우고, 계약 문서 4.1절의 "지금은 §4의 `RATE_LIMIT_*`
  둘"과 "§4 행은 `REQUEST_TIMEOUT` 하나"를 답 표에 맞게 고친다.
- `docs/manual/01-add-a-feature.md` 충돌은 앞 통합(1a4a220c)과 같게
  푼다: "5xx 여섯" 줄과 pin·사본·drift 명령 세 줄을 함께 둔다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts

Refs: 1105/03-02, 1105/07-01
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 19d10538d6 chore(review): 1105 HTTP 판정·폼 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 0e72c0c116 fix(test-run): Playwright 서버가 빈 포트를 고르고 dev 서버를 재사용하지 않는다
문제: 다섯 Playwright 설정의 서버 포트가 고정이다(e2e 4173, visual과
capability가 둘 다 4174, storybook 6006, dev 5173). 한 checkout이든 같은
기계의 두 worktree든 두 번째 실행은 `http://127.0.0.1:4173 is already
used`로 시작하지 못한다(00-R1). dev 설정만 `reuseExistingServer: true`라
5173에 다른 checkout·브랜치의 dev 서버가 떠 있으면 말없이 그 서버를
검사한다. vite는 `--strictPort` 없이 떠서, 포트가 그 사이 잡히면 다음
포트로 옮기고 Playwright는 원래 URL의 남의 서버를 검사할 수 있다
(1105/12-04).

고른 방법: 설정마다 `reservePort(TEST_<이름>_PORT)`로 빈 포트를 고른다
(`scripts/lib/run-isolation.ts`). 커널이 port 0에 준 포트를 받고 바로
닫는다. 고른 포트를 그 변수에 써 둔다. Playwright는 worker마다 설정을
다시 평가하고 worker는 runner 환경을 물려받으므로, worker의 평가가 같은
포트를 읽어 `baseURL`이 어디서나 같다. 변수를 미리 주면 그 포트를 쓴다
(디버깅용 고정). vite 서버 넷 모두 `--strictPort`로 띄우고, dev 설정은
`reuseExistingServer: false`로 바꿨다. run ID가 없어도 빈 포트를 쓴다.
두 worktree는 출력 경로가 이미 다르고 포트만 부딪히기 때문이다. 고정
번호를 읽는 곳은 없다. spec은 `baseURL`에서 origin을 얻는다
(`resumable-upload.spec.ts`, `production-csp.spec.ts`).
버린 대안: 포트 범위를 run ID에서 계산하기. 두 checkout이 같은 run ID를
쓰거나 다른 프로그램이 그 포트를 쓰면 다시 부딪힌다. Playwright
`webServer.wait`로 서버가 고른 포트를 stdout에서 읽기: `use.baseURL`은
설정을 읽을 때 정해져서 쓸 수 없다.

위험·한계: 포트를 고른 뒤 서버가 잡기 전에 다른 프로세스가 같은 포트를
잡을 수 있다. 그때는 `--strictPort`/serve-static의 listen 실패나
Playwright의 "already used"로 시작이 실패한다. 남의 서버로 검사가 새지
않는다. 기본 실행의 포트 번호가 매번 달라진다. 고정이 필요하면
`TEST_E2E_PORT=4173`처럼 준다. `test:e2e:dev`는 이제 떠 있는 dev 서버를
쓰지 않고 자기 서버를 띄운다. capability 설정이 없는 사본
(test:browser-file-storage-removal)에서는 그 설정의 포트 테스트를 돌리지 않는다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts
corepack pnpm test:browser-file-storage-removal

Refs: 1105/12-04
2026-11-06 02:58:00 +09:00
DongHyeonka 5c0b37e39e fix(contracts)!: 쓰기 뒤에도 나오는 플랫폼 code를 쓰기 전 거절로 적지 못하게 한다
문제
commandEffect.refusedBeforeWrite의 조립 검사는 code 문법, 멱등성 접두사,
중복, Envelope 여부만 본다. 계약 문서 6.1절은 BAD_PARAMETER(어느 층이든
IllegalArgumentException), MAPPING_FAILED(멱등성 응답 직렬화는 action 뒤),
DB_* 8개, LOCK_ACQUISITION_TIMEOUT, fileserver code를 "쓰기 뒤 가능"으로
적는다. 이 code를 목록에 적어도 조립이 통과하고, 그 code로 온 400·409·422가
NOT_APPLIED가 된다. 쓰기 뒤에 난 실패를 사용자가 다시 저장하면 새 키나 키
없는 새 요청이 나가 같은 항목이 둘 생길 수 있다(리뷰 실험 X2: 네 code가
조립을 통과하고 모두 NOT_APPLIED).

고른 방법
6.1절의 "쓰기 뒤 가능" 플랫폼 code를 src/contracts/external-contract-runtime.ts에
PLATFORM_CODES_POSSIBLY_AFTER_WRITE로 두고, assertRefusedBeforeWrite가 그
code의 선언을 6.1절을 이유로 거절한다. 실행기의 fail-close(조립 없이 부른
경우)도 같은 목록을 무시한다. 목록을 adapters가 아니라 contracts에 둔 것은
조립 검사가 adapters를 import할 수 없기 때문이다(리뷰 문서의 최소 개선은
backend-envelope.ts에 두라고 했다). backend-contract-pin.test.ts가 계약 문서
6.1절 표의 "쓰기 뒤 가능" 행을 읽어 목록과 양방향으로 대조한다. 참조 도메인
code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 테스트의 예외
목록에 적고 선언할 수 있게 둔다.

버린 대안
- 매뉴얼 문장만 둔다(현상 유지): 폼을 막는 code를 넣고 싶어지는 바로 그
  자리에 통제가 없다.
- 업무 code 접두사 규칙(<FEATURE>_로 시작하는 code만 허용): 다운스트림 code
  이름을 강제해 과하다.

위험·한계
- 이미 이 code를 적은 다운스트림 계약은 부팅에서 조립이 실패한다. 의도한
  실패다.
- 6.1절 표에 플랫폼 code가 더해지면 목록도 같이 고쳐야 한다. 대조 테스트가
  알린다. 백엔드가 code를 더한 것은 pin을 올릴 때 6.1절을 다시 읽어야 안다.
- 업무 code를 잘못 선언하는 것은 여전히 막지 못한다(기능 작성자의 판단).
- 대조 테스트는 계약 문서를 읽으므로, 문서를 복사하지 않는 기능 제거
  드릴(FE-GATE-020의 optional-recipe·browser-file-storage·realtime)에서는
  돌지 않는다. `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에
  `tests/unit/backend-contract-pin.test.ts`를 더했다. 저장소 자신의 test:unit은
  그대로 돌린다.

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts
tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts
corepack pnpm test:optional-recipe-removal

BREAKING CHANGE: refusedBeforeWrite에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔
플랫폼 code(PLATFORM_CODES_POSSIBLY_AFTER_WRITE)를 적으면
composeContractContributions가 거절한다. 그 code를 목록에서 지운다. 그 code의
실패는 결과 불명으로 남는다.

Refs: 1105/03-01
2026-11-06 02:33:16 +09:00
DongHyeonka 6d084cf6a2 docs(manual): 기능마다 바뀌는 추적 파일 둘과 충돌 처리 명령을 적는다
문제: 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다.
create:feature가 public/release-manifest.json(dev server manifest)의
setDigest·packages를 다시 쓰고, 참조 기능이 있는 동안은 초기 JS 기록
(config/scale/feature-shape-ceilings.json initialJavascript)을 명령으로 다시
써야 한다. 03 문서 A절은 "생성 명령이 쓰는 폴더 밖 파일은 둘"(context 선언,
a11y 기록)이라고만 적고, 정본 표(starter-experience.md "Adding a feature")에도
두 파일이 없다. 기능 브랜치 둘은 같은 setDigest 줄을 다른 값으로 바꿔
충돌하는데, 어떻게 푸는지는 test:unit 실패 문구에만 있다.

고른 방법(리뷰 대안 (a)): 문서와 생성 출력에 두 파일, 쓰는 주체, 다시 쓰는
명령, 충돌 처리("아무 쪽이나 고르고 명령을 다시 돌린다")를 적는다.
- scripts/create-feature.ts에 FEATURE_TRACKED_FILE_REWRITES(경로·명령)를
  두고 생성 출력이 충돌 처리 줄에 쓴다.
- 03 A절에 표와 충돌 단락, "기능을 지울 때"에 초기 JS 기록 재작성, 정본 표에
  두 행, 01 1단계 흐름에 manifest 재작성 줄을 더했다.
- 새 단위 테스트가 그 상수의 파일·명령이 03 A절과 정본 표에 있는지 본다.
초기 JS 기록과 그 측정 스크립트 경로는 참조 기능과 함께 지워지므로 문서에서
백틱 없이 적었다(performance-evidence.md와 같은 규칙, 제거 드릴의
verify:documentation).
버린 대안(이번에 하지 않음, 결정 대기):
- (b) dev manifest를 생성 파일로 두고(.gitignore) dev·Playwright 시작 전에
  만들기: 커밋 줄이 사라지지만 dev 스크립트와 Playwright webServer 명령을
  바꿔야 한다. Playwright 설정은 다른 작업(12-04)이 고치는 중이다.
- (d) 초기 JS 기록이 템플릿 자신의 값만 담게 측정에서 설치된 제품 기능을
  빼기: 측정 스크립트가 어떤 기능이 템플릿 것인지 알아야 한다.

위험·한계: 충돌 자체는 남는다. 두 기능 브랜치를 합칠 때 사람이 명령을 다시
돌려야 한다. 완료 기준의 둘째 길("03 A절·정본 표가 두 파일과 충돌 처리
명령을 적는다")만 채운다. 실제 두 브랜치 git merge로 재현하지 않았다.
테스트는 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴에서는 돌지
않는다(`scripts/lib/removal-fixture.ts`의 문서 테스트 목록).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-tracked-files.test.ts
corepack pnpm verify:documentation
corepack pnpm test:realtime-removal

Refs: 1105/16-01
2026-11-06 02:12:06 +09:00
DongHyeonka f4d5761a2a fix(test-run): 실행마다 빌드·Playwright 출력 폴더를 따로 쓴다
문제: 빌드는 `dist`, `.generated/frontend-runtime`, `artifacts/release`·
`artifacts/quality`에 고정으로 쓰고, 다섯 Playwright 설정은 결과·report·
JUnit을 `artifacts/tests/<이름>/`에 고정으로 쓴다. 한 checkout에서 두
번째 e2e 실행이 시작하면 빌드 1단계가 첫 실행의 preview가 서빙 중인
`dist`를 지우고, Playwright가 `outputDir`을 비워 첫 실행의 trace를 지운다.
증거 파일도 늦게 끝난 쪽 것으로 섞인다(1105/12-04).

고른 방법: 변수 두 개로 나눈다(`scripts/lib/run-isolation.ts`).
- `TEST_RUN_ID`: Playwright 설정이 읽는다. 값이 있으면 그 실행의 결과·
  report·JUnit과 서빙할 빌드를 `.tmp/runs/<id>/` 아래 같은 상대 경로에
  둔다. 없으면 지금 경로 그대로라 게이트, CI upload, 증거 검사가 읽는
  곳이 바뀌지 않는다.
- `RUN_OUTPUT_ROOT`: 설정이 web server에만 넘긴다. 빌드 단계 전부
  (`build-frontend`, contract set, runtime config, SW asset 목록, SW 빌드,
  build manifest)와 `vite.config.ts`가 읽어 `dist`·생성 모듈·증거·Vite
  캐시를 그 아래에 쓴다. preview는 `--outDir`로 같은 `dist`를 서빙한다.
빌드 코드는 `TEST_RUN_ID`를 읽지 않는다. e2e worker가 저장소 복사본을
빌드할 때(fixture-builds, service-worker-builds) runner 환경을 물려받는데,
그 빌드는 복사본 자기 `dist`에 써야 하기 때문이다.
두 루트는 `.` 또는 `.tmp/` 아래만 받는다. git, Tailwind 소스 스캔(report
안 문자열이 CSS에 들어가지 않게), Vite watcher, vitest, 저장소 복사
helper가 모두 `.tmp`를 건너뛴다. service-worker-builds의 복사 제외 목록에
`.tmp`를 더했다(fixture-builds와 같아짐). build manifest의 경로는 빌드가
쓴 폴더 기준 상대 경로로 둔다.
`vite.config.ts`가 새로 가져오는 `scripts/lib/run-isolation.ts`는 저장소
일부를 임시 루트에 복사해 빌드하는 두 목록(초기 JS 측정
`scripts/scale/measure-feature-shape-growth.ts`,
`tests/unit/product-feature-selection-build.test.ts`)에도 더한다.
Storybook은 run ID가 있으면 `build:storybook`의 두 단계를 다른 `-o`로
돌린다. 같은 단계인지는 단위 테스트가 package script와 대조한다.
버린 대안: 운영 증거 경로(54개 스크립트, `config/ci/gates.json`)까지 run
ID로 옮기기. 게이트와 workflow upload가 고정 경로를 읽으므로 이번 범위
밖이다(아래 한계). 실행마다 저장소를 임시 폴더로 복사하기: 매번 수십
MB 복사와 node_modules 링크가 들고, 개발자가 보는 결과 위치가 사라진다.

위험·한계: 포트는 아직 고정이라 이 커밋만으로는 두 실행이 함께 돌지
못한다(다음 커밋). `ci:gate`와 증거 검사(`check:test-evidence`,
`verify:browser-capability-evidence`)는 기본 경로만 읽는다. run ID를 준
채 게이트를 돌리면 증거가 기본 경로에 새로 생기지 않아 게이트가 "not
freshly produced"로 실패한다(통과로 새지 않는다). Storybook 내부 캐시
(`node_modules/.cache`)는 여전히 공유한다. capability 설정
(`playwright.capabilities.config.ts`)은 test:browser-file-storage-removal이
capability와 함께 지운다. 설정 테스트는 그 파일이 있을 때만 그 설정을 읽고,
경로를 변수로 두어 타입 검사가 그 파일을 요구하지 않는다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts tests/unit/run-output-root-build.test.ts
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts
corepack pnpm test:browser-file-storage-removal

Refs: 1105/12-04
2026-11-06 02:11:17 +09:00
DongHyeonka b45d6a03db fix(removal): 제품 기능 제거 드릴이 템플릿 테스트의 예시 ID를 잔여로 세지 않는다
문제: 매뉴얼 1단계 예시 ID는 invoice-feature이고 11단계가
`test:sample-removal -- --feature=invoice-feature`로 그 기능을 지운다.
드릴은 제품 기능의 잔여를 src·tests 모든 파일에서 기능 ID의 대소문자 무시
부분 문자열로 찾았다. 템플릿 소유 tests/unit/create-feature.test.ts가 같은
예시 ID를 데이터로 51번 쓰므로, 다른 검사가 모두 통과해도
`fixture-id-residue: residue: tests/unit/create-feature.test.ts`로 rc=1이었다
(리뷰 16-R1). errors.md의 안내는 그 템플릿 파일을 고치라는 것이었다.
notice-feature, orders-feature, shop-feature 같은 이름도 같은 충돌이 난다.

고른 방법: 제품 기능의 잔여 판정을 scripts/lib/feature-residue.ts의
productFeatureResidue로 옮기고 범위를 나눈다.
- src: 지금처럼 경로나 내용에 기능 ID·폴더 이름이 있으면 잔여. 플랫폼
  소스는 제품 기능을 이름으로 부르지 않으므로, 남은 이름은 타입 검사가 못
  보는 참조(카탈로그 키, 런타임 오버라이드, 링크)다.
- tests: 파일 이름에 기능 ID가 있거나, 기능의 src/features/<dir>/ 또는
  tests/features/<dir>/에서 import(동적 import, vi.mock 포함)하는 파일만
  잔여. 테스트 본문에 ID를 글자로 적은 것은 세지 않는다. 지운 기능에 기대는
  테스트는 같은 드릴의 test:all이 잡는다.
참조 샘플(reference-feature)은 템플릿이 모든 파일을 가지므로 기존 넓은
패턴을 그대로 쓴다. 빌드 산출물(dist) 잔여 검사도 그대로다.
단위 테스트: 저장소 자체(create-feature.test.ts 포함)를 invoice-feature로
훑으면 잔여 0, src/contracts에 ID를 남긴 파일·이름에 ID가 있는 e2e spec·기능
폴더 import는 잔여, 테스트 본문의 예시 데이터는 잔여 아님.
매뉴얼 01 11단계와 errors.md의 판정 문장·안내(템플릿 파일이 나오면 고치지
말고 템플릿에 알린다)를 고쳤다.
버린 대안:
- 제거 전에 한 번 훑어 이미 걸리던 파일을 제외: src/contracts에 남긴
  잔여도 제거 전부터 ID를 담고 있으므로 같이 빠진다(완료 기준 둘째를 못
  지킨다).
- 템플릿 테스트의 예시 ID를 예약 접두어로 바꾸기: 부분 문자열 검색이면
  접두어를 붙여도 걸리고, create-feature.test.ts의 파생 이름 기대값
  수십 곳을 함께 바꿔야 한다.
- 생성 명령이 템플릿 테스트에 나오는 ID를 거절: 목록이 따로 낡는다.

위험·한계: tests 안에서 기능 ID를 글자로만 담은 진짜 잔여(예: 기능을
import하지 않고 경로 문자열만 적은 테스트)는 이제 잔여로 나오지 않는다.
그런 테스트가 지운 기능에 기대면 test:all이 실패하고, 기대지 않으면 해가
없다. src 쪽 부분 문자열 검색은 그대로라 items 같은 짧은 ID는 플랫폼 소스의
글자에 여전히 걸릴 수 있다(이번 범위 밖). 실제 드릴 실행(198초)은 단위
테스트로 대신하지 못한다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts
16-R1과 같은 순서: create:feature invoice-feature --with-create --keyed 뒤
corepack pnpm test:sample-removal -- --feature=invoice-feature (rc=0 기대),
그리고 src/contracts/invoice-leftover.ts에 "invoice-feature"를 남긴 변이에서
rc=1(fixture-id-residue) 기대

Refs: 1105/16-04
2026-11-06 01:23:48 +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 c9aa73fbfd refactor(scale): vite 빌드 입력 목록을 한 모듈에 둔다
문제: 초기 JS 측정(scripts/scale/measure-feature-shape-growth.ts)과
VITE_PRODUCT_FEATURES=none 빌드 테스트
(tests/unit/product-feature-selection-build.test.ts)가 임시 폴더에 복사할
빌드 입력 8개를 따로 적는다. vite.config.ts가 새 로컬 파일을 import하면
두 목록이 함께 낡고, 한쪽만 고치면 원인을 말하지 않는 "Could not resolve"로
실패한다(7f9a515, 799ab7f가 두 곳을 같이 고쳤다).

고른 방법: scripts/lib/vite-build-inputs.ts에 VITE_BUILD_INPUTS 하나를 두고
두 파일이 import한다. 측정 스크립트가 테스트 파일을 import하지 않는다.
새 tests/unit/vite-build-inputs.test.ts가 (1) 두 소비자에 자기 목록이
없고 이 모듈을 쓰는지, (2) vite.config.ts가 상대 경로로 닿는 모든 파일이
목록 안에 있는지 본다. (2)는 새 로컬 import를 목록에 넣지 않으면 빌드
전에 그 파일 이름으로 실패한다.
버린 대안: 목록을 vite.config.ts에서 export — 설정 파일을 빌드 도구 밖에서
import하면 플러그인 초기화가 따라온다.

위험·한계: import 그래프는 정규식으로 따라간다. 동적 import나 alias로
읽는 파일은 보지 못한다(지금은 없다). scripts/lib/removal-fixture.ts의
복사 목록은 저장소 전체 사본용이라 목적이 달라 합치지 않았다. 측정
스크립트는 참조 기능과 함께 지워지므로(test:sample-removal), (1)은 있는
소비자만 본다. 템플릿에서 그 파일이 없어지면
tests/unit/feature-shape-growth.test.ts가 import에서 실패한다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts
tests/unit/product-feature-selection-build.test.ts
tests/unit/feature-shape-growth.test.ts
corepack pnpm ci:gate FE-GATE-020 (참조 기능을 지운 사본의 test:all)

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