Commit Graph
172 Commits
Author SHA1 Message Date
DongHyeonka 06ffafa25e docs: 살아 있는 문서의 낡은 문장을 지금 코드와 정본에 맞춘다
2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는
문서가 지금 코드와 다른 말을 한다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Refs: 1106/06-01
2026-11-06 05:17:04 +09:00
DongHyeonka 287dc6fa9b build(perf): 초기 JS 예산을 202 KiB로 올린다
문제: 1105 PR B의 수정이 템플릿 초기 JS를 1,184 B 늘렸다(202,927 →
204,111 B, 초기 파일 26 → 27개, `0fee3fe`). 예산 204,800 B까지 남은 여유가
689 B로, 기능 하나가 더하는 768 B보다 작다. FE-GATE-020의 생성 기능
드릴이 기능 둘을 더하면 205,463 B가 되어 check:bundle이 "over by 663"으로
실패한다. PR A 끝(`a793b83`)에서는 통과했다.

늘어난 곳(desktop, 2026-11-06, 커밋마다 `--initial-baseline`으로 잼):
- 1105/03-01 `ab0d4a1` +327 B: 조립 때 `refusedBeforeWrite` code 검사
- 1105/08-03 `7ce9bf1` +293 B, 초기 파일 +1: `navigation-policy` 공유 청크
- 1105/02-01 `f738348` +251 B: scope closer 진단
- 계약·앱 코어 브랜치를 합칠 때 +148 B
- 나머지 +165 B: realtime +72 B, 05-01 +46 B, 테스트 +23 B, 03-02 +15 B와
  합칠 때의 압축 차

고른 방법: `config/performance/budgets.json`의 `initialJsGzipBytes`를
204,800 → 206,848 B(202 KiB)로 올린다(메인 세션 결정, 2026-11-06). 늘어난
바이트는 비대가 아니라 검사와 진단 코드다. 이유와 재검토 조건을
`docs/operations/performance-evidence.md`에, 계약 행을 CHANGELOG 미출시 절에
적는다. 초기 파일 상한을 26 → 32로 올린 `2fef27d`와 같은 방식이다.
버린 대안: 줄이기. 08-03 청크를 기존 청크 그룹에 넣으면 약 240 B가 돌아올
것으로 본다(추정, 재지 않음). 663 B에는 모자라서 03-01·02-01의 런타임 검사를
빌드 시점으로 옮기는 설계 변경이 더 필요하다. 리뷰 라운드 중간의 설계
변경은 다음 라운드의 숫자를 흐린다.

위험·한계:
- 올린 뒤 여유는 템플릿 그대로 2,737 B(768 B 기능 셋), 드릴이 기능 둘을
  더한 뒤 1,385 B다. 기록 대조 허용치 256 B(1105/15-02)는 두 여유보다 작다.
- 재검토 조건: 예산을 다시 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을
  정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터
  본다. 이 상향은 13-03을 정하지 않는다.
- 기준선 기록(`initialJavascript`)은 앞 커밋 `0fee3fe`이 측정 스크립트
  `--initial-baseline --write`로 다시 썼다. 이 커밋은 기록을 바꾸지 않는다.

검증: desktop batch에서 확인.
corepack pnpm ci:gate FE-GATE-020 (CI env)
node scripts/run-vitest.ts run tests/unit/performance-budgets.test.ts tests/unit/check-bundle-output.test.ts tests/unit/feature-shape-growth.test.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Refs: 1105/15-02
2026-11-06 01:23:48 +09:00
DongHyeonka 92d5019c6d fix(ci): 제품 merge 게이트가 실패하면 같은 run의 release 단계를 멈춘다
문제
제품 overlay(config/ci/product-gates.json)의 mergeGates는 product_merge_gate
job으로 렌더링되는데, 다른 job이 이 job을 기다리지 않는다. release_gate는
merge_gate만 기다린다. 그래서 제품 검사(예: 짝 백엔드 계약 검사)가 실패해도
같은 run의 release·immutable_build·promotion·deployment는 그대로 돈다. 브랜치
필수 검사는 PR merge만 막는다. job 그래프는 계약이 고정해서(ci-gates.ts의
expectedJobGraph) 제품이 연결을 더할 방법도 없다.

고른 방법
- overlay에 게이트가 있으면 release_gate의 needs에 product_merge_gate를 더해
  렌더링한다(`needs: [merge_gate, product_merge_gate]`). release_gate는 release
  단계의 첫 job이고 뒤의 job은 모두 그것을 거쳐 기다린다. 템플릿 게이트가
  release를 막는 방식과 같다.
- 연결은 렌더링에서만 더한다. gates.json과 계약 그래프 검사는 그대로라 템플릿
  job 그래프와 check:ci의 엄격함은 바뀌지 않는다. 게이트가 없으면 workflow
  바이트가 같다(.gitea/workflows/quality-gates.yml 변경 없음).
- workflowGateExecutionFailures(check:ci가 부름)가 제품 게이트가 있는데
  release_gate가 product_merge_gate를 기다리지 않는 workflow를 거절한다.
  "실행된다"와 "막는다"를 따로 본다.
- 문서(ci-quality-gates.md, README)에 release 단계가 제품 job을 기다린다고
  적었다.
- 버린 대안: (a) 문서에만 "막지 않는다"고 적기. 제품이 막을 방법이 계속 없다.
  (c) 게이트마다 blocksRelease 칸. 선택권은 주지만 칸이 늘고, 불안정한 제품
  검사가 생기기 전에는 필요가 없다. 계약 그래프 검사에 overlay 예외를 넣는 것:
  템플릿 계약이 제품 overlay를 알아야 한다.

위험·한계
- 불안정한 제품 게이트는 이제 release도 멈춘다. 그때는 (c)로 간다.
- Gitea가 needs와 기본 success() 조건을 GitHub Actions처럼 처리한다고 본다.
  실제 runner에서는 확인하지 못했다(Actions 꺼짐).
- 제품 게이트를 이미 쓰는 다운스트림은 generate:ci-workflow를 다시 돌려야
  check:ci를 통과한다(생성 YAML의 release_gate needs 한 줄이 바뀐다).

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/product-ci-overlay.test.ts tests/unit/ci-workflow-generation.test.ts,
  corepack pnpm check:ci.
- RED 기대: "holds the release stage until the product merge gates pass",
  "runs product merge gates in a job of their own, apart from the template gates".

Refs: 1105/13-02
2026-11-05 22:41:50 +09:00
DongHyeonka fc95672ad5 fix(docs): 문서 검사가 짝 백엔드 참조를 pin 커밋의 트리에서 찾는다
문제
verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의
작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은
옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1,
짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면
pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는
"확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지
않았다.

고른 방법
- 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이
  작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서).
- 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의
  트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다.
  hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다.
- checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신
  unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다.
- `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다.
  실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다.
- 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만
  pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다
  `git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다.

위험·한계
- pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부
  "not verified"다. 실패하지 않는 대신 확인도 하지 않는다.
- 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터
  바꿔야 한다.
- pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다.
- 보고서 schema는 그대로다(unverifiedLinks 주석만 고침).

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm
  verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED +
  not verified 기대).
- RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or
  the working tree", "reports the references as not verified when the
  checkout does not have the pinned commit", "fails a link out of the
  repository into a repository that is not paired".

Refs: 1105/12-02
2026-11-05 22:29:19 +09:00
DongHyeonka 629c713ce4 fix(ci): immutable_build가 gate 로그와 advisory 기록을 항상 올린다
문제: ci:gate는 명령 출력을 artifacts/quality/gates/FE-GATE-<NNN>.txt에만
쓰고 콘솔에는 PASS/FAIL 한 줄만 남긴다(scripts/run-ci-gate.ts). release
단계 job immutable_build는 후보 tar만, 그것도 성공했을 때만 올린다. 그래서
실제 run에서 FE-GATE-015·027이 왜 실패했는지와 FE-GATE-027이 쓰는
artifacts/security/dependency-advisories.json(1103/13-03의 신호)이 runner
작업 디렉터리와 함께 사라진다. 다른 gate job은 artifacts/를 if: always()로
올린다.

고른 방법:
- config/ci/gates.json의 immutable_build 마지막에 upload 단계를 더한다.
  transfer ID는 immutable-gate-evidence, 이름은
  immutable-gate-evidence-<run>-<attempt>, always: true. 대상은
  FE-GATE-015·027의 log와 evidence 산출물(gate 순서)과 advisory 기록 7개다.
  FE-GATE-015의 verification.json 등은 후보가 만들어지지 않으면 후보 안에도
  없으므로 같이 올린다.
- 계약(scripts/contracts/ci-gates.ts)이 이 단계를 고정한다. immutable_build의
  단계 목록에 upload 하나가 늘고, 이 upload가 always이고 마지막 단계이며
  경로가 "job이 도는 gate의 log·evidence 경로 + advisory 기록"과 같아야
  한다. 경로는 계약의 artifact 등록에서 계산하므로 log 경로가 바뀌면 함께
  따라온다. advisory 기록은 gate evidence가 아니라(막지 않는 신호) 경로를
  scripts/lib/dependency-advisories.ts의 상수로 옮기고 scan 스크립트도 그
  상수를 쓴다.
- 후보 archive의 member set, 후보 upload(always 없음), 하위 job의 download는
  그대로다. 생성 workflow를 generator 출력과 같게 손으로 고쳤다.

버린 대안:
- immutable_build도 artifacts/ 전체를 올림: 다른 job과 같지만 후보 증거가
  두 이름으로 나가 어느 것이 승격 대상인지 흐려진다. 필요한 파일만 고정했다.
- ci:gate가 실패한 명령의 마지막 N줄을 콘솔에 씀(리뷰 대안 c, d의 콘솔
  한 줄 포함): 모든 job에 걸리고 provider 출력의 비밀 노출과 로그 상한을
  다시 따져야 한다. 담당 지시 범위(업로드) 밖이라 이번에 하지 않았다.

위험·한계:
- checkout·install 단계에서 실패하면 올릴 파일이 없어 이 단계도
  if-no-files-found: error로 실패한다. job은 이미 실패한 뒤라 결과는 같다.
  merge·release job의 upload도 같은 동작이다.
- 실제 Gitea runner에서 stage=release를 돌려 산출물이 남는지는 확인하지
  못했다(runner 없음). 확인한 것은 계약·생성 workflow까지다.
- 콘솔에는 여전히 한 줄만 나온다. 사람이 산출물을 열어야 이유를 본다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation

Refs: 1105/13-01, 1103/13-03
2026-11-05 22:12:30 +09:00
DongHyeonka 4d6f254438 fix(hosting): 자산 MIME probe가 redirect를 거절하고 live 분기를 테스트한다
문제: 확장자별 MIME probe(1103/06-03)는 install 조건 일부만 옮겼다.
1. install fetch는 `redirect: "error"`라 redirect가 하나라도 있으면
   실패한다. probe는 `redirect: "follow"`로 받고 최종 status와 MIME만
   본다. 같은 origin 안 redirect 뒤 200을 주는 호스트가 PASS다(리뷰
   06-R1). FE-GATE-019가 PASS인데 워커 install은 매번 실패한다.
2. 워커 없는 빌드에서도 돈다. 주석과 문서는 이유를 워커로만 적는다.
3. live 분기의 호출 줄(`verify-hosting-headers.ts`)을 지키는 테스트가
   없다. live 모드는 루프백·http를 거절해 저장소 테스트가 들어갈 수
   없다. 호출을 지우는 변이가 44건 통과로 살아남았다(06-R2).

고른 방법:
1. 자산 probe 기본 fetcher를 `redirect: "manual"`로 바꾸고,
   `response.redirected`이거나 `opaqueredirect`이면 관측 "redirected",
   이유 "install fetch가 redirect를 거절"로 FAIL이다. 3xx는 지금처럼
   `HTTP 3xx`로 FAIL이다. fetcher가 redirect를 따라가도 `redirected`로
   잡으므로 fetcher 방식과 무관하다.
2. 동작은 그대로 두고 의도를 주석과 운영 문서에 적었다. 워커가 없어도
   `nosniff` 아래 script·style은 MIME이 틀리면 페이지가 깨지고, 나중에
   워커를 켜는 릴리스가 호스팅을 다시 확인하지 않아도 된다. 글꼴·이미지는
   페이지에 피해가 없는데 FAIL한다는 것도 적었다. 워커 없는 빌드에서
   script·style만 보도록 좁히는 것은 검사를 약하게 하는 정책 결정이라
   하지 않았다(결정 대기, 템플릿 소유자).
3. live 분기 전체를 `probeLiveHosting`(release surface +
   자산 MIME)으로 빼고 스크립트는 그것만 부른다. 테스트가 fetcher
   대역으로 이 함수를 돌려 CSS `text/plain`이 FAIL인지 본다. 자산 probe
   호출을 빼면 이 테스트가 실패한다. 스크립트에서 `probeLiveHosting`
   호출을 빼면 live 결과가 비어 cache-control 행이 모두 FAIL이라 스스로
   드러난다.
버린 대안: 문서에 한계만 적기(리뷰 (b)). 1·3이 그대로다.

위험·한계: 정규 경로 규칙으로 자산을 redirect하는 호스트는 이제
FE-GATE-019에서 FAIL이다. 워커가 없는 제품도 마찬가지다(2의 판단).
실제 호스트로 live 모드를 돌리지는 않았다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "fails an asset the host answers only after a redirect"(옛 probe는
  redirect 뒤 200을 PASS), "checks every built asset type besides the
  release surfaces"(옛 코드에 `probeLiveHosting`이 없음)가 실패한다.
- 변이(06-R2 대응): `probeLiveHosting`에서 `probeAssetContentTypes` 결과를
  빼면 "checks every built asset type ..."가 실패해야 한다.

Refs: 1105/06-02
2026-11-05 22:11:49 +09:00
DongHyeonka 23662fb23a fix(storage): 객체를 끝까지 돈 계정 삭제 purge는 늘 partition을 지운다
문제: 승인된 LOGOUT·ACCOUNT_DELETION purge는 객체 목록을 읽고, 하나씩
지우고, 마지막에 journal 행을 한 번 센 뒤 0이면 chunk sweep으로 끝나
`chunkSweep: "COMPLETED"`를 돌려준다. 목록과 세기는 각각 한 순간만 본다.
- 다른 탭이 새 객체를 put하는 중이면 purge의 remove가 그 put이 쥔
  origin lease를 기다린다. partition에 객체가 3개 이상이면 그 put은
  목록 뒤에 commit하고 세기 전에 complete까지 끝난다. 목록에도 행 수에도
  없어 sweep이 그 chunk를 건너뛰고, 계정 삭제 뒤에도 파일이 읽힌다
  (리뷰 실험 Y1b 메모리 20/20, Chromium 6/6). 저장소 테스트는 객체
  0~1개로만 돌아서 이 틈을 놓쳤다.
- FILES_READY에서 멈춘 put의 행이 `logicalKey`를 잃으면 세지 못한다.
  staging receipt가 chunk를 sweep에서 지켜 purge마다 COMPLETED인데
  receipt·chunk·manifest가 남는다(Y2).

고른 방법: 마지막 객체까지 돈 purge는 sweep 대신 늘 partition 삭제로
끝낸다(리뷰 2.1절 (d')). exclusive partition lock이 그때 진행 중인
put·delete를 모두 기다린 뒤 디렉터리 전체(staging 포함)와 그 partition
행을 지우므로 두 경우를 함께 막는다. 객체 순회는 `removedObjects`·
`releasedBytes` 보고와 예산 단위 진행을 위해 남긴다. 예산이나 다른 탭의
변경(CONFLICT) 때문에 끝까지 돌지 못한 호출은 지금처럼
`moreObjectsAvailable: true`를 돌려주고, 그때만 journal 행을 세서 끝나지
않은 행이 있으면 바로 partition을 지운다(2026-11-03 05-01 그대로).
purge 성공 report는 이제 `partitionDeleted`와 `moreObjectsAvailable`
중 정확히 하나를 가진다(walk 뒤 abort도 more로 보고).

버린 대안:
- (a) sweep 뒤에 다시 세고 committed 객체를 한 번 더 본다: ①만 막고
  ②가 남는다. 다시 볼 때 정책상 남겨야 할 객체를 가려내려면 목록을 끝까지
  다시 읽어야 한다.
- (b)+(a): 둘 다 막지만 판단 조건이 일곱 개가 된다.
- 세기를 아예 없애기: 예산에 걸린 호출의 crash 행 처리가 다음 호출로
  밀린다. 지금 동작을 바꿀 이유가 없어 남겼다.

위험·한계:
- 모든 승인 purge가 다른 탭의 진행 중 put을 기다린다(지금까지는 끝나지
  않은 행이 있을 때만). 기다림 상한은 `mutationLockWaitTimeoutMs`
  (1103/05-02)이고 abort로 멈출 수 있다.
- 같은 partition에 LOGOUT 때 남겨야 하는 객체가 섞이면 이 방법은 맞지
  않는다. 지금 정책 검사는 OPAQUE_PARTITION이면 LOGOUT·ACCOUNT_DELETION
  모두 purge만 허용해 그런 객체가 생기지 않는다.
- port의 `chunkSweep`은 아무도 채우지 않는다. 읽는 코드가 깨지지 않게
  타입은 남기고 `@deprecated`로 적었다.
- recipe fake의 purge도 늘 `partitionDeleted`다.
- `logicalKey`를 잃은 행 자체는 여전히 남는다(05-03 설계). 그 bytes는
  이제 남지 않는다.
- Firefox·WebKit에서 Y1은 돌리지 않았다. browser spec은 객체 0·3개
  두 경우로 늘렸다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
  tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts
- node scripts/run-vitest.ts run tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm test:browser-capabilities tests/browser-capabilities/opfs-runtime.spec.ts --project=chromium

Refs: 1103/05-01
2026-11-05 22:08:19 +09:00
DongHyeonka 9655958bda fix(ci): test:system 사전 점검이 bwrap namespace를 실제로 만들어 본다
문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid
--unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가
아니므로 비특권 user namespace가 있어야 한다. 사전 점검
(scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd
bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트
(Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를
낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed
RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간
초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도
없고 운영 원장의 일회성 메모에만 있다.

고른 방법:
- 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한
  번 띄운다. 실패하면 "this host does not allow unprivileged user and
  network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값,
  고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1.
  기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다.
- 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고
  run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이
  갈라지면 점검이 다른 것을 시험하게 된다.
- 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access·
  readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다.
- config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다.
  gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의
  runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로
  그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty
  규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가
  아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선
  재기록 불필요).
- 요구 목록 세 곳(docs/operations/ci-quality-gates.md,
  docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge
  게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를
  두었다.

버린 대안:
- namespace가 없으면 provider 테스트를 skip: 거짓 초록이다.
- FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다.
- probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope
  안과 밖의 결과가 같았다. 직접 실행이 더 단순하다.
- workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직
  없다. 주석이 지금 가능한 가장 작은 표시다.

위험·한계:
- probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른
  옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로
  실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다.
- 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만
  한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서
  이유와 함께 실패한다.
- gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과
  제품 overlay는 그대로 통과한다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
- desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과
  namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지

Refs: 1105/12-01, 1105/11-02
2026-11-05 22:06:59 +09:00
DongHyeonka 2fef27d57f build(perf): 초기 JS 파일 상한에 기능 하나가 더할 여유를 둔다
문제
initialJsFiles 상한이 템플릿 그대로의 수(26)와 같다(1b8cb12). 기능의 지연
페이지가 셸과 같은 구성요소(Button, SearchField)를 쓰면 그 구성요소가 공유
청크로 떨어져 초기 파일이 하나 는다. 매뉴얼의 검색 폼 예제를 따른 기능
하나로 FE-GATE-012가 "27 > budget 26"으로 실패했다(리뷰 조치 X2 #4).

고른 방법
- 상한을 32(지금 26 + 6)로 둔다. 템플릿은 HTTP/2 서빙을 요구하고
  (1103/13-02, FE-GATE-019), 그때 파일 하나의 비용은 거의 없다(15 영역
  측정). 상한은 청크가 통째로 쪼개지는 회귀를 막는 용도다.
- performance-evidence.md에 이유와, 넘었을 때 먼저 청크 그룹을 볼 것을
  적는다.
- 버린 대안: 상한을 지금 수로 두고 제품마다 올리기. 템플릿 소유 파일을
  기능마다 고치게 된다.

위험·한계
- 합계 바이트 예산(204,800 B)은 그대로다. 여유는 1,873 B다.

검증
- performance-budgets·bundle-artifact-contract 테스트 14건,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-05, README.md 14.6 X2 #4
2026-11-05 01:33:38 +09:00
DongHyeonka 2c2d459b17 docs(operations): 성능 기록 문서가 샘플과 함께 지워지는 경로를 백틱 없이 적는다
문제
fix/r1103-release(15-02)가 performance-evidence.md에 기준선 기록 파일
(config/scale/feature-shape-ceilings.json)과 측정 테스트
(tests/unit/feature-shape-growth.test.ts)를 백틱 경로로 적었다. 둘 다 참조
기능을 복사해 재므로 test:sample-removal이 함께 지운다. 그래서 제거
fixture에서 verify:documentation이 실패하고 documentation-readiness
테스트 36건이 떨어진다(깨끗한 clone FE-GATE-020). 14-04 규칙(지울 수 있는
샘플 경로는 백틱 없이)과 2f2426a와 같은 결함이다.

고른 방법
- 두 경로를 백틱 없이 적고, 샘플과 함께 지워진다고 적는다.

검증
- verify:documentation PASS_SCOPED. 제거 fixture는 X4 재실행에서 확인한다.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04, 15-performance.md 15-02
2026-11-05 00:50:44 +09:00
DongHyeonka 505a8b0fca chore(review): 1103 release·CI·성능 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 12-07 13-01~13-03 13-05 15-02~15-07

# Conflicts:
#	docs/manual/03-outside-feature-folder.md
#	docs/operations/performance-evidence.md
#	scripts/lib/hosting-probe.ts
2026-11-04 23:10:59 +09:00
DongHyeonka fbd8f7d148 chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02

# Conflicts:
#	docs/manual/01-add-a-feature.md
#	docs/manual/02-decision-tables.md
#	docs/manual/reference/patterns.md
2026-11-04 23:08:05 +09:00